Skip to content

fix(crypto): send a proof, never the key, for recovery and family claims - #256

Merged
danileau merged 1 commit into
mainfrom
sec/proof-not-key
Nov 12, 2026
Merged

danileau merged 1 commit into
mainfrom
sec/proof-not-key

Conversation

@danileau

Copy link
Copy Markdown
Owner

Problem

Two requests sent the server the raw key that unlocks a copy of the master key the server already stores:

  • Recovery: /api/recover received recovery_key, the AES key of users.recovery_vault.
  • Family claim: /api/family/grants/claim received family_key as proof, the AES key of family_grants.wrapped_master.

Anyone able to read those request bodies on the server side (a compromised server, the TLS-terminating proxy, request logging) could unwrap that account's master key at the moment of a recovery or claim. Login was never affected; it already sends a separately derived key.

Fix

  • The client sends proof = SHA-256(key). At creation it sends verifier = SHA-256(proof), which is what the server stores. The keys never leave the browser: crypto.ts no longer returns them from any exported function.
  • New request fields: recovery_proof, grant_proof, recovery_verifier, grant_verifier.
  • Schema 10 adds users.recovery_verifier and family_grants.grant_verifier. It converts each existing value (SHA-256(key) becomes SHA-256(SHA-256(key))) and clears the old column. Keeping the old value would make a database leak a working credential, because it equals the new proof.
  • The conversion is idempotent and also runs on every boot at schema ≥ 10. After a rollback, the older image still writes the old columns for new sign-ups and invitations. Without the per-boot pass, those people would silently lose recovery and claims after the roll-forward.
  • Transition: clients cached from before this change still send the raw key in the old fields. The server accepts them by hashing once more, so nobody is locked out while their PWA updates. Accepting it adds no exposure, since that client has already sent the key. The legacy branch should be removed in a later release.
  • Redaction now also covers proof, grant_proof, recovery_proof and grant_auth; the claim endpoint now redacts too.

Rollback

The migration is marked compatible, so an older image still boots on schema 10. Its recovery and family claims fail with a 401, not a 500, until the roll-forward. Everything else works.

Residual

Database backups taken before this deploy hold the old SHA-256(key) values, which are now valid proofs. With one, someone could reset an account's password (the account stays recoverable with its code) or claim an invitation (ciphertext only, since the family key is still needed to decrypt). No plaintext is exposed. Treat pre-deploy backups as sensitive and let them age out.

Testing

  • API: 293 passed. New test_proof_not_key.py covers proof/verifier checks, legacy acceptance, confusion cases (raw key in the proof field, verifier as proof, both fields present, JSON null), verifier storage on register and grant creation, and the migration. A real-Postgres test checks that the SQL conversion matches the Python hashing and is a no-op on replay. The existing tests were moved to the new fields.
  • Frontend: 2256 passed. New crypto.proof.test.ts runs the real recovery and family flows with a deterministic KDF stand-in: nothing returned or sent equals a derived key, and the request layer has no field for a raw key. All 6 tests fail on the old code. svelte-check 0/0. Build OK.
  • Upgrade, on a throwaway Postgres 15:
    • A database created by origin/main (schema 9) was upgraded by this branch: 13 checks passed through the real endpoints. Recovery with a proof gives 200, an old client sending the raw key gives 200, a raw key in the proof field gives 401, and a family claim gives 401 with the key and 200 with the proof.
    • Rollback: the old image booted on schema 10, and recovery returned 401.
    • Roll-forward after a rollback-era signup: the row was converted on boot and that user could recover.
  • An independent security review found nothing Critical or High. Its rollback finding is fixed here (the per-boot conversion).

/health will report schema: 10.

@danileau
danileau merged commit fa7f5c8 into main Nov 12, 2026
4 checks passed
@danileau
danileau deleted the sec/proof-not-key branch November 12, 2026 14:49
@danileau danileau mentioned this pull request Nov 12, 2026
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