Skip to content

feat(dashboard): serve the browser view through a same-origin relay - #12229

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
rkeely:feat/browser-view-relay
Sep 24, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
rkeely:feat/browser-view-relay

Conversation

@rkeely

@rkeely rkeely commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

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 show view server directly at http://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 show already does).

What was built:

  • Backend relay (src/kiro_crew/dashboard/handlers/browser_view_relay.py): reverse-proxies GET /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/Range get their response halves back on streamed bodies (Content-Range, Accept-Ranges, ETag, Last-Modified — a 206 without Content-Range is 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.
  • Capability-token security model. The relayed SPA would otherwise execute on the dashboard's origin — a widening the old foreign-origin iframe never allowed. So: a per-view-server-instance capability token (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 of ps/lsof probes (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 as busy with 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 answering ok on 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-view path 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 stamped Content-Security-Policy: sandbox … (opaque origin, covering open-in-new-tab) plus X-Content-Type-Options: nosniff, and the panel iframe drops allow-same-origin. The sandbox keyword set otherwise matches the direct path — including allow-popups, which is safe here because without allow-popups-to-escape-sandbox a popup inherits the sandbox, opaque origin included. Because the origin is opaque, relayed responses carry Access-Control-Allow-Origin: * (the token gates access; CORS only gates readability of what the token already granted) and a guarded in-memory localStorage shim is injected (bare localStorage access 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.
  • View server (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 retryable busy when 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 — and relay_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.
  • Status payload (messaging.py, typed in website/src/api/client.ts): gains an optional path field (/browser-view/<token>/) alongside the existing url. Both are published only for a target the ownership proof vouched for: when relay_target() refuses (child died between the status read and the proof, or the proof was inconclusive), the payload degrades to stopped with url/port/path nulled rather than offering the stale direct url as a frameable fallback — the panel's next poll re-reports a live view.
  • Panel (WebPreviewPanel.tsx): prefers the same-origin path when present (relative iframe src — works through any tunnel), falls back to the direct url for old gateways; the view iframe uses a dedicated sandbox without allow-same-origin for 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 (the theme key), which re-reads its default per relayed load — cosmetic, and inherent to the opaque origin.
  • Owning specs (docs/system-specs/modules/dashboard-token-auth.md, docs/system-specs/modules/browser.md): the token-auth spec's bypass inventory gains both /browser-view route 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 path and keep using url; the new frontend falls back to url when path is 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, nosniff everywhere, 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, a busy refusal (supervisor lock held by a start) answering a retryable 503 + Retry-After with 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 back Content-Range/Accept-Ranges/ETag/Last-Modified while rewritten documents never carry upstream validators, and the status payload degrading to stopped (never publishing the stale url) 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 own stale_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 the relay_authorize gate 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 as busy within 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 (for relay_authorize and relay_target alike), 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 parallel relay_authorize calls 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, a proof_not_before fence 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_authorize forwards the fence to the prover, and status() followed by relay_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-view exact-bypass entry with a behavioral test that every relay route form passes the middleware .
  • Frontend (website/src/test/WebPreviewPanel.test.tsx): relay-path preference, malformed-path rejection (falls back to url), the view iframe's no-allow-same-origin sandbox for relay paths (with allow-popups present and the escape variant forbidden), the direct-URL fallback keeping allow-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-path fallback unchanged (126 panel tests pass).

Manual verification

Live smoke with the real handler mounted in front of a real playwright-cli show:

  • Wire: wrong token → 404 with no existence leak; tokened root redirect carries the token through the ws param and is itself stamped (CSP sandbox + nosniff + Access-Control-Allow-Origin on the 302, full-tab render through it boots clean); playwright-logo.svg (scriptable type) carries the sandbox CSP + nosniff while the JS bundle is CSP-exempt with nosniff.
  • Full-tab headless render of the relayed URL (the exact escape scenario the sandbox defends): SPA boots with zero console errors and zero blocked requests under the opaque origin.
  • End-to-end: a live playwright-cli session's cast streams through the relay — screenshots below.

Screenshots / video

Session list arriving over the relayed WebSocket at /browser-view/<token>/:

Session list through the same-origin relay

Live cast of a real browser session (page frames streaming through the relay, CSP-sandboxed):

Live cast through the same-origin relay

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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@rkeely
rkeely requested review from a team and buluoray September 20, 2026 07:11
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 20, 2026
@rkeely

rkeely commented Sep 20, 2026

Copy link
Copy Markdown
Contributor Author

Intent: Restore the dashboard's live browser view for remote and tunneled dashboards by relaying the playwright-cli show view server through the dashboard's own origin (/browser-view/<token>/…), gated by a per-instance capability token and confined to an opaque origin so relayed content can never act on the dashboard.
Not a goal: Changing how the view server is launched or works, reviving the removed WebSocket screencast, or altering the local direct-URL path — which remains as the fallback for old gateways.

@rkeely

rkeely commented Sep 20, 2026

Copy link
Copy Markdown
Contributor Author

Maintainer re-run requested — all code lanes are green on a28034e2d (96 checks, 0 running, 0 findings). The remaining reds all failed inside the 2026-09-20 07:20–07:23 UTC GitHub App rate-limit window, before producing any verdict:

  • GPT 5.6 Review / Opus 4.8 Review / Internal Content Scan — check-run output reads "could not run — re-run it"
  • Screenshot Evidence — 403 reading the PR body (its own log: "a read failure, not missing evidence — re-run this job")
  • Resolve desktop matrix — died at 18s in the same window, cascading into Security Scope adjudication ("no leg reported")

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!

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 20, 2026
@rkeely
rkeely force-pushed the feat/browser-view-relay branch from a28034e to c4a695f Compare September 20, 2026 21:33
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 20, 2026
@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed ca9c48e3113fe38476ddf972d54d210e5d19b7c0 via the fork AI-review pipeline; updated in place on each push.

Review details

No 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 async for chunk in upstream.content.iter_chunked(...) / await response.write(chunk) sits under the function-level except (aiohttp.ClientError, OSError), so a mid-body upstream reset or client disconnect returns _bad_gateway("browser_view_unreachable", ...) for a request whose 200, headers and first bytes are already on the wire — aiohttp raises on the second response for an already-prepared request and the connection dies with a truncated body and a logged handler error instead of a clean partial → Fix: wrap the chunk loop in its own try, and on (aiohttp.ClientError, OSError) return response (already prepared) rather than falling through, leaving _bad_gateway for pre-prepare() failures only — the sibling streaming proxy at handlers_instances.py:1940 uses exactly this shape.

[OPUS-REVIEWED] ca9c48e

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — 🟡 CONCERNS

Premise-level review of ca9c48e3113fe38476ddf972d54d210e5d19b7c0 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

  • Item 2 — inherited: the rewrites are "pinned to the current playwright-cli bundle shape (double-quoted src/href attributes, url(/…) in CSS, the '/' + ws socket-URL construction)" — a claim about a vendored tool's bundle the tests exercise only against fixture HTML, while the panel prefers the relay unconditionally, so a wrong or drifted premise regresses local dashboards that were fine on the direct URL; the spec's own words: an upstream bundle-shape change "would silently restore the direct-URL breakage this path exists to fix."
    Clears when: the view SPA is confirmed to boot through the relay against the shipped playwright-cli bundle, naming the version confirmed on.

What this change ships

Inventory (10 items) — 9 justified

Intent: 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).

  1. Browser panel works from a remote dashboard again, framed via /browser-view/<token>/ — justified
  2. Relay preferred everywhere, including local dashboards, via rewrites pinned to the CLI bundle shape — inherited (unverified vendored-bundle premise)
  3. New tokenless bypass prefix /browser-view/ (+ bare exact entry), self-authenticated by a per-instance capability token — justified
  4. /api/browser/view payload gains path; whole payload degrades to stopped on a refused ownership proof — justified
  5. Relayed view runs in an opaque-origin sandbox; responses stamped CSP sandbox/nosniff/ACAO:* — justified
  6. Relayed view no longer persists its theme (in-memory storage shim) — justified
  7. Token-holding requests during a view start get a retryable 503 instead of hanging — justified
  8. Ownership proofs single-flighted/cached and re-run post-connect before any byte flows — justified
  9. Every relay allow/deny SEL-audited — justified
  10. Browser, token-auth and feature-map docs updated same-commit — justified

[FIRST-PRINCIPLES-REVIEWED] ca9c48e

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of ca9c48e3113fe38476ddf972d54d210e5d19b7c0 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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.

Watch

The rewrites are string-pinned to the current bundle shape (double-quoted src/href, url(/, the '/' + ws construction), and the spec itself admits "an upstream bundle-shape change would silently restore the direct-URL breakage this path exists to fix." Because WebPreviewPanel.tsx prefers path whenever the gateway publishes one and exempts relay paths from the liveness probe, a shape drift blanks the Browser panel for local and remote dashboards with no ErrorNotice — the in-product failure explanation the direct path had. The documented "open the panel once after upgrading" check is the whole detection story.
Clears when: the relay detects a zero-match rewrite (e.g. an index.html producing no src="/ replacements, or a root redirect missing the ws param) and surfaces it through the status payload so the panel can show an error or fall back to the direct URL, instead of relying on a human to remember the doc sentence.

Suggestions

  • The zero-match rewrite check above is cheap (the rewrite functions already know whether they replaced anything) and would convert the accepted silent residual into an observable one without touching the security model.

[DESIGN-REVIEWED] ca9c48e

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed ca9c48e3113fe38476ddf972d54d210e5d19b7c0 via the fork AI-review pipeline; updated in place on each push.

Review details

FINDING -- src/kiro_crew/dashboard/handlers/browser_view_relay.py:539 -- "asyncio.to_thread" sends invalid-token requests through the shared pool, contradicting the stated no-contention contract -> Fix: remove that claim.
[GPT-REVIEWED] ca9c48e

@rkeely
rkeely force-pushed the feat/browser-view-relay branch from c4a695f to 4b69853 Compare September 20, 2026 22:19
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 20, 2026
@rkeely

rkeely commented Sep 20, 2026

Copy link
Copy Markdown
Contributor Author

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).

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 20, 2026
@rkeely
rkeely force-pushed the feat/browser-view-relay branch from 4b69853 to 00fad31 Compare September 21, 2026 07:08
@rkeely

rkeely commented Sep 21, 2026

Copy link
Copy Markdown
Contributor Author

Pushed 00fad31 addressing both blocking findings from the GPT 5.6 lane on 4b69853:

  1. SEL auditing of token decisions (browser_view_relay.py): every allow/deny now emits a SEL record mirroring the sibling capability handlers (sandbox_doc, artifacts) — outcome plus a fixed reason (no_token / view_down / token_mismatch, or port:<n> on allow). Never the token, and deliberately never the request path/query either: both embed credentials here (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. Four new tests cover all three deny reasons, the allow record, token-never-logged, and the best-effort property.

  2. Direct-URL fallback sandbox (WebPreviewPanel.tsx): the opaque-origin VIEW_SANDBOX now applies to the relay path only. The no-path fallback keeps the regular sandbox — it is already a foreign loopback origin (allow-same-origin grants only itself), and only relayed documents carry the localStorage shim, so an opaque-origin direct frame crashed the view SPA's boot exactly as the finding described. New test pins the fallback's sandbox; the existing relay-path test pins the opaque one.

Also rebased onto current main. 295 backend tests (relay + token_auth) and 130 panel tests pass; black/isort/flake8/mypy/tsc/eslint clean.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 21, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_token reads raw_path, guarantees the suffix starts with /, and joins it onto a fixed http://127.0.0.1:<port> authority, so //evil.com/x stays 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_token before 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_digest against 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_path keeps 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_HEADERS is Accept, Accept-Language, If-None-Match, If-Modified-Since, Range. No Cookie, no Authorization.
  • _rewrite_location fails 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/ to token_auth._BYPASS_PREFIXES is 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.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 21, 2026
@buluoray

Copy link
Copy Markdown
Contributor

Ran the maintainer re-run you asked for — re-ran Fast Gate on 00fad310 (attempt 3), which re-fired all the workflow_run-triggered fork lanes. The result is identical, and it is not a rate-limit window. It is deterministic, it has nothing to do with your diff, and re-running will never clear it.

All four Claude-backed fork lanes die in the same place, before the model is ever reached:

Installing Claude Code v2.1.263...
Installation attempt 1...
curl: (7) Failed to connect to claude.ai port 443 after 1 ms: Couldn't connect to server
Installation attempt 2...
curl: (7) Failed to connect to claude.ai port 443 after 1 ms
Installation attempt 3...
curl: (7) Failed to connect to claude.ai port 443 after 1 ms
##[error]Action failed with error: Failed to install Claude Code after 3 attempts: Error: Install failed with exit code 7

Fork Opus 4.8 Review (run 35630217875) and Fork Design Review (run 35630217918) both fail on that exact line, and First Principles and UX report the same "could not complete". The bun install from registry.npmjs.org right above it succeeds, so npm reachability is fine — it is specifically the Claude Code installer's own fetch.

The cause is a gap in the egress allowlist, not in your change. The fork lanes run step-security/harden-runner with egress-policy: block, and claude.ai:443 is not in allowed-endpoints in fork-opus-review.yml, fork-design-review.yml, fork-first-principles-review.yml, fork-ux-review.yml or fork-security-scope-review.yml. The same-repo lanes (claude-review.yml, design-review.yml, …) carry no harden-runner step at all, which is why the same reviewers work on a branch in this repository and fail on every fork. fork-gpt-review.yml is unaffected — different provider path, no claude.ai fetch — which matches GPT being the one lane that produced a verdict.

So this is repository-wide: no fork pull request can currently get an Opus verdict or any Fable advisory verdict. The fix is adding claude.ai:443 to those five allowlists; until it lands there is nothing for you to re-request.

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:

  1. The GPT finding is still live at this head and in three places, not one: browser_view_relay.py:50, the constant comment at :90, and _stamp_relay_headers's docstring at :300 all claim the stamp goes on every relayed response except script types, while the redirect branch returns a bare Location with no CSP, no nosniff and no Access-Control-Allow-Origin.
  2. Stamping the redirect the same way as everything else fixes both that claim and a real corner: 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.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@rkeely
rkeely force-pushed the feat/browser-view-relay branch from 4f6b0cd to e58193b Compare September 23, 2026 21:22
@rkeely

rkeely commented Sep 23, 2026

Copy link
Copy Markdown
Contributor Author

Pushed e58193b addressing this wave's findings — the GPT 5.6 blocking finding, both Opus 5 findings (blocking + non-blocking), and the lint gate:

  1. Lock-free token pre-check (GPT 5.6, blocking — view.py): the candidate is now compared against a lock-free token snapshot BEFORE the supervisor lock is touched. An invalid candidate is refused right there — one compare_digest, no lock contention, no bounded wait — so a bad-token flood during a start window can no longer park the shared executor at 1s per request. Only holders of the current token proceed to the bounded acquire, where the compare is repeated under the lock (rotation guard) and state is snapshotted from one hold. Regression test pins the decisive behavior: invalid candidates answer instantly while the lock is held, for both the recorded-token and first-start (nothing recorded) windows.

  2. Feature-map row restored (Opus 5, blocking): POST /api/browser/command-result is back in the Browser panel row — the relay rewrite had replaced it instead of adding alongside. Feature-map gate green against main.

  3. Probes outside the lock + retryable busy (Opus 5, non-blocking): the OS-level ownership probes now run OUTSIDE the supervisor lock on a consistent snapshot (relay_authorize and relay_target share the contract), so concurrent SPA asset fetches prove in parallel instead of serializing behind one request's lsof — a definitive failure tears down state only if it still describes the proved instance, so a mid-proof restart is never killed by the old instance's corpse (tested). And busy now answers a retryable 503 + Retry-After at both the pre-connect gate and the post-connect re-proof, instead of the permanent 404 that stranded validly-tokened assets: safe to distinguish precisely because the lock-free pre-check means only holders of the current token can reach busy. The WS branch already closed with TRY_AGAIN_LATER. Owning specs updated in the same commit (browser.md Security row; the token-auth spec's claims remain true as written).

  4. Panel probe gated off for relay paths (Opus 5, non-blocking): useLivenessProbe no longer fires for a relay path — same-origin, so its health is the dashboard's own, and the no-cors probe answered opaque while re-running both proofs every 5s per open panel. This makes the browser.md sentence ("the relay path never gets that probe") true in code. Test covers both directions: no probe against /browser-view/…, direct-URL fallback still probed (positive control).

  5. Backend Lint: pruned the one graduated entry (test/test_knowledge.py, black-clean via main) from the black baseline — the ratchet gate demanded it.

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.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 23, 2026
@rkeely
rkeely force-pushed the feat/browser-view-relay branch from e58193b to 3f962ab Compare September 24, 2026 01:38
@rkeely

rkeely commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

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 _port_owner entry) tolerates exactly one prover, and moving the probes outside the supervisor lock broke that invariant — parallel asset fetches plus the 5s poll could interleave, read a live child as a definitive False, and tear the view down (worst case reaping the live headed browser via the _recorded_state misread). Fix: a dedicated module-level proof gate inside _verify_child_listener — every prover passes through it, restoring single-writer semantics for the slot. Lock ordering is _lock → gate only (the gated prover never acquires _lock; teardown runs after the gate is released), so no deadlock path exists.

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 status() + relay_target() (the payload pair) cost one proof, not two.

The bracket invariant survives the cache. The post-connect re-proof now carries a monotonic fence (proof_not_before, captured after the connect): the cache can never satisfy it with pre-connect evidence, so every established connection is still vouched for by a proof completed AFTER its connect — concurrent connections may share one such proof, which is the single-flight benefit without reopening the proof→connect race. The status poll fences at entry too, so a squatter takeover is detected on the very next poll rather than masked for a TTL. Report-eligible startup proofs neither read nor write the cache (stdout reports stay startup-only evidence).

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).

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 24, 2026
@rkeely
rkeely force-pushed the feat/browser-view-relay branch from 3f962ab to 368bc57 Compare September 24, 2026 02:21
@rkeely

rkeely commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

Head 368bc57f6 — docstring-only fix for the Comment History Gate.

The gate (new on main this wave) flagged one history-narration phrase my proof-gate round added: view.py:1122 said the proof gate was "restoring the invariant the under-_lock callers used to get implicitly." Rewritten in present tense — the invariant now reads as what holds today ("exactly one writer at a time — the invariant holds for provers running outside _lock, not only under it"). No code change.

Verified locally: the gate's own script passes against the merge base with zero violations across the full diff (COMMENT_HISTORY_BASE_REF=<merge-base> python3 scripts/check_comment_history.py), and black/isort/flake8/mypy plus the 129-test view suite stay green. The Await Fast Gate / Coverage Gate fails on the previous head were cascades of this one gate — the test wave never ran there; this push triggers the full wave.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 24, 2026
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.
@rkeely
rkeely force-pushed the feat/browser-view-relay branch from 368bc57 to ca9c48e Compare September 24, 2026 04:22
@rkeely

rkeely commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

Head ca9c48e31 fixes the GPT 5.6 blocking finding and the Windows shard-5 failures — which turned out to be the same defect, confirmed by fixing both with one change.

The defect: the proof-verdict cache stamped time.monotonic() at proof completion, and the proof_not_before fence accepted at equality. Two consequences: (1) a proof whose ps/lsof evidence was gathered before a connect could satisfy that connect's post-connect fence merely by completing after it — pre-connect evidence blessing a post-connect fence (the review finding); (2) on Windows, where monotonic() ticks at ~15.6ms, a status poll's entry fence landing on the same tick as the prior proof's stamp was served the stale verdict instead of re-proving — which is exactly what the two shard-5 tests (test_two_status_calls_run_one_self_test_after_the_target_probe, test_status_does_not_report_a_squatter_as_running) assert against, and why they failed only on Windows CI.

The fix (src/kiro_crew/browser_cli/view.py): the cache stamps each verdict with the proof's start (captured before any evidence gathering — the stamp now bounds the age of the oldest evidence in the verdict), and the fence comparison is strict (when <= not_before refuses). Refusal never loops: a refused cache falls through to one fresh proof under the gate, which satisfies its caller's fence by program order (the fence is captured before the call begins). Cost: a same-tick-but-physically-later verdict occasionally re-proves — rare, cheap, fail-safe.

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 ensure_running now clears the verdict cache explicitly (the identity key already made inheritance impossible; cleared so all three instance-replacement sites drop it uniformly), and a stale "at entry" comment in _recorded_state now states where its fence is actually captured.

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 origin/main. Rebased onto current main twice during the round; PR body updated.

Known environment flakes not addressed here (tracked separately, unrelated to this diff): #12604 (TerminateProcess race, Backend Tests Windows) and the E2E Gateway Boot (windows) process-tree cleanup — if either appears on this head, it needs a re-run, not a change.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 24, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving after an automated readiness screen against this head:

  • readiness: passed label present and the PR Readiness required status is green on this head
  • no failing, cancelled or pending required check on this head
  • mergeable with no conflict against current main
  • no live reviewer CHANGES_REQUESTED (GitHub reviewDecision is not CHANGES_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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants