browserzap 0.4.0 → 0.5.5

package/bridge-server/screenshots.js

@@ -1,130 +1,130 @@
-/**
- * BrowserZap — screenshots kept on this device, with retention (docs/AUDIT.md AU-18).
- *
- * A screenshot is an image of the user's own page (mail, banking, admin
- * screens), so it never leaves the machine and is not kept forever:
- *
- *   <config dir>/screenshots/screenshot-<time>-<id>.jpg   (folder 0700, files 0600)
- *
- *   - kept BROWSERZAP_SCREENSHOT_DAYS days (default 7, 0 = deleted when the MCP
- *     server exits) and at most MAX_FILES files; the oldest go first
- *   - pruned when the MCP server starts and after each new screenshot
- *   - the per-session %TEMP%\browserzap-screenshots-* folders that releases up
- *     to 0.3.0 left behind are cleaned with the same retention
- *
- * `node bridge-server/index.js --screenshots` shows the folder and what it holds.
- */
-
-'use strict';
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const crypto = require('crypto');
-
-const { configDir } = require('./secret');
-
-const DEFAULT_KEEP_DAYS = 7;
-const MAX_FILES = 200;
-const LEGACY_PREFIX = 'browserzap-screenshots-';
-const FILE_RE = /^screenshot-\d+-[0-9a-f]{8}\.(jpg|png)$/;
-
-const screenshotDir = () => path.join(configDir(), 'screenshots');
-
-/** Days to keep screenshots: BROWSERZAP_SCREENSHOT_DAYS (0–365), default 7. */
-function keepDays() {
-  const raw = process.env.BROWSERZAP_SCREENSHOT_DAYS;
-  if (raw === undefined || raw === '') return DEFAULT_KEEP_DAYS;
-  const n = Number(raw);
-  return Number.isFinite(n) && n >= 0 && n <= 365 ? n : DEFAULT_KEEP_DAYS;
-}
-
-function listShots(dir) {
-  try {
-    return fs.readdirSync(dir)
-      .filter((f) => FILE_RE.test(f))
-      .map((f) => {
-        const file = path.join(dir, f);
-        try {
-          return { file, mtime: fs.statSync(file).mtimeMs };
-        } catch {
-          return null;
-        }
-      })
-      .filter(Boolean)
-      .sort((a, b) => a.mtime - b.mtime);
-  } catch {
-    return [];
-  }
-}
-
-function remove(file) {
-  try {
-    fs.unlinkSync(file);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Delete screenshots older than the retention, and the oldest beyond MAX_FILES.
- * Never throws. Returns how many files were removed.
- */
-function prune({ now = Date.now(), days = keepDays(), legacy = true } = {}) {
-  const cutoff = now - days * 86_400_000;
-  let removed = 0;
-  const shots = listShots(screenshotDir());
-  const keep = [];
-  for (const shot of shots) {
-    if (shot.mtime < cutoff && remove(shot.file)) removed++;
-    else keep.push(shot);
-  }
-  while (keep.length > MAX_FILES) if (remove(keep.shift().file)) removed++;
-
-  if (legacy) {
-    let entries = [];
-    try {
-      entries = fs.readdirSync(os.tmpdir()).filter((d) => d.startsWith(LEGACY_PREFIX));
-    } catch { /* no temp listing */ }
-    for (const name of entries) {
-      const dir = path.join(os.tmpdir(), name);
-      for (const shot of listShots(dir)) if (shot.mtime < cutoff && remove(shot.file)) removed++;
-      try {
-        if (fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
-      } catch { /* in use or gone */ }
-    }
-  }
-  return removed;
-}
-
-/** Write one screenshot and return its path. */
-function save(base64Data, format) {
-  const dir = screenshotDir();
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const filename = `screenshot-${Date.now()}-${crypto.randomUUID().slice(0, 8)}.${format === 'jpeg' ? 'jpg' : 'png'}`;
-  const file = path.join(dir, filename);
-  fs.writeFileSync(file, Buffer.from(base64Data, 'base64'), { mode: 0o600 });
-  // With 0 days the files live until the MCP server exits (pruneOnExit).
-  if (keepDays() > 0) prune({ legacy: false });
-  return file;
-}
-
-/** What the folder holds, for --screenshots and browser_status. */
-function summary() {
-  const shots = listShots(screenshotDir());
-  let bytes = 0;
-  for (const s of shots) {
-    try {
-      bytes += fs.statSync(s.file).size;
-    } catch { /* gone */ }
-  }
-  return { folder: screenshotDir(), files: shots.length, bytes, keepDays: keepDays(), maxFiles: MAX_FILES };
-}
-
-/** With BROWSERZAP_SCREENSHOT_DAYS=0, delete every screenshot when the MCP server exits. */
-function pruneOnExit() {
-  if (keepDays() === 0) prune({ days: 0, now: Date.now() + 1000, legacy: false });
-}
-
-module.exports = { save, prune, pruneOnExit, summary, screenshotDir, keepDays, MAX_FILES };
+/**
+ * BrowserZap — screenshots kept on this device, with retention (docs/AUDIT.md AU-18).
+ *
+ * A screenshot is an image of the user's own page (mail, banking, admin
+ * screens), so it never leaves the machine and is not kept forever:
+ *
+ *   <config dir>/screenshots/screenshot-<time>-<id>.jpg   (folder 0700, files 0600)
+ *
+ *   - kept BROWSERZAP_SCREENSHOT_DAYS days (default 7, 0 = deleted when the MCP
+ *     server exits) and at most MAX_FILES files; the oldest go first
+ *   - pruned when the MCP server starts and after each new screenshot
+ *   - the per-session %TEMP%\browserzap-screenshots-* folders that releases up
+ *     to 0.3.0 left behind are cleaned with the same retention
+ *
+ * `node bridge-server/index.js --screenshots` shows the folder and what it holds.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const { configDir } = require('./secret');
+
+const DEFAULT_KEEP_DAYS = 7;
+const MAX_FILES = 200;
+const LEGACY_PREFIX = 'browserzap-screenshots-';
+const FILE_RE = /^screenshot-\d+-[0-9a-f]{8}\.(jpg|png)$/;
+
+const screenshotDir = () => path.join(configDir(), 'screenshots');
+
+/** Days to keep screenshots: BROWSERZAP_SCREENSHOT_DAYS (0–365), default 7. */
+function keepDays() {
+  const raw = process.env.BROWSERZAP_SCREENSHOT_DAYS;
+  if (raw === undefined || raw === '') return DEFAULT_KEEP_DAYS;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 && n <= 365 ? n : DEFAULT_KEEP_DAYS;
+}
+
+function listShots(dir) {
+  try {
+    return fs.readdirSync(dir)
+      .filter((f) => FILE_RE.test(f))
+      .map((f) => {
+        const file = path.join(dir, f);
+        try {
+          return { file, mtime: fs.statSync(file).mtimeMs };
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean)
+      .sort((a, b) => a.mtime - b.mtime);
+  } catch {
+    return [];
+  }
+}
+
+function remove(file) {
+  try {
+    fs.unlinkSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Delete screenshots older than the retention, and the oldest beyond MAX_FILES.
+ * Never throws. Returns how many files were removed.
+ */
+function prune({ now = Date.now(), days = keepDays(), legacy = true } = {}) {
+  const cutoff = now - days * 86_400_000;
+  let removed = 0;
+  const shots = listShots(screenshotDir());
+  const keep = [];
+  for (const shot of shots) {
+    if (shot.mtime < cutoff && remove(shot.file)) removed++;
+    else keep.push(shot);
+  }
+  while (keep.length > MAX_FILES) if (remove(keep.shift().file)) removed++;
+
+  if (legacy) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(os.tmpdir()).filter((d) => d.startsWith(LEGACY_PREFIX));
+    } catch { /* no temp listing */ }
+    for (const name of entries) {
+      const dir = path.join(os.tmpdir(), name);
+      for (const shot of listShots(dir)) if (shot.mtime < cutoff && remove(shot.file)) removed++;
+      try {
+        if (fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
+      } catch { /* in use or gone */ }
+    }
+  }
+  return removed;
+}
+
+/** Write one screenshot and return its path. */
+function save(base64Data, format) {
+  const dir = screenshotDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const filename = `screenshot-${Date.now()}-${crypto.randomUUID().slice(0, 8)}.${format === 'jpeg' ? 'jpg' : 'png'}`;
+  const file = path.join(dir, filename);
+  fs.writeFileSync(file, Buffer.from(base64Data, 'base64'), { mode: 0o600 });
+  // With 0 days the files live until the MCP server exits (pruneOnExit).
+  if (keepDays() > 0) prune({ legacy: false });
+  return file;
+}
+
+/** What the folder holds, for --screenshots and browser_status. */
+function summary() {
+  const shots = listShots(screenshotDir());
+  let bytes = 0;
+  for (const s of shots) {
+    try {
+      bytes += fs.statSync(s.file).size;
+    } catch { /* gone */ }
+  }
+  return { folder: screenshotDir(), files: shots.length, bytes, keepDays: keepDays(), maxFiles: MAX_FILES };
+}
+
+/** With BROWSERZAP_SCREENSHOT_DAYS=0, delete every screenshot when the MCP server exits. */
+function pruneOnExit() {
+  if (keepDays() === 0) prune({ days: 0, now: Date.now() + 1000, legacy: false });
+}
+
+module.exports = { save, prune, pruneOnExit, summary, screenshotDir, keepDays, MAX_FILES };

package/bridge-server/secret.js

@@ -1,127 +1,127 @@
-/**
- * BrowserZap — per-install bridge secret.
- *
- * 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
- * user's logged-in browser.
- *
- * BrowserZap closes that by requiring a shared secret on the first frame of every
- * connection. This module owns generation, storage and comparison of that
- * secret.
- *
- * Storage location:
- *   Windows: %LOCALAPPDATA%\BrowserZap\bridge-secret
- *   other:   $XDG_CONFIG_HOME/BrowserZap/bridge-secret  (default ~/.config/BrowserZap)
- *   override: $BROWSERZAP_HOME
- *
- * The secret never leaves the machine and is never logged.
- */
-
-'use strict';
-
-const crypto = require('crypto');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-const SECRET_BYTES = 32;
-const SECRET_FILENAME = 'bridge-secret';
-
-/** Before 0.3.0 the product was called Browsio and kept its files under this folder name. */
-const LEGACY_DIR_NAME = 'Browsio';
-let legacyChecked = false;
-
-function configDir() {
-  if (process.env.BROWSERZAP_HOME) return process.env.BROWSERZAP_HOME;
-  const base = process.platform === 'win32'
-    ? process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local')
-    : process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
-  const dir = path.join(base, 'BrowserZap');
-  if (!legacyChecked) {
-    legacyChecked = true;
-    migrateLegacyDir(path.join(base, LEGACY_DIR_NAME), dir);
-  }
-  return dir;
-}
-
-/**
- * One-time move of the pre-rename folder, so an existing install keeps its
- * pairing (the extension already holds this secret), workflows and licence.
- * Never overwrites: if the new folder exists, the old one is left alone.
- */
-function migrateLegacyDir(legacy, dir) {
-  try {
-    if (fs.existsSync(dir) || !fs.existsSync(legacy)) return;
-    fs.renameSync(legacy, dir);
-  } catch {
-    // Folder in use or not movable: start fresh; re-pairing is documented.
-  }
-}
-
-function secretPath() {
-  return path.join(configDir(), SECRET_FILENAME);
-}
-
-/**
- * Read the existing secret, or null if none has been created yet.
- * Never creates anything — reading is side-effect free.
- */
-function readSecret() {
-  try {
-    const value = fs.readFileSync(secretPath(), 'utf8').trim();
-    return value.length > 0 ? value : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Read the secret, creating it on first use.
- *
- * The file is written with mode 0600. On Windows the POSIX mode is largely
- * advisory — the file inherits the user's profile ACL, which is already
- * user-scoped under %LOCALAPPDATA%. Documented in docs/SECURITY.md.
- */
-function getOrCreateSecret() {
-  const existing = readSecret();
-  if (existing) return existing;
-
-  const dir = configDir();
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-
-  const secret = crypto.randomBytes(SECRET_BYTES).toString('hex');
-  const file = secretPath();
-
-  // 'wx' fails if the file appeared between our read and write, so two racing
-  // processes cannot end up with different secrets.
-  try {
-    fs.writeFileSync(file, secret + '\n', { mode: 0o600, flag: 'wx' });
-  } catch (err) {
-    if (err.code === 'EEXIST') {
-      const raced = readSecret();
-      if (raced) return raced;
-    }
-    throw err;
-  }
-
-  return secret;
-}
-
-/** Constant-time comparison. Length is compared first (crypto requires equal lengths). */
-function secretMatches(provided, expected) {
-  if (typeof provided !== 'string' || typeof expected !== 'string') return false;
-  const a = Buffer.from(provided, 'utf8');
-  const b = Buffer.from(expected, 'utf8');
-  if (a.length !== b.length) return false;
-  return crypto.timingSafeEqual(a, b);
-}
-
-module.exports = {
-  SECRET_BYTES,
-  configDir,
-  secretPath,
-  readSecret,
-  getOrCreateSecret,
-  secretMatches,
-};
+/**
+ * BrowserZap — per-install bridge secret.
+ *
+ * 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
+ * user's logged-in browser.
+ *
+ * BrowserZap closes that by requiring a shared secret on the first frame of every
+ * connection. This module owns generation, storage and comparison of that
+ * secret.
+ *
+ * Storage location:
+ *   Windows: %LOCALAPPDATA%\BrowserZap\bridge-secret
+ *   other:   $XDG_CONFIG_HOME/BrowserZap/bridge-secret  (default ~/.config/BrowserZap)
+ *   override: $BROWSERZAP_HOME
+ *
+ * The secret never leaves the machine and is never logged.
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SECRET_BYTES = 32;
+const SECRET_FILENAME = 'bridge-secret';
+
+/** Before 0.3.0 the product was called Browsio and kept its files under this folder name. */
+const LEGACY_DIR_NAME = 'Browsio';
+let legacyChecked = false;
+
+function configDir() {
+  if (process.env.BROWSERZAP_HOME) return process.env.BROWSERZAP_HOME;
+  const base = process.platform === 'win32'
+    ? process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local')
+    : process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  const dir = path.join(base, 'BrowserZap');
+  if (!legacyChecked) {
+    legacyChecked = true;
+    migrateLegacyDir(path.join(base, LEGACY_DIR_NAME), dir);
+  }
+  return dir;
+}
+
+/**
+ * One-time move of the pre-rename folder, so an existing install keeps its
+ * pairing (the extension already holds this secret), workflows and licence.
+ * Never overwrites: if the new folder exists, the old one is left alone.
+ */
+function migrateLegacyDir(legacy, dir) {
+  try {
+    if (fs.existsSync(dir) || !fs.existsSync(legacy)) return;
+    fs.renameSync(legacy, dir);
+  } catch {
+    // Folder in use or not movable: start fresh; re-pairing is documented.
+  }
+}
+
+function secretPath() {
+  return path.join(configDir(), SECRET_FILENAME);
+}
+
+/**
+ * Read the existing secret, or null if none has been created yet.
+ * Never creates anything — reading is side-effect free.
+ */
+function readSecret() {
+  try {
+    const value = fs.readFileSync(secretPath(), 'utf8').trim();
+    return value.length > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the secret, creating it on first use.
+ *
+ * The file is written with mode 0600. On Windows the POSIX mode is largely
+ * advisory — the file inherits the user's profile ACL, which is already
+ * user-scoped under %LOCALAPPDATA%. Documented in docs/SECURITY.md.
+ */
+function getOrCreateSecret() {
+  const existing = readSecret();
+  if (existing) return existing;
+
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  const secret = crypto.randomBytes(SECRET_BYTES).toString('hex');
+  const file = secretPath();
+
+  // 'wx' fails if the file appeared between our read and write, so two racing
+  // processes cannot end up with different secrets.
+  try {
+    fs.writeFileSync(file, secret + '\n', { mode: 0o600, flag: 'wx' });
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      const raced = readSecret();
+      if (raced) return raced;
+    }
+    throw err;
+  }
+
+  return secret;
+}
+
+/** Constant-time comparison. Length is compared first (crypto requires equal lengths). */
+function secretMatches(provided, expected) {
+  if (typeof provided !== 'string' || typeof expected !== 'string') return false;
+  const a = Buffer.from(provided, 'utf8');
+  const b = Buffer.from(expected, 'utf8');
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+
+module.exports = {
+  SECRET_BYTES,
+  configDir,
+  secretPath,
+  readSecret,
+  getOrCreateSecret,
+  secretMatches,
+};

package/bridge-server/server.js

@@ -36,6 +36,7 @@ const { getOrCreateSecret, secretMatches, secretPath, configDir } = require('./s
 const pairing = require('./pairing');
 const { version: BRIDGE_VERSION } = require('../package.json');
 const { createPanelRunner } = require('./panel');
+const { LIMITS } = require('./limits');
 
 // ─── Constants ───────────────────────────────────────────────────────────────
 
@@ -72,7 +73,8 @@ const MAX_EXTENSION_MESSAGES_PER_SECOND = 500;
 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', 'notify',
+  'new_tab', 'list_tabs', 'switch_tab', 'close_tab', 'notify', 'upload',
+  'console', 'network',
 ]);
 
 const VALID_MESSAGE_TYPES = new Set([
@@ -168,7 +170,8 @@ function createBridgeServer(options = {}) {
    * by browser_select_profile, or automatically on the first action while
    * exactly one profile is connected. It never changes by itself, so a session
    * cannot drift into another account.
-   * @type {Map<string, { ws: WebSocket, name: string, profile: string | null, builtIn?: boolean }>}
+   * `ws` is null while a dropped session waits out its grace period (`graceTimer`).
+   * @type {Map<string, { ws: WebSocket | null, name: string, profile: string | null, builtIn?: boolean, graceTimer?: NodeJS.Timeout }>}
    */
   const agentSessions = new Map();
   /** @type {Map<WebSocket, string>} */
@@ -438,7 +441,7 @@ function createBridgeServer(options = {}) {
         const targetSession = msg.session;
         if (targetSession && agentSessions.has(targetSession)) {
           const agent = agentSessions.get(targetSession);
-          if (agent.ws.readyState === WebSocket.OPEN) {
+          if (agent.ws && agent.ws.readyState === WebSocket.OPEN) {
             agent.ws.send(data.toString());
           }
         }
@@ -455,6 +458,12 @@ function createBridgeServer(options = {}) {
         return;
       }
 
+      // A clean exit: end the session now rather than after the grace period.
+      if (msg.type === 'session_end') {
+        endAgentSession(sessionId);
+        return;
+      }
+
       if (msg.type === 'session_update') {
         const session = agentSessions.get(sessionId);
         const name = sanitizeSessionName(msg.name);
@@ -520,11 +529,17 @@ function createBridgeServer(options = {}) {
       }
       const sessionId = socketToSession.get(ws);
       if (sessionId) {
-        const session = agentSessions.get(sessionId);
-        log(`Agent "${session?.name}" disconnected (session: ${sessionId})`);
-        agentSessions.delete(sessionId);
         socketToSession.delete(ws);
-        sendTo(profileSocket(session?.profile), { type: 'session_end', session: sessionId });
+        const session = agentSessions.get(sessionId);
+        if (!session) return;
+        // 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`);
+        session.ws = null;
+        session.graceTimer = setTimeout(() => {
+          if (agentSessions.get(sessionId) === session && !session.ws) endAgentSession(sessionId);
+        }, LIMITS.SESSION_GRACE_MS);
       }
     });
 
@@ -558,7 +573,29 @@ function createBridgeServer(options = {}) {
     return true;
   }
 
+  /** The agent said goodbye, or its grace period ran out: end the session, and with it its tabs. */
+  function endAgentSession(sessionId) {
+    const session = agentSessions.get(sessionId);
+    if (!session) return;
+    clearTimeout(session.graceTimer);
+    agentSessions.delete(sessionId);
+    if (session.ws) socketToSession.delete(session.ws);
+    log(`Agent "${session.name}" ended (session: ${sessionId})`);
+    sendTo(profileSocket(session.profile), { type: 'session_end', session: sessionId });
+  }
+
   function acceptAgent(ws, hello) {
+    // The same session reconnecting within its grace period keeps its profile and tabs.
+    const orphan = typeof hello.session === 'string' ? agentSessions.get(hello.session) : undefined;
+    if (orphan && !orphan.builtIn && orphan.ws === null) {
+      clearTimeout(orphan.graceTimer);
+      orphan.ws = ws;
+      socketToSession.set(ws, hello.session);
+      log(`Agent "${orphan.name}" reconnected (session: ${hello.session})`);
+      if (!orphan.profile && profiles.size === 1) bindSession(hello.session, [...profiles.keys()][0]);
+      safeSend(ws, { type: 'session_started', session: hello.session, name: orphan.name, bridgeVersion: BRIDGE_VERSION, profiles: profiles.size });
+      return;
+    }
     const requested = typeof hello.session === 'string' && SESSION_ID_RE.test(hello.session) && !agentSessions.has(hello.session)
       ? hello.session
       : null;
@@ -618,6 +655,7 @@ function createBridgeServer(options = {}) {
 
   async function close() {
     clearInterval(reaper);
+    for (const session of agentSessions.values()) clearTimeout(session.graceTimer);
     panel?.close();
     for (const client of wss.clients) {
       try { client.close(1001, 'server-shutdown'); } catch { /* best effort */ }