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

package/dist/with-party/session/session.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Session tokens —
+ *
+ * After a vault is unlocked (via passphrase, WebAuthn, OIDC, or magic-
+ * link), the caller can call `createSession()` to get a session token that
+ * allows re-establishing the KEK for the session lifetime without re-running
+ * PBKDF2 or any interactive auth challenge.
+ *
+ * Security model
+ * ──────────────
+ * A session consists of two pieces that must both be present to recover the
+ * KEK:
+ *
+ *   1. The **session key** — a non-extractable AES-256-GCM CryptoKey that
+ *      exists only in memory. "Non-extractable" is enforced by the WebCrypto
+ *      API: the key object cannot be serialized, exported, or sent over
+ *      postMessage. When the JS context is GC'd (tab close, navigation away,
+ *      worker termination) the key becomes unrecoverable.
+ *
+ *   2. The **session token** — a JSON object that carries the KEK wrapped
+ *      with the session key (AES-256-GCM, fresh IV per session), plus
+ *      unencrypted session metadata (sessionId, userId, vault, role,
+ *      expiresAt). The token can be serialized to JSON and stored in
+ *      sessionStorage or passed across callsites within the same tab, but
+ *      it is useless without the session key.
+ *
+ * The session key is kept in a module-level Map indexed by sessionId. Callers
+ * that need to re-use a session must hold on to the sessionId returned from
+ * `createSession()`; the key is looked up automatically by `resolveSession()`.
+ *
+ * Revocation: `revokeSession()` removes the entry from the Map. Because the
+ * key is non-extractable, removal is sufficient — no one holds a serializable
+ * copy of the key.
+ *
+ * Tab-scoped lifetime: the module-level Map lives only as long as the JS
+ * module. Tab close → module unloaded → Map GC'd → all session keys gone.
+ * This is the zero-effort logout: closing the tab is always a secure logout.
+ *
+ * Expiry: `createSession()` accepts a `ttlMs` option. `resolveSession()`
+ * checks `expiresAt` and throws `SessionExpiredError` if the token is stale,
+ * even if the session key is still in the Map.
+ */
+import type { Role } from '../../kernel/types.js';
+import type { UnlockedKeyring } from '../team/keyring.js';
+/** The serializable part of a session token. Safe to store in sessionStorage. */
+export interface SessionToken {
+    readonly _noydb_session: 1;
+    /** Unique session identifier (ULID). Use this as the handle for resolve/revoke. */
+    readonly sessionId: string;
+    readonly userId: string;
+    readonly vault: string;
+    readonly role: Role;
+    /** ISO timestamp — resolveSession() rejects this token after this time. */
+    readonly expiresAt: string;
+    /** KEK wrapped with the session key (AES-256-GCM). Base64. */
+    readonly wrappedKek: string;
+    /** IV used for the wrapping operation. Base64. */
+    readonly kekIv: string;
+}
+/** Result returned from `createSession()`. */
+export interface CreateSessionResult {
+    /** Serializable token — store in sessionStorage or pass to `resolveSession()`. */
+    token: SessionToken;
+    /** The sessionId — use this handle for `resolveSession()` and `revokeSession()`. */
+    sessionId: string;
+}
+/** Options for `createSession()`. */
+export interface CreateSessionOptions {
+    /**
+     * Session lifetime in milliseconds. Defaults to 60 minutes.
+     * After this duration, `resolveSession()` throws `SessionExpiredError`.
+     */
+    ttlMs?: number;
+}
+/**
+ * Create a session for an already-unlocked keyring.
+ *
+ * Call this after any successful unlock (passphrase, WebAuthn, OIDC,
+ * magic-link). The returned `sessionId` is the handle for later
+ * `resolveSession()` and `revokeSession()` calls.
+ *
+ * The session key is generated fresh (non-extractable) and stored in the
+ * module-level Map. The KEK from `keyring.kek` is exported (it must be
+ * extractable — it was derived by `deriveKey()` which sets extractable: false,
+ * but it's unwrapped from the keyring which sets extractable: true) and then
+ * re-wrapped with the session key.
+ *
+ * @param keyring - An already-unlocked keyring whose `kek` is available.
+ * @param vault - The vault name this session is scoped to.
+ * @param options - Optional session configuration.
+ */
+export declare function createSession(keyring: UnlockedKeyring, vault: string, options?: CreateSessionOptions): Promise<CreateSessionResult>;
+/**
+ * Resolve a session token back into an UnlockedKeyring.
+ *
+ * Looks up the session key by `sessionId`, checks the token is not expired,
+ * then decrypts the payload to reconstruct the keyring's DEK set.
+ *
+ * Throws `SessionExpiredError` if the token's `expiresAt` is in the past.
+ * Throws `SessionNotFoundError` if the session key is not in the store
+ * (tab was reloaded, session was revoked, or the sessionId is wrong).
+ *
+ * @param token - The SessionToken from `createSession()`.
+ */
+export declare function resolveSession(token: SessionToken): Promise<UnlockedKeyring>;
+/**
+ * Revoke a session by removing its key from the store.
+ *
+ * After revocation, `resolveSession()` will throw `SessionNotFoundError`
+ * for this sessionId. The session token (if held by the caller) becomes
+ * permanently useless. This is the explicit logout path.
+ *
+ * No-op if the session was already expired or does not exist.
+ */
+export declare function revokeSession(sessionId: string): void;
+/**
+ * Check if a session is still alive (key in store + not expired).
+ * Does not decrypt anything — purely a metadata check.
+ */
+export declare function isSessionAlive(token: SessionToken): boolean;
+/**
+ * Revoke all active sessions. Used by `Noydb.close()` to ensure that
+ * closing the instance destroys all session state, not just the keyring
+ * cache.
+ */
+export declare function revokeAllSessions(): void;
+/**
+ * Return the number of active sessions currently in the store.
+ * Useful for diagnostics and tests.
+ */
+export declare function activeSessionCount(): number;

package/dist/with-party/session/strategy.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Strategy seam for the optional session-policy service. Core
+ * imports `SessionStrategy` type-only + `NO_SESSION` stub; real
+ * `validateSessionPolicy`, `createEnforcer`, and `revokeAllSessions`
+ * are only reachable via `withSession()` in `./active.ts`.
+ *
+ * Solo apps that never set `sessionPolicy` and never issue a session
+ * token ship none of the ~495 LOC of policy + token machinery
+ * (session-policy.ts + session.ts). Dev-unlock (~299 LOC) is a
+ * separate import already tree-shake-friendly via direct named
+ * imports.
+ *
+ * Behavior under NO_SESSION:
+ *
+ * - **validateSessionPolicy** — throws when called. Only fires if
+ *   `createNoydb({ sessionPolicy })` was passed; if you set a policy
+ *   you must opt into the strategy.
+ * - **createEnforcer** — throws. Same gate.
+ * - **revokeAllSessions** — silent no-op. Called unconditionally on
+ *   `db.close()`; without the strategy the global session registry
+ *   never recorded anything, so the no-op is correct.
+ *
+ * @internal
+ */
+import type { SessionPolicy } from '../../kernel/types.js';
+import type { PolicyEnforcer, PolicyEnforcerOptions } from './session-policy.js';
+/**
+ * @internal
+ */
+export interface SessionStrategy {
+    validateSessionPolicy(policy: SessionPolicy): void;
+    createEnforcer(opts: PolicyEnforcerOptions): PolicyEnforcer;
+    revokeAllSessions(): void;
+}
+/**
+ * No-session stub. Policy validation + enforcer construction throw
+ * with an actionable pointer; global session revocation is a silent
+ * no-op (the registry was never populated).
+ *
+ * @internal
+ */
+export declare const NO_SESSION: SessionStrategy;

package/dist/with-party/session/unlock-state.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Per-vault tier-3 (PIN / quick-resume) state.
+ *
+ * The hub holds a `PinResumeState`-shaped record in memory, keyed by
+ * vault. `enrollUnlock` populates it; `unlockViaPin` consumes it via
+ * `@noy-db/on-pin`'s `resumePin`. The cached state is wiped when the
+ * idle timer fires or `db.close()` is called.
+ *
+ * Importantly, this module does NOT depend on `@noy-db/on-pin` — the
+ * caller passes the already-built state in. That keeps the hub's
+ * `peerDependencies` empty for tier-3 and lets developers swap the
+ * primitive (e.g. an OS biometric in place of a PIN).
+ *
+ * @module
+ */
+/**
+ * Opaque `PinResumeState`-compatible record. Mirrored from
+ * `@noy-db/on-pin/PinResumeState`. The hub treats the contents as
+ * a black box.
+ */
+export interface QuickUnlockState {
+    readonly _noydb_on_pin: 1;
+    readonly salt: string;
+    readonly iv: string;
+    readonly wrappedKeyring: string;
+    readonly expiresAt: string;
+    readonly maxAttempts: number;
+    attempts: number;
+}
+/** In-memory store for tier-3 unlock state, keyed by vault. */
+export declare class QuickUnlockStore {
+    private readonly states;
+    private readonly timers;
+    /**
+     * Register a quick-unlock state for a vault. Replaces any existing
+     * state. Schedules an automatic clear when the state's `expiresAt`
+     * elapses.
+     */
+    set(vault: string, state: QuickUnlockState): void;
+    /** Read the state for a vault. Returns undefined when none is registered. */
+    get(vault: string): QuickUnlockState | undefined;
+    /** Drop the state for a vault. Cancels the auto-clear timer. */
+    delete(vault: string): void;
+    /** Drop every cached state. Called on `db.close()`. */
+    clear(): void;
+    private clearTimer;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * `@noy-db/hub/sync` — subpath export for the optional sync engine +
+ * presence service (~856 LOC).
+ *
+ * Solo / single-device apps that never replicate to a remote peer
+ * and never call `collection.presence()` exclude this subpath
+ * entirely; the constructors are routed through the `SyncStrategy`
+ * seam in core, and the `NO_SYNC` stub keeps the whole module out
+ * of the bundle.
+ *
+ * Opt in via:
+ *
+ * ```ts
+ * import { createNoydb } from '@noy-db/hub'
+ * import { withSync } from '@noy-db/hub/sync'
+ *
+ * const db = await createNoydb({
+ *   store: localStore,
+ *   sync: remoteStore,
+ *   user: ...,
+ *   syncStrategy: withSync(),
+ * })
+ * ```
+ *
+ * Note: the `SyncEngine`, `SyncTransaction`, and `PresenceHandle`
+ * classes themselves still live under `team/` and remain exposed
+ * via `@noy-db/hub/team` for advanced consumers that construct them
+ * directly. This subpath is the clean LTS factory entry point.
+ */
+export { withSync } from '../team/sync-active.js';
+export type { SyncStrategy } from '../team/sync-strategy.js';

package/dist/with-party/tab-coordination.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Multi-tab coordination: primary/secondary election (Web Locks)
+ * + presence heartbeat (BroadcastChannel). Browser-only; opt-in; no-op
+ * when the APIs are absent. The lock/channel interfaces are hub-local
+ * (structurally compatible with @noy-db/by-peer + @noy-db/by-tabs, but
+ * not imported — those packages depend on hub).
+ */
+export type TabRole = 'primary' | 'secondary' | 'unknown';
+export interface TabPresence {
+    readonly tabId: string;
+    readonly lastSeen: number;
+    readonly role: TabRole;
+}
+export type Unsubscribe = () => void;
+/** Structural subset of the Web Locks API / by-peer's MinimalLockManager. */
+export interface TabLockManager {
+    request<T>(name: string, options: {
+        mode?: 'exclusive' | 'shared';
+        signal?: AbortSignal;
+    }, callback: (lock: unknown) => Promise<T>): Promise<T>;
+}
+/** Structural subset of by-peer's PeerChannel / a BroadcastChannel wrapper. */
+export interface TabChannel {
+    send(payload: string): void;
+    on(event: 'message', listener: (payload: string) => void): Unsubscribe;
+    on(event: 'close', listener: () => void): Unsubscribe;
+    close(): void;
+    readonly isOpen: boolean;
+}
+export interface TabCoordinationOptions {
+    readonly lockManager?: TabLockManager;
+    readonly channel?: TabChannel;
+    readonly tabId?: string;
+    readonly lockName?: string;
+    readonly heartbeatMs?: number;
+    readonly staleMs?: number;
+    readonly now?: () => number;
+    /**
+     * Close the channel on `dispose()`. Set this only for a channel the
+     * coordinator owns (e.g. the one `defaultChannel()` created); leave it
+     * false for a caller-injected channel so the coordinator never closes a
+     * channel it didn't create. Default: false.
+     */
+    readonly closeChannelOnDispose?: boolean;
+    /**
+     * Also propagate committed writes to other tabs. Default true:
+     * when tab coordination is enabled and a channel is available, a write in
+     * one tab refreshes that document in every other tab. Set false to opt out.
+     */
+    readonly propagateWrites?: boolean;
+    /**
+     * Channel for write propagation — distinct from the presence
+     * channel. Default: an inline BroadcastChannel on `noydb:tab-writes`.
+     */
+    readonly writeChannel?: TabChannel;
+}
+export declare class TabCoordinator {
+    #private;
+    readonly tabId: string;
+    role: TabRole;
+    constructor(opts?: TabCoordinationOptions);
+    start(): void;
+    activeTabs(): TabPresence[];
+    onTabRoleChange(fn: (r: TabRole) => void): Unsubscribe;
+    onActiveTabsChange(fn: (t: TabPresence[]) => void): Unsubscribe;
+    dispose(): void;
+    /** @internal test seam — broadcast one heartbeat now. */
+    _beat(): void;
+}
+/** Browser default lock manager (navigator.locks) or undefined. */
+export declare function defaultLockManager(): TabLockManager | undefined;
+/** Browser default channel: an inline BroadcastChannel wrapper, or undefined. */
+export declare function defaultChannel(name?: string): TabChannel | undefined;

package/dist/with-party/tab-write-relay.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cross-tab write propagation. A role-agnostic relay: it broadcasts
+ * a ciphertext-blind signal ({vault, collection, docId, action}) for every
+ * locally-committed write (via onAfterWrite), and on receiving a peer
+ * tab's signal it asks the host to refresh that document's in-memory view by
+ * re-reading the shared encrypted store. Nothing decrypted crosses the wire.
+ */
+import type { TabChannel, Unsubscribe } from './tab-coordination.js';
+import type { WriteEvent } from '../port/with/write-hooks.js';
+export interface TabWriteMsg {
+    readonly kind: 'tab-write';
+    readonly writerId: string;
+    readonly vault: string;
+    readonly collection: string;
+    readonly docId: string;
+    readonly action: 'put' | 'delete';
+    readonly baseV: number;
+    readonly v: number;
+}
+export interface CrossTabWriteRelayOptions {
+    /** The broadcast channel (its own — distinct from the presence channel). */
+    readonly channel: TabChannel;
+    /** This tab's id — outgoing signals carry it; incoming self-signals are ignored. */
+    readonly writerId: string;
+    /** Subscribe to committed writes (the host's onAfterWrite). */
+    readonly subscribeAfterWrite: (handler: (e: WriteEvent) => void) => Unsubscribe;
+    /** Refresh a document's in-memory view from the shared store. */
+    readonly applyRemoteWrite: (vault: string, collection: string, docId: string, action: 'put' | 'delete') => void | Promise<void>;
+    /** Report a detected conflict (host captures + converges + emits). */
+    readonly reportConflict?: (vault: string, collection: string, docId: string, action: 'put' | 'delete', baseV: number, v: number, ownV: number) => void | Promise<void>;
+    /** Close the channel on dispose (only when the relay created it). Default false. */
+    readonly closeChannelOnDispose?: boolean;
+}
+export declare class CrossTabWriteRelay {
+    #private;
+    constructor(opts: CrossTabWriteRelayOptions);
+    start(): void;
+    dispose(): void;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Enable the multi-user team capability (#267 Track A tail).
+ *
+ * Pass to `createNoydb({ teamStrategy: withTeam() })` to make `db.grant` /
+ * `db.revoke` / `db.rotate` live. The keyring grant/revoke/rotate engines
+ * are statically imported HERE — this module is reachable only through the
+ * `@noy-db/hub/team` subpath (and the root barrel's tree-shakeable
+ * re-export), so a single-user floor bundle never carries them. The facade
+ * (`TeamFacade.runGrant` / `runRevoke` / `runRotate`) owns the policy-gate +
+ * keyring plumbing and receives the engine as an argument.
+ */
+import type { TeamStrategy } from './strategy.js';
+export declare function withTeam(): TeamStrategy;

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

@@ -0,0 +1,95 @@
+/**
+ * Tier-2 authenticator slot management.
+ *
+ * Each slot independently wraps the SAME KEK under a method-specific
+ * derived key (LUKS pattern). Enrolling adds a slot; removing drops
+ * one. Both are constant-time keyring writes — no DEK re-keying.
+ *
+ * The crypto for each method lives in its `@noy-db/on-*` package
+ * (`on-webauthn`, `on-oidc`, `on-password`); this module accepts the
+ * package's `wrapped_kek` ciphertext + `meta` payload and persists it.
+ *
+ * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Tier 2 — Authenticate
+ *
+ * @module
+ */
+import type { NoydbStore, KeyringAuthenticator } from '../../kernel/types.js';
+import type { UnlockedKeyring } from './keyring.js';
+/** Fields shared across both wrap-KEK and wrap-DEKs enroll inputs. */
+interface EnrollAuthenticatorBase {
+    readonly id: string;
+    readonly method: KeyringAuthenticator['method'];
+    /** Method-specific metadata (cred id, salt, …). */
+    readonly meta: Record<string, unknown>;
+    /** Tier the active session held when enrolling. Defaults to 1. */
+    readonly enrolled_via_tier?: 1 | 2;
+}
+/** Wrap-KEK enroll input (WebAuthn, OIDC). */
+export interface EnrollAuthenticatorWrappingKEKOptions extends EnrollAuthenticatorBase {
+    /** Already-wrapped KEK ciphertext (base64) — produced by the on-* package. */
+    readonly wrapped_kek: string;
+    readonly wrapKind?: 'kek';
+}
+/** Wrap-DEKs enroll input (password, future on-* using the unified wrap-DEKs primitive). */
+export interface EnrollAuthenticatorWrappingDEKsOptions extends EnrollAuthenticatorBase {
+    readonly wrapKind: 'deks';
+    /** Base64 AES-GCM ciphertext of `{ deks: { collection: base64rawDek } }`. */
+    readonly wrapped_deks: string;
+    /** Base64 AES-GCM IV used for the `wrapped_deks` ciphertext. */
+    readonly iv: string;
+}
+/** Discriminated union over the two enroll input shapes. */
+export type EnrollAuthenticatorOptions = EnrollAuthenticatorWrappingKEKOptions | EnrollAuthenticatorWrappingDEKsOptions;
+/**
+ * Append a new authenticator slot to the keyring file. Throws
+ * `ValidationError` if a slot with the same id already exists — the
+ * caller decides whether to remove + re-enroll.
+ *
+ * Accepts either wrap-KEK (WebAuthn, OIDC) or wrap-DEKs (password)
+ * input. The variant is preserved verbatim into `KeyringAuthenticator`.
+ */
+export declare function enrollAuthenticator(store: NoydbStore, vault: string, keyring: UnlockedKeyring, options: EnrollAuthenticatorOptions): Promise<UnlockedKeyring>;
+/**
+ * Caller payload for {@link updateAuthenticator}. Mutates only
+ * `meta` — the slot's id, method, and wrap material are immutable
+ * through this primitive, preserving the anti-slot-swap guard.
+ *
+ * `meta` is **merged** at the top level: keys absent from the patch
+ * are preserved, keys present overwrite. To clear a meta key, pass
+ * `null` for that key explicitly. (Same top-level merge semantics as
+ * `UserApi.updateMe`, non-recursive — meta is a flat label bag.)
+ */
+export interface UpdateAuthenticatorOptions {
+    readonly meta?: Record<string, unknown>;
+}
+/**
+ * Mutate a tier-2 authenticator slot's `meta` blob (slot rename,
+ * label changes). The slot's `id`, `method`, and wrap material
+ * (`wrapped_kek` for wrap-KEK; `wrapped_deks` + `iv` for wrap-DEKs)
+ * are immutable through this entry point — the anti-slot-swap guard
+ * is structural, not gate-driven, so even if the policy gate is
+ * weakened a future caller cannot use this path to swap one slot's
+ * crypto for another's.
+ *
+ * `meta` patch semantics:
+ *   - Top-level merge — absent keys preserved, present keys overwrite
+ *   - `null` value — delete that meta key
+ *   - Non-object values (string, number, boolean, array) — replace verbatim
+ *
+ * @throws `NoAccessError` when no slot with the given id exists.
+ * @throws `ValidationError` when no patch field is provided.
+ *
+ */
+export declare function updateAuthenticator(store: NoydbStore, vault: string, keyring: UnlockedKeyring, slotId: string, options: UpdateAuthenticatorOptions): Promise<UnlockedKeyring>;
+/**
+ * Drop a slot by id. No-op if the slot doesn't exist (idempotent —
+ * removing a non-existent slot is a recoverable retry, not an error).
+ */
+export declare function removeAuthenticator(store: NoydbStore, vault: string, keyring: UnlockedKeyring, slotId: string): Promise<UnlockedKeyring>;
+/**
+ * Look up a slot by id. Returns `undefined` when no slot matches.
+ * Used by tier-2 unlock dispatchers to fetch the wrapped KEK + meta
+ * before invoking the method-specific verifier.
+ */
+export declare function findAuthenticator(keyring: UnlockedKeyring, slotId: string): KeyringAuthenticator | undefined;
+export {};

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>;