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

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   issueDelegation,
   loadActiveDelegations,
   revokeDelegation
-} from "./chunk-XCL3WP6J.js";
+} from "./chunk-SCZXXXU4.js";
 import {
   LazyQuery,
   decodeIdxId,
@@ -31,7 +31,7 @@ import {
   readNoydbBundlePublicEnvelope,
   resetBrotliSupportCache,
   writeNoydbBundle
-} from "./chunk-FAAWLVTF.js";
+} from "./chunk-WN6UK7PM.js";
 import {
   PUBLIC_ENVELOPE_RECORD_ID,
   isPublicEnvelope,
@@ -39,13 +39,13 @@ import {
   readPublicEnvelope,
   savePublicEnvelope,
   validatePublicEnvelopeInput
-} from "./chunk-GILMPJXB.js";
+} from "./chunk-RSPLI376.js";
 import {
   CONSENT_AUDIT_COLLECTION
 } from "./chunk-M62XNWRA.js";
 import {
   PERIODS_COLLECTION
-} from "./chunk-3WCRU7TI.js";
+} from "./chunk-7XBQS42M.js";
 import "./chunk-UF3BUNQZ.js";
 import {
   CollectionFrame,
@@ -69,7 +69,7 @@ import {
   isI18nTextDescriptor,
   resolveI18nText,
   validateI18nTextValue
-} from "./chunk-NZ4XCIKS.js";
+} from "./chunk-2WGMYBYS.js";
 import {
   createBundleStore,
   routeStore,
@@ -89,12 +89,12 @@ import {
   getCredential,
   listCredentials,
   putCredential
-} from "./chunk-INSJBB5W.js";
+} from "./chunk-TOQK4KAN.js";
 import {
   PresenceHandle,
   SyncEngine,
   SyncTransaction
-} from "./chunk-CL37QSND.js";
+} from "./chunk-HC7Z5EQZ.js";
 import {
   USER_ENVELOPE_COLLECTION,
   USER_ENVELOPE_MAX_BYTES,
@@ -124,7 +124,7 @@ import {
   rotateKeys,
   saveUserEnvelope,
   validatePassphrase
-} from "./chunk-6IJQ27XN.js";
+} from "./chunk-YVFTBQHL.js";
 import {
   BUNDLE_STORE_POLICY,
   INDEXED_STORE_POLICY,
@@ -144,7 +144,7 @@ import {
   revokeAllSessions,
   revokeSession,
   validateSessionPolicy
-} from "./chunk-UFL4DUEV.js";
+} from "./chunk-VQBTTTUN.js";
 import {
   generateULID,
   isULID
@@ -161,7 +161,7 @@ import {
   LedgerStore,
   applyPatch,
   computePatch
-} from "./chunk-N2LMZKLR.js";
+} from "./chunk-Y4CMTMUW.js";
 import {
   canonicalJson,
   envelopePayloadHash,
@@ -216,14 +216,14 @@ import {
   detectMimeType,
   isPreCompressed,
   runCompaction
-} from "./chunk-KPF2HHPI.js";
+} from "./chunk-R2ZTGEVP.js";
 import {
   NOYDB_BACKUP_VERSION,
   NOYDB_FORMAT_VERSION,
   NOYDB_KEYRING_VERSION,
   NOYDB_SYNC_VERSION,
   createStore
-} from "./chunk-B6HF6NTZ.js";
+} from "./chunk-PJK6IOBC.js";
 import {
   base64ToBuffer,
   bufferToBase64,
@@ -434,14 +434,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;
@@ -545,51 +553,38 @@ var RecoveryProfileNotImplementedError = class extends NoydbError {
   }
 };
 
-// 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 [];
+// src/team/wrapped-deks.ts
+var PBKDF2_ITERATIONS = 6e5;
+var SALT_BYTES = 32;
+var IV_BYTES = 12;
+var subtle = globalThis.crypto.subtle;
+async function mintWrappedDeksBlob(deks, credential) {
+  const salt = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  const wrappingKey = await deriveWrappingKey(credential, salt);
+  const exported = {};
+  for (const [coll, dek] of deks) {
+    const raw = await subtle.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 subtle.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 subtle = 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 subtle.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();
@@ -606,10 +601,10 @@ async function unwrapDeksFromPaperEntry(entry, code) {
   }
   return deks;
 }
-async function deriveRecoveryWrappingKey(code, salt) {
+async function deriveWrappingKey(credential, salt) {
   const ikm = await subtle.importKey(
     "raw",
-    new TextEncoder().encode(code),
+    new TextEncoder().encode(credential),
     "PBKDF2",
     false,
     ["deriveKey"]
@@ -618,7 +613,7 @@ async function deriveRecoveryWrappingKey(code, salt) {
     {
       name: "PBKDF2",
       salt,
-      iterations: RECOVERY_PBKDF2_ITERATIONS,
+      iterations: PBKDF2_ITERATIONS,
       hash: "SHA-256"
     },
     ikm,
@@ -627,6 +622,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);
@@ -634,6 +634,55 @@ 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
 async function rotatePassphrase(store, vault, userId, input) {
   if (!input.allowWeakPassphrase) {
@@ -656,14 +705,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 writeKeyringFile(store, vault, userId, next);
   return {
@@ -674,7 +762,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 }
   };
@@ -1148,6 +1236,70 @@ function sanitizeId(s) {
   return s.replace(/[^a-zA-Z0-9]/g, "_");
 }
 
+// src/team/peer-recover.ts
+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/crdt/strategy.ts
 var NOT_ENABLED = new Error(
   'CRDT mode requires the CRDT strategy. Import `{ withCrdt }` from "@noy-db/hub/crdt" and pass it to `createNoydb({ crdtStrategy: withCrdt() })`.'
@@ -4804,7 +4956,12 @@ var Vault = class {
    * collection.
    */
   async delegate(opts) {
-    const { issueDelegation: issueDelegation2, DELEGATIONS_COLLECTION: DELEGATIONS_COLLECTION2 } = await import("./delegation-XDJCBTI2.js");
+    const { issueDelegation: issueDelegation2, DELEGATIONS_COLLECTION: DELEGATIONS_COLLECTION2 } = await import("./delegation-2DBS2EOH.js");
+    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(
@@ -4821,7 +4978,7 @@ var Vault = class {
    * if the id does not exist.
    */
   async revokeDelegation(id) {
-    const { revokeDelegation: revokeDelegation2, DELEGATIONS_COLLECTION: DELEGATIONS_COLLECTION2 } = await import("./delegation-XDJCBTI2.js");
+    const { revokeDelegation: revokeDelegation2, DELEGATIONS_COLLECTION: DELEGATIONS_COLLECTION2 } = await import("./delegation-2DBS2EOH.js");
     await revokeDelegation2(this.adapter, this.name, id);
     void DELEGATIONS_COLLECTION2;
   }
@@ -5221,7 +5378,7 @@ var Vault = class {
    * @see docs/subsystems/public-envelope.md
    */
   async getPublicEnvelope(opts = {}) {
-    const { readPublicEnvelope: readPublicEnvelope2 } = await import("./public-envelope-DFJZHXVH.js");
+    const { readPublicEnvelope: readPublicEnvelope2 } = await import("./public-envelope-3QTQADDW.js");
     return readPublicEnvelope2(this.adapter, this.name, opts);
   }
   /**
@@ -5795,7 +5952,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,
@@ -5806,6 +5979,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,
@@ -5859,6 +6038,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"] }],
@@ -7005,22 +7197,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") {
@@ -7074,7 +7352,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);
@@ -7503,6 +7803,8 @@ export {
   mergeCrdtStates,
   mergePolicy,
   min,
+  mintPaperRecoveryEntry,
+  mintWrappedDeksBlob,
   paddedIndex,
   parseBytes,
   parseIndex,
@@ -7513,6 +7815,7 @@ export {
   readNoydbBundlePublicEnvelope,
   readPath,
   readPublicEnvelope,
+  recoverUser,
   reduceRecords,
   ref,
   removeAuthenticator,
@@ -7534,6 +7837,8 @@ export {
   saveVaultPolicy,
   sha256Hex,
   sum,
+  unwrapDeksFromBlob,
+  unwrapDeksFromPaperEntry,
   unwrapMagicLinkGrant,
   validateI18nTextValue,
   validatePassphrase,