Crypto
Why a passkey, a passphrase, and a recovery kit
Sign-in and unlock are different jobs. Mixing them would either let the server read your mind or lock you out with no backup.
| Secret | Job | Who can reset it |
|---|---|---|
| Passkey or email link | Signs you into tuckthis.app. Session cookie. Syncs ciphertext between devices. | Website login only. Email links prove you still own the inbox. Never unwraps thoughts. |
| Vault passphrase | Daily unlock on this device (and others after they sync). Stretched with PBKDF2 on the device. Not sent to AWS. | Nobody. Forgot it? Use the kit. |
| Recovery kit | Second wrap of the same random data-encryption key. Print it, or generate a new one later from Account → Vault. A sealed copy can unwrap in an unlocked browser after sync. | You can mint a replacement. Lose both passphrase and kit and the ciphertext is gone. |
How the vault is locked
Thoughts are sealed with a random AES-256-GCM data-encryption key (the DEK) that the device generates. That key never travels in the clear. Two independent wraps of the same DEK are what let you unlock: the passphrase for daily use, and the recovery kit if the passphrase is gone. Mixing them into one unlock step would mean typing the kit every morning.
- The device generates a 256-bit DEK.
- Titles, bodies, tag names, attachment bytes, todo titles, calendar/mail secrets, and people names, emails, notes, and files are sealed with that DEK.
- The DEK is encrypted twice: passphrase (PBKDF2, 600,000 iterations) and recovery kit (10,000 iterations — the kit is already high entropy).
- Daily unlock = passphrase. Disaster unlock = kit. Refresh does not re-prompt until you lock or sign out.
Sync does not change this
A signed-in device uploads wraps + sealed notes to identity. A new laptop: passkey or email link → download blob → passphrase (or kit). AWS still cannot read thoughts. An operator with the session still cannot unwrap the DEK.
Brain names, dates, and reminder stubs stay in the clear so calendar, kanban, and the ingest worker can function without unlock. Sharing a tuck is opt-in: you publish a snapshot so a link can work without the vault. The original thought stays sealed.
What we will not do
- Derive the vault from a passkey or email link. A stolen inbox or lost device would become a vault breach.
- Email a “forgot passphrase” link. That would mean we could reconstruct the DEK.
- Store the recovery kit in Secrets Manager. Then we would hold the second wrap’s key.
Algorithms in full: docs/crypto.md in the repo. How boxes connect: architecture.