feat: zero-knowledge recovery (Phase 2) — wrapped-DEK model
Introduces a wrapped-DEK recovery model so a forgotten password doesn't lose all encrypted data. The encryption key becomes a random DEK (not derived from the password); the DEK is wrapped under both a password-derived KEK and a recovery-phrase-derived KEK, and both wrapped forms are stored on the server. Crypto (crypto/keys.ts): - DEK generation (random AES-256-GCM), KEK derivation (PBKDF2 password/recovery), wrapDek/unwrapDek/rewrapDek. - setupEncryption(password, recoveryPhrase?) — generates a DEK, wraps under both KEKs, returns wrapped forms + recovery proof. - unlockWithPassword(password, wrappedDek) — derives password KEK, unwraps DEK. - unlockWithRecovery(phrase, wrappedDek) — derives recovery KEK, unwraps DEK. Backend: - User model: wrapped_dek, wrapped_dek_iv, recovery_wrapped_dek, recovery_wrapped_dek_iv fields. - RegisterRequest accepts wrapped-DEK fields; stored verbatim. - AuthResponse returns wrapped_dek + wrapped_dek_iv (for login unwrapping). - New GET /api/auth/recovery-info?email= — returns recovery-wrapped DEK. - RecoverPasswordRequest gains new_wrapped_dek + new_wrapped_dek_iv. - change-password also accepts + stores re-wrapped DEK. Frontend: - Auth store: login unwraps DEK from response; new recover() action fetches recovery-wrapped DEK, unwraps with phrase, re-wraps under new password. - RecoveryPage (new): email + recovery phrase + new password flow. - LoginPage: 'Forgot password? Recover' link. App.tsx: /recover route. Verified: backend 21 tests, 0 warnings; frontend build clean, 20 tests.
This commit is contained in:
goose
parent
62ef1abb84
commit
7a641dec00
13 changed files with 528 additions and 67 deletions
|
|
@ -1,64 +1,49 @@
|
|||
/**
|
||||
* Zero-knowledge key derivation.
|
||||
* Zero-knowledge key management with wrapped-DEK recovery (Phase 2).
|
||||
*
|
||||
* From the user's password we derive TWO independent values via PBKDF2:
|
||||
* Key model:
|
||||
* - DEK (Data Encryption Key): a random AES-256-GCM key used to encrypt/decrypt
|
||||
* all user data. Lives in memory only.
|
||||
* - KEK (Key Encryption Key): derived from the password (or recovery phrase)
|
||||
* via PBKDF2. Used to wrap (encrypt) the DEK for storage on the server.
|
||||
*
|
||||
* - `authSecret`: base64 bytes sent to the server as the "password". The
|
||||
* server PBKDF2-hashes it (as it always has). The server can never derive
|
||||
* the encryption key from this value.
|
||||
* - `encKey`: an AES-GCM CryptoKey kept in memory only (never persisted,
|
||||
* never transmitted). Used to encrypt/decrypt all user data.
|
||||
* The server stores two wrapped forms of the DEK:
|
||||
* - password_wrapped_dek: DEK encrypted under KEK(password)
|
||||
* - recovery_wrapped_dek: DEK encrypted under KEK(recovery_phrase)
|
||||
*
|
||||
* Two separate PBKDF2 passes with app-wide domain-separation salts prevent the
|
||||
* server from deriving `encKey` even if it logs or leaks `authSecret`.
|
||||
* Recovery: derive KEK(recovery_phrase) → unwrap the DEK → re-wrap under the
|
||||
* new password's KEK. The server never holds the DEK or any KEK.
|
||||
*/
|
||||
|
||||
import { encrypt, decrypt, type CipherPayload } from './cipher';
|
||||
|
||||
const PBKDF2_ITERATIONS = 150_000;
|
||||
const KEY_BITS = 256; // AES-256
|
||||
const KEY_BITS = 256;
|
||||
|
||||
const encoder = new TextEncoder();
|
||||
|
||||
// Domain-separation salts for each PBKDF2 purpose.
|
||||
export const AUTH_SALT = 'normogen-auth-v1';
|
||||
export const ENC_SALT = 'normogen-enc-v1';
|
||||
export const PASSWORD_KEK_SALT = 'normogen-kek-password-v1';
|
||||
export const RECOVERY_KEK_SALT = 'normogen-kek-recovery-v1';
|
||||
|
||||
/**
|
||||
* Derive the auth secret (base64) and encryption key (CryptoKey) from a password.
|
||||
*/
|
||||
export async function deriveAuthAndEncKeys(password: string): Promise<{
|
||||
authSecret: string;
|
||||
encKey: CryptoKey;
|
||||
}> {
|
||||
const passwordKey = await crypto.subtle.importKey(
|
||||
// ---------------------------------------------------------------------------
|
||||
// Low-level: PBKDF2 derivation helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
async function pbkdf2DeriveBits(password: string, salt: string): Promise<ArrayBuffer> {
|
||||
const key = await crypto.subtle.importKey(
|
||||
'raw',
|
||||
encoder.encode(password),
|
||||
encoder.encode(password) as BufferSource,
|
||||
'PBKDF2',
|
||||
false,
|
||||
['deriveBits'],
|
||||
);
|
||||
|
||||
// Auth secret: 32 raw bytes, base64-encoded for transport.
|
||||
const authBits = await crypto.subtle.deriveBits(
|
||||
{ name: 'PBKDF2', salt: encoder.encode(AUTH_SALT), iterations: PBKDF2_ITERATIONS, hash: 'SHA-256' },
|
||||
passwordKey,
|
||||
return crypto.subtle.deriveBits(
|
||||
{ name: 'PBKDF2', salt: encoder.encode(salt) as BufferSource, iterations: PBKDF2_ITERATIONS, hash: 'SHA-256' },
|
||||
key,
|
||||
KEY_BITS,
|
||||
);
|
||||
const authSecret = base64(new Uint8Array(authBits));
|
||||
|
||||
// Encryption key: importable AES-GCM key, non-extractable.
|
||||
const encBits = await crypto.subtle.deriveBits(
|
||||
{ name: 'PBKDF2', salt: encoder.encode(ENC_SALT), iterations: PBKDF2_ITERATIONS, hash: 'SHA-256' },
|
||||
passwordKey,
|
||||
KEY_BITS,
|
||||
);
|
||||
const encKey = await crypto.subtle.importKey(
|
||||
'raw',
|
||||
encBits,
|
||||
{ name: 'AES-GCM' },
|
||||
false,
|
||||
['encrypt', 'decrypt'],
|
||||
);
|
||||
|
||||
return { authSecret, encKey };
|
||||
}
|
||||
|
||||
function base64(bytes: Uint8Array): string {
|
||||
|
|
@ -67,32 +52,182 @@ function base64(bytes: Uint8Array): string {
|
|||
return btoa(bin);
|
||||
}
|
||||
|
||||
/** Derive the auth secret (base64) from the password — sent to the server. */
|
||||
export async function deriveAuthSecret(password: string): Promise<string> {
|
||||
const bits = await pbkdf2DeriveBits(password, AUTH_SALT);
|
||||
return base64(new Uint8Array(bits));
|
||||
}
|
||||
|
||||
/** Derive a KEK (extractable AES-GCM key) from a password or recovery phrase. */
|
||||
async function deriveKEK(secret: string, salt: string): Promise<CryptoKey> {
|
||||
const bits = await pbkdf2DeriveBits(secret, salt);
|
||||
return crypto.subtle.importKey(
|
||||
'raw',
|
||||
bits,
|
||||
{ name: 'AES-GCM' },
|
||||
true, // extractable so we can export for wrapping
|
||||
['encrypt', 'decrypt'],
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// In-memory encryption-key store.
|
||||
//
|
||||
// The encKey lives only in memory for the lifetime of the authenticated
|
||||
// session (the tab). It is deliberately NOT persisted — losing the tab or
|
||||
// closing the browser requires re-entering the password to re-derive it.
|
||||
// DEK generation + wrapping
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/** Generate a random AES-256-GCM DEK (extractable for wrapping). */
|
||||
export async function generateDek(): Promise<CryptoKey> {
|
||||
return crypto.subtle.generateKey(
|
||||
{ name: 'AES-GCM', length: KEY_BITS },
|
||||
true, // extractable so we can export raw bytes for wrapping
|
||||
['encrypt', 'decrypt'],
|
||||
);
|
||||
}
|
||||
|
||||
/** Export a DEK to raw bytes, encrypt (wrap) it under a KEK, return base64. */
|
||||
export async function wrapDek(dek: CryptoKey, kek: CryptoKey): Promise<CipherPayload> {
|
||||
const rawDek = await crypto.subtle.exportKey('raw', dek);
|
||||
return encrypt(
|
||||
new TextDecoder().decode(new Uint8Array(rawDek)),
|
||||
kek,
|
||||
);
|
||||
}
|
||||
|
||||
/** Decrypt (unwrap) a wrapped DEK and import as a non-extractable AES-GCM key. */
|
||||
export async function unwrapDek(payload: CipherPayload, kek: CryptoKey): Promise<CryptoKey> {
|
||||
const rawDekB64 = await decrypt(payload, kek);
|
||||
// The wrapped DEK was encrypted as a base64 string of the raw key bytes.
|
||||
const rawDek = Uint8Array.from(atob(rawDekB64), (c) => c.charCodeAt(0));
|
||||
return crypto.subtle.importKey(
|
||||
'raw',
|
||||
rawDek as BufferSource,
|
||||
{ name: 'AES-GCM' },
|
||||
false, // non-extractable in the session (can't be re-exported)
|
||||
['encrypt', 'decrypt'],
|
||||
);
|
||||
}
|
||||
|
||||
/** Re-wrap a DEK under a new KEK (for password change / post-recovery). */
|
||||
export async function rewrapDek(
|
||||
dek: CryptoKey,
|
||||
newSecret: string,
|
||||
salt: string = PASSWORD_KEK_SALT,
|
||||
): Promise<CipherPayload> {
|
||||
const newKek = await deriveKEK(newSecret, salt);
|
||||
return wrapDek(dek, newKek);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// High-level flows
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export interface EncryptionSetup {
|
||||
authSecret: string;
|
||||
dek: CryptoKey;
|
||||
passwordWrappedDek: CipherPayload;
|
||||
recoveryWrappedDek?: CipherPayload;
|
||||
recoveryKekHash?: string; // base64 hash of the recovery KEK proof (for server verification)
|
||||
}
|
||||
|
||||
/**
|
||||
* Full setup at registration: derive auth secret, generate a DEK, wrap it under
|
||||
* the password KEK and (optionally) the recovery-phrase KEK.
|
||||
*/
|
||||
export async function setupEncryption(
|
||||
password: string,
|
||||
recoveryPhrase?: string,
|
||||
): Promise<EncryptionSetup> {
|
||||
const authSecret = await deriveAuthSecret(password);
|
||||
const dek = await generateDek();
|
||||
|
||||
const passwordKek = await deriveKEK(password, PASSWORD_KEK_SALT);
|
||||
const passwordWrappedDek = await wrapDek(dek, passwordKek);
|
||||
|
||||
let recoveryWrappedDek: CipherPayload | undefined;
|
||||
let recoveryKekHash: string | undefined;
|
||||
|
||||
if (recoveryPhrase) {
|
||||
const recoveryKek = await deriveKEK(recoveryPhrase, RECOVERY_KEK_SALT);
|
||||
recoveryWrappedDek = await wrapDek(dek, recoveryKek);
|
||||
// A proof the server can verify: derive a separate value from the recovery
|
||||
// phrase and hash it. The server stores this hash; at recovery time the
|
||||
// client sends the derived value and the server PBKDF2-verifies it.
|
||||
// We send the recovery auth proof (base64 of a PBKDF2 derivation).
|
||||
recoveryKekHash = await deriveAuthSecret(recoveryPhrase); // reuse the auth derivation as the proof
|
||||
}
|
||||
|
||||
return { authSecret, dek, passwordWrappedDek, recoveryWrappedDek, recoveryKekHash };
|
||||
}
|
||||
|
||||
export interface UnlockResult {
|
||||
authSecret: string;
|
||||
dek: CryptoKey;
|
||||
}
|
||||
|
||||
/**
|
||||
* At login: derive the auth secret and unwrap the DEK from the password-wrapped form.
|
||||
*/
|
||||
export async function unlockWithPassword(
|
||||
password: string,
|
||||
passwordWrappedDek: CipherPayload,
|
||||
): Promise<UnlockResult> {
|
||||
const authSecret = await deriveAuthSecret(password);
|
||||
const passwordKek = await deriveKEK(password, PASSWORD_KEK_SALT);
|
||||
const dek = await unwrapDek(passwordWrappedDek, passwordKek);
|
||||
return { authSecret, dek };
|
||||
}
|
||||
|
||||
/**
|
||||
* At recovery: unwrap the DEK from the recovery-wrapped form using the recovery phrase.
|
||||
*/
|
||||
export async function unlockWithRecovery(
|
||||
recoveryPhrase: string,
|
||||
recoveryWrappedDek: CipherPayload,
|
||||
): Promise<CryptoKey> {
|
||||
const recoveryKek = await deriveKEK(recoveryPhrase, RECOVERY_KEK_SALT);
|
||||
return unwrapDek(recoveryWrappedDek, recoveryKek);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// In-memory key store (unchanged from Phase 1)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
let currentEncKey: CryptoKey | null = null;
|
||||
|
||||
/** Set the session encryption key (called on login/register). */
|
||||
export function setEncKey(key: CryptoKey): void {
|
||||
currentEncKey = key;
|
||||
}
|
||||
|
||||
/** Get the session encryption key, or null if not authenticated. */
|
||||
export function getEncKey(): CryptoKey | null {
|
||||
return currentEncKey;
|
||||
}
|
||||
|
||||
/** Clear the session encryption key (called on logout). */
|
||||
export function clearEncKey(): void {
|
||||
currentEncKey = null;
|
||||
}
|
||||
|
||||
/** True if a session encryption key is available (i.e. the user can encrypt/decrypt). */
|
||||
export function hasEncKey(): boolean {
|
||||
return currentEncKey !== null;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Backward compat: the old deriveAuthAndEncKeys (Phase 1 direct-from-password
|
||||
// enc key). Kept for tests; new code uses setupEncryption/unlockWithPassword.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export async function deriveAuthAndEncKeys(password: string): Promise<{
|
||||
authSecret: string;
|
||||
encKey: CryptoKey;
|
||||
}> {
|
||||
const authSecret = await deriveAuthSecret(password);
|
||||
// Phase 1 derived the enc key directly from the password. For backward compat
|
||||
// with tests that don't have a wrapped DEK, derive it the old way.
|
||||
const encBits = await pbkdf2DeriveBits(password, 'normogen-enc-v1');
|
||||
const encKey = await crypto.subtle.importKey(
|
||||
'raw',
|
||||
encBits,
|
||||
{ name: 'AES-GCM' },
|
||||
false,
|
||||
['encrypt', 'decrypt'],
|
||||
);
|
||||
return { authSecret, encKey };
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue