Skip to content

feat(apps): let an enabled, trusted app declare the https origins its pages frame - #37157

Merged
bolichen97 merged 2 commits into
mainfrom
feat/app-frame-sources
Nov 16, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
feat/app-frame-sources

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

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's frame-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 editing server.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

  • Any change for an app that is disabled, untrusted or uninstalled: it adds nothing.
  • Wildcards, ports, paths, http: or loopback origins. Exact https://<hostname> only.
  • Frame-backed contribution points (apps/app_frame.py); their sandboxed documents keep frame-src 'none'.
  • Any other CSP directive.

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.

  • Manifest: ui.frameSources: string[], at most 8. Each entry must be exactly https:// plus one lowercase hostname. The validator refuses a path, port, query, http:, wildcard, user info, IP literal, localhost, public suffix (the HOST_RE / host_refusal rules in apps/app_hosts.py), a duplicate, a non-string entry and more than 8.
  • Owner approval: each origin is an entry of the explicit-only staged grant family frameSources (apps/point_grants.py, beside linkPreviewHosts). Install approves what it declares. An origin an update or a later edit of app.json adds 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 carries frameSourcesGrant: {approved, staged}.
  • CSP: apps/frame_sources.py publishes the union of declared and approved origins of apps that are installed, enabled and admitted by third_party_ceiling_closed. The dashboard CSP appends that cached string to frame-src. It re-validates each manifest while it scans, because app.json is in the app's writable tree and the value lands in a header. A failed scan publishes nothing.
  • When it rescans: enable_app, disable_app, update_app (before the route announces app_reload), uninstall_app, and each hook-reconciler tick (picks up CLI changes and trust edits in config.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.
  • An open dashboard: a document keeps the CSP it was served with, so an app enabled after the page loaded would have its iframe refused. AppHost listens for a securitypolicyviolation that 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.
  • Docs: a ui.frameSources row in manifest-reference.md; the rule in app-kit-platform.md §18 (approval, dashboard-wide admission, revoke timing); the frame-src sources in security.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-src of a gateway with no declaring app is byte-identical.

Removes nothing: no path, key, record or capability is taken away; frame-src only gains origins.

Tests

test/test_app_frame_sources.py:

  • Validator refuses each of 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-src carries an enabled, trusted app's origin and drops it on disable_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 an update_app or a live edit of app.json adds stays out of frame-src until the owner approves it (enable_app with grants_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 sends grantsConsent.frameSources.

website/src/components/appFrameSources.test.ts: a frame-src refusal of a declared origin matches, while another directive, an undeclared origin, another port or a non-URL value does not; frame-src parsing 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.py also pins the reconciler tick: one _reconcile_loop iteration publishes the origin and, after trust is withdrawn, the next drops it (fails when the tick's refresh_frame_sources call 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 the frame_source_errors check).

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_app and the real CSP builder; the one stub is the trust decision, which test/test_app_execution.py covers.

Screenshots / video

The app detail page gains one staged row: an update or an app.json edit that adds a ui.frameSources origin 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 by website/scripts/capture-37157-frame-sources-approval.mjs, which also asserts the chip, the frameSources consent the button sends, and the message after approval.

Staged, light:

Framed sites row, light

Staged, dark:

Framed sites row, dark

After approval, light:

Approved message, light

After approval, dark:

Approved message, dark

App page, a declared frame refused by the page's older policy, light:

Refresh prompt, light

App page, a declared frame refused by the page's older policy, dark:

Refresh prompt, dark

App page, a declared frame still waiting for approval, light:

Approval prompt, light

App page, a declared frame still waiting for approval, dark:

Approval prompt, dark

Related Issues

Part of #36991

Overlap note: #36967 also edits the frame_src_extra lines in security_headers.py; whichever merges second rebases a few lines.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|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

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 14, 2026 08:43
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 14, 2026
@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of d86a0bf70e0355badabf9550a7c854f7786bc598 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • frame_blocked_refresh: the code already knows the origin is approved, so drop the hedge "If you just enabled or approved this app". Use "{{origin}} was allowed after this page loaded. Reload the page to show it."
  • frame_needs_approval / open_app_details: neither string names the app, and the reader rated "Open app details" only "a guess, because the warning never names the app". Pass the app's display name, e.g. "Approve it on Mood Music's details page".
  • grants_reconsent_frame_sources: the reader didn't know what "Framed sites" or "dashboard" meant. Use "Embedded sites: lets the app show these sites inside its own page."

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d86a0bf70e0355badabf9550a7c854f7786bc598 — 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 does not.

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

  • Item 6 — one consumer, generalized: _UI_REGISTRY: list[...] and the public register_ui_grants have exactly one registration: register_ui_grants(("frameSources",), ...) in point_grants.py. I grepped for register_ui_grants|_UI_REGISTRY and found no other caller in src/. Subtraction: delete register_ui_grants and _UI_REGISTRY, and read frame_source_grant_entries(ui_view) directly in grant_source. Keep frameSources on _EXPLICIT_ONLY with a single append.

What this change ships

Inventory (8 items) — 7 justified

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

  1. App manifests can declare ui.frameSources (at most 8 exact https://host origins), and install refuses anything else — justified
  2. The dashboard frame-src admits approved origins of enabled, trusted apps, for the whole dashboard — justified
  3. Install approves the declared origins; an origin added later by an update or an app.json edit waits on a new "Framed sites" row on the app's page — justified
  4. The app row returns a new frameSourcesGrant: {approved, staged} key — justified
  5. The hook reconciler now rescans manifests every tick, and once when its task starts after boot; lifecycle calls also rescan — justified
  6. New public registry seam register_ui_grants in point_grants — one consumer, generalized
  7. When the open page's older CSP refuses a declared frame, the app page shows a dismissable notice with "Reload page" or "Open app details" — justified
  8. Screenshot harness capture-37157-frame-sources-approval.mjs (103 sibling capture-<n> scripts already exist) — justified

[FIRST-PRINCIPLES-REVIEWED] d86a0bf

Description read

[DESCRIPTION-READ] b9fe4eacc801c1f0c4bd61c16fb8479c3bc8895b5025f3cf0032936add0c32b1

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of d86a0bf70e0355badabf9550a7c854f7786bc598 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • CSP applies to the whole document, so an approved origin can be framed anywhere in the dashboard, not just on the app's page. The approval UI should say so. A "Framed sites" chip shown only on the app's page reads as narrower than what is actually granted.
  • Revoking access takes effect only on the next scan and the next document load. Disabling an app does not stop a tab that is already open from framing its sites. §18 should state this limit plainly, so nobody reads disable_app as an immediate kill.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed d86a0bf70e0355badabf9550a7c854f7786bc598 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] d86a0bf

Verdict parsed from the review's SHA-scoped output markers for commit d86a0bf70e0355badabf9550a7c854f7786bc598.

False positive or not applicable? A repository writer can comment:
/ai-review override fable d86a0bf70e0355badabf9550a7c854f7786bc598 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of d86a0bf70e0355badabf9550a7c854f7786bc598 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d86a0bf

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d86a0bf70e0355badabf9550a7c854f7786bc598 false-positive: <reason, 20 to 500 characters>

@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 Nov 14, 2026
@iamwhatever
iamwhatever force-pushed the feat/app-frame-sources branch from f00353b to 936955e Compare November 14, 2026 09:35
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=7e33853cd221

fixed in 936955e: the awaited startup scan in _hooks_startup is gone. The first scan is the hook reconciler's, which now runs refresh_frame_sources at the top of its loop task, before its sleep, so it runs after boot and off the readiness path. Until then the published suffix is empty (fail closed).

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 14, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=d872e5dd3102

fixed in 936955e: update_app calls refresh_frame_sources() after a successful update (beside refresh_app_config_keys()), which runs before the route announces app_reload, so the reloaded page gets the new origins. Test: test_update_of_an_enabled_app_republishes_its_origins.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 14, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=4c85131be810

fixed in 936955e: AppHost listens for securitypolicyviolation; a frame-src refusal of one of the mounted app's declared origins reloads the document once (website/src/components/appFrameSources.ts, at most every 30 s per app, so an untrusted app cannot loop). This covers every enable path, the CLI and trust edits, with no per-call-site reload. Tests: appFrameSources.test.ts.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=10b0472921c5

fixed in 936955e: AppHost reloads the document once when the browser refuses a frame to one of the mounted app's declared origins (securitypolicyviolation, frame-src), at most every 30 s per app (website/src/components/appFrameSources.ts). The reloaded document is served the current frame-src.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=1fab946da91f

fixed in 936955e: no scan on the boot path any more. The first publication is the hook reconciler's first loop iteration (a task started after the boot pass), and the suffix stays empty until it runs, so the CSP fails closed.

@iamwhatever
iamwhatever force-pushed the feat/app-frame-sources branch from 936955e to 38c6540 Compare November 14, 2026 09:44
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=cdb71c82f3e8

fixed in 38c6540: a refusal no longer reloads on a timer. reloadIfFrameAdmitted first reads the policy the gateway serves now (HEAD of the page URL, same CSP middleware) and reloads only when its frame-src lists the refused origin exactly. An enabled but untrusted app is never admitted, so it never reloads. The 30 s gap stays only as a backstop. Tests: appFrameSources.test.ts (refusing policy -> no reload across repeated visits; unreadable policy -> no reload).

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • span=48c5cdd31c06

Rebutted (disproportionate, as adjudicated): it needs a hand edit of config.json granting trust to an already-enabled app plus opening its page within the 15 s before the next reconciler tick. Every dashboard and CLI lifecycle path republishes at once. The result is a visible blank frame that any reload or reopen cures; retrying would need a timer or a publication channel to the document for that one window.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

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.

Comment thread test/test_app_frame_sources.py Fixed
Comment thread test/test_app_frame_sources.py Fixed
Comment thread test/test_app_frame_sources.py Fixed
@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 Nov 14, 2026
@iamwhatever
iamwhatever force-pushed the feat/app-frame-sources branch from 958accb to ed8e0ac Compare November 14, 2026 10:48
@iamwhatever

Copy link
Copy Markdown
Contributor Author

New head 28e504338c. Two fixes here.

GPT 6.1 blocking finding (AppHost.tsx:313): a frame-recovery check still pending at unmount could reload the page the user moved to. AppHost now aborts an AbortController in the effect cleanup and passes its signal to reloadIfFrameAdmitted, which passes it on to the HEAD fetch. After the policy await, the helper checks signal.aborted before it touches storage or reloads, and an aborted rejection shows no notice. Two tests cover it: one in appFrameSources.test.ts and one unmount-while-pending test in AppHostCoverage.test.tsx. Both fail when the check is removed. I am not proposing an override.

Frontend Tests on d13160b087: the new string used the formal register in de, fr, bn, hi and ru, and the register style tests caught it. It now uses du, tu, তুমি, तुम and ты. The JS CodeQL alert 1351 in the capture script, a substring includes on a URL, is replaced by an exact token match.

@iamwhatever
iamwhatever force-pushed the feat/app-frame-sources branch from 28e5043 to efb54f3 Compare November 15, 2026 08:54
@iamwhatever

Copy link
Copy Markdown
Contributor Author

New head efb54f399c. CodeQL alert 1354 in website/scripts/capture-37157-frame-sources-approval.mjs flagged Array.includes too, so the check is now a Playwright getByText(origin) locator count. The harness still passes, and nothing else changed.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@iamwhatever
iamwhatever force-pushed the feat/app-frame-sources branch from efb54f3 to a9ea734 Compare November 15, 2026 10:04
@iamwhatever

Copy link
Copy Markdown
Contributor Author

New head a9ea7341d2. This is a simpler design for the open-dashboard case, plus the import budget kept at its original ceilings.

No automatic reload. The automatic recovery (HEAD policy check, then window.location.reload()) kept producing review findings: a silent failure, then a reload landing on the next page. It is gone. When a declared frame is refused by the page's older policy, AppHost shows a dismissable notice naming the origin, with a "Reload page" button. Nothing reloads unless the owner clicks it. appFrameSources.ts now holds only the two pure functions, refusedDeclaredOrigin and policyAdmitsFrame. The HEAD request, the 30 s gap, sessionStorage and the abort handling are all removed. The notice has no agent hand-off, because the hand-off would unmount an app page that may hold unsaved input. The new key components.appHost.frame_blocked_refresh is in every locale, informal register, and replaces frame_recovery_failed. Tests: AppHostCoverage.test.tsx checks the notice and that nothing reloads before the click; the click reloads, dismiss works, and an undeclared origin shows nothing. The body and §18 are updated. The light and dark screenshots of the notice replace the failed-recovery ones.

Import budget. test_mcp_listing_import_budget.py is back to main's ceilings. The PR no longer changes that file. frame_sources is now imported at call time in manager_activation, manager_install, manager_uninstall and manager_lookup. point_grants registers the frameSources family by name, through a deferred entries function. So a server's tool listing no longer loads the module.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 15, 2026
@iamwhatever
iamwhatever force-pushed the feat/app-frame-sources branch from a9ea734 to 2c5871e Compare November 15, 2026 10:38
@iamwhatever

Copy link
Copy Markdown
Contributor Author

New head 2c5871e8d1. On a9ea7341d2, test_manager_facade.py::test_every_served_import_is_named_for_type_checkers failed. The facade's TYPE_CHECKING group still named refresh_frame_sources and frame_sources_grant_row, which no family module imports at load time now. I removed that group, so manager.py matches main again.

@iamwhatever
iamwhatever force-pushed the feat/app-frame-sources branch from 2c5871e to 351c99d Compare November 15, 2026 11:20
@iamwhatever

Copy link
Copy Markdown
Contributor Author

New head 351c99d962.

GPT 6.1 (frame_sources.py:84): frame_sources_grant_row now runs the same whole-declaration check the scan uses, UIConfig.frame_source_errors, and stages nothing while it reports errors. That covers a bad entry, a repeated entry and more than 8. The test covers all three cases and fails without the check.

UX Review (refresh shown when a refresh can't help): the notice now looks at the app row's frameSourcesGrant. An origin still waiting for approval gets "… is waiting for your approval" with "Open app details", which goes to the details page, and no reload button. An approved origin keeps the "Reload page" prompt. There are two new keys in every locale. The new test fails when the branch is removed. The body has light and dark screenshots of the approval prompt. I did not rename the "Framed sites" label; that was an optional note.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

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.

  • The CSP stays safe. frame_origin_refusal accepts only https:// plus one full-match host, and it refuses IP literals, loopback names and public suffixes. Every scan re-validates the manifest, a failed scan publishes nothing, and with no declaring app the header is unchanged from main.
  • Approval cannot be bypassed. frameSources is an explicit-only grant, so an update or a live edit of app.json that adds an origin stays staged until the owner approves it.
  • The new backend tests pass, and removing the enable, update, uninstall or reconciler-tick refresh calls turns them red.

Earlier change request on 39f4549:

  • Missing screenshots and the no-visual-delta waiver: fixed. Light and dark screenshots from this head are in the body.
  • Optional reconciler-tick test: fixed. test_reconciler_tick_publishes_and_drops_a_trust_change covers it.
  • Optional staging of invalid declarations: fixed. frame_sources_grant_row now runs frame_source_errors.
  • Optional note that recovery reloads the whole dashboard: fixed. The reload is now manual, and section 18 says why.

Optional:

  • src/kiro_crew/apps/frame_sources.py:153: no test fails when the fail-closed reset in refresh_frame_sources is removed. A test where _scan raises, followed by a check that the origin left frame-src, would pin it.
  • website/src/components/appstore/trustGrants.ts:26: install approves the declared ui.frameSources origins, but the trust prompt does not list them. You could list them there, or say in the manifest reference that install-time approval is implicit.
  • website/src/i18n/locales/de.json:11238: two existing German strings unrelated to this feature are reworded. Drop those hunks, or name the change in the body.

@KiroCrewCaptain
KiroCrewCaptain dismissed their stale review November 15, 2026 13:24

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

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 example directive.split(' ').filter(Boolean), or split on ' ' after replacing tabs if you want to cover them. The policyAdmitsFrame tests already pin the behaviour.

Non-blocking:

  • de.json also rewords two unrelated strings (load_failed and read_failed, "erneut" to "noch einmal"). Fine to keep, just outside the scope of this PR.

Happy to approve once the split is replaced.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 15, 2026
@iamwhatever
iamwhatever force-pushed the feat/app-frame-sources branch from 351c99d to 2264072 Compare November 15, 2026 19:20
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Thanks @bolichen97. Addressed on head 2264072.

Blocking: regex in policyAdmitsFrame

  • website/src/components/appFrameSources.ts no longer uses a regex. Tabs, newlines, CR and form feeds become a space through split(ws).join(' '), then the directive is read with .split(' ').filter(Boolean).
  • The existing policyAdmitsFrame tests are unchanged and pass. I added one case for runs of spaces and a tab, including a tab right after frame-src.
  • I scanned the rest of this PR's product code for new regex. The only match is HOST_RE.fullmatch in frame_origin_refusal, which is main's existing HOST_RE, as you noted. Nothing else.

Non-blocking: de.json

  • Reverted load_failed and read_failed to main's text ("erneut"). The German diff now holds only this PR's own strings.

Also in this push

Local checks: appFrameSources.test.ts plus all src/i18n tests (82 files, 1269 tests) pass; test_app_frame_sources.py, test_dashboard_security_headers.py, test_app_hidden_sessions.py, test_app_frame.py pass (138).

zejiangg added 2 commits November 15, 2026 21:17
…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.
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased onto main (4dec84c) to clear a new conflict with #32983 (app Bot grants); new head d86a0bf. The conflicts were in apps.ts (enableApp consent type), AppDetailPage.tsx (staged-grant destructure and the "Approved" list) and one AppDetailPageCoverage expectation. Each keeps main's bots and this PR's frameSources. git range-diff shows no other change; still two commits, and the policyAdmitsFrame fix from the last push is unchanged. @bolichen97 nothing new to review beyond that.

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

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.

  • The new backend tests in test/test_app_frame_sources.py pass at this head, including shuffled orders. Removing the trust check, the approval filter, the enabled check, the scan re-validation or the enable, update, uninstall and reconciler-tick refresh calls turns them red.
  • Every caller of the refresh runs off the event loop, and each refresh runs after its persisting write.
  • The frontend tests for appFrameSources, AppHost and the detail page wait on events, not timers. The light and dark screenshots in the body match this head's strings.
  • Done well: this ships a generic App Kit seam on the existing staged grant machinery, not a built-in app, and the middleware reads only a cached string.

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 policyAdmitsFrame and the de.json rewording) is fixed at this head: appFrameSources.ts now uses split and join, and de.json holds only this PR's strings. That review is waiting for its author to re-review.

For the security review:

  • frame_origin_refusal accepts only https:// plus a full-match host from main's HOST_RE and host_refusal. It refuses IP literals, localhost, public suffixes, ports, paths and a ;, so nothing can inject a new CSP directive.
  • frameSources is an explicit-only staged grant. An update or a live edit of app.json that adds an origin stays out of frame-src until the owner approves it. A stored set that predates the key approves nothing.
  • Scope is dashboard-wide. While an app qualifies, its approved origin can be framed by any page of the dashboard, including another app's page module or a srcdoc frame that inherits the policy. With no declaring app, frame-src is unchanged from main.

Optional:

  • src/kiro_crew/apps/frame_sources.py:153: no test fails when the fail-closed reset _published = "" is removed. A test that publishes an origin, makes _scan raise, then checks that the origin left frame-src would pin it.
  • Install approves declared ui.frameSources, but the install trust prompt (website/src/components/appstore/trustGrants.ts) does not list them. This matches the existing practice for events and link preview hosts. Either list them or say in a comment that this follows that practice.
  • The Problem section says a core edit is the only route today. Main's backend.webOrigin (feat(apps): serve app web origins over the dashboard connection #36967) already lets an app with a backend frame a third-party site from its own origin. A PR comment on why that is not enough for page-only apps or a non-local dashboard would help the maintainer weigh the two.

@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 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.ts policyAdmitsFrame no longer uses split(/\s+/). It folds tab, newline, CR and form feed to spaces and splits on ' ' with filter(Boolean). No regex is left in the product code this PR adds (I grepped the added lines under src/ and website/src/). The new test splits sources on runs of spaces and tabs pins the behaviour.
  • Non-blocking, done: the unrelated de.json rewording (load_failed, read_failed) is gone.

Security re-check on this head

  • apps/frame_sources.py still publishes an origin only for an app that is installed, enabled and trusted (third_party_ceiling_closed), whose ui.frameSources re-validates, and only the origins in the owner-approved frameSources staged 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_refusal probes: only https://<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-string frameSources is 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

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants