@anybrowser/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitrii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# anybrowser
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let any AI agent drive a real browser that is already logged in. No browser extension, any browser, any agent that speaks MCP.
+
+## Why
+
+Agents are good at using websites. The browsers they are given are the problem. An automation browser starts empty: no logins, no history, and a fingerprint that many sites block on sight. A browser extension fixes that, but it ties you to one browser and one assistant, it has to be installed and allowed, and the extension may limit which sites the agent can touch.
+
+anybrowser gives the agent a normal browser window with its own profile. You log in once, by hand, and the session stays. Each profile is for one site or purpose, such as `gmail-in-chrome`, so a mistake can only ever reach that one account.
+
+It works with the Chromium browsers you already have (Chrome, Brave, Edge, Arc, Vivaldi, Opera) or Playwright's own Chromium, and with any agent host that supports MCP: Claude Code, Codex, Cursor, Gemini CLI and more.
+
+## How it works
+
+```
+agent session ─┐
+agent session ─┼─ anyb mcp ──► anyb daemon ──► one browser per profile
+agent session ─┘  (stdio)      (one per user)    ├─ work-in-chrome
+                                                 └─ shop-in-brave
+```
+
+- Your agent host runs `anyb mcp`. It starts a background daemon on first use and forwards to it.
+- The daemon owns every browser. Agent sessions share them, and each session works in its own tab.
+- The browser tools are Playwright MCP's, unchanged except that each takes a `profile` argument.
+- A profile's browser closes after 10 idle minutes, and the daemon exits once nothing is connected. Logins are written to disk before either closes.
+- Each profile's traffic passes through a small proxy inside the daemon, which enforces the allowed-sites list below.
+
+## Status
+
+Pre-release, version 0.1. What works: profiles on installed Chromium browsers, login by hand, every Playwright MCP browser tool, shared sessions, idle shutdown, the allowed-sites list, and `anyb install` for Claude Code.
+
+Not yet: Firefox and WebKit, installed-browser detection outside macOS (Playwright's Chromium works everywhere), and `anyb install` for hosts other than Claude Code.
+
+## Quick start
+
+You need Node 22.12 or newer.
+
+```
+npm install -g @anybrowser/cli
+anyb install
+```
+
+Install it globally: your agent host runs the `anyb` command, so it has to be on your `PATH`. `anyb install` registers the MCP server with Claude Code and copies the agent skill. For any other MCP host, `anyb install --print` prints a config snippet to paste.
+
+Make a profile and sign in to it once:
+
+```
+anyb profile add work chrome
+anyb profile login work-in-chrome https://github.com/login
+```
+
+Sign in in the window that opens. Then open a new agent session and ask it to use the `work-in-chrome` profile. `anyb --help` lists every command.
+
+## Safety
+
+An agent in a logged-in browser can do real things, so the design limits how far a mistake can reach:
+
+- **One login per profile.** A profile holds one site or purpose. Whatever goes wrong in `gmail-in-chrome` cannot touch any other account, and none of it touches your everyday browser. A profile can hold more than one login when a task needs it, for example a site that signs in through Google. Every login you add widens what a mistake in that profile can reach, so keep profiles as narrow as the work allows.
+- **Optional allowed-sites list.** A profile can be pinned to the sites it is for. Every page load, every subresource (scripts, images, requests the page makes), every hop of a redirect chain and every WebSocket is checked against the list, and the first one that leaves it is refused. The check is by host and port, so the path of an HTTPS address is invisible to it: allowing `example.com` allows every page on it. A refusal is written to the daemon log and reported to the agent as an error that names the blocked address. A page that loads while some of its own requests are refused is not an error: the result carries a note naming the refused hosts and saying the page may be incomplete. You set the list with `anyb profile add <name> <browser> --allow <list>` or `anyb profile set <id> allowedOrigins=<list>`, and no MCP tool can change it. It is re-read on every request, so an edit applies to a running session at once, and a connection that is already open to a host you take off the list is closed within a second. Entries are literal: `example.com` does not cover `www.example.com`, `*.example.com` does not cover `example.com` itself, and a port has to be written out (`localhost:3000`, or `localhost:*` for any), so most sites need both the apex and the wildcard. A local dev server is reachable only if it is on the list; a pinned profile reaches nothing else on your machine. Two things are not covered. WebRTC connections are not checked. And an agent that can run shell commands can edit `profile.json` itself, so the list means nothing against one. It is a guard rail against a wrong turn, not a sandbox.
+- **Ask before anything irreversible.** The agent is instructed to confirm with you before it posts, sends, buys, deletes or changes settings. This is guidance to the agent, not a technical lock, so watch the window when it matters. It stays visible by default for that reason.
+
+## Development
+
+Work is test-first: a failing test, then the code that makes it pass. `CLAUDE.md` has the rules, and `docs/DESIGN.md` records each design decision and why.
+
+To run from source, clone the repository, then `npm install`, `npm run build` and `npm link`, which puts your build on your `PATH` as `anyb`.
+
+```
+npx playwright install chromium   # once, for the browser tests
+npm test                          # everything
+npm run test:unit                 # no browser
+npm run test:browser              # headless Chromium against local pages only
+npm run typecheck
+npm run format:check
+```
+
+Settings: `ANYBROWSER_HOME` moves the state directory from `~/.anybrowser`. `ANYBROWSER_IDLE_MS`, or `idleMinutes` in `config.json`, changes the idle timeout, and `off` disables it. `ANYBROWSER_HEADLESS=1` forces every browser headless.
+
+MIT licensed.

package/dist/allowedSites.js

@@ -0,0 +1,164 @@
+/**
+ * The allowed-sites list: validation and matching. Each entry is
+ * `[scheme://]host[:port]`:
+ *
+ * - `host` is a domain name, an IPv4 address or a bracketed IPv6 literal. A
+ *   leading `*.` (names only) means any subdomain, NOT the apex: `example.com`
+ *   and `*.example.com` are separate entries, on purpose. A list is a safety
+ *   boundary, so nothing is allowed that was not written down.
+ * - `scheme` is `http` or `https`; without it an entry covers both.
+ * - `port` is a number from 1 to 65535 or `*` for any; without it an entry
+ *   covers the scheme's default port only (80, 443).
+ */
+const HINT = "pass host patterns like example.com or *.example.com";
+/** A domain label: letters or digits (any script) with inner hyphens. */
+const LABEL = /^[\p{L}\p{N}](?:[\p{L}\p{N}-]*[\p{L}\p{N}])?$/u;
+function fail(error) {
+    return { ok: false, error: `${error}; ${HINT}` };
+}
+/** Validates and normalizes one entry (see the module comment for the forms). */
+export function parseAllowedOrigin(raw) {
+    const text = raw.trim();
+    if (text.length === 0) {
+        return fail("allowed-sites entry is empty");
+    }
+    if (/\s/.test(text)) {
+        return fail(`allowed-sites entry '${text}' contains whitespace`);
+    }
+    let rest = text;
+    let scheme = null;
+    const schemeMatch = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(rest);
+    if (schemeMatch) {
+        const name = schemeMatch[1].toLowerCase();
+        if (name !== "http" && name !== "https") {
+            return fail(`allowed-sites entry '${text}' has an unsupported scheme '${name}' (only http and https)`);
+        }
+        scheme = name;
+        rest = rest.slice(schemeMatch[0].length);
+    }
+    if (/[/?#]/.test(rest)) {
+        return fail(`allowed-sites entry '${text}' has a path`);
+    }
+    const wildcard = rest.startsWith("*.");
+    if (wildcard) {
+        rest = rest.slice(2);
+    }
+    let host;
+    let portText;
+    if (rest.startsWith("[")) {
+        const close = rest.indexOf("]");
+        if (close === -1 ||
+            (close !== rest.length - 1 && rest[close + 1] !== ":")) {
+            return fail(`allowed-sites entry '${text}' is not a host pattern`);
+        }
+        host = rest.slice(0, close + 1);
+        portText = close === rest.length - 1 ? undefined : rest.slice(close + 2);
+    }
+    else {
+        const parts = rest.split(":");
+        if (parts.length > 2) {
+            return fail(`allowed-sites entry '${text}' is not a host pattern`);
+        }
+        host = parts[0];
+        portText = parts[1];
+    }
+    let port = null;
+    if (portText !== undefined) {
+        if (portText === "*") {
+            port = "*";
+        }
+        else if (/^\d{1,5}$/.test(portText)) {
+            port = Number(portText);
+            if (port < 1 || port > 65535) {
+                return fail(`allowed-sites entry '${text}' has a port outside 1-65535`);
+            }
+        }
+        else {
+            return fail(`allowed-sites entry '${text}' is not a host pattern`);
+        }
+    }
+    const isIpv6 = host.startsWith("[");
+    if (wildcard && host === "") {
+        return fail(`allowed-sites entry '${text}' needs at least two labels after '*.'`);
+    }
+    if (!isIpv6 && !host.split(".").every((label) => LABEL.test(label))) {
+        return fail(`allowed-sites entry '${text}' is not a host pattern`);
+    }
+    let hostname;
+    try {
+        hostname = new URL(`http://${host}`).hostname;
+    }
+    catch {
+        return fail(`allowed-sites entry '${text}' is not a host pattern`);
+    }
+    const isAddress = isIpv6 || /^\d+\.\d+\.\d+\.\d+$/.test(hostname);
+    if (wildcard && isAddress) {
+        return fail(`allowed-sites entry '${text}' is not a host pattern`);
+    }
+    if (!isAddress) {
+        const labels = hostname.split(".").length;
+        if (wildcard && labels < 2) {
+            return fail(`allowed-sites entry '${text}' needs at least two labels after '*.' (a wildcard over a whole top-level domain allows far too much)`);
+        }
+        if (!wildcard && labels < 2 && hostname !== "localhost") {
+            return fail(`allowed-sites entry '${text}' needs at least two labels (localhost is the one exception)`);
+        }
+    }
+    const normalized = (scheme ? `${scheme}://` : "") +
+        (wildcard ? "*." : "") +
+        hostname +
+        (port === null ? "" : `:${port}`);
+    return {
+        ok: true,
+        entry: { scheme, wildcard, host: hostname, port },
+        normalized,
+    };
+}
+const DEFAULT_PORTS = { http: 80, https: 443 };
+const parsedCache = new Map();
+function parsedEntry(raw) {
+    let cached = parsedCache.get(raw);
+    if (cached === undefined) {
+        const result = parseAllowedOrigin(raw);
+        cached = result.ok ? result.entry : null;
+        parsedCache.set(raw, cached);
+    }
+    return cached;
+}
+/** Whether `url` may be requested by a profile with this list. Non-network schemes (data, blob, about) never leave the browser and are allowed; any other scheme (file, ftp, ...) is not. */
+export function isUrlAllowed(url, entries) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    const scheme = parsed.protocol.slice(0, -1);
+    if (scheme === "data" || scheme === "blob" || scheme === "about") {
+        return true;
+    }
+    const effectiveScheme = scheme === "ws" ? "http" : scheme === "wss" ? "https" : scheme;
+    if (effectiveScheme !== "http" && effectiveScheme !== "https") {
+        return false;
+    }
+    const port = parsed.port === "" ? DEFAULT_PORTS[effectiveScheme] : Number(parsed.port);
+    return entries.some((raw) => {
+        const entry = parsedEntry(raw);
+        if (!entry) {
+            return false;
+        }
+        if (entry.scheme !== null && entry.scheme !== effectiveScheme) {
+            return false;
+        }
+        const hostMatches = entry.wildcard
+            ? parsed.hostname.endsWith(`.${entry.host}`)
+            : parsed.hostname === entry.host;
+        if (!hostMatches) {
+            return false;
+        }
+        return (entry.port === "*" ||
+            port === (entry.port ?? DEFAULT_PORTS[effectiveScheme]));
+    });
+}
+//# sourceMappingURL=allowedSites.js.map

package/dist/allowedSites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowedSites.js","sourceRoot":"","sources":["../src/allowedSites.ts"],"names":[],"mappings":"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"}

package/dist/blockLedger.js

@@ -0,0 +1,111 @@
+const MAX_ENTRIES = 300;
+/** `host:port` of the destination a CONNECT refusal or a ws/https request URL names. */
+function authorityOf(url) {
+    try {
+        const parsed = new URL(url);
+        const defaults = {
+            "https:": "443",
+            "wss:": "443",
+            "http:": "80",
+            "ws:": "80",
+        };
+        const port = parsed.port || defaults[parsed.protocol];
+        return port === undefined ? null : `${parsed.hostname}:${port}`;
+    }
+    catch {
+        return null;
+    }
+}
+function hrefOf(url) {
+    try {
+        return new URL(url).href;
+    }
+    catch {
+        return null;
+    }
+}
+export class BlockLedger {
+    entries = [];
+    seq = 0;
+    changed = new Set();
+    /** A cursor: everything refused after this call is "new". */
+    mark() {
+        return this.seq;
+    }
+    /** Records one refusal made by the proxy. */
+    record(refusal) {
+        this.entries.push({ seq: ++this.seq, refusal });
+        this.entries = this.entries.slice(-MAX_ENTRIES);
+        this.notify();
+    }
+    /**
+     * A failed request whose URL names a destination the proxy refused a
+     * CONNECT to (https, wss, or a ws tunnel). Claims the newest unclaimed
+     * refusal for it; returns false when there is none, i.e. the failure was
+     * not a refusal.
+     */
+    claimConnect(url, attribution) {
+        const wanted = authorityOf(url);
+        if (wanted === null) {
+            return false;
+        }
+        const entry = this.newestUnclaimed((e) => e.refusal.kind === "connect" && authorityOf(e.refusal.url) === wanted);
+        if (!entry) {
+            return false;
+        }
+        entry.claim = attribution(entry.refusal.at);
+        this.notify();
+        return true;
+    }
+    /** A response carrying the proxy's block header for `url`; claims the newest matching plain-HTTP refusal. */
+    claimHttp(url, attribution) {
+        const wanted = hrefOf(url);
+        const entry = this.newestUnclaimed((e) => e.refusal.kind === "http" && hrefOf(e.refusal.url) === wanted);
+        if (!entry) {
+            return false;
+        }
+        entry.claim = attribution(entry.refusal.at);
+        this.notify();
+        return true;
+    }
+    /**
+     * The NEWEST unclaimed refusal matching `matches`. An event trails its own
+     * refusal by moments, so the newest match is the one it describes; older
+     * unclaimed ones (a blocked WebSocket or the browser's own traffic emits no
+     * event, ever) are stale and must not shadow it.
+     */
+    newestUnclaimed(matches) {
+        return this.entries.findLast((e) => e.claim === undefined && matches(e));
+    }
+    /** Entries refused after `mark`, oldest first. */
+    since(mark) {
+        return this.entries.filter((e) => e.seq > mark);
+    }
+    /** Resolves once every refusal after `mark` has been claimed by an event, or after `timeoutMs`. */
+    async whenClaimed(mark, timeoutMs) {
+        const pending = () => this.since(mark).some((e) => e.claim === undefined);
+        if (!pending()) {
+            return;
+        }
+        await new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                this.changed.delete(check);
+                resolve();
+            };
+            const check = () => {
+                if (!pending()) {
+                    done();
+                }
+            };
+            const timer = setTimeout(done, timeoutMs);
+            this.changed.add(check);
+        });
+    }
+    notify() {
+        for (const listener of [...this.changed]) {
+            listener();
+        }
+    }
+}
+//# sourceMappingURL=blockLedger.js.map

package/dist/blockLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blockLedger.js","sourceRoot":"","sources":["../src/blockLedger.ts"],"names":[],"mappings":"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"}