@noy-db/on-recovery 0.2.0-pre.9 → 0.3.0-pre.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noy-db/on-recovery",
-  "version": "0.2.0-pre.9",
+  "version": "0.3.0-pre.2",
   "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>",
@@ -17,17 +17,10 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
-  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -36,13 +29,13 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "peerDependencies": {
-    "@noy-db/hub": "0.2.0-pre.9"
+    "@noy-db/hub": "0.3.0-pre.2"
   },
   "devDependencies": {
-    "@noy-db/hub": "0.2.0-pre.9"
+    "@noy-db/hub": "0.3.0-pre.2"
   },
   "keywords": [
     "noy-db",

package/dist/index.cjs

@@ -1,122 +0,0 @@
-"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, {
-  formatRecoveryCode: () => formatRecoveryCode,
-  generateRecoveryCodeSet: () => generateRecoveryCodeSet,
-  parseRecoveryCode: () => parseRecoveryCode
-});
-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;
-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 = [];
-  for (let i = 0; i < count; i++) {
-    const raw = generateRawCode();
-    const formatted = formatCodeForDisplay(raw);
-    const entry = await (0, import_hub.mintPaperRecoveryEntry)(opts.deks, raw, (0, import_hub.generateULID)());
-    codes.push(formatted);
-    entries.push(entry);
-  }
-  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("-");
-}
-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;
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  formatRecoveryCode,
-  generateRecoveryCodeSet,
-  parseRecoveryCode
-});
-//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/on-recovery** — printable recovery codes for noy-db.\n *\n * The last-resort unlock path when the primary authentication is\n * unavailable. Codes are designed to be printed on paper and stored\n * in a safe — each code unlocks the vault exactly once and then is\n * burned by deleting its `_meta/recovery-paper` entry.\n *\n * Part of the `@noy-db/on-*` authentication family.\n *\n * ## Format (Option A)\n *\n * This package is now a **thin code-generator + parser layer over\n * the hub's `mintPaperRecoveryEntry` primitive**. Its job is exactly\n * three things:\n *\n * 1. Generate printable Base32 codes with checksums (the user-facing\n *    string format).\n * 2. Parse user input back into a normalized code (whitespace /\n *    hyphen / case insensitive).\n * 3. Delegate the wrapping crypto to the hub via\n *    `mintPaperRecoveryEntry(deks, code, codeId)`.\n *\n * This delegation aligns recovery with the hub's wrap-DEKs primitive\n * (the same shape used by `@noy-db/on-pin` and now `@noy-db/on-password`\n * after the wrap-DEKs path change). It eliminates the format mismatch\n * that made the previous package version unusable with `db.enrollRecovery`.\n *\n * ## Usage\n *\n * ```ts\n * import { generateRecoveryCodeSet, parseRecoveryCode } from '@noy-db/on-recovery'\n *\n * // ENROLL — after the user unlocks at tier 1, mint N codes\n * const keyring = await db.getKeyring('acme')\n * const { codes, entries } = await generateRecoveryCodeSet({ deks: keyring.deks, count: 10 })\n * showCodesToUser(codes)\n * await db.enrollRecovery('acme', { profile: 'paper', entries })\n *\n * // RECOVER — user types one back later (handled by db.recoverPassphrase)\n * const parsed = parseRecoveryCode(userInput)\n * if (parsed.status !== 'valid') return handleInvalid(parsed.status)\n * await db.recoverPassphrase('acme', {\n *   newPassphrase,\n *   recoveryProof: { profile: 'paper', payload: { code: parsed.code } },\n * })\n * ```\n *\n * @packageDocumentation\n */\n\nimport { generateULID, mintPaperRecoveryEntry, type PaperRecoveryEntry } 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// Types ────────────────────────────────────────────────────────────────\n\n/** Options for `generateRecoveryCodeSet()`. */\nexport interface GenerateRecoveryCodeSetOptions {\n  /** Number of codes to generate. Default 10. Reasonable: 8-20. */\n  count?: number\n  /**\n   * The vault's current DEK set (typically `(await db.getKeyring(vault)).deks`).\n   * Required — proves possession and is the input the hub's\n   * `mintPaperRecoveryEntry` needs.\n   */\n  deks: Map<string, 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. Returned `codes` must be shown\n * to the user exactly once (print/save); `entries` go into the vault\n * via `db.enrollRecovery({ profile: 'paper', entries })`.\n *\n * Internally calls the hub's `mintPaperRecoveryEntry` once per code.\n * The hub's wrap-DEKs format is preserved end-to-end — `db.enrollRecovery`\n * stores the entries verbatim and `db.recoverPassphrase` consumes them\n * via `unwrapDeksFromPaperEntry`.\n */\nexport async function generateRecoveryCodeSet(\n  opts: GenerateRecoveryCodeSetOptions,\n): Promise<{ codes: string[]; entries: PaperRecoveryEntry[] }> {\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: PaperRecoveryEntry[] = []\n\n  for (let i = 0; i < count; i++) {\n    const raw = generateRawCode()\n    const formatted = formatCodeForDisplay(raw)\n    // The hub stores entries keyed on the NORMALIZED code (raw, no\n    // hyphens). Mint with the normalized form so `db.recoverPassphrase`'s\n    // `normalizePaperCode(input)` matches at unlock time.\n    const entry = await mintPaperRecoveryEntry(opts.deks, raw, generateULID())\n    codes.push(formatted)\n    entries.push(entry)\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// 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  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  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"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -1,99 +0,0 @@
-import { PaperRecoveryEntry } from '@noy-db/hub';
-
-/**
- * **@noy-db/on-recovery** — printable recovery codes for noy-db.
- *
- * The last-resort unlock path when the primary authentication 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 `_meta/recovery-paper` entry.
- *
- * Part of the `@noy-db/on-*` authentication family.
- *
- * ## Format (Option A)
- *
- * This package is now a **thin code-generator + parser layer over
- * the hub's `mintPaperRecoveryEntry` primitive**. Its job is exactly
- * three things:
- *
- * 1. Generate printable Base32 codes with checksums (the user-facing
- *    string format).
- * 2. Parse user input back into a normalized code (whitespace /
- *    hyphen / case insensitive).
- * 3. Delegate the wrapping crypto to the hub via
- *    `mintPaperRecoveryEntry(deks, code, codeId)`.
- *
- * This delegation aligns recovery with the hub's wrap-DEKs primitive
- * (the same shape used by `@noy-db/on-pin` and now `@noy-db/on-password`
- * after the wrap-DEKs path change). It eliminates the format mismatch
- * that made the previous package version unusable with `db.enrollRecovery`.
- *
- * ## Usage
- *
- * ```ts
- * import { generateRecoveryCodeSet, parseRecoveryCode } from '@noy-db/on-recovery'
- *
- * // ENROLL — after the user unlocks at tier 1, mint N codes
- * const keyring = await db.getKeyring('acme')
- * const { codes, entries } = await generateRecoveryCodeSet({ deks: keyring.deks, count: 10 })
- * showCodesToUser(codes)
- * await db.enrollRecovery('acme', { profile: 'paper', entries })
- *
- * // RECOVER — user types one back later (handled by db.recoverPassphrase)
- * const parsed = parseRecoveryCode(userInput)
- * if (parsed.status !== 'valid') return handleInvalid(parsed.status)
- * await db.recoverPassphrase('acme', {
- *   newPassphrase,
- *   recoveryProof: { profile: 'paper', payload: { code: parsed.code } },
- * })
- * ```
- *
- * @packageDocumentation
- */
-
-/** Options for `generateRecoveryCodeSet()`. */
-interface GenerateRecoveryCodeSetOptions {
-    /** Number of codes to generate. Default 10. Reasonable: 8-20. */
-    count?: number;
-    /**
-     * The vault's current DEK set (typically `(await db.getKeyring(vault)).deks`).
-     * Required — proves possession and is the input the hub's
-     * `mintPaperRecoveryEntry` needs.
-     */
-    deks: Map<string, CryptoKey>;
-}
-/** Result of `parseRecoveryCode()`. */
-type ParseResult = {
-    status: 'valid';
-    code: string;
-} | {
-    status: 'invalid-checksum';
-} | {
-    status: 'invalid-format';
-};
-/**
- * Generate a fresh recovery-code set. Returned `codes` must be shown
- * to the user exactly once (print/save); `entries` go into the vault
- * via `db.enrollRecovery({ profile: 'paper', entries })`.
- *
- * Internally calls the hub's `mintPaperRecoveryEntry` once per code.
- * The hub's wrap-DEKs format is preserved end-to-end — `db.enrollRecovery`
- * stores the entries verbatim and `db.recoverPassphrase` consumes them
- * via `unwrapDeksFromPaperEntry`.
- */
-declare function generateRecoveryCodeSet(opts: GenerateRecoveryCodeSetOptions): Promise<{
-    codes: string[];
-    entries: PaperRecoveryEntry[];
-}>;
-/**
- * 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;
-
-export { type GenerateRecoveryCodeSetOptions, type ParseResult, formatRecoveryCode, generateRecoveryCodeSet, parseRecoveryCode };