@browserbridge/bbx 1.8.0 → 1.9.0

package/PRIVACY.md

@@ -1,6 +1,6 @@
 # Browser Bridge (BBX) Privacy Policy
 
-Last updated: 2026-07-22
+Last updated: 2026-07-23
 
 ## Overview
 
@@ -16,8 +16,9 @@ When you enable Browser Bridge for a Chrome window, Browser Bridge can access pa
 - Console messages and uncaught page errors
 - Network request metadata captured from page `fetch` and `XMLHttpRequest` activity, such as URL, method, status, timing, type, timestamp, and size
 - Optional Chrome DevTools Protocol metadata for broader resource activity, including request ID, redacted URL, method, resource type, status, MIME type, protocol, cache indicators, redirects, failure reason, duration, and timestamp
+- Metadata-only HAR 1.2 documents exported from an explicitly armed CDP capture, including sanitized URLs and observed status, redirect, failure, cache, and service-worker metadata
 - Current JavaScript dialog information when observable and explicitly requested, including dialog type, bounded message text, and bounded default prompt text
-- `localStorage` and `sessionStorage` values when explicitly requested
+- `localStorage` and `sessionStorage` key metadata through ordinary inspection, and one exact value only through a deliberate `sensitive.read` request
 - Screenshots or cropped image captures when explicitly requested
 - User-triggered interaction data and results such as clicks, native pointer movement/drag, DOM or native text dispatch, key presses, selection changes, dialog decisions, and navigation actions
 - Bounded semantic descriptors for optional stale-element recovery, represented in memory with normalized hashes and structural context rather than page text values or attributes written into the application DOM
@@ -26,10 +27,31 @@ All-resource network inspection excludes request and response bodies, cookies,
 authorization values, and complete headers. It removes URL credentials and
 fragments, replaces query parameter values with a redaction marker, and
 summarizes data/blob URLs before returning them. Browser Bridge does not expose
-these excluded values through that feature.
+these excluded values through that feature. HAR exports use the same URL
+sanitization: schemes, hosts, paths, and query parameter names remain visible,
+but credentials, fragments, and query values do not. HAR request/response
+headers and cookies are empty, bodies are absent, and unavailable byte sizes and
+timing phases are reported as `-1`.
+
+Recovery telemetry contains only fixed category names, bounded counts, rates,
+timestamps, and active-loop flags. It does not include page content, URLs,
+selectors, method/group identifiers, request payloads, or error text. The fixed
+categories are automatic MCP retry, stale-reference recovery, debugger
+reattachment, content-script reinjection, native-host reconnect, and request
+outcome.
 
 Browser Bridge is designed for local debugging and automation of the browser state you intentionally expose to it.
 
+Ordinary storage inspection does not return value prefixes. Exact Web Storage
+values require a separate key-specific sensitive read, are returned whole or
+rejected whole, are never batched or retried automatically, and produce a
+textual Sensitive access warning in Recent Activity. The warning stores the
+source/category and key length, not the key or value. Powerful explicit methods
+such as page evaluation and DOM inspection can still expose page data by design.
+Every page evaluation is therefore labeled as Sensitive access in Recent
+Activity, and its returned value and derived size are excluded from persisted
+activity diagnostics.
+
 ## How Browser Bridge uses data
 
 Browser Bridge uses this data only to provide its user-facing purpose: letting you inspect, test, and patch the currently enabled browser window from a connected developer tool or agent.
@@ -61,9 +83,13 @@ Browser Bridge keeps data only as long as needed for the current local session a
 
 - Window enablement state is stored in session storage and cleared when disabled or when the browser session ends.
 - Action log entries are stored for the current browser session only.
+- Incidental action/log URLs remove credentials and fragments and redact query values; sensitive structured fields and local path prefixes are reduced before persistence.
 - Console and fetch/XHR network buffers are bounded in memory and cleared when disabled or when the page state is reset.
 - Optional CDP network capture is bounded in memory, explicitly started/stopped, expires after a safety interval, and is cleared on relevant debugger, tab, or access teardown.
+- HAR export does not start, stop, or clear capture. Inline size limits remove whole oldest entries; artifact delivery uses opaque owner-scoped handles with no browser-host path. Artifacts expire after five minutes, are removed on daemon/extension teardown, and use private daemon directory/file modes on POSIX systems.
+- Recovery telemetry is held in fixed five-second buckets over a five-minute process-local window. Extension-side summaries reset with the extension service worker, daemon summaries reset with the daemon, and neither is durable history.
 - Dialog message/default prompt text is returned to the requesting caller when inspected but is excluded from persisted action-log summaries and size diagnostics.
+- Exact sensitive values traverse the selected client in memory but are excluded from action summaries, diagnostic size counters, daemon logs, and automatic artifact storage.
 - Patch rollback records and remembered element references live in the current document. Browser Bridge attempts patch rollback when access is disabled or switched, while page replacement/navigation removes document-local state.
 - Hashed semantic descriptors used for optional stale recovery are bounded in memory with the element registry and do not survive the document/registry lifecycle.
 

package/README.md

@@ -93,6 +93,7 @@ Managed installs support OpenAI Codex, Claude Code, Cursor, GitHub Copilot, Open
 ## What it's for
 
 - Debugging a UI on `localhost`: read DOM, computed styles, layout, console logs, and network state without a screenshot
+- Exporting sanitized, metadata-only HAR 1.2 evidence after explicitly capturing a network reproduction
 - Verifying a code change actually rendered the expected result in Chrome
 - Patching the live page to prove a fix visually, then moving it into source and rolling the patch back
 - Running structured browser checks from any local agent or IDE, not just one AI product
@@ -108,9 +109,10 @@ Browser Bridge is optimized for the opposite starting point: **inspect the state
 1. Install [Browser Bridge from the Chrome Web Store](https://chromewebstore.google.com/detail/browser-bridge/jjjkmmcdkpcgamlopogicbnnhdgebhie) in Chrome or another Chromium-based browser
 2. `npm install -g @browserbridge/bbx` - installs the CLI and native host
 3. Run `bbx install` (Chromium on Linux, Chrome elsewhere), or target a specific browser with `bbx install --browser chrome`, `bbx install --browser edge`, `bbx install --browser brave`, `bbx install --browser chromium`, or `bbx install --browser arc`
-4. In the extension side panel, install MCP or CLI (skill) for your agent of choice
-5. Enable Browser Bridge for the browser window you want to inspect/control with the AI agent
-6. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the installed Browser Bridge skill in CLI mode (`/browser-bridge`, `browser-bridge`, or the client-specific skill trigger)
+4. Optionally run `bbx config set auto-update compatible` to keep the global CLI on the highest stable npm release supported by the connected extension
+5. In the extension side panel, install MCP or CLI (skill) for your agent of choice
+6. Enable Browser Bridge for the browser window you want to inspect/control with the AI agent
+7. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the installed Browser Bridge skill in CLI mode (`/browser-bridge`, `browser-bridge`, or the client-specific skill trigger)
 
 On Ubuntu, Chromium is commonly installed as a strict snap, and Flatpak Chromium is similarly sandboxed. If native messaging stays disconnected there, use a non-sandboxed Chromium-based browser such as Google Chrome, Brave, or Edge.
 
@@ -122,12 +124,17 @@ MCP mode is self-contained: the server exposes tools and startup instructions, s
 - Requests default to the active tab in that window unless a tab is targeted explicitly
 - Targeted input actions reject hidden, disabled, ambiguous, stale, or obscured targets instead of silently guessing; their responses report the resolution and DOM/CDP execution path (`cdp_press_key` and `scroll_into_view` use separate contracts)
 - Native pointer/text input, dialog handling, all-resource network capture, accessibility trees, screenshots, and raw CDP reads use the existing debugger permission only when requested
+- HAR export is a read of an already armed CDP capture: start capture, reproduce, export, then stop. Export never starts, stops, or clears capture, and omits headers, cookies, bodies, authorization values, and unsupported size/timing detail
+- HAR and screenshot artifacts are opaque, owner-scoped daemon handles with a five-minute lifetime and no browser-host path; CLI capture commands download, verify, delete, and write them on the CLI host
 - Element references are document-local and strict by default; stale input recovery is opt-in, same-document, requires one strong unique semantic match, and fails safely when its bounded scan cannot prove uniqueness
+- Semantic DOM baselines provide explicit create/compare/describe/release verification without modifying the page; compact snapshots stay memory-only, expire after five minutes, and are invalidated by navigation or access teardown
 - Patches keep per-document rollback history and Browser Bridge attempts best-effort rollback when window access is disabled or switched; committing the patch baseline keeps current changes but discards their rollback history
 - URL waits observe full navigation and same-document SPA changes, and report the final URL and observed navigation kind
 - Structured DOM/style/layout reads are the primary transport; screenshots are a fallback
 - Browser input dispatch does not prove the application accepted the intended change, so agents should verify with a wait or structured read
 - Open-ended investigation should start with structured reads on a smaller, lower-cost subagent when the client supports delegation
+- Recovery diagnostics use process-local five-minute counters for six fixed, content-free categories. `health.ping`, `daemon.metrics`, and `bbx doctor` expose no page data; three failures in the same category group within 60 seconds produce an active-loop warning and fixed recovery guidance
+- Performance reads are raw browser-maintained CDP counter point samples with browser-defined names and units, not Web Vitals or Browser Bridge navigation measurements
 - The native host daemon auto-starts on demand
 
 ## Documentation

package/SECURITY.md

@@ -10,6 +10,13 @@ Only the latest version published to npm (`@browserbridge/bbx`) and the Chrome W
 receives security fixes. Older versions are not patched retroactively; upgrade to the
 latest release before reporting.
 
+The optional `compatible` npm auto-update policy follows the connected
+extension's advertised `major.minor` protocol line. It installs only stable
+versions of the fixed `@browserbridge/bbx` package, never downgrades, and runs
+only from a verified global npm installation. If an older extension line is
+still installed, this policy may intentionally select an older release than the
+latest security-supported version.
+
 ## Reporting a Vulnerability
 
 Please do **not** open a public GitHub issue for security vulnerabilities.
@@ -50,3 +57,8 @@ Out of scope:
 - Proxy mode (LAN exposure) is opt-in via `bbx proxy enable` and always provisions a
   token; an invalid `bindHost` in the config rejects the config rather than widening
   the bind address.
+- Incidental persisted activity and daemon logs recursively redact sensitive keys,
+  URL credentials/fragments/query values, and local path prefixes.
+- Ordinary Web Storage reads return key/presence metadata only. The separate
+  `sensitive.read` method requires one exact key, is excluded from batches and
+  automatic retries, and returns a value whole or fails atomically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -81,12 +81,18 @@
   "devDependencies": {
     "@types/chrome": "^0.2.2",
     "@types/node": "^26.1.1",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "c8": "^12.0.0",
+    "har-schema": "^2.0.0",
     "oxfmt": "^0.60.0",
     "oxlint": "^1.75.0",
     "tsx": "^4.23.1",
     "typescript": "^7.0.2"
   },
+  "overrides": {
+    "@hono/node-server": "2.0.11"
+  },
   "engines": {
     "node": ">=20"
   }

package/packages/agent-client/src/cli-args.js

@@ -84,6 +84,41 @@ export function extractScreenshotFlags(args) {
   return { format: rawFormat, quality, rest };
 }
 
+/**
+ * @param {string[]} args
+ * @returns {{ limit: number | undefined, urlPattern: string | undefined, delivery: 'inline' | 'artifact' | 'auto', rest: string[] }}
+ */
+export function extractHarFlags(args) {
+  const rest = [...args];
+  const limitIndex = rest.indexOf('--limit');
+  let limit;
+  if (limitIndex !== -1) {
+    limit = Number(rest[limitIndex + 1]);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+      throw new Error('--limit must be an integer from 1 to 200.');
+    }
+    rest.splice(limitIndex, 2);
+  }
+
+  const urlPatternIndex = rest.indexOf('--url-pattern');
+  const urlPattern = urlPatternIndex === -1 ? undefined : rest[urlPatternIndex + 1];
+  if (urlPatternIndex !== -1) {
+    if (!urlPattern || urlPattern.startsWith('--')) {
+      throw new Error('--url-pattern requires a value.');
+    }
+    rest.splice(urlPatternIndex, 2);
+  }
+
+  const deliveryIndex = rest.indexOf('--delivery');
+  const rawDelivery = deliveryIndex === -1 ? 'auto' : rest[deliveryIndex + 1];
+  if (rawDelivery !== 'inline' && rawDelivery !== 'artifact' && rawDelivery !== 'auto') {
+    throw new Error('--delivery must be inline, artifact, or auto.');
+  }
+  if (deliveryIndex !== -1) rest.splice(deliveryIndex, 2);
+
+  return { limit, urlPattern, delivery: rawDelivery, rest };
+}
+
 /**
  * @param {string[]} args
  * @returns {Promise<{ tabId: number | null, method: BridgeMethod, params: Record<string, unknown> }>}

package/packages/agent-client/src/cli-batch.js

@@ -2,6 +2,9 @@
 
 import {
   getProtocolVersion,
+  isBatchSafeBridgeCall,
+  MAX_BATCH_CALLS,
+  MAX_BATCH_CONCURRENCY,
   METHODS,
   summarizeBatchErrorItem,
   summarizeBatchResponseItem,
@@ -27,6 +30,10 @@ import { requestBridge } from './runtime.js';
  * }} InvalidBatchItem
  */
 
+/**
+ * @typedef {{ method: BridgeMethod, params: Record<string, unknown>, tabId: number | null }} PreparedBatchCall
+ */
+
 /**
  * @typedef {ReturnType<typeof summarizeBatchResponseItem>
  *   | ReturnType<typeof summarizeBatchErrorItem>
@@ -59,8 +66,8 @@ function invalidBatchItem(method, message) {
 }
 
 /**
- * Parse and execute `bbx batch '[...]'`: validate each call, run them in
- * parallel against the bridge, and return per-call summary items.
+ * Parse and execute `bbx batch '[...]'`: validate read-only calls, run them
+ * with bounded concurrency, and return ordered per-call summary items.
  *
  * @param {import('./client.js').BridgeClient} client
  * @param {string | undefined} input - Raw JSON array argument
@@ -80,61 +87,117 @@ export async function runBatchCalls(client, input, source) {
   if (!Array.isArray(calls)) {
     throw new Error('Batch input must be a JSON array.');
   }
-  if (!client.connected) {
-    await client.connect();
+  if (calls.length === 0 || calls.length > MAX_BATCH_CALLS) {
+    throw new Error(`Batch input must contain between 1 and ${MAX_BATCH_CALLS} calls.`);
+  }
+  const prepared = calls.map((call) => prepareBatchCall(call));
+  if (prepared.some((item) => 'error' in item)) {
+    return prepared.map((item) =>
+      'error' in item
+        ? item.error
+        : invalidBatchItem(
+            item.value.method,
+            'Batch was not executed because another call failed validation.'
+          )
+    );
+  }
+  const validPrepared = /** @type {Array<{ value: PreparedBatchCall }>} */ (prepared);
+  if (!client.connected) await client.connect();
+  return mapWithConcurrency(validPrepared, MAX_BATCH_CONCURRENCY, async (item) => {
+    const { method, params, tabId } = item.value;
+    const startTime = Date.now();
+    try {
+      const response = await requestBridge(client, method, params, {
+        tabId,
+        source,
+      });
+      return summarizeBatchResponseItem({
+        method,
+        tabId,
+        response,
+        durationMs: Date.now() - startTime,
+      });
+    } catch (err) {
+      return summarizeBatchErrorItem({
+        method,
+        tabId,
+        error: err,
+        durationMs: Date.now() - startTime,
+      });
+    }
+  });
+}
+
+/**
+ * @param {unknown} call
+ * @returns {{ value: PreparedBatchCall } | { error: InvalidBatchItem }}
+ */
+function prepareBatchCall(call) {
+  if (!call || typeof call !== 'object' || Array.isArray(call)) {
+    return { error: invalidBatchItem('', 'Each batch call needs a method.') };
+  }
+  const batchCall = /** @type {Record<string, unknown>} */ (call);
+  if (typeof batchCall.method !== 'string') {
+    return { error: invalidBatchItem('', 'Each batch call needs a method.') };
+  }
+  if (!METHODS.includes(/** @type {BridgeMethod} */ (batchCall.method))) {
+    return {
+      error: invalidBatchItem(batchCall.method, `Unknown bridge method "${batchCall.method}".`),
+    };
+  }
+  const method = /** @type {BridgeMethod} */ (batchCall.method);
+  if (method === 'sensitive.read') {
+    return {
+      error: invalidBatchItem(
+        method,
+        'sensitive.read is never allowed in batch execution. Call it sequentially.'
+      ),
+    };
+  }
+  if (
+    batchCall.params !== undefined &&
+    (!batchCall.params || typeof batchCall.params !== 'object' || Array.isArray(batchCall.params))
+  ) {
+    return { error: invalidBatchItem(method, 'Batch call params must be a JSON object.') };
+  }
+  const params =
+    batchCall.params === undefined ? {} : /** @type {Record<string, unknown>} */ (batchCall.params);
+  if (!isBatchSafeBridgeCall(method, params)) {
+    return {
+      error: invalidBatchItem(
+        method,
+        `${method} is not safe for batch execution. Call it sequentially.`
+      ),
+    };
   }
-  return Promise.all(
-    calls.map(async (call) => {
-      if (!call || typeof call !== 'object' || Array.isArray(call)) {
-        return invalidBatchItem('', 'Each batch call needs a method.');
-      }
-      const batchCall = /** @type {Record<string, unknown>} */ (call);
-      if (typeof batchCall.method !== 'string') {
-        return invalidBatchItem('', 'Each batch call needs a method.');
-      }
-      if (!METHODS.includes(/** @type {BridgeMethod} */ (batchCall.method))) {
-        return invalidBatchItem(batchCall.method, `Unknown bridge method "${batchCall.method}".`);
-      }
-      const method = /** @type {BridgeMethod} */ (batchCall.method);
-      if (
-        batchCall.params !== undefined &&
-        (!batchCall.params ||
-          typeof batchCall.params !== 'object' ||
-          Array.isArray(batchCall.params))
-      ) {
-        return invalidBatchItem(method, 'Batch call params must be a JSON object.');
-      }
-      const params =
-        batchCall.params === undefined
-          ? {}
-          : /** @type {Record<string, unknown>} */ (batchCall.params);
-      const tabId =
-        methodNeedsTab(method) &&
-        typeof batchCall.tabId === 'number' &&
-        Number.isInteger(batchCall.tabId) &&
-        batchCall.tabId > 0
-          ? batchCall.tabId
-          : null;
-      const startTime = Date.now();
-      try {
-        const response = await requestBridge(client, method, params, {
-          tabId,
-          source,
-        });
-        return summarizeBatchResponseItem({
-          method,
-          tabId,
-          response,
-          durationMs: Date.now() - startTime,
-        });
-      } catch (err) {
-        return summarizeBatchErrorItem({
-          method,
-          tabId,
-          error: err,
-          durationMs: Date.now() - startTime,
-        });
-      }
-    })
-  );
+  const tabId =
+    methodNeedsTab(method) &&
+    typeof batchCall.tabId === 'number' &&
+    Number.isInteger(batchCall.tabId) &&
+    batchCall.tabId > 0
+      ? batchCall.tabId
+      : null;
+  return { value: { method, params, tabId } };
+}
+
+/**
+ * @template T, R
+ * @param {T[]} values
+ * @param {number} concurrency
+ * @param {(value: T) => Promise<R>} callback
+ * @returns {Promise<R[]>}
+ */
+async function mapWithConcurrency(values, concurrency, callback) {
+  /** @type {R[]} */
+  const results = new Array(values.length);
+  let nextIndex = 0;
+  const workers = Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+    while (nextIndex < values.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await callback(values[index]);
+    }
+  });
+  await Promise.all(workers);
+  return results;
 }

package/packages/agent-client/src/cli-output.js

@@ -28,10 +28,17 @@ export async function printSummary(response, method) {
 
 /**
  * @param {import('../../protocol/src/types.js').BridgeResponse} response
+ * @param {string} [method]
  * @returns {void}
  */
-export function printCallResponse(response) {
+export function printCallResponse(response, method) {
   if (response.ok) {
+    if (method === 'sensitive.read') {
+      process.stdout.write(
+        `${JSON.stringify(response.result, null, process.stdout.isTTY ? 2 : undefined)}\n`
+      );
+      return;
+    }
     printJson(response.result);
     return;
   }