@browserbridge/bbx 1.7.8 → 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';
@@ -28,7 +33,8 @@ import { createNativeMessageReader, createNativeMessageWriter, writeJsonLine } f
  * @typedef {{
  *   type?: string,
  *   browserName?: string,
- *   profileLabel?: string
+ *   profileLabel?: string,
+ *   browserExtensionId?: string
  * }} HostIdentityMessage
  */
 
@@ -109,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>}
@@ -129,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;
@@ -238,6 +254,7 @@ export async function runNativeHost({
             type: 'extension.identity',
             browserName: message.browserName,
             profileLabel: message.profileLabel,
+            browserExtensionId: message.browserExtensionId,
           });
           return;
         }
@@ -255,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

@@ -11,6 +11,9 @@ export const DEFAULT_MAX_NODES = 25;
 export const DEFAULT_MAX_DEPTH = 4;
 export const DEFAULT_TEXT_BUDGET = 600;
 export const DEFAULT_PAGE_TEXT_BUDGET = 8000;
+export const DEFAULT_EXTRACT_SETTLE_TIMEOUT_MS = 2000;
+export const MAX_EXTRACT_SETTLE_TIMEOUT_MS = 10_000;
+export const EXTRACT_SETTLE_QUIET_MS = 100;
 export const DEFAULT_WAIT_TIMEOUT_MS = 5000;
 export const DEFAULT_EVAL_TIMEOUT_MS = 5000;
 export const DEFAULT_NAV_TIMEOUT_MS = 15000;
@@ -18,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;
@@ -31,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

@@ -6,8 +6,25 @@ export const ERROR_CODES = Object.freeze({
   ACCESS_DENIED: 'ACCESS_DENIED',
   TAB_MISMATCH: 'TAB_MISMATCH',
   ELEMENT_STALE: 'ELEMENT_STALE',
+  ELEMENT_AMBIGUOUS: 'ELEMENT_AMBIGUOUS',
+  ELEMENT_NOT_ACTIONABLE: 'ELEMENT_NOT_ACTIONABLE',
+  ELEMENT_OBSCURED: 'ELEMENT_OBSCURED',
+  ELEMENT_NOT_FOUND: 'ELEMENT_NOT_FOUND',
+  INPUT_UNSUPPORTED: 'INPUT_UNSUPPORTED',
+  INPUT_INVALID_TARGET: 'INPUT_INVALID_TARGET',
+  INPUT_FOCUS_CHANGED: 'INPUT_FOCUS_CHANGED',
+  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',
@@ -29,10 +46,63 @@ 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',
-    hint: 'Element was removed from the DOM. Re-query with the same selector to get a fresh elementRef.',
+    hint: 'Element was removed from the DOM. Re-query for a fresh elementRef, or retry an input once with recoverStale=true when the same page and a strong unique descriptor still apply.',
+  },
+  [ERROR_CODES.ELEMENT_AMBIGUOUS]: {
+    retry: false,
+    alternativeMethod: 'dom.query',
+    hint: 'Multiple candidates matched, candidates tied, or a bounded stale-recovery scan could not prove uniqueness. Re-query and use a more specific selector or fresh elementRef.',
+  },
+  [ERROR_CODES.ELEMENT_NOT_ACTIONABLE]: {
+    retry: false,
+    alternativeMethod: 'dom.describe',
+    hint: 'The target is hidden, disabled, inert, or has no rendered area. Inspect it and choose an actionable target.',
+  },
+  [ERROR_CODES.ELEMENT_OBSCURED]: {
+    retry: false,
+    alternativeMethod: 'layout.hit_test',
+    hint: 'Another element blocks the target point. Inspect the blocker or wait for the overlay to close.',
+  },
+  [ERROR_CODES.ELEMENT_NOT_FOUND]: {
+    retry: false,
+    alternativeMethod: 'dom.query',
+    hint: 'No element matched the target selector. Check or narrow the selector with dom.query.',
+  },
+  [ERROR_CODES.INPUT_UNSUPPORTED]: {
+    retry: false,
+    hint: 'The requested execution mode does not support this input operation. Use executionMode=dom or choose a CDP-supported input method.',
+  },
+  [ERROR_CODES.INPUT_INVALID_TARGET]: {
+    retry: false,
+    alternativeMethod: 'dom.describe',
+    hint: 'The target is not compatible with this input operation or the requested option does not exist. Inspect the target and choose the appropriate control.',
+  },
+  [ERROR_CODES.INPUT_FOCUS_CHANGED]: {
+    retry: false,
+    alternativeMethod: 'dom.describe',
+    hint: 'Focus moved away from the resolved editable target before native text dispatch. Inspect focus handlers or target the control that retained focus.',
+  },
+  [ERROR_CODES.DIALOG_NOT_OPEN]: {
+    retry: false,
+    alternativeMethod: 'page.handle_dialog',
+    hint: 'No JavaScript dialog is currently observable. Inspect or trigger the dialog before trying another explicit action.',
+  },
+  [ERROR_CODES.DIALOG_ACTION_CONFLICT]: {
+    retry: false,
+    alternativeMethod: 'page.handle_dialog',
+    hint: 'The observed dialog changed before or during CDP dispatch. Do not repeat the action automatically; inspect the current dialog state first.',
   },
   [ERROR_CODES.TAB_MISMATCH]: {
     retry: false,
@@ -44,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';