Repository navigation
feat(apps): let an enabled, trusted app declare the https origins its pages frame - #37157
Conversation
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing blocks. The blind reader understood every primary control: "Approve new permissions", "Reload page" and "Open app details". Both notices say what happened and offer the fix. Notes
[UX-REVIEWED] d86a0bf Description read[DESCRIPTION-READ] 90e79de4ad66a143fd39ada48781d8b49028a782c9d384a3f82fac1525d2292e That sha256 names everything this verdict read: the PR description, plus the 11 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) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The feature only applies to apps that declare it, nothing changes for existing apps, and approval reuses the existing staged-grant path. Notes
What this change shipsInventory (8 items) — 7 justifiedIntent: let an installed, enabled and trusted app show an approved third-party https site in an iframe on its own page, without a core edit. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] d86a0bf Description read[DESCRIPTION-READ] b9fe4eacc801c1f0c4bd61c16fb8479c3bc8895b5025f3cf0032936add0c32b1 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the change adds a manifest seam that only lets origins in, admits them only after owner approval, is limited by the trust ceiling, and fails closed. It takes nothing away, and screenshots are attached. Notes
[DESIGN-REVIEWED] d86a0bf Description read[DESCRIPTION-READ] 8fd3405ed59ea7168e939463f176c32d84f5b035239fb30f3a55e2bc0fe72588 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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
f00353b to
936955e
Compare
|
|
|
|
|
936955e to
38c6540
Compare
|
|
38c6540 to
958accb
Compare
|
Rebased: main moved in docs/app-kit/manifest-reference.md and docs/system-specs/modules/app-kit-platform.md since this head went green (d155058 -> 205d08d); CI re-running. Same push fixes the test_manager_facade failure (frame_sources.py now reads the manager facade, and refresh_frame_sources is named in its TYPE_CHECKING group). The test/tracing/test_tracing_otlp.py reds are unrelated and recorded in #37180. |
958accb to
ed8e0ac
Compare
|
New head GPT 6.1 blocking finding (AppHost.tsx:313): a frame-recovery check still pending at unmount could reload the page the user moved to. Frontend Tests on |
28e5043 to
efb54f3
Compare
|
New head |
efb54f3 to
a9ea734
Compare
|
New head No automatic reload. The automatic recovery (HEAD policy check, then Import budget. |
a9ea734 to
2c5871e
Compare
|
New head |
2c5871e to
351c99d
Compare
|
New head GPT 6.1 (frame_sources.py:84): UX Review (refresh shown when a refresh can't help): the notice now looks at the app row's |
|
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. The open question is whether an enabled, trusted app may add third-party https origins to the frame-src of the whole dashboard document. No accepted RFC or docs/decisions entry covers that yet. Review result on 351c99d: no blocking finding.
Earlier change request on 39f4549:
Optional:
|
Withdrawn: every item in this review is fixed or answered on the current head (see the follow-up comment). Other holds on this PR are listed there.
bolichen97
left a comment
There was a problem hiding this comment.
Thanks for this. I read the whole diff at 351c99d, including the tests, the capture script and every locale. The model holds up: origins reach frame-src only for an installed, enabled, trusted app, only once approved through the staged grant family (explicit only, so an old stored set approves nothing), the scan re-validates each manifest and fails closed, and the CSP middleware reads one cached string. Nothing main allows is refused: an app that does not declare ui.frameSources sees no change, and the dashboard's existing frame-src sources are unchanged. frame_origin_refusal reuses main's existing HOST_RE and host_refusal, so that is not new pattern matching.
One blocking point: new regex in product code.
website/src/components/appFrameSources.ts,policyAdmitsFrame:directive.split(/\s+/). The project does not take regex based parsing in product code. A plain split works here, for exampledirective.split(' ').filter(Boolean), or split on' 'after replacing tabs if you want to cover them. ThepolicyAdmitsFrametests already pin the behaviour.
Non-blocking:
de.jsonalso rewords two unrelated strings (load_failedandread_failed, "erneut" to "noch einmal"). Fine to keep, just outside the scope of this PR.
Happy to approve once the split is replaced.
351c99d to
2264072
Compare
|
Thanks @bolichen97. Addressed on head 2264072. Blocking: regex in
Non-blocking:
Also in this push
Local checks: |
…ves it
ui.frameSources becomes an explicit-only staged grant family, registered
from the manifest's ui section in point_grants. Install approves what it
declares; an origin an update or a live edit of app.json adds stays out
of frame-src until the owner approves it on the app's page, and a set
stored before the key existed approves none. The app row carries
frameSourcesGrant {approved, staged}, and the detail page lists the
staged origins with the other held-back grants.
Docs: say the origins are admitted dashboard-wide while the app
qualifies, that a trust revoke lands on the next reconciler tick and
open pages keep the old policy until reload, and list the origins in
security.md's frame-src sources.
|
Rebased onto main (4dec84c) to clear a new conflict with #32983 (app Bot grants); new head d86a0bf. The conflicts were in |
|
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. The open question is still whether an enabled, trusted app may add third-party https origins to the frame-src of the whole dashboard document. No accepted RFC, docs/decisions entry or maintainer reply on #36991 or this PR covers that yet, so the decision stays with the maintainers and the security reviewer. Review result on d86a0bf: no blocking finding.
Earlier change request on 39f4549: all four items were fixed, as noted in my comment on 351c99d. The change request from bolichen97 (the regex in For the security review:
Optional:
|
bolichen97
left a comment
There was a problem hiding this comment.
Approving d86a0bf. Versus 351c99d, which I asked changes on, the range-diff shows a rebase onto main (merged cleanly with the new bots grant family in AppDetailPage.tsx / apps.ts) plus the two fixes below.
Earlier points
- Blocking, fixed:
website/src/components/appFrameSources.tspolicyAdmitsFrameno longer usessplit(/\s+/). It folds tab, newline, CR and form feed to spaces and splits on' 'withfilter(Boolean). No regex is left in the product code this PR adds (I grepped the added lines undersrc/andwebsite/src/). The new testsplits sources on runs of spaces and tabspins the behaviour. - Non-blocking, done: the unrelated
de.jsonrewording (load_failed,read_failed) is gone.
Security re-check on this head
apps/frame_sources.pystill publishes an origin only for an app that is installed, enabled and trusted (third_party_ceiling_closed), whoseui.frameSourcesre-validates, and only the origins in the owner-approvedframeSourcesstaged grant. A whole-scan failure publishes"".- Mutations, one at a time, each restored: publishing the declared list instead of the approved one (3 tests red), dropping the trust check (2 red), dropping the re-validation (1 red).
frame_origin_refusalprobes: onlyhttps://<lowercase host>passes. Refused:http:,*,https://*.x, leading dot, port,/, path, query, fragment, user info, IPv4/IPv6 literals,169.254.169.254,localhost, uppercase, trailing dot,\n/\t/ space,;script-src *,'self',data:,blob:,javascript:, a Cyrillic look-alike and a bare suffix. A non-list or non-stringframeSourcesis an error.
Tests run on this head
- Backend:
test_app_frame_sources.py,test_dashboard_security_headers.py,test_app_frame*.py,test_hook_reconcile.py,test_link_preview_grants.py,test_app_execution.py,test_app_manifest*.py,test_manifest_facade.py,test_manager_facade.py: 698 passed. - Website:
appFrameSources.test.ts,AppHostCoverage.test.tsx,AppDetailPageCoverage.test.tsx: 101 passed.
Still for the maintainers, as Ray noted: no accepted RFC or docs/decisions/ entry yet covers apps framing third-party origins in the dashboard.
AI-assisted, sent by Bolin Review bot
Problem / Motivation
Goal: An installed app that the owner enabled and trusted can show a named https site (for example an embedded video player) inside its own page.
An app page (
ui.pages) is an ESM module the dashboard imports into its own document, so any<iframe>it draws is checked against the dashboard'sframe-src. That directive admits only the dashboard itself,blob:, CloudFront previews and loopback. An external app has no way to frame a third-party player or widget, and the only route today is editingserver.py, which is a core change per app.Why it matters
Apps now live in their own repositories (AGENTS.md "No built-in apps"), so a core edit per app is not available to them. Without a manifest seam, any app that needs one embedded site cannot ship as an installed app.
Not a goal
http:or loopback origins. Exacthttps://<hostname>only.apps/app_frame.py); their sandboxed documents keepframe-src 'none'.What changed (motivation → approach → change)
A trusted page module already runs with the dashboard's authority (
app-platform-trust-model.md), so the smallest correct seam is to let the manifest name the sites it frames, and let the gateway admit them only while the app may run.ui.frameSources: string[], at most 8. Each entry must be exactlyhttps://plus one lowercase hostname. The validator refuses a path, port, query,http:, wildcard, user info, IP literal,localhost, public suffix (theHOST_RE/host_refusalrules inapps/app_hosts.py), a duplicate, a non-string entry and more than 8.frameSources(apps/point_grants.py, besidelinkPreviewHosts). Install approves what it declares. An origin an update or a later edit ofapp.jsonadds is held back and listed on the app's page until the owner approves it; a set stored before the key existed approves none. The app row carriesframeSourcesGrant: {approved, staged}.apps/frame_sources.pypublishes the union of declared and approved origins of apps that are installed, enabled and admitted bythird_party_ceiling_closed. The dashboard CSP appends that cached string toframe-src. It re-validates each manifest while it scans, becauseapp.jsonis in the app's writable tree and the value lands in a header. A failed scan publishes nothing.enable_app,disable_app,update_app(before the route announcesapp_reload),uninstall_app, and each hook-reconciler tick (picks up CLI changes and trust edits inconfig.json). The reconciler's first scan runs when its task starts, so boot does no extra awaited work; until then no app origin is admitted (fail closed). The CSP middleware never reads a manifest.AppHostlistens for asecuritypolicyviolationthat refuses one of the mounted app's declared origins under a document policy that lacks it (a redirect to an undeclared host is ignored) and shows a dismissable notice naming the origin: "Reload page" for an origin in the app's approved set, or "Open app details" for one still waiting for approval, since a reload would be refused again (website/src/components/appFrameSources.ts). Nothing reloads by itself: a reload is of the whole dashboard document, not only the app frame, and the page may hold unsaved input. The notice has no agent hand-off for the same reason.ui.frameSourcesrow inmanifest-reference.md; the rule inapp-kit-platform.md§18 (approval, dashboard-wide admission, revoke timing); theframe-srcsources insecurity.md.What it opens, and why that is no new power: while an app is enabled and trusted, the sites it lists and the owner approved may be framed. CSP is per document, so they are admitted for the whole dashboard, not only the app's page. Its module can already run any script in the dashboard document and fetch any image from any https host (
img-src https:). A framed cross-origin site cannot read the dashboard. Nothing is added for an untrusted or disabled app.Backwards compatibility
Compatible: the field is new and optional, absent from every manifest today, and serialized only when declared, so existing manifests and their signed payloads are unchanged. The
frame-srcof a gateway with no declaring app is byte-identical.Removes nothing: no path, key, record or capability is taken away;
frame-srconly gains origins.Tests
test/test_app_frame_sources.py:https://example.com/path,https://example.com/,https://example.com:8443,?q=1,http://example.com,https://*.example.com,https://1.2.3.4,https://localhost,https://app.localhost,https://co.uk,https://github.io,https://user@example.com, an uppercase host and a; script-src *injection; refuses 9 entries, a duplicate, a non-list and a non-string entry; accepts 8 and round-trips.frame-srccarries an enabled, trusted app's origin and drops it ondisable_app; an untrusted or disabled app adds nothing; an origin two apps declare stays after one is disabled and goes when the other is uninstalled; a hand-edited invalid manifest adds nothing; install approves what it declares; an origin anupdate_appor a live edit ofapp.jsonadds stays out offrame-srcuntil the owner approves it (enable_appwithgrants_consent); an update that drops one stops publishing it; a set stored before the key existed approves none; the family is explicit-only.website/src/test/AppDetailPageCoverage.test.tsx: a staged framed site is listed and its approval sendsgrantsConsent.frameSources.website/src/components/appFrameSources.test.ts: aframe-srcrefusal of a declared origin matches, while another directive, an undeclared origin, another port or a non-URL value does not;frame-srcparsing is exact-origin.website/src/test/AppHostCoverage.test.tsx: a refused declared frame shows the notice with the origin, does not reload until "Reload page" is clicked, dismisses, and an undeclared origin shows nothing; an origin still staged gets "Open app details" (navigates to the details page) and no reload button.test/test_app_frame_sources.pyalso pins the reconciler tick: one_reconcile_loopiteration publishes the origin and, after trust is withdrawn, the next drops it (fails when the tick'srefresh_frame_sourcescall is removed); and nothing is staged while the declaration fails the scan's own validation: a bad entry, a repeated entry or more than 8 (fails without theframe_source_errorscheck).Determinism: the file passed 3 runs in shuffled function order (
-n0). Existing CSP pins (test/test_dashboard_security_headers.py) pass unchanged.Manual verification
N/A — unit coverage drives the real
install_app/disable_app/uninstall_appand the real CSP builder; the one stub is the trust decision, whichtest/test_app_execution.pycovers.Screenshots / video
The app detail page gains one staged row: an update or an
app.jsonedit that adds aui.frameSourcesorigin shows it under "Framed sites" with the other new permissions, and "Approve new permissions" approves it. Nothing is offered while the declaration fails the validation the scan applies, since no approval could then take effect. Captured from this head's built SPA with stubbed API data bywebsite/scripts/capture-37157-frame-sources-approval.mjs, which also asserts the chip, theframeSourcesconsent the button sends, and the message after approval.Staged, light:
Staged, dark:
After approval, light:
After approval, dark:
App page, a declared frame refused by the page's older policy, light:
App page, a declared frame refused by the page's older policy, dark:
App page, a declared frame still waiting for approval, light:
App page, a declared frame still waiting for approval, dark:
Related Issues
Part of #36991
Overlap note: #36967 also edits the
frame_src_extralines insecurity_headers.py; whichever merges second rebases a few lines.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)