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

package/dist/{types-D3QLmhlk.d.cts → types-Bnb82f5R.d.cts}

@@ -1770,6 +1770,49 @@ interface PassphrasePolicy {
     readonly minWordLength?: number;
     /** Reject adjacent identical words ("the the"). Default true. */
     readonly rejectRepeatedAdjacent?: boolean;
+    /**
+     * Override the default character-class rule (`/^[a-z]+( [a-z]+)*$/`).
+     *
+     * The hub's strict default is lowercase-letters-and-single-spaces
+     * because that's what the EFF wordlist generator emits and what
+     * most attacker password lists are keyed on. Use this knob to allow
+     * digits, uppercase, hyphens, or non-Latin scripts when the
+     * consumer's audience needs them — e.g.:
+     *
+     * ```ts
+     * // Thai + English mix with digits permitted
+     * pattern: /^[\p{L}0-9 ]+( [\p{L}0-9 ]+)*$/u
+     *
+     * // Allow uppercase + hyphens (passphrase-with-hyphens style)
+     * pattern: /^[A-Za-z]+([- ][A-Za-z]+)*$/
+     * ```
+     *
+     * The OTHER structural rules still apply (min-words split by space,
+     * min-word-length, repeated-adjacent, leading/trailing whitespace,
+     * double-space). For non-space-delimited word semantics, use
+     * {@link customValidator} instead.
+     *
+     * Added in pre.8 (#31).
+     */
+    readonly pattern?: RegExp;
+    /**
+     * Replace ALL validation entirely with a custom function. When set,
+     * none of the other PassphrasePolicy fields apply — the consumer
+     * owns every rule (word splitting, character classes, entropy
+     * thresholds, allowlist/denylist). Use sparingly; this is the
+     * escape hatch for domain-specific phrase formats:
+     *
+     *   - Localized wordlists with non-space word boundaries
+     *   - BIP-39 seed phrases (24 words, fixed wordlist, etc.)
+     *   - Organization-specific HR password policies
+     *
+     * The returned `PassphraseValidationResult` is what
+     * {@link assertStrongPassphrase} dispatches on — `ok: true` accepts;
+     * `ok: false` throws `WeakPassphraseError` with the supplied reason.
+     *
+     * Added in pre.8 (#31).
+     */
+    readonly customValidator?: (phrase: string) => PassphraseValidationResult;
 }
 /** Result of a check. Discriminated union — compile-time exhaustive. */
 type PassphraseValidationResult = {
@@ -1876,7 +1919,28 @@ interface UnlockedKeyring {
     readonly role: Role;
     readonly permissions: Permissions;
     readonly deks: Map<string, CryptoKey>;
-    readonly kek: CryptoKey;
+    /**
+     * The KEK, when this keyring was unlocked via tier 1 (passphrase) or
+     * a wrap-KEK tier-2 method (WebAuthn / OIDC). `null` when the
+     * keyring was opened via:
+     *
+     *   - Unencrypted mode (no KEK exists)
+     *   - Tier-3 PIN quick-resume (`@noy-db/on-pin`)
+     *   - Wrap-DEKs tier-2 unlock (`@noy-db/on-password`'s
+     *     `verifyPasswordSlot` after #26 Path C)
+     *   - Session-state restore (`session/session.ts`)
+     *   - Dev-unlock fixture (`session/dev-unlock.ts`)
+     *
+     * Consumers performing tier-1 operations that need the KEK
+     * (DEK rewrap, keyring persist, delegation issue/unwrap) must
+     * null-check and throw a clear error if absent — re-authenticate
+     * at tier 1 first to recover the KEK.
+     *
+     * Tightened from `CryptoKey` to `CryptoKey | null` in pre.8 (#41).
+     * The runtime contract has always allowed null; the type now
+     * matches reality.
+     */
+    readonly kek: CryptoKey | null;
     readonly salt: Uint8Array;
     /**
      * `@noy-db/as-*` export capability. Absent when the
@@ -2882,6 +2946,82 @@ declare class SyncEngine {
     private persistMeta;
 }
 
+/**
+ * Tier-2 authenticator slot management — issue #11.
+ *
+ * Each slot independently wraps the SAME KEK under a method-specific
+ * derived key (LUKS pattern). Enrolling adds a slot; removing drops
+ * one. Both are constant-time keyring writes — no DEK re-keying.
+ *
+ * The crypto for each method lives in its `@noy-db/on-*` package
+ * (`on-webauthn`, `on-oidc`, `on-password`); this module accepts the
+ * package's `wrapped_kek` ciphertext + `meta` payload and persists it.
+ *
+ * @see docs/subsystems/session-tiers.md → Tier 2 — Authenticate
+ *
+ * @module
+ */
+
+/** Fields shared across both wrap-KEK and wrap-DEKs enroll inputs. */
+interface EnrollAuthenticatorBase {
+    readonly id: string;
+    readonly method: KeyringAuthenticator['method'];
+    /** Method-specific metadata (cred id, salt, …). */
+    readonly meta: Record<string, unknown>;
+    /** Tier the active session held when enrolling. Defaults to 1. */
+    readonly enrolled_via_tier?: 1 | 2;
+}
+/** Wrap-KEK enroll input (WebAuthn, OIDC). */
+interface EnrollAuthenticatorWrappingKEKOptions extends EnrollAuthenticatorBase {
+    /** Already-wrapped KEK ciphertext (base64) — produced by the on-* package. */
+    readonly wrapped_kek: string;
+    readonly wrapKind?: 'kek';
+}
+/** Wrap-DEKs enroll input (password, future on-* using the unified wrap-DEKs primitive). */
+interface EnrollAuthenticatorWrappingDEKsOptions extends EnrollAuthenticatorBase {
+    readonly wrapKind: 'deks';
+    /** Base64 AES-GCM ciphertext of `{ deks: { collection: base64rawDek } }`. */
+    readonly wrapped_deks: string;
+    /** Base64 AES-GCM IV used for the `wrapped_deks` ciphertext. */
+    readonly iv: string;
+}
+/** Discriminated union over the two enroll input shapes. */
+type EnrollAuthenticatorOptions = EnrollAuthenticatorWrappingKEKOptions | EnrollAuthenticatorWrappingDEKsOptions;
+/**
+ * Append a new authenticator slot to the keyring file. Throws
+ * `ValidationError` if a slot with the same id already exists — the
+ * caller decides whether to remove + re-enroll.
+ *
+ * Accepts either wrap-KEK (WebAuthn, OIDC) or wrap-DEKs (password)
+ * input. The variant is preserved verbatim into `KeyringAuthenticator`.
+ */
+declare function enrollAuthenticator(store: NoydbStore, vault: string, keyring: UnlockedKeyring, options: EnrollAuthenticatorOptions): Promise<UnlockedKeyring>;
+/**
+ * Caller payload for {@link updateAuthenticator} (#55). Mutates only
+ * `meta` — the slot's id, method, and wrap material are immutable
+ * through this primitive, preserving the anti-slot-swap guard.
+ *
+ * `meta` is **merged** at the top level: keys absent from the patch
+ * are preserved, keys present overwrite. To clear a meta key, pass
+ * `null` for that key explicitly. (Same semantics as #57's
+ * `UserApi.updateMe`, scoped to this top-level merge — no recursion
+ * into nested meta values.)
+ */
+interface UpdateAuthenticatorOptions {
+    readonly meta?: Record<string, unknown>;
+}
+/**
+ * Drop a slot by id. No-op if the slot doesn't exist (idempotent —
+ * removing a non-existent slot is a recoverable retry, not an error).
+ */
+declare function removeAuthenticator(store: NoydbStore, vault: string, keyring: UnlockedKeyring, slotId: string): Promise<UnlockedKeyring>;
+/**
+ * Look up a slot by id. Returns `undefined` when no slot matches.
+ * Used by tier-2 unlock dispatchers to fetch the wrapped KEK + meta
+ * before invoking the method-specific verifier.
+ */
+declare function findAuthenticator(keyring: UnlockedKeyring, slotId: string): KeyringAuthenticator | undefined;
+
 /**
  * Tier-1 change flows — `rotatePassphrase` (user remembers old) and
  * `recoverPassphrase` (user supplies a recovery proof). Issue #10.
@@ -2901,24 +3041,86 @@ declare class SyncEngine {
  * @module
  */
 
+/**
+ * Context handed to a {@link SlotRewrapCeremony} when `rotatePassphrase`
+ * preserves a tier-2 slot. The ceremony's job is to re-derive its
+ * method-specific wrapping material (PRF assertion, PBKDF2 of a
+ * daily-password, etc.) and wrap the freshly rewrapped DEK set under
+ * the new wrapping key.
+ *
+ * Two surfaces are exposed:
+ *
+ *   - `newDeks` — the rewrapped (extractable) DEK set the slot will
+ *     wrap. This is what `mintPaperRecoveryEntry` / `enrollPassword-
+ *     Authenticator` / `wrapKeyringSummary` (in `@noy-db/on-webauthn`)
+ *     all consume; effectively the canonical input for every
+ *     post-Path C tier-2 ceremony.
+ *
+ *   - `newKek` — the freshly-derived KEK (extractable for the
+ *     ceremony scope only). Only relevant for forward-compatibility
+ *     with a hypothetical future on-* package that wants to wrap the
+ *     KEK itself under a method-derived key. None of the shipped
+ *     on-* packages need this; they all operate on `newDeks`.
+ *
+ * The ceremony MUST preserve `oldSlot.id` and `oldSlot.method` in the
+ * returned `EnrollAuthenticatorOptions`. Hub validates these — a
+ * mismatch throws `ValidationError` (prevents slot-type swap mid-
+ * rotation, e.g. converting a webauthn slot to a password slot under
+ * cover of preservation).
+ */
+interface SlotRewrapContext {
+    readonly newKek: CryptoKey;
+    readonly newDeks: Map<string, CryptoKey>;
+    readonly oldSlot: KeyringAuthenticator;
+}
+/**
+ * Callback that re-enrolls one tier-2 slot during `rotatePassphrase`.
+ * Returns the new slot's `EnrollAuthenticatorOptions` — same shape
+ * the consumer would pass to `db.enrollAuthenticator` for a fresh
+ * enrollment. Hub persists the result atomically with the rotation.
+ */
+type SlotRewrapCeremony = (ctx: SlotRewrapContext) => Promise<EnrollAuthenticatorOptions>;
 /** Caller payload for {@link rotatePassphrase}. */
 interface RotatePassphraseInput {
     readonly oldPassphrase: string;
     readonly newPassphrase: string;
     readonly passphrasePolicy?: PassphrasePolicy;
     readonly allowWeakPassphrase?: boolean;
+    /**
+     * Map of slot id → re-enrolment ceremony. Slots whose id appears
+     * here are PRESERVED across rotation (the ceremony re-derives the
+     * method-specific wrapping under the new keyring); slots whose id
+     * is absent are DROPPED (the pre-#29 behavior).
+     *
+     * Without this map, `rotatePassphrase` retains the pre-pre.8
+     * behavior of wiping every tier-2 slot. Consumers building a
+     * "rotate without losing my biometric" flow supply ceremonies for
+     * each slot they want to keep.
+     *
+     * If a ceremony throws, the entire rotation throws — no partial
+     * state. Callers wrap individual ceremonies in try/catch + return
+     * a sentinel if they want graceful degradation per slot.
+     *
+     * Added in pre.8 (#29).
+     */
+    readonly slotCeremonies?: {
+        readonly [slotId: string]: SlotRewrapCeremony;
+    };
 }
 /**
  * Re-derive the user's KEK from `oldPassphrase`, rewrap every DEK
  * under a freshly-derived KEK from `newPassphrase`, and persist.
  *
- * Tier-2 authenticator slots are NOT preserved — each slot wraps the
- * old KEK and would need the user's per-slot derivation key to
- * re-wrap; the hub doesn't hold that. The user re-enrols any slots
- * after rotation. v0.1.0-pre.5 limitation.
+ * Tier-2 authenticator slots are dropped UNLESS the caller supplies
+ * a `slotCeremonies` map (#29) — each ceremony re-derives its
+ * method-specific wrapping under the new keyring, and hub persists
+ * the rewrapped slots atomically with the rotation. Slots whose id
+ * isn't in the map are still dropped (pre-pre.8 behavior).
  *
  * @throws `InvalidKeyError` if `oldPassphrase` does not unwrap the keyring.
  * @throws `WeakPassphraseError` if `newPassphrase` fails the strength rule.
+ * @throws `ValidationError` if a ceremony's result mismatches the
+ *         slot's id or method (anti-slot-swap guard).
  */
 declare function rotatePassphrase(store: NoydbStore, vault: string, userId: string, input: RotatePassphraseInput): Promise<UnlockedKeyring>;
 /** Caller payload for {@link recoverPassphrase}. */
@@ -2949,6 +3151,58 @@ interface RecoverPassphraseInput {
     readonly recoveryProof: RecoveryProof;
     readonly passphrasePolicy?: PassphrasePolicy;
     readonly allowWeakPassphrase?: boolean;
+    /**
+     * After a successful paper-recovery, replace ALL remaining recovery
+     * entries with freshly-minted ones. Defaults to `true` (defensive).
+     *
+     * Rationale (issue #36): the user just demonstrated they had access
+     * to AT LEAST one code. The remaining codes from the same printed
+     * sheet may also be compromised — photographed, leaked via a
+     * screen-share slip, or in the hands of whoever stole the sheet.
+     * Auto-rotation closes the window without requiring consumer action.
+     *
+     * Set to `false` to preserve the original behavior (only the matched
+     * code is burned; the rest stay valid).
+     *
+     * Hub-side orchestration is non-atomic with the recovery itself:
+     * if the rotation step fails after a successful burn, the user
+     * falls back to the pre-rotation state (remaining codes still
+     * valid). Strictly safer than the previous default — a failed
+     * rotation degrades gracefully rather than leaving the vault
+     * locked or codes dual-existing.
+     */
+    readonly rotateRemainingCodes?: boolean;
+    /**
+     * Number of fresh codes to mint when `rotateRemainingCodes` is on.
+     * Defaults to the count of remaining entries POST-burn (e.g. if
+     * the user enrolled 8 originally and just consumed 1, defaults to
+     * 7). Pass an explicit number to mint a different count — useful
+     * when the consumer wants to refresh to a target N regardless of
+     * how many were left.
+     */
+    readonly newCodeCount?: number;
+    /**
+     * Override the default raw-code generator. The default is hub's
+     * {@link generateULID} — uppercase Crockford-Base32, 26 chars,
+     * passes through `normalizePaperCode` untouched.
+     *
+     * Pass `() => generateRawCode()` from `@noy-db/on-recovery` when
+     * the consumer prefers the Base32 + checksum format with hyphenated
+     * display. The `mintPaperRecoveryEntry` helper accepts any string —
+     * the generator just needs to produce a high-entropy unique value.
+     */
+    readonly codeGenerator?: () => string;
+}
+/**
+ * Return shape of `db.recoverPassphrase`. `newCodes` is populated when
+ * `rotateRemainingCodes` was enabled and at least one entry was
+ * rotated; an empty array means no rotation happened (rotation
+ * disabled, or no remaining codes after burn). Show the codes to the
+ * user once — they are the canonical credential for future recovery
+ * and CANNOT be retrieved again.
+ */
+interface RecoverPassphraseResult {
+    readonly newCodes: readonly string[];
 }
 /**
  * Reset the user's passphrase using a recovery proof. v0.1.0-pre.5
@@ -2961,6 +3215,172 @@ interface RecoverPassphraseInput {
  */
 declare function recoverPassphrase(store: NoydbStore, vault: string, userId: string, input: RecoverPassphraseInput): Promise<UnlockedKeyring>;
 
+/**
+ * Atomic peer-recovery primitive — issues #33 + #34.
+ *
+ * `recoverUser` is a SEPARATE operation from `revoke + grant`. It
+ * exists because peer-recovery has different semantics than account
+ * removal-then-reissue:
+ *
+ *   1. **Same identity preserved.** `userId`, `role`, `permissions`,
+ *      capability bits, user envelope (if any), policy override (if
+ *      any) all survive. Only the wrapping changes.
+ *   2. **No key rotation.** The existing DEKs stay valid — every
+ *      OTHER principal in the vault keeps their access. Rotating
+ *      keys would invalidate every co-user's wrapping.
+ *   3. **Atomic by construction.** A single `store.put` overwrites
+ *      `_keyring/<userId>` with the recovered file. No revoke step
+ *      means no partial-failure window.
+ *   4. **Owner→owner natively allowed.** Two co-owners recovering
+ *      each other is the explicitly-intentional case (a partner
+ *      forgot the master phrase). The existing `canRevoke` rule that
+ *      blocks owner→owner is correct for `revoke` (which is account
+ *      *removal*) and intentionally NOT replicated here. The policy
+ *      gate `peer-recover-user` carries the freshness requirement.
+ *   5. **Tier-2 slots dropped.** The slots wrap the OLD KEK under
+ *      method-derived keys; after recovery the KEK is re-derived
+ *      from the new temp passphrase. Match `rotatePassphrase`'s
+ *      precedent — the recovered user re-enrols slots after picking
+ *      their own phrase.
+ *
+ * Caller must be at least as privileged as the target. The hub
+ * `db.recoverUser` method gates this with the `peer-recover-user`
+ * policy gate (#33's factor-proof requirement); the function below
+ * enforces only the role + anti-privilege-escalation invariants.
+ *
+ * @module
+ */
+
+/** Input shape for {@link recoverUser}. */
+interface RecoverUserOptions {
+    /** Target user id whose keyring is being recovered. */
+    readonly userId: string;
+    /**
+     * Temporary passphrase under which the new keyring is wrapped.
+     * The recipient should call `db.rotatePassphrase` immediately on
+     * acceptance to choose their own phrase — this temp acts as a
+     * single-use bridge in invite / peer-recovery flows.
+     */
+    readonly passphrase: string;
+    /** Override the target's role. Defaults to the existing target's role. */
+    readonly role?: Role;
+    /** Override the target's display name. Defaults to existing. */
+    readonly displayName?: string;
+    /** Validate phrase strength against the configured policy. */
+    readonly validatePassphrase?: boolean;
+    /**
+     * Skip phrase strength validation even when `validatePassphrase` is
+     * set. The escape hatch matches `grant`'s shape — used when the
+     * temp phrase is a high-entropy one-shot string that doesn't need
+     * to satisfy the human-typeable rules.
+     */
+    readonly allowWeakPassphrase?: boolean;
+    /**
+     * Optional explicit phrase policy override (passed through to
+     * `assertStrongPassphrase`). Mirrors how `grant` accepts a custom
+     * `PassphrasePolicy` for app-specific tightening.
+     */
+    readonly passphrasePolicy?: PassphrasePolicy;
+}
+/**
+ * Atomically rewrap the target user's keyring under a fresh temp
+ * passphrase. Single store write; no revoke step; no key rotation.
+ *
+ * Caller's responsibilities (NOT enforced here):
+ *   - Run the `peer-recover-user` policy gate first via
+ *     `Noydb.checkGate` to enforce the freshness factor proof.
+ *   - Communicate the temp passphrase to the recipient via a secure
+ *     channel (URL fragment, in-person, etc.) — the hub does not
+ *     transport secrets.
+ */
+declare function recoverUser(store: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: RecoverUserOptions): Promise<void>;
+
+/**
+ * **Wrap-DEKs primitive (#44)** — a single canonical shape for the
+ * pattern of "serialize a DEK set, encrypt it under a credential-derived
+ * AES-GCM key." Used by:
+ *
+ *   - **tier-0** — paper recovery entries (`_meta/recovery-paper`),
+ *     credential = the printed code.
+ *   - **tier-2** — password authenticator slots (`KeyringFile.authenticators`,
+ *     `wrapKind: 'deks'`), credential = the daily password.
+ *
+ * **Not** used by `@noy-db/on-pin` — tier-3 wraps the DEK set under
+ * the same conceptual pattern but at **100,000 PBKDF2 iterations**
+ * (vs the 600,000 here), because the protection window for a PIN
+ * slot is short (idle-timeout-bounded, typically 15 min) and 600k
+ * iterations would make every PIN-resume noticeably slow. The wire
+ * formats are deliberately incompatible. See `@noy-db/on-pin`'s
+ * `PIN_PBKDF2_ITERATIONS` and the threat-model rationale in its
+ * module docstring.
+ *
+ * Before #44, the same crypto lived in two places: `mintPaperRecoveryEntry`
+ * (in `team/recovery.ts`) and `enrollPasswordAuthenticator` (in
+ * `@noy-db/on-password`). Both functions did identical work — PBKDF2
+ * the credential, AES-GCM-encrypt the JSON-serialized DEK set — but
+ * their implementations had drifted apart enough that fixing a bug
+ * in one wouldn't fix the other.
+ *
+ * This module owns the canonical implementation. Consumers compose:
+ *
+ *   - `mintPaperRecoveryEntry` is now a thin wrapper that calls
+ *     `mintWrappedDeksBlob` and adds `{ codeId, enrolledAt }`.
+ *   - `enrollPasswordAuthenticator` calls `mintWrappedDeksBlob` and
+ *     wraps the result in the slot envelope.
+ *
+ * @module
+ */
+/**
+ * The wrap-DEKs primitive — a serialized + AES-GCM-encrypted DEK set
+ * keyed under a credential-derived key.
+ *
+ * All three fields are base64-encoded so the blob is JSON-safe and
+ * round-trips through `_meta/*` envelopes (which carry plaintext
+ * JSON in `_data`).
+ *
+ * Composition: `PaperRecoveryEntry extends WrappedDeksBlob` plus
+ * `{ codeId, enrolledAt }`. `KeyringAuthenticatorWrappingDEKs`
+ * carries the same three fields with `salt` stored in `meta` for
+ * slot-format back-compat (#44 defers moving it to top-level).
+ */
+interface WrappedDeksBlob {
+    /** Base64 PBKDF2 salt for the credential-derived wrapping key. */
+    readonly salt: string;
+    /** Base64 AES-GCM IV used for the `wrappedDeks` ciphertext. */
+    readonly iv: string;
+    /** Base64 AES-GCM ciphertext of `{ deks: { collection: base64rawDek } }`. */
+    readonly wrappedDeks: string;
+}
+/**
+ * Mint a fresh `WrappedDeksBlob` from a DEK set + a string credential.
+ *
+ * Generates a random salt + IV, derives a 256-bit AES-GCM key via
+ * PBKDF2-SHA256(credential, salt, 600K), serializes the DEK set as
+ * `{ deks: { coll: rawBase64 } }`, and AES-GCM-encrypts.
+ *
+ * The `credential` is the user-typed string (recovery code, daily
+ * password, PIN). Caller normalization rules apply (e.g. paper
+ * recovery uppercase-strips the code before reaching this function).
+ *
+ * @param deks - DEK set to wrap. Each DEK must be exportable via
+ *               `subtle.exportKey('raw', dek)` (the hub mints DEKs
+ *               this way; consumers feeding non-extractable keys
+ *               will get `InvalidAccessError` from WebCrypto).
+ * @param credential - String input the consumer minted (paper code,
+ *               password, PIN). Treated as opaque bytes by PBKDF2.
+ */
+declare function mintWrappedDeksBlob(deks: Map<string, CryptoKey>, credential: string): Promise<WrappedDeksBlob>;
+/**
+ * Reverse of {@link mintWrappedDeksBlob}. Re-derives the wrapping key
+ * from the credential + stored salt, AES-GCM-decrypts the wrapped DEK
+ * set, and re-imports each DEK as an extractable AES-GCM CryptoKey.
+ *
+ * Throws (AES-GCM auth tag failure) when the credential doesn't
+ * match the blob. Callers iterating over multiple blobs (e.g. paper
+ * recovery's "try every entry until one matches") should catch.
+ */
+declare function unwrapDeksFromBlob(blob: WrappedDeksBlob, credential: string): Promise<Map<string, CryptoKey>>;
+
 /**
  * Recovery profile persistence + dispatch — issue #10.
  *
@@ -3000,15 +3420,15 @@ declare function recoverPassphrase(store: NoydbStore, vault: string, userId: str
  * resume — the cryptographic guarantee is identical (AES-GCM with a
  * PBKDF2-derived key), and it sidesteps the non-extractable-KEK
  * constraint cleanly.
+ *
+ * Type-level composition (#44): `PaperRecoveryEntry extends
+ * WrappedDeksBlob` — the three crypto fields (`salt`, `iv`,
+ * `wrappedDeks`) come from the shared primitive; `codeId` and
+ * `enrolledAt` are paper-recovery's own metadata. Wire format
+ * unchanged.
  */
-interface PaperRecoveryEntry {
+interface PaperRecoveryEntry extends WrappedDeksBlob {
     readonly codeId: string;
-    /** Base64 PBKDF2 salt. */
-    readonly salt: string;
-    /** Base64 AES-GCM IV used for the wrapped-DEK ciphertext. */
-    readonly iv: string;
-    /** Base64 AES-GCM ciphertext — JSON `{ deks: Record<string, base64> }`. */
-    readonly wrappedDeks: string;
     readonly enrolledAt: string;
 }
 interface PaperRecoveryDoc {
@@ -3024,6 +3444,33 @@ declare function savePaperRecoveryEntries(store: NoydbStore, vault: string, entr
 declare function burnPaperRecoveryEntry(store: NoydbStore, vault: string, codeId: string): Promise<void>;
 /** Whether at least one recovery profile has any enrolled entries. */
 declare function hasRecoveryEnrolled(store: NoydbStore, vault: string): Promise<boolean>;
+/**
+ * Generate one paper-recovery entry from an unlocked DEK set.
+ *
+ * Returns the serializable entry (persisted via
+ * {@link savePaperRecoveryEntries}). The recovery flow unwraps the
+ * DEK set, then mints a fresh KEK from the user's new passphrase.
+ *
+ * Thin wrapper over {@link mintWrappedDeksBlob} (#44) — the crypto
+ * lives in the shared primitive; this function just adds paper-
+ * recovery's own metadata (`codeId`, `enrolledAt`).
+ *
+ * @param deks      Map of collection-name → DEK (extractable).
+ * @param code      The plaintext recovery code (caller-supplied;
+ *                  pair this with `@noy-db/on-recovery`'s code
+ *                  generator/parser if available).
+ * @param codeId    Stable id used by `burnPaperRecoveryEntry`.
+ */
+declare function mintPaperRecoveryEntry(deks: Map<string, CryptoKey>, code: string, codeId: string): Promise<PaperRecoveryEntry>;
+/**
+ * Decrypt a recovery entry to recover the raw DEK set. Used by the
+ * `recoverPassphrase` flow after the user's code has been parsed.
+ *
+ * Thin wrapper over {@link unwrapDeksFromBlob} (#44).
+ *
+ * @throws when the code does not match the entry (AES-GCM auth tag fail).
+ */
+declare function unwrapDeksFromPaperEntry(entry: PaperRecoveryEntry, code: string): Promise<Map<string, CryptoKey>>;
 
 /**
  * Public envelope — owner-curated plaintext metadata, readable
@@ -3130,51 +3577,6 @@ declare function validatePublicEnvelopeInput(input: SetPublicEnvelopeInput, sche
  */
 declare function isPublicEnvelope(x: unknown): x is PublicEnvelope;
 
-/**
- * Tier-2 authenticator slot management — issue #11.
- *
- * Each slot independently wraps the SAME KEK under a method-specific
- * derived key (LUKS pattern). Enrolling adds a slot; removing drops
- * one. Both are constant-time keyring writes — no DEK re-keying.
- *
- * The crypto for each method lives in its `@noy-db/on-*` package
- * (`on-webauthn`, `on-oidc`, `on-password`); this module accepts the
- * package's `wrapped_kek` ciphertext + `meta` payload and persists it.
- *
- * @see docs/subsystems/session-tiers.md → Tier 2 — Authenticate
- *
- * @module
- */
-
-/** Input shape for `enrollAuthenticator`. */
-interface EnrollAuthenticatorOptions {
-    readonly id: string;
-    readonly method: KeyringAuthenticator['method'];
-    /** Already-wrapped KEK ciphertext (base64) — produced by the on-* package. */
-    readonly wrapped_kek: string;
-    /** Method-specific metadata (cred id, salt, …). */
-    readonly meta: Record<string, unknown>;
-    /** Tier the active session held when enrolling. Defaults to 1. */
-    readonly enrolled_via_tier?: 1 | 2;
-}
-/**
- * Append a new authenticator slot to the keyring file. Throws
- * `ValidationError` if a slot with the same id already exists — the
- * caller decides whether to remove + re-enroll.
- */
-declare function enrollAuthenticator(store: NoydbStore, vault: string, keyring: UnlockedKeyring, options: EnrollAuthenticatorOptions): Promise<UnlockedKeyring>;
-/**
- * Drop a slot by id. No-op if the slot doesn't exist (idempotent —
- * removing a non-existent slot is a recoverable retry, not an error).
- */
-declare function removeAuthenticator(store: NoydbStore, vault: string, keyring: UnlockedKeyring, slotId: string): Promise<UnlockedKeyring>;
-/**
- * Look up a slot by id. Returns `undefined` when no slot matches.
- * Used by tier-2 unlock dispatchers to fetch the wrapped KEK + meta
- * before invoking the method-specific verifier.
- */
-declare function findAuthenticator(keyring: UnlockedKeyring, slotId: string): KeyringAuthenticator | undefined;
-
 /**
  * Per-vault tier-3 (PIN / quick-resume) state — issue #11.
  *
@@ -3375,8 +3777,35 @@ declare function runTransaction<T>(db: Noydb, fn: (tx: TxContext) => Promise<T>
  * @module
  */
 
-/** A single off-device factor surface — the proof an actor presents at gate time. */
-type FactorKind = 'totp' | 'email-otp' | 'recovery' | 'shamir' | 'webauthn-roaming';
+/**
+ * A single factor surface — the proof an actor presents at gate time.
+ *
+ * | Kind | Source | Off-device? |
+ * |---|---|---|
+ * | `totp` | RFC 6238 authenticator app (Google Auth, 1Password) | yes |
+ * | `email-otp` | one-time code mailed to the user | yes |
+ * | `recovery` | printable Base32 code (`@noy-db/on-recovery`) | yes (paper) |
+ * | `shamir` | k-of-n threshold share (`@noy-db/on-shamir`) | yes |
+ * | `webauthn-roaming` | hardware key (YubiKey, SoloKey, Titan) | yes (key portable) |
+ * | `webauthn-platform` | platform passkey (Touch ID, Face ID, Hello) | no (device-bound) |
+ * | `password` | tier-2 daily password (`@noy-db/on-password`) | no |
+ * | `pin` | tier-3 quick-resume PIN (`@noy-db/on-pin`) | no |
+ *
+ * Off-device kinds (TOTP, email-OTP, recovery, shamir, roaming WebAuthn)
+ * are the strongest factor proofs because they require something
+ * separate from the device the user just unlocked. Platform / password /
+ * PIN are useful for "fresh proof of *this* user" but don't bind across
+ * devices — policies can require ANY of them or insist on a count of 2
+ * to force a mix.
+ *
+ * Added in pre.8 (#30): `webauthn-platform`, `password`, `pin` —
+ * previously consumers with no off-device infrastructure (no TOTP,
+ * no email-OTP, paper recovery not enrolled) had to disable the
+ * factor requirement entirely on `rotate-passphrase`. Now they can
+ * pin "any second factor I have wired" without losing the freshness
+ * guarantee.
+ */
+type FactorKind = 'totp' | 'email-otp' | 'recovery' | 'shamir' | 'webauthn-roaming' | 'webauthn-platform' | 'password' | 'pin';
 /**
  * One factor requirement entry. The default is "any one of the listed
  * factors, fresh within the last 5 minutes". Bumping `count` requires N
@@ -3415,11 +3844,39 @@ interface GatePolicy {
  * and use the same engine; the engine treats unknown names with no
  * configured policy as "no gate" (no-op).
  */
-type BuiltInGateName = 'rotate-passphrase' | 'recover-passphrase' | 'enroll-authenticator' | 'remove-authenticator' | 'rotate-unlock' | 'enroll-user' | 'revoke-user' | 'export-bundle' | 'export-plaintext' | 'view-user-auth'
+type BuiltInGateName = 'rotate-passphrase' | 'recover-passphrase' | 'enroll-authenticator' | 'remove-authenticator'
+/**
+ * Authorize a meta-only mutation on an existing authenticator slot —
+ * `db.updateAuthenticator` (#55). The slot's wrap material, id, and
+ * method are immutable through this gate; only the `meta` blob
+ * (nicknames, method-specific labels) can change. Anti-slot-swap
+ * guard is preserved structurally regardless of this gate's
+ * settings.
+ */
+ | 'update-authenticator' | 'rotate-unlock' | 'enroll-user' | 'revoke-user' | 'export-bundle' | 'export-plaintext' | 'view-user-auth'
 /** Authorize a write to one's own user envelope (#22). */
  | 'edit-own-profile'
 /** Authorize reading other principals' user envelopes (#22). */
- | 'view-team-profiles';
+ | 'view-team-profiles'
+/**
+ * Authorize an atomic peer-recovery — `db.recoverUser` (#33, #34).
+ * Distinct from `revoke-user` because peer-recovery is intentional
+ * re-issuance of someone's keyring under a temp passphrase, NOT
+ * removal. Allows owner→owner natively (matches the threat model:
+ * a co-owner explicitly recovering another co-owner). Ships with a
+ * factor-proof default in `STRICT_POLICY` so the issuer must
+ * affirmatively prove identity at the moment of recovery.
+ */
+ | 'peer-recover-user'
+/**
+ * Authorize a post-grant identity mutation — `db.updateUser` (#54).
+ * Covers `role`, `displayName`, `permissions` changes on an existing
+ * keyring. Pure plaintext-header rewrite — no DEKs touched, no KEK
+ * required. The role-elevation guard inside the implementation
+ * mirrors `db.grant`'s hierarchy (admin cannot promote to owner)
+ * regardless of this gate's settings.
+ */
+ | 'update-user';
 /** Either a built-in gate name or an `app:*` custom gate. */
 type GateName = BuiltInGateName | `app:${string}`;
 /**
@@ -3519,6 +3976,52 @@ declare class Noydb {
     grant(vault: string, options: GrantOptions): Promise<void>;
     /** Revoke a user's access to a vault. */
     revoke(vault: string, options: RevokeOptions): Promise<void>;
+    /**
+     * Mutate post-grant identity fields on an existing keyring — `role`,
+     * `displayName`, and/or `permissions`. Pure plaintext-header rewrite:
+     * no DEK rewrap, no KEK required, no authenticator slots touched.
+     * Tier-2 enrollments and recovery codes survive.
+     *
+     * Different from `db.revoke + db.grant`:
+     *
+     *   - Same `userId`, same DEK wrappings, same `granted_by`, same
+     *     `_users/<keyringId>` envelope. Only the specified header
+     *     fields move. Last-write-wins via the standard keyring put.
+     *   - No cascade on role demotion (admins demoted to operator keep
+     *     the keyrings they previously granted; the cascade rules are
+     *     a `db.revoke` concern, not `db.updateUser`).
+     *   - Tier-2 slots NOT dropped — the wrapping is unaffected.
+     *
+     * Role-elevation guard: BOTH the old and new role must satisfy
+     * `db.grant`'s hierarchy. Owner can do anything; admin manages
+     * admin/operator/viewer/client laterally; admin cannot promote to
+     * owner OR demote from owner. The guard runs regardless of the
+     * `update-user` policy gate's settings — gates can only be more
+     * permissive than the structural floor, never less.
+     *
+     * Gated by `update-user`. `STRICT_POLICY` requires a TOTP/email-OTP
+     * factor proof so the operator affirmatively re-asserts identity at
+     * the moment of mutation; `PERSONAL_POLICY` accepts a tier-1 unlock
+     * alone.
+     *
+     * ```ts
+     * await db.updateUser('acme', {
+     *   userId: 'bob',
+     *   role: 'operator',                 // promote
+     *   permissions: { invoices: 'rw' },
+     * }, { factors: [{ kind: 'totp' }] })
+     * ```
+     *
+     * @throws `NoAccessError` when no keyring exists for the target.
+     * @throws `PermissionDeniedError` when the role hierarchy rejects.
+     * @throws `ValidationError` when no field is provided.
+     *
+     * @see #54
+     */
+    updateUser(vault: string, options: UpdateUserOptions, factors?: {
+        factors?: ReadonlyArray<FactorProof>;
+        sharedDevice?: boolean;
+    }): Promise<void>;
     /**
      * Rotate the DEKs for the given collections in a vault.
      *
@@ -3817,6 +4320,38 @@ declare class Noydb {
     }): Promise<void>;
     /** Read the slot list for a vault. Internal — `describeAuthConfig` (#13) consumes this. */
     listAuthenticators(vault: string): Promise<ReadonlyArray<KeyringAuthenticator>>;
+    /**
+     * Mutate the `meta` blob on an existing authenticator slot — slot
+     * rename, label change, attachment of UI hints. The slot's `id`,
+     * `method`, and wrap material (`wrapped_kek` / `wrapped_deks` + `iv`)
+     * are immutable through this method. Anti-slot-swap is structural,
+     * not gate-driven.
+     *
+     * `meta` patch semantics (#57-aligned):
+     *   - Top-level merge — absent keys preserved
+     *   - `null` value — delete that meta key
+     *   - Other values — replace verbatim
+     *
+     * Use case: per-slot nickname for "iPhone Touch ID" vs "MacBook
+     * Touch ID" disambiguation in admin UIs. The slot id (auto-derived
+     * from credentialId prefix) is not human-friendly; `meta.nickname`
+     * is.
+     *
+     * Gated by `update-authenticator`. PERSONAL_POLICY: tier-1 unlock
+     * alone (matches enroll/remove). STRICT_POLICY: tier-1 +
+     * TOTP/email-OTP factor proof — a malicious rename on a shared
+     * workstation could mislead the user about which device a slot
+     * corresponds to, so STRICT requires fresh factor binding.
+     *
+     * @throws `NoAccessError` when no slot with the given id exists.
+     * @throws `ValidationError` when no patch field is provided.
+     *
+     * @see #55
+     */
+    updateAuthenticator(vault: string, slotId: string, options: UpdateAuthenticatorOptions, presented?: {
+        factors?: ReadonlyArray<FactorProof>;
+        sharedDevice?: boolean;
+    }): Promise<void>;
     /**
      * Native WebAuthn enrollment using the **real** internal keyring (#16).
      *
@@ -3968,20 +4503,84 @@ declare class Noydb {
     recoverPassphrase(vault: string, input: RecoverPassphraseInput, factors?: {
         factors?: ReadonlyArray<FactorProof>;
         sharedDevice?: boolean;
+    }): Promise<RecoverPassphraseResult>;
+    /**
+     * 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.
+     */
+    recoverUser(vault: string, options: RecoverUserOptions, factors?: {
+        factors?: ReadonlyArray<FactorProof>;
+        sharedDevice?: boolean;
     }): Promise<void>;
     /**
      * 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 })
+     * ```
      */
     enrollRecovery(vault: string, enrollment: {
         profile: 'paper';
@@ -4016,8 +4615,30 @@ declare class Noydb {
     unlockViaPin(vault: string, resume: (state: QuickUnlockState) => Promise<UnlockedKeyring>): Promise<UnlockedKeyring | undefined>;
     /** Drop the tier-3 state for a vault — explicit logout. */
     clearQuickUnlock(vault: string): void;
-    /** Get or load the keyring for a vault. */
-    private getKeyring;
+    /**
+     * 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
+     * ```
+     */
+    getKeyring(vault: string): Promise<UnlockedKeyring>;
 }
 /** Create a new NOYDB instance. */
 declare function createNoydb(options: NoydbOptions): Promise<Noydb>;
@@ -4509,6 +5130,24 @@ declare function isMagicLinkGrantExpired(payload: MagicLinkGrantPayload, now?: D
 type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
+/**
+ * Recursive partial with `null` allowed at every level — used by
+ * `updateMe` (#57) to express deletion intent in addition to merge.
+ *
+ * Semantics inside `updateMe`:
+ *   - `undefined` (or absent key) — skip; source value preserved
+ *   - `null` — delete the key from the resulting envelope
+ *   - any other value — overwrite (deep-merge for plain objects,
+ *     replace for primitives / arrays)
+ *
+ * Matches lodash `_.merge` behavior on `null` and Firestore's
+ * `FieldValue.delete()` semantics. Loosened from `DeepPartial<T>` per
+ * #57; consumers wanting the original "merge-only" surface can keep
+ * importing `DeepPartial` and avoid passing `null`.
+ */
+type DeepPartialOrNull<T> = T extends object ? {
+    [P in keyof T]?: DeepPartialOrNull<T[P]> | null;
+} : T;
 /** Cancel a previously-registered subscription. */
 type Unsubscribe = () => void;
 /**
@@ -4575,11 +5214,22 @@ declare class UserApi {
      * the envelope on first call. Optimistic-concurrency safe — a stale
      * `_v` (parallel writer on another device) throws `ConflictError`.
      *
+     * Patch semantics (#57):
+     *   - `undefined` (or omitted key) — skip; existing value preserved
+     *   - `null` — delete the field from the merged result
+     *   - any other value — overwrite (deep-merge for plain objects,
+     *     replace for primitives / arrays)
+     *
+     * To clear a field, pass `null` rather than `undefined`. Callers
+     * with shape `T = string | null` where `null` is a meaningful value
+     * should use `setMe` for that specific field instead — `null` here
+     * always means delete.
+     *
      * 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).
      */
-    updateMe<T extends object = Record<string, unknown>>(patch: DeepPartial<T>, presented?: UserEnvelopePresented): Promise<UserEnvelope<T>>;
+    updateMe<T extends object = Record<string, unknown>>(patch: DeepPartialOrNull<T>, presented?: UserEnvelopePresented): Promise<UserEnvelope<T>>;
     /**
      * Replace the writer's own envelope with `payload`. Use sparingly —
      * `updateMe` is the canonical mutation. No `expectedVersion` check;
@@ -7588,7 +8238,13 @@ type RecoveryEnrollment = {
  *
  * @see docs/subsystems/session-tiers.md → Tier 2 — Authenticate (multi-slot)
  */
-interface KeyringAuthenticator {
+/**
+ * Shared fields across all authenticator slot variants. The variant
+ * (`KeyringAuthenticatorWrappingKEK` vs `KeyringAuthenticatorWrappingDEKs`)
+ * carries the actual wrapped material; everything below is identity +
+ * metadata only.
+ */
+interface KeyringAuthenticatorBase {
     /** Caller-chosen identifier — e.g. `'webauthn-yubikey-blue'`, `'oidc-google'`, `'password-daily'`. */
     readonly id: string;
     /** Method family — selects which `@noy-db/on-*` package handles unlock. */
@@ -7600,8 +8256,6 @@ interface KeyringAuthenticator {
      * tier 2 may add a sibling slot when the active policy permits.
      */
     readonly enrolled_via_tier: 1 | 2;
-    /** Base64 wrapped-KEK ciphertext under the method-derived key. */
-    readonly wrapped_kek: string;
     /**
      * Method-specific metadata: WebAuthn cred id, OIDC issuer/sub, PBKDF2
      * salt for `on-password`, etc. The schema is open by design — the
@@ -7609,6 +8263,63 @@ interface KeyringAuthenticator {
      */
     readonly meta: Record<string, unknown>;
 }
+/**
+ * Slot that wraps the KEK directly under a method-derived AES-KW key.
+ * Used by ceremonies where the on-* package can produce/recover an
+ * extractable KEK from its own credential — WebAuthn (PRF-derived
+ * wrapping key) and split-key OIDC.
+ *
+ * `wrapKind` is optional/absent on slots written before pre.8 — those
+ * legacy slots are treated as wrap-KEK by default at unlock time.
+ */
+interface KeyringAuthenticatorWrappingKEK extends KeyringAuthenticatorBase {
+    readonly wrapKind?: 'kek';
+    /** Base64 wrapped-KEK ciphertext under the method-derived key. */
+    readonly wrapped_kek: string;
+    /** XOR guard — wrap-KEK slots must NOT carry wrap-DEKs material. */
+    readonly wrapped_deks?: never;
+    /** XOR guard — wrap-KEK slots must NOT carry wrap-DEKs material. */
+    readonly iv?: never;
+}
+/**
+ * Slot that wraps the DEK set (not the KEK) under a method-derived
+ * AES-GCM key — sidesteps the non-extractable-KEK constraint by
+ * encrypting the serialized `{ deks: { collection: rawDekBase64 } }`
+ * directly. Mirrors the format used by `mintPaperRecoveryEntry`
+ * (`PaperRecoveryEntry`) and `@noy-db/on-pin`'s `PinResumeState` —
+ * the unified wrap-DEKs primitive across tier-0 / tier-2 / tier-3.
+ *
+ * Trade-off: a slot of this kind reconstructs `UnlockedKeyring` with
+ * `kek: null` after unlock. That is semantically correct for tier-2
+ * (sensitive ops like `enrollAuthenticator` / `rotatePassphrase`
+ * require a tier-1 unlock anyway) and matches how `@noy-db/on-pin`
+ * already behaves at tier 3.
+ *
+ * @see `mintPaperRecoveryEntry` in `team/recovery.ts` — same shape on
+ *      a different on-disk path (`_meta/recovery-paper`).
+ */
+interface KeyringAuthenticatorWrappingDEKs extends KeyringAuthenticatorBase {
+    readonly wrapKind: 'deks';
+    /** Base64 AES-GCM ciphertext of `{ deks: { collection: base64rawDek } }`. */
+    readonly wrapped_deks: string;
+    /** Base64 AES-GCM IV used for the `wrapped_deks` ciphertext. */
+    readonly iv: string;
+    /** XOR guard — wrap-DEKs slots must NOT carry wrap-KEK material. */
+    readonly wrapped_kek?: never;
+}
+/**
+ * Discriminated union over the two wrap-format variants. Reads from
+ * disk should always go through this type so the variant is preserved.
+ *
+ * Discriminator: `wrapKind`. Absent → wrap-KEK (legacy / WebAuthn /
+ * OIDC). Present and `'deks'` → wrap-DEKs (password / future on-* that
+ * want to sidestep extractable-KEK).
+ *
+ * The type-level XOR enforces "exactly one of `wrapped_kek` /
+ * `wrapped_deks` is present" — a structural guarantee that the runtime
+ * dispatch is safe.
+ */
+type KeyringAuthenticator = KeyringAuthenticatorWrappingKEK | KeyringAuthenticatorWrappingDEKs;
 interface KeyringFile {
     readonly _noydb_keyring: typeof NOYDB_KEYRING_VERSION;
     readonly user_id: string;
@@ -8014,6 +8725,39 @@ interface GrantOptions {
      */
     readonly initialProfile?: unknown;
 }
+/**
+ * Caller payload for `db.updateUser` (#54). Mutate one or more
+ * identity fields on an existing keyring without rotating any keys.
+ *
+ * `role`, `displayName`, and `permissions` live in the plaintext header
+ * of `_keyring/<userId>` (the sync engine reads them without keys).
+ * Mutating them is a JSON header swap — no DEK rewrap, no KEK
+ * required, no authenticator slots touched. Tier-2 slots and recovery
+ * enrollments survive unchanged. Last-write-wins through the existing
+ * keyring put (same concurrency story as `db.grant` / `db.revoke`).
+ *
+ * Top-level fields are partial-merge: absent fields are not modified.
+ * `permissions`, however, is a **full replacement** at the map level —
+ * passing `{ invoices: 'rw' }` REPLACES the entire permissions map,
+ * silently dropping any other entries. To partially update, read the
+ * current keyring and merge: `permissions: { ...current, invoices: 'rw' }`.
+ * To clear all permissions, pass `permissions: {}` explicitly.
+ *
+ * Role-elevation guard: the same hierarchy as `db.grant`. Admins can
+ * change `admin` / `operator` / `viewer` / `client` to and from each
+ * other; admins cannot promote to or demote from `owner`. Owners can
+ * do anything. Non-admin callers (operator/viewer/client) cannot call
+ * `db.updateUser` at all — for self-displayName changes, use
+ * `vault.user.updateMe` (the user-envelope API).
+ *
+ * @see #54
+ */
+interface UpdateUserOptions {
+    readonly userId: string;
+    readonly role?: Role;
+    readonly displayName?: string;
+    readonly permissions?: Permissions;
+}
 interface RevokeOptions {
     readonly userId: string;
     readonly rotateKeys?: boolean;
@@ -8830,4 +9574,4 @@ interface DeleteManyResult {
     }>;
 }
 
-export { type ConsentAuditEntry as $, type BlobObject as A, type BlobStrategy as B, type BlobPutOptions as C, DICT_COLLECTION_PREFIX as D, type BlobResponseOptions as E, BlobSet as F, type BlobStrategyOpenArgs as G, type CompactRunOptions as H, type I18nStrategy as I, type CompactionContext as J, type CompactionResult as K, DEFAULT_CHUNK_SIZE as L, EXPORT_AUDIT_COLLECTION as M, ExportBlobsAbortedError as N, type ExportBlobsAuditEntry as O, PolicyEnforcer as P, type ExportBlobsHandle as Q, type ExportBlobsOptions as R, type SessionStrategy as S, type ExportedBlob as T, type SlotInfo as U, type SlotRecord as V, type VersionRecord as W, createExportBlobsHandle as X, runCompaction as Y, type ConsentStrategy as Z, CONSENT_AUDIT_COLLECTION as _, type DictEntry as a, type BuiltInGateName as a$, type ConsentAuditFilter as a0, type ConsentContext as a1, type ConsentOp as a2, loadConsentEntries as a3, writeConsentEntry as a4, type PeriodsStrategy as a5, type CarryForwardContext as a6, type ClosePeriodOptions as a7, type OpenPeriodOptions as a8, PERIODS_COLLECTION as a9, type DiffEntry as aA, type JsonPatch as aB, type JsonPatchOp as aC, type LedgerEntry as aD, LedgerStore as aE, type VaultEngine as aF, VaultInstant as aG, type VerifyResult as aH, applyPatch as aI, canonicalJson as aJ, computePatch as aK, diff as aL, formatDiff as aM, hashEntry as aN, paddedIndex as aO, parseIndex as aP, sha256Hex as aQ, type UserEnvelope as aR, type PublicEnvelope as aS, type GateName as aT, type GatePolicy as aU, type VaultPolicy as aV, type ActiveTier as aW, type FactorProof as aX, Vault as aY, type AccessibleVault as aZ, BUNDLE_STORE_POLICY as a_, type PeriodRecord as aa, type ReadOnlyCollection as ab, appendPeriodLedgerEntry as ac, assertTsWritable as ad, chainAnchor as ae, loadPeriods as af, validatePeriodName as ag, type ShadowStrategy as ah, CollectionFrame as ai, VaultFrame as aj, type TxStrategy as ak, TxCollection as al, TxContext as am, TxVault as an, runTransaction as ao, type SyncStrategy as ap, type Role as aq, type UnlockedKeyring as ar, type HistoryStrategy as as, type NoydbStore as at, type HistoryOptions as au, type EncryptedEnvelope as av, type PruneOptions as aw, type AppendInput as ax, type ChangeType as ay, CollectionInstant as az, type DictKeyDescriptor as b, type Permissions as b$, type BundleRecipient as b0, type CacheOptions as b1, type CacheStats as b2, type ChangeEvent as b3, Collection as b4, type CollectionChangeEvent as b5, type CollectionConflictResolver as b6, type Conflict as b7, type ConflictPolicy as b8, type ConflictStrategy as b9, type KeyringFile as bA, type ListAccessibleVaultsOptions as bB, type ListPageResult as bC, type LiveUserEnvelope as bD, type LocaleReadOptions as bE, Lru as bF, type LruOptions as bG, type LruStats as bH, MAGIC_LINK_CONTENT_INFO_PREFIX as bI, MAGIC_LINK_GRANTS_COLLECTION as bJ, MAGIC_LINK_KEK_INFO_PREFIX as bK, type MagicLinkGrantPayload as bL, type MagicLinkGrantRecord as bM, NOYDB_BACKUP_VERSION as bN, NOYDB_FORMAT_VERSION as bO, NOYDB_KEYRING_VERSION as bP, NOYDB_SYNC_VERSION as bQ, Noydb as bR, type NoydbBundleStore as bS, type NoydbEventMap as bT, type NoydbOptions as bU, PUBLIC_ENVELOPE_FIELDS as bV, type PaperRecoveryDoc as bW, type PaperRecoveryEntry as bX, type PassphrasePolicy as bY, type PassphraseValidationResult as bZ, type Permission as b_, type CrossTierAccessEvent as ba, DEFAULT_PUBLIC_ENVELOPE_SCHEMA as bb, DELEGATIONS_COLLECTION as bc, type DeepPartial as bd, type DelegationToken as be, type DeleteManyResult as bf, type DirtyEntry as bg, ELEVATION_AUDIT_COLLECTION as bh, ElevatedHandle as bi, type EnrollAuthenticatorOptions as bj, type ExportCapability as bk, type ExportChunk as bl, type ExportFormat as bm, type ExportStreamOptions as bn, type FactorKind as bo, type FactorRequirement as bp, type GhostRecord as bq, type GrantOptions as br, type HistoryConfig as bs, type HistoryEntry as bt, INDEXED_STORE_POLICY as bu, type ImportCapability as bv, type InferOutput as bw, type IssueDelegationOptions as bx, type IssueMagicLinkGrantOptions as by, type KeyringAuthenticator as bz, DictionaryHandle as c, assertStrongPassphrase as c$, type PlaintextTranslatorContext as c0, type PlaintextTranslatorFn as c1, PresenceHandle as c2, type PresencePeer as c3, type PublicEnvelopeField as c4, type PublicEnvelopeSchema as c5, type PublicEnvelopeText as c6, type PullMode as c7, type PullOptions as c8, type PullPolicy as c9, SyncEngine as cA, type SyncMetadata as cB, type SyncPolicy as cC, SyncScheduler as cD, type SyncSchedulerStatus as cE, type SyncStatus as cF, type SyncTarget as cG, type SyncTargetRole as cH, SyncTransaction as cI, type SyncTransactionResult as cJ, type TierMode as cK, type TranslatorAuditEntry as cL, type TxOp as cM, USER_ENVELOPE_COLLECTION as cN, USER_ENVELOPE_MAX_BYTES as cO, type Unsubscribe as cP, UserApi as cQ, type UserEnvelopeCheckGate as cR, UserEnvelopeOversizedError as cS, type UserEnvelopePresented as cT, type UserInfo as cU, type VaultBackup as cV, type VaultPolicyOnDisk as cW, type VaultSnapshot as cX, type WarningRules as cY, WeakPassphraseError as cZ, type WeakPassphraseReason as c_, type PullResult as ca, type PushMode as cb, type PushOptions as cc, type PushPolicy as cd, type PushResult as ce, type PutManyItemOptions as cf, type PutManyOptions as cg, type PutManyResult as ch, type QueryAcrossOptions as ci, type QueryAcrossResult as cj, type QuickUnlockState as ck, QuickUnlockStore as cl, type ReAuthOperation as cm, type RecoverPassphraseInput as cn, type RecoveryProof as co, type ResolvedPublicEnvelopeSchema as cp, type RevokeOptions as cq, type RotatePassphraseInput as cr, type SessionPolicy as cs, type SetPublicEnvelopeInput as ct, type StandardSchemaV1 as cu, type StandardSchemaV1Issue as cv, type StandardSchemaV1SyncResult as cw, type StoreAuth as cx, type StoreAuthKind as cy, type StoreCapabilities as cz, type DictionaryOptions as d, buildRecipientKeyringFile as d0, burnPaperRecoveryEntry as d1, createNoydb as d2, createStore as d3, deriveMagicLinkContentKey as d4, enrollAuthenticator as d5, estimateEntropy as d6, evaluateExportCapability as d7, evaluateImportCapability as d8, findAuthenticator as d9, writeMagicLinkGrant as dA, hasExportCapability as da, hasImportCapability as db, hasRecoveryEnrolled as dc, isMagicLinkGrantExpired as dd, isPublicEnvelope as de, issueDelegation as df, recoverPassphrase as dg, rotatePassphrase as dh, listMagicLinkGrants as di, listUsers as dj, listUsersWithEnvelopes as dk, loadActiveDelegations as dl, loadPaperRecoveryEntries as dm, magicLinkGrantRecordId as dn, readMagicLinkGrantRecord as dp, removeAuthenticator as dq, resolveSchema as dr, revokeDelegation as ds, revokeMagicLinkGrant as dt, savePaperRecoveryEntries as du, unwrapMagicLinkGrant as dv, validatePassphrase as dw, validatePublicEnvelopeInput as dx, validateSchemaInput as dy, validateSchemaOutput as dz, type I18nTextDescriptor as e, type I18nTextOptions as f, applyI18nLocale as g, dictCollectionName as h, dictKey as i, i18nText as j, isDictCollectionName as k, isDictKeyDescriptor as l, isI18nTextDescriptor as m, createEnforcer as n, validateSessionPolicy as o, BLOB_CHUNKS_COLLECTION as p, BLOB_COLLECTION as q, resolveI18nText as r, BLOB_EVICTION_AUDIT_COLLECTION as s, BLOB_INDEX_COLLECTION as t, BLOB_SLOTS_PREFIX as u, validateI18nTextValue as v, BLOB_VERSIONS_PREFIX as w, type BlobEvictionEntry as x, type BlobFieldPolicy as y, type BlobFieldsConfig as z };
+export { type ConsentAuditEntry as $, type BlobObject as A, type BlobStrategy as B, type BlobPutOptions as C, DICT_COLLECTION_PREFIX as D, type BlobResponseOptions as E, BlobSet as F, type BlobStrategyOpenArgs as G, type CompactRunOptions as H, type I18nStrategy as I, type CompactionContext as J, type CompactionResult as K, DEFAULT_CHUNK_SIZE as L, EXPORT_AUDIT_COLLECTION as M, ExportBlobsAbortedError as N, type ExportBlobsAuditEntry as O, PolicyEnforcer as P, type ExportBlobsHandle as Q, type ExportBlobsOptions as R, type SessionStrategy as S, type ExportedBlob as T, type SlotInfo as U, type SlotRecord as V, type VersionRecord as W, createExportBlobsHandle as X, runCompaction as Y, type ConsentStrategy as Z, CONSENT_AUDIT_COLLECTION as _, type DictEntry as a, type BuiltInGateName as a$, type ConsentAuditFilter as a0, type ConsentContext as a1, type ConsentOp as a2, loadConsentEntries as a3, writeConsentEntry as a4, type PeriodsStrategy as a5, type CarryForwardContext as a6, type ClosePeriodOptions as a7, type OpenPeriodOptions as a8, PERIODS_COLLECTION as a9, type DiffEntry as aA, type JsonPatch as aB, type JsonPatchOp as aC, type LedgerEntry as aD, LedgerStore as aE, type VaultEngine as aF, VaultInstant as aG, type VerifyResult as aH, applyPatch as aI, canonicalJson as aJ, computePatch as aK, diff as aL, formatDiff as aM, hashEntry as aN, paddedIndex as aO, parseIndex as aP, sha256Hex as aQ, type UserEnvelope as aR, type PublicEnvelope as aS, type GateName as aT, type GatePolicy as aU, type VaultPolicy as aV, type ActiveTier as aW, type FactorProof as aX, Vault as aY, type AccessibleVault as aZ, BUNDLE_STORE_POLICY as a_, type PeriodRecord as aa, type ReadOnlyCollection as ab, appendPeriodLedgerEntry as ac, assertTsWritable as ad, chainAnchor as ae, loadPeriods as af, validatePeriodName as ag, type ShadowStrategy as ah, CollectionFrame as ai, VaultFrame as aj, type TxStrategy as ak, TxCollection as al, TxContext as am, TxVault as an, runTransaction as ao, type SyncStrategy as ap, type Role as aq, type UnlockedKeyring as ar, type HistoryStrategy as as, type NoydbStore as at, type HistoryOptions as au, type EncryptedEnvelope as av, type PruneOptions as aw, type AppendInput as ax, type ChangeType as ay, CollectionInstant as az, type DictKeyDescriptor as b, type Permission as b$, type BundleRecipient as b0, type CacheOptions as b1, type CacheStats as b2, type ChangeEvent as b3, Collection as b4, type CollectionChangeEvent as b5, type CollectionConflictResolver as b6, type Conflict as b7, type ConflictPolicy as b8, type ConflictStrategy as b9, type KeyringAuthenticator as bA, type KeyringFile as bB, type ListAccessibleVaultsOptions as bC, type ListPageResult as bD, type LiveUserEnvelope as bE, type LocaleReadOptions as bF, Lru as bG, type LruOptions as bH, type LruStats as bI, MAGIC_LINK_CONTENT_INFO_PREFIX as bJ, MAGIC_LINK_GRANTS_COLLECTION as bK, MAGIC_LINK_KEK_INFO_PREFIX as bL, type MagicLinkGrantPayload as bM, type MagicLinkGrantRecord as bN, NOYDB_BACKUP_VERSION as bO, NOYDB_FORMAT_VERSION as bP, NOYDB_KEYRING_VERSION as bQ, NOYDB_SYNC_VERSION as bR, Noydb as bS, type NoydbBundleStore as bT, type NoydbEventMap as bU, type NoydbOptions as bV, PUBLIC_ENVELOPE_FIELDS as bW, type PaperRecoveryDoc as bX, type PaperRecoveryEntry as bY, type PassphrasePolicy as bZ, type PassphraseValidationResult as b_, type CrossTierAccessEvent as ba, DEFAULT_PUBLIC_ENVELOPE_SCHEMA as bb, DELEGATIONS_COLLECTION as bc, type DeepPartial as bd, type DeepPartialOrNull as be, type DelegationToken as bf, type DeleteManyResult as bg, type DirtyEntry as bh, ELEVATION_AUDIT_COLLECTION as bi, ElevatedHandle as bj, type EnrollAuthenticatorOptions as bk, type ExportCapability as bl, type ExportChunk as bm, type ExportFormat as bn, type ExportStreamOptions as bo, type FactorKind as bp, type FactorRequirement as bq, type GhostRecord as br, type GrantOptions as bs, type HistoryConfig as bt, type HistoryEntry as bu, INDEXED_STORE_POLICY as bv, type ImportCapability as bw, type InferOutput as bx, type IssueDelegationOptions as by, type IssueMagicLinkGrantOptions as bz, DictionaryHandle as c, type UserInfo as c$, type Permissions as c0, type PlaintextTranslatorContext as c1, type PlaintextTranslatorFn as c2, PresenceHandle as c3, type PresencePeer as c4, type PublicEnvelopeField as c5, type PublicEnvelopeSchema as c6, type PublicEnvelopeText as c7, type PullMode as c8, type PullOptions as c9, type StandardSchemaV1Issue as cA, type StandardSchemaV1SyncResult as cB, type StoreAuth as cC, type StoreAuthKind as cD, type StoreCapabilities as cE, SyncEngine as cF, type SyncMetadata as cG, type SyncPolicy as cH, SyncScheduler as cI, type SyncSchedulerStatus as cJ, type SyncStatus as cK, type SyncTarget as cL, type SyncTargetRole as cM, SyncTransaction as cN, type SyncTransactionResult as cO, type TierMode as cP, type TranslatorAuditEntry as cQ, type TxOp as cR, USER_ENVELOPE_COLLECTION as cS, USER_ENVELOPE_MAX_BYTES as cT, type Unsubscribe as cU, type UpdateAuthenticatorOptions as cV, type UpdateUserOptions as cW, UserApi as cX, type UserEnvelopeCheckGate as cY, UserEnvelopeOversizedError as cZ, type UserEnvelopePresented as c_, type PullPolicy as ca, type PullResult as cb, type PushMode as cc, type PushOptions as cd, type PushPolicy as ce, type PushResult as cf, type PutManyItemOptions as cg, type PutManyOptions as ch, type PutManyResult as ci, type QueryAcrossOptions as cj, type QueryAcrossResult as ck, type QuickUnlockState as cl, QuickUnlockStore as cm, type ReAuthOperation as cn, type RecoverPassphraseInput as co, type RecoverPassphraseResult as cp, type RecoverUserOptions as cq, type RecoveryProof as cr, type ResolvedPublicEnvelopeSchema as cs, type RevokeOptions as ct, type RotatePassphraseInput as cu, type SessionPolicy as cv, type SetPublicEnvelopeInput as cw, type SlotRewrapCeremony as cx, type SlotRewrapContext as cy, type StandardSchemaV1 as cz, type DictionaryOptions as d, type VaultBackup as d0, type VaultPolicyOnDisk as d1, type VaultSnapshot as d2, type WarningRules as d3, WeakPassphraseError as d4, type WeakPassphraseReason as d5, type WrappedDeksBlob as d6, assertStrongPassphrase as d7, buildRecipientKeyringFile as d8, burnPaperRecoveryEntry as d9, recoverUser as dA, removeAuthenticator as dB, resolveSchema as dC, revokeDelegation as dD, revokeMagicLinkGrant as dE, savePaperRecoveryEntries as dF, unwrapDeksFromBlob as dG, unwrapDeksFromPaperEntry as dH, unwrapMagicLinkGrant as dI, validatePassphrase as dJ, validatePublicEnvelopeInput as dK, validateSchemaInput as dL, validateSchemaOutput as dM, writeMagicLinkGrant as dN, createNoydb as da, createStore as db, deriveMagicLinkContentKey as dc, enrollAuthenticator as dd, estimateEntropy as de, evaluateExportCapability as df, evaluateImportCapability as dg, findAuthenticator as dh, hasExportCapability as di, hasImportCapability as dj, hasRecoveryEnrolled as dk, isMagicLinkGrantExpired as dl, isPublicEnvelope as dm, issueDelegation as dn, recoverPassphrase as dp, rotatePassphrase as dq, listMagicLinkGrants as dr, listUsers as ds, listUsersWithEnvelopes as dt, loadActiveDelegations as du, loadPaperRecoveryEntries as dv, magicLinkGrantRecordId as dw, mintPaperRecoveryEntry as dx, mintWrappedDeksBlob as dy, readMagicLinkGrantRecord as dz, type I18nTextDescriptor as e, type I18nTextOptions as f, applyI18nLocale as g, dictCollectionName as h, dictKey as i, i18nText as j, isDictCollectionName as k, isDictKeyDescriptor as l, isI18nTextDescriptor as m, createEnforcer as n, validateSessionPolicy as o, BLOB_CHUNKS_COLLECTION as p, BLOB_COLLECTION as q, resolveI18nText as r, BLOB_EVICTION_AUDIT_COLLECTION as s, BLOB_INDEX_COLLECTION as t, BLOB_SLOTS_PREFIX as u, validateI18nTextValue as v, BLOB_VERSIONS_PREFIX as w, type BlobEvictionEntry as x, type BlobFieldPolicy as y, type BlobFieldsConfig as z };