@noy-db/hub 0.3.0-pre.9 → 0.4.0-pre.0

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;

package/dist/with-party/team/magic-link-grant.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Magic-link-bound cross-user delegation grants.
+ *
+ * This module is the **core storage + encryption layer** that lets a
+ * grantor issue a tier-DEK to a user whose KEK they do not know. The
+ * trust bridge is provided by the `@noy-db/on-magic-link` package:
+ *
+ *   1. Grantor picks a grantee identity (user id + email handle).
+ *   2. Grantor mints a magic-link token (ULID) via `createMagicLinkToken`.
+ *   3. Grantor derives a **content key** + a **KEK** from
+ *      `(serverSecret, token, vault)` using HKDF-SHA256 with separate
+ *      `info` tags — both callers (grantor and grantee) can derive the
+ *      same keys given the same inputs.
+ *   4. Grantor persists a record in `_magic_link_grants/<token>`:
+ *        - envelope `_data` is AES-GCM encrypted under the content key
+ *        - the inner `wrappedDek` is AES-KW wrapped under the KEK
+ *   5. Grantee receives the URL, derives the same content key + KEK,
+ *      loads the grant, decrypts the envelope, unwraps the tier DEK.
+ *
+ * ## Why a separate collection from `_delegations`
+ *
+ * `_delegations` envelopes are encrypted under a DEK shared across
+ * every vault user (audit-visibility). External auditors / client
+ * portal users have NO pre-existing keyring, so they cannot read that
+ * DEK. Magic-link grants live in their own collection whose envelope
+ * encryption is derived purely from the magic-link URL + server secret
+ * — nothing else is required to decrypt.
+ *
+ * ## Batch grants
+ *
+ * One magic-link token may point to MULTIPLE grants (e.g. the client
+ * portal case: invoices + payments + etax all share one link). Each
+ * grant is persisted under a distinct record id:
+ *
+ *   `<token>` for the single-grant / primary entry
+ *   `<token>:<index>` for subsequent entries
+ *
+ * `listMagicLinkGrants(store, vault, token)` enumerates every record
+ * whose id begins with `<token>` so the claimant can materialize all
+ * DEKs in one pass.
+ *
+ * ## Revocation
+ *
+ * `store.delete(vault, _magic_link_grants, <token>)` immediately
+ * invalidates the link — even if the URL was captured and the server
+ * secret leaked, no payload remains to decrypt.
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { UnlockedKeyring } from './keyring.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+/** Reserved collection holding magic-link grant envelopes. */
+export declare const MAGIC_LINK_GRANTS_COLLECTION = "_magic_link_grants";
+/** HKDF `info` for the AES-GCM content key. Version-namespaced. */
+export declare const MAGIC_LINK_CONTENT_INFO_PREFIX = "noydb-magic-link-content-v1:";
+/** HKDF `info` for the AES-KW KEK. Matches `@noy-db/on-magic-link`. */
+export declare const MAGIC_LINK_KEK_INFO_PREFIX = "noydb-magic-link-v1:";
+/**
+ * Decrypted payload of a magic-link grant record. Mirrors
+ * `DelegationToken` in `team/delegation.ts` but tracked separately
+ * because the two flows persist under different collections + envelope
+ * encryption schemes.
+ */
+export interface MagicLinkGrantPayload {
+    readonly id: string;
+    readonly toUser: string;
+    readonly fromUser: string;
+    readonly tier: number;
+    /** Collection name or `null` for the vault-wide tier DEK. */
+    readonly collection: string | null;
+    /** Optional specific record id scope. */
+    readonly record?: string;
+    /** ISO timestamp — grant expires at this instant. */
+    readonly until: string;
+    /** AES-KW-wrapped tier DEK, unwrap with the magic-link KEK. */
+    readonly wrappedDek: string;
+    /** ISO timestamp the grant was issued. */
+    readonly createdAt: string;
+    /** Optional caller-provided label (surfaced in audit UIs). */
+    readonly note?: string;
+}
+export interface IssueMagicLinkGrantOptions {
+    readonly toUser: string;
+    readonly tier: number;
+    readonly collection?: string;
+    readonly record?: string;
+    readonly until: Date | string;
+    readonly note?: string;
+}
+export interface MagicLinkGrantRecord {
+    /** Store record id — `<token>` or `<token>:<index>` for batch entries. */
+    readonly recordId: string;
+    readonly payload: MagicLinkGrantPayload;
+}
+/**
+ * Derive the AES-GCM content key from the same HKDF inputs used for
+ * the magic-link KEK. Different `info` suffix → domain-separated key.
+ *
+ * Exported so the `@noy-db/on-magic-link` package can share the exact
+ * derivation path without cross-dependency between the two modules.
+ */
+export declare function deriveMagicLinkContentKey(serverSecret: string | Uint8Array<ArrayBuffer>, token: string, vault: string): Promise<EnclaveKey>;
+/**
+ * Persist a magic-link grant record. Caller derives + provides both
+ * the content key and the KEK; this function performs the wrap/encrypt
+ * and writes the envelope.
+ *
+ * `recordId` lets the caller use either the bare token (primary grant)
+ * or a suffixed id (batch entry). The writer is responsible for
+ * collision-avoidance across batch entries.
+ */
+export declare function writeMagicLinkGrant(store: NoydbStore, vault: string, grantor: UnlockedKeyring, contentKey: EnclaveKey, grantKek: EnclaveKey, recordId: string, opts: IssueMagicLinkGrantOptions): Promise<MagicLinkGrantRecord>;
+/**
+ * Fetch + decrypt a single magic-link grant record by id. Returns null
+ * when the record is absent OR when decryption fails (wrong server
+ * secret, wrong vault, tampered envelope) — callers treat a null as
+ * "this URL is not valid for this server".
+ *
+ * The returned payload's `wrappedDek` is still AES-KW-wrapped; the
+ * caller unwraps it with the magic-link KEK to obtain the tier DEK.
+ */
+export declare function readMagicLinkGrantRecord(store: NoydbStore, vault: string, contentKey: EnclaveKey, recordId: string): Promise<MagicLinkGrantPayload | null>;
+/**
+ * Enumerate every grant record sharing the magic-link `token` prefix
+ * (i.e. the primary `<token>` entry plus any `<token>:*` batch entries).
+ * Expired grants are still returned — the caller filters on `until`.
+ */
+export declare function listMagicLinkGrants(store: NoydbStore, vault: string, contentKey: EnclaveKey, token: string): Promise<MagicLinkGrantPayload[]>;
+/**
+ * Unwrap the tier DEK from a grant payload using the magic-link KEK.
+ * Thin wrapper around `unwrapKey` — provided so the claimant can avoid
+ * importing `crypto.js` directly.
+ */
+export declare function unwrapMagicLinkGrant(payload: MagicLinkGrantPayload, grantKek: EnclaveKey): Promise<EnclaveKey>;
+/**
+ * Delete a magic-link grant (primary + every batch entry sharing the
+ * token). Safe to call when nothing exists.
+ */
+export declare function revokeMagicLinkGrant(store: NoydbStore, vault: string, token: string): Promise<number>;
+/**
+ * Compose the batch-entry record id. `index === 0` → bare token.
+ * Subsequent entries use `<token>:<index>` so `store.list()` can
+ * enumerate them all by common prefix.
+ */
+export declare function magicLinkGrantRecordId(token: string, index: number): string;
+/**
+ * True when the payload's `until` is in the past relative to `now`.
+ * Kept here (rather than inlined) so the semantics stay aligned with
+ * the canonical `DelegationToken` expiry check.
+ */
+export declare function isMagicLinkGrantExpired(payload: MagicLinkGrantPayload, now?: Date): boolean;