@melaya/runner 1.0.117 → 1.1.0

package/dist/browserAuthz.js

@@ -0,0 +1,504 @@
+// packages/runner/src/browserAuthz.ts
+//
+// Melaya Browser, Phase 1 (plan Sections 6 and 10): the RUNNER-SIDE second
+// gate. The server is the first gate; this module re-enforces, immediately
+// before every consequential facade operation, the origin / scheme /
+// private-network policy and the grant's effect ceiling. It is wired in at
+// THREE boundaries, not just tool arguments:
+//
+//   1. BrowserContext routing (context.route / page.route): every HTTP/S
+//      request, redirect, subframe, popup document load, and download
+//      attempt is checked against the policy. Arg-only checks are
+//      bypassable (a page can redirect, open popups, or fetch cross-origin);
+//      routing is not.
+//   2. CDP target creation (new pages / popups observed on the context):
+//      a page whose destination URL is denied is closed before the agent
+//      can observe or act on it.
+//   3. WebSocket interception + WebRTC neutralisation (plan Section 10,
+//      egress extension):
+//      WebSocket: Playwright's `page.routeWebSocket(...)` intercepts
+//        ws:// and wss:// upgrade handshakes at the Playwright layer before
+//        the browser establishes the connection. Any ws/wss URL that fails
+//        the same origin / private-network policy check is aborted. This
+//        prevents page JS from reaching ws://169.254.169.254 or any other
+//        forbidden endpoint via a WebSocket.
+//      WebRTC: RTCPeerConnection is disabled via a page-init script that
+//        removes RTCPeerConnection, RTCSessionDescription, and
+//        RTCIceCandidate from the window and forces WebRTC IP handling
+//        mode via the CDP Network domain (disableWebRtc). This prevents
+//        data-channel exfiltration and IP leakage even when network*
+//        rules would otherwise allow them.
+//      COVERAGE NOTE: routeWebSocket is available in Playwright >= 1.48.
+//        If the pinned version is older, WebSocket blocking degrades to a
+//        best-effort page-init script that overrides window.WebSocket.
+//        WebRTC neutralisation is purely init-script-based and works on
+//        all Playwright versions.
+//
+// Default-deny (plan Section 10): localhost and loopback, RFC1918 and
+// CGNAT, link-local, cloud metadata IPs, unspecified addresses, unexpected
+// ports, DNS rebinding (every resolved A/AAAA record is re-checked, not
+// just the hostname literal), file: / data: / javascript: / blob: /
+// about: (except about:blank), extension and browser-internal pages.
+// Enterprise intranet targets are reachable only when an origin scope
+// explicitly names them (org policy is expressed through originScopes).
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { BROWSER_EFFECT_RANK } from "./browserGrantVerify.js";
+export const deny = (code, message) => ({
+    allowed: false,
+    code,
+    message,
+});
+const ALLOW = { allowed: true };
+// ---------------------------------------------------------------------
+// Scheme policy
+// ---------------------------------------------------------------------
+const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+/** Schemes that are never navigable by the agent, listed for clearer
+ *  error messages (everything not in ALLOWED_SCHEMES denies anyway). */
+const BROWSER_INTERNAL_SCHEMES = new Set([
+    "chrome:", "edge:", "brave:", "about:", "chrome-extension:",
+    "moz-extension:", "extension:", "devtools:", "view-source:",
+    "chrome-untrusted:", "chrome-search:",
+]);
+// ---------------------------------------------------------------------
+// Address classification
+// ---------------------------------------------------------------------
+/** Cloud metadata endpoints (AWS/GCP/Azure 169.254.169.254 is also
+ *  link-local, but keep the explicit list for non-link-local providers). */
+const METADATA_HOSTS = new Set([
+    "169.254.169.254", // AWS / GCP / Azure IMDS
+    "fd00:ec2::254", // AWS IMDSv6
+    "100.100.100.200", // Alibaba Cloud
+    "192.0.0.192", // Oracle Cloud legacy
+    "metadata.google.internal",
+    "metadata.goog",
+]);
+function ipv4ToInt(ip) {
+    const p = ip.split(".").map(Number);
+    return ((p[0] << 24) | (p[1] << 16) | (p[2] << 8) | p[3]) >>> 0;
+}
+function inCidr4(ip, base, bits) {
+    const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+    return (ip & mask) === (ipv4ToInt(base) & mask);
+}
+/** True when the literal IP is loopback, private, link-local, CGNAT,
+ *  unspecified, broadcast, or a metadata address. Conservative: any
+ *  parse failure classifies as forbidden (fail closed). */
+export function isForbiddenIp(ip) {
+    const family = isIP(ip);
+    if (family === 4) {
+        const n = ipv4ToInt(ip);
+        return (inCidr4(n, "127.0.0.0", 8) || // loopback
+            inCidr4(n, "10.0.0.0", 8) || // RFC1918
+            inCidr4(n, "172.16.0.0", 12) || // RFC1918
+            inCidr4(n, "192.168.0.0", 16) || // RFC1918
+            inCidr4(n, "169.254.0.0", 16) || // link-local (incl. IMDS)
+            inCidr4(n, "100.64.0.0", 10) || // CGNAT
+            inCidr4(n, "0.0.0.0", 8) || // unspecified
+            inCidr4(n, "192.0.0.0", 24) || // IETF protocol assignments
+            inCidr4(n, "198.18.0.0", 15) || // benchmarking
+            n === 0xffffffff // broadcast
+        );
+    }
+    if (family === 6) {
+        const low = ip.toLowerCase();
+        // Normalize a v4-mapped literal (::ffff:1.2.3.4) to its v4 rules.
+        const v4m = low.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+        if (v4m)
+            return isForbiddenIp(v4m[1]);
+        return (low === "::" || low === "::1" ||
+            low.startsWith("fe80:") || // link-local
+            low.startsWith("fc") || low.startsWith("fd") || // ULA
+            METADATA_HOSTS.has(low));
+    }
+    // Not an IP literal at all — caller handles hostnames separately.
+    return false;
+}
+const LOCALHOST_NAMES = new Set(["localhost", "localhost.localdomain", "ip6-localhost"]);
+function isLocalhostName(host) {
+    const h = host.toLowerCase().replace(/\.$/, "");
+    return LOCALHOST_NAMES.has(h) || h.endsWith(".localhost") || h.endsWith(".local");
+}
+export function parseOriginScope(raw) {
+    if (raw === "*") {
+        return { raw, scheme: "", wildcardHost: true, host: "", port: -1, any: true };
+    }
+    const m = raw.match(/^(https?):\/\/(\*\.)?([^/:*\s]+)(?::(\d+))?$/i);
+    if (!m)
+        return null;
+    const scheme = `${m[1].toLowerCase()}:`;
+    const port = m[4] ? Number(m[4]) : scheme === "https:" ? 443 : 80;
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return null;
+    return {
+        raw,
+        scheme,
+        wildcardHost: Boolean(m[2]),
+        host: m[3].toLowerCase(),
+        port,
+        any: false,
+    };
+}
+export function buildOriginPolicy(originScopes) {
+    const scopes = [];
+    for (const raw of originScopes) {
+        const p = parseOriginScope(raw);
+        if (p)
+            scopes.push(p);
+        // Unparseable scopes are DROPPED, never widened (fail closed).
+    }
+    return { scopes, hasScopes: scopes.length > 0 };
+}
+function urlPort(u) {
+    if (u.port)
+        return Number(u.port);
+    return u.protocol === "https:" ? 443 : 80;
+}
+/** Standard web ports plus common dev-server ports are still gated by
+ *  scopes; a scope with an explicit port is required for ANY port other
+ *  than the scheme default (unexpected-port rule, plan Section 10). */
+function portAllowed(u, scope) {
+    const p = urlPort(u);
+    if (scope.any)
+        return p === 443 || p === 80; // "*" never grants odd ports
+    return p === scope.port;
+}
+function hostMatches(host, scope) {
+    const h = host.toLowerCase().replace(/\.$/, "");
+    if (scope.any)
+        return true;
+    if (scope.wildcardHost)
+        return h !== scope.host && h.endsWith(`.${scope.host}`);
+    return h === scope.host;
+}
+// ---------------------------------------------------------------------
+// URL evaluation
+// ---------------------------------------------------------------------
+/** Synchronous structural checks: scheme, browser pages, localhost names,
+ *  IP-literal private ranges, metadata hosts, origin-scope + port match.
+ *  Does NOT resolve DNS — call evaluateUrlResolved for the full gate. */
+export function evaluateUrlSync(rawUrl, policy) {
+    let u;
+    try {
+        u = new URL(rawUrl);
+    }
+    catch {
+        return deny("scheme_forbidden", `not a valid absolute URL: ${truncate(rawUrl)}`);
+    }
+    if (u.protocol === "about:" && rawUrl === "about:blank")
+        return ALLOW; // inert
+    if (BROWSER_INTERNAL_SCHEMES.has(u.protocol)) {
+        return deny("browser_internal_page", `browser-internal page '${u.protocol}' is not navigable by the agent`);
+    }
+    if (!ALLOWED_SCHEMES.has(u.protocol)) {
+        return deny("scheme_forbidden", `scheme '${u.protocol}' is denied (only http/https)`);
+    }
+    const host = u.hostname.replace(/^\[|\]$/g, "");
+    if (isLocalhostName(host)) {
+        return deny("private_network", `localhost destination '${host}' is denied by default`);
+    }
+    if (METADATA_HOSTS.has(host.toLowerCase())) {
+        return deny("metadata_endpoint", `cloud metadata endpoint '${host}' is denied`);
+    }
+    if (isIP(host) && isForbiddenIp(host)) {
+        return deny("private_network", `private/link-local/metadata address '${host}' is denied`);
+    }
+    if (!policy.hasScopes) {
+        return deny("origin_not_in_scope", "grant carries no parseable origin scopes; denying all origins");
+    }
+    const matched = policy.scopes.find((s) => (s.any || s.scheme === u.protocol) && hostMatches(host, s));
+    if (!matched) {
+        return deny("origin_not_in_scope", `origin '${u.protocol}//${host}' is not in the grant's origin scopes`);
+    }
+    if (!portAllowed(u, matched)) {
+        return deny("port_forbidden", `port ${urlPort(u)} is not allowed for scope '${matched.raw}'`);
+    }
+    return ALLOW;
+}
+/** Full gate: structural checks PLUS DNS-rebind protection. Every
+ *  resolved address for the hostname must be public; one private record
+ *  denies the whole navigation. Resolution failure denies (fail closed).
+ *  NOTE: a TOCTOU window between this lookup and Chromium's own lookup
+ *  remains (documented residual risk); the request-level route handler
+ *  re-runs this on every request which keeps the window per-request
+ *  rather than per-session. */
+export async function evaluateUrlResolved(rawUrl, policy) {
+    const structural = evaluateUrlSync(rawUrl, policy);
+    if (!structural.allowed)
+        return structural;
+    let host;
+    try {
+        host = new URL(rawUrl).hostname.replace(/^\[|\]$/g, "");
+    }
+    catch {
+        return deny("scheme_forbidden", "unparseable URL");
+    }
+    if (rawUrl === "about:blank")
+        return ALLOW;
+    if (isIP(host))
+        return ALLOW; // literal already vetted structurally
+    try {
+        const records = await dnsLookup(host, { all: true, verbatim: true });
+        if (!records.length)
+            return deny("dns_rebind", `hostname '${host}' resolved to no addresses`);
+        for (const r of records) {
+            if (isForbiddenIp(r.address)) {
+                return deny("dns_rebind", `hostname '${host}' resolves to forbidden address ${r.address}`);
+            }
+        }
+        return ALLOW;
+    }
+    catch (e) {
+        return deny("dns_rebind", `DNS resolution failed for '${host}': ${e?.message || e} (fail closed)`);
+    }
+}
+// ---------------------------------------------------------------------
+// Effect ceiling (grant second gate)
+// ---------------------------------------------------------------------
+/** An operation's declared effect must (a) be inside the grant's
+ *  actionScopes and (b) not exceed the effect ceiling. Unknown effect
+ *  strings deny. */
+export function checkEffect(effect, grant) {
+    if (!(effect in BROWSER_EFFECT_RANK)) {
+        return deny("effect_not_granted", `unknown effect class '${effect}'`);
+    }
+    const e = effect;
+    if (BROWSER_EFFECT_RANK[e] > BROWSER_EFFECT_RANK[grant.effectCeiling]) {
+        return deny("effect_over_ceiling", `effect '${e}' exceeds grant ceiling '${grant.effectCeiling}'`);
+    }
+    if (!grant.actionScopes.includes(e)) {
+        return deny("effect_not_granted", `effect '${e}' is not in the grant's actionScopes`);
+    }
+    return ALLOW;
+}
+// ---------------------------------------------------------------------
+// WebSocket interception (plan Section 10 egress extension)
+// ---------------------------------------------------------------------
+/** Intercept a WebSocket handshake on a page and close it if the
+ *  destination URL is forbidden. Uses Playwright's routeWebSocket API
+ *  (available from Playwright 1.48). On older versions the call is a
+ *  no-op and the init-script fallback (installed in installPageGuards)
+ *  blocks the connection at the JS layer instead.
+ *
+ *  ws:// and wss:// URLs are evaluated with the same origin / private-
+ *  network / metadata checks as HTTP requests. Forbidden connections are
+ *  closed before the server handshake completes. */
+async function interceptWebSockets(page, policy, hooks) {
+    try {
+        if (typeof page["routeWebSocket"] !== "function")
+            return;
+        await page.routeWebSocket("**", (ws) => {
+            const wsAny = ws;
+            const url = wsAny.url();
+            // Evaluate synchronously — the WS URL is known at handshake time.
+            // Rewrite ws:// -> http:// and wss:// -> https:// so the URL parser
+            // and the origin-scope matcher treat them identically to HTTP(S).
+            const httpUrl = url.replace(/^wss?:\/\//, (m) => (m === "wss://" ? "https://" : "http://"));
+            const d = evaluateUrlSync(httpUrl, policy);
+            if (d.allowed) {
+                wsAny.connect?.();
+            }
+            else {
+                hooks.onViolation({ url, code: d.code, message: d.message, surface: "websocket_intercept" });
+                wsAny.close();
+            }
+        });
+    }
+    catch {
+        // routeWebSocket unavailable on this Playwright build; init-script
+        // fallback covers window.WebSocket in installPageGuards below.
+    }
+}
+// ---------------------------------------------------------------------
+// Page init scripts (WebSocket + WebRTC neutralisation)
+// ---------------------------------------------------------------------
+/** Init script injected into EVERY new document on governed pages.
+ *
+ *  Covers two egress surfaces that bypass the context.route/page.route
+ *  handler (which only sees HTTP(S) requests):
+ *
+ *  1. WebSocket fallback: overrides window.WebSocket with a wrapper that
+ *     blocks ws:// URLs whose hostname matches any forbidden address. This
+ *     runs BEFORE page JS, so even inline scripts cannot open a raw
+ *     WebSocket to 169.254.169.254 before the routeWebSocket intercept
+ *     fires. The list of forbidden prefixes mirrors isForbiddenIp and the
+ *     private-network ranges in browserAuthz. Allowed wss?:// connections
+ *     still use the native WebSocket (the wrapper delegates).
+ *
+ *  2. WebRTC neutralisation: removes RTCPeerConnection, RTCSessionDescription,
+ *     and RTCIceCandidate from the window object so page JS cannot create a
+ *     peer connection at all. This prevents data-channel exfiltration and
+ *     IP leakage via STUN/TURN. Combined with the CDP Network.enable /
+ *     setRTCConfiguration override (applied separately via CDP below), this
+ *     provides layered defence. */
+const PAGE_GUARD_INIT_SCRIPT = `(function() {
+  // WebRTC neutralisation: remove peer connection constructors.
+  try { delete window.RTCPeerConnection; } catch (_) {}
+  try { delete window.RTCSessionDescription; } catch (_) {}
+  try { delete window.RTCIceCandidate; } catch (_) {}
+  // Also zero out webkit/moz-prefixed variants some legacy code still uses.
+  try { delete window.webkitRTCPeerConnection; } catch (_) {}
+  try { delete window.mozRTCPeerConnection; } catch (_) {}
+  // Override navigator.mediaDevices.getUserMedia to prevent media/camera
+  // capture that could be combined with a data channel.
+  try {
+    if (navigator.mediaDevices && typeof navigator.mediaDevices === 'object') {
+      Object.defineProperty(navigator, 'mediaDevices', { value: Object.assign({}, navigator.mediaDevices, { getUserMedia: () => Promise.reject(new DOMException('NotAllowedError')) }), configurable: false, writable: false });
+    }
+  } catch (_) {}
+  // WebSocket URL-blocking fallback (defence-in-depth, supplements
+  // routeWebSocket interception which fires at the Playwright layer).
+  var _NativeWS = window.WebSocket;
+  function _isForbiddenWsHost(url) {
+    try {
+      var u = new URL(url);
+      var h = u.hostname.replace(/^\\[|\\]$/g,'');
+      // Loopback / localhost
+      if (h === 'localhost' || h === '127.0.0.1' || h === '::1' || h.endsWith('.localhost') || h.endsWith('.local')) return true;
+      // Link-local (169.254.x.x) — cloud metadata endpoints live here
+      if (/^169\\.254\\./.test(h)) return true;
+      // RFC1918
+      if (/^10\\./.test(h)) return true;
+      if (/^172\\.(1[6-9]|2[0-9]|3[01])\\./.test(h)) return true;
+      if (/^192\\.168\\./.test(h)) return true;
+      // CGNAT
+      if (/^100\\.(6[4-9]|[7-9][0-9]|1([01][0-9]|2[0-7]))\\./.test(h)) return true;
+      // Explicit metadata hosts
+      if (h === '100.100.100.200' || h === 'metadata.google.internal' || h === 'metadata.goog') return true;
+    } catch (_) {}
+    return false;
+  }
+  window.WebSocket = function WrappedWebSocket(url, protocols) {
+    if (_isForbiddenWsHost(String(url))) {
+      throw new DOMException('WebSocket connection to ' + url + ' is blocked by Melaya egress policy', 'SecurityError');
+    }
+    return protocols !== undefined ? new _NativeWS(url, protocols) : new _NativeWS(url);
+  };
+  window.WebSocket.prototype = _NativeWS.prototype;
+  window.WebSocket.CONNECTING = _NativeWS.CONNECTING;
+  window.WebSocket.OPEN = _NativeWS.OPEN;
+  window.WebSocket.CLOSING = _NativeWS.CLOSING;
+  window.WebSocket.CLOSED = _NativeWS.CLOSED;
+})();`;
+/** Disable WebRTC at the CDP Network domain level in addition to the
+ *  init-script layer (belt-and-suspenders). Silently skips if CDP
+ *  session creation fails (e.g. attached browser, same-process frame). */
+export async function disableWebRtcViaCdp(cdpSession) {
+    try {
+        const cdp = cdpSession;
+        await cdp.send("Network.enable").catch(() => { });
+        // Force webRtcIpHandlingPolicy to disable_non_proxied_udp, which
+        // prevents IP leakage via STUN even if RTCPeerConnection is somehow
+        // re-instated by a polyfill.
+        await cdp.send("Page.setWebRTCIPHandlingPolicy", {
+            policy: "disable_non_proxied_udp",
+        }).catch(() => { });
+    }
+    catch {
+        // CDP domain unavailable on this browser build — init script alone.
+    }
+}
+/** Install request-level enforcement on a BrowserContext we OWN (launch
+ *  mode). Every document, subresource, XHR, redirect hop, and worker
+ *  script fetch flows through here; disallowed ones are aborted.
+ *  Downloads are default-denied via the page download handler.
+ *  WebSocket connections are intercepted via routeWebSocket (Playwright
+ *  1.48+) with a page-init-script fallback for older builds.
+ *  WebRTC is neutralised via an init script on every new page. */
+export async function enforceOnContext(context, policy, hooks) {
+    await context.route("**/*", async (route) => {
+        const url = route.request().url();
+        if (hooks.isCancelled?.()) {
+            await route.abort("blockedbyclient").catch(() => { });
+            return;
+        }
+        const d = await evaluateUrlResolved(url, policy);
+        if (d.allowed) {
+            await route.continue().catch(() => { });
+        }
+        else {
+            hooks.onViolation({ url, code: d.code, message: d.message, surface: "context_route" });
+            await route.abort("blockedbyclient").catch(() => { });
+        }
+    });
+    // Inject the WebSocket + WebRTC guard script into every new document
+    // BEFORE page JS runs.
+    await context.addInitScript({ content: PAGE_GUARD_INIT_SCRIPT }).catch(() => { });
+    context.on("page", (page) => {
+        void interceptWebSockets(page, policy, hooks);
+        void guardPage(page, policy, hooks, /*closeOnDeny*/ true);
+    });
+}
+/** Install enforcement on a SINGLE page (attach mode: we never take over
+ *  routing for the user's whole externally-owned browser context, only
+ *  the leased target the run operates on; navigation of the leased page
+ *  and its popups is still fully gated).
+ *  WebSocket interception and WebRTC neutralisation are applied to this
+ *  page and its popups in the same way as the owned-context path, scoped
+ *  to the single leased target. */
+export async function enforceOnPage(page, policy, hooks) {
+    await page.route("**/*", async (route) => {
+        const url = route.request().url();
+        if (hooks.isCancelled?.()) {
+            await route.abort("blockedbyclient").catch(() => { });
+            return;
+        }
+        const d = await evaluateUrlResolved(url, policy);
+        if (d.allowed) {
+            await route.continue().catch(() => { });
+        }
+        else {
+            hooks.onViolation({ url, code: d.code, message: d.message, surface: "page_route" });
+            await route.abort("blockedbyclient").catch(() => { });
+        }
+    });
+    // WebSocket + WebRTC for the leased page.
+    await page.addInitScript({ content: PAGE_GUARD_INIT_SCRIPT }).catch(() => { });
+    await interceptWebSockets(page, policy, hooks);
+    await guardPage(page, policy, hooks, /*closeOnDeny*/ false);
+    page.on("popup", (popup) => {
+        void popup.addInitScript({ content: PAGE_GUARD_INIT_SCRIPT }).catch(() => { });
+        void interceptWebSockets(popup, policy, hooks);
+        void guardPage(popup, policy, hooks, /*closeOnDeny*/ true);
+    });
+}
+/** CDP-target-creation gate: when a page/popup materializes, verify its
+ *  destination; deny -> close before the agent can observe or act on it.
+ *  Also default-denies automatic downloads (plan Section 10). */
+async function guardPage(page, policy, hooks, closeOnDeny) {
+    page.on("download", (download) => {
+        hooks.onViolation({
+            url: download.url(),
+            code: "effect_not_granted",
+            message: "automatic downloads are default-denied in Phase 1",
+            surface: "download",
+        });
+        void download.cancel().catch(() => { });
+    });
+    page.on("framenavigated", (frame) => {
+        const url = frame.url();
+        if (!url || url === "about:blank")
+            return;
+        const d = evaluateUrlSync(url, policy);
+        if (!d.allowed) {
+            hooks.onViolation({ url, code: d.code, message: d.message, surface: "frame_navigated" });
+            if (closeOnDeny && frame === page.mainFrame()) {
+                void page.close({ runBeforeUnload: false }).catch(() => { });
+            }
+        }
+    });
+    // Initial URL check for popups that spawn pre-navigated.
+    const url = page.url();
+    if (url && url !== "about:blank") {
+        const d = evaluateUrlSync(url, policy);
+        if (!d.allowed) {
+            hooks.onViolation({ url, code: d.code, message: d.message, surface: "target_created" });
+            if (closeOnDeny)
+                await page.close({ runBeforeUnload: false }).catch(() => { });
+        }
+    }
+}
+function truncate(s, n = 160) {
+    return s.length > n ? `${s.slice(0, n)}…` : s;
+}

package/dist/browserBridge.d.ts

@@ -0,0 +1,50 @@
+import type { BrowserGrant } from "./browserGrantVerify.js";
+import { type SpaceSpec } from "./sessionManager.js";
+import { type BrowserEngineId } from "./browserProvisioner.js";
+export interface BrowserRunSpec {
+    runId: string;
+    grant: BrowserGrant;
+    mode: "launch" | "attach";
+    engine?: BrowserEngineId;
+    cdpWsEndpoint?: string;
+    space?: SpaceSpec;
+    codeMode?: boolean;
+    headless?: boolean;
+}
+export interface BrowserBridge {
+    url: string;
+    port: number;
+    /** Register a verified run. Returns the per-run bearer token to inject
+     *  as MEL_BROWSER_TOKEN. The grant itself NEVER leaves this process. */
+    registerRun(spec: BrowserRunSpec): {
+        token: string;
+    };
+    /** Idempotent full teardown for one run: cancels in-flight ops,
+     *  releases leases, closes ONLY owned contexts, forgets the grant. */
+    teardownRun(runId: string, reason: string): Promise<void>;
+    teardownAll(reason: string): Promise<void>;
+    hasRun(runId: string): boolean;
+    /**
+     * Set the watch-lease state for a session (plan Section 10.f).
+     *
+     * Called by the connection layer when the server emits a
+     * `browser:watch` socket event `{ sessionId, active }`. When
+     * active=true, the bridge begins capturing frames at an adaptive FPS
+     * (change-detection, capped at 2-4 fps) and POSTing each JPEG frame
+     * to `framePostUrl` as `{ sessionId, runId, jpegB64 }` authenticated
+     * with the runner's relay nonce. When active=false, capturing stops.
+     *
+     * The producer runs only while a viewer is watching and stops
+     * automatically when the run is torn down.
+     */
+    setWatchLease(sessionId: string, active: boolean, framePostUrl: string, runAuthHeader: string): void;
+    shutdown(): Promise<void>;
+}
+export declare function startBrowserBridge(opts: {
+    log: (msg: string) => void;
+    verbose?: boolean;
+}): Promise<BrowserBridge>;
+export declare class BridgeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}