@monoes/monobrowse 1.0.2 → 1.0.4

package/src/__tests__/batch-eval-parsing.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { parseBatchCommandLine } from '../cli/commands.js';
+
+describe('parseBatchCommandLine — eval expressions inside a batch command string', () => {
+  it('does not strip string-literal quotes from a raw JS expression passed to eval', () => {
+    // Regression: tokenizeBatchCommand's shell-style quote-stripping (correct for
+    // space-separated args like `fill @e1 "some value"`) previously ran on eval's
+    // expression too, silently deleting the expression's OWN string-literal quotes
+    // and turning `document.querySelector('a')` into `document.querySelector(a)` —
+    // a reference to an undefined identifier instead of a string literal.
+    const input = "eval document.querySelector('meta[name=mm-token]').content";
+    const { subName, subArgs } = parseBatchCommandLine(input);
+    expect(subName).toBe('eval');
+    expect(subArgs).toEqual(["document.querySelector('meta[name=mm-token]').content"]);
+  });
+
+  it('preserves double-quoted string literals in the expression too', () => {
+    const input = 'eval document.querySelector("body").tagName';
+    const { subName, subArgs } = parseBatchCommandLine(input);
+    expect(subName).toBe('eval');
+    expect(subArgs).toEqual(['document.querySelector("body").tagName']);
+  });
+
+  it('preserves an expression with multiple quoted segments and internal spaces', () => {
+    const input = "eval [...document.querySelectorAll('li')].map(x => x.textContent.trim())";
+    const { subName, subArgs } = parseBatchCommandLine(input);
+    expect(subName).toBe('eval');
+    expect(subArgs).toEqual(["[...document.querySelectorAll('li')].map(x => x.textContent.trim())"]);
+  });
+
+  it('still recognizes --json and --max-output flags placed before the expression', () => {
+    const input = "eval --json --max-output 100 document.querySelector('a').href";
+    const { subName, subArgs, flags } = parseBatchCommandLine(input);
+    expect(subName).toBe('eval');
+    expect(flags).toMatchObject({ json: true, 'max-output': 100 });
+    expect(subArgs).toEqual(["document.querySelector('a').href"]);
+  });
+
+  it('leaves non-eval commands tokenized exactly as before (no behavior change)', () => {
+    const input = 'fill @e1 "some value with spaces"';
+    const { subName, subArgs } = parseBatchCommandLine(input);
+    expect(subName).toBe('fill');
+    expect(subArgs).toEqual(['@e1', 'some value with spaces']);
+  });
+
+  it('leaves a simple multi-token command tokenized exactly as before', () => {
+    const input = 'open https://example.com --port 9333';
+    const { subName, subArgs } = parseBatchCommandLine(input);
+    expect(subName).toBe('open');
+    expect(subArgs).toEqual(['https://example.com', '--port', '9333']);
+  });
+});

package/src/__tests__/output.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+// The module exports a singleton `output` which reads process.stdout.isTTY at
+// construction time. We need to control that, so we reset modules per test.
+
+async function importOutput(isTTY: boolean) {
+  vi.resetModules();
+  // Stub isTTY before the module loads
+  Object.defineProperty(process.stdout, 'isTTY', { value: isTTY, configurable: true });
+  return import('../cli/output.js');
+}
+
+describe('OutputFormatter', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  it('printSuccess calls console.log with the message', async () => {
+    const { output } = await importOutput(false);
+    output.printSuccess('done');
+    expect(console.log).toHaveBeenCalledOnce();
+    expect((console.log as any).mock.calls[0][0]).toContain('done');
+  });
+
+  it('printError calls console.error with the message and optional details', async () => {
+    const { output } = await importOutput(false);
+    output.printError('fail', 'reason');
+    expect(console.error).toHaveBeenCalledTimes(2);
+    expect((console.error as any).mock.calls[0][0]).toContain('fail');
+    expect((console.error as any).mock.calls[1][0]).toContain('reason');
+  });
+
+  it('printWarning calls console.warn', async () => {
+    const { output } = await importOutput(false);
+    output.printWarning('careful');
+    expect(console.warn).toHaveBeenCalledOnce();
+    expect((console.warn as any).mock.calls[0][0]).toContain('careful');
+  });
+
+  it('printInfo calls console.log with info prefix', async () => {
+    const { output } = await importOutput(false);
+    output.printInfo('note');
+    expect(console.log).toHaveBeenCalledOnce();
+    expect((console.log as any).mock.calls[0][0]).toContain('note');
+  });
+
+  it('with color disabled (non-TTY), output contains no ANSI escape codes', async () => {
+    const { output } = await importOutput(false);
+    output.printSuccess('plain');
+    const logged = (console.log as any).mock.calls[0][0] as string;
+    expect(logged).not.toContain('\x1b[');
+  });
+
+  it('with color enabled (TTY), output contains ANSI escape codes', async () => {
+    const { output } = await importOutput(true);
+    output.printSuccess('colored');
+    const logged = (console.log as any).mock.calls[0][0] as string;
+    expect(logged).toContain('\x1b[');
+  });
+});

package/src/__tests__/ref-cache.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, readFile, rm, stat } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+// We need to mock process.cwd() before importing ref-cache so CACHE_DIR
+// resolves to our temp directory.
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'monobrowse-test-'));
+  vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+// Dynamic import so each test picks up the mocked cwd.
+// We must bust the module cache between tests.
+async function importRefCache() {
+  // Vitest module cache means re-import returns the same module.
+  // Since CACHE_DIR is set at module-load time, we need resetModules.
+  vi.resetModules();
+  return import('../browser/ref-cache.js');
+}
+
+function makeRefs(count = 2): Map<string, { ref: string; role: string; name: string; nodeId: number }> {
+  const map = new Map();
+  for (let i = 1; i <= count; i++) {
+    map.set(`ref${i}`, { ref: `ref${i}`, role: 'button', name: `Button ${i}`, nodeId: i });
+  }
+  return map;
+}
+
+describe('ref-cache', () => {
+  it('round-trip: save then load returns equivalent data', async () => {
+    const mod = await importRefCache();
+    const refs = makeRefs(2);
+
+    await mod.saveRefCache('target-1', 'https://example.com', refs as any);
+    const loaded = await mod.loadRefCache('target-1');
+
+    expect(loaded).not.toBeNull();
+    expect(loaded!.url).toBe('https://example.com');
+    expect(loaded!.refs.size).toBe(2);
+    expect(loaded!.refs.get('ref1')!.role).toBe('button');
+    expect(loaded!.refs.get('ref2')!.name).toBe('Button 2');
+    expect(typeof loaded!.savedAt).toBe('number');
+    expect(typeof loaded!.ageMs).toBe('number');
+  });
+
+  it('targetId mismatch returns null', async () => {
+    const mod = await importRefCache();
+    const refs = makeRefs(1);
+
+    await mod.saveRefCache('target-A', 'https://a.com', refs as any);
+    const loaded = await mod.loadRefCache('target-B');
+
+    expect(loaded).toBeNull();
+  });
+
+  it('corrupt JSON file returns null', async () => {
+    const mod = await importRefCache();
+    // First save a valid cache to create the directory structure
+    await mod.saveRefCache('t', 'https://x.com', makeRefs(1) as any);
+
+    // Now overwrite the file with invalid JSON
+    const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot.json');
+    const { writeFile: wf } = await import('fs/promises');
+    await wf(cacheFile, '{{{not valid json!!!');
+
+    const loaded = await mod.loadRefCache('t');
+    expect(loaded).toBeNull();
+  });
+
+  it('clearRefCache removes the cache file', async () => {
+    const mod = await importRefCache();
+    await mod.saveRefCache('t1', 'https://x.com', makeRefs(1) as any);
+
+    const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot.json');
+    // Verify file exists
+    const before = await stat(cacheFile).catch(() => null);
+    expect(before).not.toBeNull();
+
+    await mod.clearRefCache();
+
+    const after = await stat(cacheFile).catch(() => null);
+    expect(after).toBeNull();
+  });
+
+  it('load after clear returns null', async () => {
+    const mod = await importRefCache();
+    await mod.saveRefCache('t1', 'https://x.com', makeRefs(1) as any);
+    await mod.clearRefCache();
+
+    const loaded = await mod.loadRefCache('t1');
+    expect(loaded).toBeNull();
+  });
+
+  it('freshly saved cache is not stale', async () => {
+    const mod = await importRefCache();
+    await mod.saveRefCache('t1', 'https://x.com', makeRefs(1) as any);
+
+    const loaded = await mod.loadRefCache('t1');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.stale).toBe(false);
+    expect(loaded!.ageMs).toBeLessThan(mod.REF_CACHE_STALE_MS);
+  });
+
+  it('cache older than REF_CACHE_STALE_MS is flagged stale', async () => {
+    const mod = await importRefCache();
+    await mod.saveRefCache('t1', 'https://x.com', makeRefs(1) as any);
+
+    // Manually backdate the savedAt timestamp
+    const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot.json');
+    const raw = JSON.parse(await readFile(cacheFile, 'utf8'));
+    raw.savedAt = Date.now() - mod.REF_CACHE_STALE_MS - 5000;
+    const { writeFile: wf } = await import('fs/promises');
+    await wf(cacheFile, JSON.stringify(raw));
+
+    const loaded = await mod.loadRefCache('t1');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.stale).toBe(true);
+    expect(loaded!.ageMs).toBeGreaterThan(mod.REF_CACHE_STALE_MS);
+  });
+
+  it('loading with no cache file returns null (no crash)', async () => {
+    const mod = await importRefCache();
+    const loaded = await mod.loadRefCache('nonexistent');
+    expect(loaded).toBeNull();
+  });
+});
+
+describe('active-port persistence', () => {
+  it('round-trip: save then load returns the port; launched defaults true', async () => {
+    const mod = await importRefCache();
+    await mod.saveActivePort(9333);
+    expect(await mod.loadActivePort()).toBe(9333);
+    expect(await mod.loadActivePortInfo()).toEqual({ port: 9333, launched: true });
+  });
+
+  it('connect provenance: launched:false survives the round-trip', async () => {
+    const mod = await importRefCache();
+    await mod.saveActivePort(9229, { launched: false });
+    expect(await mod.loadActivePortInfo()).toEqual({ port: 9229, launched: false });
+  });
+
+  it('clear removes the file; load returns null afterwards', async () => {
+    const mod = await importRefCache();
+    await mod.saveActivePort(9333);
+    await mod.clearActivePort();
+    expect(await mod.loadActivePort()).toBeNull();
+    expect(await mod.loadActivePortInfo()).toBeNull();
+  });
+
+  it('clear with no file resolves without throwing', async () => {
+    const mod = await importRefCache();
+    await mod.clearActivePort();
+    await expect(mod.clearActivePort()).resolves.toBeUndefined();
+  });
+
+  it('rejects out-of-range or non-integer persisted ports', async () => {
+    const mod = await importRefCache();
+    const { writeFile, mkdir } = await import('fs/promises');
+    const dir = join(process.cwd(), '.monomind', 'monobrowse');
+    await mkdir(dir, { recursive: true });
+    for (const bad of [80, 70000, 1.5, '9222', null]) {
+      await writeFile(join(dir, 'active-port.json'), JSON.stringify({ port: bad }));
+      expect(await mod.loadActivePort()).toBeNull();
+      expect(await mod.loadActivePortInfo()).toBeNull();
+    }
+  });
+});

package/src/browser/actions.ts

@@ -496,12 +496,22 @@ export async function removeInitScript(client: CdpClient, sessionId: string, ide
   await client.send('Page.removeScriptToEvaluateOnNewDocument', { identifier }, sessionId);
 }
 
+// Default cap on how long an evaluateJs() call waits for Runtime.evaluate to
+// resolve. Because this always passes `awaitPromise: true`, an expression
+// like `new Promise(() => {})` never settles — the underlying CdpClient.send()
+// has no timeout of its own (the CDP_RESPONSE_SIZE_LIMIT in cdp.ts only guards
+// the HTTP /json/* endpoints, not WebSocket command responses), so without
+// this the caller (e.g. the `eval` CLI command) would hang forever with
+// nothing to kill it.
+const DEFAULT_EVAL_TIMEOUT_MS = 30_000;
+
 export async function evaluateJs(
   client: CdpClient,
   sessionId: string,
-  expression: string
+  expression: string,
+  timeoutMs: number = DEFAULT_EVAL_TIMEOUT_MS
 ): Promise<unknown> {
-  const result = await client.send<{
+  const evalPromise = client.send<{
     result: { value?: unknown; type: string; description?: string };
     exceptionDetails?: { text: string; exception?: { description?: string } };
   }>('Runtime.evaluate', {
@@ -510,6 +520,16 @@ export async function evaluateJs(
     awaitPromise: true,
   }, sessionId);
 
+  const result = await (timeoutMs > 0
+    ? Promise.race([
+        evalPromise,
+        new Promise<never>((_, reject) => {
+          const t = setTimeout(() => reject(new Error(`JS evaluation timed out after ${timeoutMs}ms`)), timeoutMs);
+          t.unref?.();
+        }),
+      ])
+    : evalPromise);
+
   if (result.exceptionDetails) {
     throw new Error(`JS evaluation error: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}`);
   }

package/src/browser/browser.ts

@@ -2,6 +2,7 @@ import { spawn, execSync } from 'child_process';
 import { existsSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
+import { connect } from 'net';
 import { CdpClient, fetchTargets, fetchNewTarget } from './cdp.js';
 import type { BrowserConfig, CdpTarget } from './types.js';
 import { CHROME_EXECUTABLES } from './types.js';
@@ -11,6 +12,14 @@ import { setupDialogAutoHandling } from './dialog.js';
 const DEFAULT_PORT = 9222;
 const LAUNCH_TIMEOUT = 10_000;
 const POLL_INTERVAL = 200;
+const BROWSER_CLOSE_TIMEOUT_MS = 3000;
+
+// Tracks the PID of Chrome instances *we* spawned, keyed by CDP port, so
+// closeBrowser() has a kill fallback when the graceful `Browser.close` CDP
+// command fails or times out (e.g. a hung renderer). Ports we merely attached
+// to (already-running browser) are never recorded here — we only ever kill
+// processes we launched ourselves.
+const launchedPids = new Map<number, number>();
 
 function findChrome(executablePath?: string): string {
   if (executablePath) {
@@ -42,6 +51,38 @@ export async function isPortOpen(port: number): Promise<boolean> {
   }
 }
 
+/**
+ * Confirm the CDP endpoint on `port` actually identifies as Chrome/Chromium
+ * via `/json/version`'s `Browser` field, rather than assuming any CDP-speaking
+ * responder is "ours". Reduces (does not eliminate) the risk of silently
+ * attaching to an unrelated real browser that happens to be listening there.
+ */
+async function isChromeIdentity(port: number): Promise<boolean> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/json/version`);
+    if (!res.ok) return false;
+    const info = (await res.json()) as { Browser?: string };
+    return typeof info.Browser === 'string' && /chrom(e|ium)/i.test(info.Browser);
+  } catch {
+    return false;
+  }
+}
+
+/** Raw TCP connect probe — distinguishes "nothing listening" from "something listening that isn't CDP". */
+function isTcpPortOpen(port: number, timeoutMs = 1000): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect({ host: '127.0.0.1', port, timeout: timeoutMs });
+    const done = (result: boolean) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(result);
+    };
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(false));
+    socket.once('error', () => done(false));
+  });
+}
+
 export async function launchBrowser(config: BrowserConfig = {}): Promise<number> {
   const rawPort = config.port ?? DEFAULT_PORT;
   // Validate port is in a safe range for localhost CDP debugging
@@ -51,7 +92,16 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
   const port = rawPort;
 
   if (await isPortOpen(port)) {
-    return port;
+    // Something CDP-speaking is already there — verify it's actually Chrome/Chromium
+    // before attaching, so we don't silently take over an unrelated real browser
+    // (e.g. the user's own personal Chrome) that happens to be on this port.
+    if (await isChromeIdentity(port)) {
+      return port;
+    }
+    throw new Error(
+      `Port ${port} is occupied by a CDP-speaking process that does not identify as Chrome/Chromium. ` +
+      `Refusing to attach — pass a different port or free port ${port}.`
+    );
   }
 
   const chromePath = findChrome(config.executablePath);
@@ -89,11 +139,28 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
     stdio: 'ignore',
   });
   child.unref();
+  if (child.pid) launchedPids.set(port, child.pid);
 
   const deadline = Date.now() + LAUNCH_TIMEOUT;
   while (Date.now() < deadline) {
     await sleep(POLL_INTERVAL);
-    if (await isPortOpen(port)) return port;
+    if (await isPortOpen(port)) {
+      if (await isChromeIdentity(port)) return port;
+      throw new Error(
+        `Port ${port} is occupied by a CDP-speaking process that does not identify as Chrome/Chromium. ` +
+        `Refusing to attach — pass a different port or free port ${port}.`
+      );
+    }
+  }
+
+  // Timed out waiting for our Chrome to come up on the port. Distinguish
+  // "nothing is listening" (real launch failure) from "something non-CDP is
+  // squatting the port" (confusing generic timeout otherwise) via a raw TCP probe.
+  if (await isTcpPortOpen(port)) {
+    throw new Error(
+      `Port ${port} is occupied by a non-Chrome process (TCP connection succeeds but no CDP response within ${LAUNCH_TIMEOUT}ms). ` +
+      `Free the port or pass a different one.`
+    );
   }
 
   throw new Error(`Chrome failed to start on port ${port} within ${LAUNCH_TIMEOUT}ms`);
@@ -140,6 +207,52 @@ export async function connectToTarget(port: number, targetId?: string): Promise<
   return { client, target, sessionId };
 }
 
+/**
+ * Cleanly terminate a Chrome/Chromium instance we launched on `port`.
+ * Sends the `Browser.close` CDP command (the correct graceful shutdown —
+ * closes all tabs and exits the process cleanly) over `client`'s connection.
+ * If that command fails, times out, or the connection is already gone,
+ * falls back to killing the tracked PID directly so a headed/interactive
+ * browser window (e.g. one spawned for a login/CAPTCHA flow) never lingers
+ * as a visible, authenticated, still-debuggable orphan process.
+ */
+export async function closeBrowser(client: CdpClient, port: number): Promise<void> {
+  let gracefullyClosed = false;
+  try {
+    await Promise.race([
+      client.send('Browser.close', {}),
+      new Promise<never>((_, reject) => {
+        const t = setTimeout(() => reject(new Error('Browser.close timed out')), BROWSER_CLOSE_TIMEOUT_MS);
+        t.unref?.();
+      }),
+    ]);
+    gracefullyClosed = true;
+  } catch {
+    // fall through to PID-kill fallback below
+  }
+
+  const pid = launchedPids.get(port);
+  if (pid === undefined) return; // not a process we launched — nothing to kill
+  launchedPids.delete(port);
+
+  if (!gracefullyClosed) {
+    try { process.kill(pid, 'SIGKILL'); } catch { /* already exited */ }
+    return;
+  }
+
+  // Browser.close was acknowledged — give the process a moment to exit on
+  // its own, then verify and force-kill as a safety net in case it hung.
+  const t = setTimeout(() => {
+    try {
+      process.kill(pid, 0); // throws if the process is already gone
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      /* already exited — expected path */
+    }
+  }, 1000);
+  t.unref?.();
+}
+
 export async function openUrl(client: CdpClient, sessionId: string, url: string): Promise<void> {
   // Cap to 2 MB to prevent OOM in CDP message serializer (e.g. data: URI attacks)
   if (url.length > 2_097_152) throw new Error('URL exceeds 2 MB limit');

package/src/browser/cdp.ts

@@ -151,7 +151,7 @@ export async function fetchTargets(port: number): Promise<CdpTarget[]> {
 
 export async function fetchNewTarget(port: number, url: string): Promise<CdpTarget> {
   // Chrome v92+ requires PUT for /json/new; GET returns 405. URL must be encoded.
-  const res = await fetch(`http://127.0.0.1:${port}/json/new?${url}`, { method: 'PUT' });
+  const res = await fetch(`http://127.0.0.1:${port}/json/new?${encodeURIComponent(url)}`, { method: 'PUT' });
   if (!res.ok) throw new Error(`Failed to create target: ${res.statusText}`);
   return readCdpJson(res) as Promise<CdpTarget>;
 }

package/src/browser/dashboard/server.ts

@@ -1,10 +1,11 @@
 import { createServer, IncomingMessage, ServerResponse } from 'node:http';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
+import { randomBytes } from 'node:crypto';
 
 export interface StepEvent {
   type: string;
@@ -57,6 +58,21 @@ let instance: DashboardServer | null = null;
 export function startDashboard(port = DEFAULT_PORT): DashboardServer {
   if (instance) return instance;
 
+  // ── Security: per-process auth credential for mutating (non-GET) requests ──
+  // Generated once per server start and written to a well-known location so
+  // trusted local callers (CLI) can read it and pass it back via an auth
+  // header or query param on non-GET routes. Mirrors the pattern used by the
+  // main CLI dashboard (packages/@monomind/cli/src/ui/server.ts).
+  const dashboardAuthValue = randomBytes(24).toString('hex');
+  try {
+    const authFileDir = join(homedir(), '.monomind');
+    mkdirSync(authFileDir, { recursive: true });
+    writeFileSync(join(authFileDir, 'monobrowse-dashboard-token'), dashboardAuthValue, { mode: 0o600 });
+  } catch {
+    // best-effort: if we can't persist the token, mutating routes still
+    // enforce it in-memory — trusted callers just won't be able to read it.
+  }
+
   const runHistory: RunRecord[] = [];
   const stopRequests = new Set<string>();
   /** Map from client (WebSocket or SSE response) to the subscribed project dir,
@@ -79,6 +95,13 @@ export function startDashboard(port = DEFAULT_PORT): DashboardServer {
   } catch {
     uiHtml = `<!DOCTYPE html><html><head><title>monobrowse dashboard</title></head><body style="background:#0f0f1a;color:#ccc;font-family:system-ui;padding:20px"><h1>monobrowse dashboard</h1><p>Dashboard UI not found. Run the build to include ui.html.</p><script>let _retryDelay=1000;function connectSSE(){const es=new EventSource('/events');es.onmessage=e=>{console.log(JSON.parse(e.data));_retryDelay=1000;};es.onerror=()=>{es.close();setTimeout(connectSSE,Math.min(_retryDelay*=2,30000));};};connectSSE();</script></body></html>`;
   }
+  // Hand the per-process auth token to the served page so its own JS (e.g. the
+  // stop button) can pass it back on mutating requests. Injected once at
+  // startup — the loopback-only page is the sole reader.
+  const tokenScript = `<script>window.__MONOBROWSE_TOKEN__=${JSON.stringify(dashboardAuthValue)};</script>`;
+  uiHtml = uiHtml.includes('</head>')
+    ? uiHtml.replace('</head>', `${tokenScript}</head>`)
+    : tokenScript + uiHtml;
 
   const server = createServer(async (req, res) => {
     const url = req.url ?? '/';
@@ -100,8 +123,20 @@ export function startDashboard(port = DEFAULT_PORT): DashboardServer {
       return;
     }
 
+    // ── Security: require a matching auth token on all mutating routes ──────
+    // Binding to loopback only stops remote attackers, not a malicious page
+    // open in the user's own browser (DNS rebinding / same-origin fetch to
+    // 127.0.0.1). Require the per-process token via header or query param on
+    // every non-GET/HEAD route; GET/SSE reads stay open on the loopback baseline.
     if (url.startsWith('/stop/') && req.method === 'POST') {
-      const runId = url.slice(6);
+      const parsedAuth = new URL(url, 'http://localhost');
+      const suppliedAuth = req.headers['x-monobrowse-token'] || parsedAuth.searchParams.get('token') || '';
+      if (suppliedAuth !== dashboardAuthValue) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Unauthorized: missing or invalid auth token' }));
+        return;
+      }
+      const runId = url.slice(6).split('?')[0];
       stopRequests.add(runId);
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify({ ok: true, runId }));

package/src/browser/dashboard/ui.html

@@ -678,7 +678,7 @@ function renderCards() {
     '</div>';
   }).join('');
 }
-function stopRun(id) { fetch('/stop/' + id, { method: 'POST' }).catch(function() {}); }
+function stopRun(id) { fetch('/stop/' + id, { method: 'POST', headers: { 'x-monobrowse-token': (window.__MONOBROWSE_TOKEN__ || '') } }).catch(function() {}); }
 
 // ═══════════════════════════════════════════════════════════════════
 // NODE PALETTE DEFINITIONS

package/src/browser/index.ts

@@ -20,3 +20,4 @@ export * from './trace.js';
 export * from './profiler.js';
 export * from './vitals.js';
 export * from './har.js';
+export * from './ref-cache.js';

package/src/browser/network.ts

@@ -6,6 +6,17 @@ export async function getCookies(client: CdpClient, sessionId: string): Promise<
   return result.cookies ?? [];
 }
 
+/**
+ * Get cookies scoped to specific page URLs via `Network.getCookies`, instead of
+ * `Network.getAllCookies` which returns cookies for every origin in the browser
+ * profile. Used for session save/export so we don't leak session tokens for
+ * unrelated domains the user happens to be logged into.
+ */
+export async function getCookiesForUrls(client: CdpClient, sessionId: string, urls: string[]): Promise<CdpCookie[]> {
+  const result = await client.send<{ cookies: CdpCookie[] }>('Network.getCookies', { urls }, sessionId);
+  return result.cookies ?? [];
+}
+
 export async function setCookies(client: CdpClient, sessionId: string, cookies: CdpCookie[]): Promise<void> {
   await client.send('Network.setCookies', { cookies }, sessionId);
 }