junso-browser 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# junso-browser
+
+A standalone **CloakBrowser host**. It runs one stealth-Chromium instance **per profile**, each with its **own deterministic device fingerprint + proxy + cookies**, and exposes each over a **token-authed CDP gateway**. Drive it with anything that speaks CDP — `agent-browser`, Playwright, Puppeteer — via `--cdp`.
+
+Built for [Jun](../jun-codex): Jun keeps its whole tool surface and just connects to a junso-browser profile's CDP URL, gaining real per-profile device identities (the gap a shared local browser can't close).
+
+## Why
+
+A fresh profile gives new cookies + storage; a proxy gives a new IP — but on one machine every profile shares the same **device fingerprint** (canvas/WebGL/timezone/fonts/TLS), so a site can still link them. CloakBrowser derives a full, consistent fingerprint from a **seed** (same seed = same device; different seed = different device). junso-browser runs one seeded instance per profile and hands out its CDP endpoint.
+
+## How it works
+
+```
+client (agent-browser --cdp wss://host/cdp/<profile>?token=…)
+        │  WS relay + /json discovery (token-authed gateway)
+        ▼
+junso-browser ──spawn──> cloak chrome  --fingerprint=<seed> --fingerprint-platform=…
+                          --proxy-server=…  --user-data-dir=…  --remote-debugging-port=0
+```
+
+- **No Playwright at runtime** — the cloak *binary* applies the fingerprint from `--fingerprint*` flags (`--headless=new`); junso-browser is a thin process supervisor that spawns it and proxies CDP.
+- The cloak CDP binds `127.0.0.1` with no auth; junso-browser is the only thing that touches it and fronts it with a token gateway.
+
+## Install & run
+
+```bash
+bun i -g junso-browser                                    # installs the host + MCP bins
+JUNSO_BROWSER_TOKEN=secret JUNSO_BROWSER_HOST=0.0.0.0 junso-browser   # start the host (:8790)
+```
+
+The CloakBrowser binary (~200 MB) **auto-downloads** on first run (opt out: `JUNSO_BROWSER_NO_CLOAK_DOWNLOAD=true`). Runs on **Bun** (`Bun.serve`/`Bun.spawn`).
+
+The package ships two bins: **`junso-browser`** (the host) and **`junso-browser-mcp`** (the optional MCP — see below). From source: `bun install` then `bun run start` / `bun run mcp`. Build: `bun run build` (bundle `dist/`) or `bun run build:binary` (single compiled binary).
+
+### Config (env)
+
+| Var | Default | |
+|---|---|---|
+| `JUNSO_BROWSER_PORT` | `8790` | listen port |
+| `JUNSO_BROWSER_HOST` | `127.0.0.1` | listen addr (token **required** if non-loopback) |
+| `JUNSO_BROWSER_TOKEN` | — | shared secret for API + CDP |
+| `JUNSO_BROWSER_DATA_DIR` | `~/.junso-browser` | profiles.json + user-data dirs |
+| `JUNSO_BROWSER_MAX_INSTANCES` | `3` | concurrent cloak instances (LRU-reaped) |
+| `JUNSO_BROWSER_IDLE_MS` | `1800000` | reap an instance after this idle |
+| `JUNSO_BROWSER_PUBLIC_URL` | — | base for handed-out CDP URLs (e.g. `wss://browser.example.com`) |
+| `JUNSO_BROWSER_CLOAK_PATH` | auto | override the binary path |
+
+## API
+
+All `/api/*` require the token (`Authorization: Bearer …`, `x-junso-token`, or `?token=`).
+
+| Method | Path | |
+|---|---|---|
+| GET | `/health` | status + cloak presence + running count |
+| GET | `/api/profiles` | list (proxy masked) + running flag |
+| POST | `/api/profiles` | `{ name, fingerprint?: { seed?, platform?, timezone?, locale? }, proxy? }` |
+| GET/PATCH/DELETE | `/api/profiles/:id` | read / update (incl. `rotateSeed`) / delete |
+| POST | `/api/profiles/:id/launch` | start instance → `{ cdpUrl }` |
+| POST | `/api/profiles/:id/stop` | stop instance |
+| GET | `/api/profiles/:id/cdp` | `{ cdpUrl }` (auto-launches on connect) |
+| WS/GET | `/cdp/:id` | CDP gateway (ws relay + `/cdp/:id/json*` discovery) |
+
+## Interactive viewport
+
+Open `http://<host>:8790/view/<profile>?token=<token>` in any browser to **watch and take control** of a profile's browser — live screencast + your mouse/keyboard forwarded over CDP. Use it for human-in-the-loop steps (log in by hand, solve a CAPTCHA, check something) on the *same* fingerprinted profile the agent drives via MCP. CDP supports multiple clients, so the viewport and the MCP coexist. (Frames stream on repaint — a static page shows one frame until you interact.)
+
+## Optional browser MCP
+
+junso-browser also ships an **MCP server** (`src/mcp.ts`, bin `junso-browser-mcp`) — the way to give any MCP client (Jun, Codex, Claude Desktop) browser tools without a local browser. It resolves a profile's CDP URL from the API and drives it via `agent-browser --cdp`, so it works whether junso-browser is local or remote.
+
+Add it to a client's MCP config (once `junso-browser` is installed globally):
+
+```json
+{
+  "command": "junso-browser-mcp",
+  "env": { "JUNSO_BROWSER_URL": "https://browser.example.com:8790", "JUNSO_BROWSER_TOKEN": "secret", "JUNSO_BROWSER_PROFILE": "default" }
+}
+```
+
+(or `"command": "bunx", "args": ["-y", "junso-browser-mcp"]` without a global install).
+
+Tools: `browser_status`, `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_fill`, `browser_type`, `browser_press`, `browser_select`, `browser_scroll`, `browser_wait`, `browser_read`, `browser_eval`, `browser_screenshot`, `browser_exec`, `browser_list_profiles`, `browser_switch_profile`. The active profile (env `JUNSO_BROWSER_PROFILE`, default `default`) is auto-created on the host if missing; `browser_switch_profile` changes identity at runtime.
+
+## Status
+
+Phase 1 MVP — verified e2e (profile → fingerprinted cloak → external CDP client sees the configured fingerprint, deterministic per seed). Next: Jun integration (opt-in `JUN_BROWSER_CDP` backend), single-binary deploy, optional fingerprint personas.

package/bin/junso-browser-mcp.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+/**
+ * `junso-browser-mcp` — the optional browser MCP server (stdio). Add it to any
+ * MCP client: { "command": "junso-browser-mcp", "env": { "JUNSO_BROWSER_URL": … } }
+ * (or `bunx -y junso-browser-mcp`). Runs under Bun.
+ */
+if (typeof Bun === "undefined") {
+  console.error("junso-browser-mcp runs on Bun, not Node. Install Bun (https://bun.sh).");
+  process.exit(1);
+}
+
+import path from "node:path";
+await import(path.join(path.resolve(import.meta.dir, ".."), "dist", "mcp.js"));

package/bin/junso-browser.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env bun
+/**
+ * `junso-browser` CLI — entry point of the published package. The host uses Bun
+ * APIs (Bun.serve/Bun.spawn), so it must run under Bun; the guard below catches
+ * the Node case with a pointer instead of a cryptic crash.
+ */
+if (typeof Bun === "undefined") {
+  console.error("junso-browser runs on Bun, not Node. Install Bun (https://bun.sh):\n  bun install -g junso-browser");
+  process.exit(1);
+}
+
+import path from "node:path";
+
+const root = path.resolve(import.meta.dir, "..");
+const cmd = process.argv[2] ?? "start";
+
+if (cmd === "version" || cmd === "--version" || cmd === "-v") {
+  console.log(require(path.join(root, "package.json")).version);
+} else if (cmd === "mcp") {
+  await import(path.join(root, "dist", "mcp.js")); // also available as `junso-browser-mcp`
+} else if (cmd === "start" || cmd === undefined) {
+  await import(path.join(root, "dist", "server.js"));
+} else {
+  console.error(`Unknown command: ${cmd}\nUsage: junso-browser [start|mcp|version]`);
+  process.exit(1);
+}