@cef-ai/wallet 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -41,6 +41,8 @@ type HostToPopup = {
     appContext: AppContext;
     intent: 'register' | 'login';
     label?: string;
+    name?: string;
+    email?: string;
 } | {
     type: 'wallet:requestDelegation';
     id: string;
@@ -90,6 +92,12 @@ type PopupToHost = {
     code: WalletErrorCode;
     message: string;
     traceId?: string;
+} | {
+    type: 'wallet:ui:show';
+    id: string;
+} | {
+    type: 'wallet:ui:hide';
+    id: string;
 };
 /** Spec §5.5. Channel name: `scp-wallet-v2`. Wallet-origin tabs only. */
 type BroadcastChannelMessage = {
@@ -104,6 +112,8 @@ type BroadcastChannelMessage = {
     /** absolute Unix epoch ms when session keys expire */ expMs: number;
 } | {
     type: 'logout';
+} | {
+    type: 'session-available';
 };
 declare const BROADCAST_CHANNEL_NAME = "scp-wallet-v2";
 
@@ -136,54 +146,20 @@ type PopupMessageHandler<T extends HostToPopup = HostToPopup> = (message: T, met
     origin: string;
 }) => Promise<void> | void;
 
-interface PopupTransportOptions {
-    /** Expected origin of the wallet popup, e.g. 'https://wallet.example.com'. */
-    walletOrigin: string;
-    /** Defaults to `(url, features) => window.open(url, '_blank', features)`. */
-    openPopup?: PopupOpener;
-    /** Window object hosting the event listener. Defaults to `globalThis.window`. */
-    hostWindow?: Window;
-    /** Default per-request timeout. Defaults to 60_000 ms. */
-    defaultTimeoutMs?: number;
-}
 /**
- * Host-side popup transport. Spec §5.
- *
- * Use one `PopupTransport` instance per `EmbedWallet`. The instance owns a
- * single popup window at a time, opens it on demand, auto-reopens on the next
- * `request()` after it's been closed, and correlates each in-flight request
- * by its message `id`.
- *
- * Wire handshake: every freshly opened popup must send `wallet:ready` before
- * this transport will post any `HostToPopup` envelope. Without the handshake,
- * `postMessage` may fire before the popup document has executed its `message`
- * listener and the message is dropped. Outbound messages are queued in
- * `outbox` while `popupReady === false`; `wallet:ready` flushes them.
+ * Host-side transport contract used by `EmbedWallet`. Both `PopupTransport`
+ * (separate window) and `IframeTransport` (in-page cross-origin iframe)
+ * implement it — `EmbedWallet` depends only on this, never on a concrete
+ * transport's popup/iframe mechanics.
  */
-declare class PopupTransport {
-    private readonly opts;
-    private popup;
-    private pending;
-    private listener;
-    private popupReady;
-    private outbox;
-    constructor(options: PopupTransportOptions);
+interface WalletTransport {
     request<T extends PopupToHost>(message: HostToPopup, expectedTypes: T['type'][], init?: {
         timeoutMs?: number;
     }): Promise<T>;
-    /** Close the popup if open. Pending requests will time out normally. */
+    /** Tear down the visible surface (popup window / iframe element); keep the instance reusable. */
     close(): void;
-    /**
-     * Tear down the transport entirely. Closes the popup AND removes the host-
-     * window message listener. After `destroy()`, the transport instance cannot
-     * be reused — callers should drop the reference.
-     *
-     * Use `close()` if you only want to close the popup but keep the transport
-     * alive for a later re-open.
-     */
+    /** Tear down entirely (surface + host-window listener); instance not reusable after. */
     destroy(): void;
-    private ensureListening;
-    private onMessage;
 }
 
 interface EmbedWalletOptions {
@@ -202,12 +178,21 @@ interface EmbedWalletOptions {
     };
     /** Optional name for the appContext sent via wallet:hello. Defaults to ''. */
     appName?: string;
+    /** Transport surface. 'iframe' (default) embeds the wallet inline; 'popup' opens a window. */
+    transport?: 'iframe' | 'popup';
     /**
      * Test seam. Injects an alternative `PopupTransport` instance. Production
      * callers leave this undefined and the SDK constructs its own transport.
      */
     __internal__?: {
-        transport?: PopupTransport;
+        transport?: WalletTransport;
+        /**
+         * Test seam. Injects the `openPopup` used by the transient `PopupTransport`
+         * that `register()` opens when the main transport is not already a popup
+         * (see `EmbedWallet.register`). Production callers leave this undefined and
+         * the transient popup uses the real `window.open` default.
+         */
+        registerPopupOpener?: PopupOpener;
     };
 }
 
@@ -285,12 +270,23 @@ declare class EmbedWallet {
     private _credentialId;
     private _listeners;
     private readonly transport;
+    private readonly regPopupOpener?;
     constructor(opts: EmbedWalletOptions);
     get isLoggedIn(): boolean;
     get addresses(): Addresses | null;
     get credentialId(): string | null;
+    /**
+     * Safari blocks WebAuthn `create()` in cross-origin iframes, so `register()`
+     * always runs its `wallet:hello` ceremony over a `PopupTransport` — even
+     * when the configured transport is the iframe. When the main transport is
+     * already a `PopupTransport` it's reused; otherwise a transient one is
+     * opened synchronously (within the caller's click) and closed afterward.
+     * `login()` and all other ops use the configured transport unchanged.
+     */
     register(opts?: {
         label?: string;
+        name?: string;
+        email?: string;
     }): Promise<LoginResult>;
     login(): Promise<LoginResult>;
     logout(): Promise<void>;
@@ -348,11 +344,106 @@ declare const ALLOWED_ORIGIN_SCHEMES: readonly string[];
  */
 declare function isMatchingOrigin(a: string | undefined, b: string | undefined): boolean;
 
+interface PopupTransportOptions {
+    /** Expected origin of the wallet popup, e.g. 'https://wallet.example.com'. */
+    walletOrigin: string;
+    /** Defaults to `(url, features) => window.open(url, '_blank', features)`. */
+    openPopup?: PopupOpener;
+    /** Window object hosting the event listener. Defaults to `globalThis.window`. */
+    hostWindow?: Window;
+    /** Default per-request timeout. Defaults to 60_000 ms. */
+    defaultTimeoutMs?: number;
+}
+/**
+ * Host-side popup transport. Spec §5.
+ *
+ * Use one `PopupTransport` instance per `EmbedWallet`. The instance owns a
+ * single popup window at a time, opens it on demand, auto-reopens on the next
+ * `request()` after it's been closed, and correlates each in-flight request
+ * by its message `id`.
+ *
+ * Wire handshake: every freshly opened popup must send `wallet:ready` before
+ * this transport will post any `HostToPopup` envelope. Without the handshake,
+ * `postMessage` may fire before the popup document has executed its `message`
+ * listener and the message is dropped. Outbound messages are queued in
+ * `outbox` while `popupReady === false`; `wallet:ready` flushes them.
+ */
+declare class PopupTransport implements WalletTransport {
+    private readonly opts;
+    private popup;
+    private pending;
+    private listener;
+    private popupReady;
+    private outbox;
+    constructor(options: PopupTransportOptions);
+    request<T extends PopupToHost>(message: HostToPopup, expectedTypes: T['type'][], init?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    /**
+     * Close the popup if open. Immediately rejects any in-flight `request()`
+     * calls (mirrors `IframeTransport.close()`) rather than leaving them to
+     * time out — a caller that closes the popup mid-request (e.g.
+     * `EmbedWallet.register()`'s `finally` block) gets a prompt rejection
+     * instead of waiting out the full default 60s timeout.
+     */
+    close(): void;
+    /**
+     * Tear down the transport entirely. Closes the popup AND removes the host-
+     * window message listener. After `destroy()`, the transport instance cannot
+     * be reused — callers should drop the reference.
+     *
+     * Use `close()` if you only want to close the popup but keep the transport
+     * alive for a later re-open.
+     */
+    destroy(): void;
+    /** Reject every in-flight request with a `WalletError('internal', reason)`. Idempotent. */
+    private rejectAllPending;
+    private ensureListening;
+    private onMessage;
+}
+
+interface IframeTransportOptions {
+    walletOrigin: string;
+    hostWindow?: Window;
+    document?: Document;
+    defaultTimeoutMs?: number;
+    /** Test seam: build the iframe element (happy-dom's contentWindow is null). */
+    mountIframe?: (url: string, allow: string) => HTMLIFrameElement;
+    /** Test seam: observe overlay visibility transitions without relying on real DOM layout. */
+    onOverlay?: (visible: boolean) => void;
+}
+declare class IframeTransport implements WalletTransport {
+    private readonly opts;
+    private iframe;
+    private pending;
+    private listener;
+    private ready;
+    private outbox;
+    private backdrop;
+    private hiddenCssText;
+    private overlayVisible;
+    constructor(options: IframeTransportOptions);
+    private ensureIframe;
+    private showOverlay;
+    private hideOverlay;
+    private ensureListening;
+    request<T extends PopupToHost>(message: HostToPopup, expectedTypes: T['type'][], init?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    private postToIframe;
+    close(): void;
+    destroy(): void;
+    private rejectAllPending;
+    private onMessage;
+}
+
 interface PopupHostBridgeOptions {
     /** Expected origin of the host page (the page that opened this popup). */
     hostOrigin: string;
     /** The window this bridge runs in. Defaults to `globalThis`. */
     popupWindow?: Window;
+    /** Which window to post PopupToHost messages to. 'opener' (popup, default) or 'parent' (iframe). */
+    replyTo?: 'opener' | 'parent';
 }
 /**
  * Popup-side bridge. Spec §5.
@@ -375,9 +466,9 @@ declare class PopupHostBridge {
         type: T;
     }>>): this;
     /**
-     * Send a `PopupToHost` message back to the opener. The bridge does not
-     * remember the host-window reference itself — it reads `globalThis.opener`
-     * each call, so it survives popup re-opens.
+     * Send a `PopupToHost` message back to the opener or parent, depending on
+     * `replyTo`. The bridge does not remember the host-window reference itself —
+     * it reads the target window each call, so it survives popup re-opens.
      */
     send(message: PopupToHost): void;
     /**
@@ -410,18 +501,36 @@ interface BroadcastSessionShareOptions {
      */
     getSession: () => BroadcastSession | null;
     /**
-     * Called when another tab broadcasts a `logout` message. The local handler
-     * should wipe its own session.
+     * Called when another tab broadcasts `session-available` (a keyless,
+     * fire-and-forget "a session just got established" push — see
+     * `announce()`). Session-less listeners should react by issuing a fresh
+     * `request()`; this callback never receives key material itself.
      */
-    onLogout?: () => void;
+    onAvailable?: () => void;
 }
 /**
  * Popup-side cross-tab session sharing. Spec §5.5.
  *
  * - `request()`: broadcast `request-session`, wait up to 200ms for an offer.
  * - `start()`: listen for incoming requests; reply with `offer-session` if we
- *   have a non-expired session and `getSession()` returns it.
- * - `broadcastLogout()`: notify peers to wipe their sessions too.
+ *   have a non-expired session and `getSession()` returns it. Also listens
+ *   for `session-available` pushes (see `announce()`) and invokes
+ *   `onAvailable` so a session-less peer can react without polling.
+ * - `broadcastLogout()`: notify peers to wipe their sessions too. NOTE: no
+ *   `BroadcastSessionShare` call site wires a receive-side handler for this
+ *   today — cross-tab logout is owned exclusively by `IdentityImpl` via its
+ *   own `CrossTabSync` (`packages/identity/src/CrossTabSync.ts`), which
+ *   shares this same channel name/message shape by convention. This method
+ *   (and the `'logout'` message type) stays for public-API compatibility
+ *   (`@cef-ai/wallet` is published) but intentionally has no paired
+ *   `onLogout` option — wiring one would double-handle logout alongside
+ *   `CrossTabSync`. See `ARCHITECTURE.md` Key invariants.
+ * - `announce()`: notify peers that THIS tab just established a session, so a
+ *   session-less peer can immediately issue its own `request()` rather than
+ *   waiting on a one-shot timer that may have already elapsed. Carries no key
+ *   material — only `request()`/`offer-session` ever move keys, and only in
+ *   direct response to an explicit request. This keeps the push trigger and
+ *   the key transfer on two separate, independently-gated messages.
  *
  * Channel name is the spec-locked `scp-wallet-v2`. Only wallet-origin popups
  * join. Host pages do not participate.
@@ -439,14 +548,32 @@ declare class BroadcastSessionShare {
     request(opts?: {
         timeoutMs?: number;
     }): Promise<BroadcastSession | null>;
-    /** Begin offering this tab's session in response to requests, and handle logouts. */
+    /**
+     * Begin offering this tab's session in response to requests, and invoke
+     * `onAvailable` on incoming `session-available` pushes. Callers that only
+     * care about `onAvailable` (no session to offer) still call `start()` —
+     * `getSession()` returning `null` simply means `request-session` replies
+     * are skipped.
+     */
     start(): void;
     stop(): void;
-    /** Notify peers that the user logged out. Peers wipe their sessions. */
+    /**
+     * Notify peers that the user logged out. Kept for public-API compatibility;
+     * no `BroadcastSessionShare` instance currently handles the receive side
+     * (see class doc) — cross-tab logout is `CrossTabSync`'s responsibility.
+     */
     broadcastLogout(): void;
+    /**
+     * Notify peers that this tab just established a session (register/login
+     * completed). Carries NO key material — it is purely a push trigger that
+     * tells session-less peers to issue their own `request()`. Key material
+     * still only ever moves as an `offer-session` reply to an explicit
+     * `request-session`; `announce()` does not bypass that gate.
+     */
+    announce(): void;
     /** Free the underlying channel handle. Call from unload handlers. */
     close(): void;
     private onMessage;
 }
 
-export { ALLOWED_ORIGIN_SCHEMES, type AppContext, type ApplicationBody, type ApplicationFilter, type ApplicationRecord, BROADCAST_CHANNEL_NAME, type BroadcastChannelMessage, type BroadcastSession, BroadcastSessionShare, type BroadcastSessionShareOptions, type CefSigner, type DelegationRequest, type DelegationResult, type DelegationScope, EmbedWallet, type EmbedWalletOptions, type HostMessageListener, type HostToPopup, type LoginResult, type PopupHandle, PopupHostBridge, type PopupHostBridgeOptions, type PopupMessageHandler, type PopupOpener, type PopupToHost, PopupTransport, type PopupTransportOptions, type SignIntent, type SignerSpec, type SignerType, type WalletEvent, type WalletEventListener, isMatchingOrigin };
+export { ALLOWED_ORIGIN_SCHEMES, type AppContext, type ApplicationBody, type ApplicationFilter, type ApplicationRecord, BROADCAST_CHANNEL_NAME, type BroadcastChannelMessage, type BroadcastSession, BroadcastSessionShare, type BroadcastSessionShareOptions, type CefSigner, type DelegationRequest, type DelegationResult, type DelegationScope, EmbedWallet, type EmbedWalletOptions, type HostMessageListener, type HostToPopup, IframeTransport, type IframeTransportOptions, type LoginResult, type PopupHandle, PopupHostBridge, type PopupHostBridgeOptions, type PopupMessageHandler, type PopupOpener, type PopupToHost, PopupTransport, type PopupTransportOptions, type SignIntent, type SignerSpec, type SignerType, type WalletEvent, type WalletEventListener, type WalletTransport, isMatchingOrigin };