free-computer-use 0.1.0

package/docs/SUPPORT_MATRIX.md

@@ -0,0 +1,193 @@
+# Support matrix
+
+Updated 24 September 2026. This matrix separates code that exists, automated
+contract coverage, and evidence from a real provider. An OpenAI-compatible URL
+does not prove that every service using that label accepts the same request.
+
+## Model connections
+
+| Connection | Implemented route | Automated evidence in this repository | Live evidence and current status |
+| --- | --- | --- | --- |
+| OpenAI-compatible API | `openai-compatible`; bearer key; configurable base URL; `/chat/completions`; JSON object or schema request | Seven local HTTP/mock contract cases cover request format, schema validation, usage, context trimming, HTTPS, bounded correction, safe HTTP errors and OpenAI's completion-limit parameter. | One live DeepSeek Flash completion passed on 23 September 2026 using synthetic content: one request, one parsed action, 1,517 input and 73 output tokens. OpenAI, xAI/Grok, Gemini, Mistral and OpenRouter remain individually unverified here. |
+| Anthropic API | `anthropic`; `x-api-key`; Messages endpoint; prompted JSON object, locally validated | One local HTTP contract test covers the native request, headers, usage parsing, escaped page content and unsupported JSON-schema rejection. | Not live-tested in the recorded project evidence. Unverified. |
+| ChatGPT subscription | Local Codex CLI; detects semantic CLI version, checks `codex login status`; runs an ephemeral, read-only `codex exec` request with tools disabled | Three local fake-CLI tests cover version parsing, output parsing, strict-schema conversion, records-selector restoration, required flags, environment isolation and actionable missing/unsigned errors. | One synthetic plan completion passed on 23 September 2026 using Codex CLI `0.156.1` and an authenticated ChatGPT login. One request; local budget estimates 7,022 input / 97 output tokens; model ID and actual provider usage were not reported. No browser action ran. |
+| Claude Pro/Max subscription | Local Claude Code CLI; requires version `2.1.248+`, checks first-party subscription authentication; runs a restricted, non-persistent prompt with tools disabled | Three local fake-CLI tests cover version threshold, output parsing, required flags, environment isolation and actionable missing/unsigned errors. | Not verified against an authenticated Claude subscription. The local package manifest reports `0.2.69`; its `claude --version` command currently throws a Node `TypeError`, so update the CLI before live verification. |
+
+### OpenAI-compatible configuration examples
+
+These are endpoint examples in the README, not individually verified vendor
+certifications. Check each provider's current model name, JSON support, token
+parameters, endpoint and terms before use.
+
+| Service named in project docs | Implemented route | Live model/date/result | Still unverified |
+| --- | --- | --- | --- |
+| DeepSeek | OpenAI-compatible | `deepseek-flash`; 23 September 2026; one synthetic plan completed in one request. | Browser task behavior, other model aliases and live `json_schema` behavior. |
+| OpenAI | OpenAI-compatible | No live model request recorded. | Model access, request acceptance, output/usage shape and browser task behavior. |
+| xAI / Grok | OpenAI-compatible | No live model request recorded. | Model access, request acceptance, output/usage shape and browser task behavior. |
+| Google Gemini | OpenAI-compatible endpoint | No live model request recorded. | Model access, request acceptance, output/usage shape and browser task behavior. |
+| Mistral | OpenAI-compatible | No live model request recorded. | Model access, request acceptance, output/usage shape and browser task behavior. |
+| OpenRouter | OpenAI-compatible endpoint | No live model request recorded. | Account/model routing, request acceptance, output/usage shape and browser task behavior. |
+
+## Browser, runtime and distribution
+
+| Area | Declared or implemented | Verified evidence | Limit |
+| --- | --- | --- | --- |
+| MCP host integration | Local `stdio` server, MCP TypeScript SDK `2.0.0`; tools start, inspect, follow/verify and stop a browser task. | On 24 September 2026, four focused tests passed with the official TypeScript MCP client. MCP Inspector 2.8.0 also connected to the built CLI over `stdio`, displayed site approval and declined it; the task failed with zero model calls and zero requests to the local fixture. | Only the reference Inspector client is verified; other desktop agent hosts remain unverified. Host must support form elicitation for approvals. No public npm install exists yet. |
+| Node.js | `package.json` declares an install floor of Node `>=22.13.0`; this does not certify that whole range. | A clean checkout installed with `npm ci --offline --no-audit --no-fund`, then passed `npm run validate` on Node `25.9.0`, macOS `26.6`, Apple Silicon and system Chrome `154.0.8037.57` on 24 September 2026. | Node `22.13.0`, other Node releases and Windows/Linux have not been validated. |
+| Browser engine | Playwright `1.63.0`; defaults to its matching Chromium. Optional `FCU_BROWSER_CHANNEL` selects installed Chrome/Edge to avoid a browser download. | System Chrome `154.0.8037.57` passed 102/102 serial tests and the full validation on 24 September 2026 (commit `d978b06`). `FCU_BROWSER_CHANNEL=chrome npm run demo -- --headed --contact` also completed seven local actions with zero model calls and exited cleanly. | Matching Playwright Chromium is absent. Playwright warns that non-bundled browsers may be incompatible. Other browser builds and operating systems remain unverified. No browser was downloaded. |
+| Browser task behavior | DOM observation, bounded action plans, origin/action approvals, result checks and compatible workflow replay are implemented. A loopback-only Chromium DevTools Protocol connection attaches to page targets before navigation and checks redirect hops. A second loopback proxy enforces origin policy for HTTP(S)/WebSocket traffic, blocks private/reserved DNS answers and checks private IPv4 embedded in prefixes learned through `ipv4only.arpa`. The persistent Chromium profile disables WebRTC UDP that the proxy cannot carry. Explicit IP literals need exact origin approval. Ultra/`allowExternal` opts out of origin and private-address checks. Closing the active page cancels its run and pending approval. | On 24 September, the dashboard was changed to reuse one `Agent` and Chromium context between tasks, opening a fresh tab for each task. Regression checks confirm dashboard replay keeps the same context, all eight lab workflows replay in that context, and the persistent network proxy reapplies private-address policy when the mode changes. The clean serial full suite passed 101/101 on system Chrome `154.0.8037.57`, macOS `26.6`, Node `25.9.0`. Security cases include popup redirects, simulated DNS rebinding, reserved ranges, normal/Ultra behavior and approved/blocked WebSockets. A Chrome-originated WSS fixture returns a frame through the proxy; its generated local certificate is ignored. A separate opt-in `security:wss` smoke connected to Postman Echo with Chrome’s normal TLS validation and received its synthetic message. Synthetic DNS64 fixtures cover all six RFC 6052 prefix lengths; actual NAT64 discovery remains unverified. A local STUN receiver got no WebRTC UDP packets. | Before context reuse, relaunching Chrome `154.0.8037.57` with the same persistent profile caused a `SIGSEGV` on 23 September; the `.ips` report identifies `CrBrowserMain` and `EXC_BAD_ACCESS`. The dashboard now avoids this process boundary, and its full local regression suite passes. Reopening the same profile through a standalone Playwright process remains unverified. Matching Playwright Chromium is absent; no browser was downloaded. Live NAT64 discovery, other trusted WSS endpoints, non-HTTP traffic beyond the WebRTC STUN fixture, other browser builds, Windows/Linux and universal website success remain unverified. WebRTC services needing direct UDP may fail. |
+| Vision and canvas | Local screenshots/preview exist. | Screenshot paths are documented as local. | Images are not sent to the model; model vision and visual-only/canvas control are not implemented. |
+| npm package | Package metadata declares a CLI, ESM library entry point and global `agent` command; package name is `free-computer-use`. | A clean source archive passed offline install/build/pack. Its 130-file, approximately 1.14 MB candidate installed offline in a separate temporary project; CLI version/help/doctor passed. The interactive CLI and installed dashboard each completed the read-only table workflow with one action and zero model calls. Dashboard checks passed HTTP 200, keyboard focus, 320/390/768/1440 px without horizontal overflow, and zero console errors. | `npm view free-computer-use@0.1.0 version` returns 404. The package is not published, so registry installation and public integrity are unverified. `0.1.0` remains manifest metadata, not a published release. |
+| GitHub release / binary | No release tag or GitHub release was present at audit time. | None. | No downloadable release binary or archive is currently offered. |
+| GitHub Actions | No workflow files are tracked in the checkout. | `git ls-files '.github/workflows/*'` returned no workflow; no workflow was activated or dispatched. `docs/LOCAL_VALIDATION.md` records the owner instruction. | Local checks remain the validation route unless the owner changes that instruction. |
+
+## Validation snapshot for this implementation session
+
+- Fresh-export onboarding: `git archive` of commit `eca3f17`, offline `npm ci`,
+  copied `.env.example` with Chrome selected, `chmod 600`, `agent doctor`,
+  keyboard-only no-key `ui:smoke`, and `npm run dev -- --port 0` all passed on
+  macOS `26.6` / Node `25.9.0` / system Chrome `154.0.8037.57`. Dashboard
+  returned HTTP `200`; export was removed.
+- `npm run check`: passed on Node `25.9.0` on 24 September 2026.
+- `npm run build`: passed.
+- Previous recorded `npm run security` pass covered 6,005 tracked file versions.
+  On 24 September 2026, the checkout-only scan passed 245 tracked file versions;
+  the full history rescan was stopped after 2 minutes 30 seconds without a
+  result. This pattern scan is not a complete security audit.
+- `npm audit --omit=dev --audit-level=high`: passed; zero production dependency
+  advisories reported.
+- `FCU_BROWSER_CHANNEL=chrome LLM_API_KEY= npm run agent -- doctor`: passed the
+  Node/runtime and browser-launch checks with no model configured.
+- Public-lab build regression test: passed; it ran the build twice and confirmed
+  `docs/index.html` stayed byte-for-byte unchanged and `docs/lab/index.html` was
+  stable across both runs.
+- Provider contract tests: eleven passed against local HTTP/fake-CLI fixtures.
+- Provider doctor CLI: one local test passed for offline mode, a successful
+  loopback `/models` response, missing API configuration and a simulated HTTP
+  503; the configured API key and response body stayed out of CLI output.
+- Local environment file: a subprocess test passed on macOS; a permissive `.env`
+  became owner-only before loading, a symlink was rejected without changing its
+  target, and the test key stayed out of standard output/error.
+- Focused security-file run: 26/26 tests passed on system Chrome
+  `154.0.8037.57`, including popup redirect denial/approval, simulated DNS
+  rebinding blocked before HTTP/TLS-tunnel target receipt, hostname-to-loopback
+  denial, Ultra access to a local fixture, and approved/blocked WebSockets.
+- WebRTC egress: Chrome `154.0.8037.57` generated an ICE offer while a local UDP
+  STUN fixture observed no direct packets; an unrelated browser preference was
+  preserved. This verifies the local STUN scenario only.
+- Focused action and results runs: 8/8 and 1/1 tests passed on system Chrome
+  `154.0.8037.57`; upload/download/navigation, saved-download confinement and
+  result reporting remained functional. Download directory/file modes `0700`/
+  `0600` were verified on macOS.
+- Credentialed initial URL: two focused tests passed. The library agent rejects
+  credentials before persisting a trace; the dashboard rejects credentials in
+  the starting URL or allowed-origin list before creating an agent.
+- Cross-origin WebSocket: Chrome `154.0.8037.57` tests passed for denied and
+  approved plain WS endpoints; the denied fixture received no upgrade. A
+  browser-originated WSS test passed for an approved origin and returned a frame;
+  an unapproved WSS origin was blocked before the target received a TCP
+  connection. The test ignores its generated local certificate, so public trust
+  validation and other browser builds remain unverified.
+- Profile and local-data lifecycle: 4/4 tests passed on macOS. Unknown fields are
+  rejected without replacing the existing vault; symbolic-link reads and writes
+  are refused; profile mode is `0600`; data directory/history modes are `0700`/
+  `0600`; deleting a stopped data directory and restarting creates a fresh empty
+  history. A forced filesystem write failure leaves the existing profile bytes
+  unchanged. Forty saved runs remain stored; the history limit only affects
+  displayed summaries. Retention is manual with no expiry. Windows/Linux
+  permissions remain unverified.
+- IPv6 allowlist matching: focused test passed; expanded and compressed loopback
+  spellings normalize to one origin, while a different port and path-scoped
+  allowlist are denied.
+- DNS private-address guard: a simulated first lookup to `8.8.8.8` followed by a
+  connection-time lookup to loopback was rejected before the target received an
+  HTTP request or TCP tunnel. Another test confirms a successful connection uses
+  its first vetted IP without resolving again. These run with the local proxy and
+  do not validate network-specific NAT64 or other browser builds.
+- DNS64/NAT64: synthetic DNS64 answers for RFC 6052 prefixes `/32`, `/40`, `/48`,
+  `/56`, `/64` and `/96` reject private embedded IPv4 and allow `8.8.8.8`. The
+  current system resolver returned only IPv4 A records for `ipv4only.arpa`; live
+  network-prefix discovery remains unverified.
+- First-run dashboard smoke: `FCU_BROWSER_CHANNEL=chrome npm run ui:smoke` passed
+  on 23 September 2026 from a clean export of commit `eca3f17` with Node `25.9.0`,
+  macOS `26.6`/Apple Silicon and system Chrome `154.0.8037.57`. Offline `npm ci`,
+  `.env.example` copy, `FCU_BROWSER_CHANNEL=chrome`, `chmod 600`, doctor, UI smoke
+  and CLI server startup all passed without a provider or browser download. The
+  smoke used keyboard input, Enter to start/approve/open the result, and Escape to
+  close it; the approved synthetic task completed with one browser action and
+  zero model calls. Output, preview, console and 1600/390 px overflow checks
+  passed. This verifies one clean-checkout onboarding path, not other OS, Node or
+  browser combinations.
+- Results UI smoke: `FCU_BROWSER_CHANNEL=chrome npm run ui:results` passed on
+  23 September 2026 with its authored local planning fixture. The independent
+  journey oracle, result facts, fullscreen view, viewer scrolling and browser
+  console checks passed. This validates result presentation, not model planning.
+- Dashboard UI tests: `FCU_BROWSER_CHANNEL=chrome ./node_modules/.bin/tsx --test
+  tests/ui.test.ts` passed 11/11 on 24 September 2026. Cases cover rejecting
+  site access before a visit, stopping while approval is pending, a synthetic
+  provider timeout shown as failed, a false extraction criterion shown as a
+  partial result, revoking an approved origin and blocking a fetch before the
+  local fixture receives it, and the distinct `BLOCKED` state for a
+  private-network DNS refusal. The
+  timeout used an in-process fake provider; this is not a live provider timeout
+  test. The dashboard run still reports its historical trace status as `failed`
+  with `failureKind: security` for policy blocks.
+- Agent and security tests: `FCU_BROWSER_CHANNEL=chrome ./node_modules/.bin/tsx
+  --test tests/agent.test.ts tests/security.test.ts` passed 35/35 on 24 September
+  2026 after the permission and security-state changes. This remains local test
+  evidence, not a cross-platform or full-suite result.
+- Lab/site smoke: `FCU_BROWSER_CHANNEL=chrome npm run lab:smoke` passed on
+  23 September 2026. It rendered 24 lab pages and eight task cards, played the
+  local 1600x900 demo clip, loaded the brand asset, and reported no browser
+  console errors. Horizontal overflow checks passed at 320, 390, 768 and 1440 px
+  for the lab pages/workflow library. It refreshed 50 lab and two dashboard PNG
+  captures. The dashboard and lab keyboard paths, accessible names, contrast,
+  and responsive widths are verified as recorded in `ROADMAP.md`. Spoken
+  VoiceOver/NVDA output remains unverified and is not claimed.
+- DeepSeek live smoke: one completion passed on 23 September 2026 using the
+  synthetic title `Sandbox title`; one request, one parsed action, 1,517 input
+  and 73 output tokens. This did not run a browser workflow or test other
+  vendors.
+- Full serial `FCU_BROWSER_CHANNEL=chrome npm test`: passed 100/100 on 24 September
+  2026 in 148.8 seconds before the history-scan regression test was added. The
+  latest suite passes 102/102 in 156.44 seconds at commit `d978b06` with system
+  Chrome `154.0.8037.57`, macOS `26.6`, and Node `25.9.0`. `npm test` pins test-file
+  concurrency to one. This does not validate standalone same-profile Chrome
+  relaunches, bundled Playwright Chromium, Windows, or Linux. No browser was
+  downloaded.
+- **Clean full validation (24 September 2026, commit `1ca1006`):**
+  `npm ci --offline --no-audit --no-fund` added the locked dependencies without
+  a browser download. `FCU_BROWSER_CHANNEL=chrome npm run validate` then passed
+  in 157.19 seconds: 101/101 tests, build, history scan (248 worktree files,
+  250 unique paths, 948 unique blobs) and `npm audit` with zero vulnerabilities.
+  The run needs npm registry access only for the final audit.
+- **Latest full validation (24 September 2026, commit `d978b06`):**
+  `env LLM_API_KEY= FCU_BROWSER_CHANNEL=chrome npm run validate` passed with
+  102/102 tests, build, history scan (255 worktree files, 257 unique paths,
+  980 unique blobs) and `npm audit` with zero vulnerabilities. No provider key
+  was configured and no GitHub workflow was triggered.
+- One preceding clean full run passed 100/101 because a dashboard test saw a
+  local HTTP `502`; the isolated test and the next two full suites passed. The
+  test now reports captured HTTP 5xx paths before generic console errors, but
+  the original request path and root cause were not captured. Keep this
+  intermittent result visible; the passing reruns do not prove it impossible.
+- Headed browser smoke: `FCU_BROWSER_CHANNEL=chrome npm run demo -- --headed
+  --contact` passed on 24 September 2026 with the scripted local fixture. It
+  performed seven browser actions, used zero model calls, completed the local
+  contact workflow and exited `0`. The synthetic `.fcu/demo` data was removed.
+  The full Chrome suite verifies the headless path. Both tests used Node
+  `25.9.0`, macOS `26.6`, and Chrome `154.0.8037.57`.
+- `FCU_BROWSER_CHANNEL=chrome npm run security:wss`: passed on 24 September 2026; system Chrome `154.0.8037.57` used default TLS validation to connect to `wss://ws.postman-echo.com/raw` and received the fixed synthetic payload. This is one external endpoint check, not proof for every WSS service. Postman documents this endpoint in its [Echo API guide](https://learning.postman.com/docs/developer/echo-api).
+- An earlier `FCU_BROWSER_CHANNEL=chrome npm run validate` had been stopped
+  during its per-file Git-history scan after 2 minutes 30 seconds; that scan
+  checked only the checkout at the time. The batched historical-object scan now
+  completes as part of the clean full validation above.
+- ChatGPT subscription smoke: one synthetic plan completed on 23 September 2026
+  using Codex CLI `0.156.1`; local budget estimates 7,022 input / 97 output
+  tokens. The model ID and actual provider usage were not reported. No browser
+  action ran. Claude subscription remains unverified because its local
+  `claude --version` command fails with a Node `TypeError`.
+
+Update this page only when a specific local test, dated live run, supported
+runtime check, or public release provides new evidence. Keep failures and
+untested combinations visible.

package/docs/THREAT_MODEL.md

@@ -0,0 +1,108 @@
+# Threat model
+
+**Reviewed 24 September 2026.** This describes controls visible in this checkout;
+it is not a penetration-test report or a guarantee that a task is safe.
+
+## Scope and assumptions
+
+FreeComputerUse runs a Playwright browser and local dashboard under the current
+OS account. The user chooses the starting website, provider, profile values,
+downloads and whether to enable Ultra mode. The project does not defend against
+malware or a person who already controls that OS account. It does not bypass
+CAPTCHAs or website access controls.
+
+The main assets are API credentials, provider CLI sessions, browser cookies and
+local storage, profile values and file paths, downloaded files, SQLite run
+history, extracted website content, and the integrity of actions and reported
+results.
+
+## Trust boundaries
+
+1. **Web page to planner.** Page text is untrusted input. The provider returns a
+   typed plan; Zod validation admits only the fixed action schema. No action
+   executes arbitrary JavaScript or a shell command.
+2. **Application to website.** `Agent` asks before its first document request to
+   an origin. Playwright checks HTTP(S) requests, frames and WebSockets against
+   the exact origin allowlist. A loopback-only Chromium DevTools Protocol
+   connection attaches to each page target before navigation and checks
+   redirect hops. Redirected documents ask for approval; redirected
+   subresources require an approved origin. Non-HTTP(S) protocols and URLs with
+   embedded user credentials are rejected before an agent trace is stored. A
+   local Chrome 154 test verifies that a fast popup redirect is blocked before
+   the unapproved target receives a request. Other browser builds are not yet
+   verified.
+   The exported low-level `Browser` denies network requests unless its caller
+   provides an allowlist or explicitly sets `allowExternal`; Ultra mode opts into
+   that unrestricted HTTP(S) policy and skips the private-address check too. In
+   normal mode, a loopback-only proxy resolves named destinations and connects
+   to the resulting numeric address for HTTP, HTTPS tunnels and WebSockets.
+   Private/reserved answers and IPv4-embedded private NAT64 addresses are
+   blocked. Explicit IP literals still require an exact allowlisted origin.
+   Network-specific NAT64 prefixes and non-HTTP browser traffic are outside this
+   address check.
+3. **Planner to action.** By default, sensitive actions use a separate human
+   confirmation path. The executor checks that an approved target remains
+   connected and unchanged before the effect. The original goal's completion
+   criteria cannot be weakened by a repair plan. `--confirmation never` opts
+   out; Ultra mode also skips these prompts.
+4. **Local dashboard to server.** The server binds to `127.0.0.1`; it checks the
+   Host header, a random session cookie, exact Origin and a CSRF token on
+   mutations. CSP limits scripts and connections to the local app origin.
+5. **Application to local files.** Profile values and file paths are stored in
+   the local vault. Upload actions require an explicit file alias. Downloads are
+   resolved and confined to the configured download directory before serving.
+6. **Application to provider.** Browser execution is local, but selected page
+   content and task context are sent to the configured API or subscription CLI
+   for planning. The provider can retain or process that content under its own
+   terms. Provider choice is a data-sharing choice, not an offline mode.
+
+## Threat register
+
+| Threat | Current controls in this checkout | Evidence | Residual risk and follow-up |
+| --- | --- | --- | --- |
+| A page uses prompt injection to redirect the task, reveal profile data or request an unsafe action. | Page content is marked untrusted; action plans use a fixed schema; profile values are resolved locally; default sensitive-action checks require confirmation; completion checks are independently verified. | Provider boundary tests; `tests/security.test.ts` covers approval, post-approval target replacement and trusted completion criteria. | A model can still misunderstand a task and page content can deceive a person. Avoid Ultra mode; in normal mode use `--confirmation always` for high-impact work. |
+| A page, redirect, frame, fetch or WebSocket reaches an unapproved origin. | Playwright routing checks HTTP requests; a loopback-only Chromium DevTools Protocol connection intercepts page-target requests and redirect hops. A second loopback proxy applies origin policy to HTTP, HTTPS tunnels and WebSockets, resolves hostnames and dials the vetted numeric address. Normal mode approves document origins; redirected subresources need an approved origin. Private/reserved DNS answers and private IPv4 embedded in the NAT64 prefix discovered through `ipv4only.arpa` are blocked. The persistent profile sets `webrtc.ip_handling_policy=disable_non_proxied_udp`. Ultra/`allowExternal` opts out of origin and private-address checks. Unsupported protocols and embedded URL credentials are rejected at the dashboard and agent boundaries before a trace is stored. IPv6 literals are canonicalized for allowlist comparison while preserving exact ports. | `tests/security.test.ts` covers credentialed initial URLs, simulated public-to-loopback DNS rebinding before HTTP and TLS-tunnel connection, private IPv4/IPv6 DNS rejection before target receipt, synthetic DNS64 private/public IPv4 classification for each RFC 6052 prefix length, normal/Ultra separation, exact-port IPv6 origin matching, cross-origin fetch and plain WebSocket denial before server receipt, approved WebSocket forwarding, browser-originated approved WSS frame delivery and unapproved WSS denial before the target receives TCP, cleartext SSH-style CONNECT denial before dialing, WebRTC STUN UDP blocked before a local receiver, preservation of an unrelated browser preference, frame-grant cancellation, main-page redirect rejection/approval, default-deny behavior for a bare `Browser`, and popup redirect denial/approval. The local WSS fixture ignores errors from its generated certificate. Separately, `FCU_BROWSER_CHANNEL=chrome npm run security:wss` passed on 24 September: Chrome used default TLS validation with Postman Echo and received a fixed synthetic payload. This validates one endpoint/runtime only. The dashboard test confirms credentialed starting URLs and allowlist entries are rejected before an agent is created. Browser cases pass against installed Chrome `154.0.8037.57`. | Live NAT64 discovery is unverified: the current system resolver returned only IPv4 A records for `ipv4only.arpa`. Other non-HTTP traffic beyond the WebRTC STUN fixture and other browser builds remain unverified. Sites that need unproxied WebRTC UDP may fail. Explicit IP literals in normal mode still rely on exact origin approval. HTTP is also permitted. |
+| A click or form submission causes a purchase, message, deletion or other irreversible change. | Under the default `sensitive` policy, explicit `sensitive` flags and submit actions are gated; common risky labels and form semantics are heuristically detected; the approved target is fingerprinted; uncertain effects stop automated repair. | `sensitiveReason` and executor tests cover changed targets and approval/rejection behavior. | Text heuristics cannot recognize every deceptive or ambiguous control. Prefer normal mode with `--confirmation always`; visually review the action before approval. |
+| A remote site or another browser origin takes over the local dashboard. | Loopback binding, exact Host and Origin checks, random HttpOnly SameSite cookie, CSRF header, no CORS, restrictive CSP and bounded JSON request bodies. | Local UI tests cover missing session, cross-origin mutation rejection and successful same-origin control. | A process running as the same OS user can inspect or control local state. The dashboard is not a multi-user service; do not expose it through a tunnel or reverse proxy. |
+| A profile path, upload alias or download receipt escapes its allowed directory. | Vault schemas reject prototype keys and unknown top-level settings; profile imports reject symlink files and save through a same-directory temporary file plus rename; upload values must be explicit `files.*` aliases; downloaded paths are checked with `realpath` and a directory boundary before serving. On macOS, profile/download files use POSIX `0600` and their directories use `0700`. | `tests/profile.test.ts` covers invalid import preservation, failed filesystem replacement preserving old bytes, symlink refusal and POSIX modes; `tests/actions.test.ts` covers upload alias confinement, download symlink rejection and download modes. | Files are not encrypted and a user can intentionally choose sensitive files. Windows/Linux permission behavior remains unverified. Keep profiles and downloads in an OS-protected account. |
+| Secrets or session data appear in provider prompts, traces, errors or screenshots. | Known vault values and `sk-`-shaped strings are redacted; environment credentials are stripped before subscription CLIs; traces and profiles are owner-only on supported filesystems; password/payment values are omitted from record extraction. | Provider key-error tests, CLI environment tests and security tests. | Redaction patterns cannot find every secret. Provider API requests intentionally contain task/page context. Local browser profiles, backups and history are plaintext; inspect before sharing and follow retention work in Phase 2.3. |
+| A replay repeats an obsolete action or falsely reports success. | Replay has no model, checks current page/workflow compatibility, retains normal permission gates and verifies independent completion criteria. The dashboard reuses its browser context across tasks but starts each task in a fresh tab. | Workflow and completion-oracle tests in `tests/agent.test.ts`, `tests/security.test.ts`, `tests/lab.test.ts` and `tests/ui.test.ts`; the serial suite passed 100/100 on system Chrome `154.0.8037.57` on 24 September 2026. | Similar page structure does not prove identical intent. Review learned workflows and final results. Standalone relaunch of Chrome with the same profile and bundled Playwright Chromium remain unverified. |
+| A dependency, CLI or release artifact changes behavior or contains a vulnerability. | Lockfile, local production `npm audit`, pattern-based tracked-secret scan and explicit support matrix. GitHub Actions is intentionally disabled by owner instruction. | Local checks recorded in `docs/SUPPORT_MATRIX.md`; no remote workflow is claimed. | Scanners are incomplete; manual releases need repeatable local gates and artifact verification. Address in Phase 4.3 and Phase 6. |
+
+## Response guidance
+
+- Stop a run when the requested action, domain or expected result is unclear.
+- In normal mode, use `--confirmation always` for workflows that can change
+  accounts, publish, submit, transfer, delete, purchase or send messages.
+- Do not put real credentials, private account content or real browser profiles
+  into issue reports, screenshots or benchmark fixtures.
+- Report a suspected vulnerability privately through GitHub's private
+  vulnerability reporting when the feature is available.
+- Treat any claim of local execution as distinct from local-only model
+  processing: API mode sends context to the selected provider.
+
+## Open security work
+
+- Phase 2.2 boundary tests passed 39/39 on the verified target: macOS `26.6`,
+  Node `25.9.0` and system Chrome `154.0.8037.57`; `npm run check` passed.
+  The checked cases include redirects, DNS rebinding, private IPv4/IPv6,
+  WebSockets, a rejected cleartext CONNECT tunnel, WebRTC STUN blocking,
+  download confinement and profile symlink rejection. A separate trusted-TLS
+  WSS smoke passed against one Postman Echo endpoint. Actual NAT64 discovery,
+  other browser/OS builds, bundled Playwright Chromium and non-HTTP traffic
+  beyond the tested WSS/STUN cases remain unverified. Do not infer compatibility
+  for those targets from the local fixtures.
+- Phase 2.3 local-data handling is validated on macOS `26.6`, Node `25.9.0`
+  and system Chrome `154.0.8037.57`: the local-data guide covers inspection,
+  export, deletion and manual retention; targeted profile/CLI/agent/results
+  tests passed 22/22, the full dashboard suite passed 11/11 in isolation, and
+  synthetic export/deletion recreated an empty mode-`0700` directory. OCR of
+  62 still images and all 290 frames in the two README GIFs found no `sk-` or
+  Bearer-shaped strings. OCR is heuristic. Storage remains unencrypted and has
+  no automatic expiry; Windows/Linux permissions remain unverified.
+- The 24 September serial regression suite covers cancellation, synthetic
+  provider timeout, malformed responses, interrupted profile writes, rejected
+  incompatible replays, last-tab closure and all eight lab workflow replays.
+  It passed 100/100 on system Chrome `154.0.8037.57`; this does not establish
+  support for other OS/browser combinations or standalone same-profile Chrome
+  relaunches.

package/docs/USEFUL_EXAMPLES.md

@@ -0,0 +1,151 @@
+# Useful browser examples
+
+Open the [task library](https://othmaneblial.github.io/FreeComputerUse/lab/index.html),
+choose **Real websites** or **Practice workflows**, expand a card, and copy its
+goal. Paste its starting URL and goal into <http://127.0.0.1:4318>. Normal mode
+waits for your website approval before navigating. Watch the actual browser
+pointer, progressive typing and clicks; **Full screen** enlarges the browser and
+keeps approvals and controls visible. **Execution log** opens the event stream.
+**View result** presents facts and tables instead of raw JSON. Copy its summary
+or save a standalone HTML report. Original site exports remain available under
+Saved files only after a successful download. A stopped/failed task shows a
+partial result. Toolbar arrows let you scroll the real page while idle or paused;
+the agent brings action targets fully into view before clicking.
+
+The practice site is a fictional Northstar workspace. Its filters, dialogs, file
+exports and saved state operate in the browser. No messages, bookings, purchases,
+real account creation or remote account changes occur.
+
+## Three actual multi-page practice flows
+
+These are separate HTML documents and browser navigations, rather than hidden
+panels with a changed URL. Filters and shortlists survive navigation within the
+flow. Starting pages use `workspace.html?view=…` under the lab URL.
+
+| Flow | Document sequence | Result checked independently |
+| --- | --- | --- |
+| Product research | Catalogue → `product-details.html?id=trail` → catalogue → `product-comparison.html` | Wireless, in-stock keyboards under EUR 100; Trail K2 and Summit Air; battery, weight, prices and exported CSV bytes |
+| Journey planning | Search → `journey-results.html` → route details dialog → `itinerary.html` | Paris–Lyon, 2026-10-15, two adults, step-free/refundable, at most one change; Flex Regional EUR 90; local saved itinerary and downloaded file |
+| Invoice retrieval | Filtered invoices → `invoice-details.html?id=INV-2609-04` → download | Atlas Studio, September, overdue, Maya Chen; exactly one matching invoice; EUR 180 + EUR 60 = EUR 240 and the actual downloaded contents |
+
+Three further practice cases exercise scoped analytics, dependent preferences
+with review/save/reload, and finding the newest finance document before download.
+They test realistic interactions within one page and dialogs.
+
+## Quarter-close audit: six documents, one defensible decision
+
+The new Northstar quarter-close case starts at
+`workspace.html?view=close`. It moves through **six actual HTML documents**:
+
+`scope → revenue → booked ledger → pending adjustment → policy → review`.
+
+Choose **Q3 2026 / Direct**. The revenue report shows EUR 9,400, while the
+posted ledger contains EUR 9,300. The EUR 100 difference matches ADJ-042, but
+that adjustment is still pending. The policy says every non-zero difference
+needs human review, even at EUR 100. A correct review draft must therefore use
+**Needs review**, keep the adjustment separate from booked totals, and download
+`northstar-close-review.txt`. Incorrect figures or a premature "Ready to close"
+decision are rejected by the practice site.
+
+The [authored-plan run](../artifacts/benchmark-complex-authored-close.json)
+checks the selected scope, extracted source values, every document visit,
+saved review state and actual downloaded file bytes. It also replays the
+compatible workflow with no model provider. This validates execution and reuse.
+The [separate live Flash trial](../artifacts/benchmark-complex-live-close.json)
+completed with 24 successful actions, two repaired failures, 11 model calls,
+30,841 tokens and a configured-price estimate of $0.00650. Its compatible
+repeat passed with zero model calls. Earlier failures with tighter budgets and
+the pre-fix export handling are preserved as separate reports; one controlled
+success is not a general website success rate.
+
+Model-call and token caps are optional. New installs have no total model budget
+cap; an older local `.env` may still set `FCU_MAX_INPUT_TOKENS` or
+`FCU_MAX_LLM_CALLS`. Remove those lines if long tasks stop on a budget limit.
+The dashboard shows actual usage and configured-price cost estimates.
+
+## Incident desk: compare the signal before writing a brief
+
+Start at `workspace.html?view=incident`. The six-document sequence is
+`alert queue → incident timeline → request metrics → deployments → runbook → local brief`.
+Filter to **API Gateway / High / Last 24 hours** so INC-204 is isolated. The
+timeline places deployment `dep-7c3` at 09:58 UTC and the alert at 10:04.
+For `/v1/search`, the 429 rate rises from **0.4% to 12.4%**. The prior stable
+deployment used `burst_limit=100`; `dep-7c3` uses `20`. The runbook asks for
+**Needs engineer review**, not an automatic rollback or a claim of proven
+causality. The final page rejects the wrong endpoint, figures, deployment or
+decision. A valid local draft downloads as `northstar-incident-brief.txt`.
+
+The [authored-plan report](../artifacts/benchmark-complex-authored-incident.json)
+verifies filtered state, source extracts, all document visits, the saved draft
+and actual file bytes, then repeats without a provider. The
+[separate live Flash trial](../artifacts/benchmark-complex-live-incident.json)
+passed with 23 successful actions, two repaired failures, 12 model calls,
+35,968 tokens and a configured-price estimate of $0.00818. Its compatible
+repeat used zero model calls. One controlled trial does not establish a
+general success rate or prove that a real deployment caused a real incident.
+
+For a harder test, use the same starting page with this prompt. It leaves the
+rates and configuration change for the agent to discover:
+
+```text
+Investigate synthetic incident INC-204. Filter the alert queue to API Gateway, High severity, and Last 24 hours. Open the incident, inspect its timeline, request metrics, deployment comparison, and runbook. Use the evidence you find to complete the incident brief: affected endpoint, before/after 429 rates, relevant deployment, configuration change, and the appropriate review decision. Save the brief locally and download it. Do not roll back a service, contact customers, or claim the cause is proven.
+```
+
+After the navigation and evidence-context fixes, this exact prompt passed in
+[one live Flash trial](../artifacts/benchmark-complex-live-incident-challenge.json):
+21 successful browser actions, one repaired failure, 10 model calls, 31,973
+tokens and an estimated $0.00635 at the configured prices. Its compatible
+repeat passed with zero model calls. This is one controlled run on synthetic
+pages, not a reliability estimate for other websites.
+
+## Ten researched tasks on real free websites
+
+Research checks public sources and the task design. It does not by itself prove
+that our agent completes a task. Trial results are recorded separately in the
+[real-world report](../artifacts/benchmark-real-world.json). Untested cards say so.
+
+| Need | Starting website and source | Why it is useful |
+| --- | --- | --- |
+| Audit a software dependency | [GitHub / Playwright](https://github.com/microsoft/playwright) | Inspect latest stable release, licence and security policy across documents |
+| Shortlist a small local model | [Hugging Face / Qwen3](https://huggingface.co/Qwen/Qwen3-0.6B) | Compare cards, configs and sharded weight listings; distinguish weight size from total repository size |
+| Check free hosting quotas | [Cloudflare Workers limits](https://developers.cloudflare.com/workers/platform/limits/) | Collect Workers, static-assets and D1 limits for a concrete prototype workload |
+| Check browser compatibility | [MDN / structuredClone](https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone) | Compare three reference tables and follow a fallback guide; hydrated tables remain a stretch case |
+| Compare laptops for two monitors | [Apple Mac comparison](https://www.apple.com/mac/compare/) | Change three model selectors and verify display limitations in support articles |
+| Find a usable EV dataset | [Data.gov](https://catalog.data.gov/) | Search, filter and collect publisher/licence/resource metadata and the exact CSV URL |
+| Prepare a statistics brief | [GOV.UK / National Travel Survey 2024](https://www.gov.uk/government/statistics/national-travel-survey-2024) | Navigate to the factsheet, extract measures and scope, return and collect its PDF URL |
+| Compare accessible London routes | [TfL journey planner](https://tfl.gov.uk/plan-a-journey/) | Autocomplete, departure time, accessibility preferences and route legs; complete route generation remains untested |
+| Find a suitable reading edition | [Wikisource / Jane Austen](https://en.wikisource.org/wiki/Author:Jane_Austen) | Follow the bibliography, compare editions, count chapter links and verify destinations |
+| Inventory city-service data | [Data.gov / Philadelphia 311](https://catalog.data.gov/dataset/311-service-and-information-requests) | Compare two catalogue records, coverage, update fields and downloadable-resource URLs |
+
+These external goals are for public reading/research. They do not authorize
+messaging, buying, signing in or modifying real accounts. Large datasets and model
+weights are inspected as links/listings, without downloads. Inline PDFs are
+returned as URLs: clicking them is not advertised as a guaranteed download.
+Sites that block automation are excluded; challenges are not bypassed.
+
+Detailed source evidence: [consumer research](../research_useful_browser_tasks/findings_consumer.md)
+and [professional research](../research_useful_browser_tasks/findings_professional.md).
+
+## Run checks locally
+
+```bash
+npm run lab:build
+npm run lab:serve                 # http://127.0.0.1:4319/lab/
+npm run lab:smoke                 # 24 screens, desktop/mobile, console and overflow
+npm run ui:results                # authored local journey: cards, cursor, visible controls
+npm run benchmark:complex         # supplied action plans; no model-planning claim
+npm run benchmark:complex -- --live  # real Flash planning; spends API tokens
+npm run benchmark:real            # real GitHub/GOV.UK trials; spends API tokens
+npm run validate                  # local checks only; GitHub CI is disabled
+```
+
+Each complex execution test checks state, extracted rows and file bytes, then
+repeats a compatible learned workflow with no provider installed. Each live trial
+reports correctness, model calls, tokens, cost estimates, repairs and repeat
+outcomes. Historical failed trials remain visible; individual passes are not a
+general success-rate claim.
+
+The [aggregate authored report](../artifacts/benchmark-complex-authored.json)
+covers all eight practice workflows. The two long cases also have separate
+real-Flash reports linked above. Supplied action plans and real model plans are
+not interchangeable evidence.

package/docs/brand-mark.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title desc">
+  <title id="title">FreeComputerUse mark</title>
+  <desc id="desc">A cursor acting inside a browser window.</desc>
+  <rect x="1" y="1" width="62" height="62" rx="19" fill="#101712"/>
+  <rect x="9" y="10" width="46" height="44" rx="7" fill="#18231a" stroke="#eaf0e4" stroke-width="3"/>
+  <path d="M12 21h40" stroke="#c9ed72" stroke-width="7"/>
+  <circle cx="17" cy="16" r="1.6" fill="#101712"/>
+  <circle cx="22.5" cy="16" r="1.6" fill="#101712"/>
+  <circle cx="28" cy="16" r="1.6" fill="#101712"/>
+  <path d="M16 29h7M16 35h6" stroke="#9aaa91" stroke-linecap="round" stroke-width="2.5"/>
+  <path d="M25 25v25l7.4-7.1 6.2 12.2 5.4-2.8-6.2-12.2 11-.4z" fill="#c9ed72" stroke="#18231a" stroke-linejoin="round" stroke-width="2.4"/>
+</svg>

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "free-computer-use",
+  "version": "0.1.0",
+  "description": "Local-first AI browser automation with Playwright and user-approved actions.",
+  "homepage": "https://othmaneblial.github.io/FreeComputerUse/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OthmaneBlial/FreeComputerUse.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OthmaneBlial/FreeComputerUse/issues"
+  },
+  "keywords": [
+    "ai-agent",
+    "browser-automation",
+    "browser-use",
+    "computer-use",
+    "playwright",
+    "local-first",
+    "multi-model",
+    "openai-compatible",
+    "openai",
+    "anthropic",
+    "claude-code",
+    "chatgpt",
+    "deepseek",
+    "grok",
+    "openrouter"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "bin": {
+    "agent": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc && node scripts/copy-ui.mjs",
+    "check": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "tsx --test --test-concurrency=1 tests/*.test.ts",
+    "validate": "npm run lab:build && npm run check && npm test && npm run build && npm run security && npm audit --omit=dev --audit-level=high",
+    "agent": "tsx src/cli/index.ts",
+    "dev": "tsx src/cli/index.ts ui",
+    "demo": "tsx scripts/demo.ts",
+    "fixtures": "tsx fixtures/server.ts",
+    "benchmark": "tsx scripts/benchmark.ts",
+    "security": "node scripts/security-check.mjs --history",
+    "security:wss": "tsx scripts/wss-smoke.ts",
+    "benchmark:public": "tsx scripts/public-benchmark.ts",
+    "lab:build": "tsx scripts/build-lab.ts",
+    "lab:serve": "tsx scripts/lab-server.ts",
+    "lab:smoke": "tsx scripts/lab-smoke.ts",
+    "benchmark:complex": "tsx scripts/complex-benchmark.ts",
+    "benchmark:real": "tsx scripts/real-world-benchmark.ts",
+    "ui:smoke": "tsx scripts/ui-smoke.ts",
+    "ui:results": "tsx scripts/results-smoke.ts"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    ".env.example",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
+    "docs/*.md",
+    "docs/brand-mark.svg",
+    "assets/readme/hero.svg",
+    "assets/readme/incident-demo.gif",
+    "assets/readme/incident-evidence.json",
+    "artifacts/benchmark-public.json"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "commander": "15.0.0",
+    "playwright": "1.63.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
+    "@types/node": "26.6.1",
+    "tsx": "4.23.13",
+    "typescript": "7.0.2"
+  }
+}