@noy-db/hub 0.3.0-pre.8 → 0.3.0

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

@@ -0,0 +1,97 @@
+/**
+ * FR-6 — Deed: sealed / hidden-owner provisioning.
+ *
+ * A **Deed** is a vault owned by a *latent* principal who never
+ * authenticates. The owner credential (the random passphrase that
+ * derives `KEK_owner`) is minted machine-side and sealed under a
+ * **non-firm** {@link SealingKeyProvider} — that sealing boundary is
+ * the cryptographic *inalienability anchor*: whoever holds the
+ * provider (the client / their KMS) is the only party that can ever
+ * re-derive `KEK_owner`. A firm-side custodian operates the vault
+ * fully but can never reach the owner key — there is deliberately NO
+ * firm-controlled fallback.
+ *
+ * Provisioning reuses the managed-mode seam:
+ *   - {@link resolveManagedSecret} mints + seals + persists the random
+ *     passphrase at `_meta/sealed-passphrase` (and unseals it on every
+ *     subsequent open through the same provider).
+ *   - {@link createOwnerKeyring} derives `KEK_owner` from that
+ *     passphrase and writes the `_keyring/<ownerUserId>` file.
+ *
+ * On top of that, a Deed writes a `_meta/deed` **marker**. The marker
+ * is PLAINTEXT metadata — it records WHO the latent owner is and WHICH
+ * sealing boundary protects them, so it must be readable without
+ * unlocking the vault (a custodian or auditor inspecting the vault must
+ * be able to see "this is a Deed vault, owner = X, sealed under Y"
+ * without any key). The marker itself is therefore never sealed; only
+ * the owner *credential* is.
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { UnlockedKeyring } from './keyring.js';
+import type { SealingKeyProvider } from './managed-passphrase.js';
+/** Reserved id for the Deed marker under `_meta`. */
+export declare const DEED_RECORD_ID: "deed";
+/**
+ * Plaintext metadata recording a vault's latent-owner Deed. Persisted
+ * at `_meta/deed`. Readable without unlocking the vault by design — it
+ * carries no secret material, only the identity of the latent owner
+ * and the sealing boundary that anchors inalienability.
+ */
+export interface DeedMarker {
+    /** The latent owner principal — the user id of the `_keyring/<id>` owner file. */
+    readonly ownerUserId: string;
+    /**
+     * The `SealingKeyProvider.id` the owner credential is sealed under.
+     * The inalienability anchor: only the holder of this (non-firm)
+     * provider can re-derive `KEK_owner`. Audit metadata — never secret.
+     */
+    readonly sealedUnder: string;
+    /** Always `true` for a Deed — the owner never authenticates interactively. */
+    readonly latent: true;
+    /** ISO-8601 timestamp the Deed was issued. */
+    readonly issuedAt: string;
+    /**
+     * ISO-8601 timestamp the vault was liberated (a new owner claimed it
+     * via the audited Liberate ceremony), if any. Absent until liberation.
+     */
+    readonly liberatedAt?: string;
+}
+/**
+ * Provision a Deed: a latent owner whose credential is sealed under
+ * `sealing` (a NON-firm provider). Mints + seals the owner passphrase
+ * via {@link resolveManagedSecret}, derives the owner keyring via
+ * {@link createOwnerKeyring}, then writes the plaintext `_meta/deed`
+ * marker. Returns the unlocked owner keyring.
+ *
+ * The returned keyring is the only in-memory window onto `KEK_owner`
+ * for this call; the persistent re-entry point is the sealing provider
+ * (re-run {@link resolveManagedSecret} with the same provider to
+ * re-resolve the passphrase, then {@link createOwnerKeyring}/load to
+ * unlock — no interactive passphrase is ever required).
+ *
+ * There is deliberately no firm-controlled fallback: the marker's
+ * `sealedUnder` is the single cryptographic anchor of ownership.
+ */
+export declare function createDeedOwner(store: NoydbStore, vault: string, ownerUserId: string, sealing: SealingKeyProvider): Promise<UnlockedKeyring>;
+/**
+ * Read the {@link DeedMarker} from `_meta/deed`, or `null` if the vault
+ * has no Deed marker (i.e. it is not a Deed vault). Plaintext read — no
+ * unlocking required.
+ */
+export declare function loadDeedMarker(store: NoydbStore, vault: string): Promise<DeedMarker | null>;
+/** Whether `vault` carries a Deed marker (a sealed/latent owner). */
+export declare function isDeedVault(store: NoydbStore, vault: string): Promise<boolean>;
+/**
+ * Persist a {@link DeedMarker} at `_meta/deed`. Mirrors
+ * `saveSealedPassphrase`'s envelope shape: a standard
+ * {@link EncryptedEnvelope} with AES-GCM bypassed (`_iv: ''`), the
+ * payload stored as plaintext JSON in `_data`. The marker is metadata,
+ * not a secret — sealing it would defeat its purpose (auditors /
+ * custodians must read it without a key).
+ *
+ * @internal — used by `createDeedOwner` and (later) the Liberate
+ * ceremony to stamp `liberatedAt`.
+ */
+export declare function saveDeedMarker(store: NoydbStore, vault: string, marker: DeedMarker): Promise<void>;

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

@@ -0,0 +1,88 @@
+/**
+ * Time-boxed cross-tier delegation tokens.
+ *
+ * A higher-tier user can issue a delegation that grants another user
+ * temporary access to records at a specified tier. The delegation is
+ * persisted as an encrypted envelope in the reserved `_delegations`
+ * collection. The target user's runtime scans this collection on every
+ * open and, while `until` is still in the future, merges the
+ * unwrapped tier DEKs into their in-memory DEK map.
+ *
+ * ## Token shape
+ *
+ * ```
+ * {
+ *   id,             // ULID, also the _delegations record id
+ *   toUser,         // grantee user id
+ *   fromUser,       // grantor user id (owner/admin/higher-tier principal)
+ *   tier,           // tier being delegated
+ *   collection,     // collection name OR null for "every collection"
+ *   record,         // optional specific record id
+ *   until,          // ISO timestamp — token expires at this instant
+ *   wrappedDek,     // base64 AES-KW-wrapped tier DEK, wrapped under target KEK
+ *   createdAt,      // ISO timestamp
+ * }
+ * ```
+ *
+ * The ciphertext is stored as a normal noy-db envelope — the
+ * `_delegations` collection has its own DEK shared across all vault
+ * users, so an operator can enumerate active delegations for audit
+ * without being able to *use* them (the `wrappedDek` inside is still
+ * keyed to the target user's KEK).
+ *
+ * ## Revocation
+ *
+ * Delete the `_delegations/<id>` envelope. The target user's runtime
+ * reloads the delegation list at each open and at periodic intervals
+ * (tracked by the caller — this module is pure logic).
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { UnlockedKeyring } from './keyring.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+export declare const DELEGATIONS_COLLECTION = "_delegations";
+/**
+ * Durable payload of a delegation token. Encrypted under the vault's
+ * `_delegations` DEK; the `wrappedDek` inside is additionally wrapped
+ * under the target user's KEK.
+ */
+export interface DelegationToken {
+    readonly id: string;
+    readonly toUser: string;
+    readonly fromUser: string;
+    readonly tier: number;
+    /** Collection name or `null` for all collections. */
+    readonly collection: string | null;
+    /** Optional specific record id scope. */
+    readonly record?: string;
+    readonly until: string;
+    readonly wrappedDek: string;
+    readonly createdAt: string;
+}
+export interface IssueDelegationOptions {
+    readonly toUser: string;
+    readonly tier: number;
+    readonly collection?: string;
+    readonly record?: string;
+    readonly until: Date | string;
+}
+/**
+ * Build and persist a delegation token. The caller must hold a tier-N
+ * DEK and must have already located the target user's keyring file
+ * (so the `wrappedDek` can be re-wrapped against their KEK).
+ */
+export declare function issueDelegation(store: NoydbStore, vault: string, grantor: UnlockedKeyring, targetKek: EnclaveKey | null, delegationsDek: EnclaveKey, opts: IssueDelegationOptions): Promise<DelegationToken>;
+/**
+ * Enumerate every live (non-expired) delegation addressed to `toUser`
+ * and merge the unwrapped tier DEKs into their keyring. Returns the
+ * list of merged delegations so the caller can register per-access
+ * audit context.
+ */
+export declare function loadActiveDelegations(store: NoydbStore, vault: string, user: UnlockedKeyring, delegationsDek: EnclaveKey, now?: Date): Promise<DelegationToken[]>;
+/**
+ * Revoke a delegation by id — the caller resolves the envelope and
+ * issues a `delete`. Provided as a stable helper so the naming is
+ * symmetric to `issueDelegation`.
+ */
+export declare function revokeDelegation(store: NoydbStore, vault: string, id: string): Promise<void>;

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

@@ -0,0 +1,38 @@
+/**
+ * `@noy-db/hub/team` — subpath export for multi-user / sync / keyring.
+ *
+ * Solo-user apps that never call `grant()`, `db.push()`, or open a
+ * sync target can exclude this subpath entirely — bundle savings
+ * estimated at ~4-6 KB.
+ *
+ * The main `@noy-db/hub` entry still re-exports every symbol for
+ * backward compatibility — direct subpath import is purely a
+ * tree-shaking opt-in.
+ *
+ * Named re-exports (not `export *`) so tsup keeps the barrel
+ * populated even with `sideEffects: false`.
+ */
+export { withTeam } from './active.js';
+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 { enrollAuthenticator, removeAuthenticator, updateAuthenticator, findAuthenticator, } from './authenticators.js';
+export type { EnrollAuthenticatorOptions, EnrollAuthenticatorWrappingKEKOptions, EnrollAuthenticatorWrappingDEKsOptions, UpdateAuthenticatorOptions, } from './authenticators.js';
+export { rotatePassphrase, recoverPassphrase, } from './rotate-recover.js';
+export type { RotatePassphraseInput, RecoverPassphraseInput, RecoverPassphraseResult, RecoveryProof, SlotRewrapContext, SlotRewrapCeremony, } from './rotate-recover.js';
+export { recoverUser } from './peer-recover.js';
+export type { RecoverUserOptions } from './peer-recover.js';
+export { mintPaperRecoveryEntry, unwrapDeksFromPaperEntry, loadPaperRecoveryEntries, savePaperRecoveryEntries, burnPaperRecoveryEntry, } from './recovery.js';
+export type { PaperRecoveryEntry } from './recovery.js';
+export { mintWrappedDeksBlob, unwrapDeksFromBlob, } from './wrapped-deks.js';
+export type { WrappedDeksBlob } from './wrapped-deks.js';
+export { writeMagicLinkGrant, readMagicLinkGrantRecord, listMagicLinkGrants, unwrapMagicLinkGrant, revokeMagicLinkGrant, deriveMagicLinkContentKey, magicLinkGrantRecordId, isMagicLinkGrantExpired, } from './magic-link-grant.js';
+export { hasExportCapability, evaluateExportCapability, } from './keyring.js';
+export { hasImportCapability, evaluateImportCapability, } from './keyring.js';
+export { SyncEngine } from './sync.js';
+export { SyncTransaction } from './sync-transaction.js';
+export { PresenceHandle } from './presence.js';
+export { putCredential, getCredential, deleteCredential, listCredentials, credentialStatus, SYNC_CREDENTIALS_COLLECTION, } from './sync-credentials.js';
+export type { SyncCredential } from './sync-credentials.js';

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

@@ -0,0 +1,318 @@
+import type { NoydbStore, KeyringFile, KeyringAuthenticator, Role, Permissions, GrantOptions, RevokeOptions, UpdateUserOptions, UserInfo, ExportCapability, ExportFormat, ImportCapability, VaultPolicyOnDisk, UserEnvelope as UserEnvelopeReader } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import { type PassphrasePolicy } from '../../kernel/validation.js';
+/** In-memory representation of an unlocked keyring. */
+export interface UnlockedKeyring {
+    readonly userId: string;
+    readonly displayName: string;
+    readonly role: Role;
+    readonly permissions: Permissions;
+    readonly deks: Map<string, EnclaveKey>;
+    /**
+     * The KEK, when this keyring was unlocked via tier 1 (passphrase) or
+     * a wrap-KEK tier-2 method (WebAuthn / OIDC). `null` when the
+     * keyring was opened via:
+     *
+     *   - Unencrypted mode (no KEK exists)
+     *   - Tier-3 PIN quick-resume (`@noy-db/on-pin`)
+     *   - Wrap-DEKs tier-2 unlock (`@noy-db/on-password`'s
+     *     `verifyPasswordSlot`)
+     *   - Session-state restore (`session/session.ts`)
+     *   - Dev-unlock fixture (`session/dev-unlock.ts`)
+     *
+     * Consumers performing tier-1 operations that need the KEK
+     * (DEK rewrap, keyring persist, delegation issue/unwrap) must
+     * null-check and throw a clear error if absent — re-authenticate
+     * at tier 1 first to recover the KEK.
+     *
+     * Tightened from `EnclaveKey` to `EnclaveKey | null`; the runtime
+     * contract has always allowed null, the type now matches reality.
+     */
+    readonly kek: EnclaveKey | null;
+    readonly salt: Uint8Array;
+    /**
+     * Debug-plaintext layout flag. Set only on the plaintext keyring created
+     * in `encrypt: false` + `debugPlaintext: true` mode — it lives here
+     * because its lifecycle is identical to the plaintext keyring's (no
+     * encrypted vault ever has it, so this never widens the encrypted surface).
+     * When true, user-collection records are written with their fields inlined
+     * beside the envelope metadata (`_debug: 1`) so native store tooling can
+     * read them without unwrapping `_data`.
+     */
+    readonly debugPlaintext?: boolean;
+    /**
+     * `@noy-db/as-*` export capability. Absent when the
+     * keyring was written before this RFC landed — role-based defaults
+     * apply via `hasExportCapability`.
+     */
+    readonly exportCapability?: ExportCapability;
+    /**
+     * `@noy-db/as-*` import capability. Absent when the
+     * keyring was written before the import-capability extension
+     * landed — default-closed semantics
+     * apply via `hasImportCapability` (no plaintext format granted, no
+     * bundle import granted, regardless of role).
+     */
+    readonly importCapability?: ImportCapability;
+    /**
+     * Tier-2 authenticator slots — readonly snapshot loaded from the
+     * keyring file. Mutations go through `enrollAuthenticator` /
+     * `removeAuthenticator`, which write back via
+     * `persistKeyring`. Always defined; loads with an empty array for
+     * keyrings written before the multi-slot extension landed.
+     */
+    readonly authenticators: readonly KeyringAuthenticator[];
+    /**
+     * Reserved per-keyring policy override (forward-compat for Option C
+     * — see {@link VaultPolicyOnDisk}). v1.0 round-trips this field but
+     * never enforces it; the gate engine uses `_meta/policy` only.
+     */
+    readonly policy?: VaultPolicyOnDisk;
+}
+/** Mint a fresh wrapped-canary string. Deterministic for a given KEK. */
+export declare function mintKeyringCanary(kek: EnclaveKey): Promise<string>;
+/** Load and unlock a user's keyring for a vault. */
+export declare function loadKeyring(adapter: NoydbStore, vault: string, userId: string, passphrase: string): Promise<UnlockedKeyring>;
+/**
+ * Open-policy pre-gate: decide create-vs-fail-closed **before** any
+ * vault write. `openVault` must not self-provision an owner keyring into a
+ * vault held by other principals; create-on-open is allowed only for a
+ * genuinely-new vault (no `_keyring/*` at all). Capability-free — one
+ * `store.list`. Returns when the open may proceed (the caller is a member, or
+ * the vault is genuinely-new and `create` is allowed, in which case the caller
+ * falls through to the normal `createOwnerKeyring` path); throws `NoAccessError`
+ * otherwise. Placed before managed-passphrase secret resolution (which persists
+ * on first open), so a fail-closed open writes nothing.
+ */
+export declare function assertKeyringOpenAllowed(store: NoydbStore, vault: string, userId: string, create: boolean): Promise<void>;
+/**
+ * Create the initial owner keyring for a new vault.
+ *
+ * Pass `{ validate: true }` (or a `PassphrasePolicy`) to gate creation
+ * on the phrase-format strength rules — `Noydb` threads this from
+ * `NoydbOptions.validatePassphrase`. Direct callers (CLI, scripts,
+ * test fixtures) opt in explicitly.
+ */
+export declare function createOwnerKeyring(adapter: NoydbStore, vault: string, userId: string, passphrase: string, passphraseOpts?: PassphrasePolicy & {
+    validate?: boolean;
+    allowWeakPassphrase?: boolean;
+}): Promise<UnlockedKeyring>;
+/** Grant access to a new user. Caller must have grant privilege. */
+export declare function grant(adapter: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: GrantOptions): Promise<void>;
+/** Revoke a user's access. Optionally rotate keys for affected collections. */
+export declare function revoke(adapter: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: RevokeOptions): Promise<void>;
+/**
+ * Mutate `role`, `displayName`, and/or `permissions` on an existing
+ * keyring. Pure plaintext-header rewrite — no DEK rewrap, no KEK
+ * required, no authenticator slots touched. Tier-2 enrollments and
+ * recovery codes survive the operation.
+ *
+ * Role-elevation guard: BOTH the old role AND the new role must
+ * satisfy `canUpdateRole(callerRole, _)`. This blocks the two
+ * privilege-escalation shapes:
+ *   - admin elevates someone (or themselves) to owner
+ *   - admin demotes an owner to a role they then control
+ *
+ * Owner is always allowed. Admin manages admin / operator / viewer /
+ * client laterally.
+ *
+ * Identity preserved: same userId, same DEK wrappings. Last-write-wins
+ * through the standard keyring put (same concurrency story as `grant`
+ * and `revoke`).
+ *
+ * @throws `NoAccessError` when no keyring exists for the target.
+ * @throws `PermissionDeniedError` when the role hierarchy rejects.
+ * @throws `ValidationError` when the diff is empty (nothing to update).
+ *
+ */
+export declare function updateKeyringIdentity(adapter: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: UpdateUserOptions): Promise<void>;
+/**
+ * Rotate DEKs for specified collections:
+ * 1. Generate new DEKs
+ * 2. Re-encrypt all records in affected collections
+ * 3. Re-wrap new DEKs for all remaining users
+ */
+export declare function rotateKeys(adapter: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, collections: string[]): Promise<void>;
+/**
+ * Change the user's passphrase. Re-wraps every DEK under the new KEK.
+ *
+ * Validates the new passphrase against the strength rules unless
+ * `allowWeakPassphrase: true` is passed. Mirrors `rotatePassphrase`'s
+ * default-on validation contract.
+ *
+ * `db.rotatePassphrase()` adds a `checkGate('rotate-passphrase')` step
+ * on top of this primitive and additionally requires the OLD passphrase
+ * for re-derivation; `changeSecret` reuses the cached unlocked KEK so
+ * the OLD passphrase is not retyped.
+ */
+export declare function changeSecret(adapter: NoydbStore, vault: string, keyring: UnlockedKeyring, newPassphrase: string, passphraseOpts?: PassphrasePolicy & {
+    allowWeakPassphrase?: boolean;
+}): Promise<UnlockedKeyring>;
+/**
+ * Recipient slot in a re-keyed `.noydb` bundle. Each slot becomes its
+ * own keyring file inside the bundle, sealed with its own passphrase.
+ * Same role/permission semantics as `db.grant()` but no adapter side
+ * effect — the slot only exists inside the bundle bytes.
+ *
+ * @public
+ */
+export interface BundleRecipient {
+    /** User id stamped onto the keyring file in the bundle. */
+    readonly id: string;
+    /** Optional display name. Defaults to `id`. */
+    readonly displayName?: string;
+    /** Passphrase the recipient will type to unlock. */
+    readonly passphrase: string;
+    /** Role on the destination vault. Defaults to `'viewer'`. */
+    readonly role?: Role;
+    /**
+     * Per-collection permissions. When omitted, role defaults apply.
+     * Restricting permissions here ALSO restricts which DEKs are wrapped
+     * into the slot — a slot with `{ invoices: 'ro' }` cannot decrypt
+     * other collections even though their ciphertext sits in the bundle.
+     */
+    readonly permissions?: Permissions;
+    /**
+     * Optional `as-*` export grants on the destination vault.
+     * Mirrors the `exportCapability` field on a live keyring.
+     */
+    readonly exportCapability?: ExportCapability;
+    /**
+     * Optional `as-*` import grants on the destination vault.
+     * Mirrors the `importCapability` field on a live keyring.
+     * Default-closed: no plaintext format granted, no bundle import.
+     */
+    readonly importCapability?: ImportCapability;
+    /**
+     * Optional bundle-slot expiry. ISO-8601 timestamp; past the
+     * cutoff this slot's keyring refuses to load with
+     * `KeyringExpiredError`. Time-boxed audit access pattern: "this
+     * slot works for 30 days then becomes opaque to its holder."
+     */
+    readonly expiresAt?: string;
+}
+/**
+ * Build a `KeyringFile` for one bundle recipient, given the source
+ * vault's unwrapped DEKs. Mirrors `grant()` minus the adapter write —
+ * the produced file is meant to be embedded in the bundle's
+ * `keyrings` map, never persisted to the source vault.
+ *
+ * Privilege-escalation check still runs: every DEK wrapped into the
+ * recipient's keyring must come from the source's own DEK set.
+ *
+ * @internal
+ */
+export declare function buildRecipientKeyringFile(callerKeyring: UnlockedKeyring, recipient: BundleRecipient): Promise<KeyringFile>;
+/** List all users with access to a vault. */
+export declare function listUsers(adapter: NoydbStore, vault: string): Promise<UserInfo[]>;
+/**
+ * Optional filter knobs for {@link listUsersWithEnvelopes}.
+ *
+ * - `includeHidden` — when true, principals with `_meta/visibility/<id>`
+ *   set to `{ hidden: true }` are returned alongside everyone else.
+ *   Requires `owner` or `admin` callerRole; lower roles get
+ *   {@link import('../../kernel/errors.js').PermissionDeniedError}.
+ */
+export interface ListUsersOptions {
+    readonly includeHidden?: boolean;
+}
+/**
+ * Joined enumeration: every keyring + its `_users/<keyringId>`
+ * envelope side by side. Convenience for admin UIs that want to
+ * render team-member lists with profile data ("Bob — operator —
+ * 'Bob the Auditor' avatar X locale fr-FR") in a single pass.
+ *
+ * `userEnvelopeDek` is the vault's `_users` collection DEK
+ * (`vault.getDEK('_users')`); used to decrypt every envelope.
+ *
+ * `callerRole` drives the directory-visibility checks:
+ *
+ *  - When the vault's `_meta/directory` document has `enabled: false`,
+ *    only `owner` and `admin` callers may enumerate; anyone else gets
+ *    {@link import('../../kernel/errors.js').DirectoryDisabledError}.
+ *  - Principals with `_meta/visibility/<id>` set to `{ hidden: true }`
+ *    are filtered out by default. `owner`/`admin` callers can pass
+ *    `{ includeHidden: true }` to see them; lower roles passing that
+ *    option get `PermissionDeniedError`.
+ *
+ * Honest caveat: these filters are a UX hint, not a security
+ * boundary. The keyring file is still listed at `_keyring/*` and the
+ * envelope ciphertext at `_users/*`. A caller with direct store access
+ * — or a caller that calls this function with `callerRole: 'owner'`
+ * unconditionally — sees every principal. The protection is only as
+ * strong as the role the calling layer passes in. The hub-level wrapper
+ * on `Vault` sources `callerRole` from the unlocked keyring's `role`
+ * field, which is signed-by-construction (it lives in the user's own
+ * keyring file). See `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md` →
+ * "Directory visibility".
+ *
+ * Principals without a persisted envelope (legacy keyrings predating
+ * the user-envelope feature) come back with `envelope: null`. The
+ * caller chooses how to render — usually "fall back to keyring's
+ * `displayName`".
+ *
+ * Order matches `listUsers()` (store-defined; sort if you need a
+ * stable display order).
+ */
+export declare function listUsersWithEnvelopes<T = unknown>(adapter: NoydbStore, vault: string, userEnvelopeDek: EnclaveKey, callerRole: Role, options?: ListUsersOptions): Promise<Array<{
+    user: UserInfo;
+    envelope: UserEnvelopeReader<T> | null;
+}>>;
+/** Ensure a DEK exists for a collection. Generates one if new. */
+export declare function ensureCollectionDEK(adapter: NoydbStore, vault: string, keyring: UnlockedKeyring): Promise<(collectionName: string) => Promise<EnclaveKey>>;
+/** 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. */
+export declare function hasAccess(keyring: UnlockedKeyring, collectionName: string): boolean;
+/** Persist a keyring file to the adapter. */
+export declare function persistKeyring(adapter: NoydbStore, vault: string, keyring: UnlockedKeyring): Promise<void>;
+/**
+ * Check whether a keyring is authorised for a given `@noy-db/as-*`
+ * export tier.
+ *
+ * - `tier: 'plaintext'` — returns true iff `exportCapability.plaintext`
+ *   contains the requested `format` or the `'*'` wildcard. Default for
+ *   every role is empty — no grant, no plaintext export.
+ * - `tier: 'bundle'` — returns `exportCapability.bundle` if present, or
+ *   the role-based default otherwise (owner/admin → true, else false).
+ *
+ * `@noy-db/as-*` packages MUST call this before invoking the underlying
+ * export primitive. Rogue forks that skip the check are caught by code
+ * review — the single-entry-point contract is a convention, not a
+ * runtime invariant. Vault-level gated wrappers
+ * (`vault.exportRecords` / `exportBlobs` / `writeBundle`) will land in a
+ * follow-up PR to enforce at the primitive level.
+ */
+export declare function hasExportCapability(keyring: UnlockedKeyring, tier: 'plaintext', format: ExportFormat): boolean;
+export declare function hasExportCapability(keyring: UnlockedKeyring, tier: 'bundle'): boolean;
+/**
+ * Same-shape inspector for an `ExportCapability` value that isn't yet
+ * attached to a keyring (e.g. for previewing a grant before applying).
+ * Role must be supplied separately so bundle defaults can be computed.
+ */
+export declare function evaluateExportCapability(capability: ExportCapability | undefined, role: Role, tier: 'plaintext', format: ExportFormat): boolean;
+export declare function evaluateExportCapability(capability: ExportCapability | undefined, role: Role, tier: 'bundle'): boolean;
+/**
+ * Check whether a keyring is authorised for a given `@noy-db/as-*`
+ * import tier (issue ).
+ *
+ * - `tier: 'plaintext'` — true iff `importCapability.plaintext`
+ *   contains the requested `format` or the `'*'` wildcard.
+ * - `tier: 'bundle'` — true iff `importCapability.bundle === true`.
+ *
+ * **Default-closed for every role on every dimension** — including
+ * owner. Import is more dangerous than export (corrupts vs leaks), so
+ * the policy refuses to assume intent. Owners must positively grant
+ * the capability via `vault.grant({ importCapability: ... })`.
+ */
+export declare function hasImportCapability(keyring: UnlockedKeyring, tier: 'plaintext', format: ExportFormat): boolean;
+export declare function hasImportCapability(keyring: UnlockedKeyring, tier: 'bundle'): boolean;
+/**
+ * Same-shape inspector for an `ImportCapability` value that isn't yet
+ * attached to a keyring (e.g. previewing a grant before applying).
+ * `role` is accepted for symmetry with `evaluateExportCapability` even
+ * though the import policy ignores it — bundle defaults are
+ * role-agnostic and closed.
+ */
+export declare function evaluateImportCapability(capability: ImportCapability | undefined, role: Role, tier: 'plaintext', format: ExportFormat): boolean;
+export declare function evaluateImportCapability(capability: ImportCapability | undefined, role: Role, tier: 'bundle'): boolean;