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

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

@@ -0,0 +1,201 @@
+import type { UserEnvelope, DeepPartialOrNull, Unsubscribe, UserEnvelopePresented, LiveUserEnvelope, VaultUserApi, UserApiDeps, UserApiFactory } from '../../../kernel/types.js';
+import type { UserVisibility } from '../types.js';
+import type { ExportAccessibleOptions } from '../../../with-audit/portability/export-accessible.js';
+import type { WithdrawAccessibleOptions, WithdrawResult } from '../../../with-audit/portability/withdraw-accessible.js';
+import type { RequestWithdrawalOptions, RequestWithdrawalResult, WithdrawalRequest, WithdrawalRequestStatus, ApproveWithdrawalOptions, RejectWithdrawalOptions } from '../../../with-audit/portability/request-withdrawal.js';
+/**
+ * Implementation behind `vault.user`. Constructed once per Vault via
+ * {@link createUserApi}, holds the writer's keyringId in closure so
+ * `updateMe`/`setMe` cannot target any other principal — the own-only
+ * rule is enforced at the type level (no `set(otherKeyringId, …)`
+ * method) AND at runtime (the keyringId argument simply doesn't exist
+ * on the write path).
+ */
+export declare class UserApi implements VaultUserApi {
+    /** keyringId → set of listeners. Wildcard '*' fires on every change. */
+    private readonly listeners;
+    private readonly adapter;
+    private readonly vaultName;
+    /** The writer's own keyringId. Frozen at construction time. */
+    private readonly writerKeyringId;
+    private readonly getDek;
+    /**
+     * Policy-gate validator. When omitted, gates are skipped — useful
+     * for low-level tests that exercise the storage layer directly.
+     * Production paths always wire the Noydb-backed implementation.
+     */
+    private readonly checkGate?;
+    /**
+     * Noydb-backed `exportMyAccessibleData`, injected by the Vault
+     * (which holds the keyring + bundle machinery). Omitted in low-level tests.
+     */
+    private readonly exportAccessible?;
+    /**
+     * Noydb-backed `unilateralWithdrawal`, injected by the Vault.
+     * Destructive — extract + dispose (delete | freeze). Omitted in low-level tests.
+     */
+    private readonly unilateralWithdraw?;
+    /**
+     * Noydb-backed two-party withdrawal ceremony, injected by the
+     * Vault. requestWithdraw = requester side; the rest = owner side.
+     */
+    private readonly requestWithdraw?;
+    private readonly listWithdrawals?;
+    private readonly approveWithdraw?;
+    private readonly rejectWithdraw?;
+    constructor(deps: UserApiDeps);
+    /**
+     * File a two-party withdrawal request for the caller's accessible
+     * scope. Non-destructive (writes a pending request); an owner later approves
+     * or rejects. This is the path for read-only roles (`client`/`viewer`) that
+     * cannot self-serve a destructive `unilateralWithdrawal`. Gated by
+     * `user-request-withdrawal` (enabled by default).
+     */
+    requestWithdrawal(opts?: RequestWithdrawalOptions): Promise<RequestWithdrawalResult>;
+    /** Owner side: list filed withdrawal requests (optionally by status). */
+    listWithdrawalRequests(opts?: {
+        status?: WithdrawalRequestStatus;
+    }): Promise<WithdrawalRequest[]>;
+    /**
+     * Owner side: approve a pending request. Extracts the requester's
+     * recorded scope under firm authority, disposes of the source per the
+     * request's disposition, and returns the re-keyed bundle to hand back. Gated
+     * by `approve-user-withdrawal` (tier-2 default) + owner/admin role.
+     */
+    approveWithdrawal(requestId: string, opts?: ApproveWithdrawalOptions): Promise<WithdrawResult>;
+    /** Owner side: reject a pending request (no data is touched). */
+    rejectWithdrawal(requestId: string, opts?: RejectWithdrawalOptions): Promise<WithdrawalRequest>;
+    /**
+     * Single-party withdrawal: export the caller's accessible scope
+     * (re-keyed) and dispose of the source (`delete` or `freeze`). Gated by the
+     * fail-closed built-in `client-unilateral-withdraw` policy — undefined or
+     * disabled → throws (use `requestWithdrawal`). The firm enables it at vault
+     * creation.
+     */
+    unilateralWithdrawal(opts: WithdrawAccessibleOptions): Promise<WithdrawResult>;
+    /**
+     * Export the calling user's accessible scope as a portable, re-keyed
+     * `.noydb` bundle. Non-destructive and **always allowed** (data sovereignty
+     * by construction) but audited. Scope = the caller's DEK access set.
+     */
+    exportMyAccessibleData(opts?: ExportAccessibleOptions): Promise<Uint8Array>;
+    /** Read the writer's own envelope. Returns null if never written. */
+    me<T = unknown>(): Promise<UserEnvelope<T> | null>;
+    /**
+     * Deep-merge a partial patch into the writer's own envelope. Creates
+     * the envelope on first call. Optimistic-concurrency safe — a stale
+     * `_v` (parallel writer on another device) throws `ConflictError`.
+     *
+     * Patch semantics:
+     *   - `undefined` (or omitted key) — skip; existing value preserved
+     *   - `null` — delete the field from the merged result
+     *   - any other value — overwrite (deep-merge for plain objects,
+     *     replace for primitives / arrays)
+     *
+     * To clear a field, pass `null` rather than `undefined`. Callers
+     * with shape `T = string | null` where `null` is a meaningful value
+     * should use `setMe` for that specific field instead — `null` here
+     * always means delete.
+     *
+     * Gated by the `edit-own-profile` policy gate (default `minTier: 3`).
+     * Pass `presented` to satisfy tightened policies that require a
+     * factor proof (e.g. STRICT_POLICY's TOTP requirement).
+     */
+    updateMe<T extends object = Record<string, unknown>>(patch: DeepPartialOrNull<T>, presented?: UserEnvelopePresented): Promise<UserEnvelope<T>>;
+    /**
+     * Replace the writer's own envelope with `payload`. Use sparingly —
+     * `updateMe` is the canonical mutation. No `expectedVersion` check;
+     * callers explicitly take last-write-wins semantics.
+     *
+     * Gated by `edit-own-profile`. See `updateMe` for `presented` usage.
+     */
+    setMe<T = unknown>(payload: T, presented?: UserEnvelopePresented): Promise<UserEnvelope<T>>;
+    /**
+     * Read the current user's visibility flag from
+     * `_meta/visibility/<keyringId>`. Returns `{ hidden: false }` when no
+     * document has been persisted (the default-visible case).
+     */
+    getMyVisibility(): Promise<UserVisibility>;
+    /**
+     * Update the current user's visibility in the team directory.
+     *
+     * - `hidden: true` — opt out of the default `listUsersWithEnvelopes`
+     *   listing. `owner`/`admin` callers can still see the user by passing
+     *   `{ includeHidden: true }`.
+     * - `hidden: false` — opt back in.
+     *
+     * Own-only by construction: the keyringId argument doesn't exist on
+     * this method, so no caller can hide or unhide another principal.
+     *
+     * Honest caveat: this is a UX flag, not a privacy guarantee. The
+     * envelope ciphertext at `_users/<keyringId>` and the keyring file at
+     * `_keyring/<userId>` are both still observable to anyone with direct
+     * store read access. See `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md` →
+     * "Directory visibility".
+     */
+    setMyVisibility(visibility: UserVisibility): Promise<void>;
+    /**
+     * Read another principal's envelope by their keyringId. Returns null
+     * if the principal exists but has no envelope yet, or if the
+     * keyringId does not exist at all.
+     *
+     * Gated by `view-team-profiles` (default `minTier: 2`) — but ONLY for
+     * cross-principal reads. Reading your own envelope (`keyringId ===
+     * self`) is never gated; that's just `me()` written long-form.
+     */
+    get<T = unknown>(keyringId: string, presented?: UserEnvelopePresented): Promise<UserEnvelope<T> | null>;
+    /**
+     * Read every persisted envelope in the vault. Order is store-defined.
+     *
+     * Gated by `view-team-profiles`. Default policy (`minTier: 2`) lets
+     * any authenticated session read all envelopes. Two privacy-strict
+     * opt-outs:
+     *
+     *  - `view-team-profiles.enabled: false` → list() returns only the
+     *    caller's own envelope (silent self-fallback, no thrown error).
+     *  - `view-team-profiles.minTier: 1` + insufficient tier → throws
+     *    `PolicyDeniedError` with `reason: 'insufficient-tier'`. The
+     *    caller is expected to elevate, not silently degrade.
+     *
+     * The asymmetry is deliberate: `enabled: false` is a deliberate
+     * design choice ("nobody sees teammate profiles in this app");
+     * `insufficient-tier` is "you need to authenticate further". Different
+     * UX prompts for different intents.
+     */
+    list<T = unknown>(presented?: UserEnvelopePresented): Promise<UserEnvelope<T>[]>;
+    /**
+     * Listen for changes to a specific keyringId's envelope. The callback
+     * fires synchronously after every successful local `updateMe` /
+     * `setMe` for that principal.
+     *
+     * Cross-instance changes (a teammate edits their profile on their
+     * device, the sync engine pulls the diff onto this device) will fire
+     * subscribers when the sync layer replays the write through this API.
+     * In v1, subscribers do NOT fire on raw store changes — wire your sync
+     * layer to call back through `vault.user.setMe` / `updateMe` if you
+     * need that.
+     *
+     * Pass keyringId `'*'` to fire on every change in the vault.
+     */
+    subscribe<T = unknown>(keyringId: string, cb: (env: UserEnvelope<T> | null) => void): Unsubscribe;
+    /**
+     * Reactive handle that caches the current value and re-reads on every
+     * change for the given keyringId. Convenient for framework bindings:
+     *
+     *   const live = vault.user.live<UserShape>(vault.userId)
+     *   live.subscribe(env => render(env?.data))
+     *
+     * Initial value is `null` until the first `current()` call materializes
+     * it via `vault.user.get()`. Call `stop()` when done to release the
+     * subscription.
+     */
+    live<T = unknown>(keyringId: string): LiveUserEnvelope<T>;
+    private fireChange;
+}
+/**
+ * Build the `vault.user` API implementation from its dependencies. This is
+ * the real {@link UserApiFactory} — `createNoydb()` dynamically imports it
+ * and stashes it on the `Noydb` instance so `Vault`'s constructor can call
+ * it synchronously.
+ */
+export declare const createUserApi: UserApiFactory;

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

@@ -0,0 +1,12 @@
+/**
+ * Per-principal user envelope service — storage primitives. The contract
+ * types (`UserEnvelope`, `VaultUserApi`, `UserApiDeps`, ...) and the
+ * `USER_ENVELOPE_COLLECTION` / `USER_ENVELOPE_MAX_BYTES` constants and
+ * `UserEnvelopeOversizedError` live in the kernel spine
+ * (`kernel/types.ts` / `kernel/constants.ts` / `kernel/errors.ts`).
+ *
+ * @see docs/superpowers/specs/2026-05-05-user-envelope-design.md
+ *
+ * @module
+ */
+export { loadUserEnvelope, saveUserEnvelope, deleteUserEnvelope, listUserEnvelopeIds, } from './storage.js';

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;