@interncom/diplomatic 0.11.4 → 0.12.0

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

@@ -0,0 +1,25 @@
+import { type ValStat } from "./valstat.ts";
+declare const masterSeedSymbol: unique symbol;
+declare const sealedMasterKeySymbol: unique symbol;
+/** Master seed length in bytes (Ed25519 seed / PRF material). */
+export declare const MASTER_SEED_LEN = 32;
+/**
+ * AEAD-sealed master (libsodium secretbox combined layout):
+ * 24-byte nonce + 32-byte ciphertext + 16-byte MAC.
+ */
+export declare const SEALED_MASTER_KEY_LEN: number;
+export type MasterSeed = Uint8Array & {
+    readonly [masterSeedSymbol]: true;
+};
+/**
+ * Master seed sealed under KDF(PRF) (nonce‖ciphertext‖tag).
+ * Useless without the PRF output that derives the wrap key.
+ */
+export type SealedMasterKey = Uint8Array & {
+    readonly [sealedMasterKeySymbol]: true;
+};
+/** Brand `bytes` as {@link MasterSeed} only if length is {@link MASTER_SEED_LEN}. */
+export declare function asMasterSeed(bytes: Uint8Array): ValStat<MasterSeed>;
+/** Brand `bytes` as {@link SealedMasterKey} only if length is {@link SEALED_MASTER_KEY_LEN}. */
+export declare function asSealedMasterKey(bytes: Uint8Array): ValStat<SealedMasterKey>;
+export {};

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

@@ -4,7 +4,10 @@ import { IAuthTimestamp } from "./codecs/authTimestamp.ts";
 import type { IBagPeekItem } from "./codecs/peekItem.ts";
 import { IUsageQuota } from "./codecs/usageQuota.ts";
 import { APICallName, Status } from "./consts.ts";
-import { ValStat } from "./valstat.ts";
+import type { ValStat } from "./valstat.ts";
+/** Identity seed brands — defined in seed.ts; re-exported for convenience. */
+export type { MasterSeed, SealedMasterKey } from "./seed.ts";
+export { asMasterSeed, asSealedMasterKey, MASTER_SEED_LEN, SEALED_MASTER_KEY_LEN, } from "./seed.ts";
 export type GroupID = string;
 declare const entityIDSymbol: unique symbol;
 export type EntityID = Uint8Array & {
@@ -98,15 +101,11 @@ export interface KeyPair {
     privateKey: PrivateKey;
     publicKey: PublicKey;
 }
-declare const masterSeedSymbol: unique symbol;
 declare const derivationSeedSymbol: unique symbol;
 declare const publicKeySymbol: unique symbol;
 declare const privateKeySymbol: unique symbol;
 declare const hostSpecificKeyPairSymbol: unique symbol;
 declare const hashSymbol: unique symbol;
-export type MasterSeed = Uint8Array & {
-    readonly [masterSeedSymbol]: true;
-};
 export type DerivationSeed = Uint8Array & {
     readonly [derivationSeedSymbol]: true;
 };
@@ -214,4 +213,3 @@ export interface IUpsertMessage extends IMessage {
 export interface IDeleteMessage extends Omit<IMessage, "bod"> {
     len: 0;
 }
-export {};

package/dist/web/shared/webauthn/common.d.ts

@@ -0,0 +1,38 @@
+import { Status } from "../consts.ts";
+import { type ValStat } from "../valstat.ts";
+export declare const WEBAUTHN_CHAL_LEN = 32;
+/** COSE algorithm identifiers for WebAuthn `pubKeyCredParams`. */
+export declare const COSE_ALG_ES256 = -7;
+export declare const COSE_ALG_EDDSA = -8;
+export declare const COSE_ALG_RS256 = -257;
+/** Prefer modern curves; include RS256 for broader authenticator coverage. */
+export declare const WEBAUTHN_PUB_KEY_PARAMS: PublicKeyCredentialParameters[];
+export type WebAuthnRp = {
+    rpId?: string;
+    rpName?: string;
+};
+/**
+ * Default WebAuthn RP ID: the full hostname (no eTLD+1 collapse).
+ *
+ * Credentials are scoped to this exact host. That is deliberate and simple —
+ * no Public Suffix List, no multi-part-suffix guesses. Apps that want a shared
+ * RP across subdomains (e.g. `app.example.com` + `www.example.com` →
+ * `example.com`) must pass an explicit `rpId` that is a valid suffix of the
+ * origin (WebAuthn requires the RP ID equal the effective domain or a
+ * registrable suffix of it).
+ *
+ * Normalizes case and trailing dots. Empty → `"localhost"`.
+ */
+export declare function defaultWebAuthnRpId(hostname: string): string;
+/** Copy into a fresh ArrayBuffer-backed view (DOM BufferSource typing). */
+export declare function copyToArrayBuffer(src: Uint8Array): Uint8Array;
+/** Resolve RP id from opts or `location.hostname`. */
+export declare function resolveWebAuthnRpId(opts?: WebAuthnRp): ValStat<string>;
+/** Success if WebAuthn credentials API is available in this environment. */
+export declare function checkWebAuthn(): Status;
+export declare function asPublicKeyCredential(cred: Credential | null): ValStat<PublicKeyCredential>;
+/**
+ * Best-effort capability probe (not all UAs expose this).
+ * `extKey` e.g. `"extension:largeBlob"`, `"extension:prf"`.
+ */
+export declare function webAuthnExtensionCapable(extKey: string): Promise<boolean>;

package/dist/web/shared/webauthn/largeBlob.d.ts

@@ -0,0 +1,19 @@
+import { Status } from "../consts.ts";
+import { type ValStat } from "../valstat.ts";
+import { type WebAuthnRp } from "./common.ts";
+export type LargeBlobRp = WebAuthnRp;
+export type LargeBlobCreateOpts = LargeBlobRp & {
+    userName?: string;
+    authenticatorAttachment?: string;
+};
+/** Best-effort capability probe. */
+export declare function largeBlobCapable(): Promise<boolean>;
+/** Create discoverable largeBlob-capable credential; returns credential id. */
+export declare function largeBlobCreateCred(opts?: LargeBlobCreateOpts): Promise<ValStat<Uint8Array>>;
+/** UV write of opaque bytes to largeBlob. */
+export declare function largeBlobWrite(credId: Uint8Array, data: Uint8Array, opts?: LargeBlobRp): Promise<Status>;
+/** UV read from largeBlob; `credId` undefined = discoverable assertion. */
+export declare function largeBlobRead(credId: Uint8Array | undefined, opts?: LargeBlobRp): Promise<ValStat<{
+    blob: Uint8Array;
+    credId: Uint8Array;
+}>>;

package/dist/web/shared/webauthn/prf.d.ts

@@ -0,0 +1,33 @@
+import { type ValStat } from "../valstat.ts";
+import { type WebAuthnRp } from "./common.ts";
+export type PrfRp = WebAuthnRp;
+export type PrfCreateOpts = PrfRp & {
+    userName?: string;
+    authenticatorAttachment?: string;
+};
+/** Default salt for DIPLOMATIC PRF eval (UTF-8). */
+export declare const DEFAULT_PRF_SALT: Uint8Array<ArrayBufferLike>;
+/** Bytes of PRF output we consume (first N of `results.first`). */
+export declare const PRF_OUTPUT_LEN = 32;
+export type PrfCreateResult = {
+    credId: Uint8Array;
+    prfEnabled: boolean;
+};
+/** Internal: PRF output + cred id. For Enclave only — do not re-export to apps. */
+export type PrfEvalResult = {
+    prf: Uint8Array;
+    credId: Uint8Array;
+};
+export type PrfEvalOpts = PrfRp & {
+    credId?: Uint8Array;
+    salt?: Uint8Array;
+};
+/** Best-effort: client advertises PRF extension. */
+export declare function prfCapable(): Promise<boolean>;
+/** Create a discoverable credential that enables PRF. */
+export declare function createPrfCred(opts?: PrfCreateOpts): Promise<ValStat<PrfCreateResult>>;
+/**
+ * Evaluate PRF (UV). Returns PRF bytes — only Enclave should call this and must
+ * zero/drop PRF after seal/unseal. Apps must not hold PRF alongside sealed meta.
+ */
+export declare function evalPrf(opts?: PrfEvalOpts): Promise<ValStat<PrfEvalResult>>;

package/dist/web/shared/worker/embeddedWorkerSource.d.ts

@@ -0,0 +1 @@
+export declare const DIPLOMATIC_WORKER_SOURCE = "";

package/dist/web/shared/worker/spawn.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Construct a DIPLOMATIC sync Worker from the embedded bundle.
+ * Does not inject seed — use {@link Enclave.spawnSyncWorker} for that.
+ */
+export declare function spawnDiplomaticSyncWorker(): Worker;

package/dist/web/stores/idb/seed.d.ts

@@ -1,15 +1,33 @@
 import { Enclave } from "../../shared/crypto/enclave";
-import { MasterSeed } from "../../shared/types";
-import { ISeedStore, type SetSeedOpts } from "../../types";
+import type { ICrypto } from "../../shared/types";
+import type { ISeedStore, SetSeedOpts } from "../../types";
+import { PrfSeedStore, type PrfSeedMeta, type PrfSeedStoreOpts } from "../../passkey/prf-store";
 export declare class IDBSeedStore implements ISeedStore {
+    #private;
     enclave?: Enclave;
     db: IDBDatabase;
-    constructor(db: IDBDatabase);
-    save(seed: MasterSeed, opts?: SetSeedOpts): Promise<Enclave>;
+    constructor(db: IDBDatabase, crypto: ICrypto);
+    /**
+     * Hold enclave in memory only. Durable identity is sealed meta
+     * ({@link openPrfStore} / {@link persistPrfMeta}), never plain seed.
+     * `opts.persist` is ignored (kept for API compatibility).
+     *
+     * TODO(passphrase): when PRF is missing, `persist: true` (or a dedicated
+     * wrap API) should seal under a passphrase KDF and write sealed meta here —
+     * same shape as prfMeta, not a return of raw seed.
+     */
+    save(enclave: Enclave, _opts?: SetSeedOpts): Promise<Enclave>;
     load(): Promise<Enclave | undefined>;
     /**
-     * Explicit identity clear only. Not invoked by {@link IDBStore.wipe}
-     * (that deletes the whole protocol DB, including legacy seedMeta).
+     * Drop in-memory enclave and any leftover legacy hex. Keeps {@link K_PRF_META}
+     * so daily unlock via PRF still works after a soft lock.
      */
+    clearSession(): Promise<void>;
     wipe(): Promise<void>;
+    loadPrfMeta(): Promise<PrfSeedMeta | undefined>;
+    persistPrfMeta(meta: PrfSeedMeta | undefined): Promise<void>;
+    hasPrfMeta(): Promise<boolean>;
+    openPrfStore(opts: Omit<PrfSeedStoreOpts, "crypto" | "persistMeta" | "meta"> & {
+        crypto?: ICrypto;
+    }): Promise<PrfSeedStore>;
 }

package/dist/web/stores/memory/seed.d.ts

@@ -1,9 +1,8 @@
-import { Enclave } from "../../shared/crypto/enclave";
-import { MasterSeed } from "../../shared/types";
-import { ISeedStore, type SetSeedOpts } from "../../types";
+import type { Enclave } from "../../shared/crypto/enclave";
+import type { ISeedStore, SetSeedOpts } from "../../types";
 export declare class MemorySeedStore implements ISeedStore {
     enclave?: Enclave;
-    save(seed: MasterSeed, _opts?: SetSeedOpts): Promise<Enclave>;
+    save(enclave: Enclave, _opts?: SetSeedOpts): Promise<Enclave>;
     load(): Promise<Enclave | undefined>;
     wipe(): Promise<void>;
 }

package/dist/web/types.d.ts

@@ -2,7 +2,7 @@ import type { SyncProgressEvent } from "./progress";
 import { Status } from "./shared/consts";
 import type { Enclave } from "./shared/crypto/enclave";
 import type { EncodedMessage } from "./shared/message";
-import type { EntityID, Hash, HostHandle, IDeleteParams, IEntRev, IHostConnectionInfo, IHostMetadata, IInsertParams, IMessageHead, IOp, IUpdateParams, MasterSeed, SerializedContent } from "./shared/types";
+import type { EntityID, Hash, HostHandle, IDeleteParams, IEntRev, IHostConnectionInfo, IHostMetadata, IInsertParams, IMessageHead, IOp, IUpdateParams, SerializedContent } from "./shared/types";
 import { ValStat } from "./shared/valstat";
 import { ICrypto } from "./shared/types";
 export interface IMsgParts {
@@ -29,12 +29,17 @@ export type Applier = (ops: IOp[]) => Promise<{
     types: Set<string>;
     eids: EntityID[];
 }>;
-/** Options for loading a seed into the enclave. */
+/** Options when installing a session {@link Enclave}. */
 export type SetSeedOpts = {
     /**
-     * When true, write seed to the durable store (e.g. IndexedDB).
-     * Default false (memory only) — IDB is readable by other local apps.
-     * Opt in only when the app accepts that tradeoff (or has no better store).
+     * When true, request durable storage **if the store supports a non-plaintext
+     * durable form** (e.g. passkey largeBlob as IdentityBundle wire).
+     * IDB holds the enclave in memory only — durable identity is PRF-sealed meta
+     * via {@link IDBSeedStore.openPrfStore}, never plain seed.
+     * Default false (session enclave only).
+     *
+     * Future: when PRF is unavailable, durable path is passphrase-sealed meta
+     * (KDF + AEAD inside Enclave), not plain seed on disk.
      */
     persist?: boolean;
 };
@@ -60,7 +65,7 @@ export type WipeOpts = {
     seed?: boolean;
 };
 export interface ISeedStore {
-    save: (seed: MasterSeed, opts?: SetSeedOpts) => Promise<Enclave>;
+    save: (enclave: Enclave, opts?: SetSeedOpts) => Promise<Enclave>;
     load: () => Promise<Enclave | void>;
     /**
      * Clear durable seed material for this store (IDB row, largeBlob overwrite, …)
@@ -285,7 +290,8 @@ export interface IStateEmitter<T> {
     listen(listener: (state: T) => void): UnlistenFunc;
 }
 export interface IClient<Handle extends HostHandle> {
-    setSeed(seed: MasterSeed, opts?: SetSeedOpts): Promise<void>;
+    /** Install session enclave (master seed stays inside enclave). */
+    setSeed(enclave: Enclave, opts?: SetSeedOpts): Promise<void>;
     link(host: IHostConnectionInfo<Handle>): Promise<void>;
     unlink(label: string): Promise<void>;
     /** Linked hosts from the protocol store (handle, label, lastSeq, …). */

package/dist/web/worker/client.d.ts

@@ -1,30 +1,18 @@
 import { IClock } from "../shared/clock";
 import { Status } from "../shared/consts";
-import type { EntityID, Hash, IDeleteParams, IEntRev, IHostConnectionInfo, IInsertParams, IMessageHead, IStateManager, IUpdateParams, MasterSeed, SerializedContent } from "../shared/types";
+import type { Enclave } from "../shared/crypto/enclave";
+import type { EntityID, Hash, IDeleteParams, IEntRev, IHostConnectionInfo, IInsertParams, IMessageHead, IStateManager, IUpdateParams, SerializedContent } from "../shared/types";
 import { type ValStat } from "../shared/valstat";
 import type { ApldState, IClient, IDiplomaticClientState, IDiplomaticClientXferState, IHostRow, IStateEmitter, IStore, IStoredMessage, ListMsgsOpts, ReconcileOpts, ReconcileReport, SetSeedOpts, WipeOpts } from "../types";
 /**
- * Options for attaching to an app-owned sync Worker.
- *
- * Provide a live `Worker` — the library never constructs one. See
- * `openDiplomaticClient` for bundler/CDN instantiation recipes.
- *
- * Handshake is race-safe: the worker posts unsolicited `{ kind: "ready" }`, but
- * connect also probes with `ping`. Early construction (module scope) is fine even
- * if `ready` fired before `onmessage` was set — the ping still succeeds once the
- * worker has finished init (cmds are held until then on the worker side).
- *
- * After the ready barrier, connect hydrates `clientState` / `xferState` from the
- * shared main-thread store (and recovers via getClientState/getXferState if the
- * unsolicited events were dropped). Without that, the façade defaults to
- * `hasSeed: false` and apps flash the unauthenticated UI until a later event.
+ * Options for the worker-mode façade.
+ * Prefer {@link openDiplomaticClient} with `worker: true`.
+ * The sync Worker is created only inside {@link WorkerClient.setSeed}
+ * via {@link Enclave.spawnSyncWorker}.
  */
 export type WorkerClientOptions = {
-    /** Already-constructed module Worker running `@interncom/diplomatic/worker`. */
-    worker: Worker;
     /**
-     * Max wait for handshake (`ready` event or probe ping; default 15s).
-     * Failures throw; no fallback.
+     * Max wait for Enclave.spawnSyncWorker handshake (setSeed reply; default 15s).
      */
     readyTimeoutMs?: number;
     clock?: IClock;
@@ -35,6 +23,7 @@ export type WorkerClientOptions = {
     syncDebounceMs?: number;
 };
 export declare class WorkerClient implements IClient<URL> {
+    /** Set only by setSeed → Enclave.spawnSyncWorker. */
     private worker;
     private state;
     /** Shared protocol store (main connection). */
@@ -43,9 +32,8 @@ export declare class WorkerClient implements IClient<URL> {
     private local;
     private nextId;
     private pending;
-    private ready;
-    private resolveReady;
-    private rejectReady;
+    /** Max wait for setSeed worker handshake. */
+    private readyTimeoutMs;
     /** Debounced local write → worker upload/sync. */
     private scheduledSync;
     private cachedClientState;
@@ -53,54 +41,44 @@ export declare class WorkerClient implements IClient<URL> {
     clientState: IStateEmitter<IDiplomaticClientState>;
     xferState: IStateEmitter<IDiplomaticClientXferState>;
     private constructor();
-    private failReady;
+    /** Wire handlers; terminate any previous worker. */
+    private bindWorker;
+    /** Reject all in-flight RPC (worker death / init failure). */
+    private failPending;
     /**
      * Run any pending debounced worker sync now and await it.
      * Useful in tests (with real debounce) or after a burst of local writes.
      */
     flushScheduledSync(): Promise<void>;
     /**
-     * Attach to an app-provided Worker. `store` is the shared protocol IDB (main
-     * connection) used for local msg writes; worker opens its own connection.
-     * Throws if the worker never becomes ready — does not fall back to main thread.
-     *
-     * Handshake: wait for unsolicited `ready` **or** a successful probe `ping`.
-     * The probe covers the common case where the app started the Worker early and
-     * `ready` was dropped before this thread set `onmessage`.
-     *
-     * Then hydrate client/xfer state from the shared store (and RPC) so
-     * `clientState.get()` is correct before connect returns — unsolicited
-     * `clientState` events are often lost when the Worker starts before
-     * `onmessage` is attached.
+     * Open the worker-mode façade without spawning a Worker.
+     * Shared store hydrates client/xfer state; network starts after setSeed.
      */
-    static connect(state: IStateManager, store: IStore<URL>, opts: WorkerClientOptions): Promise<WorkerClient>;
+    static open(state: IStateManager, store: IStore<URL>, opts?: WorkerClientOptions): Promise<WorkerClient>;
     /**
      * Snapshot seed/host/queues from the shared main-thread store.
      * `connected` stays false until the worker reports otherwise.
      */
     private hydrateStateFromStore;
     /**
-     * Request current client/xfer state from the worker. Recovers when unsolicited
-     * `clientState` / `xferState` events fired before `onmessage` was set.
+     * Request current client/xfer state from the worker (after setSeed).
      */
     private pullRemoteState;
-    /** Resolve the ready barrier (idempotent). */
-    private markReady;
-    /**
-     * Active handshake: post ping without waiting for the ready event.
-     * On pong, mark ready so connect can proceed even if `ready` was missed.
-     */
-    private probeReady;
-    /** Lightweight RPC check after connect. */
+    private requireWorker;
+    /** Lightweight RPC check after setSeed. */
     ping(): Promise<void>;
-    /** Terminate the worker (drops protocol DB connection in that thread). */
+    /** Terminate the worker if any (drops protocol DB connection in that thread). */
     terminate(): void;
     private onMessage;
     private allocId;
     private request;
     private requestStatus;
     private serializeHost;
-    setSeed(seed: MasterSeed, opts?: SetSeedOpts): Promise<void>;
+    /**
+     * Persist seed on main, then Enclave.spawnSyncWorker (only worker spawn path).
+     * Awaits the worker's setSeed reply (worker boots, then applies seed).
+     */
+    setSeed(enclave: Enclave, opts?: SetSeedOpts): Promise<void>;
     link(host: IHostConnectionInfo<URL>, connect?: boolean): Promise<void>;
     unlink(label: string): Promise<void>;
     /** Hosts live in shared main IDB (same as local writer). */