@noy-db/hub 0.6.0-pre.9 → 0.6.0

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[]>;
 /**

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

package/dist/with-party/team/roster-tag.d.ts

@@ -0,0 +1,101 @@
+/**
+ * #1096 — the authenticated half of a `_keyring` file's AUTHORITY.
+ *
+ * A `_keyring` file is stored plaintext (`_iv: ''`) so admins can edit a
+ * member's authority without holding that member's credential. That means
+ * `role`/`permissions` were authenticated by NOTHING — a hostile store could
+ * promote a viewer to admin by editing one word (proven in
+ * `__tests__/keyring-replay-escalation.test.ts`).
+ *
+ * The fix is a vault-wide ROSTER KEY, carried as a reserved DEK-map entry
+ * (`deks['_roster']`, see `ROSTER_KEY_ID`) so it reaches every member through
+ * the channels a DEK already travels — grant's `_`-prefix propagation,
+ * `persistKeyring`, the wrapped-DEKs recovery blob, `peer-recover`, pod
+ * recipient slots — and a `roster_tag`: AES-GCM of the canonical authority
+ * fields under that key. Every roster EDITOR holds the key (constraint:
+ * admins edit authority they don't hold the target's credential for) — which
+ * is what sets the bound below.
+ *
+ * `user_id` is inside the canonical string so a genuine tag cannot be
+ * transplanted onto another member's file.
+ *
+ * ## What "authority half" does NOT cover
+ *
+ * The canonical string is exactly {@link RosterAuthorityFields} — the fields a
+ * privilege decision reads. Other plaintext fields are deliberately excluded
+ * and REMAIN FORGEABLE by the store: `display_name` (cosmetic), `policy`
+ * (round-tripped, never enforced at v1.0), `echo` and `authenticators` (each
+ * authenticated by its own wrapped key material — a forged one fails to
+ * unlock rather than granting anything), plus `created_at` / `salt` /
+ * `_noydb_keyring`. Adding a field to the tag means adding it to
+ * `rosterCanonical`; nothing else here is a claim about it.
+ *
+ * ## The bound
+ *
+ * This stops the STORE, which holds no keys. It deliberately does NOT stop a
+ * malicious MEMBER: every roster editor must hold the roster key, so anyone
+ * who legitimately holds it can forge any authority field for any member.
+ * That bound must be stated in `SECURITY.md` (tracked as part of the #1096
+ * PR) — it is not written there yet.
+ */
+import type { KeyringFile } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+export interface RosterTag {
+    readonly iv: string;
+    readonly data: string;
+}
+export type RosterAuthorityFields = Pick<KeyringFile, 'user_id' | 'role' | 'permissions' | 'granted_by' | 'expires_at' | 'export_capability' | 'import_capability' | 'deks' | 'pending_deks'>;
+export declare function rosterCanonical(file: RosterAuthorityFields): string;
+export declare function mintRosterTag(file: RosterAuthorityFields, rosterKey: EnclaveKey): Promise<RosterTag>;
+/**
+ * false on decrypt failure OR canonical mismatch — never throws.
+ *
+ * `null` is accepted alongside `undefined` because the tag arrives from
+ * JSON a store controls: `"roster_tag": null` is a shape the type system
+ * says is impossible and the wire permits.
+ */
+export declare function verifyRosterTag(file: RosterAuthorityFields, tag: RosterTag | undefined | null, rosterKey: EnclaveKey): Promise<boolean>;
+/**
+ * #1096 — THE CHOKEPOINT. Verify a keyring file's plaintext AUTHORITY half
+ * against the roster key carried in its own, already-unwrapped, DEK set.
+ * Throws {@link KeyringTamperedError}; returns silently when the roster is
+ * authentic.
+ *
+ * **Every path that builds an `UnlockedKeyring` from a `KeyringFile` must call
+ * this — not just `loadKeyring`.** A tier-2 unlock that reconstructs
+ * `role`/`permissions` from the plaintext header without it accepts exactly
+ * the forgery tier-1 refuses, and the vault is only as strong as its weakest
+ * unlock path. That is not hypothetical: the wrap-DEKs password path shipped
+ * in this state until it was caught in review.
+ *
+ * Deliberately says nothing about the canary. The canary proves the KEK, and
+ * tier-2 paths have no KEK to prove — the roster key they hold comes from the
+ * slot's own wrapped-DEK blob, which is authenticated by its own AES-GCM tag.
+ * Callers that DO hold a KEK check the canary separately, before this.
+ *
+ * @param deks the caller's UNWRAPPED DEK set — a roster key here is proof of
+ *   possession, so this must never be handed a map built from unverified input.
+ */
+export declare function assertRosterAuthenticated(file: KeyringFile, deks: ReadonlyMap<string, EnclaveKey>, userId: string): Promise<void>;
+/**
+ * #1096 — VERIFY BEFORE YOU TRUST, and especially before you RESTAMP.
+ *
+ * The sibling of {@link assertRosterAuthenticated} for the other half of the
+ * problem. That one guards paths that *unlock* a keyring; this one guards paths
+ * that **read another member's file** — because the roster key is vault-wide, a
+ * caller holding it can verify any member's tag, not just their own.
+ *
+ * Every read-modify-write on a member's roster must call this **before** the
+ * modify. A flow that reads a forged file, edits one field and restamps does
+ * not merely tolerate the forgery — it **launders** it, converting a file
+ * `loadKeyring` refuses into one it accepts, under a genuine tag. `revoke`
+ * calls into such a flow unconditionally, so without this a single forged
+ * member plus any later revocation anywhere in the vault is a complete bypass.
+ *
+ * Fail-closed, deliberately: a forged member's file aborts the operation rather
+ * than being skipped. Skipping would complete the revoke while leaving the
+ * forgery in place, and an untrusted store can already refuse writes — so the
+ * availability it costs was never guaranteed, while the integrity it buys is
+ * the point of the mechanism.
+ */
+export declare function assertRosterTagValid(file: KeyringFile, rosterKey: EnclaveKey, userId: string): Promise<void>;

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

@@ -18,7 +18,8 @@
  */
 import type { UnlockedKeyring } from './keyring.js';
 /** Canonical DEK key for a given collection + tier. Tier 0 → bare name. */
-export declare function dekKey(collection: string, tier: number): string;
+import { dekKey } from '../../kernel/tier-visibility.js';
+export { dekKey };
 /**
  * Returns the user's effective clearance for a given collection: the
  * maximum tier for which their keyring holds a DEK. Falls back to 0

package/dist/with-pod/format.d.ts

@@ -47,14 +47,14 @@
  */
 import type { Cover } from '../with-party/directory/cover/types.js';
 import type { Redirect } from './redirect.js';
-/** Magic bytes 'NDB1' (ASCII), identifying a NOYDB bundle. */
-export declare const NOYDB_BUNDLE_MAGIC: Uint8Array<ArrayBuffer>;
+/** Magic bytes 'NDB1' (ASCII) — `NoyDB 1` — identifying a NOYDB pod (`.noydb` container). */
+export declare const NOYDB_POD_MAGIC: Uint8Array<ArrayBuffer>;
 /** Total fixed prefix before the header JSON: 4+1+1+4 bytes. */
-export declare const NOYDB_BUNDLE_PREFIX_BYTES = 10;
+export declare const NOYDB_POD_PREFIX_BYTES = 10;
 /** Current bundle format version. Bumped on layout changes. Default for unsigned pods. */
-export declare const NOYDB_BUNDLE_FORMAT_VERSION = 1;
+export declare const NOYDB_POD_FORMAT_VERSION = 1;
 /** Format version for pods carrying a header signature (`sig`/`keyId`/`sigAlg`). */
-export declare const NOYDB_BUNDLE_FORMAT_VERSION_SIGNED = 2;
+export declare const NOYDB_POD_FORMAT_VERSION_SIGNED = 2;
 /**
  * Bitfield interpretation of the flags byte.
  *
@@ -85,7 +85,7 @@ export type CompressionAlgo = 0 | 1 | 2;
  *
  * **Minimum-disclosure rules:** these are the ONLY allowed keys.
  * Any other key in a parsed header causes
- * `validateBundleHeader` to throw. The set is kept short to
+ * `validatePodHeaderFields` to throw. The set is kept short to
  * minimize attack surface from cloud-storage metadata indexing —
  * see the file-level doc comment for the rationale.
  *
@@ -249,8 +249,6 @@ export interface NoydbPodHeader {
  * family (see `unlockMethods` doc comment on `NoydbPodHeader`).
  */
 export type UnlockMethod = 'password' | 'webauthn' | 'oidc' | 'totp' | 'email-otp' | 'magic-link' | 'pin' | 'recovery' | 'shamir';
-/** @deprecated Use `NoydbPodHeader`. */
-export type NoydbBundleHeader = NoydbPodHeader;
 /**
  * Validate a parsed bundle header. Throws on any deviation from
  * the minimum-disclosure schema:
@@ -266,18 +264,18 @@ export type NoydbBundleHeader = NoydbPodHeader;
  * The error messages name the offending field so consumers can
  * fix the producer rather than the reader.
  */
-export declare function validateBundleHeader(parsed: unknown): asserts parsed is NoydbPodHeader;
+export declare function validatePodHeaderFields(parsed: unknown): asserts parsed is NoydbPodHeader;
 /**
  * Encode a header object to UTF-8 JSON bytes after validating
  * minimum disclosure. Used by the writer to serialize the header
  * region of the container.
  */
-export declare function encodeBundleHeader(header: NoydbPodHeader): Uint8Array;
+export declare function encodePodHeader(header: NoydbPodHeader): Uint8Array;
 /**
  * Parse a bundle header from its UTF-8 JSON bytes. Throws on
  * invalid JSON or any minimum-disclosure violation.
  */
-export declare function decodeBundleHeader(bytes: Uint8Array): NoydbPodHeader;
+export declare function decodePodHeader(bytes: Uint8Array): NoydbPodHeader;
 /**
  * Read a uint32 from `bytes` at `offset` in big-endian byte order.
  * No bounds check — callers must guarantee `offset + 4 <= bytes.length`.
@@ -295,4 +293,4 @@ export declare function writeUint32BE(bytes: Uint8Array, offset: number, value:
  * 4 bytes match `NDB1`. Used by readers as a fast file-type check
  * before any further parsing.
  */
-export declare function hasNoydbBundleMagic(bytes: Uint8Array): boolean;
+export declare function hasNoydbPodMagic(bytes: Uint8Array): boolean;

package/dist/with-pod/index.d.ts

@@ -11,19 +11,19 @@
  * omit this subpath and save ~805 LOC of format code + Brotli/gzip
  * wiring.
  */
-export { writePod, readPod, readPodHeader, readPodCover, writeNoydbBundle, readNoydbBundle, readNoydbBundleHeader, resetBrotliSupportCache, } from './bundle.js';
+export { writePod, readPod, readPodHeader, readPodCover, resetBrotliSupportCache, } from './pod.js';
 export type { Cover } from '../with-party/directory/cover/types.js';
-export type { WritePodOptions, WriteNoydbBundleOptions, ReadNoydbBundleOptions, NoydbBundleReadResult, } from './bundle.js';
-export { verifyPodHeader } from './bundle.js';
-export type { PodVerifyResult } from './bundle.js';
+export type { WritePodOptions, ReadPodOptions, PodReadResult, } from './pod.js';
+export { verifyPodHeader } from './pod.js';
+export type { PodVerifyResult } from './pod.js';
 export { signRecord, verifyRecord, signedBytes, POD_SIG_ALG } from './signature.js';
-export { NOYDB_BUNDLE_MAGIC, NOYDB_BUNDLE_PREFIX_BYTES, NOYDB_BUNDLE_FORMAT_VERSION, FLAG_COMPRESSED, FLAG_HAS_INTEGRITY_HASH, COMPRESSION_NONE, COMPRESSION_GZIP, COMPRESSION_BROTLI, validateBundleHeader, encodeBundleHeader, hasNoydbBundleMagic, } from './format.js';
-export type { CompressionAlgo, NoydbPodHeader, NoydbBundleHeader, UnlockMethod, } from './format.js';
+export { NOYDB_POD_MAGIC, NOYDB_POD_PREFIX_BYTES, NOYDB_POD_FORMAT_VERSION, FLAG_COMPRESSED, FLAG_HAS_INTEGRITY_HASH, COMPRESSION_NONE, COMPRESSION_GZIP, COMPRESSION_BROTLI, validatePodHeaderFields, encodePodHeader, hasNoydbPodMagic, } from './format.js';
+export type { CompressionAlgo, NoydbPodHeader, UnlockMethod, } from './format.js';
 export { generateULID, isULID } from './ulid.js';
-export { wrapPodStore, createPodStore, wrapBundleStore, createBundleStore } from './pod-store.js';
-export type { WrappedPodNoydbStore, WrapPodStoreOptions, WrappedBundleNoydbStore, WrapBundleStoreOptions, } from './pod-store.js';
-export { BundleIntegrityError, BundleSealMismatchError, PodVersionConflictError, BundleVersionConflictError, BackupLedgerError, BackupCorruptedError, } from '../kernel/errors.js';
-export { readPodRedirect } from './bundle.js';
+export { wrapPodStore, createPodStore } from './pod-store.js';
+export type { WrappedPodNoydbStore, WrapPodStoreOptions, } from './pod-store.js';
+export { PodIntegrityError, PodSealMismatchError, PodVersionConflictError, BackupLedgerError, BackupCorruptedError, } from '../kernel/errors.js';
+export { readPodRedirect } from './pod.js';
 export { signRedirect, verifyRedirect, followRedirects } from './redirect.js';
 export type { Redirect, RedirectHop, FollowRedirectsResult } from './redirect.js';
 export type { DocSigner } from '../with-audit/attestation/signer.js';

package/dist/with-pod/open.d.ts

@@ -6,7 +6,7 @@
  * reachable through published seams). Composes, in order:
  *
  *   1. `readPod` — parse + integrity-check the container (throws
- *      `BundleIntegrityError` on a corrupted/truncated pod).
+ *      `PodIntegrityError` on a corrupted/truncated pod).
  *   2. `verifyPodHeader` — only when `opts.trustedKeys` is supplied.
  *      `'unsigned'` is benign (legacy pod, or `writePod({ sign: false })`)
  *      and open() proceeds; `'untrusted'` / `'tampered'` are fail-closed —
@@ -63,7 +63,7 @@
  * @module
  */
 import type { NoydbPodHeader } from './format.js';
-import type { PodVerifyResult } from './bundle.js';
+import type { PodVerifyResult } from './pod.js';
 import type { Noydb } from '../kernel/noydb.js';
 import type { Vault } from '../kernel/vault.js';
 import type { NoydbOptions, NoydbStore, EchoSecretParts } from '../kernel/types.js';

package/dist/with-pod/pod-handle.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Vault bundle handle — the stable opaque ULID identifying a vault
+ * across `.noydb` exports.
+ *
+ * Behaviour is byte-identical to the inline `Vault.getPodHandle`
+ * method this function replaced. `Vault` keeps the public method as
+ * a thin delegator.
+ *
+ * Internal — reached through `vault.getPodHandle()`.
+ */
+import type { NoydbStore } from '../kernel/types.js';
+/**
+ * Return the stable opaque bundle handle for the given vault adapter,
+ * generating and persisting a fresh ULID on first call.
+ *
+ * See {@link import('../kernel/vault.js').Vault.getPodHandle} for
+ * the full rationale and storage-path documentation.
+ */
+export declare function buildPodHandle(adapter: NoydbStore, name: string): Promise<string>;

package/dist/with-pod/pod-store.d.ts

@@ -44,11 +44,3 @@ export declare function wrapPodStore(bundle: NoydbPodStore, options?: WrapPodSto
  * analogous to `createStore` for KV stores.
  */
 export declare function createPodStore<TOptions>(factory: (options: TOptions) => NoydbPodStore): (options: TOptions) => NoydbPodStore;
-/** @deprecated Use wrapPodStore. */
-export declare const wrapBundleStore: typeof wrapPodStore;
-/** @deprecated Use createPodStore. */
-export declare const createBundleStore: typeof createPodStore;
-/** @deprecated Use WrappedPodNoydbStore. */
-export type WrappedBundleNoydbStore = WrappedPodNoydbStore;
-/** @deprecated Use WrapPodStoreOptions. */
-export type WrapBundleStoreOptions = WrapPodStoreOptions;

package/dist/with-pod/{bundle.d.ts → pod.d.ts}

@@ -36,7 +36,7 @@ import { type NoydbPodHeader, type UnlockMethod } from './format.js';
 import type { Redirect } from './redirect.js';
 import type { DocSigner } from '../with-audit/attestation/signer.js';
 import type { Vault } from '../kernel/vault.js';
-import type { BundleRecipient } from '../with-party/team/keyring.js';
+import type { PodRecipient } from '../with-party/team/keyring.js';
 import type { Cover } from '../with-party/directory/cover/types.js';
 import type { SealingKeyProvider, RecipientSealer, RecipientHint } from '../with-party/team/managed-secret.js';
 /**
@@ -128,7 +128,7 @@ export interface WritePodOptions {
      * the bundle inherits the source keyring as-is (today's behaviour,
      * suited to personal backup-and-restore).
      */
-    readonly recipients?: readonly BundleRecipient[];
+    readonly recipients?: readonly PodRecipient[];
     /**
      * Auto-unlock — unsealed per-user credentials.
      *
@@ -266,8 +266,6 @@ export interface WritePodOptions {
      */
     readonly redirect?: Redirect;
 }
-/** @deprecated Use `WritePodOptions`. */
-export type WriteNoydbBundleOptions = WritePodOptions;
 /**
  * Every key `writePod` reads, in declaration order (#991).
  *
@@ -289,7 +287,7 @@ export declare const WRITE_POD_OPTION_KEYS: readonly ["compression", "collection
  * actually restore a vault. Splitting the layers keeps the
  * bundle module free of crypto concerns — see file-level docs.
  */
-export interface NoydbBundleReadResult {
+export interface PodReadResult {
     readonly header: NoydbPodHeader;
     readonly dumpJson: string;
     /**
@@ -317,7 +315,7 @@ export interface NoydbBundleReadResult {
  * auto-unlock paths. Without these the reader behaves exactly as before
  * (header parsed; body returned as `dumpJson`).
  */
-export interface ReadNoydbBundleOptions {
+export interface ReadPodOptions {
     /**
      * Recipient-side sealing providers used to unseal entries from
      * `sealedSecrets`. The reader picks the one whose `.id`
@@ -373,7 +371,7 @@ export declare function resetBrotliSupportCache(): void;
  *
  * Pipeline:
  *   1. Resolve or create the compartment's stable bundle handle
- *      via `vault.getBundleHandle()` — same handle on
+ *      via `vault.getPodHandle()` — same handle on
  *      every export from the same vault instance, so cloud
  *      adapters can use it as a primary key.
  *   2. `vault.dump()` → JSON string with encrypted records
@@ -398,7 +396,7 @@ export declare function resetBrotliSupportCache(): void;
  *
  * @internal
  */
-export declare function assembleBundleContainer(opts: {
+export declare function assemblePodContainer(opts: {
     handle: string;
     bodyJsonStr: string;
     compression: WritePodOptions['compression'];
@@ -413,8 +411,6 @@ export declare function assembleBundleContainer(opts: {
     signer?: DocSigner;
 }): Promise<Uint8Array>;
 export declare function writePod(vault: Vault, opts?: WritePodOptions): Promise<Uint8Array>;
-/** @deprecated Use `writePod`. */
-export declare const writeNoydbBundle: typeof writePod;
 /**
  * Read just the bundle header — no body decompression, no
  * integrity verification. Intended for cloud-listing UIs that want
@@ -430,8 +426,6 @@ export declare const writeNoydbBundle: typeof writePod;
  * range requests against bundles that may carry icons.
  */
 export declare function readPodHeader(bytes: Uint8Array): NoydbPodHeader;
-/** @deprecated Use `readPodHeader`. */
-export declare const readNoydbBundleHeader: typeof readPodHeader;
 /**
  * Outcome of {@link verifyPodHeader}.
  *
@@ -457,7 +451,7 @@ export interface PodVerifyResult {
  * (`keyId → publicKeyB64` the caller already trusts), it reports whether the
  * header was signed by a trusted document signer.
  *
- * Pairs with the signing half in `assembleBundleContainer`/`writePod`: the
+ * Pairs with the signing half in `assemblePodContainer`/`writePod`: the
  * signed payload is the final wire header with `sig` removed, so verification
  * reconstructs it by stripping EXACTLY the `sig` field — `keyId`, `sigAlg`,
  * and every other header field stay in the verified payload.
@@ -469,7 +463,7 @@ export interface PodVerifyResult {
  * header (which includes the *claimed* `bodySha256`) is signed by a trusted
  * key; it does NOT prove the body matches that hash. To trust the pod's
  * BODY you MUST also confirm the body hashes to `header.bodySha256` — call
- * `readPod`, which throws `BundleIntegrityError` on mismatch. A `verified`
+ * `readPod`, which throws `PodIntegrityError` on mismatch. A `verified`
  * header paired with a swapped body is caught only by that integrity check.
  * This function stays body-free by design so a static page can authenticate a
  * header without decompressing the body; composing the two checks is the
@@ -498,7 +492,7 @@ export declare function readPodCover(bytes: Uint8Array, opts?: {
  * the header's `redirect` field or `undefined` if the bundle was written
  * without one.
  *
- * The record is returned UNVERIFIED: `validateBundleHeader` only checks
+ * The record is returned UNVERIFIED: `validatePodHeaderFields` only checks
  * its shape at parse time (a parser has no `trustedKeys`). Callers that
  * intend to follow the redirect MUST separately call `verifyRedirect`
  * (`redirect.js`) before trusting `target`.
@@ -510,7 +504,7 @@ export declare function readPodRedirect(bytes: Uint8Array): Redirect | undefined
  * original `vault.dump()` JSON string ready to pass to
  * `vault.load()`.
  *
- * Throws `BundleIntegrityError` if the body's actual SHA-256 does
+ * Throws `PodIntegrityError` if the body's actual SHA-256 does
  * not match the value declared in the header. Distinct from a
  * format error so consumers can pattern-match in catch blocks
  * (corrupted-in-transit vs malformed-by-producer).
@@ -522,6 +516,4 @@ export declare function readPodRedirect(bytes: Uint8Array): Redirect | undefined
  * free of crypto concerns and lets the same code feed format
  * inspectors that never decrypt anything.
  */
-export declare function readPod(bytes: Uint8Array, opts?: ReadNoydbBundleOptions): Promise<NoydbBundleReadResult>;
-/** @deprecated Use `readPod`. */
-export declare const readNoydbBundle: typeof readPod;
+export declare function readPod(bytes: Uint8Array, opts?: ReadPodOptions): Promise<PodReadResult>;

package/dist/with-pod/ulid.d.ts

@@ -39,7 +39,7 @@
  *
  * If a future use case needs timestamp-free handles, a v2 of the
  * format could specify "use the random portion only" without a
- * format break — `validateBundleHeader` only checks the regex
+ * format break — `validatePodHeaderFields` only checks the regex
  * shape, not the encoded timestamp.
  */
 /**

package/dist/with-shape/blobs/blob-compaction.d.ts

@@ -30,6 +30,7 @@
  */
 import type { NoydbStore, SlotInfo } from '../../kernel/types.js';
 import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import { type OrphanChunkReport } from './orphan-report.js';
 export interface BlobFieldPolicy<T = unknown> {
     /**
      * Via port brand marker — lets a `BlobFieldPolicy` satisfy the kernel's
@@ -145,6 +146,18 @@ export interface CompactionResult {
         records: number;
         evicted: number;
     }>;
+    /**
+     * #1133 — chunk rows in `_blob_chunks` with no surviving `_blob_index` entry.
+     * Pre-#1127 residue: unreachable by every reader AND by rotation, so for a
+     * legacy blob the bytes stay openable under a retired `_blob` DEK.
+     *
+     * REPORTED, never reclaimed — deciding "orphaned" means trusting the store's
+     * `list`, and a store that withholds one index row would have us destroy a
+     * LIVE blob's chunks. See `orphan-report.ts` for the full argument. A vault
+     * that has run `migrate()` has no legacy chunks to strand, and `chunks: 0`
+     * is the expected reading everywhere else.
+     */
+    readonly orphanBlobChunks: OrphanChunkReport;
 }
 export interface CompactRunOptions {
     /** Override "now" for deterministic testing. */