@condorinst/mobile-bridge 0.18.0 → 0.19.0

package/dist/index.js

@@ -12,10 +12,10 @@ var BRIDGE_KEYS = {
   dfu: "dfu",
   systemStatus: "systemStatus",
   /**
-   * Native → client: o back do SO foi pressionado e o cliente reportou
-   * ter histórico interno (`reportNavigation(true)`). O cliente deve voltar
-   * UMA página interna. Emitido só quando o nativo decidiu delegar o back
-   * ao cliente. Vide `BridgeClient.onBack`.
+   * Native → client: the OS back button was pressed and the client had
+   * reported internal history via `reportNavigation(true)`. Go back exactly
+   * ONE internal page. Emitted only when the native side decided to delegate
+   * the back gesture. See `BridgeClient.onBack`.
    */
   navigationBack: "navigationBack",
   /**
@@ -23,7 +23,7 @@ var BRIDGE_KEYS = {
    * AND the language explicitly chosen in the app Settings, so the client can
    * apply its own precedence rule — including rendering a language the native
    * chrome does not support. Emitted on attach, after `handshake-ack`, and on
-   * every change in Settings. Vide `LanguagePayload`.
+   * every change in Settings. See `LanguagePayload`.
    */
   language: "language"
 };
@@ -439,7 +439,8 @@ var activeAdapter = null;
 function createChannelAdapter(channel) {
   return {
     isMock: false,
-    // Canal único: o `handlerName` não viaja — o nativo roteia por `type`.
+    // Single channel: `handlerName` does not travel — the native side routes
+    // on `type`.
     callHandler(_handlerName, payload) {
       channel.postMessage(JSON.stringify(payload));
     }
@@ -654,7 +655,7 @@ 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.
+          // `?? null` covers shells older than 0.17.0, which omitted the field.
           nativeVersion: msg.ack?.nativeVersion ?? null,
           accepted: msg.ack?.accepted ?? false
         });
@@ -797,10 +798,10 @@ var SandboxVerifyResponseMessage = v.object({
   type: v.literal("sandbox-verify-response"),
   flutterBridgeReachable: v.boolean(),
   condorBridgeReachable: v.boolean(),
-  // Opcional: clientes com SDK < 0.18.0 não enviam.
+  // Optional: clients on SDK < 0.18.0 do not send it.
   nativeChannelReachable: v.optional(v.boolean())
 });
-var ClientToShellMessage = v.variant("type", [
+var ClientToShellMessageSchema = v.variant("type", [
   SubscribeMessage,
   UnsubscribeMessage,
   SendMessage,
@@ -818,12 +819,12 @@ var HandshakeAckMessage = v.object({
   ack: v.object({
     shellVersion: v.string(),
     /**
-     * Versão do schema declarada pelo **nativo**, repassada pelo shell.
+     * Schema version declared by the **native** side, relayed by the 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.
+     * `null` when the native side has not answered, or does not exist (browser
+     * mock mode). The client runs inside a sandboxed iframe and never talks to
+     * the native side directly, so this is the **only** way it can learn which
+     * capabilities are available.
      */
     nativeVersion: v.nullable(v.string()),
     accepted: v.boolean()
@@ -838,7 +839,7 @@ var NackMessage = v.object({
 var VerifySandboxMessage = v.object({
   type: v.literal("verify-sandbox")
 });
-var ShellToClientMessage = v.variant("type", [
+var ShellToClientMessageSchema = v.variant("type", [
   EventMessage,
   HandshakeAckMessage,
   NackMessage,
@@ -857,7 +858,7 @@ var OVERRIDE_PREFIX = `<script>
   try {
     Object.defineProperty(window, 'flutter_inappwebview', {
       get: function(){ return undefined; },
-      set: function(_){ /* no-op: bloqueia inje\xE7\xE3o do plugin no iframe */ },
+      set: function(_){ /* no-op: blocks the plugin injecting into the iframe */ },
       configurable: false,
     });
   } catch (_) {}
@@ -876,11 +877,11 @@ var OVERRIDE_PREFIX = `<script>
     });
   } catch (_) {}
   try {
-    // Neutraliza navigator.sendBeacon: canal de exfil que a CSP connect-src
-    // n\xE3o barra de forma confi\xE1vel em alguns WebViews (pentest 2026-06-24,
-    // PT-10). O cliente comunica s\xF3 via BridgeClient/postMessage \u2014 n\xE3o tem
-    // uso leg\xEDtimo de sendBeacon. Getter no-op retorna fun\xE7\xE3o que devolve
-    // false; setter no-op ignora tentativa de restaurar.
+    // Neutralize navigator.sendBeacon: an exfiltration channel that CSP
+    // connect-src does not reliably block in some WebViews (pen test PT-10).
+    // The client communicates only through BridgeClient/postMessage, so it has
+    // no legitimate use for sendBeacon. The no-op getter returns a function
+    // that answers false; the no-op setter ignores attempts to restore it.
     Object.defineProperty(navigator, 'sendBeacon', {
       get: function(){ return function(){ return false; }; },
       set: function(_){ /* no-op */ },
@@ -894,18 +895,18 @@ var BridgeShell = class {
     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.
+     * The native version, fetched once and cached. `null` until the native side
+     * answers, and permanently `null` in a browser with no native host.
      */
     this.nativeVersion = null;
-    /** Handshake com o nativo em voo; garante uma única chamada. */
+    /** In-flight native handshake; guarantees a single call. */
     this.nativeHandshake = null;
-    // Map de `verify-sandbox` round-trips pendentes — key gerada por nonce.
+    // Pending `verify-sandbox` round trips, keyed by a generated nonce.
     this.pendingVerifies = /* @__PURE__ */ new Map();
     this.onMessage = async (event) => {
       if (this.detached) return;
       if (event.source !== this.iframe.contentWindow) return;
-      const parsed = v2.safeParse(ClientToShellMessage, event.data);
+      const parsed = v2.safeParse(ClientToShellMessageSchema, event.data);
       if (!parsed.success) {
         if (typeof console !== "undefined") {
           console.debug("[BridgeShell] dropped malformed message:", parsed.issues?.[0]?.message);
@@ -970,41 +971,40 @@ var BridgeShell = class {
     }
   }
   /**
-   * **Camada 1 do Risco 1.** Bootstrap via fetch de URL.
+   * **Layer 1.** Bootstraps by fetching a URL.
    *
-   * Atalho para o caso comum HTTP/HTTPS: faz `fetch(clientPath)` e
-   * delega para `bootstrapClientIframeWithHtml`.
+   * A shortcut for the common HTTP/HTTPS case: it runs `fetch(clientPath)` and
+   * delegates to `bootstrapClientIframeWithHtml`.
    *
-   * **Não funciona em scheme `file://`** — `fetch` em WebView Android
-   * (Chromium) bloqueia o scheme com "URL scheme 'file' is not supported".
-   * Para asset bundled em APK ou bundle inlined no build-time, use
-   * `bootstrapClientIframeWithHtml(htmlString)`.
+   * **It does not work on the `file://` scheme** — Android's Chromium WebView
+   * blocks it with "URL scheme 'file' is not supported". For an asset bundled
+   * in the APK, or a bundle inlined at build time, use
+   * `bootstrapClientIframeWithHtml(htmlString)` instead.
    *
-   * **Devo ser chamado uma vez no boot do shell**, antes de qualquer
-   * outra interação. Após retornar, `verifySandbox()` deve ser invocado
-   * para atestation (Camada 2).
+   * **Call it once at shell boot**, before any other interaction. After it
+   * returns, invoke `verifySandbox()` for attestation (Layer 2).
    */
   async bootstrapClientIframe(clientPath = "client.html") {
     const res = await fetch(clientPath);
-    if (!res.ok) throw new Error(`BridgeShell: falha ao carregar ${clientPath} (${res.status})`);
+    if (!res.ok) throw new Error(`BridgeShell: failed to load ${clientPath} (${res.status})`);
     const clientHtml = await res.text();
     await this.bootstrapClientIframeWithHtml(clientHtml);
   }
   /**
-   * **Camada 1 do Risco 1.** Bootstrap a partir de HTML string.
+   * **Layer 1.** Bootstraps from an HTML string.
    *
-   * Aceita HTML do cliente diretamente (já lido de arquivo, embedado em
-   * build-time via `esbuild.define`, lido de IndexedDB, etc.) e seta
-   * como `srcdoc` do iframe prefixado pelo override script. Override
-   * roda em parse-time, antes de qualquer outro script do cliente.
+   * Takes the client HTML directly — already read from a file, embedded at
+   * build time, read from storage — and sets it as the iframe's `srcdoc`,
+   * prefixed by the override script, which runs at parse time before any
+   * client script.
    *
-   * Use quando `fetch` não é aplicável (asset bundled em `file://`,
-   * bundle inlined no build, qualquer cenário sem rede). Para HTTP
-   * use `bootstrapClientIframe(clientPath)`.
+   * Use this when `fetch` does not apply: an asset bundled under `file://`, a
+   * bundle inlined at build time, any scenario without network. Android
+   * WebView blocks `fetch` on the `file://` scheme, so this is the path the
+   * app actually takes. For HTTP, use `bootstrapClientIframe(clientPath)`.
    *
-   * **Devo ser chamado uma vez no boot do shell**, antes de qualquer
-   * outra interação. Após retornar, `verifySandbox()` deve ser invocado
-   * para atestation (Camada 2).
+   * **Call it once at shell boot**, before any other interaction. After it
+   * returns, invoke `verifySandbox()` for attestation (Layer 2).
    */
   async bootstrapClientIframeWithHtml(clientHtml) {
     this.iframe.srcdoc = OVERRIDE_PREFIX + clientHtml;
@@ -1020,31 +1020,31 @@ var BridgeShell = class {
     });
   }
   /**
-   * **Camada 2 do Risco 1.** Round-trip `postMessage` que pede ao iframe
-   * atestation autoritativa do estado de `window.flutter_inappwebview`
-   * e `window.CondorBridge`. Timeout em 2s.
+   * **Layer 2.** A `postMessage` round trip asking the iframe for an
+   * authoritative attestation of whether the native globals are reachable.
+   * Times out after 2 s.
    *
-   * `ok` é `true` apenas se ambos forem `undefined` no iframe. Se vier
-   * `false`, **shell deve abortar o boot do app** — Camada 1 falhou e
-   * Camada 4 (dual WebView) precisa ser acionada manualmente.
+   * `ok` is `true` only when none of them is reachable. If it comes back
+   * `false`, **the shell must abort the app boot**: Layer 1 failed, and client
+   * code would run with a path to the native layer.
    */
   verifySandbox() {
     if (!this.iframe.contentWindow) {
-      return Promise.reject(new Error("BridgeShell: iframe sem contentWindow"));
+      return Promise.reject(new Error("BridgeShell: iframe has no contentWindow"));
     }
     return new Promise((resolve, reject) => {
       const nonce = Math.random().toString(36).slice(2);
       const timer = setTimeout(() => {
         this.pendingVerifies.delete(nonce);
-        reject(new Error(`BridgeShell: verify-sandbox timeout ap\xF3s ${VERIFY_TIMEOUT_MS}ms`));
+        reject(new Error(`BridgeShell: verify-sandbox timed out after ${VERIFY_TIMEOUT_MS}ms`));
       }, VERIFY_TIMEOUT_MS);
       this.pendingVerifies.set(nonce, { resolve, reject, timer });
       this.postToClient({ type: "verify-sandbox" });
     });
   }
   /**
-   * Encerra o shell — remove listener `message`, cancela subscriptions
-   * pendentes no `Bridge` nativo, limpa estado interno.
+   * Tears the shell down: removes the `message` listener, cancels pending
+   * subscriptions on the native `Bridge`, and clears internal state.
    */
   detach() {
     if (this.detached) return;
@@ -1110,13 +1110,13 @@ var BridgeShell = class {
     Bridge.send(command, args);
   }
   /**
-   * Obtém o `nativeVersion`, disparando o handshake com o nativo na primeira
-   * vez e cacheando o resultado.
+   * Resolves `nativeVersion`, firing the native handshake the first time and
+   * caching the result.
    *
-   * ⚠️ `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.
+   * ⚠️ `Bridge.handshake` has **no timeout**: its promise only settles when the
+   * native side emits `handshake-ack`. In a browser with no native host it
+   * never settles, so the race below is what guarantees the client always gets
+   * an answer — `null` — instead of hanging.
    */
   async resolveNativeVersion() {
     if (this.nativeVersion !== null) return this.nativeVersion;