80 lines
2.9 KiB
TypeScript
80 lines
2.9 KiB
TypeScript
|
/**
|
||
|
|
* Key derivation primitives for at-rest storage encryption.
|
||
|
|
*
|
||
|
|
* Hierarchy:
|
||
|
|
* masterKey (from passphrase / keychain / app-injected)
|
||
|
|
* │
|
||
|
|
* ├─ HKDF("shade-storage-v1") → storageKey (32 bytes)
|
||
|
|
* │ └─ HKDF(storageKey, table || ":" || column) → fieldKey (32 bytes)
|
||
|
|
* │
|
||
|
|
* └─ HKDF("shade-storage-version-v1") → versionKey (used during rotation)
|
||
|
|
*/
|
||
|
|
|
||
|
|
import { scryptAsync } from '@noble/hashes/scrypt.js';
|
||
|
|
import { hkdf } from '@noble/hashes/hkdf.js';
|
||
|
|
import { sha256 } from '@noble/hashes/sha2.js';
|
||
|
|
|
||
|
|
const TEXT = new TextEncoder();
|
||
|
|
|
||
|
|
/** scrypt parameters — interactive; sized for sub-second derivation on commodity HW */
|
||
|
|
export interface ScryptParams {
|
||
|
|
N: number;
|
||
|
|
r: number;
|
||
|
|
p: number;
|
||
|
|
dkLen: number;
|
||
|
|
}
|
||
|
|
|
||
|
|
/** Default: N=2^17, r=8, p=1, 32-byte output. ~250ms on a modern laptop. */
|
||
|
|
export const DEFAULT_SCRYPT: ScryptParams = { N: 1 << 17, r: 8, p: 1, dkLen: 32 };
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Derive a 32-byte master key from a passphrase + salt using scrypt.
|
||
|
|
* The salt MUST be persisted alongside the encrypted database (16-byte random).
|
||
|
|
*/
|
||
|
|
export async function deriveMasterKey(
|
||
|
|
passphrase: string,
|
||
|
|
salt: Uint8Array,
|
||
|
|
params: ScryptParams = DEFAULT_SCRYPT,
|
||
|
|
): Promise<Uint8Array> {
|
||
|
|
if (passphrase.length === 0) {
|
||
|
|
throw new Error('passphrase must be non-empty');
|
||
|
|
}
|
||
|
|
if (salt.length < 16) {
|
||
|
|
throw new Error('salt must be at least 16 bytes');
|
||
|
|
}
|
||
|
|
return scryptAsync(TEXT.encode(passphrase.normalize('NFKC')), salt, params);
|
||
|
|
}
|
||
|
|
|
||
|
|
/** HKDF-SHA-256 with explicit info string. */
|
||
|
|
export function hkdfDerive(ikm: Uint8Array, info: string, length = 32, salt?: Uint8Array): Uint8Array {
|
||
|
|
return hkdf(sha256, ikm, salt, TEXT.encode(info), length);
|
||
|
|
}
|
||
|
|
|
||
|
|
/** Derive the storageKey from masterKey. Stable, deterministic. */
|
||
|
|
export function deriveStorageKey(masterKey: Uint8Array): Uint8Array {
|
||
|
|
return hkdfDerive(masterKey, 'shade-storage-v1', 32);
|
||
|
|
}
|
||
|
|
|
||
|
|
/** Derive the per-(table, column) field key. Stable, deterministic. */
|
||
|
|
export function deriveFieldKey(storageKey: Uint8Array, table: string, column: string): Uint8Array {
|
||
|
|
return hkdfDerive(storageKey, `shade-field-v1:${table}:${column}`, 32);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Derive a deterministic 12-byte AEAD nonce from a row key (typically the
|
||
|
|
* field key) plus (table, pk) binding. With per-field keys, deterministic
|
||
|
|
* nonces are safe because each (key, plaintext) pair appears at most once
|
||
|
|
* — re-saving the same row reuses the (nonce, key) pair only because the
|
||
|
|
* plaintext also changes (chain ratchet, prekey state, etc.). The AAD
|
||
|
|
* also binds (table, column, pk) so swapping is rejected on decrypt.
|
||
|
|
*/
|
||
|
|
export function deriveNonce(rowKey: Uint8Array, table: string, pk: string): Uint8Array {
|
||
|
|
const out = hkdfDerive(rowKey, `shade-row-nonce-v1:${table}:${pk}`, 12);
|
||
|
|
return out;
|
||
|
|
}
|
||
|
|
|
||
|
|
/** Build the AAD that binds (table, column, pk) to a ciphertext. */
|
||
|
|
export function buildAad(table: string, column: string, pk: string): Uint8Array {
|
||
|
|
return TEXT.encode(`shade-aad-v1|${table}|${column}|${pk}`);
|
||
|
|
}
|