@noy-db/on-recovery 0.1.0-pre.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# @noy-db/on-recovery
+
+One-time printable recovery codes for noy-db. The **last-resort unlock path** when the primary authentication (passphrase, WebAuthn, OIDC) is unavailable. Codes are generated once, shown to the user once, printed on paper, stored in a safe. Each code unlocks the vault exactly **one time** and then burns itself.
+
+Part of the `@noy-db/on-*` authentication family. Sibling packages: `on-webauthn`, `on-oidc`, `on-magic-link`, `on-pin`.
+
+## Install
+
+```bash
+pnpm add @noy-db/on-recovery
+```
+
+## Threat model
+
+**Protects against:**
+- Primary authentication becoming unavailable (forgotten passphrase, lost passkey device, OIDC provider down)
+- Code replay — each code burns on successful unlock by deleting its keyring entry
+
+**Does NOT protect against:**
+- Physical theft of printed codes — assume paper compromise → user calls `revokeAllRecoveryCodes` + re-enrolls
+- User enrolling without actually printing — the calling application must enforce this UX
+
+Recovery codes should NEVER be the only unlock method on a vault. Enroll passphrase / WebAuthn / OIDC first, then recovery codes as a fallback.
+
+## Code format
+
+```
+XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
+```
+
+- **28 characters** total (24 Base32 body + 4 Base32 checksum)
+- **120 bits of entropy per code** — infeasible to brute-force
+- **RFC 4648 Base32 alphabet** (`A-Z2-7`) — no confusing `0/O`, `1/I/L`, `8/B` pairs
+- **4-character checksum** catches single-character transcription errors (≥99.9999% of them)
+- **Groups of 4 with hyphens** for eye-tracking when writing down
+
+Input is lenient: whitespace, hyphens, lowercase are all stripped before validation.
+
+## Security model
+
+Each code is processed through:
+
+```
+wrappingKey = PBKDF2-SHA256(
+  password   = normalizeCode(code),
+  salt       = perCodeRandomSalt,   // Stored alongside wrapped KEK
+  iterations = 600_000,              // Matches hub's passphrase derivation
+  length     = 256                   // bits
+)
+
+wrappedKEK = AES-KW(kek, wrappingKey)
+```
+
+The `wrappedKEK + salt + codeId` goes into the keyring under a `_recovery_<N>` entry. On unlock, PBKDF2 re-derives the wrapping key from the user-typed code + salt, and AES-KW unwraps the KEK.
+
+## Usage
+
+This package provides the **crypto layer only**. Storage, audit, rate-limiting, and burn-on-use are application-layer concerns handled by hub's keyring + audit-ledger APIs.
+
+### Enrollment (after primary unlock)
+
+```ts
+import { generateRecoveryCodeSet } from '@noy-db/on-recovery'
+
+// After the user unlocks with passphrase, offer recovery-code enrollment
+const { codes, entries } = await generateRecoveryCodeSet({
+  count: 10,        // 8-20 is reasonable; default 10
+  kek: currentKEK,  // The vault's currently-unwrapped KEK
+})
+
+// Show `codes` to the user ONCE — print, download, copy. Do NOT store them.
+displayRecoveryCodes(codes)
+downloadRecoveryCodes(codes)
+
+// Persist `entries` to the vault's keyring. Each entry is safe to
+// store on disk — it holds only the salt + wrapped KEK + codeId.
+for (const entry of entries) {
+  await vault.keyring.put(`_recovery_${entry.codeId}`, entry)
+}
+
+// Write an audit-ledger entry
+await vault.ledger.append({
+  type: 'on-recovery:enroll',
+  actor: currentUserId,
+  codeCount: entries.length,
+  timestamp: new Date().toISOString(),
+})
+```
+
+### Unlock (when primary auth is unavailable)
+
+```ts
+import { parseRecoveryCode, unwrapKEKFromRecovery } from '@noy-db/on-recovery'
+
+const parsed = parseRecoveryCode(userInput)
+
+if (parsed.status === 'invalid-format') {
+  // User typed junk — show "not a valid recovery code" without counting against rate limit
+  return showError('format')
+}
+if (parsed.status === 'invalid-checksum') {
+  // Well-formed but checksum wrong — transcription error, not a guess
+  return showError('checksum')
+}
+
+// Find which enrolled entry this code matches
+const allEntries = await vault.keyring.list({ prefix: '_recovery_' })
+
+for (const entry of allEntries) {
+  try {
+    const kek = await unwrapKEKFromRecovery(parsed.code, entry)
+
+    // Match! Burn this entry — delete the keyring record so the code
+    // can never be replayed.
+    await vault.keyring.delete(`_recovery_${entry.codeId}`)
+
+    // Write an audit-ledger entry
+    await vault.ledger.append({
+      type: 'on-recovery:unlock',
+      actor: currentUserId,
+      codesRemaining: allEntries.length - 1,
+      timestamp: new Date().toISOString(),
+    })
+
+    return kek
+  } catch {
+    // Wrong entry, try next
+  }
+}
+
+// No matching entry — counts against the host app's rate limit
+await vault.ledger.append({
+  type: 'on-recovery:unlock-failed',
+  actor: currentUserId,
+  reason: 'not-found',
+  timestamp: new Date().toISOString(),
+})
+throw new Error('no matching recovery code')
+```
+
+### Revocation (after a suspected paper leak)
+
+```ts
+// Scan all recovery entries, delete each.
+const allEntries = await vault.keyring.list({ prefix: '_recovery_' })
+for (const entry of allEntries) {
+  await vault.keyring.delete(`_recovery_${entry.codeId}`)
+}
+// Optionally re-enroll a fresh set.
+```
+
+## API
+
+```ts
+// Generate a full enrollment
+async function generateRecoveryCodeSet(options: {
+  count?: number         // Default 10, clamped to 1..100
+  kek: CryptoKey         // Currently-unwrapped KEK
+}): Promise<{
+  codes: string[]        // Show to user once, then forget
+  entries: RecoveryCodeEntry[]  // Persist to keyring
+}>
+
+// Parse + normalize user input
+function parseRecoveryCode(input: string): ParseResult
+
+type ParseResult =
+  | { status: 'valid'; code: string }    // Normalized, checksum verified
+  | { status: 'invalid-checksum' }        // Format OK, checksum wrong
+  | { status: 'invalid-format' }          // Not a valid code shape
+
+// Attempt to unwrap the KEK with a code + an entry; throws on mismatch
+async function unwrapKEKFromRecovery(
+  code: string,              // The normalized code from parseRecoveryCode
+  entry: RecoveryCodeEntry,  // One of the enrolled entries
+): Promise<CryptoKey>
+
+// Lower-level helpers (for advanced use cases)
+function formatRecoveryCode(normalized: string): string
+async function deriveRecoveryWrappingKey(code: string, salt: Uint8Array): Promise<CryptoKey>
+async function wrapKEKForRecovery(kek: CryptoKey, code: string, salt: Uint8Array): Promise<Uint8Array>
+
+interface RecoveryCodeEntry {
+  codeId: string        // ULID — caller uses this to delete the entry on burn
+  salt: string          // Base64
+  wrappedKEK: string    // Base64
+  enrolledAt: string    // ISO timestamp
+}
+```
+
+## Performance
+
+PBKDF2 with 600K iterations takes ~500ms per derive on modern hardware. Generating 10 codes enrolls in ~5 seconds (serial) — acceptable for a one-time enrollment flow; show a loading indicator. Unlock is a single derive per attempt (~500ms).
+
+If you need faster enrollment (e.g., a CLI test), you can parallelize via `Promise.all`.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,194 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  deriveRecoveryWrappingKey: () => deriveRecoveryWrappingKey,
+  formatRecoveryCode: () => formatRecoveryCode,
+  generateRecoveryCodeSet: () => generateRecoveryCodeSet,
+  parseRecoveryCode: () => parseRecoveryCode,
+  unwrapKEKFromRecovery: () => unwrapKEKFromRecovery,
+  wrapKEKForRecovery: () => wrapKEKForRecovery
+});
+module.exports = __toCommonJS(index_exports);
+var import_hub = require("@noy-db/hub");
+var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+var STRIPPABLE = /[\s\-_]/g;
+var CODE_ENTROPY_BYTES = 15;
+var CHECKSUM_LEN = 4;
+var PBKDF2_ITERATIONS = 6e5;
+var PBKDF2_KEY_LENGTH = 32 * 8;
+var SALT_BYTES = 16;
+async function generateRecoveryCodeSet(opts) {
+  const count = opts.count ?? 10;
+  if (!Number.isInteger(count) || count < 1 || count > 100) {
+    throw new Error(`on-recovery: count must be 1-100 (got ${count})`);
+  }
+  const codes = [];
+  const entries = [];
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  for (let i = 0; i < count; i++) {
+    const raw = generateRawCode();
+    const formatted = formatCodeForDisplay(raw);
+    const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
+    const wrappingKey = await deriveRecoveryWrappingKey(raw, salt);
+    const wrappedKEK = await wrapKEK(opts.kek, wrappingKey);
+    codes.push(formatted);
+    entries.push({
+      codeId: (0, import_hub.generateULID)(),
+      salt: base64Encode(salt),
+      wrappedKEK: base64Encode(wrappedKEK),
+      enrolledAt: now
+    });
+  }
+  return { codes, entries };
+}
+function parseRecoveryCode(input) {
+  const normalized = input.toUpperCase().replace(STRIPPABLE, "");
+  const expectedLen = base32CharsForBytes(CODE_ENTROPY_BYTES) + CHECKSUM_LEN;
+  if (normalized.length !== expectedLen) {
+    return { status: "invalid-format" };
+  }
+  for (const ch of normalized) {
+    if (!BASE32_ALPHABET.includes(ch)) {
+      return { status: "invalid-format" };
+    }
+  }
+  const bodyLen = normalized.length - CHECKSUM_LEN;
+  const body = normalized.slice(0, bodyLen);
+  const checksum = normalized.slice(bodyLen);
+  if (computeChecksum(body) !== checksum) {
+    return { status: "invalid-checksum" };
+  }
+  return { status: "valid", code: normalized };
+}
+function formatRecoveryCode(normalizedCode) {
+  const groups = [];
+  for (let i = 0; i < normalizedCode.length; i += 4) {
+    groups.push(normalizedCode.slice(i, i + 4));
+  }
+  return groups.join("-");
+}
+async function deriveRecoveryWrappingKey(code, salt) {
+  const password = new TextEncoder().encode(code);
+  const baseKey = await crypto.subtle.importKey(
+    "raw",
+    password,
+    "PBKDF2",
+    false,
+    ["deriveKey"]
+  );
+  return crypto.subtle.deriveKey(
+    {
+      name: "PBKDF2",
+      hash: "SHA-256",
+      salt,
+      iterations: PBKDF2_ITERATIONS
+    },
+    baseKey,
+    { name: "AES-KW", length: PBKDF2_KEY_LENGTH },
+    false,
+    ["wrapKey", "unwrapKey"]
+  );
+}
+async function wrapKEKForRecovery(kek, code, salt) {
+  const wrappingKey = await deriveRecoveryWrappingKey(code, salt);
+  return wrapKEK(kek, wrappingKey);
+}
+async function unwrapKEKFromRecovery(code, entry) {
+  const salt = base64Decode(entry.salt);
+  const wrappedKEK = base64Decode(entry.wrappedKEK);
+  const wrappingKey = await deriveRecoveryWrappingKey(code, salt);
+  return crypto.subtle.unwrapKey(
+    "raw",
+    wrappedKEK,
+    wrappingKey,
+    "AES-KW",
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+function generateRawCode() {
+  const entropy = crypto.getRandomValues(new Uint8Array(CODE_ENTROPY_BYTES));
+  const body = base32Encode(entropy);
+  const checksum = computeChecksum(body);
+  return body + checksum;
+}
+function formatCodeForDisplay(rawNormalized) {
+  return formatRecoveryCode(rawNormalized);
+}
+function computeChecksum(body) {
+  let h = 0;
+  for (let i = 0; i < body.length; i++) {
+    const v = BASE32_ALPHABET.indexOf(body[i]);
+    h = h * 33 + v >>> 0;
+  }
+  const chars = [];
+  for (let i = 0; i < CHECKSUM_LEN; i++) {
+    chars.push(BASE32_ALPHABET[h >>> i * 5 & 31]);
+  }
+  return chars.join("");
+}
+function base32CharsForBytes(n) {
+  return Math.ceil(n * 8 / 5);
+}
+function base32Encode(bytes) {
+  let bits = 0;
+  let value = 0;
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    value = value << 8 | bytes[i];
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += BASE32_ALPHABET[value >>> bits & 31];
+    }
+  }
+  if (bits > 0) {
+    out += BASE32_ALPHABET[value << 5 - bits & 31];
+  }
+  return out;
+}
+async function wrapKEK(kek, wrappingKey) {
+  const wrapped = await crypto.subtle.wrapKey("raw", kek, wrappingKey, "AES-KW");
+  return new Uint8Array(wrapped);
+}
+function base64Encode(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return btoa(s);
+}
+function base64Decode(str) {
+  const s = atob(str);
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  deriveRecoveryWrappingKey,
+  formatRecoveryCode,
+  generateRecoveryCodeSet,
+  parseRecoveryCode,
+  unwrapKEKFromRecovery,
+  wrapKEKForRecovery
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/on-recovery** — one-time printable recovery codes for noy-db.\n *\n * The last-resort unlock path when the primary authentication\n * (passphrase, WebAuthn, OIDC) is unavailable. Codes are designed to\n * be printed on paper and stored in a safe — each code unlocks the\n * vault exactly once and then is burned by deleting its keyring entry.\n *\n * Part of the `@noy-db/on-*` authentication family.\n *\n * ## Security model\n *\n * Each code is a random 100-bit value (20 Base32 characters) with a\n * 5-character checksum appended. The wrapping key is derived from\n * the code via:\n *\n * ```\n *   PBKDF2-SHA256(\n *     password = normalizeCode(code),\n *     salt     = perCodeRandomSalt,\n *     iter     = 600_000,\n *     length   = 32,\n *   )\n * ```\n *\n * The wrapping key is then used with AES-KW (RFC 3394) to wrap the\n * vault's KEK. The wrapped KEK + salt + code-ID land in the keyring\n * under a `_recovery_<N>` entry, alongside other unlock mechanisms.\n *\n * This package provides the CRYPTO layer only. Storage, burn, audit,\n * and rate-limiting are the caller's responsibility — typically\n * coordinated with `@noy-db/hub`'s keyring + audit-ledger APIs.\n *\n * ## Usage\n *\n * ```ts\n * import {\n *   generateRecoveryCodeSet,\n *   parseRecoveryCode,\n *   deriveRecoveryWrappingKey,\n *   wrapKEKForRecovery,\n *   unwrapKEKFromRecovery,\n * } from '@noy-db/on-recovery'\n *\n * // ENROLL — after user unlocks with passphrase, generate N codes\n * const { codes, entries } = await generateRecoveryCodeSet({ count: 10, kek })\n * // `codes` is what you show the user ONCE (to print/save).\n * // `entries` goes into the keyring file (persistent storage).\n *\n * // UNLOCK — user types in a code later\n * const parsed = parseRecoveryCode(userInput)\n * if (parsed.status !== 'valid') handleInvalidFormat(parsed.status)\n *\n * for (const entry of storedEntries) {\n *   try {\n *     const kek = await unwrapKEKFromRecovery(parsed.code, entry)\n *     // Match! Burn this entry: delete from keyring.\n *     await deleteKeyringEntry(entry.codeId)\n *     return kek\n *   } catch (e) {\n *     // Wrong entry, try next\n *   }\n * }\n * throw new Error('no matching recovery code')\n * ```\n *\n * @packageDocumentation\n */\n\nimport { generateULID } from '@noy-db/hub'\n\n// Constants ────────────────────────────────────────────────────────────\n\n/** RFC 4648 Base32 alphabet — A-Z + 2-7, no ambiguous chars. */\nconst BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'\n\n/** Characters to ignore on input (whitespace, hyphens, lowercase). */\nconst STRIPPABLE = /[\\s\\-_]/g\n\n/** How many random bytes of entropy per code. */\nconst CODE_ENTROPY_BYTES = 15   // 15 bytes = 120 bits = exactly 24 Base32 chars (clean groups of 4)\n\n/** Length of the checksum portion (Base32 chars). */\nconst CHECKSUM_LEN = 4           // 24 body + 4 checksum = 28 chars = 7 groups of 4\n\n/** PBKDF2 iteration count — matches hub's passphrase-unlock derivation. */\nconst PBKDF2_ITERATIONS = 600_000\n\n/** PBKDF2 output length — 32 bytes = 256-bit wrapping key. */\nconst PBKDF2_KEY_LENGTH = 32 * 8\n\n/** Per-code salt length. */\nconst SALT_BYTES = 16\n\n// Types ────────────────────────────────────────────────────────────────\n\n/**\n * A single recovery-code enrollment entry. The caller stores this in\n * the vault's keyring alongside other unlock mechanisms.\n */\nexport interface RecoveryCodeEntry {\n  /** Stable identifier for this code (ULID). Used by the caller to delete the entry on burn. */\n  readonly codeId: string\n  /** PBKDF2 salt for this code, base64-encoded. */\n  readonly salt: string\n  /** Wrapped KEK, base64-encoded. Unwrap with AES-KW using the code-derived key. */\n  readonly wrappedKEK: string\n  /** Timestamp the code was enrolled. */\n  readonly enrolledAt: string\n}\n\n/** Options for `generateRecoveryCodeSet()`. */\nexport interface GenerateRecoveryCodeSetOptions {\n  /** Number of codes to generate. Default 10. Reasonable: 8-20. */\n  count?: number\n  /** The vault's current KEK (unwrapped). Required — proves possession. */\n  kek: CryptoKey\n}\n\n/** Result of `parseRecoveryCode()`. */\nexport type ParseResult =\n  | { status: 'valid'; code: string }          // Normalized, checksum-verified\n  | { status: 'invalid-checksum' }             // Format OK, checksum wrong\n  | { status: 'invalid-format' }               // Not a valid code shape\n\n// Code generation ──────────────────────────────────────────────────────\n\n/**\n * Generate a fresh recovery-code set. The returned `codes` must be shown\n * to the user exactly once (print/save); the `entries` go into the\n * keyring for persistent storage.\n *\n * The caller is responsible for:\n * 1. Displaying the plaintext codes to the user ONCE.\n * 2. Writing `entries` into the vault's keyring.\n * 3. Writing an audit-ledger entry recording the enrollment.\n */\nexport async function generateRecoveryCodeSet(\n  opts: GenerateRecoveryCodeSetOptions,\n): Promise<{ codes: string[]; entries: RecoveryCodeEntry[] }> {\n  const count = opts.count ?? 10\n  if (!Number.isInteger(count) || count < 1 || count > 100) {\n    throw new Error(`on-recovery: count must be 1-100 (got ${count})`)\n  }\n\n  const codes: string[] = []\n  const entries: RecoveryCodeEntry[] = []\n  const now = new Date().toISOString()\n\n  for (let i = 0; i < count; i++) {\n    const raw = generateRawCode()\n    const formatted = formatCodeForDisplay(raw)\n    const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES))\n    const wrappingKey = await deriveRecoveryWrappingKey(raw, salt)\n    const wrappedKEK = await wrapKEK(opts.kek, wrappingKey)\n\n    codes.push(formatted)\n    entries.push({\n      codeId: generateULID(),\n      salt: base64Encode(salt),\n      wrappedKEK: base64Encode(wrappedKEK),\n      enrolledAt: now,\n    })\n  }\n\n  return { codes, entries }\n}\n\n// Code parsing + normalization ─────────────────────────────────────────\n\n/**\n * Parse user input into a normalized recovery code. Accepts whitespace,\n * hyphens, and lowercase — strips them all. Verifies the checksum.\n */\nexport function parseRecoveryCode(input: string): ParseResult {\n  const normalized = input.toUpperCase().replace(STRIPPABLE, '')\n\n  const expectedLen = base32CharsForBytes(CODE_ENTROPY_BYTES) + CHECKSUM_LEN\n  if (normalized.length !== expectedLen) {\n    return { status: 'invalid-format' }\n  }\n  for (const ch of normalized) {\n    if (!BASE32_ALPHABET.includes(ch)) {\n      return { status: 'invalid-format' }\n    }\n  }\n\n  const bodyLen = normalized.length - CHECKSUM_LEN\n  const body = normalized.slice(0, bodyLen)\n  const checksum = normalized.slice(bodyLen)\n\n  if (computeChecksum(body) !== checksum) {\n    return { status: 'invalid-checksum' }\n  }\n\n  return { status: 'valid', code: normalized }\n}\n\n/**\n * Format a normalized recovery code for display (groups of 4, hyphenated).\n * Inverse of the strip-hyphens step in `parseRecoveryCode`.\n */\nexport function formatRecoveryCode(normalizedCode: string): string {\n  const groups: string[] = []\n  for (let i = 0; i < normalizedCode.length; i += 4) {\n    groups.push(normalizedCode.slice(i, i + 4))\n  }\n  return groups.join('-')\n}\n\n// Key derivation ───────────────────────────────────────────────────────\n\n/**\n * Derive the AES-KW wrapping key from a recovery code + salt. Used for\n * both enrollment (wrap the KEK) and unlock (unwrap the KEK).\n *\n * @param code - A normalized recovery code (uppercase Base32, no\n *   hyphens/whitespace, checksum included).\n * @param salt - Per-code random salt from the stored entry.\n */\nexport async function deriveRecoveryWrappingKey(\n  code: string,\n  salt: Uint8Array,\n): Promise<CryptoKey> {\n  const password = new TextEncoder().encode(code)\n  const baseKey = await crypto.subtle.importKey(\n    'raw',\n    password as BufferSource,\n    'PBKDF2',\n    false,\n    ['deriveKey'],\n  )\n  return crypto.subtle.deriveKey(\n    {\n      name: 'PBKDF2',\n      hash: 'SHA-256',\n      salt: salt as BufferSource,\n      iterations: PBKDF2_ITERATIONS,\n    },\n    baseKey,\n    { name: 'AES-KW', length: PBKDF2_KEY_LENGTH },\n    false,\n    ['wrapKey', 'unwrapKey'],\n  )\n}\n\n// KEK wrap/unwrap ──────────────────────────────────────────────────────\n\n/**\n * Wrap a KEK with a recovery-code-derived wrapping key.\n * Returns raw bytes suitable for base64 encoding + storage.\n */\nexport async function wrapKEKForRecovery(\n  kek: CryptoKey,\n  code: string,\n  salt: Uint8Array,\n): Promise<Uint8Array> {\n  const wrappingKey = await deriveRecoveryWrappingKey(code, salt)\n  return wrapKEK(kek, wrappingKey)\n}\n\n/**\n * Unwrap the KEK using a recovery code + a stored entry.\n *\n * Throws (AES-KW authentication failure) if the code doesn't match\n * this entry. The caller typically iterates all enrolled entries and\n * catches the failure until one succeeds.\n *\n * On success, the caller MUST burn the entry — deleting `entry.codeId`\n * from the keyring — so the code can never be replayed.\n */\nexport async function unwrapKEKFromRecovery(\n  code: string,\n  entry: RecoveryCodeEntry,\n): Promise<CryptoKey> {\n  const salt = base64Decode(entry.salt)\n  const wrappedKEK = base64Decode(entry.wrappedKEK)\n  const wrappingKey = await deriveRecoveryWrappingKey(code, salt)\n\n  return crypto.subtle.unwrapKey(\n    'raw',\n    wrappedKEK as BufferSource,\n    wrappingKey,\n    'AES-KW',\n    { name: 'AES-GCM', length: 256 },\n    false,\n    ['encrypt', 'decrypt'],\n  )\n}\n\n// Internals ────────────────────────────────────────────────────────────\n\nfunction generateRawCode(): string {\n  const entropy = crypto.getRandomValues(new Uint8Array(CODE_ENTROPY_BYTES))\n  const body = base32Encode(entropy)\n  const checksum = computeChecksum(body)\n  return body + checksum\n}\n\nfunction formatCodeForDisplay(rawNormalized: string): string {\n  return formatRecoveryCode(rawNormalized)\n}\n\n/**\n * Deterministic 4-character checksum over Base32 body. Catches\n * transcription errors (single-char swaps, shifted digits) with very\n * high probability.\n *\n * Uses a simple polynomial hash reduced modulo the Base32 alphabet\n * size (32). Four output chars = 20 bits ≈ 1-in-1M false positive.\n */\nfunction computeChecksum(body: string): string {\n  let h = 0\n  for (let i = 0; i < body.length; i++) {\n    const v = BASE32_ALPHABET.indexOf(body[i]!)\n    h = (h * 33 + v) >>> 0\n  }\n  // Extract 4 Base32 chars from the 20 low bits\n  const chars: string[] = []\n  for (let i = 0; i < CHECKSUM_LEN; i++) {\n    chars.push(BASE32_ALPHABET[(h >>> (i * 5)) & 0x1f]!)\n  }\n  return chars.join('')\n}\n\nfunction base32CharsForBytes(n: number): number {\n  // Each 5 bytes → 8 Base32 chars. Partial-byte handling via ceil.\n  return Math.ceil((n * 8) / 5)\n}\n\nfunction base32Encode(bytes: Uint8Array): string {\n  let bits = 0\n  let value = 0\n  let out = ''\n  for (let i = 0; i < bytes.length; i++) {\n    value = (value << 8) | bytes[i]!\n    bits += 8\n    while (bits >= 5) {\n      bits -= 5\n      out += BASE32_ALPHABET[(value >>> bits) & 0x1f]\n    }\n  }\n  if (bits > 0) {\n    out += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f]\n  }\n  return out\n}\n\nasync function wrapKEK(kek: CryptoKey, wrappingKey: CryptoKey): Promise<Uint8Array> {\n  const wrapped = await crypto.subtle.wrapKey('raw', kek, wrappingKey, 'AES-KW')\n  return new Uint8Array(wrapped)\n}\n\nfunction base64Encode(bytes: Uint8Array): string {\n  let s = ''\n  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]!)\n  // `btoa` is globally available in browsers, Node 16+, Deno, Bun.\n  return btoa(s)\n}\n\nfunction base64Decode(str: string): Uint8Array {\n  const s = atob(str)\n  const out = new Uint8Array(s.length)\n  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i)\n  return out\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,149 @@
+/**
+ * **@noy-db/on-recovery** — one-time printable recovery codes for noy-db.
+ *
+ * The last-resort unlock path when the primary authentication
+ * (passphrase, WebAuthn, OIDC) is unavailable. Codes are designed to
+ * be printed on paper and stored in a safe — each code unlocks the
+ * vault exactly once and then is burned by deleting its keyring entry.
+ *
+ * Part of the `@noy-db/on-*` authentication family.
+ *
+ * ## Security model
+ *
+ * Each code is a random 100-bit value (20 Base32 characters) with a
+ * 5-character checksum appended. The wrapping key is derived from
+ * the code via:
+ *
+ * ```
+ *   PBKDF2-SHA256(
+ *     password = normalizeCode(code),
+ *     salt     = perCodeRandomSalt,
+ *     iter     = 600_000,
+ *     length   = 32,
+ *   )
+ * ```
+ *
+ * The wrapping key is then used with AES-KW (RFC 3394) to wrap the
+ * vault's KEK. The wrapped KEK + salt + code-ID land in the keyring
+ * under a `_recovery_<N>` entry, alongside other unlock mechanisms.
+ *
+ * This package provides the CRYPTO layer only. Storage, burn, audit,
+ * and rate-limiting are the caller's responsibility — typically
+ * coordinated with `@noy-db/hub`'s keyring + audit-ledger APIs.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import {
+ *   generateRecoveryCodeSet,
+ *   parseRecoveryCode,
+ *   deriveRecoveryWrappingKey,
+ *   wrapKEKForRecovery,
+ *   unwrapKEKFromRecovery,
+ * } from '@noy-db/on-recovery'
+ *
+ * // ENROLL — after user unlocks with passphrase, generate N codes
+ * const { codes, entries } = await generateRecoveryCodeSet({ count: 10, kek })
+ * // `codes` is what you show the user ONCE (to print/save).
+ * // `entries` goes into the keyring file (persistent storage).
+ *
+ * // UNLOCK — user types in a code later
+ * const parsed = parseRecoveryCode(userInput)
+ * if (parsed.status !== 'valid') handleInvalidFormat(parsed.status)
+ *
+ * for (const entry of storedEntries) {
+ *   try {
+ *     const kek = await unwrapKEKFromRecovery(parsed.code, entry)
+ *     // Match! Burn this entry: delete from keyring.
+ *     await deleteKeyringEntry(entry.codeId)
+ *     return kek
+ *   } catch (e) {
+ *     // Wrong entry, try next
+ *   }
+ * }
+ * throw new Error('no matching recovery code')
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * A single recovery-code enrollment entry. The caller stores this in
+ * the vault's keyring alongside other unlock mechanisms.
+ */
+interface RecoveryCodeEntry {
+    /** Stable identifier for this code (ULID). Used by the caller to delete the entry on burn. */
+    readonly codeId: string;
+    /** PBKDF2 salt for this code, base64-encoded. */
+    readonly salt: string;
+    /** Wrapped KEK, base64-encoded. Unwrap with AES-KW using the code-derived key. */
+    readonly wrappedKEK: string;
+    /** Timestamp the code was enrolled. */
+    readonly enrolledAt: string;
+}
+/** Options for `generateRecoveryCodeSet()`. */
+interface GenerateRecoveryCodeSetOptions {
+    /** Number of codes to generate. Default 10. Reasonable: 8-20. */
+    count?: number;
+    /** The vault's current KEK (unwrapped). Required — proves possession. */
+    kek: CryptoKey;
+}
+/** Result of `parseRecoveryCode()`. */
+type ParseResult = {
+    status: 'valid';
+    code: string;
+} | {
+    status: 'invalid-checksum';
+} | {
+    status: 'invalid-format';
+};
+/**
+ * Generate a fresh recovery-code set. The returned `codes` must be shown
+ * to the user exactly once (print/save); the `entries` go into the
+ * keyring for persistent storage.
+ *
+ * The caller is responsible for:
+ * 1. Displaying the plaintext codes to the user ONCE.
+ * 2. Writing `entries` into the vault's keyring.
+ * 3. Writing an audit-ledger entry recording the enrollment.
+ */
+declare function generateRecoveryCodeSet(opts: GenerateRecoveryCodeSetOptions): Promise<{
+    codes: string[];
+    entries: RecoveryCodeEntry[];
+}>;
+/**
+ * Parse user input into a normalized recovery code. Accepts whitespace,
+ * hyphens, and lowercase — strips them all. Verifies the checksum.
+ */
+declare function parseRecoveryCode(input: string): ParseResult;
+/**
+ * Format a normalized recovery code for display (groups of 4, hyphenated).
+ * Inverse of the strip-hyphens step in `parseRecoveryCode`.
+ */
+declare function formatRecoveryCode(normalizedCode: string): string;
+/**
+ * Derive the AES-KW wrapping key from a recovery code + salt. Used for
+ * both enrollment (wrap the KEK) and unlock (unwrap the KEK).
+ *
+ * @param code - A normalized recovery code (uppercase Base32, no
+ *   hyphens/whitespace, checksum included).
+ * @param salt - Per-code random salt from the stored entry.
+ */
+declare function deriveRecoveryWrappingKey(code: string, salt: Uint8Array): Promise<CryptoKey>;
+/**
+ * Wrap a KEK with a recovery-code-derived wrapping key.
+ * Returns raw bytes suitable for base64 encoding + storage.
+ */
+declare function wrapKEKForRecovery(kek: CryptoKey, code: string, salt: Uint8Array): Promise<Uint8Array>;
+/**
+ * Unwrap the KEK using a recovery code + a stored entry.
+ *
+ * Throws (AES-KW authentication failure) if the code doesn't match
+ * this entry. The caller typically iterates all enrolled entries and
+ * catches the failure until one succeeds.
+ *
+ * On success, the caller MUST burn the entry — deleting `entry.codeId`
+ * from the keyring — so the code can never be replayed.
+ */
+declare function unwrapKEKFromRecovery(code: string, entry: RecoveryCodeEntry): Promise<CryptoKey>;
+
+export { type GenerateRecoveryCodeSetOptions, type ParseResult, type RecoveryCodeEntry, deriveRecoveryWrappingKey, formatRecoveryCode, generateRecoveryCodeSet, parseRecoveryCode, unwrapKEKFromRecovery, wrapKEKForRecovery };

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+/**
+ * **@noy-db/on-recovery** — one-time printable recovery codes for noy-db.
+ *
+ * The last-resort unlock path when the primary authentication
+ * (passphrase, WebAuthn, OIDC) is unavailable. Codes are designed to
+ * be printed on paper and stored in a safe — each code unlocks the
+ * vault exactly once and then is burned by deleting its keyring entry.
+ *
+ * Part of the `@noy-db/on-*` authentication family.
+ *
+ * ## Security model
+ *
+ * Each code is a random 100-bit value (20 Base32 characters) with a
+ * 5-character checksum appended. The wrapping key is derived from
+ * the code via:
+ *
+ * ```
+ *   PBKDF2-SHA256(
+ *     password = normalizeCode(code),
+ *     salt     = perCodeRandomSalt,
+ *     iter     = 600_000,
+ *     length   = 32,
+ *   )
+ * ```
+ *
+ * The wrapping key is then used with AES-KW (RFC 3394) to wrap the
+ * vault's KEK. The wrapped KEK + salt + code-ID land in the keyring
+ * under a `_recovery_<N>` entry, alongside other unlock mechanisms.
+ *
+ * This package provides the CRYPTO layer only. Storage, burn, audit,
+ * and rate-limiting are the caller's responsibility — typically
+ * coordinated with `@noy-db/hub`'s keyring + audit-ledger APIs.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import {
+ *   generateRecoveryCodeSet,
+ *   parseRecoveryCode,
+ *   deriveRecoveryWrappingKey,
+ *   wrapKEKForRecovery,
+ *   unwrapKEKFromRecovery,
+ * } from '@noy-db/on-recovery'
+ *
+ * // ENROLL — after user unlocks with passphrase, generate N codes
+ * const { codes, entries } = await generateRecoveryCodeSet({ count: 10, kek })
+ * // `codes` is what you show the user ONCE (to print/save).
+ * // `entries` goes into the keyring file (persistent storage).
+ *
+ * // UNLOCK — user types in a code later
+ * const parsed = parseRecoveryCode(userInput)
+ * if (parsed.status !== 'valid') handleInvalidFormat(parsed.status)
+ *
+ * for (const entry of storedEntries) {
+ *   try {
+ *     const kek = await unwrapKEKFromRecovery(parsed.code, entry)
+ *     // Match! Burn this entry: delete from keyring.
+ *     await deleteKeyringEntry(entry.codeId)
+ *     return kek
+ *   } catch (e) {
+ *     // Wrong entry, try next
+ *   }
+ * }
+ * throw new Error('no matching recovery code')
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * A single recovery-code enrollment entry. The caller stores this in
+ * the vault's keyring alongside other unlock mechanisms.
+ */
+interface RecoveryCodeEntry {
+    /** Stable identifier for this code (ULID). Used by the caller to delete the entry on burn. */
+    readonly codeId: string;
+    /** PBKDF2 salt for this code, base64-encoded. */
+    readonly salt: string;
+    /** Wrapped KEK, base64-encoded. Unwrap with AES-KW using the code-derived key. */
+    readonly wrappedKEK: string;
+    /** Timestamp the code was enrolled. */
+    readonly enrolledAt: string;
+}
+/** Options for `generateRecoveryCodeSet()`. */
+interface GenerateRecoveryCodeSetOptions {
+    /** Number of codes to generate. Default 10. Reasonable: 8-20. */
+    count?: number;
+    /** The vault's current KEK (unwrapped). Required — proves possession. */
+    kek: CryptoKey;
+}
+/** Result of `parseRecoveryCode()`. */
+type ParseResult = {
+    status: 'valid';
+    code: string;
+} | {
+    status: 'invalid-checksum';
+} | {
+    status: 'invalid-format';
+};
+/**
+ * Generate a fresh recovery-code set. The returned `codes` must be shown
+ * to the user exactly once (print/save); the `entries` go into the
+ * keyring for persistent storage.
+ *
+ * The caller is responsible for:
+ * 1. Displaying the plaintext codes to the user ONCE.
+ * 2. Writing `entries` into the vault's keyring.
+ * 3. Writing an audit-ledger entry recording the enrollment.
+ */
+declare function generateRecoveryCodeSet(opts: GenerateRecoveryCodeSetOptions): Promise<{
+    codes: string[];
+    entries: RecoveryCodeEntry[];
+}>;
+/**
+ * Parse user input into a normalized recovery code. Accepts whitespace,
+ * hyphens, and lowercase — strips them all. Verifies the checksum.
+ */
+declare function parseRecoveryCode(input: string): ParseResult;
+/**
+ * Format a normalized recovery code for display (groups of 4, hyphenated).
+ * Inverse of the strip-hyphens step in `parseRecoveryCode`.
+ */
+declare function formatRecoveryCode(normalizedCode: string): string;
+/**
+ * Derive the AES-KW wrapping key from a recovery code + salt. Used for
+ * both enrollment (wrap the KEK) and unlock (unwrap the KEK).
+ *
+ * @param code - A normalized recovery code (uppercase Base32, no
+ *   hyphens/whitespace, checksum included).
+ * @param salt - Per-code random salt from the stored entry.
+ */
+declare function deriveRecoveryWrappingKey(code: string, salt: Uint8Array): Promise<CryptoKey>;
+/**
+ * Wrap a KEK with a recovery-code-derived wrapping key.
+ * Returns raw bytes suitable for base64 encoding + storage.
+ */
+declare function wrapKEKForRecovery(kek: CryptoKey, code: string, salt: Uint8Array): Promise<Uint8Array>;
+/**
+ * Unwrap the KEK using a recovery code + a stored entry.
+ *
+ * Throws (AES-KW authentication failure) if the code doesn't match
+ * this entry. The caller typically iterates all enrolled entries and
+ * catches the failure until one succeeds.
+ *
+ * On success, the caller MUST burn the entry — deleting `entry.codeId`
+ * from the keyring — so the code can never be replayed.
+ */
+declare function unwrapKEKFromRecovery(code: string, entry: RecoveryCodeEntry): Promise<CryptoKey>;
+
+export { type GenerateRecoveryCodeSetOptions, type ParseResult, type RecoveryCodeEntry, deriveRecoveryWrappingKey, formatRecoveryCode, generateRecoveryCodeSet, parseRecoveryCode, unwrapKEKFromRecovery, wrapKEKForRecovery };

package/dist/index.js

@@ -0,0 +1,164 @@
+// src/index.ts
+import { generateULID } from "@noy-db/hub";
+var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+var STRIPPABLE = /[\s\-_]/g;
+var CODE_ENTROPY_BYTES = 15;
+var CHECKSUM_LEN = 4;
+var PBKDF2_ITERATIONS = 6e5;
+var PBKDF2_KEY_LENGTH = 32 * 8;
+var SALT_BYTES = 16;
+async function generateRecoveryCodeSet(opts) {
+  const count = opts.count ?? 10;
+  if (!Number.isInteger(count) || count < 1 || count > 100) {
+    throw new Error(`on-recovery: count must be 1-100 (got ${count})`);
+  }
+  const codes = [];
+  const entries = [];
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  for (let i = 0; i < count; i++) {
+    const raw = generateRawCode();
+    const formatted = formatCodeForDisplay(raw);
+    const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
+    const wrappingKey = await deriveRecoveryWrappingKey(raw, salt);
+    const wrappedKEK = await wrapKEK(opts.kek, wrappingKey);
+    codes.push(formatted);
+    entries.push({
+      codeId: generateULID(),
+      salt: base64Encode(salt),
+      wrappedKEK: base64Encode(wrappedKEK),
+      enrolledAt: now
+    });
+  }
+  return { codes, entries };
+}
+function parseRecoveryCode(input) {
+  const normalized = input.toUpperCase().replace(STRIPPABLE, "");
+  const expectedLen = base32CharsForBytes(CODE_ENTROPY_BYTES) + CHECKSUM_LEN;
+  if (normalized.length !== expectedLen) {
+    return { status: "invalid-format" };
+  }
+  for (const ch of normalized) {
+    if (!BASE32_ALPHABET.includes(ch)) {
+      return { status: "invalid-format" };
+    }
+  }
+  const bodyLen = normalized.length - CHECKSUM_LEN;
+  const body = normalized.slice(0, bodyLen);
+  const checksum = normalized.slice(bodyLen);
+  if (computeChecksum(body) !== checksum) {
+    return { status: "invalid-checksum" };
+  }
+  return { status: "valid", code: normalized };
+}
+function formatRecoveryCode(normalizedCode) {
+  const groups = [];
+  for (let i = 0; i < normalizedCode.length; i += 4) {
+    groups.push(normalizedCode.slice(i, i + 4));
+  }
+  return groups.join("-");
+}
+async function deriveRecoveryWrappingKey(code, salt) {
+  const password = new TextEncoder().encode(code);
+  const baseKey = await crypto.subtle.importKey(
+    "raw",
+    password,
+    "PBKDF2",
+    false,
+    ["deriveKey"]
+  );
+  return crypto.subtle.deriveKey(
+    {
+      name: "PBKDF2",
+      hash: "SHA-256",
+      salt,
+      iterations: PBKDF2_ITERATIONS
+    },
+    baseKey,
+    { name: "AES-KW", length: PBKDF2_KEY_LENGTH },
+    false,
+    ["wrapKey", "unwrapKey"]
+  );
+}
+async function wrapKEKForRecovery(kek, code, salt) {
+  const wrappingKey = await deriveRecoveryWrappingKey(code, salt);
+  return wrapKEK(kek, wrappingKey);
+}
+async function unwrapKEKFromRecovery(code, entry) {
+  const salt = base64Decode(entry.salt);
+  const wrappedKEK = base64Decode(entry.wrappedKEK);
+  const wrappingKey = await deriveRecoveryWrappingKey(code, salt);
+  return crypto.subtle.unwrapKey(
+    "raw",
+    wrappedKEK,
+    wrappingKey,
+    "AES-KW",
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+function generateRawCode() {
+  const entropy = crypto.getRandomValues(new Uint8Array(CODE_ENTROPY_BYTES));
+  const body = base32Encode(entropy);
+  const checksum = computeChecksum(body);
+  return body + checksum;
+}
+function formatCodeForDisplay(rawNormalized) {
+  return formatRecoveryCode(rawNormalized);
+}
+function computeChecksum(body) {
+  let h = 0;
+  for (let i = 0; i < body.length; i++) {
+    const v = BASE32_ALPHABET.indexOf(body[i]);
+    h = h * 33 + v >>> 0;
+  }
+  const chars = [];
+  for (let i = 0; i < CHECKSUM_LEN; i++) {
+    chars.push(BASE32_ALPHABET[h >>> i * 5 & 31]);
+  }
+  return chars.join("");
+}
+function base32CharsForBytes(n) {
+  return Math.ceil(n * 8 / 5);
+}
+function base32Encode(bytes) {
+  let bits = 0;
+  let value = 0;
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    value = value << 8 | bytes[i];
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += BASE32_ALPHABET[value >>> bits & 31];
+    }
+  }
+  if (bits > 0) {
+    out += BASE32_ALPHABET[value << 5 - bits & 31];
+  }
+  return out;
+}
+async function wrapKEK(kek, wrappingKey) {
+  const wrapped = await crypto.subtle.wrapKey("raw", kek, wrappingKey, "AES-KW");
+  return new Uint8Array(wrapped);
+}
+function base64Encode(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return btoa(s);
+}
+function base64Decode(str) {
+  const s = atob(str);
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+export {
+  deriveRecoveryWrappingKey,
+  formatRecoveryCode,
+  generateRecoveryCodeSet,
+  parseRecoveryCode,
+  unwrapKEKFromRecovery,
+  wrapKEKForRecovery
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/on-recovery** — one-time printable recovery codes for noy-db.\n *\n * The last-resort unlock path when the primary authentication\n * (passphrase, WebAuthn, OIDC) is unavailable. Codes are designed to\n * be printed on paper and stored in a safe — each code unlocks the\n * vault exactly once and then is burned by deleting its keyring entry.\n *\n * Part of the `@noy-db/on-*` authentication family.\n *\n * ## Security model\n *\n * Each code is a random 100-bit value (20 Base32 characters) with a\n * 5-character checksum appended. The wrapping key is derived from\n * the code via:\n *\n * ```\n *   PBKDF2-SHA256(\n *     password = normalizeCode(code),\n *     salt     = perCodeRandomSalt,\n *     iter     = 600_000,\n *     length   = 32,\n *   )\n * ```\n *\n * The wrapping key is then used with AES-KW (RFC 3394) to wrap the\n * vault's KEK. The wrapped KEK + salt + code-ID land in the keyring\n * under a `_recovery_<N>` entry, alongside other unlock mechanisms.\n *\n * This package provides the CRYPTO layer only. Storage, burn, audit,\n * and rate-limiting are the caller's responsibility — typically\n * coordinated with `@noy-db/hub`'s keyring + audit-ledger APIs.\n *\n * ## Usage\n *\n * ```ts\n * import {\n *   generateRecoveryCodeSet,\n *   parseRecoveryCode,\n *   deriveRecoveryWrappingKey,\n *   wrapKEKForRecovery,\n *   unwrapKEKFromRecovery,\n * } from '@noy-db/on-recovery'\n *\n * // ENROLL — after user unlocks with passphrase, generate N codes\n * const { codes, entries } = await generateRecoveryCodeSet({ count: 10, kek })\n * // `codes` is what you show the user ONCE (to print/save).\n * // `entries` goes into the keyring file (persistent storage).\n *\n * // UNLOCK — user types in a code later\n * const parsed = parseRecoveryCode(userInput)\n * if (parsed.status !== 'valid') handleInvalidFormat(parsed.status)\n *\n * for (const entry of storedEntries) {\n *   try {\n *     const kek = await unwrapKEKFromRecovery(parsed.code, entry)\n *     // Match! Burn this entry: delete from keyring.\n *     await deleteKeyringEntry(entry.codeId)\n *     return kek\n *   } catch (e) {\n *     // Wrong entry, try next\n *   }\n * }\n * throw new Error('no matching recovery code')\n * ```\n *\n * @packageDocumentation\n */\n\nimport { generateULID } from '@noy-db/hub'\n\n// Constants ────────────────────────────────────────────────────────────\n\n/** RFC 4648 Base32 alphabet — A-Z + 2-7, no ambiguous chars. */\nconst BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567'\n\n/** Characters to ignore on input (whitespace, hyphens, lowercase). */\nconst STRIPPABLE = /[\\s\\-_]/g\n\n/** How many random bytes of entropy per code. */\nconst CODE_ENTROPY_BYTES = 15   // 15 bytes = 120 bits = exactly 24 Base32 chars (clean groups of 4)\n\n/** Length of the checksum portion (Base32 chars). */\nconst CHECKSUM_LEN = 4           // 24 body + 4 checksum = 28 chars = 7 groups of 4\n\n/** PBKDF2 iteration count — matches hub's passphrase-unlock derivation. */\nconst PBKDF2_ITERATIONS = 600_000\n\n/** PBKDF2 output length — 32 bytes = 256-bit wrapping key. */\nconst PBKDF2_KEY_LENGTH = 32 * 8\n\n/** Per-code salt length. */\nconst SALT_BYTES = 16\n\n// Types ────────────────────────────────────────────────────────────────\n\n/**\n * A single recovery-code enrollment entry. The caller stores this in\n * the vault's keyring alongside other unlock mechanisms.\n */\nexport interface RecoveryCodeEntry {\n  /** Stable identifier for this code (ULID). Used by the caller to delete the entry on burn. */\n  readonly codeId: string\n  /** PBKDF2 salt for this code, base64-encoded. */\n  readonly salt: string\n  /** Wrapped KEK, base64-encoded. Unwrap with AES-KW using the code-derived key. */\n  readonly wrappedKEK: string\n  /** Timestamp the code was enrolled. */\n  readonly enrolledAt: string\n}\n\n/** Options for `generateRecoveryCodeSet()`. */\nexport interface GenerateRecoveryCodeSetOptions {\n  /** Number of codes to generate. Default 10. Reasonable: 8-20. */\n  count?: number\n  /** The vault's current KEK (unwrapped). Required — proves possession. */\n  kek: CryptoKey\n}\n\n/** Result of `parseRecoveryCode()`. */\nexport type ParseResult =\n  | { status: 'valid'; code: string }          // Normalized, checksum-verified\n  | { status: 'invalid-checksum' }             // Format OK, checksum wrong\n  | { status: 'invalid-format' }               // Not a valid code shape\n\n// Code generation ──────────────────────────────────────────────────────\n\n/**\n * Generate a fresh recovery-code set. The returned `codes` must be shown\n * to the user exactly once (print/save); the `entries` go into the\n * keyring for persistent storage.\n *\n * The caller is responsible for:\n * 1. Displaying the plaintext codes to the user ONCE.\n * 2. Writing `entries` into the vault's keyring.\n * 3. Writing an audit-ledger entry recording the enrollment.\n */\nexport async function generateRecoveryCodeSet(\n  opts: GenerateRecoveryCodeSetOptions,\n): Promise<{ codes: string[]; entries: RecoveryCodeEntry[] }> {\n  const count = opts.count ?? 10\n  if (!Number.isInteger(count) || count < 1 || count > 100) {\n    throw new Error(`on-recovery: count must be 1-100 (got ${count})`)\n  }\n\n  const codes: string[] = []\n  const entries: RecoveryCodeEntry[] = []\n  const now = new Date().toISOString()\n\n  for (let i = 0; i < count; i++) {\n    const raw = generateRawCode()\n    const formatted = formatCodeForDisplay(raw)\n    const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES))\n    const wrappingKey = await deriveRecoveryWrappingKey(raw, salt)\n    const wrappedKEK = await wrapKEK(opts.kek, wrappingKey)\n\n    codes.push(formatted)\n    entries.push({\n      codeId: generateULID(),\n      salt: base64Encode(salt),\n      wrappedKEK: base64Encode(wrappedKEK),\n      enrolledAt: now,\n    })\n  }\n\n  return { codes, entries }\n}\n\n// Code parsing + normalization ─────────────────────────────────────────\n\n/**\n * Parse user input into a normalized recovery code. Accepts whitespace,\n * hyphens, and lowercase — strips them all. Verifies the checksum.\n */\nexport function parseRecoveryCode(input: string): ParseResult {\n  const normalized = input.toUpperCase().replace(STRIPPABLE, '')\n\n  const expectedLen = base32CharsForBytes(CODE_ENTROPY_BYTES) + CHECKSUM_LEN\n  if (normalized.length !== expectedLen) {\n    return { status: 'invalid-format' }\n  }\n  for (const ch of normalized) {\n    if (!BASE32_ALPHABET.includes(ch)) {\n      return { status: 'invalid-format' }\n    }\n  }\n\n  const bodyLen = normalized.length - CHECKSUM_LEN\n  const body = normalized.slice(0, bodyLen)\n  const checksum = normalized.slice(bodyLen)\n\n  if (computeChecksum(body) !== checksum) {\n    return { status: 'invalid-checksum' }\n  }\n\n  return { status: 'valid', code: normalized }\n}\n\n/**\n * Format a normalized recovery code for display (groups of 4, hyphenated).\n * Inverse of the strip-hyphens step in `parseRecoveryCode`.\n */\nexport function formatRecoveryCode(normalizedCode: string): string {\n  const groups: string[] = []\n  for (let i = 0; i < normalizedCode.length; i += 4) {\n    groups.push(normalizedCode.slice(i, i + 4))\n  }\n  return groups.join('-')\n}\n\n// Key derivation ───────────────────────────────────────────────────────\n\n/**\n * Derive the AES-KW wrapping key from a recovery code + salt. Used for\n * both enrollment (wrap the KEK) and unlock (unwrap the KEK).\n *\n * @param code - A normalized recovery code (uppercase Base32, no\n *   hyphens/whitespace, checksum included).\n * @param salt - Per-code random salt from the stored entry.\n */\nexport async function deriveRecoveryWrappingKey(\n  code: string,\n  salt: Uint8Array,\n): Promise<CryptoKey> {\n  const password = new TextEncoder().encode(code)\n  const baseKey = await crypto.subtle.importKey(\n    'raw',\n    password as BufferSource,\n    'PBKDF2',\n    false,\n    ['deriveKey'],\n  )\n  return crypto.subtle.deriveKey(\n    {\n      name: 'PBKDF2',\n      hash: 'SHA-256',\n      salt: salt as BufferSource,\n      iterations: PBKDF2_ITERATIONS,\n    },\n    baseKey,\n    { name: 'AES-KW', length: PBKDF2_KEY_LENGTH },\n    false,\n    ['wrapKey', 'unwrapKey'],\n  )\n}\n\n// KEK wrap/unwrap ──────────────────────────────────────────────────────\n\n/**\n * Wrap a KEK with a recovery-code-derived wrapping key.\n * Returns raw bytes suitable for base64 encoding + storage.\n */\nexport async function wrapKEKForRecovery(\n  kek: CryptoKey,\n  code: string,\n  salt: Uint8Array,\n): Promise<Uint8Array> {\n  const wrappingKey = await deriveRecoveryWrappingKey(code, salt)\n  return wrapKEK(kek, wrappingKey)\n}\n\n/**\n * Unwrap the KEK using a recovery code + a stored entry.\n *\n * Throws (AES-KW authentication failure) if the code doesn't match\n * this entry. The caller typically iterates all enrolled entries and\n * catches the failure until one succeeds.\n *\n * On success, the caller MUST burn the entry — deleting `entry.codeId`\n * from the keyring — so the code can never be replayed.\n */\nexport async function unwrapKEKFromRecovery(\n  code: string,\n  entry: RecoveryCodeEntry,\n): Promise<CryptoKey> {\n  const salt = base64Decode(entry.salt)\n  const wrappedKEK = base64Decode(entry.wrappedKEK)\n  const wrappingKey = await deriveRecoveryWrappingKey(code, salt)\n\n  return crypto.subtle.unwrapKey(\n    'raw',\n    wrappedKEK as BufferSource,\n    wrappingKey,\n    'AES-KW',\n    { name: 'AES-GCM', length: 256 },\n    false,\n    ['encrypt', 'decrypt'],\n  )\n}\n\n// Internals ────────────────────────────────────────────────────────────\n\nfunction generateRawCode(): string {\n  const entropy = crypto.getRandomValues(new Uint8Array(CODE_ENTROPY_BYTES))\n  const body = base32Encode(entropy)\n  const checksum = computeChecksum(body)\n  return body + checksum\n}\n\nfunction formatCodeForDisplay(rawNormalized: string): string {\n  return formatRecoveryCode(rawNormalized)\n}\n\n/**\n * Deterministic 4-character checksum over Base32 body. Catches\n * transcription errors (single-char swaps, shifted digits) with very\n * high probability.\n *\n * Uses a simple polynomial hash reduced modulo the Base32 alphabet\n * size (32). Four output chars = 20 bits ≈ 1-in-1M false positive.\n */\nfunction computeChecksum(body: string): string {\n  let h = 0\n  for (let i = 0; i < body.length; i++) {\n    const v = BASE32_ALPHABET.indexOf(body[i]!)\n    h = (h * 33 + v) >>> 0\n  }\n  // Extract 4 Base32 chars from the 20 low bits\n  const chars: string[] = []\n  for (let i = 0; i < CHECKSUM_LEN; i++) {\n    chars.push(BASE32_ALPHABET[(h >>> (i * 5)) & 0x1f]!)\n  }\n  return chars.join('')\n}\n\nfunction base32CharsForBytes(n: number): number {\n  // Each 5 bytes → 8 Base32 chars. Partial-byte handling via ceil.\n  return Math.ceil((n * 8) / 5)\n}\n\nfunction base32Encode(bytes: Uint8Array): string {\n  let bits = 0\n  let value = 0\n  let out = ''\n  for (let i = 0; i < bytes.length; i++) {\n    value = (value << 8) | bytes[i]!\n    bits += 8\n    while (bits >= 5) {\n      bits -= 5\n      out += BASE32_ALPHABET[(value >>> bits) & 0x1f]\n    }\n  }\n  if (bits > 0) {\n    out += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f]\n  }\n  return out\n}\n\nasync function wrapKEK(kek: CryptoKey, wrappingKey: CryptoKey): Promise<Uint8Array> {\n  const wrapped = await crypto.subtle.wrapKey('raw', kek, wrappingKey, 'AES-KW')\n  return new Uint8Array(wrapped)\n}\n\nfunction base64Encode(bytes: Uint8Array): string {\n  let s = ''\n  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]!)\n  // `btoa` is globally available in browsers, Node 16+, Deno, Bun.\n  return btoa(s)\n}\n\nfunction base64Decode(str: string): Uint8Array {\n  const s = atob(str)\n  const out = new Uint8Array(s.length)\n  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i)\n  return out\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@noy-db/on-recovery",
+  "version": "0.1.0-pre.3",
+  "description": "One-time printable recovery codes for noy-db — last-resort vault unlock when the passphrase, passkey, and OIDC provider are all unavailable. Base32 + checksum codes, PBKDF2-derived wrapping keys, burn-on-use. Part of the @noy-db/on-* authentication family.",
+  "license": "MIT",
+  "author": "vLannaAi <vicio@lanna.ai>",
+  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/on-recovery#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vLannaAi/noy-db.git",
+    "directory": "packages/on-recovery"
+  },
+  "bugs": {
+    "url": "https://github.com/vLannaAi/noy-db/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@noy-db/hub": "0.1.0-pre.3"
+  },
+  "devDependencies": {
+    "@noy-db/hub": "0.1.0-pre.3"
+  },
+  "keywords": [
+    "noy-db",
+    "auth",
+    "on-recovery",
+    "recovery-codes",
+    "one-time-codes",
+    "paper-backup",
+    "base32",
+    "pbkdf2",
+    "zero-knowledge"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}