@multiplatform.one/web3 7.24.0 → 7.25.0

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";

package/src/bridge/nativeHost.spec.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from "vitest";
+import { BridgeHost } from "./BridgeHost";
+import { buildInjectScript, createNativeBridge } from "./nativeHost";
+import { createPostMessageTransport } from "./postMessageTransport";
+import { BRIDGE_PROTOCOL_VERSION } from "./protocol";
+
+/**
+ * A fake page: `inject` runs the native side's script against a fake window
+ * whose `__bridgeReceive` feeds a BridgeHost, and the host's replies come back
+ * through `native.receive` with the page's URL.
+ */
+function setup(pageUrl = "https://wallet.example.com/webview.html") {
+  const injected: string[] = [];
+  const win: { location: { origin: string }; __bridgeReceive?: (raw: string) => void } = {
+    location: { origin: new URL(pageUrl).origin },
+  };
+  let postedFrom = pageUrl;
+  const native = createNativeBridge({
+    pageUrl,
+    allowDevHosts: true,
+    inject(script) {
+      injected.push(script);
+      new Function("window", script)(win);
+    },
+  });
+  const transport = createPostMessageTransport((raw) => native.receive(raw, postedFrom));
+  win.__bridgeReceive = (raw) => transport.receive(raw);
+  const host = new BridgeHost(transport);
+  return {
+    native,
+    host,
+    injected,
+    win,
+    postFrom(url: string) {
+      postedFrom = url;
+    },
+  };
+}
+
+describe("createNativeBridge", () => {
+  it("refuses a page that is not hosted", () => {
+    expect(() =>
+      createNativeBridge({ pageUrl: "file:///webview.html", inject: () => undefined }),
+    ).toThrow(/https/);
+  });
+
+  it("refuses a plain-http dev page unless dev hosts are allowed", () => {
+    const pageUrl = "http://localhost:8099/webview.html";
+    expect(() => createNativeBridge({ pageUrl, inject: () => undefined })).toThrow(
+      /development builds/,
+    );
+    expect(
+      createNativeBridge({ pageUrl, inject: () => undefined, allowDevHosts: true }).pageOrigin,
+    ).toBe("http://localhost:8099");
+  });
+
+  it("queues requests until sys.ready, then flushes them", async () => {
+    const { native, host, injected } = setup();
+    host.register("evm", (method) => (method === "eth_chainId" ? "0x1" : null));
+    const pending = native.client.request("evm", "eth_chainId");
+    expect(injected).toHaveLength(0);
+    host.ready();
+    await expect(pending).resolves.toBe("0x1");
+    expect(injected).toHaveLength(1);
+    expect(native.peer).toEqual({ protocol: BRIDGE_PROTOCOL_VERSION, namespaces: ["evm", "sys"] });
+  });
+
+  it("drops messages posted by a page on another origin", async () => {
+    const { native, host, postFrom } = setup();
+    host.register("evm", () => "0x1");
+    postFrom("https://evil.example/");
+    host.ready();
+    expect(native.peer).toBeNull();
+    postFrom("https://wallet.example.com/other");
+    host.ready();
+    expect(native.peer).not.toBeNull();
+  });
+
+  it("drops messages that name no sender", () => {
+    const { native, postFrom, host } = setup();
+    postFrom("");
+    host.ready();
+    expect(native.peer).toBeNull();
+  });
+
+  it("delivers nothing into a document on another origin", async () => {
+    const { native, host, injected, win } = setup();
+    host.register("evm", () => "0x1");
+    host.ready();
+    win.location.origin = "https://evil.example";
+    const lost = native.client.request("evm", "eth_chainId", undefined, { timeoutMs: 20 });
+    expect(injected).toHaveLength(1);
+    await expect(lost).rejects.toThrow();
+  });
+
+  it("a top-frame load on another origin fails what is in flight and stops delivery", async () => {
+    const { native, host, injected } = setup();
+    host.register("evm", (method) =>
+      method === "eth_chainId" ? "0x1" : new Promise(() => undefined),
+    );
+    host.ready();
+    const lost = native.client.request("evm", "eth_requestAccounts");
+    expect(native.navigated("https://wallet.example.com/webview.html")).toBe(false);
+    expect(native.navigated("about:blank")).toBe(false);
+    expect(native.peer).not.toBeNull();
+    expect(native.navigated("https://evil.example/form")).toBe(true);
+    await expect(lost).rejects.toThrow(/went away/);
+    expect(native.peer).toBeNull();
+    const before = injected.length;
+    const next = native.client.request("evm", "eth_chainId");
+    expect(injected).toHaveLength(before);
+    host.ready();
+    await expect(next).resolves.toBe("0x1");
+  });
+
+  it("fails requests in flight when the page announces itself again", async () => {
+    const { native, host } = setup();
+    host.register("evm", () => new Promise(() => undefined));
+    host.ready();
+    const lost = native.client.request("evm", "eth_requestAccounts");
+    host.ready();
+    await expect(lost).rejects.toThrow(/reloaded/);
+  });
+
+  it("pageGone fails what is in flight and queues until the next ready", async () => {
+    const { native, host, injected } = setup();
+    host.register("evm", (method) =>
+      method === "eth_chainId" ? "0x1" : new Promise(() => undefined),
+    );
+    host.ready();
+    const lost = native.client.request("evm", "eth_requestAccounts");
+    native.pageGone();
+    await expect(lost).rejects.toThrow(/went away/);
+    const before = injected.length;
+    const next = native.client.request("evm", "eth_chainId");
+    expect(injected).toHaveLength(before);
+    host.ready();
+    await expect(next).resolves.toBe("0x1");
+  });
+
+  it("asks for the page back twice at most until it announces itself again", () => {
+    const { native, host } = setup();
+    host.ready();
+    expect(native.navigated("https://evil.example/")).toBe(true);
+    expect(native.navigated("https://evil.example/")).toBe(true);
+    expect(native.navigated("https://evil.example/")).toBe(false);
+    host.ready();
+    expect(native.navigated("https://evil.example/")).toBe(true);
+  });
+
+  it("exposes the page origin", () => {
+    expect(setup("http://localhost:8099/webview.html").native.pageOrigin).toBe(
+      "http://localhost:8099",
+    );
+  });
+
+  it("buildInjectScript survives quotes and newlines", () => {
+    const received: string[] = [];
+    const raw = 'he said "hi"\nline2\\end </script>';
+    new Function("window", buildInjectScript(raw))({
+      __bridgeReceive: (s: string) => received.push(s),
+    });
+    expect(received).toEqual([raw]);
+  });
+});

package/src/bridge/nativeHost.ts

@@ -0,0 +1,120 @@
+import { BridgeClient } from "./BridgeClient";
+import { hostedPageOrigin, parseOrigin } from "./hosting";
+import { createPostMessageTransport } from "./postMessageTransport";
+import { BRIDGE_PROTOCOL_VERSION, type BridgeReady } from "./protocol";
+
+export interface NativeBridgeOptions {
+  /** The hosted wallet page. Must pass `isHostedPageUrl`. */
+  pageUrl: string;
+  /** Accept plain http on the development hosts. Pass `__DEV__`; never true in a release build. */
+  allowDevHosts?: boolean;
+  /** Runs a script in the page: react-native-webview's `injectJavaScript`. */
+  inject(script: string): void;
+  /** Default request timeout, see BridgeClient. */
+  timeoutMs?: number;
+  /** Called once the page reports `sys.ready`. */
+  onReady?(ready: BridgeReady): void;
+}
+
+export interface NativeBridge {
+  readonly client: BridgeClient;
+  /** Origin of the hosted page; messages from any other origin are dropped. */
+  readonly pageOrigin: string;
+  /** What the page announced in `sys.ready`, or null before it has. */
+  readonly peer: BridgeReady | null;
+  /**
+   * Feed a WebView message in: `receive(e.nativeEvent.data, e.nativeEvent.url)`.
+   * A message whose `fromUrl` is missing or on another origin is dropped.
+   */
+  receive(data: string, fromUrl: string): void;
+  /**
+   * The top frame started loading `url` (react-native-webview's `onLoadStart`).
+   * A document on another origin is not the page: what is in flight fails,
+   * nothing more is delivered until the page announces itself again, and the
+   * answer is true so the host loads `pageUrl` back. Twice at most between two
+   * `sys.ready`s: a page that never comes back stays down instead of looping.
+   */
+  navigated(url: string): boolean;
+  /**
+   * The page died (WebView content process gone) or is being reloaded: fail
+   * the requests in flight and queue new ones until the next `sys.ready`.
+   */
+  pageGone(): void;
+  dispose(): void;
+}
+
+/**
+ * The script that delivers one message into the page. The raw string is
+ * embedded with JSON.stringify so quotes, newlines and backslashes survive;
+ * the trailing `true;` is react-native-webview's injectJavaScript contract.
+ * With `pageOrigin` the script delivers only while the top frame is on that
+ * origin, so a document that replaced the page never sees a message.
+ */
+export function buildInjectScript(raw: string, pageOrigin?: string): string {
+  const guard = pageOrigin
+    ? `window.location && window.location.origin === ${JSON.stringify(pageOrigin)} && `
+    : "";
+  return `${guard}window.__bridgeReceive && window.__bridgeReceive(${JSON.stringify(raw)});true;`;
+}
+
+/**
+ * The native end of the bridge for any React Native WebView host. Requests
+ * wait in a queue until the page says `sys.ready`, because the first request
+ * usually fires before the page has loaded.
+ */
+export function createNativeBridge(options: NativeBridgeOptions): NativeBridge {
+  const pageOrigin = hostedPageOrigin(options.pageUrl, { allowDevHosts: options.allowDevHosts });
+  const queue: string[] = [];
+  let peer: BridgeReady | null = null;
+  let reloads = 0;
+
+  const transport = createPostMessageTransport((raw) => {
+    if (peer) options.inject(buildInjectScript(raw, pageOrigin));
+    else queue.push(raw);
+  });
+  const offReady = transport.subscribe((message) => {
+    if (message.ns !== "sys" || message.kind !== "event" || message.method !== "ready") return;
+    // A second ready is a new document: whatever the old one was answering is lost.
+    if (peer) client.rejectPending(new Error("The wallet page reloaded"));
+    reloads = 0;
+    const params = message.params as Partial<BridgeReady> | undefined;
+    peer = {
+      protocol: typeof params?.protocol === "number" ? params.protocol : BRIDGE_PROTOCOL_VERSION,
+      namespaces: Array.isArray(params?.namespaces) ? params.namespaces : [],
+    };
+    for (const raw of queue.splice(0)) options.inject(buildInjectScript(raw, pageOrigin));
+    options.onReady?.(peer);
+  });
+  const client = new BridgeClient(transport, { timeoutMs: options.timeoutMs });
+
+  const pageGone = () => {
+    peer = null;
+    queue.length = 0;
+    client.rejectPending(new Error("The wallet page went away"));
+  };
+
+  return {
+    client,
+    pageOrigin,
+    get peer() {
+      return peer;
+    },
+    receive(data, fromUrl) {
+      if (!fromUrl || parseOrigin(fromUrl)?.origin !== pageOrigin) return;
+      transport.receive(data);
+    },
+    navigated(url) {
+      if (url.trim().toLowerCase() === "about:blank") return false;
+      if (parseOrigin(url)?.origin === pageOrigin) return false;
+      pageGone();
+      reloads += 1;
+      return reloads <= 2;
+    },
+    pageGone,
+    dispose() {
+      offReady();
+      client.dispose();
+      queue.length = 0;
+    },
+  };
+}

package/src/bridge/protocol.spec.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { isBridgeMessage, newRequestId, type BridgeMessage } from "./protocol";
+import {
+  BridgeRequestError,
+  NAMESPACES,
+  isBridgeMessage,
+  newRequestId,
+  type BridgeMessage,
+} from "./protocol";
 
 describe("protocol", () => {
   it("accepts a well-formed req", () => {
@@ -9,6 +15,23 @@ describe("protocol", () => {
   it("accepts an event without id", () => {
     expect(isBridgeMessage({ ns: "solana", kind: "event", method: "connect" })).toBe(true);
   });
+  it("accepts the sui, gpg and auth namespaces", () => {
+    expect(NAMESPACES).toEqual(["evm", "solana", "sui", "gpg", "auth", "sys"]);
+    for (const ns of ["sui", "gpg", "auth"]) {
+      expect(isBridgeMessage({ id: "1", ns, kind: "req", method: "signMessage" })).toBe(true);
+    }
+  });
+  it("BridgeRequestError keeps code and data", () => {
+    const e = new BridgeRequestError(-32002, "refused", { status: 401 });
+    expect(e).toBeInstanceOf(Error);
+    expect([e.name, e.code, e.message, e.data]).toEqual([
+      "BridgeRequestError",
+      -32002,
+      "refused",
+      { status: 401 },
+    ]);
+    expect("data" in new BridgeRequestError(1, "x")).toBe(false);
+  });
   it("rejects unknown namespace", () => {
     expect(isBridgeMessage({ ns: "btc", kind: "req", method: "x" })).toBe(false);
   });

package/src/bridge/protocol.ts

@@ -1,12 +1,36 @@
-export const NAMESPACES = ["evm", "solana", "sys"] as const;
+/**
+ * Version of the wire protocol in docs/bridge-protocol.md. The WebView sends it
+ * in `sys.ready`; bump it only for a change an existing host cannot ignore.
+ */
+export const BRIDGE_PROTOCOL_VERSION = 1;
+
+export const NAMESPACES = ["evm", "solana", "sui", "gpg", "auth", "sys"] as const;
 export type Namespace = (typeof NAMESPACES)[number];
 
 export const KINDS = ["req", "res", "event"] as const;
 export type Kind = (typeof KINDS)[number];
 
+/** Error codes a response can carry. EIP-1193 and JSON-RPC codes keep their meaning. */
+export const BridgeErrorCode = {
+  userRejected: 4001,
+  unsupportedMethod: 4200,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internal: -32000,
+  /** The page is not served over https (or loopback http), so it cannot sign in. */
+  pageNotHosted: -32001,
+  /** Keycloak refused the request; `data` carries `status`, `error`, `errorDescription`. */
+  keycloakRefused: -32002,
+  /** No wallet or signer for the requested family is available in the page. */
+  walletUnavailable: -32003,
+  /** The account has required actions left and no onboarding client was given. */
+  profileIncomplete: -32004,
+} as const;
+
 export interface BridgeError {
   code: number;
   message: string;
+  data?: unknown;
 }
 
 export interface BridgeMessage {
@@ -20,6 +44,25 @@ export interface BridgeMessage {
   error?: BridgeError;
 }
 
+/** What the WebView announces in `sys.ready`. */
+export interface BridgeReady {
+  protocol: number;
+  namespaces: Namespace[];
+}
+
+/** An error that crosses the bridge with its code and data intact, in either direction. */
+export class BridgeRequestError extends Error {
+  readonly code: number;
+  readonly data?: unknown;
+
+  constructor(code: number, message: string, data?: unknown) {
+    super(message);
+    this.name = "BridgeRequestError";
+    this.code = code;
+    if (data !== undefined) this.data = data;
+  }
+}
+
 export function isBridgeMessage(value: unknown): value is BridgeMessage {
   if (typeof value !== "object" || value === null) return false;
   const m = value as Record<string, unknown>;

package/src/index.ts

@@ -3,6 +3,8 @@ export {
   WalletProvider,
   useWeb3Config,
   defaultChains,
+  useWalletBridge,
+  type WalletBridgeContextValue,
   type WalletProviderProps,
   type Web3Config,
 } from "./providers";