hallpass-browser 0.0.0-stage → 1.5.0

package/src/ab.mjs

@@ -0,0 +1,216 @@
+// Thin, hardened wrapper around the agent-browser CLI.
+//  - secrets only ever travel over stdin (JSON `batch`), never argv, so they are not visible in process listings
+//  - every byte coming back is passed through the Redactor before anything can print or log it
+import { spawn, spawnSync, execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { createRequire } from 'node:module';
+import { home } from './paths.mjs';
+
+export const runtimeDir = () => path.join(home(), 'runtime');
+
+// The agent-browser binary receives every typed secret on stdin, so WHICH binary it is must not be steerable from the
+// agent's shell. There is no env override, and once resolved the absolute path is pinned in config.json: a later
+// `PATH=/tmp/fake:$PATH hallpass login x` cannot redirect it. Re-pinning (after moving/reinstalling) is a human action:
+// `hallpass doctor --repin`.
+const cfgFile = () => path.join(home(), 'config.json');
+const readCfg = () => { try { return JSON.parse(fs.readFileSync(cfgFile(), 'utf8')); } catch { return {}; } };
+const pinned = () => { const p = readCfg().agentBrowser; return typeof p === 'string' && fs.existsSync(p) ? p : null; };
+const pin = (p, { human = false } = {}) => { try { fs.writeFileSync(cfgFile(), JSON.stringify({ ...readCfg(), agentBrowser: p, agentBrowserPinnedBy: human ? 'person' : 'auto' }), { mode: 0o600 }); } catch { /* best effort */ } };
+export const pinnedByHuman = () => readCfg().agentBrowserPinnedBy === 'person';
+
+// The agent-browser release line this version of hallpass was developed and tested against. Newer lines may change CLI output.
+export const TESTED_AGENT_BROWSER = '0.41';
+
+let binCache;
+export function findBinary({ repin = false, human = false } = {}) {
+  if (!repin) {
+    if (binCache) return binCache;
+    const p = pinned();
+    // Our own copy (this package's dependency, or ~/.hallpass/runtime) is the one hallpass was tested with and is not steerable
+    // from a shell, so it replaces an older pin to some other install (typically a global agent-browser from before hallpass
+    // shipped its own). A pin to anything else stays: choosing a different agent-browser is a human decision (`doctor --repin`).
+    const own = ownBinary();
+    if (p && (!own || p === own)) return (binCache = p);
+    if (own && p && !pinnedByHuman()) { pin(own); return (binCache = own); }
+    if (p) return (binCache = p);
+  }
+  const found = resolveFromPath();
+  pin(found, { human });
+  return (binCache = found);
+}
+
+// The native binary inside an agent-browser package folder, or null. Linux has glibc and musl builds; take whichever exists.
+function nativeIn(pkgDir) {
+  const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+  const names = { win32: ['agent-browser-win32-x64.exe'], darwin: [`agent-browser-darwin-${arch}`], linux: [`agent-browser-linux-${arch}`, `agent-browser-linux-musl-${arch}`] }[process.platform] || [];
+  for (const n of names) {
+    const p = path.join(pkgDir, 'bin', n);
+    if (!fs.existsSync(p)) continue;
+    // npm run with --ignore-scripts leaves the binary without its execute bit: fix it rather than fail later with "permission denied"
+    if (process.platform !== 'win32') { try { fs.accessSync(p, fs.constants.X_OK); } catch { try { fs.chmodSync(p, 0o755); } catch { continue; } } }
+    return p;
+  }
+  return null;
+}
+
+/** Hallpass's own agent-browser: the package dependency, else the copy installed under ~/.hallpass/runtime. Never PATH. */
+export function ownBinary() {
+  try { const own = nativeIn(path.dirname(createRequire(import.meta.url).resolve('agent-browser/package.json'))); if (own) return own; } catch { /* not a dependency here */ }
+  return nativeIn(path.join(runtimeDir(), 'node_modules', 'agent-browser'));
+}
+
+/** "0.39.2" for a binary, or null. */
+export function versionOf(bin) {
+  const r = spawnSync(bin, ['--version'], { encoding: 'utf8', timeout: 15_000, windowsHide: true });
+  return /(\d+\.\d+\.\d+)/.exec(r.stdout || '')?.[1] || null;
+}
+/** true when a version is on an older minor line than the one hallpass is tested with. */
+export const olderThanTested = (v) => { const a = String(v || '').split('.').map(Number), b = TESTED_AGENT_BROWSER.split('.').map(Number); return a.length >= 2 && !a.some(Number.isNaN) && (a[0] < b[0] || (a[0] === b[0] && a[1] < b[1])); };
+
+// Where agent-browser may come from, in trust order. Our own dependency and our own runtime folder come BEFORE anything an
+// environment variable or PATH could steer; the result is then pinned (see above).
+function resolveFromPath() {
+  const own = ownBinary();
+  if (own) return (binCache = own);
+  for (const d of (process.env.PATH || '').split(path.delimiter)) {
+    for (const n of ['agent-browser.cmd', 'agent-browser.exe', 'agent-browser']) {
+      const p = path.join(d, n);
+      if (!fs.existsSync(p)) continue;
+      // npm global layout: <prefix>/agent-browser(.cmd) beside <prefix>/node_modules/agent-browser/bin/<native>
+      const native = nativeIn(path.join(d, 'node_modules', 'agent-browser'));
+      if (native) return (binCache = native);
+      if (!p.endsWith('.cmd')) return (binCache = p);
+    }
+  }
+  try {
+    const root = execFileSync('npm', ['root', '-g'], { encoding: 'utf8', shell: process.platform === 'win32' }).trim();
+    const native = nativeIn(path.join(root, 'agent-browser'));
+    if (native) return (binCache = native);
+  } catch { /* fall through */ }
+  throw new Error('agent-browser not found. Run: hallpass setup   (or: npm i -g agent-browser && agent-browser install)');
+}
+
+// Google refuses sign-in ("Couldn't sign you in / This browser or app may not be secure") in Chrome for Testing, the build
+// agent-browser downloads. A person's own installed Chrome or Edge is accepted, so prefer it. HALLPASS_BROWSER=<path> forces one.
+// Also supports config.json "browser": "edge" | "chrome" | "/path/to/browser".
+export function systemBrowser() {
+  const cfgBrowser = readCfg().browser;
+  const env = process.env.HALLPASS_BROWSER || (cfgBrowser && fs.existsSync(cfgBrowser) ? cfgBrowser : null);
+  if (env) return fs.existsSync(env) ? env : null;
+  const pf = [process.env.PROGRAMFILES, process.env['PROGRAMFILES(X86)'], process.env.LOCALAPPDATA].filter(Boolean);
+  const cands = {
+    win32: pf.flatMap((d) => [path.join(d, 'Google', 'Chrome', 'Application', 'chrome.exe'), path.join(d, 'Microsoft', 'Edge', 'Application', 'msedge.exe')]),
+    darwin: ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+    linux: ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/microsoft-edge', '/usr/bin/microsoft-edge-stable'],
+  }[process.platform] || [];
+  const preferEdge = /edge/i.test(process.env.HALLPASS_BROWSER || cfgBrowser || '');
+  const rank = (p) => (preferEdge ? (/edge/i.test(p) ? 0 : 1) : (/edge/i.test(p) ? 1 : 0));
+  return cands.filter((p) => fs.existsSync(p)).sort((a, b) => rank(a) - rank(b))[0] || null;
+}
+
+// Google will not accept a sign-in typed into a browser that is being remote-controlled. So for that one step the person signs in
+// in a plain, un-automated Chrome/Edge window that uses the same profile folder; closing the window saves the cookies, and the
+// automated session then reopens on that profile already signed in. Resolves true once the window was closed by the person.
+export function signInManually(profile, url, { timeoutMs = 15 * 60_000 } = {}) {
+  const exe = systemBrowser();
+  if (!exe) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const p = spawn(exe, [`--user-data-dir=${profile}`, '--no-first-run', '--no-default-browser-check', url], { stdio: 'ignore' });
+    const t = setTimeout(() => { try { p.kill(); } catch { /* already gone */ } }, timeoutMs);
+    p.on('error', () => { clearTimeout(t); resolve(false); });
+    p.on('exit', () => { clearTimeout(t); setTimeout(() => resolve(true), 1500); }); // let Chrome flush its cookie store
+  });
+}
+
+export class Browser {
+  constructor({ session, profile, headed = false, redactor, allowedDomains = null }) {
+    Object.assign(this, { session, profile, headed, redactor, allowedDomains });
+  }
+
+  _flags(json = true) {
+    const f = ['--session', this.session, '--profile', this.profile];
+    if (json) f.push('--json');
+    if (this.headed) f.push('--headed');
+    if (this.allowedDomains?.length) f.push('--allowed-domains', this.allowedDomains.join(','));
+    return f;
+  }
+
+  // Launch settings for the browser daemon (read when the session's first command starts it). A default only: a user-set
+  // AGENT_BROWSER_EXECUTABLE_PATH wins because process.env is spread after this.
+  _launchEnv() {
+    const exe = systemBrowser();
+    return exe ? { AGENT_BROWSER_EXECUTABLE_PATH: exe } : {};
+  }
+
+  run(args, { input, timeout = 60_000, json: wantJson = true, env: extraEnv = {}, bare = false } = {}) {
+    // Output goes to temp files, not pipes: the first command of a session spawns a long-lived daemon that
+    // inherits our stdio, and a pipe would never reach EOF (spawnSync would hang until its timeout).
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hp-'));
+    const fo = fs.openSync(path.join(dir, 'out'), 'w');
+    const fe = fs.openSync(path.join(dir, 'err'), 'w');
+    let r;
+    try {
+      r = spawnSync(findBinary(), [...(bare ? ['--json'] : this._flags(wantJson)), ...args], {
+        input, timeout, windowsHide: false, stdio: [input === undefined ? 'ignore' : 'pipe', fo, fe],
+        env: { AGENT_BROWSER_IDLE_TIMEOUT_MS: '7200000', ...this._launchEnv(), ...process.env, AGENT_BROWSER_HEADED: this.headed ? 'true' : 'false', ...extraEnv },
+      });
+    } finally { fs.closeSync(fo); fs.closeSync(fe); }
+    const read = (f) => { try { return fs.readFileSync(path.join(dir, f), 'utf8'); } catch { return ''; } };
+    const stdout = read('out'), stderr = read('err');
+    fs.rmSync(dir, { recursive: true, force: true });
+    const scrub = (s) => this.redactor.scrub(s || '');
+    let json = null;
+    try { json = JSON.parse(stdout); } catch { /* non-json output */ }
+    return {
+      ok: r.status === 0 && json?.success !== false,
+      json, stdout: scrub(stdout), stderr: scrub(stderr),
+      error: r.error ? scrub(String(r.error.message)) : null,
+    };
+  }
+
+  // Plain-text pass-through for an agent's own commands (used by the MCP server).
+  // Page output is wrapped in boundary markers so injected page text is clearly delimited from tool output.
+  text(args, { timeout = 60_000, boundaries = true } = {}) {
+    const r = this.run(args, { timeout, json: false, env: boundaries ? { AGENT_BROWSER_CONTENT_BOUNDARIES: 'true' } : {} });
+    return { ok: r.ok, stdout: r.stdout, stderr: r.stderr, error: r.error };
+  }
+
+  open(url) { return this.run(['open', url], { timeout: 120_000 }); }
+
+  // commands: array of string arrays. May contain secrets; they go over stdin only.
+  batch(commands) {
+    const r = this.run(['batch', '--bail'], { input: JSON.stringify(commands) });
+    const results = Array.isArray(r.json) ? r.json : [];
+    return {
+      ok: r.ok && results.length === commands.length && results.every((x) => x.success),
+      results: this.redactor.scrubDeep(results),
+      error: r.error || r.stderr,
+    };
+  }
+
+  // Runs a script in the page and parses its JSON result.
+  evalJson(script) {
+    const r = this.run(['eval', '--stdin'], { input: script });
+    if (!r.ok) return null;
+    const raw = r.json?.data?.result;
+    try { return typeof raw === 'string' ? JSON.parse(raw) : raw; } catch { return null; }
+  }
+
+  // `close` returns before the daemon has finished exiting, and for a second or two `session list` still shows the session. A
+  // relaunch (headless to headed) or a quick logout-then-open in that window would talk to the dying daemon, so wait it out.
+  close() {
+    const r = this.run(['close'], { timeout: 30_000 });
+    for (let i = 0; i < 24 && this.alive(); i++) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 250);
+    return r;
+  }
+  // Is there a live session by this name? Must NOT use a page command: on a missing session those silently
+  // launch a new blank browser, which would make "closed" look like "open".
+  alive() {
+    // bare: no --session flag, because with one the listing marks the current session as "-> name"
+    const r = this.run(['session', 'list'], { timeout: 15_000, bare: true });
+    return r.ok && Array.isArray(r.json?.data?.sessions) && r.json.data.sessions.includes(this.session);
+  }
+}

package/src/act.mjs

@@ -0,0 +1,226 @@
+// Running browser commands on behalf of an agent, with three safety layers:
+//   1. guard      a fixed allowlist of page commands; hallpass sessions only; http(s) URLs only
+//   2. read-only  HALLPASS_READONLY=1 (set by the PERSON in the MCP client config) permits observation only
+//   3. gate       clicks that look irreversible/outward-facing (Delete, Publish, Pay, Submit application, ...) need a
+//                 native yes/no dialog that only the person can answer. No GUI available = denied.
+//                 HALLPASS_GATE=off|risky|all  (default risky)
+// The gate is a HEURISTIC on the visible label, not a proof: it catches the common dangerous buttons, not every one.
+// `upload` (files from disk into a page) is vetted by upload.mjs and approved per batch; HALLPASS_UPLOAD=ask|allow|off.
+import path from 'node:path';
+import { Browser } from './ab.mjs';
+import { Redactor } from './redact.mjs';
+import { profilesDir } from './paths.mjs';
+import { ask } from './ui.mjs';
+import { audit } from './audit.mjs';
+import { safeUrl, parseOrigin } from './origin.mjs';
+import { vetUploads, describeFiles, screenshotCommand } from './upload.mjs';
+
+export const ALLOWED = new Set(['open', 'click', 'activate', 'dblclick', 'fill', 'type', 'press', 'keyboard', 'hover', 'focus', 'check', 'uncheck', 'select', 'scroll', 'scrollintoview', 'wait', 'snapshot', 'get', 'is', 'find', 'tab', 'back', 'forward', 'reload', 'dialog', 'drag', 'highlight', 'upload', 'screenshot']);
+const LONG_FLAGS = new Set(['--full', '--annotate', '--exact', '--name', '--new-tab', '--text', '--url', '--load', '--interactive', '--compact', '--depth', '--selector']);
+const SHORT_FLAGS = new Set(['-i', '-c', '-u', '-d', '-s']);
+const BAD_SCHEME = /^\s*(file|javascript|data|chrome|chrome-extension|view-source|devtools|ftp):/i;
+const SESSION_RE = /^hp-[a-z0-9][a-z0-9._-]{0,62}$/;
+// `activate <target> [Enter|Space]`: focus the control and press the key a keyboard user would. Some pages (Play Console's sticky
+// Save bar, Material buttons in dialogs) swallow or mis-aim a pointer click while the same control works from the keyboard.
+const ACTIVATE_KEYS = new Set(['Enter', 'Space']);
+
+// Positions in the argv that are text TO TYPE (release notes, a store description), not flags/selectors/URLs. Such text may
+// legitimately start with "-" or "data:"; it never reaches the CLI's flag parser (see execCommand).
+function payloadStart(command) {
+  const [verb] = command;
+  if (verb === 'fill' || verb === 'type' || verb === 'select') return 2;
+  if (verb === 'keyboard') return 2;
+  if (verb === 'find') { const i = command.findIndex((a, n) => n >= 3 && (a === 'fill' || a === 'type')); return i > 0 ? i + 1 : Infinity; }
+  return Infinity;
+}
+const payloadArgs = (command) => { const at = payloadStart(command); const idx = new Set(); command.forEach((a, n) => { if (n >= at && !(command[0] === 'find' && a.startsWith('--') && LONG_FLAGS.has(a.split('=')[0]))) idx.add(n); }); return idx; };
+
+export function guardBrowser({ session, command }) {
+  if (!SESSION_RE.test(session || '')) return 'session must be a hallpass session (hp-...) returned by hallpass_open';
+  if (!Array.isArray(command) || !command.length || command.length > 24 || command.some((a) => typeof a !== 'string' || a.length > 4000)) return 'command must be a non-empty array of strings';
+  if (!ALLOWED.has(command[0])) return `"${command[0]}" is not available through this tool (allowed: ${[...ALLOWED].join(' ')})`;
+  if (command[0] === 'activate' && (command.length < 2 || command.length > 3 || (command[2] !== undefined && !ACTIVATE_KEYS.has(command[2])))) return 'usage: activate <@ref|selector> [Enter|Space]';
+  const text = payloadArgs(command);
+  for (let n = 1; n < command.length; n++) {
+    const a = command[n];
+    if (text.has(n)) continue;
+    if (a.startsWith('--') && !LONG_FLAGS.has(a.split('=')[0])) return `flag ${a.split('=')[0]} is not allowed`;
+    if (/^-[A-Za-z]$/.test(a) && !SHORT_FLAGS.has(a)) return `flag ${a} is not allowed`;
+    if (BAD_SCHEME.test(a)) return 'only http(s) URLs are allowed';
+  }
+  return null;
+}
+
+// ---- read-only ----
+export const readOnly = () => process.env.HALLPASS_READONLY === '1';
+const WRITE_VERBS = new Set(['click', 'activate', 'dblclick', 'fill', 'type', 'press', 'keyboard', 'check', 'uncheck', 'select', 'drag', 'dialog', 'upload']);
+const FIND_ACTIONS_THAT_WRITE = new Set(['click', 'dblclick', 'fill', 'type', 'check', 'uncheck', 'select', 'hover-click']);
+export function writesState(command) {
+  if (WRITE_VERBS.has(command[0])) return true;
+  if (command[0] === 'find') return command.slice(1).some((a) => FIND_ACTIONS_THAT_WRITE.has(a));
+  return false;
+}
+
+// ---- gate ----
+export const gateMode = () => { const m = (process.env.HALLPASS_GATE || 'risky').toLowerCase(); return ['off', 'risky', 'all'].includes(m) ? m : 'risky'; };
+export const RISKY = /\b(submit|apply(?! (filter|filters|changes to view))|publish|release|roll ?out|deploy|promote|delete|remove|erase|destroy|terminate|drop|pay|purchase|buy|checkout|place order|order now|subscribe|upgrade|transfer|invite|revoke|disable|deactivate|send\b[^.\n]{0,40}\bfor (review|approval)|go live)\b/i;
+// Labels that contain a risky word but only open an editor or name a field (Play Console: "Create new release", "Release notes").
+// The final, outward-facing buttons ("Start rollout", "Publish", "Send for review") still match. Applied to the visible label only.
+const BENIGN = /\b(create new|review|view|edit)\s+releases?\b|\breleases?\s+(notes?|name|dashboard|history|type|summary|details|track)\b/gi;
+export const isRiskyLabel = (label) => RISKY.test(String(label).replace(BENIGN, ' '));
+// Stems matched as SUBSTRINGS in id/class/name/data-testid (catches deleteBtn, btn-remove, publish_release, ...).
+export const RISKY_ATTR = /(delet|remov|destroy|erase|terminat|publish|release|rollout|deploy|promote|purchase|checkout|subscribe|upgrade|invite|revoke|deactivat|transfer|submit|pay(?!load)|buy)/i;
+const CLICKY = new Set(['click', 'activate', 'dblclick', 'check', 'uncheck', 'select', 'drag']);
+const FIND_BY_SELECTOR = new Set(['first', 'last', 'nth']);
+
+function clickTarget(command) {
+  if (command[0] === 'find') {
+    const loc = command[1];
+    if (FIND_BY_SELECTOR.has(loc)) { // find first|last|nth <selector> <action>: no label in the command itself
+      const sel = loc === 'nth' ? command[3] : command[2];
+      const action = loc === 'nth' ? command[4] : command[3];
+      return CLICKY.has(action) ? { ref: sel, uncertain: loc !== 'first' } : null; // last/nth: we cannot tell which element, so ask
+    }
+    const action = command[3];
+    if (!CLICKY.has(action)) return null;
+    const nameIdx = command.indexOf('--name');
+    return { find: [command[2], nameIdx > 0 ? command[nameIdx + 1] : ''].join(' ') };
+  }
+  if (CLICKY.has(command[0])) return { ref: command[1] };
+  if (command[0] === 'press' || command[0] === 'dialog') return { ref: null, keystroke: true }; // can submit/confirm; only gated in "all" mode
+  return null;
+}
+
+// Returns { label, attrs }: what a person would read on the control, and the id/class/name/testid a developer gave it.
+function labelFor(browser, t) {
+  if (t.find !== undefined) return { label: t.find.toLowerCase().slice(0, 300), attrs: '' };
+  if (!t.ref) return { label: '', attrs: '' };
+  // one process, several lookups: visible text, accessible name, button value, title, and developer-chosen attributes
+  const q = [['get', 'text', t.ref], ['get', 'attr', t.ref, 'aria-label'], ['get', 'attr', t.ref, 'value'], ['get', 'attr', t.ref, 'title'],
+    ['get', 'attr', t.ref, 'id'], ['get', 'attr', t.ref, 'class'], ['get', 'attr', t.ref, 'name'], ['get', 'attr', t.ref, 'data-testid']];
+  const r = browser.run(['batch'], { input: JSON.stringify(q), timeout: 25_000 });
+  if (!Array.isArray(r.json)) return { label: '', attrs: '', unreadable: true };
+  // Each result is { text } / { value } (plus, in newer agent-browser releases, a long "lifecycle" block): take the field that holds
+  // the text itself. Stringifying the whole object would let the bookkeeping push the real label past the length cap.
+  const pick = (i) => { const x = r.json[i]?.result; const v = x && typeof x === 'object' ? (x.text ?? x.value ?? x.attr ?? '') : (x ?? ''); return JSON.stringify(String(v)).toLowerCase(); };
+  const label = [0, 1, 2, 3].map(pick).join(' ').slice(0, 300), attrs = [4, 5, 6, 7].map(pick).join(' ').slice(0, 300);
+  // None of the eight lookups worked (selector matched nothing, page changed, CLI output not understood): we cannot tell what
+  // this click does, so the caller asks the person instead of assuming it is harmless.
+  return { label, attrs, unreadable: !r.json.some((x) => x?.success) };
+}
+
+// ---- uploads ----
+export const uploadMode = () => { const m = (process.env.HALLPASS_UPLOAD || 'ask').toLowerCase(); return ['off', 'ask', 'allow'].includes(m) ? m : 'ask'; };
+const UPLOAD_GRANT_MS = 60 * 60 * 1000;
+const uploadGrants = new Map(); // origin -> expiry; lives in this process only (the long-running MCP server), never on disk
+
+// Returns { error } or { command } with every file replaced by its vetted, symlink-resolved absolute path.
+function authorizeUpload(b, session, command, approver) {
+  if (uploadMode() === 'off') return { error: 'Uploads are disabled on this hallpass server (HALLPASS_UPLOAD=off). Ask the user to upload the file themselves.' };
+  if (!command[1] || command[1].startsWith('-')) return { error: 'usage: upload <selector> <file> [file...]' };
+  const v = vetUploads(command.slice(2));
+  if (v.error) { audit('upload', { session, decision: 'rejected', reason: v.error.slice(0, 120) }); return { error: 'Upload refused: ' + v.error }; }
+  const where = safeUrl((b.run(['get', 'url'], { json: false, timeout: 15_000 }).stdout || '').trim());
+  const origin = parseOrigin(where) || where;
+  const names = v.files.map((f) => path.basename(f.path)).join(', ').slice(0, 200);
+  if (uploadMode() === 'ask' && !((uploadGrants.get(origin) || 0) > Date.now())) {
+    const choice = approver({
+      title: 'Hallpass: confirm file upload',
+      message: `Your AI tool wants to upload ${v.files.length} file${v.files.length > 1 ? 's' : ''} to:\n\n    ${where || 'the current page'}\n\n${describeFiles(v.files)}\n\nApprove only if you asked for this. "Allow for 1 hour" skips this question for ${origin || 'this site'} until then.`,
+      buttons: [{ id: 'deny', label: 'Deny' }, { id: 'hour', label: 'Allow for 1 hour' }, { id: 'once', label: 'Allow once' }],
+      timeoutSec: process.env.HALLPASS_ACTOR === 'mcp' ? 45 : 120,
+    });
+    audit('upload', { session, files: names, url: where, decision: choice || 'deny' });
+    if (choice === 'hour') uploadGrants.set(origin, Date.now() + UPLOAD_GRANT_MS);
+    else if (choice !== 'once') return { error: 'Blocked: the user did not approve this upload (denied, timed out, or no desktop dialog was available). Do not retry. Tell the user which file you wanted to upload and where.' };
+  } else audit('upload', { session, files: names, url: where, decision: 'allowed' });
+  return { command: ['upload', command[1], ...v.files.map((f) => f.path)] };
+}
+
+// Text to type that starts with "-" must not go through the CLI's own flag parser ("--json" or "--headed" would be eaten as
+// options). JSON over stdin (agent-browser `batch`) carries it literally.
+function execCommand(b, command) {
+  const at = payloadStart(command);
+  if (command.slice(at).some((a) => a.startsWith('-')) && ['fill', 'type', 'keyboard', 'select', 'find'].includes(command[0])) {
+    const r = b.batch([command]);
+    const one = r.results[0];
+    return { ok: r.ok, stdout: one?.success ? JSON.stringify(one.result ?? 'ok') : '', stderr: one?.success ? '' : String(one?.error || r.error || 'command failed') };
+  }
+  return b.text(command);
+}
+
+const RETRY_COVERED = new Set(['click', 'dblclick', 'check', 'uncheck']);
+
+// One command, with the two recoveries a pointer-driven page needs. The gate has already approved this exact action, so both
+// recoveries repeat it rather than doing anything new.
+//   activate   -> focus + keypress (a keyboard "click")
+//   click etc. -> "covered by <sticky footer>": scroll the target into view once and retry
+function runAction(b, command) {
+  if (command[0] === 'activate') {
+    const f = execCommand(b, ['focus', command[1]]);
+    return f.ok ? execCommand(b, ['press', command[2] || 'Enter']) : f;
+  }
+  let r = execCommand(b, command);
+  if (!r.ok && RETRY_COVERED.has(command[0]) && /is covered by/i.test(`${r.stdout}\n${r.stderr}`)) {
+    if (execCommand(b, ['scrollintoview', command[1]]).ok) r = execCommand(b, command);
+  }
+  return r;
+}
+
+const browserFor = (session) => new Browser({ session, profile: path.join(profilesDir(), session.slice(3)), redactor: new Redactor() });
+
+/** Returns { isError, text }. `approver` is injectable for tests only. */
+export function runBrowser({ session, command }, { approver = ask } = {}) {
+  const bad = guardBrowser({ session, command });
+  if (bad) return { isError: true, text: bad };
+  if (readOnly() && writesState(command)) {
+    audit('browser', { session, verb: command[0], decision: 'blocked-readonly' });
+    return { isError: true, text: `This hallpass server is read-only (HALLPASS_READONLY=1), so "${command[0]}" is not permitted. You can still snapshot, read, scroll and navigate.` };
+  }
+  const b = browserFor(session);
+
+  // Never read a password back out of the page: whatever hallpass (or the user) typed there would come back in the clear.
+  if (command[0] === 'get' && command[1] === 'value' && command[2]) {
+    const t = b.run(['get', 'attr', command[2], 'type'], { timeout: 15_000 });
+    if (String(t.json?.data?.value ?? '').trim().toLowerCase() === 'password') { // the attribute's value only: the JSON also carries the page URL, which may contain the word
+      audit('browser', { session, verb: 'get value', decision: 'blocked-password-field' });
+      return { isError: true, text: 'Reading the value of a password field is not permitted. (Snapshots show it masked.)' };
+    }
+  }
+
+  const mode = gateMode();
+  const target = mode === 'off' ? null : clickTarget(command);
+  if (target) {
+    const { label, attrs, unreadable } = labelFor(b, target);
+    // "all" gates every click-like action and keystroke-submits; otherwise: risky words in what the person sees, risky stems
+    // in what the developer named it, or a target we cannot identify (find last/nth) which we ask about rather than guess.
+    const risky = mode === 'all' || target.uncertain === true || unreadable === true || isRiskyLabel(label) || RISKY_ATTR.test(attrs);
+    if (risky) {
+      const where = safeUrl((b.run(['get', 'url'], { json: false, timeout: 15_000 }).stdout || '').trim());
+      const shown = (label.trim() ? label : attrs).replace(/\s+/g, ' ').replace(/["{}\[\]\\]/g, '').replace(/\bresult\b|\btext\b/g, '').trim().slice(0, 90) || '(unlabelled control)';
+      const choice = approver({
+        title: 'Hallpass: confirm action',
+        message: `Your AI tool wants to ${command[0]}:\n\n    ${shown}\n\non ${where || 'the current page'}\n\n${mode === 'all' ? 'Every click and keystroke action is gated.' : 'This looks irreversible or outward-facing (publish, delete, pay, submit, ...).'}\nApprove only if this is exactly what you asked for.`,
+        buttons: [{ id: 'deny', label: 'Deny' }, { id: 'once', label: 'Allow this action' }],
+        timeoutSec: process.env.HALLPASS_ACTOR === 'mcp' ? 45 : 120,
+      });
+      audit('gate', { session, verb: command[0], label: shown, url: where, decision: choice === 'once' ? 'allowed' : 'denied' });
+      if (choice !== 'once') return { isError: true, text: 'Blocked: the user did not approve this action (denied, timed out, or no desktop dialog was available). Do not retry it. Explain to the user what you wanted to do and ask them to do it or to approve it.' };
+    }
+  }
+
+  let toRun = command, shot = null;
+  if (command[0] === 'upload') {
+    const u = authorizeUpload(b, session, command, approver);
+    if (u.error) return { isError: true, text: u.error };
+    toRun = u.command;
+  } else if (command[0] === 'screenshot') {
+    ({ command: toRun, file: shot } = screenshotCommand(command));
+  }
+  if (writesState(command)) audit('browser', { session, verb: command[0], decision: 'allowed' });
+  const r = runAction(b, toRun);
+  let body = [r.stdout, r.stderr].filter(Boolean).join('\n').trim() || (r.ok ? 'ok' : 'command failed');
+  if (body.length > 40_000) body = body.slice(0, 40_000) + '\n[truncated]';
+  if (shot && r.ok) body += `\nSaved to ${shot}`;
+  return { isError: !r.ok, text: body };
+}

package/src/audit.mjs

@@ -0,0 +1,57 @@
+// Append-only, hash-chained audit log of everything an agent did with your logins. Never contains secrets:
+// callers pass only names, origin+path, verbs and outcomes. Best-effort: logging can never break a login.
+// Tamper-EVIDENT, not tamper-proof: a same-user process can still delete the file, but cannot edit history unnoticed.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { home } from './paths.mjs';
+
+const file = () => path.join(home(), 'audit.log');
+const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');
+const GENESIS = '0'.repeat(64);
+const trim = (v) => (typeof v === 'string' ? v.replace(/[\u0000-\u001f\u007f]+/g, ' ').slice(0, 200) : v);
+
+function lastHash(f) {
+  try {
+    const fd = fs.openSync(f, 'r');
+    const { size } = fs.fstatSync(fd);
+    const len = Math.min(size, 8192);
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, size - len);
+    fs.closeSync(fd);
+    const lines = buf.toString('utf8').trimEnd().split('\n');
+    return JSON.parse(lines[lines.length - 1]).hash || GENESIS;
+  } catch { return GENESIS; }
+}
+
+export function audit(event, fields = {}) {
+  try {
+    const f = file();
+    const clean = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined && v !== null).map(([k, v]) => [k, trim(v)]));
+    const rec = { ts: new Date().toISOString(), actor: process.env.HALLPASS_ACTOR || 'cli', event, ...clean, prev: lastHash(f) };
+    fs.appendFileSync(f, JSON.stringify({ ...rec, hash: sha(JSON.stringify(rec)) }) + '\n', { mode: 0o600 });
+  } catch { /* never break the caller */ }
+}
+
+export function readLog({ tail = 50 } = {}) {
+  const f = file();
+  if (!fs.existsSync(f)) return [];
+  const rows = fs.readFileSync(f, 'utf8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return { event: 'corrupt-line' }; } });
+  return rows.slice(-tail);
+}
+
+export function verifyLog() {
+  const f = file();
+  if (!fs.existsSync(f)) return { ok: true, entries: 0 };
+  let prev = GENESIS, n = 0;
+  for (const line of fs.readFileSync(f, 'utf8').split('\n').filter(Boolean)) {
+    n++;
+    let r;
+    try { r = JSON.parse(line); } catch { return { ok: false, entries: n, broken_at: n, reason: 'unparseable line' }; }
+    const { hash, ...rec } = r;
+    if (rec.prev !== prev) return { ok: false, entries: n, broken_at: n, reason: 'chain broken (entry removed or reordered)' };
+    if (sha(JSON.stringify(rec)) !== hash) return { ok: false, entries: n, broken_at: n, reason: 'entry modified' };
+    prev = hash;
+  }
+  return { ok: true, entries: n };
+}

package/src/install.mjs

@@ -0,0 +1,96 @@
+// Teaches each AI tool how to use hallpass (instruction files) and prints the MCP config for each client.
+// Instruction files are written only inside a clearly marked block (or a file hallpass owns); nothing else is touched.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const BEGIN = '<!-- hallpass:begin (managed by `hallpass install`; edits inside are overwritten) -->';
+const END = '<!-- hallpass:end -->';
+
+const skillFile = () => path.join(ROOT, 'skills', 'hallpass', 'SKILL.md');
+const stripFrontmatter = (t) => t.replace(/^---[\s\S]*?\n---\n/, '');
+
+const MCP_NOTE = `
+## If hallpass is available as MCP tools
+
+Use the tools instead of the shell commands above: \`hallpass_open\` (= \`hallpass open\`), \`hallpass_resume\`, \`hallpass_status\`, \`hallpass_logout\`, \`hallpass_list\`, and \`hallpass_request_credential\` (= \`hallpass request\`: the user types a login into a form, you never see it), then drive the page with the \`browser\` tool (\`command\` is the argv array you would pass to \`agent-browser --session <session>\`; risky clicks are confirmed by the user) and \`browser_screenshot\`. The rules above apply unchanged.
+`;
+
+export function instructionBody() {
+  return `# hallpass: open any site and log in safely\n` + stripFrontmatter(fs.readFileSync(skillFile(), 'utf8')).replace(/^# hallpass[^\n]*\n/, '') + MCP_NOTE;
+}
+
+function upsertBlock(file, body) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const block = `${BEGIN}\n${body.trim()}\n${END}\n`;
+  let cur = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const re = new RegExp(`${BEGIN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n?`);
+  let action;
+  if (re.test(cur)) { cur = cur.replace(re, block); action = 'updated'; }
+  else { cur = (cur && !cur.endsWith('\n') ? cur + '\n' : cur) + (cur ? '\n' : '') + block; action = cur === block ? 'created' : 'appended'; }
+  fs.writeFileSync(file, cur);
+  return action;
+}
+
+function ownFile(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const action = fs.existsSync(file) ? 'updated' : 'created';
+  fs.writeFileSync(file, content);
+  return action;
+}
+
+export const TARGETS = {
+  claude: { desc: 'Claude Code / Claude Desktop skill', run: ({ home }) => { const f = path.join(home, '.claude', 'skills', 'hallpass', 'SKILL.md'); fs.mkdirSync(path.dirname(f), { recursive: true }); const a = fs.existsSync(f) ? 'updated' : 'created'; fs.copyFileSync(skillFile(), f); return { file: f, action: a }; } },
+  codex: { desc: 'OpenAI Codex CLI / IDE (global AGENTS.md)', run: ({ home }) => { const f = path.join(home, '.codex', 'AGENTS.md'); return { file: f, action: upsertBlock(f, instructionBody()) }; } },
+  gemini: { desc: 'Gemini CLI (global GEMINI.md)', run: ({ home }) => { const f = path.join(home, '.gemini', 'GEMINI.md'); return { file: f, action: upsertBlock(f, instructionBody()) }; } },
+  // Antigravity reads real skills (progressive disclosure: only the description is loaded until it is relevant).
+  // Locations confirmed against the docs AND a working Antigravity IDE install: ~/.gemini/config/skills/<name>/SKILL.md (IDE),
+  // ~/.gemini/antigravity-cli/skills/<name>/SKILL.md (CLI, written only if the CLI home exists).
+  antigravity: { desc: 'Google Antigravity IDE/CLI (global skill)', run: ({ home }) => {
+    const put = (f) => { fs.mkdirSync(path.dirname(f), { recursive: true }); const a = fs.existsSync(f) ? 'updated' : 'created'; fs.copyFileSync(skillFile(), f); return a; };
+    const ide = path.join(home, '.gemini', 'config', 'skills', 'hallpass', 'SKILL.md');
+    const out = { file: ide, action: put(ide) };
+    if (fs.existsSync(path.join(home, '.gemini', 'antigravity-cli'))) { const cli = path.join(home, '.gemini', 'antigravity-cli', 'skills', 'hallpass', 'SKILL.md'); out.also = [{ file: cli, action: put(cli) }]; }
+    return out;
+  } },
+  'antigravity-project': { desc: 'Google Antigravity (this workspace: .agents/skills/hallpass)', run: ({ cwd }) => {
+    const f = path.join(cwd, '.agents', 'skills', 'hallpass', 'SKILL.md'); fs.mkdirSync(path.dirname(f), { recursive: true });
+    const a = fs.existsSync(f) ? 'updated' : 'created'; fs.copyFileSync(skillFile(), f); return { file: f, action: a };
+  } },
+  cursor: { desc: 'Cursor (project rule .cursor/rules/hallpass.mdc)', run: ({ cwd }) => { const f = path.join(cwd, '.cursor', 'rules', 'hallpass.mdc'); return { file: f, action: ownFile(f, `---\ndescription: Open websites and log in safely with hallpass (use when a task needs a logged-in browser or a site login)\nalwaysApply: false\n---\n\n${instructionBody()}`) }; } },
+  windsurf: { desc: 'Windsurf (project rule .windsurf/rules/hallpass.md)', run: ({ cwd }) => { const f = path.join(cwd, '.windsurf', 'rules', 'hallpass.md'); return { file: f, action: ownFile(f, `---\ntrigger: model_decision\ndescription: Open websites and log in safely with hallpass (use when a task needs a logged-in browser or a site login)\n---\n\n${instructionBody()}`) }; } },
+  copilot: { desc: 'GitHub Copilot (project .github/copilot-instructions.md)', run: ({ cwd }) => { const f = path.join(cwd, '.github', 'copilot-instructions.md'); return { file: f, action: upsertBlock(f, instructionBody()) }; } },
+  agents: { desc: 'Any tool that reads AGENTS.md (project AGENTS.md)', run: ({ cwd }) => { const f = path.join(cwd, 'AGENTS.md'); return { file: f, action: upsertBlock(f, instructionBody()) }; } },
+};
+
+export function install(target, { home = process.env.HALLPASS_TARGET_HOME || os.homedir(), cwd = process.cwd() } = {}) {
+  const names = target === 'all' ? Object.keys(TARGETS) : [target];
+  const results = [];
+  for (const n of names) {
+    if (!TARGETS[n]) throw new Error(`unknown target "${n}". Choose: ${Object.keys(TARGETS).join(', ')}, all`);
+    results.push({ target: n, ...TARGETS[n].run({ home, cwd }) });
+  }
+  return results;
+}
+
+// ---- MCP client configuration (printed, never written: we do not edit your tools' config files) ----
+export function mcpConfig(target, { npx = false } = {}) {
+  const script = path.join(ROOT, 'bin', 'hallpass.mjs');
+  // --npx: for people who installed from npm (`npx -y hallpass-browser mcp`); default points at this checkout's script
+  const server = npx ? { command: 'npx', args: ['-y', 'hallpass-browser', 'mcp'] } : { command: 'node', args: [script, 'mcp'] };
+  const std = (file, extra = '') => ({ file, format: 'json', snippet: { mcpServers: { hallpass: server } }, note: `Merge into ${file}.${extra}` });
+  const cfg = {
+    claude: { command: npx ? 'claude mcp add hallpass -- npx -y hallpass-browser mcp' : `claude mcp add hallpass -- node "${script}" mcp`, note: 'Run once in a terminal (Claude Code). For Claude Desktop use the JSON in claude_desktop_config.json: { "mcpServers": { "hallpass": { "command": "node", "args": ["<script>", "mcp"] } } }' },
+    cursor: std('~/.cursor/mcp.json (or .cursor/mcp.json in a project)'),
+    gemini: std('~/.gemini/settings.json', ' Or install it as a Gemini CLI extension: gemini extensions install <repo-url> (bundles the skill and this server).'),
+    antigravity: std('~/.gemini/config/mcp_config.json (global, IDE and CLI) or .agents/mcp_config.json (this workspace)', ' Same file Settings > Customizations > Installed MCP Servers edits. Use absolute paths: variable expansion is not documented.'),
+    windsurf: std('~/.codeium/windsurf/mcp_config.json'),
+    vscode: { file: '.vscode/mcp.json (VS Code / GitHub Copilot agent mode)', format: 'json', snippet: { servers: { hallpass: { type: 'stdio', ...server } } }, note: 'Create .vscode/mcp.json with this content.' },
+    codex: { file: '~/.codex/config.toml', format: 'toml', snippet: `[mcp_servers.hallpass]\ncommand = ${JSON.stringify(server.command)}\nargs = ${JSON.stringify(server.args)}\ntool_timeout_sec = 180\n`, note: 'Append to ~/.codex/config.toml. tool_timeout_sec raises the per-call limit (a login can take ~60s).' },
+  };
+  if (!cfg[target]) throw new Error(`unknown target "${target}". Choose: ${Object.keys(cfg).join(', ')}`);
+  return { target, ...cfg[target] };
+}
+export const MCP_TARGETS = ['claude', 'cursor', 'gemini', 'antigravity', 'windsurf', 'vscode', 'codex'];