Skip to content

fix(apps): audit a denied browser media action; explain held slots - #38866

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/app-browser-media-scope
Nov 18, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/app-browser-media-scope

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A browse-denied media action is audited, and a chat held after its app's sites are withdrawn says why and how to recover.

These come from bolichen97's review of #38333 (review 5947126093), raised there as non-blocking notes:

  • A media POST refused by capabilities.browse wrote no audit row, unlike the sibling /api/browser/* routes.
  • A slot held to NO_PAGES (its app's sites were withdrawn after the gate approved a call) was refused with a message that did not say why, or how the hold ends.

Why it matters

The first leaves a gap in the audit trail for an action the policy refused. The second leaves a user or agent with a refusal they cannot act on.

Not a goal

What changed (motivation → approach → change)

  1. Audit a refused action. browse_refusal(audit=request.method != "GET") in api_browser_media: a refused POST writes its row as the sibling routes do; the state poll (GET) still writes none, so a player's poll does not fill the log.
  2. Say why a held slot is held. One string, browser_ops.SITES_REVOKED_TEXT: the sites were withdrawn (app disabled or uninstalled, trust removed, or approval dropped), and enabling the app and approving its sites again ends the hold. It is the error of the op route's site_not_allowed, of a held slot's blanked page (redirect_refused), and of the media route's not_app_browser. Codes are unchanged.
  3. Spec. app-kit-platform §45 states that the media route cannot tell one app's page from another's, and why.

Backwards compatibility

Compatible: no request is refused that was accepted before; only an audit row and refusal text are added.

Removes nothing: no route, key, row or behaviour is hidden, deleted or tightened.

Tests

  • test_a_browse_denied_media_action_is_audited_and_a_poll_is_not: a denied POST asks with audit=True, a denied GET with audit=False.
  • test_a_held_slot_says_its_sites_were_withdrawn_and_how_to_recover and test_a_held_slots_blanked_page_names_the_withdrawal: the op route and the media route answer with the withdrawal text.
  • Mutation checks: 5 reverts, one at a time (both audit spellings, all three text sites); each fails the tests.

Proof: PROVEN test/test_app_browser_sites.py::test_a_browse_denied_media_action_is_audited_and_a_poll_is_not (head f21d1fa)

Manual verification

N/A — unit coverage sufficient: the change is an audit flag and a refusal string, both exercised through the real route slice.

Related Issues

Follow-up to #38333 (review 5947126093). Part of #38306.

Sibling sweep

Swept: git grep -n "browse_refusal(audit=" -- src/kiro_crew/dashboard/handlers/
Sibling: src/kiro_crew/dashboard/handlers/browser_live.py -- not affected -- audits by route class (AUDITED, QUIET, UNGATED) already
Sibling: src/kiro_crew/dashboard/handlers/browser_recordings.py -- not affected -- passes its own audit flag per route already

Pattern harvest

Not generalizable: the missing audit flag was one route's own call; every sibling route already chose its flag.

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

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: fa8e373
  • What rule changed: POST/GET /api/browser/media (owner-only) now also requires the slot's _app to equal the app the calling page names (embed_app); a POST refused by capabilities.browse is now audited; the refusal text of a slot held to NO_PAGES now says why and how the hold ends. No tool-gate row, sandbox rule or deny rule changes.
  • Before -> after (what was allowed/blocked, now): before, any app page declaring /api/browser/media could control any app-owned browsing slot it named. After, only the page of the app that owns the slot can; any other is 403 not_app_browser before the tab is touched. Before, a browse-denied media POST wrote no audit row; after, it does (GET polls still do not). Held-slot behaviour is unchanged; only the error text differs.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): an app's own page is refused its own media buttons (if embed_app were not sent). The SDK sends it on every request and AppSdkBrowserMedia.test.tsx pins that. No secret or credential path is touched.
  • Evidence checked (which sandbox result proves it): test_one_apps_page_cannot_drive_another_apps_tab (another app, empty, missing; POST and GET), test_a_browse_denied_media_action_is_audited_and_a_poll_is_not, the two held-slot text tests; 8 reverting mutants all fail the tests; prove.py: PROVEN on head fa8e373.
  • No regression:
    • Tools still work (which tools/commands were run, result): test_app_browser_sites.py, test_browser_live_routes.py, test_browser_browse_governance.py, test_browser_ops_route.py, test_json_object_body_guard.py (276 passed) and AppSdkBrowserMedia.test.tsx (4 passed) on this head.
    • Backward compatible (old config / old data / old callers still work, how checked): the route shipped in feat(apps): let an app's own agent browse its approved sites unasked #38333 today; its only writer is the SDK hook, updated here. No registry app calls it yet.
    • Existing tests (which suites passed on this head): the suites above, plus test_flake_pattern_ratchet.py.
  • How to undo: revert this commit.

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

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of f21d1faa04dcab36a1dac3290639898142ce2b3a — 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

Both fixes sit at the mechanism: the media route makes its own audit choice per method, and the held-slot text is defined once. Nothing is duplicated and no default changes.

Notes

  • Item 7 (undeclared): it only rewraps four existing test calls. It carries no risk and is listed as inventory only.

What this change ships

Inventory (7 items) — 6 justified

Intent: when browsing is refused or an app's sites are withdrawn, the user gets an audit record and an error they can act on. This is a FIX.

  1. A media action (POST) refused by capabilities.browse now writes an audit row; a state poll (GET) still writes none — justified
  2. The media route's error for a held slot now says the sites were withdrawn and how to recover — justified
  3. The op route's site_not_allowed error for a held slot now says the same — justified
  4. When a held slot's page is blanked (redirect_refused), its error now names the withdrawal — justified
  5. A new constant, browser_ops.SITES_REVOKED_TEXT, used at 3 sites in 2 modules — justified
  6. The app-kit-platform spec now says the media route can't tell one app's page from another's, and documents the held-slot text — justified
  7. Four existing media-route test calls are rewrapped across more lines — undeclared, rides along

[FIRST-PRINCIPLES-REVIEWED] f21d1fa

Description read

[DESCRIPTION-READ] 77d2db63e620b87c9f6e25eaa7e22e6af8afbf051ff0054f9196e8f98af00922

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 18, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Small, proportionate fix: one audit flag and one shared refusal string. It removes nothing and adds no new surface.

[DESIGN-REVIEWED] f21d1fa

Description read

[DESCRIPTION-READ] 70c438123a2d6bfb7a707f6d8033c18330d18be64ae9382ffb337e41b3ce890c

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 18, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] f21d1fa

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

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

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision f21d1faa04dcab36a1dac3290639898142ce2b3a touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] f21d1fa

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

Follow-up to #38333 from the review on it (5947126093).

A media POST refused by capabilities.browse now writes its audit row,
like the sibling routes; the state poll (GET) still does not.

A slot held to NO_PAGES after its app's sites were withdrawn now says so
in its refusal, and how the hold ends: enable the app and approve its
sites again. Behaviour is unchanged.

The spec now says the media route cannot tell one app's page from
another's: a page module runs with the owner's cookie, so that needs an
app-scoped credential, which is out of scope here.
@iamwhatever
iamwhatever force-pushed the fix/app-browser-media-scope branch from fa8e373 to f21d1fa Compare November 18, 2026 01:07
@iamwhatever iamwhatever changed the title fix(apps): hold browser media to the calling app; explain held slots fix(apps): audit a denied browser media action; explain held slots Nov 18, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: f21d1fa
  • What rule changed: POST /api/browser/media refused by capabilities.browse is now audited (GET polls are not); the refusal text of a slot held to NO_PAGES now says why and how the hold ends. No tool-gate row, sandbox rule, deny rule or access check changes.
  • Before -> after (what was allowed/blocked, now): every request allowed or refused before is allowed or refused the same way now. Before, a browse-denied media POST wrote no audit row; after, it does. A held slot's error text changes; its codes do not.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): one extra audit row per denied media button press. No secret or credential path is touched. Cross-app isolation on this route needs an app-scoped credential; it is out of scope and recorded separately.
  • Evidence checked (which sandbox result proves it): test_a_browse_denied_media_action_is_audited_and_a_poll_is_not, the two held-slot text tests; 5 reverting mutants all fail the tests; prove.py: PROVEN on head f21d1fa.
  • No regression:
    • Tools still work (which tools/commands were run, result): test_app_browser_sites.py, test_browser_live_routes.py, test_browser_browse_governance.py, test_browser_ops_route.py, test_json_object_body_guard.py: 273 passed on this head.
    • Backward compatible (old config / old data / old callers still work, how checked): no request shape changes; the SDK is untouched.
    • Existing tests (which suites passed on this head): the suites above.
  • How to undo: revert this commit.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Re First Principles on fa8e373: agreed. embed_app is set by the calling page, so the comparison could not stop a page that names another app, and the route has no server-verified way to tell one app's page from another's: a page module runs with the owner's cookie, the same authority as the dashboard. That item is removed on f21d1fa (route check, SDK sends and their test), and the Goal is narrowed to the two remaining fixes, at the owner's request. Cross-app isolation on this route needs an app-scoped credential; it is out of scope here and recorded separately. app-kit-platform §45 now says the route cannot tell the pages apart.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 18, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 18, 2026 04:15

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This review checked head f21d1fa and found nothing blocking. Every allow and refuse decision is the same as on main, and so is every refusal code. A refused media POST now writes an audit row, the same way the sibling browse routes do, and a GET poll still writes none. The suite test/test_app_browser_sites.py passes at this head (92 passed), and reverting each of the five production hunks, one at a time, turns its own test red. One thing done well: the held-slot explanation is a single constant, SITES_REVOKED_TEXT, used at all three places a held slot is refused, so the three messages cannot drift apart.

Security: this adds no gate, sandbox or access change. The only security-relevant change is one more audit row on an existing capabilities.browse decision.

The design is signed off under the standing maintainer sign-off for changes by team members.

Optional:

  • browser_ops.py:406: the held-slot text leaves out one cause: an app update or a manifest edit can remove browserSites or make it invalid. In that case, and for an uninstalled app, "approve its sites again on the app's page" cannot work. Wording that covers every cause would fix it.
  • browser_media.py:116: useBrowserMedia keeps only the refusal code, which is still not_app_browser, so an app page never shows the new text. A separate code would let it, in a follow-up.
  • app-kit-platform.md: with audit=True, every POST decision is audited, allowed ones too, as on the sibling routes. The parenthetical "an action's refusal is audited" says less than that.

@KiroCrewCaptain
KiroCrewCaptain merged commit 31e0fa4 into main Nov 18, 2026
106 of 117 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/app-browser-media-scope branch November 18, 2026 04:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants