browserzap 0.6.1 → 0.8.0

package/bridge-server/native-host.js

@@ -22,11 +22,11 @@
  * closes or after a bounded wait with no request.
  */
 
-const { getOrCreateSecret } = require('./secret');
+const { getOrCreateSecret, configDir } = require('./secret');
 const { DEFAULT_PORT, PROTOCOL_VERSION, fileLogger } = require('./server');
 const { ensureBridge } = require('./ensure-bridge');
 const { helloProbe } = require('./probe');
-const { HOST_NAME, allowedOrigins } = require('./extension-id');
+const { HOST_NAME, allowedOrigins, allowedExtensionIds } = require('./extension-id');
 
 /** Inbound frames above this are rejected before parsing. Chrome's own host→Chrome cap is 1 MiB. */
 const MAX_MESSAGE_BYTES = 1024 * 1024;
@@ -139,11 +139,29 @@ async function handleRequest(request, options = {}) {
   return { type: 'hello', port, token, protocolVersion: PROTOCOL_VERSION };
 }
 
+/**
+ * Whether Chrome's reported caller origin may start this helper.
+ *
+ * Defense in depth: allowed_origins in the host manifest is the real control.
+ * Chrome may pass no origin at all, and anything that is not a
+ * chrome-extension:// origin is not ours to judge here. The set of extension
+ * ids comes from `dir` (store id only, plus the unpacked id after
+ * `browserzap setup --dev`), so it is the same answer `setup` wrote.
+ */
+function isAllowedOrigin(origin, { dir } = {}) {
+  if (typeof origin !== 'string' || !origin.startsWith('chrome-extension://')) return true;
+  try {
+    return allowedOrigins(allowedExtensionIds({ dir })).includes(origin);
+  } catch {
+    return false; // a config dir we cannot read allows nothing beyond the manifest
+  }
+}
+
 function main() {
   // Defense in depth: allowed_origins is the real control, but refuse a caller
   // that is not the BrowserZap extension if Chrome tells us who it is.
   const origin = process.argv[2];
-  if (typeof origin === 'string' && origin.startsWith('chrome-extension://') && !allowedOrigins().includes(origin)) {
+  if (!isAllowedOrigin(origin, { dir: configDir() })) {
     logLine('wrong_origin');
     process.exit(1);
   }
@@ -204,4 +222,5 @@ module.exports = {
   decodeMessage,
   handleRequest,
   configuredPort,
+  isAllowedOrigin,
 };

package/bridge-server/panel.js

@@ -73,9 +73,10 @@ function writeLastRuns(runs) {
  * @param {object} io
  * @param {(msg: object, socket: object, profile: string) => boolean} io.deliver  send an action for the panel session to that profile; false if it is not connected
  * @param {(msg: object, profile: string) => void} io.toExtension                  send a panel_event / cancel to that profile's extension
+ * @param {(session: string | null) => void} [io.onFeedback]                       a batch was saved for this session (null: any)
  * @param {(event: string, fields?: object) => void} [io.log]
  */
-function createPanelRunner({ deliver, toExtension, log = () => {} }) {
+function createPanelRunner({ deliver, toExtension, isSessionLive = () => true, onFeedback = () => {}, log = () => {} }) {
   const service = createWorkflowService({ log });
   const sessionLog = createSessionLog({ session: PANEL_SESSION, client: () => 'side panel' });
   let current = null;
@@ -438,9 +439,14 @@ function createPanelRunner({ deliver, toExtension, log = () => {} }) {
           return { ok: true, data: {} };
         case 'feedback_submit': {
           // Comment mode (docs/COMMENT_MODE.md): stored on this device for the agent's feedback_get.
-          const saved = feedback.saveBatch(args.batch);
-          log('feedback_saved', { batch: saved.id, comments: saved.count });
-          return { ok: true, data: { batchId: saved.id, count: saved.count } };
+          // Addressed to an agent that has gone? Then "any agent" (session null), never an id nobody can read.
+          const asked = args.batch && typeof args.batch.session === 'string' ? args.batch.session : null;
+          const live = asked ? isSessionLive(asked) : false;
+          const saved = feedback.saveBatch(live ? args.batch : { ...args.batch, session: null });
+          log('feedback_saved', { batch: saved.id, comments: saved.count, live });
+          // Wake a waiting feedback_wait now instead of on its next poll.
+          onFeedback(live ? asked : null);
+          return { ok: true, data: { batchId: saved.id, count: saved.count, session: live ? asked : null, live } };
         }
         default:
           return { ok: false, error: { code: 'INVALID_ARGUMENT', message: `Unknown panel request "${op}".` } };

package/bridge-server/probe.js

@@ -82,6 +82,61 @@ function helloProbe({ port, token, session, name, timeoutMs = 3000 }) {
   });
 }
 
+/**
+ * Ask the bridge which Chrome profiles are connected (`browserzap doctor`).
+ *
+ * Connects like helloProbe, then sends the bridge's own `profiles_list`
+ * request (answered by server.js with `{ type: 'bridge_reply', id, ok, data }`)
+ * and ends its session on close as helloProbe does, so no session lingers.
+ * Resolves { ok: true, profiles } or { ok: false, profiles: [] }. Never logs
+ * the token.
+ */
+function listProfiles({ port, token, session, name, timeoutMs = 2000 }) {
+  const requestId = 'doctor-profiles';
+  return new Promise((resolve) => {
+    const ws = new WebSocket(`ws://${BIND_HOST}:${port}`);
+    let settled = false;
+    const finish = (result, { gracefully = false } = {}) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        if (gracefully) ws.close();
+        else ws.terminate();
+      } catch { /* already closed */ }
+      resolve(result);
+    };
+    const timer = setTimeout(() => finish({ ok: false, profiles: [] }), timeoutMs);
+    ws.on('open', () => {
+      ws.send(JSON.stringify({ type: 'hello', role: 'agent', token: token ?? '', protocolVersion: PROTOCOL_VERSION, session, name }));
+    });
+    ws.on('message', (data) => {
+      let msg;
+      try {
+        msg = JSON.parse(String(data));
+      } catch {
+        return; // the timer covers a stuck handshake
+      }
+      if (msg.type === 'session_started') {
+        // Same rule as helloProbe: a probe's session ends with its socket.
+        const close = ws.close.bind(ws);
+        ws.close = (...closeArgs) => {
+          try { ws.send(JSON.stringify({ type: 'session_end', session: msg.session })); } catch { /* closing anyway */ }
+          close(...closeArgs);
+        };
+        ws.send(JSON.stringify({ type: 'profiles_list', id: requestId }));
+        return;
+      }
+      if (msg.type === 'bridge_reply' && msg.id === requestId) {
+        const profiles = msg.data?.profiles ?? msg.evidence?.profiles;
+        finish(Array.isArray(profiles) ? { ok: true, profiles } : { ok: false, profiles: [] }, { gracefully: true });
+      }
+    });
+    ws.on('close', () => finish({ ok: false, profiles: [] }));
+    ws.on('error', () => finish({ ok: false, profiles: [] }));
+  });
+}
+
 /** The protocol a refusing bridge says it speaks ("Version mismatch: this bridge speaks protocol 2, …"), or null. */
 function bridgeProtocolFrom(reason) {
   const m = /speaks protocol (\d+)/.exec(String(reason || ''));
@@ -121,4 +176,4 @@ async function stopBridgeOnPort(port) {
   return pids;
 }
 
-module.exports = { isListening, helloProbe, bridgeProtocolFrom, nodePidsOnPort, stopBridgeOnPort };
+module.exports = { isListening, helloProbe, listProfiles, bridgeProtocolFrom, nodePidsOnPort, stopBridgeOnPort };

package/bridge-server/profile-labels.js

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * Stable names for connected browser profiles, kept per extension install id.
+ *
+ * An unnamed profile gets "Profile N" once and keeps it across reconnects and bridge restarts; the number is
+ * never handed to another install. A rename changes only that install. Names live in `profiles.json` in the
+ * config folder (no page data, only id → label). Without a file (tests) they live in memory.
+ */
+
+const fs = require('fs');
+
+const MAX_ENTRIES = 50;
+
+function createProfileLabels(file = null) {
+  /** @type {Record<string, { label: string, custom: boolean, number?: number, seen: number }>} */
+  let entries = {};
+  if (file) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) entries = parsed;
+    } catch {
+      /* first run or unreadable: start empty */
+    }
+  }
+
+  function save() {
+    const ids = Object.keys(entries);
+    if (ids.length > MAX_ENTRIES) {
+      ids.sort((a, b) => entries[a].seen - entries[b].seen).slice(0, ids.length - MAX_ENTRIES).forEach((id) => delete entries[id]);
+    }
+    if (!file) return;
+    try {
+      fs.writeFileSync(file, JSON.stringify(entries, null, 2), { mode: 0o600 });
+    } catch {
+      /* names still work for this run */
+    }
+  }
+
+  function nextNumber() {
+    let max = 0;
+    for (const entry of Object.values(entries)) if (typeof entry.number === 'number' && entry.number > max) max = entry.number;
+    return max + 1;
+  }
+
+  return {
+    /** The name for an install that just connected: what it sent, else what it had, else a new "Profile N". */
+    connect(id, sentLabel) {
+      const entry = entries[id];
+      if (sentLabel) {
+        // A named install takes no number: "Profile N" counts unnamed ones. It keeps one it already had.
+        entries[id] = { ...entry, label: sentLabel, custom: true, seen: Date.now() };
+      } else if (entry) {
+        entry.seen = Date.now();
+      } else {
+        const number = nextNumber();
+        entries[id] = { label: `Profile ${number}`, custom: false, number, seen: Date.now() };
+      }
+      save();
+      return entries[id].label;
+    },
+    /** The person renamed this install; no other entry changes. */
+    rename(id, label) {
+      entries[id] = { ...entries[id], label, custom: true, seen: Date.now() };
+      save();
+      return label;
+    },
+    /** The person cleared the name: back to this install's own "Profile N". */
+    reset(id) {
+      const number = entries[id]?.number ?? nextNumber();
+      entries[id] = { label: `Profile ${number}`, custom: false, number, seen: Date.now() };
+      save();
+      return entries[id].label;
+    },
+    get(id) {
+      return entries[id]?.label ?? null;
+    },
+  };
+}
+
+module.exports = { createProfileLabels };

package/bridge-server/resolvers.js

@@ -12,7 +12,7 @@ const { LIMITS } = require('./limits');
  * step — so every wait and every retry still goes through the normal tool path
  * and extension policy.
  *
- * Design: docs/NEXT_RELEASE_SCOPE_0.6.md (§3 of the 0.5 doc);
+ * Design: docs/archive/NEXT_RELEASE_SCOPE_0.6.md (§3 of the 0.5 doc);
  * the wait kinds it relies on: docs/ADR/ADR-007-waiting-and-timeouts.md.
  *
  * Adding a resolver is one entry here plus a fixture that fails without it.

package/bridge-server/secret.js

@@ -3,7 +3,7 @@
  *
  * The bridge WebSocket is the only network listener in the system. Upstream
  * shipped it bound to 0.0.0.0 with no authentication at all (finding SEC-01 in
- * docs/REPOSITORY_AUDIT.md), which let any local or LAN process drive the
+ * docs/archive/REPOSITORY_AUDIT.md), which let any local or LAN process drive the
  * user's logged-in browser.
  *
  * BrowserZap closes that by requiring a shared secret on the first frame of every

package/bridge-server/server.js

@@ -9,7 +9,7 @@
  *
  * Derived from Open Browser Control (MIT, Copyright (c) 2026 smankoo) at commit
  * 4e6c262. Changes from upstream are marked "// BROWSERZAP:" and are summarised in
- * docs/PHASE_1_REPORT.md:
+ * docs/archive/PHASE_1_REPORT.md:
  *
  *   - the listener binds 127.0.0.1 only and refuses to run otherwise (SEC-01)
  *   - every connection must authenticate with the per-install secret before it
@@ -36,6 +36,8 @@ const { getOrCreateSecret, secretMatches, secretPath, configDir } = require('./s
 const pairing = require('./pairing');
 const { version: BRIDGE_VERSION } = require('../package.json');
 const { createPanelRunner } = require('./panel');
+const feedback = require('./feedback');
+const { createProfileLabels } = require('./profile-labels');
 const { LIMITS } = require('./limits');
 
 // ─── Constants ───────────────────────────────────────────────────────────────
@@ -74,7 +76,7 @@ const VALID_AGENT_ACTIONS = new Set([
   'status', 'inspect', 'navigate', 'click', 'fill', 'select_option', 'wait_for',
   'screenshot', 'press_key', 'scroll', 'pause', 'resume',
   'new_tab', 'list_tabs', 'switch_tab', 'close_tab', 'notify', 'upload',
-  'console', 'network',
+  'console', 'network', 'say',
 ]);
 
 const VALID_MESSAGE_TYPES = new Set([
@@ -108,6 +110,7 @@ function isValidMessage(msg) {
   }
   if (msg.type === 'cancel' && (typeof msg.id !== 'string' || !msg.id)) return false;
   if (msg.type === 'session_start' && typeof msg.name !== 'string') return false;
+  if (msg.type === 'session_update' && typeof msg.name !== 'string' && typeof msg.listening !== 'boolean' && !Number.isInteger(msg.chatTabId)) return false;
   return true;
 }
 
@@ -137,10 +140,13 @@ function isLoopbackAddress(address) {
  *                                  decision, not a convenience.
  * @param {string} [options.secret] Expected pairing secret. Defaults to the on-disk secret.
  * @param {(msg: string) => void} [options.log]
+ * @param {object} [options.limits] Test seam only: timer values to use instead of `limits.js`. The E2E
+ *                                  harness shortens the session grace period; no shipped build passes this.
  */
 function createBridgeServer(options = {}) {
   const port = options.port ?? DEFAULT_PORT;
   const host = options.host ?? BIND_HOST;
+  const limits = options.limits ?? LIMITS;
   const expectedSecret = options.secret ?? getOrCreateSecret();
   const log = options.log ?? ((msg) => process.stderr.write(`[browserzap-bridge] ${msg}\n`));
 
@@ -157,13 +163,21 @@ function createBridgeServer(options = {}) {
    * Connected browser profiles. Every Chrome profile has its own copy of the
    * extension (its own instance id, tabs and logins), and each may connect
    * once (multi-profile, docs/MULTI_PROFILE.md). The same install reconnecting
-   * replaces its own socket.
-   * @type {Map<string, { ws: WebSocket, browser: string, label: string, connectedAt: number }>}
+   * replaces its own socket. `extensionVersion` is what the extension reported
+   * in its hello (WP5); null when it is older and reports nothing.
+   * `extensionId` is the Chrome extension id: two different ids connected at
+   * once mean two different builds (store + developer), not one profile each (B-05).
+   * @type {Map<string, { ws: WebSocket, browser: string, label: string, connectedAt: number, extensionVersion: string | null, extensionId: string | null }>}
    */
   const profiles = new Map();
   /** @type {Map<WebSocket, string>} */
   const socketToProfile = new Map();
   let anonymousProfiles = 0;
+  // Names per install id, kept on disk so a restart never renumbers profiles (B-05, 0.8 public).
+  // Tests that pass their own secret keep names in memory unless they name a file.
+  const labels = createProfileLabels(options.profileLabelsFile !== undefined
+    ? options.profileLabelsFile
+    : (options.secret ? null : path.join(configDir(), 'profiles.json')));
 
   /**
    * Agent sessions. `profile` is the browser profile the session acts in: set
@@ -183,8 +197,21 @@ function createBridgeServer(options = {}) {
   };
   const profileList = (selected) => [...profiles.entries()].map(([id, p]) => ({
     id, label: p.label, browser: p.browser, connectedAt: new Date(p.connectedAt).toISOString(), selected: id === selected,
+    // What the build said in its hello; null for a build older than 0.7.0 / 0.8.0.
+    extensionVersion: p.extensionVersion ?? null,
+    extensionId: p.extensionId ?? null,
   }));
 
+  /**
+   * The extension view of the connected profiles, sent on every change so each
+   * side panel can warn when two different builds run at once (B-05). An older
+   * extension ignores the event, which is why it is additive.
+   */
+  function broadcastProfiles() {
+    const data = { profiles: profileList(null) };
+    for (const p of profiles.values()) safeSend(p.ws, { type: 'event', event: 'profiles', data });
+  }
+
   // The side panel's workflow runner: a built-in session that drives the
   // extension like an agent would, so every step gets the same checks. A run
   // acts in the profile whose side panel started it.
@@ -196,6 +223,19 @@ function createBridgeServer(options = {}) {
       return true;
     },
     toExtension: (msg, profile) => sendTo(profileSocket(profile), msg),
+    // Whether a named session still has a live socket: a message addressed to an agent that has gone is stored
+    // as "any agent" instead of being unreadable for ever (feedback.releaseOrphans).
+    isSessionLive: (id) => {
+      const session = agentSessions.get(id);
+      return Boolean(session && (session.builtIn || session.ws));
+    },
+    // A message was stored: tell the agent it is for (or every agent, when unaddressed) so a feedback_wait returns at
+    // once. Only a nudge; the agent still reads the batch from the folder, and an older MCP server ignores the event.
+    onFeedback: (session) => {
+      for (const [id, s] of agentSessions) {
+        if (!s.builtIn && s.ws && (!session || id === session)) safeSend(s.ws, { type: 'event', event: 'feedback_new' });
+      }
+    },
     log: (event, fields) => log(`panel ${event}${fields ? ` ${JSON.stringify(fields)}` : ''}`),
   });
   if (panel) agentSessions.set(panel.session, { ws: panel.socket, name: panel.sessionName, profile: null, builtIn: true });
@@ -431,9 +471,11 @@ function createBridgeServer(options = {}) {
         if (msg.type === 'profile_update') {
           const label = sanitizeSessionName(msg.label);
           const p = profiles.get(fromProfile);
-          if (p && label) {
-            p.label = label;
-            log(`Profile renamed to "${label}"`);
+          if (p) {
+            // An empty name gives this install back its own "Profile N"; no other profile changes.
+            p.label = label ? labels.rename(fromProfile, label) : labels.reset(fromProfile);
+            log(`Profile renamed to "${p.label}"`);
+            broadcastProfiles();
           }
           return;
         }
@@ -467,13 +509,19 @@ function createBridgeServer(options = {}) {
       if (msg.type === 'session_update') {
         const session = agentSessions.get(sessionId);
         const name = sanitizeSessionName(msg.name);
-        if (session && name) {
+        const listening = typeof msg.listening === 'boolean' ? msg.listening : undefined;
+        // The tab a reply belongs to when the agent read a message from a tab no session owned (updateChatTab).
+        const chatTabId = Number.isInteger(msg.chatTabId) && msg.chatTabId >= 0 ? msg.chatTabId : undefined;
+        if (!session || (!name && listening === undefined && chatTabId === undefined)) return;
+        if (name) {
           session.name = name;
-          msg.name = name;
           log(`Agent "${session.name}" renamed (session: ${sessionId})`);
-        } else {
-          return;
         }
+        // Only these fields reach the extension.
+        for (const key of Object.keys(msg)) if (!['type', 'session'].includes(key)) delete msg[key];
+        if (name) msg.name = name;
+        if (listening !== undefined) msg.listening = listening;
+        if (chatTabId !== undefined) msg.chatTabId = chatTabId;
       }
       // The bridge, not the agent, decides which session a message belongs to.
       msg.session = sessionId;
@@ -524,6 +572,7 @@ function createBridgeServer(options = {}) {
         if (profiles.get(profileId)?.ws === ws) {
           log(`Browser profile "${profiles.get(profileId).label}" disconnected`);
           profiles.delete(profileId);
+          broadcastProfiles();
         }
         return;
       }
@@ -535,11 +584,11 @@ function createBridgeServer(options = {}) {
         // The connection dropped without a goodbye: the agent may come back with
         // the same session id (a restart, a blip), so its tabs wait
         // SESSION_GRACE_MS before the session ends (D-38).
-        log(`Agent "${session.name}" disconnected (session: ${sessionId}); ending it in ${LIMITS.SESSION_GRACE_MS / 1000} s unless it reconnects`);
+        log(`Agent "${session.name}" disconnected (session: ${sessionId}); ending it in ${limits.SESSION_GRACE_MS / 1000} s unless it reconnects`);
         session.ws = null;
         session.graceTimer = setTimeout(() => {
           if (agentSessions.get(sessionId) === session && !session.ws) endAgentSession(sessionId);
-        }, LIMITS.SESSION_GRACE_MS);
+        }, limits.SESSION_GRACE_MS);
       }
     });
 
@@ -552,17 +601,31 @@ function createBridgeServer(options = {}) {
     // came from auto-pairing or from a pasted token (ADR-009).
     pairing.recordPairing(id);
     const browser = typeof hello.browser === 'string' ? hello.browser : 'unknown';
+    // Additive hello field (WP5): a build older than 0.7.0 sends nothing, which
+    // is accepted as it always was. A reconnect that omits it keeps the version
+    // this profile reported before.
+    const extensionVersion = typeof hello.extensionVersion === 'string' && hello.extensionVersion ? hello.extensionVersion.slice(0, 32) : null;
+    // Which build this is. Additive: a pre-0.8 extension sends nothing.
+    const extensionId = typeof hello.extensionId === 'string' && /^[a-p]{32}$/.test(hello.extensionId) ? hello.extensionId : null;
     const existing = profiles.get(id);
     if (existing && existing.ws !== ws && existing.ws.readyState === WebSocket.OPEN) {
       log('Browser profile reconnected (replacing old connection)');
       existing.ws.close(CLOSE_REPLACED, 'Replaced by new extension connection');
     }
-    const label = sanitizeSessionName(hello.label) ?? existing?.label ?? `Profile ${profiles.size + (existing ? 0 : 1)}`;
-    profiles.set(id, { ws, browser, label, connectedAt: Date.now() });
+    const label = labels.connect(id, sanitizeSessionName(hello.label));
+    profiles.set(id, {
+      ws, browser, label, connectedAt: Date.now(),
+      extensionVersion: extensionVersion ?? existing?.extensionVersion ?? null,
+      extensionId: extensionId ?? existing?.extensionId ?? null,
+    });
     socketToProfile.set(ws, id);
     log(`Browser profile "${label}" connected (${browser}, ${id.slice(0, 8)}); ${profiles.size} connected`);
 
-    safeSend(ws, { type: 'event', event: 'connected', data: { protocolVersion: PROTOCOL_VERSION, profile: { id, label }, profiles: profiles.size } });
+    safeSend(ws, {
+      type: 'event', event: 'connected',
+      data: { protocolVersion: PROTOCOL_VERSION, profile: { id, label }, profiles: profiles.size, profilesList: profileList(id) },
+    });
+    broadcastProfiles();
 
     // The built-in panel session exists in every profile; agent sessions only in the one they act in.
     for (const [sessionId, session] of agentSessions) {
@@ -581,6 +644,9 @@ function createBridgeServer(options = {}) {
     agentSessions.delete(sessionId);
     if (session.ws) socketToSession.delete(session.ws);
     log(`Agent "${session.name}" ended (session: ${sessionId})`);
+    // Anything the person sent to this agent and it never read is given back to "any agent" (feedback.releaseOrphans).
+    const released = feedback.releaseOrphans({ session: sessionId, liveSessionIds: new Set(agentSessions.keys()) });
+    if (released) log(`Released ${released} unread message(s) from "${session.name}"`);
     sendTo(profileSocket(session.profile), { type: 'session_end', session: sessionId });
   }
 
@@ -621,6 +687,15 @@ function createBridgeServer(options = {}) {
 
   // ─── Lifecycle ─────────────────────────────────────────────────────────────
 
+  // A killed bridge leaves messages addressed to sessions that no longer exist. No agent is live at start, so
+  // every undelivered stamp is released and the next agent to ask can read it (feedback.releaseOrphans).
+  try {
+    const swept = feedback.releaseOrphans({ liveSessionIds: new Set() });
+    if (swept) log(`Released ${swept} unread message(s) left by a previous run`);
+  } catch (err) {
+    log(`Could not release old messages: ${err.message}`);
+  }
+
   // Resolves once the listener is bound (or fails), so callers/tests do not race.
   const ready = new Promise((resolve, reject) => {
     wss.once('listening', () => {