Repository navigation
docs: record the persisted key, and what a restore now needs - #174
Conversation
#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.
There was a problem hiding this comment.
ℹ️ 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.keyis persisted beside the database and must be backed up separately from the Litestream replica. - CHANGELOG —
Added: the native-ARMarm64-smokegate. - 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?deepseek-v4.1-flash | 𝕏
| > 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. |
There was a problem hiding this comment.
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.|
|
||
| ### 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 |
There was a problem hiding this comment.
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.

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:2.
DEPLOY.mddescribed the old recovery contractIt said: "Recovery is automatic: if the volume comes up empty,
entrypoint.shrestores the latest replica." That remains true for the database, but Litestream does not replicatecalnode.key, so a deployment that never setCALNODE_ENCRYPTION_KEYcannot start from a restore alone. Added a note covering:calnode.keythat must be replaced with the real one;CALNODE_ENCRYPTION_KEYare 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/### Addedper section, the 0.11.2 section is untouched, and no code changed.