hallpass-browser 1.5.0 → 1.5.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "hallpass-browser",
   "displayName": "Hallpass Browser",
-  "version": "1.5.0",
+  "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.",
   "author": {
     "name": "techgniouss"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "hallpass-browser",
-  "version": "1.5.0",
+  "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.",
   "author": {
     "name": "techgniouss"

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.5.1 (fix: opening any site with a dot in its host)
+
+Fixed
+- **`hallpass open https://example.com` failed on agent-browser 0.41.x** with `Invalid session name 'hp-site-example.com'`: 0.41 only accepts letters, digits, `-` and `_` in a session name, and hallpass named sessions after the host. Dots are now mapped to `_` when talking to agent-browser (the name the agent sees is unchanged). Found by installing 1.5.0 from the registry into a clean folder; the test suites only used `localhost`, which has no dot. A regression test now covers it. **1.5.0 is affected: upgrade.**
+
 ## 1.5.0 (activate, temp-folder uploads, click retry)
 
 Changed

package/README.md

@@ -1,10 +1,29 @@
-# Hallpass Browser
+<div align="center">
 
-**Let an AI agent log in to anything without ever being able to read your password.**
+# 🛂 Hallpass Browser
 
-Hallpass wraps [agent-browser](https://github.com/vercel-labs/agent-browser) with a sealed credential vault, origin pinning, automatic TOTP, output redaction, per-use approval, an irreversible-action gate, and a clean hand-off to *you* (a visible browser window) for CAPTCHAs, push-approval MFA, and first logins. It works with Claude Code, Codex, Gemini CLI, Antigravity, Cursor, Windsurf, VS Code/Copilot, or any agent that has a shell or speaks MCP.
+**Let your AI agent log in to anything, without ever being able to read your password.**
 
-> **Status: beta.** Built and tested on Windows. macOS and Linux code paths exist but have not been run. Not independently security-audited. Read [SECURITY.md](SECURITY.md) before trusting it with anything important.
+[![npm](https://img.shields.io/npm/v/hallpass-browser?color=cb3837&logo=npm)](https://www.npmjs.com/package/hallpass-browser)
+[![CI](https://github.com/techgniouss/hallpass-browser/actions/workflows/ci.yml/badge.svg)](https://github.com/techgniouss/hallpass-browser/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/node/v/hallpass-browser?logo=node.js&logoColor=white)](package.json)
+[![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)](#per-tool-setup)
+
+Works with **Claude Code · Codex · Gemini CLI · Antigravity · Cursor · Windsurf · VS Code/Copilot**, or any agent that has a shell or speaks MCP.
+
+</div>
+
+---
+
+## The problem
+
+You want an agent to "go to my Play Console and publish the release", "check the Supabase dashboard", "download last month's invoices". Today you have two bad options:
+
+1. **Paste your password into the chat.** It is now in a transcript, a log, and a model's context.
+2. **Do the login yourself and hope the agent reuses it.** It works until the session expires, and then you are the bottleneck again.
+
+Hallpass is the third option: the agent gets a **logged-in browser**, and **never sees the secret** that got it there.
 
 ```
  you (own terminal / private form)       agent (any AI tool)
@@ -18,9 +37,44 @@ Hallpass wraps [agent-browser](https://github.com/vercel-labs/agent-browser) wit
         hallpass resume ───────────▶ agent drives the logged-in page
 ```
 
-## Install
+## What it looks like
+
+```console
+# output abbreviated
+$ hallpass open https://play.google.com/console
+{"status":"needs_human","reason":"login","name":"play-console", ...}
+
+# you log in (2-step prompt, passkey, CAPTCHA, whatever) in that window, then tell the agent
+
+$ hallpass resume play-console
+{"status":"logged_in","session":"hp-play-console","via":"human"}
+
+# from now on the agent drives the logged-in page; later runs are headless and instant
+$ hallpass do hp-play-console snapshot
+```
+
+No credential was ever given to the agent. The browser profile keeps the session, so next time `hallpass open` is usually silent.
+
+## Why Hallpass
+
+| | |
+|---|---|
+| 🔒 **Sealed vault** | Logins are AES-GCM encrypted with a key sealed by your OS (DPAPI / Keychain / libsecret). The agent can *use* a login; it cannot *read* one. |
+| 🎯 **Origin pinning** | A password is only ever typed into the exact origin you approved. A look-alike page gets nothing. |
+| 🙋 **Human hand-off** | CAPTCHA, push-approval MFA, passkeys and first logins open a **visible window for you**. Hallpass never fights a CAPTCHA and never types for you. |
+| 🔑 **Automatic TOTP** | Authenticator codes are generated on the fly, never shown. |
+| 🛑 **Irreversible-action gate** | Delete / Publish / Pay / Submit-type clicks need a native confirmation from you, not the model. |
+| 🧾 **Tamper-evident audit log** | Hash-chained record of what agents did. No secrets in it. `hallpass log --verify` |
+| 🧹 **Output redaction** | Secrets are scrubbed from what flows back to the model; password fields refuse to be read. |
+| 🔌 **Works everywhere** | A CLI that prints JSON, an MCP server, and native plugins for Claude Code, Codex and Gemini CLI. |
+
+Built on top of [agent-browser](https://github.com/vercel-labs/agent-browser), which drives Chrome.
 
-Requirements: **Node 20+**. Nothing else to install: [agent-browser](https://www.npmjs.com/package/agent-browser) (the program that drives Chrome) is a dependency of this package, and Chrome for it is downloaded automatically (about 150 MB, once) by `npm i`, or on first use if that step was skipped. This also covers plugin installs (Claude Code, Codex, Gemini), where `npm` never runs: the first `hallpass_open` answers `setting_up` while it installs in the background, and works a minute later. `hallpass setup` does it by hand; `HALLPASS_NO_AUTO_INSTALL=1` turns it all off. On a bare Linux box Chrome may need system libraries: `agent-browser install --with-deps` (hallpass never runs apt for you).
+> **Status: beta.** Read [SECURITY.md](SECURITY.md) (threat model, what is and is not protected) before trusting it with anything important. It has not been independently audited.
+
+## Quick start (about two minutes)
+
+Requirements: **Node 20+**. Nothing else: agent-browser is a dependency and Chrome (about 150 MB, once) is fetched automatically.
 
 ```bash
 npm i -g hallpass-browser      # gives you the `hallpass` command
@@ -28,11 +82,22 @@ hallpass doctor                # checks Node, agent-browser, keystore
 hallpass init --yes            # detects your AI tools and installs the instructions
 ```
 
-(From a clone instead: `npm link` in this folder.)
+Then ask your agent: *"Open my Supabase dashboard and tell me which projects are paused."* It will run `hallpass open`, hand you a window if a login is needed, and carry on.
+
+Just want to try the MCP server without installing? `npx -y hallpass-browser mcp`.
+
+<details>
+<summary><b>Install details, plugin installs, and troubleshooting</b></summary>
+
+Plugin installs (Claude Code, Codex, Gemini) never run `npm`, so the first `hallpass_open` answers `setting_up` while it installs agent-browser and Chrome in the background, and works a minute later. `hallpass setup` does it by hand; `HALLPASS_NO_AUTO_INSTALL=1` turns all of it off. On a bare Linux box Chrome may need system libraries: `agent-browser install --with-deps` (Hallpass never runs apt for you).
+
+From a clone instead: `npm link` in the repository folder.
+
+</details>
 
 ### Per-tool setup
 
-Each tool gets a *native* package where one exists. **"Checked"** says how far I have verified it, honestly.
+Each tool gets a *native* package where one exists. **"Checked"** says how far it has been verified.
 
 | Tool | Install | What you get | Checked |
 |---|---|---|---|
@@ -44,7 +109,7 @@ Each tool gets a *native* package where one exists. **"Checked"** says how far I
 | **Anything else with a shell** | nothing extra: it is a CLI that prints JSON | | tested |
 | **ChatGPT / claude.ai (web)** | not supported | they only reach *remote* connectors, and exposing a local browser controller to the internet is something Hallpass deliberately does not do | |
 
-`hallpass install --for <claude|codex|gemini|antigravity|antigravity-project|cursor|windsurf|copilot|agents|all>` writes the instruction files (only inside a marked block or a file Hallpass owns). `hallpass mcp-config --for <tool> [--npx]` **prints** the MCP configuration for a client; it never edits your config files. `--npx` prints the `npx -y hallpass-browser mcp` form for people who installed from npm.
+`hallpass install --for <claude|codex|gemini|antigravity|antigravity-project|cursor|windsurf|copilot|agents|all>` writes the instruction files (only inside a marked block or a file Hallpass owns). `hallpass mcp-config --for <tool> [--npx]` **prints** the MCP configuration for a client; it never edits your config files.
 
 ## Use it
 
@@ -55,17 +120,26 @@ hallpass open https://play.google.com/console      # the agent runs this; deep l
 | Situation | What happens |
 |---|---|
 | You logged in before (or the page needs no login) | opens headless on that site's saved profile; no credentials involved |
-| Login wall, no stored credential | a visible Chrome window opens; **you** log in (MFA, CAPTCHA, anything); tell the agent; it runs `hallpass resume`. Hallpass never types for you. The profile keeps the session. |
+| Login wall, no stored credential | a visible Chrome window opens; **you** log in (MFA, CAPTCHA, passkey, anything); tell the agent; it runs `hallpass resume`. Hallpass never types for you. The profile keeps the session. |
 | A stored credential matches the site | logs in headless, typing the password without ever showing it (TOTP included) |
 
 Flags: `--headed` (you always log in), `--headless` (never open a window), `--as <name>` (pick the account when several match; Hallpass refuses to guess).
 
-### Add a credential (optional)
+### Add a credential (optional, for hands-free logins)
 
 - **Let the agent ask, you type:** the agent runs `hallpass request <login-url>` (MCP: `hallpass_request_credential`). A one-time form opens in *your* browser; you type the login; the agent never sees it.
 - **Or in your own terminal:** `hallpass add supabase --url https://supabase.com/dashboard/sign-in --origin "https://*.supabase.com" --success-url "https://supabase.com/dashboard/**"`
 - **From a password manager:** `--password-ref op://Vault/Item/password` (also `bw:<id>`, `pass:<path>`): Hallpass stores a pointer and fetches the secret at login.
 
+## How it compares
+
+| Approach | Agent sees the password? | Survives session expiry? | Handles CAPTCHA / MFA? | Stops "delete account" clicks? |
+|---|---|---|---|---|
+| Paste the password into the prompt | **Yes** | yes | no | no |
+| Export cookies / reuse your own browser profile | No, but it holds a full session | until it expires | no | no |
+| Headless script with env-var credentials | Yes (in the process the agent controls) | yes | no | no |
+| **Hallpass** | **No** | yes (vault) or by profile | **Hands off to you** | **Yes, native confirmation** |
+
 ## Safety controls
 
 | Control | What it does | How to turn it on |
@@ -87,28 +161,46 @@ Flags: `--headed` (you always log in), `--headless` (never open a window), `--as
 
 Housekeeping: `hallpass sessions`, `hallpass prune --older-than 30d`, `hallpass init`, `hallpass doctor`. Containers/CI without an OS keyring can opt in to `HALLPASS_KEYSTORE=file` (weaker: protects only against other OS users). Cloud browsers work through agent-browser's own `AGENT_BROWSER_PROVIDER` setting; credentials are still resolved locally.
 
-## Tests
+## FAQ
+
+**Can the agent just read the password out of the page?** No. Typed values are cleared after entry, and the MCP tool refuses to read password fields. A shell agent can still call `agent-browser` directly, which is why the vault, not the browser, is the trust boundary. See [SECURITY.md](SECURITY.md).
+
+**Does it solve CAPTCHAs?** No, on purpose. It hands them to you in a visible window.
+
+**Does it send my data anywhere?** No. The vault, profiles and audit log live on your machine. Cloud browsers are opt-in.
+
+**Do I have to store credentials?** No. The default is that *you* log in once in a visible window and the profile keeps the session.
+
+**Which sites work?** Anything agent-browser can open. Sign-in detection is heuristic (it ships a 28-page corpus in 7 languages), so when it guesses wrong it asks you instead of failing.
+
+## Development and tests
 
 ```bash
+git clone https://github.com/techgniouss/hallpass-browser && cd hallpass-browser
+npm install
 npm test              # no browser: crypto/vault, TOTP (RFC 6238), origins, redaction, policy, audit chain, references, credential form, export/import, trust, packaging
 npm run test:browser  # real Chrome: logins, hand-offs, MCP server, action gate, 28-page detection corpus (opens a visible window or two)
 npm run test:dialog   # Windows: the real native approval dialog, answered by clicks and keypresses
 npm run test:all
 ```
 
-Everything runs against local mock sites. The detection corpus is structural re-creations of common sign-in pages, not copies of real sites, so it measures regressions, not real-world accuracy.
+Everything runs against local mock sites. The detection corpus is structural re-creations of common sign-in pages, not copies of real sites, so it measures regressions, not real-world accuracy. CI runs the unit and browser suites on Linux, Windows and macOS.
 
 ## Known limits
 
-- Only **Windows** has been exercised. macOS (Keychain, osascript) and Linux (libsecret, zenity) paths exist but are unrun; `.github/workflows/ci.yml` is written to cover them and has never been run.
+- **Windows** is the most exercised platform. macOS and Linux pass CI, but CI uses the file keystore there; the real Keychain (macOS) and libsecret (Linux) paths and the zenity/osascript dialogs have not been run by hand.
 - **agent-browser compatibility:** tested against 0.41.x (0.27.x also needs a Chrome older than about 155: its headed window loses the page on newer Chrome). Other releases may change output formats; `hallpass doctor` tells you which version you have.
 - Logins inside **iframes or shadow DOM** are not auto-filled (the page still reads as a login wall, so a person is asked). Sites needing extra fields (e.g. AWS IAM account ID) need a site recipe (not built, see [ROADMAP](ROADMAP.md)).
-- **Passkeys/WebAuthn**, reading **email/SMS codes**, and a **separate-user broker** are not built.
+- **Passkeys/WebAuthn** can be used by *you* in the hand-off window, but Hallpass cannot store or replay them. Reading **email/SMS codes** and a **separate-user broker** are not built.
 - The **action gate** is a heuristic on labels: it catches common dangerous buttons, not every one, and a shell agent can bypass it by calling `agent-browser` directly.
 - Vaults are bound to one OS account; move machines with `export` / `import`.
 
-## Contributing, security, license
+## Contributing
+
+Issues and pull requests are welcome, especially: **macOS and Linux testing**, **site recipes**, and **more sign-in detection fixtures**. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the [ROADMAP](ROADMAP.md); look for issues labelled `good first issue`. Please report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+
+If Hallpass saves you from pasting a password into a chat, a ⭐ helps other people find it.
 
-[CONTRIBUTING.md](CONTRIBUTING.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · [SECURITY.md](SECURITY.md) (how to report a vulnerability) · [CHANGELOG.md](CHANGELOG.md) · [ROADMAP.md](ROADMAP.md) · MIT licensed ([LICENSE](LICENSE)).
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · [CHANGELOG.md](CHANGELOG.md) · MIT licensed ([LICENSE](LICENSE)).
 
 Use it only on accounts you own and where automation is permitted by the site's terms. Hallpass does not solve CAPTCHAs or bypass bot protection: it hands them to you.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "hallpass-browser",
-  "version": "1.5.0",
+  "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": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hallpass-browser",
-  "version": "1.5.0",
+  "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",

package/src/ab.mjs

@@ -125,13 +125,16 @@ export function signInManually(profile, url, { timeoutMs = 15 * 60_000 } = {}) {
   });
 }
 
+/** agent-browser 0.41+ only accepts [A-Za-z0-9_-] in a session name, but hallpass names sites after their host ("hp-site-example.com"). Dots become "_" on the way in; hallpass keeps using the dotted name everywhere else. */
+export const abSession = (s) => String(s).replace(/\./g, '_');
+
 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];
+    const f = ['--session', abSession(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(','));
@@ -211,6 +214,6 @@ export class Browser {
   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);
+    return r.ok && Array.isArray(r.json?.data?.sessions) && r.json.data.sessions.includes(abSession(this.session));
   }
 }

package/src/mcp.mjs

@@ -17,7 +17,7 @@ import { startBackgroundSetup } from './setup.mjs';
 export { guardBrowser };
 import { profilesDir } from './paths.mjs';
 
-const VERSION = '1.5.0';
+const VERSION = '1.5.1';
 
 export const INSTRUCTIONS = `hallpass opens websites in a browser you can drive, and handles login safely.
 

package/src/sessions.mjs

@@ -2,7 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { Browser } from './ab.mjs';
+import { Browser, abSession } from './ab.mjs';
 import { Redactor } from './redact.mjs';
 import { profilesDir, stateDir } from './paths.mjs';
 import { audit } from './audit.mjs';
@@ -40,7 +40,7 @@ export function listSessions() {
   return fs.readdirSync(profilesDir(), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => {
     const t = lastUsed(e.name);
     return {
-      name: e.name, kind: e.name.startsWith('site-') ? 'saved-login-site' : 'credential-profile', running: running.has('hp-' + e.name),
+      name: e.name, kind: e.name.startsWith('site-') ? 'saved-login-site' : 'credential-profile', running: running.has(abSession('hp-' + e.name)),
       last_used: t ? new Date(t).toISOString() : null, age_days: t ? Math.floor((Date.now() - t) / 86400e3) : null,
       size_mb: Math.round(dirSize(path.join(profilesDir(), e.name)) / 1e5) / 10,
     };