anyagent-bridge 0.5.0

package/docs/INSTALL.md

@@ -0,0 +1,138 @@
+# Installation
+
+anyagent-bridge runs on **macOS, Windows, and Linux**. Pick one of the three
+install paths below. For what the bridge is and how to use it once running, see
+the top-level [README](../README.md); for the security model, read
+[SECURITY.md](SECURITY.md) before exposing it to anything but localhost.
+
+## Requirements
+
+- **Node.js ≥ 18** (`node -v`). The bridge uses only Node's built-ins plus a few
+  small npm packages; the one native dependency is `node-pty`.
+- **A C/C++ toolchain** so `node-pty` can build (only for the npx / from-source
+  paths — the Docker image builds it for you):
+  - **macOS** — Xcode Command Line Tools: `xcode-select --install`.
+  - **Linux** — `build-essential` + `python3` (Debian/Ubuntu:
+    `sudo apt-get install -y build-essential python3`).
+  - **Windows** — Visual Studio Build Tools (C++ workload) + Python 3. The
+    simplest route is to install Node via the official installer with the
+    "Tools for Native Modules" checkbox ticked.
+- **The agent CLI(s) you want to drive** — e.g. `claude` (Claude Code) or
+  `codex` — installed and working in your own terminal. The bridge launches
+  whatever you register; it does not bundle any agent.
+- **Optional:** Docker (only for the container path or for Stage 4 sandboxing),
+  and a tunnel CLI (`devtunnel`, `cloudflared`, or `tailscale`) for remote access.
+
+---
+
+## Path A — `npx` (fastest way to try it)
+
+```bash
+npx anyagent-bridge
+```
+
+This downloads and runs the bridge in one step, then prints an access URL with a
+token. Open it in your browser. Useful flags:
+
+```bash
+npx anyagent-bridge --port 8080            # listen on a different port
+npx anyagent-bridge --host 0.0.0.0         # expose on your LAN (token is the only gate)
+npx anyagent-bridge --tunnel devtunnel     # also open a remote tunnel
+npx anyagent-bridge --help                 # all flags
+```
+
+**State location caveat.** Run this way, the generated token and runtime state
+live inside the package's install directory under npm's cache, not in your
+current folder. That is fine for a quick try, but for daily or persistent use
+prefer **Path B (from source)** or **Path C (Docker)**, where you control where
+state lives.
+
+---
+
+## Path B — From source (recommended for regular use)
+
+```bash
+git clone https://github.com/elon-choo/anyagent-bridge.git
+cd anyagent-bridge
+npm ci                       # installs deps and builds node-pty
+cp config.example.json config.json
+npm start
+```
+
+Edit `config.json` to register your agents, projects, and (optionally) auth or
+tunnel settings — every field is documented inline in `config.example.json` and
+in the README. Environment overrides go in a `.env` file (copy `.env.example`).
+
+On first boot the server generates an access token and saves it to
+`.data/auth.json`; the startup banner prints the full URL with the token. Re-runs
+reuse the saved token.
+
+To keep it running in the background, use your platform's process manager
+(`pm2 start npm --name anyagent-bridge -- start`, a `systemd` unit, a `launchd`
+agent, or Windows Task Scheduler).
+
+---
+
+## Path C — Docker / docker-compose (isolated, reproducible)
+
+```bash
+git clone https://github.com/elon-choo/anyagent-bridge.git
+cd anyagent-bridge
+docker compose up -d --build
+docker compose logs bridge          # the startup banner prints your access token
+```
+
+Then open <http://127.0.0.1:3001> and paste the token. The compose file:
+
+- Publishes the port on **127.0.0.1 only** (localhost). The bridge binds
+  `0.0.0.0` *inside* the container; the `ports:` mapping is what controls host
+  exposure — keep it on `127.0.0.1` unless you front it with an authenticated
+  tunnel/proxy.
+- Persists the access token and audit log (both under `.data`) in a named volume
+  (`bridge-data`), so they survive `docker compose down && up`. (The session list
+  in `sessions.json` lives outside `.data` and is not in the volume.)
+
+**Reading the token without the logs:** pin your own instead —
+set `BRIDGE_AUTH_TOKEN` in the `environment:` block of `docker-compose.yml`.
+
+**Agents inside the container.** The image ships the bridge plus a `bash` shell,
+**not** the agent CLIs. To launch `claude`/`codex` from within the container you
+must either:
+
+1. derive your own image (`FROM anyagent-bridge:local`, then install the agent
+   CLI and bake in or mount its credentials), or
+2. run the bridge on the host (Path A/B) where your agents already live, and use
+   Docker only for Stage 4's per-session sandbox (which runs each session in a
+   *separate*, operator-supplied agent image).
+
+Plain shell access and the file API work in the container as-is.
+
+---
+
+## Updating
+
+- **npx** — always fetches the latest published version; nothing to update.
+- **From source** — `git pull && npm ci`.
+- **Docker** — `git pull && docker compose up -d --build`.
+
+## Uninstalling
+
+- **From source** — delete the cloned folder; it holds `.data/` (including your
+  token) and there is no Docker volume to clean up.
+- **Docker** — `docker compose down -v` (the `-v` also deletes the `bridge-data`
+  volume and its token), then delete the cloned folder.
+- **npx** — `npm cache clean --force` removes the cached package.
+
+## Troubleshooting
+
+- **`node-pty` build fails** — you are missing the toolchain above. Install it,
+  then `npm ci` again. On Windows, reopen the terminal after installing the
+  Build Tools so the new `PATH` is picked up.
+- **Port already in use (`EADDRINUSE`)** — pick another port with `--port` /
+  `PORT=` / `config.json`.
+- **The agent dropdown is empty or "command not found"** — the agent CLI is not
+  on the `PATH` of the process running the bridge. Verify it works in the same
+  shell, or set an absolute `command` in `config.json`.
+- **Remote access not connecting** — see the README's "Remote access" section;
+  confirm the tunnel CLI is installed and logged in, and set
+  `auth.oauth.callbackBaseUrl` to your public URL when using OAuth behind a tunnel.

package/docs/ROADMAP.md

@@ -0,0 +1,168 @@
+# Roadmap
+
+anyagent-bridge ships in stages. Stage 1 is a self-contained, useful tool on its own;
+each later stage adds a layer for safer remote access without breaking the core. The
+codebase deliberately leaves clean extension points (seams) for these stages.
+
+## Stage 1 — Portable core ✅ (current)
+
+The "it works" core, with nothing macOS- or person-specific:
+
+- `TerminalSession` class with PTY spawn/respawn (automatic re-creation + backoff).
+- Multi-viewer broadcast over a WebSocket protocol.
+- Scrollback buffer (10,000 lines), heartbeat, and dead-connection detection.
+- Session persistence (`sessions.json`).
+- Universal agent profiles — register **any** command; launch via `startAgent`, drive via `sendAgent`/raw `input`.
+- File-management API (browse/read/write/rename/move/delete/upload/download) behind a path whitelist.
+- Crash guards (`uncaughtException`, `unhandledRejection`, `SIGINT`, `SIGTERM`).
+- Token auth with constant-time comparison and a rate-limiting structure.
+- Cross-platform shell selection and plain `fs.*` file access (no platform-specific brokers).
+
+## Stage 2 — Free tunnel adapters ✅
+
+Zero-/low-config remote access without paying for anything, via pluggable
+adapters spawned as external CLIs (no new npm dependencies). Disabled by default;
+when off, missing, or misconfigured the server runs exactly like Stage 1
+(localhost-only) and never crashes.
+
+- **Microsoft Dev Tunnels** (default) — one-time `devtunnel user login`; the URL rotates per run unless you pre-create a tunnel (`tunnelId`).
+- **Cloudflare Quick Tunnel** (`cloudflare-quick`) — no account; ephemeral `*.trycloudflare.com` URL; testing-grade (≈200 req cap, no SSE).
+- **Tailscale** (`tailscale`) — needs `tailscale up` + Funnel enabled in the tailnet ACL; stable `*.ts.net` URL; may need sudo.
+- **cloudflared named tunnel** (`cloudflared-named`) — needs a Cloudflare account + zone, a pre-created tunnel and DNS route; stable custom hostname.
+
+Config: the `tunnel` block in `config.json` (default `enabled:false`,
+`provider:"devtunnel"`). Env overrides: `BRIDGE_TUNNEL_ENABLED`,
+`BRIDGE_TUNNEL_PROVIDER`, `BRIDGE_TUNNEL_HOSTNAME`. Control at runtime:
+`GET|POST /api/tunnel/{status,start,stop,restart}`. Add a 5th provider by
+dropping an adapter under `server/tunnel/adapters/` and registering it in
+`server/tunnel/registry.js`.
+
+## Stage 3 — Authentication & sessions ✅
+
+Login on top of Stage 1's static token, all opt-in. With OAuth off, no TOTP
+enrolled, and `requireLogin` false, the bridge behaves exactly like Stage 2 (the
+static token works everywhere). Zero new npm dependencies — built on Node's
+`crypto` and the global `fetch`. Lives in `server/auth/`.
+
+- **Signed sessions** — HMAC-SHA256 tokens, expiring and revocable, tracked by id
+  and persisted (`.data/auth-sessions.json`). Primary browser transport is an
+  httpOnly `aab_session` cookie (the WS upgrade and fetches carry it automatically);
+  `X-Session-Token` / `Authorization: Bearer` / `?session=` work for API clients.
+- **TOTP 2FA** (RFC 6238) — enroll from the UI (`/api/auth/totp/setup` → `confirm`),
+  scan the `otpauth://` QR, get one-time recovery codes. A replay guard tracks the
+  last accepted step counter. Operator-only.
+- **OAuth** — Google (auth-code + PKCE S256) and GitHub (auth-code + state). CSRF
+  `state` is single-use and TTL-bounded. Identity is checked against a per-provider
+  allowlist (`allowedEmails` / `allowedLogins`); an empty allowlist fails closed
+  unless `claimFirstUser` is on (first successful login claims the bridge, TOFU).
+- **The one rule** — the static token is a *direct* credential UNLESS `requireLogin`
+  is set OR a TOTP secret is confirmed; then it becomes *login-only* (must be
+  exchanged, with the 2FA code, for a session). This is what makes 2FA real.
+
+Config: the `auth` block in `config.json` (or `BRIDGE_*` env overrides — keep
+OAuth client secrets in env). Routes: `POST /api/auth/login`, `/logout`,
+`GET /api/auth/config|me|sessions`, `DELETE /api/auth/sessions/:id`,
+`GET /api/auth/oauth/:provider/{start,callback}`, `/api/auth/totp/{status,setup,confirm,disable}`.
+
+Defense-in-depth added here: a CSRF Origin check on cookie-authenticated writes
+(bearer/token clients are exempt — they are not CSRF-able), an expanded file-API
+denylist for secret-bearing dotfiles, and a bounded OAuth pending-state map.
+
+Known residuals (deferred to Stage 4 hardening): `getClientIP` trusts
+`X-Forwarded-For` unconditionally — behind an untrusted proxy the per-IP login
+rate limit is evadable (the global cap still applies); set `callbackBaseUrl` when
+OAuth is exposed so the redirect URI is not derived from request headers.
+
+## Stage 4 — Sandboxing & safety ✅
+
+Four opt-in safety layers in one subsystem, `server/safety/` (entry `index.js` exports
+`createSafetyManager`; `manager.js` orchestrates; `sandbox.js` / `audit.js` / `redact.js`
+/ `clientip.js` are pure leaves). All default **off** — with `safety.enabled` false the
+server is byte-identical to Stage 3 (proven by `test/stage4-boot.js`). Zero new npm
+dependencies: the Docker layer spawns the `docker` CLI (reusing `tunnel/detect`),
+everything else is Node core. `server/index.js` is touched only at marked seams;
+`auth._isOperator` is reused for the operator gate (auth internals untouched).
+
+- **Docker isolation** — the whole session PTY runs `docker run` (the agent launches
+  inside the container, so `startAgent`/`sendToAgent` are unchanged). Only sessions
+  with a bounded **project dir** are sandboxed (never bind-mounts `$HOME`); the project
+  mounts at `/workspace`. Operator-supplied `image` (must contain the agent CLI).
+  `-it` for an in-container TTY; default limits (`--memory`/`--cpus`/`--pids-limit`/
+  `--security-opt no-new-privileges`); opt-in hardening (`--read-only`/`--cap-drop ALL`/
+  `--user`, the last Linux-only). Secrets reach the container as `-e NAME` (values off
+  the process table); the docker client env is a minimal allowlist (never the full
+  `process.env`); `BRIDGE_*`/token are denied even if listed. `network` defaults to
+  `bridge`. `onDockerMissing` = `host` (fall back, default) | `refuse`. Repeated fast
+  container exits auto-degrade to a host shell (no respawn storm). **Graceful, never
+  crashes.**
+- **Kill-switch** — `POST /api/safety/kill/:id` (SIGKILL pty + `docker rm -f`),
+  `POST /api/safety/panic` (kill all + sweep `aab-<installId>-sess-*` strays + optional
+  tunnel stop + optional **lock**), `POST /api/safety/unlock`. The lock gates only new
+  agent launches (never the shell — no remote soft-brick) and persists across restart.
+  Operator-only on REST and WebSocket (`{type:"panic"|"kill"}`). Graceful `destroy()`
+  also reaps its container (no leak); a per-install container-name nonce so panic never
+  kills another install's containers.
+- **Audit logging** — append-only JSONL under `.data/audit/` via one `res.on('finish')`
+  middleware (REST mutations) + WS seams (`agent.start`/`agent.send`); raw keystrokes
+  are intentionally not logged. Date + size rotation, retention prune by strict regex,
+  synchronous ordered append, `flushSync` on exit. Every field is redacted before write.
+- **Secret redaction** — the audit log is **always** scrubbed (AWS/OpenAI/GitHub/Slack/
+  Google keys, JWT, PEM blocks, plus the bridge's own token + session secret by exact
+  match). Live PTY-stream redaction is opt-in (`redaction.liveStream`, default off so the
+  stream stays byte-identical) with a boundary hold-back for split tokens/PEM/ANSI and a
+  bounded `maxHoldBytes` (overflow masks the partial rather than leaking it).
+
+**Stage 3 residual closed:** `trustProxy` (default off, opt-in) makes the client IP for
+rate limiting + audit come from the direct socket peer instead of a spoofable
+`X-Forwarded-For`; `true`/`N` trust the nearest / Nth proxy hop. (The OAuth
+`redirect_uri`-from-Host residual remains a documented boot warning — hardening it would
+require changing the shipped Stage-3 auth route, so it is deferred.)
+
+Config: the `safety` block in `config.json` (`BRIDGE_SAFETY_ENABLED`, `BRIDGE_SANDBOX_*`,
+`BRIDGE_AUDIT_ENABLED`, `BRIDGE_REDACT_LIVE`, `BRIDGE_TRUST_PROXY` env overrides).
+Verified: `test/stage4-smoke.js` (32 unit) + `test/stage4-boot.js` (9 integrated,
+byte-identical-off + safety-on + audit recording), **plus a live run against a real
+Docker daemon (colima, 2026-06-26):** the real `spawnSpecFor` argv launches a sandbox
+container (the project bind-mounted at `/workspace`, `--network none`, memory/cpu/pid
+limits, `--security-opt no-new-privileges`, secrets passed by name), the session shell
+runs *inside* it (`uname` → Linux), and `panic` kills + sweeps every
+`aab-<installId>-sess-*` container with no leak while the lock gates new agent launches.
+
+## Stage 5 — Packaging & distribution ✅
+
+One-command installs plus the docs to run the bridge safely on any of the three
+platforms. Zero new runtime dependencies and **no changes to the Stage 1–4 server** —
+the launcher only sets environment variables the server already reads.
+
+- **npx** — `bin/anyagent-bridge.js` (declared in `package.json`'s `bin`) boots the
+  server in-process and maps friendly flags (`--port` / `--host` / `--token` /
+  `--tunnel [provider]` / `--no-tunnel`) onto the existing `PORT` / `HOST` /
+  `BRIDGE_*` env vars. Because dotenv does not override an already-set variable, the
+  precedence is CLI flag > `.env` > `config.json`, and `npx anyagent-bridge` stays
+  equivalent to `node server/index.js`. Unknown flags and bad values fail with exit 1.
+- **Docker** — a multi-stage `Dockerfile` builds `node-pty` in a toolchain stage and
+  ships a slim non-root runtime (`tini` as PID 1, a Node-only `/health` healthcheck,
+  `HOST=0.0.0.0` so the published port reaches it). `docker-compose.yml` publishes on
+  `127.0.0.1` only and persists the token / sessions / audit log in the `bridge-data`
+  named volume (read the token from `docker compose logs`). `.dockerignore` keeps host
+  state and secrets out of the build context. The image carries the bridge + a `bash`
+  shell but **not** the agent CLIs — documented, with two ways to add an agent.
+- **Publishing hygiene** — a `files` allowlist in `package.json` publishes only the app
+  (`bin`/`server`/`client`/`docs`/`test` + `config.example.json` + `.env.example`); a
+  `npm pack --dry-run` confirms `config.json`, `.data/`, `.env`, and `sessions.json` are
+  never in the tarball (38 files, no secrets).
+- **Docs** — `docs/INSTALL.md` (npx · from source · Docker, per-OS toolchain notes,
+  updating / uninstalling / troubleshooting), `docs/SECURITY.md` (threat model, safe
+  defaults, what to enable before exposing it, disclaimers), and `docs/WALKTHROUGH.md`
+  (end-to-end tour + screenshot capture guide). README gains a Quick start.
+
+Verified offline: `node bin/anyagent-bridge.js --version/--help`, error paths exit 1, a
+real boot through the launcher with `/health` returning **HTTP 200** and the banner
+reflecting the `--port`/`--token` flags, `npm pack --dry-run` (file set above), and the
+Stage 4 suites still green (`npm test` → 32 + 9 pass). **Verified live (Docker via colima,
+2026-06-26):** `docker compose up --build` builds the multi-stage image, the container
+runs **healthy**, `/health` returns 200 on the localhost-published port, it runs
+**non-root** (`uid 1000`), `node-pty` loads and spawns a real PTY inside the container,
+and the named volume persists the access token across `down && up` (the banner's token
+source flips `generated`→`file`). Screenshot PNGs remain deferred to a live capture
+(`docs/WALKTHROUGH.md` ships the text walkthrough + capture steps).

package/docs/SECURITY.md

@@ -0,0 +1,85 @@
+# Security model & disclaimers
+
+Read this before you expose anyagent-bridge to anything beyond your own machine.
+
+## What you are running
+
+anyagent-bridge gives a web browser **a real terminal and file access on the
+machine it runs on**. Anyone who can reach the server *and* holds a valid token
+or session can run commands, read and write files (within the configured path
+whitelist), and drive your AI coding agents — with the same privileges as the
+user running the bridge. Treat the access token like an SSH key.
+
+## Safe by default
+
+Out of the box the bridge is conservative:
+
+- **Binds to `127.0.0.1`** (localhost only). Nothing on your network can reach it
+  until you explicitly set `host`/`HOST` to `0.0.0.0` or publish it.
+- **No tunnel.** Remote access (Stage 2) is opt-in and off by default.
+- **Token required.** A 32-byte random token is generated on first boot and
+  saved to `.data/auth.json` with `0600` permissions. There is never a blank or
+  default token. Token comparison is constant-time.
+- **Path whitelist.** The file API is restricted to configured `allowedPaths`
+  (your home directory by default), and a denylist blocks secret-bearing dotfiles
+  (`.env`, `.npmrc`, SSH keys, cloud-credential files, …).
+
+## Before you expose it (tunnel or `0.0.0.0`)
+
+The token alone is a single shared secret. When the bridge is reachable beyond
+localhost, layer on the opt-in protections:
+
+- **Turn on authentication (Stage 3).** Set `requireLogin` so the static token
+  becomes login-only, enroll **TOTP 2FA**, and/or require **Google/GitHub OAuth**
+  with an email/login allowlist. With 2FA or `requireLogin` on, a leaked token is
+  no longer enough by itself.
+- **Use a tunnel that has its own auth.** Microsoft Dev Tunnels can require a
+  sign-in; a Cloudflare/Tailscale path can sit behind their access controls.
+  Don't put a raw `0.0.0.0` bind directly on the public internet.
+- **Pin `auth.oauth.callbackBaseUrl`** to your public URL when OAuth is on behind
+  a tunnel, so the redirect URI is not derived from (spoofable) request headers.
+- **Set `trustProxy`** (Stage 4) only when you actually sit behind a known proxy,
+  so per-client rate limiting and the audit log record the real client IP instead
+  of a spoofable `X-Forwarded-For`. Leave it off otherwise.
+- **Sandbox the sessions (Stage 4).** Run each session inside a Docker container
+  (`safety.sandbox`) so the agent touches only a mounted project directory, with
+  memory/CPU/pid limits and `no-new-privileges`. Use `--network none` for an
+  offline agent, `readOnlyRootfs`/`dropAllCaps` to harden further.
+- **Enable the audit log (Stage 4).** Append-only JSONL of REST mutations and
+  agent commands, with secrets redacted. Pair it with the kill-switch
+  (`POST /api/safety/panic`) for an emergency stop that kills sessions and locks
+  new agent launches.
+
+## Handling secrets
+
+- **Keep OAuth client secrets in environment variables**, not in `config.json`
+  (which can be written back to disk at runtime). `config.json` is gitignored.
+- The published npm package and the Docker image **exclude** `config.json`,
+  `.data/`, `.env`, and `sessions.json` — your token and secrets are never baked
+  into a distributable artifact.
+- Audit logs are always secret-redacted; live PTY-stream redaction is available
+  opt-in (`redaction.liveStream`).
+
+## Known limitations
+
+- Stage 1 ships **no TLS** of its own. Terminate TLS at your tunnel/reverse proxy
+  (Dev Tunnels, Cloudflare, etc.) — never send a token over plain `http://` across
+  an untrusted network.
+- Docker sandboxing is **defense-in-depth, not a security boundary you should bet
+  a hostile multi-tenant workload on**. Do not mount the Docker socket into a
+  sandboxed session (that is host-equivalent access), and do not bind-mount `$HOME`.
+- The bridge is meant for **a single operator controlling their own machine**, not
+  as a multi-user SaaS. It is not a substitute for a VPN or a zero-trust gateway
+  in a sensitive environment.
+
+## Reporting a vulnerability
+
+Please report security issues **privately** — open a GitHub Security Advisory on
+the repository (Security → Report a vulnerability) rather than a public issue, so
+a fix can ship before details are public.
+
+## Disclaimer
+
+anyagent-bridge is provided **as-is, under the MIT License, with no warranty**.
+You are responsible for how and where you expose it. Running it on a machine with
+access to sensitive data or networks is at your own risk.

package/docs/WALKTHROUGH.md

@@ -0,0 +1,82 @@
+# Walkthrough
+
+A guided tour of using anyagent-bridge end to end. The screenshots below live in
+[`docs/screenshots/`](screenshots/); to regenerate them yourself, see the
+[capture instructions](#capturing-screenshots).
+
+## 1. Start the bridge
+
+```bash
+npx anyagent-bridge          # or: npm start  /  docker compose up -d --build
+```
+
+The startup banner prints the access URL and token:
+
+```
+===============================================================
+  AnyAgent Bridge — server running
+===============================================================
+  URL:       http://127.0.0.1:3001?token=ab12…ef
+  WebSocket: ws://127.0.0.1:3001/ws
+  Host:      127.0.0.1
+  Shell:     /bin/zsh
+  Agents:    claude, codex
+  ...
+  Access token (generated): ab12…ef
+===============================================================
+```
+
+![Startup banner with the access URL and token](screenshots/01-startup-banner.png)
+
+## 2. Open the browser UI
+
+Open the printed URL (the `?token=…` logs you in automatically), or visit
+<http://127.0.0.1:3001> and paste the token. You land on the terminal view: a full
+xterm.js terminal wired to a live shell on your machine, plus a toolbar with the
+agent launcher, a file browser, and (if configured) project and tunnel controls.
+
+![The main terminal view — a live shell in the browser](screenshots/02-terminal-view.png)
+
+## 3. Launch an AI agent
+
+Pick an agent (e.g. **Claude Code**) from the dropdown and start it. The bridge
+spawns the agent's CLI inside the session's PTY, so you interact with it exactly
+as you would in your own terminal — streamed live to the browser. Type prompts,
+send keys, and watch output in real time. Detaching the browser keeps the session
+alive; reconnecting reattaches with full scrollback.
+
+![Claude Code running inside a bridge session](screenshots/03-agent-running.png)
+
+## 4. Browse and edit files
+
+Use the file panel to browse, open, edit, upload, and download files within the
+configured path whitelist. Image uploads are supported (handy for pasting a
+screenshot to an agent).
+
+## 5. Go remote (optional)
+
+To reach the bridge from your phone or another machine, enable a tunnel — either
+at startup (`--tunnel devtunnel`) or at runtime via the tunnel controls
+(`POST /api/tunnel/start`). The banner and the UI show the public URL once it is
+ready. Before exposing anything, read [SECURITY.md](SECURITY.md) and turn on
+login / 2FA / OAuth.
+
+![The bridge UI at a phone-sized viewport](screenshots/04-mobile.png)
+
+---
+
+## Capturing screenshots
+
+The images above were captured locally against a running bridge. To regenerate
+them yourself:
+
+1. Start the bridge and note the token: `npm start`.
+2. Open the printed URL in a browser (desktop and a phone/responsive view for the
+   mobile shot).
+3. Capture each state listed above and save it under `docs/screenshots/` with the
+   matching filename (`01-startup-banner.png`, `02-terminal-view.png`, …).
+4. PNG, ~1400px wide, is plenty. Crop out anything sensitive — **the token in the
+   URL bar and any real file contents** — before committing.
+
+Because the token grants full access, never publish a screenshot that shows a
+live token, private file paths, or agent credentials.

package/docs/screenshots/.gitkeep

@@ -0,0 +1,3 @@
+# Screenshot assets for the walkthrough go here.
+# See ../WALKTHROUGH.md → "Capturing screenshots" for the expected filenames and
+# how to capture them. Redact any access token / private paths before committing.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "anyagent-bridge",
+  "version": "0.5.0",
+  "description": "Control your local terminal and any CLI AI coding agent from a browser, anywhere.",
+  "license": "MIT",
+  "author": "elon-choo",
+  "homepage": "https://github.com/elon-choo/anyagent-bridge#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elon-choo/anyagent-bridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/elon-choo/anyagent-bridge/issues"
+  },
+  "main": "server/index.js",
+  "bin": {
+    "anyagent-bridge": "bin/anyagent-bridge.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "client/",
+    "docs/",
+    "test/",
+    "config.example.json",
+    ".env.example",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude-code",
+    "codex",
+    "ai-agent",
+    "terminal",
+    "pty",
+    "websocket",
+    "remote",
+    "bridge",
+    "self-hosted",
+    "developer-tools"
+  ],
+  "scripts": {
+    "start": "node server/index.js",
+    "test": "node test/stage4-smoke.js && node test/stage4-boot.js"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.2",
+    "multer": "^1.4.5-lts.1",
+    "node-pty": "^1.0.0",
+    "ws": "^8.18.0"
+  }
+}

package/server/auth/index.js

@@ -0,0 +1,20 @@
+/**
+ * AnyAgent Bridge — auth subsystem entry (Stage 3)
+ *
+ * The only module server/index.js imports for authentication. Creates an
+ * AuthManager and exposes the OAuth provider list for diagnostics. Sits on top
+ * of the Stage 1 static token; disabled features leave Stage 2 behavior intact.
+ */
+
+const AuthManager = require('./manager');
+const { PROVIDERS } = require('./oauth');
+
+function createAuthManager(authConfig, deps) {
+  return new AuthManager(authConfig, deps);
+}
+
+function listOAuthProviders() {
+  return Object.keys(PROVIDERS);
+}
+
+module.exports = { createAuthManager, listOAuthProviders };