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

package/dist/with-party/broker/seed.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `_broker` reserved-collection seed lifecycle (#479, credential-broker
+ * spec §2/§3). Modeled on `with-party/team/sync-credentials.ts`: a
+ * `_`-prefixed reserved collection, record id = `brokerId`, encrypted under
+ * the collection's own DEK, `requireAdminAccess` role gate (owner/admin
+ * only — custodian intentionally excluded, same rationale as
+ * `_sync_credentials`: this is transport-auth material, not the
+ * custodian's operational scope).
+ *
+ * Three operations, each a free function taking a {@link BrokerSeedCtx}
+ * (the {@link BrokerCtx} threaded through `with-party/broker/active.ts`,
+ * augmented there with the `config` its closure was built with):
+ *
+ *  - {@link enrollSeed} — two-phase commit (I9): create-if-absent CAS the
+ *    seed (I4), then register its derived proof key with the broker host,
+ *    then (only on a 2xx) mark the record `registered: true`. A seed
+ *    persisted whose `/enroll` POST failed stays `registered: false` so a
+ *    later `credentialSource()` fails fast instead of degrading into an
+ *    opaque `BrokerProofError` (I9/V23).
+ *  - {@link rotateSeed} — quiesce-then-swap (I5): mint a fresh seed,
+ *    register-new-first, THEN overwrite the local record — closing the
+ *    torn-proof window a naive local-overwrite-then-register order would
+ *    open. The single-flight cache quiesce itself (await in-flight, bump
+ *    epoch) is the caller's job (`with-party/broker/active.ts`) since the
+ *    cache lives in that closure, not here.
+ *  - {@link mintStoreCredentials} — the challenge/response round trip
+ *    (`/challenge` then `/credentials`) that produces one `StoreCredentials`
+ *    value; the single-flight cache wrapping it lives in `active.ts`.
+ *
+ * First-seed creation calls `ensureCollectionDEK`, which throws
+ * (`ValidationError`) when the keyring's KEK is `null` (PIN quick-resume /
+ * session-restore) — this module intercepts that and re-surfaces it as
+ * {@link BrokerEnrolmentError} (R-B8/I3): *enrol* needs the KEK; *use* of an
+ * already-enrolled seed needs only the DEK.
+ *
+ * @module
+ */
+import type { StoreCredentials } from '../../kernel/types.js';
+import type { BrokerSeedCtx } from '../../port/with/broker-strategy.js';
+/** The `_broker/<brokerId>` record payload (spec §3). */
+export interface BrokerSeedRecord {
+    readonly brokerId: string;
+    /** base64(32 random bytes). */
+    readonly seed: string;
+    readonly endpoint: string;
+    readonly createdAt: string;
+    /** `true` only once `/enroll` has returned a 2xx for this seed (I9). */
+    readonly registered: boolean;
+}
+/**
+ * Enrol (idempotent, two-phase commit — I9): create-if-absent the `_broker`
+ * seed (I4), derive+register its proof key with the broker host, and only
+ * on a 2xx mark the record `registered: true`. Requires owner/admin role
+ * and (for first-seed creation only) the KEK.
+ */
+export declare function enrollSeed(ctx: BrokerSeedCtx): Promise<void>;
+/**
+ * Rotate (quiesce-then-swap — I5): mint a fresh seed, register its proof
+ * key with the broker host FIRST, then overwrite the local `_broker`
+ * record. The broker host is expected to accept both the old and new
+ * registration for a short grace window, so an in-flight proof computed
+ * under the old key (from before rotation started) still verifies. Cache
+ * quiescing (awaiting any in-flight round-trip, bumping the refresh-cache
+ * epoch) is the caller's job — `with-party/broker/active.ts` — since the
+ * cache lives in that closure, not here.
+ */
+export declare function rotateSeed(ctx: BrokerSeedCtx): Promise<void>;
+/**
+ * The challenge/response round trip: `POST /challenge`, derive+sign the
+ * proof from the decrypted seed, `POST /credentials`. One network round
+ * trip per call — the single-flight/cache wrapping lives in `active.ts`.
+ *
+ * Fails fast with {@link BrokerEnrolmentError} if the seed hasn't completed
+ * enrolment yet (`registered !== true` — I9/V23), never degrading into an
+ * opaque {@link BrokerProofError}.
+ */
+export declare function mintStoreCredentials(ctx: BrokerSeedCtx, profile?: string): Promise<StoreCredentials>;

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

@@ -0,0 +1,10 @@
+/**
+ * Enable the sovereign-custody (FR-6) capability.
+ * Pass to `createNoydb({ custodyStrategy: withCustody() })` to make
+ * `db.grantCustodian` / `db.revokeCustodian` (and the `vault.custody.*` facade
+ * that delegates to them) plus `vault.custody.liberate()` live. The heavy
+ * `liberateVault` ceremony is dynamically imported here, so it is reached only
+ * via opt-in; grant/revoke run the host's own gate + keyring engine.
+ */
+import type { CustodyStrategy } from './strategy.js';
+export declare function withCustody(): CustodyStrategy;

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

@@ -0,0 +1,69 @@
+/**
+ * Public `vault.custody.*` API surface (FR-6).
+ *
+ * The custody namespace is the vault-instance face of the FR-6 sovereign-custody
+ * model — it mirrors `vault.user.*` exactly: a thin delegation shell with NO
+ * business logic. The Vault constructs one `CustodyApi` per session, injecting
+ * closures that bind the vault name / keyring into the genuinely-core
+ * implementations (`Noydb.grantCustodian` / `Noydb.revokeCustodian` and the
+ * `liberateVault` ceremony). Each method just forwards to its injected callback.
+ *
+ * Three operations:
+ *  - `grantCustodian(opts)` — owner-only: mint a `custodian` who operates the
+ *    vault fully but can never grant / rotate / sever / extract.
+ *  - `revokeCustodian(opts)` — owner-only: remove a custodian.
+ *  - `liberate(opts)` — custodian-only: audited claim of ownership over a
+ *    sealed-owner (Deed) vault (mints a DISTINCT new owner; ledger-audited).
+ *
+ * Provisioning a Deed (`createDeedOwner`) is deliberately NOT on this class: it
+ * is a store-level operation that mints the vault's first owner, so there is no
+ * vault instance (and thus no custody namespace) yet — it stays the exported
+ * `team/deed.ts` function.
+ *
+ * @see docs/superpowers/specs/2026-06-17-fr6-deed-custodian-liberate-design.md
+ * @module
+ */
+import type { GrantOptions, RevokeOptions, FactorProofBundle } from '../../kernel/types.js';
+import type { LiberateOptions, LiberateResult } from './liberate.js';
+/** Options for `vault.custody.grantCustodian` — a grant with the role fixed to `custodian`. */
+export type GrantCustodianOptions = Omit<GrantOptions, 'role'>;
+export { withCustody } from './active.js';
+export { NO_CUSTODY, type CustodyStrategy, type CustodyHost } from './strategy.js';
+export { CustodyNotEnabledError } from '../../kernel/errors.js';
+/**
+ * Implementation behind `vault.custody`. Constructed once per Vault. Holds the
+ * injected, vault-bound implementations in closure; every method delegates with
+ * no added logic (the owner-only / custodian-only / gate checks all live in the
+ * injected implementations — `Noydb.grantCustodian` etc. and `liberateVault`).
+ */
+export declare class CustodyApi {
+    /** Bound `Noydb.grantCustodian(this.name, ...)` — owner-only, gated. */
+    private readonly _grantCustodian;
+    /** Bound `Noydb.revokeCustodian(this.name, ...)` — owner-only, gated. */
+    private readonly _revokeCustodian;
+    /** Bound `liberateVault(this, ...)` — custodian-only audited ownership claim. */
+    private readonly _liberate;
+    constructor(
+    /** Bound `Noydb.grantCustodian(this.name, ...)` — owner-only, gated. */
+    _grantCustodian: (options: GrantCustodianOptions, factors?: FactorProofBundle) => Promise<void>, 
+    /** Bound `Noydb.revokeCustodian(this.name, ...)` — owner-only, gated. */
+    _revokeCustodian: (options: RevokeOptions, factors?: FactorProofBundle) => Promise<void>, 
+    /** Bound `liberateVault(this, ...)` — custodian-only audited ownership claim. */
+    _liberate: (opts: LiberateOptions) => Promise<LiberateResult>);
+    /**
+     * Owner-only: grant the FR-6 `custodian` role. The custodian operates every
+     * collection (rw + access) but is provably unable to grant / revoke / rotate /
+     * extract-and-sever. Defended in depth (gate + owner-only role check) inside
+     * the injected `Noydb.grantCustodian`.
+     */
+    grantCustodian(options: GrantCustodianOptions, factors?: FactorProofBundle): Promise<void>;
+    /** Owner-only: revoke a custodian. */
+    revokeCustodian(options: RevokeOptions, factors?: FactorProofBundle): Promise<void>;
+    /**
+     * Custodian-only: the audited claim of ownership over a sealed-owner (Deed)
+     * vault. Mints a DISTINCT new owner re-wrapping the incumbent DEKs under a
+     * fresh KEK (the latent owner is never impersonated), ledger-audited. See
+     * {@link liberateVault}.
+     */
+    liberate(opts: LiberateOptions): Promise<LiberateResult>;
+}

package/dist/with-party/custody/liberate.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `liberateVault` — the audited claim of ownership over a
+ * sealed-owner (Deed) vault. The inverse of withdrawal.
+ *
+ * A **Deed** vault's owner credential is sealed under a non-firm provider, so
+ * the firm-side **custodian** (which holds every collection DEK and operates
+ * the vault fully) can never reach `KEK_owner`. Liberation is the ONLY route
+ * by which a custodian assumes ownership, and it is deliberately a manual,
+ * audited ceremony:
+ *
+ *   1. gate `'liberate-vault'` (fail-closed)
+ *   2. caller MUST be the `custodian` (the de-facto authority holding the DEKs)
+ *   3. freeze a PRE-liberation EVIDENCE snapshot (hash-pinned in the ledger) —
+ *      but PRESERVE the live data for the new owner (see the freeze decision
+ *      below)
+ *   4. mint a NEW owner keyring re-wrapping the incumbent DEKs under the new
+ *      owner's KEK
+ *   5. lifecycle ledger `liberation-claimed:<newOwnerId>:<legalBasis>`
+ *   6. stamp the `_meta/deed` marker with `liberatedAt`
+ *
+ * ## Security: the inalienability floor
+ *
+ * Liberation **mints a new owner from the custodian's DEKs** — it does NOT
+ * unseal the original sealed owner. The old sealed-owner credential is left
+ * untouched and ORPHANED (its `_keyring/<id>` file remains, its KEK is still
+ * sealed under the non-firm provider), never impersonated. The new owner is a
+ * DISTINCT principal under a fresh KEK derived from `newOwnerPassphrase`. This
+ * preserves the inalienability floor: the act of claiming ownership is itself
+ * auditable and produces a different principal, rather than silently assuming
+ * the latent owner's identity.
+ *
+ * ## Freeze decision: snapshot-only, not freeze-and-delete
+ *
+ * `freezeAndDeleteClosure` (withdraw-accessible.ts) writes a hash-pinned
+ * snapshot and THEN delete-closures the live records — correct for a
+ * destructive withdrawal, WRONG for liberation. Liberation transfers
+ * operational continuity; it must leave the live data intact for the new
+ * owner. We therefore call the snapshot-only core `freezeSnapshotOnly`
+ * (factored out of that module; the freeze-AND-delete withdrawal path is
+ * unchanged) to pin the evidence snapshot while preserving the records.
+ *
+ * @module
+ */
+import type { Vault } from '../../kernel/vault.js';
+import type { FactorProofBundle } from '../../kernel/types.js';
+import type { FrozenSnapshotRef } from '../../with-audit/portability/withdraw-accessible.js';
+export interface LiberateOptions {
+    /** The id of the new owner principal the custodian mints by claiming ownership. */
+    readonly newOwnerId: string;
+    /** The passphrase that derives the new owner's KEK (the DEKs are re-wrapped under it). */
+    readonly newOwnerPassphrase: string;
+    /** Legal/contractual basis recorded in the audit (e.g. 'contractual-handover'). */
+    readonly legalBasis: string;
+    readonly factors?: FactorProofBundle;
+}
+export interface LiberateResult {
+    /** The hash-pinned pre-liberation evidence snapshot. */
+    readonly snapshot: FrozenSnapshotRef;
+}
+/**
+ * Audited claim of ownership over a sealed-owner vault by its custodian. See
+ * the module doc for the full ceremony + security rationale.
+ */
+export declare function liberateVault(vault: Vault, opts: LiberateOptions): Promise<LiberateResult>;

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

@@ -0,0 +1,48 @@
+/**
+ * Sovereign-custody (FR-6) capability strategy — the three on-demand
+ * operations the custody surface routes through: minting a custodian
+ * (`grantCustodian`), removing one (`revokeCustodian`), and the audited
+ * ownership-claim ceremony (`liberate`). The active engine ({@link withCustody})
+ * runs the grant/revoke impls the host exposes and dynamically imports the
+ * heavy `liberateVault` ceremony (keeping it out of the floor bundle);
+ * {@link NO_CUSTODY} throws.
+ *
+ * `Noydb.grantCustodian` / `Noydb.revokeCustodian` delegate here (passing
+ * themselves as the {@link CustodyHost}), and `vault.custody.liberate` delegates
+ * here with its {@link Vault}. An un-opted-in caller hits `NO_CUSTODY`'s throw.
+ *
+ * Note: the lower-level `liberateVault` FREE FUNCTION (exported from
+ * `custody/liberate.ts`) stays ungated — it has no `createNoydb` instance to
+ * gate against (the same carve-out as the `openSealedRecord` host opener). Only
+ * the instance surfaces (`db.grantCustodian` / `db.revokeCustodian` /
+ * `vault.custody.*`) are the capability.
+ * @internal
+ */
+import type { GrantOptions, RevokeOptions, FactorProofBundle, NoydbStore } from '../../kernel/types.js';
+import type { Vault } from '../../kernel/vault.js';
+import type { UnlockedKeyring } from '../team/keyring.js';
+import type { GrantCustodianOptions } from './index.js';
+import type { LiberateOptions, LiberateResult } from './liberate.js';
+/**
+ * The grant/revoke engine the strategy runs when opted in — implemented by
+ * `Noydb` (`_grantCustodianImpl` / `_revokeCustodianImpl` hold the gate +
+ * keyring logic; the public `grantCustodian` / `revokeCustodian` route through
+ * the strategy). Since the #267 team split the keyring grant/revoke engines
+ * are passed IN by `withCustody()` (statically linked there, not in the
+ * kernel) so the single-user floor never carries them.
+ */
+export interface CustodyHost {
+    _grantCustodianImpl(engine: (adapter: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: GrantOptions) => Promise<void>, vault: string, options: GrantCustodianOptions, factors?: FactorProofBundle): Promise<void>;
+    _revokeCustodianImpl(engine: (adapter: NoydbStore, vault: string, callerKeyring: UnlockedKeyring, options: RevokeOptions) => Promise<void>, vault: string, options: RevokeOptions, factors?: FactorProofBundle): Promise<void>;
+}
+export interface CustodyStrategy {
+    grantCustodian(host: CustodyHost, vault: string, options: GrantCustodianOptions, factors?: FactorProofBundle): Promise<void>;
+    revokeCustodian(host: CustodyHost, vault: string, options: RevokeOptions, factors?: FactorProofBundle): Promise<void>;
+    liberate(vault: Vault, opts: LiberateOptions): Promise<LiberateResult>;
+}
+/**
+ * No-op stub — the floor default. Every custody operation throws
+ * {@link CustodyNotEnabledError}; opt in with `custodyStrategy: withCustody()`
+ * in createNoydb. @internal
+ */
+export declare const NO_CUSTODY: CustodyStrategy;

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/public-envelope/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public envelope service — barrel export.
+ *
+ * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md
+ *
+ * @module
+ */
+export type { PublicEnvelope, PublicEnvelopeText, PublicEnvelopeSchema, PublicEnvelopeField, ResolvedPublicEnvelopeSchema, } from './types.js';
+export { PUBLIC_ENVELOPE_FIELDS, DEFAULT_PUBLIC_ENVELOPE_SCHEMA, resolveSchema, } from './types.js';
+export type { SetPublicEnvelopeInput } from './schema.js';
+export { validatePublicEnvelopeInput, isPublicEnvelope } from './schema.js';
+export { loadPublicEnvelope, savePublicEnvelope, readPublicEnvelope, resolveLocale, pickLocale, PUBLIC_ENVELOPE_RECORD_ID, } from './storage.js';

package/dist/with-party/directory/public-envelope/schema.d.ts

@@ -0,0 +1,24 @@
+import type { PublicEnvelope, PublicEnvelopeText, ResolvedPublicEnvelopeSchema } from './types.js';
+/** Owner-supplied input — the subset of {@link PublicEnvelope} the owner can set. */
+export interface SetPublicEnvelopeInput {
+    readonly name?: PublicEnvelopeText;
+    readonly description?: PublicEnvelopeText;
+    readonly icon?: string;
+    readonly defaultLocale?: string;
+}
+/**
+ * Validate an owner-supplied envelope 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 validatePublicEnvelopeInput(input: SetPublicEnvelopeInput, schema: ResolvedPublicEnvelopeSchema): void;
+/**
+ * Lightweight runtime predicate — used by the bundle header
+ * validator to recognise a public envelope without requiring it.
+ */
+export declare function isPublicEnvelope(x: unknown): x is PublicEnvelope;

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

@@ -0,0 +1,59 @@
+/**
+ * Persistence helpers for `_meta/public-envelope`. 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 { PublicEnvelope } from './types.js';
+/** Reserved id for the vault-level public envelope record. */
+export declare const PUBLIC_ENVELOPE_RECORD_ID = "public-envelope";
+/**
+ * Read the public envelope from `_meta/public-envelope`. Returns
+ * `undefined` when no envelope 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 loadPublicEnvelope(store: NoydbStore, vault: string): Promise<PublicEnvelope | undefined>;
+/** Persist the public envelope. Idempotent — overwrites any prior write. */
+export declare function savePublicEnvelope(store: NoydbStore, vault: string, envelope: PublicEnvelope): 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
+ * envelope, which a multilingual picker can render as it pleases.
+ */
+export declare function readPublicEnvelope(store: NoydbStore, vault: string, opts?: {
+    readonly locale?: string;
+}): Promise<PublicEnvelope | undefined>;
+/**
+ * Resolve the locale-map fields (`name`, `description`) of a public
+ * envelope to plain strings for the requested locale, falling back
+ * through `defaultLocale` and then any available translation.
+ *
+ * @internal
+ */
+export declare function resolveLocale(envelope: PublicEnvelope, locale: string): PublicEnvelope;
+/**
+ * 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 envelope).
+ *   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;

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

@@ -0,0 +1,80 @@
+/**
+ * Public envelope — owner-curated plaintext metadata, readable
+ * before vault unlock or bundle decryption.
+ *
+ * @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 PublicEnvelopeText = string | Record<string, string>;
+/**
+ * Persisted shape — both `_meta/public-envelope` 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 PublicEnvelope {
+    readonly _noydb_public: 1;
+    readonly version: number;
+    readonly name?: PublicEnvelopeText;
+    readonly description?: PublicEnvelopeText;
+    /** Inline `data:` URL (`data:image/png;base64,…` or `data:image/svg+xml;base64,…`). */
+    readonly icon?: string;
+    /** ISO-8601 timestamp; auto-set on first envelope write, immutable thereafter. */
+    readonly createdAt?: string;
+    /** ISO-8601 timestamp; auto-updated on every `setPublicEnvelope` call. */
+    readonly updatedAt?: string;
+    /** BCP-47 fallback locale for renderers when the user's locale isn't covered. */
+    readonly defaultLocale?: string;
+}
+/** Field names the developer can allow in `PublicEnvelopeSchema.fields`. */
+export declare const PUBLIC_ENVELOPE_FIELDS: readonly ["name", "description", "icon", "createdAt", "updatedAt", "defaultLocale"];
+export type PublicEnvelopeField = (typeof PUBLIC_ENVELOPE_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 PublicEnvelopeSchema {
+    /**
+     * 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<PublicEnvelopeField>;
+    /**
+     * 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;
+}
+/** Default schema values; merged onto every developer-supplied 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;
+};
+/** Resolved schema after merging developer override onto defaults. */
+export interface ResolvedPublicEnvelopeSchema {
+    readonly fields: ReadonlyArray<PublicEnvelopeField>;
+    readonly maxIconBytes: number;
+    readonly iconMimeTypes: ReadonlyArray<string>;
+    readonly maxStringChars: 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 | PublicEnvelopeSchema | undefined): ResolvedPublicEnvelopeSchema | undefined;

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