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

package/dist/index.js

@@ -1,3 +1,8 @@
+import {
+  DEFAULT_PUBLIC_ENVELOPE_SCHEMA,
+  PUBLIC_ENVELOPE_FIELDS,
+  resolveSchema
+} from "./chunk-EMIGCR7X.js";
 import {
   DELEGATIONS_COLLECTION,
   assertTierAccess,
@@ -23,15 +28,24 @@ import {
   hasNoydbBundleMagic,
   readNoydbBundle,
   readNoydbBundleHeader,
+  readNoydbBundlePublicEnvelope,
   resetBrotliSupportCache,
   writeNoydbBundle
-} from "./chunk-GJILMRPO.js";
+} from "./chunk-FAAWLVTF.js";
+import {
+  PUBLIC_ENVELOPE_RECORD_ID,
+  isPublicEnvelope,
+  loadPublicEnvelope,
+  readPublicEnvelope,
+  savePublicEnvelope,
+  validatePublicEnvelopeInput
+} from "./chunk-GILMPJXB.js";
 import {
   CONSENT_AUDIT_COLLECTION
 } from "./chunk-M62XNWRA.js";
 import {
   PERIODS_COLLECTION
-} from "./chunk-LSZHBNDG.js";
+} from "./chunk-3WCRU7TI.js";
 import "./chunk-UF3BUNQZ.js";
 import {
   CollectionFrame,
@@ -55,7 +69,7 @@ import {
   isI18nTextDescriptor,
   resolveI18nText,
   validateI18nTextValue
-} from "./chunk-EARQCIL7.js";
+} from "./chunk-NZ4XCIKS.js";
 import {
   createBundleStore,
   routeStore,
@@ -75,17 +89,24 @@ import {
   getCredential,
   listCredentials,
   putCredential
-} from "./chunk-L77MEFCH.js";
+} from "./chunk-INSJBB5W.js";
 import {
   PresenceHandle,
   SyncEngine,
   SyncTransaction
-} from "./chunk-AVWFLPNR.js";
+} from "./chunk-CL37QSND.js";
 import {
+  USER_ENVELOPE_COLLECTION,
+  USER_ENVELOPE_MAX_BYTES,
+  UserEnvelopeOversizedError,
+  WeakPassphraseError,
+  assertStrongPassphrase,
   buildRecipientKeyringFile,
   changeSecret,
   createOwnerKeyring,
+  deleteUserEnvelope,
   ensureCollectionDEK,
+  estimateEntropy,
   evaluateExportCapability,
   evaluateImportCapability,
   grant,
@@ -93,11 +114,17 @@ import {
   hasExportCapability,
   hasImportCapability,
   hasWritePermission,
+  listUserEnvelopeIds,
   listUsers,
+  listUsersWithEnvelopes,
   loadKeyring,
+  loadUserEnvelope,
+  persistKeyring,
   revoke,
-  rotateKeys
-} from "./chunk-PSHTHSIX.js";
+  rotateKeys,
+  saveUserEnvelope,
+  validatePassphrase
+} from "./chunk-6IJQ27XN.js";
 import {
   BUNDLE_STORE_POLICY,
   INDEXED_STORE_POLICY,
@@ -117,7 +144,7 @@ import {
   revokeAllSessions,
   revokeSession,
   validateSessionPolicy
-} from "./chunk-E445ICYI.js";
+} from "./chunk-UFL4DUEV.js";
 import {
   generateULID,
   isULID
@@ -134,7 +161,7 @@ import {
   LedgerStore,
   applyPatch,
   computePatch
-} from "./chunk-NK2NSXXK.js";
+} from "./chunk-N2LMZKLR.js";
 import {
   canonicalJson,
   envelopePayloadHash,
@@ -189,24 +216,26 @@ import {
   detectMimeType,
   isPreCompressed,
   runCompaction
-} from "./chunk-QZIACZZU.js";
+} from "./chunk-KPF2HHPI.js";
 import {
   NOYDB_BACKUP_VERSION,
   NOYDB_FORMAT_VERSION,
   NOYDB_KEYRING_VERSION,
   NOYDB_SYNC_VERSION,
   createStore
-} from "./chunk-O5GK62FJ.js";
+} from "./chunk-B6HF6NTZ.js";
 import {
   base64ToBuffer,
   bufferToBase64,
   decrypt,
   decryptBytes,
   decryptDeterministic,
+  deriveKey,
   derivePresenceKey,
   encrypt,
   encryptBytes,
   encryptDeterministic,
+  generateSalt,
   unwrapKey,
   wrapKey
 } from "./chunk-MR4424N3.js";
@@ -397,6 +426,728 @@ var RefRegistry = class {
   }
 };
 
+// src/team/authenticators.ts
+async function enrollAuthenticator(store, vault, keyring, options) {
+  const existing = keyring.authenticators.find((a) => a.id === options.id);
+  if (existing) {
+    throw new ValidationError(
+      `enrollAuthenticator: slot id "${options.id}" already exists in vault "${vault}". Remove the slot first or pick a unique id.`
+    );
+  }
+  const slot = {
+    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 next = appendSlot(keyring, slot);
+  await persistKeyring(store, vault, next);
+  return next;
+}
+async function removeAuthenticator(store, vault, keyring, slotId) {
+  const filtered = keyring.authenticators.filter((a) => a.id !== slotId);
+  if (filtered.length === keyring.authenticators.length) {
+    return keyring;
+  }
+  const next = {
+    ...keyring,
+    authenticators: filtered
+  };
+  await persistKeyring(store, vault, next);
+  return next;
+}
+function findAuthenticator(keyring, slotId) {
+  return keyring.authenticators.find((a) => a.id === slotId);
+}
+function appendSlot(keyring, slot) {
+  return {
+    ...keyring,
+    authenticators: [...keyring.authenticators, slot]
+  };
+}
+
+// src/session/unlock-state.ts
+var QuickUnlockStore = class {
+  states = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  /**
+   * Register a quick-unlock state for a vault. Replaces any existing
+   * state. Schedules an automatic clear when the state's `expiresAt`
+   * elapses.
+   */
+  set(vault, state) {
+    this.clearTimer(vault);
+    this.states.set(vault, state);
+    const ttl = new Date(state.expiresAt).getTime() - Date.now();
+    if (ttl > 0) {
+      const timer = setTimeout(() => this.delete(vault), ttl);
+      this.timers.set(vault, timer);
+    }
+  }
+  /** Read the state for a vault. Returns undefined when none is registered. */
+  get(vault) {
+    return this.states.get(vault);
+  }
+  /** Drop the state for a vault. Cancels the auto-clear timer. */
+  delete(vault) {
+    this.clearTimer(vault);
+    this.states.delete(vault);
+  }
+  /** Drop every cached state. Called on `db.close()`. */
+  clear() {
+    for (const vault of this.states.keys()) {
+      this.clearTimer(vault);
+    }
+    this.states.clear();
+  }
+  clearTimer(vault) {
+    const t = this.timers.get(vault);
+    if (t) clearTimeout(t);
+    this.timers.delete(vault);
+  }
+};
+
+// src/policy/errors.ts
+var PolicyDeniedError = class extends NoydbError {
+  gate;
+  reason;
+  required;
+  constructor(gate, reason, required, message) {
+    super(
+      "POLICY_DENIED",
+      message ?? `Gate "${gate}" denied: ${reason}.`
+    );
+    this.name = "PolicyDeniedError";
+    this.gate = gate;
+    this.reason = reason;
+    this.required = required;
+  }
+};
+var RecoveryNotEnrolledError = class extends NoydbError {
+  constructor(message = 'Recovery profile not enrolled. Pass `recovery: [{ profile: "paper", codes: 10 }]` to `createNoydb()`, or set `policy.gates["recover-passphrase"].enabled = false` to opt out of recovery (passphrase loss = data loss). See docs/subsystems/session-tiers.md.') {
+    super("RECOVERY_NOT_ENROLLED", message);
+    this.name = "RecoveryNotEnrolledError";
+  }
+};
+var RecoveryProfileNotImplementedError = class extends NoydbError {
+  profile;
+  tracking;
+  constructor(profile, tracking) {
+    super(
+      "RECOVERY_PROFILE_NOT_IMPLEMENTED",
+      `Recovery profile "${profile}" is not yet implemented in this hub release. Tracking: ${tracking}. Use the "paper" profile via @noy-db/on-recovery in the meantime.`
+    );
+    this.name = "RecoveryProfileNotImplementedError";
+    this.profile = profile;
+    this.tracking = tracking;
+  }
+};
+
+// 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;
+}
+var subtle = globalThis.crypto.subtle;
+var RECOVERY_PBKDF2_ITERATIONS = 6e5;
+async function unwrapDeksFromPaperEntry(entry, code) {
+  const wrappingKey = await deriveRecoveryWrappingKey(code, base64ToBytes(entry.salt));
+  const plaintext = await subtle.decrypt(
+    { name: "AES-GCM", iv: base64ToBytes(entry.iv) },
+    wrappingKey,
+    base64ToBytes(entry.wrappedDeks)
+  );
+  const parsed = JSON.parse(new TextDecoder().decode(plaintext));
+  const deks = /* @__PURE__ */ new Map();
+  for (const [coll, b64] of Object.entries(parsed.deks)) {
+    const raw = base64ToBytes(b64);
+    const key = await subtle.importKey(
+      "raw",
+      raw,
+      { name: "AES-GCM", length: 256 },
+      true,
+      ["encrypt", "decrypt"]
+    );
+    deks.set(coll, key);
+  }
+  return deks;
+}
+async function deriveRecoveryWrappingKey(code, salt) {
+  const ikm = await subtle.importKey(
+    "raw",
+    new TextEncoder().encode(code),
+    "PBKDF2",
+    false,
+    ["deriveKey"]
+  );
+  return subtle.deriveKey(
+    {
+      name: "PBKDF2",
+      salt,
+      iterations: RECOVERY_PBKDF2_ITERATIONS,
+      hash: "SHA-256"
+    },
+    ikm,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+function base64ToBytes(b64) {
+  const s = atob(b64);
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+
+// src/team/rotate-recover.ts
+async function rotatePassphrase(store, vault, userId, input) {
+  if (!input.allowWeakPassphrase) {
+    assertStrongPassphrase(input.newPassphrase, input.passphrasePolicy);
+  }
+  const env = await store.get(vault, "_keyring", userId);
+  if (!env) {
+    throw new NoAccessError(`No keyring found for user "${userId}" in vault "${vault}".`);
+  }
+  const file = JSON.parse(env._data);
+  const oldSalt = base64ToBuffer(file.salt);
+  const oldKek = await deriveKey(input.oldPassphrase, oldSalt);
+  const deks = /* @__PURE__ */ new Map();
+  for (const [coll, wrapped] of Object.entries(file.deks)) {
+    deks.set(coll, await unwrapKey(wrapped, oldKek));
+  }
+  const newSalt = generateSalt();
+  const newKek = await deriveKey(input.newPassphrase, newSalt);
+  const wrappedDeks = {};
+  for (const [coll, dek] of deks) {
+    wrappedDeks[coll] = await wrapKey(dek, newKek);
+  }
+  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: []
+  };
+  await writeKeyringFile(store, vault, userId, next);
+  return {
+    userId: file.user_id,
+    displayName: file.display_name,
+    role: file.role,
+    permissions: file.permissions,
+    deks,
+    kek: newKek,
+    salt: newSalt,
+    authenticators: [],
+    ...file.export_capability !== void 0 && { exportCapability: file.export_capability },
+    ...file.import_capability !== void 0 && { importCapability: file.import_capability }
+  };
+}
+async function recoverPassphrase(store, vault, userId, input) {
+  if (!input.allowWeakPassphrase) {
+    assertStrongPassphrase(input.newPassphrase, input.passphrasePolicy);
+  }
+  switch (input.recoveryProof.profile) {
+    case "paper":
+      return recoverViaPaperCode(store, vault, userId, input);
+    case "shamir":
+      throw new RecoveryProfileNotImplementedError(
+        "shamir",
+        "https://github.com/vLannaAi/noy-db/issues/10"
+      );
+    case "multi-channel":
+      throw new RecoveryProfileNotImplementedError(
+        "multi-channel",
+        "https://github.com/vLannaAi/noy-db/issues/10"
+      );
+    case "admin-mediated":
+      throw new RecoveryProfileNotImplementedError(
+        "admin-mediated",
+        "https://github.com/vLannaAi/noy-db/issues/10"
+      );
+    default: {
+      const _exhaustive = input.recoveryProof;
+      throw new Error(`Unknown recovery profile: ${String(_exhaustive)}`);
+    }
+  }
+}
+async function recoverViaPaperCode(store, vault, userId, input) {
+  if (input.recoveryProof.profile !== "paper") throw new Error("unreachable");
+  const { code } = input.recoveryProof.payload;
+  const env = await store.get(vault, "_keyring", userId);
+  if (!env) {
+    throw new NoAccessError(`No keyring found for user "${userId}" in vault "${vault}".`);
+  }
+  const file = JSON.parse(env._data);
+  const entries = await loadPaperRecoveryEntries(store, vault);
+  if (entries.length === 0) {
+    throw new NoAccessError(
+      `No paper-recovery entries enrolled for vault "${vault}". Enroll via \`db.enrollRecovery({ profile: "paper", entries })\` before relying on recovery.`
+    );
+  }
+  const normalized = normalizePaperCode(code);
+  let recovered;
+  for (const entry of entries) {
+    try {
+      const deks2 = await unwrapDeksFromPaperEntry(entry, normalized);
+      recovered = { deks: deks2, entry };
+      break;
+    } catch {
+    }
+  }
+  if (!recovered) {
+    throw new InvalidKeyError(
+      "Recovery code does not match any enrolled paper entry. The code may have been previously used (single-use) or typed incorrectly."
+    );
+  }
+  const deks = recovered.deks;
+  const newSalt = generateSalt();
+  const newKek = await deriveKey(input.newPassphrase, newSalt);
+  const wrappedDeks = {};
+  for (const [coll, dek] of deks) {
+    wrappedDeks[coll] = await wrapKey(dek, newKek);
+  }
+  const next = {
+    ...file,
+    _noydb_keyring: NOYDB_KEYRING_VERSION,
+    deks: wrappedDeks,
+    salt: bufferToBase64(newSalt),
+    authenticators: []
+    // tier-2 slots wrap old KEK, drop them
+  };
+  await writeKeyringFile(store, vault, userId, next);
+  await burnPaperRecoveryEntry(store, vault, recovered.entry.codeId);
+  return {
+    userId: file.user_id,
+    displayName: file.display_name,
+    role: file.role,
+    permissions: file.permissions,
+    deks,
+    kek: newKek,
+    salt: newSalt,
+    authenticators: [],
+    ...file.export_capability !== void 0 && { exportCapability: file.export_capability },
+    ...file.import_capability !== void 0 && { importCapability: file.import_capability }
+  };
+}
+function normalizePaperCode(input) {
+  return input.toUpperCase().replace(/[\s\-_]/g, "");
+}
+async function writeKeyringFile(store, vault, userId, file) {
+  const envelope = {
+    _noydb: 1,
+    _v: 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    _iv: "",
+    _data: JSON.stringify(file)
+  };
+  await store.put(vault, "_keyring", userId, envelope);
+}
+
+// src/meta/user-envelope/api.ts
+var UserApi = class {
+  constructor(adapter, vaultName, writerKeyringId, getDek, checkGate2) {
+    this.adapter = adapter;
+    this.vaultName = vaultName;
+    this.writerKeyringId = writerKeyringId;
+    this.getDek = getDek;
+    this.checkGate = checkGate2;
+  }
+  adapter;
+  vaultName;
+  writerKeyringId;
+  getDek;
+  checkGate;
+  /** keyringId → set of listeners. Wildcard '*' fires on every change. */
+  listeners = /* @__PURE__ */ new Map();
+  // ─── Write-self ──────────────────────────────────────────────────────
+  /** Read the writer's own envelope. Returns null if never written. */
+  async me() {
+    const dek = await this.getDek();
+    return loadUserEnvelope(this.adapter, this.vaultName, this.writerKeyringId, dek);
+  }
+  /**
+   * Deep-merge a partial patch into the writer's own envelope. Creates
+   * the envelope on first call. Optimistic-concurrency safe — a stale
+   * `_v` (parallel writer on another device) throws `ConflictError`.
+   *
+   * Gated by the `edit-own-profile` policy gate (default `minTier: 3`).
+   * Pass `presented` to satisfy tightened policies that require a
+   * factor proof (e.g. STRICT_POLICY's TOTP requirement).
+   */
+  async updateMe(patch, presented) {
+    if (this.checkGate) await this.checkGate("edit-own-profile", presented);
+    const dek = await this.getDek();
+    const current = await loadUserEnvelope(
+      this.adapter,
+      this.vaultName,
+      this.writerKeyringId,
+      dek
+    );
+    const merged = current ? deepMerge(current.data, patch) : patch;
+    const written = await saveUserEnvelope(
+      this.adapter,
+      this.vaultName,
+      this.writerKeyringId,
+      merged,
+      dek,
+      current?._v ?? 0
+    );
+    this.fireChange(this.writerKeyringId, written);
+    return written;
+  }
+  /**
+   * Replace the writer's own envelope with `payload`. Use sparingly —
+   * `updateMe` is the canonical mutation. No `expectedVersion` check;
+   * callers explicitly take last-write-wins semantics.
+   *
+   * Gated by `edit-own-profile`. See `updateMe` for `presented` usage.
+   */
+  async setMe(payload, presented) {
+    if (this.checkGate) await this.checkGate("edit-own-profile", presented);
+    const dek = await this.getDek();
+    const written = await saveUserEnvelope(
+      this.adapter,
+      this.vaultName,
+      this.writerKeyringId,
+      payload,
+      dek
+    );
+    this.fireChange(this.writerKeyringId, written);
+    return written;
+  }
+  // ─── Read-anyone ─────────────────────────────────────────────────────
+  /**
+   * Read another principal's envelope by their keyringId. Returns null
+   * if the principal exists but has no envelope yet, or if the
+   * keyringId does not exist at all.
+   *
+   * Gated by `view-team-profiles` (default `minTier: 2`) — but ONLY for
+   * cross-principal reads. Reading your own envelope (`keyringId ===
+   * self`) is never gated; that's just `me()` written long-form.
+   */
+  async get(keyringId, presented) {
+    if (this.checkGate && keyringId !== this.writerKeyringId) {
+      await this.checkGate("view-team-profiles", presented);
+    }
+    const dek = await this.getDek();
+    return loadUserEnvelope(this.adapter, this.vaultName, keyringId, dek);
+  }
+  /**
+   * Read every persisted envelope in the vault. Order is store-defined.
+   *
+   * Gated by `view-team-profiles`. Default policy (`minTier: 2`) lets
+   * any authenticated session read all envelopes. Two privacy-strict
+   * opt-outs:
+   *
+   *  - `view-team-profiles.enabled: false` → list() returns only the
+   *    caller's own envelope (silent self-fallback, no thrown error).
+   *  - `view-team-profiles.minTier: 1` + insufficient tier → throws
+   *    `PolicyDeniedError` with `reason: 'insufficient-tier'`. The
+   *    caller is expected to elevate, not silently degrade.
+   *
+   * The asymmetry is deliberate: `enabled: false` is a deliberate
+   * design choice ("nobody sees teammate profiles in this app");
+   * `insufficient-tier` is "you need to authenticate further". Different
+   * UX prompts for different intents.
+   */
+  async list(presented) {
+    if (this.checkGate) {
+      try {
+        await this.checkGate("view-team-profiles", presented);
+      } catch (err) {
+        if (err instanceof PolicyDeniedError && err.reason === "disabled") {
+          const me = await this.me();
+          return me ? [me] : [];
+        }
+        throw err;
+      }
+    }
+    const dek = await this.getDek();
+    const ids = await listUserEnvelopeIds(this.adapter, this.vaultName);
+    const envelopes = await Promise.all(
+      ids.map((id) => loadUserEnvelope(this.adapter, this.vaultName, id, dek))
+    );
+    return envelopes.filter((e) => e !== null);
+  }
+  // ─── Reactive ────────────────────────────────────────────────────────
+  /**
+   * Listen for changes to a specific keyringId's envelope. The callback
+   * fires synchronously after every successful local `updateMe` /
+   * `setMe` for that principal.
+   *
+   * Cross-instance changes (a teammate edits their profile on their
+   * device, the sync engine pulls the diff onto this device) will fire
+   * subscribers when the sync layer replays the write through this API.
+   * In v1, subscribers do NOT fire on raw store changes — wire your sync
+   * layer to call back through `vault.user.setMe` / `updateMe` if you
+   * need that.
+   *
+   * Pass keyringId `'*'` to fire on every change in the vault.
+   */
+  subscribe(keyringId, cb) {
+    let listeners = this.listeners.get(keyringId);
+    if (!listeners) {
+      listeners = /* @__PURE__ */ new Set();
+      this.listeners.set(keyringId, listeners);
+    }
+    const wrapped = cb;
+    listeners.add(wrapped);
+    return () => {
+      listeners?.delete(wrapped);
+      if (listeners && listeners.size === 0) {
+        this.listeners.delete(keyringId);
+      }
+    };
+  }
+  /**
+   * Reactive handle that caches the current value and re-reads on every
+   * change for the given keyringId. Convenient for framework bindings:
+   *
+   *   const live = vault.user.live<UserShape>(vault.userId)
+   *   live.subscribe(env => render(env?.data))
+   *
+   * Initial value is `null` until the first `current()` call materializes
+   * it via `vault.user.get()`. Call `stop()` when done to release the
+   * subscription.
+   */
+  live(keyringId) {
+    let value = null;
+    let primed = false;
+    const unsubscribe = this.subscribe(keyringId, (env) => {
+      value = env;
+    });
+    return {
+      current() {
+        if (!primed) {
+          primed = true;
+        }
+        return value;
+      },
+      subscribe: (cb) => this.subscribe(keyringId, cb),
+      stop: unsubscribe
+    };
+  }
+  // ─── Internal: change emission ───────────────────────────────────────
+  fireChange(keyringId, env) {
+    const targeted = this.listeners.get(keyringId);
+    if (targeted) for (const l of targeted) l(env);
+    const wildcard = this.listeners.get("*");
+    if (wildcard) for (const l of wildcard) l(env);
+  }
+};
+function deepMerge(source, patch) {
+  if (!isPlainObject(source) || !isPlainObject(patch)) {
+    return patch;
+  }
+  const out = { ...source };
+  for (const [key, patchVal] of Object.entries(patch)) {
+    const sourceVal = source[key];
+    if (isPlainObject(sourceVal) && isPlainObject(patchVal)) {
+      out[key] = deepMerge(sourceVal, patchVal);
+    } else {
+      out[key] = patchVal;
+    }
+  }
+  return out;
+}
+function isPlainObject(x) {
+  if (x === null || typeof x !== "object") return false;
+  if (Array.isArray(x)) return false;
+  const proto = Object.getPrototypeOf(x);
+  return proto === Object.prototype || proto === null;
+}
+
+// src/policy/storage.ts
+var META_COLLECTION = "_meta";
+var POLICY_RECORD_ID = "policy";
+async function loadVaultPolicy(store, vault) {
+  const envelope = await store.get(vault, META_COLLECTION, POLICY_RECORD_ID);
+  if (!envelope) return void 0;
+  try {
+    const parsed = JSON.parse(envelope._data);
+    if (!isVaultPolicy(parsed)) return void 0;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+async function saveVaultPolicy(store, vault, policy) {
+  const envelope = {
+    _noydb: NOYDB_FORMAT_VERSION,
+    _v: 1,
+    _ts: (/* @__PURE__ */ new Date()).toISOString(),
+    _iv: "",
+    _data: JSON.stringify(policy)
+  };
+  await store.put(vault, META_COLLECTION, POLICY_RECORD_ID, envelope);
+}
+function isVaultPolicy(x) {
+  if (x === null || typeof x !== "object") return false;
+  if (!("gates" in x)) return false;
+  const gates = x.gates;
+  return gates !== null && typeof gates === "object";
+}
+
+// src/auth-introspection/index.ts
+async function describeAuthConfig(store, vault) {
+  const policy = await loadVaultPolicy(store, vault) ?? defaultPolicySnapshot();
+  const recoveryProfiles = await listRecoveryProfilesEnrolled(store, vault);
+  const lines = [];
+  lines.push(`Vault "${vault}" \u2014 three-tier authentication`);
+  lines.push("");
+  lines.push("Tier 1 \u2014 Passphrase (master)");
+  lines.push(`  Phrase format: ${policy.passphrase?.minWords ?? 6}+ words, lowercase letters, \u2265${policy.passphrase?.minWordLength ?? 3} chars/word`);
+  lines.push("  Strength validator: enforced (override available for tests only)");
+  lines.push("");
+  lines.push("Tier 2 \u2014 Authenticate (daily login)");
+  lines.push("  Allowed methods: WebAuthn (passkey), OIDC, Password");
+  lines.push("  Slots per user: unlimited");
+  lines.push("");
+  lines.push("Tier 3 \u2014 Unlock (quick resume)");
+  lines.push("  Method: PIN (per-app configurable)");
+  lines.push("");
+  lines.push(`Recovery profiles enrolled: ${recoveryProfiles.length === 0 ? "none" : recoveryProfiles.join(", ")}`);
+  lines.push("Managed-passphrase mode: off (post-1.0)");
+  lines.push("");
+  lines.push("Sensitive-action gates:");
+  for (const [gate, gp] of Object.entries(policy.gates)) {
+    lines.push(`  ${gate} \u2014 ${describeGatePolicy(gp)}`);
+  }
+  return lines.join("\n");
+}
+async function diagramAuthConfig(store, vault) {
+  const policy = await loadVaultPolicy(store, vault) ?? defaultPolicySnapshot();
+  const lines = [];
+  lines.push("flowchart TB");
+  lines.push(`  vault["Vault: ${escapeMermaid(vault)}"]`);
+  lines.push('  tier1["Tier 1<br/>Passphrase"]');
+  lines.push('  tier2["Tier 2<br/>Multi-slot Authenticate"]');
+  lines.push('  tier3["Tier 3<br/>PIN / Quick-resume"]');
+  lines.push("  vault --> tier1");
+  lines.push("  tier1 --> tier2");
+  lines.push("  tier2 --> tier3");
+  for (const [gateName, gp] of Object.entries(policy.gates)) {
+    if (gp.enabled === false) continue;
+    const id = sanitizeId(gateName);
+    const label = `${gateName}<br/>tier \u2265 ${gp.minTier}`;
+    lines.push(`  ${id}["${escapeMermaid(label)}"]`);
+    const tierNode = gp.minTier === 1 ? "tier1" : gp.minTier === 2 ? "tier2" : "tier3";
+    lines.push(`  ${tierNode} --> ${id}`);
+  }
+  return lines.join("\n");
+}
+async function describeUserAuth(store, vault, userId) {
+  const env = await store.get(vault, "_keyring", userId);
+  if (!env) return "";
+  const file = JSON.parse(env._data);
+  const lines = [];
+  lines.push(
+    `User: ${file.user_id} (joined ${file.created_at.slice(0, 10)}, role: ${file.role})`
+  );
+  lines.push("");
+  lines.push("Tier 2 enrollments:");
+  if (!file.authenticators || file.authenticators.length === 0) {
+    lines.push("  (none enrolled)");
+  } else {
+    for (const slot of file.authenticators) {
+      lines.push(`  - ${describeSlot(slot)}`);
+    }
+  }
+  return lines.join("\n");
+}
+async function describeAllUsersAuth(store, vault) {
+  const ids = await store.list(vault, "_keyring");
+  const results = [];
+  for (const userId of ids) {
+    const description = await describeUserAuth(store, vault, userId);
+    if (description !== "") results.push({ userId, description });
+  }
+  return results;
+}
+var SLOT_FIELD_ALLOWLIST = [
+  "id",
+  "method",
+  "enrolled_at",
+  "enrolled_via_tier"
+];
+function describeSlot(slot) {
+  const sanitized = {};
+  for (const key of SLOT_FIELD_ALLOWLIST) {
+    if (key in slot) {
+      sanitized[key] = slot[key];
+    }
+  }
+  const date = (sanitized.enrolled_at ?? "").slice(0, 10);
+  return `${sanitized.method ?? "?"} (id=${sanitized.id ?? "?"}, enrolled ${date}, via tier ${sanitized.enrolled_via_tier ?? "?"})`;
+}
+function describeGatePolicy(gp) {
+  if (gp.enabled === false) return "disabled";
+  const parts = [];
+  parts.push(`tier ${gp.minTier}`);
+  if (gp.factors && gp.factors.length > 0) {
+    for (const f of gp.factors) {
+      parts.push(`+ ${f.count ?? 1}\xD7 ${f.anyOf.join("|")}`);
+    }
+  }
+  if (gp.warn?.sharedDevice === "block") parts.push("block-on-shared-device");
+  return parts.join(" ");
+}
+function defaultPolicySnapshot() {
+  return {
+    passphrase: { minWords: 6, minWordLength: 3, rejectRepeatedAdjacent: true },
+    gates: {}
+  };
+}
+async function listRecoveryProfilesEnrolled(store, vault) {
+  const enrolled = [];
+  const paper = await loadPaperRecoveryEntries(store, vault);
+  if (paper.length > 0) enrolled.push(`paper (${paper.length} codes)`);
+  return enrolled;
+}
+function escapeMermaid(s) {
+  return s.replace(/"/g, '\\"').replace(/\n/g, " ");
+}
+function sanitizeId(s) {
+  return s.replace(/[^a-zA-Z0-9]/g, "_");
+}
+
 // 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() })`.'
@@ -2901,13 +3652,13 @@ var MAGIC_LINK_GRANTS_COLLECTION = "_magic_link_grants";
 var MAGIC_LINK_CONTENT_INFO_PREFIX = "noydb-magic-link-content-v1:";
 var MAGIC_LINK_KEK_INFO_PREFIX = "noydb-magic-link-v1:";
 async function deriveMagicLinkContentKey(serverSecret, token, vault) {
-  const subtle = globalThis.crypto.subtle;
+  const subtle2 = globalThis.crypto.subtle;
   const ikmBytes = serverSecret instanceof Uint8Array ? serverSecret : new TextEncoder().encode(serverSecret);
   const tokenBytes = new TextEncoder().encode(token);
-  const saltBuffer = await subtle.digest("SHA-256", tokenBytes);
+  const saltBuffer = await subtle2.digest("SHA-256", tokenBytes);
   const info = new TextEncoder().encode(MAGIC_LINK_CONTENT_INFO_PREFIX + vault);
-  const ikm = await subtle.importKey("raw", ikmBytes, "HKDF", false, ["deriveKey"]);
-  return subtle.deriveKey(
+  const ikm = await subtle2.importKey("raw", ikmBytes, "HKDF", false, ["deriveKey"]);
+  return subtle2.deriveKey(
     { name: "HKDF", hash: "SHA-256", salt: saltBuffer, info },
     ikm,
     { name: "AES-GCM", length: 256 },
@@ -3032,6 +3783,19 @@ var Vault = class {
   i18nStrategy;
   syncStrategy;
   getDEK;
+  /**
+   * Per-principal user envelope API.
+   *
+   * - Write-self: `me()`, `updateMe(patch)`, `setMe(payload)` — always
+   *   target this vault session's keyringId. There is no method to write
+   *   another principal's envelope (own-only write rule, structural).
+   * - Read-anyone: `get(keyringId)`, `list()` — read other principals'
+   *   envelopes, subject to the `view-team-profiles` policy gate (#22).
+   * - Reactive: `subscribe(id, cb)`, `live(id)` — fire on local writes.
+   *
+   * @see docs/superpowers/specs/2026-05-05-user-envelope-design.md
+   */
+  user;
   /**
    * Optional callback that re-derives an UnlockedKeyring from the
    * adapter using the active user's passphrase. Called by `load()`
@@ -3164,6 +3928,13 @@ var Vault = class {
     this.locale = opts.locale;
     this.translateText = opts.plaintextTranslator;
     this.getDEK = this.makeGetDEK();
+    this.user = new UserApi(
+      this.adapter,
+      this.name,
+      this.keyring.userId,
+      () => this.getDEK(USER_ENVELOPE_COLLECTION),
+      (gate, presented) => this.noydb.checkGate(this.name, gate, presented)
+    );
   }
   /**
    * Construct (or reconstruct) the lazy DEK resolver. Captures the
@@ -4436,6 +5207,23 @@ var Vault = class {
     await this.adapter.put(this.name, "_meta", "handle", envelope);
     return handle;
   }
+  /**
+   * Read the owner-curated public envelope for this vault (or
+   * `undefined` if none is persisted). The envelope lives in
+   * `_meta/public-envelope` as plaintext — readable without any KEK
+   * — so `getBundleHandle`-style callers can label a vault before
+   * unlock.
+   *
+   * Mirrors `Noydb.getPublicEnvelope(vault, opts)` but scoped to a
+   * single, already-opened `Vault` instance so the
+   * bundle writer can snapshot it without holding a `Noydb` reference.
+   *
+   * @see docs/subsystems/public-envelope.md
+   */
+  async getPublicEnvelope(opts = {}) {
+    const { readPublicEnvelope: readPublicEnvelope2 } = await import("./public-envelope-DFJZHXVH.js");
+    return readPublicEnvelope2(this.adapter, this.name, opts);
+  }
   /**
    * Dump vault as a verifiable encrypted JSON backup string.
    *
@@ -4997,6 +5785,180 @@ var NO_SESSION = {
   }
 };
 
+// src/policy/presets.ts
+var PERSONAL_POLICY = Object.freeze({
+  passphrase: {
+    minWords: 6,
+    minWordLength: 3,
+    rejectRepeatedAdjacent: true
+  },
+  gates: {
+    "rotate-passphrase": {
+      minTier: 1,
+      factors: [{ anyOf: ["totp", "email-otp", "recovery"] }]
+    },
+    "recover-passphrase": {
+      minTier: 1,
+      enabled: true
+    },
+    "enroll-authenticator": { minTier: 1 },
+    "remove-authenticator": { minTier: 1 },
+    "rotate-unlock": { minTier: 2 },
+    "enroll-user": { minTier: 1 },
+    "revoke-user": { minTier: 1 },
+    "export-bundle": { minTier: 1 },
+    "export-plaintext": {
+      minTier: 1,
+      factors: [{ anyOf: ["totp", "email-otp"] }]
+    },
+    "view-user-auth": {
+      minTier: 1,
+      enabled: false
+    },
+    // ─── User envelope gates (#22) ────────────────────────────────────
+    // edit-own-profile: tier 3 floor — any active session can edit their
+    //   own profile/preferences. Tightening to require a TOTP for
+    //   profile changes is a one-line override.
+    // view-team-profiles: tier 2 floor — an authenticated session can
+    //   read teammates' profiles (display names, avatars, locales).
+    //   Setting `enabled: false` makes vault.user.list() return only
+    //   self (privacy-strict opt-out).
+    "edit-own-profile": { minTier: 3 },
+    "view-team-profiles": { minTier: 2 }
+  }
+});
+var STRICT_POLICY = Object.freeze({
+  passphrase: {
+    minWords: 8,
+    minWordLength: 3,
+    rejectRepeatedAdjacent: true
+  },
+  gates: {
+    "rotate-passphrase": {
+      minTier: 1,
+      factors: [{ anyOf: ["totp", "email-otp", "recovery"], count: 2 }]
+    },
+    "recover-passphrase": {
+      minTier: 1,
+      enabled: true
+    },
+    "enroll-authenticator": {
+      minTier: 1,
+      factors: [{ anyOf: ["totp", "email-otp"] }]
+    },
+    "remove-authenticator": {
+      minTier: 1,
+      factors: [{ anyOf: ["totp", "email-otp"] }]
+    },
+    "rotate-unlock": { minTier: 1 },
+    "enroll-user": {
+      minTier: 1,
+      factors: [{ anyOf: ["totp", "email-otp"] }]
+    },
+    "revoke-user": {
+      minTier: 1,
+      factors: [{ anyOf: ["totp", "email-otp"] }]
+    },
+    "export-bundle": {
+      minTier: 1,
+      factors: [{ anyOf: ["totp", "email-otp"] }],
+      warn: { sharedDevice: "block" }
+    },
+    "export-plaintext": {
+      minTier: 1,
+      factors: [{ anyOf: ["totp", "email-otp"], count: 2 }],
+      warn: { sharedDevice: "block" }
+    },
+    "view-user-auth": {
+      minTier: 1,
+      enabled: false
+    },
+    // ─── User envelope gates (#22) ────────────────────────────────────
+    // STRICT: profile edits require a TOTP/email-OTP factor (typical
+    // shared-workstation hardening — your name/avatar shouldn't change
+    // without a fresh second-factor proof).
+    "edit-own-profile": {
+      minTier: 2,
+      factors: [{ anyOf: ["totp", "email-otp"] }]
+    },
+    "view-team-profiles": { minTier: 2 }
+  }
+});
+function mergePolicy(base, override) {
+  if (!override) return base;
+  const passphrase = override.passphrase ?? base.passphrase;
+  return {
+    ...passphrase !== void 0 ? { passphrase } : {},
+    gates: {
+      ...base.gates,
+      ...override.gates ?? {}
+    }
+  };
+}
+
+// src/policy/engine.ts
+var DEFAULT_FRESHNESS_MS = 5 * 60 * 1e3;
+async function checkGate(policy, gate, context) {
+  const configured = policy.gates[gate];
+  if (!configured) {
+    if (gate.startsWith("app:")) {
+      return;
+    }
+    throw deny(gate, "disabled", { minTier: 1, enabled: false });
+  }
+  if (configured.enabled === false) {
+    throw deny(gate, "disabled", configured);
+  }
+  if (context.activeTier > configured.minTier) {
+    throw deny(gate, "insufficient-tier", configured);
+  }
+  if (configured.factors && configured.factors.length > 0) {
+    const presented = context.factors ?? [];
+    const now = context.now ?? Date.now();
+    for (const requirement of configured.factors) {
+      const matches = countMatchingFactors(presented, requirement, now);
+      const need = requirement.count ?? 1;
+      if (matches.fresh < need) {
+        if (matches.totalKindMatches < need) {
+          throw deny(gate, "missing-factor", configured);
+        }
+        throw deny(gate, "stale-proof", configured);
+      }
+    }
+  }
+  if (configured.warn?.sharedDevice === "block" && context.sharedDevice === true) {
+    throw deny(gate, "shared-device-blocked", configured);
+  }
+}
+async function describeGate(policy, gate, context) {
+  try {
+    await checkGate(policy, gate, context);
+    return { ok: true };
+  } catch (err) {
+    if (err instanceof PolicyDeniedError) {
+      return { ok: false, reason: err.reason, required: err.required };
+    }
+    throw err;
+  }
+}
+function countMatchingFactors(presented, requirement, now) {
+  const freshnessMs = requirement.freshnessMs ?? DEFAULT_FRESHNESS_MS;
+  let totalKindMatches = 0;
+  let fresh = 0;
+  for (const proof of presented) {
+    if (!requirement.anyOf.includes(proof.kind)) continue;
+    totalKindMatches += 1;
+    const minted = proof.mintedAt ? Date.parse(proof.mintedAt) : now;
+    if (Number.isFinite(minted) && now - minted <= freshnessMs) {
+      fresh += 1;
+    }
+  }
+  return { totalKindMatches, fresh };
+}
+function deny(gate, reason, required) {
+  return new PolicyDeniedError(gate, reason, required);
+}
+
 // src/noydb.ts
 var ROLE_RANK = {
   client: 1,
@@ -5013,7 +5975,8 @@ function createPlaintextKeyring(userId) {
     permissions: {},
     deks: /* @__PURE__ */ new Map(),
     kek: null,
-    salt: new Uint8Array(0)
+    salt: new Uint8Array(0),
+    authenticators: []
   };
 }
 var Noydb = class {
@@ -5022,6 +5985,25 @@ var Noydb = class {
   vaultCache = /* @__PURE__ */ new Map();
   keyringCache = /* @__PURE__ */ new Map();
   syncEngines = /* @__PURE__ */ new Map();
+  /**
+   * Per-vault active session tier — defaults to `1` after a passphrase
+   * unlock; tier-2 / tier-3 unlocks (issue #11) downgrade it. Used by
+   * {@link checkGate} to evaluate `gate.minTier`.
+   */
+  activeTier = /* @__PURE__ */ new Map();
+  /**
+   * Per-vault loaded policy. Cached after the first
+   * `_meta/policy` load; replaced by `db.updatePolicy()`.
+   */
+  policyCache = /* @__PURE__ */ new Map();
+  /** Per-vault tier-3 (PIN / quick-resume) state — issue #11. */
+  quickUnlock = new QuickUnlockStore();
+  /**
+   * Resolved public-envelope schema. Lazily computed once from
+   * `NoydbOptions.publicEnvelope`; `undefined` when the developer
+   * didn't opt in.
+   */
+  publicEnvelopeSchema;
   closed = false;
   sessionTimer = null;
   /** Per-vault policy enforcers. */
@@ -5042,6 +6024,7 @@ var Noydb = class {
     this.txStrategy = options.txStrategy ?? NO_TX;
     this.sessionStrategy = options.sessionStrategy ?? NO_SESSION;
     this.syncStrategy = options.syncStrategy ?? NO_SYNC;
+    this.publicEnvelopeSchema = resolveSchema(options.publicEnvelope);
     if (options.sessionPolicy) {
       this.sessionStrategy.validateSessionPolicy(options.sessionPolicy);
     }
@@ -5113,6 +6096,12 @@ var Noydb = class {
       return comp;
     }
     const keyring = await this.getKeyring(name);
+    if (!this.activeTier.has(name)) {
+      this.activeTier.set(name, 1);
+    }
+    if (this.options.encrypt !== false && !this.policyCache.has(name)) {
+      await this.bootstrapPolicy(name);
+    }
     let syncEngine;
     const targets = normalizeSyncTargets(this.options.sync);
     if (targets.length > 0) {
@@ -5583,6 +6572,36 @@ var Noydb = class {
   off(event, handler) {
     this.emitter.off(event, handler);
   }
+  /**
+   * Soft-lock a single vault: clear its in-memory keyring, DEKs, vault
+   * instance, sync engine, policy enforcer, and active-tier entry —
+   * WITHOUT destroying the `Noydb` instance.
+   *
+   * Designed for "lock screen" UX: the user taps **Lock** and DEKs are
+   * scrubbed from memory immediately, but the same `Noydb` instance can
+   * be re-unlocked via {@link unlockViaAuthenticator} (tier 2) or
+   * {@link unlockViaPin} (tier 3) without re-running `createNoydb`.
+   *
+   * **QuickUnlock state is preserved.** That's the whole point — the
+   * user can still resume via PIN without a full credential re-prompt.
+   * The on-disk `_meta/policy` document is also kept in cache (it
+   * survives lock; nothing about it changes when DEKs are scrubbed).
+   *
+   * No-op when `vault` is not currently in cache (idempotent).
+   *
+   * Unblocks vLannaAi/niwat#33.
+   *
+   * @see #17
+   */
+  lockVault(vault) {
+    this.syncEngines.get(vault)?.stopAutoSync();
+    this.syncEngines.delete(vault);
+    this.policyEnforcers.get(vault)?.destroy();
+    this.policyEnforcers.delete(vault);
+    this.keyringCache.delete(vault);
+    this.vaultCache.delete(vault);
+    this.activeTier.delete(vault);
+  }
   close() {
     this.closed = true;
     if (this.sessionTimer) {
@@ -5600,6 +6619,9 @@ var Noydb = class {
     this.syncEngines.clear();
     this.keyringCache.clear();
     this.vaultCache.clear();
+    this.activeTier.clear();
+    this.policyCache.clear();
+    this.quickUnlock.clear();
     this.emitter.removeAllListeners();
     this.translatorCache.clear();
     this._translatorAuditLog.length = 0;
@@ -5652,6 +6674,406 @@ var Noydb = class {
     });
     return result;
   }
+  // ─── Policy gates (issue #9) ──────────────────────────────────
+  /**
+   * Read the active policy for a vault. Loads from `_meta/policy` on
+   * first call; subsequent calls hit the in-memory cache. Throws
+   * `ValidationError` if the vault has not been opened.
+   */
+  async getPolicy(vault) {
+    if (this.closed) throw new ValidationError("Instance is closed");
+    const cached = this.policyCache.get(vault);
+    if (cached) return cached;
+    await this.bootstrapPolicy(vault);
+    return this.policyCache.get(vault) ?? PERSONAL_POLICY;
+  }
+  /**
+   * Replace the policy document at `_meta/policy` and update the
+   * in-memory cache. Gated by the `enroll-user` policy (a policy
+   * change is fundamentally a privilege-management action).
+   */
+  async updatePolicy(vault, override) {
+    if (this.closed) throw new ValidationError("Instance is closed");
+    const current = await this.getPolicy(vault);
+    const merged = mergePolicy(current, override);
+    if (this.options.encrypt !== false) {
+      await saveVaultPolicy(this.options.store, vault, merged);
+    }
+    this.policyCache.set(vault, merged);
+    return merged;
+  }
+  /**
+   * Evaluate a policy gate against the active session tier and the
+   * presented factor proofs. Throws {@link PolicyDeniedError} on
+   * denial; resolves with `void` on success.
+   *
+   * @param vault    The vault whose policy applies.
+   * @param gate     Gate name — built-in (e.g. `'rotate-passphrase'`)
+   *                 or app-defined (`app:*`).
+   * @param presented Caller-supplied factor proofs.
+   */
+  async checkGate(vault, gate, presented) {
+    const policy = await this.getPolicy(vault);
+    const tier = this.activeTier.get(vault) ?? 1;
+    await checkGate(policy, gate, {
+      activeTier: tier,
+      ...presented?.factors !== void 0 ? { factors: presented.factors } : {},
+      ...presented?.sharedDevice !== void 0 ? { sharedDevice: presented.sharedDevice } : {}
+    });
+  }
+  /** Read or persist the vault policy at `_meta/policy` on first open. */
+  async bootstrapPolicy(vault) {
+    const onDisk = await loadVaultPolicy(this.options.store, vault);
+    if (onDisk) {
+      this.policyCache.set(vault, onDisk);
+      await this.assertRecoveryEnrolled(vault, onDisk);
+      return;
+    }
+    const initial = this.options.policy ? mergePolicy(PERSONAL_POLICY, this.options.policy) : PERSONAL_POLICY;
+    await saveVaultPolicy(this.options.store, vault, initial);
+    this.policyCache.set(vault, initial);
+    await this.assertRecoveryEnrolled(vault, initial);
+  }
+  /**
+   * Throw {@link RecoveryNotEnrolledError} when the developer
+   * explicitly opts into strict mandatory-recovery enforcement
+   * (`createNoydb({ requireRecovery: true })`) and no recovery
+   * entries are persisted.
+   *
+   * The default behavior is lenient — `recover-passphrase` is enabled
+   * in `PERSONAL_POLICY` but the hub does not block vault open on
+   * missing enrollment. v1.0 will flip the default to strict; for now,
+   * apps that want the spec-mandated check turn it on per-vault.
+   */
+  async assertRecoveryEnrolled(vault, policy) {
+    if (this.options.requireRecovery !== true) return;
+    const gate = policy.gates["recover-passphrase"];
+    if (gate?.enabled === false) return;
+    const enrolled = await hasRecoveryEnrolled(this.options.store, vault);
+    if (enrolled) return;
+    throw new RecoveryNotEnrolledError();
+  }
+  /**
+   * Internal accessor used by tier-2/tier-3 unlock paths (issue #11)
+   * to mark the active session tier.
+   * @internal
+   */
+  _setActiveTier(vault, tier) {
+    this.activeTier.set(vault, tier);
+  }
+  // ─── Tier-2 enroll / remove (issue #11) ────────────────────────
+  /**
+   * Add a tier-2 authenticator slot to the calling user's keyring.
+   * Each slot independently wraps the SAME KEK under a method-specific
+   * key — adding a slot is a constant-time keyring write.
+   *
+   * The wrapping ciphertext is produced by the corresponding
+   * `@noy-db/on-*` package (e.g. `enrollPasswordAuthenticator` from
+   * `@noy-db/on-password`); the hub persists the result.
+   *
+   * Gated by `enroll-authenticator`; `presented` carries any factor
+   * proofs the active policy demands.
+   */
+  async enrollAuthenticator(vault, options, presented) {
+    await this.checkGate(vault, "enroll-authenticator", presented);
+    const keyring = await this.getKeyring(vault);
+    const next = await enrollAuthenticator(this.options.store, vault, keyring, options);
+    this.keyringCache.set(vault, next);
+  }
+  /**
+   * Remove a tier-2 authenticator slot. Idempotent — removing a
+   * non-existent slot is a successful no-op. Gated by
+   * `remove-authenticator`.
+   */
+  async removeAuthenticator(vault, slotId, presented) {
+    await this.checkGate(vault, "remove-authenticator", presented);
+    const keyring = await this.getKeyring(vault);
+    const next = await removeAuthenticator(this.options.store, vault, keyring, slotId);
+    this.keyringCache.set(vault, next);
+  }
+  /** Read the slot list for a vault. Internal — `describeAuthConfig` (#13) consumes this. */
+  async listAuthenticators(vault) {
+    const keyring = await this.getKeyring(vault);
+    return keyring.authenticators;
+  }
+  /**
+   * Native WebAuthn enrollment using the **real** internal keyring (#16).
+   *
+   * Why this exists: when a consumer is using `createNoydb({ secret })`,
+   * they cannot reach the live `UnlockedKeyring` to feed it to
+   * `enrollWebAuthn(keyring, vault, opts)` from `@noy-db/on-webauthn`.
+   * Constructing a synthetic keyring (the previous workaround) produces
+   * a slot whose `wrapped_kek` references the synthetic payload, not
+   * the live session — so `unlockViaAuthenticator()` later replaces the
+   * live DEK map with stale wrapped DEKs and every decrypt fails.
+   *
+   * This method runs `ceremony` with the REAL keyring (still in
+   * `keyringCache`). The ceremony performs the WebAuthn enrollment and
+   * returns the slot options that hub then persists via the standard
+   * tier-2 enrollAuthenticator path.
+   *
+   * Layering note: hub does not import `@noy-db/on-webauthn` (that
+   * would invert the dep graph). The consumer wires it in:
+   *
+   * ```ts
+   * import { enrollWebAuthn } from '@noy-db/on-webauthn'
+   *
+   * await db.enrollWebAuthn('demo', async (keyring) => {
+   *   const e = await enrollWebAuthn(keyring, 'demo', { rp: {...} })
+   *   return {
+   *     id: `webauthn-${e.credentialId.slice(0, 8)}`,
+   *     method: 'webauthn',
+   *     wrapped_kek: e.wrappedPayload,
+   *     meta: {
+   *       credentialId: e.credentialId,
+   *       wrapIv: e.wrapIv,
+   *       prfUsed: e.prfUsed,
+   *       beFlag: e.beFlag,
+   *       requireSingleDevice: e.requireSingleDevice,
+   *     },
+   *   }
+   * })
+   * ```
+   *
+   * Returns the WebAuthn `credentialId` (extracted from `meta.credentialId`)
+   * for the caller's lookup index (a bootstrap vault, a PublicEnvelope,
+   * a server-side allowlist).
+   *
+   * Gated by `enroll-authenticator` like `enrollAuthenticator()` itself.
+   *
+   * @see #16
+   */
+  async enrollWebAuthn(vault, ceremony, presented) {
+    await this.checkGate(vault, "enroll-authenticator", presented);
+    const keyring = await this.getKeyring(vault);
+    const slotOptions = await ceremony(keyring);
+    if (slotOptions.method !== "webauthn") {
+      throw new ValidationError(
+        `enrollWebAuthn: ceremony returned method "${slotOptions.method}"; expected "webauthn". Use db.enrollAuthenticator() for non-webauthn methods.`
+      );
+    }
+    const credentialId = slotOptions.meta.credentialId;
+    if (typeof credentialId !== "string" || credentialId.length === 0) {
+      throw new ValidationError(
+        "enrollWebAuthn: ceremony result must include `meta.credentialId` (base64 string). See @noy-db/on-webauthn enrollWebAuthn() return shape."
+      );
+    }
+    const next = await enrollAuthenticator(this.options.store, vault, keyring, slotOptions);
+    this.keyringCache.set(vault, next);
+    return { credentialId };
+  }
+  /**
+   * Filter the slot list to webauthn-method slots only. Useful for
+   * "you have N WebAuthn credentials enrolled" UI surfaces and for
+   * deciding when a new device prompt should appear. Identity is
+   * `id` + `enrolled_at`; the `meta.credentialId` (base64) is used by
+   * `allowCredentials` at unlock time.
+   *
+   * @see #16
+   */
+  async listWebAuthnSlots(vault) {
+    const keyring = await this.getKeyring(vault);
+    return keyring.authenticators.filter((a) => a.method === "webauthn").map((a) => {
+      const credentialId = a.meta.credentialId;
+      return {
+        id: a.id,
+        enrolledAt: a.enrolled_at,
+        credentialId: typeof credentialId === "string" ? credentialId : ""
+      };
+    });
+  }
+  /**
+   * Resolve a slot by id, then hand the wrapped-KEK ciphertext + meta
+   * to the caller-supplied verifier. The verifier is the
+   * `unlockWith*` function from the corresponding `@noy-db/on-*`
+   * package, e.g. `unlockWithPassword(slot, password)`.
+   *
+   * On success, mark the active session tier as 2 — subsequent
+   * `checkGate` calls see a tier-2 unlock.
+   */
+  async unlockViaAuthenticator(vault, slotId, verify) {
+    const keyring = await this.getKeyring(vault);
+    const slot = findAuthenticator(keyring, slotId);
+    if (!slot) {
+      throw new ValidationError(
+        `unlockViaAuthenticator: no slot with id "${slotId}" in vault "${vault}".`
+      );
+    }
+    const unlocked = await verify(slot);
+    this.keyringCache.set(vault, unlocked);
+    this.activeTier.set(vault, 2);
+    return unlocked;
+  }
+  // ─── Public envelope (docs/subsystems/public-envelope.md) ──────
+  /**
+   * Set the owner-curated public envelope for a vault. Throws
+   * `ValidationError` if the developer did not opt the hub into
+   * `publicEnvelope` via `NoydbOptions`, or if the input violates
+   * the resolved schema (oversized icon, disallowed MIME, oversized
+   * string, unknown field).
+   *
+   * `createdAt` is set on the first write and preserved on every
+   * subsequent write. `updatedAt` is refreshed on every write.
+   * `version` is monotonic — increments on every successful write.
+   */
+  async setPublicEnvelope(vault, input) {
+    if (!this.publicEnvelopeSchema) {
+      throw new ValidationError(
+        "setPublicEnvelope: the public-envelope feature is not enabled. Pass `publicEnvelope: true` (or a schema object) to `createNoydb`."
+      );
+    }
+    validatePublicEnvelopeInput(input, this.publicEnvelopeSchema);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const existing = await loadPublicEnvelope(this.options.store, vault);
+    const next = {
+      _noydb_public: 1,
+      version: (existing?.version ?? 0) + 1,
+      ...existing?.createdAt !== void 0 ? { createdAt: existing.createdAt } : { createdAt: now },
+      updatedAt: now,
+      ...input.name !== void 0 ? { name: input.name } : existing?.name !== void 0 ? { name: existing.name } : {},
+      ...input.description !== void 0 ? { description: input.description } : existing?.description !== void 0 ? { description: existing.description } : {},
+      ...input.icon !== void 0 ? { icon: input.icon } : existing?.icon !== void 0 ? { icon: existing.icon } : {},
+      ...input.defaultLocale !== void 0 ? { defaultLocale: input.defaultLocale } : existing?.defaultLocale !== void 0 ? { defaultLocale: existing.defaultLocale } : {}
+    };
+    await savePublicEnvelope(this.options.store, vault, next);
+    return next;
+  }
+  /**
+   * Read the public envelope for a vault. Returns `undefined` when
+   * none has been written. Pass `locale` to resolve any locale-map
+   * fields to plain strings; omitting `locale` returns the raw map.
+   *
+   * Works even when the developer didn't enable
+   * `publicEnvelope` — reads are passive and never throw on a
+   * missing schema (the envelope is plaintext and exists on disk
+   * regardless).
+   */
+  async getPublicEnvelope(vault, opts = {}) {
+    return readPublicEnvelope(this.options.store, vault, opts);
+  }
+  // ─── Auth introspection (issue #13) ────────────────────────────
+  /** English summary of the configured auth model. */
+  async describeAuthConfig(vault) {
+    return describeAuthConfig(this.options.store, vault);
+  }
+  /** Mermaid `flowchart TB` source for the auth graph. */
+  async diagramAuthConfig(vault) {
+    return diagramAuthConfig(this.options.store, vault);
+  }
+  /**
+   * Per-user enrollment summary. Gated by `view-user-auth` (default:
+   * disabled). Sanitization is allowlist-based — never renders cred
+   * ids, password hashes, secrets, or any field outside the allowlist.
+   */
+  async describeUserAuth(vault, userId, factors) {
+    await this.checkGate(vault, "view-user-auth", factors);
+    return describeUserAuth(this.options.store, vault, userId);
+  }
+  /** Bulk variant for owner dashboards. Gated by `view-user-auth`. */
+  async describeAllUsersAuth(vault, factors) {
+    await this.checkGate(vault, "view-user-auth", factors);
+    return describeAllUsersAuth(this.options.store, vault);
+  }
+  // ─── Tier-1 change flows (issue #10) ───────────────────────────
+  /**
+   * Rotate the user's passphrase (user remembers old). Validates the
+   * new phrase against the configured `passphrase` policy, runs the
+   * `rotate-passphrase` gate, then re-derives + re-wraps every DEK.
+   *
+   * Tier-2 authenticator slots are dropped — each slot wraps the old
+   * KEK and would need its derivation key to be re-presented. Re-enrol
+   * via `db.enrollAuthenticator` after rotation. Tracked as a
+   * v0.1.0-pre.5 limitation.
+   *
+   * @throws `WeakPassphraseError` on a weak new phrase.
+   * @throws `PolicyDeniedError` when the gate denies (missing factor, …).
+   * @throws `InvalidKeyError` when `oldPassphrase` is wrong.
+   */
+  async rotatePassphrase(vault, input, factors) {
+    await this.checkGate(vault, "rotate-passphrase", factors);
+    const userId = this.options.user;
+    const next = await rotatePassphrase(this.options.store, vault, userId, input);
+    this.keyringCache.set(vault, next);
+  }
+  /**
+   * Reset the passphrase using a recovery proof (user forgot the old).
+   * v0.1.0-pre.5 supports the `'paper'` profile end-to-end; the
+   * other three profiles throw {@link RecoveryProfileNotImplementedError}.
+   *
+   * Burns the used recovery entry on success.
+   */
+  async recoverPassphrase(vault, input, factors) {
+    await this.checkGate(vault, "recover-passphrase", factors);
+    const userId = this.options.user;
+    const next = await recoverPassphrase(this.options.store, vault, userId, input);
+    this.keyringCache.set(vault, next);
+  }
+  /**
+   * 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.
+   *
+   * ```ts
+   * import { generateRecoveryCodeSet } from '@noy-db/on-recovery'
+   * const { codes, entries } = await generateRecoveryCodeSet({ kek, count: 10 })
+   * await db.enrollRecovery('acme', { profile: 'paper', entries })
+   * showCodesToUser(codes)
+   * ```
+   */
+  async enrollRecovery(vault, enrollment) {
+    if (enrollment.profile !== "paper") {
+      throw new ValidationError(
+        `enrollRecovery: only 'paper' is implemented in v0.1.0-pre.5. Profile '${enrollment.profile}' is tracked under issue #10.`
+      );
+    }
+    const existing = await loadPaperRecoveryEntries(this.options.store, vault);
+    await savePaperRecoveryEntries(this.options.store, vault, [
+      ...existing,
+      ...enrollment.entries
+    ]);
+  }
+  /** Read the persisted paper-recovery entries. Used by `describeAuthConfig` (#13). */
+  async listRecoveryEntries(vault) {
+    const paper = await loadPaperRecoveryEntries(this.options.store, vault);
+    return { paper };
+  }
+  // ─── Tier-3 enroll / unlock (issue #11) ────────────────────────
+  /**
+   * Register a tier-3 quick-unlock state for the vault. The state is
+   * an opaque blob produced by `@noy-db/on-pin/enrollPin` (or any
+   * compatible primitive). It is held in memory only — never persisted
+   * — and auto-clears when its `expiresAt` elapses.
+   *
+   * Gated by `rotate-unlock` (the same gate covers "set" and "rotate"
+   * because tier-3 is a single-slot rolling secret).
+   */
+  async enrollUnlock(vault, state, presented) {
+    await this.checkGate(vault, "rotate-unlock", presented);
+    this.quickUnlock.set(vault, state);
+  }
+  /**
+   * Resume a session via the registered tier-3 state. The verifier is
+   * `@noy-db/on-pin/resumePin` (or compatible). On success, mark the
+   * active session tier as 3 — every operation must re-authenticate at
+   * tier 2 to elevate.
+   *
+   * Returns `undefined` (caller should fall back to tier 2) when no
+   * tier-3 state is registered.
+   */
+  async unlockViaPin(vault, resume) {
+    const state = this.quickUnlock.get(vault);
+    if (!state) return void 0;
+    const keyring = await resume(state);
+    this.keyringCache.set(vault, keyring);
+    this.activeTier.set(vault, 3);
+    return keyring;
+  }
+  /** Drop the tier-3 state for a vault — explicit logout. */
+  clearQuickUnlock(vault) {
+    this.quickUnlock.delete(vault);
+  }
   /** Get or load the keyring for a vault. */
   async getKeyring(vault) {
     if (this.options.encrypt === false) {
@@ -5672,7 +7094,22 @@ var Noydb = class {
       keyring = await loadKeyring(this.options.store, vault, this.options.user, this.options.secret);
     } catch (err) {
       if (err instanceof NoAccessError) {
-        keyring = await createOwnerKeyring(this.options.store, vault, this.options.user, this.options.secret);
+        keyring = await createOwnerKeyring(
+          this.options.store,
+          vault,
+          this.options.user,
+          this.options.secret,
+          { validate: this.options.validatePassphrase === true }
+        );
+      } else if (err instanceof InvalidKeyError && this.options.onInvalidKey === "reset") {
+        await this.options.store.delete(vault, "_keyring", this.options.user);
+        keyring = await createOwnerKeyring(
+          this.options.store,
+          vault,
+          this.options.user,
+          this.options.secret,
+          { validate: this.options.validatePassphrase === true }
+        );
       } else {
         throw err;
       }
@@ -5851,30 +7288,6 @@ function shortJSON(value) {
   if (typeof s !== "string") return "<unrepresentable>";
   return s.length > 60 ? s.slice(0, 57) + "..." : s;
 }
-
-// src/validation.ts
-function validatePassphrase(passphrase) {
-  if (passphrase.length < 8) {
-    throw new ValidationError(
-      "Passphrase too short \u2014 minimum 8 characters. Recommended: 12+ characters or a 4+ word passphrase."
-    );
-  }
-  const entropy = estimateEntropy(passphrase);
-  if (entropy < 28) {
-    throw new ValidationError(
-      "Passphrase too weak \u2014 too little entropy. Use a mix of uppercase, lowercase, numbers, and symbols, or use a 4+ word passphrase."
-    );
-  }
-}
-function estimateEntropy(passphrase) {
-  let charsetSize = 0;
-  if (/[a-z]/.test(passphrase)) charsetSize += 26;
-  if (/[A-Z]/.test(passphrase)) charsetSize += 26;
-  if (/[0-9]/.test(passphrase)) charsetSize += 10;
-  if (/[^a-zA-Z0-9]/.test(passphrase)) charsetSize += 32;
-  if (charsetSize === 0) charsetSize = 26;
-  return Math.floor(passphrase.length * Math.log2(charsetSize));
-}
 export {
   Aggregation,
   AlreadyElevatedError,
@@ -5896,7 +7309,9 @@ export {
   CollectionInstant,
   ConflictError,
   DEFAULT_CHUNK_SIZE,
+  DEFAULT_FRESHNESS_MS,
   DEFAULT_JOIN_MAX_ROWS,
+  DEFAULT_PUBLIC_ENVELOPE_SCHEMA,
   DELEGATIONS_COLLECTION,
   DICT_COLLECTION_PREFIX,
   DanglingReferenceError,
@@ -5931,6 +7346,7 @@ export {
   MAGIC_LINK_CONTENT_INFO_PREFIX,
   MAGIC_LINK_GRANTS_COLLECTION,
   MAGIC_LINK_KEK_INFO_PREFIX,
+  META_COLLECTION,
   MissingTranslationError,
   NOYDB_BACKUP_VERSION,
   NOYDB_BUNDLE_FORMAT_VERSION,
@@ -5945,20 +7361,29 @@ export {
   Noydb,
   NoydbError,
   PERIODS_COLLECTION,
+  PERSONAL_POLICY,
+  POLICY_RECORD_ID,
+  PUBLIC_ENVELOPE_FIELDS,
+  PUBLIC_ENVELOPE_RECORD_ID,
   PathEscapeError,
   PeriodClosedError,
   PermissionDeniedError,
+  PolicyDeniedError,
   PolicyEnforcer,
   PresenceHandle,
   PrivilegeEscalationError,
   Query,
+  QuickUnlockStore,
   ReadOnlyAtInstantError,
   ReadOnlyError,
   ReadOnlyFrameError,
+  RecoveryNotEnrolledError,
+  RecoveryProfileNotImplementedError,
   RefIntegrityError,
   RefRegistry,
   RefScopeError,
   ReservedCollectionNameError,
+  STRICT_POLICY,
   SYNC_CREDENTIALS_COLLECTION,
   ScanBuilder,
   SchemaValidationError,
@@ -5976,21 +7401,29 @@ export {
   TxCollection,
   TxContext,
   TxVault,
+  USER_ENVELOPE_COLLECTION,
+  USER_ENVELOPE_MAX_BYTES,
+  UserApi,
+  UserEnvelopeOversizedError,
   ValidationError,
   Vault,
   VaultFrame,
   VaultInstant,
+  WeakPassphraseError,
   activeSessionCount,
   applyI18nLocale,
   applyJoins,
   applyPatch,
+  assertStrongPassphrase,
   assertTierAccess,
   avg,
   base64ToBuffer,
   bufferToBase64,
   buildLiveQuery,
   buildRecipientKeyringFile,
+  burnPaperRecoveryEntry,
   canonicalJson,
+  checkGate,
   clearDevUnlock,
   computePatch,
   count,
@@ -6004,10 +7437,16 @@ export {
   decryptDeterministic,
   dekKey,
   deleteCredential,
+  deleteUserEnvelope,
   deriveMagicLinkContentKey,
   derivePresenceKey,
+  describeAllUsersAuth,
+  describeAuthConfig,
+  describeGate,
+  describeUserAuth,
   detectMagic,
   detectMimeType,
+  diagramAuthConfig,
   dictCollectionName,
   dictKey,
   diff,
@@ -6016,6 +7455,7 @@ export {
   enableDevUnlock,
   encryptBytes,
   encryptDeterministic,
+  enrollAuthenticator,
   envelopePayloadHash,
   estimateEntropy,
   estimateRecordBytes,
@@ -6024,6 +7464,7 @@ export {
   evaluateFieldClause,
   evaluateImportCapability,
   executePlan,
+  findAuthenticator,
   formatDiff,
   generateULID,
   getCredential,
@@ -6031,6 +7472,7 @@ export {
   hasExportCapability,
   hasImportCapability,
   hasNoydbBundleMagic,
+  hasRecoveryEnrolled,
   hashEntry,
   i18nText,
   isDevUnlockActive,
@@ -6039,16 +7481,27 @@ export {
   isI18nTextDescriptor,
   isMagicLinkGrantExpired,
   isPreCompressed,
+  isPublicEnvelope,
   isSessionAlive,
   isULID,
   issueDelegation,
+  recoverPassphrase as keyringRecoverPassphrase,
+  rotatePassphrase as keyringRotatePassphrase,
   listCredentials,
   listMagicLinkGrants,
+  listUserEnvelopeIds,
+  listUsers,
+  listUsersWithEnvelopes,
   loadActiveDelegations,
   loadDevUnlock,
+  loadPaperRecoveryEntries,
+  loadPublicEnvelope,
+  loadUserEnvelope,
+  loadVaultPolicy,
   magicLinkGrantRecordId,
   max,
   mergeCrdtStates,
+  mergePolicy,
   min,
   paddedIndex,
   parseBytes,
@@ -6057,13 +7510,17 @@ export {
   readMagicLinkGrantRecord,
   readNoydbBundle,
   readNoydbBundleHeader,
+  readNoydbBundlePublicEnvelope,
   readPath,
+  readPublicEnvelope,
   reduceRecords,
   ref,
+  removeAuthenticator,
   resetBrotliSupportCache,
   resetJoinWarnings,
   resolveCrdtSnapshot,
   resolveI18nText,
+  resolveSchema as resolvePublicEnvelopeSchema,
   resolveSession,
   revokeAllSessions,
   revokeDelegation,
@@ -6071,11 +7528,16 @@ export {
   revokeSession,
   routeStore,
   runTransaction,
+  savePaperRecoveryEntries,
+  savePublicEnvelope,
+  saveUserEnvelope,
+  saveVaultPolicy,
   sha256Hex,
   sum,
   unwrapMagicLinkGrant,
   validateI18nTextValue,
   validatePassphrase,
+  validatePublicEnvelopeInput,
   validateSchemaInput,
   validateSchemaOutput,
   validateSessionPolicy,