@browserbridge/bbx 1.8.0 → 1.9.0

package/packages/mcp-server/src/server.js

@@ -19,6 +19,7 @@ import {
   handleLogTool,
   handleNavigationTool,
   handlePageTool,
+  handleSensitiveReadTool,
   handlePatchTool,
   handleRawCallTool,
   handleSetupTool,
@@ -33,6 +34,7 @@ import {
   BUDGET_PRESETS,
   DEFAULT_CONSOLE_LIMIT,
   DEFAULT_EVAL_TIMEOUT_MS,
+  DEFAULT_HAR_LIMIT,
   DEFAULT_LOG_TAIL_LIMIT,
   DEFAULT_MAX_DEPTH,
   DEFAULT_MAX_HTML_LENGTH,
@@ -41,6 +43,7 @@ import {
   DEFAULT_TEXT_BUDGET,
   DEFAULT_NAV_TIMEOUT_MS,
   DEFAULT_WAIT_TIMEOUT_MS,
+  MAX_HAR_ENTRIES,
   getMethodsByMaxComplexity,
 } from '../../protocol/src/index.js';
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
@@ -215,6 +218,10 @@ export function createBridgeMcpServer() {
         action: z
           .enum([
             'query',
+            'baseline_create',
+            'baseline_compare',
+            'baseline_describe',
+            'baseline_release',
             'describe',
             'text',
             'attributes',
@@ -237,6 +244,14 @@ export function createBridgeMcpServer() {
           .describe(
             'CSS selector (used if no elementRef; accessibility_tree requires exactly one match)'
           ),
+        baselineId: z.string().optional().describe('Opaque semantic DOM baseline identifier'),
+        maxChanges: z
+          .number()
+          .int()
+          .positive()
+          .max(200)
+          .optional()
+          .describe('Maximum returned change examples; exact counts are always retained'),
         elementRef: z
           .string()
           .optional()
@@ -361,12 +376,31 @@ export function createBridgeMcpServer() {
     handleStylesLayoutTool
   );
 
+  server.registerTool(
+    'browser_sensitive_read',
+    {
+      title: 'Sensitive Browser Read',
+      description:
+        'High-risk exact-value read for one local or session storage key. This operation is logged as Sensitive access, is never batched or retried, and returns the whole value or fails atomically.',
+      inputSchema: {
+        source: z.enum(['local_storage', 'session_storage']).describe('Exact storage source'),
+        key: z
+          .string()
+          .max(2_048)
+          .describe('Exact storage key, including an empty key if intended'),
+        tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+      },
+    },
+    handleSensitiveReadTool
+  );
+
   server.registerTool(
     'browser_page',
     {
       title: 'Browser Page State',
       description:
-        'Read page-level data, wait for load/URL conditions, or explicitly inspect/handle JavaScript dialogs. For element-level reads, use browser_dom. evaluate, performance, handle_dialog, and source=cdp network capture are debugger-backed.',
+        'Read page-level data, export captured network evidence as HAR 1.2, wait for load/URL conditions, or explicitly inspect/handle JavaScript dialogs. The performance action returns a raw CDP Performance.getMetrics point sample: Chrome defines names and units, which vary, while BBX sets no navigation observation window and does not measure LCP, CLS, or INP. For element-level reads, use browser_dom. evaluate, performance, handle_dialog, and source=cdp network capture are debugger-backed.',
       inputSchema: {
         action: z
           .enum([
@@ -379,9 +413,12 @@ export function createBridgeMcpServer() {
             'text',
             'extract_content',
             'network',
+            'har',
             'performance',
           ])
-          .describe('Page operation to perform'),
+          .describe(
+            'Page operation to perform; performance reads raw Chrome/CDP counters, not LCP, CLS, or INP'
+          ),
         tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
         destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
         budgetPreset: z
@@ -434,7 +471,9 @@ export function createBridgeMcpServer() {
           .int()
           .positive()
           .optional()
-          .describe(`Maximum entries to return (default: ${DEFAULT_CONSOLE_LIMIT})`),
+          .describe(
+            `Maximum entries to return (console default: ${DEFAULT_CONSOLE_LIMIT}; HAR default: ${DEFAULT_HAR_LIMIT}, max: ${MAX_HAR_ENTRIES})`
+          ),
         type: z
           .enum(['local', 'session'])
           .optional()
@@ -468,7 +507,11 @@ export function createBridgeMcpServer() {
           .positive()
           .optional()
           .describe('Maximum semantic extraction settlement wait (default: 2000)'),
-        urlPattern: z.string().optional().describe('Filter network entries by URL pattern'),
+        urlPattern: z
+          .string()
+          .max(2_048)
+          .optional()
+          .describe('Bounded URL pattern used to filter network entries or HAR export evidence'),
         source: z
           .enum(['fetch-xhr', 'cdp'])
           .optional()
@@ -477,6 +520,10 @@ export function createBridgeMcpServer() {
           .enum(['read', 'start', 'clear', 'stop'])
           .optional()
           .describe('Explicit CDP capture lifecycle action (default: read)'),
+        delivery: z
+          .enum(['auto', 'inline', 'artifact'])
+          .optional()
+          .describe('HAR delivery mode: auto chooses inline or a daemon-owned artifact'),
         waitForLoad: z
           .boolean()
           .optional()
@@ -626,7 +673,7 @@ export function createBridgeMcpServer() {
           .int()
           .nonnegative()
           .optional()
-          .describe('Hover duration in ms (default: 0)'),
+          .describe('Delay after hover dispatch in ms; does not end hover (default: 0)'),
         sourceElementRef: z.string().optional().describe('Drag source element (for drag action)'),
         sourceSelector: z
           .string()
@@ -674,7 +721,14 @@ export function createBridgeMcpServer() {
           .describe('CSS property: value pairs (for apply_styles)'),
         important: z.boolean().optional().describe('Add !important flag (default: false)'),
         operation: z
-          .enum(['setAttribute', 'removeAttribute', 'addClass', 'removeClass', 'setTextContent'])
+          .enum([
+            'setAttribute',
+            'removeAttribute',
+            'addClass',
+            'removeClass',
+            'toggleClass',
+            'setTextContent',
+          ])
           .optional()
           .describe('DOM mutation type'),
         value: z.unknown().optional().describe('Value for the DOM operation'),
@@ -728,6 +782,11 @@ export function createBridgeMcpServer() {
           .positive()
           .optional()
           .describe('CDP node id for cdp_box_model/cdp_computed_styles'),
+        computedStyles: z
+          .array(z.string().min(1).max(128))
+          .max(100)
+          .optional()
+          .describe('CSS property names to include for cdp_dom_snapshot'),
         rect: z
           .object({
             x: z.number().nonnegative().describe('Region left edge (viewport pixels)'),
@@ -748,6 +807,16 @@ export function createBridgeMcpServer() {
           .max(100)
           .optional()
           .describe('JPEG/WebP quality from 0 to 100; ignored for PNG'),
+        delivery: z
+          .enum(['auto', 'inline', 'artifact'])
+          .optional()
+          .describe('Delivery mode: auto chooses inline or a daemon-owned artifact'),
+        scale: z
+          .number()
+          .min(0.1)
+          .max(4)
+          .optional()
+          .describe('Screenshot capture scale (0.1 to 4)'),
       },
     },
     handleCaptureTool

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

@@ -0,0 +1,353 @@
+// @ts-check
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+import {
+  ARTIFACT_CHUNK_BYTES,
+  ARTIFACT_TTL_MS,
+  BridgeError,
+  ERROR_CODES,
+  MAX_ARTIFACT_BYTES,
+  MAX_ARTIFACT_CLIENT_BYTES,
+  MAX_ARTIFACT_TOTAL_BYTES,
+  MAX_ARTIFACTS_PER_CLIENT,
+} from '../../protocol/src/index.js';
+
+/** @typedef {import('../../protocol/src/types.js').ArtifactKind} ArtifactKind */
+/** @typedef {{ artifactId: string, requestId: string, ownerId: string, extensionId: string, kind: ArtifactKind, mimeType: string, totalBytes: number, sha256: string, chunkCount: number, createdAt: string, expiresAt: string, fd: number, temporaryPath: string, finalPath: string, written: number, nextChunk: number, hash: import('node:crypto').Hash }} ArtifactTransfer */
+/** @typedef {{ artifactId: string, requestId: string, ownerId: string, extensionId: string, kind: ArtifactKind, mimeType: string, byteLength: number, sha256: string, chunkCount: number, createdAt: string, expiresAt: string, filePath: string }} ArtifactRecord */
+
+export class ArtifactStore {
+  /** @param {string} rootPath @param {() => number} [now] */
+  constructor(rootPath, now = Date.now) {
+    this.rootPath = rootPath;
+    this.now = now;
+    /** @type {Map<string, ArtifactTransfer>} */
+    this.transfers = new Map();
+    /** @type {Map<string, ArtifactRecord>} */
+    this.artifacts = new Map();
+    /** @type {Map<string, ReturnType<typeof setTimeout>>} */
+    this.expiryTimers = new Map();
+  }
+
+  reset() {
+    for (const transfer of this.transfers.values()) {
+      try {
+        fs.closeSync(transfer.fd);
+      } catch {}
+    }
+    for (const timer of this.expiryTimers.values()) clearTimeout(timer);
+    fs.rmSync(this.rootPath, { recursive: true, force: true });
+    fs.mkdirSync(this.rootPath, { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32') fs.chmodSync(this.rootPath, 0o700);
+    this.transfers.clear();
+    this.artifacts.clear();
+    this.expiryTimers.clear();
+  }
+
+  /** @param {Omit<ArtifactTransfer, 'fd' | 'temporaryPath' | 'finalPath' | 'written' | 'nextChunk' | 'hash'>} input */
+  begin(input) {
+    this.pruneExpired();
+    if (!/^art_[A-Za-z0-9_-]{32,64}$/u.test(input.artifactId)) {
+      throw new BridgeError(
+        ERROR_CODES.ARTIFACT_TRANSFER_INVALID,
+        'Artifact identifier is invalid.'
+      );
+    }
+    if (
+      !Number.isInteger(input.totalBytes) ||
+      input.totalBytes < 1 ||
+      input.totalBytes > MAX_ARTIFACT_BYTES ||
+      input.chunkCount !== Math.ceil(input.totalBytes / ARTIFACT_CHUNK_BYTES)
+    ) {
+      throw new BridgeError(ERROR_CODES.ARTIFACT_TRANSFER_INVALID, 'Artifact size is invalid.');
+    }
+    const now = this.now();
+    const createdAt = Date.parse(input.createdAt);
+    const expiresAt = Date.parse(input.expiresAt);
+    if (
+      !/^[a-f0-9]{64}$/u.test(input.sha256) ||
+      !isValidKindAndMimeType(input.kind, input.mimeType) ||
+      !Number.isFinite(createdAt) ||
+      !Number.isFinite(expiresAt) ||
+      createdAt > now + 10_000 ||
+      createdAt < now - ARTIFACT_TTL_MS ||
+      expiresAt <= now ||
+      expiresAt <= createdAt ||
+      expiresAt > now + ARTIFACT_TTL_MS
+    ) {
+      throw new BridgeError(ERROR_CODES.ARTIFACT_TRANSFER_INVALID, 'Artifact metadata is invalid.');
+    }
+    if (this.transfers.has(input.artifactId) || this.artifacts.has(input.artifactId)) {
+      throw new BridgeError(
+        ERROR_CODES.ARTIFACT_TRANSFER_INVALID,
+        'Artifact identifier is already in use.'
+      );
+    }
+    const ownedArtifacts = [...this.artifacts.values()].filter(
+      (item) => item.ownerId === input.ownerId
+    );
+    const ownedTransfers = [...this.transfers.values()].filter(
+      (item) => item.ownerId === input.ownerId
+    );
+    const clientBytes =
+      ownedArtifacts.reduce((total, item) => total + item.byteLength, 0) +
+      ownedTransfers.reduce((total, item) => total + item.totalBytes, 0);
+    const totalBytes =
+      [...this.artifacts.values()].reduce((total, item) => total + item.byteLength, 0) +
+      [...this.transfers.values()].reduce((total, item) => total + item.totalBytes, 0);
+    if (
+      ownedArtifacts.length + ownedTransfers.length >= MAX_ARTIFACTS_PER_CLIENT ||
+      clientBytes + input.totalBytes > MAX_ARTIFACT_CLIENT_BYTES ||
+      totalBytes + input.totalBytes > MAX_ARTIFACT_TOTAL_BYTES
+    ) {
+      throw new BridgeError(ERROR_CODES.ARTIFACT_QUOTA_EXCEEDED, 'Artifact quota exceeded.');
+    }
+    const temporaryPath = path.join(this.rootPath, `${input.artifactId}.part`);
+    const finalPath = path.join(this.rootPath, `${input.artifactId}.bin`);
+    const fd = fs.openSync(temporaryPath, 'wx', 0o600);
+    this.transfers.set(input.artifactId, {
+      ...input,
+      fd,
+      temporaryPath,
+      finalPath,
+      written: 0,
+      nextChunk: 0,
+      hash: createHash('sha256'),
+    });
+  }
+
+  /** @param {string} artifactId @param {number} chunkIndex @param {string} data */
+  writeChunk(artifactId, chunkIndex, data) {
+    const transfer = this.transfers.get(artifactId);
+    if (!transfer || chunkIndex !== transfer.nextChunk) {
+      throw new BridgeError(
+        ERROR_CODES.ARTIFACT_TRANSFER_INVALID,
+        'Artifact chunk order is invalid.'
+      );
+    }
+    const bytes = decodeBase64(data);
+    if (bytes.length < 1 || bytes.length > ARTIFACT_CHUNK_BYTES) {
+      throw new BridgeError(
+        ERROR_CODES.ARTIFACT_TRANSFER_INVALID,
+        'Artifact chunk size is invalid.'
+      );
+    }
+    if (transfer.written + bytes.length > transfer.totalBytes) {
+      throw new BridgeError(
+        ERROR_CODES.ARTIFACT_TRANSFER_INVALID,
+        'Artifact exceeds declared size.'
+      );
+    }
+    fs.writeSync(transfer.fd, bytes);
+    transfer.hash.update(bytes);
+    transfer.written += bytes.length;
+    transfer.nextChunk += 1;
+  }
+
+  /** @param {string} artifactId @returns {ArtifactRecord} */
+  commit(artifactId) {
+    const transfer = this.transfers.get(artifactId);
+    if (!transfer) {
+      throw new BridgeError(ERROR_CODES.ARTIFACT_TRANSFER_INVALID, 'Artifact transfer is missing.');
+    }
+    const digest = transfer.hash.digest('hex');
+    if (
+      transfer.written !== transfer.totalBytes ||
+      transfer.nextChunk !== transfer.chunkCount ||
+      digest !== transfer.sha256
+    ) {
+      this.abort(artifactId);
+      throw new BridgeError(ERROR_CODES.ARTIFACT_TRANSFER_INVALID, 'Artifact checksum is invalid.');
+    }
+    fs.closeSync(transfer.fd);
+    fs.renameSync(transfer.temporaryPath, transfer.finalPath);
+    if (process.platform !== 'win32') fs.chmodSync(transfer.finalPath, 0o600);
+    const record = {
+      artifactId: transfer.artifactId,
+      requestId: transfer.requestId,
+      ownerId: transfer.ownerId,
+      extensionId: transfer.extensionId,
+      kind: transfer.kind,
+      mimeType: transfer.mimeType,
+      byteLength: transfer.totalBytes,
+      sha256: digest,
+      chunkCount: transfer.chunkCount,
+      createdAt: transfer.createdAt,
+      expiresAt: transfer.expiresAt,
+      filePath: transfer.finalPath,
+    };
+    this.transfers.delete(artifactId);
+    this.artifacts.set(artifactId, record);
+    const timer = setTimeout(
+      () => this.removeCommitted(artifactId),
+      Math.max(0, Date.parse(record.expiresAt) - this.now())
+    );
+    timer.unref?.();
+    this.expiryTimers.set(artifactId, timer);
+    return record;
+  }
+
+  /** @param {string} artifactId @param {string} ownerId @param {number} offset @param {number} maxBytes */
+  read(artifactId, ownerId, offset, maxBytes) {
+    const record = this.getOwned(artifactId, ownerId);
+    const start = Math.min(offset, record.byteLength);
+    const byteLength = Math.min(maxBytes, record.byteLength - start);
+    const bytes = Buffer.alloc(byteLength);
+    const fd = fs.openSync(record.filePath, 'r');
+    try {
+      fs.readSync(fd, bytes, 0, byteLength, start);
+    } finally {
+      fs.closeSync(fd);
+    }
+    const nextOffset = start + byteLength < record.byteLength ? start + byteLength : null;
+    return {
+      artifactId,
+      data: bytes.toString('base64'),
+      offset: start,
+      byteLength,
+      chunkIndex: Math.floor(start / ARTIFACT_CHUNK_BYTES),
+      chunkCount: record.chunkCount,
+      nextOffset,
+      totalBytes: record.byteLength,
+      sha256: record.sha256,
+      expiresAt: record.expiresAt,
+    };
+  }
+
+  /** @param {string} artifactId @param {string} ownerId */
+  delete(artifactId, ownerId) {
+    this.getOwned(artifactId, ownerId);
+    this.removeCommitted(artifactId);
+    return { artifactId, deleted: true };
+  }
+
+  /** @param {string} artifactId @param {string} ownerId @param {string} requestId @param {ArtifactKind} [kind] */
+  ownsCommitted(artifactId, ownerId, requestId, kind) {
+    const record = this.artifacts.get(artifactId);
+    return (
+      record?.ownerId === ownerId &&
+      record.requestId === requestId &&
+      (kind === undefined || record.kind === kind)
+    );
+  }
+
+  /**
+   * @param {string} artifactId
+   * @param {string} ownerId
+   * @param {string} requestId
+   * @param {Record<string, unknown>} descriptor
+   * @param {ArtifactKind | undefined} expectedKind
+   */
+  matchesCommitted(artifactId, ownerId, requestId, descriptor, expectedKind) {
+    const record = this.artifacts.get(artifactId);
+    return Boolean(
+      record &&
+      record.ownerId === ownerId &&
+      record.requestId === requestId &&
+      (expectedKind === undefined || record.kind === expectedKind) &&
+      descriptor.kind === record.kind &&
+      descriptor.mimeType === record.mimeType &&
+      descriptor.byteLength === record.byteLength &&
+      descriptor.sha256 === record.sha256 &&
+      descriptor.chunkSize === ARTIFACT_CHUNK_BYTES &&
+      descriptor.chunkCount === record.chunkCount &&
+      descriptor.createdAt === record.createdAt &&
+      descriptor.expiresAt === record.expiresAt
+    );
+  }
+
+  /** @param {string} requestId */
+  abortRequest(requestId) {
+    for (const transfer of this.transfers.values()) {
+      if (transfer.requestId === requestId) this.abort(transfer.artifactId);
+    }
+  }
+
+  /** @param {string} requestId */
+  deleteRequest(requestId) {
+    this.abortRequest(requestId);
+    for (const record of [...this.artifacts.values()]) {
+      if (record.requestId === requestId) this.removeCommitted(record.artifactId);
+    }
+  }
+
+  /** @param {string} extensionId */
+  deleteByExtension(extensionId) {
+    for (const transfer of [...this.transfers.values()]) {
+      if (transfer.extensionId === extensionId) this.abort(transfer.artifactId);
+    }
+    for (const record of this.artifacts.values()) {
+      if (record.extensionId === extensionId) {
+        this.removeCommitted(record.artifactId);
+      }
+    }
+  }
+
+  pruneExpired() {
+    const now = this.now();
+    for (const transfer of [...this.transfers.values()]) {
+      if (Date.parse(transfer.expiresAt) <= now) this.abort(transfer.artifactId);
+    }
+    for (const record of this.artifacts.values()) {
+      if (Date.parse(record.expiresAt) <= now) this.removeCommitted(record.artifactId);
+    }
+  }
+
+  /** @param {string} artifactId */
+  abort(artifactId) {
+    const transfer = this.transfers.get(artifactId);
+    if (!transfer) return;
+    this.transfers.delete(artifactId);
+    try {
+      fs.closeSync(transfer.fd);
+    } catch {}
+    fs.rmSync(transfer.temporaryPath, { force: true });
+  }
+
+  /** @param {string} artifactId */
+  removeCommitted(artifactId) {
+    const record = this.artifacts.get(artifactId);
+    if (!record) return;
+    this.artifacts.delete(artifactId);
+    const timer = this.expiryTimers.get(artifactId);
+    if (timer) clearTimeout(timer);
+    this.expiryTimers.delete(artifactId);
+    fs.rmSync(record.filePath, { force: true });
+  }
+
+  /** @param {string} artifactId @param {string} ownerId */
+  getOwned(artifactId, ownerId) {
+    this.pruneExpired();
+    const record = this.artifacts.get(artifactId);
+    if (!record || record.ownerId !== ownerId) {
+      throw new BridgeError(ERROR_CODES.ARTIFACT_NOT_FOUND, 'Artifact was not found.');
+    }
+    return record;
+  }
+}
+
+/** @param {ArtifactKind} kind @param {string} mimeType */
+function isValidKindAndMimeType(kind, mimeType) {
+  return (
+    (kind === 'screenshot' && mimeType.startsWith('image/')) ||
+    (kind === 'har' && mimeType === 'application/json')
+  );
+}
+
+/** @param {string} value */
+function decodeBase64(value) {
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(value)) {
+    throw new BridgeError(ERROR_CODES.ARTIFACT_TRANSFER_INVALID, 'Artifact chunk is not base64.');
+  }
+  const bytes = Buffer.from(value, 'base64');
+  if (bytes.toString('base64') !== value) {
+    throw new BridgeError(
+      ERROR_CODES.ARTIFACT_TRANSFER_INVALID,
+      'Artifact chunk is not canonical base64.'
+    );
+  }
+  return bytes;
+}

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

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
+import { sanitizeIncidentalPath, sanitizeIncidentalText } from '../../protocol/src/index.js';
 
 export const APP_NAME = 'com.browserbridge.browser_bridge';
 export const BRIDGE_HOME_ENV = 'BROWSER_BRIDGE_HOME';
@@ -58,6 +59,11 @@ export function getBridgeDir(env = process.env) {
   return path.join(xdgDataHome, 'browser-bridge');
 }
 
+/** @param {NodeJS.ProcessEnv} [env=process.env] */
+export function getArtifactStorePath(env = process.env) {
+  return path.join(getBridgeDir(env), 'artifacts');
+}
+
 /**
  * Resolve the IPC endpoint the daemon listens on and the CLI / native host
  * connect to. On Windows we use a Named Pipe by default because Node's AF_UNIX
@@ -125,7 +131,9 @@ function normalizePort(value) {
  * @returns {void}
  */
 function warnProxyConfigIgnored(configPath, reason) {
-  console.error(`browser-bridge: ignoring proxy config at ${configPath}: ${reason}`);
+  console.error(
+    `browser-bridge: ignoring proxy config at ${sanitizeIncidentalPath(configPath)}: ${sanitizeIncidentalText(reason)}`
+  );
 }
 
 /**

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

@@ -1,5 +1,7 @@
 // @ts-check
 
+import { sanitizeIncidentalValue } from '../../protocol/src/index.js';
+
 /** @typedef {{ write: (chunk: string) => void }} LogStream */
 
 /**
@@ -62,7 +64,7 @@ export class DaemonLogger {
       message,
       ...extra,
     };
-    this.#stream.write(`${JSON.stringify(entry)}\n`);
+    this.#stream.write(`${JSON.stringify(sanitizeIncidentalValue(entry))}\n`);
   }
 
   /**