Repository navigation
feat(apps): serve app web origins over the dashboard connection - #36967
Conversation
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own. This adds an opt-in per-app site, .apps.localhost:, which the gateway relays to the app's backend. I found no blocking defect. The new middleware runs ahead of the Host barrier and token auth, so its own checks are the boundary, and they hold: a request on the Session Manager listener (caught by socket port), a relayed request, a proxied or forwarded request, a non-loopback peer and the Unix socket are all refused before any backend lookup. What gets through is a direct local request or an ssh -L forward, which gives no more access than the backend's own loopback port does today. No credential, X-KiroCrew-* header or dashboard cookie is forwarded, nothing is signed, and response cookies and CSP are hardened. The CSRF allowlist does not gain the new origin. Opt-in, enabled and running are checked again on every request. The audit-500 finding from the earlier GPT review is fixed, and tests cover the security-relevant paths. The remaining notes are a design caveat about cross-app SameSite cookies, slight over-claiming in the description, and CI jobs that were still running at review time. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
ca446e2 to
c7c2852
Compare
|
|
|
c7c2852 to
e5e11ff
Compare
|
Opus 5.5 finding on
The same push, from local review before it, also:
Rebased onto |
UX Review (Opus 5.5, fork) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. The diff adds no dashboard control, label or state. The new pieces are a backend relay, a manifest key and an App SDK function ( [UX-REVIEWED] 443dac6 Description read[DESCRIPTION-READ] 36ee0236626208101b66552cb48fa7ab75791640501bd0bde67c9daec414e003 That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: this is a generic App Kit seam aimed at a real failure (a blank frame over one Notes
[DESIGN-REVIEWED] 443dac6 Description read[DESCRIPTION-READ] fb3a2de9da7728e3d27ecdd260a063376af99f2891446804f18ddce90646adfa That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing here blocks. The new public surface has no consumer in this repo, and none can be counted here, since apps ship from outside core and the description names none. The Notes
What this change shipsInventory (10 items) — 8 justifiedIntent: let an app that frames its own backend's pages work when the dashboard is reached over one
[FIRST-PRINCIPLES-REVIEWED] 443dac6 Description read[DESCRIPTION-READ] 6e7a7b48ca9eea98872e54ff75656c0ce7115457d68a3b35e7478d3c71cf20a8 That sha256 names the PR description this verdict read. Recompute it with |
e5e11ff to
83165b2
Compare
|
Thanks for re-running shard 7, Bolin. It failed again on the same known flake, |
2a60c5a to
4294519
Compare
4294519 to
251fc9f
Compare
|
Opus 5.5 finding on
I also read the rest of the module for other APIs newer than 3.9: GPT 6.1 Review on |
251fc9f to
635dcf0
Compare
An app that frames its own backend's pages had to point the frame at the backend's loopback port. The browser resolves that on its own machine, so a dashboard reached through one ssh -L forward showed a blank frame: the port only exists on the gateway's host. An app can now set backend.webOrigin: true. The gateway serves its backend at http://<app>.apps.localhost:<dashboard port>, routed by Host on the dashboard's own listener, HTTP and WebSocket. A *.localhost name resolves to the browser's own loopback, so the frame rides whatever carries the dashboard, and it is a different site from the dashboard, so no dashboard cookie or script reaches it. Only direct local requests on a dashboard port are served, and only for an enabled, opted-in, running app. The gateway forwards no credential of its own and signs nothing there, and the response may set only host-only cookies, cannot clear site data, and may be framed only by the dashboard. The dashboard CSP admits the names in frame-src and connect-src; the CSRF allowlist does not. appWebOrigin(name) on the App SDK (seam level 8) gives an app its origin, or null where none is served.
635dcf0 to
443dac6
Compare
|
GPT 6.1 finding on
Local: the app web origin, security header, composition contract, SSM trust site and routes facade suites (177), |
|
This adds a new concept, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here. To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/). The review found no blocking defect on this head. The change adds a new path that serves app backends before dashboard token auth and adds sources to the dashboard CSP. A maintainer decides whether to accept that. For the security review: SSM listener, relayed, proxied and forwarded requests, non-loopback peers, and ports the dashboard does not serve all get 421 before any backend lookup. The backend target is fixed to 127.0.0.1. Dashboard cookies, X-KiroCrew-* headers and relay headers are stripped through the API proxy's own strip list, and a subset test pins that. Cookie Domain is removed from responses. frame-ancestors is replaced in each CSP policy, and every other directive is kept. The CSRF allowlist does not gain the new origin. The new tests use bound waits and port 0. Optional:
|
bolichen97
left a comment
There was a problem hiding this comment.
Thanks for this. The design reads well: the router sits inside the deny-audit boundary and ahead of the Host barrier, it refuses Session Manager listener requests by socket, it drops every gateway credential and X-KiroCrew-* header, it strips Domain from cookies, and it replaces only frame-ancestors in the backend's CSP. Nothing that main serves today is refused by this change, and the feature is off unless a manifest sets backend.webOrigin: true. I read the whole diff at 443dac6, including the tests and the SDK files. All 96 checks are green.
One blocking point: the PR adds new regex matching in product code, and the project does not take regex based parsing or validation in product code.
apps/app_web_origin.py:_LABEL_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"), used byparse_app_host.website/src/app-sdk/webOrigin.ts:LABEL_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/, used byappWebOrigin.
Suggested replacements:
- Gateway: main already has the single app name contract,
app_name_errorinapps/manifest_names.py. A label could be accepted whenlen(label) <= 63 and app_name_error(label) is None, which also keeps this door in line with every other door that admits an app name. If you want the check to stay local, a plain character test works too: non empty, at most 63 characters, every character instring.ascii_lowercase + string.digits + "-", and the first and last character not-. - SDK: the same plain test, for example
name.length >= 1 && name.length <= 63 && [...name].every((c) => ALLOWED.has(c)) && !name.startsWith('-') && !name.endsWith('-'), withALLOWEDaSetof the lowercase letters, digits and-.
The existing test_parse_app_host cases and the webOrigin.test.ts refusal cases (a.b, -x, x-, 64 characters, a_b, Docs) already pin the behaviour, so they show whichever replacement you pick keeps it.
Happy to approve once both patterns are replaced.
Problem / Motivation
Goal: An app that frames its own backend's pages works when the dashboard is opened from another machine over a single forward of the dashboard port.
An app whose UI embeds its backend's web pages (for example a local reverse proxy in front of a third-party editor) has to point its frame at
http://127.0.0.1:<backend port>. The browser resolves that address on its own machine. When the gateway runs on a remote desktop and the dashboard is opened from a laptop throughssh -L <port>:localhost:<port>, everything that goes through the dashboard works, but the frame dials a port on the laptop where nothing listens, and the pane stays blank. The only workaround is a second forward per app, which breaks whenever anautoport changes and collides with the same app on the laptop.Why it matters
Running the gateway on a remote dev machine and the browser or desktop app on a laptop is a common setup. Today, any app that frames a page of its own is unusable there, with no error explaining why.
Not a goal
/apps/<app>/api/proxy, its signing, or frame-backed contribution points.What changed (motivation → approach → change)
The frame needs an origin the browser can reach over the dashboard's own connection, but it cannot share the dashboard's origin: the framed page may be a third party's scripts, and on the dashboard's origin they could read its page and credentials.
So the gateway gives each opted-in app its own site on the dashboard's port:
http://<app>.apps.localhost:<dashboard port>. Browsers resolve every*.localhostname to their own loopback, so that name rides the same forward as the dashboard, and the gateway tells it apart byHost.localhostis not a public suffix, so the name is a different site: the dashboard's host-only cookies are never sent to it.backend.webOrigin: truein the manifest (src/kiro_crew/apps/manifest_sections.py,src/kiro_crew/apps/manifest.py), parsed likesignedPrincipal. Names over 63 characters are refused, because the name becomes a DNS label.src/kiro_crew/apps/app_web_origin.py, placed bysrc/kiro_crew/dashboard/server_runtime/middleware_chain.py) sits just inside the deny-audit boundary, ahead of the host canonicalization and theHostbarrier. AHostunder.apps.localhostnever reaches a dashboard layer. It is served only to a direct local request, on a port the dashboard's own loopback origins name, for an installed, enabled, opted-in app with a running backend. A request that arrives on the Session Manager listener is refused before any backend lookup. Anything else gets 421 or 404. HTTP and WebSocket are relayed, with streaming and an idle bound, and a WebSocket message is capped at 64 MiB. Each serve and each refusal is written to the security event log.Authorization, the internal-auth headers, relay headers, everyX-KiroCrew-*header and the dashboard's own cookies are dropped. The request is not signed: a backend trusts the proxy signature as proof the API proxy forwarded a call, and a framed third-party page must not be able to produce one.Clear-Site-Dataare dropped,Set-CookielosesDomain, and each comma-separated CSP policy loses only itsframe-ancestors, replaced by one policy naming the dashboard's loopback origins.http://*.apps.localhost:*is added to the CSPframe-srcandconnect-src(src/kiro_crew/dashboard/server_runtime/security_headers.py). The CSRF allowlist does not gain it.appWebOrigin(name)on the App SDK, seam level 8 (src/kiro_crew/apps/app_sdk_level.pyand its website mirror). It returns the origin when the dashboard is onlocalhost,127.0.0.1orkirocrew.localhostover http, andnullotherwise (including[::1], whichframe-ancestorscannot name), so an app keeps its old frame there and on older hosts.Considered and not taken: serving the app under a path on the dashboard origin, which shares the dashboard's origin; a capability path in an opaque sandbox, which gives no cookies or storage; a second listener per app, which needs another forward; and forwarding app ports automatically, which misses a manual
ssh -Land breaks when ports change.Backwards compatibility
Compatible: the manifest key is additive and ignored by older gateways, apps that do not opt in see no change, and a
Hostunder.apps.localhostwas refused by theHostbarrier before this change.Removes nothing: no route, key, header or accepted input that main serves today is removed or narrowed; the only change on existing responses is one more source in the dashboard CSP's
frame-srcandconnect-src.Tests
test/test_app_web_origin.py, run through the real middleware in front of a real loopback backend:Authorization, forged proxy, principal and relay headers;Domain,Clear-Site-Data,frame-ancestors);http://*.apps.localhost:*as its wildcard name.website/src/app-sdk/webOrigin.test.ts:appWebOriginonlocalhost,127.0.0.1andkirocrew.localhost, with the browser's port kept, andnullfor[::1], Remote Crew pane names, published hosts, https and malformed app names.test/test_app_web_origin.pypassed 5 runs at-n 4(64/64 each time), and its WebSocket, close-code, audit and Session Manager tests passed 20 repeats at-n0.Proof: not provable -- other: feature PR; the new tests fail on main because the module and manifest key do not exist there
Manual verification
This was checked end to end in headless Chromium on Linux. The real middleware and the real dashboard CSP ran in front of a real app backend: a local reverse proxy to a stub third-party site, with HTTP, a save endpoint and a WebSocket. The browser could reach the gateway only through a raw TCP forwarder standing in for
ssh -L. Through the app origin, the framed page rendered, picked up the dashboard theme, saved an edit, held a live WebSocket, and followed a link to another page. The browser sent the app host only the app's own cookie and never the dashboard cookie. A POST from the app origin to a dashboard API was refused, while the dashboard's own POST was accepted. The same checks passed without the forwarder. WithappWebOriginabsent, as on an older host, the app fell back to its loopback frame. On the same setup: a request on a Session Manager listener (a second listener on the same runner) got 421 for HTTP and WebSocket; a 5 MiB WebSocket message reached the stub site, while one over 64 MiB closed the relay with 1009 and never reached it; and every served request left onegrantedrow in the security event log.Not verified: Safari or WebKit (the local WebKit build would not start), Firefox, and the desktop app shell.
Screenshots / video
Why no screenshot: the only frontend change is a new SDK function with no rendered surface; the dashboard looks identical.
Related Issues
Closes #36965
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)