neoagent 3.2.1-beta.2 → 3.2.1-beta.3

package/server/services/browser/extension/gateway.js

@@ -3,6 +3,7 @@ const { BROWSER_EXTENSION_WS_PATH } = require('./protocol');
 
 const DEFAULT_UPGRADE_RATE_LIMIT_WINDOW_MS = 60 * 1000;
 const DEFAULT_UPGRADE_RATE_LIMIT_MAX = 30;
+const MAX_EXTENSION_MESSAGE_BYTES = 32 * 1024 * 1024;
 
 function rejectUpgrade(socket, statusCode, message) {
   try {
@@ -22,8 +23,13 @@ function rejectUpgrade(socket, statusCode, message) {
 }
 
 function bindBrowserExtensionGateway(httpServer, app) {
-  const wss = new WebSocketServer({ noServer: true });
+  const wss = new WebSocketServer({
+    noServer: true,
+    maxPayload: MAX_EXTENSION_MESSAGE_BYTES,
+  });
   const attemptsByIp = new Map();
+  let closing = false;
+  let closePromise = null;
   const windowMs = Number(process.env.NEOAGENT_BROWSER_EXTENSION_UPGRADE_WINDOW_MS || DEFAULT_UPGRADE_RATE_LIMIT_WINDOW_MS);
 
   const cleanupTimer = setInterval(() => {
@@ -50,7 +56,7 @@ function bindBrowserExtensionGateway(httpServer, app) {
     return entry.count > maxAttempts;
   }
 
-  httpServer.on('upgrade', (req, socket, head) => {
+  const handleUpgrade = (req, socket, head) => {
     let url;
     try {
       url = new URL(req.url, 'http://localhost');
@@ -60,6 +66,10 @@ function bindBrowserExtensionGateway(httpServer, app) {
     if (url.pathname !== BROWSER_EXTENSION_WS_PATH) {
       return;
     }
+    if (closing) {
+      rejectUpgrade(socket, 503, 'Service Unavailable');
+      return;
+    }
 
     const remoteAddress = req.socket?.remoteAddress || 'unknown';
     if (isRateLimited(remoteAddress)) {
@@ -81,24 +91,38 @@ function bindBrowserExtensionGateway(httpServer, app) {
     }
 
     wss.handleUpgrade(req, socket, head, (ws) => {
-      registry.registerConnection(tokenRow, ws, {
-        remoteAddress,
-        userAgent: req.headers['user-agent'] || null,
-      });
-      ws.send(JSON.stringify({
-        type: 'hello',
-        ok: true,
-        userId: tokenRow.user_id,
-        tokenId: tokenRow.id,
-      }));
+      try {
+        registry.registerConnection(tokenRow, ws, {
+          remoteAddress,
+          userAgent: req.headers['user-agent'] || null,
+        });
+        ws.send(JSON.stringify({
+          type: 'hello',
+          ok: true,
+          userId: tokenRow.user_id,
+          tokenId: tokenRow.id,
+        }));
+      } catch (error) {
+        try { ws.close(1012, String(error?.message || 'Service unavailable').slice(0, 120)); } catch {}
+      }
     });
-  });
+  };
+  httpServer.on('upgrade', handleUpgrade);
 
   app.locals.browserExtensionGateway = {
-    close: () => new Promise((resolve) => {
+    close: () => {
+      if (closePromise) return closePromise;
+      closing = true;
       clearInterval(cleanupTimer);
-      wss.close(() => resolve());
-    }),
+      httpServer.removeListener('upgrade', handleUpgrade);
+      for (const client of wss.clients) {
+        try { client.terminate(); } catch {}
+      }
+      closePromise = new Promise((resolve) => {
+        wss.close(() => resolve());
+      });
+      return closePromise;
+    },
   };
 
   return wss;

package/server/services/browser/extension/protocol.js

@@ -1,6 +1,15 @@
+'use strict';
+
 const BROWSER_EXTENSION_WS_PATH = '/api/browser-extension/ws';
 const EXTENSION_PROTOCOL_VERSION = 1;
 
+const EXTENSION_MESSAGE_TYPES = Object.freeze({
+  COMMAND: 'command',
+  RESULT: 'result',
+  URL_VALIDATION_REQUEST: 'urlValidationRequest',
+  URL_VALIDATION_RESULT: 'urlValidationResult',
+});
+
 const EXTENSION_COMMANDS = Object.freeze({
   LAUNCH: 'launch',
   NAVIGATE: 'navigate',
@@ -16,6 +25,7 @@ const EXTENSION_COMMANDS = Object.freeze({
   CLOSE: 'close',
   GET_PAGE_INFO: 'getPageInfo',
   GET_COOKIES: 'getCookies',
+  CANCEL_COMMAND: 'cancelCommand',
 });
 
 class ExtensionBrowserUnavailableError extends Error {
@@ -28,7 +38,7 @@ class ExtensionBrowserUnavailableError extends Error {
 
 function createCommandMessage(id, command, payload = {}) {
   return {
-    type: 'command',
+    type: EXTENSION_MESSAGE_TYPES.COMMAND,
     version: EXTENSION_PROTOCOL_VERSION,
     id,
     command,
@@ -46,6 +56,7 @@ function parseExtensionMessage(data) {
 module.exports = {
   BROWSER_EXTENSION_WS_PATH,
   EXTENSION_PROTOCOL_VERSION,
+  EXTENSION_MESSAGE_TYPES,
   EXTENSION_COMMANDS,
   ExtensionBrowserUnavailableError,
   createCommandMessage,

package/server/services/browser/extension/provider.js

@@ -1,18 +1,15 @@
+'use strict';
+
 const fs = require('fs');
 const path = require('path');
 const { DATA_DIR } = require('../../../../runtime/paths');
+const { writeBufferAtomic } = require('../../../utils/files');
+const { decodeBase64Image } = require('../../../utils/image_payload');
 const { EXTENSION_COMMANDS, ExtensionBrowserUnavailableError } = require('./protocol');
 
 const SCREENSHOTS_DIR = path.join(DATA_DIR, 'screenshots');
 if (!fs.existsSync(SCREENSHOTS_DIR)) fs.mkdirSync(SCREENSHOTS_DIR, { recursive: true });
 
-function extractBase64Png(value) {
-  const text = String(value || '');
-  if (!text) return null;
-  const match = text.match(/^data:image\/png;base64,(.+)$/);
-  return match ? match[1] : text;
-}
-
 class ExtensionBrowserProvider {
   constructor(options = {}) {
     this.registry = options.registry;
@@ -31,11 +28,18 @@ class ExtensionBrowserProvider {
 
   async #dispatch(command, payload = {}, options = {}) {
     this.#assertReady();
-    const result = await this.registry.dispatch(this.userId, command, payload, {
+    const safePayload = { ...(payload || {}) };
+    const signal = options.signal || safePayload.signal || null;
+    const timeoutMs = options.timeoutMs ?? safePayload.timeoutMs;
+    delete safePayload.signal;
+    delete safePayload.timeoutMs;
+    const result = await this.registry.dispatch(this.userId, command, safePayload, {
       ...options,
+      signal,
+      timeoutMs,
       tokenId: options.tokenId || this.tokenId,
     });
-    return this.#materialize(result);
+    return this.#materialize(result, { signal });
   }
 
   #disconnect() {
@@ -46,18 +50,17 @@ class ExtensionBrowserProvider {
     }
   }
 
-  #writeScreenshotArtifact(base64) {
-    const buffer = Buffer.from(base64, 'base64');
+  async #writeScreenshotArtifact(image, options = {}) {
     if (this.artifactStore && this.userId != null) {
-      const artifact = this.artifactStore.allocateFile(this.userId, {
+      const artifact = await this.artifactStore.createBufferArtifact(this.userId, {
         kind: 'browser-screenshot',
         backend: 'extension',
-        extension: 'png',
-        contentType: 'image/png',
+        extension: image.extension,
+        contentType: image.contentType,
         filenameBase: 'browser-extension-screenshot',
+        content: image.buffer,
+        signal: options.signal,
       });
-      fs.writeFileSync(artifact.storagePath, buffer);
-      this.artifactStore.finalizeFile(artifact.artifactId, artifact.storagePath);
       return {
         screenshotPath: artifact.url,
         artifactId: artifact.artifactId,
@@ -68,7 +71,7 @@ class ExtensionBrowserProvider {
 
     const filename = `browser_extension_${Date.now()}_${Math.random().toString(16).slice(2)}.png`;
     const fullPath = path.join(SCREENSHOTS_DIR, filename);
-    fs.writeFileSync(fullPath, buffer);
+    await writeBufferAtomic(fullPath, image.buffer, { signal: options.signal });
     return {
       screenshotPath: `/screenshots/${filename}`,
       artifactId: null,
@@ -77,13 +80,12 @@ class ExtensionBrowserProvider {
     };
   }
 
-  #materialize(result) {
+  async #materialize(result, options = {}) {
     if (!result || typeof result !== 'object') return result;
     const raw = result.screenshotDataUrl || result.screenshotData || result.screenshotBase64;
     if (!raw) return result;
-    const base64 = extractBase64Png(raw);
-    if (!base64) return result;
-    const screenshot = this.#writeScreenshotArtifact(base64);
+    const image = decodeBase64Image(raw, { allowedTypes: ['image/png'] });
+    const screenshot = await this.#writeScreenshotArtifact(image, options);
     const next = { ...result, ...screenshot };
     delete next.screenshotDataUrl;
     delete next.screenshotData;
@@ -92,79 +94,90 @@ class ExtensionBrowserProvider {
   }
 
   navigate(url, options = {}) {
-    return this.#dispatch(EXTENSION_COMMANDS.NAVIGATE, { url, ...options });
+    return this.#dispatch(EXTENSION_COMMANDS.NAVIGATE, { url, ...options }, options);
   }
 
-  click(selector, text, screenshot = true) {
-    return this.#dispatch(EXTENSION_COMMANDS.CLICK, { selector, text, screenshot });
+  click(selector, text, screenshot = true, options = {}) {
+    return this.#dispatch(EXTENSION_COMMANDS.CLICK, { selector, text, screenshot }, options);
   }
 
-  clickPoint(x, y, screenshot = true) {
-    return this.#dispatch(EXTENSION_COMMANDS.CLICK_POINT, { x, y, screenshot });
+  clickPoint(x, y, screenshot = true, options = {}) {
+    return this.#dispatch(EXTENSION_COMMANDS.CLICK_POINT, { x, y, screenshot }, options);
   }
 
   type(selector, text, options = {}) {
-    return this.#dispatch(EXTENSION_COMMANDS.TYPE, { selector, text, ...options });
+    return this.#dispatch(EXTENSION_COMMANDS.TYPE, { selector, text, ...options }, options);
   }
 
   typeText(text, options = {}) {
-    return this.#dispatch(EXTENSION_COMMANDS.TYPE_TEXT, { text, ...options });
+    return this.#dispatch(EXTENSION_COMMANDS.TYPE_TEXT, { text, ...options }, options);
   }
 
-  pressKey(key, screenshot = true) {
-    return this.#dispatch(EXTENSION_COMMANDS.PRESS_KEY, { key, screenshot });
+  pressKey(key, screenshot = true, options = {}) {
+    return this.#dispatch(EXTENSION_COMMANDS.PRESS_KEY, { key, screenshot }, options);
   }
 
-  scroll(deltaX = 0, deltaY = 0, screenshot = true) {
-    return this.#dispatch(EXTENSION_COMMANDS.SCROLL, { deltaX, deltaY, screenshot });
+  scroll(deltaX = 0, deltaY = 0, screenshot = true, options = {}) {
+    return this.#dispatch(EXTENSION_COMMANDS.SCROLL, { deltaX, deltaY, screenshot }, options);
   }
 
-  extract(selector, attribute, all = false) {
-    return this.#dispatch(EXTENSION_COMMANDS.EXTRACT, { selector, attribute, all });
+  extract(selector, attribute, all = false, options = {}) {
+    return this.#dispatch(EXTENSION_COMMANDS.EXTRACT, { selector, attribute, all }, options);
   }
 
-  evaluate(script) {
-    return this.#dispatch(EXTENSION_COMMANDS.EVALUATE, { script });
+  evaluate(script, options = {}) {
+    return this.#dispatch(EXTENSION_COMMANDS.EVALUATE, { script }, options);
   }
 
   screenshot(options = {}) {
-    return this.#dispatch(EXTENSION_COMMANDS.SCREENSHOT, options);
+    return this.#dispatch(EXTENSION_COMMANDS.SCREENSHOT, options, options);
   }
 
   launch(options = {}) {
-    return this.#dispatch(EXTENSION_COMMANDS.LAUNCH, options);
+    return this.#dispatch(EXTENSION_COMMANDS.LAUNCH, options, options);
   }
 
-  async closeBrowser() {
+  async closeBrowser(options = {}) {
     if (!this.registry || this.userId == null || !this.registry.isConnected(this.userId, this.tokenId)) {
       return { success: true, extensionConnected: false };
     }
-    const result = await this.#dispatch(EXTENSION_COMMANDS.CLOSE, {});
+    const result = await this.#dispatch(EXTENSION_COMMANDS.CLOSE, {}, options);
     this.#disconnect();
     return { ...result, success: result?.success !== false, extensionConnected: false };
   }
 
-  fill(selector, value) {
-    return this.type(selector, String(value));
+  fill(selector, value, options = {}) {
+    return this.type(selector, String(value), options);
   }
 
   extractContent(options = {}) {
-    return this.extract(options.selector, options.attribute, options.all);
+    return this.extract(options.selector, options.attribute, options.all, options);
   }
 
-  executeJS(code) {
-    return this.evaluate(code);
+  executeJS(code, options = {}) {
+    return this.evaluate(code, options);
   }
 
-  async getPageInfo() {
+  async getPageInfo(options = {}) {
     if (!this.registry || this.userId == null || !this.registry.isConnected(this.userId, this.tokenId)) {
       return { url: null, title: null, extensionConnected: false };
     }
     return this.registry.dispatch(this.userId, EXTENSION_COMMANDS.GET_PAGE_INFO, {}, {
       tokenId: this.tokenId,
+      signal: options.signal,
     });
   }
 
+  async getCookies(options = {}) {
+    const pageInfo = await this.getPageInfo(options);
+    let hostname = '';
+    try { hostname = new URL(String(pageInfo?.url || '')).hostname; } catch {}
+    if (!hostname) return { cookies: [], domains: [] };
+    return this.#dispatch(EXTENSION_COMMANDS.GET_COOKIES, {
+      domains: [hostname],
+    }, options);
+  }
+
   isLaunched() {
     return Boolean(this.registry && this.userId != null && this.registry.isConnected(this.userId, this.tokenId));
   }
@@ -181,5 +194,4 @@ class ExtensionBrowserProvider {
 
 module.exports = {
   ExtensionBrowserProvider,
-  extractBase64Png,
 };

package/server/services/browser/extension/registry.js

@@ -1,6 +1,13 @@
+'use strict';
+
 const crypto = require('crypto');
 const db = require('../../../db/database');
+const { createAbortError } = require('../../../utils/abort');
+const { validateCloudUrlWithDns } = require('../../../utils/cloud-security');
 const {
+  EXTENSION_COMMANDS,
+  EXTENSION_MESSAGE_TYPES,
+  EXTENSION_PROTOCOL_VERSION,
   ExtensionBrowserUnavailableError,
   createCommandMessage,
   parseExtensionMessage,
@@ -11,6 +18,8 @@ const DEFAULT_COMMAND_TIMEOUT_MS = 30 * 1000;
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 25 * 1000;
 const DEFAULT_HEARTBEAT_TIMEOUT_MS = 75 * 1000;
 const DEFAULT_PRESENCE_TOUCH_INTERVAL_MS = 15 * 1000;
+const DEFAULT_URL_VALIDATION_LIMIT = 128;
+const MAX_URL_VALIDATION_CHARS = 8192;
 
 function sha256(value) {
   return crypto.createHash('sha256').update(String(value || '')).digest('hex');
@@ -48,7 +57,13 @@ class BrowserExtensionRegistry {
     this.heartbeatIntervalMs = Number(options.heartbeatIntervalMs || process.env.NEOAGENT_BROWSER_EXTENSION_HEARTBEAT_INTERVAL_MS || DEFAULT_HEARTBEAT_INTERVAL_MS);
     this.heartbeatTimeoutMs = Number(options.heartbeatTimeoutMs || process.env.NEOAGENT_BROWSER_EXTENSION_HEARTBEAT_TIMEOUT_MS || DEFAULT_HEARTBEAT_TIMEOUT_MS);
     this.presenceTouchIntervalMs = Number(options.presenceTouchIntervalMs || process.env.NEOAGENT_BROWSER_EXTENSION_PRESENCE_TOUCH_INTERVAL_MS || DEFAULT_PRESENCE_TOUCH_INTERVAL_MS);
+    this.urlValidator = options.urlValidator || validateCloudUrlWithDns;
+    this.urlValidationLimit = Math.max(1, Math.min(
+      512,
+      Number(options.urlValidationLimit || DEFAULT_URL_VALIDATION_LIMIT),
+    ));
     this.connectionsByUser = new Map();
+    this.closed = false;
   }
 
   #getUserConnections(userId, create = false) {
@@ -204,6 +219,9 @@ class BrowserExtensionRegistry {
   }
 
   registerConnection(tokenRow, ws, meta = {}) {
+    if (this.closed) {
+      throw new ExtensionBrowserUnavailableError('Browser extension registry is shutting down.');
+    }
     const userId = String(tokenRow.user_id);
     const userMap = this.#getUserConnections(userId, true);
     const existing = userMap.get(tokenRow.id);
@@ -223,11 +241,15 @@ class BrowserExtensionRegistry {
       presenceTouchIntervalMs: this.presenceTouchIntervalMs,
     });
     userMap.set(tokenRow.id, connection);
-    this.db.prepare(
-      `UPDATE browser_extension_tokens
-       SET last_connected_at = datetime('now'), last_seen_at = datetime('now')
-       WHERE id = ?`
-    ).run(tokenRow.id);
+    try {
+      this.db.prepare(
+        `UPDATE browser_extension_tokens
+         SET last_connected_at = datetime('now'), last_seen_at = datetime('now')
+         WHERE id = ?`
+      ).run(tokenRow.id);
+    } catch (error) {
+      console.warn('[BrowserExtension] Failed to record connection presence:', error?.message);
+    }
     return connection;
   }
 
@@ -322,9 +344,13 @@ class BrowserExtensionRegistry {
     const userMap = this.#getUserConnections(userId);
     const connection = userMap?.get(String(tokenId));
     if (!connection?.isOpen()) return;
-    this.db.prepare(
-      `UPDATE browser_extension_tokens SET last_seen_at = datetime('now') WHERE id = ?`
-    ).run(tokenId);
+    try {
+      this.db.prepare(
+        `UPDATE browser_extension_tokens SET last_seen_at = datetime('now') WHERE id = ?`
+      ).run(tokenId);
+    } catch (error) {
+      console.warn('[BrowserExtension] Failed to update connection presence:', error?.message);
+    }
   }
 
   async dispatch(userId, command, payload = {}, options = {}) {
@@ -333,12 +359,14 @@ class BrowserExtensionRegistry {
       throw new ExtensionBrowserUnavailableError();
     }
     const result = await connection.sendCommand(command, payload, options);
-    this.db.prepare(
-      `UPDATE browser_extension_tokens SET last_seen_at = datetime('now') WHERE id = ?`
-    ).run(connection.tokenId);
+    this.touchPresence(userId, connection.tokenId);
     return result;
   }
 
+  validateBrowserUrl(url, options = {}) {
+    return this.urlValidator(url, options);
+  }
+
   getStatus(userId) {
     const userMap = this.#getUserConnections(userId);
     let selectedTokenId = this.getSelectedTokenId(userId);
@@ -396,22 +424,22 @@ class BrowserExtensionRegistry {
       ).run(userId);
     }
 
-    const connection = this.getConnection(userId, targetTokenId);
-    if (connection && (!targetTokenId || connection.tokenId === targetTokenId)) {
+    const userMap = this.#getUserConnections(userId);
+    const connections = targetTokenId
+      ? [userMap?.get(targetTokenId)].filter(Boolean)
+      : Array.from(userMap?.values() || []);
+    for (const connection of connections) {
       connection.close('extension token revoked');
     }
     return { success: true };
   }
 
   closeAll() {
-    for (const connection of this.connectionsByUser.values()) {
-      if (connection instanceof Map) {
-        for (const nested of connection.values()) {
-          nested.close('server shutdown');
-        }
-      } else {
-        connection.close('server shutdown');
-      }
+    this.closed = true;
+    const connections = Array.from(this.connectionsByUser.values())
+      .flatMap((entry) => entry instanceof Map ? Array.from(entry.values()) : [entry]);
+    for (const connection of connections) {
+      connection.close('server shutdown');
     }
     this.connectionsByUser.clear();
   }
@@ -433,24 +461,34 @@ class ExtensionBrowserConnection {
     this.lastPongAt = Date.now();
     this.lastPresenceTouchAt = 0;
     this.heartbeatTimer = null;
+    this.urlValidationCount = 0;
+    this.urlValidationController = new AbortController();
+    this.closed = false;
 
-    ws.on('message', (data) => this.#handleMessage(data));
+    ws.on('message', (data) => {
+      this.#handleMessage(data).catch(() => {});
+    });
     ws.on('pong', () => {
       this.lastPongAt = Date.now();
       this.touchPresence();
     });
     ws.on('close', () => this.#closePending(new ExtensionBrowserUnavailableError('Extension browser disconnected.')));
-    ws.on('error', (error) => this.#closePending(error));
+    ws.on('error', (error) => {
+      try { ws.terminate(); } catch {}
+      this.#closePending(error);
+    });
     this.#startHeartbeat();
   }
 
   isOpen() {
-    return this.ws && this.ws.readyState === 1;
+    return !this.closed && this.ws && this.ws.readyState === 1;
   }
 
   close(reason) {
+    const wasOpen = this.isOpen();
+    this.closed = true;
     try {
-      if (this.isOpen()) {
+      if (wasOpen) {
         this.ws.close(1000, String(reason || 'closing').slice(0, 120));
       }
     } catch {}
@@ -478,25 +516,57 @@ class ExtensionBrowserConnection {
       return Promise.reject(new ExtensionBrowserUnavailableError());
     }
     const id = crypto.randomUUID();
-    const timeoutMs = Number(options.timeoutMs || this.timeoutMs);
+    const requestedTimeout = Number(options.timeoutMs || this.timeoutMs);
+    const timeoutMs = Number.isFinite(requestedTimeout)
+      ? Math.min(10 * 60 * 1000, Math.max(100, requestedTimeout))
+      : DEFAULT_COMMAND_TIMEOUT_MS;
     const message = createCommandMessage(id, command, payload);
     return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
+      const signal = options.signal || null;
+      const sendCancellation = () => {
+        if (!this.isOpen() || command === EXTENSION_COMMANDS.CANCEL_COMMAND) return;
+        try {
+          this.ws.send(JSON.stringify(createCommandMessage(
+            crypto.randomUUID(),
+            EXTENSION_COMMANDS.CANCEL_COMMAND,
+            { commandId: id },
+          )));
+        } catch {}
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
         this.pending.delete(id);
-        reject(new Error(`Browser extension command timed out: ${command}`));
+      };
+      const onAbort = () => {
+        cleanup();
+        sendCancellation();
+        reject(createAbortError(signal, `Browser extension command aborted: ${command}`));
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        sendCancellation();
+        const error = new Error(`Browser extension command timed out: ${command}`);
+        error.code = 'BROWSER_EXTENSION_COMMAND_TIMEOUT';
+        reject(error);
       }, timeoutMs);
-      this.pending.set(id, { resolve, reject, timer, command });
+      timer.unref?.();
+      if (signal?.aborted) {
+        onAbort();
+        return;
+      }
+      signal?.addEventListener('abort', onAbort, { once: true });
+      this.pending.set(id, { resolve, reject, timer, command, signal, onAbort });
       try {
         this.ws.send(JSON.stringify(message));
       } catch (error) {
-        clearTimeout(timer);
-        this.pending.delete(id);
+        cleanup();
         reject(error);
       }
     });
   }
 
-  #handleMessage(data) {
+  async #handleMessage(data) {
     this.lastPongAt = Date.now();
     this.touchPresence();
     let message;
@@ -505,21 +575,70 @@ class ExtensionBrowserConnection {
     } catch {
       return;
     }
-    if (!message || message.type !== 'result' || !message.id) {
+    if (!message || !message.id) {
       return;
     }
+    if (message.type === EXTENSION_MESSAGE_TYPES.URL_VALIDATION_REQUEST) {
+      await this.#handleUrlValidationRequest(message);
+      return;
+    }
+    if (message.type !== EXTENSION_MESSAGE_TYPES.RESULT) return;
     const pending = this.pending.get(message.id);
     if (!pending) return;
     clearTimeout(pending.timer);
+    pending.signal?.removeEventListener('abort', pending.onAbort);
     this.pending.delete(message.id);
     if (message.ok === false) {
       pending.reject(new Error(message.error || `Browser extension command failed: ${pending.command}`));
       return;
     }
-    pending.resolve(message.result || {});
+    pending.resolve(message.result ?? {});
+  }
+
+  async #handleUrlValidationRequest(message) {
+    const id = typeof message.id === 'string' ? message.id : '';
+    if (!id || id.length > 200 || !this.isOpen()) return;
+
+    let allowed = false;
+    const url = typeof message.url === 'string' ? message.url : '';
+    const versionMatches = Number(message.version) === EXTENSION_PROTOCOL_VERSION;
+    const validationLimit = Number(this.registry.urlValidationLimit) || DEFAULT_URL_VALIDATION_LIMIT;
+    if (
+      versionMatches
+      && url.length > 0
+      && url.length <= MAX_URL_VALIDATION_CHARS
+      && this.urlValidationCount < validationLimit
+      && typeof this.registry.validateBrowserUrl === 'function'
+    ) {
+      this.urlValidationCount += 1;
+      try {
+        const result = await this.registry.validateBrowserUrl(url, {
+          signal: this.urlValidationController.signal,
+        });
+        allowed = result?.allowed === true;
+      } catch {
+        allowed = false;
+      } finally {
+        this.urlValidationCount -= 1;
+      }
+    }
+
+    if (!this.isOpen()) return;
+    try {
+      this.ws.send(JSON.stringify({
+        type: EXTENSION_MESSAGE_TYPES.URL_VALIDATION_RESULT,
+        version: EXTENSION_PROTOCOL_VERSION,
+        id,
+        allowed,
+      }));
+    } catch {}
   }
 
   #closePending(error) {
+    this.closed = true;
+    if (!this.urlValidationController.signal.aborted) {
+      this.urlValidationController.abort(error);
+    }
     this.registry.unregisterConnection(this);
     if (this.heartbeatTimer) {
       clearInterval(this.heartbeatTimer);
@@ -527,6 +646,7 @@ class ExtensionBrowserConnection {
     }
     for (const pending of this.pending.values()) {
       clearTimeout(pending.timer);
+      pending.signal?.removeEventListener('abort', pending.onAbort);
       pending.reject(error);
     }
     this.pending.clear();
@@ -559,6 +679,7 @@ class ExtensionBrowserConnection {
 }
 
 module.exports = {
+  ExtensionBrowserConnection,
   BrowserExtensionRegistry,
   sha256,
 };