chrome-bridge-mcp 1.8.0

package/server/formatters.js

@@ -0,0 +1,35 @@
+/**
+ * Formatter riga-per-riga condivisi tra tool MCP (tools.js) e CLI (cli.js).
+ * Un'unica fonte: stesso output sui due canali, niente divergenza.
+ */
+
+/** Messaggi console: "level<TAB>+Δms<TAB>testo", delta relativo al primo mostrato. */
+export function consoleLines(tail, total) {
+  const t0 = tail[0]?.timestamp ?? 0;
+  const lines = tail.map((m) => `${m.level}\t+${(m.timestamp ?? t0) - t0}ms\t${(m.args ?? []).join(' ')}`);
+  return `console total=${total} shown=${tail.length}\n${lines.join('\n')}`;
+}
+
+/** Richieste di rete: "status<TAB>ms<TAB>method<TAB>url", errori come ERR(msg). */
+export function networkLines(tail, total) {
+  const lines = tail.map((r) => `${r.status ?? `ERR(${r.error})`}\t${r.duration}ms\t${r.method}\t${r.url}`);
+  return `network total=${total} shown=${tail.length}\n${lines.join('\n')}`;
+}
+
+/** Elementi interattivi: flag (disabled/hidden/occluded) solo quando anomali. Ref n1..nN in testa se presente. */
+export function interactivesLines(data) {
+  const els = data?.elements ?? [];
+  const lines = els.map((e) => {
+    const flags = [!e.enabled && 'disabled', !e.visible && 'hidden', e.occluded && 'occluded'].filter(Boolean).join(',');
+    const rect = e.rect ? `@${e.rect.x},${e.rect.y} ${e.rect.width}x${e.rect.height}` : '';
+    return [...(e.ref ? [e.ref] : []), `${e.selector}`, `${e.tag}${e.type ? `:${e.type}` : ''}`, e.text ?? '', ...(flags ? [flags] : []), rect].join('\t');
+  });
+  const note = data?.note ? ` note=${data.note}` : '';
+  return `interactives count=${data?.count ?? els.length}${note}\n${lines.join('\n')}`;
+}
+
+/** Esito verifica link: "status<TAB>url<TAB>error". */
+export function linksLines(results, { total, broken, anchors }) {
+  const lines = results.map((r) => `${r.status}\t${r.url}${r.error ? `\t${r.error}` : ''}`);
+  return `links total=${total} checked=${results.length} broken=${broken} anchors=${anchors}\n${lines.join('\n')}`;
+}

package/server/har.js

@@ -0,0 +1,22 @@
+/**
+ * Conversione delle richieste catturate in formato HAR 1.2.
+ */
+
+import { VERSION } from './protocol.js';
+
+export function toHar(requests) {
+  return {
+    log: {
+      version: '1.2',
+      creator: { name: 'chrome-bridge', version: VERSION },
+      entries: requests.map((r) => ({
+        startedDateTime: new Date(r.startTime).toISOString(),
+        time: r.duration ?? 0,
+        request: { method: r.method || 'GET', url: r.url, httpVersion: '', headers: [], queryString: [], cookies: [], headersSize: -1, bodySize: -1 },
+        response: { status: r.status ?? 0, statusText: r.error || '', httpVersion: '', headers: [], cookies: [], content: { size: -1, mimeType: '' }, redirectURL: '', headersSize: -1, bodySize: -1 },
+        cache: {},
+        timings: { send: 0, wait: r.duration ?? 0, receive: 0 },
+      })),
+    },
+  };
+}

package/server/index.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+/**
+ * Chrome Bridge MCP Server
+ *
+ * Entry point che avvia:
+ * 1. Il server WebSocket (per comunicare con l'estensione Chrome)
+ * 2. Il server MCP (per comunicare con Claude Code via stdio)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { WSManager } from './ws-manager.js';
+import { registerTools } from './tools.js';
+import { launchBrowser } from './launcher.js';
+import { DEFAULT_PORT, VERSION } from './protocol.js';
+
+// Launch mode: browser dedicato (profilo effimero + estensione unpacked).
+// Porta effimera di default: zero conflitti con un bridge già attivo.
+const LAUNCH = process.argv.includes('--launch');
+const HEADLESS = process.argv.includes('--headless');
+function argValue(flag) {
+  const i = process.argv.indexOf(flag);
+  return i !== -1 ? process.argv[i + 1] : undefined;
+}
+// Bind: loopback di default, 0.0.0.0 solo su richiesta esplicita (Crostini).
+const HOST = argValue('--host') ?? process.env.CHROME_BRIDGE_HOST ?? '127.0.0.1';
+const PORT = process.env.CHROME_BRIDGE_PORT
+  ? parseInt(process.env.CHROME_BRIDGE_PORT, 10)
+  : (LAUNCH ? 0 : DEFAULT_PORT);
+
+// Capability: default = solo set core (30 tool). --caps audits,visual o
+// CHROME_BRIDGE_CAPS attivano i gruppi opt-in; "all" registra tutto.
+function parseCaps() {
+  const i = process.argv.indexOf('--caps');
+  if (i !== -1 && process.argv[i + 1]) return process.argv[i + 1];
+  return process.env.CHROME_BRIDGE_CAPS || 'core';
+}
+
+async function main() {
+  // 1. Crea il server MCP
+  // instructions: dette una volta qui invece che ripetute in ogni descrizione
+  // tool — pesano ~1 volta nel contesto del client anziché ~50.
+  const mcpServer = new McpServer({
+    name: 'chrome-bridge',
+    version: VERSION,
+  }, {
+    instructions: [
+      'Selector parameters on DOM tools support shadow-DOM piercing with ">>>" (e.g. "my-app >>> button.save").',
+      'tab_id omitted = the tab last navigated/created in this session, else the active tab. frame_id omitted = main frame (list frames with get_frames).',
+      'Prefer get_interactives over read_page(html) to discover targets; its refs (n1, n2…) work as the ref param of click/type_text/hover.',
+      // Il costo dominante sono i TURNI, non i byte: un turno vale ~15-30 volte
+      // un KB di output risparmiato. Queste due clausole si pagano una volta
+      // qui e valgono più di qualunque ottimizzazione di schema.
+      'For more than one field use fill_form once (with submit_selector to submit in the same call) instead of repeated type_text: one turn instead of N.',
+      'For tables use extract_table (server-side where/columns filtering) or extract, never read_page: read_page on a big table costs tens of thousands of tokens for data you filter anyway.',
+    ].join(' '),
+  });
+
+  // 2. Avvia il WebSocket server
+  const wsManager = new WSManager(PORT, { host: HOST });
+  await wsManager.start();
+
+  // 2b. Launch mode: browser dedicato che si connette alla nostra porta.
+  // Gli handler di shutdown sono registrati PRIMA del launch: registrarli dopo
+  // lasciava Chromium e il profilo temporaneo orfani a ogni segnale ricevuto
+  // durante l'avvio (osservate 3 directory residue, una da 122 MB).
+  let browser = null;
+  const shutdown = async () => {
+    console.error('[chrome-bridge] Shutting down...');
+    try { if (browser) await browser.stop(); } catch {}
+    try { await wsManager.stop(); } catch {}
+    try { await mcpServer.close(); } catch {}
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+  process.on('uncaughtException', (err) => {
+    console.error('[chrome-bridge] Uncaught exception:', err);
+    shutdown().catch(() => process.exit(1));
+  });
+  process.on('unhandledRejection', (err) => {
+    console.error('[chrome-bridge] Unhandled rejection:', err);
+  });
+
+  if (LAUNCH) {
+    if (wsManager.mode !== 'primary') {
+      throw new Error(`--launch requires a dedicated port, but ${wsManager.port} is owned by another chrome-bridge. Unset CHROME_BRIDGE_PORT (ephemeral) or pick a free one.`);
+    }
+    browser = await launchBrowser({ port: wsManager.port, headless: HEADLESS });
+  }
+
+  // 3. Registra i tool MCP (filtrati per capability)
+  registerTools(mcpServer, wsManager, parseCaps());
+
+  // 4. Avvia il trasporto stdio MCP
+  const transport = new StdioServerTransport();
+  await mcpServer.connect(transport);
+
+  console.error(`[chrome-bridge] MCP server ready (stdio + WebSocket, mode: ${wsManager.mode})`);
+
+}
+
+main().catch((err) => {
+  console.error('[chrome-bridge] Fatal error:', err);
+  process.exit(1);
+});

package/server/launcher.js

@@ -0,0 +1,97 @@
+/**
+ * Launch mode: avvia un browser Chromium dedicato (headless o no) con
+ * profilo effimero e l'estensione caricata unpacked da una copia temporanea.
+ *
+ * La copia contiene un launch.json con la porta WS del server: nel pacchetto
+ * Chrome Web Store il file non esiste e l'estensione usa la porta da storage.
+ * Profilo e copia vengono rimossi allo stop.
+ */
+
+import { spawn } from 'node:child_process';
+import { cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const EXTENSION_SRC = join(dirname(fileURLToPath(import.meta.url)), '..', 'extension');
+
+const BROWSER_CANDIDATES = [
+  '/usr/bin/chromium',
+  '/usr/bin/chromium-browser',
+  '/usr/bin/google-chrome',
+  '/usr/bin/google-chrome-stable',
+];
+
+export function findBrowser() {
+  if (process.env.CHROME_BRIDGE_BROWSER) {
+    if (!existsSync(process.env.CHROME_BRIDGE_BROWSER)) {
+      throw new Error(`CHROME_BRIDGE_BROWSER not found: ${process.env.CHROME_BRIDGE_BROWSER}`);
+    }
+    return process.env.CHROME_BRIDGE_BROWSER;
+  }
+  const found = BROWSER_CANDIDATES.find((p) => existsSync(p));
+  if (!found) {
+    throw new Error(`No Chromium/Chrome binary found (tried: ${BROWSER_CANDIDATES.join(', ')}). Set CHROME_BRIDGE_BROWSER.`);
+  }
+  return found;
+}
+
+/** Prepara dir temporanee: copia estensione + launch.json, profilo con dev mode. */
+export async function prepareLaunch(port) {
+  const base = await mkdtemp(join(tmpdir(), 'chrome-bridge-launch-'));
+  const extDir = join(base, 'ext');
+  const profileDir = join(base, 'profile');
+
+  await cp(EXTENSION_SRC, extDir, { recursive: true });
+  await writeFile(join(extDir, 'launch.json'), JSON.stringify({ port }));
+
+  // Dev mode pre-abilitato: su Chrome 135-137 sblocca chrome.userScripts;
+  // su versioni successive execute_js usa comunque il fallback new Function.
+  await mkdir(join(profileDir, 'Default'), { recursive: true });
+  await writeFile(join(profileDir, 'Default', 'Preferences'),
+    JSON.stringify({ extensions: { ui: { developer_mode: true } } }));
+
+  return { base, extDir, profileDir };
+}
+
+/**
+ * Avvia il browser. Ritorna { pid, stop } — stop() termina il processo e
+ * rimuove le directory temporanee.
+ */
+export async function launchBrowser({ port, headless = false }) {
+  const browser = findBrowser();
+  const { base, extDir, profileDir } = await prepareLaunch(port);
+
+  const args = [
+    `--user-data-dir=${profileDir}`,
+    `--load-extension=${extDir}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--hide-crash-restore-bubble',
+    '--disable-gpu',
+    '--window-size=1280,800',
+  ];
+  if (headless) args.push('--headless=new');
+  args.push('about:blank');
+
+  const proc = spawn(browser, args, { stdio: 'ignore', detached: false });
+  proc.on('error', (err) => console.error(`[chrome-bridge] browser process error: ${err.message}`));
+
+  let stopped = false;
+  const stop = async () => {
+    if (stopped) return;
+    stopped = true;
+    if (proc.exitCode === null) {
+      proc.kill('SIGTERM');
+      await new Promise((resolve) => {
+        const t = setTimeout(() => { try { proc.kill('SIGKILL'); } catch {} resolve(); }, 3000);
+        proc.once('exit', () => { clearTimeout(t); resolve(); });
+      });
+    }
+    await rm(base, { recursive: true, force: true }).catch(() => {});
+  };
+
+  console.error(`[chrome-bridge] launched ${browser}${headless ? ' (headless)' : ''} pid=${proc.pid}, ws port ${port}`);
+  return { pid: proc.pid, stop };
+}

package/server/link-checker.js

@@ -0,0 +1,57 @@
+/**
+ * Verifica HTTP dei link lato server (niente limiti CORS della pagina).
+ * HEAD con fallback GET per server che non supportano HEAD.
+ *
+ * Nota SSRF: i link arrivano dalla pagina aperta dall'utente (tool locale di
+ * sviluppo); nessun filtro su IP privati. Solo http/https.
+ *
+ * Nota: HEAD 403 da bot-protection può causare falsi positivi; il fallback
+ * GET scatta solo su 405/501 by design.
+ */
+
+async function checkOne({ url, text }, timeoutMs) {
+  // Scheme guard: solo http/https supportati
+  try {
+    const proto = new URL(url).protocol;
+    if (proto !== 'http:' && proto !== 'https:') {
+      return { url, text, status: 0, ok: false, broken: true, error: 'Unsupported scheme' };
+    }
+  } catch {
+    return { url, text, status: 0, ok: false, broken: true, error: 'Invalid URL' };
+  }
+
+  let lastError = null;
+  for (const method of ['HEAD', 'GET']) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const resp = await fetch(url, { method, redirect: 'follow', signal: ctrl.signal });
+      clearTimeout(timer);
+      if (method === 'HEAD' && (resp.status === 405 || resp.status === 501)) continue;
+      if (method === 'GET') await resp.body?.cancel();
+      return { url, text, status: resp.status, ok: resp.ok, broken: resp.status >= 400 };
+    } catch (err) {
+      clearTimeout(timer);
+      if (err.name === 'AbortError' || err.cause?.name === 'AbortError') {
+        lastError = `timeout after ${timeoutMs}ms`;
+        break;
+      }
+      lastError = err.cause?.message || err.message || 'Network error';
+    }
+  }
+  return { url, text, status: 0, ok: false, broken: true, error: lastError };
+}
+
+export async function checkLinksBatch(links, timeoutMs = 5000, concurrency = 10) {
+  const results = new Array(links.length);
+  let next = 0;
+  async function worker() {
+    while (next < links.length) {
+      const idx = next++;
+      results[idx] = await checkOne(links[idx], timeoutMs);
+    }
+  }
+  const workers = Array.from({ length: Math.min(concurrency, links.length) }, worker);
+  await Promise.all(workers);
+  return results;
+}

package/server/protocol.js

@@ -0,0 +1,135 @@
+/**
+ * Costanti del protocollo e helper per la comunicazione WebSocket.
+ */
+
+import { randomBytes } from 'node:crypto';
+
+// Tipi di messaggi WebSocket
+export const MessageType = Object.freeze({
+  // Comandi (server → extension)
+  NAVIGATE:        'navigate',
+  SCREENSHOT:      'screenshot',
+  EXECUTE_JS:      'execute_js',
+  CLICK:           'click',
+  TYPE_TEXT:        'type_text',
+  READ_PAGE:       'read_page',
+  GET_TABS:        'get_tabs',
+  GET_PAGE_INFO:   'get_page_info',
+  GET_STORAGE:     'get_storage',
+  GET_PERFORMANCE: 'get_performance',
+  QUERY_DOM:       'query_dom',
+  MODIFY_DOM:      'modify_dom',
+  INJECT_CSS:      'inject_css',
+  READ_CONSOLE:         'read_console',
+  MONITOR_NETWORK:      'monitor_network',
+  CREATE_TAB:           'create_tab',
+  WAIT_FOR_ELEMENT:     'wait_for_element',
+  SCROLL_TO:            'scroll_to',
+  SET_STORAGE:          'set_storage',
+  FILL_FORM:            'fill_form',
+  VIEWPORT_RESIZE:      'viewport_resize',
+  FULL_PAGE_SCREENSHOT: 'full_page_screenshot',
+  ELEMENT_SCREENSHOT:   'element_screenshot',
+  HIGHLIGHT_ELEMENTS:   'highlight_elements',
+  ACCESSIBILITY_AUDIT:  'accessibility_audit',
+  COLLECT_LINKS:        'collect_links',
+  MEASURE_SPACING:      'measure_spacing',
+  WATCH_DOM:            'watch_dom',
+  EMULATE_MEDIA:        'emulate_media',
+  HOVER:                'hover',
+  PRESS_KEY:            'press_key',
+  GET_FRAMES:           'get_frames',
+  TAB_ACTION:           'tab_action',
+  UPLOAD_FILE:           'upload_file',
+  WAIT_FOR_NAVIGATION:   'wait_for_navigation',
+  WAIT_FOR_NETWORK_IDLE: 'wait_for_network_idle',
+  HANDLE_DIALOGS:        'handle_dialogs',
+  FIND_TEXT:             'find_text',
+  NETWORK_RULES:         'network_rules',
+  SCREENSHOT_DIFF:       'screenshot_diff',
+  WEB_VITALS:            'web_vitals',
+  LIST_EVENT_LISTENERS:  'list_event_listeners',
+  MONITOR_WEBSOCKET:     'monitor_websocket',
+  SEO_AUDIT:             'seo_audit',
+  EXTRACT_TABLE:         'extract_table',
+  UNUSED_CSS:            'unused_css',
+  DRAG_AND_DROP:         'drag_and_drop',
+  CLIPBOARD:             'clipboard',
+  SET_GEOLOCATION:       'set_geolocation',
+  MANAGE_DOWNLOADS:      'manage_downloads',
+  SAVE_PAGE:             'save_page',
+  SET_ZOOM:              'set_zoom',
+  HTTP_AUTH:             'http_auth',
+  GET_RESPONSE_HEADERS:  'get_response_headers',
+  GET_INTERACTIVES:      'get_interactives',
+  WAIT_FOR_FUNCTION:     'wait_for_function',
+  SCROLL_UNTIL:          'scroll_until',
+  DISMISS_OVERLAYS:      'dismiss_overlays',
+
+  // Risposte (extension → server)
+  RESULT: 'result',
+  ERROR:  'error',
+
+  // Heartbeat
+  PING: 'ping',
+  PONG: 'pong',
+
+  // Handshake identificazione connessione
+  EXT_INIT:   'ext_init',
+  RELAY_INIT: 'relay_init',
+});
+
+// Versione
+export const VERSION               = '1.8.0';
+
+// Configurazione
+export const DEFAULT_PORT          = 8765;
+export const COMMAND_TIMEOUT_MS    = 30000;  // 30s per comandi normali
+export const SCREENSHOT_TIMEOUT_MS = 10000;  // 10s per screenshot
+export const PING_INTERVAL_MS      = 15000;  // 15s heartbeat
+export const IDENT_TIMEOUT_MS      = 5000;   // tempo max per identificarsi
+export const PENDING_RELAY_TTL_MS  = 150000; // deve superare il timeout comando più lungo (120s full_page_screenshot)
+
+// Entropia per instance + contatore globale per ID univoci
+// 4 byte casuali per processo (2^32 valori): sufficiente per un bridge locale
+const instanceId = randomBytes(4).toString('hex');
+let messageCounter = 0;
+
+/**
+ * Crea un oggetto comando da inviare all'estensione.
+ *
+ * @param {string} type - Tipo di comando (da MessageType)
+ * @param {object} params - Parametri del comando
+ * @returns {object} Comando serializzabile in JSON
+ */
+export function createCommand(type, params = {}) {
+  messageCounter += 1;
+  return {
+    id: `msg_${instanceId}_${messageCounter}`,
+    type,
+    params,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Restituisce il timeout appropriato per un tipo di comando.
+ *
+ * @param {string} type - Tipo di comando
+ * @returns {number} Timeout in millisecondi
+ */
+export function getTimeout(type) {
+  if (type === MessageType.SCREENSHOT
+    || type === MessageType.ELEMENT_SCREENSHOT
+    || type === MessageType.SCREENSHOT_DIFF) return SCREENSHOT_TIMEOUT_MS;
+  if (type === MessageType.FULL_PAGE_SCREENSHOT) return 120000;
+  if (type === MessageType.WAIT_FOR_ELEMENT
+    || type === MessageType.WAIT_FOR_NAVIGATION
+    || type === MessageType.WAIT_FOR_NETWORK_IDLE
+    || type === MessageType.UPLOAD_FILE
+    || type === MessageType.MANAGE_DOWNLOADS
+    || type === MessageType.SAVE_PAGE
+    || type === MessageType.WAIT_FOR_FUNCTION
+    || type === MessageType.SCROLL_UNTIL) return 60000;
+  return COMMAND_TIMEOUT_MS;
+}

package/server/security-headers.js

@@ -0,0 +1,68 @@
+/**
+ * Valutazione lato server degli header di sicurezza HTTP
+ * (header raccolti dall'estensione via webRequest).
+ */
+
+export function evaluateSecurityHeaders(headers, url) {
+  // headers: oggetto con chiavi lowercase
+  const findings = [];
+  const isHttps = url.startsWith('https:');
+  const add = (severity, header, message) => findings.push({ severity, header, message });
+
+  const csp = headers['content-security-policy'];
+  // Wildcard "nuda" (token * isolato), non sottodomini tipo *.example.com
+  const cspBareWildcard = !!csp && /default-src[^;]*(?:^|\s)\*(?=\s|;|$)/.test(csp);
+  if (!csp) {
+    add('warning', 'content-security-policy', 'No Content-Security-Policy header');
+  } else {
+    if (csp.includes("'unsafe-inline'")) add('warning', 'content-security-policy', "CSP allows 'unsafe-inline'");
+    if (csp.includes("'unsafe-eval'")) add('warning', 'content-security-policy', "CSP allows 'unsafe-eval'");
+    if (cspBareWildcard) add('warning', 'content-security-policy', 'CSP default-src allows any origin (*)');
+  }
+
+  if (isHttps && !headers['strict-transport-security']) {
+    add('warning', 'strict-transport-security', 'No Strict-Transport-Security header (HSTS)');
+  }
+
+  if (!headers['x-content-type-options'] || headers['x-content-type-options'].toLowerCase() !== 'nosniff') {
+    add('warning', 'x-content-type-options', 'X-Content-Type-Options: nosniff missing');
+  }
+
+  const hasFrameProtection = headers['x-frame-options'] || (csp && csp.includes('frame-ancestors'));
+  if (!hasFrameProtection) {
+    add('warning', 'x-frame-options', 'No clickjacking protection (X-Frame-Options or CSP frame-ancestors)');
+  }
+
+  if (!headers['referrer-policy']) {
+    add('info', 'referrer-policy', 'No Referrer-Policy header');
+  }
+
+  if (!headers['permissions-policy']) {
+    add('info', 'permissions-policy', 'No Permissions-Policy header');
+  }
+
+  const server = headers['server'];
+  if (server && /\/[\d.]+/.test(server)) {
+    add('info', 'server', `Server header leaks software version: "${server}"`);
+  }
+  const powered = headers['x-powered-by'];
+  if (powered) {
+    add('info', 'x-powered-by', `X-Powered-By header leaks stack: "${powered}"`);
+  }
+
+  return {
+    url,
+    findings,
+    summary: {
+      errors: findings.filter((f) => f.severity === 'error').length,
+      warnings: findings.filter((f) => f.severity === 'warning').length,
+      info: findings.filter((f) => f.severity === 'info').length,
+    },
+    grade_hints: {
+      csp: !!csp && !csp.includes("'unsafe-inline'") && !csp.includes("'unsafe-eval'") && !cspBareWildcard,
+      hsts: !isHttps || !!headers['strict-transport-security'],
+      nosniff: headers['x-content-type-options']?.toLowerCase() === 'nosniff',
+      clickjacking: !!hasFrameProtection,
+    },
+  };
+}

package/server/stub-server.js

@@ -0,0 +1,81 @@
+/**
+ * Mini server HTTP per il response stubbing di network_rules.
+ *
+ * declarativeNetRequest può bloccare/redirigere ma non sintetizzare body:
+ * le richieste da stubbare vengono redirette qui, dove serviamo la risposta
+ * registrata (CORS aperto). Porta effimera, avviato al primo stub.
+ *
+ * Nota mixed-content: da pagine HTTPS il browser blocca redirect verso
+ * http:// non-trustworthy. 127.0.0.1 è trattato come sicuro; su ChromeOS
+ * (host penguin.linux.test) gli stub valgono per pagine http/dev server.
+ */
+
+import { createServer } from 'node:http';
+import { hostname } from 'node:os';
+
+const stubs = new Map();
+let server = null;
+let port = null;
+let seq = 0;
+
+/** Host raggiungibile dal browser: override env, poi euristica Crostini. */
+export function stubHost() {
+  if (process.env.CHROME_BRIDGE_STUB_HOST) return process.env.CHROME_BRIDGE_STUB_HOST;
+  return hostname() === 'penguin' ? 'penguin.linux.test' : '127.0.0.1';
+}
+
+export async function ensureStubServer() {
+  if (server) return port;
+  server = createServer((req, res) => {
+    const cors = {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': '*',
+      'Access-Control-Allow-Headers': '*',
+    };
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, cors);
+      res.end();
+      return;
+    }
+    const id = (req.url || '').replace(/^\/__stub__\//, '').split('?')[0];
+    const stub = stubs.get(id);
+    if (!stub) {
+      res.writeHead(404, { ...cors, 'Content-Type': 'text/plain' });
+      res.end('stub not found');
+      return;
+    }
+    res.writeHead(stub.status, { ...cors, 'Content-Type': stub.content_type });
+    res.end(stub.body);
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    // 0.0.0.0: su Crostini il browser host entra dall'interfaccia del container
+    server.listen(0, '0.0.0.0', resolve);
+  });
+  server.unref();
+  port = server.address().port;
+  return port;
+}
+
+export function addStub({ body, status = 200, content_type = 'application/json' }) {
+  const id = `s${++seq}`;
+  stubs.set(id, { body, status, content_type });
+  return id;
+}
+
+export function clearStubs() {
+  stubs.clear();
+}
+
+export function listStubs() {
+  return [...stubs.entries()].map(([id, s]) => ({ id, status: s.status, content_type: s.content_type, bytes: Buffer.byteLength(s.body) }));
+}
+
+export async function stopStubServer() {
+  stubs.clear();
+  if (server) {
+    await new Promise((r) => server.close(r));
+    server = null;
+    port = null;
+  }
+}