Zaki
01c56edf25
In a zero-knowledge vault, forgetting the master password normally
means losing the data — the AES key is derived from the master pw
and the server can't help. This commit adds the standard escape
hatch: a one-time recovery code that key-wraps the AES key so the
user can get back in.
Threat model
============
The plaintext recovery code is shown to the user exactly once, at
generation time. Server only ever stores SHA-256(code) + an AES-GCM
wrap of the vault key under a KEK = PBKDF2(code, kdf_salt, 600k).
Without the plaintext code the server cannot unwrap. The code is
high-entropy (96 bits from a 32-char ambiguity-free alphabet, in 4
groups of 4) — printed form is misreading-resistant.
Single use: redeeming deletes the row inside the same DB.Lock the
lookup happened in, so concurrent redeem attempts are race-free.
Failed redemptions feed both the per-IP rate limit AND the per-
username lockout, so brute-forcing the code is infeasible.
Schema
======
recovery_keys (
user_id INTEGER PRIMARY KEY (1:1 with users, FK cascade),
code_hash TEXT NOT NULL (SHA-256 hex of plaintext code),
kdf_salt TEXT NOT NULL (PBKDF2 salt for KEK derivation),
wrapped_key TEXT NOT NULL (base64 AES-GCM ciphertext of vault key),
wrapped_iv TEXT NOT NULL (base64 12B IV for the wrap),
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
)
Backend: new unit PM.Handler.Recovery
=====================================
GET /recovery-key/status (auth) -> { configured, created_at? }
POST /recovery-key/setup (auth + CSRF) body {masterPassword, codeHash,
kdfSalt, wrappedKey, wrappedIv}
DELETE /recovery-key (auth + CSRF) -> remove config
POST /recovery-key/redeem (NO auth) body {username, code}
-> session + wrappedKey + wrappedIv + kdfSalt
+ user's current salt + kdfIterations
VerifyMasterPassword() helper handles both legacy 'pbkdf2' and
current 'pbkdf2-sha256' schemes consistently with PM.Handler.Auth.
Setup flow
==========
1. Settings → "Generate recovery code" button (asks master pw via reauth).
2. Client generates: 16-char code + fresh kdf_salt + exports the current
AES key via crypto.subtle.exportKey('raw').
3. Client wraps the raw key under KEK=PBKDF2(code, kdf_salt, 600k)
with a random 12B IV → base64.
4. POSTs to /recovery-key/setup. Server verifies master pw, INSERT-or-
replaces the row (DELETE+INSERT, no UPSERT — same pattern as the
lockout table since FireDAC's UPSERT support is patchy).
5. Confirm modal shows the plaintext code in a monospace, user-select-all
panel. The modal is forcing: "I saved it" button is the only way out.
Modal is the only place the code ever appears — server never sees it.
Redeem flow (forgot master pw)
==============================
1. Auth screen → "Forgot master password? Use a recovery code" link.
2. promptDialog: username, then code (masked input).
3. POST /recovery-key/redeem. Server hashes the typed code, joins with
users by username, ConstantTimeEquals against stored hash. On match:
- deletes the recovery_keys row (single-use)
- issues a fresh session token + CSRF
- returns: { token, csrfToken, salt, kdfIterations, kdfSalt,
wrappedKey, wrappedIv, userId }
4. Client unwraps the AES key with PBKDF2(code, kdfSalt, 600k) → raw bytes
→ importKey('raw') back into a CryptoKey.
5. State is reconstituted from the new session, persistCryptoKey, enterApp.
6. Client immediately opens the Change-master-password modal — the
recovery code is consumed and the account needs a fresh master pw
AND a fresh recovery code (the user generates a new one from Settings).
Backward compat
===============
Recovery is opt-in. Existing users see "No recovery key set" in Settings
until they generate one. No migration needed — the table is created via
CREATE TABLE IF NOT EXISTS at server startup, FK cascade on user delete.
Minor UI additions
==================
- .btn-link CSS class for the auth-screen "Forgot master password?" link.
- Recovery-status label in Settings refreshed on every openSettings()
via GET /recovery-key/status.
33 lines
1.0 KiB
ObjectPascal
33 lines
1.0 KiB
ObjectPascal
program PMServer;
|
|
|
|
uses
|
|
System.StartUpCopy,
|
|
FMX.Forms,
|
|
UMainForm in 'UMainForm.pas' {MainForm},
|
|
PM.JSON in 'Source\PM.JSON.pas',
|
|
PM.Database in 'Source\PM.Database.pas',
|
|
PM.Router in 'Source\PM.Router.pas',
|
|
PM.StaticFiles in 'Source\PM.StaticFiles.pas',
|
|
PM.EmbeddedAssets in 'Source\PM.EmbeddedAssets.pas',
|
|
PM.Crypto in 'Source\PM.Crypto.pas',
|
|
PM.RateLimit in 'Source\PM.RateLimit.pas',
|
|
PM.Audit in 'Source\PM.Audit.pas',
|
|
PM.Session in 'Source\PM.Session.pas',
|
|
PM.HTTPServer in 'Source\PM.HTTPServer.pas',
|
|
PM.Bridge in 'Source\PM.Bridge.pas',
|
|
PM.Handler.Ping in 'Handlers\PM.Handler.Ping.pas',
|
|
PM.Handler.Auth in 'Handlers\PM.Handler.Auth.pas',
|
|
PM.Handler.Folders in 'Handlers\PM.Handler.Folders.pas',
|
|
PM.Handler.Entries in 'Handlers\PM.Handler.Entries.pas',
|
|
PM.Handler.Passkey in 'Handlers\PM.Handler.Passkey.pas',
|
|
PM.Handler.Recovery in 'Handlers\PM.Handler.Recovery.pas';
|
|
|
|
{$R *.res}
|
|
{$R assets\assets.res}
|
|
|
|
begin
|
|
Application.Initialize;
|
|
Application.CreateForm(TMainForm, MainForm);
|
|
Application.Run;
|
|
end.
|