@cef-ai/wallet 1.0.0 → 1.1.0

package/README.md

@@ -57,17 +57,112 @@ const sig = await signer.signMessage(new TextEncoder().encode('Hello'));
 console.log('Signature bytes:', sig);
 ```
 
+## Transport: iframe (default) vs popup
+
+```ts
+new EmbedWallet({ appId, walletOrigin, transport: 'iframe' | 'popup' });
+```
+
+`transport` defaults to `'iframe'`. This controls how the SDK talks to the
+wallet UI at `${walletOrigin}/embed/wallet`:
+
+- **`'iframe'` (default, `IframeTransport`).** The SDK injects a hidden,
+  zero-size `<iframe>` pinned to `walletOrigin` on first use. It stays
+  invisible until the wallet needs to show UI (a consent prompt or the
+  login "Continue" gesture — see below), at which point it grows into a
+  centered modal with a backdrop, then shrinks back to hidden. No
+  popup-blocker exposure, no separate window for the user to lose track of.
+- **`'popup'` (`PopupTransport`, the original transport).** Opens
+  `${walletOrigin}/embed/wallet` in a real popup window via `window.open`.
+  Still fully supported — pass `transport: 'popup'` to opt back into it (e.g.
+  if your host page can't grant the iframe permission below, or you prefer
+  the popup UX).
+
+Both implement the same `WalletTransport` interface, so `EmbedWallet`'s
+public methods behave identically regardless of which one is active.
+
+### `allow` / `Permissions-Policy` requirement (iframe transport only)
+
+The injected iframe is created with:
+
+```html
+<iframe
+  src="https://wallet.example.com/embed/wallet?origin=..."
+  allow="publickey-credentials-get https://wallet.example.com"
+/>
+```
+
+This delegates the WebAuthn **`get()`** (i.e. `login()`) ceremony into the
+cross-origin iframe. Two things follow for host apps:
+
+1. If your page sends a restrictive `Permissions-Policy` HTTP response
+   header, it must explicitly allow `publickey-credentials-get` for your
+   wallet origin (e.g. `Permissions-Policy: publickey-credentials-get=(self "https://wallet.example.com")`),
+   or the browser will block WebAuthn `get()` inside the iframe regardless of
+   the `allow` attribute. Pages with no `Permissions-Policy` header (the
+   common case) need no action — the `allow` attribute alone is sufficient.
+2. **Only `-get` is delegated, not `-create`.** Safari blocks WebAuthn
+   `create()` (passkey registration) in cross-origin iframes outright, so
+   `create` is deliberately not requested in `allow`. See "Register uses a
+   synchronous popup" below.
+
+### Register uses a synchronous popup
+
+`EmbedWallet.register()` always performs its WebAuthn ceremony over a
+`PopupTransport`, even when the SDK is configured with the (default) iframe
+transport:
+
+- If the configured transport is already `PopupTransport` (`transport: 'popup'`),
+  `register()` reuses it directly.
+- Otherwise (iframe transport), `register()` opens a **transient popup
+  synchronously** — inside the same call stack as the consumer's click
+  handler — performs the `wallet:hello` (`intent: 'register'`) ceremony over
+  it, and closes it when done. "Synchronous" matters: Safari requires
+  `window.open` to happen within a real user-activation event, so `register()`
+  cannot defer opening the popup until after an `await`.
+- `login()` and every other method (`getSigner`, `asSigner`,
+  `requestDelegation`, `saveApplication`, `findApplications`, `logout`) always
+  use the configured transport (iframe by default) unchanged — only
+  `register()` special-cases the popup punch-out.
+- After the register popup completes, the persistent iframe adopts the new
+  session automatically via a same-origin `BroadcastChannel('scp-wallet-v2')`
+  handoff (`BroadcastSessionShare`) — no explicit `login()` call is needed
+  after `register()` resolves.
+
 ## Architecture
 
-- A popup-window-based transport (`PopupTransport`) opens `wallet.example.com/embed/wallet?origin=...`
-- The popup runs the wallet UI, performs the WebAuthn ceremony, and posts results back
-- Cross-tab session sharing via `BroadcastChannel('scp-wallet-v2')` so a second host tab discovers an existing session
+- Default transport (`IframeTransport`) injects a hidden, permission-scoped
+  iframe at `wallet.example.com/embed/wallet?origin=...` and shows/hides a
+  modal overlay on request from the wallet document (see "Transport" above).
+- Opt-in transport (`PopupTransport`) opens `wallet.example.com/embed/wallet?origin=...`
+  in a separate popup window instead.
+- Either way, the wallet surface runs the WebAuthn ceremony, signing, and
+  consent UI, and posts id-correlated results back over `postMessage`.
+- Cross-tab session sharing via `BroadcastChannel('scp-wallet-v2')` so a second
+  host tab (or the register popup handing off to the iframe) discovers an
+  existing session.
 
 Design specs and ADRs are maintained in the company memory bank.
 
+## Public exports
+
+- `EmbedWallet` — the SDK class (see Quick start).
+- `WalletTransport` (type) — the transport interface both transports
+  implement; only relevant if you're injecting a custom transport via the
+  `__internal__` test seam.
+- `PopupTransport` / `PopupTransportOptions` — the popup-window transport.
+- `IframeTransport` / `IframeTransportOptions` — the default iframe transport.
+  Options: `walletOrigin`, `hostWindow?`, `document?`, `defaultTimeoutMs?`,
+  plus two test seams (`mountIframe?`, `onOverlay?`) not needed in production
+  use.
+- `PopupHostBridge` / `PopupHostBridgeOptions`, `BroadcastSessionShare` /
+  `BroadcastSessionShareOptions` / `BroadcastSession` — wallet-side building
+  blocks (used by the wallet SPA itself, exported for advanced/embedding
+  scenarios); most host-app integrations never need these directly.
+
 ## Capabilities
 
-- `register({ label? })` / `login()` — opens the popup, performs the WebAuthn ceremony, returns the session
+- `register({ name?, email?, label? })` / `login()` — opens the configured transport surface (iframe by default; `register()` always punches out to a popup — see "Register uses a synchronous popup"), performs the WebAuthn ceremony, returns the session. `name` → the passkey's `user.displayName`, `email` → `user.name` (what OS/browser passkey managers show); `label` is a legacy single-field fallback for both.
 - `getSigner({ chain })` — returns an `EthersSigner` (`'evm'`), `PolkadotSigner` (`'cere'`), or `SolanaSigner` (`'solana'`); each exposes `signMessage(bytes: Uint8Array): Promise<Uint8Array>`
 - `requestDelegation({ capabilities, ttl, appId?, agentPubkey?, constraints? })` — requests a scoped delegation token; the popup shows a consent UI
 - `saveApplication(record)` / `findApplications(filter)` — manage app context records

package/dist/index.cjs

@@ -107,8 +107,15 @@ var PopupTransport = class {
       });
     });
   }
-  /** Close the popup if open. Pending requests will time out normally. */
+  /**
+   * 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() {
+    this.rejectAllPending("transport closed");
     if (this.popup && !this.popup.closed) {
       this.popup.close();
     }
@@ -132,6 +139,14 @@ var PopupTransport = class {
     }
   }
   // ---- internal -------------------------------------------------------------
+  /** Reject every in-flight request with a `WalletError('internal', reason)`. Idempotent. */
+  rejectAllPending(reason) {
+    for (const [id, pending] of this.pending) {
+      clearTimeout(pending.timer);
+      this.pending.delete(id);
+      pending.reject(new walletApiClient.WalletError("internal", reason));
+    }
+  }
   ensureListening() {
     if (this.listener) return;
     this.listener = (event) => this.onMessage(event);
@@ -189,6 +204,173 @@ function defaultOpener(url, features) {
   const opened = w == null ? void 0 : w.open(url, "_blank", features);
   return opened;
 }
+var IframeTransport = class {
+  constructor(options) {
+    this.iframe = null;
+    this.pending = /* @__PURE__ */ new Map();
+    this.listener = null;
+    this.ready = false;
+    this.outbox = [];
+    this.backdrop = null;
+    this.hiddenCssText = "";
+    this.overlayVisible = false;
+    this.opts = __spreadValues({
+      hostWindow: globalThis.window,
+      document: globalThis.document,
+      defaultTimeoutMs: 6e4,
+      mountIframe: options.mountIframe,
+      onOverlay: options.onOverlay
+    }, options);
+  }
+  ensureIframe() {
+    var _a, _b, _c;
+    if (this.iframe) return;
+    const hostOrigin = (_b = (_a = globalThis.location) == null ? void 0 : _a.origin) != null ? _b : "";
+    const url = `${this.opts.walletOrigin}/embed/wallet?origin=${encodeURIComponent(hostOrigin)}`;
+    const allow = `publickey-credentials-get ${this.opts.walletOrigin}`;
+    if (this.opts.mountIframe) {
+      this.iframe = this.opts.mountIframe(url, allow);
+    } else {
+      const el = this.opts.document.createElement("iframe");
+      el.src = url;
+      el.setAttribute("allow", allow);
+      el.style.cssText = "position:fixed;border:0;width:0;height:0;left:-9999px;";
+      this.opts.document.body.appendChild(el);
+      this.iframe = el;
+    }
+    this.hiddenCssText = (_c = this.iframe.style.cssText) != null ? _c : "";
+    this.ready = false;
+    this.outbox = [];
+    this.overlayVisible = false;
+    this.ensureListening();
+  }
+  showOverlay() {
+    var _a, _b;
+    if (this.overlayVisible) return;
+    this.overlayVisible = true;
+    if (this.iframe) {
+      const backdrop = this.opts.document.createElement("div");
+      backdrop.setAttribute("data-wallet-overlay-backdrop", "");
+      backdrop.style.cssText = "position:fixed;inset:0;background:rgba(0,0,0,.4);z-index:2147483646;";
+      this.opts.document.body.appendChild(backdrop);
+      this.backdrop = backdrop;
+      this.iframe.style.cssText = "position:fixed;border:0;z-index:2147483647;width:min(420px,100vw);height:min(640px,100vh);left:50%;top:50%;transform:translate(-50%,-50%);";
+    }
+    (_b = (_a = this.opts).onOverlay) == null ? void 0 : _b.call(_a, true);
+  }
+  hideOverlay() {
+    var _a, _b, _c;
+    if (!this.overlayVisible) return;
+    this.overlayVisible = false;
+    (_a = this.backdrop) == null ? void 0 : _a.remove();
+    this.backdrop = null;
+    if (this.iframe) {
+      this.iframe.style.cssText = this.hiddenCssText;
+    }
+    (_c = (_b = this.opts).onOverlay) == null ? void 0 : _c.call(_b, false);
+  }
+  ensureListening() {
+    if (this.listener) return;
+    this.listener = (e) => this.onMessage(e);
+    this.opts.hostWindow.addEventListener("message", this.listener);
+  }
+  request(_0, _1) {
+    return __async(this, arguments, function* (message, expectedTypes, init = {}) {
+      var _a;
+      this.ensureIframe();
+      const id = message.id;
+      const timeoutMs = (_a = init.timeoutMs) != null ? _a : this.opts.defaultTimeoutMs;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          if (this.pending.has(id)) {
+            this.pending.delete(id);
+            this.outbox = this.outbox.filter((m) => m.id !== id);
+            reject(new walletApiClient.WalletError("internal", `request "${message.type}" (id=${id}) timed out after ${timeoutMs}ms`));
+          }
+        }, timeoutMs);
+        this.pending.set(id, { expectedTypes, resolve: (m) => resolve(m), reject, timer });
+        if (this.ready) this.postToIframe(message);
+        else this.outbox.push(message);
+      });
+    });
+  }
+  postToIframe(message) {
+    var _a, _b;
+    (_b = (_a = this.iframe) == null ? void 0 : _a.contentWindow) == null ? void 0 : _b.postMessage(message, this.opts.walletOrigin);
+  }
+  close() {
+    var _a, _b;
+    this.rejectAllPending("transport closed");
+    (_a = this.backdrop) == null ? void 0 : _a.remove();
+    this.backdrop = null;
+    this.overlayVisible = false;
+    (_b = this.iframe) == null ? void 0 : _b.remove();
+    this.iframe = null;
+    this.ready = false;
+    this.outbox = [];
+  }
+  destroy() {
+    this.close();
+    if (this.listener) {
+      this.opts.hostWindow.removeEventListener("message", this.listener);
+      this.listener = null;
+    }
+  }
+  rejectAllPending(reason) {
+    for (const [id, p] of this.pending) {
+      clearTimeout(p.timer);
+      this.pending.delete(id);
+      p.reject(new walletApiClient.WalletError("internal", reason));
+    }
+  }
+  onMessage(event) {
+    const data = event.data;
+    if (!isMatchingOrigin(event.origin, this.opts.walletOrigin)) {
+      if (data && typeof data.id === "string" && this.pending.has(data.id)) {
+        const p2 = this.pending.get(data.id);
+        this.pending.delete(data.id);
+        clearTimeout(p2.timer);
+        p2.reject(
+          new walletApiClient.WalletError(
+            "origin-mismatch",
+            `message from "${event.origin}" rejected (expected "${this.opts.walletOrigin}")`
+          )
+        );
+      }
+      return;
+    }
+    if (!data || typeof data.type !== "string" || typeof data.id !== "string") return;
+    if (data.type === "wallet:ready") {
+      if (this.ready) return;
+      this.ready = true;
+      const flush = this.outbox;
+      this.outbox = [];
+      for (const m of flush) this.postToIframe(m);
+      return;
+    }
+    if (data.type === "wallet:ui:show") {
+      this.showOverlay();
+      return;
+    }
+    if (data.type === "wallet:ui:hide") {
+      this.hideOverlay();
+      return;
+    }
+    const p = this.pending.get(data.id);
+    if (!p) return;
+    clearTimeout(p.timer);
+    this.pending.delete(data.id);
+    if (data.type === "wallet:error") {
+      p.reject(new walletApiClient.WalletError(data.code, data.message, data.traceId));
+      return;
+    }
+    if (!p.expectedTypes.includes(data.type)) {
+      p.reject(new walletApiClient.WalletError("internal", `received unexpected response type "${data.type}" for id "${data.id}"`));
+      return;
+    }
+    p.resolve(data);
+  }
+};
 
 // src/EmbedWallet.ts
 var EmbedWallet = class {
@@ -196,7 +378,7 @@ var EmbedWallet = class {
     this._addresses = null;
     this._credentialId = null;
     this._listeners = {};
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h;
     const injectedTransport = (_a = opts.__internal__) == null ? void 0 : _a.transport;
     if (!injectedTransport && !opts.walletOrigin) {
       throw new Error("EmbedWallet: `walletOrigin` is required (e.g. https://wallet.example.com).");
@@ -205,9 +387,8 @@ var EmbedWallet = class {
     this.walletOrigin = (_b = opts.walletOrigin) != null ? _b : "";
     this.popup = { width: (_d = (_c = opts.popup) == null ? void 0 : _c.width) != null ? _d : 420, height: (_f = (_e = opts.popup) == null ? void 0 : _e.height) != null ? _f : 640 };
     this.appName = (_g = opts.appName) != null ? _g : "";
-    this.transport = injectedTransport != null ? injectedTransport : new PopupTransport({
-      walletOrigin: this.walletOrigin
-    });
+    this.regPopupOpener = (_h = opts.__internal__) == null ? void 0 : _h.registerPopupOpener;
+    this.transport = injectedTransport != null ? injectedTransport : opts.transport === "popup" ? new PopupTransport({ walletOrigin: this.walletOrigin }) : new IframeTransport({ walletOrigin: this.walletOrigin });
   }
   get isLoggedIn() {
     return this._addresses !== null;
@@ -218,9 +399,27 @@ var EmbedWallet = class {
   get credentialId() {
     return this._credentialId;
   }
+  /**
+   * 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() {
     return __async(this, arguments, function* (opts = {}) {
-      return this.helloAndAwaitLogin("register", opts);
+      if (this.transport instanceof PopupTransport) {
+        return this.helloAndAwaitLogin("register", opts);
+      }
+      const popup = new PopupTransport(__spreadValues({
+        walletOrigin: this.walletOrigin
+      }, this.regPopupOpener ? { openPopup: this.regPopupOpener } : {}));
+      try {
+        return yield this.helloAndAwaitLogin("register", opts, popup);
+      } finally {
+        popup.close();
+      }
     });
   }
   login() {
@@ -379,16 +578,18 @@ var EmbedWallet = class {
     return { appId: this.appId, name: this.appName, origin };
   }
   helloAndAwaitLogin(_0) {
-    return __async(this, arguments, function* (intent, opts = {}) {
+    return __async(this, arguments, function* (intent, opts = {}, transport = this.transport) {
       const id = crypto.randomUUID();
       const helloMessage = {
         type: "wallet:hello",
         id,
         appContext: this.appContext(),
         intent,
-        label: opts.label
+        label: opts.label,
+        name: opts.name,
+        email: opts.email
       };
-      const result = yield this.transport.request(helloMessage, [
+      const result = yield transport.request(helloMessage, [
         "wallet:login:ok"
       ]);
       this._addresses = result.addresses;
@@ -421,7 +622,8 @@ var PopupHostBridge = class {
     this.handlers = {};
     this.listener = null;
     this.opts = __spreadValues({
-      popupWindow: globalThis.window
+      popupWindow: globalThis.window,
+      replyTo: "opener"
     }, options);
   }
   /** Register a handler for a specific message type. Replaces any prior handler. */
@@ -430,16 +632,16 @@ var PopupHostBridge = class {
     return 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) {
-    const opener = globalThis.opener;
-    if (!opener || typeof opener.postMessage !== "function") {
+    const target = this.opts.replyTo === "parent" ? globalThis.parent : globalThis.opener;
+    if (!target || typeof target.postMessage !== "function") {
       return;
     }
-    opener.postMessage(message, this.opts.hostOrigin);
+    target.postMessage(message, this.opts.hostOrigin);
   }
   /**
    * Start listening for inbound messages.
@@ -525,8 +727,8 @@ var BroadcastSessionShare = class {
         });
         return;
       }
-      if (msg.type === "logout") {
-        (_b = (_a = this.opts).onLogout) == null ? void 0 : _b.call(_a);
+      if (msg.type === "session-available") {
+        (_b = (_a = this.opts).onAvailable) == null ? void 0 : _b.call(_a);
         return;
       }
     };
@@ -565,7 +767,13 @@ var BroadcastSessionShare = class {
       });
     });
   }
-  /** 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() {
     if (this.listening) return;
     this.listening = true;
@@ -575,10 +783,24 @@ var BroadcastSessionShare = class {
     this.channel.removeEventListener("message", this.onMessage);
     this.listening = false;
   }
-  /** 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() {
     this.channel.postMessage({ type: "logout" });
   }
+  /**
+   * 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() {
+    this.channel.postMessage({ type: "session-available" });
+  }
   /** Free the underlying channel handle. Call from unload handlers. */
   close() {
     this.stop();
@@ -590,6 +812,7 @@ exports.ALLOWED_ORIGIN_SCHEMES = ALLOWED_ORIGIN_SCHEMES;
 exports.BROADCAST_CHANNEL_NAME = BROADCAST_CHANNEL_NAME;
 exports.BroadcastSessionShare = BroadcastSessionShare;
 exports.EmbedWallet = EmbedWallet;
+exports.IframeTransport = IframeTransport;
 exports.PopupHostBridge = PopupHostBridge;
 exports.PopupTransport = PopupTransport;
 exports.isMatchingOrigin = isMatchingOrigin;