@multiplatform.one/web3 7.24.0 → 7.26.0

package/src/providers/WalletProvider.native.tsx

@@ -4,25 +4,36 @@ import { createContext, useContext, useEffect, useMemo, useReducer, useRef, useS
 import { AppState, Linking, StyleSheet, View } from "react-native";
 import { WebView, type WebViewMessageEvent, type WebViewProps } from "react-native-webview";
 import { http, WagmiProvider, createConfig } from "wagmi";
+import { AuthBridge } from "../bridge/AuthBridge";
 import { BridgeClient } from "../bridge/BridgeClient";
+import { GpgBridge } from "../bridge/GpgBridge";
 import { SolanaBridge } from "../bridge/SolanaBridge";
+import { SuiBridge } from "../bridge/SuiBridge";
 import { createBridgeConnector } from "../bridge/bridgeConnector";
-import { createPostMessageTransport } from "../bridge/postMessageTransport";
-import { parseWalletReturn, shouldOpenExternally } from "./native/deepLink";
-import { buildConfigInjection, buildInjectScript } from "./native/inject";
+import { queryParams } from "../bridge/hosting";
+import { createNativeBridge } from "../bridge/nativeHost";
+import { createMemoryTransportPair } from "../bridge/transport";
+import {
+  decideNavigation,
+  decideNewWindow,
+  isUnderUrl,
+  parseWalletReturn,
+} from "./native/deepLink";
+import { buildConfigInjection } from "./native/inject";
 import { initialVisibility, nextVisibility } from "./native/visibility";
+import { WalletBridgeContext, type WalletBridgeContextValue } from "./walletBridge";
 import { type Web3Config, Web3ConfigContext, resolveChains } from "./walletConfig";
 
 type WebViewSource = NonNullable<WebViewProps["source"]>;
 
-// The wallet WebView must be loaded over a URL. WKWebView won't render the ~7MB
-// bundle inline via source={{html}} (size limit + it breaks the host render), so
-// there is no inline fallback: callers pass `webViewSource` or set `config.webViewUrl`
-// to a served copy of assets/webview.html.
+// The wallet WebView loads a HOSTED page (config.webViewUrl, https): the
+// sign-in message's domain and the Keycloak nonce cookie belong to the page's
+// host, so a file:// or inline page can never sign in, and WKWebView will not
+// render the multi-MB bundle inline anyway.
 export interface WalletProviderProps extends PropsWithChildren {
   config: Web3Config;
   queryClient?: QueryClient;
-  /** Override the WebView content (defaults to `config.webViewUrl`). */
+  /** Override the WebView content (defaults to `config.webViewUrl`); must be a hosted `{ uri }`. */
   webViewSource?: WebViewSource;
 }
 
@@ -43,6 +54,17 @@ export function useSolanaWallet(): SolanaWalletContextValue {
 
 const defaultQueryClient = new QueryClient();
 
+function pageUrlOf(config: Web3Config, source: WebViewSource | undefined): string | undefined {
+  if (!source) return config.webViewUrl || undefined;
+  const uri = (source as { uri?: unknown }).uri;
+  if (typeof uri !== "string") {
+    throw new Error(
+      "WalletProvider: webViewSource must be a hosted { uri }; an inline page has no host to sign in for",
+    );
+  }
+  return uri;
+}
+
 export function WalletProvider({
   children,
   config: web3Config,
@@ -50,68 +72,91 @@ export function WalletProvider({
   webViewSource,
 }: WalletProviderProps) {
   const webRef = useRef<WebView>(null);
-  const readyRef = useRef(false);
-  const outboundQueue = useRef<string[]>([]);
-
+  const [pageLoad, setPageLoad] = useState(0);
   const [visibility, dispatchVisibility] = useReducer(nextVisibility, initialVisibility);
   const [publicKey, setPublicKey] = useState<string | null>(null);
 
-  // One bridge for the WebView's lifetime. Outbound messages are queued until the
-  // WebView signals `sys/ready`, then flushed (the connect request often fires first).
-  const { bridge, solana, transport } = useMemo(() => {
-    const t = createPostMessageTransport((raw) => {
-      if (readyRef.current && webRef.current)
-        webRef.current.injectJavaScript(buildInjectScript(raw));
-      else outboundQueue.current.push(raw);
-    });
-    const client = new BridgeClient(t);
-    return { bridge: client, solana: new SolanaBridge(client), transport: t };
-  }, []);
+  // No guessed default: mounting the WebView against an unreachable URL (e.g.
+  // http://localhost on a physical device, where localhost is the phone) fires
+  // NSURLErrorDomain -1004 at app startup. With no URL the providers still
+  // mount and connect flows stay inert until WEB3_WEBVIEW_URL is set.
+  const pageUrl = pageUrlOf(web3Config, webViewSource);
+
+  // Throws on a page that is not hosted, which is the point.
+  const host = useMemo(
+    () =>
+      pageUrl
+        ? createNativeBridge({
+            pageUrl,
+            allowDevHosts: typeof __DEV__ !== "undefined" && __DEV__,
+            inject: (script) => webRef.current?.injectJavaScript(script),
+          })
+        : null,
+    [pageUrl],
+  );
+
+  const authDefaults = JSON.stringify(web3Config.auth ?? null);
+  const bridge = useMemo<WalletBridgeContextValue>(() => {
+    const client = host?.client ?? new BridgeClient(createMemoryTransportPair().a);
+    return {
+      client,
+      solana: new SolanaBridge(client),
+      sui: new SuiBridge(client),
+      gpg: new GpgBridge(client),
+      auth: new AuthBridge(client, {
+        openUrl: (url) => Linking.openURL(url),
+        defaults: JSON.parse(authDefaults) ?? undefined,
+      }),
+    };
+  }, [host, authDefaults]);
+  const { client } = bridge;
 
   // React to the WebView's lifecycle + account events.
   useEffect(() => {
-    const off = bridge.on((ns, method, params) => {
-      if (ns === "sys") {
-        if (method === "ready") {
-          readyRef.current = true;
-          const queued = outboundQueue.current.splice(0);
-          for (const raw of queued) webRef.current?.injectJavaScript(buildInjectScript(raw));
-        } else if (method === "modalOpen" || method === "modalClose") {
-          dispatchVisibility(method);
-        }
+    const off = client.on((ns, method, params) => {
+      if (ns === "sys" && (method === "modalOpen" || method === "modalClose")) {
+        dispatchVisibility(method);
       } else if (ns === "solana" && method === "accountChanged") {
         setPublicKey((params as { publicKey: string | null } | undefined)?.publicKey ?? null);
       }
     });
     return off;
-  }, [bridge]);
+  }, [client]);
 
   // On app foreground (e.g. return from a wallet deep link) ask the WebView to
   // re-report account/chain state.
   useEffect(() => {
     const sub = AppState.addEventListener("change", (state) => {
-      if (state === "active" && readyRef.current) {
-        void bridge.request("sys", "resync").catch(() => undefined);
+      if (state === "active" && host?.peer) {
+        void client.request("sys", "resync").catch(() => undefined);
       }
     });
     return () => sub.remove();
-  }, [bridge]);
+  }, [client, host]);
 
   // Inbound app-link returns from a wallet app: forward the params into the
   // WebView (the mock-wallet path consumes address/signature; a real wallet
-  // just needs the resync that AppState already triggers).
+  // just needs the resync that AppState already triggers). Only links under
+  // walletReturnUrl reach the page, and never Keycloak's onboarding return,
+  // whose code belongs to native.
+  const walletReturnUrl = web3Config.walletReturnUrl;
+  const onboardingReturnUrl = web3Config.auth?.onboarding?.redirectUri;
   useEffect(() => {
+    if (!walletReturnUrl) return;
     const handle = (url: string | null) => {
-      if (!url) return;
+      if (!url || !isUnderUrl(url, walletReturnUrl)) return;
+      if (onboardingReturnUrl && isUnderUrl(url, onboardingReturnUrl)) return;
+      const onboarding = bridge.auth.pendingOnboarding;
+      if (onboarding && queryParams(url).state === onboarding.state) return;
       const params = parseWalletReturn(url);
-      if (params) void bridge.request("sys", "deepLinkReturn", params).catch(() => undefined);
+      if (params) void client.request("sys", "deepLinkReturn", params).catch(() => undefined);
     };
     const sub = Linking.addEventListener("url", (event) => handle(event.url));
     void Linking.getInitialURL()
       .then(handle)
       .catch(() => undefined);
     return () => sub.remove();
-  }, [bridge]);
+  }, [bridge, client, walletReturnUrl, onboardingReturnUrl]);
 
   const wagmiConfig = useMemo(() => {
     // Same chain resolution as web (testnet filter + optional localnet dev
@@ -122,12 +167,12 @@ export function WalletProvider({
     return createConfig({
       chains,
       transports,
-      connectors: [createBridgeConnector(bridge)],
+      connectors: [createBridgeConnector(client)],
       multiInjectedProviderDiscovery: false,
     });
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
-    bridge,
+    client,
     web3Config.chains,
     web3Config.enableTestnets,
     web3Config.localnet,
@@ -135,58 +180,66 @@ export function WalletProvider({
   ]);
 
   const solanaValue = useMemo<SolanaWalletContextValue>(
-    () => ({ bridge: solana, publicKey, connected: publicKey !== null }),
-    [solana, publicKey],
+    () => ({ bridge: bridge.solana, publicKey, connected: publicKey !== null }),
+    [bridge.solana, publicKey],
   );
 
-  const onMessage = (event: WebViewMessageEvent) => transport.receive(event.nativeEvent.data);
+  const onMessage = (event: WebViewMessageEvent) =>
+    host?.receive(event.nativeEvent.data, event.nativeEvent.url);
 
-  // No inline HTML fallback: the bundle is too large for WKWebView source={{html}}.
-  // And no guessed-URL fallback either: mounting the WebView against an
-  // unreachable default (e.g. http://localhost:8099 on a physical device, where
-  // localhost is the phone) fires NSURLErrorDomain -1004 at app startup. When
-  // neither `webViewSource` nor `config.webViewUrl` resolves, skip the WebView
-  // entirely — providers still mount so wagmi/bridge consumers render; connect
-  // flows stay inert until WEB3_WEBVIEW_URL points at a served copy of
-  // @multiplatform.one/web3/assets/webview.html.
-  const resolvedSource =
-    webViewSource ?? (web3Config.webViewUrl ? { uri: web3Config.webViewUrl } : undefined);
+  const openExternally = (url: string) => void Linking.openURL(url).catch(() => undefined);
 
   return (
     <Web3ConfigContext.Provider value={web3Config}>
       <WagmiProvider config={wagmiConfig}>
         <QueryClientProvider client={queryClient}>
-          <SolanaWalletContext.Provider value={solanaValue}>
-            {children}
-            {resolvedSource && (
-              <View
-                style={visibility.sheetOpen ? styles.visible : styles.hidden}
-                pointerEvents={visibility.sheetOpen ? "auto" : "none"}
-              >
-                <WebView
-                  ref={webRef}
-                  source={resolvedSource}
-                  originWhitelist={["*"]}
-                  javaScriptEnabled
-                  domStorageEnabled
-                  onMessage={onMessage}
-                  onShouldStartLoadWithRequest={(req) => {
-                    // Hand wallet deep links to the OS; keep everything else in the WebView.
-                    if (shouldOpenExternally(req.url)) {
-                      void Linking.openURL(req.url).catch(() => undefined);
-                      return false;
-                    }
-                    return true;
-                  }}
-                  injectedJavaScriptBeforeContentLoaded={buildConfigInjection({
-                    ...web3Config,
-                    appUrl: web3Config.appUrl ?? "",
-                  })}
-                  style={styles.webview}
-                />
-              </View>
-            )}
-          </SolanaWalletContext.Provider>
+          <WalletBridgeContext.Provider value={bridge}>
+            <SolanaWalletContext.Provider value={solanaValue}>
+              {children}
+              {host && pageUrl && (
+                <View
+                  style={visibility.sheetOpen ? styles.visible : styles.hidden}
+                  pointerEvents={visibility.sheetOpen ? "auto" : "none"}
+                >
+                  <WebView
+                    key={pageLoad}
+                    ref={webRef}
+                    source={webViewSource ?? { uri: pageUrl }}
+                    originWhitelist={["*"]}
+                    javaScriptEnabled
+                    domStorageEnabled
+                    javaScriptCanOpenWindowsAutomatically
+                    onMessage={onMessage}
+                    onLoadStart={(event) => {
+                      if (host.navigated(event.nativeEvent.url)) setPageLoad((n) => n + 1);
+                    }}
+                    onShouldStartLoadWithRequest={(req) => {
+                      const decision = decideNavigation(req.url, host.pageOrigin, req.isTopFrame);
+                      if (decision === "external") openExternally(req.url);
+                      return decision === "load";
+                    }}
+                    onOpenWindow={(event) => {
+                      const url = event.nativeEvent.targetUrl;
+                      if (decideNewWindow(url) === "external") openExternally(url);
+                    }}
+                    onContentProcessDidTerminate={() => {
+                      host.pageGone();
+                      webRef.current?.reload();
+                    }}
+                    onRenderProcessGone={() => {
+                      host.pageGone();
+                      webRef.current?.reload();
+                    }}
+                    injectedJavaScriptBeforeContentLoaded={buildConfigInjection({
+                      ...web3Config,
+                      appUrl: web3Config.appUrl ?? "",
+                    })}
+                    style={styles.webview}
+                  />
+                </View>
+              )}
+            </SolanaWalletContext.Provider>
+          </WalletBridgeContext.Provider>
         </QueryClientProvider>
       </WagmiProvider>
     </Web3ConfigContext.Provider>
@@ -201,5 +254,6 @@ const styles = StyleSheet.create({
   webview: { flex: 1, backgroundColor: "transparent" },
 });
 
+export { useWalletBridge, type WalletBridgeContextValue } from "./walletBridge";
 export { defaultChains } from "./walletConfig";
 export { useWeb3Config, type Web3Config } from "./walletConfig";

package/src/providers/WalletProvider.tsx

@@ -3,7 +3,6 @@ import { ConnectKitProvider, SIWEProvider, type SIWEConfig, getDefaultConfig } f
 import { isWeb } from "@multiplatform.one/platform";
 import type { PropsWithChildren } from "react";
 import { useMemo } from "react";
-import type { Chain } from "viem";
 import { WagmiProvider, createConfig, http } from "wagmi";
 import { createMockConnector } from "./mockConnector";
 import { type Web3Config, Web3ConfigContext, resolveChains } from "./walletConfig";
@@ -108,5 +107,6 @@ export function WalletProvider({
   );
 }
 
+export { useWalletBridge, type WalletBridgeContextValue } from "./walletBridge";
 export { defaultChains } from "./walletConfig";
 export { useWeb3Config, type Web3Config } from "./walletConfig";

package/src/providers/index.ts

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

package/src/providers/native/deepLink.spec.ts

@@ -1,17 +1,28 @@
 import { describe, expect, it } from "vitest";
-import { parseWalletReturn, shouldOpenExternally } from "./deepLink";
+import {
+  decideNavigation,
+  decideNewWindow,
+  isUnderUrl,
+  parseWalletReturn,
+  shouldOpenExternally,
+} from "./deepLink";
 
 describe("shouldOpenExternally", () => {
   it("opens wallet custom schemes externally", () => {
     expect(shouldOpenExternally("metamask://connect/mwp?p=abc")).toBe(true);
     expect(shouldOpenExternally("phantom://v1/connect?app_url=...")).toBe(true);
     expect(shouldOpenExternally("ethereum:0xabc")).toBe(true);
+    expect(shouldOpenExternally("solflare://ul/v1/connect?app_url=x")).toBe(true);
+    expect(shouldOpenExternally("backpack://ul/v1/connect?app_url=x")).toBe(true);
   });
 
   it("opens known wallet universal links externally", () => {
     expect(shouldOpenExternally("https://metamask.app.link/connect/mwp?p=abc")).toBe(true);
     expect(shouldOpenExternally("https://link.trustwallet.com/open_url?url=...")).toBe(true);
     expect(shouldOpenExternally("https://phantom.app/ul/v1/connect")).toBe(true);
+    expect(shouldOpenExternally("https://solflare.com/ul/v1/signMessage")).toBe(true);
+    expect(shouldOpenExternally("https://backpack.app/ul/v1/connect")).toBe(true);
+    expect(shouldOpenExternally("HTTPS://Link.Metamask.App.Link/x")).toBe(true);
   });
 
   it("keeps internal / non-wallet navigations in the WebView", () => {
@@ -23,6 +34,53 @@ describe("shouldOpenExternally", () => {
   });
 });
 
+const page = "https://wallet.example.com";
+
+describe("decideNavigation", () => {
+  it("keeps the hosted page's own origin in the WebView", () => {
+    expect(decideNavigation("https://wallet.example.com/webview.html#x", page)).toBe("load");
+    expect(decideNavigation("about:blank", page)).toBe("load");
+  });
+
+  it("hands wallet links to the OS from any frame", () => {
+    expect(decideNavigation("metamask://connect/mwp?p=abc", page)).toBe("external");
+    expect(decideNavigation("https://metamask.app.link/connect", page, false)).toBe("external");
+    expect(decideNavigation("solflare://ul/v1/connect", page)).toBe("external");
+  });
+
+  it("never lets the top frame leave the page's origin", () => {
+    expect(decideNavigation("https://evil.example/phish", page)).toBe("external");
+    expect(decideNavigation("http://wallet.example.com/webview.html", page)).toBe("external");
+    expect(decideNavigation("mailto:help@example.com", page)).toBe("external");
+    expect(decideNavigation("javascript:alert(1)", page)).toBe("block");
+    expect(decideNavigation("file:///etc/hosts", page)).toBe("block");
+    expect(decideNavigation("data:text/html,<p>x</p>", page)).toBe("block");
+    expect(decideNavigation("intent://x#Intent;end", page)).toBe("block");
+  });
+
+  it("lets frames load what the page asks for", () => {
+    expect(decideNavigation("https://relay.example/frame", page, false)).toBe("load");
+    expect(decideNavigation("about:srcdoc", page, false)).toBe("load");
+  });
+});
+
+describe("decideNewWindow", () => {
+  it("opens wallet links and web pages outside the app", () => {
+    expect(decideNewWindow("https://metamask.app.link/connect/mwp?p=abc")).toBe("external");
+    expect(decideNewWindow("phantom://v1/connect")).toBe("external");
+    expect(decideNewWindow("backpack://ul/v1/connect")).toBe("external");
+    expect(decideNewWindow("https://solflare.com/ul/v1/connect")).toBe("external");
+    expect(decideNewWindow("https://metamask.io/download")).toBe("external");
+  });
+
+  it("drops script and local URLs", () => {
+    expect(decideNewWindow("javascript:void(0)")).toBe("block");
+    expect(decideNewWindow("about:blank")).toBe("block");
+    expect(decideNewWindow("file:///sdcard/x")).toBe("block");
+    expect(decideNewWindow("")).toBe("block");
+  });
+});
+
 describe("parseWalletReturn", () => {
   it("extracts query params from a return url", () => {
     expect(parseWalletReturn("mpoapp://wallet-return?address=0x1&signature=0xab")).toEqual({
@@ -39,3 +97,17 @@ describe("parseWalletReturn", () => {
     expect(parseWalletReturn("not a url at all %%%")).toBeNull();
   });
 });
+
+describe("isUnderUrl", () => {
+  it("matches the base and what sits below it on a boundary", () => {
+    const base = "myapp://wallet-return";
+    expect(isUnderUrl("myapp://wallet-return", base)).toBe(true);
+    expect(isUnderUrl("myapp://wallet-return?address=0x1", base)).toBe(true);
+    expect(isUnderUrl("myapp://wallet-return/done", base)).toBe(true);
+    expect(isUnderUrl("myapp://wallet-return#x", base)).toBe(true);
+    expect(isUnderUrl("myapp://wallet-returned", base)).toBe(false);
+    expect(isUnderUrl("myapp://auth?code=c", base)).toBe(false);
+    expect(isUnderUrl("myapp://wallet-return/x", "myapp://wallet-return/")).toBe(true);
+    expect(isUnderUrl("myapp://anything", "")).toBe(false);
+  });
+});

package/src/providers/native/deepLink.ts

@@ -1,16 +1,21 @@
+import { parseOrigin, queryParams } from "../../bridge/hosting";
+
 /**
- * Wallet hand-off URL classification for the native WebView. The WebView loads
- * trusted local content (file://); when its ConnectKit flow tries to
- * open a wallet app it navigates to a wallet custom-scheme or universal link —
- * those must be handed to the OS via Linking.openURL, not loaded in the WebView.
+ * Wallet hand-off for the native WebView. The WebView shows the hosted wallet
+ * page; when its flow opens a wallet app it navigates to a wallet custom
+ * scheme or universal link, or opens one in a new window. Those go to the OS
+ * through Linking.openURL and are never loaded in the WebView.
  */
 
-const WALLET_SCHEMES = new Set([
+/** Custom schemes that open a wallet app. docs/bridge-protocol.md lists the same. */
+export const WALLET_SCHEMES: readonly string[] = [
   "ethereum",
   "metamask",
   "rainbow",
   "trust",
   "phantom",
+  "solflare",
+  "backpack",
   "solana",
   "cbwallet",
   "ledgerlive",
@@ -19,43 +24,86 @@ const WALLET_SCHEMES = new Set([
   "okx",
   "imtokenv2",
   "wallet",
-]);
+];
 
-const WALLET_UNIVERSAL_HOSTS = [
+/** Hosts (and subdomains) of wallet universal links. docs/bridge-protocol.md lists the same. */
+export const WALLET_UNIVERSAL_HOSTS: readonly string[] = [
   "metamask.app.link",
   "link.trustwallet.com",
   "phantom.app",
+  "solflare.com",
+  "backpack.app",
   "rnbwapp.com",
   "go.cb-w.com",
   "ledger.com",
 ];
 
+const OS_SCHEMES = new Set(["mailto", "tel", "sms"]);
+
 /** True when a WebView navigation should be opened in an external wallet app. */
 export function shouldOpenExternally(url: string): boolean {
-  const scheme = url.slice(0, Math.max(0, url.indexOf(":"))).toLowerCase();
-  if (!scheme) return false;
-  if (WALLET_SCHEMES.has(scheme)) return true;
-  if (scheme === "https" || scheme === "http") {
-    try {
-      const host = new URL(url).hostname.toLowerCase();
-      return WALLET_UNIVERSAL_HOSTS.some((h) => host === h || host.endsWith(`.${h}`));
-    } catch {
-      return false;
-    }
+  const parsed = parseOrigin(url);
+  if (!parsed) return false;
+  if (WALLET_SCHEMES.includes(parsed.scheme)) return true;
+  if (parsed.scheme !== "https" && parsed.scheme !== "http") return false;
+  return WALLET_UNIVERSAL_HOSTS.some(
+    (h) => parsed.hostname === h || parsed.hostname.endsWith(`.${h}`),
+  );
+}
+
+/** `load` in the WebView, hand to the OS (`external`), or drop (`block`). */
+export type NavigationDecision = "load" | "external" | "block";
+
+/**
+ * Decide a navigation in the wallet WebView (`onShouldStartLoadWithRequest`).
+ * The top frame never leaves the hosted page's origin: the bridge would
+ * otherwise hand its messages, tokens included, to whatever page loaded next.
+ * Other http(s) pages open in the system browser; frames are the page's own
+ * business.
+ */
+export function decideNavigation(
+  url: string,
+  pageOrigin: string,
+  isTopFrame = true,
+): NavigationDecision {
+  if (shouldOpenExternally(url)) return "external";
+  const parsed = parseOrigin(url);
+  if (!parsed) return "block";
+  if (!isTopFrame) return "load";
+  if (parsed.origin === pageOrigin) return "load";
+  if (url.trim().toLowerCase() === "about:blank") return "load";
+  if (parsed.scheme === "https" || parsed.scheme === "http" || OS_SCHEMES.has(parsed.scheme)) {
+    return "external";
+  }
+  return "block";
+}
+
+/**
+ * Decide a `window.open` / `target=_blank` navigation (`onOpenWindow`). A new
+ * window never opens inside the app: wallet links and web pages go to the OS.
+ */
+export function decideNewWindow(url: string): NavigationDecision {
+  if (shouldOpenExternally(url)) return "external";
+  const parsed = parseOrigin(url);
+  if (!parsed) return "block";
+  if (parsed.scheme === "https" || parsed.scheme === "http" || OS_SCHEMES.has(parsed.scheme)) {
+    return "external";
   }
-  return false;
+  return "block";
 }
 
 /** Parse the query params of an inbound app-link return (e.g. from a wallet redirect). */
 export function parseWalletReturn(url: string): Record<string, string> | null {
-  try {
-    const parsed = new URL(url);
-    const out: Record<string, string> = {};
-    parsed.searchParams.forEach((value, key) => {
-      out[key] = value;
-    });
-    return out;
-  } catch {
-    return null;
-  }
+  return parseOrigin(url) ? queryParams(url) : null;
+}
+
+/**
+ * True when `url` is `base` or below it: `myapp://wallet-return?x=1` and
+ * `myapp://wallet-return/done` are under `myapp://wallet-return`,
+ * `myapp://wallet-returned` is not.
+ */
+export function isUnderUrl(url: string, base: string): boolean {
+  if (!base || !url.startsWith(base)) return false;
+  if (url.length === base.length || /[/?#]$/.test(base)) return true;
+  return "/?#".includes(url[base.length]);
 }

package/src/providers/native/inject.ts

@@ -1,14 +1,6 @@
 import type { Web3Config } from "../walletConfig";
 
-/**
- * Build the JS the native side runs inside the WebView (via `injectJavaScript`)
- * to deliver one inbound bridge message. The raw string is embedded with
- * JSON.stringify so quotes/newlines/backslashes survive intact. The trailing
- * `true;` is required by react-native-webview's injectJavaScript contract.
- */
-export function buildInjectScript(raw: string): string {
-  return `window.__bridgeReceive && window.__bridgeReceive(${JSON.stringify(raw)});true;`;
-}
+export { buildInjectScript } from "../../bridge/nativeHost";
 
 /**
  * Build the JS injected *before* the WebView content loads

package/src/providers/walletBridge.ts

@@ -0,0 +1,24 @@
+import { createContext, useContext } from "react";
+import type { AuthBridge } from "../bridge/AuthBridge";
+import type { BridgeClient } from "../bridge/BridgeClient";
+import type { GpgBridge } from "../bridge/GpgBridge";
+import type { SolanaBridge } from "../bridge/SolanaBridge";
+import type { SuiBridge } from "../bridge/SuiBridge";
+
+/** Every bridge namespace of the native WalletProvider's hosted wallet page. */
+export interface WalletBridgeContextValue {
+  client: BridgeClient;
+  solana: SolanaBridge;
+  sui: SuiBridge;
+  gpg: GpgBridge;
+  auth: AuthBridge;
+}
+
+export const WalletBridgeContext = createContext<WalletBridgeContextValue | null>(null);
+
+/** Native only: on web the wallet runs in the page itself and there is no bridge. */
+export function useWalletBridge(): WalletBridgeContextValue {
+  const value = useContext(WalletBridgeContext);
+  if (!value) throw new Error("useWalletBridge must be used within a native WalletProvider");
+  return value;
+}

package/src/providers/walletConfig.ts

@@ -1,6 +1,7 @@
 import { createContext, useContext } from "react";
 import type { Chain } from "viem";
 import { arbitrum, base, hardhat, mainnet, optimism, polygon, sepolia } from "wagmi/chains";
+import type { AuthKeycloakConfig, AuthOnboardingConfig } from "../bridge/authTypes";
 
 /**
  * Shared config seam for both platform variants of WalletProvider. Keeping the
@@ -43,8 +44,21 @@ export interface Web3Config {
   suiRpcUrl?: string;
   /** E2E only (native): route connect through the in-WebView mock wallet. */
   mockWallet?: boolean;
-  /** Native: URL serving the wallet WebView HTML (preferred over the inline string). */
+  /**
+   * Native: https URL serving `assets/webview.html`. Its host is the sign-in
+   * message's domain, so it must be in the realm's `siww.allowedDomains` /
+   * `wallet.allowedDomains` and in the client's web origins. Plain http is
+   * accepted only on loopback and 10.0.2.2, in development builds.
+   */
   webViewUrl?: string;
+  /**
+   * Native: the app link wallets send the user back to, e.g.
+   * `myapp://wallet-return`. Returns under it reach the page as
+   * `sys.deepLinkReturn`; no other app link does.
+   */
+  walletReturnUrl?: string;
+  /** Native: the Keycloak client `useWalletBridge().auth` signs in with when a call names none. */
+  auth?: { keycloak?: AuthKeycloakConfig; onboarding?: AuthOnboardingConfig };
 }
 
 /**