Skip to content

docs: record the persisted key, and what a restore now needs - #174

Merged
shockalotti merged 1 commit into
mainfrom
docs/key-file-and-restore
Oct 28, 2026
Merged

shockalotti merged 1 commit into
mainfrom
docs/key-file-and-restore

Conversation

@shockalotti

Copy link
Copy Markdown
Contributor

Follow-up to #173, which was merged as 30d6408. Two gaps found in review, both documentation.

1. No CHANGELOG entry

#173 was a user-facing fix plus new behaviour, and the CHANGELOG is what generates release notes. Added under Unreleased:

  • the silent-credential-loss bug and how the secret is now resolved,
  • the restore behaviour, described as it actually is rather than as it ideally would be,
  • the key-file backup requirement,
  • the new native arm64 gate.

2. DEPLOY.md described the old recovery contract

It said: "Recovery is automatic: if the volume comes up empty, entrypoint.sh restores the latest replica." That remains true for the database, but Litestream does not replicate calnode.key, so a deployment that never set CALNODE_ENCRYPTION_KEY cannot start from a restore alone. Added a note covering:

  • the replica holds the database, not the key;
  • a failed restore generates a useless calnode.key that must be replaced with the real one;
  • deployments that set CALNODE_ENCRYPTION_KEY are unaffected.

Deliberately not done here

The stronger guard — refuse to generate a key at all when the database already holds a wrapped data key — is a behaviour change in the key-resolution path, and it needs a distinguishable "wrong key" error to remove the file safely. Flagged on #173; worth its own change.

Verification

Docs only. CHANGELOG parses with a single ### Fixed / ### Changed / ### Added per section, the 0.11.2 section is untouched, and no code changed.

#173 made the platform secret persist beside the database when it is not
supplied in the environment, which fixes a real silent data-loss bug. Two
documentation gaps were left:

1. No CHANGELOG entry. This is a user-facing fix plus new behaviour, and the
   CHANGELOG is what generates release notes. Recorded under Unreleased,
   describing what actually happens rather than the ideal: a restore missing
   the key generates one and then refuses to start, so the data is never
   re-keyed, and the generated file has to be replaced.

2. DEPLOY.md still says recovery is automatic when the volume comes up empty.
   That is no longer the whole story for deployments without
   CALNODE_ENCRYPTION_KEY: Litestream replicates the database, not calnode.key,
   so restoring the replica alone will not start. Added the caveat, the
   recovery step for a failed restore, and the note that env-key deployments
   are unaffected.

@pullfrog pullfrog Bot left a comment

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.

ℹ️ No critical issues — one accuracy gap in the new restore note, plus sibling docs that still describe the pre-#173 contract.

Reviewed changes

Docs-only follow-up to #173, checked against main at 30d6408. Adds:

  • CHANGELOG — Fixed: the silent credential-loss bug and the new secret resolution, plus the restore failure mode.
  • CHANGELOG — Changed: calnode.key is persisted beside the database and must be backed up separately from the Litestream replica.
  • CHANGELOG — Added: the native-ARM arm64-smoke gate.
  • DEPLOY §6: a restore note covering the replica/key split and the useless key a failed start leaves behind.

ℹ️ DEPLOY.md still documents the old key-enforcement contract elsewhere

The new note in §6 is accurate for current databases, but three other places in the same file still tell operators the pre-#173 story, so the guide now contradicts itself.

Technical details
# Stale pre-#173 statements left in DEPLOY.md

## Affected sites
- `DEPLOY.md:58` — `CALNODE_ENCRYPTION_KEY` is marked "prod: yes" and "Required
  when `BASE_URL` is https — the app refuses to start without it". `main.go:88-93`
  now resolves a key for every unset case; the app starts and writes `calnode.key`.
- `DEPLOY.md:60` — the `BASE_URL` row still promises "encryption-key enforcement".
  `devMode` now only affects cookies/other behaviour (`main.go:103-106`); it no
  longer gates key generation.
- `DEPLOY.md:423` — troubleshooting says "App won't start (prod)" is caused by a
  missing key with an https `BASE_URL`, which is no longer a startup failure.
- `docs/ARCHITECTURE.md:160-162` — "with no `CALNODE_ENCRYPTION_KEY` and a
  non-https BASE_URL, the vault generates an ephemeral per-process DEK ...
  Production (https BASE_URL) hard-fails without the key." Both arms are
  unreachable from `main`/`mcp` now that `ResolvePlatformSecret` runs first.

## Required outcome
- The variables table, troubleshooting row, and §5 dev caveat should describe the
  persisted-key behaviour (key optional but recommended, generated to 0600 next to
  the DB when unset, Litestream does not carry it) rather than "required / refuses
  to start / ephemeral".

## Open questions for the human
- Scope check: is `docs/ARCHITECTURE.md` deliberately left for a separate pass, or
  should this docs follow-up bring it in line too?

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using deepseek-v4.1-flash | 𝕏

Comment thread DEPLOY.md
Comment on lines +314 to +317
> container). Litestream does not replicate that file, so restoring the database
> from the replica on its own will not start: the restored rows are sealed under a
> key that is gone, and the app exits rather than re-keying your data. Back that
> file up separately, and restore it beside the database.

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 is not true for a pre-keystore database. When no key file exists, ResolvePlatformSecret generates a fresh 64-hex secret; if the restored DB has *_enc data but no crypto_keystore row, Open takes the legacy branch and adopts that generated secret as the DEK, so the app starts while the restored ciphertext stays unreadable. The CHANGELOG headline at CHANGELOG.md:27 has the same overstatement. Scope both to databases that already hold a wrapped data key, or warn that legacy backups behave differently.

Technical details
# Legacy restore silently adopts the generated key

## Affected sites
- `DEPLOY.md:314-317` — "will not start ... the app exits rather than re-keying"
- `CHANGELOG.md:27` — "a restore ... now fails instead of starting fresh"

## Why
- `internal/keyvault/secret.go:92-131` generates a 64-hex secret whenever no env
  key or key file exists.
- `internal/keyvault/keyvault.go:111-119` then finds no `primary` keystore row and
  calls `migrateLegacy` if any `*_enc` column is populated.
- `internal/keyvault/keyvault.go:193-206` hex-decodes that generated secret and
  stores it as the DEK, returning success. No verification against existing
  ciphertext, so startup succeeds with the wrong DEK.
- The "refuses to start" path is `openExisting`
  (`internal/keyvault/keyvault.go:98-105`, `:170-180`), which only runs when a
  wrapped DEK already exists.

## Required outcome
- Docs must distinguish: a DB with a `crypto_keystore` row fails to start and the
  generated key can be replaced; a legacy DB (no keystore row, `*_enc` data) starts
  with a key that cannot read the old secrets.

Comment thread CHANGELOG.md

### Added
- **The published arm64 image is now exercised on native hardware on every PR and every
publish.** A new `arm64-smoke` job runs on an ARM runner, asserts the image and the

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.

The job does not assert either architecture. .github/workflows/docker-publish.yml:187 only prints docker image inspect ... --format, and :201 only echoes docker exec calnode uname -m; neither is wrapped in a test. Running natively means a wrong-arch image cannot execute, but the explicit assertion claimed here does not exist — soften to "prints" or add the test lines.

@shockalotti
shockalotti merged commit 19c8023 into main Oct 28, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant