@cef-ai/widget-runtime 1.0.5 → 1.1.0

package/README.md

@@ -16,15 +16,175 @@ for consumers that import the helpers directly.
 
 The runtime resolves a signing identity from the best available source:
 
-1. **Embedded (host):** when iframed by the Cere Vault, it signs through the
-   host's postMessage sign-bridge.
-2. **Standalone (interactive wallet):** when there is no responding host — the
-   widget is opened top-level via a direct link — it connects an interactive
-   Cere embed-wallet built from `manifest.wallet.{appId,env}` (opens the wallet
-   UI) and signs locally.
-
-Both paths feed the same `@cef-ai/vault-sdk` client, so cubby reads, connect,
-publish, and audio uploads behave identically embedded or standalone.
+1. **Embedded (host):** when the widget is framed, it asks the embedding page
+   for an identity over `postMessage` and signs through it. The host does not
+   have to be the Cere Vault — the contract is host-agnostic and exported (see
+   [Host contract](#host-contract) below), so a browser-extension panel, a
+   partner app, or any page that has already authenticated the user can supply
+   it.
+2. **Standalone (interactive wallet) — currently NON-FUNCTIONAL.** When the
+   widget is **not** framed — opened top-level via a direct link — it was meant
+   to connect an interactive Cere embed-wallet built from
+   `manifest.wallet.{appId,env}` and sign locally. That path terminates at
+   `beta.openlogin.com`, which no longer resolves, so it fails rather than
+   opening a wallet. Tracked in CEF-AI/sdk#144 (dead endpoint) and #146
+   (replacement); `standalone-wallet.ts` is unchanged and still shipped.
+   **Until those land, treat path 1 as the only working one: frame the widget
+   and mount a host.**
+
+Path 1 feeds the `@cef-ai/vault-sdk` client, so cubby reads, connect, publish,
+and audio uploads work the same way whichever host supplies the identity.
+
+**A framed widget never falls back to (2)** (behaviour change in 1.1). If the
+host does not answer the handshake within 8 s, or answers malformed, the runtime
+surfaces `WidgetSignedOutError` and the identity stays `anon`. It used to
+silently open the standalone wallet instead, which looked like a hang and
+produced an identity the host knew nothing about. The Cere Vault host already
+implements the handshake, so it is unaffected; a page that frames a CEF widget
+**without** implementing the host contract now gets `WidgetSignedOutError` where
+it previously got the silent fallback. If you frame a widget in your own page,
+mount [`createWidgetHost`](#host-contract) on it.
+
+## Host contract
+
+Four `postMessage` messages, widget → host and back.
+
+**Gate the inbound side first.** The host holds the user's signing key, so
+`createWidgetHost` makes you name who may talk to it. `allowedOrigins` is
+**required and non-empty**, and it throws at mount without it — an ungated
+listener is a signing oracle for every other frame, opener, or popup on the
+page.
+
+**A frame handle does not pin a document.** `widget` is an optional, and
+recommended, *extra* narrowing — never a replacement for `allowedOrigins`. A
+`WindowProxy` keeps its identity across navigation, **cross-origin included**:
+after the framed page follows an open redirect, or navigates itself, or has its
+`src` set from a query param, `event.source === iframe.contentWindow` still
+holds and only `event.origin` has moved. A host gated on the frame alone would
+sign arbitrary bytes for whatever later occupies that slot. When both options
+are given, **both must pass**.
+
+Each `allowedOrigins` entry must be a canonical origin spelled exactly as
+`event.origin` reports it — scheme + host + non-default port, lower-case, no
+trailing slash, no path (`'https://widget.example'`,
+`'http://localhost:5173'`). A default port is not optional spelling: an origin
+omits `:443` on https and `:80` on http, so `'https://widget.example:443'`
+throws too. Anything else throws at mount rather than failing
+silently at runtime. In particular **`'*'` is rejected**: `postMessage` takes
+`*` as a `targetOrigin` wildcard, but `event.origin` is never the string `"*"`,
+so an allowlist of `['*']` would mount clean and then answer nobody.
+
+**Sandboxed widgets.** A sandboxed frame's `event.origin` is the literal string
+`"null"`, so pass `allowedOrigins: ['null']` to frame one. That is an opaque
+origin — every sandboxed frame reports it, so pair it with `widget` if any
+other sandboxed frame can reach the page. Separately, a `"null"` origin relaxes
+only the **reply** `targetOrigin` (`'*'`, since `"null"` is not a valid
+`targetOrigin`); it never relaxes the inbound decision.
+
+Bytes on the wire are `number[]`, **not** `Uint8Array`. Structured clone handles
+typed arrays everywhere; the reason is the rest of the chain. A real host
+usually forwards the payload over a JSON-serialising transport —
+`chrome.runtime.sendMessage` to an extension service worker, a native-messaging
+port — which turns a `Uint8Array` into `{"0":1,"1":2,…}` and hands the signer
+something the widget never sent.
+
+| Message | Direction | Fields |
+| --- | --- | --- |
+| `cef-widget:identity-request` | widget → host | `requestId: string`, `v: number` |
+| `cef-widget:identity-response` | host → widget | `requestId: string`, `v?: number`, `pubkey?: string`, `sigType?: 'ed25519' \| 'sr25519'` (default `ed25519`), `error?: string`, `errorCode?: 'unsupported-version'` |
+| `cef-widget:sign-request` | widget → host | `requestId: string`, `v: number`, `bytes: number[]` |
+| `cef-widget:sign-response` | host → widget | `requestId: string`, `v?: number`, `signature: number[] \| null` (`null` = user declined), `error?: string`, `errorCode?: 'unsupported-version'` |
+
+Rules:
+
+- **Versioning (`v`).** Current version is `1` (`PROTOCOL_VERSION`). A message
+  that carries **no `v` is treated as v1** — that is what keeps
+  already-deployed widgets and the existing Vault host working untouched. An
+  **unrecognised `v` is rejected** with a named `WidgetProtocolVersionError`;
+  it is never silently ignored. A peer that rejects the other side's `v`
+  answers with `errorCode: 'unsupported-version'` — its own reply is still a v1
+  message, so `v` itself cannot carry the rejection, and without the code the
+  receiver would just see an opaque error string and keep retrying.
+- **Sign verbatim.** The host must sign the exact bytes it receives with
+  **`ed25519_signRaw`**. Do **not** use the high-level `signMessage` /
+  `wallet_signMessage`, which wrap the payload in Substrate's
+  `<Bytes>…</Bytes>` envelope — a signature over the wrapped form verifies
+  nowhere (not in GAR, not at the DDC gateway).
+- **Validate what you sign.** Every element of `bytes` must be an integer
+  `0–255`, and the payload is capped at 64 KiB (`MAX_SIGN_BYTES`). `Uint8Array.from`
+  coerces junk silently (`300` → `44`, `'zz'` → `0`, and a sparse array's holes
+  → `0`), which would produce a perfectly valid signature over the wrong
+  payload. `createWidgetHost` does this check for you and answers
+  `WidgetMalformedMessageError`; a hand-rolled host must do it itself —
+  `isByteArray` and `MAX_SIGN_BYTES` are exported for exactly that, so the cap
+  moves in one place. The widget applies the same check to `signature`, and
+  refuses to post a payload over the cap in the first place.
+- **Timing.** The widget retries `identity-request` every **400 ms** for up to
+  **8 s** before giving up (the host page and the iframe race to attach their
+  listeners, so the first request is often sent before the host is ready — just
+  answer whichever request you see). A reply **slower than the retry interval
+  still counts**: every request the handshake issued stays open, which is what a
+  cold extension service worker needs. A `sign-request` waits up to **60 s**,
+  the user's time to approve in the host's UI. A handshake that times out is not
+  cached — a later action (the user connects after the widget loaded) starts a
+  fresh one.
+- **Replies are source-gated.** The widget only accepts messages whose
+  `event.source === window.parent`. Always reply to `event.source`, echoing the
+  request's `requestId`.
+
+### Mounting a host (non-Vault example)
+
+`createWidgetHost` is the host side of the table above — one listener, no
+dependencies. Mount it once on the page that frames the widget:
+
+```ts
+import { createWidgetHost } from '@cef-ai/widget-runtime';
+
+// An extension panel that has ALREADY authenticated the user with SCP Wallet.
+const dispose = createWidgetHost({
+  // REQUIRED. The gate between the page and the user's key: which DOCUMENT may
+  // ask. Canonical origins only — no trailing slash, no path, and no '*'.
+  // Use ['null'] for a sandboxed widget.
+  allowedOrigins: ['https://widget.example'],
+
+  // Optional but recommended: narrow to one frame as well. Both must pass.
+  // On its own this would NOT be safe — the handle survives navigation.
+  widget: document.querySelector<HTMLIFrameElement>('iframe#cef-widget')!,
+
+  // Return null/undefined while the user is not signed in yet — the widget
+  // retries for 8 s, and a later action retries again after that.
+  getIdentity: () => (scp.isConnected() ? { pubkey: scp.publicKey, sigType: 'ed25519' } : null),
+
+  // Verbatim raw-bytes signing. Return null if the user declines; throw to
+  // report a failure. Never route this to signMessage/wallet_signMessage.
+  //
+  // NOTE: called more than once per widget action — a first `query()` signs
+  // twice (delegation-token mint, then vault claim). If you put a user prompt
+  // behind this, the reader sees two prompts before the first cubby read.
+  // Cache or batch consent rather than prompting per call.
+  sign: async (bytes) => scp.request({ method: 'ed25519_signRaw', params: [bytes] }),
+});
+
+// On unmount:
+dispose();
+```
+
+The widget then resolves its identity through the host, exactly as it does
+inside the Cere Vault, and the standalone wallet is never opened.
+
+**Chrome extension hosts:** an MV3 panel must also allow the widget's origin in
+its own CSP, or the frame never loads and the handshake has nothing to answer:
+
+```json
+"content_security_policy": {
+  "extension_pages": "script-src 'self'; object-src 'self'; frame-src https://widget.example"
+}
+```
+
+Verified end-to-end against a real extension: the widget resolves the host's
+identity, signatures cross the frame as `number[]` and verify, and with no host
+mounted the framed widget fails `WidgetSignedOutError` without reaching the
+legacy wallet.
 
 ## Build
 

package/dist/entry.js

@@ -3,6 +3,7 @@ import { VaultSDK } from '@cef-ai/vault-sdk';
 import { createHostBridge } from './host-bridge.js';
 import { toVaultSdkSigner } from './bridge-wallet.js';
 import { connectStandaloneWallet } from './standalone-wallet.js';
+import { createIdentityResolver } from './resolve-identity.js';
 import { createVaultClient } from './vault-client.js';
 import { createWidgetRuntime } from './runtime.js';
 import { captureAndUploadAudio, createVaultObjectUploader } from './audio/capture-upload.js';
@@ -27,42 +28,16 @@ function boot() {
         return;
     const bridge = createHostBridge();
     // ── Multi-source identity ─────────────────────────────────────────────────
-    // Tier 1: the Vault host iframes us → use the postMessage sign-bridge.
-    // Tier 2/3: no responding host (top-level link, or the bridge times out
-    // returning null) → connect an interactive Cere embed-wallet built from
-    // `manifest.wallet.{appId,env}` (opens the wallet UI). Both paths yield a
-    // pubkey + raw-bytes signer that feed the SAME vault-sdk client.
-    //
-    // Memoized so the (possibly interactive) resolution runs at most once — the
-    // wallet popup must not open on every query/connect/upload.
-    let identityP = null;
-    const resolveSigningIdentity = () => {
-        if (identityP)
-            return identityP;
-        identityP = (async () => {
-            const hostId = await bridge.requestIdentity();
-            if (hostId) {
-                return {
-                    source: 'host',
-                    publicKey: hostId.pubkey,
-                    sigType: hostId.sigType,
-                    sign: (bytes) => bridge.sign(bytes),
-                };
-            }
-            // No host → interactive wallet (standalone / direct-link boot).
-            const wallet = await connectStandaloneWallet(manifest.wallet);
-            return {
-                source: 'wallet',
-                publicKey: wallet.pubkey(),
-                sigType: wallet.sigType,
-                sign: (bytes) => wallet.signRawBytes(bytes),
-            };
-        })().catch((err) => {
-            identityP = null; // let a later action retry (e.g. user reopens the wallet)
-            throw err;
-        });
-        return identityP;
-    };
+    // Framed → the embedding host (Cere Vault, or any page mounting
+    // `createWidgetHost`) answers the postMessage handshake. Top-level → an
+    // interactive Cere embed-wallet built from `manifest.wallet.{appId,env}`.
+    // Both paths yield a pubkey + raw-bytes signer feeding the SAME vault-sdk
+    // client. A framed widget whose handshake fails throws WidgetSignedOutError
+    // rather than downgrading to the wallet — see ./resolve-identity.
+    const resolveSigningIdentity = createIdentityResolver({
+        bridge,
+        connectWallet: () => connectStandaloneWallet(manifest.wallet),
+    });
     const deps = {
         resolveIdentity: async () => {
             const id = await resolveSigningIdentity();

package/dist/host-bridge.d.ts

@@ -1,11 +1,81 @@
+import type { VaultSigType } from '@cef-ai/vault-sdk';
 export declare const IDENTITY_REQUEST_TYPE = "cef-widget:identity-request";
 export declare const IDENTITY_RESPONSE_TYPE = "cef-widget:identity-response";
 export declare const SIGN_REQUEST_TYPE = "cef-widget:sign-request";
 export declare const SIGN_RESPONSE_TYPE = "cef-widget:sign-response";
+/**
+ * Protocol version stamped on every outgoing message as `v`.
+ *
+ * Compatibility rule: a message that carries NO `v` is treated as v1. That is
+ * what keeps every already-deployed widget and the existing Vault host working
+ * untouched — neither of them sends `v`. An unrecognised `v` is a hard failure
+ * (`WidgetProtocolVersionError`), never a silently ignored message.
+ */
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * `errorCode` value a peer sets when it rejected the OTHER side's `v`. The
+ * reply itself is still a v1 message, so `v` cannot carry this: without the
+ * code the receiver would see a plain error string and keep retrying.
+ */
+export declare const UNSUPPORTED_VERSION_CODE = "unsupported-version";
+/** Largest `bytes` payload a host will sign, and largest signature accepted. */
+export declare const MAX_SIGN_BYTES: number;
+export type SigType = VaultSigType;
+export interface IdentityRequest {
+    type: typeof IDENTITY_REQUEST_TYPE;
+    requestId: string;
+    v: number;
+}
+export interface IdentityResponse {
+    type: typeof IDENTITY_RESPONSE_TYPE;
+    requestId: string;
+    /** Omitted by pre-versioning hosts; absent means v1. */
+    v?: number;
+    pubkey?: string;
+    /** Defaults to 'ed25519' when omitted. */
+    sigType?: SigType;
+    error?: string;
+    /** Machine-readable reason; see UNSUPPORTED_VERSION_CODE. */
+    errorCode?: typeof UNSUPPORTED_VERSION_CODE;
+}
+export interface SignRequest {
+    type: typeof SIGN_REQUEST_TYPE;
+    requestId: string;
+    v: number;
+    /** Bytes to sign verbatim. number[], not Uint8Array — see the README. */
+    bytes: number[];
+}
+export interface SignResponse {
+    type: typeof SIGN_RESPONSE_TYPE;
+    requestId: string;
+    /** Omitted by pre-versioning hosts; absent means v1. */
+    v?: number;
+    /** number[] signature, or null when the user declined. */
+    signature: number[] | null;
+    error?: string;
+    /** Machine-readable reason; see UNSUPPORTED_VERSION_CODE. */
+    errorCode?: typeof UNSUPPORTED_VERSION_CODE;
+}
+/** A peer spoke a protocol version this build does not understand. */
+export declare class WidgetProtocolVersionError extends Error {
+    constructor(detail: string);
+}
+/** A peer sent a message that does not match the wire contract. */
+export declare class WidgetMalformedMessageError extends Error {
+    constructor(detail: string);
+}
+/** True when `v` is present and is not a version we speak. Absent `v` == v1. */
+export declare function isUnsupportedVersion(v: unknown): boolean;
+/**
+ * Wire bytes are number[] — and nothing else. `Uint8Array.from` coerces junk
+ * silently (`'zz'` → 0, `300` → 44), which would hand a signer a payload the
+ * peer never sent, so both directions validate every element here.
+ */
+export declare function isByteArray(value: unknown): value is number[];
 export interface HostBridge {
     requestIdentity: () => Promise<{
         pubkey: string;
-        sigType: 'ed25519' | 'sr25519';
+        sigType: SigType;
     } | null>;
     sign: (bytes: Uint8Array) => Promise<Uint8Array>;
 }

package/dist/host-bridge.js

@@ -1,16 +1,73 @@
 // packages/widget-runtime/src/host-bridge.ts
 //
-// postMessage client that talks to the Vault host's widget-sign-bridge.
-// Protocol types MUST match the host repo exactly (protocol.ts in vault):
+// postMessage client for the widget→host identity/signing contract. The Cere
+// Vault is one host; ANY page that frames a widget can implement the same four
+// messages (see `createWidgetHost` in ./widget-host for a ready-made host
+// side, and the protocol table in the package README):
 //   cef-widget:identity-request / cef-widget:identity-response
 //   cef-widget:sign-request     / cef-widget:sign-response
 //
-// Wire bytes are always number[] (not Uint8Array) — postMessage does not
-// structured-clone Uint8Array reliably across sandboxed origin pairs.
+// The contract rules a host must honour (verbatim signing, number[] on the
+// wire, versioning) live in the README's "Host contract" section — one copy.
 export const IDENTITY_REQUEST_TYPE = 'cef-widget:identity-request';
 export const IDENTITY_RESPONSE_TYPE = 'cef-widget:identity-response';
 export const SIGN_REQUEST_TYPE = 'cef-widget:sign-request';
 export const SIGN_RESPONSE_TYPE = 'cef-widget:sign-response';
+/**
+ * Protocol version stamped on every outgoing message as `v`.
+ *
+ * Compatibility rule: a message that carries NO `v` is treated as v1. That is
+ * what keeps every already-deployed widget and the existing Vault host working
+ * untouched — neither of them sends `v`. An unrecognised `v` is a hard failure
+ * (`WidgetProtocolVersionError`), never a silently ignored message.
+ */
+export const PROTOCOL_VERSION = 1;
+/**
+ * `errorCode` value a peer sets when it rejected the OTHER side's `v`. The
+ * reply itself is still a v1 message, so `v` cannot carry this: without the
+ * code the receiver would see a plain error string and keep retrying.
+ */
+export const UNSUPPORTED_VERSION_CODE = 'unsupported-version';
+/** Largest `bytes` payload a host will sign, and largest signature accepted. */
+export const MAX_SIGN_BYTES = 64 * 1024;
+/** A peer spoke a protocol version this build does not understand. */
+export class WidgetProtocolVersionError extends Error {
+    constructor(detail) {
+        super(`WidgetProtocolVersionError: ${detail}`);
+        this.name = 'WidgetProtocolVersionError';
+    }
+}
+/** A peer sent a message that does not match the wire contract. */
+export class WidgetMalformedMessageError extends Error {
+    constructor(detail) {
+        super(`WidgetMalformedMessageError: ${detail}`);
+        this.name = 'WidgetMalformedMessageError';
+    }
+}
+/** True when `v` is present and is not a version we speak. Absent `v` == v1. */
+export function isUnsupportedVersion(v) {
+    return v !== undefined && v !== PROTOCOL_VERSION;
+}
+/**
+ * Wire bytes are number[] — and nothing else. `Uint8Array.from` coerces junk
+ * silently (`'zz'` → 0, `300` → 44), which would hand a signer a payload the
+ * peer never sent, so both directions validate every element here.
+ */
+export function isByteArray(value) {
+    if (!Array.isArray(value) || value.length > MAX_SIGN_BYTES)
+        return false;
+    for (let i = 0; i < value.length; i++) {
+        // Not `.every()`: it SKIPS holes, so `[1, 2, , 4]` passed and
+        // `Uint8Array.from` then filled the gap with 0. structuredClone preserves
+        // holes, so a sparse array really does survive postMessage.
+        if (!(i in value))
+            return false;
+        const n = value[i];
+        if (typeof n !== 'number' || !Number.isInteger(n) || n < 0 || n > 255)
+            return false;
+    }
+    return true;
+}
 /** Singleton message listener + pending-request map; set up once on first use. */
 let listenerAttached = false;
 const pending = new Map();
@@ -41,16 +98,21 @@ function ensureListener() {
 function generateId() {
     return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
 }
-/** Identity result cached after first successful handshake. */
+/** Identity result cached after a SUCCESSFUL handshake. Failures are not
+ * cached: the user typically connects in the host after the widget loaded, so
+ * a later action must be able to handshake again. */
 let cachedIdentity = undefined;
 /**
- * Request the connected-wallet identity from the Vault host.
+ * Request the connected-wallet identity from the embedding host.
  *
  * Returns null when:
  *   - Not running inside an iframe (window.parent === window).
  *   - Host doesn't reply within ~8 s (attach-vs-load race exhausted).
  *   - Host replies with an error on every attempt.
  *
+ * Rejects with WidgetProtocolVersionError when the host answers with a `v`
+ * this build does not speak, or rejects ours.
+ *
  * Resolves immediately (from cache) on subsequent calls after a success.
  */
 async function requestIdentity() {
@@ -64,13 +126,17 @@ async function requestIdentity() {
     const RETRY_INTERVAL_MS = 400;
     const TOTAL_TIMEOUT_MS = 8000;
     const deadline = Date.now() + TOTAL_TIMEOUT_MS;
-    return new Promise((outerResolve) => {
+    return new Promise((outerResolve, outerReject) => {
         let settled = false;
         let retryTimer;
         let guardTimer;
-        let currentRequestId;
-        /** Clear both the retry timer and the outer deadline guard. */
-        function clearTimers() {
+        // EVERY request this handshake has issued stays pending: a host slower
+        // than the 400 ms retry interval (a cold extension service worker easily
+        // is) answers an earlier requestId, and that reply must still count.
+        const issued = new Set();
+        /** Stop the clock and drop every request this handshake issued. */
+        function finish() {
+            settled = true;
             if (retryTimer !== undefined) {
                 clearTimeout(retryTimer);
                 retryTimer = undefined;
@@ -79,28 +145,38 @@ async function requestIdentity() {
                 clearTimeout(guardTimer);
                 guardTimer = undefined;
             }
+            for (const id of issued)
+                pending.delete(id);
+            issued.clear();
         }
         function attempt() {
             if (settled)
                 return;
-            // Remove old pending entry (the host reply arrives on a per-requestId
-            // basis; stale IDs just get GC'd from the map when we replace them).
-            if (currentRequestId)
-                pending.delete(currentRequestId);
-            currentRequestId = generateId();
-            pending.set(currentRequestId, {
+            const requestId = generateId();
+            issued.add(requestId);
+            pending.set(requestId, {
                 resolve: (data) => {
                     if (settled)
                         return;
                     const d = data;
+                    // A version mismatch is permanent — retrying cannot fix it.
+                    if (isUnsupportedVersion(d.v)) {
+                        finish();
+                        outerReject(new WidgetProtocolVersionError(`the host replied in protocol v${String(d.v)}; this build speaks v${PROTOCOL_VERSION}`));
+                        return;
+                    }
+                    if (d.errorCode === UNSUPPORTED_VERSION_CODE) {
+                        finish();
+                        outerReject(new WidgetProtocolVersionError(`the host rejected protocol v${PROTOCOL_VERSION} (${d.error ?? 'no detail'})`));
+                        return;
+                    }
                     if (d.error || !d.pubkey) {
                         // Error response — keep retrying until deadline.
                         scheduleRetryOrTimeout();
                         return;
                     }
-                    settled = true;
-                    clearTimers();
-                    const result = { pubkey: d.pubkey, sigType: (d.sigType ?? 'ed25519') };
+                    const result = { pubkey: d.pubkey, sigType: d.sigType ?? 'ed25519' };
+                    finish();
                     cachedIdentity = result;
                     outerResolve(result);
                 },
@@ -112,7 +188,7 @@ async function requestIdentity() {
             });
             // targetOrigin '*' — same trust assumption as the sign request (see the
             // note below): host origin unknown to the widget; replies are source-gated.
-            window.parent.postMessage({ type: IDENTITY_REQUEST_TYPE, requestId: currentRequestId }, '*');
+            window.parent.postMessage({ type: IDENTITY_REQUEST_TYPE, requestId, v: PROTOCOL_VERSION }, '*');
             // Schedule an automatic retry in case no reply arrives within the interval.
             scheduleRetryOrTimeout();
         }
@@ -126,11 +202,7 @@ async function requestIdentity() {
             }
             const remaining = deadline - Date.now();
             if (remaining <= 0) {
-                settled = true;
-                clearTimers();
-                if (currentRequestId)
-                    pending.delete(currentRequestId);
-                cachedIdentity = null;
+                finish();
                 outerResolve(null);
                 return;
             }
@@ -143,45 +215,59 @@ async function requestIdentity() {
         // Also set an outer deadline guard in case no reply ever arrives.
         guardTimer = setTimeout(() => {
             if (!settled) {
-                settled = true;
-                clearTimers();
-                if (currentRequestId)
-                    pending.delete(currentRequestId);
-                cachedIdentity = null;
+                finish();
                 outerResolve(null);
             }
         }, TOTAL_TIMEOUT_MS + RETRY_INTERVAL_MS);
     });
 }
 /**
- * Ask the Vault host to sign `bytes` with the connected wallet.
+ * Ask the embedding host to sign `bytes` verbatim with the connected wallet.
  *
  * Rejects on:
+ *   - A payload over `MAX_SIGN_BYTES` (`WidgetMalformedMessageError`, before
+ *     anything is posted — the host would only reject it a round trip later,
+ *     and as an opaque `error` string).
  *   - `signature === null` (user declined).
  *   - `error` string in the response.
- *   - No response within ~60 s (modal closed / stale-reply race).
+ *   - A malformed reply (`WidgetMalformedMessageError`).
+ *   - No response within ~60 s (host closed the widget / stale-reply race).
  */
 async function sign(bytes) {
     if (window.parent === window)
         throw new Error('sign called outside of an iframe');
+    if (bytes.length > MAX_SIGN_BYTES) {
+        throw new WidgetMalformedMessageError(`sign-request.bytes is ${bytes.length} bytes; the contract caps it at ${MAX_SIGN_BYTES}`);
+    }
     ensureListener();
     const SIGN_TIMEOUT_MS = 60000;
     const requestId = generateId();
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
             pending.delete(requestId);
-            reject(new Error('widget signing timed out — the vault modal may have closed'));
+            reject(new Error('widget signing timed out — the host page may have closed the widget'));
         }, SIGN_TIMEOUT_MS);
         pending.set(requestId, {
             resolve: (data) => {
                 clearTimeout(timer);
                 const d = data;
-                if (d.error) {
+                if (isUnsupportedVersion(d.v)) {
+                    reject(new WidgetProtocolVersionError(`the host replied in protocol v${String(d.v)}; this build speaks v${PROTOCOL_VERSION}`));
+                }
+                else if (d.errorCode === UNSUPPORTED_VERSION_CODE) {
+                    reject(new WidgetProtocolVersionError(`the host rejected protocol v${PROTOCOL_VERSION} (${d.error ?? 'no detail'})`));
+                }
+                else if (d.error) {
                     reject(new Error(d.error));
                 }
                 else if (d.signature === null) {
                     reject(new Error('widget signing was declined'));
                 }
+                else if (!isByteArray(d.signature)) {
+                    // Without this the Uint8Array.from below throws out of the DOM
+                    // listener — after clearTimeout — and sign() never settles at all.
+                    reject(new WidgetMalformedMessageError('sign-response.signature must be null or an array of integers 0-255'));
+                }
                 else {
                     resolve(Uint8Array.from(d.signature));
                 }
@@ -191,11 +277,11 @@ async function sign(bytes) {
                 reject(reason);
             },
         });
-        // targetOrigin '*': the widget doesn't know the Vault host's origin (it's
+        // targetOrigin '*': the widget doesn't know the host's origin (it's
         // not in the manifest), and the host is trusted. Safe because replies are
         // gated on `event.source === window.parent` — only the real parent can
         // answer. If the manifest ever carries the host origin, pin it here.
-        window.parent.postMessage({ type: SIGN_REQUEST_TYPE, requestId, bytes: Array.from(bytes) }, '*');
+        window.parent.postMessage({ type: SIGN_REQUEST_TYPE, requestId, v: PROTOCOL_VERSION, bytes: Array.from(bytes) }, '*');
     });
 }
 /**

package/dist/index.d.ts

@@ -21,5 +21,9 @@ export { encodeWav } from './audio/wav.js';
 export { segmentPcm, decodeToMono16k } from './audio/segment.js';
 export { requestMicStream } from './audio/mic.js';
 export { createHostBridge, type HostBridge } from './host-bridge.js';
+export { IDENTITY_REQUEST_TYPE, IDENTITY_RESPONSE_TYPE, SIGN_REQUEST_TYPE, SIGN_RESPONSE_TYPE, PROTOCOL_VERSION, UNSUPPORTED_VERSION_CODE, MAX_SIGN_BYTES, isByteArray, WidgetProtocolVersionError, WidgetMalformedMessageError, } from './host-bridge.js';
+export type { SigType, IdentityRequest, IdentityResponse, SignRequest, SignResponse, } from './host-bridge.js';
+export { createWidgetHost, type WidgetHostOptions, type WidgetHostIdentity } from './widget-host.js';
+export { WidgetSignedOutError, type ResolvedSigningIdentity } from './resolve-identity.js';
 export { toVaultSdkSigner, toClientSdkWallet, toUploaderSignerPair, type VaultSignedWallet } from './bridge-wallet.js';
 export { connectStandaloneWallet, type StandaloneWallet } from './standalone-wallet.js';

package/dist/index.js

@@ -17,5 +17,14 @@ export { encodeWav } from './audio/wav.js';
 export { segmentPcm, decodeToMono16k } from './audio/segment.js';
 export { requestMicStream } from './audio/mic.js';
 export { createHostBridge } from './host-bridge.js';
+// ── Widget↔host contract (see README "Host contract") ───────────────────────
+// A host page implements the two RESPONSE shapes; it never constructs requests
+// — but it must PARSE them, so the request types ship too. `MAX_SIGN_BYTES`,
+// `UNSUPPORTED_VERSION_CODE` and `isByteArray` are the contract rules the
+// README hands a hand-rolled host: exported so nobody has to re-type them and
+// then drift when they move.
+export { IDENTITY_REQUEST_TYPE, IDENTITY_RESPONSE_TYPE, SIGN_REQUEST_TYPE, SIGN_RESPONSE_TYPE, PROTOCOL_VERSION, UNSUPPORTED_VERSION_CODE, MAX_SIGN_BYTES, isByteArray, WidgetProtocolVersionError, WidgetMalformedMessageError, } from './host-bridge.js';
+export { createWidgetHost } from './widget-host.js';
+export { WidgetSignedOutError } from './resolve-identity.js';
 export { toVaultSdkSigner, toClientSdkWallet, toUploaderSignerPair } from './bridge-wallet.js';
 export { connectStandaloneWallet } from './standalone-wallet.js';