@multiplatform.one/web3 7.24.0 → 7.25.0

package/dist/jsx/providers/walletBridge.mjs

@@ -0,0 +1,9 @@
+import { createContext, useContext } from "react";
+const WalletBridgeContext = createContext(null);
+function useWalletBridge() {
+  const value = useContext(WalletBridgeContext);
+  if (!value) throw new Error("useWalletBridge must be used within a native WalletProvider");
+  return value;
+}
+export { WalletBridgeContext, useWalletBridge };
+//# sourceMappingURL=walletBridge.mjs.map

package/dist/jsx/providers/walletBridge.mjs.map

@@ -0,0 +1 @@
+{"version":3,"names":["createContext","useContext","WalletBridgeContext","useWalletBridge","value","Error"],"sources":["../../../src/providers/walletBridge.ts"],"sourcesContent":[null],"mappings":"AAAA,SAASA,aAAA,EAAeC,UAAA,QAAkB;AAgBnC,MAAMC,mBAAA,GAAsBF,aAAA,CAA+C,IAAI;AAG/E,SAASG,gBAAA,EAA4C;EAC1D,MAAMC,KAAA,GAAQH,UAAA,CAAWC,mBAAmB;EAC5C,IAAI,CAACE,KAAA,EAAO,MAAM,IAAIC,KAAA,CAAM,6DAA6D;EACzF,OAAOD,KAAA;AACT","ignoreList":[]}

package/dist/jsx/providers/walletBridge.native.js

@@ -0,0 +1,38 @@
+"use strict";
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all) __defProp(target, name, {
+    get: all[name],
+    enumerable: true
+  });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    });
+  }
+  return to;
+};
+var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
+  value: true
+}), mod);
+var walletBridge_exports = {};
+__export(walletBridge_exports, {
+  WalletBridgeContext: () => WalletBridgeContext,
+  useWalletBridge: () => useWalletBridge
+});
+module.exports = __toCommonJS(walletBridge_exports);
+var import_react = require("react");
+var WalletBridgeContext = (0, import_react.createContext)(null);
+function useWalletBridge() {
+  var value = (0, import_react.useContext)(WalletBridgeContext);
+  if (!value) throw new Error("useWalletBridge must be used within a native WalletProvider");
+  return value;
+}
+//# sourceMappingURL=walletBridge.native.js.map

package/dist/jsx/providers/walletBridge.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["__defProp","Object","defineProperty","__getOwnPropDesc","getOwnPropertyDescriptor","__getOwnPropNames","getOwnPropertyNames","__hasOwnProp","prototype","hasOwnProperty","__export","target","all","name"],"sources":["../../../src/providers/walletBridge.ts"],"sourcesContent":[null],"mappings":"AAAA,YAAS;;AAgBF,IAAAA,SAAM,GAAAC,MAAA,CAAAC,cAAsB;AAG5B,IAAAC,gBAAS,GAAAF,MAA4C,CAAAG,wBAAA;AAC1D,IAAAC,iBAAc,GAAAJ,MAAW,CAAAK,mBAAmB;AAC5C,IAAAC,YAAY,GAAAN,MAAU,CAAAO,SAAM,CAAAC,cAAA;AAC5B,IAAAC,QAAO,GAAAA,CAAAC,MAAA,EAAAC,GAAA;EACT,SAAAC,IAAA,IAAAD,GAAA,E","ignoreList":[]}

package/dist/jsx/providers/walletConfig.mjs.map

@@ -1 +1 @@
-{"version":3,"names":["createContext","useContext","arbitrum","base","hardhat","mainnet","optimism","polygon","sepolia","defaultChains","resolveChains","config","chains","enableTestnets","localnet","localnetRpcUrl","active","filter","chain","testnet","length","local","rpcUrls","default","http","id","Web3ConfigContext","useWeb3Config","Error"],"sources":["../../../src/providers/walletConfig.ts"],"sourcesContent":[null],"mappings":"AAAA,SAASA,aAAA,EAAeC,UAAA,QAAkB;AAE1C,SAASC,QAAA,EAAUC,IAAA,EAAMC,OAAA,EAASC,OAAA,EAASC,QAAA,EAAUC,OAAA,EAASC,OAAA,QAAe;AAQtE,MAAMC,aAAA,GAA8C,CACzDJ,OAAA,EACAE,OAAA,EACAD,QAAA,EACAJ,QAAA,EACAC,IAAA,EACAK,OAAA,CACF;AAsCO,SAASE,cAAcC,MAAA,EAAkD;EAC9E,MAAM;IACJC,MAAA,GAASH,aAAA;IACTI,cAAA,GAAiB;IACjBC,QAAA,GAAW;IACXC;EACF,IAAIJ,MAAA;EACJ,IAAIK,MAAA,GAAkBH,cAAA,GAAiB,CAAC,GAAGD,MAAM,IAAIA,MAAA,CAAOK,MAAA,CAAQC,KAAA,IAAU,CAACA,KAAA,CAAMC,OAAO;EAC5F,IAAIH,MAAA,CAAOI,MAAA,KAAW,GAAGJ,MAAA,GAAS,CAAC,GAAGJ,MAAM;EAC5C,IAAIE,QAAA,EAAU;IACZ,MAAMO,KAAA,GAAeN,cAAA,GACjB;MAAE,GAAGX,OAAA;MAASkB,OAAA,EAAS;QAAEC,OAAA,EAAS;UAAEC,IAAA,EAAM,CAACT,cAAc;QAAE;MAAE;IAAE,IAC/DX,OAAA;IACJY,MAAA,GAAS,CAACK,KAAA,EAAO,GAAGL,MAAA,CAAOC,MAAA,CAAQC,KAAA,IAAUA,KAAA,CAAMO,EAAA,KAAOrB,OAAA,CAAQqB,EAAE,CAAC;EACvE;EACA,OAAOT,MAAA;AACT;AAEO,MAAMU,iBAAA,GAAoB1B,aAAA,CAAiC,IAAI;AAE/D,SAAS2B,cAAA,EAA4B;EAC1C,MAAMhB,MAAA,GAASV,UAAA,CAAWyB,iBAAiB;EAC3C,IAAI,CAACf,MAAA,EAAQ;IACX,MAAM,IAAIiB,KAAA,CAAM,oDAAoD;EACtE;EACA,OAAOjB,MAAA;AACT","ignoreList":[]}
+{"version":3,"names":["createContext","useContext","arbitrum","base","hardhat","mainnet","optimism","polygon","sepolia","defaultChains","resolveChains","config","chains","enableTestnets","localnet","localnetRpcUrl","active","filter","chain","testnet","length","local","rpcUrls","default","http","id","Web3ConfigContext","useWeb3Config","Error"],"sources":["../../../src/providers/walletConfig.ts"],"sourcesContent":[null],"mappings":"AAAA,SAASA,aAAA,EAAeC,UAAA,QAAkB;AAE1C,SAASC,QAAA,EAAUC,IAAA,EAAMC,OAAA,EAASC,OAAA,EAASC,QAAA,EAAUC,OAAA,EAASC,OAAA,QAAe;AAStE,MAAMC,aAAA,GAA8C,CACzDJ,OAAA,EACAE,OAAA,EACAD,QAAA,EACAJ,QAAA,EACAC,IAAA,EACAK,OAAA,CACF;AAmDO,SAASE,cAAcC,MAAA,EAAkD;EAC9E,MAAM;IACJC,MAAA,GAASH,aAAA;IACTI,cAAA,GAAiB;IACjBC,QAAA,GAAW;IACXC;EACF,IAAIJ,MAAA;EACJ,IAAIK,MAAA,GAAkBH,cAAA,GAAiB,CAAC,GAAGD,MAAM,IAAIA,MAAA,CAAOK,MAAA,CAAQC,KAAA,IAAU,CAACA,KAAA,CAAMC,OAAO;EAC5F,IAAIH,MAAA,CAAOI,MAAA,KAAW,GAAGJ,MAAA,GAAS,CAAC,GAAGJ,MAAM;EAC5C,IAAIE,QAAA,EAAU;IACZ,MAAMO,KAAA,GAAeN,cAAA,GACjB;MAAE,GAAGX,OAAA;MAASkB,OAAA,EAAS;QAAEC,OAAA,EAAS;UAAEC,IAAA,EAAM,CAACT,cAAc;QAAE;MAAE;IAAE,IAC/DX,OAAA;IACJY,MAAA,GAAS,CAACK,KAAA,EAAO,GAAGL,MAAA,CAAOC,MAAA,CAAQC,KAAA,IAAUA,KAAA,CAAMO,EAAA,KAAOrB,OAAA,CAAQqB,EAAE,CAAC;EACvE;EACA,OAAOT,MAAA;AACT;AAEO,MAAMU,iBAAA,GAAoB1B,aAAA,CAAiC,IAAI;AAE/D,SAAS2B,cAAA,EAA4B;EAC1C,MAAMhB,MAAA,GAASV,UAAA,CAAWyB,iBAAiB;EAC3C,IAAI,CAACf,MAAA,EAAQ;IACX,MAAM,IAAIiB,KAAA,CAAM,oDAAoD;EACtE;EACA,OAAOjB,MAAA;AACT","ignoreList":[]}

package/dist/jsx/providers/walletConfig.native.js.map

@@ -1 +1 @@
-{"version":3,"names":["__defProp","Object","defineProperty","__getOwnPropDesc","getOwnPropertyDescriptor","__getOwnPropNames","getOwnPropertyNames","__hasOwnProp","prototype","hasOwnProperty","__export","target","all","name","get","enumerable","__copyProps","to","from","except","desc","key","call","__toCommonJS","mod","value","walletConfig_exports","Web3ConfigContext","defaultChains","resolveChains","useWeb3Config","module","exports","import_react","require","import_chains","mainnet","polygon","optimism","arbitrum"],"sources":["../../../src/providers/walletConfig.ts"],"sourcesContent":[null],"mappings":"AAAA,YAAS;;AAET,IAAAA,SAAS,GAAAC,MAAU,CAAAC,cAAe;AAQ3B,IAAAC,gBAAM,GAA8CF,MAAA,CAAAG,wBAAA;AAAA,IACzDC,iBAAA,GAAAJ,MAAA,CAAAK,mBAAA;AAAA,IACAC,YAAA,GAAAN,MAAA,CAAAO,SAAA,CAAAC,cAAA;AAAA,IACAC,QAAA,GAAAA,CAAAC,MAAA,EAAAC,GAAA;EACA,SAAAC,IAAA,IAAAD,GAAA,EACAZ,SAAA,CAAAW,MAAA,EAAAE,IAAA;IAAAC,GAAA,EAAAF,GAAA,CAAAC,IAAA;IAAAE,UAAA;EAAA;AAAA;AAEF,IAAAC,WAAA,GAAAA,CAAAC,EAAA,EAAAC,IAAA,EAAAC,MAAA,EAAAC,IAAA;EAsCO,IAAAF,IAAS,WAAAA,IAAc,aAAkD,WAAAA,IAAA;IAC9E,KAAM,IAAAG,GAAA,IAAAhB,iBAAA,CAAAa,IAAA,GACJ,KAAAX,YAAS,CAAAe,IAAA,CAAAL,EAAA,EAAAI,GAAA,KAAAA,GAAA,KAAAF,MAAA,EACTnB,SAAA,CAAAiB,EAAA,EAAiBI,GAAA;MAAAP,GAAA,EAAAA,CAAA,KAAAI,IAAA,CAAAG,GAAA;MAAAN,UAAA,IAAAK,IAAA,GAAAjB,gBAAA,CAAAe,IAAA,EAAAG,GAAA,MAAAD,IAAA,CAAAL;IAAA;EAAA;EACN,OACXE,EAAA;AAAA;AAEF,IAAAM,YAAsB,GAAAC,GAAA,IAAAR,WAAqB,CAAAhB,SAAU,KAAO,YAAQ;EAAAyB,KAAW;AAAM,IAAOD,GAAA;AAC5F,IAAAE,oBAAsB,GAAG;AACzBhB,QAAI,CAAAgB,oBAAU;EACZC,iBAAqB,EAAAA,CAAA,KAAAA,iBACZ;EAETC,aAAU,EAAAA,CAAA,KAAOA,aAAU;EAC7BC,aAAA,EAAAA,CAAA,KAAAA,aAAA;EACAC,aAAO,EAAAA,CAAA,KAAAA;AACT;AAEOC,MAAM,CAAAC,OAAA,GAAAT,YAAoB,CAAAG,oBAAqC;AAE/D,IAAAO,YAAS,GAAAC,OAA4B;AAC1C,IAAAC,aAAe,GAAAD,OAAA,CAAW;AAC1B,IAAAN,aAAa,IACXO,aAAU,CAAAC,OAAM,EAClBD,aAAA,CAAAE,OAAA,EACAF,aAAO,CAAAG,QAAA,EACTH,aAAA,CAAAI,QAAA,E","ignoreList":[]}
+{"version":3,"names":["__defProp","Object","defineProperty","__getOwnPropDesc","getOwnPropertyDescriptor","__getOwnPropNames","getOwnPropertyNames","__hasOwnProp","prototype","hasOwnProperty","__export","target","all","name","get","enumerable","__copyProps","to","from","except","desc","key","call","__toCommonJS","mod","value","walletConfig_exports","Web3ConfigContext","defaultChains","resolveChains","useWeb3Config","module","exports","import_react","require","import_chains","mainnet","polygon","optimism","arbitrum"],"sources":["../../../src/providers/walletConfig.ts"],"sourcesContent":[null],"mappings":"AAAA,YAAS;;AAET,IAAAA,SAAS,GAAAC,MAAU,CAAAC,cAAe;AAS3B,IAAAC,gBAAM,GAA8CF,MAAA,CAAAG,wBAAA;AAAA,IACzDC,iBAAA,GAAAJ,MAAA,CAAAK,mBAAA;AAAA,IACAC,YAAA,GAAAN,MAAA,CAAAO,SAAA,CAAAC,cAAA;AAAA,IACAC,QAAA,GAAAA,CAAAC,MAAA,EAAAC,GAAA;EACA,SAAAC,IAAA,IAAAD,GAAA,EACAZ,SAAA,CAAAW,MAAA,EAAAE,IAAA;IAAAC,GAAA,EAAAF,GAAA,CAAAC,IAAA;IAAAE,UAAA;EAAA;AAAA;AAEF,IAAAC,WAAA,GAAAA,CAAAC,EAAA,EAAAC,IAAA,EAAAC,MAAA,EAAAC,IAAA;EAmDO,IAAAF,IAAS,WAAAA,IAAc,aAAkD,WAAAA,IAAA;IAC9E,KAAM,IAAAG,GAAA,IAAAhB,iBAAA,CAAAa,IAAA,GACJ,KAAAX,YAAS,CAAAe,IAAA,CAAAL,EAAA,EAAAI,GAAA,KAAAA,GAAA,KAAAF,MAAA,EACTnB,SAAA,CAAAiB,EAAA,EAAiBI,GAAA;MAAAP,GAAA,EAAAA,CAAA,KAAAI,IAAA,CAAAG,GAAA;MAAAN,UAAA,IAAAK,IAAA,GAAAjB,gBAAA,CAAAe,IAAA,EAAAG,GAAA,MAAAD,IAAA,CAAAL;IAAA;EAAA;EACN,OACXE,EAAA;AAAA;AAEF,IAAAM,YAAsB,GAAAC,GAAA,IAAAR,WAAqB,CAAAhB,SAAU,KAAO,YAAQ;EAAAyB,KAAW;AAAM,IAAOD,GAAA;AAC5F,IAAAE,oBAAsB,GAAG;AACzBhB,QAAI,CAAAgB,oBAAU;EACZC,iBAAqB,EAAAA,CAAA,KAAAA,iBACZ;EAETC,aAAU,EAAAA,CAAA,KAAOA,aAAU;EAC7BC,aAAA,EAAAA,CAAA,KAAAA,aAAA;EACAC,aAAO,EAAAA,CAAA,KAAAA;AACT;AAEOC,MAAM,CAAAC,OAAA,GAAAT,YAAoB,CAAAG,oBAAqC;AAE/D,IAAAO,YAAS,GAAAC,OAA4B;AAC1C,IAAAC,aAAe,GAAAD,OAAA,CAAW;AAC1B,IAAAN,aAAa,IACXO,aAAU,CAAAC,OAAM,EAClBD,aAAA,CAAAE,OAAA,EACAF,aAAO,CAAAG,QAAA,EACTH,aAAA,CAAAI,QAAA,E","ignoreList":[]}

package/docs/bridge-protocol.md

@@ -0,0 +1,485 @@
+# mpo web3 WebView bridge protocol
+
+Protocol version: 1
+
+A native app shows mpo web3's wallet UI by loading a hosted web page in a
+WebView and talking to it through JSON messages. The page owns every wallet
+and chain interaction: the connect modal, MetaMask Connect, Phantom, the
+Sui and GPG signers, and the Keycloak wallet sign-in. The app never links a
+wallet SDK. This document is the whole contract, so a Kotlin or Swift host can
+implement it without reading the TypeScript. The React Native host in
+`src/providers/WalletProvider.native.tsx` and `src/bridge/nativeHost.ts` is one
+implementation of it.
+
+Terms: the **host** is the native app, the **page** is the hosted
+`webview.html` running inside the host's WebView.
+
+## 1. The page must be hosted
+
+Serve `@multiplatform.one/web3/assets/webview.html` over https and load it
+by URL. Never load it from `file:`, `data:`, an asset loader or inline HTML.
+
+- The sign-in message's `domain` is the page's host
+  (`window.location.host`). A `file:` page has an empty host, and the
+  Keycloak wallet SPI refuses a message whose domain is not allowed.
+- Add the page's host (with its port, if not 443) to the realm's
+  `siww.allowedDomains` (SHC Keycloak) or `wallet.allowedDomains` (mpo
+  Keycloak).
+- Add the page's origin to the Keycloak client's **Web origins**. The page
+  calls Keycloak with `fetch` and credentials, so CORS must allow it.
+- The nonce is bound to a `KEYCLOAK_SESSION_SIWW` / `KEYCLOAK_SESSION_WALLET`
+  cookie. When the page and Keycloak are on different sites that cookie has to
+  be `SameSite=None; Secure`, which Keycloak only sends over https.
+- Plain http is accepted in development builds only, on `localhost`,
+  `127.0.0.1`, `[::1]` and `10.0.2.2` (the Android emulator's address for the
+  host machine). Reach a dev server on the host from an emulator with
+  `adb reverse tcp:8099 tcp:8099` and `http://localhost:8099/webview.html`. A
+  release build refuses them: on a phone any app can listen on a loopback
+  port, and `10.0.2.2` is an ordinary network address.
+
+The page refuses `auth` requests with `-32001` when it is not hosted, and the
+React Native host refuses to mount a WebView for such a URL.
+
+## 2. Transport
+
+All messages are JSON text, one message per string.
+
+| direction    | mechanism                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------- |
+| page to host | the page calls `window.ReactNativeWebView.postMessage(text)`                                |
+| host to page | the host evaluates the delivery script below                                                |
+| host config  | before the page's scripts run, the host sets `window.__web3Config = <object>` (section 2.1) |
+
+The delivery script hands one message to the page only while the top frame
+is still on the page's origin:
+
+```js
+window.location.origin === "<page origin>" &&
+  window.__bridgeReceive &&
+  window.__bridgeReceive(<text as JS string>);
+```
+
+`<text as JS string>` is the message text encoded as a JavaScript string
+literal. A JSON encoder's string output is one (escape `U+2028` and `U+2029`
+as well if your encoder does not).
+
+Accept a page message only when it comes from the top frame on the page's
+origin. Drop one whose sending frame or origin the WebView does not report:
+a cross-origin frame inside the page (an ad, a wallet SDK's iframe) can call
+the same function, and a forged `tokensChanged` would sign the user in as
+someone else.
+
+Write the page origin the way `location.origin` does: lowercase scheme and
+host, punycode for an internationalized host, and the port only when it is
+not the scheme's default (`WKSecurityOrigin.port` is 0 for the default).
+
+The React Native host in this package is looser than this section asks:
+react-native-webview reports the sending frame's URL but not whether it is
+the top frame, so it accepts same-origin frames, and on an Android WebView
+without `WEB_MESSAGE_LISTENER` it sees the top frame's URL for every frame.
+The origin check in the delivery script still holds there.
+
+**Android (Kotlin).** Receive page messages with
+`WebViewCompat.addWebMessageListener(webView, "ReactNativeWebView", setOf(pageOrigin), listener)`,
+which gives the page a `ReactNativeWebView.postMessage(text)`, and in the
+listener accept a message only when `isMainFrame` is true and `sourceOrigin`
+is the page's origin. Do not use `addJavascriptInterface`: it is exposed to
+every frame and does not say which one called. On a WebView without
+`WebViewFeature.WEB_MESSAGE_LISTENER`, do not run the bridge. Deliver host
+messages with `webView.evaluateJavascript(...)` on the UI thread. Inject the
+config with a document-start script
+(`WebViewCompat.addDocumentStartJavaScript`, allowed origins `setOf(pageOrigin)`).
+
+**iOS (Swift).** Register a `WKScriptMessageHandler` under the name
+`ReactNativeWebView` and accept a message only when
+`message.frameInfo.isMainFrame` is true and `message.frameInfo.securityOrigin`
+is the page's (protocol, host and port). Add this user script at document
+start, main frame only, so the page finds the function it calls:
+
+```js
+window.ReactNativeWebView = {
+  postMessage: (text) => window.webkit.messageHandlers.ReactNativeWebView.postMessage(text),
+};
+```
+
+Deliver host messages with `webView.evaluateJavaScript(...)`.
+
+### 2.1 Config
+
+```js
+window.__web3Config = {
+  appName: "QuickCam",
+  appDescription: "Connect your wallet",
+  appUrl: "https://quickcam.app",
+  appIcon: "https://quickcam.app/icon.png",
+  solanaRpcUrl: "https://api.mainnet-beta.solana.com",
+  mockWallet: false,
+};
+```
+
+Every field but `appName` is optional, and the page ignores fields it does
+not know (the React Native host passes its whole `Web3Config`).
+`mockWallet: true` replaces every
+wallet with an in-page test signer that produces real signatures; it is for
+end-to-end tests and must never be set in a release build.
+
+## 3. Envelope
+
+| field    | type   | present on       | meaning                                                 |
+| -------- | ------ | ---------------- | ------------------------------------------------------- |
+| `id`     | string | `req`, `res`     | chosen by the requester, echoed by the response         |
+| `ns`     | string | always           | namespace: `evm`, `solana`, `sui`, `gpg`, `auth`, `sys` |
+| `kind`   | string | always           | `req`, `res` or `event`                                 |
+| `method` | string | `req`, `event`   | the operation or event name                             |
+| `params` | any    | `req`, `event`   | method input, omitted when there is none                |
+| `result` | any    | `res` on success | method output (`null` when there is nothing to return)  |
+| `error`  | object | `res` on failure | `{ "code": number, "message": string, "data"?: any }`   |
+
+Rules:
+
+- The host sends `req`; the page answers each one with exactly one `res` with
+  the same `id`, in whatever order they finish. The page sends `event`s at any
+  time; events carry no `id` and get no answer.
+- `id` must be unique among the host's requests in flight. Any string works;
+  the React Native host uses a counter.
+- Drop any text that is not JSON, and any message whose `ns` or `kind` is not
+  in the lists above. Ignore a `res` whose `id` you are not waiting for, and
+  events and fields you do not know.
+- Bytes cross as standard base64 with padding, never as arrays.
+- A request that waits on the user (a wallet signature, a GPG paste) can take
+  minutes. The React Native host times out sign-in after 10 minutes and GPG
+  after 15; plain requests after 2.
+
+Request and response:
+
+```json
+{ "id": "7", "ns": "evm", "kind": "req", "method": "eth_chainId" }
+```
+
+```json
+{ "id": "7", "ns": "evm", "kind": "res", "result": "0x2105" }
+```
+
+Error response:
+
+```json
+{
+  "id": "8",
+  "ns": "evm",
+  "kind": "res",
+  "error": { "code": 4001, "message": "User rejected the request." }
+}
+```
+
+Event:
+
+```json
+{
+  "ns": "evm",
+  "kind": "event",
+  "method": "accountsChanged",
+  "params": ["0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"]
+}
+```
+
+## 4. Lifecycle
+
+1. The host loads the page URL with the config injected.
+2. The page registers its namespaces and sends `sys.ready`. Until then the
+   host queues its requests; it must not deliver any before `ready`.
+3. The host reads `protocol` and `namespaces` from `ready`. A page whose
+   `protocol` is higher than the host supports may have changed a message the
+   host relies on: warn, and do not call methods the host does not know.
+   Before calling a namespace, check that it is listed; a page built without
+   it answers `-32601`.
+4. On a reload the page sends `ready` again. Requests in flight when the page
+   went away never get an answer: fail them on the host (a reload, a crash,
+   `onRenderProcessGone` / `webViewWebContentProcessDidTerminate`).
+5. When the app returns to the foreground (typically back from a wallet app)
+   the host sends `sys.resync` so the page re-reports account state.
+
+```json
+{
+  "ns": "sys",
+  "kind": "event",
+  "method": "ready",
+  "params": { "protocol": 1, "namespaces": ["evm", "solana", "sui", "gpg", "auth", "sys"] }
+}
+```
+
+Versioning: `protocol` changes only for a change an existing host could not
+ignore (a renamed method, a changed result shape, a different transport). New
+namespaces, methods, events, optional params and result fields are added
+without a bump, which is why hosts ignore what they do not know.
+
+## 5. Navigation and wallet hand-off
+
+Wallets are separate apps. The page opens them by navigating to a wallet URL
+or opening one in a new window; the host must hand those to the OS and must
+keep the page itself in place.
+
+Top-frame navigations (`shouldOverrideUrlLoading` /
+`decidePolicyFor navigationAction`):
+
+| URL                                                             | host does                |
+| --------------------------------------------------------------- | ------------------------ |
+| a wallet scheme or wallet universal link (lists below)          | open with the OS, cancel |
+| same origin as the page, or `about:blank`                       | allow                    |
+| any other `http`/`https` URL, `mailto:`, `tel:`, `sms:`         | open with the OS, cancel |
+| anything else (`javascript:`, `file:`, `data:`, `intent:`, ...) | cancel                   |
+
+The top frame must never leave the page's origin: the page's messages carry
+tokens, and a foreign page would receive them. Android does not ask
+`shouldOverrideUrlLoading` about a POST (a form with `target=_top`), so also
+watch the top frame start loading (`onPageStarted` /
+`didStartProvisionalNavigation`): a document on another origin means the page
+is gone. Fail what is in flight and deliver nothing until the next
+`sys.ready`, then load the page's URL again (not a reload, which would reload
+the foreign document), twice at most until the page announces itself. Sub-frame loads are the page's business; allow them
+unless they are wallet links.
+
+New windows (`window.open`, `target=_blank`; `onCreateWindow` /
+`createWebViewWith`) never open in the app: wallet links and `http`/`https`
+URLs go to the OS, everything else is dropped. Allow the page to open windows
+without a user gesture (`javaScriptCanOpenWindowsAutomatically`): a wallet
+link is often opened after an `await`.
+
+Wallet schemes: `ethereum`, `metamask`, `rainbow`, `trust`, `phantom`,
+`solflare`, `backpack`, `solana`, `cbwallet`, `ledgerlive`, `zerion`,
+`rabby`, `okx`, `imtokenv2`, `wallet`.
+
+Wallet universal-link hosts (and their subdomains): `metamask.app.link`,
+`link.trustwallet.com`, `phantom.app`, `solflare.com`, `backpack.app`,
+`rnbwapp.com`, `go.cb-w.com`, `ledger.com`.
+
+A wallet that sends the user back opens the app's own deep link. The host may
+forward the query parameters of its wallet-return link with
+`sys.deepLinkReturn`, and only that link: never Keycloak's onboarding
+redirect, whose `code` is the host's. MetaMask Connect needs only the
+`resync`.
+
+## 6. Errors
+
+| code     | meaning                                                                                           |
+| -------- | ------------------------------------------------------------------------------------------------- |
+| `4001`   | the user rejected the request (in the wallet, or by cancelling the GPG paste)                     |
+| `4200`   | the wallet does not support the method                                                            |
+| `-32601` | unknown namespace or method                                                                       |
+| `-32602` | invalid params                                                                                    |
+| `-32000` | any other failure; `message` says what                                                            |
+| `-32001` | the page is not hosted (section 1), so it cannot sign in                                          |
+| `-32002` | Keycloak refused; `data` is `{ "status": number, "error"?: string, "errorDescription"?: string }` |
+| `-32003` | the page has no wallet or signer for the requested family                                         |
+| `-32004` | the account has required actions left and no `onboarding` client was given                        |
+
+`evm` errors are whatever the wallet's EIP-1193 provider threw, with its code.
+
+## 7. Namespaces
+
+### `sys`
+
+| method           | direction           | params                                          | result |
+| ---------------- | ------------------- | ----------------------------------------------- | ------ |
+| `ready`          | event, page to host | `{ protocol, namespaces }`                      |        |
+| `modalOpen`      | event, page to host | none                                            |        |
+| `modalClose`     | event, page to host | none                                            |        |
+| `resync`         | req                 | none                                            | `null` |
+| `deepLinkReturn` | req                 | the return URL's query, as an object of strings | `null` |
+
+Keep the WebView mounted for the app's whole life but invisible, and show it
+full screen between `modalOpen` and `modalClose`: the page raises them around
+the connect modal and the GPG paste box. A hidden WebView keeps its wallet
+sessions; destroying it drops them.
+
+### `evm`
+
+Every request is an EIP-1193 call forwarded to the page's connected wallet:
+`method` is the RPC method, `params` its params array, `result` its result.
+`eth_requestAccounts` opens the connect modal when nothing is connected and
+answers once a wallet connects. `personal_sign` takes the message as 0x hex.
+
+```json
+{
+  "id": "12",
+  "ns": "evm",
+  "kind": "req",
+  "method": "personal_sign",
+  "params": ["0x48656c6c6f", "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"]
+}
+```
+
+Events: `accountsChanged` (array of addresses), `chainChanged` (hex chain id),
+`connect`, `disconnect`.
+
+### `solana`
+
+| method                | params                         | result                                        |
+| --------------------- | ------------------------------ | --------------------------------------------- |
+| `connect`             | none                           | `{ "publicKey": base58 }`                     |
+| `disconnect`          | none                           | `null`                                        |
+| `signMessage`         | `{ "message": base64 }`        | `{ "signature": base64 }` (ed25519, 64 bytes) |
+| `signTransaction`     | `{ "transaction": base64 }`    | `{ "transaction": base64 }`                   |
+| `signAllTransactions` | `{ "transactions": [base64] }` | `{ "transactions": [base64] }`                |
+
+Transactions are serialized legacy or versioned transactions. Event:
+`accountChanged` with `{ "publicKey": base58 | null }`.
+
+### `sui`
+
+| method        | params                  | result                    |
+| ------------- | ----------------------- | ------------------------- |
+| `connect`     | none                    | `{ "address": "0x…" }`    |
+| `disconnect`  | none                    | `null`                    |
+| `signMessage` | `{ "message": string }` | `{ "signature": base64 }` |
+
+`message` is UTF-8 text, signed as a Sui personal message. `signature` is
+Sui's serialized signature (flag, signature, public key), the form the
+Keycloak Sui verifier takes. `signMessage` connects first when needed. Event:
+`accountChanged` with `{ "address": string | null }`.
+
+```json
+{
+  "id": "20",
+  "ns": "sui",
+  "kind": "req",
+  "method": "signMessage",
+  "params": { "message": "Sign in With Sui." }
+}
+```
+
+### `gpg`
+
+GPG signing is copy and paste: the user runs a command in a terminal and
+pastes its output.
+
+| method        | params                    | result                                                                |
+| ------------- | ------------------------- | --------------------------------------------------------------------- |
+| `signMessage` | `{ "message": string }`   | `{ "signature": string }`: armored signature, then armored public key |
+| `submit`      | `{ "signature": string }` | `null`; `-32602` if the paste is incomplete or covers another message |
+| `cancel`      | none                      | `null`; the pending `signMessage` fails with `4001`                   |
+
+`signMessage` stays pending until pasted output settles it. By default the
+page shows its own paste box (and raises `sys.modalOpen`). A host that draws
+its own listens for `pendingChanged` and calls `submit`. A second
+`signMessage` replaces the first, which fails.
+
+Event `pendingChanged`: `{ "request": { "message": string, "command": string } | null }`.
+
+```json
+{
+  "ns": "gpg",
+  "kind": "event",
+  "method": "pendingChanged",
+  "params": {
+    "request": {
+      "message": "wallet.example.com wants you to sign in with your GPG key.",
+      "command": "{ printf %s '…' | gpg --detach-sign --armor; gpg --armor --export; }"
+    }
+  }
+}
+```
+
+### `auth`
+
+Keycloak wallet sign-in, run inside the page so the nonce cookie and the
+message domain belong to the hosted page. The host receives tokens.
+
+Shared params:
+
+- `keycloak`: `{ "baseUrl": string, "realm": string, "resource"?: "siww" | "wallet", "clientId": string, "scope"?: string | [string] }`.
+  `baseUrl` is Keycloak's root (`https://account.example.com`, or with `/auth`
+  on a Keycloak that still serves it there). `resource` is `siww` on the SHC
+  Keycloak (the default) and `wallet` on mpo's. `clientId` is a public client
+  with direct access grants enabled.
+- `onboarding`: `{ "clientId": string, "redirectUri": string, "scope"?: string | [string] }`,
+  a client with the standard flow enabled and `redirectUri` (the app's deep
+  link) registered exactly.
+
+Tokens: `{ "accessToken", "refreshToken"?, "idToken"?, "tokenType", "scope"?, "expiresAt", "refreshExpiresAt"? }`,
+times in epoch milliseconds.
+
+| method    | params                                     | result                   |
+| --------- | ------------------------------------------ | ------------------------ |
+| `signIn`  | `{ "family"?, "keycloak", "onboarding"? }` | a sign-in result (below) |
+| `refresh` | `{ "keycloak", "refreshToken"? }`          | `{ "tokens": Tokens }`   |
+| `logout`  | `{ "keycloak", "refreshToken"? }`          | `null`                   |
+
+`family` is `eth` (default), `sol`, `sui` or `gpg`. `signIn` connects that
+family's wallet (opening the modal if needed), fetches a nonce from
+`<baseUrl>/realms/<realm>/<resource>/nonce`, builds the family's sign-in
+message with the page's host as domain, has the wallet sign it, and trades it
+for tokens with a password grant (`username` = signature, `password` =
+base64 of the message). `refresh` and `logout` default to the page's stored
+refresh token for that realm and client; after a page reload, pass the one
+the host kept. A `logout` Keycloak refuses fails with `-32002` (the page's
+own session is cleared either way), so a host never takes a live token for
+a revoked one. `400` with `invalid_grant` means Keycloak no longer honours
+that refresh token, and the host can drop it.
+
+Sign-in results:
+
+- `{ "status": "signed-in", "family", "address", "tokens" }`. `address` is
+  null for GPG.
+- `{ "status": "profile-incomplete", "family", "address", "browserLogin": { "url", "state", "codeVerifier" } }`.
+  Keycloak took the signature but the account has required actions (a new
+  user's profile form) that a direct grant cannot run. Check that `url` starts
+  with `<baseUrl>/realms/<realm>/protocol/openid-connect/auth?` for the
+  `keycloak` the host sent, then open it in the system browser once (never in
+  the WebView, never in a loop). Keycloak shows its own forms there and then
+  redirects to `redirectUri` with `code` and `state`. When `state` matches,
+  call `signIn` again, which now succeeds; a return carrying `error` (the user
+  cancelled) ends the onboarding instead. A host may also redeem `code` with
+  `codeVerifier` (PKCE S256) at the token endpoint for tokens of the
+  onboarding client.
+
+Event `tokensChanged`: `{ "baseUrl", "realm", "clientId", "tokens": Tokens | null }`
+on every sign-in, refresh and logout. Persist the refresh token from it.
+
+```json
+{
+  "id": "30",
+  "ns": "auth",
+  "kind": "req",
+  "method": "signIn",
+  "params": {
+    "family": "eth",
+    "keycloak": {
+      "baseUrl": "https://account.example.com",
+      "realm": "main",
+      "resource": "wallet",
+      "clientId": "siwe-public"
+    },
+    "onboarding": { "clientId": "wallet-onboarding", "redirectUri": "quickcam://auth" }
+  }
+}
+```
+
+```json
+{
+  "id": "30",
+  "ns": "auth",
+  "kind": "res",
+  "result": {
+    "status": "profile-incomplete",
+    "family": "eth",
+    "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
+    "browserLogin": {
+      "url": "https://account.example.com/realms/main/protocol/openid-connect/auth?client_id=wallet-onboarding&redirect_uri=quickcam%3A%2F%2Fauth&response_type=code&scope=openid&state=Q2x1&code_challenge=E9Mel&code_challenge_method=S256",
+      "state": "Q2x1",
+      "codeVerifier": "dBjftJeZ4CVP"
+    }
+  }
+}
+```
+
+## 8. Security
+
+- Keys never cross the bridge. Only addresses, signatures and tokens do, and
+  every signature needs the wallet's own approval.
+- Load only the page you host, keep its top frame on its origin (section 5),
+  accept page messages only from its top frame on its origin, and deliver
+  messages only while the top frame is on that origin (section 2).
+- Tokens arrive in `auth` results and `tokensChanged`. Store them the way the
+  app stores any credential (Keystore, Keychain); never log them.
+- `mockWallet` signs with a throwaway in-page key and approves everything.
+  It exists for tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/web3",
-  "version": "7.24.0",
+  "version": "7.25.0",
   "description": "Web3 wallet integration for multiplatform.one ecosystem with ConnectKit and wagmi",
   "keywords": [
     "connectkit",
@@ -23,6 +23,7 @@
   "source": "src/index.ts",
   "files": [
     "dist",
+    "docs",
     "src",
     "types",
     "!types/.tsbuildinfo"
@@ -53,6 +54,13 @@
       "require": "./dist/cjs/index.native.js",
       "default": "./dist/esm/index.native.js"
     },
+    "./bridge": {
+      "source": "./src/bridge/core.ts",
+      "react-native": "./src/bridge/core.ts",
+      "types": "./types/bridge/core.d.ts",
+      "import": "./dist/esm/bridge/core.mjs",
+      "require": "./dist/cjs/bridge/core.cjs"
+    },
     "./connectkit": {
       "source": "./src/connectkit/index.ts",
       "types": "./types/connectkit/index.d.ts",
@@ -99,10 +107,10 @@
   "dependencies": {
     "@aave/account": "^0.2.0",
     "@metamask/connect-evm": "^2.1.1",
-    "@multiplatform.one/connectkit": "7.24.0",
-    "@multiplatform.one/gpg": "7.24.0",
-    "@multiplatform.one/platform": "7.24.0",
-    "@multiplatform.one/theme": "7.24.0",
+    "@multiplatform.one/connectkit": "7.25.0",
+    "@multiplatform.one/gpg": "7.25.0",
+    "@multiplatform.one/platform": "7.25.0",
+    "@multiplatform.one/theme": "7.25.0",
     "@noble/curves": "^1.9.7",
     "@solana/kit": "^8.3.0",
     "@solana/wallet-adapter-base": "^0.9.27",
@@ -126,7 +134,7 @@
     "wagmi": "^3.7.1"
   },
   "devDependencies": {
-    "@multiplatform.one/config": "7.24.0",
+    "@multiplatform.one/config": "7.25.0",
     "@tamagui/build": "2.7.6",
     "@tanstack/react-query": "^5.100.7",
     "@testing-library/jest-dom": "^6.9.1",