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

package/dist/with-party/directory/cover/custom.d.ts

@@ -0,0 +1,34 @@
+import type { Cover, JsonValue, ResolvedCoverSchema } from './types.js';
+/**
+ * Validate the owner-supplied `custom` input: the field must be a
+ * plain object, every key must match {@link CUSTOM_KEY_PATTERN}, and
+ * every value must be JSON-serializable (no functions, `undefined`,
+ * symbols, bigints, or cycles) within the depth cap. `null` is
+ * accepted — it is the delete-this-namespace directive and never
+ * persists. Throws `ValidationError` on the first violation.
+ */
+export declare function validateCustomInput(custom: Record<string, JsonValue>): void;
+/**
+ * Namespace-level patch merge for `setCover`: provided namespaces
+ * replace their previous value, absent namespaces are preserved, and
+ * an explicit `null` deletes that namespace (so `null` never persists
+ * as a namespace value). A whole-`custom`-absent patch preserves the
+ * previous custom, consistent with the other cover fields. Rationale:
+ * framework A must never need read-modify-write of framework B's data.
+ *
+ * Returns a spreadable fragment — `{ custom }` when the merge leaves
+ * at least one namespace, `{}` when it leaves none (the field is
+ * dropped from the persisted document rather than stored empty).
+ */
+export declare function mergeCustom(existing: Record<string, JsonValue> | undefined, patch: Record<string, JsonValue> | undefined): {
+    custom: Record<string, JsonValue>;
+} | Record<string, never>;
+/**
+ * Post-merge size caps — validates the WOULD-BE-PERSISTED document
+ * (after the namespace merge), so a small patch can't tip the stored
+ * cover over a cap unnoticed. `maxCoverBytes` bounds the entire
+ * serialized document, which also closes the unbounded locale-map
+ * key-count hole for `name` / `description`. Sizes are measured as
+ * `JSON.stringify` length. Throws `ValidationError` on violation.
+ */
+export declare function validateCoverSize(cover: Cover, schema: ResolvedCoverSchema): void;

package/dist/with-party/directory/cover/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cover service — barrel export. (Formerly "public envelope"; the
+ * old names remain as deprecated aliases for one pre-release window.)
+ *
+ * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md
+ *
+ * @module
+ */
+export type { Cover, CoverText, CoverSchema, CoverField, JsonValue, ResolvedCoverSchema, } from './types.js';
+export { COVER_FIELDS, DEFAULT_COVER_SCHEMA, resolveSchema, } from './types.js';
+export type { SetCoverInput } from './schema.js';
+export { validateCoverInput, isCover } from './schema.js';
+export { mergeCustom, validateCoverSize } from './custom.js';
+export { loadCover, saveCover, readCover, resolveLocale, pickLocale, COVER_RECORD_ID, } from './storage.js';
+export type { PublicEnvelope, PublicEnvelopeText, PublicEnvelopeSchema, PublicEnvelopeField, ResolvedPublicEnvelopeSchema, } from './types.js';
+export { PUBLIC_ENVELOPE_FIELDS, DEFAULT_PUBLIC_ENVELOPE_SCHEMA, } from './types.js';
+export type { SetPublicEnvelopeInput } from './schema.js';
+export { validatePublicEnvelopeInput, isPublicEnvelope } from './schema.js';
+export { loadPublicEnvelope, savePublicEnvelope, readPublicEnvelope, PUBLIC_ENVELOPE_RECORD_ID, } from './storage.js';

package/dist/with-party/directory/cover/schema.d.ts

@@ -0,0 +1,39 @@
+import type { Cover, CoverText, JsonValue, ResolvedCoverSchema } from './types.js';
+/** Owner-supplied input — the subset of {@link Cover} the owner can set. */
+export interface SetCoverInput {
+    readonly name?: CoverText;
+    readonly description?: CoverText;
+    readonly icon?: string;
+    readonly defaultLocale?: string;
+    /**
+     * Namespace-level patch for the cover's `custom` slot (#800):
+     * provided namespaces replace their previous value, absent
+     * namespaces are preserved, an explicit `null` deletes that
+     * namespace. Requires `'custom'` in the schema's `fields` list —
+     * the `cover: true` shorthand does NOT enable it.
+     */
+    readonly custom?: Record<string, JsonValue>;
+}
+/**
+ * Validate an owner-supplied cover input against the developer's
+ * resolved schema. Throws `ValidationError` on the first violation;
+ * returns void on success.
+ *
+ * The validator is deliberately strict: every fail mode is a hard
+ * error rather than a silent drop, so the owner finds out immediately
+ * which field they oversized rather than discovering a truncated
+ * label months later.
+ */
+export declare function validateCoverInput(input: SetCoverInput, schema: ResolvedCoverSchema): void;
+/**
+ * Lightweight runtime predicate — used by the bundle header
+ * validator to recognise a cover without requiring it. (The wire
+ * discriminator keeps its frozen name: `_noydb_public: 1`.)
+ */
+export declare function isCover(x: unknown): x is Cover;
+/** @deprecated Use {@link SetCoverInput}. */
+export type SetPublicEnvelopeInput = SetCoverInput;
+/** @deprecated Use {@link validateCoverInput}. */
+export declare const validatePublicEnvelopeInput: typeof validateCoverInput;
+/** @deprecated Use {@link isCover}. */
+export declare const isPublicEnvelope: typeof isCover;

package/dist/with-party/directory/cover/storage.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Persistence helpers for `_meta/public-envelope` — the cover's
+ * frozen wire location. Mirrors the bypass-AES pattern used by
+ * `_meta/handle` and `_meta/policy` — the document is plaintext
+ * JSON, the envelope's `_iv` field is left empty.
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../../kernel/types.js';
+import type { Cover } from './types.js';
+/**
+ * Reserved id for the vault-level cover record. The VALUE is frozen
+ * wire format — the record predates the #799 rename and stays at
+ * `_meta/public-envelope` so existing vaults need no migration.
+ */
+export declare const COVER_RECORD_ID = "public-envelope";
+/**
+ * Read the cover from `_meta/public-envelope`. Returns `undefined`
+ * when no cover has been persisted (fresh vault, or a vault written
+ * before the feature was enabled). Tolerates corrupted documents —
+ * a JSON parse failure surfaces as `undefined`, not a thrown error,
+ * mirroring `_meta/handle`'s contract.
+ */
+export declare function loadCover(store: NoydbStore, vault: string): Promise<Cover | undefined>;
+/** Persist the cover. Idempotent — overwrites any prior write. */
+export declare function saveCover(store: NoydbStore, vault: string, cover: Cover): Promise<void>;
+/**
+ * Public, no-key reader. Plain function, not a method on `Noydb` —
+ * the whole point is it works without an authenticated session, so
+ * a UI can show "Acme 2026 Tax Records" before unlocking.
+ *
+ * Resolves any `name` / `description` locale map through the supplied
+ * `locale` (when provided). Omitting `locale` returns the raw
+ * cover, which a multilingual picker can render as it pleases.
+ */
+export declare function readCover(store: NoydbStore, vault: string, opts?: {
+    readonly locale?: string;
+}): Promise<Cover | undefined>;
+/**
+ * Resolve the locale-map fields (`name`, `description`) of a cover
+ * to plain strings for the requested locale, falling back through
+ * `defaultLocale` and then any available translation.
+ *
+ * @internal
+ */
+export declare function resolveLocale(cover: Cover, locale: string): Cover;
+/**
+ * Resolve a `string | { [locale]: string }` value to a string for a
+ * given locale. Exported so the bundle reader can reuse it without
+ * duplicating the fallback chain.
+ *
+ * **Looser than `resolveI18nText`** — the hub's record-field resolver
+ * throws `LocaleNotSpecifiedError` when no translation matches, but
+ * label semantics deliberately prefer "show *something*" over
+ * throwing. The fallback chain is:
+ *   1. Exact `locale` match.
+ *   2. `defaultLocale` (when supplied on the cover).
+ *   3. First non-empty value in the map.
+ *   4. Empty string (only if every translation is empty — pathological).
+ *
+ * This deviation is documented in `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md`.
+ */
+export declare function pickLocale(value: string | Record<string, string>, locale: string, defaultLocale: string | undefined): string;
+/** @deprecated Use {@link COVER_RECORD_ID}. */
+export declare const PUBLIC_ENVELOPE_RECORD_ID = "public-envelope";
+/** @deprecated Use {@link loadCover}. */
+export declare const loadPublicEnvelope: typeof loadCover;
+/** @deprecated Use {@link saveCover}. */
+export declare const savePublicEnvelope: typeof saveCover;
+/** @deprecated Use {@link readCover}. */
+export declare const readPublicEnvelope: typeof readCover;

package/dist/with-party/directory/cover/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Cover — owner-curated plaintext metadata, readable before vault
+ * unlock or bundle decryption. Like a book's cover: title, cover
+ * art, back-cover blurb — readable on the shelf without opening
+ * the book, and never trusted as the book's contents.
+ *
+ * (Formerly "public envelope" — the wire keeps that name: the
+ * record still lives at `_meta/public-envelope` and carries the
+ * `_noydb_public: 1` discriminator.)
+ *
+ * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md
+ *
+ * @module
+ */
+/**
+ * Either a single string (used when the developer's app is
+ * single-locale) or a locale → string map for i18n. Mirrors the
+ * shape `@noy-db/hub/i18n` already uses for record fields, so the
+ * existing `resolveI18nText` resolver applies.
+ */
+export type CoverText = string | Record<string, string>;
+/**
+ * A JSON-serializable value — what a `custom` namespace payload may
+ * hold. No functions, `undefined`, symbols, bigints, or cycles; the
+ * validator additionally caps nesting depth at 8 levels.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Persisted shape — both `_meta/public-envelope` (the frozen wire
+ * name) and the bundle header carry this. The version number is
+ * monotonic per vault and helps cache invalidators detect change
+ * without hashing the JSON.
+ */
+export interface Cover {
+    readonly _noydb_public: 1;
+    readonly version: number;
+    readonly name?: CoverText;
+    readonly description?: CoverText;
+    /** Inline `data:` URL (`data:image/png;base64,…` or `data:image/svg+xml;base64,…`). */
+    readonly icon?: string;
+    /** ISO-8601 timestamp; auto-set on first cover write, immutable thereafter. */
+    readonly createdAt?: string;
+    /** ISO-8601 timestamp; auto-updated on every `setCover` call. */
+    readonly updatedAt?: string;
+    /** BCP-47 fallback locale for renderers when the user's locale isn't covered. */
+    readonly defaultLocale?: string;
+    /**
+     * Namespaced integrator slot (#800) — e.g.
+     * `{ 'noydb.viewer': { defaultCollection: 'invoices' } }`. Keys must
+     * be reverse-DNS / package-style (`noydb.viewer`, `com.acme.registry`).
+     * Like everything on the cover it is plaintext, public, and
+     * unauthenticated — payloads are hints, never authority. Opt-in:
+     * excluded from `DEFAULT_COVER_SCHEMA.fields`, so `cover: true`
+     * does NOT enable it.
+     */
+    readonly custom?: Record<string, JsonValue>;
+}
+/** Field names the developer can allow in `CoverSchema.fields`. */
+export declare const COVER_FIELDS: readonly ["name", "description", "icon", "createdAt", "updatedAt", "defaultLocale", "custom"];
+export type CoverField = (typeof COVER_FIELDS)[number];
+/**
+ * Build-time schema. The developer enables the feature and bounds
+ * what the owner can set. `true` is shorthand for "all defaults" —
+ * gives the owner the full field set with the standard caps.
+ */
+export interface CoverSchema {
+    /**
+     * Allowed field names. Setting `name`/`description`/`icon`/`defaultLocale` is
+     * gated on the field being listed here. `createdAt` / `updatedAt` are managed
+     * by the hub; including them is a no-op (the owner cannot set them
+     * directly). Default: every field above.
+     */
+    readonly fields?: ReadonlyArray<CoverField>;
+    /**
+     * Maximum icon size — measured as the length of the data-URL
+     * string. Default 256 KB.
+     */
+    readonly maxIconBytes?: number;
+    /** Allowed icon MIME types. Default ['image/png', 'image/svg+xml']. */
+    readonly iconMimeTypes?: ReadonlyArray<string>;
+    /** Maximum length of `name` / `description` per locale. Default 200. */
+    readonly maxStringChars?: number;
+    /**
+     * Maximum serialized size (`JSON.stringify` length) of the whole
+     * would-be-persisted `custom` object, measured AFTER the namespace
+     * patch merge. Default 8 KB.
+     */
+    readonly maxCustomBytes?: number;
+    /**
+     * Maximum serialized size of the ENTIRE would-be-persisted cover
+     * document. The consumer-protection cap — bounds what a pre-auth
+     * reader must fetch and parse, and closes the unbounded locale-map
+     * key-count hole for `name` / `description`. Default 300 KB
+     * (headroom over the 256 KB icon cap + text fields).
+     */
+    readonly maxCoverBytes?: number;
+}
+/**
+ * Default schema values; merged onto every developer-supplied schema.
+ * NOTE: `fields` is the six display fields, deliberately NOT
+ * {@link COVER_FIELDS} — the opt-in `'custom'` slot is excluded, so
+ * the `cover: true` shorthand never exposes it by accident.
+ */
+export declare const DEFAULT_COVER_SCHEMA: {
+    readonly fields: readonly ["name", "description", "icon", "createdAt", "updatedAt", "defaultLocale"];
+    readonly maxIconBytes: number;
+    readonly iconMimeTypes: readonly ["image/png", "image/svg+xml"];
+    readonly maxStringChars: 200;
+    readonly maxCustomBytes: number;
+    readonly maxCoverBytes: number;
+};
+/** Resolved schema after merging developer override onto defaults. */
+export interface ResolvedCoverSchema {
+    readonly fields: ReadonlyArray<CoverField>;
+    readonly maxIconBytes: number;
+    readonly iconMimeTypes: ReadonlyArray<string>;
+    readonly maxStringChars: number;
+    readonly maxCustomBytes: number;
+    readonly maxCoverBytes: number;
+}
+/**
+ * Merge developer schema onto the defaults. The shorthand `true`
+ * resolves to the full default schema; an explicit object only
+ * overrides the keys it provides.
+ */
+export declare function resolveSchema(schema: true | CoverSchema | undefined): ResolvedCoverSchema | undefined;
+/** @deprecated Use {@link Cover}. */
+export type PublicEnvelope = Cover;
+/** @deprecated Use {@link CoverText}. */
+export type PublicEnvelopeText = CoverText;
+/** @deprecated Use {@link CoverField}. */
+export type PublicEnvelopeField = CoverField;
+/** @deprecated Use {@link CoverSchema}. */
+export type PublicEnvelopeSchema = CoverSchema;
+/** @deprecated Use {@link ResolvedCoverSchema}. */
+export type ResolvedPublicEnvelopeSchema = ResolvedCoverSchema;
+/** @deprecated Use {@link COVER_FIELDS}. */
+export declare const PUBLIC_ENVELOPE_FIELDS: readonly ["name", "description", "icon", "createdAt", "updatedAt", "defaultLocale", "custom"];
+/** @deprecated Use {@link DEFAULT_COVER_SCHEMA}. */
+export declare const DEFAULT_PUBLIC_ENVELOPE_SCHEMA: {
+    readonly fields: readonly ["name", "description", "icon", "createdAt", "updatedAt", "defaultLocale"];
+    readonly maxIconBytes: number;
+    readonly iconMimeTypes: readonly ["image/png", "image/svg+xml"];
+    readonly maxStringChars: 200;
+    readonly maxCustomBytes: number;
+    readonly maxCoverBytes: number;
+};

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

@@ -0,0 +1,11 @@
+/**
+ * User-list visibility — barrel export for the
+ * `@noy-db/hub/directory` surface.
+ *
+ * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md → Directory visibility
+ *
+ * @module
+ */
+export type { DirectoryConfig, UserVisibility } from './types.js';
+export { readDirectoryConfig, persistDirectoryConfig, META_COLLECTION, DIRECTORY_RECORD_ID, } from './storage.js';
+export { readUserVisibility, persistUserVisibility, deleteUserVisibility, visibilityRecordId, VISIBILITY_RECORD_PREFIX, } from './visibility.js';

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

@@ -0,0 +1,33 @@
+/**
+ * Persistence helpers for the vault-level user-directory toggle
+ * (`_meta/directory`). Mirrors the bypass-AES pattern used by
+ * `_meta/policy` — the directory 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/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 { DirectoryConfig } from './types.js';
+/** Reserved collection name for vault-level metadata documents. */
+export declare const META_COLLECTION = "_meta";
+/** Reserved id for the vault-level directory document. */
+export declare const DIRECTORY_RECORD_ID = "directory";
+/**
+ * Read the directory toggle from `_meta/directory`. Returns `undefined`
+ * when no document has been persisted — callers treat that as the
+ * default-on case (`{ enabled: true }`).
+ *
+ * Tolerates corrupted documents the same way `_meta/policy` does: a
+ * JSON parse failure surfaces as `undefined`, not a thrown error, so a
+ * bad write never permanently breaks team enumeration.
+ */
+export declare function readDirectoryConfig(store: NoydbStore, vault: string): Promise<DirectoryConfig | undefined>;
+/**
+ * Persist the directory toggle at `_meta/directory`. Idempotent — call
+ * on every `db.setDirectoryEnabled()` invocation. Owner-only at the
+ * caller site; this primitive does not check roles.
+ */
+export declare function persistDirectoryConfig(store: NoydbStore, vault: string, config: DirectoryConfig): Promise<void>;

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

@@ -0,0 +1,43 @@
+/**
+ * Type surface for the user-list visibility service.
+ *
+ * Two complementary flags:
+ *  - {@link DirectoryConfig} — vault-level "is the directory listing
+ *    enabled at all?" toggle. Owner-only mutation.
+ *  - {@link UserVisibility} — per-user "hide me from teammate listings"
+ *    opt-out. Self-mutation via `vault.user.setMyVisibility`.
+ *
+ * Both flags live in the existing `_meta` collection as plaintext-bypass
+ * sidecars (`_iv: ''`). Neither is a security boundary — the keyring
+ * file is still observable at `_keyring/*` and the envelope ciphertext
+ * is still at `_users/*` to anyone with direct store read access. The
+ * flags exist to keep admin-UI listings tidy, not to hide principals
+ * from a determined attacker.
+ *
+ * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md → Directory visibility
+ *
+ * @module
+ */
+/**
+ * Vault-level directory toggle. Persisted at `_meta/directory`.
+ *
+ * - `enabled: true` (default when no document exists) — every authenticated
+ *   caller can enumerate users via `listUsersWithEnvelopes`.
+ * - `enabled: false` — only `owner` and `admin` callers can enumerate;
+ *   anyone else gets {@link import('../../kernel/errors.js').DirectoryDisabledError}.
+ */
+export interface DirectoryConfig {
+    readonly enabled: boolean;
+}
+/**
+ * Per-user visibility flag. Persisted at `_meta/visibility/<keyringId>`.
+ *
+ * - `hidden: false` (default when no document exists) — the user shows up
+ *   in `listUsersWithEnvelopes` like any other principal.
+ * - `hidden: true` — the user is filtered out of the default listing.
+ *   `owner`/`admin` callers can still see them by passing
+ *   `{ includeHidden: true }`.
+ */
+export interface UserVisibility {
+    readonly hidden: boolean;
+}

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