@browserbridge/bbx 1.8.0 → 1.9.0

package/packages/native-host/src/native-host.js

@@ -2,7 +2,12 @@
 
 import net from 'node:net';
 
-import { createFailure, ERROR_CODES, MAX_JSON_LINE_BYTES } from '../../protocol/src/index.js';
+import {
+  createFailure,
+  ERROR_CODES,
+  MAX_JSON_LINE_BYTES,
+  sanitizeIncidentalText,
+} from '../../protocol/src/index.js';
 import { readBridgeAuthToken } from './auth-token.js';
 import { createSocketBridgeTransport, getBridgeTransport } from './config.js';
 import { spawnBridgeDaemonProcess } from './daemon-process.js';
@@ -110,6 +115,16 @@ function isHostActivity(message) {
   );
 }
 
+/** @param {unknown} message */
+function isHostArtifactMessage(message) {
+  return Boolean(
+    message &&
+    typeof message === 'object' &&
+    typeof (/** @type {Record<string, unknown>} */ (message).type) === 'string' &&
+    String(/** @type {Record<string, unknown>} */ (message).type).startsWith('host.artifact.')
+  );
+}
+
 /**
  * @param {{ transport?: BridgeTransport, socketPath?: string }} [options={}]
  * @returns {Promise<void>}
@@ -130,7 +145,7 @@ export async function runNativeHost({
       response: createFailure(
         'native_bootstrap',
         ERROR_CODES.NATIVE_HOST_UNAVAILABLE,
-        error instanceof Error ? error.message : String(error)
+        sanitizeIncidentalText(error instanceof Error ? error.message : String(error))
       ),
     });
     return;
@@ -257,6 +272,14 @@ export async function runNativeHost({
           });
           return;
         }
+        if (isHostArtifactMessage(message)) {
+          const record = /** @type {Record<string, unknown>} */ (message);
+          await writeJsonLine(socket, {
+            ...record,
+            type: String(record.type).replace(/^host\./u, 'extension.'),
+          });
+          return;
+        }
         await writeJsonLine(socket, {
           type: 'extension.response',
           response: message,

package/packages/protocol/src/capability-values.js

@@ -20,6 +20,7 @@ export const CAPABILITIES = Object.freeze({
   PERFORMANCE_READ: 'performance.read',
   NETWORK_READ: 'network.read',
   NETWORK_INTERCEPT: 'network.intercept',
+  SENSITIVE_READ: 'sensitive.read',
 });
 
 export const DEFAULT_CAPABILITIES = Object.freeze([
@@ -42,4 +43,5 @@ export const DEFAULT_CAPABILITIES = Object.freeze([
   CAPABILITIES.PERFORMANCE_READ,
   CAPABILITIES.NETWORK_READ,
   CAPABILITIES.NETWORK_INTERCEPT,
+  CAPABILITIES.SENSITIVE_READ,
 ]);

package/packages/protocol/src/defaults.js

@@ -21,6 +21,9 @@ export const DEFAULT_MAX_HTML_LENGTH = 2000;
 export const DEFAULT_A11Y_MAX_NODES = 500;
 export const DEFAULT_A11Y_MAX_DEPTH = 6;
 export const DEFAULT_NETWORK_LIMIT = 50;
+export const DEFAULT_HAR_LIMIT = 50;
+export const MAX_HAR_ENTRIES = 200;
+export const HAR_AUTO_INLINE_BYTES = 262_144;
 export const DEFAULT_CONSOLE_LIMIT = 50;
 export const DEFAULT_VIEWPORT_WIDTH = 1280;
 export const DEFAULT_VIEWPORT_HEIGHT = 720;
@@ -34,6 +37,31 @@ export const MAX_NATIVE_MESSAGE_BYTES = 1_048_576;
 /** Maximum size of one newline-delimited daemon socket message in bytes. */
 export const MAX_JSON_LINE_BYTES = MAX_NATIVE_MESSAGE_BYTES;
 
+/** Maximum UTF-8 size of an exact sensitive value returned atomically. */
+export const MAX_SENSITIVE_VALUE_BYTES = 262_144;
+
+/** Maximum calls accepted by any read-only batch surface. */
+export const MAX_BATCH_CALLS = 20;
+
+/** Maximum read-only batch calls executing concurrently. */
+export const MAX_BATCH_CONCURRENCY = 5;
+export const SCREENSHOT_AUTO_INLINE_BYTES = 262_144;
+export const SCREENSHOT_MAX_INLINE_BYTES = 524_288;
+export const ARTIFACT_CHUNK_BYTES = 196_608;
+export const MAX_ARTIFACT_BYTES = 33_554_432;
+export const MAX_ARTIFACT_CLIENT_BYTES = 67_108_864;
+export const MAX_ARTIFACT_TOTAL_BYTES = 268_435_456;
+export const MAX_ARTIFACTS_PER_CLIENT = 16;
+export const ARTIFACT_TTL_MS = 300_000;
+
+/** DOM baseline retention and storage limits. */
+export const DOM_BASELINE_TTL_MS = 300_000;
+export const MAX_DOM_BASELINES_PER_TAB = 8;
+export const MAX_DOM_BASELINES_GLOBAL = 32;
+export const MAX_DOM_BASELINE_BYTES_PER_TAB = 1_048_576;
+export const MAX_DOM_BASELINE_BYTES_GLOBAL = 4_194_304;
+export const MAX_DOM_BASELINE_BYTES = 262_144;
+
 /** Default timeout for a bridge request awaiting an extension response (ms). */
 export const DEFAULT_DAEMON_PENDING_TIMEOUT_MS = 30_000;
 

package/packages/protocol/src/errors.js

@@ -16,7 +16,15 @@ export const ERROR_CODES = Object.freeze({
   DIALOG_NOT_OPEN: 'DIALOG_NOT_OPEN',
   DIALOG_ACTION_CONFLICT: 'DIALOG_ACTION_CONFLICT',
   RESULT_TRUNCATED: 'RESULT_TRUNCATED',
-  RATE_LIMITED: 'RATE_LIMITED',
+  RESULT_TOO_LARGE: 'RESULT_TOO_LARGE',
+  SENSITIVE_TARGET_NOT_FOUND: 'SENSITIVE_TARGET_NOT_FOUND',
+  CONTENT_SCRIPT_UNAVAILABLE: 'CONTENT_SCRIPT_UNAVAILABLE',
+  ARTIFACT_NOT_FOUND: 'ARTIFACT_NOT_FOUND',
+  ARTIFACT_QUOTA_EXCEEDED: 'ARTIFACT_QUOTA_EXCEEDED',
+  ARTIFACT_TRANSFER_INVALID: 'ARTIFACT_TRANSFER_INVALID',
+  DOM_BASELINE_NOT_FOUND: 'DOM_BASELINE_NOT_FOUND',
+  DOM_BASELINE_INVALIDATED: 'DOM_BASELINE_INVALIDATED',
+  DOM_BASELINE_QUOTA_EXCEEDED: 'DOM_BASELINE_QUOTA_EXCEEDED',
   INTERNAL_ERROR: 'INTERNAL_ERROR',
   INVALID_REQUEST: 'INVALID_REQUEST',
   NATIVE_HOST_UNAVAILABLE: 'NATIVE_HOST_UNAVAILABLE',
@@ -38,6 +46,15 @@ export const ERROR_RECOVERY = Object.freeze({
     retry: false,
     hint: 'Result was truncated to fit the response budget. Narrow the query or raise the relevant budget if more detail is required.',
   },
+  [ERROR_CODES.RESULT_TOO_LARGE]: {
+    retry: false,
+    hint: 'The result exceeds its atomic delivery limit. For screenshots, use artifact delivery, a smaller region, lower scale, or lossy compression. For sensitive reads, use a narrower exact target; partial values are never returned.',
+  },
+  [ERROR_CODES.SENSITIVE_TARGET_NOT_FOUND]: {
+    retry: false,
+    alternativeMethod: 'page.get_storage',
+    hint: 'The exact storage key does not exist. Use page.get_storage to inspect metadata before another deliberate sensitive read.',
+  },
   [ERROR_CODES.ELEMENT_STALE]: {
     retry: false,
     alternativeMethod: 'dom.query',
@@ -97,10 +114,36 @@ export const ERROR_RECOVERY = Object.freeze({
     retryAfterMs: 1000,
     hint: 'Operation exceeded the time limit. Retry once, or simplify the request (smaller maxNodes, narrower selector).',
   },
-  [ERROR_CODES.RATE_LIMITED]: {
-    retry: true,
-    retryAfterMs: 2000,
-    hint: 'Too many requests. Back off and retry after a short delay.',
+  [ERROR_CODES.CONTENT_SCRIPT_UNAVAILABLE]: {
+    retry: false,
+    hint: 'The page cannot host the Browser Bridge content script. Switch to a normal http(s) page in the enabled window.',
+  },
+  [ERROR_CODES.ARTIFACT_NOT_FOUND]: {
+    retry: false,
+    hint: 'The artifact is missing, expired, deleted, or owned by another client. Capture it again.',
+  },
+  [ERROR_CODES.ARTIFACT_QUOTA_EXCEEDED]: {
+    retry: false,
+    hint: 'Artifact storage quota was exceeded. Delete unneeded artifacts or retry after expiry.',
+  },
+  [ERROR_CODES.ARTIFACT_TRANSFER_INVALID]: {
+    retry: false,
+    hint: 'Artifact transfer validation failed. Capture the screenshot again.',
+  },
+  [ERROR_CODES.DOM_BASELINE_NOT_FOUND]: {
+    retry: false,
+    alternativeMethod: 'dom.baseline.create',
+    hint: 'The DOM baseline is missing, expired, or released. Create a new baseline before comparing or describing it.',
+  },
+  [ERROR_CODES.DOM_BASELINE_INVALIDATED]: {
+    retry: false,
+    alternativeMethod: 'dom.baseline.create',
+    hint: 'The page document or baseline scope changed. Create a new baseline in the current document.',
+  },
+  [ERROR_CODES.DOM_BASELINE_QUOTA_EXCEEDED]: {
+    retry: false,
+    alternativeMethod: 'dom.baseline.release',
+    hint: 'DOM baseline storage quota was exceeded. Release unneeded baselines, narrow the selector, or reduce maxNodes and textBudget before creating another baseline.',
   },
   [ERROR_CODES.EXTENSION_DISCONNECTED]: {
     retry: true,

package/packages/protocol/src/incidental-sanitizer.js

@@ -0,0 +1,197 @@
+// @ts-check
+
+const DEFAULT_MAX_STRING_LENGTH = 4_096;
+const DEFAULT_MAX_DEPTH = 8;
+const DEFAULT_MAX_NODES = 1_000;
+const REDACTED = '[redacted]';
+const REDACTED_PATH = '[redacted-path]';
+
+const SENSITIVE_KEYS = new Set([
+  'authorization',
+  'proxyauthorization',
+  'cookie',
+  'setcookie',
+  'password',
+  'passphrase',
+  'secret',
+  'clientsecret',
+  'token',
+  'accesstoken',
+  'refreshtoken',
+  'idtoken',
+  'authtoken',
+  'apikey',
+  'credential',
+  'credentials',
+]);
+
+/** @param {string} key */
+export function isSensitiveIncidentalKey(key) {
+  return SENSITIVE_KEYS.has(key.toLowerCase().replaceAll(/[^a-z0-9]/gu, ''));
+}
+
+/**
+ * Sanitize a URL that appears incidentally in logs, activity, or diagnostics.
+ * Query-key context is retained while credentials, values, and fragments are
+ * discarded.
+ *
+ * @param {unknown} value
+ * @param {number} [maxLength]
+ * @returns {string}
+ */
+export function sanitizeIncidentalUrl(value, maxLength = DEFAULT_MAX_STRING_LENGTH) {
+  const raw = typeof value === 'string' ? value.slice(0, maxLength) : String(value ?? '');
+  if (!raw) return '';
+  if (/^data:/iu.test(raw)) {
+    const mime = raw
+      .slice(5)
+      .split(/[;,]/u, 1)[0]
+      .replace(/[^a-z0-9./+-]/giu, '')
+      .slice(0, 100);
+    return mime ? `data:${mime};${REDACTED}` : `data:${REDACTED}`;
+  }
+  if (/^blob:/iu.test(raw)) {
+    try {
+      return `blob:${new URL(raw.slice(5)).origin}/${REDACTED}`.slice(0, maxLength);
+    } catch {
+      return `blob:${REDACTED}`;
+    }
+  }
+  if (/^file:/iu.test(raw)) {
+    try {
+      return `file:${sanitizeIncidentalPath(decodeURIComponent(new URL(raw).pathname))}`;
+    } catch {
+      return `file:${REDACTED_PATH}`;
+    }
+  }
+  try {
+    const parsed = new URL(raw);
+    parsed.username = '';
+    parsed.password = '';
+    parsed.hash = '';
+    for (const key of new Set(parsed.searchParams.keys())) {
+      parsed.searchParams.set(key, REDACTED);
+    }
+    return parsed.href.slice(0, maxLength);
+  } catch {
+    const withoutCredentials = raw.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@\s]*@/iu, '$1');
+    const summary = withoutCredentials.split(/[?#]/u, 1)[0];
+    return summary ? summary.slice(0, maxLength) : '[redacted-url]';
+  }
+}
+
+/**
+ * Reduce a local path to a basename-only marker.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function sanitizeIncidentalPath(value) {
+  const raw = typeof value === 'string' ? value : String(value ?? '');
+  const basename = raw.split(/[\\/]/u).filter(Boolean).at(-1)?.slice(0, 160);
+  return basename ? `${REDACTED_PATH}/${basename}` : REDACTED_PATH;
+}
+
+/**
+ * Sanitize secrets, URLs, and paths embedded in an incidental text message.
+ *
+ * @param {unknown} value
+ * @param {number} [maxLength]
+ * @returns {string}
+ */
+export function sanitizeIncidentalText(value, maxLength = DEFAULT_MAX_STRING_LENGTH) {
+  let text = typeof value === 'string' ? value : String(value ?? '');
+  text = text.replace(
+    /\b(authorization|proxy-authorization)\s*:\s*[^\r\n,;]+/giu,
+    (_match, name) => `${name}: ${REDACTED}`
+  );
+  text = text.replace(/\b(set-cookie|cookie)\s*:\s*[^\r\n]+/giu, (_match, name) => {
+    return `${name}: ${REDACTED}`;
+  });
+  text = text.replace(
+    /\b(?:https?|file|blob|chrome|chrome-extension|edge|devtools):[^\s"'<>]+/giu,
+    (url) => sanitizeIncidentalUrl(url, maxLength)
+  );
+  text = text.replace(/\bdata:[^\s"'<>]+/giu, (url) => sanitizeIncidentalUrl(url, maxLength));
+  text = text.replace(/(?:^|[\s"'(])([a-z]:\\[^\s"')]+|\\\\[^\s"')]+)/giu, (match, path) =>
+    match.replace(path, sanitizeIncidentalPath(path))
+  );
+  text = text.replace(
+    /(?:^|[\s"'(])(\/(?:Users|home|private|var|tmp|opt|etc|root|usr|srv|mnt|Volumes|Library|Applications)\/[^\s"')]+)/gu,
+    (match, path) => match.replace(path, sanitizeIncidentalPath(path))
+  );
+  return text.slice(0, maxLength);
+}
+
+/**
+ * Recursively sanitize incidental structured data while bounding traversal.
+ * Explicit sensitive-read values must never pass through this helper.
+ *
+ * @param {unknown} value
+ * @param {{ maxDepth?: number, maxNodes?: number, maxStringLength?: number }} [options]
+ * @returns {unknown}
+ */
+export function sanitizeIncidentalValue(value, options = {}) {
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
+  const maxStringLength = options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH;
+  const seen = new WeakSet();
+  let nodes = 0;
+
+  /** @param {unknown} current @param {number} depth @param {string | null} key @returns {unknown} */
+  const visit = (current, depth, key) => {
+    nodes += 1;
+    if (nodes > maxNodes) return '[truncated]';
+    if (key !== null && isSensitiveIncidentalKey(key)) return REDACTED;
+    if (typeof current === 'string') {
+      if (key && /url|uri|href|endpoint/iu.test(key)) {
+        return sanitizeIncidentalUrl(current, maxStringLength);
+      }
+      if (key && /path|directory|filename/iu.test(key) && isAbsolutePath(current)) {
+        return sanitizeIncidentalPath(current);
+      }
+      return sanitizeIncidentalText(current, maxStringLength);
+    }
+    if (
+      current === null ||
+      typeof current === 'number' ||
+      typeof current === 'boolean' ||
+      typeof current === 'undefined'
+    ) {
+      return current;
+    }
+    if (
+      typeof current === 'bigint' ||
+      typeof current === 'symbol' ||
+      typeof current === 'function'
+    ) {
+      return sanitizeIncidentalText(current, maxStringLength);
+    }
+    if (current instanceof Error) {
+      return {
+        name: sanitizeIncidentalText(current.name, maxStringLength),
+        message: sanitizeIncidentalText(current.message, maxStringLength),
+      };
+    }
+    if (depth >= maxDepth) return '[truncated]';
+    if (seen.has(current)) return '[circular]';
+    seen.add(current);
+    if (Array.isArray(current)) {
+      return current.map((item) => visit(item, depth + 1, null));
+    }
+    const result = /** @type {Record<string, unknown>} */ ({});
+    for (const [childKey, childValue] of Object.entries(current)) {
+      result[sanitizeIncidentalText(childKey, 160)] = visit(childValue, depth + 1, childKey);
+    }
+    return result;
+  };
+
+  return visit(value, 0, null);
+}
+
+/** @param {string} value */
+function isAbsolutePath(value) {
+  return /^(?:[a-z]:\\|\\\\|\/(?:Users|home|private|var|tmp|opt|etc|root|usr|srv|mnt|Volumes|Library|Applications)\/)/iu.test(
+    value
+  );
+}

package/packages/protocol/src/index.js

@@ -8,8 +8,10 @@ export * from './budget.js';
 export * from './capabilities.js';
 export * from './defaults.js';
 export * from './errors.js';
+export * from './incidental-sanitizer.js';
 export * from './json-lines.js';
 export * from './payload-cost.js';
 export * from './protocol.js';
 export * from './registry.js';
+export * from './recovery-telemetry.js';
 export * from './summary.js';