alvaro/normogen
1
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

docs: update ADR for ZK Phase 2 (wrapped-DEK recovery) completion
Some checks failed
Lint and Build / format (push) Successful in 33s
Details
Lint and Build / clippy (push) Successful in 1m36s
Details
Lint and Build / build (push) Successful in 3m37s
Details
Lint and Build / test (push) Failing after 2m33s
Details

Browse source 
Records the implemented wrapped-DEK recovery model, new endpoints, and the
password-change re-wrapping. Strikes the 'future' Phase 2 items as done.
This commit is contained in:
goose 2026-06-29 08:51:03 -03:00
parent 8a538cbbb8
commit 38bf0ae8b4
1 changed files with 27 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

33
docs/adr/zero-knowledge-encryption.md
View file

@ -1,7 +1,7 @@
# ADR: Zero-Knowledge Encryption (Phase 1)
**Status**: Implemented (Phase 1)
**Date**: 2026-06-28
**Status**: Implemented (Phase 1 + Phase 2)
**Date**: 2026-06-28 (Phase 1), 2026-06-29 (Phase 2)
## Context
@ -56,10 +56,31 @@ re-derive it. This is the core ZK trade-off.
- No data migration was needed (no real user data existed).
### Phase 2 (future)
- Recovery key-wrapping (wrap the enc key under a recovery-derived key so a
forgotten password doesn't lose data).
- Password-change re-wrapping (re-wrap the enc key under the new password).
- Wrapped-DEK model (separate data-encryption key + key-encryption key).
- ~~Recovery key-wrapping (wrap the enc key under a recovery-derived key so a
forgotten password doesn't lose data).~~ **Done (Phase 2).**
- ~~Password-change re-wrapping (re-wrap the enc key under the new password).~~ **Done (Phase 2).**
- ~~Wrapped-DEK model (separate data-encryption key + key-encryption key).~~ **Done (Phase 2).**
## Phase 2: Wrapped-DEK Recovery (Implemented)
Phase 2 introduced the wrapped-DEK model so a forgotten password doesn't lose
all encrypted data:
- A **random DEK** (data encryption key) encrypts all user data (not a key
derived directly from the password).
- The DEK is **wrapped** (AES-GCM encrypted) under a password-derived KEK and
a recovery-phrase-derived KEK. Both wrapped forms are stored on the server.
- At login, the client derives the password KEK and **unwraps** the DEK.
- At recovery, the client derives the recovery KEK, unwraps the DEK from the
recovery-wrapped form, **re-wraps** it under the new password, and sends the
new wrapped form to the server.
- Password change also re-wraps the DEK under the new password.
- New endpoints: `GET /api/auth/recovery-info` (returns the recovery-wrapped
DEK), updated `POST /api/auth/recover-password` (accepts new wrapped DEK).
- New frontend: `RecoveryPage` (email → recovery phrase → new password flow),
recovery phrase field on `RegisterPage`.
The server never holds the DEK or any KEK — only the wrapped forms.
## Relationship to the original design doc