@multiplatform.one/web3 7.24.0 → 7.26.0

package/src/bridge/BridgeClient.spec.ts

@@ -71,6 +71,18 @@ describe("BridgeClient events", () => {
     ]);
   });
 
+  it("rejectPending() fails in-flight requests and keeps the client working", async () => {
+    const { a, b } = createMemoryTransportPair();
+    const client = new BridgeClient(a);
+    const lost = client.request("evm", "eth_requestAccounts");
+    client.rejectPending(new Error("page reloaded"));
+    await expect(lost).rejects.toThrow("page reloaded");
+    b.subscribe((m) => {
+      if (m.kind === "req") b.post({ id: m.id, ns: m.ns, kind: "res", result: "0x1" });
+    });
+    await expect(client.request("evm", "eth_chainId")).resolves.toBe("0x1");
+  });
+
   it("dispose() rejects in-flight requests and stops events", async () => {
     const { a, b } = createMemoryTransportPair();
     const client = new BridgeClient(a);

package/src/bridge/BridgeClient.ts

@@ -1,4 +1,5 @@
 import {
+  BridgeRequestError,
   isBridgeMessage,
   newRequestId,
   type BridgeError,
@@ -79,15 +80,21 @@ export class BridgeClient {
     };
   }
 
-  /** Reject all in-flight requests — call on WebView reload/crash. */
+  /** Fail every request in flight and keep the client usable: the page they went to is gone. */
+  rejectPending(reason: Error): void {
+    const pending = Array.from(this.pending.values());
+    this.pending.clear();
+    for (const p of pending) {
+      p.cleanup();
+      p.reject(reason);
+    }
+  }
+
+  /** Reject all in-flight requests and stop listening. */
   dispose(): void {
     this.disposed = true;
     this.unsubscribe();
-    for (const [, p] of this.pending) {
-      p.cleanup();
-      p.reject(new Error("Bridge disposed"));
-    }
-    this.pending.clear();
+    this.rejectPending(new Error("Bridge disposed"));
     this.listeners.clear();
   }
 
@@ -119,8 +126,6 @@ export class BridgeClient {
   };
 }
 
-function toError(e: BridgeError): Error {
-  const err = new Error(e.message) as Error & { code?: number };
-  err.code = e.code;
-  return err;
+function toError(e: BridgeError): BridgeRequestError {
+  return new BridgeRequestError(e.code, e.message, e.data);
 }

package/src/bridge/BridgeHost.spec.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { BridgeClient } from "./BridgeClient";
 import { BridgeHost } from "./BridgeHost";
+import { BridgeRequestError } from "./protocol";
 import { createMemoryTransportPair } from "./transport";
 
 /** Pair a native client (a) with a webview host (b) over the in-memory transport. */
@@ -60,13 +61,28 @@ describe("BridgeHost", () => {
     expect(seen).toEqual([["evm", "accountsChanged", ["0xabc"]]]);
   });
 
-  it("ready() emits a sys ready event", () => {
+  it("ready() emits a sys ready event with the protocol version and namespaces", () => {
     const { client, host } = pair();
     const onReady = vi.fn();
-    client.on((ns, method) => {
-      if (ns === "sys" && method === "ready") onReady();
+    client.on((ns, method, params) => {
+      if (ns === "sys" && method === "ready") onReady(params);
     });
+    host.register("evm", () => null);
+    host.register("auth", () => null);
     host.ready();
-    expect(onReady).toHaveBeenCalledOnce();
+    expect(onReady).toHaveBeenCalledExactlyOnceWith({
+      protocol: 1,
+      namespaces: ["evm", "auth", "sys"],
+    });
+  });
+
+  it("carries an error's data to the client", async () => {
+    const { client, host } = pair();
+    host.register("auth", () => {
+      throw new BridgeRequestError(-32002, "Invalid user credentials", { status: 401 });
+    });
+    const error = await client.request("auth", "signIn").catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(BridgeRequestError);
+    expect(error).toMatchObject({ code: -32002, data: { status: 401 } });
   });
 });

package/src/bridge/BridgeHost.ts

@@ -1,4 +1,11 @@
-import { isBridgeMessage, type BridgeError, type BridgeMessage, type Namespace } from "./protocol";
+import {
+  BRIDGE_PROTOCOL_VERSION,
+  isBridgeMessage,
+  type BridgeError,
+  type BridgeMessage,
+  type BridgeReady,
+  type Namespace,
+} from "./protocol";
 import type { Transport } from "./transport";
 
 /**
@@ -31,9 +38,11 @@ export class BridgeHost {
     this.transport.post({ ns, kind: "event", method, params });
   }
 
-  /** Tell native the host is initialized. */
+  /** Tell native the host is initialized, which protocol it speaks and what it serves. */
   ready(): void {
-    this.transport.post({ ns: "sys", kind: "event", method: "ready" });
+    const namespaces = Array.from(new Set<Namespace>([...this.handlers.keys(), "sys"]));
+    const params: BridgeReady = { protocol: BRIDGE_PROTOCOL_VERSION, namespaces };
+    this.transport.post({ ns: "sys", kind: "event", method: "ready", params });
   }
 
   dispose(): void {
@@ -63,11 +72,13 @@ export class BridgeHost {
 
 function toBridgeError(e: unknown): BridgeError {
   if (e && typeof e === "object") {
-    const o = e as { code?: unknown; message?: unknown };
-    return {
+    const o = e as { code?: unknown; message?: unknown; data?: unknown };
+    const error: BridgeError = {
       code: typeof o.code === "number" ? o.code : -32000,
       message: typeof o.message === "string" ? o.message : String(e),
     };
+    if (o.data !== undefined) error.data = o.data;
+    return error;
   }
   return { code: -32000, message: String(e) };
 }

package/src/bridge/GpgBridge.ts

@@ -0,0 +1,49 @@
+import type { BridgeClient, RequestOptions } from "./BridgeClient";
+
+/** A signature the WebView is waiting for: the message and the terminal command that signs it. */
+export interface GpgPendingRequest {
+  message: string;
+  command: string;
+}
+
+// The user signs in a terminal and pastes the output back, which takes longer
+// than a wallet tap.
+const GPG_TIMEOUT_MS = 15 * 60_000;
+
+/**
+ * Native-side proxy for the WebView's copy/paste GPG signer. `signMessage`
+ * parks a request in the page, which shows the command and a paste box; a
+ * native host that draws its own paste box calls `submit` instead.
+ */
+export class GpgBridge {
+  constructor(private readonly bridge: BridgeClient) {}
+
+  /** Resolves with the armored signature followed by the armored public key. */
+  async signMessage(message: string, options: RequestOptions = {}): Promise<string> {
+    const res = (await this.bridge.request(
+      "gpg",
+      "signMessage",
+      { message },
+      { timeoutMs: GPG_TIMEOUT_MS, ...options },
+    )) as { signature: string };
+    return res.signature;
+  }
+
+  /** Hand pasted terminal output to the pending request. Rejects when it does not cover its message. */
+  async submit(signature: string): Promise<void> {
+    await this.bridge.request("gpg", "submit", { signature });
+  }
+
+  async cancel(): Promise<void> {
+    await this.bridge.request("gpg", "cancel");
+  }
+
+  /** Called with the pending request whenever one is parked, and with null when it settles. */
+  onPendingChanged(handler: (request: GpgPendingRequest | null) => void): () => void {
+    return this.bridge.on((ns, method, params) => {
+      if (ns === "gpg" && method === "pendingChanged") {
+        handler((params as { request: GpgPendingRequest | null } | undefined)?.request ?? null);
+      }
+    });
+  }
+}

package/src/bridge/SuiBridge.ts

@@ -0,0 +1,34 @@
+import type { BridgeClient, RequestOptions } from "./BridgeClient";
+
+/**
+ * Native-side proxy for the WebView's Sui wallet. Messages are UTF-8 text; the
+ * signature is Sui's serialized signature (flag || signature || public key),
+ * base64, which is what the Keycloak Sui verifier takes as the login username.
+ */
+export class SuiBridge {
+  constructor(private readonly bridge: BridgeClient) {}
+
+  async connect(options?: RequestOptions): Promise<{ address: string }> {
+    return (await this.bridge.request("sui", "connect", undefined, options)) as {
+      address: string;
+    };
+  }
+
+  async disconnect(): Promise<void> {
+    await this.bridge.request("sui", "disconnect");
+  }
+
+  async signMessage(message: string, options?: RequestOptions): Promise<string> {
+    const res = (await this.bridge.request("sui", "signMessage", { message }, options)) as {
+      signature: string;
+    };
+    return res.signature;
+  }
+
+  /** Subscribe to sui events (`accountChanged`). */
+  on(handler: (event: string, params: unknown) => void): () => void {
+    return this.bridge.on((ns, method, params) => {
+      if (ns === "sui") handler(method, params);
+    });
+  }
+}

package/src/bridge/authTypes.ts

@@ -0,0 +1,76 @@
+/** Who signs an `auth.signIn`: the message families the Keycloak wallet SPIs verify. */
+export type AuthFamily = "eth" | "sol" | "sui" | "gpg";
+
+export const AUTH_FAMILIES: readonly AuthFamily[] = ["eth", "sol", "sui", "gpg"];
+
+export interface AuthKeycloakConfig {
+  /** e.g. `https://account.example.com`, or `http://localhost:8080/auth` in dev. */
+  baseUrl: string;
+  realm: string;
+  /** The wallet SPI's REST resource: `siww` on the SHC Keycloak (default), `wallet` on mpo's. */
+  resource?: "siww" | "wallet";
+  /** A public client with direct access grants enabled. */
+  clientId: string;
+  /** Default `openid`. */
+  scope?: string | string[];
+}
+
+/**
+ * The client Keycloak's own browser login runs under when the account still
+ * has required actions: standard flow on, `redirectUri` registered exactly.
+ */
+export interface AuthOnboardingConfig {
+  clientId: string;
+  /** Where Keycloak sends the system browser back, usually the app's deep link. */
+  redirectUri: string;
+  scope?: string | string[];
+}
+
+export interface AuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  idToken?: string;
+  tokenType: string;
+  scope?: string;
+  /** Epoch ms. */
+  expiresAt: number;
+  /** Epoch ms; absent for offline or non-expiring refresh tokens. */
+  refreshExpiresAt?: number;
+}
+
+export interface AuthSignInParams {
+  /** Default `eth`. */
+  family?: AuthFamily;
+  keycloak: AuthKeycloakConfig;
+  onboarding?: AuthOnboardingConfig;
+}
+
+/** Keycloak's authorization-code login with a fresh `state` and PKCE S256 verifier. */
+export interface AuthBrowserLogin {
+  url: string;
+  state: string;
+  codeVerifier: string;
+}
+
+export type AuthSignInResult =
+  | { status: "signed-in"; family: AuthFamily; address: string | null; tokens: AuthTokens }
+  | {
+      status: "profile-incomplete";
+      family: AuthFamily;
+      address: string | null;
+      browserLogin: AuthBrowserLogin;
+    };
+
+export interface AuthSessionParams {
+  keycloak: AuthKeycloakConfig;
+  /** Defaults to the refresh token of the page's last sign-in for this realm and client. */
+  refreshToken?: string;
+}
+
+/** `auth.tokensChanged` event params. */
+export interface AuthTokensChanged {
+  baseUrl: string;
+  realm: string;
+  clientId: string;
+  tokens: AuthTokens | null;
+}

package/src/bridge/core.ts

@@ -0,0 +1,42 @@
+// The Hermes-safe bridge surface, without the wagmi connector: what a React
+// Native host needs to drive the hosted wallet page (`@multiplatform.one/web3/bridge`).
+export * from "./protocol";
+export * from "./transport";
+export * from "./authTypes";
+export { createPostMessageTransport, type PostMessageTransport } from "./postMessageTransport";
+export { BridgeClient, type EventHandler, type RequestOptions } from "./BridgeClient";
+export { BridgeHost, type RequestHandler } from "./BridgeHost";
+export { createBridgeProvider, type BridgeProvider, type Eip1193RequestArgs } from "./eip1193";
+export { bytesToBase64, base64ToBytes } from "./base64";
+export { SolanaBridge } from "./SolanaBridge";
+export { SuiBridge } from "./SuiBridge";
+export { GpgBridge, type GpgPendingRequest } from "./GpgBridge";
+export {
+  AuthBridge,
+  type AuthBridgeOptions,
+  type AuthSignInOptions,
+  type AuthSignInOutcome,
+} from "./AuthBridge";
+export {
+  DEV_HOSTNAMES,
+  hostedPageOrigin,
+  isHostedPageUrl,
+  parseOrigin,
+  queryParams,
+  type ParsedOrigin,
+} from "./hosting";
+export {
+  buildInjectScript,
+  createNativeBridge,
+  type NativeBridge,
+  type NativeBridgeOptions,
+} from "./nativeHost";
+export {
+  decideNavigation,
+  decideNewWindow,
+  parseWalletReturn,
+  shouldOpenExternally,
+  WALLET_SCHEMES,
+  WALLET_UNIVERSAL_HOSTS,
+  type NavigationDecision,
+} from "../providers/native/deepLink";

package/src/bridge/hosting.spec.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { hostedPageOrigin, isHostedPageUrl, parseOrigin, queryParams } from "./hosting";
+
+describe("parseOrigin", () => {
+  it("lowercases and drops the default port", () => {
+    expect(parseOrigin("HTTPS://Wallet.Example.com:443/webview.html?x=1")).toEqual({
+      scheme: "https",
+      host: "wallet.example.com",
+      hostname: "wallet.example.com",
+      origin: "https://wallet.example.com",
+    });
+  });
+
+  it("keeps a non-default port, strips userinfo and handles IPv6", () => {
+    expect(parseOrigin("http://user:pw@localhost:8099/webview.html")?.origin).toBe(
+      "http://localhost:8099",
+    );
+    expect(parseOrigin("http://[::1]:8099/")?.hostname).toBe("[::1]");
+  });
+
+  it("ends the authority at a backslash, as browsers do", () => {
+    expect(parseOrigin("http://evil.com\\@localhost:8099/")?.origin).toBe("http://evil.com");
+    expect(isHostedPageUrl("http://evil.com\\@localhost:8099/", { allowDevHosts: true })).toBe(
+      false,
+    );
+  });
+
+  it("gives schemes without an authority an empty host", () => {
+    expect(parseOrigin("about:blank")).toEqual({
+      scheme: "about",
+      host: "",
+      hostname: "",
+      origin: "about:",
+    });
+    expect(parseOrigin("metamask://connect")?.hostname).toBe("connect");
+  });
+
+  it("returns null for text that is not a URL", () => {
+    expect(parseOrigin("not a url")).toBeNull();
+    expect(parseOrigin("")).toBeNull();
+  });
+});
+
+describe("isHostedPageUrl", () => {
+  it("accepts https pages", () => {
+    expect(isHostedPageUrl("https://wallet.example.com/webview.html")).toBe(true);
+  });
+
+  it("accepts plain http only on development hosts, and only when asked to", () => {
+    const dev = { allowDevHosts: true };
+    expect(isHostedPageUrl("http://localhost:8099/webview.html", dev)).toBe(true);
+    expect(isHostedPageUrl("http://127.0.0.1:8099/webview.html", dev)).toBe(true);
+    expect(isHostedPageUrl("http://10.0.2.2:8099/webview.html", dev)).toBe(true);
+    expect(isHostedPageUrl("http://wallet.example.com/webview.html", dev)).toBe(false);
+    expect(isHostedPageUrl("http://192.168.1.20:8099/webview.html", dev)).toBe(false);
+    expect(isHostedPageUrl("http://localhost:8099/webview.html")).toBe(false);
+    expect(isHostedPageUrl("http://10.0.2.2:8099/webview.html")).toBe(false);
+  });
+
+  it("refuses pages with no host", () => {
+    expect(isHostedPageUrl("file:///android_asset/webview.html")).toBe(false);
+    expect(isHostedPageUrl("data:text/html,<p>hi</p>")).toBe(false);
+    expect(isHostedPageUrl("about:blank")).toBe(false);
+  });
+});
+
+describe("hostedPageOrigin", () => {
+  it("returns the origin of a hosted page", () => {
+    expect(hostedPageOrigin("https://wallet.example.com/a/webview.html")).toBe(
+      "https://wallet.example.com",
+    );
+  });
+
+  it("throws naming the allowlist for anything else", () => {
+    expect(() => hostedPageOrigin("file:///webview.html")).toThrow(/siww\.allowedDomains/);
+    expect(() => hostedPageOrigin("http://localhost:8099/webview.html")).toThrow(
+      /only in development builds/,
+    );
+    expect(hostedPageOrigin("http://localhost:8099/webview.html", { allowDevHosts: true })).toBe(
+      "http://localhost:8099",
+    );
+  });
+});
+
+describe("queryParams", () => {
+  it("decodes keys and values and keeps the first of a repeated name", () => {
+    expect(queryParams("app://cb?state=a%2Fb&code=x+y&state=later#frag")).toEqual({
+      state: "a/b",
+      code: "x y",
+    });
+  });
+
+  it("does not let a key reach the prototype", () => {
+    const params = queryParams("app://cb?__proto__=x&constructor=y");
+    expect(Object.getPrototypeOf(params)).toBe(Object.prototype);
+    expect(params.constructor).toBe("y");
+  });
+});

package/src/bridge/hosting.ts

@@ -0,0 +1,99 @@
+// URL handling without the URL global: React Native's own URL throws on
+// `hostname` and `searchParams` outside Expo, and native hosts run this code.
+
+export interface ParsedOrigin {
+  /** Lowercased, without the colon. */
+  scheme: string;
+  /** Lowercased hostname with a non-default port, e.g. `example.com:8443`; empty for `about:`. */
+  host: string;
+  /** Lowercased hostname, IPv6 in brackets. */
+  hostname: string;
+  /** `scheme://host`, or `scheme:` for a URL without an authority. */
+  origin: string;
+}
+
+// A backslash ends the authority, as browsers read http(s) URLs:
+// `http://evil.com\@localhost/` is evil.com, not localhost.
+const schemeAndAuthority = /^([a-z][a-z0-9+.-]*):(?:\/\/([^/?#\\]*))?/i;
+const hostAndPort = /^(\[[^\]]*\]|[^:]*)(?::(\d*))?$/;
+const defaultPorts: Record<string, string> = { http: "80", https: "443" };
+
+export function parseOrigin(url: string): ParsedOrigin | null {
+  const match = url.trim().match(schemeAndAuthority);
+  if (!match) return null;
+  const scheme = match[1].toLowerCase();
+  if (match[2] === undefined) return { scheme, host: "", hostname: "", origin: `${scheme}:` };
+  const authority = match[2].slice(match[2].lastIndexOf("@") + 1).toLowerCase();
+  const hostPort = authority.match(hostAndPort);
+  if (!hostPort) return null;
+  const hostname = hostPort[1];
+  const port = hostPort[2] && hostPort[2] !== defaultPorts[scheme] ? hostPort[2] : "";
+  const host = port ? `${hostname}:${port}` : hostname;
+  return { scheme, host, hostname, origin: `${scheme}://${host}` };
+}
+
+/** The query parameters of `url`, decoded; a repeated name keeps its first value. */
+export function queryParams(url: string): Record<string, string> {
+  const params = new Map<string, string>();
+  const query = url.match(/\?([^#]*)/)?.[1] ?? "";
+  for (const pair of query.split("&")) {
+    if (!pair) continue;
+    const eq = pair.indexOf("=");
+    const key = safeDecode(eq === -1 ? pair : pair.slice(0, eq));
+    if (!params.has(key)) params.set(key, eq === -1 ? "" : safeDecode(pair.slice(eq + 1)));
+  }
+  return Object.fromEntries(params);
+}
+
+function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value.replace(/\+/g, " "));
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Plain http is allowed only where the device itself is the server: loopback,
+ * reached from an emulator through `adb reverse`, and 10.0.2.2, the Android
+ * emulator's alias for the host machine. Development builds only: on a phone
+ * any app can bind a loopback port, and 10.0.2.2 is a LAN address there.
+ */
+export const DEV_HOSTNAMES: readonly string[] = ["localhost", "127.0.0.1", "[::1]", "10.0.2.2"];
+
+export interface HostedPageOptions {
+  /** Accept plain http on `DEV_HOSTNAMES`. Default false; a React Native host passes `__DEV__`. */
+  allowDevHosts?: boolean;
+}
+
+/**
+ * True when a page at `url` can run the wallet bridge: https, or http on a
+ * development host. The sign-in message's domain is the page's host and the
+ * Keycloak nonce cookie is set for it, so a `file:`, `data:` or inline page,
+ * whose host is empty, can never sign in.
+ */
+export function isHostedPageUrl(url: string, options: HostedPageOptions = {}): boolean {
+  const parsed = parseOrigin(url);
+  if (!parsed || !parsed.hostname) return false;
+  if (parsed.scheme === "https") return true;
+  return (
+    options.allowDevHosts === true &&
+    parsed.scheme === "http" &&
+    DEV_HOSTNAMES.includes(parsed.hostname)
+  );
+}
+
+/** The origin of a hosted wallet page, or a thrown error naming what is wrong with `url`. */
+export function hostedPageOrigin(url: string, options: HostedPageOptions = {}): string {
+  if (!isHostedPageUrl(url, options)) {
+    throw new Error(
+      `The wallet WebView page must be served over https (got ${JSON.stringify(url)}). ` +
+        "Serve @multiplatform.one/web3/assets/webview.html from a host listed in the realm's " +
+        "siww.allowedDomains / wallet.allowedDomains; " +
+        (options.allowDevHosts
+          ? `plain http is accepted only on ${DEV_HOSTNAMES.join(", ")} for development.`
+          : "plain http is accepted only in development builds."),
+    );
+  }
+  return (parseOrigin(url) as ParsedOrigin).origin;
+}

package/src/bridge/index.ts

@@ -1,9 +1,2 @@
-export * from "./protocol";
-export * from "./transport";
-export { createPostMessageTransport, type PostMessageTransport } from "./postMessageTransport";
-export { BridgeClient, type EventHandler, type RequestOptions } from "./BridgeClient";
-export { BridgeHost, type RequestHandler } from "./BridgeHost";
-export { createBridgeProvider, type BridgeProvider, type Eip1193RequestArgs } from "./eip1193";
+export * from "./core";
 export { createBridgeConnector } from "./bridgeConnector";
-export { bytesToBase64, base64ToBytes } from "./base64";
-export { SolanaBridge } from "./SolanaBridge";