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
33 changes: 33 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,23 @@ exact tag (`ghcr.io/calnode/calnode:0.1.0`) if you need stability between upgrad
## [Unreleased]

### Fixed
- **A plain `docker run` no longer loses stored credentials on restart.** The documented
first install starts Calnode with no `CALNODE_ENCRYPTION_KEY`. With `BASE_URL` on
`http://`, the vault treated that as development mode and generated an ephemeral data key,
so every credential stored in the database — the SMTP password, Stripe keys, Zoom and
LiveKit secrets, OAuth client secrets — became unreadable at the next restart, while the
volume made the data look persisted. The only signal was the `BASE_URL` scheme, so a
production deployment behind a TLS-terminating proxy (`BASE_URL http`, TLS at the edge)
took the same silent path. A secret is now resolved before the vault opens: an explicit
`CALNODE_ENCRYPTION_KEY` still wins and writes nothing, an existing key file beside the
database is reused, and only a genuinely fresh install generates one, written `0600` with
`O_EXCL` so two starts cannot overwrite each other. An empty key file is now an error
rather than a cue to generate a replacement.
- **A restore that is missing the encryption key now fails instead of starting fresh over an
encrypted database.** If the database already holds a wrapped data key but no key file is
present, Calnode generates one and then refuses to start, because it cannot unwrap the
existing data key — it never re-keys the data. The generated file is useless: replace it
with the real key, or set `CALNODE_ENCRYPTION_KEY`, before retrying the restore.
- **An NS8 module release can no longer mix architectures.** The module build pushes each
architecture to a fixed staging tag (`:build-amd64`, `:build-arm64`) and then assembles the
multi-arch index from them. The workflow's concurrency group included the git ref, so a
Expand All @@ -24,6 +41,22 @@ exact tag (`ghcr.io/calnode/calnode:0.1.0`) if you need stability between upgrad
cancelled by an unrelated push. The post-publish architecture assertion is what caught it
and remains in place.

### Changed
- **The encryption key is persisted beside the database, and must be backed up with it.**
When Calnode generates the platform secret itself it writes `calnode.key` next to the
database (`/data/calnode.key` in the container). Litestream replicates the database, not
that file, so the two must be kept together: restoring the database alone will not start.
Deployments that set `CALNODE_ENCRYPTION_KEY` in the environment are unchanged and write
no key file.

### 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.

container really are `aarch64`, checks the app serves over HTTP, and — the part that
matters for this release — verifies the key file is persisted and that a restart unwraps
the existing data key rather than generating a new one. On a publish it pulls the exact
digest the build job produced, so it cannot pass against a stale tag.

## [0.11.2] - 2026-10-28

### Added
Expand Down
16 changes: 16 additions & 0 deletions DEPLOY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

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.

>
> 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 '
Expand Down
Loading