@cef-ai/widget-runtime 1.0.5 → 1.1.1

package/dist/resolve-identity.d.ts

@@ -0,0 +1,26 @@
+import type { HostBridge } from './host-bridge.js';
+import type { StandaloneWallet } from './standalone-wallet.js';
+/**
+ * A resolved signing identity plus its raw-bytes signer. Shared by both the
+ * vault client (cubby reads / connect / publish) and the audio uploader.
+ */
+export interface ResolvedSigningIdentity {
+    source: 'host' | 'wallet';
+    publicKey: string;
+    sigType: 'ed25519' | 'sr25519';
+    sign: (bytes: Uint8Array) => Promise<Uint8Array>;
+}
+/**
+ * The widget is framed by a host, but the host never supplied an identity —
+ * it did not answer the handshake within ~8 s, or answered malformed.
+ */
+export declare class WidgetSignedOutError extends Error {
+    constructor(message?: string);
+}
+export interface IdentityResolverDeps {
+    bridge: HostBridge;
+    /** Opens the interactive wallet. Only ever called when NOT framed. */
+    connectWallet: () => Promise<StandaloneWallet>;
+}
+/** Build the memoized identity resolver. A failure clears the memo so a later action can retry. */
+export declare function createIdentityResolver(deps: IdentityResolverDeps): () => Promise<ResolvedSigningIdentity>;

package/dist/resolve-identity.js

@@ -0,0 +1,58 @@
+// packages/widget-runtime/src/resolve-identity.ts
+//
+// Multi-source identity resolution for the widget runtime, memoized so the
+// (possibly interactive) resolution runs at most once per session.
+//
+//   Framed  → the embedding host answers the postMessage handshake.
+//   Top-level → connect an interactive wallet (standalone / direct-link boot).
+//
+// A FRAMED widget whose handshake fails does NOT fall through to the
+// standalone wallet: the host meant to supply the identity and didn't, so we
+// surface WidgetSignedOutError instead of silently opening a second, different
+// wallet the host knows nothing about.
+/**
+ * The widget is framed by a host, but the host never supplied an identity —
+ * it did not answer the handshake within ~8 s, or answered malformed.
+ */
+export class WidgetSignedOutError extends Error {
+    constructor(message = 'WidgetSignedOutError: the embedding host did not supply an identity ' +
+        '(no cef-widget:identity-response within 8s, or a malformed one). ' +
+        'Mount createWidgetHost() on the host page.') {
+        super(message);
+        this.name = 'WidgetSignedOutError';
+    }
+}
+/** Build the memoized identity resolver. A failure clears the memo so a later action can retry. */
+export function createIdentityResolver(deps) {
+    let identityP = null;
+    return function resolveSigningIdentity() {
+        if (identityP)
+            return identityP;
+        identityP = (async () => {
+            const hostId = await deps.bridge.requestIdentity();
+            if (hostId) {
+                return {
+                    source: 'host',
+                    publicKey: hostId.pubkey,
+                    sigType: hostId.sigType,
+                    sign: (bytes) => deps.bridge.sign(bytes),
+                };
+            }
+            // Framed but unanswered: the host owns the identity. Do not downgrade.
+            if (window.parent !== window)
+                throw new WidgetSignedOutError();
+            // Top-level boot → interactive wallet.
+            const wallet = await deps.connectWallet();
+            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;
+    };
+}

package/dist/widget-host.d.ts

@@ -0,0 +1,62 @@
+import { type SigType } from './host-bridge.js';
+export interface WidgetHostIdentity {
+    /** 0x-hex public key of the already-authenticated user. */
+    pubkey: string;
+    /** Defaults to 'ed25519'. */
+    sigType?: SigType;
+}
+export interface WidgetHostOptions {
+    /**
+     * REQUIRED, non-empty. The origins this host answers — the only gate that
+     * pins WHICH DOCUMENT is talking to you.
+     *
+     * Each entry must be a canonical origin exactly as `event.origin` spells 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. A sandboxed
+     * widget's `event.origin` is the literal string `"null"`, so pass `'null'`
+     * to frame one. `'*'` is NOT accepted — it is a `postMessage` targetOrigin
+     * wildcard, never an `event.origin`, so it would match nothing.
+     */
+    allowedOrigins: string[];
+    /**
+     * Optional, recommended: narrow further to ONE frame — the `<iframe>`
+     * element or its `contentWindow`. When given, a message must pass BOTH this
+     * and `allowedOrigins`.
+     *
+     * It cannot replace `allowedOrigins`. A `WindowProxy` keeps its identity
+     * across navigation, cross-origin included, so `event.source ===
+     * iframe.contentWindow` still holds after the framed page follows an open
+     * redirect or navigates itself — the handle names the SLOT, not the document
+     * in it.
+     */
+    widget?: HTMLIFrameElement | Window;
+    /**
+     * The identity to hand the widget. Return null/undefined when the host has
+     * no signed-in user yet — the widget retries for ~8 s before giving up.
+     */
+    getIdentity: () => WidgetHostIdentity | null | undefined | Promise<WidgetHostIdentity | null | undefined>;
+    /**
+     * Sign `bytes` VERBATIM — `ed25519_signRaw`, never the high-level
+     * `signMessage` / `wallet_signMessage`, which wrap the payload in Substrate's
+     * `<Bytes>…</Bytes>` envelope; a signature over the wrapped form verifies
+     * nowhere. Return null when the user declines; throw to report a failure.
+     *
+     * Your signer only ever sees a Uint8Array — this module converts to and from
+     * the `number[]` wire form.
+     */
+    sign: (bytes: Uint8Array) => Promise<Uint8Array | null> | Uint8Array | null;
+}
+/**
+ * Attach the widget-host message listener to `window`.
+ *
+ * Returns a disposer that removes it (call it on unmount — a leaked listener
+ * keeps answering identity requests from whatever the iframe navigated to).
+ *
+ * Throws unless `allowedOrigins` is non-empty and every entry is a canonical
+ * origin: an ungated host is a signing oracle for every frame on the page, and
+ * an entry that can never match is the same thing with a false sense of
+ * safety.
+ */
+export declare function createWidgetHost(opts: WidgetHostOptions): () => void;

package/dist/widget-host.js

@@ -0,0 +1,153 @@
+// packages/widget-runtime/src/widget-host.ts
+//
+// Host side of the widget↔host contract: the few lines a page that frames a
+// CEF widget needs in order to hand the widget an identity it has ALREADY
+// authenticated (an extension panel with SCP Wallet, a partner app, the Cere
+// Vault). Mount it once; it answers `cef-widget:identity-request` and routes
+// `cef-widget:sign-request` to your signer.
+//
+// This module holds the user's signing key, so it is the trust boundary: it
+// answers ONLY the origins you name (optionally narrowed to one frame), and
+// validates every byte it is asked to sign. The full contract is in the
+// package README.
+import { IDENTITY_REQUEST_TYPE, IDENTITY_RESPONSE_TYPE, SIGN_REQUEST_TYPE, SIGN_RESPONSE_TYPE, PROTOCOL_VERSION, UNSUPPORTED_VERSION_CODE, MAX_SIGN_BYTES, WidgetProtocolVersionError, WidgetMalformedMessageError, isUnsupportedVersion, isByteArray, } from './host-bridge.js';
+/** Type guard for the postMessage call below — NOT the identity check; that is
+ * `allowedOrigins`. A Window is self-referential; a MessagePort or
+ * ServiceWorker is not (and its postMessage would throw on our string
+ * targetOrigin). `event.source` is browser-set and cannot be forged. */
+function isWindow(source) {
+    return (!!source &&
+        typeof source.postMessage === 'function' &&
+        source.window === source);
+}
+/** Read lazily: an iframe's contentWindow is null before it is attached, and
+ * changes across navigations. */
+function widgetWindow(widget) {
+    return 'contentWindow' in widget ? widget.contentWindow : widget;
+}
+/** `event.origin` is a canonical serialized origin — or the literal "null" for
+ * a sandboxed/opaque one. Anything that does not round-trip through URL exactly
+ * can never equal an event.origin, so it is a mount-time mistake, not a
+ * runtime miss. */
+function assertCanonicalOrigin(entry) {
+    const shown = typeof entry === 'string' ? `'${entry}'` : String(entry);
+    const reject = (why) => {
+        throw new Error(`createWidgetHost: allowedOrigins entry ${shown} ${why}`);
+    };
+    if (typeof entry !== 'string' || !entry)
+        reject('is not a string origin');
+    if (entry === '*') {
+        reject('is a wildcard. postMessage accepts `*` as a targetOrigin, but `event.origin` is ' +
+            'never the string "*", so this would mount clean and then answer nobody. List the ' +
+            "origins you actually frame, or 'null' for a sandboxed widget.");
+    }
+    // 'null' is what a sandboxed / opaque origin reports; URL cannot parse it.
+    if (entry === 'null')
+        return;
+    let origin;
+    try {
+        origin = new URL(entry).origin;
+    }
+    catch {
+        return reject('is not a URL. Use scheme + host + optional port, e.g. https://widget.example');
+    }
+    if (origin !== entry) {
+        reject(`is not a canonical origin — event.origin would read '${origin}'. Drop any trailing ` +
+            'slash, path, upper-case in the host, or default port — an origin omits :443 on https ' +
+            'and :80 on http.');
+    }
+}
+/**
+ * Attach the widget-host message listener to `window`.
+ *
+ * Returns a disposer that removes it (call it on unmount — a leaked listener
+ * keeps answering identity requests from whatever the iframe navigated to).
+ *
+ * Throws unless `allowedOrigins` is non-empty and every entry is a canonical
+ * origin: an ungated host is a signing oracle for every frame on the page, and
+ * an entry that can never match is the same thing with a false sense of
+ * safety.
+ */
+export function createWidgetHost(opts) {
+    if (!opts.allowedOrigins?.length) {
+        throw new Error('createWidgetHost: `allowedOrigins` is required and must be non-empty. An ungated host ' +
+            'signs arbitrary bytes for any frame on the page. `widget` alone is NOT sufficient: a ' +
+            'WindowProxy keeps its identity across navigation (cross-origin included), so the frame ' +
+            'handle still matches after the widget page navigates or follows an open redirect — it ' +
+            "names the slot, not the document. Pass 'null' for a sandboxed widget.");
+    }
+    opts.allowedOrigins.forEach(assertCanonicalOrigin);
+    const origins = new Set(opts.allowedOrigins);
+    const onMessage = (event) => {
+        // ── Trust boundary: who is allowed to ask us to sign ─────────────────────
+        // Origin first and always: it is the only check that pins the document.
+        if (!origins.has(event.origin))
+            return;
+        const source = event.source;
+        if (!isWindow(source))
+            return;
+        // Optional extra narrowing to one frame; never a substitute for the above.
+        if (opts.widget && source !== widgetWindow(opts.widget))
+            return;
+        const data = event.data;
+        if (!data || typeof data !== 'object')
+            return;
+        const { type, requestId, v } = data;
+        if (typeof requestId !== 'string')
+            return;
+        if (type !== IDENTITY_REQUEST_TYPE && type !== SIGN_REQUEST_TYPE)
+            return;
+        const responseType = type === IDENTITY_REQUEST_TYPE ? IDENTITY_RESPONSE_TYPE : SIGN_RESPONSE_TYPE;
+        // Reply to the exact frame that asked, on its own origin. A sandboxed
+        // widget has origin "null", which is not a valid targetOrigin — only then
+        // fall back to '*'.
+        const target = event.origin && event.origin !== 'null' ? event.origin : '*';
+        const reply = (fields) => {
+            // A frame can be torn down between its request and our reply; a throw
+            // here would escape the listener (fail() runs outside the try below).
+            try {
+                source.postMessage({ type: responseType, requestId, v: PROTOCOL_VERSION, ...fields }, target);
+            }
+            catch { /* frame gone — nothing to report to */ }
+        };
+        // Sign failures carry `signature: null` alongside the error so the widget
+        // sees a well-formed SignResponse either way.
+        const fail = (message, extra) => reply(type === SIGN_REQUEST_TYPE
+            ? { signature: null, error: message, ...extra }
+            : { error: message, ...extra });
+        if (isUnsupportedVersion(v)) {
+            // errorCode, not `v`: this reply IS a v1 message, so echoing the bad
+            // version would lie. Without the code the widget sees a plain error
+            // string and retries to its deadline.
+            fail(new WidgetProtocolVersionError(`the widget requested protocol v${String(v)}; this host speaks v${PROTOCOL_VERSION}`).message, { errorCode: UNSUPPORTED_VERSION_CODE });
+            return;
+        }
+        void (async () => {
+            try {
+                if (type === IDENTITY_REQUEST_TYPE) {
+                    const id = await opts.getIdentity();
+                    if (!id?.pubkey) {
+                        fail('host has no signed-in identity');
+                        return;
+                    }
+                    reply({ pubkey: id.pubkey, sigType: id.sigType ?? 'ed25519' });
+                    return;
+                }
+                const bytes = data.bytes;
+                if (!isByteArray(bytes)) {
+                    // Uint8Array.from would coerce silently — 300 → 44, 'zz' → 0 — and
+                    // hand the signer a payload the widget never sent.
+                    fail(new WidgetMalformedMessageError(`sign-request.bytes must be an array of at most ${MAX_SIGN_BYTES} integers 0-255`).message);
+                    return;
+                }
+                const signature = await opts.sign(Uint8Array.from(bytes));
+                reply({ signature: signature ? Array.from(signature) : null });
+            }
+            catch (err) {
+                fail(err instanceof Error ? err.message : String(err));
+            }
+        })();
+    };
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+}