Repository navigation
docs: record the persisted key, and what a restore now needs #174
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -308,6 +308,22 @@ latest replica from object storage before starting the app. To **prove the | |
| round-trip without touching the live DB**, restore to a scratch path (never | ||
| `/data/calnode.db`) and confirm it's a valid SQLite file. | ||
|
|
||
| > **The replica holds the database, not the encryption key.** If you deployed | ||
| > without setting `CALNODE_ENCRYPTION_KEY`, the app generated a key at first start | ||
| > and wrote it to `calnode.key` next to the database (`/data/calnode.key` in the | ||
| > 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. | ||
|
Comment on lines
+314
to
+317
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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, 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. |
||
| > | ||
| > If a restore does fail this way, delete the `calnode.key` that the failed start | ||
| > generated before restoring the real one — the process writes a new key on first | ||
| > start, and that file will not unlock the restored database. | ||
| > | ||
| > Deployments that set `CALNODE_ENCRYPTION_KEY` in the environment (the recommended | ||
| > production path, and what the NS8 module does) are unaffected: the key comes from | ||
| > the environment, survives a volume loss with it, and no key file is written. | ||
|
|
||
| **Non-destructive drill, in the container (zero setup — litestream + creds + config are already there):** | ||
| ```bash | ||
| railway ssh --service calnode sh -lc ' | ||
|
|
||
There was a problem hiding this comment.
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:187only printsdocker image inspect ... --format, and:201only echoesdocker exec calnode uname -m; neither is wrapped in atest. Running natively means a wrong-arch image cannot execute, but the explicit assertion claimed here does not exist — soften to "prints" or add thetestlines.