Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 133 additions & 0 deletions .github/workflows/docker-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,11 @@ env:
jobs:
build:
runs-on: ubuntu-latest
outputs:
# Digest of the multi-arch index this job pushed. The arm64 smoke test
# pulls exactly this image, so it cannot test a stale tag and cannot race
# the publish: it runs after this job, against the bytes just published.
digest: ${{ steps.build.outputs.digest }}
# Without this the job inherits GitHub's 360-minute default, so a hung
# multi-arch build sits for six hours before being cancelled (observed on
# one branch, cancelled at exactly 6h0m44s). Normal duration is 11-13
Expand Down Expand Up @@ -77,6 +82,7 @@ jobs:
type=semver,pattern={{major}}.{{minor}}

- name: Build (push on branch pushes and on tags)
id: build
uses: docker/build-push-action@v7
with:
context: .
Expand Down Expand Up @@ -119,6 +125,133 @@ jobs:
path: dist/release/
if-no-files-found: error

arm64-smoke:
# Proves the arm64 half of the multi-arch image actually runs on an ARM CPU,
# not under QEMU. The build job cross-builds both arches under emulation,
# which cannot demonstrate native execution.
#
# Two paths, because the image is not always in the registry:
# push (main/dev/tag) -> pull the exact digest the build job just pushed
# pull request -> build the image natively here, so a PR is checked
# too and this job is proven BEFORE it reaches main
# The pull-request path matters as much as the assertion itself: a gate that
# cannot run until it is merged has not been tested at all.
#
# Free and unmetered: standard arm64 runners cost nothing on public repos.
needs: build
runs-on: ubuntu-24.04-arm
timeout-minutes: 30
permissions:
contents: read
packages: read
steps:
- uses: actions/checkout@v7

- name: Prove this runner is genuinely arm64
run: |
set -euo pipefail
echo "uname -m: $(uname -m)"
echo "nproc: $(nproc)"
test "$(uname -m)" = "aarch64"

- name: Pull the image this build just published
if: github.event_name != 'pull_request'
env:
IMAGE_REF: "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.build.outputs.digest }}"
run: |
set -euo pipefail
if [ -z "${{ needs.build.outputs.digest }}" ]; then
echo "::error::build produced no digest, so there is nothing to verify"
exit 1
fi
docker pull "$IMAGE_REF"

- name: Build for arm64 natively (pull requests only)
if: github.event_name == 'pull_request'
run: docker build --platform linux/arm64 -t calnode-pr:arm64 .

- name: Resolve the image under test
id: img
run: |
set -euo pipefail
if [ "${{ github.event_name }}" = "pull_request" ]; then
echo "ref=calnode-pr:arm64" >> "$GITHUB_OUTPUT"
else
echo "ref=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.build.outputs.digest }}" >> "$GITHUB_OUTPUT"
fi

- name: Confirm the image is arm64
env:
IMAGE_REF: ${{ steps.img.outputs.ref }}
run: |
docker image inspect "$IMAGE_REF" --format 'image arch: {{.Architecture}} / {{.Os}}'

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This step only prints Architecture/Os; it never asserts the value, so "Confirm the image is arm64" can succeed on an amd64 image. The later native docker run only catches that by accident — because the runner has no binfmt/QEMU — which is an implicit dependency rather than the check the step claims to be. Add a test against the inspected value.


- name: Run it natively, as a deployment would
env:
IMAGE_REF: ${{ steps.img.outputs.ref }}
run: |
set -euo pipefail
docker run -d --name calnode \
-p 127.0.0.1:3000:3000 \
-e PORT=3000 \
-e DATABASE_URL=sqlite:///data/calnode.db \
-e BASE_URL=http://127.0.0.1:3000 \
-v calnode-data:/data \
"$IMAGE_REF"
echo "container arch: $(docker exec calnode uname -m)"

- name: Wait for HTTP and assert the app serves
run: |
set -euo pipefail
for i in $(seq 1 60); do
code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3000/ || true)
if [ "$code" = "200" ] || [ "$code" = "302" ] || [ "$code" = "307" ]; then
echo "app answered on native arm64 (attempt $i, HTTP $code)"
exit 0
fi
sleep 2
done
echo "::error::app did not answer within 120s on arm64"
exit 1

- name: Assert the admin UI loads
run: |
set -euo pipefail
code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3000/admin/)
echo "/admin/ -> HTTP $code"
test "$code" = "200"

- name: Assert the encryption key was persisted, not ephemeral
# Regression guard for the quick-start trap: a first start with no
# CALNODE_ENCRYPTION_KEY must write a key beside the database, so stored
# credentials survive a restart instead of becoming unreadable.
run: |
set -euo pipefail
docker run --rm -v calnode-data:/data alpine:3 sh -c 'test -s /data/calnode.key' \
&& echo "key persisted beside the database"

- name: Assert a restart still finds the key
run: |
set -euo pipefail
docker restart calnode
for i in $(seq 1 60); do
code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3000/ || true)
if [ "$code" = "200" ] || [ "$code" = "302" ] || [ "$code" = "307" ]; then
echo "still serving after restart (HTTP $code)"
docker logs calnode 2>&1 | grep -q "DEK unwrapped from keystore" \
&& echo "restart reused the persisted key" \
|| { echo "::error::restart did not reuse the persisted key"; exit 1; }
exit 0
fi
sleep 2
done
echo "::error::app did not come back after restart"
exit 1

- name: Show app logs
if: always()
run: docker logs calnode 2>&1 | tail -30

release:
# Only on a version tag, and only once the image built + pushed.
if: startsWith(github.ref, 'refs/tags/v')
Expand Down
11 changes: 7 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,13 @@ docker run -p 3000:3000 -v ./data:/data ghcr.io/calnode/calnode:latest
```

The whole app — booking pages, admin UI, SQLite — in one container, with data in
`./data`. With no encryption key set it runs on an ephemeral one (fine for a look;
stored credentials won't survive a restart). **Deploying for real** — HTTPS, a
persistent encryption key, backups — see **[Deploy for real](#deploy-for-real)** below,
or the full **[DEPLOY.md](DEPLOY.md)**.
`./data`. The first start generates an encryption key and writes it to
`./data/calnode.key`, so stored credentials survive a restart. **Back that file up
with the database**: it is the only thing that can decrypt them, and Litestream
replicates the database, not the key.

**Deploying for real** — HTTPS, backups, and managing the key yourself — see
**[Deploy for real](#deploy-for-real)** below, or the full **[DEPLOY.md](DEPLOY.md)**.

---

Expand Down
28 changes: 24 additions & 4 deletions cmd/calnode/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -79,11 +79,31 @@ func main() {
}
logger.Info("database migrations applied")

// Open the key vault. devMode allows an ephemeral DEK when no secret is set
// (handy for local development); production deployments must set
// CALNODE_ENCRYPTION_KEY or the vault will refuse to start.
// Resolve the platform secret BEFORE opening the vault. A missing
// CALNODE_ENCRYPTION_KEY no longer falls back to an ephemeral key chosen by
// guessing from the BASE_URL scheme: a secret is generated once and persisted
// beside the database, so a plain `docker run` survives a restart and a
// deployment behind a TLS-terminating proxy does not silently take the
// "development" path. An explicit CALNODE_ENCRYPTION_KEY still wins.
platformSecret, secretSource, secretPath, err := keyvault.ResolvePlatformSecret(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A generated secret is handed straight to Open, which cannot distinguish it from an operator-supplied legacy key. On a pre-keystore database (crypto_keystore empty, *_enc data present) Open takes the migrateLegacy branch, adopts this random 64-hex value as the DEK, and writes the keystore row — so the existing ciphertext becomes unreadable and the original key can no longer be re-adopted through the app. Before this change an empty secret left the keystore untouched, so supplying the real key later still recovered the data.

Technical details
# A generated secret must never be adopted as the legacy DEK

## Affected sites
- `cmd/calnode/main.go:88` — passes the resolved secret (possibly generated) into `Open`.
- `cmd/calnode/mcp.go:48` — same call, same exposure.
- `internal/keyvault/keyvault.go:116` / `migrateLegacy` (`:193`) — hex-decodes any 64-char secret and adopts it as the DEK when the keystore is empty and `*_enc` data exists.

## Evidence
Reproduced against a migrated in-memory DB seeded with `smtp_pass_enc` and no `crypto_keystore` row: `Open(db, <generated 64-hex>, "", false)` succeeds via `migrateLegacy`; a subsequent `Open` with the true legacy key fails with `failed to unwrap DEK — is CALNODE_ENCRYPTION_KEY correct? cipher: message authentication failed`.

## Required outcome
- A secret whose source is `SecretFromGenerated` must not be accepted as the legacy DEK. The same reasoning already applied to an empty key file applies here: a generated replacement silently destroys access to existing ciphertext.
- Fail with an actionable error telling the operator to supply the original `CALNODE_ENCRYPTION_KEY`; because the keystore stays empty, the data remains recoverable then.
- `Open`/`migrateLegacy` needs to know the secret was generated. Both call sites already hold `secretSource`, so pass that intent through instead of re-deriving it from the string.

cfg.EncryptionKey, db.FilePath(cfg.DatabaseURL))
if err != nil {
logger.Error("keyvault: cannot determine the platform secret", "error", err)
os.Exit(1)
}
switch secretSource {
case keyvault.SecretFromGenerated:
logger.Warn("keyvault: CALNODE_ENCRYPTION_KEY is not set; generated a platform secret and persisted it",
"path", secretPath,
"note", "back it up together with the database: without it the encrypted columns cannot be read")
case keyvault.SecretFromFile:
logger.Info("keyvault: platform secret loaded from file", "path", secretPath)
}

// devMode still governs non-secret behaviour elsewhere; the vault no longer
// uses it to invent a key.
devMode := !strings.HasPrefix(cfg.BaseURL, "https://")
vault, err := keyvault.Open(database, cfg.EncryptionKey, cfg.RecoverySecret, devMode)
vault, err := keyvault.Open(database, platformSecret, cfg.RecoverySecret, devMode)
if err != nil {
logger.Error("keyvault: failed to open", "error", err)
os.Exit(1)
Expand Down
15 changes: 14 additions & 1 deletion cmd/calnode/mcp.go
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,23 @@ func runMCPStdio(_ []string) {
os.Exit(1)
}

// Resolve the platform secret the same way the server does, so `calnode mcp`
// and `calnode serve` always agree on which key unlocks the vault. Diverging
// here would let one process read what the other wrote only by accident.
platformSecret, secretSource, secretPath, err := keyvault.ResolvePlatformSecret(
cfg.EncryptionKey, db.FilePath(cfg.DatabaseURL))
if err != nil {
logger.Error("mcp: cannot determine the platform secret", "error", err)
os.Exit(1)
}
if secretSource == keyvault.SecretFromGenerated {
logger.Warn("mcp: generated and persisted a platform secret", "path", secretPath)
}

// Open the key vault (same dev-mode rule as the server) and swap the real DEK into
// cfg so calendar/webhook token crypto works.
devMode := !strings.HasPrefix(cfg.BaseURL, "https://")
vault, err := keyvault.Open(database, cfg.EncryptionKey, cfg.RecoverySecret, devMode)
vault, err := keyvault.Open(database, platformSecret, cfg.RecoverySecret, devMode)
if err != nil {
logger.Error("mcp: keyvault failed to open", "error", err)
os.Exit(1)
Expand Down
7 changes: 7 additions & 0 deletions internal/db/db.go
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,13 @@ func SchemaReady(ctx context.Context, db *sql.DB) (bool, error) {
return applied >= target, nil
}

// FilePath returns the on-disk database file path for a connection URL, e.g.
// sqlite:///data/calnode.db -> /data/calnode.db. Used to place companion files,
// like the keyvault key, beside the database they belong to.
func FilePath(databaseURL string) string {
return parseDSN(databaseURL)
}

func parseDSN(url string) string {
// Strip scheme prefix: sqlite:// → remainder
dsn := strings.TrimPrefix(url, "sqlite://")
Expand Down
8 changes: 8 additions & 0 deletions internal/keyvault/keyvault.go
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,14 @@ func (v *Vault) DEKHex() string { return hex.EncodeToString(v.dek[:]) }
// working; wrap and store it.
// 4. platformSecret empty + devMode → ephemeral random DEK; warn; never stored.
// 5. platformSecret empty + !devMode → fatal error.
//
// Cases 4 and 5 are the library's last-resort behaviour for a caller that hands
// over no secret. The CLI entry points no longer reach them: main and mcp call
// ResolvePlatformSecret first, which reads or generates a secret persisted beside
// the database. That is deliberate, because choosing between 4 and 5 by guessing
// from the BASE_URL scheme gave a plain `docker run` an ephemeral DEK (secrets
// unreadable after a restart) and refused to boot behind a TLS-terminating proxy.
// Any new caller should resolve the secret the same way rather than pass "".
func Open(db *sql.DB, platformSecret, recoverySecret string, devMode bool) (*Vault, error) {
if platformSecret == "" {
if devMode {
Expand Down
132 changes: 132 additions & 0 deletions internal/keyvault/secret.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
// Package keyvault: platform-secret resolution.
//
// The vault needs one value from outside the database: the platform secret that
// derives the KEK. Until now that value had to come from the environment, and a
// missing value was handled by guessing intent from the BASE_URL scheme:
//
// BASE_URL http://... -> devMode -> ephemeral DEK, warned, secrets lost on restart
// BASE_URL https://... -> fatal error, server will not start
//
// Both arms are wrong for a plain `docker run`, which is the documented first
// install. Over http it silently generates an ephemeral DEK, so the SMTP
// password, Stripe keys and OAuth client secrets stored in the database become
// unreadable at the next restart. Over https it refuses to boot at all. And
// because the scheme is the only signal, a production deployment behind a TLS
// terminating proxy (BASE_URL http, TLS at the edge) takes the silent arm.
//
// Persisting a generated secret next to the database removes the guess. The key
// file lives beside the database it unlocks, which is also where backups already
// go, so the pair stays together. An explicit CALNODE_ENCRYPTION_KEY still wins,
// which is what the NS8 module and any externally managed deployment rely on.

//nolint:revive // file-level rationale.
package keyvault

import (
"crypto/rand"
"encoding/hex"
"errors"
"fmt"
"io/fs"
"os"
"path/filepath"
"strings"
)

// KeyFileName is the persisted platform secret written next to the database.
//
// #nosec G101 -- this is a file NAME, not a credential. The secret it names is
// generated at runtime and never appears in source.
const KeyFileName = "calnode.key"

// Where the platform secret came from, for logging and for tests.
const (
// #nosec G101 -- the NAME of an environment variable, not a credential.
SecretFromEnv = "CALNODE_ENCRYPTION_KEY"
SecretFromFile = "file"
SecretFromGenerated = "generated"
)

// ResolvePlatformSecret returns the platform secret that unlocks the vault.
//
// Precedence:
// 1. explicit (CALNODE_ENCRYPTION_KEY) - used verbatim, nothing is written.
// 2. an existing key file beside the database - read and reused.
// 3. no key at all - a new random secret is generated, written 0600 beside the
// database, and returned. This is the plain `docker run` case.
//
// dbPath is the on-disk database file; the key is placed in the same directory.
// The purpose is that a restart, an update, or a restored volume finds the same
// secret and the ciphertext in the database stays readable.
func ResolvePlatformSecret(explicit, dbPath string) (secret, source, path string, err error) {
if explicit != "" {
return explicit, SecretFromEnv, "", nil
}
if strings.TrimSpace(dbPath) == "" {
return "", "", "", errors.New("keyvault: no database path to place " + KeyFileName + " beside")
}

path = filepath.Join(filepath.Dir(dbPath), KeyFileName)

// An unreadable-but-present file must not silently fall through to
// generating a new secret: that would replace a working key with one that
// cannot decrypt the existing database.
// #nosec G304 -- path is derived from the operator's DATABASE_URL, not from
// request data. Where the key lives is deployment configuration.
if raw, readErr := os.ReadFile(path); readErr == nil {
existing := strings.TrimSpace(string(raw))
if existing == "" {
return "", "", "", fmt.Errorf(
"keyvault: %s exists but is empty; delete it to generate a new key, "+
"or restore it together with the database", path)
}
return existing, SecretFromFile, path, nil
} else if !errors.Is(readErr, fs.ErrNotExist) {
return "", "", "", fmt.Errorf("keyvault: read %s: %w", path, readErr)
}

if mkErr := os.MkdirAll(filepath.Dir(path), 0o700); mkErr != nil {
return "", "", "", fmt.Errorf("keyvault: create key directory: %w", mkErr)
}

var raw [32]byte
if _, randErr := rand.Read(raw[:]); randErr != nil {
return "", "", "", fmt.Errorf("keyvault: generate platform secret: %w", randErr)
}
generated := hex.EncodeToString(raw[:])

// O_EXCL so two processes starting at once cannot overwrite each other; the
// loser re-reads the winner's file rather than proceeding with its own.
// #nosec G304 -- same operator-controlled path as above.
f, createErr := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
if errors.Is(createErr, fs.ErrExist) {
// #nosec G304 -- same operator-controlled path.
if existing, readErr := os.ReadFile(path); readErr == nil {
if s := strings.TrimSpace(string(existing)); s != "" {
return s, SecretFromFile, path, nil
}
}
return "", "", "", fmt.Errorf("keyvault: %s appeared but could not be read", path)
}
if createErr != nil {
return "", "", "", fmt.Errorf("keyvault: create %s: %w", path, createErr)
}
if _, writeErr := f.WriteString(generated + "\n"); writeErr != nil {
// Join rather than discard: a close or cleanup failure is worth reporting
// alongside the write failure, and a half-written key file must not be
// left behind looking usable.
writeErr = errors.Join(writeErr, f.Close())
if rmErr := os.Remove(path); rmErr != nil && !errors.Is(rmErr, fs.ErrNotExist) {
writeErr = errors.Join(writeErr, rmErr)
}
return "", "", "", fmt.Errorf("keyvault: write %s: %w", path, writeErr)
}
if closeErr := f.Close(); closeErr != nil {
if rmErr := os.Remove(path); rmErr != nil && !errors.Is(rmErr, fs.ErrNotExist) {
closeErr = errors.Join(closeErr, rmErr)
}
return "", "", "", fmt.Errorf("keyvault: close %s: %w", path, closeErr)
}

return generated, SecretFromGenerated, path, nil
}
Loading
Loading