feat: browser_intercept, managed daemon lifecycle, loopback-only hardening, MAIN-world console capture

.env.example

@@ -12,10 +12,9 @@
 # Port the daemon's WebSocket + HTTP server binds on. The extension connects
 # here. Override only if something else owns 7225 on your machine.
 # WS_PORT=7225
-
-# Interface to bind. 127.0.0.1 keeps the daemon loopback-only (recommended);
-# do NOT set 0.0.0.0 unless you understand the exposure.
-# WS_HOST=127.0.0.1
+# The daemon always binds its HTTP/WebSocket control plane to 127.0.0.1.
+# There is intentionally no WS_HOST override: remote callers (including n8n)
+# need a separately authenticated transport, not a public browser socket.
 
 # --- Daemon state --------------------------------------------------------
 

SECURITY.md

@@ -28,7 +28,8 @@ Report vulnerabilities through:
 
 ## Security Model
 
-- **Local-only communication**: WebSocket between extension and server runs on localhost only.
+- **Local-only communication**: the daemon's HTTP/WebSocket control plane is hard-bound to IPv4 loopback (`127.0.0.1`), not configurable through `WS_HOST`. WebSocket traffic between the extension and daemon remains local. MCP clients use stdio and then an authenticated local IPC socket; they do not get a TCP listener.
+- **Remote callers and n8n**: Browser Controller has no supported remote or n8n ingress protocol. Do not publish port 7225 or change the listener to a wildcard address. A remote integration should run on the same host and reach the MCP client through its approved local process boundary, or be given a separately authenticated transport; browser-control credentials must not be reused as a network API key.
 - **Origin validation (exact-match on a pinned extension ID)**: the daemon pins the extension's `chrome-extension://<id>` Origin on first contact, then rejects every later request whose Origin is not an exact match. This applies to BOTH the WebSocket upgrade and the HTTP endpoints (`/pair`, `/status`, `/kill`) through one shared gate — a web page and a co-installed hostile extension (which carries its own Origin and cannot forge ours) are both rejected. The browser sets the `Origin` header; it cannot be forged from page JS.
 - **Token auth on the control plane**: the WebSocket upgrade additionally requires the daemon's auth token (sent out-of-band via `Sec-WebSocket-Protocol` subprotocol, with a `?token=` legacy fallback). HTTP endpoints cannot require that token because `/pair` is how it is obtained; they instead require the browser-asserted pinned Origin plus the separate `X-BC-Enrollment` secret.
 - **Versioned capability handshake**: transport authentication is necessary but not sufficient to mark the extension ready. The daemon and extension advertise a protocol major, application version, and capabilities before tool traffic is routed. An explicitly incompatible protocol major is rejected; application-version differences alone are diagnostic because compatible patch releases can share the same wire contract. Peers that omit the protocol field are identified as legacy during the migration window rather than being silently mistaken for a current peer.

deploy/systemd/browser-controller-daemon.service

@@ -0,0 +1,17 @@
+# Example systemd user unit. Adjust the checkout path (and node location if
+# `node` is not on the user manager's PATH) to match your installation.
+[Unit]
+Description=Browser Controller shared daemon
+After=graphical-session.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h/browser-controller
+Environment=HOME=%h
+ExecStart=/usr/bin/env node %h/browser-controller/mcp-server/dist/daemon.js
+Restart=always
+RestartSec=2
+NoNewPrivileges=true
+
+[Install]
+WantedBy=default.target

eslint.config.js

@@ -27,7 +27,8 @@ export default [
       parserOptions: {
         requireConfigFile: false,
         babelOptions: {
-          presets: [['@babel/preset-typescript', { allowDeclareFields: true }]],
+          // Babel 8 always allows `declare` fields (the option was removed).
+          presets: ['@babel/preset-typescript'],
         },
       },
     },

extension/console-main.js

@@ -0,0 +1,36 @@
+/**
+ * MAIN-world console capture. content.js runs in the extension's isolated
+ * world, where patching `console` only sees the extension's own calls — the
+ * page's console.log/warn/info/debug/error never reached browser_console.
+ * This script patches the PAGE's console and hands each entry to content.js
+ * as a JSON string on a private DOM event (object details don't cross
+ * worlds). Uncaught errors / rejections are still captured by content.js.
+ */
+(function () {
+  'use strict';
+  if (window.__bcConsoleMain) return;
+  Object.defineProperty(window, '__bcConsoleMain', { value: true });
+  const EVENT = '__bc_console_entry';
+  const LEVELS = ['log', 'info', 'warn', 'error', 'debug'];
+  const fmt = (a) => {
+    if (typeof a === 'string') return a;
+    if (a instanceof Error) return `${a.name}: ${a.message}`;
+    if (a && typeof a === 'object') {
+      try { return JSON.stringify(a); } catch { return Object.prototype.toString.call(a); }
+    }
+    return String(a);
+  };
+  for (const level of LEVELS) {
+    const orig = console[level];
+    if (typeof orig !== 'function') continue;
+    const patched = function (...args) {
+      try {
+        let text = args.map(fmt).join(' ');
+        if (text.length > 2000) text = text.slice(0, 2000) + '…[truncated]';
+        document.dispatchEvent(new CustomEvent(EVENT, { detail: JSON.stringify({ level, text }) }));
+      } catch { /* never break the page's logging */ }
+      return orig.apply(this, args);
+    };
+    try { console[level] = patched; } catch { /* frozen console */ }
+  }
+})();

extension/content.js

@@ -37,6 +37,15 @@
   console.info = (...a) => capture('info', ...a);
   console.debug = (...a) => capture('debug', ...a);
 
+  // Page console entries from console-main.js (MAIN world), JSON on a DOM event.
+  document.addEventListener('__bc_console_entry', (e) => {
+    let entry;
+    try { entry = JSON.parse(e.detail); } catch { return; }
+    if (!entry || typeof entry.text !== 'string') return;
+    if (entry.text.indexOf('ResizeObserver loop') !== -1) return;
+    try { chrome.runtime.sendMessage({ type: 'console', level: String(entry.level || 'log'), text: entry.text.slice(0, 2100) }); } catch {}
+  });
+
   window.addEventListener('error', (e) => {
     // Silence the well-known ResizeObserver loop warning: it's a benign browser
     // notice (element resized during its own observation callback), not a real

extension/events.js

@@ -13,17 +13,18 @@ import {
   persistSessionState,
   dropTabState,
   dropDocumentState,
-} from './lib/state.js';
-import { showLockShield, hideLockShield } from './lib/overlay.js';
-import { lockTabUi, releaseTabUi } from './lib/lock-ops.js';
+} from "./lib/state.js";
+import { showLockShield, hideLockShield } from "./lib/overlay.js";
+import { enrichCapture } from "./handlers/intercept.js";
+import { lockTabUi, releaseTabUi } from "./lib/lock-ops.js";
 import {
   getOpenTabs,
   buildStatusPayload,
   broadcastStatus,
   applyPort,
   applyToken,
   applyEnrollment,
-} from './lib/connection.js';
+} from "./lib/connection.js";
 
 export function registerEventListeners() {
   chrome.runtime.onMessage.addListener((msg, sender, respond) => {
@@ -32,12 +33,17 @@ export function registerEventListeners() {
     // before that, Chrome logs "message channel closed before a response was
     // received". Every branch below responds synchronously (or is fire-and-forget),
     // so we return false (or nothing) — Chrome handles it without the warning.
-    if (msg.type === 'console' && sender.tab?.id != null) {
+    if (msg.type === "console" && sender.tab?.id != null) {
       const buf = getTabBuffer(consoleByTab, sender.tab.id);
-      pushCapped(buf, { level: msg.level, text: msg.text, timestamp: Date.now(), url: sender.tab.url });
+      pushCapped(buf, {
+        level: msg.level,
+        text: msg.text,
+        timestamp: Date.now(),
+        url: sender.tab.url,
+      });
       return false; // fire-and-forget; no response expected
     }
-    if (msg.type === 'getStatus') {
+    if (msg.type === "getStatus") {
       // Async: fetch tabs before responding so the popup gets a full snapshot
       // (connection + locks + open tabs) in one message. Returning true signals
       // Chrome we'll call respond() asynchronously.
@@ -46,15 +52,15 @@ export function registerEventListeners() {
       });
       return true; // async response
     }
-    if (msg.type === 'setPort') {
+    if (msg.type === "setPort") {
       respond(applyPort(msg.port));
       return false;
     }
-    if (msg.type === 'setToken') {
+    if (msg.type === "setToken") {
       respond(applyToken(msg.token));
       return false;
     }
-    if (msg.type === 'setEnrollment') {
+    if (msg.type === "setEnrollment") {
       // The popup owns the user-facing entry of the enrollment secret. Persist,
       // re-pair, reconnect — all inside connection.js. The onMessage listener is
       // NOT async, so we .then() and return true (Chrome keeps the respond()
@@ -64,38 +70,40 @@ export function registerEventListeners() {
       });
       return true; // async response — respond() fires from the .then()
     }
-    if (msg.type === 'unlockAll') {
+    if (msg.type === "unlockAll") {
       // Snapshot BEFORE unlockAll() — unlockAll clears the map, so reading after
       // would lose the list of tabs whose shields need removing.
       const prev = tabLocks.snapshot();
       tabLocks.unlockAll();
       persistSessionState();
       for (const { tabId } of prev) hideLockShield(tabId);
-      broadcastStatus('All tab locks cleared');
+      broadcastStatus("All tab locks cleared");
       respond({ success: true });
       return false;
     }
-    if (msg.type === 'lockTab') {
+    if (msg.type === "lockTab") {
       const owner = msg.sessionId;
       if (msg.tabId == null || !owner) {
-        respond({ success: false, error: 'tabId and sessionId required' });
+        respond({ success: false, error: "tabId and sessionId required" });
         return false;
       }
       // lockTabUi is async (it awaits the shield injection) — keep Chrome's
       // respond() channel open for the async reply.
       lockTabUi(msg.tabId, owner, `Tab ${msg.tabId} pinned to ${owner}`)
         .then((shielded) => respond({ success: true, shielded }))
-        .catch((err) => respond({ success: false, error: err?.message || String(err) }));
+        .catch((err) =>
+          respond({ success: false, error: err?.message || String(err) }),
+        );
       return true;
     }
-    if (msg.type === 'unlockTab') {
+    if (msg.type === "unlockTab") {
       // { tabId } — release one tab's lock (vs unlockAll which clears all).
       if (msg.tabId == null) {
-        respond({ success: false, error: 'tabId required' });
+        respond({ success: false, error: "tabId required" });
         return false;
       }
       const was = releaseTabUi(msg.tabId);
-      broadcastStatus(`Tab ${msg.tabId} unpinned (was ${was || '-'})`);
+      broadcastStatus(`Tab ${msg.tabId} unpinned (was ${was || "-"})`);
       respond({ success: true, previousSession: was || null });
       return false;
     }
@@ -106,12 +114,34 @@ export function registerEventListeners() {
     (details) => {
       if (details.tabId == null || details.tabId < 0) return; // not a real tab
       const buf = getTabBuffer(networkByTab, details.tabId);
-      pushCapped(buf, {
+      const entry = {
         method: details.method,
         url: details.url,
         status: details.statusCode,
         type: details.type,
         timestamp: details.timeStamp,
+      };
+      pushCapped(buf, entry);
+      // Intercept ledger enrichment (best-effort; never breaks capture).
+      try {
+        enrichCapture(details.tabId, entry);
+      } catch {}
+    },
+    { urls: ["<all_urls>"] },
+  );
+
+  // Requests that never completed (DNS failure, blocked, aborted, CORS…):
+  // onCompleted never fires for them, so without this they were invisible.
+  chrome.webRequest.onErrorOccurred.addListener(
+    (details) => {
+      if (details.tabId == null || details.tabId < 0) return;
+      const buf = getTabBuffer(networkByTab, details.tabId);
+      pushCapped(buf, {
+        method: details.method,
+        url: details.url,
+        error: details.error,
+        type: details.type,
+        timestamp: details.timeStamp,
       });
     },
     { urls: ['<all_urls>'] },
@@ -136,11 +166,11 @@ export function registerEventListeners() {
   // from the short-lived per-call listener inside handleNavigate — they share no
   // state and Chrome supports multiple onUpdated listeners (review NOTE 7c).
   chrome.tabs.onUpdated.addListener((tabId, changeInfo) => {
-    if (changeInfo.status === 'loading') {
+    if (changeInfo.status === "loading") {
       dropDocumentState(tabId);
       persistSessionState();
     }
-    if (changeInfo.status === 'complete' && tabLocks.owner(tabId)) {
+    if (changeInfo.status === "complete" && tabLocks.owner(tabId)) {
       showLockShield(tabId);
     }
   });