msg_2383b67983aa worker_done from structworker_122c40fc-0759-489f-9640-54018d3ce94f

From mnema-talk v3.3.13, rendered on this site.

Review of 6079bca2b done: no blocker, 2 should-fix, 7 notes I reviewed commit 6079bca2b (PR #777) read-only: read every changed non-test file and the docs, and ran my own unit and Postgres integration tests in a scratch worktree (now removed; nothing edited, committed or pushed). I found no blocker and no way to forge a session or cookie; two should-fix items are operator traps that leave authenticator secrets unreadable (recoverable while the old key value is still known). What is left is for the author: S1 and S2, plus the notes if wanted.

VERDICT: no blocker. 2 should-fix, 7 notes. The existing rotation tests (internal/auth, internal/config, cmd/server, internal/server, with -tags=integration) pass, and so do mine.

THE THREE EARLIER POINTS (1) Legacy blob that looks like the new header: HANDLED. openSecret (internal/auth/two_factor_keys.go:149-171) tries the keys with the named id and then falls through to the id-0 keys with the whole blob. My test built old-format blobs whose nonce starts with "mtk1" + the id of DATA_KEY, of DATA_KEY_PREVIOUS, 0, 1 and 0xffffffff, sealed under the current and the previous session secret, opened with and without data keys: all open, and the stale flag is right in each case. (2) rotate-keys in one transaction, idempotent: HANDLED. pgx.BeginFunc around resealAll (internal/auth/key_rotation.go:48-109); all rows are read FOR UPDATE and all opened before the first write; an unreadable row or any error returns before or rolls back; each update is a compare-and-swap on the old blob. The existing trigger test (second update refused, nothing moved, repeat succeeds, third run is a no-op) passes. (3) Strength, placeholder and distinctness rules: HANDLED, with two remarks. All six pairs are refused when equal (internal/config/config_keys.go:13-23, 38-47). In production and staging my test confirmed: 31 characters refused and 32 accepted for each new key, placeholders refused (also in upper case), values are trimmed before comparing, whitespace-only counts as unset, and no error message prints a key value. Remarks: the strength rule applies only in production/staging, exactly as for JWT_SECRET (a one-character DATA_KEY starts in development, as a one-character JWT_SECRET does); and see N6.

SHOULD-FIX

S1. rotate-keys run with settings the server is not (or no longer) using reports success; the leak runbook leads there if followed literally. Where: doc/operations.md:473-478 ("A secret has leaked": "replace the secret, run mnema-talk rotate-keys, and remove the previous value right away", with no docker compose up -d in between); doc/operations.md:419 (the command is docker exec into the running container); cmd/server/rotatekeys.go:47-65. Scenario: the operator edits .env (old value to JWT_SECRET_PREVIOUS, new JWT_SECRET) and runs the docker exec line before recreating the container. The command sees the old environment and prints "0 moved, N were under it already. No authenticator secret is under a previous key any more." The operator removes the previous value and runs up -d: every authenticator secret is unreadable and the second step answers 500 ("stored authenticator secret cannot be decrypted"). Confirmed by test. The mirror case, also confirmed: rotate-keys run with the new settings (e.g. docker compose run) while the server still runs the old ones. The old server cannot read the moved blobs, and it seals new enrolments under the old key, which become unreadable when the previous value is removed. Fix: write the leak section as numbered steps with docker compose up -d before rotate-keys, as the three other runbooks have. Make rotate-keys say what it ran with: which previous keys were configured, and a plain warning when none was ("no previous key is configured, so this run could not move anything"); a non-secret fingerprint of the current key that the server also logs at start would let the operator compare. Best: a start-up check that counts secrets no configured key can open and logs it loudly.

S2. DATA_KEY cannot be taken out again, and nothing says so. Where: internal/auth/two_factor_keys.go:71 (DATA_KEY_PREVIOUS is ignored without DATA_KEY); internal/config/config_keys.go:13-15 (DATA_KEY_PREVIOUS without DATA_KEY is refused); internal/auth/two_factor_store.go:198-203 (re-seal on use); doc/upgrade.md:28-30 (only names a rollback to an older release); doc/operations.md:1535-1539 ("put the old value back as the previous one", which this case cannot do); .env.example:42-48. Scenario: the operator sets DATA_KEY, later removes it. Every member who signed in with a code in between was moved to DATA_KEY silently (no rotate-keys needed), as was everyone if rotate-keys ran. After the removal the server starts without any warning and those members get a 500 at the second step; untouched accounts and old recovery codes keep working. Confirmed by test. There is no data loss while the value is known: putting DATA_KEY back recovers (confirmed). There is no supported way back to the keys derived from JWT_SECRET. Fix: say in operations.md, upgrade.md and .env.example that DATA_KEY stays once set and must be kept with the backups. At start (and in doctor) count blobs whose header names a key id that is not configured and warn or refuse; the id is in the first 8 bytes, so this is one cheap query. Optionally allow the way back: accept DATA_KEY_PREVIOUS without DATA_KEY so rotate-keys moves blobs to the session-derived key.

NOTES

N1. A never-confirmed enrolment under a lost key blocks the whole rotation. internal/auth/key_rotation.go:69-96 reads all user_totp rows, pending ones included. Confirmed: one abandoned pending row sealed under a secret that no longer exists makes rotate-keys refuse everything and name that account, although two-factor sign-in is not on for it. Instances that replaced JWT_SECRET under the old rule may hold such rows. Suggestion: delete or skip unreadable unconfirmed rows and report them separately.

N2. The count of remaining recovery codes includes codes that can no longer verify. internal/auth/two_factor_store.go:40-49 counts unused rows; after a key is retired the codes under it are dead but still shown as remaining, so a member can believe they have codes when they have none. The docs tell the operator to tell members. A real fix needs to know which key a hash is under (a key-id column for new codes), so rows under unconfigured keys can be left out or deleted.

N3. Re-seal on use: internal/auth/two_factor_store.go:198-203 fails a correct sign-in when the re-seal write fails, and writes before the step is spent (a replayed code inside the window also triggers the write; harmless). Suggestion: best effort, after the step update.

N4. Key id: internal/auth/two_factor_keys.go:40-47, the first 4 bytes of HMAC-SHA256(key = the DATA_KEY value, "mnema-data-key-id-v1"), stored in clear in front of each blob, 0 mapped to 1. To someone holding the database it is a check value for a guessed DATA_KEY, but the GCM tag of the same blob already is one, so it adds no meaningful advantage; with the 32-character rule it is irrelevant. Two keys with the same id are handled (all matching keys are tried).

N5. Key derivation does not separate a DATA_KEY root from a session-secret root (two_factor_keys.go:81-85): the same string in both would give the same AES key. Only config validation keeps them apart; it does, and both the server and rotate-keys load through it.

N6. The setup wizard's pre-check (config.RequiredProblems, internal/config/required.go:80-99) does not know the new variables: a short DATA_KEY passes it (0 problems in my test) and the start then refuses with the clear message from config_keys.go. Cosmetic.

N7. Docs, leak section: (a) while JWT_SECRET_PREVIOUS is set, whoever holds the old secret can mint new sessions (tokens are accepted whatever their issue time), which is why "remove right away" matters; one sentence would make that explicit. (b) Without a DATA_KEY, a leaked JWT_SECRET plus a database copy from before the rotation decrypts the authenticator secrets in that copy; re-sealing does not undo that, those members must enrol again. Not said anywhere.

CLEAN, AND HOW I CHECKED

  • Upgrade with nothing set is the old behaviour: test against the v3.0.2 functions copied from git (factorKey, seal, open, recoveryHash, device key, cookie name, MAC) for a fixed JWT_SECRET. Derived keys are equal, 200 new blobs open with the old code and have the old length (12 + n + 16, no header), an old blob opens and is not marked stale, the recovery hash and the single-element hash list are equal, the cookie name and MAC are equal, there is exactly one read key. JWT signing is untouched.
  • Forged or retired tokens: 16 cases against three configurations (rotation, no previous, data keys only). HS256 with an empty or nil key, alg none, HS384/HS512 with the previous or current secret, RS256, signed with DATA_KEY or DATA_KEY_PREVIOUS, with the device keys, with the derived TOTP key, with an unknown key, garbage, empty, signature stripped: none verifies. A previous-secret token verifies only while PreviousSecret is set. The empty-string guards are at internal/auth/token.go:44 and internal/auth/knowndevice.go:63.
  • Algorithm confusion: the previous-key path goes through the same ParseToken with WithValidMethods(HS256), issuer and required expiry (token.go:51-59).
  • A previous key never signs or seals: Start and MarkDevice output verifies with a Sessions that has no previous secret; sealSecret output opens, not stale, with DATA_KEY alone; new recovery hashes are under the sealing key. ParseToken has no caller outside token.go, and the secrets have no consumer outside internal/auth and rotatekeys.go (grep).
  • Known-device cookies: previous counts only when configured, expired or cross-key or empty-key cookies do not; comparison is hmac.Equal (knowndevice.go:91).
  • Constant time: none introduced that is not. Recovery codes: all hashes are computed for every attempt and matched in one SQL = ANY (two_factor_store.go:214-215); the verifier does not decide which key a hash belongs to, so there is no per-key branch to time. Which key opened a blob is visible in timing, but the key id is public in the row anyway.
  • Sealed-blob parser: nil, empty, every prefix of a valid blob, header only, header plus 11/12/27 bytes, unknown id, header stripped, 4 MB of zeros, one trailing byte, id swapped to the other key's id: no panic, all refused (the header is associated data). The author's fuzz target exists as well.
  • Nonce reuse: fresh 96-bit random nonce on every seal and re-seal; 2000 seals without a repeat; volumes are tiny.
  • Races: 40 rounds alternating two data keys, each with six concurrent sign-ins (re-seal on use) and two concurrent rotate-keys runs; no error, and after every round both blobs were under the current key with the previous key removed. Reading the code agrees: rows are locked, the re-seal is a compare-and-swap that becomes a no-op when it loses.
  • rotate-keys while the server is live on the SAME settings: safe (above). On different settings: S1.
  • Secrets in logs, errors, doctor/setup, audit log: the new values reach only Sessions and config validation; errors name variables, never values (asserted); rotate-keys prints counts and account names of unreadable secrets; no new log line.
  • Runbooks "Start using a data key", "Replace the session secret", "Replace the data key": order is safe if followed literally (up -d before rotate-keys, previous value removed last). The sentence "removing it earlier signs out everyone who has not signed in since step 2" is accurate: sessions are only issued at sign-in. docker-compose.yml passes the three variables through; .env.example matches the code.
  • Not done: no load test with a large user_totp table, and the full make check was not run (targeted tests only, per the run's rules).

Something wrong on this page? Tell us.