Shade/packages/shade-storage-encrypted/src/crypto/kdf.ts

/**
 * 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 { argon2idAsync } from '@noble/hashes/argon2.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);
}

/** Argon2id parameters — memory-hard KDF preferred for low-entropy secrets (PINs). */
export interface Argon2idParams {
  /** Memory cost in KiB. */
  m: number;
  /** Time cost (iterations). */
  t: number;
  /** Parallelism. */
  p: number;
  /** Output length in bytes. */
  dkLen: number;
}

/**
 * Default: m=64 MiB, t=3, p=1, 32-byte output. Tuned for ~250–400 ms on a
 * modern Chromium / Firefox / Safari laptop. RFC 9106 "second recommended"
 * profile shrunk to a browser-friendly memory footprint — strong enough for
 * 4–6 digit PINs as a defense-in-depth factor on top of a passphrase.
 */
export const DEFAULT_ARGON2ID: Argon2idParams = { m: 64 * 1024, t: 3, p: 1, dkLen: 32 };

/**
 * Derive a 32-byte master key from a low-entropy secret + salt using
 * argon2id. Salt MUST be persisted alongside the DB (16-byte random).
 */
export async function deriveMasterKeyArgon2id(
  secret: string | Uint8Array,
  salt: Uint8Array,
  params: Argon2idParams = DEFAULT_ARGON2ID,
): Promise<Uint8Array> {
  if (typeof secret === 'string' ? secret.length === 0 : secret.length === 0) {
    throw new Error('argon2id secret must be non-empty');
  }
  if (salt.length < 16) {
    throw new Error('salt must be at least 16 bytes');
  }
  const password = typeof secret === 'string' ? TEXT.encode(secret.normalize('NFKC')) : secret;
  return argon2idAsync(password, salt, {
    m: params.m,
    t: params.t,
    p: params.p,
    dkLen: params.dkLen,
  });
}

/** 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}`);
}

// ─── V4.9 — relay-side encrypted blob primitive ──────────────
//
// Three deterministic 32-byte derivations rooted at the user's master
// key, used by `@shade/sdk`'s `Profile` namespace to bootstrap a brand
// new device into existing E2EE state from credentials alone:
//
//   slotId    = HKDF(masterKey, info=`shade-blob-slot-v1:${app}`)
//   blobKey   = HKDF(masterKey, info=`shade-blob-key-v1:${app}`)
//   sigSeed   = HKDF(masterKey, info=`shade-blob-sig-v1:${app}`)
//
// `app` is a caller-supplied namespace (e.g. `"prism-profile"`) so two
// Shade apps with the same user/master never collide on the same slot.
//
// The slot identifier and the AEAD key are *both* derived from the
// master — the relay sees opaque slotIds and AEAD-sealed blobs and
// cannot decrypt or correlate slots to users. The signing seed is the
// raw 32-byte Ed25519 private key (matches @noble/curves' API: pubkey
// = ed25519.getPublicKey(seed)).

/** Lower-hex 64-char slotId derived from the master key. */
export function deriveBlobSlotId(masterKey: Uint8Array, app: string): Uint8Array {
  return hkdfDerive(masterKey, `shade-blob-slot-v1:${app}`, 32);
}

/** AEAD key for sealing/opening the blob. Use AAD = slotId. */
export function deriveBlobKey(masterKey: Uint8Array, app: string): Uint8Array {
  return hkdfDerive(masterKey, `shade-blob-key-v1:${app}`, 32);
}

/**
 * 32-byte Ed25519 signing seed (== the private key in the @noble/curves
 * convention). The pubkey, derived deterministically from the seed, is
 * what the relay TOFU-stores on the first PUT and verifies subsequent
 * writes against.
 */
export function deriveBlobSigningSeed(masterKey: Uint8Array, app: string): Uint8Array {
  return hkdfDerive(masterKey, `shade-blob-sig-v1:${app}`, 32);
}