@multiplatform.one/web3 7.24.0 → 7.25.0

package/src/bridge/AuthBridge.ts

@@ -0,0 +1,146 @@
+import type {
+  AuthBrowserLogin,
+  AuthKeycloakConfig,
+  AuthOnboardingConfig,
+  AuthSignInParams,
+  AuthSignInResult,
+  AuthTokens,
+  AuthTokensChanged,
+} from "./authTypes";
+import type { BridgeClient, RequestOptions } from "./BridgeClient";
+import { queryParams } from "./hosting";
+import { BridgeErrorCode, BridgeRequestError } from "./protocol";
+
+export interface AuthBridgeOptions {
+  /** Opens a URL in the system browser: `Linking.openURL` in React Native. */
+  openUrl(url: string): unknown;
+  /** Used when a call leaves `keycloak` or `onboarding` out. */
+  defaults?: { keycloak?: AuthKeycloakConfig; onboarding?: AuthOnboardingConfig };
+  /** Sign-in waits on the user in a wallet app. Default 10 minutes. */
+  signInTimeoutMs?: number;
+}
+
+export type AuthSignInOutcome = AuthSignInResult & {
+  /** Set on `profile-incomplete`: whether this call opened the onboarding page. */
+  onboardingOpened?: boolean;
+};
+
+export interface AuthSignInOptions extends RequestOptions {
+  /** Open Keycloak's onboarding in the system browser on `profile-incomplete`. Default true. */
+  openOnboarding?: boolean;
+}
+
+/**
+ * Native side of the `auth` namespace. Sign-in runs in the hosted WebView
+ * page, so the Keycloak nonce cookie and the message domain belong to that
+ * page's host; native gets the tokens back.
+ *
+ * A direct grant cannot run Keycloak's required actions (a new user's profile
+ * form). The page then answers `profile-incomplete` with Keycloak's browser
+ * login, and `signIn` opens it in the system browser, once per call and never
+ * in a loop. After the user finishes there, the next `signIn` succeeds.
+ */
+export class AuthBridge {
+  private pending: AuthBrowserLogin | null = null;
+
+  constructor(
+    private readonly bridge: BridgeClient,
+    private readonly options: AuthBridgeOptions,
+  ) {}
+
+  async signIn(
+    params: Partial<AuthSignInParams> = {},
+    options: AuthSignInOptions = {},
+  ): Promise<AuthSignInOutcome> {
+    const { openOnboarding = true, ...request } = options;
+    const onboarding = params.onboarding ?? this.options.defaults?.onboarding;
+    const keycloak = this.keycloak(params.keycloak);
+    const result = (await this.bridge.request(
+      "auth",
+      "signIn",
+      {
+        family: params.family ?? "eth",
+        keycloak,
+        ...(onboarding ? { onboarding } : {}),
+      },
+      { timeoutMs: this.options.signInTimeoutMs ?? 10 * 60_000, ...request },
+    )) as AuthSignInResult;
+    if (result.status !== "profile-incomplete") {
+      this.pending = null;
+      return result;
+    }
+    // The page picks the URL the system browser opens, so it has to be this
+    // realm's authorization endpoint and nothing else (no intent:, no tel:).
+    if (!isAuthorizationUrl(result.browserLogin?.url, keycloak)) {
+      throw new BridgeRequestError(
+        BridgeErrorCode.internal,
+        "auth.signIn: the page's browser login is not the realm's authorization endpoint",
+      );
+    }
+    this.pending = result.browserLogin;
+    if (!openOnboarding) return { ...result, onboardingOpened: false };
+    await this.options.openUrl(result.browserLogin.url);
+    return { ...result, onboardingOpened: true };
+  }
+
+  async refresh(
+    params: { keycloak?: AuthKeycloakConfig; refreshToken?: string } = {},
+  ): Promise<AuthTokens> {
+    const res = (await this.bridge.request("auth", "refresh", {
+      keycloak: this.keycloak(params.keycloak),
+      ...(params.refreshToken ? { refreshToken: params.refreshToken } : {}),
+    })) as { tokens: AuthTokens };
+    return res.tokens;
+  }
+
+  async logout(
+    params: { keycloak?: AuthKeycloakConfig; refreshToken?: string } = {},
+  ): Promise<void> {
+    await this.bridge.request("auth", "logout", {
+      keycloak: this.keycloak(params.keycloak),
+      ...(params.refreshToken ? { refreshToken: params.refreshToken } : {}),
+    });
+  }
+
+  /** The browser login the last `profile-incomplete` answer carried, until a sign-in succeeds. */
+  get pendingOnboarding(): AuthBrowserLogin | null {
+    return this.pending;
+  }
+
+  /**
+   * True when `url` is Keycloak sending the browser back from that onboarding
+   * (its `state` matches) with no `error`. A matching return, cancelled or
+   * not, ends the pending onboarding, so the same return never counts twice.
+   */
+  isOnboardingReturn(url: string): boolean {
+    if (this.pending === null) return false;
+    const params = queryParams(url);
+    if (params.state !== this.pending.state) return false;
+    this.pending = null;
+    return params.error === undefined;
+  }
+
+  /** `tokensChanged` fires whenever the page's tokens for a realm and client change. */
+  onTokensChanged(handler: (change: AuthTokensChanged) => void): () => void {
+    return this.bridge.on((ns, method, params) => {
+      if (ns === "auth" && method === "tokensChanged") handler(params as AuthTokensChanged);
+    });
+  }
+
+  private keycloak(keycloak: AuthKeycloakConfig | undefined): AuthKeycloakConfig {
+    const resolved = keycloak ?? this.options.defaults?.keycloak;
+    if (!resolved) {
+      throw new BridgeRequestError(
+        BridgeErrorCode.invalidParams,
+        "auth: pass keycloak { baseUrl, realm, clientId } or set it in the provider defaults",
+      );
+    }
+    return resolved;
+  }
+}
+
+function isAuthorizationUrl(url: unknown, keycloak: AuthKeycloakConfig): boolean {
+  if (typeof url !== "string") return false;
+  const realmUrl = `${keycloak.baseUrl.replace(/\/+$/, "")}/realms/${encodeURIComponent(keycloak.realm)}`;
+  return url.startsWith(`${realmUrl}/protocol/openid-connect/auth?`);
+}

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");
+  });
+});