@interncom/diplomatic 0.13.6 → 0.14.0

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

@@ -2,58 +2,94 @@ import { Enclave, type PasskeyPrfOpts } from "../shared/crypto/enclave";
 import { type SealedMasterKey } from "../shared/seed";
 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). */
+import { type PrfRp } from "../shared/webauthn/prf";
+import { type AuthenticatorAttachmentName, type EnrolledOs } from "../shared/webauthn/common";
+/** Max bindings on one device. Keeps allowCredentials small. */
+export declare const KEYRING_MAX = 8;
+export type KeyringType = "prf";
+/** One PRF binding (one binding key). Future types (shard, …) share this list. */
+export type KeyringEntry = {
+    type: "prf";
     sealedMaster: SealedMasterKey;
-    /** PRF salt used at wrap time. */
+    credId: Uint8Array;
+    /** blake3(master ‖ bindtag ‖ credId); check-only, not a display fingerprint. */
+    tag: Uint8Array;
+    userId?: Uint8Array;
+    nick?: string;
+    enrolledAt: number;
+    lastUsedAt?: number;
+    attachment?: AuthenticatorAttachmentName;
+    transports?: string[];
+    aaguid?: Uint8Array;
+    enrolledOs?: EnrolledOs;
+};
+/** Local keyring: one PRF salt, a flat list of typed bindings. */
+export type Keyring = {
     salt: Uint8Array;
-    /**
-     * Last PRF passkey id (allowCredentials). The sealed-meta row itself is
-     * the breadcrumb that this device enrolled PRF unlock.
-     */
-    credId?: Uint8Array;
+    entries: KeyringEntry[];
+};
+/** Public row — no sealed bytes. */
+export type KeyringRow = {
+    type: "prf";
+    credId: Uint8Array;
+    userId?: Uint8Array;
+    nick?: string;
+    enrolledAt: number;
+    lastUsedAt?: number;
+    attachment?: AuthenticatorAttachmentName;
+    transports?: string[];
+    aaguid?: Uint8Array;
+    enrolledOs?: EnrolledOs;
 };
 /**
- * Persist sealed-master metadata for cold start (e.g. protocol IDB seedMeta).
+ * Persist the keyring for cold start (e.g. protocol IDB).
  * Called with `undefined` when the store is wiped.
  */
-export type PersistPrfSeedMeta = (meta: PrfSeedMeta | undefined) => void | Promise<void>;
+export type PersistKeyring = (ring: Keyring | undefined) => void | Promise<void>;
 export type PrfSeedStoreOpts = PrfRp & {
-    /**
-     * 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;
+    persistKeyring: PersistKeyring;
+    keyring?: Keyring;
 };
 /**
- * Session + durable PRF-wrapped seed. Session secret is always {@link Enclave}.
+ * Session + durable PRF-bound 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 bindAndSave} creates a binding and appends/upserts a keyring entry.
  * - {@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;
+    get keyring(): Keyring | undefined;
+    /** Public rows (no sealed master). */
+    list(): KeyringRow[];
     save(enclave: Enclave, opts?: SetSeedOpts): Promise<Enclave>;
     /**
-     * PRF UV inside Enclave, seal master, persist meta (no PRF leaves Enclave).
+     * PRF UV inside Enclave.bind, persist the entry.
+     * Always creates a new cred unless `credId` is passed (re-bind that cred).
+     * Existing tags are checked inside the enclave (one keyring, one master).
      */
-    wrapAndSave(enclave: Enclave, opts?: Pick<PasskeyPrfOpts, "salt" | "credId" | "createCredIfNeeded" | "authenticatorAttachment" | "hints">): Promise<ValStat<Enclave>>;
+    bindAndSave(enclave: Enclave, opts?: Pick<PasskeyPrfOpts, "salt" | "credId" | "createCredIfNeeded" | "authenticatorAttachment" | "hints" | "excludeCredentials"> & {
+        nick?: string;
+    }): Promise<ValStat<Enclave>>;
     load(): Promise<Enclave | void>;
     /** Passkey UV inside Enclave → new session enclave. */
     unlock(): Promise<ValStat<Enclave>>;
+    /** Set a display nick (local only; does not update the binding key). */
+    rename(credId: Uint8Array, nick: string): Promise<ValStat<void>>;
     /**
-     * Install sealed meta + session enclave (e.g. after pair-package open) and persist.
+     * Drop a binding from this browser. Does not delete the binding-key cred.
+     * Last entry clears the keyring.
      */
-    adoptSealed(enclave: Enclave, meta: PrfSeedMeta): Promise<ValStat<Enclave>>;
+    remove(credId: Uint8Array): Promise<ValStat<void>>;
     wipe(): Promise<void>;
 }
+export declare function cloneKeyring(r: Keyring): Keyring;
+/** Read a keyring from IDB structured-clone output. */
+export declare function decodeKeyring(raw: unknown): Keyring | undefined;
+/** Cred ids of every keyring entry. */
+export declare function keyringCredIds(ring: Keyring | undefined): Uint8Array[];
+/** Inferred kind for UI. Not attested. */
+export declare function keyringKind(row: KeyringRow): string;
+/** Display label: nick, else inferred kind + short cred id. */
+export declare function keyringLabel(row: KeyringRow): string;

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

@@ -5,20 +5,33 @@ import type { ICrypto, PublicKey } from "../types.ts";
 import { type ValStat } from "../valstat.ts";
 import { type DHKEReq, type DHKEResp, PairRequest } from "./pairing.ts";
 import { type LargeBlobCreateOpts, type LargeBlobRp } from "../webauthn/largeBlob.ts";
-import { type PrfCreateOpts, type PrfEvalOpts, type PrfRp } from "../webauthn/prf.ts";
+import { type PrfCeremony, 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 = PrfCreateOpts & {
-    credId?: Uint8Array;
+    credId?: Uint8Array | readonly Uint8Array[];
     /** Seal only: create a PRF credential first when no credId is known. */
     createCredIfNeeded?: boolean;
 };
-/** Durable PRF-sealed master + public meta (never includes PRF output). */
-export type PrfSealedMaster = {
+/** One binding to try on unseal (cred id + sealed master). */
+export type PrfBinding = {
+    sealedMaster: SealedMasterKey;
+    credId: Uint8Array;
+};
+/** Durable PRF-sealed master + public ceremony facts (never includes PRF output). */
+export type PrfSealedMaster = PrfCeremony & {
     sealedMaster: SealedMasterKey;
     salt: Uint8Array;
+};
+/** One existing keyring member used to prove this enclave matches the list. */
+export type BindPrior = {
     credId: Uint8Array;
+    tag: Uint8Array;
+};
+/** Seal + bind-tag from {@link Enclave.bind} (tag is not a global fingerprint). */
+export type PrfBound = PrfSealedMaster & {
+    tag: Uint8Array;
 };
 export type EncryptCipher = {
     encrypt: (data: Uint8Array) => Promise<Uint8Array>;
@@ -46,7 +59,7 @@ export type Identity = {
     /** Per-bag KDM mixed with this identity's private key (see bag seal). */
     kdmFor: (msgHeadEnc: Uint8Array) => Promise<Uint8Array>;
 };
-declare const SEAL_WRAP_DOMAIN: Uint8Array<ArrayBufferLike>;
+declare const SEAL_BIND_DOMAIN: Uint8Array<ArrayBufferLike>;
 declare const SEAL_KEY_LEN = 32;
 declare const SEAL_PRF_MIN_LEN = 16;
 export declare class Enclave {
@@ -69,11 +82,16 @@ export declare class Enclave {
      */
     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.
-     * Returns the credential id used so stores can persist it (skip picker next time).
+     * UV + PRF seal, plus a per-cred bind tag (blake3(master ‖ domain ‖ credId)).
+     * Tag compute and compare stay in the enclave. If `prior` is non-empty, every
+     * stored tag must match this master or bind fails (one keyring, one master).
+     */
+    bind(opts?: PasskeyPrfOpts, prior?: readonly BindPrior[]): Promise<ValStat<PrfBound>>;
+    /**
+     * UV + PRF ceremony, then unseal one of `bindings` into a new Enclave.
+     * allowCredentials is the union of binding cred ids. Returns the asserted id.
      */
-    static unsealWithPasskey(sealedMaster: SealedMasterKey, opts: PasskeyPrfOpts & {
+    static unsealWithPasskey(bindings: readonly PrfBinding[], opts: PasskeyPrfOpts & {
         salt: Uint8Array;
     }): Promise<ValStat<{
         enclave: Enclave;
@@ -135,4 +153,4 @@ export declare class Enclave {
 }
 /** Derive seal key from PRF output (domain-separated). Used by enclave seal/unseal. */
 export declare function sealKeyFromPrf(crypto: ICrypto, prf: Uint8Array, domain?: Uint8Array): Promise<ValStat<Uint8Array>>;
-export { MASTER_SEED_LEN, SEAL_KEY_LEN, SEAL_PRF_MIN_LEN, SEAL_WRAP_DOMAIN };
+export { MASTER_SEED_LEN, SEAL_BIND_DOMAIN, SEAL_KEY_LEN, SEAL_PRF_MIN_LEN };

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

@@ -13,7 +13,7 @@ export type MasterSeed = Uint8Array & {
 };
 /**
  * Master seed sealed under KDF(PRF) (nonce‖ciphertext‖tag).
- * Useless without the PRF output that derives the wrap key.
+ * Useless without the PRF output that derives the binding key.
  */
 export type SealedMasterKey = Uint8Array & {
     readonly [sealedMasterKeySymbol]: true;

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

@@ -5,7 +5,7 @@ export declare const WEBAUTHN_CHAL_LEN = 32;
 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. */
+/** Prefer modern curves; include RS256 for broader binding-key coverage. */
 export declare const WEBAUTHN_PUB_KEY_PARAMS: PublicKeyCredentialParameters[];
 /** UA preference for the WebAuthn picker. Not exclusive; omit attachment to allow both. */
 export type WebAuthnHint = "security-key" | "client-device" | "hybrid";
@@ -51,3 +51,13 @@ export declare function asPublicKeyCredential(cred: Credential | null): ValStat<
  * `extKey` e.g. `"extension:largeBlob"`, `"extension:prf"`.
  */
 export declare function webAuthnExtensionCapable(extKey: string): Promise<boolean>;
+export type AuthenticatorAttachmentName = "platform" | "cross-platform";
+export type EnrolledOs = "ios" | "macos" | "android" | "windows" | "linux" | "other";
+/** Maps a WebAuthn attachment string to the two legal values. */
+export declare function readAttachment(v: string | null | undefined): AuthenticatorAttachmentName | undefined;
+/** Coarse OS of this browser (enrollment / display only). */
+export declare function enrolledOsFromUA(ua: string): EnrolledOs;
+/** `getTransports()` on an attestation response, if the UA exposes it. */
+export declare function readTransports(pk: PublicKeyCredential): string[] | undefined;
+/** AAGUID from attested credential data (create). Undefined if AT is absent. */
+export declare function readAaguid(pk: PublicKeyCredential): Uint8Array | undefined;

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

@@ -1,5 +1,5 @@
 import { type ValStat } from "../valstat.ts";
-import { type WebAuthnRp } from "./common.ts";
+import { type AuthenticatorAttachmentName, type WebAuthnRp } from "./common.ts";
 export type PrfRp = WebAuthnRp;
 export type PrfCreateOpts = PrfRp & {
     userName?: string;
@@ -7,22 +7,33 @@ export type PrfCreateOpts = PrfRp & {
     authenticatorAttachment?: "platform" | "cross-platform";
     /** Seal salt (eval is on get, not create — some UAs throw on create-time eval). */
     salt?: Uint8Array;
+    /** Already-bound cred ids so create does not assert an existing key. */
+    excludeCredentials?: readonly Uint8Array[];
 };
 /** Default salt for DIPLOMATIC PRF eval (UTF-8). */
 export declare const DEFAULT_PRF_SALT: Uint8Array<ArrayBufferLike>;
+/** Default WebAuthn user.name / displayName when none is supplied. */
+export declare const DEFAULT_PRF_USER_NAME = "diplomatic-prf";
 /** Bytes of PRF output we consume (first N of `results.first`). */
 export declare const PRF_OUTPUT_LEN = 32;
-export type PrfCreateResult = {
+/** Public ceremony facts (no PRF bytes). */
+export type PrfCeremony = {
     credId: Uint8Array;
+    userId?: Uint8Array;
+    attachment?: AuthenticatorAttachmentName;
+    transports?: string[];
+    aaguid?: Uint8Array;
+};
+export type PrfCreateResult = PrfCeremony & {
     prfEnabled: boolean;
 };
 /** Internal: PRF output + cred id. For Enclave only — do not re-export to apps. */
-export type PrfEvalResult = {
+export type PrfEvalResult = PrfCeremony & {
     prf: Uint8Array;
-    credId: Uint8Array;
 };
 export type PrfEvalOpts = PrfRp & {
-    credId?: Uint8Array;
+    /** One id, or every bound id so a spare key can assert in one get(). */
+    credId?: Uint8Array | readonly Uint8Array[];
     salt?: Uint8Array;
 };
 /** Best-effort: client advertises PRF extension. */

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

@@ -1,34 +1,32 @@
 import { Enclave } from "../../shared/crypto/enclave";
 import type { ICrypto } from "../../shared/types";
 import type { ISeedStore, SetSeedOpts } from "../../types";
-import { type PrfSeedMeta, PrfSeedStore, type PrfSeedStoreOpts } from "../../passkey/prf-store";
+import { type Keyring, PrfSeedStore, type PrfSeedStoreOpts } from "../../passkey/prf-store";
 export declare class IDBSeedStore implements ISeedStore {
     #private;
     db: IDBDatabase;
     constructor(db: IDBDatabase, crypto: ICrypto);
     /**
-     * Hold enclave in memory only. Durable identity is sealed meta
-     * ({@link openPrfStore} / {@link persistPrfMeta}), never plain seed.
+     * Hold enclave in memory only. Durable identity is the keyring
+     * ({@link openPrfStore} / {@link persistKeyring}), never plain seed.
      * Pins identity (nonce+hash) on first save; later saves must match
      * (largeBlob / PRF unlock cannot switch masters under this DB).
      * `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.
+     * bind API) should seal under a passphrase KDF and write sealed meta here —
+     * same shape as a keyring entry, not a return of raw seed.
      */
     save(enclave: Enclave, _opts?: SetSeedOpts): Promise<Enclave>;
     load(): Promise<Enclave | undefined>;
     /**
-     * Drop in-memory enclave. Keeps {@link K_PRF_META} and {@link K_ID_PIN}
+     * Drop in-memory enclave. Keeps {@link K_KEYRING} and {@link K_ID_PIN}
      * so unlock / largeBlob restore still match this device.
      */
     clearSession(): Promise<void>;
     wipe(): Promise<void>;
-    loadPrfMeta(): Promise<PrfSeedMeta | undefined>;
-    persistPrfMeta(meta: PrfSeedMeta | undefined): Promise<void>;
-    hasPrfMeta(): Promise<boolean>;
-    /** Last PRF passkey id, if this device has a sealed PRF identity. */
-    lastPrfCredId(): Promise<Uint8Array | undefined>;
-    openPrfStore(opts: Omit<PrfSeedStoreOpts, "persistMeta" | "meta">): Promise<PrfSeedStore>;
+    loadKeyring(): Promise<Keyring | undefined>;
+    persistKeyring(ring: Keyring | undefined): Promise<void>;
+    hasKeyring(): Promise<boolean>;
+    openPrfStore(opts: Omit<PrfSeedStoreOpts, "persistKeyring" | "keyring">): Promise<PrfSeedStore>;
 }

package/dist/web/types.d.ts

@@ -35,7 +35,7 @@ export type SetSeedOpts = {
     /**
      * 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
+     * IDB holds the enclave in memory only — durable identity is the PRF keyring
      * via {@link IDBSeedStore.openPrfStore}, never plain seed.
      * Default false (session enclave only).
      *
@@ -50,7 +50,7 @@ export type SetSeedOpts = {
  * Default `client.wipe()` / `client.wipe({})` clears **everything except seed**:
  * msgs, ents, meta = true; seed = false.
  * That avoids passkey/largeBlob UV when the user only wants to clear app data.
- * Pass `{ seed: true }` to also clear identity (may prompt the authenticator).
+ * Pass `{ seed: true }` to also clear identity (may prompt the binding key).
  */
 export type WipeOpts = {
     /** Message archive. Default true. */