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

package/dist/with-party/directory/user-envelope/storage.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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
+ */
+import type { NoydbStore, UserEnvelope } from '../../../kernel/types.js';
+import { type EnclaveKey } from '../../../kernel/enclave/index.js';
+/**
+ * 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".
+ */
+export declare function loadUserEnvelope<T = unknown>(store: NoydbStore, vault: string, keyringId: string, dek: EnclaveKey): 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}.
+ */
+export declare function saveUserEnvelope<T>(store: NoydbStore, vault: string, keyringId: string, payload: T, dek: EnclaveKey, 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.
+ */
+export 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.
+ */
+export declare function listUserEnvelopeIds(store: NoydbStore, vault: string): Promise<string[]>;

package/dist/with-party/directory/visibility.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Persistence helpers for the per-user visibility flag
+ * (`_meta/visibility/<keyringId>`). Mirrors the bypass-AES pattern used
+ * by `_meta/policy` — the visibility document is plain JSON, the
+ * envelope's `_iv` field is left empty.
+ *
+ * Stored alongside the keyring file rather than inside the encrypted
+ * user envelope (`_users/<keyringId>`) because:
+ *
+ *  - `UserEnvelope<T>.data` is opaque-to-hub by contract — hub does not
+ *    introspect or reserve any keys inside it. Adding `hidden` there
+ *    would violate that contract.
+ *  - `listUsersWithEnvelopes` filters by the flag, and the filter must
+ *    work even when decryption fails (legacy keyrings predating the
+ *    envelope feature, or a corrupted envelope).
+ *
+ * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md → Directory visibility
+ * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/plaintext-bypass.md — every `_iv: ''` write site
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { UserVisibility } from './types.js';
+/** Prefix for per-user visibility records inside `_meta`. */
+export declare const VISIBILITY_RECORD_PREFIX = "visibility/";
+/** Compose the `_meta` record id for a keyring's visibility doc. */
+export declare function visibilityRecordId(keyringId: string): string;
+/**
+ * Read the visibility flag for `keyringId`. Returns `undefined` when no
+ * document has been persisted — callers treat that as the default-visible
+ * case (`{ hidden: false }`).
+ */
+export declare function readUserVisibility(store: NoydbStore, vault: string, keyringId: string): Promise<UserVisibility | undefined>;
+/**
+ * Persist the visibility flag for `keyringId` at
+ * `_meta/visibility/<keyringId>`. Idempotent — call on every
+ * `vault.user.setMyVisibility()` invocation. Own-only at the caller
+ * site; this primitive does not enforce keyring ownership.
+ */
+export declare function persistUserVisibility(store: NoydbStore, vault: string, keyringId: string, visibility: UserVisibility): Promise<void>;
+/**
+ * Delete the visibility flag for `keyringId`. Called from `revoke()`
+ * alongside `deleteUserEnvelope` so the sidecar does not leak to a
+ * re-granted principal with the same `userId`. Idempotent — the store's
+ * `delete()` is already a no-op when the record is absent.
+ */
+export declare function deleteUserVisibility(store: NoydbStore, vault: string, keyringId: string): Promise<void>;

package/dist/with-party/policy/engine.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → checkGate() API
+ *
+ * @module
+ */
+import { type PolicyDenyReason } from '../../kernel/errors.js';
+import type { ActiveTier, FactorProof, GateName, GatePolicy, VaultPolicy } from '../../kernel/types.js';
+/** Default freshness window — 5 minutes. */
+export declare const DEFAULT_FRESHNESS_MS: number;
+/** Caller-supplied context for one `checkGate` invocation. */
+export 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.
+ */
+export 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.
+ */
+export declare function describeGate(policy: VaultPolicy, gate: GateName, context: CheckGateContext): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: PolicyDenyReason;
+    required: GatePolicy;
+}>;

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

@@ -0,0 +1,15 @@
+/**
+ * Policy gate DSL — barrel export for the `@noy-db/hub/policy` surface.
+ *
+ * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Policy gates DSL
+ *
+ * @module
+ */
+export type { FactorKind, FactorRequirement, FactorProof, FactorProofBundle, GatePolicy, WarningRules, GateName, BuiltInGateName, VaultPolicy, ActiveTier, } from '../../kernel/types.js';
+export { PolicyDeniedError, RecoveryNotEnrolledError, RecoveryProfileNotImplementedError, ManagedRecoveryNotEnrolledError, } from '../../kernel/errors.js';
+export type { PolicyDenyReason } from '../../kernel/errors.js';
+export { PERSONAL_POLICY, STRICT_POLICY, mergePolicy } from './presets.js';
+export { checkGate, describeGate, DEFAULT_FRESHNESS_MS } from './engine.js';
+export type { CheckGateContext } from './engine.js';
+export { loadVaultPolicy, saveVaultPolicy, META_COLLECTION, POLICY_RECORD_ID, } from './storage.js';
+export { createNoydbPolicy } from './noydb-facade.js';

package/dist/with-party/policy/noydb-facade.d.ts

@@ -0,0 +1,39 @@
+import type { VaultPolicy, ReAuthOperation, NoydbPolicyApi, NoydbPolicyDeps, NoydbPolicyFactory } from '../../kernel/types.js';
+export declare class NoydbPolicy implements NoydbPolicyApi {
+    private readonly deps;
+    constructor(deps: NoydbPolicyDeps);
+    /**
+     * Touch the policy enforcer for a vault (records activity, resets
+     * idle timer). Also touches the legacy session timer. No-op if no enforcer.
+     */
+    touchPolicy(vault?: string): void;
+    /**
+     * Check that a policy-guarded operation is permitted.
+     * Throws `SessionPolicyError` if re-auth is required.
+     */
+    checkPolicyOperation(vault: string, op: ReAuthOperation): void;
+    /**
+     * Read the active policy for a vault. Loads from `_meta/policy` on
+     * first call; subsequent calls hit the in-memory cache. Throws
+     * `ValidationError` if the vault has not been opened.
+     */
+    getPolicy(vault: string): Promise<VaultPolicy>;
+    /**
+     * Replace the policy document at `_meta/policy` and update the
+     * in-memory cache. Gated by the `enroll-user` policy (a policy
+     * change is fundamentally a privilege-management action).
+     */
+    updatePolicy(vault: string, override: Partial<VaultPolicy>): Promise<VaultPolicy>;
+    /** Read or persist the vault policy at `_meta/policy` on first open. */
+    bootstrapPolicy(vault: string, opts?: {
+        skipManagedCheck?: boolean;
+    }): Promise<void>;
+}
+/**
+ * Factory that builds the `NoydbPolicy` service. `createNoydb()`
+ * pre-resolves this via a dynamic import (mirrors
+ * `with-party/directory/user-envelope/api.js#createUserApi`) and threads
+ * it through `NoydbOptions.policyFactory` so `Noydb`'s constructor can
+ * build `this.policyManager` synchronously.
+ */
+export declare const createNoydbPolicy: NoydbPolicyFactory;

package/dist/with-party/policy/presets.d.ts

@@ -0,0 +1,38 @@
+import type { VaultPolicy } from '../../kernel/types.js';
+/**
+ * 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 https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Built-in gates
+ */
+export 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.
+ */
+export 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.
+ * ```
+ */
+export declare function mergePolicy(base: VaultPolicy, override?: Partial<VaultPolicy>): VaultPolicy;

package/dist/with-party/policy/storage.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Storage location
+ *
+ * @module
+ */
+import type { NoydbStore, VaultPolicy } from '../../kernel/types.js';
+/** Reserved collection name for vault-level metadata documents. */
+export declare const META_COLLECTION = "_meta";
+/** Reserved id for the vault-level policy document. */
+export 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.
+ */
+export 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.
+ */
+export declare function saveVaultPolicy(store: NoydbStore, vault: string, policy: VaultPolicy): Promise<void>;

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

@@ -0,0 +1,34 @@
+/**
+ * Active session strategy — `withSession()` returns the real
+ * implementation that wires `SessionPolicy` validation, the
+ * `PolicyEnforcer`, and the global session-token registry into the
+ * Noydb lifecycle.
+ *
+ * Consumers opt in by:
+ *
+ * ```ts
+ * import { createNoydb } from '@noy-db/hub'
+ * import { withSession } from '@noy-db/hub/session'
+ *
+ * const db = await createNoydb({
+ *   store: ...,
+ *   user: ...,
+ *   sessionPolicy: { idleTimeoutMs: 15 * 60_000 },
+ *   sessionStrategy: withSession(),
+ * })
+ * ```
+ *
+ * The factory delegates to the existing `session-policy.ts` and
+ * `session.ts` modules. Splitting the import chain through this file
+ * is what lets tsup tree-shake the ~495 LOC of policy + token code
+ * out of the default bundle when no `withSession()` import is
+ * present.
+ *
+ * Note: dev-unlock (`devUnlock`, `cancelDevUnlock`) is a separate
+ * named import from `@noy-db/hub` and tree-shakes independently —
+ * apps that don't import it never include it.
+ *
+ * @public
+ */
+import type { SessionStrategy } from './strategy.js';
+export declare function withSession(): SessionStrategy;

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

@@ -0,0 +1,128 @@
+/**
+ * Dev-mode persistent unlock —
+ *
+ * Solves the developer inner-loop friction: hot-reload destroys the session
+ * (page navigation semantics), forcing a passphrase re-entry every refresh.
+ *
+ * This module provides an opt-in, deliberately-named escape hatch that lets
+ * developers store the keyring payload in sessionStorage or localStorage so
+ * the vault auto-unlocks on every page load — without a passphrase,
+ * without a biometric prompt, without any OIDC flow.
+ *
+ * ⚠️ WARNING — this is a loaded footgun ⚠️
+ * ─────────────────────────────────────────
+ * The keyring payload stored by this module contains the DEKs. Whoever has
+ * access to sessionStorage/localStorage has access to the DEKs. On a shared
+ * development machine, a compromised browser extension, or a mis-configured
+ * origin, this is a complete key exposure.
+ *
+ * This module is ONLY safe for local development. It must NEVER be active
+ * in production builds.
+ *
+ * Guardrails (all enforced by the module, not by the caller)
+ * ──────────────────────────────────────────────────────────
+ * 1. **Production guard:** `enableDevUnlock()` throws immediately if
+ *    `process.env.NODE_ENV === 'production'` or if `import.meta.env?.PROD === true`
+ *    (Vite convention). Also throws if the hostname is NOT localhost or 127.0.0.1.
+ *
+ * 2. **Explicit acknowledgement string:** the caller must pass
+ *    `acknowledge: 'I-UNDERSTAND-THIS-DISABLES-UNLOCK-SECURITY'` or the call
+ *    throws. This string appears in every grep for `devUnlock` in the codebase,
+ *    making it impossible to enable this feature accidentally.
+ *
+ * 3. **Scope is vault + userId:** the storage key includes both the
+ *    vault name and the userId, so dev-unlock for vault-A does
+ *    NOT auto-unlock vault-B.
+ *
+ * 4. **Storage scope:** default is `sessionStorage` (cleared on tab close).
+ *    `localStorage` is opt-in and requires an additional
+ *    `persistAcrossTabs: true` flag in the options.
+ *
+ * 5. **Clear method:** `clearDevUnlock()` removes the stored payload. Wire
+ *    this to a dev toolbar button or `Ctrl+Shift+L` so clearing is one action.
+ *
+ * 6. **Console banner:** on first enable, a highly visible console warning
+ *    fires. Cannot be suppressed.
+ *
+ * Usage
+ * ─────
+ * ```ts
+ * // In your dev entry point only (guarded by import.meta.env.DEV):
+ * if (import.meta.env.DEV) {
+ *   const { enableDevUnlock, loadDevUnlock } = await import('@noy-db/hub')
+ *   enableDevUnlock('my-compartment', 'alice', keyring, {
+ *     acknowledge: 'I-UNDERSTAND-THIS-DISABLES-UNLOCK-SECURITY',
+ *   })
+ * }
+ *
+ * // On page load:
+ * if (import.meta.env.DEV) {
+ *   const keyring = await loadDevUnlock('my-compartment', 'alice')
+ *   if (keyring) {
+ *     // Skip unlock prompt, use keyring directly
+ *   }
+ * }
+ * ```
+ */
+import type { UnlockedKeyring } from '../team/keyring.js';
+export interface DevUnlockOptions {
+    /**
+     * Required: the exact string 'I-UNDERSTAND-THIS-DISABLES-UNLOCK-SECURITY'.
+     * Any other value causes `enableDevUnlock()` to throw.
+     */
+    acknowledge: string;
+    /**
+     * If `true`, stores in localStorage (persists across tabs and browser restarts).
+     * If `false` (default), stores in sessionStorage (cleared on tab close).
+     */
+    persistAcrossTabs?: boolean;
+}
+/**
+ * Serialize and store a keyring to browser storage for dev-mode auto-unlock.
+ *
+ * Throws immediately if:
+ *   - The acknowledge string is wrong.
+ *   - Running in a production environment (NODE_ENV=production).
+ *   - Running on a non-localhost hostname.
+ *
+ * Emits a highly visible console warning that cannot be suppressed.
+ *
+ * @param vault - The vault name.
+ * @param userId - The user ID.
+ * @param keyring - The unlocked keyring to persist.
+ * @param options - Options including the required acknowledge string.
+ */
+export declare function enableDevUnlock(vault: string, userId: string, keyring: UnlockedKeyring, options: DevUnlockOptions): Promise<void>;
+/**
+ * Load a dev-mode keyring from browser storage.
+ *
+ * Returns `null` if no dev-unlock state is stored for this vault + user,
+ * or if the stored payload is malformed.
+ *
+ * Does NOT perform the production environment check — it's safe to CALL
+ * `loadDevUnlock` in production (it will simply return `null` because no
+ * dev-unlock state was ever written). The guard only fires on `enableDevUnlock`.
+ *
+ * @param vault - The vault name.
+ * @param userId - The user ID.
+ * @param options - Optional storage override.
+ */
+export declare function loadDevUnlock(vault: string, userId: string, options?: {
+    persistAcrossTabs?: boolean;
+}): Promise<UnlockedKeyring | null>;
+/**
+ * Remove dev-unlock state from browser storage.
+ *
+ * Safe to call in production (no-op if no dev state exists).
+ */
+export declare function clearDevUnlock(vault: string, userId: string, options?: {
+    persistAcrossTabs?: boolean;
+}): void;
+/**
+ * Check if dev-unlock state exists for this vault + user.
+ *
+ * Safe to call in production (returns false if nothing is stored).
+ */
+export declare function isDevUnlockActive(vault: string, userId: string, options?: {
+    persistAcrossTabs?: boolean;
+}): boolean;

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

@@ -0,0 +1,23 @@
+/**
+ * `@noy-db/hub/session` — subpath export for session tokens + policies.
+ *
+ * Apps that use single-shot unlock (one `createNoydb()` call per user
+ * action) can exclude this subpath — ~2 KB saved. Long-running apps
+ * with idle timeout, re-auth policies, magic-link viewer sessions,
+ * or dev-mode unlock opt in here.
+ *
+ * The main `@noy-db/hub` entry still re-exports every symbol for
+ * backward compatibility through.x.
+ *
+ * NOTE: magic-link helpers are expected to extract into a new
+ * `@noy-db/on-magic-link` package. Until that lands,
+ * they live here alongside session primitives.
+ */
+export { createSession, resolveSession, revokeSession, revokeAllSessions, isSessionAlive, activeSessionCount, } from './session.js';
+export type { SessionToken, CreateSessionResult, CreateSessionOptions, } from './session.js';
+export { PolicyEnforcer, createEnforcer, validateSessionPolicy } from './session-policy.js';
+export { enableDevUnlock, loadDevUnlock, clearDevUnlock, isDevUnlockActive, } from './dev-unlock.js';
+export type { DevUnlockOptions } from './dev-unlock.js';
+export { withSession } from './active.js';
+export type { SessionStrategy } from './strategy.js';
+export { SessionExpiredError, SessionNotFoundError, SessionPolicyError, } from '../../kernel/errors.js';

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

@@ -0,0 +1,92 @@
+/**
+ * Session policies —
+ *
+ * A `SessionPolicy` is a small declarative object that controls how long a
+ * session lives and which operations require re-authentication. It is
+ * evaluated by the `PolicyEnforcer` class, which the Noydb instance
+ * integrates to replace the bare `sessionTimeout` timer from.
+ *
+ * Design decisions
+ * ────────────────
+ * Policies are stateless value objects — no timers, no event listeners.
+ * The Noydb instance is the stateful coordinator: it holds the enforcer,
+ * calls `enforcer.touch()` on every operation, and calls
+ * `enforcer.checkOperation()` before high-risk operations.
+ *
+ * This keeps the policy module easy to unit-test (no global timers to mock)
+ * and avoids the "who owns cleanup" problem that comes with timer-based
+ * callbacks embedded in a value object.
+ *
+ * `lockOnBackground` registers a `visibilitychange` listener on the document
+ * at enforcer creation time and removes it on `destroy()`. It is a no-op in
+ * non-browser environments (no `document`).
+ */
+import type { SessionPolicy, ReAuthOperation } from '../../kernel/types.js';
+export interface PolicyEnforcerOptions {
+    /** The policy to enforce. */
+    policy: SessionPolicy;
+    /** The session ID to revoke when idle/absolute timeouts fire. */
+    sessionId: string;
+    /**
+     * Called when the policy decides the session should end (idle timeout,
+     * absolute timeout, or lockOnBackground). Use this to trigger the
+     * same cleanup that `Noydb.close()` would perform.
+     */
+    onRevoke: (reason: 'idle' | 'absolute' | 'background') => void;
+}
+/**
+ * Stateful enforcer for a single session policy.
+ *
+ * Create one per open session, call `touch()` on every operation,
+ * call `checkOperation(op)` before export/grant/revoke/rotate/changeSecret,
+ * and call `destroy()` when the session ends.
+ */
+export declare class PolicyEnforcer {
+    private readonly policy;
+    private readonly sessionId;
+    private readonly onRevoke;
+    private readonly createdAt;
+    private lastActivityAt;
+    private idleTimer;
+    private absoluteTimer;
+    private visibilityHandler;
+    constructor(opts: PolicyEnforcerOptions);
+    /**
+     * Record an activity timestamp and reset the idle timer.
+     * Call this at the top of every Noydb public method.
+     */
+    touch(): void;
+    /**
+     * Check whether the given operation is allowed under the active policy.
+     * Throws `SessionPolicyError` if the operation requires re-authentication.
+     * Throws `SessionExpiredError` if the absolute timeout has been exceeded
+     * (defensive check in case the timer fired before the call arrived).
+     *
+     * This is a synchronous check — callers don't await it.
+     */
+    checkOperation(op: ReAuthOperation): void;
+    /**
+     * Tear down timers and background-lock listener. Call from `Noydb.close()`
+     * and whenever the session is revoked externally.
+     */
+    destroy(): void;
+    /** How long since the last activity, in ms. */
+    get idleMs(): number;
+    /** How long since session creation, in ms. */
+    get ageMs(): number;
+    private scheduleIdleTimer;
+    private scheduleAbsoluteTimer;
+    private registerBackgroundLock;
+    private expire;
+}
+/**
+ * Build a `PolicyEnforcer` from a policy + session token, and return it
+ * alongside a cleanup function. Convenience wrapper for Noydb.
+ */
+export declare function createEnforcer(opts: PolicyEnforcerOptions): PolicyEnforcer;
+/**
+ * Validate that a `SessionPolicy` is well-formed.
+ * Throws a plain `Error` (not `NoydbError`) because this is a developer
+ * error — invalid policies passed at construction time, not at runtime.
+ */
+export declare function validateSessionPolicy(policy: SessionPolicy): void;