@noy-db/hub 0.6.0-pre.2 → 0.6.0-pre.21

package/dist/with-commit/vault-head/head.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The vault head's storage layer (#1044).
+ *
+ * A bucket is an ordinary encrypted record at `_head/<collection>::<n>`, so it
+ * inherits #1041's identity binding for free: the store cannot relocate a
+ * bucket, re-author it, or serve one bucket's bytes as another's. What it can
+ * still do is serve an OLD bucket, which is why {@link readBucket} enforces
+ * monotonicity against the caller's own record of what it last wrote.
+ *
+ * @packageDocumentation
+ */
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import type { NoydbStore } from '../../kernel/types.js';
+/** `{ recordId → version }` for one bucket. */
+export type BucketBody = Record<string, number>;
+/**
+ * FNV-1a over `collection/id`. A hash, not a cipher: the bucket a record lands
+ * in is not secret — the store already sees which bucket was written, and it
+ * already saw the record's own address. Choosing something stronger would buy
+ * nothing and cost every write.
+ */
+export declare function bucketIndex(collection: string, id: string, buckets: number): number;
+export declare function bucketId(collection: string, id: string, buckets: number): string;
+export declare function readBucket(store: NoydbStore, vault: string, dek: EnclaveKey, bucket: string): Promise<{
+    body: BucketBody;
+    version: number;
+}>;
+export declare function writeBucket(store: NoydbStore, vault: string, dek: EnclaveKey, bucket: string, body: BucketBody, expectedVersion: number): Promise<void>;

package/dist/with-commit/vault-head/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@noy-db/hub/vault-head` — detect a store that WITHHOLDS (#1044).
+ *
+ * @packageDocumentation
+ */
+export { withVaultHead } from './active.js';
+export { verifyVaultHead, type HeadDiscrepancy, type HeadVerifyResult, type HeadVerdict, type HeadUnverifiableReason } from './verify.js';
+export { NO_VAULT_HEAD, VAULT_HEAD_COLLECTION, DEFAULT_HEAD_BUCKETS, type VaultHeadStrategy, type WithVaultHeadOptions, type HeadEntry, } from './strategy.js';
+export type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
+export type { EnclaveKey } from '../../kernel/enclave/index.js';

package/dist/with-commit/vault-head/strategy.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `withVaultHead()` — the opt-in detector for **omission** (#1044).
+ *
+ * ## What it is for, and what it deliberately is not
+ *
+ * #1041 made every envelope self-authenticating at its identity, and #1042
+ * made the merge reject one that is not. What neither can catch is **absence**:
+ * a store that serves a genuine, unmodified `v1` when `v7` exists, or serves
+ * nothing at all. An authentic old envelope is indistinguishable from an
+ * authentic current one without external knowledge of what *should* be there.
+ *
+ * The head is that external knowledge: an authenticated `{id → version}`
+ * manifest the client writes and the store cannot forge. It is **not** a Merkle
+ * chain over content — content integrity is already handled, so the head needs
+ * only versions.
+ *
+ * ## Why it is opt-in when AAD is not
+ *
+ * AAD costs nothing to coordinate and closes *alteration*, so it is kernel. The
+ * head costs a write per commit and needs anti-entropy; on a single-device
+ * offline vault it defends against nothing. Making it kernel would tax every
+ * user for a multi-writer property. ADR 0003, Decision 3.
+ *
+ * `SECURITY.md` states the split exactly: a store cannot alter, relocate,
+ * re-tier, re-author or rewind a record; **without `withVaultHead()` it can
+ * still withhold or omit.**
+ *
+ * ## Bucketed, and why that is not a compromise
+ *
+ * ADR 0003 left head granularity open and asked for it to be sized early.
+ * Measured, at the documented 50K-record vault ceiling:
+ *
+ * | shape | write cost per commit | detection |
+ * |---|---|---|
+ * | one per-vault manifest | **1.1 MiB** | per-record |
+ * | one per collection | the same problem, renamed | per-record |
+ * | **bucketed, 256 buckets** | **~4.4 KiB** | per-record |
+ *
+ * Bucketing changes *only* write amplification. Each bucket still lists every
+ * one of its records' versions, so detection stays per-record — which is why
+ * this is not a trade-off between cost and strength. Verifying one pulled
+ * record reads one bucket rather than a megabyte.
+ *
+ * ## Wired as a bus OBSERVER, not a call in `collection.ts`
+ *
+ * That is what `kernel-surface` means by "register on the ServiceBus instead of
+ * growing this file", and it keeps the hot write path untouched for anyone who
+ * has not opted in: nothing is registered at all, so `hasHandlers` stays false
+ * and the dispatch never happens.
+ *
+ * Both `afterPut` AND `afterDelete`, because a delete is a version bump like
+ * any other. A head that stopped tracking deleted records would let a store
+ * resurrect one by withholding the tombstone — precisely the omission this
+ * exists to catch.
+ *
+ * ⚠️ The registration must be UNCONDITIONAL on anything but `enabled`. Its first
+ * draft sat inside `#registerForgetHooks()`, which returns early when no forget
+ * subjects are declared, so the head silently recorded nothing unless the vault
+ * happened to use an unrelated feature. The tests caught it only because they
+ * asserted a COUNT rather than "no error" — a head that records nothing raises
+ * no errors and sweeps perfectly clean.
+ *
+ * @packageDocumentation
+ */
+import type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+/** Reserved collection the head's buckets live in. */
+export declare const VAULT_HEAD_COLLECTION: "_head";
+/** Default bucket count — see the sizing table above. */
+export declare const DEFAULT_HEAD_BUCKETS = 256;
+export interface WithVaultHeadOptions {
+    /**
+     * How many buckets the manifest is split across. Higher means smaller writes
+     * and more reads to sweep the whole vault; lower means the opposite.
+     * Changing it on an existing vault re-homes every entry, so treat it as a
+     * layout decision rather than a tuning knob.
+     */
+    readonly buckets?: number;
+}
+/** One record's expected state, as the client last committed it. */
+export interface HeadEntry {
+    readonly collection: string;
+    readonly id: string;
+    readonly version: number;
+}
+export interface VaultHeadStrategy {
+    /**
+     * Is the head actually keeping a manifest?
+     *
+     * An explicit flag rather than an identity check against the stub: the kernel
+     * decides whether to register the write-path observer at all, and
+     * `port-layering` forbids it importing `NO_VAULT_HEAD` to compare. Without
+     * this, every write in a vault that never opted in would still pay a cache
+     * lookup and a no-op call.
+     */
+    readonly enabled: boolean;
+    /** Bucket a record id lands in — pure, so callers can pre-group a batch. */
+    bucketFor(collection: string, id: string): string;
+    /**
+     * Record `entry` as the client's expectation for that record.
+     *
+     * Called on every committed write, INSIDE the same logical operation, so
+     * there is no window where the record exists and the head does not know it.
+     */
+    note(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>, entry: HeadEntry): Promise<void>;
+    /**
+     * What the client expects for `collection/id`, or `null` if the head has
+     * never seen it.
+     */
+    expected(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>, collection: string, id: string): Promise<number | null>;
+    /**
+     * Every record the head knows about in `collection` — the set a sweep
+     * compares against what the store actually serves, which is how DELETION
+     * SUPPRESSION is caught. A withheld record is absent from the store but
+     * present here.
+     */
+    knownIn(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>, collection: string): Promise<ReadonlyMap<string, number>>;
+}
+/**
+ * The un-opted-in stub. `note` is a NO-OP rather than a throw: the write path
+ * calls it unconditionally, and a vault without the head must simply not keep
+ * one. The READ side throws, because asking what the head expects when there is
+ * no head is a caller error, not a silent "nothing to report" — the latter
+ * would look exactly like a clean sweep.
+ */
+export declare const NO_VAULT_HEAD: VaultHeadStrategy;
+export type { EncryptedEnvelope };

package/dist/with-commit/vault-head/verify.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The sweep — comparing what the head expects against what the store serves (#1044).
+ *
+ * This is the only place absence becomes visible. #1041 and #1042 can reject a
+ * record that lies about itself; neither can notice one that never arrived, or
+ * one served at an older version than the client wrote. Both are indistinguishable
+ * from the truth without an independent record of what should be there.
+ *
+ * @packageDocumentation
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { VaultHeadStrategy } from './strategy.js';
+/** One record the store is not serving faithfully. */
+export interface HeadDiscrepancy {
+    readonly collection: string;
+    readonly id: string;
+    /** What the client last committed. */
+    readonly expected: number;
+    /**
+     * What the store serves now — or `null` when it serves nothing.
+     *
+     * The two are different attacks wearing the same result. `null` is
+     * **suppression**: the record is gone. A lower number is **rollback**: an
+     * authentic older version served in place of the current one, which is the
+     * case no amount of per-envelope authentication can see.
+     */
+    readonly actual: number | null;
+    readonly kind: 'withheld' | 'rolled-back';
+}
+/**
+ * Why a sweep could not reach a conclusion.
+ *
+ * - `'no-expectations'` — the head holds nothing for this collection. A fresh
+ *   vault, a head switched on after the fact, or a **restore from a snapshot**:
+ *   `_head` is `_`-prefixed, so `loadAll` excludes it and a restored vault has
+ *   no head to compare against.
+ * - `'store-cannot-cas'` — the store does not advertise `capabilities.casAtomic`,
+ *   so two writers racing on one bucket can silently lose an entry. A lost entry
+ *   is a record the sweep stops expecting, which is a false clean.
+ */
+export type HeadUnverifiableReason = 'no-expectations' | 'store-cannot-cas';
+/**
+ * ## Three-way, deliberately (#1101)
+ *
+ * - `'verified'` — the head held expectations, every one was met, and the store
+ *   can serialize head writes.
+ * - `'unverifiable'` — the sweep could not conclude. See `because`.
+ * - `'tampered'` — at least one discrepancy. Positive evidence, so it wins over
+ *   any `unverifiable` reason present at the same time.
+ *
+ * **The middle value is the point, and collapsing it is wrong in a different
+ * direction each way:** folded into "clean" it hides withholding, which is the
+ * one thing this service exists to catch; folded into "tampered" it cries wolf
+ * on a vault that is merely unexamined.
+ *
+ * That is not hypothetical. #1044's own first bug was a head that recorded
+ * nothing and swept **perfectly clean** — the degraded state rendered
+ * identically to a healthy one, which is why its test asserts `checked` before
+ * anything else. A two-way verdict makes that state a supported outcome.
+ */
+export type HeadVerdict = 'verified' | 'unverifiable' | 'tampered';
+export interface HeadVerifyResult {
+    readonly verdict: HeadVerdict;
+    readonly checked: number;
+    readonly discrepancies: readonly HeadDiscrepancy[];
+    /**
+     * Non-empty only when `verdict === 'unverifiable'`.
+     *
+     * There is deliberately no `clean: boolean`. It could not distinguish "no
+     * expectations" from "all expectations met" — both rendered `true` — and that
+     * indistinguishability *was* the defect. Replacing it rather than keeping it
+     * alongside forces every caller to face the three-way.
+     */
+    readonly because: readonly HeadUnverifiableReason[];
+}
+/**
+ * Sweep one collection.
+ *
+ * **A record the store serves that the head does NOT know is not reported.**
+ * That is not an oversight: the head can be enabled on an existing vault, and
+ * every pre-existing record would otherwise read as an anomaly. The head's
+ * claim is one-directional — *what I wrote must still be there* — and an
+ * unknown record simply falls outside it.
+ *
+ * **A HIGHER version than expected is also not reported**, for the same reason:
+ * another device legitimately advanced it. The head detects going backwards, not
+ * moving forwards.
+ */
+export declare function verifyVaultHead(head: VaultHeadStrategy, store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>, collection: string): Promise<HeadVerifyResult>;

package/dist/with-formula/materialized-views/types.d.ts

@@ -4,6 +4,7 @@ import type { ReduceSpec, Reduction } from '../../with-lookup/reduce/reduction.j
 import type { GroupedReduction } from '../../with-lookup/reduce/groupby.js';
 import type { JoinStrategy } from '../../kernel/query/join.js';
 import type { MoneyDescriptor } from '../../via/money/descriptor.js';
+import type { ExactMath } from '../../via/money/exact.js';
 import type { I18nTextDescriptor } from '../../via/i18n/core.js';
 /**
  * Minimal vault-shaped accessor passed to the MV `query()` callback.
@@ -269,6 +270,57 @@ export interface MaterializedViewSpec<TRow extends Record<string, unknown>> {
      * UNION-mode only. Ignored if {@link query} is set.
      */
     aggregate?: ReduceSpec;
+    /**
+     * Post-aggregate projection over ONE finished row (#1007).
+     *
+     * `aggregate` accepts reducers only, so a row can carry every input a
+     * derived value needs and still not express it — `max(0, netTotal - paid)`
+     * is not a reduction. `derive` closes that gap: it receives the row the
+     * grouping/aggregation pipeline just produced and returns a patch merged
+     * onto it, immediately before materialisation.
+     *
+     * ```ts
+     * aggregate: { paid: sum('paid'), netTotal: sum('netTotal') },
+     * derive: (row) => ({ toPay: Math.max(0, row.netTotal - row.paid) }),
+     * ```
+     *
+     * Deliberately narrow, and the narrowness is what keeps it safe under
+     * incremental recompute: **pure, single-row, no cross-row access, no second
+     * aggregation pass.** It only ever sees the row the reducer just produced,
+     * so a refresh triggered by one source write recomputes it correctly without
+     * the engine needing to know anything about the function.
+     *
+     * Returning `null` / `undefined` leaves the row unchanged. Returned keys
+     * that collide with a {@link groupBy} field throw
+     * `MaterializedViewConfigError` — a group key is the row's identity and
+     * feeds {@link rowKey}, so rewriting it would silently re-home the row.
+     *
+     * **Money:** money leaves a reducer as an exact decimal string, and
+     * `Number(a) - Number(b)` would put it straight back through binary floating
+     * point — `10.05 - 0.10` becomes `9.950000000000001`, which the money
+     * quantiser then refuses rather than storing drift. So `derive` receives
+     * {@link ExactMath} as its second argument; it works in scaled BigInt and
+     * cannot introduce a representation error:
+     *
+     * ```ts
+     * moneyFields: { netTotal: THB, paid: THB, toPay: THB },
+     * derive: (row, exact) => ({ toPay: exact.max(0, exact.sub(row.netTotal, row.paid)) }),
+     * ```
+     *
+     * Declare the derived field in {@link moneyFields} and the result is
+     * quantised through that descriptor before storage, exact at its scale.
+     *
+     * Note the one place `TRow` under-describes what arrives: a field declared
+     * in {@link moneyFields} reaches `derive` DECODED — the decimal string a
+     * reader would see, not the scaled integer the reducer left behind — even
+     * where `TRow` types it as `number` (which is what the arms' `map` emits).
+     * `ExactMath` accepts both, which is why its operations are the right tool
+     * here and why no cast is needed.
+     *
+     * Applies to every MV form (union, projection, and query), always as the
+     * last step before rows are materialised.
+     */
+    derive?: (row: TRow, exact: ExactMath) => Record<string, unknown> | null | undefined;
     /**
      * Money descriptors for the UNION-mode aggregate, keyed by the
      * OUTPUT/intermediate field name as it appears in the mapped row and

package/dist/with-party/directory/cover/storage.d.ts

@@ -1,11 +1,3 @@
-/**
- * Persistence helpers for `_meta/public-envelope` — the cover's
- * frozen wire location. Mirrors the bypass-AES pattern used by
- * `_meta/handle` and `_meta/policy` — the document is plaintext
- * JSON, the envelope's `_iv` field is left empty.
- *
- * @module
- */
 import type { NoydbStore } from '../../../kernel/types.js';
 import type { Cover } from './types.js';
 /**

package/dist/with-party/directory/storage.d.ts

@@ -1,14 +1,3 @@
-/**
- * Persistence helpers for the vault-level user-directory toggle
- * (`_meta/directory`). Mirrors the bypass-AES pattern used by
- * `_meta/policy` — the directory document is plain JSON, the
- * envelope's `_iv` field is left empty.
- *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md → Directory visibility
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/plaintext-bypass.md — every `_iv: ''` write site
- *
- * @module
- */
 import type { NoydbStore } from '../../kernel/types.js';
 import type { DirectoryConfig } from './types.js';
 /** Reserved collection name for vault-level metadata documents. */

package/dist/with-party/directory/visibility.d.ts

@@ -1,24 +1,3 @@
-/**
- * Persistence helpers for the per-user visibility flag
- * (`_meta/visibility/<keyringId>`). Mirrors the bypass-AES pattern used
- * by `_meta/policy` — the visibility document is plain JSON, the
- * envelope's `_iv` field is left empty.
- *
- * Stored alongside the keyring file rather than inside the encrypted
- * user envelope (`_users/<keyringId>`) because:
- *
- *  - `UserEnvelope<T>.data` is opaque-to-hub by contract — hub does not
- *    introspect or reserve any keys inside it. Adding `hidden` there
- *    would violate that contract.
- *  - `listUsersWithEnvelopes` filters by the flag, and the filter must
- *    work even when decryption fails (legacy keyrings predating the
- *    envelope feature, or a corrupted envelope).
- *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md → Directory visibility
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/plaintext-bypass.md — every `_iv: ''` write site
- *
- * @module
- */
 import type { NoydbStore } from '../../kernel/types.js';
 import type { UserVisibility } from './types.js';
 /** Prefix for per-user visibility records inside `_meta`. */

package/dist/with-party/policy/storage.d.ts

@@ -1,13 +1,3 @@
-/**
- * Persistence helpers for the vault-level policy document
- * (`_meta/policy`). Mirrors the bypass-AES pattern used by
- * `_meta/handle` — the policy document is plain JSON, the envelope's
- * `_iv` field is left empty.
- *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Storage location
- *
- * @module
- */
 import type { NoydbStore, VaultPolicy } from '../../kernel/types.js';
 /** Reserved collection name for vault-level metadata documents. */
 export declare const META_COLLECTION = "_meta";

package/dist/with-party/team/index.d.ts

@@ -17,7 +17,7 @@ export { NO_TEAM, type TeamStrategy } from './strategy.js';
 export { TeamNotEnabledError } from '../../kernel/errors.js';
 export type { UnlockedKeyring } from './keyring.js';
 export { loadKeyring, createOwnerKeyring, grant, revoke, changeSecret, listUsers, listUsersWithEnvelopes, ensureCollectionDEK, persistKeyring, updateKeyringIdentity, buildRecipientKeyringFile, } from './keyring.js';
-export type { BundleRecipient, ListUsersOptions } from './keyring.js';
+export type { PodRecipient, ListUsersOptions } from './keyring.js';
 export type { LoadKeyringOptions, CreateOwnerKeyringOptions, RotateKeysOptions, ChangeSecretOptions, } from './keyring.js';
 export { enrollAuthenticator, removeAuthenticator, updateAuthenticator, findAuthenticator, } from './authenticators.js';
 export type { EnrollAuthenticatorOptions, EnrollAuthenticatorWrappingKEKOptions, EnrollAuthenticatorWrappingDEKsOptions, UpdateAuthenticatorOptions, } from './authenticators.js';

package/dist/with-party/team/keyring.d.ts

@@ -1,5 +1,6 @@
 import type { NoydbStore, KeyringFile, KeyringAuthenticator, Role, Permissions, GrantOptions, RevokeOptions, UpdateUserOptions, UserInfo, EncryptedEnvelope, ExportCapability, ExportFormat, ImportCapability, VaultPolicyOnDisk, UserEnvelope } from '../../kernel/types.js';
 import { type EnclaveKey, type EchoSecretParts } from '../../kernel/enclave/index.js';
+import type { KeyringTamperedReason } from '../../kernel/errors.js';
 import { type SecretPolicy, type EchoSecretPolicy } from '../../kernel/validation.js';
 import type { DeviceSealProvider } from './device-seal.js';
 /** In-memory representation of an unlocked keyring. */
@@ -9,6 +10,11 @@ export interface UnlockedKeyring {
     readonly role: Role;
     readonly permissions: Permissions;
     readonly deks: Map<string, EnclaveKey>;
+    /**
+     * Unwrapped counterpart of {@link KeyringFile.pending_deks} — an
+     * uncommitted rotation (#1074). Empty in the normal state.
+     */
+    readonly pendingDeks?: Map<string, EnclaveKey> | undefined;
     /**
      * The KEK, when this keyring was unlocked via tier 1 (secret) or
      * a wrap-KEK tier-2 method (WebAuthn / OIDC). `null` when the
@@ -72,6 +78,23 @@ export interface UnlockedKeyring {
 }
 /** Mint a fresh wrapped-canary string. Deterministic for a given KEK. */
 export declare function mintKeyringCanary(kek: EnclaveKey): Promise<string>;
+/**
+ * The vault roster key held by this keyring, or `null` when the keyring
+ * carries none.
+ *
+ * Null is expected on the resume-style paths (`kek: null` sessions, tier-3
+ * PIN resume, plaintext mode) — none of which may write a keyring file.
+ * Every stamping site null-guards this exactly as it guards `kek`: minting a
+ * file without a verifiable `roster_tag` would be worse than refusing, since
+ * it is indistinguishable on the next load from a store having stripped it.
+ */
+export declare function rosterKeyOf(keyring: UnlockedKeyring): EnclaveKey | null;
+/**
+ * Shared wording for the stamping-site guards — mirrors the `kek` guard's shape.
+ * Exported so every roster-stamping site in the hub raises ONE error with one
+ * wording, rather than each hand-copying it (`peer-recover`, `liberate`).
+ */
+export declare function requireRosterKey(keyring: UnlockedKeyring, fn: string): EnclaveKey;
 /** Options for {@link loadKeyring} (#846b). */
 export interface LoadKeyringOptions {
     /** The user whose keyring to unlock. */
@@ -168,6 +191,100 @@ export declare function createOwnerKeyring(store: NoydbStore, vault: string, opt
 export declare function grant(store: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: GrantOptions): Promise<void>;
 /** Revoke a user's access. Optionally rotate keys for affected collections. */
 export declare function revoke(store: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: RevokeOptions): Promise<void>;
+/** What {@link verifyRoster} found. */
+export interface RosterVerifyResult {
+    /**
+     * How many `_keyring` files were examined.
+     *
+     * Reported first, and deliberately: "nothing unverified" is equally true of a
+     * sweep that examined nothing, and a roster check that silently covered zero
+     * members would look identical to a healthy vault. Same lesson as the vault
+     * head's `no-expectations` verdict (#1101).
+     */
+    readonly checked: number;
+    /** The files that failed authentication, and why. */
+    readonly unverified: ReadonlyArray<{
+        readonly userId: string;
+        readonly reason: KeyringTamperedReason;
+    }>;
+}
+export declare function verifyRoster(store: NoydbStore, vault: string, callerKeyring: UnlockedKeyring): Promise<RosterVerifyResult>;
+/** What {@link quarantineKeyring} did. */
+export interface QuarantineResult {
+    readonly userId: string;
+    /** Why the file could not be authenticated — the justification for removing it. */
+    readonly reason: KeyringTamperedReason;
+    /** Collections re-keyed as part of the removal. */
+    readonly rotated: readonly string[];
+    /**
+     * (member, collection) pairs whose access the rotation dropped — the OTHER
+     * members, who must be re-granted.
+     *
+     * Passed through from `rotateKeys` rather than discarded, because a
+     * quarantine rotates broadly (see the scope note on the function) and so
+     * de-provisions more people than the one being removed. An operator who is
+     * not told this discovers it as unrelated `NoAccessError`s later.
+     */
+    readonly needsRegrant: RotateResult['needsRegrant'];
+    /**
+     * OTHER members whose own files also failed authentication, found while
+     * rotating. One forged file is rarely the only one, and the operator is
+     * already holding the tool for them.
+     */
+    readonly alsoUnverified: RotateResult['unverified'];
+}
+/**
+ * Remove a `_keyring` file that cannot be authenticated, and re-key behind it
+ * (#1121).
+ *
+ * ## Why this is not a flag on `revoke`
+ *
+ * `revoke` reads the target's own `role` to decide whether the caller may
+ * revoke them, so it cannot act on a file it will not trust — which left a
+ * forged file removable only by editing the store by hand. Relaxing `revoke`
+ * conditionally would grow the safe path a parameter that turns it into the
+ * dangerous one; ADR 0003's standing rule is that if the implementation needs
+ * to weaken a guard, the design is wrong. This is a separate operation with its
+ * own contract, so `revoke`'s invariant stays absolute and the dangerous act is
+ * named at the call site rather than hidden in an option bag.
+ *
+ * ## The two properties that keep it from being a backdoor
+ *
+ * 1. **It refuses a file that verifies.** Otherwise it would delete any keyring
+ *    while ignoring `canRevoke` — including an owner's, which `revoke` protects
+ *    unconditionally.
+ * 2. **Because of (1) it can safely ignore the claimed `role` — and it must.**
+ *    `canRevoke` refuses any target whose role reads `owner`, so a store that
+ *    forged `"role":"owner"` onto its victim would otherwise make them
+ *    permanently unremovable. Consulting the forged field is exactly the
+ *    mistake this operation exists to avoid.
+ *
+ * Owner-only: the narrowest role that can always act, and quarantine
+ * deliberately consumes NO field of the file it is removing.
+ *
+ * ## Why it rotates, and why the scope comes from the CALLER
+ *
+ * Deleting the file is not a revocation — the store may decline the delete, and
+ * the member may already hold unwrapped DEKs. So this rotates, exactly as
+ * `revoke` does. The scope is every collection the CALLER holds, not the
+ * target's DEK map: that map is unauthenticated (#1115), so deriving the scope
+ * from it would let the store choose which collections survive a quarantine.
+ *
+ * ⚠️ **That is the security-correct scope, and it is NOT free.** An earlier
+ * draft of this comment called over-rotating "the safe direction"; a review
+ * probe disproved it. Rotation re-keys `store.list(vault, <name>)` plus the
+ * derived refs `rotateKeys` knows about, so a DEK slot whose ciphertext lives
+ * under a *different* collection name — `_blob`, whose data sits in
+ * `_blob_index`/`_blob_chunks`, and the `collection#tier` slots — is re-keyed
+ * without its data being re-encrypted, and that data then fails to open. That
+ * gap belongs to `rotateKeys` (it is reachable through an ordinary `revoke` of
+ * a whole-vault grantee, with no quarantine involved) and is filed as #1122,
+ * but a quarantine takes the maximal scope *unconditionally*, so it meets the
+ * gap every time rather than occasionally. Until that is fixed, treat a
+ * quarantine as an emergency operation with a real blast radius, and read
+ * `needsRegrant` afterwards.
+ */
+export declare function quarantineKeyring(store: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, userId: string): Promise<QuarantineResult>;
 /**
  * Mutate `role`, `displayName`, and/or `permissions` on an existing
  * keyring. Pure plaintext-header rewrite — no DEK rewrap, no KEK
@@ -217,6 +334,26 @@ export interface RotateResult {
         readonly userId: string;
         readonly collection: string;
     }>;
+    /**
+     * Members skipped because their `_keyring` file failed roster verification
+     * (#1114).
+     *
+     * Rotation hands a member re-wrapped DEKs, so skipping one gives them
+     * **less**, never more: the file is left untouched and its wrappings for the
+     * rotated collections go stale. That is the same fail-closed end state as
+     * `needsRegrant`, but it needs a different remedy and so gets a different
+     * field — a `needsRegrant` entry is fixed by `grant()`, whereas one of these
+     * is a file that no longer authenticates and cannot be repaired by granting
+     * over it.
+     *
+     * Before this existed, one such file threw and took `revoke` and
+     * `rotateKeys` down vault-wide — the two operations most needed when a
+     * roster is suspect.
+     */
+    readonly unverified: ReadonlyArray<{
+        readonly userId: string;
+        readonly reason: KeyringTamperedReason;
+    }>;
 }
 /** Options for {@link rotateKeys} (#846b — was a bare `string[]`). */
 export interface RotateKeysOptions {
@@ -261,7 +398,7 @@ export interface EchoRecipientSecret extends EchoSecretParts {
  *
  * @public
  */
-export interface BundleRecipient {
+export interface PodRecipient {
     /** User id stamped onto the keyring file in the bundle. */
     readonly id: string;
     /** Optional display name. Defaults to `id`. */
@@ -312,7 +449,7 @@ export interface BundleRecipient {
  *
  * @internal
  */
-export declare function buildRecipientKeyringFile(callerKeyring: UnlockedKeyring, recipient: BundleRecipient): Promise<KeyringFile>;
+export declare function buildRecipientKeyringFile(callerKeyring: UnlockedKeyring, recipient: PodRecipient): Promise<KeyringFile>;
 /** List all users with access to a vault. */
 export declare function listUsers(store: NoydbStore, vault: string): Promise<UserInfo[]>;
 /**
@@ -368,8 +505,17 @@ export declare function listUsersWithEnvelopes<T = unknown>(store: NoydbStore, v
     user: UserInfo;
     envelope: UserEnvelope<T> | null;
 }>>;
-/** Ensure a DEK exists for a collection. Generates one if new. */
 export declare function ensureCollectionDEK(store: NoydbStore, vault: string, keyring: UnlockedKeyring): Promise<(collectionName: string) => Promise<EnclaveKey>>;
+/**
+ * The `Permissions` catch-all key (#1010). `Permissions` has always documented
+ * `'*'` as "the wildcard collection matching all collections in the vault", but
+ * nothing expanded it — a grantee handed the documented catch-all got no keys
+ * at all. It is honoured in three places, and they must agree: the DEK wrapping
+ * in `grant()`, and both permission checks below.
+ */
+export declare const PERMISSION_WILDCARD = "*";
+/** Does this permission map hand over the whole vault? */
+export declare function permissionsAreWildcard(permissions: Permissions | undefined): boolean;
 /** Check if a user has write permission for a collection. */
 export declare function hasWritePermission(keyring: UnlockedKeyring, collectionName: string): boolean;
 /** Check if a user has any access to a collection. */

package/dist/with-party/team/noydb-facade.d.ts

@@ -19,7 +19,7 @@
  * Internal service — reached through `noydb.team.rotateSecret(...)` etc.
  */
 import type { NoydbOptions, NoydbStore, KeyringAuthenticator } from '../../kernel/types.js';
-import type { RotateResult, RotateKeysOptions } from './keyring.js';
+import type { RotateResult, RotateKeysOptions, RosterVerifyResult, QuarantineResult } from './keyring.js';
 import { type RotateSecretInput, type RecoverSecretInput, type RecoverSecretResult, type RotateRecoveryOptions, type RotateRecoveryResult, type EnrollRecoveryResult, type RecoveryEnrollmentInput, type RecoveryProof } from './rotate-recover.js';
 import { type RecoverUserOptions } from './peer-recover.js';
 import { type PaperRecoveryEntry, type ShamirRecoveryEntry } from './recovery.js';
@@ -74,6 +74,10 @@ export declare class TeamFacade {
     runRevoke(engine: (adapter: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: RevokeOptions) => Promise<void>, vault: string, options: RevokeOptions, factors?: FactorProofBundle): Promise<void>;
     /** Gate + run a `rotateKeys` engine. See `Noydb.rotate` for the public contract. */
     runRotate(engine: (store: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, opts: RotateKeysOptions) => Promise<RotateResult>, vault: string, collections: string[]): Promise<RotateResult>;
+    /** Gate + run the `verifyRoster` engine (#1121). See `Noydb.verifyRoster`. */
+    runVerifyRoster(engine: (store: NoydbStore, vault: string, callerKeyring: UnlockedKeyring) => Promise<RosterVerifyResult>, vault: string): Promise<RosterVerifyResult>;
+    /** Gate + run the `quarantineKeyring` engine (#1121). See `Noydb.quarantineKeyring`. */
+    runQuarantine(engine: (store: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, userId: string) => Promise<QuarantineResult>, vault: string, userId: string, factors?: FactorProofBundle): Promise<QuarantineResult>;
     /**
      * Add a tier-2 authenticator slot to the calling user's keyring.
      * Each slot independently wraps the SAME KEK under a method-specific