Repository navigation
feat(dashboard): serve the browser view through a same-origin relay - #12229
Conversation
|
Intent: Restore the dashboard's live browser view for remote and tunneled dashboards by relaying the |
|
Maintainer re-run requested — all code lanes are green on
No code change is pending, so a Re-run failed jobs on this head should let everything settle. As a fork contributor I can't trigger the re-run myself. Thanks! |
a28034e to
c4a695f
Compare
Opus 5 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings that block — one advisory defect in the relay's error handling. FINDING — src/kiro_crew/dashboard/handlers/browser_view_relay.py:626 — the streamed branch's [OPUS-REVIEWED] ca9c48e |
First Principles Review (Fable 5, fork) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The rewrite layer rests on an unverified playwright-cli bundle-shape premise, and the panel prefers the relay even on local dashboards where the direct URL worked. Not justified as shipped
What this change shipsInventory (10 items) — 9 justifiedIntent: restore the Browser panel's live view on remote/tunneled dashboards by relaying it through the dashboard's own origin — a FIX (regression documented in the base spec's own "dead unless pinned and forwarded" text).
[FIRST-PRINCIPLES-REVIEWED] ca9c48e |
Design Review (Fable 5, fork) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Relay breakage after a playwright-cli upgrade is silent: the panel prefers the relay unconditionally, its liveness probe is disabled, and the only guard is a manual ritual. WatchThe rewrites are string-pinned to the current bundle shape (double-quoted Suggestions
[DESIGN-REVIEWED] ca9c48e |
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsFINDING -- src/kiro_crew/dashboard/handlers/browser_view_relay.py:539 -- |
c4a695f to
4b69853
Compare
|
Pushed 4b69853 addressing the blocking finding from the GPT 5.6 lane: relay_target() no longer hands out the recorded port/token blindly. It now re-proves ownership on every lookup using the supervisor's existing process-liveness, root-identity, and listener-ownership checks (no HTTP probe on the per-request path). A definitive failure tears down the relay state and invalidates the token before anything can squat on the freed port; an inconclusive proof withholds the target without destroying state so a later request can retry. Three regression tests cover the dead-child, inconclusive, and proven paths. Also rebased onto current main (picked up #12340's server.py changes cleanly). |
4b69853 to
00fad31
Compare
|
Pushed 00fad31 addressing both blocking findings from the GPT 5.6 lane on 4b69853:
Also rebased onto current main. 295 backend tests (relay + token_auth) and 130 panel tests pass; black/isort/flake8/mypy/tsc/eslint clean. |
buluoray
left a comment
There was a problem hiding this comment.
Read this at head 00fad310 against source. The code is good — I went looking for the usual ways a relay like this goes wrong and did not find them. I am commenting rather than approving, for a reason about the review coverage rather than the change, at the end.
What I verified rather than took on trust
The design resolves the tension its own title creates. "Same-origin relay" is the host, so a tunnel or SSH forward needs no second port; the document is then forced into an opaque origin by Content-Security-Policy: sandbox with no allow-same-origin, so relayed content cannot reach dashboard cookies, storage or an authenticated fetch. That is the right way round, and the _STORAGE_SHIM exists precisely because the opaque origin makes a bare localStorage read throw — which is evidence the sandbox is real rather than nominal.
- The target cannot be steered.
_split_tokenreadsraw_path, guarantees the suffix starts with/, and joins it onto a fixedhttp://127.0.0.1:<port>authority, so//evil.com/xstays a path on loopback. The port comes from the supervisor, never from the request. relay_target()genuinely re-proves ownership per request — process liveness, root identity, and listener ownership, with no HTTP probe on the hot path. A definitive failure tears down_info/_relay/_child_port/_relay_tokenbefore anything can squat the freed port; an inconclusive proof withholds without destroying state. Port and token return as one pair under one lock, so a token from one instance can never proxy to another. This closes the earlier blocking finding properly rather than narrowing it.- The token check is sound.
hmac.compare_digestagainst a"\x00none"placeholder when no view exists, so the dead-view and wrong-token paths take the same time and answer the same uniform 404.raw_pathkeeps percent-encoding, so no request can spell a literal NUL — that detail is load-bearing and the comment says so. - No credential is forwarded upstream.
_FORWARD_REQUEST_HEADERSis Accept, Accept-Language, If-None-Match, If-Modified-Since, Range. No Cookie, no Authorization. _rewrite_locationfails closed — anything carrying a scheme or netloc degrades to the relay root instead of sending the browser off-origin.- The bypass entry is justified rather than convenient. Adding
/browser-view/totoken_auth._BYPASS_PREFIXESis the part I scrutinised hardest, since it removes cookie auth from a prefix. Cookie auth is structurally unavailable here (an opaque origin sends none), the capability token replaces it, and this mirrors the/artifact-app/and/sandbox-doc/precedent sitting directly above it.
One live finding
GPT's finding from the last round is still open at this head, in three places rather than one: :50, the constant comment at :90, and _stamp_relay_headers's own docstring at :300 all say the stamp goes on every relayed response except script types. The redirect branch returns a bare Location response with no CSP, no nosniff and no Access-Control-Allow-Origin.
I do not think it is exploitable — a 3xx body is not rendered, and Location is always set (the .get("Location", "/") default plus _rewrite_location never returning empty). But the claim is false in the file's own security posture description, which is where the next person adding a response branch will look for the rule. That is worth a wording fix even though no behaviour changes.
There is a functional twin worth a moment's thought: a CORS-mode request must pass the CORS check on each response including redirects, so if the view server ever 302s an asset, the crossorigin script and stylesheet tags that motivated Access-Control-Allow-Origin: * would fail on the redirect hop. Stamping the redirect the same way as everything else fixes both the claim and that corner in one line.
Why I am not approving
Of the five review lanes, one produced a verdict on this head. Opus 4.8 is failure / "review incomplete" with no verdict for this commit, and Design, First Principles and UX all report "could not complete". For a change that adds an authentication-bypass prefix, my reading should not stand in for four lanes that never ran — so this wants the maintainer re-run you already asked for, not a human approval on top of one lane.
Related, and not this PR's fault: the Security Scope lane published "nothing to scope — no security-surface path touched". That is true against its configured list, and the list is the problem. Between the SCOPE-SURFACE-BEGIN/END sentinels in security-scope-review.yml the surface is src/kiro_crew/security/, deny_guidance.py, platform/security_authority.py, hooks.py, two security-conductor JSONs and four scripts — src/kiro_crew/dashboard/token_auth.py is not among them. So a change that edits _BYPASS_PREFIXES, which is what deciding "this URL prefix no longer needs the session cookie" means, cannot trigger the lane built to scope security changes. The two precedents above your entry presumably landed the same way. Worth an issue on its own.
|
Ran the maintainer re-run you asked for — re-ran Fast Gate on All four Claude-backed fork lanes die in the same place, before the model is ever reached: Fork Opus 4.8 Review (run The cause is a gap in the egress allowlist, not in your change. The fork lanes run So this is repository-wide: no fork pull request can currently get an Opus verdict or any Fable advisory verdict. The fix is adding My earlier review stands unchanged — the code reads well and I found no security defect. Two things still worth your time, both independent of the above:
|
4f6b0cd to
e58193b
Compare
|
Pushed e58193b addressing this wave's findings — the GPT 5.6 blocking finding, both Opus 5 findings (blocking + non-blocking), and the lint gate:
Verified: 435 backend tests across the three touched suites (30 relay + 122 view + 283 token_auth), 126 panel tests, black/isort/flake8/mypy/tsc/eslint clean, feature-map gate green. Base was unmoved; no rebase this round. |
e58193b to
3f962ab
Compare
|
Pushed 3f962ab addressing the Opus 5 verdict on e58193b (both findings, one mechanism): Blocking — concurrent provers clobbering the per-proc proof slot. The finding was correct end to end: the slot protocol (record→take, cleared on Non-blocking — probe fan-out and the payload double-proof. Same mechanism: a single-flight verdict cache (~0.5s TTL, keyed to the exact process instance + pid + port, invalidated on stop/teardown) fronts the gate with a double-checked lookup — waiters consume the leader's verdict instead of proving again, so one page load's fan-out costs one proof run, and The bracket invariant survives the cache. The post-connect re-proof now carries a monotonic fence ( 7 new view-supervisor tests (deterministic gate serialization with the waiter consuming the leader's verdict, the 8-thread clobber regression through the REAL slot protocol, TTL expiry, fence refusal of older verdicts, report-path cache bypass, fence forwarding, and the status+relay_target single-proof pair) plus 1 relay test (the re-proof demonstrably carries a fence the pre-connect call does not). 473 backend tests pass across the four affected suites; black/isort/flake8/mypy and the feature-map gate green. Rebased onto current main twice during the round (zero conflicts both times). |
3f962ab to
368bc57
Compare
|
Head The gate (new on main this wave) flagged one history-narration phrase my proof-gate round added: Verified locally: the gate's own script passes against the merge base with zero violations across the full diff ( |
The Playwright CLI view server binds the gateway host's loopback, so a
remote dashboard (SSH forward, tunnel) could not frame it without
pinning dashboard.browser_view_port and forwarding a second port -- and
tunnels that publish only the dashboard port could never reach it.
Add /browser-view/{token}/{tail}: an HTTP+WebSocket reverse proxy on
the dashboard's own origin. Three server-side rewrites make the
root-absolute view SPA work under the prefix (redirect Location + ws
query param, HTML src/href, CSS url()); everything else streams
through. The view status payload gains a 'path' field the panel
prefers over the absolute loopback URL, falling back for older
gateways.
Isolation matches the old loopback origin: the panel frames the relay
WITHOUT allow-same-origin, and the relay stamps CSP 'sandbox' plus
X-Content-Type-Options: nosniff on every relayed response except
script types (a worker script's own response CSP governs the worker;
a script type never renders as a document), so relayed content gets an
opaque origin (never the dashboard's) even in a full tab and for ANY
document type a squatted or compromised upstream answers with -- HTML,
XHTML, SVG, XML, or a sniffable unknown. An opaque origin sends no
cookies, so the relay authenticates with a per-instance capability
token embedded in the path -- minted on every view-server start,
disclosed only through the cookie-authed owner-gated status payload,
constant-time compared, uniform 404 without it. Opaque-origin support:
relayed responses are CORS-open (the token gates access; CORS only
gates readability) and documents carry an in-memory storage shim, since
bare window.localStorage reads throw in a sandboxed document.
The capability stays bound to the child that minted it: relay_target()
re-proves ownership on every lookup with the supervisor's cheap
process-liveness, root-identity, and listener-ownership checks (no HTTP
probe on the per-request path). A definitive failure tears down relay
state and invalidates the token before any process can squat on the
released port; an inconclusive proof withholds the target without
destroying state so a later request can retry.
Token allow/deny decisions are SEL-audited like the sibling capability
handlers: outcome plus a fixed reason (no_token / view_down /
token_mismatch, or the upstream port on allow), never the token or the
request path/query -- both embed credentials (the path carries the
relay token, the rewritten ws param the socket token). The wire answer
stays a uniform 404; the audit is what makes probing visible. Audit
failure never breaks serving. The panel's opaque-origin sandbox applies
to the RELAY PATH ONLY: the direct-URL fallback (older gateway, no
path) keeps the regular sandbox, since it is already a foreign loopback
origin and only relayed documents carry the storage shim -- sandboxing
it opaque crashed the view SPA's boot on its bare localStorage access.
Authentication comes FIRST on the relay's request path: a tokenless
request is refused before the supervisor is consulted at all, and
relay_authorize() -- one lock hold end to end -- constant-time-compares
the candidate BEFORE running the ownership probes, so an
unauthenticated bad-token flood costs one compare, never OS-level
process/listener probe work serialized under the supervisor lock.
relay_target() stays as the trusted read behind the owner-authed
status payload. A matched token whose proof fails definitively still
tears down and invalidates (audited as ownership_unproven); the bare
/browser-view route form gets its own token_auth exact-bypass entry so
it answers the handler's uniform 404 instead of the middleware's
distinguishable 403; and the redirect branch is stamped like every
other relayed non-script response (CSP sandbox + nosniff + CORS), so
CORS-mode asset fetches survive a 302 hop and the posture claims stay
true on every branch.
The owner-authed status payload publishes url/port only for a target
the ownership proof vouched for: when relay_target() refuses (child
exited between the status read and the proof, or the proof was
inconclusive), the payload degrades to stopped with url/port/path
nulled instead of offering the stale direct url as a frameable
fallback for whatever wins the freed loopback port. The panel polls,
so a live view is re-reported on the next cycle.
Popup parity with the direct path (UX review): VIEW_SANDBOX and the
server CSP stamp both grant allow-popups — without
allow-popups-to-escape-sandbox a popup inherits the sandbox, opaque
origin included, so parity costs no isolation. The storage shim's
persistence cost is audited and documented: the view SPA stores
exactly one preference (theme), which resets per relayed load.
The ownership proof runs a second time after each upstream connection
is established, before any byte or frame is sent downstream: the child
holds its listener from startup to death, so a passing same-port
re-proof means the listener was continuously the child's across the
connect, closing the proof-to-connect race a dying child would open.
A restarted view (ok on a new port) is refused as stale. One re-proof
per established connection, never per frame; refusals answer the same
uniform 404 and carry their own stale_upstream audit reason.
Deep-review round (buluoray): the owning specs are updated in the same
commit per the repo rule — the token-auth spec's bypass inventory gains
both /browser-view route forms (the one bypass that proxies foreign
content, authed by its own capability token), and the browser spec
teaches the relay-first model, gains the relay's Security-table row,
and records the upgrade-time bundle-shape check for the rewrites. The
header allowlists are made symmetric: streamed bodies carry back
Content-Range/Accept-Ranges/ETag/Last-Modified (a 206 without
Content-Range is a protocol violation), while rewritten documents
deliberately carry no upstream validators since their bodies are
transformed. relay_authorize's lock acquisition is bounded: a
concurrent ensure_running holds the supervisor lock across its 30s
startup poll, so the pre-auth gate refuses as busy (same uniform 404,
own audit reason) within one second instead of letting a tokenless
flood park the shared thread pool for the window.
Review round (GPT 5.6 blocking + Opus 5): the token compare moves to a
lock-free snapshot ahead of the supervisor lock, so an invalid
candidate is refused without ever contending the lock or the shared
thread pool — the bounded acquire alone still let a bad-token flood
during a start window park each request for the bound. Only holders of
the current token reach the lock; state is snapshotted under one
bounded hold and the OS-level ownership probes run OUTSIDE the lock,
so concurrent asset fetches prove in parallel instead of serializing,
and a definitive failure tears down state only if it still describes
the proved instance. A busy refusal now answers a retryable 503 +
Retry-After instead of the uniform 404 — reachable only with the
current token, and a 404 on a validly-tokened asset is permanent to
the browser. The panel's liveness probe is gated off for relay paths
(same-origin: its health is the dashboard's own, and a no-cors probe
told us nothing while re-running the proofs every 5s per panel). The
feature-map row restores POST /api/browser/command-result, which the
relay rewrite had dropped, and the black baseline prunes its one
graduated entry.
The prover's per-proc evidence slot (record→take, cleared on entry)
tolerates exactly one writer: moving the probes outside the supervisor
lock made concurrent provers clobber each other's window into false
definitive failures that tore down live views. A dedicated proof gate
now serializes every prover (lock ordering _lock→gate only; the gated
prover never takes _lock, so no deadlock path), and a single-flight
verdict cache (~0.5s TTL, keyed to the exact process instance and
port, invalidated on stop/teardown) collapses one page load's probe
fan-out into one proof run — the status payload's status()+
relay_target() pair costs one proof, not two. The post-connect
re-proof carries a monotonic fence (proof_not_before) so a cached
pre-connect verdict can never vouch for a connection established
after it, and the status poll fences at entry so a squatter takeover
is detected on the very next poll, never masked by the cache.
Report-eligible startup proofs neither read nor write the cache.
Fence semantics: the proof cache stamps each verdict with the proof's
START (captured before any evidence gathering), and proof_not_before
refuses at equality — no evidence gathered before a caller's fence can
satisfy that fence, regardless of when the proof completes, and shared
clock readings on coarse-tick platforms (Windows monotonic, ~15.6ms)
refuse-and-reprove instead of serving. A refused cache falls through to
one fresh proof under the gate, valid for its caller by program order.
368bc57 to
ca9c48e
Compare
|
Head The defect: the proof-verdict cache stamped The fix ( Regression tests (3 fence tests total, all verified to fail when the fix is reverted): the pre-connect-started/post-connect-completed proof is refused via a mid-proof fence; the equal-tick case is pinned deterministically with a fake coarse clock, so the Windows failure mode now runs on every Linux run too; the original fence test keeps its cross-tick semantics. Also from an adversarial pre-review pass on this diff: the reuse-failure cleanup in Verified before pushing: 131 view + 314 relay/token_auth tests, black/isort/flake8/mypy, the black-baseline gate, and all twelve fast-gate scripts (comment-history, focus-cue, feature-map, loop-bound-locks, harness-parity, brand, vendor-manifest, changelog, builtin-skill-scope, testpaths-coverage, memory-store-seam, docs-lint) run locally against Known environment flakes not addressed here (tracked separately, unrelated to this diff): #12604 ( |
bolichen97
left a comment
There was a problem hiding this comment.
Approving after an automated readiness screen against this head:
readiness: passedlabel present and thePR Readinessrequired status is green on this head- no failing, cancelled or pending required check on this head
mergeablewith no conflict against currentmain- no live reviewer
CHANGES_REQUESTED(GitHubreviewDecisionis notCHANGES_REQUESTED) - every review-lane finding on this head is either PASS, withdrawn, disposed of by the author, or advisory-only — no unresolved blocking change request
Auto-merge (squash) is enabled; branch protection still gates the merge.
Problem / Motivation
Remote dashboards lost the live browser view. Since the browser moved from the MCP proxy to the CLI (#3233), the Browser panel iframes the
playwright-cli showview server directly athttp://127.0.0.1:<port>/— a loopback address on the gateway host, bound to an ephemeral port by default. From a remote dashboard (SSH tunnel, reverse proxy, tunnel services that publish only the dashboard port) that URL resolves to the viewer's machine, where nothing is listening. The panel shows "Preview server not reachable" and the cast is simply gone — the old WebSocket screencast this replaced worked remotely for free because frames rode the dashboard's own connection.The existing escape hatch (pin
dashboard.browser_view_port, forward a second port) requires knowing an undocumented knob, doesn't survive ephemeral-port defaults, and is impossible through single-port tunnels.Why it matters
Anyone running the gateway on a remote host — cloud desktops, dev servers, containers — has a permanently dead Browser panel today. That's a regression of a shipped capability, and "watch the agent browse" is one of the dashboard's most legible trust features.
What changed (motivation → approach → change)
Goal: make the browser view reachable wherever the dashboard itself is reachable, with zero extra configuration.
Approach: relay the view server through the dashboard's own origin, so the iframe rides whatever connection the user already has. Alternatives considered: a fixed default port (still needs a second forward, still dead through single-port tunnels) and reviving the WS screencast (~6k lines, re-implements what
playwright-cli showalready does).What was built:
src/kiro_crew/dashboard/handlers/browser_view_relay.py): reverse-proxiesGET /browser-view/{token}/{tail}(HTTP + WebSocket pump) to the loopback view server. Root-absolute paths in redirects (Location, the?ws=param), HTML (src/href) and CSS (url()) are rewritten under the prefix so the SPA works unmodified. The header allowlists are symmetric: the forwarded conditionals/Rangeget their response halves back on streamed bodies (Content-Range,Accept-Ranges,ETag,Last-Modified— a 206 withoutContent-Rangeis a protocol violation the browser discards), while rewritten documents deliberately carry no upstream validators, since the relay transforms those bodies and upstream's validators would describe bytes it did not send.secrets.token_urlsafe(24), constant-time compare, uniform 404 on any mismatch) is the sole gate, and authentication comes FIRST: a tokenless request is refused before the view supervisor is consulted at all, and the constant-time compare runs against a LOCK-FREE token snapshot before the supervisor lock is touched — an invalid candidate is refused without ever contending the lock or the shared thread pool, no matter how long a concurrent start holds that lock across its startup poll (up to 30s). Only a caller already holding the current token proceeds to the bounded lock acquisition (state is snapshotted under one hold, with the compare repeated in case the token rotated), and the OS-level ownership probes then run OUTSIDE the lock on that snapshot and are serialized inside the prover behind a dedicated proof gate with a single-flight verdict cache (~0.5s TTL, keyed to the exact process instance and port, invalidated on stop/teardown) — the prover's per-proc evidence slot tolerates exactly one writer at a time, so the gate is what keeps concurrent provers from clobbering each other's proof into a false teardown of a live view, and the cache is what keeps one page load's fan-out from spawning dozens ofps/lsofprobes (concurrent asset fetches share one proof run; the 5s status payload's two reads cost one proof, not two); a definitive proof failure tears down state only if it still describes the proved instance. A token-holding caller that lands in a start window (lock held past the bound) is refused asbusywith a retryable 503 +Retry-After— safe to distinguish from the uniform 404 precisely because only holders of the current token can reach it, and necessary because a 404 on a validly-tokened stylesheet is permanent to the browser. The proof then runs a SECOND time after each upstream connection is established, before any byte or frame goes downstream, closing the proof→connect race: the child holds its listener from startup to death, so a passing same-port re-proof means the listener was continuously the child's across the connect, and a child that died in the gap (or a restarted view answeringokon a NEW port while the held connection went to the freed old one) is refused with the same uniform 404 — the re-proof carries a monotonic fence so the verdict cache can never satisfy it with pre-connect evidence: the cache stamps each verdict with the proof's START (captured before any evidence gathering) and the fence refuses at equality, so no evidence gathered before the connect can vouch for the connection — not a proof that merely completed after it, and not one sharing the fence's clock reading on coarse-tick platforms (Windows monotonic ticks at ~15.6ms); a refused cache falls through to one fresh proof (concurrent connections may share one such proof), at most one re-proof per established connection, never per frame or chunk. The relay path joins the existing cookie-less capability-URL bypass family (/artifact-app/,/sandbox-doc/) in both route forms — the bare/browser-viewpath has its own exact-bypass entry so it gets the handler's uniform 404, not the middleware's distinguishable 403. Every relayed response except script types — redirects included, so CORS-mode asset fetches survive every hop — is stampedContent-Security-Policy: sandbox …(opaque origin, covering open-in-new-tab) plusX-Content-Type-Options: nosniff, and the panel iframe dropsallow-same-origin. The sandbox keyword set otherwise matches the direct path — includingallow-popups, which is safe here because withoutallow-popups-to-escape-sandboxa popup inherits the sandbox, opaque origin included. Because the origin is opaque, relayed responses carryAccess-Control-Allow-Origin: *(the token gates access; CORS only gates readability of what the token already granted) and a guarded in-memorylocalStorageshim is injected (barelocalStorageaccess throws in sandboxed documents and kills the SPA boot). Every token allow/deny decision is SEL-audited (outcome plus a fixed reason —no_token,busy,view_down,token_mismatch,ownership_unproven,stale_upstream:<reason>for post-connect refusals, or the allowed port; never the token or the request path/query, which embed the relay and socket tokens), so probing stays visible while the wire response stays uniform.browser_cli/view.py): mints/clears the token with the instance and exposes two accessors:relay_authorize(candidate)— the relay's per-request gate, which constant-time-compares the candidate against a lock-free token snapshot FIRST (an invalid candidate never touches the supervisor lock), then snapshots state under one bounded lock hold (refusing as retryablebusywhen a concurrent start holds it, instead of parking), and runs the ownership proof (process-liveness, root-identity, listener-ownership — no HTTP probe) OUTSIDE the lock on that snapshot — andrelay_target(), the trusted read the owner-authed status payload uses, sharing the same snapshot-then-prove contract. A definitive proof failure tears down relay state and invalidates the token before any process can squat on the released port — re-checking under the lock that the state still describes the failed instance, so a mid-proof restart is never torn down by the old instance's corpse; an inconclusive proof withholds the target without destroying state.messaging.py, typed inwebsite/src/api/client.ts): gains an optionalpathfield (/browser-view/<token>/) alongside the existingurl. Both are published only for a target the ownership proof vouched for: whenrelay_target()refuses (child died between the status read and the proof, or the proof was inconclusive), the payload degrades tostoppedwithurl/port/pathnulled rather than offering the stale directurlas a frameable fallback — the panel's next poll re-reports a live view.WebPreviewPanel.tsx): prefers the same-originpathwhen present (relative iframe src — works through any tunnel), falls back to the directurlfor old gateways; the view iframe uses a dedicated sandbox withoutallow-same-originfor the relay path only — the direct-URL fallback keeps the regular sandbox, since it is already a foreign loopback origin and only relayed documents carry the storage shim (an opaque-origin direct frame would crash the SPA boot). The shim's persistence cost was audited against the shipped view SPA bundle: it stores exactly one preference (thethemekey), which re-reads its default per relayed load — cosmetic, and inherent to the opaque origin.docs/system-specs/modules/dashboard-token-auth.md,docs/system-specs/modules/browser.md): the token-auth spec's bypass inventory gains both/browser-viewroute forms with the characterization the next auth change needs (the one bypass that proxies foreign content, authed by its own capability token); the browser spec's remote-reachability paragraph now teaches the relay-first model (direct pinned-port URL demoted to old-gateway fallback), its Security table gains the relay's full control row, and it records the upgrade-time check for the rewrites' pinned bundle-shape assumptions (open the Browser panel once on a remote dashboard after a playwright-cli upgrade).Backwards compatibility
Compatible: the status payload only gains an optional field — old frontends ignore
pathand keep usingurl; the new frontend falls back tourlwhenpathis absent, so mixed gateway/frontend versions keep today's behavior.Tests
test/test_browser_view_relay.py(new, 31 tests): token auth (wrong/missing token → uniform 404, constant-time compare), redirect +?ws=rewrite carrying the token, HTML/CSS path rewrites, CSP sandbox stamped on every non-script type (HTML, SVG, XHTML, unknown) and absent on script types,nosniffeverywhere,Access-Control-Allow-Origin, storage-shim injection, upstream-down →browser_view_unreachable, WebSocket pump round-trip, SEL auditing of both token outcomes (all four deny reasons recorded, token never logged, audit failure never breaks serving), the stamp on the redirect hop, a tokenless request never reaching the supervisor, abusyrefusal (supervisor lock held by a start) answering a retryable 503 +Retry-Afterwith its own audit reason — at the pre-connect gate and at the post-connect re-proof alike, both reachable only with the current token — streamed bodies carrying backContent-Range/Accept-Ranges/ETag/Last-Modifiedwhile rewritten documents never carry upstream validators, and the status payload degrading tostopped(never publishing the staleurl) when the ownership proof refuses the target. The post-connect re-proof is pinned end to end: exactly two proofs per happy-path connection, the re-proof demonstrably carrying a monotonic fence the pre-connect call does not (so a cached pre-connect verdict can never vouch for the established connection), a failed or inconclusive re-proof answers the uniform 404 with nothing streamed (redirect branch included), same-ok-different-port is refused as stale, the WebSocket bridge closes before the first frame, and post-connect denials carry their ownstale_upstream:*audit reason (314 backend tests pass together).test/test_browser_cli_view.py: 21 new tests — dead-child lookup invalidates the token (a squatter on the freed port gets nothing), inconclusive ownership preserves state for retry, proven ownership returns the pair without an HTTP probe, and therelay_authorizegate contract: a mismatched token never triggers the probes, nothing-recorded answers without probing, probes run only after a match, a matched token with a dead child tears down and invalidates, inconclusive proof preserves state, the lock acquire is bounded — a held supervisor lock refuses the RIGHT token asbusywithin its bound instead of parking, with recorded state untouched — invalid candidates are refused instantly while the lock is held (never paying the bound: the lock-free pre-check is what keeps a flood off the shared pool), the ownership probes demonstrably run with the supervisor lock RELEASED (forrelay_authorizeandrelay_targetalike), and a definitive failure whose instance was replaced mid-proof spares the replacement's recorded state. The prover's concurrency contract is pinned directly: two concurrent provers serialize behind the proof gate with the waiter consuming the leader's cached verdict (never proving twice), eight parallelrelay_authorizecalls through the REAL record→take slot protocol all authorize with state intact (the clobber regression), verdicts are cached within the TTL and re-proved after it, aproof_not_beforefence refuses any cached proof not started strictly after the caller's fence — including a proof sharing the fence's own clock reading (the Windows coarse-tick case, pinned deterministically) and a proof started before the fence that merely completed after it (start-stamp semantics, pinned with a mid-proof fence) — report-eligible startup proofs neither write nor consume the cache,relay_authorizeforwards the fence to the prover, andstatus()followed byrelay_target()— the payload's poll pair — costs exactly one proof run.test_token_auth.py:/browser-view/added to the capability-bypass and SPA-fallback-exclusion contracts, plus the bare/browser-viewexact-bypass entry with a behavioral test that every relay route form passes the middleware .website/src/test/WebPreviewPanel.test.tsx): relay-path preference, malformed-path rejection (falls back tourl), the view iframe's no-allow-same-originsandbox for relay paths (withallow-popupspresent and the escape variant forbidden), the direct-URL fallback keepingallow-same-origin(it never gets the relay shim), and the liveness probe never firing against a relay path — it is same-origin, so a no-cors probe answers opaque while costing the relay's ownership proofs every 5s per open panel — with the direct-URL fallback still probed (the positive control); existing tests pin the no-pathfallback unchanged (126 panel tests pass).Manual verification
Live smoke with the real handler mounted in front of a real
playwright-cli show:wsparam and is itself stamped (CSP sandbox +nosniff+Access-Control-Allow-Originon the 302, full-tab render through it boots clean);playwright-logo.svg(scriptable type) carries the sandbox CSP +nosniffwhile the JS bundle is CSP-exempt withnosniff.playwright-clisession's cast streams through the relay — screenshots below.Screenshots / video
Session list arriving over the relayed WebSocket at
/browser-view/<token>/:Live cast of a real browser session (page frames streaming through the relay, CSP-sandboxed):
Related Issues
No linked issue: this fixes a regression introduced by the browser-to-CLI move in #3233 — the WebSocket screencast that change removed was remote-transparent, and no tracking issue exists for the loss.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)