@browserbridge/bbx 1.12.5 → 1.14.0

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

@@ -54,7 +54,12 @@ import {
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
 import { getMcpServerInstructions } from './guidance.js';
 import { isToolEnabledForEra, LOADABLE_TOOLSET_TOOLS } from './toolset.js';
-import { runWithMcpRequestTarget } from './handlers-utils.js';
+import {
+  runWithMcpRequestTarget,
+  createMcpClientSession,
+  runWithMcpClientSession,
+  closeMcpClientSession,
+} from './handlers-utils.js';
 
 export const BUDGET_PRESET_DESCRIPTION = `Budget preset: "quick", "normal", or "deep" (defaults: query ${BUDGET_PRESETS.normal.maxNodes} nodes / depth ${BUDGET_PRESETS.normal.maxDepth} / text ${BUDGET_PRESETS.normal.textBudget}). Numeric fields override the preset when both are provided.`;
 export const TAB_ID_DESCRIPTION =
@@ -181,6 +186,18 @@ export function createBridgeMcpServer(options = {}) {
 
   /** @type {Map<string, ReturnType<typeof server.registerTool>>} */
   const registrations = new Map();
+  const clientSession = createMcpClientSession();
+  server.server.onclose = () => {
+    void closeMcpClientSession(clientSession);
+  };
+  const closeServer = server.close.bind(server);
+  server.close = async () => {
+    try {
+      await closeServer();
+    } finally {
+      await closeMcpClientSession(clientSession);
+    }
+  };
 
   /**
    * Register a tool, then hide it when it is not part of the era's compact surface.
@@ -206,7 +223,10 @@ export function createBridgeMcpServer(options = {}) {
       (args, context) =>
         runWithMcpRequestEra(
           era,
-          () => runWithMcpRequestTarget(args, () => handler(args, context)),
+          () =>
+            runWithMcpClientSession(clientSession, () =>
+              runWithMcpRequestTarget(args, () => handler(args, context))
+            ),
           context.mcpReq.signal
         )
     );

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

@@ -58,7 +58,7 @@ export class ArtifactStore {
     }
     if (
       !Number.isInteger(input.totalBytes) ||
-      input.totalBytes < 1 ||
+      input.totalBytes < (input.kind === 'resource' ? 0 : 1) ||
       input.totalBytes > MAX_ARTIFACT_BYTES ||
       input.chunkCount !== Math.ceil(input.totalBytes / ARTIFACT_CHUNK_BYTES)
     ) {
@@ -128,6 +128,12 @@ export class ArtifactStore {
         'Artifact chunk order is invalid.'
       );
     }
+    if (data.length > Math.ceil(ARTIFACT_CHUNK_BYTES / 3) * 4) {
+      throw new BridgeError(
+        ERROR_CODES.ARTIFACT_TRANSFER_INVALID,
+        'Artifact chunk size is invalid.'
+      );
+    }
     const bytes = decodeBase64(data);
     if (bytes.length < 1 || bytes.length > ARTIFACT_CHUNK_BYTES) {
       throw new BridgeError(
@@ -141,7 +147,17 @@ export class ArtifactStore {
         'Artifact exceeds declared size.'
       );
     }
-    fs.writeSync(transfer.fd, bytes);
+    try {
+      let offset = 0;
+      while (offset < bytes.length) {
+        const written = fs.writeSync(transfer.fd, bytes, offset, bytes.length - offset);
+        if (written <= 0) throw new Error('Artifact write made no progress.');
+        offset += written;
+      }
+    } catch (error) {
+      this.abort(artifactId);
+      throw error;
+    }
     transfer.hash.update(bytes);
     transfer.written += bytes.length;
     transfer.nextChunk += 1;
@@ -198,7 +214,16 @@ export class ArtifactStore {
     const bytes = Buffer.alloc(byteLength);
     const fd = fs.openSync(record.filePath, 'r');
     try {
-      fs.readSync(fd, bytes, 0, byteLength, start);
+      let offset = 0;
+      while (offset < byteLength) {
+        const read = fs.readSync(fd, bytes, offset, byteLength - offset, start + offset);
+        if (read <= 0)
+          throw new BridgeError(
+            ERROR_CODES.ARTIFACT_TRANSFER_INVALID,
+            'Artifact was truncated on disk.'
+          );
+        offset += read;
+      }
     } finally {
       fs.closeSync(fd);
     }
@@ -286,6 +311,16 @@ export class ArtifactStore {
     }
   }
 
+  /** @param {string} ownerId */
+  deleteByOwner(ownerId) {
+    for (const transfer of this.transfers.values()) {
+      if (transfer.ownerId === ownerId) this.abort(transfer.artifactId);
+    }
+    for (const record of this.artifacts.values()) {
+      if (record.ownerId === ownerId) this.removeCommitted(record.artifactId);
+    }
+  }
+
   pruneExpired() {
     const now = this.now();
     for (const transfer of [...this.transfers.values()]) {
@@ -333,7 +368,10 @@ export class ArtifactStore {
 function isValidKindAndMimeType(kind, mimeType) {
   return (
     (kind === 'screenshot' && mimeType.startsWith('image/')) ||
-    (kind === 'har' && mimeType === 'application/json')
+    (kind === 'har' && mimeType === 'application/json') ||
+    (kind === 'resource' &&
+      /^[a-zA-Z0-9!#$&^_.+-]+\/[a-zA-Z0-9!#$&^_.+-]+$/u.test(mimeType) &&
+      mimeType.length <= 120)
   );
 }
 

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

@@ -46,6 +46,8 @@ import {
   getSocketPath,
 } from './config.js';
 import { ArtifactStore } from './artifact-store.js';
+import { RecordingStore } from './recording-store.js';
+import { BridgeError } from '../../protocol/src/errors.js';
 import {
   bridgeAuthTokensEqual,
   ensureBridgeAuthToken,
@@ -211,6 +213,23 @@ function normalizeExtensionHealthResult(value) {
   /** @type {Record<string, unknown>} */
   const normalized = {};
   if (result.extension === 'ok') normalized.extension = 'ok';
+  const build = asHealthRecord(result.loadedBuild);
+  if (
+    build &&
+    typeof build.workerId === 'string' &&
+    /^[a-f0-9-]{36}$/u.test(build.workerId) &&
+    typeof build.startedAt === 'string' &&
+    build.startedAt.length <= 32 &&
+    Number.isFinite(Date.parse(build.startedAt)) &&
+    (build.sourceDigest === null ||
+      (typeof build.sourceDigest === 'string' && /^[a-f0-9]{64}$/u.test(build.sourceDigest)))
+  ) {
+    normalized.loadedBuild = {
+      workerId: build.workerId,
+      startedAt: build.startedAt,
+      sourceDigest: build.sourceDigest,
+    };
+  }
   if (
     typeof result.extensionVersion === 'string' &&
     /^\d+\.\d+\.\d+$/u.test(result.extensionVersion)
@@ -432,12 +451,30 @@ export function isWindowsNamedPipePath(socketPath) {
  *   artifact?: Record<string, unknown>,
  *   chunkIndex?: number,
  *   data?: string
+ *   journalId?: string,
+ *   offset?: number,
+ *   messageId?: string,
  * }} DaemonMessage
  */
 
 /** @typedef {import('../../protocol/src/types.js').ArtifactKind} ArtifactKind */
 
 export class BridgeDaemon {
+  /** File data belongs to a transport connection, never a caller-selected label.
+   * @type {WeakMap<ClientSocket, string>} */
+  dataOwners = new WeakMap();
+  /** @type {WeakMap<ClientSocket, Set<ClientSocket>>} */
+  dataOwnerTargets = new WeakMap();
+
+  /** @param {ClientSocket} socket */
+  getDataOwner(socket) {
+    let owner = this.dataOwners.get(socket);
+    if (!owner) {
+      owner = randomUUID();
+      this.dataOwners.set(socket, owner);
+    }
+    return owner;
+  }
   /**
    * @param {{
    *   transport?: BridgeTransport,
@@ -448,7 +485,8 @@ export class BridgeDaemon {
    *   logger?: DaemonLoggerLike | Pick<Console, 'log' | 'error'>,
    *   authToken?: string | null,
    *   extensionAuthToken?: string | null,
-   *   artifactStore?: ArtifactStore
+   *   artifactStore?: ArtifactStore,
+   *   recordingStore?: RecordingStore,
    * }} [options={}]
    */
   constructor({
@@ -461,6 +499,9 @@ export class BridgeDaemon {
     authToken = undefined,
     extensionAuthToken = undefined,
     artifactStore = new ArtifactStore(getArtifactStorePath()),
+    recordingStore = new RecordingStore(
+      path.join(path.dirname(getArtifactStorePath()), 'recordings')
+    ),
   } = {}) {
     this.transport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
     this.socketPath =
@@ -512,6 +553,7 @@ export class BridgeDaemon {
     /** @type {string | null | undefined} */
     this.extensionAuthToken = extensionAuthToken;
     this.artifactStore = artifactStore;
+    this.recordingStore = recordingStore;
     this.artifactStoreInitialized = false;
     this.domBaselines = new DomBaselineOwnerRegistry({
       isCurrentExtensionSocket: (socket) =>
@@ -1016,6 +1058,40 @@ export class BridgeDaemon {
       }
       return this.handleExtensionArtifact(socket, message);
     }
+    if (
+      message?.type === 'extension.journal.begin' ||
+      message?.type === 'extension.journal.append'
+    ) {
+      if (socket.__role !== 'extension' || !socket.__extensionId)
+        return this.rejectMessageForRole(socket, message);
+      try {
+        let result;
+        if (message.type === 'extension.journal.begin') {
+          const pending = this.pendingRequests.get(String(message.requestId));
+          if (!pending || pending.method !== 'session.start' || !pending.targets.has(socket))
+            throw new Error('Journal must be created by a pending session.start request.');
+          result = this.recordingStore.begin(socket.__extensionId);
+        } else
+          result = this.recordingStore.append(
+            String(message.journalId),
+            socket.__extensionId,
+            Number(message.offset),
+            String(message.data)
+          );
+        await writeJsonLine(socket, {
+          type: 'extension.journal.ack',
+          messageId: message.messageId,
+          result,
+        });
+      } catch (error) {
+        await writeJsonLine(socket, {
+          type: 'extension.journal.ack',
+          messageId: message.messageId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+      return;
+    }
 
     if (message?.type === 'extension.setup_status.request') {
       if (socket.__role !== 'extension') {
@@ -1187,8 +1263,36 @@ export class BridgeDaemon {
       return;
     }
 
+    if (request.method === 'session.journal_read' || request.method === 'session.journal_delete') {
+      try {
+        const result =
+          request.method === 'session.journal_read'
+            ? this.recordingStore.read(
+                String(request.params.journalId),
+                Number(request.params.offset),
+                Number(request.params.maxBytes)
+              )
+            : this.recordingStore.delete(String(request.params.journalId));
+        await writeJsonLine(socket, {
+          type: 'agent.response',
+          response: createSuccess(request.id, result, { method: request.method }),
+        });
+      } catch (error) {
+        await writeJsonLine(socket, {
+          type: 'agent.response',
+          response: createFailure(
+            request.id,
+            error instanceof BridgeError ? error.code : ERROR_CODES.ARTIFACT_NOT_FOUND,
+            error instanceof BridgeError ? error.message : 'Recording journal unavailable.',
+            null,
+            { method: request.method }
+          ),
+        });
+      }
+      return;
+    }
     if (request.method === 'artifact.read' || request.method === 'artifact.delete') {
-      const ownerId = socket.__clientId;
+      const ownerId = socket.__clientId ? this.getDataOwner(socket) : null;
       if (!ownerId) {
         const response = createFailure(
           request.id,
@@ -1424,7 +1528,20 @@ export class BridgeDaemon {
       targetCount: 1,
     });
     try {
-      await writeJsonLine(target, { type: 'extension.request', request });
+      if (
+        /^(?:files\.|session\.|download\.|input\.(?:set_files|paste_image)$)/u.test(request.method)
+      ) {
+        const targets = this.dataOwnerTargets.get(socket) ?? new Set();
+        targets.add(target);
+        this.dataOwnerTargets.set(socket, targets);
+      }
+      await writeJsonLine(target, {
+        type: 'extension.request',
+        request: {
+          ...request,
+          meta: { ...request.meta, transport_owner: this.getDataOwner(socket) },
+        },
+      });
     } catch (error) {
       this.logger.error('request route failed', {
         requestId: request.id,
@@ -1609,6 +1726,7 @@ export class BridgeDaemon {
         : null;
     if (!accessEnabled && socket.__extensionId) {
       this.artifactStore.deleteByExtension(socket.__extensionId);
+      this.recordingStore.disconnect(socket.__extensionId);
       this.domBaselines.clearForSocket(socket);
     }
     if (socket.__accessEnabled !== accessEnabled) {
@@ -1653,7 +1771,7 @@ export class BridgeDaemon {
     const requestId = typeof artifact.requestId === 'string' ? artifact.requestId : '';
     const pending = this.pendingRequests.get(requestId);
     if (!pending || !pending.targets.has(socket) || !socket.__extensionId) return;
-    const ownerId = pending.socket.__clientId;
+    const ownerId = pending.socket.__clientId ? this.getDataOwner(pending.socket) : null;
     if (!ownerId) return;
     try {
       if (
@@ -1671,6 +1789,9 @@ export class BridgeDaemon {
         }
       }
       if (message.type === 'extension.artifact.begin') {
+        if (artifact.kind !== getArtifactKindForMethod(pending.method)) {
+          throw new Error('Artifact kind does not match the routed operation.');
+        }
         this.artifactStore.begin({
           artifactId: String(artifact.artifactId ?? ''),
           requestId,
@@ -1698,7 +1819,7 @@ export class BridgeDaemon {
         error && typeof error === 'object' && 'code' in error
           ? /** @type {import('../../protocol/src/types.js').ErrorCode} */ (error.code)
           : ERROR_CODES.ARTIFACT_TRANSFER_INVALID;
-      pending.lastErrorResponse = createFailure(
+      pending.lastErrorResponse ??= createFailure(
         requestId,
         code,
         error instanceof Error ? error.message : String(error),
@@ -1784,7 +1905,7 @@ export class BridgeDaemon {
           !pending.socket.__clientId ||
           !this.artifactStore.matchesCommitted(
             String(artifact.artifactId ?? ''),
-            pending.socket.__clientId,
+            this.getDataOwner(pending.socket),
             responseMessage.id,
             artifact,
             expectedArtifactKind ?? undefined
@@ -1895,6 +2016,19 @@ export class BridgeDaemon {
    * @returns {void}
    */
   handleSocketClose(socket) {
+    const dataOwner = this.dataOwners.get(socket);
+    if (dataOwner) {
+      this.artifactStore.deleteByOwner(dataOwner);
+      for (const target of this.dataOwnerTargets.get(socket) ?? []) {
+        if (!target.destroyed)
+          void writeJsonLine(target, {
+            type: 'extension.owner_disconnected',
+            ownerId: dataOwner,
+          }).catch(() => {});
+      }
+    }
+    this.dataOwnerTargets.delete(socket);
+    this.dataOwners.delete(socket);
     this.windowActions.disconnect(socket);
     this.clientSockets.delete(socket);
     if (socket.__registrationTimeoutId) {
@@ -2068,6 +2202,8 @@ function isAutomaticMcpRetry(meta) {
 function getArtifactKindForMethod(method) {
   if (method?.startsWith('screenshot.')) return 'screenshot';
   if (method === 'network.export_har') return 'har';
+  if (method === 'download.resource') return 'resource';
+  if (method === 'session.export') return 'resource';
   return null;
 }
 

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

@@ -183,6 +183,13 @@ export async function runNativeHost({
           await writeNativeMessageQueued(message.request);
           return;
         }
+        if (message.type === 'extension.owner_disconnected') {
+          await writeNativeMessageQueued({
+            type: 'host.owner_disconnected',
+            ownerId: message.ownerId,
+          });
+          return;
+        }
         if (message.type === 'agent.response') {
           await writeNativeMessageQueued({
             type: 'host.bridge_response',
@@ -199,6 +206,7 @@ export async function runNativeHost({
         }
         if (
           message.type === 'extension.window_action.command' ||
+          message.type === 'extension.journal.ack' ||
           message.type === 'extension.window_action.response'
         ) {
           await writeNativeMessageQueued({
@@ -290,6 +298,8 @@ export async function runNativeHost({
           const record = /** @type {Record<string, unknown>} */ (message);
           if (
             record.type === 'host.window_action.request' ||
+            record.type === 'host.journal.begin' ||
+            record.type === 'host.journal.append' ||
             record.type === 'host.window_action.result'
           ) {
             await writeJsonLine(socket, {

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

@@ -0,0 +1,136 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { BridgeError, ERROR_CODES } from '../../protocol/src/index.js';
+
+const MAX_BYTES = 128 * 1024 * 1024;
+const TOTAL_BYTES = 256 * 1024 * 1024;
+const TTL = 24 * 60 * 60 * 1000;
+const validId = /^journal_[a-f0-9]{64}$/u;
+
+/** Durable append-only journals. The random ID is a read/delete capability, never a path.
+ * Writes require the original extension connection as well as the capability.
+ * Existing files survive process restarts; the last partial line is reported by replay readers. */
+export class RecordingStore {
+  /** @param {string} directory */
+  constructor(directory) {
+    this.directory = directory;
+    /** @type {Map<string, string>} */
+    this.writers = new Map();
+  }
+  /** @param {string} id */
+  filename(id) {
+    if (!validId.test(id))
+      throw new BridgeError(ERROR_CODES.ARTIFACT_NOT_FOUND, 'Unknown recording journal.');
+    return path.join(this.directory, `${id}.jsonl`);
+  }
+  /** @returns {number} */
+  prune() {
+    fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+    let bytes = 0;
+    for (const name of fs.readdirSync(this.directory)) {
+      const id = name.replace(/\.jsonl$/u, '');
+      if (!validId.test(id)) continue;
+      const filename = this.filename(id);
+      const stat = fs.lstatSync(filename);
+      if (!stat.isFile() || stat.isSymbolicLink()) continue;
+      if (Date.now() - stat.mtimeMs > TTL) {
+        fs.unlinkSync(filename);
+        this.writers.delete(id);
+      } else bytes += stat.size;
+    }
+    return bytes;
+  }
+  /** @param {string} extensionId */
+  begin(extensionId) {
+    const used = this.prune();
+    if (used >= TOTAL_BYTES || fs.readdirSync(this.directory).length >= 32)
+      throw new BridgeError(
+        ERROR_CODES.ARTIFACT_QUOTA_EXCEEDED,
+        'Recording journal quota exceeded. Delete old journals.'
+      );
+    const journalId = `journal_${randomBytes(32).toString('hex')}`;
+    const fd = fs.openSync(this.filename(journalId), 'wx', 0o600);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    this.writers.set(journalId, extensionId);
+    return { journalId, nextOffset: 0, expiresAt: new Date(Date.now() + TTL).toISOString() };
+  }
+  /** @param {string} id @param {string} extensionId @param {number} offset @param {string} data */
+  append(id, extensionId, offset, data) {
+    if (this.writers.get(id) !== extensionId)
+      throw new BridgeError(ERROR_CODES.ACCESS_DENIED, 'Journal writer connection does not match.');
+    if (
+      !Number.isSafeInteger(offset) ||
+      offset < 0 ||
+      data.length > 262144 ||
+      !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(data)
+    )
+      throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'Invalid journal chunk.');
+    const bytes = Buffer.from(data, 'base64');
+    if (this.prune() + bytes.length > TOTAL_BYTES || offset + bytes.length > MAX_BYTES)
+      throw new BridgeError(
+        ERROR_CODES.ARTIFACT_QUOTA_EXCEEDED,
+        'Recording journal byte quota exceeded.'
+      );
+    const fd = fs.openSync(
+      this.filename(id),
+      fs.constants.O_WRONLY | (fs.constants.O_NOFOLLOW ?? 0)
+    );
+    try {
+      if (fs.fstatSync(fd).size !== offset)
+        throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'Journal offset mismatch.');
+      let written = 0;
+      while (written < bytes.length) {
+        const count = fs.writeSync(fd, bytes, written, bytes.length - written, offset + written);
+        if (!count) throw new Error('Journal write made no progress.');
+        written += count;
+      }
+      fs.fsyncSync(fd);
+      return { journalId: id, nextOffset: offset + written };
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+  /** @param {string} id @param {number} offset @param {number} limit */
+  read(id, offset, limit) {
+    this.prune();
+    const filename = this.filename(id);
+    const fd = fs.openSync(filename, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+      const size = fs.fstatSync(fd).size;
+      if (
+        !Number.isSafeInteger(offset) ||
+        offset < 0 ||
+        offset > size ||
+        !Number.isInteger(limit) ||
+        limit < 1 ||
+        limit > 196608
+      )
+        throw new BridgeError(ERROR_CODES.INVALID_REQUEST, 'Invalid journal read range.');
+      const data = Buffer.alloc(Math.min(limit, size - offset));
+      const count = fs.readSync(fd, data, 0, data.length, offset);
+      return {
+        journalId: id,
+        offset,
+        byteLength: count,
+        totalBytes: size,
+        nextOffset: offset + count < size ? offset + count : null,
+        data: data.subarray(0, count).toString('base64'),
+      };
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+  /** @param {string} id */
+  delete(id) {
+    fs.unlinkSync(this.filename(id));
+    this.writers.delete(id);
+    return { deleted: true };
+  }
+  /** @param {string} extensionId */
+  disconnect(extensionId) {
+    for (const [id, owner] of this.writers) if (owner === extensionId) this.writers.delete(id);
+  }
+}

package/packages/protocol/src/downloads.js

@@ -0,0 +1,35 @@
+// @ts-check
+import { booleanParam, invalidWorkflow, onlyKeys, stringParam } from './emulation.js';
+
+/** @param {string} method @param {Record<string, unknown>} params */
+export function normalizeDownload(method, params) {
+  if (method !== 'download.start') {
+    onlyKeys(params, ['downloadId']);
+    return { downloadId: stringParam(params.downloadId, 'downloadId', 100) };
+  }
+  onlyKeys(params, ['url', 'filename', 'saveAs']);
+  const url = stringParam(params.url, 'url', 8192);
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return invalidWorkflow('Invalid download URL.');
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password)
+    invalidWorkflow('Downloads require HTTP(S) without URL credentials.');
+  const filename =
+    params.filename === undefined ? undefined : stringParam(params.filename, 'filename', 240);
+  if (
+    filename &&
+    (/[\\/:]/u.test(filename) ||
+      [...filename].some((character) => character.charCodeAt(0) < 32) ||
+      filename === '.' ||
+      filename === '..')
+  )
+    invalidWorkflow('filename must be a single filename, not a path.');
+  return {
+    url,
+    ...(filename ? { filename } : {}),
+    saveAs: booleanParam(params.saveAs ?? false, 'saveAs'),
+  };
+}