@noy-db/hub 0.1.0-pre.7 → 0.1.0-pre.8

package/dist/index.cjs

@@ -1919,6 +1919,7 @@ async function loadActiveDelegations(store, vault, user, delegationsDek, now = /
     }
     if (token.toUser !== user.userId) continue;
     if (token.until <= nowIso) continue;
+    if (!user.kek) continue;
     let dek;
     try {
       dek = await unwrapKey(token.wrappedDek, user.kek);
@@ -2163,6 +2164,8 @@ __export(src_exports, {
   mergeCrdtStates: () => mergeCrdtStates,
   mergePolicy: () => mergePolicy,
   min: () => min,
+  mintPaperRecoveryEntry: () => mintPaperRecoveryEntry,
+  mintWrappedDeksBlob: () => mintWrappedDeksBlob,
   paddedIndex: () => paddedIndex,
   parseBytes: () => parseBytes,
   parseIndex: () => parseIndex,
@@ -2173,6 +2176,7 @@ __export(src_exports, {
   readNoydbBundlePublicEnvelope: () => readNoydbBundlePublicEnvelope,
   readPath: () => readPath,
   readPublicEnvelope: () => readPublicEnvelope,
+  recoverUser: () => recoverUser,
   reduceRecords: () => reduceRecords,
   ref: () => ref,
   removeAuthenticator: () => removeAuthenticator,
@@ -2194,6 +2198,8 @@ __export(src_exports, {
   saveVaultPolicy: () => saveVaultPolicy,
   sha256Hex: () => sha256Hex3,
   sum: () => sum,
+  unwrapDeksFromBlob: () => unwrapDeksFromBlob,
+  unwrapDeksFromPaperEntry: () => unwrapDeksFromPaperEntry,
   unwrapMagicLinkGrant: () => unwrapMagicLinkGrant,
   validateI18nTextValue: () => validateI18nTextValue,
   validatePassphrase: () => validatePassphrase,
@@ -4869,6 +4875,9 @@ var SUGGESTIONS = {
   "repeated-adjacent": "Avoid repeating the same word twice in a row."
 };
 function validatePassphrase(s, opts) {
+  if (opts?.customValidator) {
+    return opts.customValidator(s);
+  }
   const minWords = opts?.minWords ?? DEFAULT_MIN_WORDS;
   const minWordLength = opts?.minWordLength ?? DEFAULT_MIN_WORD_LENGTH;
   const rejectRepeated = opts?.rejectRepeatedAdjacent ?? true;
@@ -4881,7 +4890,8 @@ function validatePassphrase(s, opts) {
   if (s.includes("  ")) {
     return { ok: false, reason: "double-space" };
   }
-  if (!/^[a-z]+( [a-z]+)*$/.test(s)) {
+  const charPattern = opts?.pattern ?? /^[a-z]+( [a-z]+)*$/;
+  if (!charPattern.test(s)) {
     return { ok: false, reason: "invalid-chars" };
   }
   const words = s.split(" ");
@@ -5393,6 +5403,11 @@ function hasAccess(keyring, collectionName) {
   return collectionName in keyring.permissions;
 }
 async function persistKeyring(adapter, vault, keyring) {
+  if (!keyring.kek) {
+    throw new ValidationError(
+      "persistKeyring: keyring.kek is null \u2014 cannot wrap DEKs without the KEK. This typically means the keyring was opened via tier-3 PIN resume, session restore, or a wrap-DEKs tier-2 unlock. Re-authenticate at tier 1 (passphrase) before persisting."
+    );
+  }
   const wrappedDeks = {};
   for (const [collName, dek] of keyring.deks) {
     wrappedDeks[collName] = await wrapKey(dek, keyring.kek);
@@ -5470,14 +5485,22 @@ async function enrollAuthenticator(store, vault, keyring, options) {
       `enrollAuthenticator: slot id "${options.id}" already exists in vault "${vault}". Remove the slot first or pick a unique id.`
     );
   }
-  const slot = {
+  const base = {
     id: options.id,
     method: options.method,
     enrolled_at: (/* @__PURE__ */ new Date()).toISOString(),
     enrolled_via_tier: options.enrolled_via_tier ?? 1,
-    wrapped_kek: options.wrapped_kek,
     meta: options.meta
   };
+  const slot = options.wrapKind === "deks" ? {
+    ...base,
+    wrapKind: "deks",
+    wrapped_deks: options.wrapped_deks,
+    iv: options.iv
+  } : {
+    ...base,
+    wrapped_kek: options.wrapped_kek
+  };
   const next = appendSlot(keyring, slot);
   await persistKeyring(store, vault, next);
   return next;
@@ -5589,50 +5612,39 @@ var RecoveryProfileNotImplementedError = class extends NoydbError {
 
 // src/team/recovery.ts
 init_types();
-var PAPER_DOC_ID = "recovery-paper";
-async function loadPaperRecoveryEntries(store, vault) {
-  const env = await store.get(vault, "_meta", PAPER_DOC_ID);
-  if (!env) return [];
-  try {
-    const doc = JSON.parse(env._data);
-    if (doc.profile !== "paper" || !Array.isArray(doc.entries)) return [];
-    return doc.entries;
-  } catch {
-    return [];
+
+// src/team/wrapped-deks.ts
+var PBKDF2_ITERATIONS2 = 6e5;
+var SALT_BYTES2 = 32;
+var IV_BYTES2 = 12;
+var subtle2 = globalThis.crypto.subtle;
+async function mintWrappedDeksBlob(deks, credential) {
+  const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES2));
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES2));
+  const wrappingKey = await deriveWrappingKey(credential, salt);
+  const exported = {};
+  for (const [coll, dek] of deks) {
+    const raw = await subtle2.exportKey("raw", dek);
+    exported[coll] = bytesToBase64(new Uint8Array(raw));
   }
-}
-async function savePaperRecoveryEntries(store, vault, entries) {
-  const doc = {
-    _noydb_recovery: 1,
-    profile: "paper",
-    entries
-  };
-  const envelope = {
-    _noydb: NOYDB_FORMAT_VERSION,
-    _v: 1,
-    _ts: (/* @__PURE__ */ new Date()).toISOString(),
-    _iv: "",
-    _data: JSON.stringify(doc)
+  const plaintext = new TextEncoder().encode(JSON.stringify({ deks: exported }));
+  const ciphertext = await subtle2.encrypt(
+    { name: "AES-GCM", iv },
+    wrappingKey,
+    plaintext
+  );
+  return {
+    salt: bytesToBase64(salt),
+    iv: bytesToBase64(iv),
+    wrappedDeks: bytesToBase64(new Uint8Array(ciphertext))
   };
-  await store.put(vault, "_meta", PAPER_DOC_ID, envelope);
-}
-async function burnPaperRecoveryEntry(store, vault, codeId) {
-  const entries = await loadPaperRecoveryEntries(store, vault);
-  const remaining = entries.filter((e) => e.codeId !== codeId);
-  await savePaperRecoveryEntries(store, vault, remaining);
-}
-async function hasRecoveryEnrolled(store, vault) {
-  const paper = await loadPaperRecoveryEntries(store, vault);
-  return paper.length > 0;
 }
-var subtle2 = globalThis.crypto.subtle;
-var RECOVERY_PBKDF2_ITERATIONS = 6e5;
-async function unwrapDeksFromPaperEntry(entry, code) {
-  const wrappingKey = await deriveRecoveryWrappingKey(code, base64ToBytes(entry.salt));
+async function unwrapDeksFromBlob(blob, credential) {
+  const wrappingKey = await deriveWrappingKey(credential, base64ToBytes(blob.salt));
   const plaintext = await subtle2.decrypt(
-    { name: "AES-GCM", iv: base64ToBytes(entry.iv) },
+    { name: "AES-GCM", iv: base64ToBytes(blob.iv) },
     wrappingKey,
-    base64ToBytes(entry.wrappedDeks)
+    base64ToBytes(blob.wrappedDeks)
   );
   const parsed = JSON.parse(new TextDecoder().decode(plaintext));
   const deks = /* @__PURE__ */ new Map();
@@ -5649,10 +5661,10 @@ async function unwrapDeksFromPaperEntry(entry, code) {
   }
   return deks;
 }
-async function deriveRecoveryWrappingKey(code, salt) {
+async function deriveWrappingKey(credential, salt) {
   const ikm = await subtle2.importKey(
     "raw",
-    new TextEncoder().encode(code),
+    new TextEncoder().encode(credential),
     "PBKDF2",
     false,
     ["deriveKey"]
@@ -5661,7 +5673,7 @@ async function deriveRecoveryWrappingKey(code, salt) {
     {
       name: "PBKDF2",
       salt,
-      iterations: RECOVERY_PBKDF2_ITERATIONS,
+      iterations: PBKDF2_ITERATIONS2,
       hash: "SHA-256"
     },
     ikm,
@@ -5670,6 +5682,11 @@ async function deriveRecoveryWrappingKey(code, salt) {
     ["encrypt", "decrypt"]
   );
 }
+function bytesToBase64(b) {
+  let s = "";
+  for (const x of b) s += String.fromCharCode(x);
+  return btoa(s);
+}
 function base64ToBytes(b64) {
   const s = atob(b64);
   const out = new Uint8Array(s.length);
@@ -5677,7 +5694,57 @@ function base64ToBytes(b64) {
   return out;
 }
 
+// src/team/recovery.ts
+var PAPER_DOC_ID = "recovery-paper";
+async function loadPaperRecoveryEntries(store, vault) {
+  const env = await store.get(vault, "_meta", PAPER_DOC_ID);
+  if (!env) return [];
+  try {
+    const doc = JSON.parse(env._data);
+    if (doc.profile !== "paper" || !Array.isArray(doc.entries)) return [];
+    return doc.entries;
+  } catch {
+    return [];
+  }
+}
+async function savePaperRecoveryEntries(store, vault, entries) {
+  const doc = {
+    _noydb_recovery: 1,
+    profile: "paper",
+    entries
+  };
+  const envelope = {
+    _noydb: NOYDB_FORMAT_VERSION,
+    _v: 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    _iv: "",
+    _data: JSON.stringify(doc)
+  };
+  await store.put(vault, "_meta", PAPER_DOC_ID, envelope);
+}
+async function burnPaperRecoveryEntry(store, vault, codeId) {
+  const entries = await loadPaperRecoveryEntries(store, vault);
+  const remaining = entries.filter((e) => e.codeId !== codeId);
+  await savePaperRecoveryEntries(store, vault, remaining);
+}
+async function hasRecoveryEnrolled(store, vault) {
+  const paper = await loadPaperRecoveryEntries(store, vault);
+  return paper.length > 0;
+}
+async function mintPaperRecoveryEntry(deks, code, codeId) {
+  const blob = await mintWrappedDeksBlob(deks, code);
+  return {
+    ...blob,
+    codeId,
+    enrolledAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function unwrapDeksFromPaperEntry(entry, code) {
+  return unwrapDeksFromBlob(entry, code);
+}
+
 // src/team/rotate-recover.ts
+init_errors();
 async function rotatePassphrase(store, vault, userId, input) {
   if (!input.allowWeakPassphrase) {
     assertStrongPassphrase(input.newPassphrase, input.passphrasePolicy);
@@ -5699,14 +5766,53 @@ async function rotatePassphrase(store, vault, userId, input) {
   for (const [coll, dek] of deks) {
     wrappedDeks[coll] = await wrapKey(dek, newKek);
   }
+  const oldSlots = file.authenticators ?? [];
+  const newSlots = [];
+  if (input.slotCeremonies && oldSlots.length > 0) {
+    for (const oldSlot of oldSlots) {
+      const ceremony = input.slotCeremonies[oldSlot.id];
+      if (!ceremony) continue;
+      const result = await ceremony({ newKek, newDeks: deks, oldSlot });
+      if (result.id !== oldSlot.id) {
+        throw new ValidationError(
+          `slotCeremonies['${oldSlot.id}'] returned id="${result.id}". The id must match the rotated slot \u2014 a ceremony cannot change a slot's identity.`
+        );
+      }
+      if (result.method !== oldSlot.method) {
+        throw new ValidationError(
+          `slotCeremonies['${oldSlot.id}'] returned method="${result.method}", expected "${oldSlot.method}". The method must match the rotated slot \u2014 a ceremony cannot change the auth method (e.g. webauthn \u2192 password) under cover of rotation.`
+        );
+      }
+      const baseFields = {
+        id: result.id,
+        method: result.method,
+        // Preserve original enrolled_at — rotation is rewrapping, not
+        // re-enrollment. The slot's enrolment timestamp tracks when
+        // the user originally added the slot, not when it was last
+        // rewrapped. Forensics consumers reading enrolled_at are
+        // tracking the slot's ORIGIN, not its CURRENT wrapping.
+        enrolled_at: oldSlot.enrolled_at,
+        enrolled_via_tier: result.enrolled_via_tier ?? oldSlot.enrolled_via_tier,
+        meta: result.meta
+      };
+      const newSlot = result.wrapKind === "deks" ? {
+        ...baseFields,
+        wrapKind: "deks",
+        wrapped_deks: result.wrapped_deks,
+        iv: result.iv
+      } : {
+        ...baseFields,
+        wrapped_kek: result.wrapped_kek
+      };
+      newSlots.push(newSlot);
+    }
+  }
   const next = {
     ...file,
     _noydb_keyring: NOYDB_KEYRING_VERSION,
     deks: wrappedDeks,
     salt: bufferToBase64(newSalt),
-    // Tier-2 slots reference the old KEK — drop them. User
-    // re-enrols afterwards via `db.enrollAuthenticator`.
-    authenticators: []
+    authenticators: newSlots
   };
   await writeKeyringFile2(store, vault, userId, next);
   return {
@@ -5717,7 +5823,7 @@ async function rotatePassphrase(store, vault, userId, input) {
     deks,
     kek: newKek,
     salt: newSalt,
-    authenticators: [],
+    authenticators: newSlots,
     ...file.export_capability !== void 0 && { exportCapability: file.export_capability },
     ...file.import_capability !== void 0 && { importCapability: file.import_capability }
   };
@@ -6195,8 +6301,76 @@ function sanitizeId(s) {
   return s.replace(/[^a-zA-Z0-9]/g, "_");
 }
 
+// src/team/peer-recover.ts
+init_types();
+init_crypto();
+init_errors();
+var ADMIN_RECOVERABLE_TARGETS = ["operator", "viewer", "client", "admin"];
+function canRecover(callerRole, targetRole) {
+  if (callerRole === "owner") return true;
+  if (callerRole === "admin") return ADMIN_RECOVERABLE_TARGETS.includes(targetRole);
+  return false;
+}
+async function recoverUser(store, vault, callerKeyring, options) {
+  const env = await store.get(vault, "_keyring", options.userId);
+  if (!env) {
+    throw new NoAccessError(
+      `recoverUser: user "${options.userId}" has no keyring in vault "${vault}".`
+    );
+  }
+  const target = JSON.parse(env._data);
+  const targetRole = options.role ?? target.role;
+  if (!canRecover(callerKeyring.role, targetRole)) {
+    throw new PermissionDeniedError(
+      `Role "${callerKeyring.role}" cannot recover role "${targetRole}"`
+    );
+  }
+  if (!canRecover(callerKeyring.role, target.role)) {
+    throw new PermissionDeniedError(
+      `Role "${callerKeyring.role}" cannot recover role "${target.role}"`
+    );
+  }
+  for (const coll of Object.keys(target.deks)) {
+    if (!callerKeyring.deks.has(coll)) {
+      throw new PrivilegeEscalationError(coll);
+    }
+  }
+  if (options.validatePassphrase && !options.allowWeakPassphrase) {
+    assertStrongPassphrase(options.passphrase, options.passphrasePolicy);
+  }
+  const newSalt = generateSalt();
+  const newKek = await deriveKey(options.passphrase, newSalt);
+  const wrappedDeks = {};
+  for (const coll of Object.keys(target.deks)) {
+    const callerDek = callerKeyring.deks.get(coll);
+    if (!callerDek) {
+      throw new PrivilegeEscalationError(coll);
+    }
+    wrappedDeks[coll] = await wrapKey(callerDek, newKek);
+  }
+  const next = {
+    ...target,
+    _noydb_keyring: NOYDB_KEYRING_VERSION,
+    role: targetRole,
+    display_name: options.displayName ?? target.display_name,
+    deks: wrappedDeks,
+    salt: bufferToBase64(newSalt),
+    granted_by: callerKeyring.userId,
+    authenticators: []
+  };
+  const envelope = {
+    _noydb: 1,
+    _v: 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    _iv: "",
+    _data: JSON.stringify(next)
+  };
+  await store.put(vault, "_keyring", options.userId, envelope);
+}
+
 // src/noydb.ts
 init_errors();
+init_ulid();
 init_public_envelope();
 
 // src/vault.ts
@@ -12463,6 +12637,11 @@ var Vault = class {
    */
   async delegate(opts) {
     const { issueDelegation: issueDelegation2, DELEGATIONS_COLLECTION: DELEGATIONS_COLLECTION2 } = await Promise.resolve().then(() => (init_delegation(), delegation_exports));
+    if (!this.keyring.kek) {
+      throw new ValidationError(
+        "issueDelegation: keyring.kek is null \u2014 issuing a delegation requires a tier-1 unlock. Re-authenticate at tier 1 (passphrase) first."
+      );
+    }
     const targetKek = this.keyring.kek;
     const delegationsDek = await this.getDEK(DELEGATIONS_COLLECTION2);
     return issueDelegation2(
@@ -13453,7 +13632,23 @@ var PERSONAL_POLICY = Object.freeze({
   gates: {
     "rotate-passphrase": {
       minTier: 1,
-      factors: [{ anyOf: ["totp", "email-otp", "recovery"] }]
+      // Any second factor satisfies the gate — off-device kinds (TOTP,
+      // email-OTP, paper recovery, roaming WebAuthn) are the strongest;
+      // platform-bound kinds (platform WebAuthn, password, PIN) are
+      // accepted because requiring "something off-device" is overkill
+      // for personal/SMB threat models. Consumers needing the off-device
+      // guarantee should use STRICT_POLICY or override this gate.
+      factors: [{
+        anyOf: [
+          "totp",
+          "email-otp",
+          "recovery",
+          "webauthn-roaming",
+          "webauthn-platform",
+          "password",
+          "pin"
+        ]
+      }]
     },
     "recover-passphrase": {
       minTier: 1,
@@ -13464,6 +13659,12 @@ var PERSONAL_POLICY = Object.freeze({
     "rotate-unlock": { minTier: 2 },
     "enroll-user": { minTier: 1 },
     "revoke-user": { minTier: 1 },
+    // Peer-recovery is a high-trust intentional op — co-owners
+    // recovering each other should not need an off-device factor in
+    // the personal/SMB threat model (the partner is already vetted by
+    // virtue of being a co-owner). Tier-1 unlock is the floor; the
+    // STRICT preset adds a recovery/email-OTP requirement.
+    "peer-recover-user": { minTier: 1 },
     "export-bundle": { minTier: 1 },
     "export-plaintext": {
       minTier: 1,
@@ -13517,6 +13718,19 @@ var STRICT_POLICY = Object.freeze({
       minTier: 1,
       factors: [{ anyOf: ["totp", "email-otp"] }]
     },
+    // STRICT peer-recovery: the issuer must present a recovery code
+    // OR a fresh off-device second factor at the moment of recovery.
+    // This binds the high-trust operation to a verifiable proof
+    // (recovery sheet photographed by an attacker won't suffice —
+    // they'd also need tier-1 unlock first; this gate is the freshness
+    // binding on top). Roaming WebAuthn (YubiKey-class hardware key)
+    // accepted; platform-bound kinds (Touch ID, password, PIN)
+    // intentionally excluded under STRICT because they don't survive
+    // device theft — the off-device requirement is the whole point.
+    "peer-recover-user": {
+      minTier: 1,
+      factors: [{ anyOf: ["recovery", "totp", "email-otp", "webauthn-roaming"] }]
+    },
     "export-bundle": {
       minTier: 1,
       factors: [{ anyOf: ["totp", "email-otp"] }],
@@ -14663,22 +14877,108 @@ var Noydb = class {
   async recoverPassphrase(vault, input, factors) {
     await this.checkGate(vault, "recover-passphrase", factors);
     const userId = this.options.user;
+    const entriesBeforeRecovery = await loadPaperRecoveryEntries(this.options.store, vault);
     const next = await recoverPassphrase(this.options.store, vault, userId, input);
     this.keyringCache.set(vault, next);
+    const rotateRemaining = input.rotateRemainingCodes ?? true;
+    const remainingAfterBurn = Math.max(0, entriesBeforeRecovery.length - 1);
+    if (!rotateRemaining || remainingAfterBurn === 0) {
+      return { newCodes: [] };
+    }
+    const codeGen = input.codeGenerator ?? generateULID;
+    const newCodeCount = input.newCodeCount ?? remainingAfterBurn;
+    const codes = [];
+    const newEntries = [];
+    for (let i = 0; i < newCodeCount; i++) {
+      const rawCode = codeGen();
+      const entry = await mintPaperRecoveryEntry(next.deks, rawCode, generateULID());
+      codes.push(rawCode);
+      newEntries.push(entry);
+    }
+    await savePaperRecoveryEntries(this.options.store, vault, newEntries);
+    return { newCodes: codes };
+  }
+  /**
+   * Atomic peer-recovery — re-wraps an EXISTING user's keyring under
+   * a fresh temp passphrase in a single store write. Closes #34's
+   * partial-failure window (the previous compose-from-primitives
+   * pattern was `db.revoke + db.grant`, two writes — if the issuer
+   * cancelled between them the target was locked out entirely).
+   *
+   * Different from `db.revoke + db.grant`:
+   *
+   *   - Same `userId`, role, permissions, capabilities preserved.
+   *   - DEKs unchanged → every other principal in the vault keeps
+   *     access. No key rotation.
+   *   - Allows owner→owner natively (#33). The existing
+   *     `db.revoke` retains its block — peer-recovery is a separate,
+   *     intentionally-named operation.
+   *   - Tier-2 slots dropped (they wrap the old KEK).
+   *
+   * Gated by `peer-recover-user`; `STRICT_POLICY` requires a
+   * recovery / TOTP / email-OTP factor proof at the moment of
+   * recovery, so the issuer affirmatively re-asserts identity.
+   *
+   * The recipient should call `db.rotatePassphrase` on first session
+   * to choose their own phrase — the temp acts as a single-use
+   * bridge.
+   *
+   * ```ts
+   * await db.recoverUser('acme', {
+   *   userId: 'bob',
+   *   passphrase: 'temporary-correct-horse-battery-staple-printer',
+   * }, { factors: [{ kind: 'recovery' }] })
+   * // Bob opens createNoydb({ user: 'bob', secret: tempPhrase })
+   * // and immediately calls db.rotatePassphrase to set his own.
+   * ```
+   *
+   * @throws `NoAccessError` when no keyring exists for the target.
+   * @throws `PermissionDeniedError` when the caller's role can't
+   *         recover the target's role (admin→owner is blocked even
+   *         under recovery).
+   * @throws `PrivilegeEscalationError` when the caller lacks a DEK
+   *         the target previously had access to.
+   *
+   * @see #33 #34 — the issues this method closes.
+   */
+  async recoverUser(vault, options, factors) {
+    await this.checkGate(vault, "peer-recover-user", factors);
+    const callerKeyring = await this.getKeyring(vault);
+    await recoverUser(this.options.store, vault, callerKeyring, options);
+    if (options.userId === this.options.user) {
+      this.keyringCache.delete(vault);
+    }
   }
   /**
    * Persist a recovery enrollment. v0.1.0-pre.5 accepts the `'paper'`
-   * profile — the developer first calls
-   * `@noy-db/on-recovery/generateRecoveryCodeSet` to mint codes +
-   * entries, shows the codes to the user once, then hands the entries
-   * here.
+   * profile.
+   *
+   * The hub wraps the user's DEK set (not the KEK) under a code-derived
+   * AES-GCM key — see `team/recovery.ts` for the rationale. The mint
+   * helper {@link mintPaperRecoveryEntry} is the canonical primitive;
+   * pair it with `db.getKeyring(vault)` to obtain the live DEK set:
    *
    * ```ts
-   * import { generateRecoveryCodeSet } from '@noy-db/on-recovery'
-   * const { codes, entries } = await generateRecoveryCodeSet({ kek, count: 10 })
+   * import { mintPaperRecoveryEntry } from '@noy-db/hub'
+   *
+   * const keyring = await db.getKeyring('acme')
+   * const codes: string[] = ['CORRECT-HORSE-1', 'BATTERY-STAPLE-2', ...]
+   * const entries = await Promise.all(
+   *   codes.map((code, i) => mintPaperRecoveryEntry(keyring.deks, code, `code-${i}`)),
+   * )
    * await db.enrollRecovery('acme', { profile: 'paper', entries })
    * showCodesToUser(codes)
    * ```
+   *
+   * As of pre.8, `@noy-db/on-recovery`'s `generateRecoveryCodeSet`
+   * delegates to `mintPaperRecoveryEntry` internally — its output is
+   * fed directly to this API. Pick whichever fits your code-gen layer:
+   *
+   * ```ts
+   * import { generateRecoveryCodeSet } from '@noy-db/on-recovery'
+   * const { codes, entries } = await generateRecoveryCodeSet({ deks: keyring.deks, count: 8 })
+   * await db.enrollRecovery('acme', { profile: 'paper', entries })
+   * ```
    */
   async enrollRecovery(vault, enrollment) {
     if (enrollment.profile !== "paper") {
@@ -14732,7 +15032,29 @@ var Noydb = class {
   clearQuickUnlock(vault) {
     this.quickUnlock.delete(vault);
   }
-  /** Get or load the keyring for a vault. */
+  /**
+   * Public accessor for the unlocked keyring of a vault — issue #28.
+   *
+   * Returns the cached `UnlockedKeyring` (already in memory after
+   * `createNoydb` + first vault touch); loads it on demand if absent.
+   * Used by `@noy-db/on-*` ceremonies that need the live DEK set
+   * (paper recovery via {@link mintPaperRecoveryEntry}, tier-3 PIN
+   * enrolment via on-pin's `enrollPin`, custom on-* ceremonies that
+   * don't have a hub-side wrapper).
+   *
+   * No new permission gate — this is an accessor over already-unlocked
+   * state. The keyring is materialized only after the calling session
+   * has unlocked the vault at tier 1, 2, or 3, so exposing it does not
+   * widen access. Throws `ValidationError` when encryption is enabled
+   * and no `secret` / `getKeyring` is configured.
+   *
+   * ```ts
+   * const keyring = await db.getKeyring('acme')
+   * // keyring.deks: Map<collection, CryptoKey>
+   * // keyring.kek:  CryptoKey   (non-extractable; null for tier-3 sessions)
+   * // keyring.role / .permissions / .authenticators
+   * ```
+   */
   async getKeyring(vault) {
     if (this.options.encrypt === false) {
       return createPlaintextKeyring(this.options.user);
@@ -16655,6 +16977,8 @@ function shortJSON(value) {
   mergeCrdtStates,
   mergePolicy,
   min,
+  mintPaperRecoveryEntry,
+  mintWrappedDeksBlob,
   paddedIndex,
   parseBytes,
   parseIndex,
@@ -16665,6 +16989,7 @@ function shortJSON(value) {
   readNoydbBundlePublicEnvelope,
   readPath,
   readPublicEnvelope,
+  recoverUser,
   reduceRecords,
   ref,
   removeAuthenticator,
@@ -16686,6 +17011,8 @@ function shortJSON(value) {
   saveVaultPolicy,
   sha256Hex,
   sum,
+  unwrapDeksFromBlob,
+  unwrapDeksFromPaperEntry,
   unwrapMagicLinkGrant,
   validateI18nTextValue,
   validatePassphrase,