Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

Get Bots past bot checks: headed browsers, Web Bot Auth, a residential proxy option, Bun 1.4.3, and a handoff that keeps its page (#772)

David McKayc7edf4aef191
diff --git a/.env.example b/.env.example
index 66ec3235..733d0b49 100644
--- a/.env.example
+++ b/.env.example
@@ -329,10 +329,25 @@ COMPUTER_TOKEN=
# docker-compose.yml. Pointing it somewhere unmounted disables login persistence.
# PROFILES_DIR=/profiles
-# Browser process used by a Bot's computer. Managed mode always uses full Chromium. `headless` is
-# the default; Linux `headed` uses a private virtual display with the same live-screen controls.
+# Browser process used by a Bot's computer. Managed mode always uses full Chromium. `headed` is the
+# default wherever a hosted computer runs (Linux: a container, a pod, the desktop app's engine): full
+# Chromium on the computer's own virtual display, behind the same live screen, which bot checks such
+# as Cloudflare's challenge far less than headless. `headless` is still available, smaller, and the
+# default only when the computer runs directly on macOS or Windows, where headed would open windows.
# COMPUTER_BROWSER_BACKEND=managed
-# COMPUTER_BROWSER_MODE=headless
+# COMPUTER_BROWSER_MODE=headed
+
+# Web Bot Auth: every request a Bot's browser makes is signed as coming from this deployment
+# (Ed25519, HTTP Message Signatures), and the public key is published at
+# <OPENBOT_PUBLIC_URL>/.well-known/http-message-signatures-directory. Unset means on whenever
+# OPENBOT_PUBLIC_URL (or BETTER_AUTH_URL) is https on a public address, because verifiers fetch the
+# key from there; off otherwise, which includes every laptop. `on` also signs behind a private https
+# address, and is refused for plain http or loopback. It only earns anything once the
+# deployment is registered with Cloudflare, a manual step: see docs/configuration.md.
+# WEB_BOT_AUTH=on
+# The signing key, an Ed25519 private key as a JSON Web Key. Unset derives one from
+# KEY_ENCRYPTION_KEY, the same on every replica, so nothing new is needed to start. Never logged.
+# WEB_BOT_AUTH_KEY=
# Opt-in installed Chrome on the same machine as a local API deployment:
# bun scripts/start-local-chrome-computer.ts
@@ -364,6 +379,12 @@ COMPUTER_TOKEN=
#
# EGRESS_PROXY_DEFAULT=http://user:[email protected]:8080
# EGRESS_PROXY_SALES_BOT=http://sales.proxy.internal:8080
+#
+# A residential or ISP proxy goes in the same place, and is the operator's choice to make knowingly:
+# the Bots' traffic then leaves from an address a consumer ISP owns, so sites see what looks like a
+# person at home rather than a datacenter. Off unless set. The egress filter still applies first.
+#
+# EGRESS_PROXY_DEFAULT=http://customer-user:[email protected]:8000
# The managed coworker AG-UI endpoint. Optional: use an HTTP(S) URL, and set MANAGED_AGENT_TOKEN
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 034757e1..7572893d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -30,7 +30,7 @@ jobs:
persist-credentials: false
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
- run: bun install --frozen-lockfile
- run: bun run format:check
- run: bun run lint
@@ -75,7 +75,7 @@ jobs:
persist-credentials: false
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
# Two installs, and the root one is load-bearing. Both packages set `types: ["bun"]` in
# their tsconfig while `@types/bun` is a root devDependency, so tsc resolves it by walking up
# to the root node_modules. Without it the typecheck fails with TS2688 on a fresh checkout.
@@ -118,19 +118,34 @@ jobs:
persist-credentials: false
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
- run: bun install --frozen-lockfile
- run: bun install --frozen-lockfile
working-directory: agent-computer
- run: bunx playwright install --with-deps chromium
working-directory: agent-computer
+ # Headless here: these launch through the profile path without the computer's own X server.
+ # The headless run of the Web Bot Auth test is also the one that checks the user agent fix.
- run: >-
bun test tests/sign-in.test.ts tests/session-cookies.test.ts tests/follows-popup.test.ts
- tests/demonstration-live.test.ts tests/webrtc-proxy.test.ts
+ tests/demonstration-live.test.ts tests/webrtc-proxy.test.ts tests/web-bot-auth-browser.test.ts
+ tests/handoff-page-restore.test.ts
working-directory: agent-computer
env:
OPENBOT_COMPUTER_BROWSER: '1'
OPENBOT_DEMONSTRATION_LIVE: '1'
+ COMPUTER_BROWSER_MODE: headless
+ # Headed is the default for hosted computers, so it is tested as one: the computer starting its
+ # own Xvfb, and the signing again with cross-site frames in processes of their own.
+ - run: bun test tests/headed-browser.test.ts
+ working-directory: agent-computer
+ env:
+ OPENBOT_HEADED_BROWSER: '1'
+ - run: xvfb-run --auto-servernum bun test tests/web-bot-auth-browser.test.ts
+ working-directory: agent-computer
+ env:
+ OPENBOT_COMPUTER_BROWSER: '1'
+ COMPUTER_BROWSER_MODE: headed
chart:
name: chart (${{ matrix.target }})
@@ -153,7 +168,7 @@ jobs:
# For the coherence check below, which is a Bun script like everything else here.
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
# Nothing rendered this chart until now, which is how four values files that produce a server
# unable to start were shipped and stayed shipped. Rendering is the cheap half; the refusals in
# validation.yaml are the half that catches a missing value before a cluster does.
@@ -218,6 +233,19 @@ jobs:
--set networkPolicy.enabled=true \
--set computers.extraEnv[0].name=EGRESS_PROXY_DEFAULT \
--set-string computers.extraEnv[0].value=http://proxy.internal:3128
+ # The residential proxy setting, whose address is a secret the template cannot read, with
+ # network policies on and no path opened to it.
+ refuses "a residential proxy with no path through the network policy" \
+ --set networkPolicy.enabled=true --set computers.egressProxy.enabled=true \
+ --set-string secrets.egressProxyUrl=http://user:[email protected]:8000
+ # The same setting switched on with no URL behind it, where this chart holds the secret.
+ if ! grep -qE '^ *enabled: true' <(sed -n '/^externalSecrets:/,/^[a-z]/p' charts/openbot/ci/${{ matrix.target }}-values.yaml) \
+ && ! grep -qE '^ *existingSecret: [^"]' <(sed -n '/^secrets:/,/^[a-z]/p' charts/openbot/ci/${{ matrix.target }}-values.yaml); then
+ refuses "a residential proxy switched on with no URL" \
+ --set computers.egressProxy.enabled=true
+ else
+ echo "skipped: the proxy URL refusal is armed only where this chart writes the Secret"
+ fi
# A delivery or directory switch with no secret behind it. Armed on every target: the chart
# requires the value when it holds the secret, and requires the store to name the key when
# a store does.
@@ -282,7 +310,7 @@ jobs:
persist-credentials: false
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
- run: bun install --frozen-lockfile
# The Bots are not root workspaces and each keeps its own lockfile. The startup tests spawn
# the real entrypoint, so its dependencies have to be installed as well.
@@ -292,6 +320,10 @@ jobs:
# Bot's own tree and not in the root one.
- run: bun install --frozen-lockfile
working-directory: agent-langgraph
+ # Same for the computer: its Web Bot Auth tests import `web-bot-auth`, which lives in
+ # agent-computer's own tree and not in the root one.
+ - run: bun install --frozen-lockfile
+ working-directory: agent-computer
# Same for the Mastra Bot: root test discovery imports its receiver tests, which load Mastra
# from that Bot's own dependency tree.
- run: bun install
@@ -321,7 +353,7 @@ jobs:
persist-credentials: false
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
- run: bun install --frozen-lockfile
- run: bun test app/tests/build-cache.test.ts
@@ -337,7 +369,7 @@ jobs:
python-version: "3.12"
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
- name: CrewAI provider-boundary regression
run: |
set -euo pipefail
@@ -430,7 +462,7 @@ jobs:
persist-credentials: false
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
- run: bun install --frozen-lockfile
- run: bun run build
@@ -449,7 +481,7 @@ jobs:
persist-credentials: false
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
- run: bun install --frozen-lockfile
# Collisions and gaps between the migration files themselves.
- run: bunx drizzle-kit check --config=drizzle.config.ts
diff --git a/.github/workflows/desktop-signing.yml b/.github/workflows/desktop-signing.yml
index 4bcf3d7d..7452aad6 100644
--- a/.github/workflows/desktop-signing.yml
+++ b/.github/workflows/desktop-signing.yml
@@ -89,7 +89,7 @@ jobs:
if ($LASTEXITCODE -ne 0) { throw 'Could not read signing certificate.' }
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
- uses: dtolnay/rust-toolchain@e2a55d2ffb04f378e9626c28d38b36d230d1e12f # master
with:
toolchain: stable
diff --git a/.github/workflows/desktop.yml b/.github/workflows/desktop.yml
index 237dfc01..dd3abf74 100644
--- a/.github/workflows/desktop.yml
+++ b/.github/workflows/desktop.yml
@@ -70,7 +70,7 @@ jobs:
persist-credentials: false
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
- uses: dtolnay/rust-toolchain@e2a55d2ffb04f378e9626c28d38b36d230d1e12f # master
with:
toolchain: stable
diff --git a/.github/workflows/publish-release.yml b/.github/workflows/publish-release.yml
index a7e7ea4a..6ef52db4 100644
--- a/.github/workflows/publish-release.yml
+++ b/.github/workflows/publish-release.yml
@@ -86,7 +86,7 @@ jobs:
persist-credentials: false
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
- env:
VERSION: ${{ needs.metadata.outputs.version }}
run: |
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 8d43bfc8..107cc552 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -53,7 +53,7 @@ jobs:
persist-credentials: false
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
with:
- bun-version: 1.3.14
+ bun-version: 1.4.3
- id: prepare
name: Write the version and promote the notes
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 25b10f07..cf3129c9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,40 @@ Newest first. `Unreleased` is what is on `main` and not yet tagged.
## Unreleased
+**Before upgrading.** Four things change for an existing deployment:
+- A hosted computer's browser is now headed by default. It uses a little more memory than headless
+ did; set `COMPUTER_BROWSER_MODE=headless` (Helm: `computers.browserMode: headless`) to keep the old
+ behaviour.
+- A deployment whose public URL is https on a public address starts signing its Bots' requests with
+ Web Bot Auth; `WEB_BOT_AUTH=off` (Helm: `config.webBotAuth: "off"`) prevents it.
+- Migration `0054_memory_on_intelligence` adds two columns to `personal_memories`. On a deployment
+ entitled to Intelligence memory, the memory sweep then copies existing reviewed, switched-on memories
+ into Intelligence, a few people at a time each minute; it is idempotent and safe to interrupt.
+ Memories awaiting review, paused or forgotten stay local until that changes.
+- With nothing saved under Admin → Automatic Learning and no `CPK_INTELLIGENCE_LEARNING_CONTAINER_ID`,
+ the server assigns its Intelligence project's `openbot` container once it exists, and `scripts/start.sh`
+ creates that container. A saved setting, including off, is never changed;
+ `OPENBOT_LEARNING_AUTO_ASSIGN=false` (Helm: `config.learning.autoAssign: false`) prevents it.
+
+### Fewer "Verify you are human" pages
+
+Sites behind Cloudflare challenged a Bot's browser on sight, and opening one could restart the
+computer and leave the person a blank page to solve. Now:
+- The computer no longer restarts on such a page, and a help request reopens the page the Bot was
+ on, so the person taking control always gets the check to solve. That handoff is the designed
+ fallback for a check a Bot cannot pass.
+- A hosted computer runs headed Chromium on its own virtual display, behind the same live screen.
+ Headless Chromium is what bot checks catch first. A computer still run headless no longer calls
+ itself `HeadlessChrome`.
+- With a public https URL, every request a Bot's browser sends is signed with Web Bot Auth and the
+ key is published at `/.well-known/http-message-signatures-directory`. Register the deployment once
+ with Cloudflare (Bot Submission Form, Request Signature) for sites that allow signed agents to let
+ Bots through. See docs/configuration.md. Every site a Bot visits sees the deployment's URL.
+- A residential or ISP proxy is a first-class setting: `EGRESS_PROXY_DEFAULT`, or on Helm
+ `computers.egressProxy` with the URL in a Secret. Off by default; turning it on makes Bots' traffic
+ look like a person's home connection, which is the operator's choice to make.
+- Bun 1.4.3 throughout, which fixes the connection crash behind the restarts.
+
### Automatic Learning assigns its container without a trip to Admin
Learning was on by default but collected nothing until somebody assigned a container. Now, when
@@ -29,11 +63,6 @@ and which Bot or source it came from, and applies those rules to everything Inte
Bot-formed memory still reaches only the Bot that formed it. Without Intelligence memory nothing changes:
OpenBot's own tables remain the store.
-**Before upgrading.** Migration `0054_memory_on_intelligence` adds two columns to `personal_memories`.
-On an entitled deployment, the memory sweep then copies existing reviewed, switched-on memories into
-Intelligence, a few people at a time each minute; it is idempotent and safe to interrupt. Memories
-awaiting review, paused or forgotten stay local until that changes.
-
## 0.2.0
**Before upgrading.** Two things change for an existing deployment:
diff --git a/Dockerfile b/Dockerfile
index 06b64c50..2f2e0dda 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -18,7 +18,7 @@
# image. Keep this version matched to `agent-computer/package.json`: bump both or neither.
FROM node:24.18.1-bookworm-slim AS node-toolchain
-FROM oven/bun:1.3.14@sha256:e10577f0db68676a7024391c6e5cb4b879ebd17188ab750cf10024a6d700e5c4 AS bun-toolchain
+FROM oven/bun:1.4.3@sha256:ec06c3b6cea04192ae6770c434f668ca41d343ad19fa6472216c7b48be39c598 AS bun-toolchain
FROM ubuntu:24.04 AS base
diff --git a/agent-bot/Dockerfile b/agent-bot/Dockerfile
index 249f57d9..7a33f88e 100644
--- a/agent-bot/Dockerfile
+++ b/agent-bot/Dockerfile
@@ -1,6 +1,6 @@
# The built-in Bot only speaks AG-UI and a model provider; the browser runs in a separate computer
# container so either side can be replaced independently.
-FROM oven/bun:1.3-alpine
+FROM oven/bun:1.4-alpine
WORKDIR /app
RUN chown bun:bun /app
diff --git a/agent-computer/Dockerfile b/agent-computer/Dockerfile
index 8fac490a..42bf6da3 100644
--- a/agent-computer/Dockerfile
+++ b/agent-computer/Dockerfile
@@ -3,7 +3,7 @@
# The image tag and Playwright dependency must be pinned to the same exact version. Bump both or
# neither.
FROM node:24.18.1-bookworm-slim AS node-toolchain
-FROM oven/bun:1.3.14@sha256:e10577f0db68676a7024391c6e5cb4b879ebd17188ab750cf10024a6d700e5c4 AS bun-toolchain
+FROM oven/bun:1.4.3@sha256:ec06c3b6cea04192ae6770c434f668ca41d343ad19fa6472216c7b48be39c598 AS bun-toolchain
FROM ubuntu:24.04
diff --git a/agent-computer/bun.lock b/agent-computer/bun.lock
index 929dce1d..49615ea9 100644
--- a/agent-computer/bun.lock
+++ b/agent-computer/bun.lock
@@ -7,6 +7,7 @@
"dependencies": {
"playwright": "1.62.1",
"spiffe": "^0.5.1",
+ "web-bot-auth": "0.2.0",
"yaml": "^2.9.0",
},
"devDependencies": {
@@ -95,8 +96,12 @@
"get-caller-file": ["[email protected]", "", {}, "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="],
+ "http-message-sig": ["[email protected]", "", { "dependencies": { "structured-headers": "2.0.3" } }, "sha512-ossX5ZDDCRD+YtMzryp3gCg+5wqLFes1RVChEFmEE9Bzbd49Ts2IIIvFnTst/mYWx0ivrxrTTPsIIKKJ07s7+w=="],
+
"is-fullwidth-code-point": ["[email protected]", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
+ "jsonwebkey-thumbprint": ["[email protected]", "", {}, "sha512-4m/gJEUQH8N2NfvZFjCL8/E+vlt0FlrmHoR4T93CEXQRkC64qwRi6oQri4/eqLVXqEqXYCss0+Q7pLx6vJBqzw=="],
+
"lodash.camelcase": ["[email protected]", "", {}, "sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA=="],
"long": ["[email protected]", "", {}, "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA=="],
@@ -121,6 +126,8 @@
"strip-ansi": ["[email protected]", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
+ "structured-headers": ["[email protected]", "", {}, "sha512-4g5yxhlDMClRwCcfKfLeS7Z8yAVdOWGDADwm80Poh1iReU2KVKLGBlqwpHWJ2qovq0+ZIf1atAEO1eua2o9Rgg=="],
+
"tslib": ["[email protected]", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
"tsyringe": ["[email protected]", "", { "dependencies": { "tslib": "^1.9.3" } }, "sha512-axr3IdNuVIxnaK5XGEUFTu3YmAQ6lllgrvqfEoR16g/HGnYY/6We4oWENtAnzK6/LpJ2ur9PAb80RBt7/U4ugw=="],
@@ -129,6 +136,8 @@
"undici-types": ["[email protected]", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+ "web-bot-auth": ["[email protected]", "", { "dependencies": { "http-message-sig": "^0.3.0", "jsonwebkey-thumbprint": "^0.1.0", "structured-headers": "2.0.3" } }, "sha512-3DJ72ZhWK4a3yCHCClF6q32g03X37DJlpyASYeBroGTRj/qFkHNcPwkESc3FLigjW6NOWF6MR+Hat9AfOqqtAQ=="],
+
"webcrypto-core": ["[email protected]", "", { "dependencies": { "@peculiar/asn1-schema": "^2.7.0", "@peculiar/json-schema": "^1.1.12", "@peculiar/utils": "^2.0.2", "asn1js": "^3.0.10", "tslib": "^2.8.1" } }, "sha512-gsXecm82UQNlTBURJGuqOWy1Ww08S3kZUcr3aOJS02Pk0xLtkfeUAVC0u0xhgdonFme80edSJUIJyuvL/7250Q=="],
"wrap-ansi": ["[email protected]", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q=="],
diff --git a/agent-computer/package.json b/agent-computer/package.json
index 4a21501a..52c56129 100644
--- a/agent-computer/package.json
+++ b/agent-computer/package.json
@@ -11,6 +11,7 @@
"dependencies": {
"playwright": "1.62.1",
"spiffe": "^0.5.1",
+ "web-bot-auth": "0.2.0",
"yaml": "^2.9.0"
},
"devDependencies": {
diff --git a/agent-computer/src/browser-runtime.ts b/agent-computer/src/browser-runtime.ts
index b4123fc8..50a2b144 100644
--- a/agent-computer/src/browser-runtime.ts
+++ b/agent-computer/src/browser-runtime.ts
@@ -21,8 +21,19 @@ export function browserRuntimeFromEnv(
);
}
const local = backend === "local-chrome";
+ /*
+ * Headed wherever a hosted computer runs, which is Linux: a container, a Kubernetes pod, the
+ * desktop app's Podman machine. Headless Chromium is the browser bot checks are best at spotting
+ * (it says `HeadlessChrome`, renders without a GPU path a person's browser has, and is missing what
+ * a windowed browser has), and Cloudflare in front of ChatGPT, Canva and the like challenges it on
+ * sight. The window goes to the in-container X server (`virtual-display.ts`), so nothing appears
+ * anywhere and the live screen is unchanged. A developer running this directly on a Mac or Windows
+ * keeps headless, where a headed default would open windows on their desktop.
+ * `COMPUTER_BROWSER_MODE=headless` still chooses headless anywhere.
+ */
const mode = browserModeFromEnv(
- env.COMPUTER_BROWSER_MODE?.trim() || (local ? "headed" : "headless"),
+ env.COMPUTER_BROWSER_MODE?.trim() ||
+ (local || platform === "linux" ? "headed" : "headless"),
);
if (local && mode !== "headed") {
throw new Error(
diff --git a/agent-computer/src/challenge.ts b/agent-computer/src/challenge.ts
index 668753eb..bb209aee 100644
--- a/agent-computer/src/challenge.ts
+++ b/agent-computer/src/challenge.ts
@@ -95,6 +95,9 @@ export async function detectChallenge(
result.reason,
options.toolCallId,
result.kind,
+ // The challenge's own address, so a browser that restarts before anyone takes control is sent
+ // back to it rather than handing the person a blank page with nothing to solve.
+ page.url(),
).request;
if (!request)
throw new Error("The challenge handoff did not produce a request.");
diff --git a/agent-computer/src/control-store.ts b/agent-computer/src/control-store.ts
index 6dbf1d65..60f09e7c 100644
--- a/agent-computer/src/control-store.ts
+++ b/agent-computer/src/control-store.ts
@@ -36,6 +36,8 @@ const statuses = new Set([
"interrupted",
]);
const sources = new Set(["model", "manual", "cloudflare", "visible-challenge"]);
+/** The longest page address a request keeps. Longer ones are not kept rather than cut. */
+export const MAX_REQUEST_URL = 2048;
const record = (v: unknown): v is Record<string, unknown> =>
!!v && typeof v === "object" && !Array.isArray(v);
const timestamp = (v: unknown): v is string =>
@@ -60,6 +62,9 @@ function validRequest(v: unknown): v is HandoffRequest {
(v.expiresAt === undefined || timestamp(v.expiresAt)) &&
(v.finishedAt === undefined || timestamp(v.finishedAt)) &&
(v.interruption === undefined || typeof v.interruption === "string") &&
+ (v.url === undefined ||
+ (typeof v.url === "string" && v.url.length <= MAX_REQUEST_URL)) &&
+ (v.keepsPage === undefined || typeof v.keepsPage === "boolean") &&
(v.status !== "waiting" || timestamp(v.expiresAt)) &&
(v.status === "waiting" || v.expiresAt === undefined) &&
(v.status === "waiting" || v.status === "taken"
diff --git a/agent-computer/src/control.ts b/agent-computer/src/control.ts
index 8f519401..2041b0f3 100644
--- a/agent-computer/src/control.ts
+++ b/agent-computer/src/control.ts
@@ -4,7 +4,11 @@ import type {
HandoffSource,
} from "../../shared/computer-control";
import { createActionBarrier } from "./action-barrier";
-import type { ControlStore, StoredControl } from "./control-store";
+import {
+ type ControlStore,
+ MAX_REQUEST_URL,
+ type StoredControl,
+} from "./control-store";
export type ControlState = ComputerControlState;
export class ControlError extends Error {
constructor(message: string) {
@@ -40,6 +44,26 @@ type Options = {
drainTimeoutMs?: number;
};
+/**
+ * A page worth sending a blank browser back to: a real http(s) address, short enough to keep.
+ *
+ * Cloudflare's `__cf_chl_*` parameters are dropped. They are one-time tokens for the challenge that
+ * was on screen, which a restart has already lost, so the page kept is the one the Bot was opening.
+ */
+export function pageWorthKeeping(url: unknown): string | undefined {
+ if (typeof url !== "string" || url.length > MAX_REQUEST_URL) return undefined;
+ try {
+ const parsed = new URL(url);
+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+ return undefined;
+ for (const name of [...parsed.searchParams.keys()])
+ if (name.startsWith("__cf_chl_")) parsed.searchParams.delete(name);
+ return parsed.toString();
+ } catch {
+ return undefined;
+ }
+}
+
/** Request identity is durable; secret values never enter this state machine. */
export function createControl(
now: () => string = () => new Date().toISOString(),
@@ -92,16 +116,54 @@ export function createControl(
throw storageError;
}
}
+ /**
+ * End a request.
+ *
+ * Its page goes with it unless a restart interrupted it. A page address can carry a one-time token
+ * (a sign-in code, a reset or magic link), and the record is kept on disk for a month: the address
+ * is only needed while the request is live, or so a request raised after a restart can reopen it.
+ */
function finish(
request: HandoffRequest,
status: "completed" | "cancelled" | "expired" | "interrupted",
interruption?: string,
+ keepPage = false,
) {
request.status = status;
request.updatedAt = now();
request.finishedAt = request.updatedAt;
delete request.expiresAt;
if (interruption) request.interruption = interruption;
+ if (status === "interrupted" && keepPage && request.url)
+ request.keepsPage = true;
+ else {
+ delete request.url;
+ delete request.keepsPage;
+ }
+ }
+ /**
+ * Drop every page a finished request no longer needs: all of them, except the latest request's when
+ * a restart interrupted it within the help TTL. Also cleans records written before pages were
+ * dropped on finish. True when something changed.
+ */
+ function scrubPages(at: string): boolean {
+ let changed = false;
+ const latest = data.requests.at(-1);
+ for (const request of data.requests) {
+ if ((!request.url && !request.keepsPage) || active(request)) continue;
+ const inheritable =
+ request === latest &&
+ request.status === "interrupted" &&
+ request.keepsPage === true &&
+ request.url !== undefined &&
+ request.finishedAt !== undefined &&
+ Date.parse(at) - Date.parse(request.finishedAt) <= HELP_REQUEST_TTL_MS;
+ if (inheritable) continue;
+ delete request.url;
+ delete request.keepsPage;
+ changed = true;
+ }
+ return changed;
}
function syncAdmission() {
if (active(current()) || data.holder === "human" || data.recoveryRequired)
@@ -110,6 +172,7 @@ export function createControl(
}
function expire() {
if (storageError) throw storageError;
+ if (scrubPages(now())) persist();
const request = current();
if (
request?.status === "waiting" &&
@@ -163,13 +226,33 @@ export function createControl(
);
return request;
}
- function interrupt(reason: string): ControlState {
+ /**
+ * The computer stopped serving the current request.
+ *
+ * `keepPage` only for a restart underneath the request (the process or the browser coming back up):
+ * then a request raised from the blank browser that follows can reopen the page. A deliberate stop
+ * or reset is someone moving on, and reset is meant to forget everything, so neither keeps it.
+ */
+ function interrupt(
+ reason: string,
+ { keepPage = false }: { keepPage?: boolean } = {},
+ ): ControlState {
const request = current();
// Recovery is for a page a person was driving: what they left it as is unknown until someone
// looks. A request nobody took left the page exactly as the Bot had it, and holding the Bot
// until a person "checks" a page no person touched stranded it asking for control it had.
const personHadIt = data.holder === "human" || request?.status === "taken";
- if (request && active(request)) finish(request, "interrupted", reason);
+ if (request && active(request))
+ finish(request, "interrupted", reason, keepPage);
+ if (!keepPage) {
+ // A restart may already have interrupted this request and kept its page (a stop closes the
+ // browser first, which reports as a replacement). The stop or reset is the last word.
+ const latest = data.requests.at(-1);
+ if (latest?.status === "interrupted") {
+ delete latest.url;
+ delete latest.keepsPage;
+ }
+ }
if (personHadIt) data.recoveryRequired = true;
data.holder = "bot";
data.since = now();
@@ -184,13 +267,39 @@ export function createControl(
if (restored && (active(current()) || data.holder === "human"))
interrupt(
"The computer process restarted; the previous page was interrupted. Request help again to continue.",
+ { keepPage: true },
);
+ // Records saved before finished requests dropped their pages are cleaned on first read.
+ if (restored && scrubPages(now())) persist();
if (restored && !active(current()) && data.holder === "bot") {
data.resumeSnapshotRequired = true;
persist();
}
syncAdmission();
+ /**
+ * The page of the most recent request, when that request was interrupted recently.
+ *
+ * Only the most recent one: a request that finished, was cancelled or expired after an
+ * interruption means the person or the Bot moved on, and an older page must not come back.
+ */
+ function interruptedPage(at: string): string | undefined {
+ const latest = data.requests.at(-1);
+ if (
+ latest?.status !== "interrupted" ||
+ latest.keepsPage !== true ||
+ !latest.url ||
+ !latest.finishedAt
+ )
+ return undefined;
+ if (Date.parse(at) - Date.parse(latest.finishedAt) <= HELP_REQUEST_TTL_MS)
+ return latest.url;
+ // Past the TTL the address is only a liability; requestHelp persists right after.
+ delete latest.url;
+ delete latest.keepsPage;
+ return undefined;
+ }
+
function rememberAlias(toolCallId: string, requestId: string) {
Object.defineProperty(data.aliases, toolCallId, {
value: requestId,
@@ -206,6 +315,7 @@ export function createControl(
reason: unknown,
toolCallId?: string,
source: HandoffSource = "model",
+ pageUrl?: string,
): ControlState {
expire();
if (
@@ -230,6 +340,13 @@ export function createControl(
}
barrier.close(); // Before any persistence or awaited browser operation.
const at = now();
+ /*
+ * The page this request is about. A browser that restarted comes back blank, so a request
+ * raised on a blank page inherits the page of the request a restart interrupted, if that was
+ * recent: the Bot asking again after "the computer process restarted" is still asking about
+ * the page it lost, and the person it hands control to needs that page in front of them.
+ */
+ const url = pageWorthKeeping(pageUrl) ?? interruptedPage(at);
const request: HandoffRequest = {
id: crypto.randomUUID(),
toolCallId,
@@ -242,6 +359,7 @@ export function createControl(
createdAt: at,
updatedAt: at,
expiresAt: new Date(Date.parse(at) + HELP_REQUEST_TTL_MS).toISOString(),
+ ...(url ? { url } : {}),
};
data.currentRequestId = request.id;
data.requests.push(request);
@@ -309,6 +427,17 @@ export function createControl(
return get();
},
interrupt,
+ /**
+ * Where a blank browser should be sent before a person works the current handoff.
+ *
+ * The live request's page, while one is waiting or held. Nothing otherwise: once the request
+ * is over, whatever the browser shows is the Bot's business again.
+ */
+ pageToRestore(): string | undefined {
+ expire();
+ const request = current();
+ return active(request) ? request?.url : undefined;
+ },
snapshotTaken() {
if (
data.holder === "bot" &&
diff --git a/agent-computer/src/egress.ts b/agent-computer/src/egress.ts
index a1fe5635..bd651d3f 100644
--- a/agent-computer/src/egress.ts
+++ b/agent-computer/src/egress.ts
@@ -580,29 +580,110 @@ async function decide(
}
/**
- * Connection options that reach a name through the addresses already checked, and nothing else.
+ * The checked addresses in the order they are tried: IPv4 first, then IPv6, each in DNS order.
*
- * Every address the name resolved to passed the deny check, so any of them may be tried. Node's own
- * Happy Eyeballs (`autoSelectFamily`, RFC 8305) then tries them in turn, so an AAAA answer on a
- * computer with no IPv6 route falls back to the A record instead of failing. The `lookup` answers
- * from the checked list without asking DNS, which is what keeps the pin: the name is never resolved
- * a second time. A literal address needs neither.
+ * IPv4 first because a container network is the usual place this runs, and many have no IPv6 route:
+ * an AAAA answer tried first there costs a full attempt timeout on every connection.
+ */
+export function connectOrder(addresses: readonly string[]): string[] {
+ return [
+ ...addresses.filter((address) => isIP(address) !== 6),
+ ...addresses.filter((address) => isIP(address) === 6),
+ ];
+}
+
+/** How long one address may take to accept before the next checked address is tried. */
+export const CONNECT_ATTEMPT_TIMEOUT_MS = 3_000;
+
+/**
+ * Connect to a name through the addresses already checked, one at a time, and nothing else.
+ *
+ * Every address the name resolved to passed the deny check, so any of them may be tried; a literal
+ * address is the only one tried. The name is never resolved a second time, which is what keeps the
+ * pin. Each attempt connects to one literal address, so no lookup runs and no runtime fallback logic
+ * is involved: this loop is the fallback.
+ *
+ * NOT `autoSelectFamily` WITH THE CHECKED LIST, WHICH THIS USED TO BE. Bun's `node:net` walks a list
+ * of addresses with a timer that can fire after the connection it belongs to has been torn down, and
+ * then throws `TypeError: null is not an object (evaluating 'context')` from
+ * `internalConnectMultipleTimeout` (oven-sh/bun#25633, still reproducing on 1.3.13 and seen here on
+ * 1.3.14). The throw is in a timer, so nothing catches it and the computer process exits. A
+ * Cloudflare-fronted site resolves to several addresses and a challenge page opens and abandons many
+ * connections at once, so opening one in a Bot's browser restarted the computer and lost the page the
+ * person was being asked to solve.
+ *
+ * Bun fixed the timer in 1.4.0 (oven-sh/bun#32660, which this repository now runs on 1.4.3, where
+ * Bun's own regression fixture passes and fails on 1.3.14). Kept anyway: walking the checked list
+ * ourselves is what pins the connection to addresses that passed the deny check, so it is the right
+ * shape regardless of the runtime bug, and it costs nothing a person would notice.
+ */
+export function connectInTurn(
+ target: { host: string; port: number; addresses?: readonly string[] },
+ onReady: (socket: Socket) => void,
+ onError: (error: Error) => void,
+ attemptTimeoutMs = CONNECT_ATTEMPT_TIMEOUT_MS,
+): void {
+ const queue = target.addresses?.length
+ ? connectOrder(target.addresses)
+ : [target.host];
+ let lastError: Error | undefined;
+ const attempt = (index: number) => {
+ const address = queue[index];
+ if (address === undefined) {
+ onError(lastError ?? new Error(`Could not connect to ${target.host}.`));
+ return;
+ }
+ let settled = false;
+ const socket = connect({ host: address, port: target.port });
+ const moveOn = (error: Error) => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ lastError = error;
+ socket.destroy();
+ attempt(index + 1);
+ };
+ const timer = setTimeout(
+ () =>
+ moveOn(new Error(`${address}:${target.port} did not answer in time.`)),
+ attemptTimeoutMs,
+ );
+ socket.once("error", moveOn);
+ socket.once("connect", () => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ socket.off("error", moveOn);
+ // From here an error belongs to the caller, exactly as it did when it registered its own.
+ socket.once("error", onError);
+ onReady(socket);
+ });
+ };
+ attempt(0);
+}
+
+/**
+ * Request options that reach a name through one checked address, without a second lookup.
+ *
+ * For plain HTTP, where the request library owns the socket. One address rather than the list, for
+ * the reason given on {@link connectInTurn}: the list is what sends Bun down its crashing path. The
+ * first IPv4 address is chosen, so a computer with no IPv6 route still connects.
*/
function pinnedTo(addresses: readonly string[] | undefined) {
if (!addresses?.length) return {};
- const entries = addresses.map((address) => ({
- address,
- family: isIP(address) === 6 ? 6 : 4,
- }));
+ const [address] = connectOrder(addresses);
+ if (address === undefined) return {};
+ const family = isIP(address) === 6 ? 6 : 4;
return {
- autoSelectFamily: true,
+ autoSelectFamily: false,
lookup: (
_host: string,
options: { all?: boolean } | number | undefined,
callback: (...args: unknown[]) => void,
) => {
- if (typeof options === "object" && options?.all) callback(null, entries);
- else callback(null, entries[0]?.address, entries[0]?.family);
+ if (typeof options === "object" && options?.all)
+ callback(null, [{ address, family }]);
+ else callback(null, address, family);
},
};
}
@@ -654,15 +735,7 @@ function tunnel(
onError: (error: Error) => void,
) {
if (!upstream) {
- const socket = connect(
- {
- host: target.host,
- port: target.port,
- ...(pinnedTo(target.addresses) as object),
- },
- () => onReady(socket),
- );
- socket.once("error", onError);
+ connectInTurn(target, onReady, onError);
return;
}
const via = upstreamAddress(upstream);
diff --git a/agent-computer/src/index.ts b/agent-computer/src/index.ts
index 8863fc75..01ce9a2f 100644
--- a/agent-computer/src/index.ts
+++ b/agent-computer/src/index.ts
@@ -1,4 +1,5 @@
import { mkdir, rm, writeFile } from "node:fs/promises";
+import { setDefaultAutoSelectFamily } from "node:net";
import { join } from "node:path";
import { serve } from "bun";
import type { Page } from "playwright";
@@ -52,6 +53,7 @@ import { type BotSession, createSessions } from "./sessions";
import { createShell } from "./shell";
import { fillSignIn, parseSignInFill } from "./sign-in";
import { startVirtualDisplay } from "./virtual-display";
+import { applyWebBotAuthPush } from "./web-bot-auth";
import {
createWorkspace,
WorkspaceFileError,
@@ -105,6 +107,15 @@ if (!COMPUTER_TOKEN) {
process.exit(1);
}
+/*
+ * No multi-address connect anywhere in this process. Bun turns it on by default, and its timer can
+ * throw from `internalConnectMultipleTimeout` after the connection is gone, which exits the process
+ * (oven-sh/bun#25633, fixed in Bun 1.4.0, kept as defence in depth). The egress filter already
+ * connects one checked address at a time (see `connectInTurn`); this covers every other connect here,
+ * such as reaching an upstream proxy by name.
+ */
+setDefaultAutoSelectFamily(false);
+
const RUNTIME = browserRuntimeFromEnv(process.env);
const BROWSER_MODE = RUNTIME.mode;
const VIRTUAL_DISPLAY = await startVirtualDisplay(
@@ -305,6 +316,73 @@ async function currentPage(
return page;
}
+/** A browser that has not been sent anywhere, which is what a restarted one shows. */
+function isBlankPage(url: string): boolean {
+ return (
+ url === "" ||
+ url === "about:blank" ||
+ url.startsWith("chrome://newtab") ||
+ url.startsWith("chrome://new-tab-page")
+ );
+}
+
+/**
+ * Put the page a handoff is about back in front of the person, when the browser came back blank.
+ *
+ * A browser restarts underneath a waiting request more often than it should: Chromium crashing, the
+ * idle sweep or the cap closing it, the whole computer restarting. Each of those relaunches onto
+ * `about:blank`, and before this a person who took control was handed a blank screen with nothing to
+ * solve while the Bot waited for them to solve it. The request carries the page it was raised on, so
+ * the computer opens it again first. Through the same navigation the Bot uses, so the egress filter
+ * and the page-access rule still decide whether it may load.
+ *
+ * Only a blank browser is touched. A person or a site that moved the page somewhere else meant to.
+ * Best effort: a page that will not load is logged and the handoff goes ahead, because a person in
+ * front of a blank browser can still type the address, and a refused handoff helps nobody.
+ */
+const restoringPages = new Set<string>();
+async function restoreHandoffPage(botId: string): Promise<void> {
+ // One at a time per Bot: the help call and "Take control" both start one, and the second would
+ // navigate again over the first while it is still loading.
+ if (restoringPages.has(botId)) return;
+ const session = sessions.for(botId);
+ const want = session.control.pageToRestore();
+ if (!want) return;
+ // Run in the background, so the help call and "Take control" answer at once. Starting the browser
+ // can take a while; by the time it is up the person may already be driving, or the request over.
+ const inputsBefore = session.humanInputs;
+ restoringPages.add(botId);
+ try {
+ const target = await currentPage(botId);
+ if (!isBlankPage(target.url())) return;
+ if (
+ session.humanInputs !== inputsBefore ||
+ session.control.pageToRestore() !== want
+ )
+ return;
+ await navigateWebPage(target, want, RUNTIME.backend, NAVIGATION_TIMEOUT_MS);
+ // A new document, so every ref handed out before it is retired, as after any navigation.
+ session.snapshotId += 1;
+ console.info(
+ JSON.stringify({
+ type: "computer-handoff-page-restored",
+ botId,
+ origin: new URL(want).origin,
+ }),
+ );
+ } catch (error) {
+ console.info(
+ JSON.stringify({
+ type: "computer-handoff-page-not-restored",
+ botId,
+ reason: error instanceof Error ? error.message : String(error),
+ }),
+ );
+ } finally {
+ restoringPages.delete(botId);
+ }
+}
+
/**
* The page as text, the way a reader sees it.
*
@@ -598,6 +676,7 @@ serve<StreamData>({
ws.send(JSON.stringify({ type: "error", error: TAKE_CONTROL_FIRST }));
return;
}
+ session.humanInputs += 1;
try {
const recorded = ws.data.recordingId
? await describeHumanGesture(
@@ -678,8 +757,16 @@ serve<StreamData>({
return json({ error: "That is not a usable bot id." }, 400);
}
// The admin network policy, pushed by the server on every change; applied without a restart.
- if (url.pathname === "/egress-policy" && request.method === "PUT")
- return handleEgressPolicyRequest(botId, request);
+ // The deployment's Web Bot Auth key rides the same push (see `web-bot-auth.ts`).
+ if (url.pathname === "/egress-policy" && request.method === "PUT") {
+ const body = (await request
+ .clone()
+ .json()
+ .catch(() => null)) as { webBotAuth?: unknown } | null;
+ const applied = await handleEgressPolicyRequest(botId, request);
+ if (applied.ok) await applyWebBotAuthPush(body?.webBotAuth);
+ return applied;
+ }
const session = sessions.for(botId);
/*
@@ -750,9 +837,19 @@ serve<StreamData>({
typeof body.toolCallId !== "string"
)
return json({ error: "toolCallId must be a string." }, 400);
- return json(
- session.control.requestHelp(body?.reason, body?.toolCallId),
+ // The page the Bot is stuck on, recorded with the request. A browser that will not start is
+ // no reason to refuse the request: the person is the one who can see why.
+ const stuckOn = await currentPage(botId).catch(() => undefined);
+ const state = session.control.requestHelp(
+ body?.reason,
+ body?.toolCallId,
+ "model",
+ stuckOn?.url(),
);
+ // Not awaited: reopening the page can take a navigation timeout plus a cold browser start,
+ // and the Bot's help call must not wait on it. It catches its own errors.
+ void restoreHandoffPage(botId);
+ return json(state);
}
// The Bot asking for one value it must not be told. It has already focused the field.
@@ -872,8 +969,13 @@ serve<StreamData>({
} | null;
if (typeof body?.requestId !== "string" || !body.requestId.trim())
return json({ error: "A requestId is required." }, 400);
- if (url.pathname === "/control/take")
- return json(await session.control.take(body.requestId));
+ if (url.pathname === "/control/take") {
+ const taken = await session.control.take(body.requestId);
+ // The browser may have restarted while the request waited; give the person the page. In the
+ // background, so "Take control" answers at once; the live screen shows the page as it loads.
+ void restoreHandoffPage(botId);
+ return json(taken);
+ }
if (url.pathname === "/control/cancel")
return json(session.control.cancel(body.requestId));
return json(session.control.release(body.requestId));
@@ -886,6 +988,7 @@ serve<StreamData>({
if (!session.control.humanMayDrive()) {
return json({ error: TAKE_CONTROL_FIRST }, 409);
}
+ session.humanInputs += 1;
const body = (await request.json().catch(() => null)) as Record<
string,
unknown
diff --git a/agent-computer/src/page-network.ts b/agent-computer/src/page-network.ts
new file mode 100644
index 00000000..f0dcfb46
--- /dev/null
+++ b/agent-computer/src/page-network.ts
@@ -0,0 +1,418 @@
+import type { BrowserContext, CDPSession, Page } from "playwright";
+import {
+ onWebBotAuthChange,
+ signedHeaders,
+ webBotAuthEnabled,
+} from "./web-bot-auth";
+
+/**
+ * What a Bot's browser says about itself on the network: its user agent, and its Web Bot Auth
+ * signature.
+ *
+ * ON THE WIRE, ONE BROWSER-LEVEL SESSION. The DevTools `Fetch` domain enabled on the browser target
+ * pauses every request the browser sends, whichever target sent it: pages, cross-site frames in
+ * processes of their own, dedicated workers, service workers and their script fetches. Each paused
+ * request is continued with its headers amended. That is after the page has decided the request and
+ * before the network stack sends it, so cookies are still attached, no CORS preflight is added, TLS is
+ * Chromium's own, and the request still goes through the egress filter like any other. Verified
+ * against a real Chromium in `tests/web-bot-auth-browser.test.ts`, for every one of those request
+ * kinds.
+ *
+ * Not Playwright's `route()`: routing turns off the browser's HTTP cache for the whole context (every
+ * asset fetched afresh on every page, which a site sees and a person waits for), and it does not see
+ * what a service worker sends.
+ *
+ * IN JAVASCRIPT, PER PAGE, AND ONLY HEADLESS. A headless browser names itself `HeadlessChrome` in its
+ * user agent and in its client hints. The wire is fixed above for every request; what a page's script
+ * reads (`navigator.userAgent`, `navigator.userAgentData`) is fixed per page with
+ * `Network.setUserAgentOverride`, and per cross-site frame by auto-attaching to each one, paused
+ * before it runs. A headed browser says `Chrome` already and needs none of this.
+ */
+
+type Brand = { brand: string; version: string };
+
+type UserAgentOverride = {
+ userAgent: string;
+ userAgentMetadata?: {
+ brands: Brand[];
+ fullVersionList: Brand[];
+ platform: string;
+ platformVersion: string;
+ architecture: string;
+ model: string;
+ mobile: boolean;
+ bitness: string;
+ wow64: boolean;
+ };
+};
+
+/** The two calls this needs from a DevTools session, whether Playwright's or one relayed through it. */
+type Target = {
+ send(method: string, params?: object): Promise<unknown>;
+ on(event: string, listener: (params: never) => void): void;
+};
+
+function fromPlaywright(session: CDPSession): Target {
+ return {
+ send: (method, params) =>
+ session.send(method as never, params as never) as Promise<unknown>,
+ on: (event, listener) => {
+ session.on(event as never, listener as never);
+ },
+ };
+}
+
+/* ----------------------------------- the wire: every request ----------------------------------- */
+
+type BrowserNetwork = {
+ target: Target;
+ headless: boolean;
+ /** The words a headless browser sends that a headed one does not, and what to send instead. */
+ wire?: { userAgent: string; dropBrand: string };
+ intercepting: boolean;
+ /** Switches are applied in order, so a quick on-off-on cannot leave the browser in the wrong state. */
+ chain: Promise<void>;
+};
+
+const browsers = new Set<BrowserNetwork>();
+
+onWebBotAuthChange(() => {
+ for (const browser of browsers) follow(browser);
+});
+
+/** Intercept while there is something to change: always when headless, and while signing is on. */
+function follow(browser: BrowserNetwork) {
+ browser.chain = browser.chain.then(async () => {
+ const want = browser.headless || webBotAuthEnabled();
+ if (want === browser.intercepting) return;
+ browser.intercepting = want;
+ try {
+ if (want) {
+ await browser.target.send("Fetch.enable", {
+ patterns: [{ urlPattern: "*", requestStage: "Request" }],
+ });
+ } else {
+ await browser.target.send("Fetch.disable");
+ }
+ } catch {
+ // The browser closed between the switch and the command, which leaves nothing to switch.
+ }
+ });
+}
+
+/** `sec-ch-ua` and `sec-ch-ua-full-version-list` without one brand. */
+function withoutBrand(value: string, brand: string): string {
+ return value
+ .split(/,\s*/)
+ .filter((entry) => !entry.startsWith(`"${brand}"`))
+ .join(", ");
+}
+
+/** A headless browser's headers as the same browser sends them headed. */
+function headedHeaders(
+ headers: Record<string, string>,
+ wire: BrowserNetwork["wire"],
+): Record<string, string> {
+ if (!wire) return headers;
+ // Set even where the paused request has none yet: a service worker's script fetch gets its user
+ // agent from the network stack after this point, which would be the headless one.
+ const out: Record<string, string> = { "User-Agent": wire.userAgent };
+ for (const [name, value] of Object.entries(headers)) {
+ const lower = name.toLowerCase();
+ if (lower === "user-agent") continue;
+ if (lower === "sec-ch-ua" || lower === "sec-ch-ua-full-version-list")
+ out[name] = withoutBrand(value, wire.dropBrand);
+ else out[name] = value;
+ }
+ return out;
+}
+
+let signingFailureLogged = false;
+
+type RequestPaused = {
+ requestId: string;
+ request: { url: string; method: string; headers: Record<string, string> };
+};
+
+async function continueRequest(browser: BrowserNetwork, event: RequestPaused) {
+ const original = event.request.headers;
+ const fixed = headedHeaders(original, browser.wire);
+ let headers: { name: string; value: string }[] | undefined;
+ try {
+ headers = await signedHeaders(
+ event.request.method,
+ event.request.url,
+ fixed,
+ );
+ } catch (error) {
+ // Sent unsigned rather than held: a request that never continues is a page that never loads.
+ if (!signingFailureLogged) {
+ signingFailureLogged = true;
+ console.warn(
+ JSON.stringify({
+ type: "computer-web-bot-auth-sign-failed",
+ error: error instanceof Error ? error.message : String(error),
+ }),
+ );
+ }
+ }
+ if (!headers && fixed !== original) {
+ headers = Object.entries(fixed).map(([name, value]) => ({ name, value }));
+ }
+ await browser.target
+ .send("Fetch.continueRequest", {
+ requestId: event.requestId,
+ ...(headers ? { headers } : {}),
+ })
+ .catch(() => undefined);
+}
+
+/**
+ * Attach a launched browser. Awaited before its first navigation, so the first request a site sees is
+ * already signed and already says `Chrome`.
+ */
+export async function attachBrowserNetwork(
+ context: BrowserContext,
+ options: { headless: boolean },
+): Promise<void> {
+ const owner = context.browser();
+ if (!owner) {
+ console.warn(
+ JSON.stringify({
+ type: "computer-browser-network-unavailable",
+ note: "No browser-level DevTools session, so requests go out unsigned.",
+ }),
+ );
+ return;
+ }
+ const session = await owner.newBrowserCDPSession();
+ const target = fromPlaywright(session);
+ const browser: BrowserNetwork = {
+ target,
+ headless: options.headless,
+ intercepting: false,
+ chain: Promise.resolve(),
+ };
+ if (options.headless) {
+ const version = (await target
+ .send("Browser.getVersion")
+ .catch(() => undefined)) as { userAgent?: string } | undefined;
+ if (version?.userAgent?.includes("HeadlessChrome")) {
+ browser.wire = {
+ // The browser-reported string is the full version; what a page sends is the reduced one,
+ // which is what a site expects from Chrome. Taken from the page below when it can be.
+ userAgent: version.userAgent.replace("HeadlessChrome/", "Chrome/"),
+ dropBrand: "HeadlessChrome",
+ };
+ }
+ }
+ target.on("Fetch.requestPaused", (event: RequestPaused) => {
+ void continueRequest(browser, event);
+ });
+ browsers.add(browser);
+ context.once("close", () => browsers.delete(browser));
+ follow(browser);
+ await browser.chain;
+ const page = context.pages()[0];
+ if (options.headless && page) {
+ const override = await userAgentFor(context, page);
+ if (override && browser.wire) browser.wire.userAgent = override.userAgent;
+ }
+}
+
+/* ------------------------------- what scripts read: headless only ------------------------------ */
+
+/** A child target reached through its parent's session (non-flattened auto-attach). */
+function relayed(parent: Target, sessionId: string) {
+ let next = 0;
+ const pending = new Map<
+ number,
+ { resolve: (value: unknown) => void; reject: (error: Error) => void }
+ >();
+ const target: Target = {
+ send(method, params = {}) {
+ const id = ++next;
+ return new Promise((resolve, reject) => {
+ pending.set(id, { resolve, reject });
+ parent
+ .send("Target.sendMessageToTarget", {
+ sessionId,
+ message: JSON.stringify({ id, method, params }),
+ })
+ .catch((error: unknown) => {
+ pending.delete(id);
+ reject(error instanceof Error ? error : new Error(String(error)));
+ });
+ });
+ },
+ // Nothing listens for a child's events: it is only told things.
+ on() {},
+ };
+ return {
+ target,
+ receive(raw: string) {
+ const message = JSON.parse(raw) as {
+ id?: number;
+ result?: unknown;
+ error?: { message?: string };
+ };
+ if (message.id === undefined) return;
+ const waiting = pending.get(message.id);
+ pending.delete(message.id);
+ if (message.error)
+ waiting?.reject(new Error(message.error.message ?? "CDP error"));
+ else waiting?.resolve(message.result);
+ },
+ gone() {
+ for (const waiting of pending.values())
+ waiting.reject(new Error("The target went away."));
+ pending.clear();
+ },
+ };
+}
+
+const userAgents = new WeakMap<
+ BrowserContext,
+ Promise<UserAgentOverride | undefined>
+>();
+
+/**
+ * What the same browser reports headed: the page's own (already reduced, `Chrome/151.0.0.0`) user
+ * agent with the word changed, and its client hints without the `HeadlessChrome` brand. Read once per
+ * browser, from a page, because the high-entropy hints are only asked of a page.
+ */
+async function headlessUserAgent(
+ target: Target,
+): Promise<UserAgentOverride | undefined> {
+ const evaluated = (await target.send("Runtime.evaluate", {
+ expression: `(navigator.userAgentData ? navigator.userAgentData.getHighEntropyValues(["architecture", "bitness", "model", "platformVersion", "fullVersionList", "wow64"]) : Promise.resolve({})).then((values) => JSON.stringify({ ...values, userAgent: navigator.userAgent, platform: navigator.userAgentData?.platform, mobile: navigator.userAgentData?.mobile }))`,
+ awaitPromise: true,
+ returnByValue: true,
+ })) as { result: { value?: string } };
+ const reported = JSON.parse(evaluated.result.value ?? "{}") as Partial<
+ NonNullable<UserAgentOverride["userAgentMetadata"]>
+ > & { userAgent?: string };
+ if (!reported.userAgent?.includes("HeadlessChrome")) return undefined;
+ const userAgent = reported.userAgent.replace("HeadlessChrome/", "Chrome/");
+ if (!reported.brands) {
+ // The string alone still drops the word; Chromium then sends no client hints rather than wrong ones.
+ return { userAgent };
+ }
+ const real = (list: Brand[] = []) =>
+ list.filter((entry) => entry.brand !== "HeadlessChrome");
+ return {
+ userAgent,
+ userAgentMetadata: {
+ brands: real(reported.brands),
+ fullVersionList: real(reported.fullVersionList),
+ platform: reported.platform ?? "",
+ platformVersion: reported.platformVersion ?? "",
+ architecture: reported.architecture ?? "",
+ model: reported.model ?? "",
+ mobile: reported.mobile ?? false,
+ bitness: reported.bitness ?? "",
+ wow64: reported.wow64 ?? false,
+ },
+ };
+}
+
+const pageSessions = new WeakMap<Page, Promise<Target | undefined>>();
+
+function sessionFor(context: BrowserContext, page: Page) {
+ let session = pageSessions.get(page);
+ if (!session) {
+ session = context
+ .newCDPSession(page)
+ .then(fromPlaywright)
+ .catch(() => undefined);
+ pageSessions.set(page, session);
+ }
+ return session;
+}
+
+async function userAgentFor(context: BrowserContext, page: Page) {
+ let pending = userAgents.get(context);
+ if (!pending) {
+ pending = sessionFor(context, page).then((target) =>
+ target ? headlessUserAgent(target).catch(() => undefined) : undefined,
+ );
+ userAgents.set(context, pending);
+ }
+ return pending;
+}
+
+/** How long a cross-site frame is held for its user agent before it is let go regardless. */
+const CHILD_SETUP_BUDGET_MS = 2_000;
+
+/** Override one target's user agent, and every cross-site frame's inside it as each one starts. */
+async function overrideUserAgent(target: Target, override: UserAgentOverride) {
+ await target
+ .send("Network.setUserAgentOverride", override)
+ .catch(() => undefined);
+ const children = new Map<string, ReturnType<typeof relayed>>();
+ target.on(
+ "Target.receivedMessageFromTarget",
+ (event: { sessionId: string; message: string }) => {
+ children.get(event.sessionId)?.receive(event.message);
+ },
+ );
+ target.on(
+ "Target.attachedToTarget",
+ (event: { sessionId: string; waitingForDebugger: boolean }) => {
+ const child = relayed(target, event.sessionId);
+ children.set(event.sessionId, child);
+ void (async () => {
+ try {
+ await Promise.race([
+ child.target.send("Network.setUserAgentOverride", override),
+ new Promise((resolve) =>
+ setTimeout(resolve, CHILD_SETUP_BUDGET_MS),
+ ),
+ ]);
+ } catch {
+ // A frame that cannot take the override still runs, with the browser's own.
+ } finally {
+ // Always let it go: a frame left waiting for a debugger is a frame that never loads.
+ if (event.waitingForDebugger) {
+ await child.target
+ .send("Runtime.runIfWaitingForDebugger")
+ .catch(() => undefined);
+ }
+ }
+ })();
+ },
+ );
+ target.on("Target.detachedFromTarget", (event: { sessionId: string }) => {
+ children.get(event.sessionId)?.gone();
+ children.delete(event.sessionId);
+ });
+ // Non-flattened, with messages relayed through this session: a flattened child session would be
+ // addressed on Playwright's connection, which has no way to hand it to us.
+ await target
+ .send("Target.setAutoAttach", {
+ autoAttach: true,
+ waitForDebuggerOnStart: true,
+ flatten: false,
+ filter: [{ type: "iframe", exclude: false }, { exclude: true }],
+ })
+ .catch(() => undefined);
+}
+
+const overridden = new WeakSet<Page>();
+
+/**
+ * A page's script sees `Chrome`, not `HeadlessChrome`. Headless only; awaited for the page a browser
+ * launches with, and run as each later page (a popup) opens.
+ */
+export async function attachPageNetwork(
+ context: BrowserContext,
+ page: Page,
+ options: { headless: boolean },
+): Promise<void> {
+ if (!options.headless || overridden.has(page)) return;
+ overridden.add(page);
+ const override = await userAgentFor(context, page);
+ if (!override) return;
+ const target = await sessionFor(context, page);
+ if (target) await overrideUserAgent(target, override);
+}
diff --git a/agent-computer/src/profiles.ts b/agent-computer/src/profiles.ts
index 58784607..3aeb838e 100644
--- a/agent-computer/src/profiles.ts
+++ b/agent-computer/src/profiles.ts
@@ -42,6 +42,7 @@ import { browserRuntimeFromEnv } from "./browser-runtime";
import { egressFor, egressLabel } from "./egress";
import { numberFromEnv, settleWithin } from "./env";
import { chooseLivePage } from "./live-page";
+import { attachBrowserNetwork, attachPageNetwork } from "./page-network";
import { botIdsIn } from "./profile-listing";
import {
type SessionCookieKeeper,
@@ -516,6 +517,16 @@ export function createProfiles(root: string, onClosed: BrowserClosed) {
}
// Persistent contexts open with a page already; reuse it rather than leaving an extra blank tab.
const page = context.pages()[0] ?? (await context.newPage());
+ /*
+ * The user agent fix and the Web Bot Auth signature, before the first navigation so the first
+ * request a site sees already carries both. Not for a native Chrome: that is the person's own
+ * browser, which says who it is already and should not announce a deployment on their behalf.
+ */
+ const network = { headless: BROWSER_RUNTIME.mode === "headless" };
+ if (!LOCAL_CHROME) {
+ await attachBrowserNetwork(context, network);
+ await attachPageNetwork(context, page, network);
+ }
const record: LiveBrowser = {
context,
page,
@@ -539,6 +550,7 @@ export function createProfiles(root: string, onClosed: BrowserClosed) {
// Without this the Bot stays pinned to the page it launched with, so a sign-in the site opens
// in a new window is neither shown to the person taking the wheel nor reachable by input.
context.on("page", (opened) => {
+ if (!LOCAL_CHROME) void attachPageNetwork(context, opened, network);
record.retarget();
// A popup closes itself when it succeeds, and the record must move back to the opener
// rather than leave a closed page to be read as a dead browser.
diff --git a/agent-computer/src/sessions.ts b/agent-computer/src/sessions.ts
index 5716c054..72177328 100644
--- a/agent-computer/src/sessions.ts
+++ b/agent-computer/src/sessions.ts
@@ -53,6 +53,11 @@ export type BotSession = {
* whoever is. An empty slot is a Bot nobody is watching; there is no second way to say that.
*/
viewer: ViewerSlot;
+ /**
+ * How many inputs a person has sent this browser. A background page restore compares it before
+ * navigating, so it never moves a page out from under someone who has started driving.
+ */
+ humanInputs: number;
};
export type SessionsOptions = {
@@ -127,6 +132,7 @@ export function createSessions(options: SessionsOptions) {
},
run: mintRun(),
viewer: createViewerSlot(),
+ humanInputs: 0,
};
sessions.set(botId, created);
// Cheap, and only ever on the path that adds one, so the map cannot grow without this running.
@@ -174,8 +180,12 @@ export function createSessions(options: SessionsOptions) {
const existing = sessions.get(botId);
// Nothing to renew: a Bot nobody has touched yet gets a session, and its run is already new.
if (!existing) return sessionFor(botId).run;
+ // A browser that closed or was replaced underneath the request is a restart, so its page stays
+ // for a request raised from the blank browser that follows. A deliberate stop or reset clears
+ // it straight after, in its own route.
existing.control.interrupt(
"The browser was stopped or replaced; request help again to continue.",
+ { keepPage: true },
);
existing.livePage = undefined;
existing.browserContext = undefined;
diff --git a/agent-computer/src/web-bot-auth.ts b/agent-computer/src/web-bot-auth.ts
new file mode 100644
index 00000000..64bade92
--- /dev/null
+++ b/agent-computer/src/web-bot-auth.ts
@@ -0,0 +1,180 @@
+import { generateNonce, sign, type WebBotSigner } from "web-bot-auth";
+import { signerFromJWK } from "web-bot-auth/crypto";
+
+/**
+ * Signing a Bot's browser requests with the deployment's Web Bot Auth key.
+ *
+ * The API server holds the key and publishes its public half at
+ * `/.well-known/http-message-signatures-directory` (`server/src/web-bot-auth.ts`), then hands the key
+ * to each computer alongside the network policy it already pushes. Every request the browser sends
+ * then carries three headers, in the form Cloudflare's verifier reads
+ * (https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/):
+ *
+ * Signature-Agent: "https://openbot.example.com"
+ * Signature-Input: sig1=("@authority" "signature-agent");created=…;keyid="…";alg="ed25519";expires=…;nonce="…";tag="web-bot-auth"
+ * Signature: sig1=:…:
+ *
+ * `Signature-Agent` is a bare string rather than the dictionary the newer draft uses, because that is
+ * what Cloudflare documents and what it verifies. The headers are added inside the browser (see
+ * `page-network.ts`), after the request leaves the page and before it reaches the egress filter, so
+ * the filter still judges every connection and TLS is still Chromium's own.
+ *
+ * The key reaching the computer means a Bot's computer can sign as the deployment, which is what it
+ * is for. It is a key of its own, derived one way from the deployment key or given separately, so
+ * nothing else the deployment holds can be recovered from it, and rotating it is changing
+ * `WEB_BOT_AUTH_KEY`.
+ */
+
+/** Short, because the signature covers the host and not the request: it is good for any request there. */
+const SIGNATURE_LIFETIME_MS = 60_000;
+
+export type WebBotAuthPush = { agent: string; jwk: JsonWebKey };
+
+type Identity = {
+ /** The `Signature-Agent` value: the agent URL as a quoted structured-field string. */
+ header: string;
+ signer: WebBotSigner;
+ /** The public key, which is what tells one pushed key from the next. */
+ x: string;
+};
+
+let current: Identity | null = null;
+const listeners = new Set<() => void>();
+
+/** Signing is on. Read on every request, so a push turns it on or off without a restart. */
+export function webBotAuthEnabled(): boolean {
+ return current !== null;
+}
+
+/** Called whenever signing turns on or off, so open pages can follow. */
+export function onWebBotAuthChange(listener: () => void): () => void {
+ listeners.add(listener);
+ return () => listeners.delete(listener);
+}
+
+/**
+ * Read the `webBotAuth` member of a policy push. Absent or null is off: an API server that predates
+ * Web Bot Auth, or one with it switched off, pushes neither.
+ */
+export function parseWebBotAuthPush(
+ input: unknown,
+): { ok: true; push: WebBotAuthPush | null } | { ok: false; error: string } {
+ if (input === undefined || input === null) return { ok: true, push: null };
+ if (typeof input !== "object") {
+ return { ok: false, error: "webBotAuth must be an object." };
+ }
+ const { agent, jwk } = input as { agent?: unknown; jwk?: unknown };
+ let url: URL;
+ try {
+ url = new URL(String(agent));
+ } catch {
+ return { ok: false, error: "webBotAuth.agent must be a URL." };
+ }
+ if (url.protocol !== "https:" || url.origin !== agent) {
+ return {
+ ok: false,
+ error: "webBotAuth.agent must be an https origin with no path.",
+ };
+ }
+ const key = jwk as JsonWebKey | undefined;
+ if (
+ !key ||
+ typeof key !== "object" ||
+ key.kty !== "OKP" ||
+ key.crv !== "Ed25519" ||
+ typeof key.d !== "string" ||
+ typeof key.x !== "string"
+ ) {
+ return {
+ ok: false,
+ error: "webBotAuth.jwk must be an Ed25519 private key.",
+ };
+ }
+ return { ok: true, push: { agent: url.origin, jwk: key } };
+}
+
+/** Install the pushed identity, or with null stop signing. */
+export async function setWebBotAuth(
+ push: WebBotAuthPush | null,
+): Promise<void> {
+ if (!push) {
+ if (current === null) return;
+ current = null;
+ for (const listener of listeners) listener();
+ return;
+ }
+ const header = JSON.stringify(push.agent);
+ if (current && current.x === push.jwk.x && current.header === header) return;
+ const signer = await signerFromJWK({
+ kty: "OKP",
+ crv: "Ed25519",
+ d: push.jwk.d,
+ x: push.jwk.x,
+ });
+ const wasOff = current === null;
+ current = { header, signer, x: push.jwk.x as string };
+ if (wasOff) for (const listener of listeners) listener();
+}
+
+/**
+ * Apply what a policy push carried. A malformed member turns signing off and says so, rather than
+ * refusing the push: the network policy in the same body has to land whatever happens here.
+ */
+export async function applyWebBotAuthPush(input: unknown): Promise<void> {
+ const parsed = parseWebBotAuthPush(input);
+ if (!parsed.ok) {
+ console.warn(
+ JSON.stringify({
+ type: "computer-web-bot-auth-refused",
+ error: parsed.error,
+ }),
+ );
+ }
+ await setWebBotAuth(parsed.ok ? parsed.push : null);
+}
+
+const SIGNATURE_HEADERS = new Set([
+ "signature",
+ "signature-input",
+ "signature-agent",
+]);
+
+/**
+ * The request's headers with this deployment's signature added, or undefined to leave the request as
+ * it is (signing off, or a scheme that has no authority to sign).
+ *
+ * Any signature headers the page set itself are replaced, so a request never carries two
+ * `Signature-Agent` values for a verifier to choose between.
+ */
+export async function signedHeaders(
+ method: string,
+ url: string,
+ headers: Record<string, string>,
+ now: Date = new Date(),
+): Promise<{ name: string; value: string }[] | undefined> {
+ const identity = current;
+ if (!identity) return undefined;
+ if (!url.startsWith("https:") && !url.startsWith("http:")) return undefined;
+ const fields = await sign(
+ {
+ kind: "request",
+ method,
+ targetUri: url,
+ fields: [{ name: "signature-agent", value: identity.header }],
+ },
+ {
+ signer: identity.signer,
+ created: now,
+ expires: new Date(now.getTime() + SIGNATURE_LIFETIME_MS),
+ nonce: generateNonce(),
+ },
+ );
+ return [
+ ...Object.entries(headers)
+ .filter(([name]) => !SIGNATURE_HEADERS.has(name.toLowerCase()))
+ .map(([name, value]) => ({ name, value })),
+ { name: "Signature-Agent", value: identity.header },
+ { name: "Signature-Input", value: fields.signatureInput },
+ { name: "Signature", value: fields.signature },
+ ];
+}
diff --git a/agent-computer/tests/browser-runtime.test.ts b/agent-computer/tests/browser-runtime.test.ts
index 5b85eeee..94d1f299 100644
--- a/agent-computer/tests/browser-runtime.test.ts
+++ b/agent-computer/tests/browser-runtime.test.ts
@@ -2,8 +2,19 @@ import { describe, expect, test } from "bun:test";
import { browserRuntimeFromEnv } from "../src/browser-runtime";
describe("the configured browser runtime", () => {
- test.each(["linux", "darwin", "win32"])(
- "managed %s uses full headless Chromium",
+ // Linux is where hosted computers run: a container, a pod, the desktop app's Podman machine.
+ test("managed Linux is headed on its own virtual display", () => {
+ expect(browserRuntimeFromEnv({}, "linux")).toEqual({
+ backend: "managed",
+ channel: "chromium",
+ mode: "headed",
+ useVirtualDisplay: true,
+ allowExec: true,
+ });
+ });
+
+ test.each(["darwin", "win32"])(
+ "managed %s, a developer's own machine, stays headless",
(platform) => {
expect(browserRuntimeFromEnv({}, platform)).toEqual({
backend: "managed",
@@ -15,6 +26,15 @@ describe("the configured browser runtime", () => {
},
);
+ test.each(["linux", "darwin", "win32"])(
+ "headless is still chosen on %s when asked for",
+ (platform) => {
+ expect(
+ browserRuntimeFromEnv({ COMPUTER_BROWSER_MODE: "headless" }, platform),
+ ).toMatchObject({ mode: "headless", useVirtualDisplay: false });
+ },
+ );
+
test.each(["linux", "darwin", "win32"])(
"headed %s needs Xvfb only on Linux",
(platform) => {
diff --git a/agent-computer/tests/control-handoff-page.test.ts b/agent-computer/tests/control-handoff-page.test.ts
new file mode 100644
index 00000000..23fe4dc9
--- /dev/null
+++ b/agent-computer/tests/control-handoff-page.test.ts
@@ -0,0 +1,304 @@
+import { describe, expect, test } from "bun:test";
+import type { Page } from "playwright";
+import { detectChallenge } from "../src/challenge";
+import {
+ createControl,
+ HELP_REQUEST_TTL_MS,
+ pageWorthKeeping,
+} from "../src/control";
+import type { StoredControl } from "../src/control-store";
+import { createSessions } from "../src/sessions";
+
+/** A store that survives "restarts": a new control built on it is the computer coming back up. */
+function memoryStore() {
+ let saved: StoredControl | undefined;
+ return {
+ load: () => (saved ? structuredClone(saved) : undefined),
+ save: (state: StoredControl) => {
+ saved = structuredClone(state);
+ },
+ };
+}
+
+function clock(start = "2026-10-12T17:00:00Z") {
+ let tick = Date.parse(start);
+ return {
+ now: () => new Date(tick).toISOString(),
+ advance: (ms: number) => {
+ tick += ms;
+ },
+ };
+}
+
+const CHALLENGE = "https://chatgpt.com/share/abc";
+
+describe("a handoff remembers the page it is about", () => {
+ test("a challenge request records the page it was raised on", () => {
+ const time = clock();
+ const control = createControl(time.now, { store: memoryStore() });
+ const state = control.requestHelp(
+ "Complete the challenge.",
+ "call-1",
+ "cloudflare",
+ CHALLENGE,
+ );
+ expect(state.request?.url).toBe(CHALLENGE);
+ expect(control.pageToRestore()).toBe(CHALLENGE);
+ });
+
+ test("after the computer restarts, asking again from a blank browser brings the lost page back", () => {
+ const time = clock();
+ const store = memoryStore();
+ createControl(time.now, { store }).requestHelp(
+ "Complete the challenge.",
+ "call-1",
+ "cloudflare",
+ CHALLENGE,
+ );
+
+ // The process restarts: the waiting request is interrupted, and the browser comes back blank.
+ time.advance(20_000);
+ const restarted = createControl(time.now, { store });
+ expect(restarted.get().request?.status).toBe("interrupted");
+ expect(restarted.pageToRestore()).toBeUndefined();
+
+ time.advance(5_000);
+ const again = restarted.requestHelp(
+ "The browser restarted; please complete the challenge.",
+ "call-2",
+ "model",
+ "about:blank",
+ );
+ expect(again.request?.url).toBe(CHALLENGE);
+ expect(restarted.pageToRestore()).toBe(CHALLENGE);
+ });
+
+ test("the page is restorable while a person holds control, and not after they hand back", async () => {
+ const time = clock();
+ const control = createControl(time.now, { store: memoryStore() });
+ const id = control.requestHelp(
+ "Solve it.",
+ "call-1",
+ "cloudflare",
+ CHALLENGE,
+ ).request!.id;
+ await control.take(id);
+ expect(control.pageToRestore()).toBe(CHALLENGE);
+ control.release(id);
+ expect(control.pageToRestore()).toBeUndefined();
+ });
+
+ test("an interruption long ago, or one somebody moved on from, does not bring an old page back", () => {
+ const time = clock();
+ const store = memoryStore();
+ createControl(time.now, { store }).requestHelp(
+ "Solve it.",
+ "call-1",
+ "cloudflare",
+ CHALLENGE,
+ );
+ time.advance(1_000);
+ const restarted = createControl(time.now, { store });
+
+ time.advance(HELP_REQUEST_TTL_MS + 1_000);
+ expect(
+ restarted.requestHelp("Something else.", "call-2", "model", "about:blank")
+ .request?.url,
+ ).toBeUndefined();
+
+ // Cancelled, then asked again: the cancelled request is the latest, so nothing is inherited.
+ const latest = restarted.get().request!;
+ restarted.cancel(latest.id);
+ expect(
+ restarted.requestHelp("Another thing.", "call-3", "model", "about:blank")
+ .request?.url,
+ ).toBeUndefined();
+ });
+});
+
+const RESET_LINK = "https://bank.example/reset?token=secret";
+
+describe("a stop or reset forgets the page", () => {
+ test("a help request after a reset does not reopen the page the reset left", () => {
+ const control = createControl(clock().now, { store: memoryStore() });
+ control.requestHelp("Reset the password.", "a", "model", RESET_LINK);
+ control.interrupt(
+ "The computer was reset; the previous task was interrupted.",
+ );
+ expect(
+ control.requestHelp("other", "b", "model", "about:blank").request?.url,
+ ).toBeUndefined();
+ });
+
+ // The routes close the browser before they interrupt, and a closing browser reaches `renewRun` as
+ // a restart that keeps the page. The route's own interrupt has to win; reset renews once more after.
+ test("a stop or reset that closes the browser first still forgets it", () => {
+ for (const route of ["stop", "reset"] as const) {
+ const sessions = createSessions({ isLive: () => false });
+ const control = sessions.for("bot").control;
+ control.requestHelp("Reset the password.", "a", "model", RESET_LINK);
+ sessions.renewRun("bot");
+ control.interrupt(
+ route === "stop"
+ ? "The computer stopped; the previous task was interrupted."
+ : "The computer was reset; the previous task was interrupted.",
+ );
+ if (route === "reset") sessions.renewRun("bot");
+ expect(
+ control.requestHelp("other", "b", "model", "about:blank").request?.url,
+ ).toBeUndefined();
+ }
+ });
+
+ test("a browser that closes underneath the request still hands its page on", () => {
+ const sessions = createSessions({ isLive: () => false });
+ const control = sessions.for("bot").control;
+ control.requestHelp("Solve it.", "a", "cloudflare", CHALLENGE);
+ sessions.renewRun("bot");
+ expect(
+ control.requestHelp("Again.", "b", "model", "about:blank").request?.url,
+ ).toBe(CHALLENGE);
+ });
+});
+
+describe("a finished request does not keep its page on disk", () => {
+ const CODE = "https://example.com/callback?code=abc";
+
+ test("cancelled, completed and expired requests drop the page, in memory and in the store", async () => {
+ const time = clock();
+ const store = memoryStore();
+ const control = createControl(time.now, { store });
+ control.cancel(
+ control.requestHelp("One.", "c1", "model", CODE).request!.id,
+ );
+ const completed = control.requestHelp("Two.", "c2", "model", CODE).request!
+ .id;
+ await control.take(completed);
+ control.release(completed);
+ control.requestHelp("Three.", "c3", "model", CODE);
+ time.advance(HELP_REQUEST_TTL_MS + 1_000);
+ expect(control.get().request?.status).toBe("expired");
+
+ const saved = store.load()!;
+ expect(saved.requests.map((request) => request.status)).toEqual([
+ "cancelled",
+ "completed",
+ "expired",
+ ]);
+ expect(saved.requests.map((request) => request.url)).toEqual([
+ undefined,
+ undefined,
+ undefined,
+ ]);
+ expect(JSON.stringify(saved)).not.toContain("code=abc");
+ });
+
+ test("a restart's page leaves the store once the help TTL has passed", () => {
+ const time = clock();
+ const store = memoryStore();
+ createControl(time.now, { store }).requestHelp(
+ "Solve it.",
+ "c1",
+ "cloudflare",
+ CHALLENGE,
+ );
+ time.advance(1_000);
+ const restarted = createControl(time.now, { store });
+ expect(store.load()!.requests.at(-1)?.url).toBe(CHALLENGE);
+
+ time.advance(HELP_REQUEST_TTL_MS + 1_000);
+ restarted.get();
+ expect(store.load()!.requests.at(-1)?.url).toBeUndefined();
+ });
+
+ test("a record saved before pages were dropped is cleaned when it is read", () => {
+ const time = clock();
+ const store = memoryStore();
+ const at = time.now();
+ store.save({
+ version: 1,
+ holder: "bot",
+ since: at,
+ resumeSnapshotRequired: false,
+ recoveryRequired: false,
+ currentRequestId: "old-2",
+ requests: [
+ {
+ id: "old-1",
+ reason: "One.",
+ source: "model",
+ status: "cancelled",
+ createdAt: at,
+ updatedAt: at,
+ finishedAt: at,
+ url: CODE,
+ },
+ {
+ id: "old-2",
+ reason: "Two.",
+ source: "model",
+ status: "interrupted",
+ createdAt: at,
+ updatedAt: at,
+ finishedAt: at,
+ interruption:
+ "The computer was reset; the previous task was interrupted.",
+ url: RESET_LINK,
+ },
+ ],
+ aliases: {},
+ });
+
+ time.advance(1_000);
+ const control = createControl(time.now, { store });
+ const saved = JSON.stringify(store.load());
+ expect(saved).not.toContain("code=abc");
+ expect(saved).not.toContain("token=secret");
+ expect(
+ control.requestHelp("other", "b", "model", "about:blank").request?.url,
+ ).toBeUndefined();
+ });
+});
+
+describe("only a real page is worth keeping", () => {
+ test("http and https are kept; blank, browser and script pages are not", () => {
+ expect(pageWorthKeeping(CHALLENGE)).toBe(CHALLENGE);
+ expect(pageWorthKeeping("http://example.com/a")).toBe(
+ "http://example.com/a",
+ );
+ expect(pageWorthKeeping("about:blank")).toBeUndefined();
+ expect(pageWorthKeeping("chrome://newtab/")).toBeUndefined();
+ expect(pageWorthKeeping("javascript:alert(1)")).toBeUndefined();
+ expect(
+ pageWorthKeeping(`https://example.com/${"a".repeat(3000)}`),
+ ).toBeUndefined();
+ expect(pageWorthKeeping(undefined)).toBeUndefined();
+ });
+
+ test("a spent Cloudflare challenge token is not kept, the rest of the address is", () => {
+ expect(
+ pageWorthKeeping("https://chatgpt.com/?__cf_chl_rt_tk=spent-1.0.1.1-abc"),
+ ).toBe("https://chatgpt.com/");
+ expect(
+ pageWorthKeeping(
+ "https://chatgpt.com/share/abc?__cf_chl_tk=x&ref=mail&__cf_chl_f_tk=y",
+ ),
+ ).toBe("https://chatgpt.com/share/abc?ref=mail");
+ });
+});
+
+describe("a detected challenge remembers its page", () => {
+ test("the handoff a Cloudflare challenge raises carries the challenge's address", async () => {
+ const control = createControl();
+ const page = {
+ url: () => "https://chatgpt.com/share/abc",
+ } as unknown as Page;
+ const challenge = await detectChallenge(page, control, {
+ cfMitigated: "challenge",
+ toolCallId: "call-1",
+ });
+ expect(challenge?.kind).toBe("cloudflare");
+ expect(control.get().request?.url).toBe("https://chatgpt.com/share/abc");
+ expect(control.pageToRestore()).toBe("https://chatgpt.com/share/abc");
+ });
+});
diff --git a/agent-computer/tests/egress-connect.test.ts b/agent-computer/tests/egress-connect.test.ts
new file mode 100644
index 00000000..404fb981
--- /dev/null
+++ b/agent-computer/tests/egress-connect.test.ts
@@ -0,0 +1,104 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { createServer, type Server, type Socket } from "node:net";
+import { connectInTurn, connectOrder } from "../src/egress";
+
+const servers: Server[] = [];
+afterEach(async () => {
+ await Promise.all(
+ servers.splice(0).map((s) => new Promise((r) => s.close(() => r(null)))),
+ );
+});
+
+async function listening(): Promise<number> {
+ const server = createServer((socket) => socket.on("error", () => undefined));
+ servers.push(server);
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ return (server.address() as { port: number }).port;
+}
+
+function attempt(
+ target: { host: string; port: number; addresses?: readonly string[] },
+ timeoutMs: number,
+): Promise<{ socket?: Socket; error?: Error }> {
+ return new Promise((resolve) =>
+ connectInTurn(
+ target,
+ (socket) => resolve({ socket }),
+ (error) => resolve({ error }),
+ timeoutMs,
+ ),
+ );
+}
+
+describe("the egress filter connects one checked address at a time", () => {
+ test("IPv4 addresses are tried before IPv6, each in DNS order", () => {
+ expect(
+ connectOrder([
+ "2606:4700::1",
+ "104.18.32.47",
+ "2606:4700::2",
+ "172.64.155.209",
+ ]),
+ ).toEqual([
+ "104.18.32.47",
+ "172.64.155.209",
+ "2606:4700::1",
+ "2606:4700::2",
+ ]);
+ });
+
+ test("an address that refuses is passed over for the next checked one", async () => {
+ const port = await listening();
+ // 127.0.0.2 has nothing listening on this port in a loopback /8, so it refuses or fails fast.
+ const { socket, error } = await attempt(
+ { host: "site.test", port, addresses: ["127.0.0.2", "127.0.0.1"] },
+ 1_000,
+ );
+ expect(error).toBeUndefined();
+ expect(socket?.remoteAddress).toBe("127.0.0.1");
+ socket?.destroy();
+ });
+
+ test("an address that never answers is given up on after the attempt timeout", async () => {
+ const port = await listening();
+ const started = Date.now();
+ // A non-routable address: depending on the host it hangs or fails at once. Either way the next
+ // checked address must be reached, and within the timeout rather than the OS connect timeout.
+ const { socket, error } = await attempt(
+ { host: "site.test", port, addresses: ["10.255.255.1", "127.0.0.1"] },
+ 300,
+ );
+ expect(error).toBeUndefined();
+ expect(socket?.remoteAddress).toBe("127.0.0.1");
+ expect(Date.now() - started).toBeLessThan(3_000);
+ socket?.destroy();
+ });
+
+ test("when every address fails, the caller is told once", async () => {
+ let errors = 0;
+ const error = await new Promise<Error>((resolve) =>
+ connectInTurn(
+ { host: "site.test", port: 1, addresses: ["127.0.0.2", "127.0.0.3"] },
+ () => {
+ throw new Error("must not connect");
+ },
+ (e) => {
+ errors += 1;
+ resolve(e);
+ },
+ 300,
+ ),
+ );
+ await new Promise((r) => setTimeout(r, 400));
+ expect(error).toBeInstanceOf(Error);
+ expect(errors).toBe(1);
+ });
+
+ test("a literal address with no checked list connects directly", async () => {
+ const port = await listening();
+ const { socket, error } = await attempt({ host: "127.0.0.1", port }, 1_000);
+ expect(error).toBeUndefined();
+ expect(socket?.remoteAddress).toBe("127.0.0.1");
+ socket?.destroy();
+ });
+});
diff --git a/agent-computer/tests/handoff-page-restore.test.ts b/agent-computer/tests/handoff-page-restore.test.ts
new file mode 100644
index 00000000..d81bd4fb
--- /dev/null
+++ b/agent-computer/tests/handoff-page-restore.test.ts
@@ -0,0 +1,201 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ComputerControlState } from "../../shared/computer-control";
+import type { StoredControl } from "../src/control-store";
+
+/**
+ * Reopening a handoff's page happens behind the answer, not in front of it.
+ *
+ * The page a restart lost can take a cold browser and a whole navigation timeout to load, and the
+ * Bot's help call and the person's "Take control" used to wait for all of it. Here the page is held
+ * open by the test until both have answered, and is then expected on the screen anyway.
+ *
+ * A real computer process and a real Chromium, so it is asked for by name:
+ *
+ * cd agent-computer && bunx playwright install chromium
+ * OPENBOT_COMPUTER_BROWSER=1 bun test tests/handoff-page-restore.test.ts
+ */
+const asked = process.env.OPENBOT_COMPUTER_BROWSER === "1";
+const TOKEN = "handoff-page-restore-token";
+const BOT = "bot-restore";
+/** Short, so the old awaited restore is still bounded; well above what an answer should take. */
+const NAVIGATION_TIMEOUT_MS = 4_000;
+const PROMPT_MS = 2_000;
+
+let root = "";
+let base = "";
+let challenge = "";
+let child: ReturnType<typeof Bun.spawn> | undefined;
+let site: ReturnType<typeof Bun.serve> | undefined;
+let hits = 0;
+let open = false;
+const held: (() => void)[] = [];
+
+function api(path: string, init?: RequestInit) {
+ return fetch(`${base}${path}`, {
+ ...init,
+ headers: {
+ "content-type": "application/json",
+ "x-openbot-bot-id": BOT,
+ "x-openbot-computer-token": TOKEN,
+ ...(init?.headers ?? {}),
+ },
+ });
+}
+
+async function timed(path: string, body: unknown) {
+ const started = performance.now();
+ const response = await api(path, {
+ method: "POST",
+ body: JSON.stringify(body),
+ });
+ return { response, elapsed: performance.now() - started };
+}
+
+async function until(check: () => Promise<boolean>, ms = 10_000) {
+ const end = Date.now() + ms;
+ while (!(await check())) {
+ if (Date.now() > end)
+ throw new Error("Timed out waiting for the computer fixture.");
+ await Bun.sleep(25);
+ }
+}
+
+beforeAll(async () => {
+ if (!asked) return;
+ root = await mkdtemp(join(tmpdir(), "handoff-page-restore-"));
+ site = Bun.serve({
+ hostname: "127.0.0.1",
+ port: 0,
+ fetch: async () => {
+ hits += 1;
+ if (!open) await new Promise<void>((resolve) => held.push(resolve));
+ return new Response(
+ "<!doctype html><title>Challenge</title><h1>The challenge</h1>",
+ { headers: { "content-type": "text/html; charset=utf-8" } },
+ );
+ },
+ });
+ challenge = `http://127.0.0.1:${site.port}/challenge`;
+
+ // A request that was waiting on the challenge page when the computer last went down.
+ const at = new Date(Date.now() - 5_000).toISOString();
+ const stored: StoredControl = {
+ version: 1,
+ holder: "bot",
+ since: at,
+ resumeSnapshotRequired: false,
+ recoveryRequired: false,
+ currentRequestId: "before-restart",
+ requests: [
+ {
+ id: "before-restart",
+ reason: "Complete the challenge.",
+ source: "cloudflare",
+ status: "waiting",
+ createdAt: at,
+ updatedAt: at,
+ expiresAt: new Date(Date.now() + 60_000).toISOString(),
+ url: challenge,
+ },
+ ],
+ aliases: {},
+ };
+ await mkdir(join(root, "profiles", ".control"), {
+ recursive: true,
+ mode: 0o700,
+ });
+ await writeFile(
+ join(root, "profiles", ".control", `${BOT}.json`),
+ JSON.stringify(stored),
+ { mode: 0o600 },
+ );
+
+ const probe = Bun.serve({
+ hostname: "127.0.0.1",
+ port: 0,
+ fetch: () => new Response(),
+ });
+ const port = probe.port;
+ await probe.stop(true);
+ base = `http://127.0.0.1:${port}`;
+ child = Bun.spawn([process.execPath, "src/index.ts"], {
+ cwd: join(import.meta.dir, ".."),
+ env: {
+ ...process.env,
+ COMPUTER_TOKEN: TOKEN,
+ COMPUTER_BROWSER_BACKEND: "managed",
+ COMPUTER_BROWSER_MODE: "headless",
+ // No API server pushes a network policy here, as in headed-browser.test.ts.
+ EGRESS_POLICY_REQUIRED: "0",
+ NAVIGATION_TIMEOUT_MS: String(NAVIGATION_TIMEOUT_MS),
+ PORT: String(port),
+ PROFILES_DIR: join(root, "profiles"),
+ WORKSPACE_DIR: join(root, "workspace"),
+ },
+ stdout: "ignore",
+ stderr: "inherit",
+ });
+ await until(async () => {
+ if (child?.exitCode !== null)
+ throw new Error(`Computer fixture exited with ${child?.exitCode}.`);
+ try {
+ return (await fetch(`${base}/health`)).ok;
+ } catch {
+ return false;
+ }
+ });
+ // The browser comes back blank after the restart. Started here so its launch is not what is timed.
+ const read = await api("/read");
+ expect(read.status).toBe(200);
+ expect(((await read.json()) as { url: string }).url).toBe("about:blank");
+}, 60_000);
+
+afterAll(async () => {
+ if (!asked) return;
+ open = true;
+ for (const release of held.splice(0)) release();
+ await api("/computers/stop", { method: "POST" }).catch(() => undefined);
+ child?.kill();
+ await child?.exited;
+ site?.stop(true);
+ await rm(root, { recursive: true, force: true });
+}, 30_000);
+
+describe.skipIf(!asked)("reopening the page a restart lost", () => {
+ let requestId = "";
+
+ test("the Bot's help call answers before the page has loaded", async () => {
+ const { response, elapsed } = await timed("/control/request", {
+ reason: "The browser restarted; please complete the challenge.",
+ toolCallId: "call-2",
+ });
+ expect(response.status).toBe(200);
+ const state = (await response.json()) as ComputerControlState;
+ expect(state.request?.url).toBe(challenge);
+ requestId = state.request!.id;
+ expect(elapsed).toBeLessThan(PROMPT_MS);
+ // And the page is on its way: the browser has asked for it.
+ await until(async () => hits > 0);
+ }, 30_000);
+
+ test("Take control answers before it too, and the person is still shown the page", async () => {
+ const { response, elapsed } = await timed("/control/take", { requestId });
+ expect(response.status).toBe(200);
+ expect(((await response.json()) as ComputerControlState).holder).toBe(
+ "human",
+ );
+ expect(elapsed).toBeLessThan(PROMPT_MS);
+
+ open = true;
+ for (const release of held.splice(0)) release();
+ await until(async () => {
+ const read = await api("/read");
+ if (read.status !== 200) return false;
+ const page = (await read.json()) as { url: string; text: string };
+ return page.url === challenge && page.text.includes("The challenge");
+ });
+ }, 30_000);
+});
diff --git a/agent-computer/tests/headed-browser.test.ts b/agent-computer/tests/headed-browser.test.ts
index 2a36552f..020b67f3 100644
--- a/agent-computer/tests/headed-browser.test.ts
+++ b/agent-computer/tests/headed-browser.test.ts
@@ -35,6 +35,7 @@ async function freePort(): Promise<number> {
let base = "";
let root = "";
+let site: ReturnType<typeof Bun.serve> | undefined;
function api(path: string, init?: RequestInit) {
return fetch(`${base}${path}`, {
@@ -54,8 +55,23 @@ beforeAll(async () => {
const port = await freePort();
base = `http://127.0.0.1:${port}`;
process.env.COMPUTER_TOKEN = TOKEN;
- process.env.COMPUTER_BROWSER_MODE = "headed";
+ // Linux is where hosted computers run and headed is their default, so it is left to the default
+ // there; anywhere else it has to be asked for.
+ if (process.platform === "linux") delete process.env.COMPUTER_BROWSER_MODE;
+ else process.env.COMPUTER_BROWSER_MODE = "headed";
process.env.PORT = String(port);
+ // No API server pushes this computer a network policy, so it browses before one arrives, as in
+ // demonstration-live.test.ts. The page is served over http because `/navigate` refuses data: URLs.
+ process.env.EGRESS_POLICY_REQUIRED = "0";
+ site = Bun.serve({
+ hostname: "127.0.0.1",
+ port: 0,
+ fetch: () =>
+ new Response(
+ "<!doctype html><body></body><script>document.body.textContent=navigator.userAgent+'\\nwebdriver='+navigator.webdriver</script>",
+ { headers: { "content-type": "text/html; charset=utf-8" } },
+ ),
+ });
process.env.PROFILES_DIR = join(root, "profiles");
process.env.WORKSPACE_DIR = join(root, "workspace");
await mkdir(process.env.PROFILES_DIR, { recursive: true });
@@ -65,16 +81,13 @@ beforeAll(async () => {
afterAll(async () => {
if (!asked) return;
await api("/computers/stop", { method: "POST" }).catch(() => undefined);
+ site?.stop(true);
await rm(root, { recursive: true, force: true });
}, 30_000);
describe.skipIf(!asked)("a browser a person can take over", () => {
test("is full Chromium rather than the headless shell", async () => {
- const page =
- "data:text/html," +
- encodeURIComponent(
- "<body></body><script>document.body.textContent=navigator.userAgent+'\\nwebdriver='+navigator.webdriver</script>",
- );
+ const page = `http://127.0.0.1:${site?.port}/`;
const navigated = await api("/navigate", {
method: "POST",
body: JSON.stringify({ url: page }),
diff --git a/agent-computer/tests/profile-launch-options.test.ts b/agent-computer/tests/profile-launch-options.test.ts
index de0e8f1f..13278372 100644
--- a/agent-computer/tests/profile-launch-options.test.ts
+++ b/agent-computer/tests/profile-launch-options.test.ts
@@ -48,7 +48,10 @@ describe.skipIf(
expect(options?.channel).toBe(
backend === "managed" ? "chromium" : "chrome",
);
- expect(options?.headless).toBe(backend === "managed");
+ // Managed is headed where hosted computers run (Linux) and headless on a developer's machine.
+ expect(options?.headless).toBe(
+ backend === "managed" && process.platform !== "linux",
+ );
expect(options?.handleSIGINT).toBe(false);
expect(options?.handleSIGTERM).toBe(false);
expect(options?.ignoreDefaultArgs).toEqual(["--enable-automation"]);
diff --git a/agent-computer/tests/residential-proxy.test.ts b/agent-computer/tests/residential-proxy.test.ts
new file mode 100644
index 00000000..a847be23
--- /dev/null
+++ b/agent-computer/tests/residential-proxy.test.ts
@@ -0,0 +1,246 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { createServer, type IncomingMessage } from "node:http";
+import { connect, type Socket } from "node:net";
+import {
+ egressFor,
+ egressLabel,
+ setEgressPolicy,
+ startEgressFilter,
+ stopEgressFilter,
+} from "../src/egress";
+
+/**
+ * A residential or ISP proxy, end to end: a Bot's request through the egress filter, the filter
+ * through a credentialed upstream, the upstream to the site.
+ *
+ * The upstream here behaves as the commercial gateways do: `407` with `Proxy-Authenticate` to anything
+ * without the right Basic credentials, for plain HTTP and for CONNECT alike. What has to hold is that
+ * the credentials in `EGRESS_PROXY_DEFAULT` reach it (percent-encoded characters decoded), that the
+ * Bot's own filter credentials do not, that the network policy is decided before the upstream is ever
+ * asked, and that the password appears nowhere a person would read it.
+ */
+
+const USER = "customer-acme-country-us";
+const PASSWORD = "p@ss:w0rd/with%chars";
+const PROXY_URL = (port: number) =>
+ `http://${USER}:${encodeURIComponent(PASSWORD)}@127.0.0.1:${port}`;
+const EXPECTED = `Basic ${Buffer.from(`${USER}:${PASSWORD}`).toString("base64")}`;
+
+type Upstream = {
+ port: number;
+ seen: { method: string; target: string; authorization?: string }[];
+ close: () => Promise<void>;
+};
+
+async function residentialGateway(): Promise<Upstream> {
+ const seen: Upstream["seen"] = [];
+ const server = createServer((request, response) => {
+ const authorization = request.headers["proxy-authorization"];
+ seen.push({
+ method: request.method ?? "",
+ target: request.url ?? "",
+ ...(authorization ? { authorization } : {}),
+ });
+ if (authorization !== EXPECTED) {
+ response
+ .writeHead(407, { "proxy-authenticate": 'Basic realm="residential"' })
+ .end();
+ return;
+ }
+ response.end(`via residential: ${request.url}`);
+ });
+ server.on("connect", (request: IncomingMessage, client: Socket) => {
+ const authorization = request.headers["proxy-authorization"];
+ seen.push({
+ method: "CONNECT",
+ target: request.url ?? "",
+ ...(authorization ? { authorization } : {}),
+ });
+ if (authorization !== EXPECTED) {
+ client.end(
+ 'HTTP/1.1 407 Proxy Authentication Required\r\nProxy-Authenticate: Basic realm="residential"\r\n\r\n',
+ );
+ return;
+ }
+ const [host = "", port = "0"] = (request.url ?? "").split(":");
+ const remote = connect(Number(port), host, () => {
+ client.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+ remote.pipe(client);
+ client.pipe(remote);
+ });
+ remote.on("error", () => client.destroy());
+ });
+ await new Promise<void>((resolve) =>
+ server.listen(0, "127.0.0.1", () => resolve()),
+ );
+ const address = server.address();
+ return {
+ port: typeof address === "object" && address ? address.port : 0,
+ seen,
+ close: () => new Promise<void>((resolve) => server.close(() => resolve())),
+ };
+}
+
+async function site() {
+ const server = createServer((request, response) =>
+ response.end(`site answered ${request.url}`),
+ );
+ await new Promise<void>((resolve) =>
+ server.listen(0, "127.0.0.1", () => resolve()),
+ );
+ const address = server.address();
+ return {
+ port: typeof address === "object" && address ? address.port : 0,
+ close: () => new Promise<void>((resolve) => server.close(() => resolve())),
+ };
+}
+
+/** Send raw bytes to the filter as the Bot's browser does, with the Bot's own proxy credentials. */
+function throughFilter(bot: string, payload: (auth: string) => string) {
+ const egress = egressFor(bot, {});
+ if (!egress?.username) throw new Error("the filter is not running");
+ const auth = `Basic ${Buffer.from(`${egress.username}:${egress.password}`).toString("base64")}`;
+ const port = Number(new URL(egress.server).port);
+ return new Promise<string>((resolve, reject) => {
+ const socket = connect(port, "127.0.0.1", () =>
+ socket.write(payload(auth)),
+ );
+ let answer = "";
+ socket.on("data", (chunk) => {
+ answer += String(chunk);
+ });
+ socket.on("end", () => resolve(answer));
+ socket.on("error", reject);
+ setTimeout(() => {
+ socket.destroy();
+ resolve(answer);
+ }, 3_000);
+ });
+}
+
+describe("a residential proxy behind the egress filter", () => {
+ afterEach(async () => {
+ await stopEgressFilter();
+ });
+
+ test("plain HTTP reaches the site with the proxy's credentials, not the Bot's", async () => {
+ const gateway = await residentialGateway();
+ const target = await site();
+ await startEgressFilter({
+ env: { EGRESS_PROXY_DEFAULT: PROXY_URL(gateway.port) },
+ });
+ setEgressPolicy("sales", { mode: "allow_all", rules: [] });
+ try {
+ const answer = await throughFilter(
+ "sales",
+ (auth) =>
+ `GET http://127.0.0.1:${target.port}/page HTTP/1.1\r\nHost: 127.0.0.1:${target.port}\r\nProxy-Authorization: ${auth}\r\nConnection: close\r\n\r\n`,
+ );
+ expect(answer).toContain(
+ `via residential: http://127.0.0.1:${target.port}/page`,
+ );
+ expect(gateway.seen).toEqual([
+ {
+ method: "GET",
+ target: `http://127.0.0.1:${target.port}/page`,
+ authorization: EXPECTED,
+ },
+ ]);
+ } finally {
+ await gateway.close();
+ await target.close();
+ }
+ });
+
+ test("HTTPS goes through as a CONNECT carrying the proxy's credentials", async () => {
+ const gateway = await residentialGateway();
+ const target = await site();
+ await startEgressFilter({
+ env: { EGRESS_PROXY_DEFAULT: PROXY_URL(gateway.port) },
+ });
+ setEgressPolicy("sales", { mode: "allow_all", rules: [] });
+ try {
+ const answer = await throughFilter(
+ "sales",
+ (auth) =>
+ `CONNECT 127.0.0.1:${target.port} HTTP/1.1\r\nHost: 127.0.0.1:${target.port}\r\nProxy-Authorization: ${auth}\r\n\r\nGET /secure HTTP/1.1\r\nHost: 127.0.0.1:${target.port}\r\nConnection: close\r\n\r\n`,
+ );
+ expect(answer).toContain("200 Connection Established");
+ expect(answer).toContain("site answered /secure");
+ expect(gateway.seen).toEqual([
+ {
+ method: "CONNECT",
+ target: `127.0.0.1:${target.port}`,
+ authorization: EXPECTED,
+ },
+ ]);
+ } finally {
+ await gateway.close();
+ await target.close();
+ }
+ });
+
+ test("wrong credentials are the gateway's refusal, passed back rather than retried around", async () => {
+ const gateway = await residentialGateway();
+ const target = await site();
+ await startEgressFilter({
+ env: {
+ EGRESS_PROXY_DEFAULT: `http://${USER}:[email protected]:${gateway.port}`,
+ },
+ });
+ setEgressPolicy("sales", { mode: "allow_all", rules: [] });
+ try {
+ const answer = await throughFilter(
+ "sales",
+ (auth) =>
+ `GET http://127.0.0.1:${target.port}/page HTTP/1.1\r\nHost: 127.0.0.1:${target.port}\r\nProxy-Authorization: ${auth}\r\nConnection: close\r\n\r\n`,
+ );
+ expect(answer).not.toContain("site answered");
+ expect(answer).toMatch(/^HTTP\/1\.1 (407|502)/);
+ } finally {
+ await gateway.close();
+ await target.close();
+ }
+ });
+
+ test("the network policy is decided first: a refused destination never reaches the gateway", async () => {
+ const gateway = await residentialGateway();
+ await startEgressFilter({
+ env: { EGRESS_PROXY_DEFAULT: PROXY_URL(gateway.port) },
+ });
+ setEgressPolicy("sales", {
+ mode: "allowlist_only",
+ rules: [{ type: "domain", value: "allowed.example" }],
+ });
+ try {
+ const plain = await throughFilter(
+ "sales",
+ (auth) =>
+ `GET http://refused.example/ HTTP/1.1\r\nHost: refused.example\r\nProxy-Authorization: ${auth}\r\nConnection: close\r\n\r\n`,
+ );
+ const tunnel = await throughFilter(
+ "sales",
+ (auth) =>
+ `CONNECT refused.example:443 HTTP/1.1\r\nHost: refused.example:443\r\nProxy-Authorization: ${auth}\r\n\r\n`,
+ );
+ expect(plain).toStartWith("HTTP/1.1 403");
+ expect(tunnel).toStartWith("HTTP/1.1 403");
+ expect(gateway.seen).toEqual([]);
+ } finally {
+ await gateway.close();
+ }
+ });
+
+ test("the password is in nothing a person reads", () => {
+ const egress = egressFor("sales", {
+ EGRESS_PROXY_DEFAULT: PROXY_URL(8000),
+ });
+ expect(egress?.server).toBe("http://127.0.0.1:8000");
+ expect(egress?.password).toBe(PASSWORD);
+ const label = JSON.stringify(
+ egressLabel("sales", { EGRESS_PROXY_DEFAULT: PROXY_URL(8000) }),
+ );
+ expect(label).not.toContain("w0rd");
+ expect(label).not.toContain(encodeURIComponent(PASSWORD));
+ });
+});
diff --git a/agent-computer/tests/web-bot-auth-browser.test.ts b/agent-computer/tests/web-bot-auth-browser.test.ts
new file mode 100644
index 00000000..bae166de
--- /dev/null
+++ b/agent-computer/tests/web-bot-auth-browser.test.ts
@@ -0,0 +1,266 @@
+import { describe, expect, test } from "bun:test";
+import { generateKeyPairSync } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { verify } from "web-bot-auth";
+import { verifierFromJWK } from "web-bot-auth/crypto";
+import {
+ setEgressPolicy,
+ setEgressResolver,
+ startEgressFilter,
+ stopEgressFilter,
+} from "../src/egress";
+import { setWebBotAuth } from "../src/web-bot-auth";
+
+/**
+ * A Bot's real browser signs what it sends, and nothing else about it changes.
+ *
+ * Launched through the real profile path with the egress filter in front of it, as on a computer. A
+ * site on this machine records every request and checks its signature with the reference verifier,
+ * the way a site behind Cloudflare would. What it proves beyond the unit tests: the DevTools `Fetch`
+ * interception reaches navigations, redirects, subresources, cross-origin fetches, a cross-site frame
+ * (its own process when headed), dedicated workers, and a service worker's script and its own fetches;
+ * cookies still go out; no CORS preflight appears; a headless
+ * browser no longer says `HeadlessChrome`; and the filter still refuses what the policy refuses,
+ * signed or not.
+ *
+ * Asked for by name, like `webrtc-proxy.test.ts`: it launches a real Chromium.
+ *
+ * cd agent-computer && bunx playwright install chromium
+ * OPENBOT_COMPUTER_BROWSER=1 COMPUTER_BROWSER_MODE=headless bun test tests/web-bot-auth-browser.test.ts
+ */
+const asked = process.env.OPENBOT_COMPUTER_BROWSER === "1";
+const AGENT = "https://openbot.example.com";
+
+type Seen = {
+ path: string;
+ method: string;
+ cookie: string | null;
+ userAgent: string;
+ clientHints: string | null;
+ verified: string | null;
+};
+
+describe.skipIf(!asked)("Web Bot Auth from a Bot's browser", () => {
+ test("signs every request the page makes, and the filter still decides", async () => {
+ const jwk = generateKeyPairSync("ed25519").privateKey.export({
+ format: "jwk",
+ });
+ const verifier = await verifierFromJWK({
+ kty: "OKP",
+ crv: "Ed25519",
+ x: jwk.x,
+ });
+ const seen: Seen[] = [];
+ const record = async (request: Request) => {
+ let verified: string | null = null;
+ try {
+ const result = await verify(request, {
+ resolver: (candidate) => {
+ if (candidate.keyid !== verifier.keyid)
+ throw new Error("unknown key");
+ return verifier;
+ },
+ });
+ verified = result.signatureAgent?.uri ?? "no agent";
+ } catch {
+ verified = null;
+ }
+ seen.push({
+ path: new URL(request.url).pathname,
+ method: request.method,
+ cookie: request.headers.get("cookie"),
+ userAgent: request.headers.get("user-agent") ?? "",
+ clientHints: request.headers.get("sec-ch-ua"),
+ verified,
+ });
+ };
+ const html = (body: string) =>
+ new Response(`<!doctype html><body>${body}</body>`, {
+ headers: { "content-type": "text/html" },
+ });
+ let refusedReached = 0;
+ const refused = Bun.serve({
+ hostname: "127.0.0.1",
+ port: 0,
+ fetch: () => {
+ refusedReached += 1;
+ return new Response("should never be reached", {
+ headers: { "access-control-allow-origin": "*" },
+ });
+ },
+ });
+ const crossOrigin = Bun.serve({
+ hostname: "127.0.0.1",
+ port: 0,
+ async fetch(request) {
+ await record(request);
+ if (new URL(request.url).pathname === "/frame")
+ return html(
+ `<script>fetch("/from-frame").then(() => parent.postMessage("frame", "*"))</script>`,
+ );
+ return new Response("cross-origin", {
+ headers: { "access-control-allow-origin": "*" },
+ });
+ },
+ });
+ const site = Bun.serve({
+ hostname: "127.0.0.1",
+ port: 0,
+ async fetch(request) {
+ await record(request);
+ const path = new URL(request.url).pathname;
+ if (path === "/set-cookie")
+ return new Response("set", {
+ headers: { "set-cookie": "session=kept; Path=/" },
+ });
+ if (path === "/redirect")
+ return new Response(null, {
+ status: 302,
+ headers: { location: "/landing" },
+ });
+ if (path === "/worker.js")
+ return new Response(
+ `fetch("/from-worker").then(() => postMessage("done"))`,
+ { headers: { "content-type": "text/javascript" } },
+ );
+ if (path === "/sw.js")
+ return new Response(
+ `self.addEventListener("install", () => self.skipWaiting());
+ self.addEventListener("activate", (event) => event.waitUntil(clients.claim()));
+ self.addEventListener("fetch", (event) => {
+ if (new URL(event.request.url).pathname === "/through-worker")
+ event.respondWith(fetch("/from-service-worker"));
+ });`,
+ { headers: { "content-type": "text/javascript" } },
+ );
+ if (path === "/")
+ return html(`<script>
+ window.results = {};
+ const settle = (name, promise) => promise.then(
+ (value) => (results[name] = value),
+ (error) => (results[name] = "failed: " + error),
+ );
+ settle("crossOrigin", fetch("http://127.0.0.1:${crossOrigin.port}/cors").then((r) => r.text()));
+ settle("refused", fetch("http://127.0.0.1:${refused.port}/nope").then((r) => r.status));
+ settle("worker", new Promise((resolve) => {
+ const worker = new Worker("/worker.js");
+ worker.onmessage = () => resolve("done");
+ }));
+ settle("serviceWorker", navigator.serviceWorker.register("/sw.js")
+ .then(() => navigator.serviceWorker.ready)
+ .then(() => new Promise((resolve) => setTimeout(resolve, 500)))
+ .then(() => fetch("/through-worker"))
+ .then((r) => r.text()));
+ settle("frame", new Promise((resolve) => {
+ addEventListener("message", (event) => event.data === "frame" && resolve("done"));
+ }));
+ </script>
+ <iframe src="http://frame.test:${crossOrigin.port}/frame"></iframe>`);
+ return new Response(path);
+ },
+ });
+
+ await startEgressFilter({ env: {} });
+ // Another site for the frame, so a headed browser puts it in a process of its own. The browser
+ // hands the name to the proxy unresolved, and the filter resolves it here.
+ setEgressResolver(async (host) => {
+ if (host === "frame.test") return ["127.0.0.1"];
+ throw new Error(`no such host ${host}`);
+ });
+ const { createProfiles } = await import("../src/profiles");
+ const root = await mkdtemp(join(tmpdir(), "openbot-web-bot-auth-"));
+ const profiles = createProfiles(root);
+ const bot = "web-bot-auth-test";
+ // The site and the cross-origin server are allowed; the third server is not.
+ setEgressPolicy(bot, {
+ mode: "allowlist_only",
+ rules: [
+ {
+ type: "cidr",
+ value: "127.0.0.1/32",
+ ports: `${site.port},${crossOrigin.port}`,
+ },
+ ],
+ });
+ await setWebBotAuth({ agent: AGENT, jwk });
+ try {
+ const page = await profiles.page(bot);
+ const origin = `http://127.0.0.1:${site.port}`;
+ await page.goto(`${origin}/set-cookie`);
+ await page.goto(`${origin}/redirect`);
+ await page.goto(`${origin}/`);
+ await page.waitForFunction(
+ () => {
+ const results = (window as unknown as { results?: object }).results;
+ return results && Object.keys(results).length === 5;
+ },
+ undefined,
+ { timeout: 15_000 },
+ );
+ const results = await page.evaluate(
+ () =>
+ (window as unknown as { results: Record<string, unknown> }).results,
+ );
+ expect(results.crossOrigin).toBe("cross-origin");
+ expect(results.worker).toBe("done");
+ expect(String(results.refused)).toContain("failed");
+ // The service worker answered, with a request of its own.
+ expect(results.serviceWorker).toBe("/from-service-worker");
+ expect(results.frame).toBe("done");
+
+ for (const path of [
+ "/set-cookie",
+ "/redirect",
+ "/landing",
+ "/",
+ "/cors",
+ "/worker.js",
+ "/from-worker",
+ "/sw.js",
+ "/from-service-worker",
+ "/frame",
+ "/from-frame",
+ ]) {
+ const request = seen.find((entry) => entry.path === path);
+ expect({ path, verified: request?.verified }).toEqual({
+ path,
+ verified: AGENT,
+ });
+ }
+ // Cookies still go out with the signature.
+ expect(seen.find((entry) => entry.path === "/landing")?.cookie).toBe(
+ "session=kept",
+ );
+ // A simple cross-origin GET stayed simple: no preflight was added for the new headers.
+ expect(seen.some((entry) => entry.method === "OPTIONS")).toBe(false);
+ // The filter refused the request the policy does not allow, signed or not.
+ expect(refusedReached).toBe(0);
+ // Whichever mode this ran in, the browser does not call itself headless, on any request.
+ for (const entry of seen) {
+ expect(entry.userAgent).not.toContain("HeadlessChrome");
+ expect(entry.clientHints ?? "").not.toContain("HeadlessChrome");
+ }
+ expect(await page.evaluate(() => navigator.userAgent)).not.toContain(
+ "HeadlessChrome",
+ );
+
+ // Switched off by a push that carries no key: the next request goes out unsigned.
+ await setWebBotAuth(null);
+ await new Promise((resolve) => setTimeout(resolve, 200));
+ await page.goto(`${origin}/after-off`);
+ const after = seen.find((entry) => entry.path === "/after-off");
+ expect(after?.verified).toBeNull();
+ } finally {
+ await setWebBotAuth(null);
+ await profiles.stop(bot).catch(() => undefined);
+ await stopEgressFilter();
+ setEgressResolver(null);
+ site.stop(true);
+ crossOrigin.stop(true);
+ refused.stop(true);
+ await rm(root, { recursive: true, force: true }).catch(() => undefined);
+ }
+ }, 120_000);
+});
diff --git a/agent-computer/tests/web-bot-auth.test.ts b/agent-computer/tests/web-bot-auth.test.ts
new file mode 100644
index 00000000..9416546a
--- /dev/null
+++ b/agent-computer/tests/web-bot-auth.test.ts
@@ -0,0 +1,168 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { generateKeyPairSync } from "node:crypto";
+import { verify } from "web-bot-auth";
+import { verifierFromJWK } from "web-bot-auth/crypto";
+import {
+ parseWebBotAuthPush,
+ setWebBotAuth,
+ signedHeaders,
+ webBotAuthEnabled,
+} from "../src/web-bot-auth";
+
+const AGENT = "https://openbot.example.com";
+const jwk = generateKeyPairSync("ed25519").privateKey.export({
+ format: "jwk",
+});
+const publicJwk = { kty: "OKP", crv: "Ed25519", x: jwk.x };
+
+afterEach(async () => {
+ await setWebBotAuth(null);
+});
+
+/** Verify the way a site does: with the reference verifier and the key from the directory. */
+async function verified(
+ url: string,
+ headers: { name: string; value: string }[],
+) {
+ const verifier = await verifierFromJWK(publicJwk);
+ return verify(
+ new Request(url, {
+ headers: headers.map(
+ ({ name, value }) => [name, value] as [string, string],
+ ),
+ }),
+ {
+ resolver: (candidate) => {
+ if (candidate.keyid !== verifier.keyid) throw new Error("unknown key");
+ return verifier;
+ },
+ },
+ );
+}
+
+describe("a policy push's webBotAuth member", () => {
+ test("absent or null is off", () => {
+ expect(parseWebBotAuthPush(undefined)).toEqual({ ok: true, push: null });
+ expect(parseWebBotAuthPush(null)).toEqual({ ok: true, push: null });
+ });
+
+ test("an https origin and an Ed25519 private key is accepted", () => {
+ expect(parseWebBotAuthPush({ agent: AGENT, jwk })).toEqual({
+ ok: true,
+ push: { agent: AGENT, jwk },
+ });
+ });
+
+ test.each([
+ [{ agent: "http://openbot.example.com", jwk }, "https origin"],
+ [{ agent: `${AGENT}/path`, jwk }, "https origin"],
+ [{ agent: "not a url", jwk }, "must be a URL"],
+ [{ agent: AGENT, jwk: publicJwk }, "Ed25519 private key"],
+ [{ agent: AGENT, jwk: { ...jwk, crv: "X25519" } }, "Ed25519 private key"],
+ ["a string", "must be an object"],
+ ])("refuses %j", (input, error) => {
+ const parsed = parseWebBotAuthPush(input);
+ expect(parsed.ok).toBe(false);
+ expect(parsed.ok ? "" : parsed.error).toContain(error);
+ });
+});
+
+describe("signing a request", () => {
+ test("leaves requests alone while off", async () => {
+ expect(webBotAuthEnabled()).toBe(false);
+ expect(
+ await signedHeaders("GET", "https://chatgpt.com/", { accept: "*/*" }),
+ ).toBeUndefined();
+ });
+
+ test("adds a signature the reference verifier accepts, in Cloudflare's form", async () => {
+ await setWebBotAuth({ agent: AGENT, jwk });
+ expect(webBotAuthEnabled()).toBe(true);
+ const now = new Date();
+ const headers = await signedHeaders(
+ "GET",
+ "https://chatgpt.com/c/123?x=1",
+ { accept: "text/html", cookie: "session=kept" },
+ now,
+ );
+ expect(headers).toBeDefined();
+ const byName = Object.fromEntries(
+ (headers ?? []).map(({ name, value }) => [name.toLowerCase(), value]),
+ );
+ // The page's own headers are kept, cookies included.
+ expect(byName.cookie).toBe("session=kept");
+ expect(byName.accept).toBe("text/html");
+ // A bare string, which is what Cloudflare documents, not the newer dictionary form.
+ expect(byName["signature-agent"]).toBe(`"${AGENT}"`);
+ expect(byName["signature-input"]).toStartWith(
+ 'sig1=("@authority" "signature-agent");',
+ );
+ expect(byName["signature-input"]).toContain('tag="web-bot-auth"');
+ expect(byName["signature-input"]).toContain('alg="ed25519"');
+
+ const result = await verified(
+ "https://chatgpt.com/c/123?x=1",
+ headers ?? [],
+ );
+ expect(result.signatureAgent?.uri).toBe(AGENT);
+ expect(result.expires.getTime() - result.created.getTime()).toBe(60_000);
+ expect(result.nonce).toBeString();
+ });
+
+ test("a signature for one host does not verify for another", async () => {
+ await setWebBotAuth({ agent: AGENT, jwk });
+ const headers = await signedHeaders("GET", "https://chatgpt.com/", {});
+ await expect(
+ verified("https://evil.example/", headers ?? []),
+ ).rejects.toThrow();
+ });
+
+ test("covers the port when the URL names one", async () => {
+ await setWebBotAuth({ agent: AGENT, jwk });
+ const headers = await signedHeaders("GET", "http://127.0.0.1:8080/x", {});
+ await verified("http://127.0.0.1:8080/x", headers ?? []);
+ await expect(
+ verified("http://127.0.0.1:8081/x", headers ?? []),
+ ).rejects.toThrow();
+ });
+
+ // A page can set these on a fetch itself. Two Signature-Agent values would leave a verifier
+ // choosing between them.
+ test("replaces signature headers the page set", async () => {
+ await setWebBotAuth({ agent: AGENT, jwk });
+ const headers = await signedHeaders("POST", "https://chatgpt.com/", {
+ Signature: "sig1=:forged:",
+ "signature-agent": '"https://someone-else.example"',
+ });
+ const agents = (headers ?? []).filter(
+ ({ name }) => name.toLowerCase() === "signature-agent",
+ );
+ expect(agents).toEqual([{ name: "Signature-Agent", value: `"${AGENT}"` }]);
+ expect(
+ (headers ?? []).filter(({ name }) => name.toLowerCase() === "signature"),
+ ).toHaveLength(1);
+ });
+
+ test.each([
+ "data:text/html,hi",
+ "blob:https://chatgpt.com/1",
+ "chrome://version",
+ ])("leaves %s alone, which has no authority to sign", async (url) => {
+ await setWebBotAuth({ agent: AGENT, jwk });
+ expect(await signedHeaders("GET", url, {})).toBeUndefined();
+ });
+
+ test("stops when a push carries no key", async () => {
+ await setWebBotAuth({ agent: AGENT, jwk });
+ await setWebBotAuth(null);
+ expect(
+ await signedHeaders("GET", "https://chatgpt.com/", {}),
+ ).toBeUndefined();
+ });
+
+ test("never puts the private key in a header", async () => {
+ await setWebBotAuth({ agent: AGENT, jwk });
+ const headers = await signedHeaders("GET", "https://chatgpt.com/", {});
+ expect(JSON.stringify(headers)).not.toContain(jwk.d as string);
+ });
+});
diff --git a/agent-langgraph/Dockerfile b/agent-langgraph/Dockerfile
index 614d766e..878c6cb6 100644
--- a/agent-langgraph/Dockerfile
+++ b/agent-langgraph/Dockerfile
@@ -2,7 +2,7 @@
# AG-UI and talks to a model, and the computer it drives is a separate container with its own
# lifecycle. Two Bots in the box rather than one, so "any AG-UI agent is a Bot" is demonstrated by
# two implementations that share nothing but the protocol.
-FROM oven/bun:1.3-alpine
+FROM oven/bun:1.4-alpine
WORKDIR /app
# The lockfile as well as the manifest: `--frozen-lockfile` with no lockfile present resolves afresh
diff --git a/agent-mastra/Dockerfile b/agent-mastra/Dockerfile
index 52066367..641c430f 100644
--- a/agent-mastra/Dockerfile
+++ b/agent-mastra/Dockerfile
@@ -1,6 +1,6 @@
# Mastra, as a Bot. Bun and Mastra's own server, because Mastra serves its AG-UI route itself
# rather than handing back a handler to mount.
-FROM oven/bun:1.3-alpine
+FROM oven/bun:1.4-alpine
WORKDIR /app
COPY agent-mastra/package.json ./
diff --git a/bun.lock b/bun.lock
index ed19ae67..b9ede3ac 100644
--- a/bun.lock
+++ b/bun.lock
@@ -90,9 +90,11 @@
"drizzle-orm": "^0.45.2",
"eventsource": "3.0.7",
"hono": "^4.10.0",
+ "http-message-sig": "0.3.0",
"postgres": "^3.4.9",
"rxjs": "7.8.1",
"twilio": "5.13.0",
+ "web-bot-auth": "0.2.0",
"yaml": "^2.9.0",
"zod": "^4.4.3",
},
@@ -1472,6 +1474,8 @@
"http-errors": ["[email protected]", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
+ "http-message-sig": ["[email protected]", "", { "dependencies": { "structured-headers": "2.0.3" } }, "sha512-ossX5ZDDCRD+YtMzryp3gCg+5wqLFes1RVChEFmEE9Bzbd49Ts2IIIvFnTst/mYWx0ivrxrTTPsIIKKJ07s7+w=="],
+
"https-proxy-agent": ["[email protected]", "", { "dependencies": { "agent-base": "6", "debug": "4" } }, "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA=="],
"human-signals": ["[email protected]", "", {}, "sha512-eKCa6bwnJhvxj14kZk5NCPc6Hb6BdsU9DZcOnmQKSnO1VKrfV0zCvtttPZUsBvjmNDn8rpcJfpwSYnHBjc95MQ=="],
@@ -1582,6 +1586,8 @@
"jsonfile": ["[email protected]", "", { "dependencies": { "universalify": "^2.0.0" }, "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q=="],
+ "jsonwebkey-thumbprint": ["[email protected]", "", {}, "sha512-4m/gJEUQH8N2NfvZFjCL8/E+vlt0FlrmHoR4T93CEXQRkC64qwRi6oQri4/eqLVXqEqXYCss0+Q7pLx6vJBqzw=="],
+
"jsonwebtoken": ["[email protected]", "", { "dependencies": { "jws": "^4.0.1", "lodash.includes": "^4.3.0", "lodash.isboolean": "^3.0.3", "lodash.isinteger": "^4.0.4", "lodash.isnumber": "^3.0.3", "lodash.isplainobject": "^4.0.6", "lodash.isstring": "^4.0.1", "lodash.once": "^4.0.0", "ms": "^2.1.1", "semver": "^7.5.4" } }, "sha512-MT/xP0CrubFRNLNKvxJ2BYfy53Zkm++5bX9dtuPbqAeQpTVe0MQTFhao8+Cp//EmJp244xt6Drw/GVEGCUj40g=="],
"jwa": ["[email protected]", "", { "dependencies": { "buffer-equal-constant-time": "^1.0.1", "ecdsa-sig-formatter": "1.0.11", "safe-buffer": "^5.0.1" } }, "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg=="],
@@ -2166,6 +2172,8 @@
"strnum": ["[email protected]", "", { "dependencies": { "anynum": "^1.0.1" } }, "sha512-rDG3Ah4TV0k1hWvLSzkZtMmLN9+eS+h3knq4MP6A42Y3Yh5qGNnOUs1jJkoSr8FG5dsL28c7KgkIBzSEykqtuw=="],
+ "structured-headers": ["[email protected]", "", {}, "sha512-4g5yxhlDMClRwCcfKfLeS7Z8yAVdOWGDADwm80Poh1iReU2KVKLGBlqwpHWJ2qovq0+ZIf1atAEO1eua2o9Rgg=="],
+
"style-to-js": ["[email protected]", "", { "dependencies": { "style-to-object": "1.0.14" } }, "sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ=="],
"style-to-object": ["[email protected]", "", { "dependencies": { "inline-style-parser": "0.1.1" } }, "sha512-HYNoHZa2GorYNyqiCaBgsxvcJIn7OHq6inEga+E6Ke3m5JkoqpQbnFssk4jwe+K7AhGa2fcha4wSOf1Kn01dMg=="],
@@ -2296,6 +2304,8 @@
"vite": ["[email protected]", "", { "dependencies": { "esbuild": "^0.27.0 || ^0.28.0", "fdir": "^6.5.0", "picomatch": "^4.0.3", "postcss": "^8.5.6", "rollup": "^4.43.0", "tinyglobby": "^0.2.15" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "peerDependencies": { "@types/node": "^20.19.0 || >=22.12.0", "jiti": ">=1.21.0", "less": "^4.0.0", "lightningcss": "^1.21.0", "sass": "^1.70.0", "sass-embedded": "^1.70.0", "stylus": ">=0.54.8", "sugarss": "^5.0.0", "terser": "^5.16.0", "tsx": "^4.8.1", "yaml": "^2.4.2" }, "optionalPeers": ["@types/node", "jiti", "less", "lightningcss", "sass", "sass-embedded", "stylus", "sugarss", "terser", "tsx", "yaml"], "bin": { "vite": "bin/vite.js" } }, "sha512-4XP60spRGjSZFf1qYH+dJIkK2znL3zQfl9KkOV9MkkRR/3Dls0dxaBsQPTloEc5BLXWPL9vsOxopxyKoMmDueg=="],
+ "web-bot-auth": ["[email protected]", "", { "dependencies": { "http-message-sig": "^0.3.0", "jsonwebkey-thumbprint": "^0.1.0", "structured-headers": "2.0.3" } }, "sha512-3DJ72ZhWK4a3yCHCClF6q32g03X37DJlpyASYeBroGTRj/qFkHNcPwkESc3FLigjW6NOWF6MR+Hat9AfOqqtAQ=="],
+
"web-namespaces": ["[email protected]", "", {}, "sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ=="],
"web-streams-polyfill": ["[email protected]", "", {}, "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw=="],
diff --git a/charts/openbot/README.md b/charts/openbot/README.md
index 69bd5d2c..b69fbefb 100644
--- a/charts/openbot/README.md
+++ b/charts/openbot/README.md
@@ -312,7 +312,9 @@ cluster with no Sandbox CRD; both an Ingress and an HTTPRoute are enabled; both
an existing Secret are named; a Bot endpoint is named with no token to call it with; a browser is
asked for inside more than one API replica; `networkPolicy.enabled` is set with an external database
and no `networkPolicy.extraEgress`, or with `computers.mode: sandbox` and no
-`networkPolicy.kubernetesApiCidr`; a computer proxy is named that the network policy blocks; or
+`networkPolicy.kubernetesApiCidr`; a computer proxy is named that the network policy blocks, or
+`computers.egressProxy` is turned on with policies and no `networkPolicy.computerExtraEgress`, or with
+no `secrets.egressProxyUrl` where this chart writes the Secret; or
`routines.enabled` is set with no `secrets.workerSharedSecret` — and, on `externalSecrets`, no
`worker-shared-secret` key named for it to read instead. One combination gets no refusal at all:
`secrets.existingSecret` with `routines.enabled`, because the Secret this chart would otherwise
@@ -526,6 +528,54 @@ networkPolicy:
upper-cased and anything unusual replaced. Naming a proxy the policy provably blocks is refused at
install rather than found as a browser that fails on every page.
+## Getting past bot checks
+
+Sites behind Cloudflare decide per request whether to challenge. Three settings change what a Bot's
+browser looks like to them, and the handoff (the Bot asks, a person takes control, solves the check
+and hands back) is the designed fallback when they are not enough. The full explanation is in
+[docs/configuration.md](../../docs/configuration.md#getting-past-bot-checks).
+
+**Headed Chromium, on by default.** `computers.browserMode: headed` runs full Chromium on the pod's
+own Xvfb, in `shared` and `sandbox` mode alike, behind the same live screen. `headless` is still
+there and uses less memory; it is the browser bot checks are best at spotting.
+
+**Web Bot Auth, on whenever `config.publicUrl` is https on a public address.** Every request a Bot's browser sends is
+signed as coming from this deployment, and the key is published at
+`<publicUrl>/.well-known/http-message-signatures-directory`. `config.webBotAuth: "on"` or `"off"`
+decides it explicitly. The key is derived from `secrets.keyEncryptionKey`; `secrets.webBotAuthKey`
+(an Ed25519 private JWK, key `web-bot-auth-key` in a Secret of your own) replaces it. It earns
+nothing until the deployment is registered with Cloudflare, once, by hand:
+
+1. `curl -i https://<publicUrl>/.well-known/http-message-signatures-directory` answers `200` with
+ `Signature` and `Signature-Input` headers.
+2. In the Cloudflare dashboard: **Manage Account** > **Configurations** > **Bot Submission Form**.
+3. **Verification Method**: **Request Signature**. **Validation Instructions**: the directory URL.
+ Submit, and follow it under **BotBase** > **Submission history**.
+
+**A residential or ISP proxy, off by default and the operator's choice.** The Bots' traffic then
+leaves from an address a consumer ISP owns, so sites see what looks like a person at home rather than
+a datacenter. The credentialed URL is a secret:
+
+```yaml
+computers:
+ egressProxy:
+ enabled: true
+ # existingSecret: residential-proxy # else the chart writes secrets.egressProxyUrl
+ # existingSecretKey: egress-proxy-url
+networkPolicy:
+ computerExtraEgress:
+ - to:
+ - ipBlock:
+ cidr: 0.0.0.0/0
+ ports:
+ - port: 8000
+ protocol: TCP
+```
+
+It reaches every computer as `EGRESS_PROXY_DEFAULT`, behind the egress filter, so the network
+policy still decides what a Bot may reach. Turning it on with `networkPolicy.enabled` and no
+`computerExtraEgress`, or with no URL where this chart holds the Secret, is refused at install.
+
## Upgrades
### Coming from a release before 0.0.14: a computer now runs as uid 1001
diff --git a/charts/openbot/templates/_helpers.tpl b/charts/openbot/templates/_helpers.tpl
index 51f2a75a..106ac651 100644
--- a/charts/openbot/templates/_helpers.tpl
+++ b/charts/openbot/templates/_helpers.tpl
@@ -261,6 +261,21 @@ and in whatever holds the release, which is not where `KEY_ENCRYPTION_KEY` belon
- name: BETTER_AUTH_URL
value: {{ .Values.config.publicUrl | quote }}
{{- end }}
+{{- /* Guarded: absent on a release upgraded with --reuse-values, which leaves the server's default. */}}
+{{- with (.Values.config).webBotAuth }}
+- name: WEB_BOT_AUTH
+ value: {{ . | quote }}
+{{- end }}
+{{- /*
+ Optional on purpose: the server derives a key from KEY_ENCRYPTION_KEY when this one is absent, so
+ a Secret of your own, or the chart's without `secrets.webBotAuthKey`, simply does not carry it.
+*/}}
+- name: WEB_BOT_AUTH_KEY
+ valueFrom:
+ secretKeyRef:
+ name: {{ include "openbot.secretName" . }}
+ key: web-bot-auth-key
+ optional: true
{{- if .Values.config.initialAdminEmails }}
- name: INITIAL_ADMIN_EMAILS
value: {{ .Values.config.initialAdminEmails | quote }}
@@ -601,6 +616,31 @@ podAntiAffinity:
{{- end -}}
{{- end -}}
+{{/*
+The computer settings this chart has values for, as a JSON list of env entries.
+
+One definition, read by the shared StatefulSet and by the per-Bot sandbox template, so a computer
+cannot be headed in one mode and headless in the other, or proxied in one and not the other.
+
+Each key is reached through a guard, because `helm upgrade --reuse-values` hands an existing release
+none of the keys this release added (see scripts/check-new-values-keys.ts). Absent `browserMode`
+leaves the computer to its own default, which is headed on Linux, the same thing.
+*/}}
+{{- define "openbot.computerEnv" -}}
+{{- $env := list -}}
+{{- $computers := .Values.computers | default dict -}}
+{{- with $computers.browserMode -}}
+{{- $env = append $env (dict "name" "COMPUTER_BROWSER_MODE" "value" (toString .)) -}}
+{{- end -}}
+{{- $egressProxy := $computers.egressProxy | default dict -}}
+{{- if $egressProxy.enabled -}}
+{{- $env = append $env (dict "name" "EGRESS_PROXY_DEFAULT" "valueFrom" (dict "secretKeyRef" (dict
+ "name" (default (include "openbot.secretName" .) $egressProxy.existingSecret)
+ "key" (ternary (default "egress-proxy-url" $egressProxy.existingSecretKey) "egress-proxy-url" (not (empty $egressProxy.existingSecret)))))) -}}
+{{- end -}}
+{{- toJson $env -}}
+{{- end -}}
+
{{/*
The pod and volumes every Bot's computer is cut from, as JSON.
@@ -621,6 +661,7 @@ therefore set here instead. See `computers.podSecurityContext` in values.yaml fo
1001 and what is deliberately NOT set alongside it.
*/}}
{{- define "openbot.sandboxPodTemplate" -}}
+{{- $computerEnv := include "openbot.computerEnv" . | fromJsonArray -}}
{{- $spec := dict
"podTemplate" (dict
"metadata" (dict "labels" (dict
@@ -646,6 +687,7 @@ therefore set here instead. See `computers.podSecurityContext` in values.yaml fo
(dict "name" "COMPUTER_TOKEN" "valueFrom" (dict "secretKeyRef" (dict
"name" (default (include "openbot.secretName" .) .Values.computers.existingTokenSecret)
"key" "computer-token"))))
+ $computerEnv
.Values.computers.extraEnv)
"volumeMounts" (list
(dict "name" "profiles" "mountPath" "/profiles")
diff --git a/charts/openbot/templates/computer/statefulset.yaml b/charts/openbot/templates/computer/statefulset.yaml
index eb10ab1d..c5c96cb3 100644
--- a/charts/openbot/templates/computer/statefulset.yaml
+++ b/charts/openbot/templates/computer/statefulset.yaml
@@ -157,6 +157,9 @@ spec:
- name: COMPUTER_BROWSER_IDLE_MS
value: {{ . | quote }}
{{- end }}
+ {{- with include "openbot.computerEnv" . | fromJsonArray }}
+{{ toYaml . | indent 12 }}
+ {{- end }}
{{- with .Values.computers.extraEnv }}
{{ toYaml . | indent 12 }}
{{- end }}
diff --git a/charts/openbot/templates/secret.yaml b/charts/openbot/templates/secret.yaml
index 901e3597..9e08cd38 100644
--- a/charts/openbot/templates/secret.yaml
+++ b/charts/openbot/templates/secret.yaml
@@ -82,4 +82,15 @@ stringData:
{{- with .Values.secrets.otelHeaders }}
otel-headers: {{ . | quote }}
{{- end }}
+ {{- with (.Values.secrets).webBotAuthKey }}
+ web-bot-auth-key: {{ . | quote }}
+ {{- end }}
+ {{- /*
+ The computers reference this key whenever the proxy is on and names no Secret of its own, so the
+ switch without the URL fails here rather than as a computer whose every page fails.
+ */}}
+ {{- $egressProxy := (.Values.computers).egressProxy | default dict }}
+ {{- if and $egressProxy.enabled (not $egressProxy.existingSecret) }}
+ egress-proxy-url: {{ required "secrets.egressProxyUrl is required when computers.egressProxy.enabled and computers.egressProxy.existingSecret is empty. It is the proxy URL with its credentials, such as http://user:[email protected]:8000." (.Values.secrets).egressProxyUrl | quote }}
+ {{- end }}
{{- end }}
diff --git a/charts/openbot/templates/validation.yaml b/charts/openbot/templates/validation.yaml
index 337b401d..25ac1d75 100644
--- a/charts/openbot/templates/validation.yaml
+++ b/charts/openbot/templates/validation.yaml
@@ -287,6 +287,14 @@ This template renders nothing.
a public one at template time, so this misses that case rather than guessing at it. A proxy
supplied through `extraEnvFrom` is not readable here at all.
*/}}
+{{- /*
+ The residential proxy is a Secret this template cannot read, so where it is cannot be checked: with
+ network policies on, the computer reaches 80 and 443 on public addresses and nothing else, and
+ residential gateways almost always listen elsewhere. Asked for by name rather than guessed at.
+*/}}
+{{- if and .Values.networkPolicy.enabled (not .Values.networkPolicy.computerExtraEgress) ((.Values.computers).egressProxy | default dict).enabled }}
+{{- fail "computers.egressProxy.enabled with networkPolicy.enabled needs the proxy named in networkPolicy.computerExtraEgress (its address and port), or every page a Bot opens would fail at the computer's network policy." }}
+{{- end }}
{{- if and .Values.networkPolicy.enabled (not .Values.networkPolicy.computerExtraEgress) }}
{{- range .Values.computers.extraEnv }}
{{- if hasPrefix "EGRESS_PROXY" (.name | default "") }}
diff --git a/charts/openbot/values.yaml b/charts/openbot/values.yaml
index a41f05d5..8530147c 100644
--- a/charts/openbot/values.yaml
+++ b/charts/openbot/values.yaml
@@ -119,6 +119,14 @@ migrations:
config:
# Where people reach this deployment. Sets the OAuth callback and the trusted origin.
publicUrl: ""
+ # Web Bot Auth: every request a Bot's browser makes is signed as coming from this deployment, and
+ # the public key is published at `<publicUrl>/.well-known/http-message-signatures-directory`, so a
+ # site behind Cloudflare that allows signed agents lets the Bot through instead of challenging it.
+ # Empty means on whenever `publicUrl` is https on a public address (verifiers must be able to fetch
+ # the key), off otherwise; `on` or `off` decides it, and `on` also signs behind a private address. Signing earns nothing until the deployment is registered
+ # with Cloudflare, a manual step described in the chart README. The key is derived from
+ # `secrets.keyEncryptionKey` unless `secrets.webBotAuthKey` gives one.
+ webBotAuth: ""
# Administrators by email address, comma-separated. Required unless singleUser is on.
initialAdminEmails: ""
# Email domains admitted at sign-in, comma-separated. Empty admits everybody, which is what the
@@ -346,6 +354,28 @@ computers:
maxBrowsers: ""
browserIdleMs: ""
+ # Which Chromium a Bot's computer runs. `headed` is full Chromium drawing to the pod's own X server
+ # (Xvfb, started by the computer), behind the same streamed screen: it is what sites see from a
+ # person's browser, and Cloudflare's bot check challenges it far less than headless Chromium. Costs
+ # a little more memory and CPU than `headless`, which is still available.
+ browserMode: headed
+
+ # A residential or ISP proxy for every Bot's outbound traffic. OFF BY DEFAULT, and an operator's
+ # choice to make knowingly: through one, a Bot's traffic leaves from an address a consumer ISP owns,
+ # so a site sees what looks like a person at home rather than a datacenter. That is the point (a
+ # datacenter address is the other thing bot checks key on) and also the thing to be comfortable
+ # with. The credentialed URL (`http://user:[email protected]:8000`) is a secret:
+ # `secrets.egressProxyUrl`, or a key in a Secret of your own. It reaches every computer as
+ # `EGRESS_PROXY_DEFAULT`, behind the egress filter, so the network policy still decides what a Bot
+ # may reach. With `networkPolicy.enabled`, also name the proxy in
+ # `networkPolicy.computerExtraEgress`. One Bot's own proxy is still `EGRESS_PROXY_<BOT>` in
+ # `extraEnv` below.
+ egressProxy:
+ enabled: false
+ # Empty uses the chart's Secret (`secrets.egressProxyUrl`).
+ existingSecret: ""
+ existingSecretKey: egress-proxy-url
+
persistence:
# EMPTY MEANS THE CLUSTER'S DEFAULT CLASS. Naming `gp3` or `pd-balanced` is how a chart stops
# installing on a bare-metal cluster. Note that the ordinary block volume on every cloud is
@@ -360,7 +390,8 @@ computers:
resources:
requests:
cpu: 500m
- # Chromium is roughly 200-500MB headless and up to 2GB with real pages open.
+ # Chromium is roughly 200-500MB per browser (a little more headed, plus a few MB for Xvfb) and
+ # up to 2GB with real pages open.
memory: 1Gi
limits:
memory: 4Gi
@@ -567,6 +598,12 @@ secrets:
# logs ones are unset.
otelLogsHeaders: ""
otelHeaders: ""
+ # Optional, with `config.webBotAuth`. An Ed25519 private key as a JSON Web Key, to sign with instead
+ # of the one derived from `keyEncryptionKey`. Read from key `web-bot-auth-key` of whichever Secret
+ # this chart uses, when present.
+ webBotAuthKey: ""
+ # Required when `computers.egressProxy.enabled` and no `existingSecret` is named there.
+ egressProxyUrl: ""
externalSecrets:
enabled: false
diff --git a/desktop/src-tauri/icons/README.md b/desktop/src-tauri/icons/README.md
index cc89f7f6..7a76450f 100644
--- a/desktop/src-tauri/icons/README.md
+++ b/desktop/src-tauri/icons/README.md
@@ -16,7 +16,7 @@ and loads no application or network content.
## Reproduce the source export
Tool versions used: Node 24.16.0, Playwright 1.62.1, Chromium 151.0.7922.34,
-Bun 1.3.14, and the desktop lockfile's Tauri CLI 2.11.4. Use an installed
+Bun 1.4.3, and the desktop lockfile's Tauri CLI 2.11.4. Use an installed
Playwright 1.62.1 module and its matching Chromium executable. The renderer
records the executable hash and refuses a different browser version.
diff --git a/desktop/src-tauri/src/install.rs b/desktop/src-tauri/src/install.rs
index e451d415..2900d3a5 100644
--- a/desktop/src-tauri/src/install.rs
+++ b/desktop/src-tauri/src/install.rs
@@ -44,7 +44,7 @@ use crate::problem::Problem;
pub const PODMAN: &str = "6.1.1";
pub const COMPOSE: &str = "5.5.1";
/// Keep aligned with the repository's packageManager and container runtime.
-pub const BUN: &str = "1.3.14";
+pub const BUN: &str = "1.4.3";
/// A file to fetch and the digest it has to have.
#[derive(Debug, PartialEq, Eq)]
@@ -221,31 +221,31 @@ fn ensure_bun_with(
}
fn bun_download(os: &str, arch: &str) -> Result<Download, Problem> {
- // Official bun-v1.3.14/SHASUMS256.txt. The baseline x64 build also supports older CPUs.
+ // Official bun-v1.4.3/SHASUMS256.txt. The baseline x64 build also supports older CPUs.
let (file, sha256) = match (os, arch) {
("windows", "x86_64") => (
"bun-windows-x64-baseline.zip",
- "538f9c846355d9e847b2671bc00c47da4229a0befb24df3282b739770f3b475f",
+ "d7a7d3eb216614544aab0cde2d8d9f2e4e87839bf5a30a1cd11d077f02d84e0c",
),
("windows", "aarch64") => (
"bun-windows-aarch64.zip",
- "89841f5a57f2348b67ec0839b718f4bf4ea7d07c371c9ba4b77b6c790f918953",
+ "5e8f142ef722cbc9f67dc068a166e46ee72be8307b38cac7186589d2face668f",
),
("macos", "x86_64") => (
"bun-darwin-x64-baseline.zip",
- "3e35ad6f53971a9834bf9e6786e2adf72b5f1921cc9a9c5fde073d2972944076",
+ "0fde04e8b092156b97fe6432e899baf16d9ed6ce52cbb4218d2d9c07a2f827ef",
),
("macos", "aarch64") => (
"bun-darwin-aarch64.zip",
- "d8b96221828ad6f97ac7ac0ab7e95872341af763001e8803e8267652c2652620",
+ "80afd4c069b46a6fa8f3ec520bebc750a7843e4a8d5b9583d29ad436c00a3403",
),
("linux", "x86_64") => (
"bun-linux-x64-baseline.zip",
- "a063908ae08b7852ca10939bbdc6ceed3ddabce8fb9402dce83d65d73b36e6c7",
+ "1fc2edac843102909e3a1be1d8d9802cc6071cf074e67e88231f4ffe0f8b397b",
),
("linux", "aarch64") => (
"bun-linux-aarch64.zip",
- "a27ffb63a8310375836e0d6f668ae17fa8d8d18b88c37c821c65331973a19a3b",
+ "efa9813da5ed72423bf847f916e8d2c47c0d776add972354026a75e10da9aa21",
),
_ => {
return Err(Problem::with(
@@ -824,17 +824,17 @@ mod tests {
fn bun_zip_fixture(name: &str) -> (PathBuf, Download) {
use base64::Engine as _;
- // A deflated ZIP containing bun-fixture/bun, a /bin/sh script printing 1.3.14,
+ // A deflated ZIP containing bun-fixture/bun, a /bin/sh script printing 1.4.3,
// and an unrelated traversal entry that must never be extracted. Fixed bytes keep
// digest verification and real decompression in this offline regression.
let bytes = base64::engine::general_purpose::STANDARD.decode(
- "UEsDBBQAAAAIAAAAIVwlsF+1HgAAABwAAAAPAAAAYnVuLWZpeHR1cmUvYnVuU1bUT8rM0y/O4CooyswrSVNQN9Qz1jM0iclT5wIAUEsDBBQAAAAIAAAAIVw6VdAHFwAAABUAAAANAAAALi4vdW5leHBlY3RlZMstLS5RyMsvUUhKVUitKClKTC5JTQEAUEsBAhQDFAAAAAgAAAAhXCWwX7UeAAAAHAAAAA8AAAAAAAAAAAAAAIABAAAAAGJ1bi1maXh0dXJlL2J1blBLAQIUAxQAAAAIAAAAIVw6VdAHFwAAABUAAAANAAAAAAAAAAAAAACAAUsAAAAuLi91bmV4cGVjdGVkUEsFBgAAAAACAAIAeAAAAI0AAAAAAA==",
+ "UEsDBBQAAAAIAAAAIVxUT2uCHQAAABsAAAAPAAAAYnVuLWZpeHR1cmUvYnVuU1bUT8rM0y/O4CooyswrSVNQN9Qz0TOOyVPnAgBQSwMEFAAAAAgAAAAhXDpV0AcXAAAAFQAAAA0AAAAuLi91bmV4cGVjdGVkyy0tLlHIyy9RSEpVSK0oKUpMLklNAQBQSwECFAMUAAAACAAAACFcVE9rgh0AAAAbAAAADwAAAAAAAAAAAAAAgAEAAAAAYnVuLWZpeHR1cmUvYnVuUEsBAhQDFAAAAAgAAAAhXDpV0AcXAAAAFQAAAA0AAAAAAAAAAAAAAIABSgAAAC4uL3VuZXhwZWN0ZWRQSwUGAAAAAAIAAgB4AAAAjAAAAAAA",
).unwrap();
let root = temp_root(name);
std::fs::create_dir_all(&root).unwrap();
let download = Download {
url: "http://127.0.0.1:1/never-reached".into(),
- sha256: "afeced1e41e23b9a5a7c63fb917f68ee663a3735f02fe717cf859be06b1e29b6",
+ sha256: "2620378dbeb5b75aa500d3402928732c4e9f800a4546e609f2ff99be95470a29",
file: "bun-fixture.zip",
};
std::fs::write(root.join(download.file), bytes).unwrap();
@@ -847,12 +847,12 @@ mod tests {
(
"x86_64",
"bun-linux-x64-baseline.zip",
- "a063908ae08b7852ca10939bbdc6ceed3ddabce8fb9402dce83d65d73b36e6c7",
+ "1fc2edac843102909e3a1be1d8d9802cc6071cf074e67e88231f4ffe0f8b397b",
),
(
"aarch64",
"bun-linux-aarch64.zip",
- "a27ffb63a8310375836e0d6f668ae17fa8d8d18b88c37c821c65331973a19a3b",
+ "efa9813da5ed72423bf847f916e8d2c47c0d776add972354026a75e10da9aa21",
),
] {
let download = bun_download("linux", arch).unwrap();
@@ -917,7 +917,7 @@ mod tests {
extract_bun(&archive, &target, "bun-fixture/bun").unwrap();
assert_eq!(
std::fs::read(&target).unwrap(),
- b"#!/bin/sh\nprintf '1.3.14\\n'\n"
+ b"#!/bin/sh\nprintf '1.4.3\\n'\n"
);
assert_eq!(std::fs::read_dir(&into).unwrap().count(), 1);
assert!(!root.join("unexpected").exists());
diff --git a/desktop/src-tauri/src/preparation.rs b/desktop/src-tauri/src/preparation.rs
index 787d4ac5..0fb5d492 100644
--- a/desktop/src-tauri/src/preparation.rs
+++ b/desktop/src-tauri/src/preparation.rs
@@ -378,7 +378,7 @@ fn main() {
let args: Vec<String> = std::env::args().skip(1).collect();
if args == ["--version"] {
let version = std::env::current_exe().unwrap().parent().unwrap().join("runtime-version");
- println!("{}", std::fs::read_to_string(version).unwrap_or_else(|_| "1.3.14".into()));
+ println!("{}", std::fs::read_to_string(version).unwrap_or_else(|_| "1.4.3".into()));
return;
}
assert_eq!(args, ["install", "--frozen-lockfile", "--ignore-scripts"]);
diff --git a/desktop/src-tauri/tests/fixtures/engine.rs b/desktop/src-tauri/tests/fixtures/engine.rs
index 1b79437a..4f8bf8c9 100644
--- a/desktop/src-tauri/tests/fixtures/engine.rs
+++ b/desktop/src-tauri/tests/fixtures/engine.rs
@@ -14,7 +14,7 @@ fn main() {
let joined = args.join(" ");
if SCENARIO == "runtime" {
assert_eq!(joined, "--version", "launch must not install dependencies");
- println!("1.3.14");
+ println!("1.4.3");
return;
}
if joined.starts_with("image inspect ") {
diff --git a/docker-compose.yml b/docker-compose.yml
index 735c08b1..f59f104c 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -101,9 +101,10 @@ services:
# shutdown notes tell you to use -- hands the container an empty string instead. Reaches only
# a loopback-bound port; a deployment sets a real value in .env.
COMPUTER_TOKEN: ${COMPUTER_TOKEN:-openbot-dev-computer-token}
- # `headed` runs full Chromium behind the same streamed screen, so a person taking the wheel
- # gets a browser sites treat like their ordinary desktop browser. Headless remains the default.
- COMPUTER_BROWSER_MODE: ${COMPUTER_BROWSER_MODE:-headless}
+ # Headed by default: full Chromium on the container's own X server, behind the same streamed
+ # screen, which bot checks such as Cloudflare's challenge far less than headless. `headless`
+ # still chooses headless, for a smaller footprint where the sites a Bot uses do not mind.
+ COMPUTER_BROWSER_MODE: ${COMPUTER_BROWSER_MODE:-headed}
# How many Bots may hold a running browser at once, and how long an untouched one is kept.
# A few hundred MB each, so on a deployment with many Bots these are the difference between
# a container that holds steady and one that is killed for memory. Defaults are 8 and 30
@@ -200,8 +201,8 @@ services:
SUPERVISOR_TOKEN: ${SUPERVISOR_TOKEN:-openbot-dev-supervisor-token}
# Handed to every computer this creates, so the server and the computers share one secret.
COMPUTER_TOKEN: ${COMPUTER_TOKEN:-openbot-dev-computer-token}
- # Forwarded into every per-Bot computer the supervisor creates.
- COMPUTER_BROWSER_MODE: ${COMPUTER_BROWSER_MODE:-headless}
+ # Forwarded into every per-Bot computer the supervisor creates. Headed, as above.
+ COMPUTER_BROWSER_MODE: ${COMPUTER_BROWSER_MODE:-headed}
COMPUTER_IMAGE: ${COMPUTER_IMAGE:-openbot-agent-computer:latest}
# Which deployment the computers it creates belong to, so two stacks on one Docker host never
# derive the same container and volume names for the same Bot.
diff --git a/docs/architecture.md b/docs/architecture.md
index 56d8fa0b..7b79231d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -136,6 +136,8 @@ Handovers are audited as control events:
While a person controls the browser, Bot actions are refused rather than queued. A run with no browser attached pauses instead, waiting on the handover.
+The handover is also the designed fallback for a bot check a Bot cannot pass (a "Verify you are human" page, a CAPTCHA). OpenBot reduces how often that happens (headed Chromium, Web Bot Auth signatures, an optional residential proxy; see [Getting past bot checks](configuration.md#getting-past-bot-checks)) and never solves one on anyone's behalf: the Bot asks, the person solves it in the live screen, and hands back. A help request records the page it was made on, so a computer that restarted in between reopens that page rather than handing over a blank browser.
+
Secret entry is separate from chat content. The audit trail records that a secret was requested or supplied and the character count, not the secret value.
## Watching a Bot work
diff --git a/docs/configuration.md b/docs/configuration.md
index 11940def..7361d5d7 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -621,7 +621,9 @@ is still the record.
| `COMPUTER_MAX_BROWSERS` | How many Bots may hold a running browser at once. `8` by default; the least recently used is closed past it. |
| `COMPUTER_BROWSER_IDLE_MS` | How long an untouched browser is kept. 30 minutes by default; `0` keeps them resident. |
| `COMPUTER_BROWSER_BACKEND` | `managed` by default (full bundled Chromium); `local-chrome` opts into installed Chrome with dedicated profiles and a loopback API. |
-| `COMPUTER_BROWSER_MODE` | Managed defaults to `headless` (full Chromium's new headless mode). `headed` uses Xvfb on Linux and a native window on macOS/Windows. Local Chrome requires `headed`. |
+| `COMPUTER_BROWSER_MODE` | Managed defaults to `headed` on Linux, which is every hosted computer (a container, a pod, the desktop app's engine): full Chromium on the computer's own Xvfb display. A computer run directly on macOS or Windows defaults to `headless`, where headed would open windows on the desktop. `headless` is full Chromium's new headless mode. Local Chrome requires `headed`. See [Getting past bot checks](#getting-past-bot-checks). |
+| `WEB_BOT_AUTH` | `on` or `off`. Unset means on when the public URL is https on a public address, off otherwise. See [Web Bot Auth](#web-bot-auth). |
+| `WEB_BOT_AUTH_KEY` | The Web Bot Auth signing key, an Ed25519 private JWK. Unset derives one from `KEY_ENCRYPTION_KEY`. Never logged. |
| `OPENBOT_LOCAL_COMPUTER_DIR` | Local startup helper's absolute data root. Defaults to the platform's OpenBot user-data directory; contains `profiles/` and `workspace/`. |
| `COMPUTER_SUPERVISOR_URL` | Supervisor URL for per-Bot computers. If absent, Bots share `AGENT_COMPUTER_URL`. |
| `SUPERVISOR_TOKEN` | Bearer token required by the supervisor. |
@@ -648,29 +650,34 @@ docker ps -aq --filter "label=openbot.namespace=openbot" | xargs -r docker rm -f
The supervisor recreates each computer with the same named volumes on its next request.
-### Headed managed Chromium in Docker or Helm
+### Headed or headless managed Chromium in Docker or Helm
The managed backend uses Playwright's full `chromium` channel in either mode. The Docker image
-already installs that browser and Xvfb; it does not require Google Chrome. For Compose, set
-`COMPUTER_BROWSER_MODE=headed` in the deployment environment and recreate the shared computer or
-supervisor as applicable:
+already installs that browser and Xvfb; it does not require Google Chrome. Headed is the default in
+Compose (`agent-computer` and the computers the supervisor creates) and in the Helm chart
+(`computers.browserMode: headed`). The computer starts its own Xvfb, so nothing appears on any screen
+and the live screen, take control and hand back work exactly as before. Headed costs a little more
+memory and CPU than headless.
+
+To run headless instead, set `COMPUTER_BROWSER_MODE=headless` for Compose and recreate the shared
+computer or supervisor as applicable:
```sh
docker compose up -d --force-recreate agent-computer supervisor
```
Existing supervisor-created computers retain their mode until recreated as described above. The
-same per-Bot profile volumes and streamed viewer continue to work. For Helm, add to your values:
+same per-Bot profile volumes and streamed viewer continue to work. For Helm:
```yaml
computers:
- extraEnv:
- - name: COMPUTER_BROWSER_MODE
- value: headed
+ browserMode: headless
```
Apply the Helm upgrade. A newly created computer uses the new setting; recreate existing supervised
-computers through your deployment's lifecycle controls while keeping their persistent volumes.
+computers through your deployment's lifecycle controls while keeping their persistent volumes. A
+headless computer no longer calls itself `HeadlessChrome`: its user agent and client hints report what
+the same browser reports headed.
### Installed Chrome for a local API deployment
@@ -812,6 +819,111 @@ docker volume ls -q --filter "label=openbot.namespace=openbot" | xargs -r docker
Proxy credentials may appear in proxy URLs, but the computer strips them before reporting proxy status.
+### Getting past bot checks
+
+Sites behind Cloudflare and similar services (ChatGPT, Canva and many more) decide on every request
+whether it comes from a person, a known good bot, or something to challenge. A Bot's browser gives
+them three answers, in order of how much each one is in the operator's hands, and then a fallback
+for when none of them is enough.
+
+1. **A real browser.** Headed Chromium, the default for hosted computers (see above). Headless
+ Chromium is what bot checks are best at spotting, and is challenged even from a residential
+ address.
+2. **Web Bot Auth.** The browser signs every request as coming from this deployment, the way
+ OpenAI's agent does. A site that allows signed agents lets it through. See below.
+3. **Where the traffic leaves from.** A datacenter address is the other thing bot checks key on. A
+ residential or ISP proxy changes it. See [Residential or ISP proxy](#residential-or-isp-proxy).
+4. **The handoff, which is the designed fallback.** When a site still challenges (a "Verify you are
+ human" check, a CAPTCHA, a sign-in), the Bot asks for help, the person takes control in the live
+ screen, solves it, and hands back. OpenBot never solves a challenge on anyone's behalf. The page
+ survives a computer restart: the handoff reopens it rather than showing a blank browser.
+
+#### Web Bot Auth
+
+[Web Bot Auth](https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/) is
+Cloudflare's signed-agent scheme, built on HTTP Message Signatures (RFC 9421). With it on:
+
+- The server holds one Ed25519 key and publishes its public half, signed, at
+ `<public URL>/.well-known/http-message-signatures-directory` (content type
+ `application/http-message-signatures-directory+json`).
+- Every request a Bot's browser sends carries `Signature-Agent: "<public URL>"`, plus `Signature-Input`
+ and `Signature` over `@authority` and `signature-agent`, with `created`, a 60 second `expires`, a
+ nonce, `tag="web-bot-auth"` and the key's JWK thumbprint as `keyid`. The headers are added inside
+ the browser as each request leaves it, so the egress filter still judges every connection, TLS is
+ still Chromium's own, cookies are unchanged, and no CORS preflight is added.
+
+**When it is on.** `WEB_BOT_AUTH` unset means on when `OPENBOT_PUBLIC_URL` (or `BETTER_AUTH_URL`)
+is https on a public address, and off otherwise. A verifier has to fetch the key from the internet
+over HTTPS, so a laptop on `http://localhost:3001` would only be signing with a directory nobody can
+read. A private address (`10.x`, `192.168.x`, `*.internal`, a single-label name) stays off unless
+`WEB_BOT_AUTH=on`, because only the operator knows whether their verifier reaches it. `on` with plain
+http or a loopback address is refused at start-up; `off` turns it off anywhere. On Helm,
+`config.webBotAuth`.
+
+**The key.** Derived from `KEY_ENCRYPTION_KEY` (one way, with HKDF), so every replica and restart
+signs with the same key and nothing new is needed to start. `WEB_BOT_AUTH_KEY` names one instead, an
+Ed25519 private JWK (on Helm, `secrets.webBotAuthKey`). The server hands it to each computer with
+the network policy it already pushes, because the browser is what signs: a Bot's computer can sign as
+this deployment, which is what it is for, and nothing else the deployment holds can be recovered from
+it. Rotate by setting a new `WEB_BOT_AUTH_KEY` and registering again.
+
+**Registering with Cloudflare (manual, once).** Signing earns nothing until Cloudflare knows the key:
+
+1. Check the directory answers from the internet:
+ `curl -i https://openbot.example.com/.well-known/http-message-signatures-directory` shows `200`,
+ the content type above, `Signature` and `Signature-Input` headers, and one key.
+2. In the [Cloudflare dashboard](https://dash.cloudflare.com/), choose your account, then
+ **Manage Account** > **Configurations** > **Bot Submission Form**.
+3. For **Verification Method**, choose **Request Signature**. For **Validation Instructions**, give
+ the key directory URL from step 1. Submit.
+4. Follow the request under **BotBase** > **Submission history**.
+
+Until it is approved, signed requests are treated like any others. Other services that verify Web
+Bot Auth read the same directory.
+
+**What it tells sites.** Every site a Bot visits, Cloudflare-fronted or not, sees this deployment's
+public URL in `Signature-Agent`. That is the point (an honest agent says who it is), and it is why
+the switch exists.
+
+**What is signed.** Every request the browser sends, whatever sent it: pages, redirects,
+subresources, cross-site frames running in processes of their own, dedicated workers, and service
+workers, including their script fetches. The signing happens in one browser-level DevTools session,
+so no kind of target can be missed by not being attached. The identity is per deployment, not per
+Bot. The local Chrome backend never signs: it is the person's own browser.
+
+#### Residential or ISP proxy
+
+`EGRESS_PROXY_DEFAULT` (and `EGRESS_PROXY_<BOT_ID>`, see [Per-Bot egress](#per-bot-egress)) takes a
+residential or ISP proxy's gateway URL, credentials included:
+
+```sh
+# egress.env
+EGRESS_PROXY_DEFAULT=http://customer-user:[email protected]:8000
+```
+
+On Helm, put the URL in a Secret and turn it on:
+
+```yaml
+computers:
+ egressProxy:
+ enabled: true
+ # existingSecret: my-proxy # or let the chart hold it in secrets.egressProxyUrl
+ # existingSecretKey: egress-proxy-url
+networkPolicy:
+ computerExtraEgress: # needed when networkPolicy.enabled
+ - to: [{ ipBlock: { cidr: 0.0.0.0/0 } }]
+ ports: [{ port: 8000, protocol: TCP }]
+```
+
+It reaches the shared computer and every per-Bot computer as `EGRESS_PROXY_DEFAULT`. The egress
+filter chains to it, so the network policy still decides what a Bot may reach, and the proxy's
+credentials are split out before Chromium or any status report sees them.
+
+**This is the operator's choice, and it is off by default.** Through a residential proxy, a Bot's
+traffic leaves from an address a consumer ISP owns, so a site sees what looks like a person at home
+rather than a datacenter. That is why it works, and it is a choice to make knowingly: it changes
+what the Bot appears to be, where Web Bot Auth says what it is. They can be used together.
+
## Attested identity
When optional SPIRE services are used:
diff --git a/package.json b/package.json
index 80fed48a..644d4646 100644
--- a/package.json
+++ b/package.json
@@ -3,7 +3,7 @@
"version": "0.2.0",
"license": "MIT",
"private": true,
- "packageManager": "[email protected]",
+ "packageManager": "[email protected]",
"workspaces": [
"app",
"server",
diff --git a/prompt.txt b/prompt.txt
index f9d4da98..aedf0bfa 100644
--- a/prompt.txt
+++ b/prompt.txt
@@ -49,7 +49,7 @@ B. CLONE: RUN OPENBOT LOCALLY, CHANGE IT, OR EDIT A TENANT PACKAGE
Use this to run OpenBot from source on their machine, or to edit code or configuration.
Requirements for the clone path:
-- Bun 1.3.14. The repository pins it in package.json.
+- Bun 1.4.3. The repository pins it in package.json.
- Docker CLI plus Docker Compose, or a compatible `docker` command/socket. `scripts/start.sh`
calls `docker compose` for PostgreSQL and shipped Bots; Podman works only when it is exposed
through that Docker-compatible command path.
diff --git a/server/Dockerfile b/server/Dockerfile
index 4cb116ad..d66feafc 100644
--- a/server/Dockerfile
+++ b/server/Dockerfile
@@ -6,7 +6,7 @@
#
# Multi-stage so the build's dependencies do not ship. Non-root because nothing here needs to be.
-FROM oven/bun:1.3.14 AS deps
+FROM oven/bun:1.4.3 AS deps
WORKDIR /app
@@ -36,7 +36,7 @@ COPY examples examples
RUN bun run --cwd app build
-FROM oven/bun:1.3.14 AS runtime
+FROM oven/bun:1.4.3 AS runtime
# Not root. The API opens a socket and talks to Postgres; neither needs privileges, and a Chromium
# container is a separate image with its own reasons.
diff --git a/server/package.json b/server/package.json
index 0d5ba1cd..a8b7080e 100644
--- a/server/package.json
+++ b/server/package.json
@@ -35,9 +35,11 @@
"drizzle-orm": "^0.45.2",
"eventsource": "3.0.7",
"hono": "^4.10.0",
+ "http-message-sig": "0.3.0",
"postgres": "^3.4.9",
"rxjs": "7.8.1",
"twilio": "5.13.0",
+ "web-bot-auth": "0.2.0",
"yaml": "^2.9.0",
"zod": "^4.4.3"
},
diff --git a/server/src/admin/controls.ts b/server/src/admin/controls.ts
index 181804a6..a2a03d10 100644
--- a/server/src/admin/controls.ts
+++ b/server/src/admin/controls.ts
@@ -58,6 +58,7 @@ import {
type EnterpriseStore,
type NetworkPolicyRow,
} from "./settings-store";
+import type { WebBotAuth } from "../web-bot-auth";
/** Action Recording keeps 90 days, as Grok Bot's does. */
export const ACTION_RECORD_RETENTION_DAYS = 90;
@@ -77,6 +78,8 @@ export type EnterpriseDeps = {
auditStore: AuditStore;
provider?: ComputerProvider;
computerToken?: string;
+ /** Pushed to every computer with its policy; see `computer/policy-network.ts`. */
+ webBotAuth?: WebBotAuth;
/** `provider/model` the built-in Bot runs on, for the model allowlist and usage view. */
builtInModel?: string;
/** Offboarding: ends sessions and deny-lists, and retires what a person granted. */
@@ -383,6 +386,7 @@ export async function installEnterpriseControls(
provider: deps.provider as ComputerProvider,
token: deps.computerToken,
policyForBot,
+ ...(deps.webBotAuth ? { webBotAuth: deps.webBotAuth } : {}),
});
if (report.failed.length > 0) {
console.warn(
diff --git a/server/src/app.ts b/server/src/app.ts
index f09acf6a..cadced79 100644
--- a/server/src/app.ts
+++ b/server/src/app.ts
@@ -138,6 +138,10 @@ import { userPreferencesRoutes } from "./user-preferences-routes";
import { createVoiceProvider } from "./voice/provider";
import { createVoiceRoutes } from "./voice/routes";
import type { VoiceSessionServices } from "./voice/session-routes";
+import {
+ DIRECTORY_PATH as WEB_BOT_AUTH_DIRECTORY_PATH,
+ directoryResponse as webBotAuthDirectory,
+} from "./web-bot-auth";
/**
* How much of a multipart body is boundary, headers and other fields rather than file.
@@ -447,6 +451,14 @@ export function createApp(
mountProviderOAuthProxy(app, modelProviderProxy);
app.get("/health", (context) => context.json({ status: "ok" }));
+ // The public key Bots' browsers sign their requests with, where Cloudflare and any other verifier
+ // look for it. Public by design, and absent when Web Bot Auth is off. See web-bot-auth.ts.
+ const webBotAuth = config.webBotAuth;
+ if (webBotAuth) {
+ app.get(WEB_BOT_AUTH_DIRECTORY_PATH, (context) =>
+ webBotAuthDirectory(context.req.raw, webBotAuth),
+ );
+ }
// Projected, never the raw runtime. config.runtime carries the Intelligence contract, including
// INTELLIGENCE_API_KEY and the licence token, and this endpoint is reachable by anyone. Returning
// the object wholesale would serve deployment secrets to the browser. Add fields here explicitly.
diff --git a/server/src/computer/policy-network.ts b/server/src/computer/policy-network.ts
index 794bb710..b243f487 100644
--- a/server/src/computer/policy-network.ts
+++ b/server/src/computer/policy-network.ts
@@ -22,6 +22,7 @@ import {
parseEgressRules,
} from "../../../agent-computer/src/egress";
import type { NetworkPolicyRow } from "../admin/settings-store";
+import type { WebBotAuth } from "../web-bot-auth";
import type { ComputerProvider } from "./provider";
export type { EgressPolicy, EgressRule };
@@ -76,6 +77,7 @@ export async function pushEgressPolicies(options: {
provider: ComputerProvider;
token?: string;
policyForBot: (botId: string) => Promise<EgressPolicy>;
+ webBotAuth?: WebBotAuth;
fetchImpl?: typeof fetch;
}): Promise<EgressPushReport> {
const fetchImpl = options.fetchImpl ?? fetch;
@@ -87,6 +89,7 @@ export async function pushEgressPolicies(options: {
const policy = await options.policyForBot(computer.botId);
await pushEgressPolicy(computer.url, computer.botId, policy, {
...(options.token ? { token: options.token } : {}),
+ ...(options.webBotAuth ? { webBotAuth: options.webBotAuth } : {}),
fetchImpl,
});
report.pushed.push(computer.botId);
@@ -100,12 +103,21 @@ export async function pushEgressPolicies(options: {
return report;
}
-/** Push one computer one Bot's policy. Throws with the reason when the computer does not take it. */
+/**
+ * Push one computer one Bot's policy. Throws with the reason when the computer does not take it.
+ *
+ * The deployment's Web Bot Auth key travels in the same body when it is on, so every computer that
+ * has a policy also has the key its browser signs with, and one pushed no key stops signing.
+ */
export async function pushEgressPolicy(
url: string,
botId: string,
policy: EgressPolicy,
- options: { token?: string; fetchImpl?: typeof fetch } = {},
+ options: {
+ token?: string;
+ webBotAuth?: WebBotAuth;
+ fetchImpl?: typeof fetch;
+ } = {},
): Promise<void> {
const response = await (options.fetchImpl ?? fetch)(
`${url.replace(/\/$/, "")}/egress-policy`,
@@ -118,6 +130,14 @@ export async function pushEgressPolicy(
},
body: JSON.stringify({
policy: { mode: policy.mode, rules: policy.rules },
+ ...(options.webBotAuth
+ ? {
+ webBotAuth: {
+ agent: options.webBotAuth.agent,
+ jwk: options.webBotAuth.privateJwk,
+ },
+ }
+ : {}),
}),
signal: AbortSignal.timeout(5_000),
},
@@ -149,6 +169,7 @@ export function withPolicyPushOnWake(
botId: string,
) => Promise<EgressPolicy | undefined> | undefined;
token?: string;
+ webBotAuth?: WebBotAuth;
fetchImpl?: typeof fetch;
},
): ComputerProvider {
@@ -170,6 +191,7 @@ export function withPolicyPushOnWake(
if (!policy) return;
await pushEgressPolicy(url, botId, policy, {
...(options.token ? { token: options.token } : {}),
+ ...(options.webBotAuth ? { webBotAuth: options.webBotAuth } : {}),
...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
});
pushed.set(botId, { run, at: Date.now() });
diff --git a/server/src/config.ts b/server/src/config.ts
index d3889510..ed85b906 100644
--- a/server/src/config.ts
+++ b/server/src/config.ts
@@ -17,6 +17,7 @@ import {
transcriptionConfig,
} from "./dictation/config";
import { type VoiceConfig, voiceConfig } from "./voice/config";
+import { type WebBotAuth, webBotAuthFromEnv } from "./web-bot-auth";
export type RuntimeCapabilities = {
mode: "intelligence";
@@ -244,6 +245,11 @@ export type DeploymentConfig = {
* deployment running without authentication — and there is nothing to connect there anyway.
*/
publicUrl: string | undefined;
+ /**
+ * The key Bots' browsers sign their requests with, and the address its public half is published
+ * under. Undefined when Web Bot Auth is off; see `web-bot-auth.ts` for when that is.
+ */
+ webBotAuth?: WebBotAuth;
/**
* Where the browser app is served from, with no trailing slash.
*
@@ -1312,13 +1318,19 @@ export function loadConfig(
);
}
const workerSharedSecret = optional(environment, "WORKER_SHARED_SECRET");
+ const deploymentKey = keyEncryptionKey(environment);
+ const webBotAuth = webBotAuthFromEnv(environment, {
+ publicUrl,
+ keyEncryptionKey: deploymentKey,
+ });
return {
port: serverPort(environment),
transcription: transcriptionConfig(environment),
voice: voiceConfig(environment),
databaseUrl: required(environment, "DATABASE_URL"),
- keyEncryptionKey: keyEncryptionKey(environment),
+ keyEncryptionKey: deploymentKey,
+ ...(webBotAuth ? { webBotAuth } : {}),
...(managedAgent ? { managedAgent } : {}),
...(githubApp ? { githubApp } : {}),
agentEndpointAllowedHosts: agentEndpointAllowedHosts(environment),
diff --git a/server/src/index.ts b/server/src/index.ts
index 5bb3e96a..e5425cc1 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -476,6 +476,7 @@ const computerProvider = config.computer
? withPolicyPushOnWake(createComputerProvider(config.computer), {
policyForBot: (botId) => enterpriseControls()?.policyForBot(botId),
...(config.computer.token ? { token: config.computer.token } : {}),
+ ...(config.webBotAuth ? { webBotAuth: config.webBotAuth } : {}),
})
: undefined;
@@ -2913,6 +2914,7 @@ await installEnterpriseControls({
auditStore: bootAuditStore,
...(computerProvider ? { provider: computerProvider } : {}),
...(config.computer?.token ? { computerToken: config.computer.token } : {}),
+ ...(config.webBotAuth ? { webBotAuth: config.webBotAuth } : {}),
builtInModel: `${runtimeModel.provider}/${runtimeModel.defaultModel}`,
people: peopleStore,
initialAdminEmails: config.auth?.initialAdminEmails ?? [],
diff --git a/server/src/web-bot-auth.ts b/server/src/web-bot-auth.ts
new file mode 100644
index 00000000..b72b9398
--- /dev/null
+++ b/server/src/web-bot-auth.ts
@@ -0,0 +1,250 @@
+import {
+ createHash,
+ createPrivateKey,
+ createPublicKey,
+ hkdfSync,
+} from "node:crypto";
+import { component, createSignature } from "http-message-sig";
+import { generateNonce, HTTP_MESSAGE_SIGNATURES_DIRECTORY } from "web-bot-auth";
+import { signerFromJWK } from "web-bot-auth/crypto";
+
+/**
+ * Web Bot Auth: a Bot's browser says, cryptographically, which deployment it browses for.
+ *
+ * The protocol is Cloudflare's signed agents (https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/),
+ * built on HTTP Message Signatures (RFC 9421). The deployment holds one Ed25519 key, publishes its
+ * public half at `/.well-known/http-message-signatures-directory`, and every request a Bot's browser
+ * makes carries `Signature-Agent`, `Signature-Input` and `Signature` (signed in agent-computer, see
+ * `agent-computer/src/web-bot-auth.ts`). A site behind Cloudflare that allows signed agents lets the
+ * request through instead of challenging it; one that does not is unaffected. It is how OpenAI's
+ * agent identifies itself, and the honest alternative to looking like a person.
+ *
+ * Signing alone earns nothing until the deployment is registered with Cloudflare, which is a manual
+ * step: see docs/configuration.md.
+ */
+
+export const DIRECTORY_PATH = HTTP_MESSAGE_SIGNATURES_DIRECTORY;
+export const DIRECTORY_CONTENT_TYPE =
+ "application/http-message-signatures-directory+json";
+
+/**
+ * How long a directory signature is good for. Each fetch is signed afresh, so this only has to
+ * outlive a cache between the deployment and the verifier.
+ */
+const DIRECTORY_SIGNATURE_TTL_SECONDS = 300;
+
+export type WebBotAuth = {
+ /** `https://host`, the value Bots send in `Signature-Agent`; the directory lives under it. */
+ agent: string;
+ /** Full private key. Sent to this deployment's computers so they can sign; never logged. */
+ privateJwk: JsonWebKey;
+ publicJwk: JsonWebKey;
+ /** RFC 7638 thumbprint, the `keyid` every signature names. */
+ keyid: string;
+};
+
+/** The private seed derived from the deployment key, when no key is given explicitly. */
+function derivedSeed(keyEncryptionKey: string): Buffer {
+ return Buffer.from(
+ hkdfSync(
+ "sha256",
+ Buffer.from(keyEncryptionKey, "base64"),
+ Buffer.alloc(0),
+ Buffer.from("openbot web-bot-auth ed25519 v1"),
+ 32,
+ ),
+ );
+}
+
+/** PKCS#8 for an Ed25519 seed: the fixed RFC 8410 prefix followed by the 32 bytes. */
+function ed25519FromSeed(seed: Buffer): JsonWebKey {
+ const pkcs8 = Buffer.concat([
+ Buffer.from("302e020100300506032b657004220420", "hex"),
+ seed,
+ ]);
+ return createPrivateKey({ key: pkcs8, format: "der", type: "pkcs8" }).export({
+ format: "jwk",
+ }) as JsonWebKey;
+}
+
+function parseJwk(raw: string): JsonWebKey {
+ let jwk: JsonWebKey;
+ try {
+ jwk = JSON.parse(raw) as JsonWebKey;
+ } catch {
+ throw new Error(
+ "WEB_BOT_AUTH_KEY must be an Ed25519 private key as a JSON Web Key.",
+ );
+ }
+ if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.d || !jwk.x) {
+ throw new Error(
+ "WEB_BOT_AUTH_KEY must be an Ed25519 private key (kty OKP, crv Ed25519, with d and x).",
+ );
+ }
+ // Refuse a pair whose halves do not match, which would publish a key nothing signs with.
+ const derived = createPublicKey(
+ createPrivateKey({ key: jwk, format: "jwk" }),
+ ).export({ format: "jwk" }) as JsonWebKey;
+ if (derived.x !== jwk.x) {
+ throw new Error("WEB_BOT_AUTH_KEY's x does not match its d.");
+ }
+ return { kty: "OKP", crv: "Ed25519", d: jwk.d, x: jwk.x };
+}
+
+/** RFC 7638: SHA-256 over the required members in lexical order, base64url. Cloudflare's `keyid`. */
+function thumbprint(x: string): string {
+ return createHash("sha256")
+ .update(JSON.stringify({ crv: "Ed25519", kty: "OKP", x }))
+ .digest("base64url");
+}
+
+/**
+ * Where a verifier could fetch the directory from: `public` for an https address on the internet,
+ * `private` for https on a private or single-label name (an intranet verifier, perhaps), and
+ * undefined for anything that is not https or is this machine.
+ */
+function httpsReach(
+ url: string | undefined,
+): { origin: string; reach: "public" | "private" } | undefined {
+ if (!url) return undefined;
+ let parsed: URL;
+ try {
+ parsed = new URL(url);
+ } catch {
+ return undefined;
+ }
+ if (parsed.protocol !== "https:") return undefined;
+ const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+ if (
+ host === "localhost" ||
+ host.endsWith(".localhost") ||
+ host === "::1" ||
+ /^127(\.\d{1,3}){3}$/.test(host)
+ ) {
+ return undefined;
+ }
+ const octets = host.split(".").map(Number);
+ const [a = -1, b = -1] = octets;
+ const privateAddress =
+ (octets.length === 4 &&
+ octets.every((octet) => Number.isInteger(octet)) &&
+ (a === 10 ||
+ (a === 172 && b >= 16 && b <= 31) ||
+ (a === 192 && b === 168) ||
+ (a === 169 && b === 254) ||
+ (a === 100 && b >= 64 && b <= 127))) ||
+ /^f[cd]|^fe[89ab]/.test(host) ||
+ !host.includes(".") ||
+ /\.(local|internal|lan|home\.arpa|test)$/.test(host);
+ return {
+ origin: parsed.origin,
+ reach: privateAddress ? "private" : "public",
+ };
+}
+
+/**
+ * The deployment's Web Bot Auth identity, or undefined when it is off.
+ *
+ * `WEB_BOT_AUTH=on|off`; unset means on whenever the deployment has a public HTTPS address
+ * (`OPENBOT_PUBLIC_URL`, else `BETTER_AUTH_URL`), because the directory has to be fetchable over
+ * HTTPS from the internet for the signatures to mean anything, and off otherwise: plain http, this
+ * machine, or a private address. `on` also signs with a private HTTPS address, and is refused for
+ * plain http or this machine rather than signing with a directory nobody can read.
+ *
+ * The key is `WEB_BOT_AUTH_KEY` (an Ed25519 private JWK) when given, otherwise derived from
+ * `KEY_ENCRYPTION_KEY` with HKDF, so every replica and every restart signs with the same key and a
+ * deployment needs no new secret to start.
+ */
+export function webBotAuthFromEnv(
+ environment: Record<string, string | undefined>,
+ options: { publicUrl: string | undefined; keyEncryptionKey: string },
+): WebBotAuth | undefined {
+ const switchValue = environment.WEB_BOT_AUTH?.trim().toLowerCase() || "";
+ if (switchValue && switchValue !== "on" && switchValue !== "off") {
+ throw new Error(
+ `WEB_BOT_AUTH must be on or off, not ${JSON.stringify(environment.WEB_BOT_AUTH)}.`,
+ );
+ }
+ if (switchValue === "off") return undefined;
+ const reach = httpsReach(options.publicUrl);
+ if (!reach) {
+ if (switchValue === "on") {
+ throw new Error(
+ "WEB_BOT_AUTH=on needs an HTTPS address in OPENBOT_PUBLIC_URL (or BETTER_AUTH_URL) other than this machine, where verifiers fetch the signing key.",
+ );
+ }
+ return undefined;
+ }
+ // On by itself only where the internet can read the key. A private address is the operator's
+ // call, since only they know whether their verifier can reach it.
+ if (reach.reach === "private" && switchValue !== "on") return undefined;
+ const agent = reach.origin;
+ const explicit = environment.WEB_BOT_AUTH_KEY?.trim();
+ const privateJwk = explicit
+ ? parseJwk(explicit)
+ : ed25519FromSeed(derivedSeed(options.keyEncryptionKey));
+ const publicJwk: JsonWebKey = {
+ kty: "OKP",
+ crv: "Ed25519",
+ x: privateJwk.x as string,
+ };
+ return {
+ agent,
+ privateJwk,
+ publicJwk,
+ keyid: thumbprint(privateJwk.x as string),
+ };
+}
+
+/**
+ * `GET /.well-known/http-message-signatures-directory`: the public key, signed.
+ *
+ * The response carries its own signature over `("@authority";req)` with the
+ * `http-message-signatures-directory` tag, which is how a verifier knows the key was published by
+ * the holder of the key and not merely placed on the host.
+ */
+export async function directoryResponse(
+ request: Request,
+ identity: WebBotAuth,
+ now: Date = new Date(),
+): Promise<Response> {
+ const body = JSON.stringify({ keys: [identity.publicJwk] });
+ const authority = request.headers.get("host") ?? new URL(request.url).host;
+ const created = Math.floor(now.getTime() / 1000);
+ const signer = await signerFromJWK(identity.privateJwk);
+ const fields = await createSignature(
+ {
+ kind: "response",
+ status: 200,
+ fields: [{ name: "content-type", value: DIRECTORY_CONTENT_TYPE }],
+ request: {
+ kind: "request",
+ method: "GET",
+ targetUri: `https://${authority}${DIRECTORY_PATH}`,
+ fields: [{ name: "host", value: authority }],
+ },
+ },
+ {
+ label: "sig1",
+ components: [component("@authority", { req: true })],
+ parameters: {
+ alg: "ed25519",
+ keyid: identity.keyid,
+ created,
+ expires: created + DIRECTORY_SIGNATURE_TTL_SECONDS,
+ nonce: generateNonce(),
+ tag: "http-message-signatures-directory",
+ },
+ signer,
+ },
+ );
+ return new Response(body, {
+ status: 200,
+ headers: {
+ "content-type": DIRECTORY_CONTENT_TYPE,
+ "cache-control": "public, max-age=60",
+ signature: fields.signature,
+ "signature-input": fields.signatureInput,
+ },
+ });
+}
diff --git a/server/tests/tool-selection-environment-restoration-driver.test.ts b/server/tests/tool-selection-environment-restoration-driver.test.ts
index 631b4bce..4de4a191 100644
--- a/server/tests/tool-selection-environment-restoration-driver.test.ts
+++ b/server/tests/tool-selection-environment-restoration-driver.test.ts
@@ -145,20 +145,25 @@ async function emitRestorationProof(modelModule: ModelModule) {
}
}
+/**
+ * A refused, reset or broken connection, however this Bun spells it. Bun 1.3 threw an Error with
+ * `code: "ConnectionRefused"`; Bun 1.4 throws a TypeError with `code: "ECONNREFUSED"` and the code
+ * prefixed to the message. Node-style errors carry it on `cause`. Matched on codes, not message text.
+ */
+const STOPPED_LISTENER_CODES = new Set([
+ "ConnectionRefused",
+ "ECONNREFUSED",
+ "ECONNRESET",
+ "EPIPE",
+]);
+
function fetchFailureLooksLikeStoppedListener(error: unknown) {
if (!(error instanceof Error)) return false;
- if (
- error.message ===
- "Unable to connect. Is the computer able to access the url?"
- ) {
- return true;
- }
-
+ const code = (error as { code?: unknown }).code;
const cause = (error as { cause?: { code?: unknown } }).cause;
return (
- cause?.code === "ECONNREFUSED" ||
- cause?.code === "ECONNRESET" ||
- cause?.code === "EPIPE"
+ (typeof code === "string" && STOPPED_LISTENER_CODES.has(code)) ||
+ (typeof cause?.code === "string" && STOPPED_LISTENER_CODES.has(cause.code))
);
}
diff --git a/server/tests/web-bot-auth.test.ts b/server/tests/web-bot-auth.test.ts
new file mode 100644
index 00000000..d614e3d7
--- /dev/null
+++ b/server/tests/web-bot-auth.test.ts
@@ -0,0 +1,326 @@
+import { describe, expect, test } from "bun:test";
+import { generateKeyPairSync } from "node:crypto";
+import { component, verifySignature } from "http-message-sig";
+import { signerFromJWK, verifierFromJWK } from "web-bot-auth/crypto";
+import { createApp } from "../src/app";
+import { pushEgressPolicy } from "../src/computer/policy-network";
+import { loadConfig } from "../src/config";
+import {
+ DIRECTORY_CONTENT_TYPE,
+ DIRECTORY_PATH,
+ directoryResponse,
+ webBotAuthFromEnv,
+} from "../src/web-bot-auth";
+import { testEnvironment } from "./support/environment";
+
+const KEY = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+const OTHER_KEY = "AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE=";
+const PUBLIC = "https://openbot.example.com";
+
+function generatedJwk(): JsonWebKey {
+ return generateKeyPairSync("ed25519").privateKey.export({ format: "jwk" });
+}
+
+describe("whether Web Bot Auth is on", () => {
+ test("on by default when the deployment has a public HTTPS address", () => {
+ const identity = webBotAuthFromEnv(
+ {},
+ { publicUrl: PUBLIC, keyEncryptionKey: KEY },
+ );
+ expect(identity?.agent).toBe(PUBLIC);
+ });
+
+ // A verifier on the internet has to fetch the key over HTTPS, so anything else would sign with a
+ // directory nobody can read.
+ test.each([
+ undefined,
+ "http://openbot.example.com",
+ "https://localhost:3001",
+ "https://127.0.0.1",
+ "https://app.localhost",
+ "https://10.0.0.5",
+ "https://192.168.1.20:3001",
+ "https://openbot.internal",
+ "https://intranet",
+ ])("off by default for %s", (publicUrl) => {
+ expect(
+ webBotAuthFromEnv({}, { publicUrl, keyEncryptionKey: KEY }),
+ ).toBeUndefined();
+ });
+
+ test("off when switched off, whatever the address", () => {
+ expect(
+ webBotAuthFromEnv(
+ { WEB_BOT_AUTH: "off" },
+ { publicUrl: PUBLIC, keyEncryptionKey: KEY },
+ ),
+ ).toBeUndefined();
+ });
+
+ test.each([
+ "http://openbot.example.com",
+ "https://localhost:3001",
+ undefined,
+ ])(
+ "on with %s, which nobody else can fetch over HTTPS, is refused at start-up",
+ (publicUrl) => {
+ expect(() =>
+ webBotAuthFromEnv(
+ { WEB_BOT_AUTH: "on" },
+ { publicUrl, keyEncryptionKey: KEY },
+ ),
+ ).toThrow("WEB_BOT_AUTH=on needs an HTTPS address");
+ },
+ );
+
+ // Only the operator knows whether their verifier can reach a private address.
+ test("on signs with a private HTTPS address", () => {
+ expect(
+ webBotAuthFromEnv(
+ { WEB_BOT_AUTH: "on" },
+ { publicUrl: "https://10.0.0.5", keyEncryptionKey: KEY },
+ )?.agent,
+ ).toBe("https://10.0.0.5");
+ });
+
+ test("an unknown switch value is refused", () => {
+ expect(() =>
+ webBotAuthFromEnv(
+ { WEB_BOT_AUTH: "yes" },
+ { publicUrl: PUBLIC, keyEncryptionKey: KEY },
+ ),
+ ).toThrow("WEB_BOT_AUTH must be on or off");
+ });
+
+ test("reaches the configuration, and stays off in an ordinary local one", () => {
+ expect(loadConfig(testEnvironment()).webBotAuth).toBeUndefined();
+ expect(
+ loadConfig(testEnvironment({ OPENBOT_PUBLIC_URL: PUBLIC })).webBotAuth
+ ?.agent,
+ ).toBe(PUBLIC);
+ });
+});
+
+describe("the signing key", () => {
+ test("is derived from the deployment key, the same on every replica and restart", () => {
+ const first = webBotAuthFromEnv(
+ {},
+ { publicUrl: PUBLIC, keyEncryptionKey: KEY },
+ );
+ const second = webBotAuthFromEnv(
+ {},
+ { publicUrl: PUBLIC, keyEncryptionKey: KEY },
+ );
+ const other = webBotAuthFromEnv(
+ {},
+ { publicUrl: PUBLIC, keyEncryptionKey: OTHER_KEY },
+ );
+ expect(first?.privateJwk).toEqual(second?.privateJwk as JsonWebKey);
+ expect(first?.keyid).not.toBe(other?.keyid);
+ // One way: the deployment key is not the signing key or anything in the published directory.
+ expect(JSON.stringify(first)).not.toContain(KEY.replace(/=+$/, ""));
+ });
+
+ test("is WEB_BOT_AUTH_KEY when given", () => {
+ const jwk = generatedJwk();
+ const identity = webBotAuthFromEnv(
+ { WEB_BOT_AUTH_KEY: JSON.stringify(jwk) },
+ { publicUrl: PUBLIC, keyEncryptionKey: KEY },
+ );
+ expect(identity?.publicJwk).toEqual({
+ kty: "OKP",
+ crv: "Ed25519",
+ x: jwk.x,
+ });
+ });
+
+ test("refuses a key whose public half does not match its private half", () => {
+ const jwk = { ...generatedJwk(), x: generatedJwk().x };
+ expect(() =>
+ webBotAuthFromEnv(
+ { WEB_BOT_AUTH_KEY: JSON.stringify(jwk) },
+ { publicUrl: PUBLIC, keyEncryptionKey: KEY },
+ ),
+ ).toThrow("does not match");
+ });
+
+ test("refuses something that is not an Ed25519 private key, without echoing it", () => {
+ const rsa = generateKeyPairSync("rsa", {
+ modulusLength: 2048,
+ }).privateKey.export({ format: "jwk" });
+ for (const value of ["not json", JSON.stringify(rsa)]) {
+ let message = "";
+ try {
+ webBotAuthFromEnv(
+ { WEB_BOT_AUTH_KEY: value },
+ { publicUrl: PUBLIC, keyEncryptionKey: KEY },
+ );
+ } catch (error) {
+ message = String(error);
+ }
+ expect(message).toContain("WEB_BOT_AUTH_KEY must be an Ed25519");
+ expect(message).not.toContain(value);
+ }
+ });
+
+ test("is named by its RFC 7638 thumbprint, as the reference signer names it", async () => {
+ const identity = webBotAuthFromEnv(
+ {},
+ { publicUrl: PUBLIC, keyEncryptionKey: KEY },
+ );
+ const signer = await signerFromJWK(identity?.privateJwk as JsonWebKey);
+ expect(identity?.keyid).toBe(signer.keyid);
+ });
+});
+
+describe("the key directory", () => {
+ const identity = webBotAuthFromEnv(
+ {},
+ { publicUrl: PUBLIC, keyEncryptionKey: KEY },
+ )!;
+
+ test("publishes the public key and nothing private", async () => {
+ const response = await directoryResponse(
+ new Request(`${PUBLIC}${DIRECTORY_PATH}`),
+ identity,
+ );
+ expect(response.status).toBe(200);
+ expect(response.headers.get("content-type")).toBe(DIRECTORY_CONTENT_TYPE);
+ const body = (await response.json()) as { keys: JsonWebKey[] };
+ expect(body).toEqual({ keys: [identity.publicJwk] });
+ expect(JSON.stringify(body)).not.toContain(identity.privateJwk.d as string);
+ });
+
+ // What tells a verifier the key was published by the holder of the key: the response is signed
+ // over the authority it was fetched from, with the directory tag.
+ test("is signed by its own key over the authority it was fetched from", async () => {
+ const request = new Request(`${PUBLIC}${DIRECTORY_PATH}`);
+ const response = await directoryResponse(request, identity);
+ expect(response.headers.get("signature-input")).toContain(
+ '("@authority";req)',
+ );
+ expect(response.headers.get("signature-input")).toContain(
+ 'tag="http-message-signatures-directory"',
+ );
+ const verifier = await verifierFromJWK(identity.publicJwk);
+ const verified = await verifySignature(
+ {
+ kind: "response",
+ status: response.status,
+ fields: [...response.headers].map(([name, value]) => ({
+ name,
+ value,
+ })),
+ request: {
+ kind: "request",
+ method: "GET",
+ targetUri: request.url,
+ fields: [{ name: "host", value: new URL(PUBLIC).host }],
+ },
+ },
+ {
+ policy: {
+ algorithms: ["ed25519"],
+ requiredComponents: [component("@authority", { req: true })],
+ requiredParameters: ["created", "expires", "keyid", "tag"],
+ },
+ resolveVerifier: (candidate) => {
+ expect(candidate.parameters.keyid).toBe(identity.keyid);
+ return verifier;
+ },
+ },
+ );
+ expect(verified.parameters.tag).toBe("http-message-signatures-directory");
+ const { created, expires } = verified.parameters;
+ expect((expires as number) - (created as number)).toBe(300);
+ });
+
+ test("a signature over one host does not verify for another", async () => {
+ const response = await directoryResponse(
+ new Request(`${PUBLIC}${DIRECTORY_PATH}`),
+ identity,
+ );
+ const verifier = await verifierFromJWK(identity.publicJwk);
+ await expect(
+ verifySignature(
+ {
+ kind: "response",
+ status: 200,
+ fields: [...response.headers].map(([name, value]) => ({
+ name,
+ value,
+ })),
+ request: {
+ kind: "request",
+ method: "GET",
+ targetUri: `https://elsewhere.example${DIRECTORY_PATH}`,
+ fields: [{ name: "host", value: "elsewhere.example" }],
+ },
+ },
+ {
+ policy: {
+ algorithms: ["ed25519"],
+ requiredComponents: [component("@authority", { req: true })],
+ requiredParameters: ["created", "expires", "keyid", "tag"],
+ },
+ resolveVerifier: () => verifier,
+ },
+ ),
+ ).rejects.toMatchObject({ code: "VerificationFailed" });
+ });
+
+ test("is served at the well-known path when on, and not served when off", async () => {
+ const on = createApp(
+ loadConfig(testEnvironment({ OPENBOT_PUBLIC_URL: PUBLIC })),
+ );
+ const served = await on.request(`${PUBLIC}${DIRECTORY_PATH}`);
+ expect(served.status).toBe(200);
+ expect(served.headers.get("content-type")).toBe(DIRECTORY_CONTENT_TYPE);
+ expect(served.headers.get("signature")).toStartWith("sig1=:");
+
+ const off = createApp(loadConfig(testEnvironment()));
+ const missing = await off.request(`http://openbot.local${DIRECTORY_PATH}`);
+ expect(missing.headers.get("content-type")).not.toBe(
+ DIRECTORY_CONTENT_TYPE,
+ );
+ });
+});
+
+describe("handing the key to a computer", () => {
+ const identity = webBotAuthFromEnv(
+ {},
+ { publicUrl: PUBLIC, keyEncryptionKey: KEY },
+ )!;
+
+ async function pushedBody(webBotAuth?: typeof identity) {
+ let body: unknown;
+ await pushEgressPolicy(
+ "http://computer.internal:4100",
+ "bot-1",
+ { mode: "allow_all", rules: [] },
+ {
+ ...(webBotAuth ? { webBotAuth } : {}),
+ fetchImpl: (async (_url: string, init?: RequestInit) => {
+ body = JSON.parse(String(init?.body));
+ return new Response("{}");
+ }) as unknown as typeof fetch,
+ },
+ );
+ return body as { policy: unknown; webBotAuth?: unknown };
+ }
+
+ test("rides the policy push when on", async () => {
+ const body = await pushedBody(identity);
+ expect(body.policy).toEqual({ mode: "allow_all", rules: [] });
+ expect(body.webBotAuth).toEqual({
+ agent: PUBLIC,
+ jwk: identity.privateJwk,
+ });
+ });
+
+ // A computer pushed no key stops signing, so switching the deployment off reaches every computer.
+ test("is absent when off", async () => {
+ const body = await pushedBody();
+ expect(body).not.toHaveProperty("webBotAuth");
+ });
+});
diff --git a/shared/computer-control.ts b/shared/computer-control.ts
index 07ad4191..dc29657a 100644
--- a/shared/computer-control.ts
+++ b/shared/computer-control.ts
@@ -22,6 +22,16 @@ export type HandoffRequest = {
expiresAt?: string;
finishedAt?: string;
interruption?: string;
+ /**
+ * The page the request was raised on, so a browser that comes back blank can be sent there again
+ * before a person is asked to solve it. http(s) only; absent when the page was blank.
+ */
+ url?: string;
+ /**
+ * Set only on a request a restart interrupted while it still holds its page: the one case a later
+ * request may reopen that page. A stop or reset clears it, and so does the help TTL running out.
+ */
+ keepsPage?: boolean;
};
export type ComputerControlState = {
holder: "bot" | "human";
diff --git a/supervisor/Dockerfile b/supervisor/Dockerfile
index 5a682967..d2235c67 100644
--- a/supervisor/Dockerfile
+++ b/supervisor/Dockerfile
@@ -7,7 +7,7 @@
# supervisor reports and carries on from.
FROM ghcr.io/spiffe/spire-server:1.15.1 AS spire
-FROM oven/bun:1.3.14-alpine
+FROM oven/bun:1.4.3-alpine
WORKDIR /app
# The lockfile as well as the manifest: `--frozen-lockfile` with no lockfile present resolves afresh
diff --git a/supervisor/tests/fixtures/Dockerfile b/supervisor/tests/fixtures/Dockerfile
index 614e49a8..43c7b6c8 100644
--- a/supervisor/tests/fixtures/Dockerfile
+++ b/supervisor/tests/fixtures/Dockerfile
@@ -1,4 +1,4 @@
-FROM oven/bun:1.3.14-slim
+FROM oven/bun:1.4.3-slim
ARG FIXTURE_NAMESPACE
ARG FIXTURE_VARIANT
LABEL openbot.test-fixture=$FIXTURE_NAMESPACE openbot.test-variant=$FIXTURE_VARIANT