[Broccolito]

Fixes #402. Also restores path-prefix support from #9, lost when biorouter-headless was retired.

What was broken

All reproduced in Chrome (headless, via Playwright) through a TLS proxy that behaves like a JupyterHub chain: the prefix is stripped, Host is preserved, and X-Forwarded-Proto arrives as https,http.

1. Proxied HTTPS was refused with "Open Biorouter through localhost or HTTPS…", although Chrome had sent Sec-Fetch-Mode: navigate / Sec-Fetch-Dest: document. auth::reached_over_a_secure_context (new in 1.93.0) also required X-Forwarded-Proto: https, and it reads the last value. JupyterHub's configurable-http-proxy appends http after the TLS terminator's https, and JupyterHub's documented nginx block sends no X-Forwarded-Proto at all.
2. Path prefixes 404'd. The root-base bundle asks for /assets/... at the host root, so the page stays on "Loading Biorouter…".
3. Built apps never connected behind any HTTPS proxy. Chrome sends no Fetch Metadata on WebSocket handshakes, so each app's agent socket failed the same secure-address check ("No Biorouter backend"). Under a prefix, the app page, launch bounce, app cookie and SDK also all named /apps/{id}/ from the root.

What changed

• Secure address = the browser's word. A non-loopback Host passes on Fetch Metadata (sent only to https or loopback URLs, and unforgeable by script). A WebSocket handshake, which carries none, passes when its Origin is https. X-Forwarded-Proto is no longer consulted here. Plain-HTTP LAN is still refused, for pages and for handshakes from http pages.
• Relative bundle plus <base href>. build:web passes --base ./, and the daemon writes <base href> (./, ../, …, derived from the request path depth; only dot segments) first in the shell's head. The renderer derives its API and /headless bases from document.baseURI. The token bounce goes to ./.
• biorouter serve --public-url <url> (or BIOROUTER_PUBLIC_URL):
  • prints the public address with the token;
  • adds its origin to the WebSocket gates (Chrome sends no Fetch Metadata on handshakes, so a chain that rewrites Host or appends http otherwise refuses every live view);
  • scopes the session cookie Path to the prefix;
  • must be https unless loopback;
  • is read only by a daemon that serves the UI;
  • is validated identically in the CLI and the daemon.
• Apps under a prefix:
  • the page gets <base href="./"> and the launch bounce goes to ./;
  • the app cookie carries no Path, so the browser scopes it to the redeeming address (at the root that is the same /apps/{id} as before);
  • sdk.ts reads the prefix in front of /apps/<id>/ from its own address for the socket, REST and figure-frame URLs (export pages unchanged).
• Hardening from an independent security review:
  • a daemon-served page ignores ?api= / ?headless= from the address bar, which with --no-token let any site redirect the secret;
  • the JupyterHub recipe no longer recommends --no-token where users share one machine;
  • the CI deep-path check no longer pipes curl into grep -q.
• Docs: decision SD-15 (supersedes SD-4, amends SD-14); "Behind a reverse proxy" and JupyterHub sections; updated headless-linux.md, serve-architecture.md and CLAUDE.md.

Verification (real Chrome through the JupyterHub-like proxy)

Scenario	Before	After
Interface at /user/minrk/proxy/9999/	403	mounts; all requests under the prefix
Clean https proxy with prefix	assets 404	mounts
Interface live-view socket (with --public-url)	n/a	connects
Built app: page, bundle, agent socket	socket 403	all work; cookie Path=/user/minrk/proxy/9999/apps/<id>
Token flow and deep paths under the prefix	n/a	work
?api=https://evil.example link	n/a	no request leaves for that host
Plain serve on loopback at /	works	works
Plain-HTTP LAN address	403	403

• cargo test -p biorouter-server --lib (1004 passed) and cargo test -p biorouter-cli --lib (791 passed)
• -p biorouter-mcp --lib agent_drafter:: (386 passed), --test ui_example_apps, --test serve_lifecycle
• clippy -D warnings on all three crates
• the app SDK jsdom harness, including new prefix checks that fail on the old SDK
• lint:check and format:check
• the rust.yml serve contract script, run locally

Notes for review

• Security-sensitive: auth.rs (secure-address check, app cookie) and routes/mod.rs (WebSocket origin gate). Reasoning is in SD-15.
• The proxy must strip the prefix, and the address is opened with its trailing slash.
• Changing sdk.ts changes its content hash, so existing apps rebuild on their next load, which is the designed path.

🤖 Generated with Claude Code