bwb-browser 4.0.0 → 4.1.0

package/lib/session.mjs

@@ -7,20 +7,37 @@
  * Sessions are stored as JSON files in ~/.bwb/sessions/
  */
 
-import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync } from "fs";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, chmodSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 
 const SESSION_DIR = join(homedir(), ".bwb", "sessions");
 
+// These files hold live login cookies for every domain the browser has visited.
+// They were written with the default umask (0644 = world-readable) inside a
+// 0755 directory. 600/700, and chmod pre-existing files on read too.
 function ensureDir() {
-  mkdirSync(SESSION_DIR, { recursive: true });
+  mkdirSync(SESSION_DIR, { recursive: true, mode: 0o700 });
+  try { chmodSync(SESSION_DIR, 0o700); } catch {}
+}
+
+function writeSecure(path, data) {
+  writeFileSync(path, data, { mode: 0o600 });
+  chmodSync(path, 0o600);
+}
+
+/** True when a cookie belongs to one of the requested domains. */
+function inDomains(cookie, domains) {
+  if (!domains || !domains.length) return true;
+  const host = String(cookie.domain || "").replace(/^\./, "").toLowerCase();
+  return domains.some((d) => host === d || host.endsWith("." + d));
 }
 
 /**
  * Save all cookies from the current browser session to a named session file.
+ * @param {object} [opts] {domains} — restrict to specific domains
  */
-export async function saveSession(name, protocol) {
+export async function saveSession(name, protocol, { domains } = {}) {
   if (!name || typeof name !== "string") {
     throw new Error("Session name is required");
   }
@@ -29,15 +46,25 @@ export async function saveSession(name, protocol) {
   ensureDir();
 
   const { cookies } = await protocol.Network.getAllCookies();
+  const wanted = domains?.length
+    ? cookies.filter((c) => inDomains(c, domains.map((d) => String(d).toLowerCase())))
+    : cookies;
   const path = join(SESSION_DIR, `${safeName}.json`);
-  writeFileSync(path, JSON.stringify({
+  writeSecure(path, JSON.stringify({
     name: safeName,
-    cookieCount: cookies.length,
+    cookieCount: wanted.length,
+    domains: domains || null,
     savedAt: Date.now(),
-    cookies,
+    cookies: wanted,
   }, null, 2));
 
-  return { savedTo: path, cookieCount: cookies.length, name: safeName };
+  return {
+    savedTo: path,
+    cookieCount: wanted.length,
+    name: safeName,
+    ...(domains?.length ? { domains } : {}),
+    warning: "This file contains live login credentials (mode 600). Treat it like a password.",
+  };
 }
 
 /**

package/lib/setup.mjs

@@ -8,14 +8,23 @@
  */
 
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const HOME = process.env.HOME || '/root';
+// os.homedir(), not process.env.HOME: on Windows HOME is usually unset, and the
+// old '/root' fallback made setup look in a directory nobody has.
+const HOME = os.homedir();
 const SERVER_PATH = path.resolve(__dirname, '..', 'server.mjs');
 
+// ─── Dry run by default ──────────────────────────────────────────────────────
+// setup edits up to eight other tools' config files. It used to do that with no
+// confirmation and no way to preview; --yes applies, --dry-run (default) prints.
+const ASSUME_YES = process.argv.includes('--yes');
+const DRY_RUN = process.argv.includes('--dry-run') || !ASSUME_YES;
+
 // ─── Detect Chrome/Chromium ───────────────────────────────────────
 function detectChrome() {
   if (process.env.BWB_CHROME_PATH) {
@@ -34,18 +43,32 @@ function detectChrome() {
     'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
   ];
 
+  // No shell: the candidate list is data. `which`/`where` is tried per bin.
+  const lookups = os.platform() === 'win32' ? ['where'] : ['which', 'command -v'];
   for (const bin of candidates) {
-    try {
-      const out = execSync(`which "${bin}" 2>/dev/null || command -v "${bin}" 2>/dev/null || echo ""`, {
-        encoding: 'utf8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe']
-      }).trim();
-      if (out) return { path: out, source: 'PATH' };
-    } catch { /* not found */ }
+    if (path.isAbsolute(bin) && fs.existsSync(bin)) return { path: bin, source: 'filesystem' };
+    for (const cmd of lookups) {
+      try {
+        const args = cmd === 'command -v' ? ['-v', bin] : [bin];
+        const out = execFileSync(cmd, args, {
+          encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore']
+        }).split(/\r?\n/).map((l) => l.trim()).filter(Boolean)[0];
+        if (out) return { path: out, source: 'PATH' };
+      } catch { /* not found */ }
+    }
   }
 
   return null;
 }
 
+function whichExists(bin) {
+  const cmd = os.platform() === 'win32' ? 'where' : 'which';
+  try {
+    execFileSync(cmd, [bin], { stdio: 'ignore', timeout: 3000 });
+    return true;
+  } catch { return false; }
+}
+
 // ─── Detect AI CLI tools ──────────────────────────────────────────
 const AGENT_CONFIGS = [
   {
@@ -90,9 +113,26 @@ const AGENT_CONFIGS = [
     }
   },
   {
+    // Claude Code reads MCP servers from ~/.claude.json (user scope) or a
+    // project .mcp.json — NOT from ~/.claude/settings.json, where the old
+    // setup wrote mcpServers and then reported "✅ configured" while nothing
+    // changed (anthropics/claude-code#4976, #26167). Use the CLI when it
+    // exists so the write lands where Claude Code actually looks.
     name: 'Claude Code',
-    file: path.join(HOME, '.claude/settings.json'),
+    file: path.join(HOME, '.claude.json'),
     detect: (cfg) => !!(cfg.mcpServers?.bwb),
+    cli() {
+      const add = ['mcp', 'add', '--scope', 'user', 'bwb', '--', process.execPath, SERVER_PATH];
+      const print = `claude ${add.join(' ')}`;
+      if (!whichExists('claude')) return { manual: print };
+      if (DRY_RUN) return { manual: print };
+      try {
+        execFileSync('claude', add, { encoding: 'utf8', timeout: 30000, stdio: ['ignore', 'pipe', 'pipe'] });
+        return { ok: true, file: path.join(HOME, '.claude.json') };
+      } catch (err) {
+        return { manual: print, error: err.message };
+      }
+    },
     add(cfg) {
       if (!cfg.mcpServers) cfg.mcpServers = {};
       cfg.mcpServers.bwb = {
@@ -162,7 +202,10 @@ const AGENT_CONFIGS = [
 
 // ─── Core logic ────────────────────────────────────────────────────
 function backup(file) {
-  const bak = file + '.bak';
+  // Timestamped: a single .bak was overwritten on every re-run, so the second
+  // run destroyed the only copy of the user's original config.
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const bak = `${file}.${stamp}.bak`;
   try {
     fs.copyFileSync(file, bak);
     return bak;
@@ -179,7 +222,19 @@ function writeConfigSafely(file, data) {
 }
 
 function configureAgent(agent) {
-  const { name, file, detect, add } = agent;
+  const { name, file, detect, add, cli } = agent;
+
+  // Some agents must be configured through their own CLI, not by editing JSON.
+  if (cli) {
+    const res = cli();
+    if (res.ok) return { name, status: 'configured', file: res.file, via: 'claude mcp add' };
+    if (res.manual) {
+      return fs.existsSync(file) && detect(JSON.parse(fs.readFileSync(file, 'utf8')))
+        ? { name, status: 'already configured', file }
+        : { name, status: 'manual', command: res.manual, error: res.error };
+    }
+  }
+
   const fileExists = fs.existsSync(file);
 
   if (!fileExists) return { name, status: 'skipped', reason: 'not installed' };
@@ -194,8 +249,11 @@ function configureAgent(agent) {
       return { name, status: 'already configured', file };
     }
 
-    const bak = backup(file);
     config = add(config);
+    if (DRY_RUN) {
+      return { name, status: 'would configure', file };
+    }
+    const bak = backup(file);
     if (!writeConfigSafely(file, config)) {
       return { name, status: 'error', reason: 'write failed' };
     }
@@ -263,12 +321,21 @@ export function runSetup() {
   const results = AGENT_CONFIGS.map(configureAgent);
 
   const configured = results.filter(r => r.status === 'configured');
+  const would = results.filter(r => r.status === 'would configure');
   const alreadyDone = results.filter(r => r.status === 'already configured');
   const skipped = results.filter(r => r.status === 'skipped');
   const errors = results.filter(r => r.status === 'error');
 
   for (const r of results) {
     switch (r.status) {
+      case 'would configure':
+        console.log(`  📝 ${r.name}: would write ${r.file}`);
+        break;
+      case 'manual':
+        console.log(`  📎 ${r.name}: run this yourself — bwb cannot verify it for you:`);
+        console.log(`     ${r.command}`);
+        if (r.error) console.log(`     (attempt failed: ${String(r.error).slice(0, 120)})`);
+        break;
       case 'configured':
         console.log(`  ✅ ${r.name}: configured`);
         if (r.backup) console.log(`     backup: ${r.backup}`);
@@ -289,9 +356,23 @@ export function runSetup() {
   console.log(`  ✅ Agents configured:  ${configured.length}`);
   console.log(`  ✅ Already set up:     ${alreadyDone.length}`);
   console.log(`  ⏭️  Not installed:      ${skipped.length}`);
+  if (would.length) console.log(`  📝 Would configure:    ${would.length}  (re-run with --yes to apply)`);
   if (errors.length) console.log(`  ❌ Errors:             ${errors.length}`);
   console.log();
 
+  if (DRY_RUN && (would.length || configured.length)) {
+    console.log('  🔎 DRY RUN — nothing was written.');
+    console.log('     Apply with: bwb --setup --yes\n');
+  }
+  if (DRY_RUN && !process.stdout.isTTY) {
+    // Not a terminal => almost certainly a provisioning script or CI step.
+    // A silent no-op here is the one 4.x -> 4.1.0 break that does not fail
+    // loudly, so say it on stderr where scripts actually surface errors.
+    console.error(
+      'bwb: --setup ran in dry-run mode and wrote NOTHING.\n' +
+      '      If you are scripting this, pass --yes: bwb --setup --yes\n'
+    );
+  }
   if (configured.length > 0) {
     console.log('  🔄 RESTART REQUIRED: Close and reopen your AI agent');
     console.log('     for the new MCP tools to take effect.\n');
@@ -304,7 +385,7 @@ export function runSetup() {
     console.log('     Linux:   apt install chromium-browser\n');
   }
 
-  console.log('  🚀 Ready to go! Try: browser_status\n');
+  if (!DRY_RUN) console.log('  🚀 Ready to go! Try: browser_status\n');
   printSurvivalGuide();
   return { configured: configured.length, alreadyDone: alreadyDone.length, errors: errors.length };
 }

package/lib/tabs.mjs

@@ -7,19 +7,38 @@
  */
 
 import CDP from "chrome-remote-interface";
-import { ensureBrowser, protocol, actualCdpPort, cfg } from "./browser.mjs";
-import { writeFileSync, readFileSync, existsSync } from "fs";
+import { ensureBrowser, protocol, actualCdpPort, cfg, attached, browserExited } from "./browser.mjs";
+import { assertNavigable } from "./urlpolicy.mjs";
+import { writeFileSync, readFileSync, existsSync, mkdirSync, chmodSync } from "fs";
 import { join } from "path";
 
 // ─── Tab Journal (working-set survival across LMK kills / mayfly teardown) ───
 // Tiny JSON append on every mutation. Journal is the truth the next fresh
 // browser restores from — cookies live in user-data-dir, tab URLs live here.
+//
+// The journal stores ORIGIN + PATH only. Tab URLs routinely carry OAuth
+// callbacks, magic links and reset tokens in the query string, and on desktop
+// nothing re-navigates them anyway (see restoreJournal) — so writing and
+// replaying the full URL was leaking credentials onto disk for no benefit.
+// BWB_JOURNAL=full restores the old behaviour for anyone who needs it.
 
 function journalPath() {
   if (!cfg.userDataDir) return null;
   return join(cfg.userDataDir, "bwb-tabs.json");
 }
 
+/** Strip query + fragment unless the user explicitly asked for full URLs. */
+export function journalUrl(url) {
+  if (!url) return url;
+  if (cfg.journalFull) return url;
+  try {
+    const u = new URL(url);
+    return u.origin === "null" ? u.href : `${u.origin}${u.pathname}`;
+  } catch {
+    return url.split(/[?#]/)[0];
+  }
+}
+
 function saveJournal() {
   try {
     const path = journalPath();
@@ -27,10 +46,17 @@ function saveJournal() {
     const entries = [];
     for (const [id, tab] of tabs) {
       if (tab.url && tab.url !== "about:blank") {
-        entries.push({ url: tab.url, title: tab.title || "", active: id === activeTabId });
+        entries.push({
+          url: journalUrl(tab.url),
+          ...(cfg.journalFull ? { fullUrl: tab.url } : {}),
+          title: tab.title || "",
+          active: id === activeTabId,
+        });
       }
     }
-    writeFileSync(path, JSON.stringify(entries));
+    mkdirSync(path.replace(/[^/\\]+$/, ""), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(entries), { mode: 0o600 });
+    chmodSync(path, 0o600);
   } catch {}
 }
 
@@ -39,7 +65,11 @@ function loadJournal() {
     const path = journalPath();
     if (!path || !existsSync(path)) return [];
     const entries = JSON.parse(readFileSync(path, "utf8"));
-    return Array.isArray(entries) ? entries.filter((e) => e && e.url) : [];
+    if (!Array.isArray(entries)) return [];
+    // fullUrl only exists when BWB_JOURNAL=full was on when it was written.
+    return entries
+      .filter((e) => e && (e.url || e.fullUrl))
+      .map((e) => ({ ...e, url: e.fullUrl || e.url }));
   } catch {
     return [];
   }
@@ -65,7 +95,12 @@ async function ensureDefaultTab() {
 
   // Browser must be started first
   await ensureBrowser();
-  if (!protocol) throw new Error("Browser not started");
+  if (!protocol) {
+    throw new Error(
+      `Browser not started (exited=${browserExited} attached=${attached} port=${actualCdpPort}). ` +
+      `If another bwb process is using ${cfg.userDataDir}, it kills this browser — use a different --user-data-dir or --port.`
+    );
+  }
 
   const port = actualCdpPort || cfg.port;
   const targets = await CDP.List({ port });
@@ -82,6 +117,11 @@ async function ensureDefaultTab() {
  * Returns the CDP protocol for the active tab.
  * If no tabs are managed, ensures browser is started and returns default protocol.
  * All tool handlers should use this instead of ensureBrowser() directly.
+ *
+ * This is also where the static rung is paid off: if browser_goto answered
+ * from a plain HTTP fetch, the browser has never seen the URL. The first tool
+ * that needs Chromium materializes it here — the browser starts, navigates to
+ * the same URL, and every later tool works on that page.
  */
 export async function getActiveProtocol() {
   if (tabs.size === 0) {
@@ -98,26 +138,90 @@ export async function getActiveProtocol() {
   return protocol;
 }
 
+/**
+ * A page served by the static rung that Chromium has not loaded yet.
+ * Set by browser_goto; consumed (navigated to) by the first browser tool.
+ */
+let pendingStatic = null;
+
+export function setPendingStatic(url, title = "") {
+  pendingStatic = url ? { url, title } : null;
+}
+
+export function getPendingStatic() {
+  return pendingStatic;
+}
+
+export function clearPendingStatic() {
+  pendingStatic = null;
+}
+
+/** True when a browser-backed tool must run but Chromium shows nothing. */
+export function needsMaterialize() {
+  if (!pendingStatic) return false;
+  const tab = activeTabId ? tabs.get(activeTabId) : null;
+  const current = tab?.url || "";
+  return !current || current === "about:blank" || current !== pendingStatic.url;
+}
+
+/**
+ * Bring Chromium to the page the static rung served, if the tab is not already
+ * there. Called from the single choke point (server.mjs) before any tool that
+ * needs a live page.
+ */
+export async function materializeStatic() {
+  if (!needsMaterialize()) return null;
+  const target = pendingStatic;
+  const cdp = await getActiveProtocol();
+  try {
+    assertNavigable(target.url);
+    await cdp.Page.enable?.();
+    // Wait for the real load events rather than a fixed sleep: a fixed sleep
+    // is how the first browser_text after a static goto comes back empty.
+    const { gotoUrl } = await import("./helpers.mjs");
+    const landed = await gotoUrl(cdp.Page, cdp.Runtime, target.url, cfg.navTimeout || 30000);
+    pendingStatic = null;
+    syncActiveTab(landed.title, landed.url);
+    return landed;
+  } catch (err) {
+    pendingStatic = null;
+    throw err;
+  }
+}
+
 /**
  * Hibernate a tab: URL stays in the journal + visible in listTabs, but the
  * renderer is closed and memory freed. Woken transparently on switchTab.
  * Never hibernates the active tab — caller must switch away first.
+ *
+ * The default tab's `protocol` IS the global browser connection, so closing
+ * that target used to leave the global connected to a dead target: the next
+ * ensureBrowser() saw a live `protocol` and handed out a connection to a tab
+ * that no longer existed.
  */
 export async function hibernateTab(targetId) {
   const id = targetId || [...tabs.keys()].find((k) => k !== activeTabId && !tabs.get(k)?.hibernated);
   if (!id || !tabs.has(id)) return null;
   const tab = tabs.get(id);
   if (tab.hibernated) return { id, hibernated: true };
+  // Guest mode: those are the user's real tabs. Never close one to save RAM.
+  if (attached) return { id, skipped: true, reason: "attach mode: never closes real tabs" };
   const port = actualCdpPort || cfg.port;
   try { await CDP.Close({ id, port }); } catch {}
-  if (tab.protocol && tab.protocol !== protocol) {
-    try { await tab.protocol.close(); } catch {}
-  }
+  closeTabConnection(tab);
   tabs.set(id, { protocol: null, title: tab.title, url: tab.url, hibernated: true });
   saveJournal();
   return { id, hibernated: true, url: tab.url };
 }
 
+/** Close a tab's CDP connection, including the shared global one. */
+function closeTabConnection(tab) {
+  if (!tab?.protocol) return;
+  try {
+    if (tab.protocol === protocol) protocol.close().catch(() => {});
+  } catch {}
+}
+
 /** Wake a hibernated tab: fresh target, journaled URL re-navigated. */
 async function wakeTab(targetId) {
   const tab = tabs.get(targetId);
@@ -136,6 +240,12 @@ async function wakeTab(targetId) {
  * Restore the journaled working set after a fresh spawn. First entry
  * navigates now; the rest become about:blank placeholders woken on switch.
  * Capped at cfg.tabMax so restore never re-spikes memory at startup.
+ *
+ * Auto-restore RE-NAVIGATES. On a lean profile that is the point (resurrect
+ * the working set after an LMK kill). On desktop it is not: a stale journal
+ * from yesterday would re-fire every URL the moment bwb starts. So on desktop
+ * the entries are surfaced as placeholders and nothing is fetched until the
+ * agent asks for it via browser_listTabs + browser_switchTab.
  */
 export async function restoreJournal() {
   const entries = loadJournal();
@@ -144,9 +254,10 @@ export async function restoreJournal() {
   const cap = cfg.tabMax && cfg.tabMax > 0 ? cfg.tabMax : entries.length;
   const wanted = entries.slice(0, Math.max(cap, 1));
   const port = actualCdpPort || cfg.port;
+  const auto = Boolean(cfg.lean) || Boolean(cfg.journalFull);
   let first = true;
   for (const entry of wanted) {
-    if (first) {
+    if (first && auto) {
       first = false;
       try {
         await protocol.Page.navigate({ url: entry.url });
@@ -154,6 +265,7 @@ export async function restoreJournal() {
       } catch {}
       continue;
     }
+    first = false;
     try {
       const info = await CDP.New({ port, url: "about:blank" });
       const newProtocol = await CDP({ target: info.id, port });
@@ -161,7 +273,7 @@ export async function restoreJournal() {
     } catch {}
   }
   saveJournal();
-  return true;
+  return auto;
 }
 
 // ─── Create Tab ──────────────────────────────────────────────────────────────
@@ -171,11 +283,13 @@ export async function restoreJournal() {
  * Switches to the new tab automatically.
  */
 export async function createTab(url) {
+  if (url) assertNavigable(url, { allowDomains: cfg.allowDomains || null });
   await ensureDefaultTab();
 
   // Live-tab cap: hibernate the oldest non-active tab instead of growing
   // renderers until Android LMK notices. Journal keeps everything restorable.
-  if (cfg.tabMax && cfg.tabMax > 0) {
+  // Never in attach mode — those tabs belong to the human.
+  if (!attached && cfg.tabMax && cfg.tabMax > 0) {
     while (liveCount() >= cfg.tabMax) {
       const victim = [...tabs.keys()].find((k) => k !== activeTabId && !tabs.get(k)?.hibernated);
       if (!victim) break;
@@ -215,9 +329,7 @@ export async function closeTab(targetId) {
   await CDP.Close({ id, port });
 
   const tab = tabs.get(id);
-  if (tab && tab.protocol && tab.protocol !== protocol) {
-    try { await tab.protocol.close(); } catch {}
-  }
+  closeTabConnection(tab);
   tabs.delete(id);
 
   // Switch to another tab

package/lib/urlpolicy.mjs

@@ -0,0 +1,137 @@
+/**
+ * bwb-browser — URL navigation policy
+ *
+ * One chokepoint for every URL that reaches the network or the browser. The
+ * agent reads untrusted pages, and a page can talk the agent into fetching
+ * `file:///…` or the cloud metadata address. Scheme and address checks live
+ * here so goto, newTab, act-navigation, download and static fetch all agree.
+ */
+
+const BLOCKED_SCHEMES = new Set([
+  "file:", "chrome:", "chrome-extension:", "chrome-search:", "chrome-untrusted:",
+  "devtools:", "javascript:", "view-source:", "data:", "blob:", "ftp:", "ws:", "wss:",
+]);
+
+const NAVIGABLE_SCHEMES = new Set(["http:", "https:", "about:"]);
+
+export class UrlPolicyError extends Error {
+  constructor(message, url) {
+    super(message);
+    this.name = "UrlPolicyError";
+    this.url = url;
+  }
+}
+
+/**
+ * Parse and check a URL for navigation. Scheme allowlist only — this is what
+ * every navigation path (goto, newTab, act, history) goes through.
+ * @returns {URL}
+ */
+export function assertNavigable(raw, { allowDomains = null } = {}) {
+  if (typeof raw !== "string" || !raw.trim()) {
+    throw new UrlPolicyError("URL is required", raw);
+  }
+  let u;
+  try {
+    u = new URL(raw.trim());
+  } catch {
+    throw new UrlPolicyError(`Not a valid URL: ${raw}`, raw);
+  }
+  if (BLOCKED_SCHEMES.has(u.protocol)) {
+    throw new UrlPolicyError(`Blocked URL scheme: ${u.protocol}`, raw);
+  }
+  if (!NAVIGABLE_SCHEMES.has(u.protocol)) {
+    throw new UrlPolicyError(`Unsupported URL scheme: ${u.protocol} (http, https, about)`, raw);
+  }
+  if (allowDomains && allowDomains.length) {
+    assertDomainAllowed(u.hostname, allowDomains);
+  }
+  return u;
+}
+
+/** http(s) only — for anything that will be fetched by us or a subprocess. */
+export function assertHttpUrl(raw, opts = {}) {
+  const u = assertNavigable(raw, opts);
+  if (u.protocol !== "http:" && u.protocol !== "https:") {
+    throw new UrlPolicyError(`Only http(s) URLs are allowed, got ${u.protocol}`, raw);
+  }
+  return u;
+}
+
+/**
+ * Check a hostname against an optional allowlist. `example.com` also covers
+ * `www.example.com`; `*.example.com` covers subdomains only.
+ */
+export function assertDomainAllowed(hostname, allowDomains) {
+  if (!allowDomains || !allowDomains.length) return true;
+  const host = String(hostname || "").toLowerCase();
+  const ok = allowDomains.some((d) => host === d || host.endsWith("." + d));
+  if (!ok) {
+    throw new UrlPolicyError(`Domain not allowed by --allow-domains: ${host}`, host);
+  }
+  return true;
+}
+
+const IPV4_RE = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+
+/**
+ * Is this hostname a loopback / private / link-local address or a name that
+ * resolves to one? DNS names other than localhost are not resolved here (the
+ * static fetch resolves them itself), but literal IPs and known-local names
+ * are caught without a lookup.
+ */
+export function isPrivateHost(hostname) {
+  const host = String(hostname || "").toLowerCase().replace(/^\[|\]$/g, "");
+  if (!host) return true;
+  if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")) return true;
+  if (host === "metadata.google.internal" || host.endsWith(".internal")) return true;
+
+  const v4 = IPV4_RE.exec(host);
+  if (v4) {
+    const [a, b] = [Number(v4[1]), Number(v4[2])];
+    if (a === 127) return true; // 127/8 loopback
+    if (a === 10) return true; // 10/8
+    if (a === 172 && b >= 16 && b <= 31) return true; // 172.16/12
+    if (a === 192 && b === 168) return true; // 192.168/16
+    if (a === 169 && b === 254) return true; // 169.254/16 link-local + metadata
+    if (a === 0) return true; // 0.0.0.0/8
+    if (a === 100 && b >= 64 && b <= 127) return true; // 100.64/10 CGNAT
+    if (a >= 224) return true; // multicast / reserved
+    return false;
+  }
+
+  if (host.includes(":")) {
+    // IPv6 literal
+    if (host === "::1" || host === "::") return true;
+    if (/^f[cd]/.test(host)) return true; // fc00::/7 unique-local
+    if (host.startsWith("fe80")) return true; // link-local
+  }
+  return false;
+}
+
+/**
+ * Full outbound-fetch policy: http(s) only, and (unless BWB_ALLOW_PRIVATE=1)
+ * no loopback / private / link-local targets. Used by the static fetch rung so
+ * a prompt-injected page cannot make the agent read the host's LAN or the
+ * cloud metadata service.
+ *
+ * `allowPrivate` may be `true` (allow everything private — local development)
+ * or an array of hostnames (only those). Tests and dev servers use the array
+ * form so a redirect to 169.254.169.254 is still refused.
+ */
+export async function assertOutbound(raw, { allowPrivate = false, allowDomains = null } = {}) {
+  const u = assertHttpUrl(raw, { allowDomains });
+  if (allowPrivate === true) return u;
+  const allowed = Array.isArray(allowPrivate)
+    ? allowPrivate.map((h) => String(h).toLowerCase())
+    : [];
+  if (allowed.includes(u.hostname.toLowerCase())) return u;
+  if (isPrivateHost(u.hostname)) {
+    throw new UrlPolicyError(
+      `Refusing to fetch a private/loopback address (${u.hostname}). ` +
+      `Set BWB_ALLOW_PRIVATE=1 to allow local development targets.`,
+      raw
+    );
+  }
+  return u;
+}