hallpass-browser 0.0.0-stage → 1.5.1

package/SECURITY.md

@@ -0,0 +1,104 @@
+# hallpass security model
+
+Goal: an AI agent can **use** a credential to log in, but has no path to **read** it.
+This document says exactly what that does and does not protect against. Read it before trusting the tool.
+
+## What hallpass guarantees
+
+| Property | How |
+|---|---|
+| No command prints a secret | The CLI has no `get`/`reveal`/`export`. `vault.unseal()` is called from one place (`login.mjs`) and its result never reaches stdout. |
+| Entering secrets needs a human | `hallpass add` refuses to run without a real TTY and reads the password with echo off. The agent's shell has no TTY. (`--stdin-json` exists for piping from a password manager; whoever runs that already holds the secret.) |
+| Secrets rest encrypted | AES-256-GCM per entry. The 256-bit master key is sealed by Windows DPAPI (CurrentUser), macOS Keychain, or libsecret, and is never written in the clear. |
+| Entries cannot be quietly re-pointed | Approved origins and selectors are authenticated as GCM AAD. Editing `entries/<name>.json` to add an attacker origin makes the entry fail its integrity check. |
+| Secrets only go to approved origins | Before each fill the page origin must match the origins approved at `add` time (https only, `localhost` exempt, wildcards are subdomain-only). A redirect to another origin (phishing, open redirect, compromised link) gets nothing: `failed: origin_not_allowed`. |
+| No time-of-check/time-of-use gap | Fields are targeted through a per-run random attribute set during the probe. If the page navigates before the fill, the selector matches nothing and nothing is typed. A hostile page cannot pre-plant the attribute (unknown nonce). Hidden (honeypot) inputs are never selected. |
+| Secrets do not appear in process listings | Passwords go to `agent-browser` over **stdin** (`batch`), not argv. |
+| Output is scrubbed | All output from the browser is passed through a redactor that removes the password / TOTP seed in raw, JSON-escaped, URL-encoded and base64 forms. hallpass never returns page text; URLs are returned as origin + path only (no query/fragment, where tokens live). |
+| No lockout loops | A rejected password is never retried. TOTP is retried once, and never submitted in the last 4 s of its window. |
+| Human-only steps stay human | CAPTCHA and non-TOTP MFA return `needs_human`; hallpass does not try to solve or bypass them. |
+
+Verified by `npm run test:e2e`, which logs in against a local site with a honeypot field, a phishing redirect, a wrong password, a TOTP step and a CAPTCHA, and then scans everything hallpass printed, every file in the vault, and agent-browser's own logs for the password and the TOTP seed.
+
+### MCP specifics
+
+| Property | How |
+|---|---|
+| No credential tool | The MCP server exposes no tool that adds, reads or exports secrets; credentials enter only via `hallpass add` in a human terminal. |
+| Confined to hallpass's browsers | `browser` / `browser_screenshot` accept only `hp-*` sessions, so a model cannot steer your other agent-browser sessions. |
+| Narrow command set | An allowlist of page commands; long flags allowlisted (blocks `--cdp`, `--proxy`, `--headers`, `--init-script`, `--profile`, ...); no `eval`, `cookies`, `storage`, `state`, `download`, `network`. `upload` is allowed only with vetted files and a person's approval (below). `file:`/`javascript:`/`data:`/`chrome:` URLs rejected. This stops a prompt-injected page from turning the model into a local-file reader or cookie exfiltrator *via this tool*. |
+| Injection marking | Page content is returned inside `AGENT_BROWSER_PAGE_CONTENT nonce=...` markers. |
+| Clean protocol | stdout carries only JSON-RPC; tool errors come back in-band. |
+
+An agent that also has a general shell is not constrained by these limits (it can run `agent-browser` directly). They protect MCP-only clients and add defence in depth.
+
+### Approval, policy, gate, entry, references
+
+| Property | How |
+|---|---|
+| Human-only approval | `--require-approval` shows a native dialog (WinForms / osascript / zenity). The agent cannot click it; with no GUI or no answer the result is **deny**. Verified by a test that answers the real dialog with a physical click. 1-hour grants are HMAC-signed with a key derived from the vault master key. |
+| Policy before decryption | Expiry, use limits and approval are checked before any secret is unsealed; they live in the entry's authenticated metadata. |
+| Lockout protection | A rejected password/TOTP disables automatic login for that entry (`credential_locked`) across processes until a person clears it. |
+| Action gate | In the MCP `browser` tool and `hallpass do`, controls whose label/aria-label/value/title match irreversible patterns (delete, publish, pay, submit, ...) need a native confirmation. Fail-closed. |
+| Auto-installed browser | agent-browser is a pinned-range dependency (`~0.41.1`); if it is missing, hallpass installs that same range with `npm` into `~/.hallpass/runtime` (a folder agents are fenced off from) and pins the resulting absolute path. It is resolved from hallpass's own dependency or that folder BEFORE any PATH lookup, so a planted `agent-browser` earlier on PATH is ignored. Trust is in the npm package and its GitHub-release binary download, as for any npm dependency; `HALLPASS_NO_AUTO_INSTALL=1` disables all of it. `--with-deps` (apt as root) is never run automatically. |
+| File upload | `upload` only takes files of a short allowlist of types (app bundles, images, video, documents, archives, plain text), resolved through symlinks, never inside a dot-folder or the hallpass home / OS config locations, with private-key blocks sniffed out of text files. Each batch needs a native dialog naming the files and the site ("Allow once" / "for 1 hour" for that site, held in memory of the MCP server only). `HALLPASS_UPLOAD=off` disables it; `=allow` skips the dialog but keeps the vetting. A shell agent that calls `agent-browser` directly bypasses this, as with the gate. |
+| Screenshots | `screenshot` can only write a file name inside a private (0700) hallpass folder; the agent never chooses a path. |
+| Read-only | `HALLPASS_READONLY=1` on the MCP server permits observation only; set by the person in the client config. |
+| Just-in-time entry | `hallpass request` serves a form on 127.0.0.1 only, behind a 256-bit one-time path, with Host + Origin checks (DNS-rebinding / cross-site posts), a CSRF token, strict CSP, no caching, an 8 KB cap, 5-minute-class expiry and single use. It refuses to overwrite an existing entry. |
+| References | `--password-ref` stores a pointer; the secret is fetched at login and never stored. Reference strings are validated against a strict character set before any CLI call. **Registering a reference is terminal-only**, otherwise an agent could pin a password-manager item to an attacker origin. |
+| Audit | `hallpass log` is a hash chain (edits, deletions, reordering are detectable; a same-user process can still delete the whole file). Contains names, origin+path, verbs, outcomes; never secrets. |
+| Export | The only path that serialises vault contents. Terminal-only, scrypt + AES-256-GCM under a passphrase the person chooses. |
+
+### Hardening added in the second audit
+
+| Property | How |
+|---|---|
+| Secrets are used only when typed | Decryption, password-manager calls, approval dialogs and use-counting happen at the moment a credential must be typed. A still-valid saved session consumes no use, shows no dialog and touches no password manager. Expiry (metadata only) is checked up front. |
+| The programs we trust cannot be swapped from the shell | The OS helpers that hold the master key or show approval dialogs (PowerShell, osascript, security, secret-tool, zenity, ...) are launched by **absolute system path**, never via PATH/cwd; a test forbids bare-name launches. There is **no** environment override for the agent-browser binary (it receives every typed secret), and its absolute path is **pinned** in `config.json` after first resolution; `hallpass doctor --repin` (terminal only) changes it. |
+| Destructive/state-clearing commands need a person | `remove`, `unlock`, `add --force` over an existing entry, `export`, `import`, `doctor --repin` and registering a reference all require a real terminal. An agent can add a *new* login (`request`, or `add --stdin-json` for a new name) but cannot delete or overwrite yours, nor reset a lockout. |
+| Typed secrets do not linger in the page | After typing, password / one-time-code fields are emptied (a single-page app otherwise keeps them after a rejected attempt, and `get value` returns them in the clear). The MCP `browser` tool also refuses `get value` on password fields. Snapshots mask them. |
+| Approval dialog defaults to Deny | Focus starts on Deny and Esc denies, so a stray Enter or Space keypress while you type elsewhere cannot approve. Tested with real keypresses. |
+| The one-time form URL is not handed to the agent | When a window could be opened for you, the agent is not told the URL (otherwise it could submit its own credential first and consume your form). One pending form per origin; at most 12 forms per 10 minutes. |
+| Reserved names | Credential names starting with `site-` are refused: they would collide with the saved-session profile of credential-less sites. |
+| Gate coverage | The action gate also reads `id`/`class`/`name`/`data-testid` (catches icon-only "trash" buttons), asks about `find last|nth` targets it cannot identify, and in `HALLPASS_GATE=all` gates `press` and `dialog` as well. |
+
+## What hallpass does NOT protect against
+
+Be honest with yourself about these.
+
+- **You are the last line of defence on two prompts.** The credential form displays the origin a password will be pinned to, but the *agent chooses that URL*: read it. Likewise the approval dialog shows the target; do not approve sign-ins you did not start.
+- **The action gate is a label heuristic.** A dangerous control with an innocuous label ("OK", "Continue") passes. Shell agents can skip it by calling `agent-browser` directly. Treat it as a seatbelt, not a cage.
+- **A shell agent can run `agent-browser get value` on a password field in the short window between typing and the scrub** (or while a person is mid-handoff in a visible window, when fields are deliberately left filled). The MCP tool refuses this; direct shell access cannot be fenced.
+- **Preloading code into hallpass itself** (e.g. `NODE_OPTIONS=--require evil.js hallpass login x`) runs arbitrary code as you inside the process that holds decrypted secrets. That is the same-user limit below, not something hallpass can detect or stop. `hallpass doctor` warns about safety-relevant `HALLPASS_*` overrides it can see.
+- **The credential form is plain HTTP on loopback.** Other local processes of your user could in principle observe loopback traffic; a hostile local process is already outside this threat model (see next point).
+- **`HALLPASS_KEYSTORE=file`** keeps the master key in a file next to the vault. Use it only where no OS keystore exists (containers, CI).
+1. **A same-user process can decrypt the vault.** DPAPI/Keychain bind secrets to *your OS account*, not to "hallpass". An agent that is allowed to run arbitrary shell commands as you could, in principle, call the OS crypto API itself. hallpass removes the *easy and accidental* paths and the prompt-injection paths; it is not an OS sandbox. Mitigations, in order of strength:
+   - Run the agent as a different OS user, or in a container/VM, with only the `hallpass` binary and the sealed vault reachable via a socket/sudo wrapper (not provided).
+   - Add the deny rules from `hallpass harden` to Claude Code settings (best-effort string matching, not a boundary).
+   - Keep high-value accounts (banking, root cloud accounts, registrars) out of the vault.
+2. **The logged-in session is the agent's.** Once logged in, the agent can read cookies/localStorage (`agent-browser state save`, `eval`) and do anything the account can do. hallpass protects the *password and TOTP seed* (which allow persistent access from anywhere), not the *session*. Use least-privilege accounts, short-lived sessions (`hallpass logout --wipe`), and the confirmation rule in the skill for irreversible actions.
+3. **Browser profiles hold session cookies** under `~/.hallpass/profiles/<name>` in Chrome's own format. Treat that directory like a logged-in browser.
+4. **A TOTP seed in the vault weakens 2FA** into "something the agent's machine has". That is the trade-off for hands-free MFA; omit the TOTP secret for accounts where you want a human tap on every login.
+5. **Compromised approved origins.** If an origin you approved (or a subdomain under a wildcard) serves attacker content, it can receive the credential. Prefer exact origins over wildcards.
+6. **Login forms in iframes / shadow DOM / canvas** are not auto-detected (they fail closed: nothing is typed).
+7. **macOS/Linux backends are untested.** Only Windows DPAPI is exercised by the test-suite. On macOS the master key is briefly visible in `security`'s argv once, at vault creation.
+8. **Terms of service.** Some sites forbid automated logins. You are responsible for using this on accounts you own and where automation is permitted.
+
+## Reporting
+
+Open an issue with a reproduction. Do not include real credentials.
+
+## Reporting a vulnerability
+
+Please **do not open a public issue** for a security problem.
+
+- Use GitHub's private vulnerability reporting: the repository's **Security → Report a vulnerability** button (maintainers: enable *Private vulnerability reporting* in the repository settings).
+- Include: affected version (`hallpass --version`), OS, what an attacker or a careless agent can do, and a minimal reproduction. **Never include real credentials.**
+- What counts: any path by which an agent (or a web page) can *read* a stored secret, make Hallpass type one into the wrong origin, bypass an approval dialog or the terminal-only rules, or read/forge the audit log undetectably. Weaknesses already listed under "What hallpass does NOT protect against" are known limits, not vulnerabilities, but improvements are welcome.
+- Expect an acknowledgement within a few days and a coordinated fix and disclosure. This is a volunteer project; there is no bug bounty.
+
+Supported versions: the latest release only (the project is pre-1.x-stable and moves quickly).
+
+## Using this software safely
+
+Hallpass is a beta, single-author tool that has **not been independently audited**. Do not use it for accounts whose compromise would be severe (banking, domain registrars, root cloud accounts) until it has been reviewed by people other than its author.

package/bin/hallpass

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Puts `hallpass` on the Bash tool PATH when installed as a Claude Code plugin (bin/ is added to PATH).
+exec node "$(dirname "$0")/hallpass.mjs" "$@"

package/bin/hallpass.mjs

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+// hallpass - let an agent USE credentials without ever being able to READ them.
+// stdout is always one JSON document. Exit codes: 0 ok / logged_in, 10 needs_human, 1 failed, 2 usage.
+import { parseArgs } from 'node:util';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import * as vault from '../src/vault.mjs';
+import { backend, masterKey } from '../src/keystore.mjs';
+import { normalizeAllowed, parseOrigin } from '../src/origin.mjs';
+import { parseTotpInput, base32Decode } from '../src/totp.mjs';
+import { isTTY, ask, askHidden, readAllStdin } from '../src/prompt.mjs';
+import { login, openSite, resume, status, logout, clearState } from '../src/login.mjs';
+import { findBinary, TESTED_AGENT_BROWSER } from '../src/ab.mjs';
+import { home } from '../src/paths.mjs';
+import { install, mcpConfig, TARGETS, MCP_TARGETS } from '../src/install.mjs';
+import { parseExpiry, resetUses, revokeGrant } from '../src/policy.mjs';
+import { audit, readLog, verifyLog } from '../src/audit.mjs';
+import { startCredentialRequest, describeRequest } from '../src/request.mjs';
+import { runBrowser } from '../src/act.mjs';
+import { exportVault, importVault } from '../src/portable.mjs';
+import { listSessions, pruneSessions } from '../src/sessions.mjs';
+import { parseRef, resolveRef, SecretUnavailable } from '../src/refs.mjs';
+import { serve } from '../src/mcp.mjs';
+import { setup, inspect as inspectRuntime, withLock, recordFailure } from '../src/setup.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const out = (obj, code = 0) => { process.stdout.write(JSON.stringify(obj) + '\n'); process.exit(code); };
+const usage = (msg) => out({ status: 'usage_error', message: msg }, 2);
+
+const HELP = `hallpass - agent logins with credentials the agent can use but not read
+
+  Run these in YOUR OWN terminal (they need a real keyboard):
+    hallpass add <name> --url <login-url> [--origin <url>]... [options]
+    hallpass add <name> ... --force          replace an existing entry
+    hallpass remove <name>
+    hallpass do <session> <command...>      run a browser command through the same guard + irreversible-action gate
+    hallpass request <login-url> [--name n]  a PERSON enters a login in a one-time local form; safe for agents to start
+    hallpass sessions                       saved browser sessions: age, size, running
+    hallpass prune [--older-than 30d] [--dry-run]   forget saved sessions not used lately (credentials untouched)
+    hallpass export <file> / import <file>  passphrase-encrypted backup to move machines (terminal only)
+    hallpass init [--yes]                   detect your AI tools and set them up
+    hallpass log [--tail n] [--verify]     what agents did with your logins (hash-chained, no secrets)
+    hallpass unlock <name>                  re-enable auto-login after a rejected password
+
+  The agent runs these:
+    hallpass open <url> [--headed|--headless] [--as <name>]
+                                            open ANY site. Stored credential for its origin -> headless login.
+                                            None -> headless on a saved profile; if a login wall appears, a visible
+                                            window opens and the person logs in. --headed forces person-logs-in mode.
+    hallpass list                            names, URLs, approved origins (no secrets)
+    hallpass show <name>                     metadata for one entry
+    hallpass login <name> [--headed|--headless] [--wait <sec>] [--manual] [--timeout <sec>]
+    hallpass resume <name> [--timeout <sec>] continue after a person solved a CAPTCHA / MFA
+    hallpass status <name>
+    hallpass logout <name> [--wipe]          close the browser (--wipe also deletes its profile)
+
+  Setup:
+    hallpass setup                           install what hallpass needs (agent-browser and Chrome); automatic on first use, safe to re-run
+    hallpass doctor
+    hallpass harden                          print Claude Code deny-rules that fence off the vault
+    hallpass install --for <tool>            teach an AI tool how to use hallpass. tool = claude | codex | gemini |
+                                            antigravity | cursor | windsurf | copilot | agents | all
+    hallpass mcp-config --for <tool>         print the MCP server config for: claude cursor gemini antigravity
+                                            windsurf vscode codex   (then the tool gets hallpass_* and browser tools)
+    hallpass mcp                             run as an MCP server over stdio (clients launch this themselves)
+    hallpass install-skill [--dir <path>]    Claude-only shortcut for: install --for claude
+
+  add options:
+    --origin <url>            extra approved origin (repeatable), e.g. https://accounts.google.com or https://*.example.com
+    --username-selector / --password-selector / --otp-selector / --submit-selector <css>
+    --success-url <glob>      e.g. "https://app.example.com/**"  (strongly recommended)
+    --success-text <text>     text that only appears when logged in
+    --require-approval        every sign-in needs a native yes/no dialog that only the person can click (no GUI = deny)
+    --expires <12h|30d|2w|date>   credential stops working after this
+    --max-uses <n>            credential stops working after n sign-ins
+    --lock-navigation         refuse navigation outside approved origins for the whole session
+    --password-ref <ref>      use a password manager instead of storing the password: op://Vault/Item/field | bw:<item-id> | pass:<path>
+    --totp-ref <ref>          same, for the one-time code; --username <u> to skip the username prompt (terminal only)
+    --stdin-json              read {"username","password","totp"} from stdin (e.g. piped from a password manager)
+`;
+
+const [cmd, ...rest] = process.argv.slice(2);
+if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') { process.stderr.write(HELP); process.exit(cmd ? 0 : 2); }
+
+function opts(options, allowPositionals = true) {
+  try { return parseArgs({ args: rest, options, allowPositionals, strict: true }); }
+  catch (e) { return usage(e.message); }
+}
+const needName = (positionals) => { if (!positionals[0]) usage(`usage: hallpass ${cmd} <name>`); return positionals[0]; };
+const mask = (u) => (u.includes('@') ? u[0] + '***@' + u.split('@')[1] : u.slice(0, 1) + '***');
+const safe = (fn) => { try { return fn(); } catch (e) { return out({ status: 'failed', reason: 'error', detail: e.message }, 1); } };
+const exitFor = (r) => out(r, r.status === 'logged_in' ? 0 : r.status === 'needs_human' ? 10 : 1);
+
+switch (cmd) {
+  case '--version': case '-v': case 'version': out({ name: 'hallpass', version: JSON.parse(fs.readFileSync(path.join(HERE, '..', 'package.json'), 'utf8')).version }); break;
+  case 'add': {
+    const { values: v, positionals } = opts({
+      url: { type: 'string' }, origin: { type: 'string', multiple: true },
+      'username-selector': { type: 'string' }, 'password-selector': { type: 'string' },
+      'otp-selector': { type: 'string' }, 'submit-selector': { type: 'string' },
+      'success-url': { type: 'string' }, 'success-text': { type: 'string' },
+      'lock-navigation': { type: 'boolean' }, 'stdin-json': { type: 'boolean' }, force: { type: 'boolean' },
+      'require-approval': { type: 'boolean' }, expires: { type: 'string' }, 'max-uses': { type: 'string' },
+      username: { type: 'string' }, 'password-ref': { type: 'string' }, 'totp-ref': { type: 'string' },
+    });
+    const name = needName(positionals);
+    if (!vault.validName(name)) usage('name must be lowercase letters, digits, . _ - (max 63)');
+    if (!v.url) usage('--url is required (the login page)');
+    const loginOrigin = parseOrigin(v.url);
+    if (!loginOrigin) usage('--url must be https:// (http:// only for localhost)');
+    if (vault.exists(name) && !v.force) usage(`"${name}" already exists. Use --force to replace it.`);
+    if (vault.exists(name) && !isTTY()) usage('replacing an existing credential needs a real terminal: it also clears lockout, approval grants and use limits, so a person must do it.');
+    if (name.startsWith('site-')) usage('names starting with "site-" are reserved');
+
+    const allowedSet = new Set([loginOrigin]);
+    for (const o of v.origin ?? []) {
+      const n = normalizeAllowed(o);
+      if (!n) usage(`invalid --origin "${o}" (https only; wildcards must be https://*.domain.tld)`);
+      allowedSet.add(n);
+    }
+    const allowed = [...allowedSet];
+
+    let username, password, totpRaw = '', passwordRef = null, totpRef = null;
+    if (v['password-ref'] || v['totp-ref']) {
+      // Registering a reference is as sensitive as typing a password: it decides where a vaulted secret can be sent.
+      if (!isTTY() || v['stdin-json']) usage('references (--password-ref/--totp-ref) can only be registered by a person in a real terminal.');
+      passwordRef = v['password-ref'] || null;
+      totpRef = v['totp-ref'] || null;
+      for (const r of [passwordRef, totpRef].filter(Boolean)) if (!parseRef(r)) usage('unsupported or unsafe reference. Use op://Vault/Item/field, bw:<item-id>, or pass:<path> (letters, digits, space and _ . @ : + / ? = ~ - only).');
+      try { if (passwordRef) resolveRef(passwordRef, 'password'); } catch (e) { usage('could not read the password reference: ' + (e instanceof SecretUnavailable ? e.message : 'unknown error')); }
+      username = v.username || await ask('Username / email: ');
+      password = 'reference-only'; // placeholder so the length check below is skipped for refs
+    } else if (v['stdin-json']) {
+      try { ({ username, password, totp: totpRaw = '' } = JSON.parse(await readAllStdin())); } catch { usage('--stdin-json expects {"username","password","totp"?}'); }
+    } else {
+      if (!isTTY()) usage('hallpass add needs a real terminal so the password is typed by you, not by the agent. Open your own terminal and run it there (or use --stdin-json to pipe from a password manager).');
+      process.stderr.write(`Adding "${name}" - approved origins: ${allowed.join(', ')}\n`);
+      username = await ask('Username / email: ');
+      password = await askHidden('Password (hidden): ');
+      if (password !== await askHidden('Confirm password:  ')) usage('passwords did not match');
+      totpRaw = await askHidden('TOTP secret or otpauth:// URI (hidden, Enter to skip): ');
+    }
+    if (!username) usage('username is required');
+    if (!passwordRef && (!password || password.length < 6)) usage('password must be at least 6 characters');
+
+    let totpCfg;
+    if (totpRaw) {
+      try { totpCfg = parseTotpInput(totpRaw); base32Decode(totpCfg.secret); } catch (e) { usage('bad TOTP secret: ' + e.message); }
+    }
+    let expiresAt = null;
+    if (v.expires) { expiresAt = parseExpiry(v.expires); if (!expiresAt) usage('--expires must look like 12h, 30d, 2w or an ISO date'); }
+    const maxUses = v['max-uses'] ? Number(v['max-uses']) : null;
+    if (v['max-uses'] && !(Number.isInteger(maxUses) && maxUses > 0)) usage('--max-uses must be a positive integer');
+    const selectors = Object.fromEntries(Object.entries({
+      username: v['username-selector'], password: v['password-selector'], otp: v['otp-selector'], submit: v['submit-selector'],
+    }).filter(([, x]) => x));
+
+    safe(() => vault.put(name, {
+      url: v.url, allowed, userHint: mask(username), hasTotp: !!totpCfg || !!totpRef, source: passwordRef ? parseRef(passwordRef).kind : 'vault',
+      selectors, successUrl: v['success-url'] || null, successText: v['success-text'] || null,
+      lockNavigation: !!v['lock-navigation'], createdAt: new Date().toISOString(),
+      requireApproval: !!v['require-approval'], expiresAt, maxUses,
+    }, { username, ...(passwordRef ? { passwordRef } : { password }), ...(totpRef ? { totpRef } : {}), ...(totpCfg ? { totp: totpCfg } : {}) }));
+    clearState(name); // a fresh credential gets a fresh chance
+    resetUses(name); revokeGrant(name);
+    audit('add', { name, origins: allowed.join(' ') });
+    out({ status: 'saved', name, sealed_with: backend().name, user: mask(username), totp: !!totpCfg, allowed_origins: allowed,
+      note: 'Secrets are encrypted at rest and cannot be read back with hallpass.' });
+    break;
+  }
+  case 'list': out({ entries: safe(() => vault.list()) }); break;
+  case 'show': { const { positionals } = opts({}); out({ name: positionals[0], ...safe(() => vault.meta(needName(positionals))) }); break; }
+  case 'remove': {
+    const { positionals } = opts({});
+    const name = needName(positionals);
+    if (!isTTY()) usage('hallpass remove needs a real terminal: it permanently deletes a stored login.');
+    safe(() => vault.remove(name));
+    clearState(name);
+    try { logout(name, { wipe: true }); } catch { /* browser may not be running */ }
+    out({ status: 'removed', name });
+    break;
+  }
+  case 'login': {
+    const { values: v, positionals } = opts({ headed: { type: 'boolean' }, headless: { type: 'boolean' }, manual: { type: 'boolean' }, wait: { type: 'string' }, timeout: { type: 'string' } });
+    const name = needName(positionals);
+    if (v.headed && v.headless) usage('choose --headed or --headless, not both');
+    exitFor(await login(name, { headed: v.headless ? false : v.headed ? true : undefined, manual: v.manual, wait: v.wait && Number(v.wait), timeout: v.timeout && Number(v.timeout) }).catch((e) => ({ status: 'failed', reason: 'error', detail: e.message })));
+    break;
+  }
+  case 'open': {
+    const { values: v, positionals } = opts({ headed: { type: 'boolean' }, headless: { type: 'boolean' }, as: { type: 'string' }, wait: { type: 'string' }, timeout: { type: 'string' } });
+    if (!positionals[0]) usage('usage: hallpass open <url> [--headed|--headless] [--as <credential>]');
+    if (v.headed && v.headless) usage('choose --headed or --headless, not both');
+    exitFor(await openSite(positionals[0], { mode: v.headed ? 'headed' : v.headless ? 'headless' : 'auto', as: v.as, wait: v.wait && Number(v.wait), timeout: v.timeout && Number(v.timeout) }).catch((e) => ({ status: 'failed', reason: 'error', detail: e.message })));
+    break;
+  }
+  case 'resume': {
+    const { values: v, positionals } = opts({ timeout: { type: 'string' } });
+    exitFor(await resume(needName(positionals), { timeout: v.timeout && Number(v.timeout) }).catch((e) => ({ status: 'failed', reason: 'error', detail: e.message })));
+    break;
+  }
+  case 'status': { const { positionals } = opts({}); out(safe(() => status(needName(positionals)))); break; }
+  case 'logout': { const { values: v, positionals } = opts({ wipe: { type: 'boolean' } }); out(safe(() => logout(needName(positionals), { wipe: v.wipe }))); break; }
+
+  case 'unlock': {
+    const { positionals } = opts({});
+    const name = needName(positionals);
+    safe(() => vault.meta(name));
+    if (!isTTY()) usage('hallpass unlock needs a real terminal: it re-enables automatic logins after a rejected password, so a person must do it.');
+    if ((await ask(`Re-enable automatic login for "${name}"? Only do this if the password is now correct on the site. Type yes: `)).toLowerCase() !== 'yes') usage('cancelled');
+    clearState(name);
+    out({ status: 'unlocked', name });
+    break;
+  }
+  case 'request': {
+    // Safe for an agent to run: a PERSON types the credential into a one-time local form; the agent never sees it.
+    const { values: v, positionals } = opts({ name: { type: 'string' }, ttl: { type: 'string' } });
+    if (!positionals[0]) usage('usage: hallpass request <login-url> [--name <name>]');
+    let req;
+    try { req = await startCredentialRequest({ url: positionals[0], name: v.name, ttlSec: Number(v.ttl) || 600 }); }
+    catch (e) { out({ status: 'failed', reason: 'cannot_start', detail: e.message }, 1); }
+    process.stdout.write(JSON.stringify(describeRequest(req)) + '\n');
+    const r = await req.wait();
+    out(r, r.status === 'saved' ? 0 : 1);
+    break;
+  }
+  case 'do': {
+    // hallpass do <session> <agent-browser command...>   same guard + irreversible-action gate as the MCP browser tool
+    const args = process.argv.slice(3);
+    const session = args.shift();
+    if (args[0] === '--') args.shift();
+    if (!session || !args.length) usage('usage: hallpass do <session> <command...>   e.g. hallpass do hp-site-example.com click @e3');
+    const r = runBrowser({ session, command: args });
+    process.stdout.write(r.text + '\n'); // page output, like agent-browser itself (not JSON)
+    process.exit(r.isError ? 1 : 0);
+    break;
+  }
+  case 'sessions': out({ sessions: safe(() => listSessions()) }); break;
+  case 'prune': {
+    const { values: v } = opts({ 'older-than': { type: 'string' }, 'dry-run': { type: 'boolean' } }, false);
+    out(safe(() => pruneSessions({ olderThan: v['older-than'] || '30d', dryRun: !!v['dry-run'] })));
+    break;
+  }
+  case 'export': {
+    // The only path that turns vault contents into portable bytes: a person, in a terminal, with a passphrase only they know.
+    const { values: v, positionals } = opts({ force: { type: 'boolean' } });
+    const file = positionals[0];
+    if (!file) usage('usage: hallpass export <file>');
+    if (!isTTY()) usage('hallpass export needs a real terminal: it writes your credentials (encrypted) to a file, so a person must do it.');
+    if (fs.existsSync(file) && !v.force) usage(`${file} already exists (use --force)`);
+    const p1 = await askHidden('Export passphrase (12+ chars, hidden): ');
+    if (p1 !== await askHidden('Repeat passphrase:                    ')) usage('passphrases did not match');
+    const bundle = safe(() => exportVault(p1));
+    fs.writeFileSync(file, JSON.stringify(bundle), { mode: 0o600 });
+    out({ status: 'exported', file, note: 'Encrypted with your passphrase. Without it the file is useless; with it, it contains all your logins: store it carefully.' });
+    break;
+  }
+  case 'import': {
+    const { values: v, positionals } = opts({ force: { type: 'boolean' } });
+    const file = positionals[0];
+    if (!file) usage('usage: hallpass import <file> [--force]');
+    if (!isTTY()) usage('hallpass import needs a real terminal (it asks for the export passphrase).');
+    let bundle;
+    try { bundle = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { usage('cannot read that file'); }
+    const pass = await askHidden('Export passphrase (hidden): ');
+    out({ status: 'imported', ...safe(() => importVault(bundle, pass, { force: !!v.force })) });
+    break;
+  }
+  case 'init': {
+    // Detect installed AI tools and show (or, with --yes, apply) the user-level setup. Project-level rule files
+    // (Cursor, Windsurf, Copilot, AGENTS.md) are written by running `hallpass install --for <tool>` inside a project.
+    const { values: v } = opts({ yes: { type: 'boolean' } }, false);
+    const h = process.env.HALLPASS_TARGET_HOME || os.homedir();
+    const probes = { claude: '.claude', codex: '.codex', gemini: '.gemini', cursor: '.cursor', windsurf: '.codeium' };
+    const detected = Object.entries(probes).filter(([, d]) => fs.existsSync(path.join(h, d))).map(([k]) => k);
+    const userLevel = detected.filter((t) => ['claude', 'codex', 'gemini'].includes(t));
+    const plan = detected.map((t) => ({ tool: t, instructions: `hallpass install --for ${t}`, mcp: MCP_TARGETS.includes(t) ? `hallpass mcp-config --for ${t}` : null, scope: userLevel.includes(t) ? 'user' : 'project (run inside a project)' }));
+    const applied = v.yes ? userLevel.flatMap((t) => safe(() => install(t))) : [];
+    out({ status: 'ok', detected, plan, applied, applied_note: v.yes ? 'User-level instructions installed. MCP configs are printed by mcp-config; they are never written for you.' : 'Dry run. Re-run with --yes to install the user-level instructions.' });
+    break;
+  }
+  case 'log': {
+    const { values: v } = opts({ tail: { type: 'string' }, verify: { type: 'boolean' } }, false);
+    out(v.verify ? { chain: verifyLog() } : { entries: readLog({ tail: Number(v.tail) || 50 }), chain: verifyLog() });
+    break;
+  }
+  case 'doctor': {
+    const { values: dv } = opts({ repin: { type: 'boolean' } }, false);
+    if (dv.repin) { // changes WHICH agent-browser receives your typed secrets: a person must do this
+      if (!isTTY()) usage('hallpass doctor --repin needs a real terminal: it decides which program receives your typed secrets.');
+      out({ status: 'repinned', agent_browser: safe(() => findBinary({ repin: true, human: true })) });
+    }
+    const checks = [];
+    const add = (name, okk, detail) => checks.push({ name, ok: okk, detail });
+    add('node >= 20', Number(process.versions.node.split('.')[0]) >= 20, process.versions.node);
+    try { const bin = findBinary(); const rt = inspectRuntime(); add('chrome for agent-browser', rt.browser !== false, rt.browser === false ? 'not installed: run hallpass setup' : rt.browser ? 'installed' : 'could not tell (older/newer agent-browser)'); const r = spawnSync(bin, ['--version'], { encoding: 'utf8' }); const ver = /(\d+\.\d+)\.\d+/.exec(r.stdout || '')?.[1]; add('agent-browser', r.status === 0, `${(r.stdout || '').trim()} (pinned: ${bin})`); add('agent-browser compatibility', !(rt.outdated), ver === TESTED_AGENT_BROWSER ? `${ver}.x is the tested release line` : rt.outdated ? `agent-browser ${rt.version} is older than the ${TESTED_AGENT_BROWSER}.x line; on current Chrome its visible login window can lose the page. Run: hallpass setup` : `NOTE: hallpass was tested with ${TESTED_AGENT_BROWSER}.x; you have ${ver || 'unknown'}. It may work, but report anything odd`); } catch (e) { add('agent-browser', false, e.message); }
+    try { const b = backend(); const k = masterKey({ create: false }); add('keystore', true, `${b.name}; master key ${k ? 'present' : 'not created yet (created on first "hallpass add")'}`); } catch (e) { add('keystore', false, e.message); }
+    add('home dir', true, home());
+    try { const c = verifyLog(); add('audit log', c.ok, c.ok ? `${c.entries} entries, chain intact` : `TAMPERED or damaged at entry ${c.broken_at}: ${c.reason}`); } catch (e) { add('audit log', false, e.message); }
+    // env vars that weaken a safety control for whoever sets them (an agent can set them on its own command line)
+    const weak = [['HALLPASS_GATE', 'off', 'irreversible-action gate disabled'], ['HALLPASS_UPLOAD', 'allow', 'file uploads no longer need your approval (files are still vetted)'], ['HALLPASS_NO_UI', '1', 'no dialogs: approvals deny, notifications off'], ['HALLPASS_KEYSTORE', 'file', 'master key kept in a file, not the OS keystore']].filter(([k, v]) => process.env[k] === v);
+    add('environment', true, weak.length ? 'NOTE: ' + weak.map(([k, v, why]) => `${k}=${v} (${why})`).join('; ') : 'no safety-relevant overrides set');
+    out({ status: checks.every((c) => c.ok) ? 'ok' : 'problems', checks }, checks.every((c) => c.ok) ? 0 : 1);
+    break;
+  }
+  case 'harden': {
+    const h = home().replace(/\\/g, '/');
+    out({
+      note: 'Merge into ~/.claude/settings.json. Best-effort fence: stops the agent from casually opening the vault. The real guarantee is that hallpass has no command that prints a secret.',
+      permissions: { deny: [
+        `Read(${h}/**)`, `Edit(${h}/**)`, `Write(${h}/**)`, 'Read(~/.hallpass/**)', 'Edit(~/.hallpass/**)',
+        'Bash(hallpass add:*)', 'Bash(*ProtectedData*)', 'Bash(*master.key*)', 'Bash(*.hallpass*)',
+        'Bash(*find-generic-password*)', 'Bash(*secret-tool*)',
+      ] },
+    });
+    break;
+  }
+  case 'setup': {
+    const { values: v } = opts({ background: { type: 'boolean' } }, false);
+    try { out({ ...withLock(() => setup({ log: (m) => m && process.stderr.write(`hallpass setup: ${m}\n`) })), ...inspectRuntime() }); }
+    catch (e) { if (v.background) recordFailure(e.message); out({ status: 'failed', reason: 'setup_failed', detail: e.message }, 1); }
+    break;
+  }
+  case 'mcp': serve(); break; // stdio MCP server; stays alive until the client closes stdin
+  case 'install': {
+    const { values: v } = opts({ for: { type: 'string' } }, false);
+    if (!v.for) usage('usage: hallpass install --for <' + [...Object.keys(TARGETS), 'all'].join('|') + '>');
+    out({ status: 'installed', results: safe(() => install(v.for)), next: 'Also run: hallpass mcp-config --for <tool>  to connect the MCP server (optional, recommended for IDE agents).' });
+    break;
+  }
+  case 'mcp-config': {
+    const { values: v } = opts({ for: { type: 'string' }, npx: { type: 'boolean' } }, false);
+    if (!v.for) usage('usage: hallpass mcp-config --for <' + MCP_TARGETS.join('|') + '> [--npx]');
+    out(safe(() => mcpConfig(v.for, { npx: !!v.npx })));
+    break;
+  }
+  case 'install-skill': {
+    const { values: v } = opts({ dir: { type: 'string' } }, false);
+    const dest = path.join(v.dir || path.join(os.homedir(), '.claude', 'skills'), 'hallpass');
+    fs.mkdirSync(dest, { recursive: true });
+    fs.copyFileSync(path.join(HERE, '..', 'skills', 'hallpass', 'SKILL.md'), path.join(dest, 'SKILL.md'));
+    out({ status: 'installed', path: path.join(dest, 'SKILL.md') });
+    break;
+  }
+  default: usage(`unknown command "${cmd}". Run: hallpass help`);
+}

package/bin/postinstall.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// npm postinstall: fetch Chrome for agent-browser right away so the first `hallpass open` is instant.
+// Best effort by design: this must never make `npm i -g hallpass-browser` fail (offline, proxy, locked-down CI).
+// Anything missed here is installed on first use anyway (src/setup.mjs).
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+if (process.env.HALLPASS_NO_AUTO_INSTALL === '1' || process.env.CI || process.env.HALLPASS_SKIP_POSTINSTALL === '1') process.exit(0);
+const r = spawnSync(process.execPath, [path.join(path.dirname(fileURLToPath(import.meta.url)), 'hallpass.mjs'), 'setup'], { stdio: ['ignore', 'ignore', 'inherit'], timeout: 15 * 60_000 });
+if (r.status !== 0) process.stderr.write('hallpass: could not finish browser setup now; it will be retried automatically on first use (or run: hallpass setup)\n');
+process.exit(0);

package/gemini-extension.json

@@ -0,0 +1,13 @@
+{
+  "name": "hallpass-browser",
+  "version": "1.5.1",
+  "description": "Open any website in a browser your AI agent can drive, and log in safely: credentials the agent can use but never read, with a hand-off to you for CAPTCHA/MFA.",
+  "mcpServers": {
+    "hallpass": {
+      "command": "node",
+      "args": ["${extensionPath}${/}bin${/}hallpass.mjs", "mcp"],
+      "cwd": "${extensionPath}"
+    }
+  },
+  "contextFileName": "GEMINI.md"
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "hallpass-browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.5.1",
+  "description": "Open any website in a browser your AI agent can drive and log in safely: credentials the agent can use but never read, with a hand-off to you for CAPTCHA/MFA. CLI, MCP server, and plugins for Claude Code, Codex, Gemini CLI and Antigravity.",
+  "keywords": [
+    "ai-agent",
+    "browser",
+    "login",
+    "credentials",
+    "mcp",
+    "agent-browser",
+    "claude-code",
+    "codex",
+    "gemini",
+    "antigravity",
+    "security"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "techgniouss"
+  },
+  "type": "module",
+  "bin": {
+    "hallpass": "bin/hallpass.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    ".claude-plugin",
+    ".codex-plugin",
+    ".codex-mcp.json",
+    ".agents/plugins",
+    ".mcp.json",
+    "gemini-extension.json",
+    "GEMINI.md",
+    "README.md",
+    "SECURITY.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node --test test/unit.test.mjs test/audit.test.mjs test/refs.test.mjs test/request.test.mjs test/ops.test.mjs test/trust.test.mjs test/packaging.test.mjs test/setup.test.mjs",
+    "test:e2e": "node --test --test-concurrency=1 test/e2e.test.mjs",
+    "test:mcp": "node --test --test-concurrency=1 test/mcp.test.mjs",
+    "test:gate": "node --test --test-concurrency=1 test/gate.test.mjs",
+    "test:upload": "node --test --test-concurrency=1 test/upload.test.mjs",
+    "test:detect": "node --test --test-concurrency=1 test/detect.test.mjs",
+    "test:dialog": "node --test --test-concurrency=1 test/dialog.test.mjs",
+    "test:browser": "node --test --test-concurrency=1 test/e2e.test.mjs test/mcp.test.mjs test/gate.test.mjs test/upload.test.mjs test/detect.test.mjs",
+    "test:all": "npm test && npm run test:browser && npm run test:dialog",
+    "prepublishOnly": "npm test",
+    "postinstall": "node bin/postinstall.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/techgniouss/hallpass-browser.git"
+  },
+  "homepage": "https://github.com/techgniouss/hallpass-browser#readme",
+  "bugs": {
+    "url": "https://github.com/techgniouss/hallpass-browser/issues"
+  },
+  "dependencies": {
+    "agent-browser": "~0.41.1"
+  }
+}