@interncom/diplomatic 0.11.4 → 0.12.0

package/dist/web/openClient.d.ts

@@ -1,103 +1,10 @@
 import { IClock } from "./shared/clock";
 import type { IStateManager } from "./shared/types";
 import type { IClient, IStore } from "./types";
-/**
- * How to construct the Worker you pass to {@link openDiplomaticClient} /
- * {@link WorkerClient.connect} / `useClient`.
- *
- * The library accepts only a live `Worker` instance. Instantiation is bundler-
- * and hosting-specific — the app owns that step so DIPLOMATIC never guesses a
- * script URL that would 404 under a different tool.
- *
- * The worker entry is the package export `@interncom/diplomatic/worker`
- * (built as `worker.mjs` in the published package). It must run as a
- * **module** worker (`type: "module"`).
- *
- * ## Handshake (race-safe)
- *
- * The worker posts an unsolicited `{ kind: "ready" }` after init. Apps often
- * construct the Worker at module load (or before `openDiplomaticClient` finishes
- * opening IndexedDB), so that event can fire before the library sets
- * `onmessage`. **That is fine:** connect also probes with a request/response
- * `ping`. The worker holds commands until init completes, so the probe succeeds
- * even if `ready` was dropped. Do **not** reimplement message buffering in the
- * app unless you need it for other reasons.
- *
- * ## Vite (recommended for SPA templates)
- *
- * ```ts
- * import DiplomaticWorker from "@interncom/diplomatic/worker?worker";
- * const worker = new DiplomaticWorker();
- * await openDiplomaticClient({ state, worker });
- * ```
- *
- * `?worker` makes Vite emit a real worker asset and a constructor. Create the
- * instance once (module scope or `useMemo`/`useRef`) — not on every render.
- * Early construction is supported; the handshake recovers if `ready` is missed.
- *
- * ## webpack / Rollup / esbuild / Parcel (`new URL` + import.meta.url)
- *
- * Point at the package worker file so the bundler copies it next to the app:
- *
- * ```ts
- * const worker = new Worker(
- *   new URL("@interncom/diplomatic/worker", import.meta.url),
- *   { type: "module" },
- * );
- * ```
- *
- * If the package path does not resolve, import the built file explicitly:
- *
- * ```ts
- * const worker = new Worker(
- *   new URL(
- *     "../node_modules/@interncom/diplomatic/dist/worker.mjs",
- *     import.meta.url,
- *   ),
- *   { type: "module" },
- * );
- * ```
- *
- * (Exact relative path depends on your app layout; prefer the package export
- * when your bundler supports it.)
- *
- * ## Plain HTML / CDN / static hosting (no bundler)
- *
- * Host `worker.mjs` (from the package `dist/`) as a same-origin static asset,
- * then:
- *
- * ```html
- * <script type="module">
- *   import { openDiplomaticClient } from "https://cdn.example/diplomatic.js";
- *   const worker = new Worker("/path/to/worker.mjs", { type: "module" });
- *   const { client } = await openDiplomaticClient({ state, worker });
- * </script>
- * ```
- *
- * The worker script must be **same-origin** (or CORS-enabled for classic
- * workers; module workers generally need same-origin). Do not invent a path
- * into `node_modules` from the browser — copy or serve the built file.
- *
- * ## React (`useClient`)
- *
- * Same rules: build the Worker once, pass the instance:
- *
- * ```ts
- * import DiplomaticWorker from "@interncom/diplomatic/worker?worker";
- * const syncWorker = new DiplomaticWorker(); // module scope
- * useClient({ seed, host, worker: syncWorker });
- * ```
- *
- * ## Lifecycle
- *
- * Workers die with the page (tab close / full navigation). Mid-session death
- * is rare; if you recreate a Worker yourself, open a new client against it.
- * `dispose` / `WorkerClient.terminate` stops the worker DIPLOMATIC is using.
- */
 type OpenDiplomaticClientBase = {
     state: IStateManager;
     clock?: IClock;
-    /** Max wait for worker ready when using a worker (default 15s). */
+    /** Max wait for setSeed → Enclave.spawnSyncWorker handshake (default 15s). */
     readyTimeoutMs?: number;
     /**
      * Debounce local write → worker sync (default `defaultSyncDebounceMs`).
@@ -106,29 +13,29 @@ type OpenDiplomaticClientBase = {
     syncDebounceMs?: number;
 };
 /**
- * Worker path: protocol sync off the main thread. Main and worker both use
- * IndexedDB (shared durable state). A custom `store` is a type error and a
- * runtime error — the worker always opens IDB, so a MemoryStore (etc.) on
- * main would silently diverge.
+ * Worker path: protocol sync off the main thread after setSeed. Main and worker
+ * both use IndexedDB. Custom `store` is forbidden (worker always opens IDB).
+ *
+ * No worker is spawned at open. Only {@link Enclave.spawnSyncWorker} (from
+ * setSeed) creates a worker and injects seed.
+ *
+ * CSP: allow `worker-src blob:` (or `script-src blob:`) if you use a strict CSP.
  */
 export type OpenDiplomaticClientWorkerOptions = OpenDiplomaticClientBase & {
-    /**
-     * App-constructed sync Worker (see module docs above for how to create it).
-     * Misconfiguration or ready timeout throws — no silent main-thread fallback.
-     */
-    worker: Worker;
+    /** Request a library-managed sync worker. */
+    worker: true;
     store?: never;
 };
 /**
  * Main-thread path: SyncClient on the page. Optional custom store; default is
- * IndexedDB. No automatic memory fallback when IndexedDB is missing.
+ * IndexedDB.
  */
 export type OpenDiplomaticClientMainOptions = OpenDiplomaticClientBase & {
-    worker?: undefined;
+    worker?: undefined | false;
     /**
      * Protocol message store. Default: IndexedDB (`openIDBStore`).
      * Pass explicitly for non-IDB backends (e.g. `new MemoryStore(crypto)`).
-     * Incompatible with `worker` (see {@link OpenDiplomaticClientWorkerOptions}).
+     * Incompatible with `worker: true`.
      */
     store?: IStore<URL>;
 };
@@ -143,10 +50,8 @@ export type OpenedDiplomaticClient = {
 /**
  * Open a browser client.
  *
- * - **Worker path:** pass `worker` (already constructed). Always IndexedDB.
+ * - **Worker path:** `worker: true` — façade ready; Worker appears on setSeed.
  * - **Main path:** omit `worker` → SyncClient on the page; optional `store`.
- *
- * See {@link OpenDiplomaticClientOptions} for Worker instantiation recipes.
  */
 export declare function openDiplomaticClient(opts: OpenDiplomaticClientOptions): Promise<OpenedDiplomaticClient>;
 export {};

package/dist/web/passkey/largeBlob.d.ts

@@ -0,0 +1,17 @@
+import { Status } from "../shared/consts";
+import { type LargeBlobCreateOpts, type LargeBlobRp } from "../shared/webauthn/largeBlob";
+import { type ValStat } from "../shared/valstat";
+export type { LargeBlobCreateOpts, LargeBlobRp };
+/**
+ * WebAuthn largeBlob byte I/O for non-seed opaque data.
+ * For seed/identity use {@link Enclave} largeBlob methods only.
+ */
+export declare const LargeBlob: {
+    readonly capable: () => Promise<boolean>;
+    readonly createCred: (opts?: LargeBlobCreateOpts) => Promise<ValStat<Uint8Array>>;
+    /**
+     * Write arbitrary opaque bytes (UV). Do not pass unencrypted seed from app code.
+     */
+    readonly write: (credId: Uint8Array, data: Uint8Array, opts?: LargeBlobRp) => Promise<Status>;
+    readonly read: (credId: Uint8Array, opts?: LargeBlobRp) => Promise<ValStat<Uint8Array>>;
+};

package/dist/web/passkey/prf-store.d.ts

@@ -0,0 +1,62 @@
+import { Enclave } from "../shared/crypto/enclave";
+import { type SealedMasterKey } from "../shared/seed";
+import type { ICrypto } from "../shared/types";
+import { type ValStat } from "../shared/valstat";
+import type { ISeedStore, SetSeedOpts } from "../types";
+import type { PrfRp } from "../shared/webauthn/prf";
+export type PrfSeedMeta = {
+    /** AEAD-sealed master under KDF(PRF). */
+    sealedMaster: SealedMasterKey;
+    /** PRF salt used at wrap time. */
+    salt: Uint8Array;
+    /** Optional allowCredentials id. */
+    credId?: Uint8Array;
+};
+/**
+ * Persist sealed-master metadata for cold start (e.g. protocol IDB seedMeta).
+ * Called with `undefined` when the store is wiped.
+ */
+export type PersistPrfSeedMeta = (meta: PrfSeedMeta | undefined) => void | Promise<void>;
+export type PrfSeedStoreOpts = PrfRp & {
+    crypto: ICrypto;
+    /**
+     * Required durable write path for sealed master + salt + credId.
+     * Protocol IDB implements this via {@link IDBSeedStore.persistPrfMeta}.
+     */
+    persistMeta: PersistPrfSeedMeta;
+    /** Previously persisted meta (cold start). Does not re-call persistMeta. */
+    meta?: PrfSeedMeta;
+};
+/**
+ * Session + durable PRF-wrapped seed. Session secret is always {@link Enclave}.
+ *
+ * - {@link save} is memory-only (holds enclave).
+ * - {@link wrapAndSave} runs PRF UV inside Enclave and persists sealed meta.
+ * - {@link unlock} runs PRF UV inside Enclave and returns a new enclave.
+ *
+ * Fallback when PRF is unavailable (not implemented yet): passphrase-sealed
+ * meta with the same layout — no plain seed on disk either way.
+ */
+export declare class PrfSeedStore implements ISeedStore {
+    #private;
+    constructor(opts: PrfSeedStoreOpts);
+    get meta(): PrfSeedMeta | undefined;
+    setMeta(meta: PrfSeedMeta | undefined): void;
+    save(enclave: Enclave, opts?: SetSeedOpts): Promise<Enclave>;
+    /**
+     * PRF UV inside Enclave, seal master, persist meta (no PRF leaves Enclave).
+     */
+    wrapAndSave(enclave: Enclave, opts?: {
+        salt?: Uint8Array;
+        credId?: Uint8Array;
+        createCredIfNeeded?: boolean;
+    }): Promise<ValStat<Enclave>>;
+    load(): Promise<Enclave | void>;
+    /** Passkey UV inside Enclave → new session enclave. */
+    unlock(): Promise<ValStat<Enclave>>;
+    /**
+     * Install sealed meta + session enclave (e.g. after pair-package open) and persist.
+     */
+    adoptSealed(enclave: Enclave, meta: PrfSeedMeta): Promise<ValStat<Enclave>>;
+    wipe(): Promise<void>;
+}

package/dist/web/passkey/seed.d.ts

@@ -1,111 +1,25 @@
 import { Enclave } from "../shared/crypto/enclave";
-import type { MasterSeed } from "../shared/types";
+import type { ICrypto } from "../shared/types";
+import { type ValStat } from "../shared/valstat";
 import type { ISeedStore, SetSeedOpts } from "../types";
-export type LargeBlobRp = {
-    rpId?: string;
-    rpName?: string;
+import { type LargeBlobRp } from "./largeBlob";
+export { defaultWebAuthnRpId } from "./webauthn";
+export { LargeBlob, type LargeBlobCreateOpts, type LargeBlobRp, } from "./largeBlob";
+export type PasskeySeedStoreOpts = LargeBlobRp & {
+    crypto: ICrypto;
+    credId?: Uint8Array;
 };
 /**
- * Stable WebAuthn RP ID for a hostname: registrable domain (eTLD+1) when
- * possible, else the hostname itself.
- *
- * Using the full hostname (e.g. life.example.com) scopes credentials to that
- * host only. Safari/Apple Passwords often present the site as the apex domain;
- * Chrome + security keys tend to store whatever rpId we pass. Defaulting to
- * eTLD+1 keeps platform + roaming authenticators on the same RP ID across
- * subdomains and browsers.
- *
- * localhost / IPs are returned unchanged (valid only for those origins).
- */
-export declare function defaultWebAuthnRpId(hostname: string): string;
-/**
- * Best-effort capability probe (not all UAs expose this accurately).
- *
- * Safari 17+ supports largeBlob on platform authenticators but often omits or
- * mis-reports `extension:largeBlob` from {@link PublicKeyCredential.getClientCapabilities}.
- * Treat Apple Safari as capable so UI can offer enroll; create still checks
- * `largeBlob.supported` after the ceremony.
- */
-export declare function largeBlobCapable(): Promise<boolean>;
-export type LargeBlobCreateOpts = LargeBlobRp & {
-    userName?: string;
-    /**
-     * Omit (default) to allow both platform (Hello/Touch ID) and roaming
-     * authenticators (YubiKey). Set only if you intentionally restrict.
-     */
-    authenticatorAttachment?: AuthenticatorAttachment;
-};
-/**
- * Create a discoverable credential with largeBlob support.
- * Does **not** write the seed — call {@link writeLargeBlobSeed} from a
- * **separate user gesture** (second click). Safari / WebKit will not reliably
- * run two WebAuthn ceremonies from one button press; chaining create→write
- * leaves empty passkeys (see blobviem / nsatragno largeBlob demos).
- *
- * On Apple Safari, defaults to `authenticatorAttachment: "platform"` so
- * iCloud Keychain is preferred (Apple largeBlob is platform-oriented).
- * Pass `authenticatorAttachment: "cross-platform"` for security keys.
- */
-export declare function createLargeBlobCred(opts?: LargeBlobCreateOpts): Promise<Uint8Array>;
-/**
- * Persist seed on an existing largeBlob-capable credential.
- * Must be invoked from its **own** user gesture (not chained after create
- * in the same click handler on Safari).
- *
- * Spec: allowCredentials must contain exactly one credential for write.
- */
-export declare function writeLargeBlobSeed(credId: Uint8Array, seed: MasterSeed, opts?: LargeBlobRp): Promise<void>;
-/** Overwrite largeBlob with 32 zero bytes (destroys stored seed material). UV required. */
-export declare function clearLargeBlobSeed(credId: Uint8Array, opts?: LargeBlobRp): Promise<void>;
-export type LargeBlobUnlock = {
-    seed: MasterSeed;
-    /** Authenticator credential id — app should persist for faster local unlock. */
-    credId: Uint8Array;
-};
-/**
- * Read seed from largeBlob on a known credential (user verification required).
- */
-export declare function readLargeBlobSeed(credId: Uint8Array, opts?: LargeBlobRp): Promise<MasterSeed>;
-/**
- * Same as {@link readLargeBlobSeed} but also returns the credential id used.
- */
-export declare function readLargeBlobUnlock(credId: Uint8Array, opts?: LargeBlobRp): Promise<LargeBlobUnlock>;
-/**
- * Discoverable assertion + largeBlob read (no local credential id).
- *
- * Omits `allowCredentials` so the platform can offer resident keys for this
- * rpId — including iCloud-synced passkeys. Returns seed and `credId` so the
- * app can cache the id for later non-discoverable unlocks.
- */
-export declare function discoverLargeBlobSeed(opts?: LargeBlobRp): Promise<LargeBlobUnlock>;
-/**
- * Create credential then write seed in one call.
- *
- * **Safari/WebKit:** prefer {@link createLargeBlobCred} + {@link writeLargeBlobSeed}
- * from **two separate clicks**. Chaining both after one gesture often creates a
- * passkey without a blob (`written` false / later `missing blob` on read).
- *
- * Returns credential id — persist it; the seed lives on the authenticator.
- */
-export declare function storeSeedLargeBlob(seed: MasterSeed, opts?: LargeBlobCreateOpts): Promise<Uint8Array>;
-/**
- * ISeedStore backed by largeBlob.
- * - {@link save} creates (or reuses) cred + writes seed (gestures).
- * - {@link load} returns in-memory enclave only; call {@link unlock} after restart.
- * - Local {@link credId} must be persisted by the app across sessions.
- * - {@link wipe} overwrites largeBlob with zeros (UV), then drops memory + credId.
- *   Does not delete the WebAuthn credential from the authenticator.
+ * ISeedStore backed by largeBlob. Session secret is always {@link Enclave}.
+ * Persist uses {@link Enclave.persistToLargeBlob} / {@link Enclave.fromLargeBlob}.
  */
 export declare class PasskeySeedStore implements ISeedStore {
     #private;
-    constructor(opts?: LargeBlobRp & {
-        credId?: Uint8Array;
-    });
+    constructor(opts: PasskeySeedStoreOpts);
     get credId(): Uint8Array | undefined;
     setCredId(credId: Uint8Array | undefined): void;
-    save(seed: MasterSeed, opts?: SetSeedOpts): Promise<Enclave>;
+    save(enclave: Enclave, opts?: SetSeedOpts): Promise<Enclave>;
     load(): Promise<Enclave | void>;
-    /** User-gesture unlock after cold start (needs {@link credId}). */
-    unlock(): Promise<Enclave>;
+    unlock(): Promise<ValStat<Enclave>>;
     wipe(): Promise<void>;
 }

package/dist/web/passkey/webauthn.d.ts

@@ -0,0 +1 @@
+export { asPublicKeyCredential, checkWebAuthn, copyToArrayBuffer, defaultWebAuthnRpId, resolveWebAuthnRpId, webAuthnExtensionCapable, COSE_ALG_EDDSA, COSE_ALG_ES256, COSE_ALG_RS256, WEBAUTHN_CHAL_LEN, WEBAUTHN_PUB_KEY_PARAMS, type WebAuthnRp, } from "../shared/webauthn/common";

package/dist/web/react/useClient.d.ts

@@ -1,46 +1,39 @@
 import { IEntDB } from "../entdb/entdb";
 import { IClock } from "../shared/clock";
-import { IHostConnectionInfo, IStateManager, MasterSeed } from "../shared/types";
+import type { Enclave } from "../shared/crypto/enclave";
+import { IHostConnectionInfo, IStateManager } from "../shared/types";
 import type { IClient, IDiplomaticClientState, IDiplomaticClientXferState, IStore } from "../types";
 export declare function useClientState(client: Pick<IClient<URL>, "clientState">): IDiplomaticClientState | undefined;
 export declare function useClientXferState(client: Pick<IClient<URL>, "xferState">): IDiplomaticClientXferState | undefined;
 export declare function useSyncOnResume(client: Pick<IClient<URL>, "connect" | "sync">): void;
 type UseClientBase = {
     clock?: IClock;
-    seed?: MasterSeed;
+    /** Session enclave (master seed stays inside Enclave). */
+    seed?: Enclave;
     host?: IHostConnectionInfo<URL>;
     readyTimeoutMs?: number;
 };
 /**
- * Worker path: always IndexedDB on main + worker. Custom `store` is forbidden
- * (type + runtime) so durable state cannot diverge.
+ * Worker path: IndexedDB on main; sync Worker appears on setSeed via Enclave.
+ * Custom `store` is forbidden so durable state cannot diverge.
  *
- * Vite:
- *   import DiplomaticWorker from "@interncom/diplomatic/worker?worker";
- *   const syncWorker = new DiplomaticWorker();
- *   useClient({ worker: syncWorker, seed, host });
- *
- * Handshake is race-safe (ready event and/or probe ping). See
- * `openDiplomaticClient` for bundler recipes and handshake notes.
+ * ```ts
+ * useClient({ worker: true, seed, host });
+ * ```
  */
 export type UseClientWorkerOptions = UseClientBase & {
-    /**
-     * App-constructed sync Worker. Create once (module scope or useMemo/useRef),
-     * not each render. Early construction before `useClient` opens IDB is OK —
-     * the library does not require catching the unsolicited `ready` event.
-     * See `openDiplomaticClient` for instantiation recipes.
-     */
-    worker: Worker;
+    /** Worker-mode client; Enclave.spawnSyncWorker runs inside setSeed. */
+    worker: true;
     store?: never;
 };
 /**
  * Main-thread path. Optional custom store; default IndexedDB.
  */
 export type UseClientMainOptions = UseClientBase & {
-    worker?: undefined;
+    worker?: undefined | false;
     /**
      * Protocol store override. Default: IndexedDB. Pass explicitly for
-     * MemoryStore or other backends. Incompatible with `worker`.
+     * MemoryStore or other backends. Incompatible with `worker: true`.
      */
     store?: IStore<URL>;
 };

package/dist/web/shared/binary.d.ts

@@ -3,6 +3,10 @@ export declare function htob(hex: string): Uint8Array;
 export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
 export declare let btob64: (bytes: Uint8Array) => string;
 export declare let b64tob: (b64: string) => Uint8Array;
+/** Bytes → base64url (no padding). For string transport (pair packages, QR payloads). */
+export declare function btob64url(bytes: Uint8Array): string;
+/** Base64url (padding optional) → bytes. */
+export declare function b64urltob(b64url: string): Uint8Array;
 export declare function concat(a: Uint8Array, b: Uint8Array): Uint8Array;
 export declare function btob128(bytes: Uint8Array): string;
 export declare function b128tob(str: string): Uint8Array;

package/dist/web/shared/codecs/bundleHost.d.ts

@@ -0,0 +1,11 @@
+import { ICodecStruct } from "../codec.ts";
+import type { IHostConnectionInfo } from "../types.ts";
+/**
+ * Wire form of {@link IHostConnectionInfo}: same fields, handle as string URL
+ * (live clients use `URL | IProtoHost`).
+ */
+export type BundleHost = Omit<IHostConnectionInfo<URL>, "handle"> & {
+    handle: string;
+};
+/** handle (varstring), label (varstring), idx (varint; default 0). */
+export declare const bundleHostCodec: ICodecStruct<BundleHost>;

package/dist/web/shared/codecs/identityBundle.d.ts

@@ -0,0 +1,25 @@
+import { ICodecStruct } from "../codec.ts";
+import { type MasterSeed } from "../seed.ts";
+import { type ValStat } from "../valstat.ts";
+import { type BundleHost } from "./bundleHost.ts";
+export { type BundleHost, bundleHostCodec } from "./bundleHost.ts";
+export declare const IDENTITY_BUNDLE_VERSION = 1;
+export type IdentityBundle = {
+    v: number;
+    masterSeed: MasterSeed;
+    hosts: BundleHost[];
+};
+/**
+ * IdentityBundle wire layout:
+ *   v: varint
+ *   masterSeed: 32 fixed bytes
+ *   hostsLen: varint
+ *   hosts: hostsLen × BundleHost
+ */
+export declare const identityBundleCodec: ICodecStruct<IdentityBundle>;
+/**
+ * Build a wire-format identity bundle from a branded {@link MasterSeed} + hosts.
+ * Codec/tests only. Runtime seed I/O must go through Enclave.persistToLargeBlob
+ * — never encode then hand seed-bearing bytes to outer layers.
+ */
+export declare function createIdentityBundle(masterSeed: MasterSeed, hosts: BundleHost[]): ValStat<IdentityBundle>;

package/dist/web/shared/codecs/pairPackage.d.ts

@@ -0,0 +1,15 @@
+import { ICodecStruct } from "../codec.ts";
+import { type MasterSeed } from "../seed.ts";
+import { type BundleHost } from "./bundleHost.ts";
+export type PairPackagePlain = {
+    masterSeed: MasterSeed;
+    hosts: BundleHost[];
+};
+/**
+ * Inner plaintext body (not sealed here — AEAD is applied by the pairing
+ * ceremony, then carried as `body` in {@link pairPackageEnvelopeCodec}):
+ *   masterSeed: 32 fixed bytes
+ *   hostsLen: varint
+ *   hosts: hostsLen × BundleHost
+ */
+export declare const pairPackagePlainCodec: ICodecStruct<PairPackagePlain>;

package/dist/web/shared/codecs/pairPackageEnvelope.d.ts

@@ -0,0 +1,18 @@
+import { ICodecStruct } from "../codec.ts";
+export declare const PAIR_PACKAGE_VERSION = 1;
+export type PairPackageEnvelope = {
+    v: number;
+    salt: Uint8Array;
+    /** Empty when absent. */
+    credId: Uint8Array;
+    /** AEAD ciphertext of pairPackagePlainCodec bytes under KDF(PRF). */
+    body: Uint8Array;
+};
+/**
+ * Outer envelope (metadata is not secret; body is AEAD ciphertext):
+ *   v: varint
+ *   salt: varbytes
+ *   credId: varbytes (length 0 if none)
+ *   body: varbytes (AEAD of pair-package plain)
+ */
+export declare const pairPackageEnvelopeCodec: ICodecStruct<PairPackageEnvelope>;

package/dist/web/shared/crypto/enclave.d.ts

@@ -1,4 +1,26 @@
-import type { ICrypto, MasterSeed, PublicKey } from "../types.ts";
+import type { BundleHost } from "../codecs/bundleHost.ts";
+import { Status } from "../consts.ts";
+import { MASTER_SEED_LEN, type SealedMasterKey } from "../seed.ts";
+import type { ICrypto, PublicKey } from "../types.ts";
+import { type ValStat } from "../valstat.ts";
+import { type LargeBlobCreateOpts, type LargeBlobRp } from "../webauthn/largeBlob.ts";
+import { type PrfCreateOpts, type PrfEvalOpts, type PrfRp } from "../webauthn/prf.ts";
+export type { LargeBlobCreateOpts, LargeBlobRp };
+export type { PrfCreateOpts, PrfEvalOpts, PrfRp };
+/** Options for PRF seal/unseal ceremonies (no raw PRF bytes). */
+export type PasskeyPrfOpts = PrfRp & {
+    salt?: Uint8Array;
+    credId?: Uint8Array;
+    /** Seal only: create a PRF credential first when no credId is known. */
+    createCredIfNeeded?: boolean;
+    userName?: string;
+};
+/** Durable PRF-sealed master + public meta (never includes PRF output). */
+export type PrfSealedMaster = {
+    sealedMaster: SealedMasterKey;
+    salt: Uint8Array;
+    credId: Uint8Array;
+};
 export type EncryptCipher = {
     encrypt: (data: Uint8Array) => Promise<Uint8Array>;
 };
@@ -25,9 +47,95 @@ export type Identity = {
     /** Per-bag KDM mixed with this identity's private key (see bag seal). */
     kdmFor: (msgHeadEnc: Uint8Array) => Promise<Uint8Array>;
 };
+declare const SEAL_KEY_LEN = 32;
+declare const SEAL_PRF_MIN_LEN = 16;
 export declare class Enclave {
     #private;
-    constructor(seed: MasterSeed, crypto: ICrypto);
+    private constructor();
+    /** New enclave with a fresh 32-byte master seed. */
+    static fromRandom(crypto: ICrypto): Promise<Enclave>;
+    /**
+     * Construct from raw master seed bytes (import / bootstrap only).
+     * Copies the seed so callers may zero their buffer after success.
+     * Prefer {@link fromRandom} or {@link unsealWithPasskey} for normal flows.
+     */
+    static fromBytes(crypto: ICrypto, bytes: Uint8Array): ValStat<Enclave>;
+    /**
+     * UV + PRF ceremony, then AEAD-seal master. Returns sealed ciphertext + public
+     * meta only — never PRF output. Sealed blob on disk is useless without a
+     * ceremony Enclave itself runs on unlock.
+     *
+     * Future: sealWithPassphrase when PRF is unavailable (same sealed layout).
+     */
+    sealWithPasskey(opts?: PasskeyPrfOpts): Promise<ValStat<PrfSealedMaster>>;
+    /**
+     * UV + PRF ceremony, then unseal durable master into a new Enclave.
+     * Callers never supply PRF bytes — only sealed meta + RP/salt/credId.
+     */
+    static unsealWithPasskey(crypto: ICrypto, sealedMaster: SealedMasterKey, opts: PasskeyPrfOpts & {
+        salt: Uint8Array;
+    }): Promise<ValStat<Enclave>>;
+    /**
+     * UV + write IdentityBundle (seed + hosts) to largeBlob.
+     * Encode and WebAuthn write complete inside this method; nothing seed-bearing
+     * is returned. Prefer empty `hosts` for seed-only backup.
+     *
+     * Pass `opts.credId` to write an existing credential (one UV). Omit it to
+     * create a largeBlob-capable credential then write (two UV). Returns the
+     * credential id used.
+     */
+    persistToLargeBlob(hosts?: BundleHost[], opts?: LargeBlobCreateOpts & {
+        credId?: Uint8Array;
+    }): Promise<ValStat<Uint8Array>>;
+    /**
+     * UV + read largeBlob payload into a new Enclave (+ hosts if IdentityBundle).
+     * Seed material never leaves this factory.
+     *
+     * Pass `opts.credId` for a known credential; omit for discoverable assertion.
+     * Returns the credential id used (useful after discover).
+     */
+    static fromLargeBlob(crypto: ICrypto, opts?: LargeBlobRp & {
+        credId?: Uint8Array;
+    }): Promise<ValStat<{
+        enclave: Enclave;
+        hosts: BundleHost[];
+        credId: Uint8Array;
+    }>>;
+    /** UV + overwrite largeBlob with zeros (destroys stored seed material). */
+    static clearLargeBlob(credId: Uint8Array, opts?: LargeBlobRp): Promise<Status>;
+    /**
+     * UV + PRF, then AEAD-seal pair-package plaintext (seed + hosts).
+     * Returns ciphertext body + public ceremony meta (no PRF).
+     */
+    sealPairPackageBody(hosts: BundleHost[], opts?: PasskeyPrfOpts): Promise<ValStat<{
+        body: Uint8Array;
+        salt: Uint8Array;
+        credId: Uint8Array;
+    }>>;
+    /**
+     * UV + PRF (using envelope salt/credId), decrypt pair body, build Enclave.
+     * Also seals master under the same PRF for durable IDB (single ceremony).
+     */
+    static openPairPackageBody(crypto: ICrypto, body: Uint8Array, opts: PasskeyPrfOpts & {
+        salt: Uint8Array;
+    }): Promise<ValStat<{
+        enclave: Enclave;
+        hosts: BundleHost[];
+        sealedMaster: SealedMasterKey;
+        credId: Uint8Array;
+    }>>;
+    /**
+     * Spawn a new sync Worker from the embedded bundle and inject this enclave's
+     * master seed into it (transfer). Seed never goes to a caller-supplied port —
+     * only to a worker this method just created.
+     *
+     * Returns the Worker. Caller (WorkerClient) should adopt it and await the
+     * `setSeed` reply for `opts.id`.
+     */
+    spawnSyncWorker(opts: {
+        id: number;
+        persist?: boolean;
+    }): Worker;
     /**
      * Cipher for public KDM. Does not hold key bytes; each op re-enters the
      * enclave (async, hardware-shaped). `usage` selects the return shape:
@@ -40,3 +148,6 @@ export declare class Enclave {
      */
     deriveIdentity(keyPath: string, idx?: number): Promise<Identity>;
 }
+/** Derive seal key from PRF output (domain-separated). Used by enclave seal/unseal. */
+export declare function sealKeyFromPrf(crypto: ICrypto, prf: Uint8Array): Promise<ValStat<Uint8Array>>;
+export { MASTER_SEED_LEN, SEAL_KEY_LEN, SEAL_PRF_MIN_LEN };

package/dist/web/shared/crypto/entropy.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Fill and return `n` cryptographically secure random bytes.
+ */
+export declare function randomBytes(n: number): Uint8Array;
+/**
+ * Same as {@link randomBytes}, typed as `Uint8Array<ArrayBuffer>` for DOM
+ * `BufferSource` APIs (e.g. WebAuthn challenges and user ids).
+ */
+export declare function randomBytesArrayBuffer(n: number): Uint8Array<ArrayBuffer>;
+/** 32 cryptographically secure random bytes (e.g. master seed material). */
+export declare function random256BitSeed(): Uint8Array;