@condorinst/mobile-bridge 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.18.0] — 2026-09-16
+
+### Added
+
+- **Native transport over the `CondorNative` JavaScript channel.** The app is
+  moving from `flutter_inappwebview` to the official `webview_flutter`, whose
+  only JS → native path is a named channel that accepts a string. When
+  `window.CondorNative.postMessage` exists, the SDK uses it and sends the
+  `{type, version, payload}` envelope as JSON. It takes precedence over
+  `window.flutter_inappwebview`, which keeps working for the transition.
+- **`Bridge.setOutgoingStamp(stamp | null)`.** A single, supported hook that
+  transforms every JS → native message (handshake included) right before it is
+  sent. It exists so the shell can stamp its nonce. Until now the shell had to
+  monkey-patch `flutter_inappwebview.callHandler`, which has no equivalent on a
+  channel. Client code should not use it.
+- `NATIVE_CHANNEL_NAME` and the `OutgoingStamp` type are exported.
+- `SandboxVerifyResult.nativeChannelReachable`: the client now also reports
+  whether `window.CondorNative` is visible inside the iframe, and `ok` requires
+  it to be `false`. Clients built with an older SDK do not send the field; the
+  shell treats it as `false`.
+
+### Changed
+
+- **Layer 1 override prefix also removes and locks `window.CondorNative`.**
+  Measured on a real iPhone (iOS 26.6) and an Android device: the prefix removes
+  the channel from the iframe, but the WebView injects the channel into every
+  frame, so a child iframe created by the client gets it back, and on iOS
+  `window.webkit.messageHandlers` cannot be locked. Layer 1 is defense in depth;
+  the guarantee is the nonce validated natively (layer 3), which discarded every
+  message sent through those paths.
+
+### Deprecated
+
+- The `window.flutter_inappwebview` host. It will be removed in a future minor
+  once no app ships it.
+
+## [0.17.0] — 2026-09-01
+
+### Added
+
+- **The shell now relays `nativeVersion` to the sandboxed client.**
+  `BridgeClientHandshakeAck` gains `nativeVersion: string | null`, and the shell
+  performs the native handshake on the client's behalf to fill it in.
+
+  This closes a hole the 0.16.0 docs walked straight into. Those docs told
+  consumers to "check `nativeVersion` from the handshake ack" before relying on
+  the new raw light channels — but a client lives inside a sandboxed iframe and
+  handshakes with the *shell*, not the native, and the shell answered with
+  `shellVersion` alone. The check was impossible to perform. Worse, nothing in
+  the SDK ever called `Bridge.handshake`, so the native version was not merely
+  unreachable from the client: nobody obtained it at all.
+
+  `null` means the native has not answered (or does not exist, as in a browser
+  mock) and is honest information, not a placeholder. `Bridge.handshake` has no
+  timeout of its own, so the shell bounds the wait at 2s and answers the client
+  either way — without that, a client in a browser would hang forever waiting
+  for a handshake that never resolves.
+
+### Changed
+
+- **The shell touches the native during the client handshake.** Until 0.16.x it
+  answered immediately and deliberately did not; a test asserted exactly that.
+  That test now asserts the relay instead. Clients see one extra round-trip on
+  handshake, bounded at 2s.
+- `SHELL_VERSION` 0.5.1 → 0.6.0.
+- `client_demo` logs `nativeVersion` alongside `shellVersion`, which is how an
+  E2E confirms which native it is actually talking to.
+
 ## [0.16.0] — 2026-09-01
 
 ### Added

package/README.md

@@ -146,13 +146,13 @@ if (!verify.ok) {
 // automatically. Nothing else to do at boot.
 ```
 
-### Layered defense (propagation of `window.flutter_inappwebview`)
+### Layered defense (propagation of the native channel into the iframe)
 
 | Layer | Where | What it does |
 |---|---|---|
-| **1** | `BridgeShell.bootstrapClientIframe` | `srcdoc` with a prefix that deletes `window.flutter_inappwebview` + `window.CondorBridge` before any client script runs. |
-| **2** | `BridgeShell.verifySandbox` + `BridgeClient` handler | Round-trip `postMessage` to attest the iframe state. |
-| **3** | (Native side) | Shell nonce validated natively in the Flutter bridge. |
+| **1** | `BridgeShell.bootstrapClientIframe` | `srcdoc` with a prefix that deletes `window.CondorNative`, `window.flutter_inappwebview` and `window.CondorBridge` before any client script runs. Defense in depth only: the WebView injects the channel into every frame, so a child iframe created by the client gets it back (and on iOS `window.webkit.messageHandlers` cannot be locked). |
+| **2** | `BridgeShell.verifySandbox` + `BridgeClient` handler | Round-trip `postMessage` to attest the iframe state (`nativeChannelReachable` since 0.18.0). |
+| **3** | (Native side) | Shell nonce, stamped on every outgoing message via `Bridge.setOutgoingStamp`, validated natively. **This is the guarantee.** |
 | **4** | (Fallback if 1+2 fail) | Dual `InAppWebView` — shell and client in separate WebViews. |
 
 ## Build CLI — `condor-mobile-bridge build`
@@ -253,7 +253,11 @@ land once there are 2+ versions in the field.
 
 The package detects automatically:
 
-- **Android / iOS** — `window.flutter_inappwebview` (via the `flutter_inappwebview` package on the Flutter side).
+- **Android / iOS** — `window.CondorNative`, a JavaScript channel registered with
+  `webview_flutter` (`addJavaScriptChannel('CondorNative')`). Messages are sent as a
+  JSON string. Takes precedence when present.
+- **Android / iOS (legacy)** — `window.flutter_inappwebview` (via the `flutter_inappwebview`
+  package). Still supported for the transition; will be removed in a future minor.
 - **Browser outside the app** (dev/test): **mock mode** activates automatically.
 
 ## Mock mode

package/dist/index.cjs

@@ -33,7 +33,8 @@ __export(index_exports, {
   BRIDGE_KEYS: () => BRIDGE_KEYS,
   Bridge: () => Bridge,
   BridgeClient: () => BridgeClient,
-  BridgeShell: () => BridgeShell
+  BridgeShell: () => BridgeShell,
+  NATIVE_CHANNEL_NAME: () => NATIVE_CHANNEL_NAME
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -469,8 +470,22 @@ function createMockAdapter() {
 }
 
 // src/internal/native.ts
+var NATIVE_CHANNEL_NAME = "CondorNative";
+var outgoingStamp = null;
+function setOutgoingStamp(stamp) {
+  outgoingStamp = stamp;
+}
 var activeAdapter = null;
-function createRealAdapter(host) {
+function createChannelAdapter(channel) {
+  return {
+    isMock: false,
+    // Canal único: o `handlerName` não viaja — o nativo roteia por `type`.
+    callHandler(_handlerName, payload) {
+      channel.postMessage(JSON.stringify(payload));
+    }
+  };
+}
+function createLegacyAdapter(host) {
   return {
     isMock: false,
     callHandler(handlerName, payload) {
@@ -482,9 +497,13 @@ function detectAdapter() {
   if (typeof window === "undefined") {
     return createMockAdapter();
   }
+  const channel = window.CondorNative;
+  if (channel && typeof channel.postMessage === "function") {
+    return createChannelAdapter(channel);
+  }
   const host = window.flutter_inappwebview;
   if (host && typeof host.callHandler === "function") {
-    return createRealAdapter(host);
+    return createLegacyAdapter(host);
   }
   return createMockAdapter();
 }
@@ -495,7 +514,8 @@ function getActiveAdapter() {
   return activeAdapter;
 }
 function callNative(handlerName, payload) {
-  getActiveAdapter().callHandler(handlerName, payload);
+  const stamped = outgoingStamp ? outgoingStamp(payload) : payload;
+  getActiveAdapter().callHandler(handlerName, stamped);
 }
 
 // src/internal/subscribers.ts
@@ -611,6 +631,9 @@ var Bridge = {
   openSettings() {
     this.send("openSettings");
   },
+  setOutgoingStamp(stamp) {
+    setOutgoingStamp(stamp);
+  },
   mockEmit(key, payload) {
     requireMockAdapter().triggerEmit(key, payload ?? {});
   },
@@ -671,6 +694,8 @@ function onMessage(event) {
         pendingHandshake2 = null;
         resolve({
           shellVersion: msg.ack?.shellVersion ?? "unknown",
+          // `?? null` cobre o shell anterior à 0.17.0, que não mandava o campo.
+          nativeVersion: msg.ack?.nativeVersion ?? null,
           accepted: msg.ack?.accepted ?? false
         });
       }
@@ -684,7 +709,8 @@ function onMessage(event) {
       postToShell({
         type: "sandbox-verify-response",
         flutterBridgeReachable: typeof w.flutter_inappwebview !== "undefined",
-        condorBridgeReachable: typeof w.CondorBridge !== "undefined"
+        condorBridgeReachable: typeof w.CondorBridge !== "undefined",
+        nativeChannelReachable: typeof w.CondorNative !== "undefined"
       });
       break;
     }
@@ -810,7 +836,9 @@ var JsErrorMessage = v.object({
 var SandboxVerifyResponseMessage = v.object({
   type: v.literal("sandbox-verify-response"),
   flutterBridgeReachable: v.boolean(),
-  condorBridgeReachable: v.boolean()
+  condorBridgeReachable: v.boolean(),
+  // Opcional: clientes com SDK < 0.18.0 não enviam.
+  nativeChannelReachable: v.optional(v.boolean())
 });
 var ClientToShellMessage = v.variant("type", [
   SubscribeMessage,
@@ -829,6 +857,15 @@ var HandshakeAckMessage = v.object({
   type: v.literal("handshake-ack"),
   ack: v.object({
     shellVersion: v.string(),
+    /**
+     * Versão do schema declarada pelo **nativo**, repassada pelo shell.
+     *
+     * `null` quando o nativo ainda não respondeu (ou não existe, como no
+     * mock de browser). O cliente roda dentro de um iframe sandboxed e não
+     * fala com o nativo diretamente, então este é o **único** caminho pelo
+     * qual ele descobre de qual versão são as capacidades disponíveis.
+     */
+    nativeVersion: v.nullable(v.string()),
     accepted: v.boolean()
   })
 });
@@ -849,12 +886,14 @@ var ShellToClientMessage = v.variant("type", [
 ]);
 
 // src/bridge-shell.ts
-var SHELL_VERSION = "0.5.1";
+var SHELL_VERSION = "0.6.0";
+var NATIVE_HANDSHAKE_TIMEOUT_MS = 2e3;
 var VERIFY_TIMEOUT_MS = 2e3;
 var OVERRIDE_PREFIX = `<script>
 (function(){
   try { delete window.flutter_inappwebview; } catch (_) {}
   try { delete window.CondorBridge; } catch (_) {}
+  try { delete window.CondorNative; } catch (_) {}
   try {
     Object.defineProperty(window, 'flutter_inappwebview', {
       get: function(){ return undefined; },
@@ -862,6 +901,13 @@ var OVERRIDE_PREFIX = `<script>
       configurable: false,
     });
   } catch (_) {}
+  try {
+    Object.defineProperty(window, 'CondorNative', {
+      get: function(){ return undefined; },
+      set: function(_){ /* no-op: bloqueia o canal do webview_flutter no iframe */ },
+      configurable: false,
+    });
+  } catch (_) {}
   try {
     Object.defineProperty(window, 'CondorBridge', {
       get: function(){ return undefined; },
@@ -887,6 +933,13 @@ var BridgeShell = class {
   constructor(opts) {
     this.subscriptions = /* @__PURE__ */ new Map();
     this.detached = false;
+    /**
+     * Versão do nativo, obtida uma vez e cacheada. `null` até o nativo
+     * responder — e permanentemente `null` num browser sem nativo.
+     */
+    this.nativeVersion = null;
+    /** Handshake com o nativo em voo; garante uma única chamada. */
+    this.nativeHandshake = null;
     // Map de `verify-sandbox` round-trips pendentes — key gerada por nonce.
     this.pendingVerifies = /* @__PURE__ */ new Map();
     this.onMessage = async (event) => {
@@ -911,9 +964,11 @@ var BridgeShell = class {
           await this.handleSend(msg.command, msg.args ?? {});
           break;
         case "handshake":
-          this.postToClient({
-            type: "handshake-ack",
-            ack: { shellVersion: SHELL_VERSION, accepted: true }
+          void this.resolveNativeVersion().then((nativeVersion) => {
+            this.postToClient({
+              type: "handshake-ack",
+              ack: { shellVersion: SHELL_VERSION, nativeVersion, accepted: true }
+            });
           });
           break;
         case "jsError":
@@ -933,10 +988,12 @@ var BridgeShell = class {
             if (pending) {
               clearTimeout(pending.timer);
               this.pendingVerifies.delete(first);
-              const ok = !msg.flutterBridgeReachable && !msg.condorBridgeReachable;
+              const nativeChannelReachable = msg.nativeChannelReachable ?? false;
+              const ok = !msg.flutterBridgeReachable && !msg.condorBridgeReachable && !nativeChannelReachable;
               pending.resolve({
                 flutterBridgeReachable: msg.flutterBridgeReachable,
                 condorBridgeReachable: msg.condorBridgeReachable,
+                nativeChannelReachable,
                 ok
               });
             }
@@ -1092,6 +1149,29 @@ var BridgeShell = class {
     }
     Bridge.send(command, args);
   }
+  /**
+   * Obtém o `nativeVersion`, disparando o handshake com o nativo na primeira
+   * vez e cacheando o resultado.
+   *
+   * ⚠️ `Bridge.handshake` **não tem timeout**: a Promise só resolve quando o
+   * nativo emite `handshake-ack`. Num browser sem nativo ela nunca resolve,
+   * então o `race` abaixo é o que garante que o cliente sempre receba
+   * resposta — com `null` — em vez de ficar pendurado.
+   */
+  async resolveNativeVersion() {
+    if (this.nativeVersion !== null) return this.nativeVersion;
+    if (!this.nativeHandshake) {
+      this.nativeHandshake = Bridge.handshake({ clientVersion: SHELL_VERSION }).then((ack) => {
+        this.nativeVersion = ack.nativeVersion;
+      }).catch(() => {
+      });
+    }
+    await Promise.race([
+      this.nativeHandshake,
+      new Promise((resolve) => setTimeout(resolve, NATIVE_HANDSHAKE_TIMEOUT_MS))
+    ]);
+    return this.nativeVersion;
+  }
   postToClient(msg) {
     if (this.detached) return;
     this.iframe.contentWindow?.postMessage(msg, "*");
@@ -1102,6 +1182,7 @@ var BridgeShell = class {
   BRIDGE_KEYS,
   Bridge,
   BridgeClient,
-  BridgeShell
+  BridgeShell,
+  NATIVE_CHANNEL_NAME
 });
 //# sourceMappingURL=index.cjs.map