diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index 29933937..56f52598 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -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 @@ -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: . @@ -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}}' + + - 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') diff --git a/README.md b/README.md index 411efeb1..65102b39 100644 --- a/README.md +++ b/README.md @@ -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)**. --- diff --git a/cmd/calnode/main.go b/cmd/calnode/main.go index 1b70edc5..defd7f91 100644 --- a/cmd/calnode/main.go +++ b/cmd/calnode/main.go @@ -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( + 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) diff --git a/cmd/calnode/mcp.go b/cmd/calnode/mcp.go index aa6984d2..b0444be5 100644 --- a/cmd/calnode/mcp.go +++ b/cmd/calnode/mcp.go @@ -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) diff --git a/internal/db/db.go b/internal/db/db.go index 21c62409..f887c8f1 100644 --- a/internal/db/db.go +++ b/internal/db/db.go @@ -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://") diff --git a/internal/keyvault/keyvault.go b/internal/keyvault/keyvault.go index 2a799a2c..808b3920 100644 --- a/internal/keyvault/keyvault.go +++ b/internal/keyvault/keyvault.go @@ -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 { diff --git a/internal/keyvault/secret.go b/internal/keyvault/secret.go new file mode 100644 index 00000000..ccf494c3 --- /dev/null +++ b/internal/keyvault/secret.go @@ -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 +} diff --git a/internal/keyvault/secret_test.go b/internal/keyvault/secret_test.go new file mode 100644 index 00000000..74ef31c5 --- /dev/null +++ b/internal/keyvault/secret_test.go @@ -0,0 +1,134 @@ +package keyvault + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +func TestResolveExplicitSecretWinsAndWritesNothing(t *testing.T) { + dir := t.TempDir() + dbPath := filepath.Join(dir, "calnode.db") + + secret, source, path, err := ResolvePlatformSecret("explicit-value", dbPath) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if secret != "explicit-value" { + t.Fatalf("secret = %q, want the explicit value", secret) + } + if source != SecretFromEnv { + t.Fatalf("source = %q, want %q", source, SecretFromEnv) + } + if path != "" { + t.Fatalf("path = %q, want empty when the env var is used", path) + } + if _, statErr := os.Stat(filepath.Join(dir, KeyFileName)); !os.IsNotExist(statErr) { + t.Fatalf("a key file was written even though CALNODE_ENCRYPTION_KEY was set") + } +} + +func TestResolveGeneratesAndPersistsBesideDatabase(t *testing.T) { + dir := t.TempDir() + dbPath := filepath.Join(dir, "calnode.db") + + secret, source, path, err := ResolvePlatformSecret("", dbPath) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if source != SecretFromGenerated { + t.Fatalf("source = %q, want %q", source, SecretFromGenerated) + } + if want := filepath.Join(dir, KeyFileName); path != want { + t.Fatalf("path = %q, want %q", path, want) + } + if len(secret) != 64 { + t.Fatalf("secret length = %d, want 64 hex chars (32 bytes)", len(secret)) + } + + info, statErr := os.Stat(path) + if statErr != nil { + t.Fatalf("key file missing: %v", statErr) + } + if perm := info.Mode().Perm(); perm != 0o600 { + t.Fatalf("key file mode = %o, want 600: the platform secret must not be group/world readable", perm) + } +} + +func TestResolveIsStableAcrossRestarts(t *testing.T) { + // This is the whole point: a restart must find the same secret, or every + // encrypted column in the database becomes unreadable. + dir := t.TempDir() + dbPath := filepath.Join(dir, "calnode.db") + + first, _, _, err := ResolvePlatformSecret("", dbPath) + if err != nil { + t.Fatalf("first call: %v", err) + } + second, source, _, err := ResolvePlatformSecret("", dbPath) + if err != nil { + t.Fatalf("second call: %v", err) + } + if first != second { + t.Fatalf("secret changed between starts: %q then %q", first, second) + } + if source != SecretFromFile { + t.Fatalf("source on second call = %q, want %q", source, SecretFromFile) + } +} + +func TestResolveEmptyKeyFileIsAnErrorNotANewKey(t *testing.T) { + // Generating a replacement here would destroy access to the existing data. + dir := t.TempDir() + dbPath := filepath.Join(dir, "calnode.db") + if err := os.WriteFile(filepath.Join(dir, KeyFileName), []byte("\n"), 0o600); err != nil { + t.Fatal(err) + } + + _, _, _, err := ResolvePlatformSecret("", dbPath) + if err == nil { + t.Fatal("expected an error for an empty key file, got nil") + } + if !strings.Contains(err.Error(), "empty") { + t.Fatalf("error = %v, want it to mention the empty key file", err) + } +} + +func TestResolveReadsExistingKeyFile(t *testing.T) { + dir := t.TempDir() + dbPath := filepath.Join(dir, "calnode.db") + if err := os.WriteFile(filepath.Join(dir, KeyFileName), []byte("deadbeef\n"), 0o600); err != nil { + t.Fatal(err) + } + + secret, source, _, err := ResolvePlatformSecret("", dbPath) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if secret != "deadbeef" { + t.Fatalf("secret = %q, want deadbeef (trailing newline trimmed)", secret) + } + if source != SecretFromFile { + t.Fatalf("source = %q, want %q", source, SecretFromFile) + } +} + +func TestResolveNeedsADatabasePath(t *testing.T) { + if _, _, _, err := ResolvePlatformSecret("", ""); err == nil { + t.Fatal("expected an error when there is no database path") + } +} + +func TestResolveCreatesMissingDirectory(t *testing.T) { + dir := t.TempDir() + dbPath := filepath.Join(dir, "nested", "deeper", "calnode.db") + + _, _, path, err := ResolvePlatformSecret("", dbPath) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if _, statErr := os.Stat(path); statErr != nil { + t.Fatalf("key file not created in missing directory: %v", statErr) + } +}