@noy-db/hub 0.1.0-pre.10

package/dist/index.d.cts

@@ -0,0 +1,565 @@
+import { at as NoydbStore, aR as UserEnvelope, aS as PublicEnvelope, aT as GateName, aU as GatePolicy, aV as VaultPolicy, aW as ActiveTier, aX as FactorProof, ar as UnlockedKeyring, aY as Vault, aA as DiffEntry } from './types-zwwMOqkg.cjs';
+export { aZ as AccessibleVault, ax as AppendInput, p as BLOB_CHUNKS_COLLECTION, q as BLOB_COLLECTION, t as BLOB_INDEX_COLLECTION, u as BLOB_SLOTS_PREFIX, w as BLOB_VERSIONS_PREFIX, a_ as BUNDLE_STORE_POLICY, A as BlobObject, C as BlobPutOptions, E as BlobResponseOptions, F as BlobSet, a$ as BuiltInGateName, b0 as BundleRecipient, _ as CONSENT_AUDIT_COLLECTION, b1 as CacheOptions, b2 as CacheStats, b3 as ChangeEvent, ay as ChangeType, a7 as ClosePeriodOptions, b4 as Collection, b5 as CollectionChangeEvent, b6 as CollectionConflictResolver, ai as CollectionFrame, az as CollectionInstant, b7 as Conflict, b8 as ConflictPolicy, b9 as ConflictStrategy, $ as ConsentAuditEntry, a0 as ConsentAuditFilter, a1 as ConsentContext, a2 as ConsentOp, ba as CrossTierAccessEvent, L as DEFAULT_CHUNK_SIZE, bb as DEFAULT_PUBLIC_ENVELOPE_SCHEMA, bc as DELEGATIONS_COLLECTION, D as DICT_COLLECTION_PREFIX, bd as DeepPartial, be as DeepPartialOrNull, bf as DelegationToken, bg as DeleteManyResult, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, bh as DirtyEntry, bi as ELEVATION_AUDIT_COLLECTION, bj as ElevatedHandle, av as EncryptedEnvelope, bk as EnrollAuthenticatorOptions, bl as EnrollAuthenticatorWrappingDEKsOptions, bm as EnrollAuthenticatorWrappingKEKOptions, bn as ExportCapability, bo as ExportChunk, bp as ExportFormat, bq as ExportStreamOptions, br as FactorKind, bs as FactorProofBundle, bt as FactorRequirement, bu as GhostRecord, bv as GrantOptions, bw as HistoryConfig, bx as HistoryEntry, au as HistoryOptions, e as I18nTextDescriptor, f as I18nTextOptions, by as INDEXED_STORE_POLICY, bz as ImportCapability, bA as InferOutput, bB as IssueDelegationOptions, bC as IssueMagicLinkGrantOptions, aB as JsonPatch, aC as JsonPatchOp, bD as KeyringAuthenticator, bE as KeyringAuthenticatorWrappingDEKs, bF as KeyringAuthenticatorWrappingKEK, bG as KeyringFile, aD as LedgerEntry, aE as LedgerStore, bH as ListAccessibleVaultsOptions, bI as ListPageResult, bJ as LiveUserEnvelope, bK as LocaleReadOptions, bL as Lru, bM as LruOptions, bN as LruStats, bO as MAGIC_LINK_CONTENT_INFO_PREFIX, bP as MAGIC_LINK_GRANTS_COLLECTION, bQ as MAGIC_LINK_KEK_INFO_PREFIX, bR as MagicLinkGrantPayload, bS as MagicLinkGrantRecord, bT as NOYDB_BACKUP_VERSION, bU as NOYDB_FORMAT_VERSION, bV as NOYDB_KEYRING_VERSION, bW as NOYDB_SYNC_VERSION, bX as Noydb, bY as NoydbBundleStore, bZ as NoydbEventMap, b_ as NoydbOptions, a8 as OpenPeriodOptions, a9 as PERIODS_COLLECTION, b$ as PUBLIC_ENVELOPE_FIELDS, c0 as PaperRecoveryDoc, c1 as PaperRecoveryEntry, c2 as PassphrasePolicy, c3 as PassphraseValidationResult, aa as PeriodRecord, c4 as Permission, c5 as Permissions, c6 as PlaintextTranslatorContext, c7 as PlaintextTranslatorFn, P as PolicyEnforcer, c8 as PresenceHandle, c9 as PresencePeer, aw as PruneOptions, ca as PublicEnvelopeField, cb as PublicEnvelopeSchema, cc as PublicEnvelopeText, cd as PullMode, ce as PullOptions, cf as PullPolicy, cg as PullResult, ch as PushMode, ci as PushOptions, cj as PushPolicy, ck as PushResult, cl as PutManyItemOptions, cm as PutManyOptions, cn as PutManyResult, co as QueryAcrossOptions, cp as QueryAcrossResult, cq as QuickUnlockState, cr as QuickUnlockStore, cs as ReAuthOperation, ct as RecoverPassphraseInput, cu as RecoverPassphraseResult, cv as RecoverUserOptions, cw as RecoveryProof, cx as ResolvedPublicEnvelopeSchema, cy as RevokeOptions, aq as Role, cz as RotatePassphraseInput, cA as SessionPolicy, cB as SetPublicEnvelopeInput, U as SlotInfo, V as SlotRecord, cC as SlotRewrapCeremony, cD as SlotRewrapContext, cE as StandardSchemaV1, cF as StandardSchemaV1Issue, cG as StandardSchemaV1SyncResult, cH as StoreAuth, cI as StoreAuthKind, cJ as StoreCapabilities, cK as SyncEngine, cL as SyncMetadata, cM as SyncPolicy, cN as SyncScheduler, cO as SyncSchedulerStatus, cP as SyncStatus, cQ as SyncTarget, cR as SyncTargetRole, cS as SyncTransaction, cT as SyncTransactionResult, cU as TierMode, cV as TranslatorAuditEntry, al as TxCollection, am as TxContext, cW as TxOp, an as TxVault, cX as USER_ENVELOPE_COLLECTION, cY as USER_ENVELOPE_MAX_BYTES, cZ as Unsubscribe, c_ as UpdateAuthenticatorOptions, c$ as UpdateUserOptions, d0 as UserApi, d1 as UserEnvelopeCheckGate, d2 as UserEnvelopeOversizedError, d3 as UserEnvelopePresented, d4 as UserInfo, d5 as VaultBackup, aF as VaultEngine, aj as VaultFrame, aG as VaultInstant, d6 as VaultPolicyOnDisk, d7 as VaultSnapshot, aH as VerifyResult, W as VersionRecord, d8 as WarningRules, d9 as WeakPassphraseError, da as WeakPassphraseReason, db as WrappedDeksBlob, g as applyI18nLocale, aI as applyPatch, dc as assertStrongPassphrase, dd as buildRecipientKeyringFile, de as burnPaperRecoveryEntry, aJ as canonicalJson, aK as computePatch, n as createEnforcer, df as createNoydb, dg as createStore, dh as deriveMagicLinkContentKey, h as dictCollectionName, i as dictKey, aL as diff, di as enrollAuthenticator, dj as estimateEntropy, dk as evaluateExportCapability, dl as evaluateImportCapability, dm as findAuthenticator, aM as formatDiff, dn as hasExportCapability, dp as hasImportCapability, dq as hasRecoveryEnrolled, aN as hashEntry, j as i18nText, k as isDictCollectionName, l as isDictKeyDescriptor, m as isI18nTextDescriptor, dr as isMagicLinkGrantExpired, ds as isPublicEnvelope, dt as issueDelegation, du as keyringRecoverPassphrase, dv as keyringRotatePassphrase, dw as listMagicLinkGrants, dx as listUsers, dy as listUsersWithEnvelopes, dz as loadActiveDelegations, dA as loadPaperRecoveryEntries, dB as magicLinkGrantRecordId, dC as mintPaperRecoveryEntry, dD as mintWrappedDeksBlob, aO as paddedIndex, aP as parseIndex, dE as readMagicLinkGrantRecord, dF as recoverUser, dG as removeAuthenticator, r as resolveI18nText, dH as resolvePublicEnvelopeSchema, dI as revokeDelegation, dJ as revokeMagicLinkGrant, ao as runTransaction, dK as savePaperRecoveryEntries, aQ as sha256Hex, dL as unwrapDeksFromBlob, dM as unwrapDeksFromPaperEntry, dN as unwrapMagicLinkGrant, v as validateI18nTextValue, dO as validatePassphrase, dP as validatePublicEnvelopeInput, dQ as validateSchemaInput, dR as validateSchemaOutput, o as validateSessionPolicy, dS as writeMagicLinkGrant } from './types-zwwMOqkg.cjs';
+export { d as detectMagic, a as detectMimeType, i as isPreCompressed } from './mime-magic-CBBSOkjm.cjs';
+export { AgeRoute, BlobLifecyclePolicy, BlobStoreRoute, CircuitBreakerOptions, HealthCheckOptions, LogLevel, LoggingOptions, MetricsOptions, OverrideOptions, OverrideTarget, RetryOptions, RouteStatus, RouteStoreOptions, RoutedNoydbStore, StoreCacheOptions, StoreMiddleware, StoreOperation, SuspendOptions, WrapBundleStoreOptions, WrappedBundleNoydbStore, createBundleStore, routeStore, withCache, withCircuitBreaker, withHealthCheck, withLogging, withMetrics, withRetry, wrapBundleStore, wrapStore } from './store/index.cjs';
+import { N as NoydbError } from './index-CLRxPs-W.cjs';
+export { A as AlreadyElevatedError, B as BackupCorruptedError, d as BackupLedgerError, e as BundleIntegrityError, f as BundleVersionConflictError, C as ConflictError, g as DEFAULT_JOIN_MAX_ROWS, h as DanglingReferenceError, i as DecryptionError, j as DelegationTargetMissingError, D as DictKeyInUseError, a as DictKeyMissingError, E as ElevationExpiredError, k as ExportCapabilityError, F as FilenameSanitizationError, G as GroupCardinalityError, I as ImportCapabilityError, l as IndexRequiredError, m as IndexWriteFailureError, n as InvalidKeyError, J as JoinContext, o as JoinLeg, p as JoinStrategy, q as JoinTooLargeError, r as JoinableSource, K as KeyringCorruptError, s as KeyringExpiredError, t as LedgerContentionError, u as LiveQuery, v as LiveUpstream, L as LocaleNotSpecifiedError, M as MissingTranslationError, w as NetworkError, x as NoAccessError, y as NotFoundError, O as OrderBy, P as PathEscapeError, z as PeriodClosedError, H as PermissionDeniedError, Q as PrivilegeEscalationError, U as Query, V as QueryPlan, W as QuerySource, X as ReadOnlyAtInstantError, Y as ReadOnlyError, Z as ReadOnlyFrameError, _ as RefDescriptor, $ as RefIntegrityError, a0 as RefMode, a1 as RefRegistry, a2 as RefScopeError, a3 as RefViolation, R as ReservedCollectionNameError, a4 as ScanBuilder, a5 as ScanPageProvider, a6 as SchemaValidationError, S as SessionExpiredError, b as SessionNotFoundError, c as SessionPolicyError, a7 as StoreCapabilityError, a8 as TamperedError, a9 as TierDemoteDeniedError, aa as TierNotGrantedError, T as TranslatorNotConfiguredError, ab as ValidationError, ac as applyJoins, ad as buildLiveQuery, ae as executePlan, af as ref, ag as resetJoinWarnings } from './index-CLRxPs-W.cjs';
+export { C as CompressionAlgo, N as NOYDB_BUNDLE_FORMAT_VERSION, a as NOYDB_BUNDLE_MAGIC, b as NOYDB_BUNDLE_PREFIX_BYTES, c as NoydbBundleHeader, d as NoydbBundleReadResult, W as WriteNoydbBundleOptions, g as generateULID, h as hasNoydbBundleMagic, i as isULID, r as readNoydbBundle, e as readNoydbBundleHeader, f as readNoydbBundlePublicEnvelope, j as resetBrotliSupportCache, w as writeNoydbBundle } from './index-CD1VnONm.cjs';
+export { a as CrdtMode, b as CrdtState, L as LwwMapState, R as RgaState, Y as YjsState, m as mergeCrdtStates, r as resolveCrdtSnapshot } from './strategy-BSxFXGzb.cjs';
+export { SYNC_CREDENTIALS_COLLECTION, SyncCredential, credentialStatus, deleteCredential, getCredential, listCredentials, putCredential } from './team/index.cjs';
+export { C as CreateSessionOptions, a as CreateSessionResult, D as DevUnlockOptions, S as SessionToken, b as activeSessionCount, c as clearDevUnlock, d as createSession, e as enableDevUnlock, i as isDevUnlockActive, f as isSessionAlive, l as loadDevUnlock, r as resolveSession, g as revokeAllSessions, h as revokeSession } from './dev-unlock-D4xB0_gs.cjs';
+export { a as Clause, C as CollectionIndexes, F as FieldClause, b as FilterClause, G as GroupClause, H as HashIndex, I as IndexDef, O as Operator, e as evaluateClause, c as evaluateFieldClause, r as readPath } from './predicate-SBHmi6D0.cjs';
+export { a as AggregateResult, b as AggregateSpec, c as Aggregation, d as AggregationUpstream, G as GROUPBY_MAX_CARDINALITY, e as GROUPBY_WARN_CARDINALITY, f as GroupedAggregation, g as GroupedQuery, h as GroupedRow, L as LiveAggregation, R as Reducer, i as ReducerOptions, j as avg, l as count, m as groupAndReduce, n as max, o as min, r as reduceRecords, s as sum } from './strategy-D-SrOLCl.cjs';
+export { L as LEDGER_COLLECTION, a as LEDGER_DELTAS_COLLECTION, e as envelopePayloadHash } from './hash--EflSV65.cjs';
+import './lazy-builder-CZVLKh0Z.cjs';
+
+/**
+ * Persistence helpers for per-principal user envelopes stored at
+ * `_users/<keyringId>` (logically: `_meta/user/<keyringId>`).
+ *
+ * Unlike `_meta/policy` and `_meta/handle` which are plaintext, user
+ * envelopes carry user data and are encrypted with a dedicated
+ * {@link USER_ENVELOPE_COLLECTION} DEK (provisioned at vault open and
+ * propagated to every keyring via the system-collection DEK path in
+ * `team/keyring.ts`).
+ *
+ * This module is the **storage primitive** layer. The public API
+ * (`vault.user.*`) sits on top of this; permission gates, own-only
+ * write enforcement, and presence-channel propagation live there.
+ *
+ * @see docs/superpowers/specs/2026-05-05-user-envelope-design.md
+ *
+ * @module
+ */
+
+/**
+ * Read and decrypt the user envelope for `keyringId`. Returns `null`
+ * when no envelope has been persisted (either the principal has never
+ * called `updateMe`, or the keyring predates this feature).
+ *
+ * Decryption errors propagate — a tampered or wrong-keyed envelope
+ * surfaces as the underlying crypto error rather than masquerading as
+ * "not found".
+ */
+declare function loadUserEnvelope<T = unknown>(store: NoydbStore, vault: string, keyringId: string, dek: CryptoKey): Promise<UserEnvelope<T> | null>;
+/**
+ * Encrypt and persist the user envelope for `keyringId`. The new
+ * version is `(prior._v ?? 0) + 1`. Pass `expectedVersion` to enable
+ * optimistic-concurrency checks: a mismatch with the stored version
+ * throws {@link ConflictError} with the actual stored version.
+ *
+ * `expectedVersion: 0` means "expect no prior envelope"; the write
+ * succeeds only if no envelope exists yet.
+ *
+ * Soft-caps the JSON-serialized payload at {@link USER_ENVELOPE_MAX_BYTES};
+ * larger payloads throw {@link UserEnvelopeOversizedError}.
+ */
+declare function saveUserEnvelope<T>(store: NoydbStore, vault: string, keyringId: string, payload: T, dek: CryptoKey, expectedVersion?: number): Promise<UserEnvelope<T>>;
+/**
+ * Delete the user envelope for `keyringId`. Idempotent — no error if
+ * the envelope is already absent. Called from the keyring revoke path
+ * (cascade-delete) and is a no-op for keyrings that never wrote.
+ */
+declare function deleteUserEnvelope(store: NoydbStore, vault: string, keyringId: string): Promise<void>;
+/**
+ * List the keyring ids that have a user envelope persisted in `vault`.
+ * Order is store-defined — callers that need a stable order should sort.
+ */
+declare function listUserEnvelopeIds(store: NoydbStore, vault: string): Promise<string[]>;
+
+/**
+ * Cache policy helpers — parse human-friendly byte budgets into raw numbers.
+ *
+ * Accepted shapes (case-insensitive on suffix):
+ *   number       — interpreted as raw bytes
+ *   '1024'       — string of digits, raw bytes
+ *   '50KB'       — kilobytes (×1024)
+ *   '50MB'       — megabytes (×1024²)
+ *   '1GB'        — gigabytes (×1024³)
+ *
+ * Decimals are accepted (`'1.5GB'` → 1610612736 bytes).
+ *
+ * Anything else throws — better to fail loud at construction time than
+ * to silently treat a typo as 0 bytes (which would evict everything).
+ */
+/** Parse a byte budget into a positive integer number of bytes. */
+declare function parseBytes(input: number | string): number;
+/**
+ * Estimate the in-memory byte size of a decrypted record.
+ *
+ * Uses `JSON.stringify().length` as a stand-in for actual heap usage.
+ * It's a deliberate approximation: real V8 heap size includes pointer
+ * overhead, hidden classes, and string interning that we can't measure
+ * from JavaScript. The JSON length is a stable, monotonic proxy that
+ * costs O(record size) per insert — fine when records are typically
+ * < 1 KB and the cache eviction is the slow path anyway.
+ *
+ * Returns `0` (and the caller must treat it as 1 for accounting) if
+ * stringification throws on circular references; this is documented
+ * but in practice records always come from JSON-decoded envelopes.
+ */
+declare function estimateRecordBytes(record: unknown): number;
+
+/**
+ * Persistence helpers for `_meta/public-envelope`. 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
+ */
+
+/** Reserved id for the vault-level public envelope record. */
+declare const PUBLIC_ENVELOPE_RECORD_ID = "public-envelope";
+/**
+ * Read the public envelope from `_meta/public-envelope`. Returns
+ * `undefined` when no envelope has been persisted (fresh vault, or
+ * a vault written before the feature was enabled). Tolerates
+ * corrupted documents — a JSON parse failure surfaces as `undefined`,
+ * not a thrown error, mirroring `_meta/handle`'s contract.
+ */
+declare function loadPublicEnvelope(store: NoydbStore, vault: string): Promise<PublicEnvelope | undefined>;
+/** Persist the public envelope. Idempotent — overwrites any prior write. */
+declare function savePublicEnvelope(store: NoydbStore, vault: string, envelope: PublicEnvelope): Promise<void>;
+/**
+ * Public, no-key reader. Plain function, not a method on `Noydb` —
+ * the whole point is it works without an authenticated session, so
+ * a UI can show "Acme 2026 Tax Records" before unlocking.
+ *
+ * Resolves any `name` / `description` locale map through the supplied
+ * `locale` (when provided). Omitting `locale` returns the raw
+ * envelope, which a multilingual picker can render as it pleases.
+ */
+declare function readPublicEnvelope(store: NoydbStore, vault: string, opts?: {
+    readonly locale?: string;
+}): Promise<PublicEnvelope | undefined>;
+
+/**
+ * Why a gate denied a request. Stable across hub versions so consumers
+ * can switch on the value in error UIs.
+ */
+type PolicyDenyReason = 'insufficient-tier' | 'missing-factor' | 'stale-proof' | 'disabled' | 'shared-device-blocked';
+/**
+ * Thrown by {@link checkGate} when the active session does not meet
+ * the gate's requirements. Carries the gate name, the reason, and the
+ * full required {@link GatePolicy} so error UIs can prompt the user
+ * for the missing factor without re-reading the policy document.
+ */
+declare class PolicyDeniedError extends NoydbError {
+    readonly gate: GateName;
+    readonly reason: PolicyDenyReason;
+    readonly required: GatePolicy;
+    constructor(gate: GateName, reason: PolicyDenyReason, required: GatePolicy, message?: string);
+}
+/**
+ * Raised by `createNoydb({ ... })` when the developer omits a recovery
+ * profile and `recover-passphrase` is not explicitly disabled. Vaults
+ * MUST have at least one recovery path enrolled before being
+ * production-ready (paper, shamir, multi-channel, or admin-mediated).
+ *
+ * The error references issue #10 in its message so a developer hitting
+ * it gets a one-line pointer to the design.
+ */
+declare class RecoveryNotEnrolledError extends NoydbError {
+    constructor(message?: string);
+}
+/**
+ * Raised by `db.recoverPassphrase` when the developer requests a
+ * recovery profile other than `'paper'` in v0.1.0-pre.5. The other
+ * three profiles (Shamir, multi-channel, admin-mediated) ship the API
+ * shape now; their per-profile dispatch lands in follow-up issues.
+ *
+ * The carried `profile` and `tracking` fields let consumers steer the
+ * UI ("Shamir recovery is not yet wired up — open issue #N to follow").
+ */
+declare class RecoveryProfileNotImplementedError extends NoydbError {
+    readonly profile: string;
+    readonly tracking: string;
+    constructor(profile: string, tracking: string);
+}
+
+/**
+ * Default policy for personal vaults and SMB deployments — the gates
+ * that need an off-device factor get one (TOTP / email-OTP / paper
+ * recovery), the rest take a tier-1 unlock alone. Tier-3 (PIN) is the
+ * floor only for `rotate-unlock` because that's the
+ * "change my PIN" flow.
+ *
+ * The unspecified gates (e.g. `view-user-auth`) inherit the engine
+ * default of `{ enabled: false, minTier: 1 }` — they fail closed.
+ *
+ * @see docs/subsystems/session-tiers.md → Built-in gates
+ */
+declare const PERSONAL_POLICY: VaultPolicy;
+/**
+ * Strict policy for regulated deployments and shared workstations —
+ * raises the phrase floor to 8 words, demands two distinct factors for
+ * exports, and blocks export-on-shared-device. Use as a base for
+ * `policy: { ...STRICT_POLICY, gates: { ...STRICT_POLICY.gates, ... } }`
+ * tweaks.
+ */
+declare const STRICT_POLICY: VaultPolicy;
+/**
+ * Merge a developer override onto a preset. Unspecified gates inherit;
+ * specified gates fully replace the preset's entry for that gate.
+ *
+ * Example:
+ *
+ * ```ts
+ * mergePolicy(PERSONAL_POLICY, {
+ *   gates: {
+ *     'app:approve-large-payment': { minTier: 2, factors: [{ anyOf: ['totp'] }] },
+ *   },
+ * })
+ * // → PERSONAL_POLICY plus the new app gate; existing gates intact.
+ * ```
+ */
+declare function mergePolicy(base: VaultPolicy, override?: Partial<VaultPolicy>): VaultPolicy;
+
+/**
+ * Policy gate engine — the {@link checkGate} entry point.
+ *
+ * Given a configured {@link VaultPolicy}, an active session tier, and
+ * the factor proofs an actor is presenting, decide whether the gate
+ * permits the action. On denial, throws {@link PolicyDeniedError} with
+ * a stable {@link PolicyDenyReason} so consumers can branch in error
+ * UIs.
+ *
+ * @see docs/subsystems/session-tiers.md → checkGate() API
+ *
+ * @module
+ */
+
+/** Default freshness window — 5 minutes. */
+declare const DEFAULT_FRESHNESS_MS: number;
+/** Caller-supplied context for one `checkGate` invocation. */
+interface CheckGateContext {
+    /** Tier the active session currently holds. */
+    readonly activeTier: ActiveTier;
+    /** Proofs the actor is presenting for this gate. */
+    readonly factors?: ReadonlyArray<FactorProof>;
+    /**
+     * If the host knows the actor is on a shared device, set this to
+     * `true` so the engine can apply `warn.sharedDevice` rules. Defaults
+     * to `false`.
+     */
+    readonly sharedDevice?: boolean;
+    /**
+     * Override `now()` for tests. Defaults to `Date.now()`.
+     * @internal
+     */
+    readonly now?: number;
+}
+/**
+ * Decide whether `gate` permits the action under `context`. Throws
+ * {@link PolicyDeniedError} on denial; resolves with `void` on success.
+ *
+ * Lookup rules:
+ * - **Built-in gates** without a configured policy fail closed
+ *   (`enabled: false`).
+ * - **App-defined gates** (`app:*`) without a configured policy are
+ *   treated as no-op (allow). The developer registered the policy if
+ *   they wanted enforcement; absence means the gate is informational.
+ */
+declare function checkGate(policy: VaultPolicy, gate: GateName, context: CheckGateContext): Promise<void>;
+/**
+ * Same as {@link checkGate} but returns a structured verdict instead
+ * of throwing. Useful when an error UI wants to show the user
+ * "you'll need TOTP plus a recovery code to do that" without first
+ * triggering the action.
+ */
+declare function describeGate(policy: VaultPolicy, gate: GateName, context: CheckGateContext): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: PolicyDenyReason;
+    required: GatePolicy;
+}>;
+
+/**
+ * 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 docs/subsystems/session-tiers.md → Storage location
+ *
+ * @module
+ */
+
+/** Reserved collection name for vault-level metadata documents. */
+declare const META_COLLECTION = "_meta";
+/** Reserved id for the vault-level policy document. */
+declare const POLICY_RECORD_ID = "policy";
+/**
+ * Read the vault-level policy from `_meta/policy`. Returns `undefined`
+ * when no policy has been persisted (fresh vault, or a vault written
+ * before the policy module landed). The caller falls back to the
+ * default preset.
+ *
+ * Tolerates corrupted documents the same way `_meta/handle` does: a
+ * JSON parse failure surfaces as `undefined`, not a thrown error, so
+ * a bad write never permanently locks a vault.
+ */
+declare function loadVaultPolicy(store: NoydbStore, vault: string): Promise<VaultPolicy | undefined>;
+/**
+ * Persist the vault-level policy at `_meta/policy`. Idempotent — call
+ * once at vault creation and again on `db.updatePolicy()` invocations.
+ */
+declare function saveVaultPolicy(store: NoydbStore, vault: string, policy: VaultPolicy): Promise<void>;
+
+/**
+ * Authentication introspection — issue #13.
+ *
+ * Three surfaces over the configured tier model and the actual
+ * per-user enrollment state:
+ *
+ * 1. **Vault-wide English summary** — {@link describeAuthConfig}.
+ * 2. **Vault-wide Mermaid diagram** — {@link diagramAuthConfig}.
+ * 3. **Per-user introspection** — {@link describeUserAuth}, gated by
+ *    the `view-user-auth` policy gate (off by default).
+ *
+ * The per-user surface is held to a strict allowlist — fields not on
+ * the allowlist are dropped, never rendered. The negative test in
+ * `auth-introspection.test.ts` exercises the allowlist by feeding a
+ * contrived keyring with fake "secret" fields and asserting that none
+ * of them appear in the output.
+ *
+ * @module
+ */
+
+/** Vault-wide English summary of the configured authentication graph. */
+declare function describeAuthConfig(store: NoydbStore, vault: string): Promise<string>;
+/**
+ * Render the vault's auth graph as Mermaid `flowchart TB` source. The
+ * caller pipes this through Mermaid (CLI or browser) to get an SVG.
+ */
+declare function diagramAuthConfig(store: NoydbStore, vault: string): Promise<string>;
+/**
+ * Render the per-user enrollment summary. Returns an empty
+ * (non-throwing) string when the user has no keyring file — never
+ * confirms or denies the existence of the user from the document
+ * alone.
+ *
+ * Sanitization is strict: only the slot list, enrollment dates, and
+ * recovery-profile counts are rendered. WebAuthn cred ids, OIDC
+ * subject ids, password hashes, recovery codes, TOTP secrets — all
+ * dropped at the allowlist boundary, not redacted.
+ */
+declare function describeUserAuth(store: NoydbStore, vault: string, userId: string): Promise<string>;
+/** Bulk variant for owner dashboards. */
+declare function describeAllUsersAuth(store: NoydbStore, vault: string): Promise<Array<{
+    userId: string;
+    description: string;
+}>>;
+
+interface EncryptResult {
+    iv: string;
+    data: string;
+}
+/**
+ * Encrypt raw bytes with AES-256-GCM using a fresh random IV.
+ * Used by the attachment store so binary blobs avoid double base64 encoding
+ * (the existing `encrypt()` function calls `TextEncoder` on a string — here
+ * we pass the `Uint8Array` directly to `subtle.encrypt`).
+ */
+declare function encryptBytes(data: Uint8Array, dek: CryptoKey): Promise<EncryptResult>;
+/**
+ * Decrypt AES-256-GCM ciphertext back to raw bytes.
+ * Counterpart to `encryptBytes`. Throws `TamperedError` on auth-tag failure.
+ */
+declare function decryptBytes(ivBase64: string, dataBase64: string, dek: CryptoKey): Promise<Uint8Array>;
+/**
+ * Derive an AES-256-GCM presence key from a collection DEK using HKDF-SHA256.
+ *
+ * The presence key is domain-separated from the data DEK by the fixed salt
+ * `'noydb-presence'` and the `info` = collection name. This means:
+ *  - The adapter never sees the presence key.
+ *  - Presence payloads rotate automatically when the collection DEK is rotated.
+ *  - Revoked users cannot derive the new presence key after a DEK rotation.
+ *
+ * @param dek            The collection's AES-256-GCM DEK (extractable).
+ * @param collectionName Used as the HKDF `info` parameter for domain separation.
+ * @returns A non-extractable AES-256-GCM key suitable for presence payload encryption.
+ */
+declare function derivePresenceKey(dek: CryptoKey, collectionName: string): Promise<CryptoKey>;
+/**
+ * Encrypt a plaintext string with AES-256-GCM and a deterministic,
+ * HKDF-derived IV.
+ *
+ * The same `{ dek, context, plaintext }` triple always produces the
+ * same `{ iv, data }` — call this twice and you can string-compare the
+ * ciphertexts to check equality of the inputs without decrypting them.
+ *
+ * @param context  Domain-separation string — by convention
+ *                 `'<collection>/<field>'`. Different contexts encrypt
+ *                 the same plaintext to different ciphertexts, so
+ *                 `email` in collection `users` does not collide with
+ *                 `email` in collection `customers`.
+ */
+declare function encryptDeterministic(plaintext: string, dek: CryptoKey, context: string): Promise<EncryptResult>;
+/**
+ * Counterpart to {@link encryptDeterministic}. The IV is stored
+ * alongside the ciphertext (exactly like the randomized path), so
+ * decrypt uses the stored IV and verifies the GCM auth tag — a tampered
+ * ciphertext throws `TamperedError` just like randomized AES-GCM.
+ */
+declare function decryptDeterministic(ivBase64: string, dataBase64: string, dek: CryptoKey): Promise<string>;
+declare function bufferToBase64(buffer: ArrayBuffer | Uint8Array): string;
+declare function base64ToBuffer(base64: string): Uint8Array<ArrayBuffer>;
+
+/**
+ * Hierarchical access — tier-aware keyring helpers.
+ *
+ * The keyring's existing `deks: Map<string, CryptoKey>` is keyed by
+ * collection name. extends the key space:
+ *
+ *   `'invoices'`      — tier-0 DEK (unchanged from v0.x)
+ *   `'invoices#1'`    — tier-1 DEK
+ *   `'invoices#2'`    — tier-2 DEK
+ *
+ * Tier 0 keeps the bare collection name so any keyring written
+ * before tiers existed loads without migration. Tiers ≥ 1 use `#N`
+ * suffixes that
+ * would be invalid as user-supplied collection names (see
+ * `ReservedCollectionNameError` — `#` is reserved).
+ *
+ * @module
+ */
+
+/** Canonical DEK key for a given collection + tier. Tier 0 → bare name. */
+declare function dekKey(collection: string, tier: number): string;
+/**
+ * Returns the user's effective clearance for a given collection: the
+ * maximum tier for which their keyring holds a DEK. Falls back to 0
+ * when the user has only the tier-0 DEK (or none — the getDEK caller
+ * will raise separately).
+ */
+declare function effectiveClearance(keyring: UnlockedKeyring, collection: string): number;
+/**
+ * Assert the caller is cleared for the requested tier. Owners and
+ * admins always pass (they can mint any new tier DEK on demand);
+ * other roles must already hold the tier DEK — via a prior grant or
+ * an active delegation — otherwise this throws `TierNotGrantedError`.
+ *
+ * This gate runs BEFORE `getDEK()` on the mutation path so a
+ * non-cleared operator never has the opportunity to silently
+ * auto-create a tier DEK they shouldn't have.
+ */
+declare function assertTierAccess(keyring: UnlockedKeyring, collection: string, tier: number): void;
+
+/**
+ * Vault-level diff orchestrator.
+ *
+ * Compares a live `Vault`'s plaintext state against a candidate state
+ * (another vault, a plain `{ collection: records[] }` map, or a vault
+ * dump JSON) and returns a structured `VaultDiff` plan listing the
+ * records that would be added, modified, or deleted to bring the live
+ * vault into the candidate's shape.
+ *
+ * Builds on two existing record-level helpers:
+ *
+ *   1. `diff(a, b)` from `./history/diff.ts` — emits dot-pathed
+ *      `DiffEntry[]` with `type: 'added' | 'removed' | 'changed'` for
+ *      each changed field of two records. Used here for the
+ *      `fieldDiffs` of every `modified` entry, and (with empty result)
+ *      as the default deep-equal check.
+ *
+ *   2. `Vault.exportStream()` from `./vault.ts` — the canonical
+ *      decrypt-and-stream-records iterator. Used to walk both sides
+ *      when the candidate is itself a `Vault`. ACL-scoped: collections
+ *      the caller can't read silently drop out, the same way every
+ *      other plaintext-emitting export pipeline filters them.
+ *
+ * The new orchestration is the **vault-level** enumeration: bucket
+ * each record id into added (only in candidate), deleted (only in
+ * vault), or modified (in both with field changes); leave the
+ * field-level granularity to the existing `diff()`.
+ *
+ * Use cases:
+ *
+ *   - Import preview (`@noy-db/as-*` `fromString` returns a plan
+ *     whose body is a `VaultDiff`).
+ *   - Backup verification ("does this `.noydb` bundle from yesterday
+ *     match the current vault?").
+ *   - Two-vault reconciliation ("what's different between Office A
+ *     and Office B before we sync?").
+ *   - Test assertions (golden-file testing with one-liner
+ *     `expect(plan.summary).toEqual(...)`).
+ *
+ * @module
+ */
+
+/** Per-record entry shape — added and deleted records carry only the record value. */
+interface VaultDiffEntry<T = unknown> {
+    readonly collection: string;
+    readonly id: string;
+    readonly record: T;
+}
+/** Modified records carry both halves of the diff plus the field-level breakdown. */
+interface VaultDiffModifiedEntry<T = unknown> extends VaultDiffEntry<T> {
+    /** The record as it stands in the live vault. */
+    readonly before: T;
+    /** Top-level keys whose values differ between `before` and `record`. */
+    readonly fieldsChanged: readonly string[];
+    /**
+     * Field-level diff entries from `diff(before, record)`. Reuses the
+     * existing per-record diff helper so consumers can render git-style
+     * `path: from → to` rows without re-walking the records.
+     */
+    readonly fieldDiffs: readonly DiffEntry[];
+}
+interface VaultDiff<T = unknown> {
+    readonly added: readonly VaultDiffEntry<T>[];
+    readonly modified: readonly VaultDiffModifiedEntry<T>[];
+    readonly deleted: readonly VaultDiffEntry<T>[];
+    /** Only populated when `options.includeUnchanged: true`. */
+    readonly unchanged: readonly VaultDiffEntry<T>[] | undefined;
+    readonly summary: {
+        readonly add: number;
+        readonly modify: number;
+        readonly delete: number;
+        readonly total: number;
+    };
+    /**
+     * Format the diff as a human-readable string.
+     *
+     *   - `'count'`   — one line, just the numbers (`12 added · 3 modified · 0 deleted`)
+     *   - `'one-line'` — count plus a single overview line
+     *   - `'full'`    — count + one row per added/modified/deleted record (default)
+     */
+    format(opts?: {
+        detail?: 'count' | 'one-line' | 'full';
+    }): string;
+}
+interface DiffOptions {
+    /** Restrict the diff to a subset of collections. */
+    readonly collections?: readonly string[];
+    /** Field on each record that carries its id. Defaults to `'id'`. */
+    readonly idKey?: string;
+    /** Override the default deep-equal check for "modified vs unchanged". */
+    readonly compareFn?: (a: unknown, b: unknown) => boolean;
+    /** If true, include unchanged records in the diff (off by default to save memory). */
+    readonly includeUnchanged?: boolean;
+}
+/**
+ * Candidate state to diff the vault against:
+ *
+ *   - A `Vault` instance — both sides are walked via `exportStream()`.
+ *   - A `Record<collection, records[]>` map — same shape `as-json.toObject()`
+ *     produces. Useful for diffing parsed file content against the live vault.
+ *   - A `VaultDump` (output of `vault.dump()`) — a JSON string carrying the
+ *     full vault state. Parsed and reduced to the map shape above.
+ */
+type DiffCandidate<T = unknown> = Vault | Record<string, readonly T[]> | string;
+/**
+ * Compute the diff between a live vault and a candidate state.
+ *
+ * Returns a fully buffered `VaultDiff` — no streaming. Memory cost is
+ * O(n + m) in the row count of vault + candidate. For documented
+ * 1K-50K-record vaults this is fine; a streaming variant lands as a
+ * follow-up if a > 100K-record consumer arrives.
+ */
+declare function diffVault<T = unknown>(vault: Vault, candidate: DiffCandidate<T>, options?: DiffOptions): Promise<VaultDiff<T>>;
+
+export { ActiveTier, type CheckGateContext, DEFAULT_FRESHNESS_MS, type DiffCandidate, DiffEntry, type DiffOptions, FactorProof, GateName, GatePolicy, META_COLLECTION, NoydbError, NoydbStore, PERSONAL_POLICY, POLICY_RECORD_ID, PUBLIC_ENVELOPE_RECORD_ID, PolicyDeniedError, type PolicyDenyReason, PublicEnvelope, RecoveryNotEnrolledError, RecoveryProfileNotImplementedError, STRICT_POLICY, UnlockedKeyring, UserEnvelope, Vault, type VaultDiff, type VaultDiffEntry, type VaultDiffModifiedEntry, VaultPolicy, assertTierAccess, base64ToBuffer, bufferToBase64, checkGate, decryptBytes, decryptDeterministic, dekKey, deleteUserEnvelope, derivePresenceKey, describeAllUsersAuth, describeAuthConfig, describeGate, describeUserAuth, diagramAuthConfig, diffVault, effectiveClearance, encryptBytes, encryptDeterministic, estimateRecordBytes, listUserEnvelopeIds, loadPublicEnvelope, loadUserEnvelope, loadVaultPolicy, mergePolicy, parseBytes, readPublicEnvelope, savePublicEnvelope, saveUserEnvelope, saveVaultPolicy };