Skip to content

fix: scope the dashboard SSE stream and log stream per app token - #38254

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
crew/LinuxFlackyGuard/sse-slots-scope
Nov 17, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
crew/LinuxFlackyGuard/sse-slots-scope

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An app token reading the dashboard's SSE stream or log stream receives only what its declared scope allows, the same as on the WebSocket, and a reader with no recognised identity is refused.

Three gaps on the two SSE doors in src/kiro_crew/dashboard/handlers/updates_streams.py:

  • GET /api/stream fanned every note on its queue to an app token with no per-app filtering. An app granted the route but no slots:* scope received every slot row (titles, previews, last message), every slot title and every chat message, and the periodic status frame with owner-only fields. The WebSocket door filters all of these through ws_event_scope.
  • GET /api/logs admitted an app that had not declared the log scope; its docstring and the WebSocket's subscribe_logs require it.
  • A reader carrying neither the dashboard-user mark nor an app claim was served. No production path reaches either route that way today (every auth path sets one of the two), but the doors did not fail closed.

The gap predates #37408. That change (the rule-table redaction engine) only made it visible: test_chat_send_echo_scope.py::test_user_echo_reaches_only_authorized_ws_clients uses a synthetic ghp_ value the old engine masked and the new one, which validates the checksum, does not, so the text an unscoped app was already receiving stopped being masked and the test went red intermittently (only when a slots push reached the stream before its fence frame). A real credential is still masked; what reached the app was the user's chat text and session previews.

Why it matters

An app is a third-party extension with a declared scope. The SSE stream let any app holding the route read the person's conversations and session list across all slots, and the log stream let it read every log line, without declaring either. It also kept one backend test red on unrelated PRs.

Not a goal

  • Relayed Shared Crew teammates: they count as dashboard users and keep reading /api/logs as today. Whether a teammate should see the operator's log ring is a separate decision, left open.
  • Changing what the WebSocket door decides (including its behaviour when an app's declarations cannot be read).
  • An app update that moves the app's tree while its declarations are being read: the grants helper then returns nothing approved, which this change treats as "approved nothing" (the app keeps only its own slots, as an app that declares nothing does), not as unreadable.
  • New scopes or manifest fields.

What changed (motivation → approach → change)

Both SSE doors now take the WebSocket gate's decisions instead of a second evaluator. A new module, src/kiro_crew/dashboard/sse_event_scope.py, wires the shared ws_event_scope helpers into the SSE handlers:

  • Who is scoped: a reader with request["app"] set and no dashboard-user mark. Dashboard users (including relayed teammates) keep today's stream. A reader with neither mark gets the auth middleware's own 403 before the stream opens, as does a disabled app. (Since fix: let every shared crew teammate act as the owner inside the crew #38209 a Shared Crew teammate acts as the owner, so it is a dashboard user here.)
  • /api/stream: declarations are loaded at connect (off the loop, like api_ws) and intersected with the live set for every note (effective_allowed_events, so a revoked scope takes effect mid-stream). slots rows go through filter_slots_for_app and no frame is sent when none is left; slot_title, chat_message and every other note type go through ws_event_allowed; chat_message keeps include_metadata=False. The status frame drops branch, commit and update_policy_file for an app reader, through one helper (strip_owner_only_status) now shared with ws.py.
  • /api/logs: an app must be enabled and have declared log or log:all, or it gets 403. The scope is re-checked before every replayed and every live entry, so a revocation ends the stream.
  • Fail closed: declarations count as read only when the manifest's entries were actually returned, so a missing or corrupt app.json, a failed read, or the grants helper returning before it reads all count as unreadable (load_declared_events_checked). The declaration cache keeps that marker in its own field (one writer, _store_declared), and both SSE doors check it before every live decision, so a stream opened while the declarations were readable drops to Tier 0 (refresh, update_progress, models_changed) and a log tail ends once they become unreadable. The WebSocket keeps mapping an unreadable set to an empty one, exactly as before. An exception in a scope check drops the note.
  • Audit: every grant and denial on both doors goes through the shared deduplicated _audit_allow / _audit_deny helpers, including live log grants, scope_check_exception, declarations_unreadable, and a dashboard user's log grant (as ws.py records it).
  • docs/system-specs/modules/app-kit-platform.md describes the SSE scoping and the new module.

Backwards compatibility

Breaking: an app that lists /api/logs in permissions.api but has not declared the log event scope now gets 403 where it used to get the stream; an app reading /api/stream now receives only its scope instead of every slot. Writer sweep on origin/main @ 521ee4d: no in-tree app or frontend consumer reads either SSE route (the spec lists none); the in-tree callers are test doubles, updated to set the positive mark the middleware sets. An installed third-party app relying on the unscoped stream would need to declare the scope it reads, as it already must on the WebSocket.

Reader: src/kiro_crew/dashboard/handlers/updates_streams.py:api_stream -- app -- scoped like the WebSocket; test_sse_stream_app_scope.py::test_app_token_stream_reader_sees_only_its_scope
Reader: src/kiro_crew/dashboard/handlers/updates_streams.py:api_logs -- app -- needs log; test_sse_stream_app_scope.py::test_log_stream_needs_the_log_scope
Reader: src/kiro_crew/dashboard/kiro_relay/admission.py -- crew page -- relayed teammates keep the dashboard-user mark; test_kiro_relay_teammate_app_frames.py

Tests

Proof: not provable -- other: prove.py stops at collection because reverting the production hunks removes the new sse_event_scope module the new tests import; instead the new test file was run against main 09e5482, where its scope, log and unmarked-reader tests fail, and test_chat_send_echo_scope.py is intermittently red on main

test/test_sse_stream_app_scope.py (new, 26 tests) drives both handlers through an aiohttp test server bound to port 0, puts notes directly on the client's queue and reads to a fence frame with bounded waits, so it does not depend on frame arrival order. It covers: an app without slots:* scope gets no slot content; an app scoped to its own slots gets only those; the dashboard user gets everything; the status frame's owner-only fields are stripped for an app; /api/logs with and without log; unreadable declarations (a real manifest read error inside the loader) send nothing scoped; a disabled app and a reader with neither mark are refused; a scope revoked after connect, during replay and during the live tail ends delivery, with the denial audited; a corrupt app.json, a grants read that returns before reading, and declarations that become unreadable after connect all fall back to Tier 0 on /api/stream and 403 or an ended tail on /api/logs, while the WebSocket mapping stays unchanged. Unit tests of sse_event_scope cover every fail-closed branch (a loader or live check that raises, a live scope read that raises, a disabled app on /api/logs, a failing audit write) and bring the module to 100% line coverage, above the Coverage Gate's 80% floor.

Planted regressions, each red by name: removing the slot filter, the per-note live re-check, the replay re-check, the live log re-check, the disabled-app refusal, the unidentified-reader refusal, the status-field strip, the unreadable marker, or the live denial audit.

test_chat_send_echo_scope.py, unchanged: 20/20 runs green with -n0 (intermittently red on main). Related files (everything touching updates_streams, /api/stream, /api/logs, sse_event_scope, ws_event_scope, _push_status, the token-auth middleware and the relay teammate frames, plus the flake ratchet and facade guards): 2909 passed, 4 skipped. flake8, isort, black gate, mypy --platform linux on the changed modules, comment-history, brand, line-cap, docs-lint, subprocess-encoding, harness-parity gates, and semgrep --config semgrep/ (no new finding): clean. Two local AI reviews (GPT 6.1, Opus 5.5) ran on the same change; their findings are fixed in it.

Manual verification

N/A — the handlers are exercised end to end through aiohttp's test server in the new tests; no UI surface changes.

Related Issues

Surfaced by test_chat_send_echo_scope.py turning intermittently red after #37408 (the cause predates it).

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

Sibling sweep

Swept: git grep -nE "register_sse|async def api_(stream|logs)|filter_slots_for_app|ws_event_allowed" -- src/
Sibling: src/kiro_crew/dashboard/ws.py -- not affected -- the WebSocket door already filters through ws_event_scope
Sibling: src/kiro_crew/dashboard/chat_api/slot_detail.py -- not affected -- GET slot routes already apply filter_slots_for_app and deny_app_slot_access
Sibling: src/kiro_crew/dashboard/sessions_parts/history_reads.py -- not affected -- history routes return only the app's own sessions

Pattern harvest

Rule candidate: review-prompt
Pattern: a new event transport for app readers must route every frame through the shared ws_event_scope decisions, never its own allow logic

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 17, 2026 04:42
@bolichen97
bolichen97 enabled auto-merge (squash) November 17, 2026 04:42
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 17, 2026
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 35ab2184c68bce87ced50609d663447649a2b65a 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 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 35ab2184c68bce87ced50609d663447649a2b65a — 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. Each change is aimed at the real gap: the SSE queue had no per-app gate at all. Two notes: a second "unreadable declarations" behaviour that the WebSocket does not have, and a log-scope check now written in two places.

Notes

  • Item 5 — oversized: the Goal is "receives only what its declared scope allows, the same as on the WebSocket", but SSE now treats unreadable declarations as Tier 0 only, while the WebSocket keeps "own slots only". That needs a fourth cache field, _read_declared_events_checked, load_declared_events_checked, declared_events_unreadable and _unreadable_now. Subtraction: delete all five and use load_declared_events_for_connect / effective_allowed_events as api_ws does (unreadable means an empty set). Clears when: the mechanism is removed, or a human amends the Goal.
  • Item 2 — duplicate of src/kiro_crew/dashboard/ws.py:1368: the check "log" in _live or "log:all" in _live now exists in 2 places (I grepped log:all; 2 checks, the WebSocket one at ws.py:1368 and the new one at sse_event_scope.py:131). Subtraction: have subscribe_logs call log_scope_granted and delete the inline copy.
  • Item 3 — rides along: the description itself says "No production path reaches either route that way today". Subtraction: remove unidentified_reader_refusal and keep the positive is_dashboard_user / app marks.

What this change ships

Inventory (7 items) — 4 justified

Intent: stop an app token from reading every slot, chat and log line through the SSE streams without the scope it declared. This is a FIX.

  1. An app reading /api/stream gets only the slots, titles and chat messages its scope allows — justified
  2. An app on /api/logs without the log scope gets 403, and losing the scope mid-stream ends the stream — duplicate of the inline check at ws.py:1368
  3. A reader with neither the dashboard-user mark nor an app claim gets 403 on both streams — rides along, no production path reaches it
  4. The SSE status frame drops branch, commit and update_policy_file for app readers, using a helper now shared with ws.py — justified
  5. When an app's declarations can't be read, SSE sends Tier 0 frames only and the log tail ends — oversized, goes further than the WebSocket does
  6. Every SSE grant and denial is written to the audit log — justified
  7. A third-party app that relied on the unscoped stream breaks (declared in the description) — justified

[FIRST-PRINCIPLES-REVIEWED] 35ab218

Description read

[DESCRIPTION-READ] 116abce67db86f5a8e0d35d23daa25f06fe42a8508bebe75ea4bb8c1615ebf3c

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. Both SSE doors now use the WebSocket's own scope helpers instead of a second evaluator, and the only things taken away are the two app-token breaks the description lists and accepts.

Notes

  • The SSE doors drop to Tier 0 on unreadable declarations, while the WebSocket keeps the app's own slots. The two doors now disagree on purpose, and Not a goal leaves the WebSocket as it is. Settle that in a follow-up so the next door added doesn't have to pick a side.

[DESIGN-REVIEWED] 35ab218

Description read

[DESCRIPTION-READ] dc8f183f39c6144cddc3f6b18996fdff89b512a80f0d21f3732b87c149a916d5

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 35ab218

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

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 35ab218

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

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

@bolichen97
bolichen97 force-pushed the crew/LinuxFlackyGuard/sse-slots-scope branch from 5719b9f to b6fa42d Compare November 17, 2026 05:02
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 17, 2026
@bolichen97
bolichen97 force-pushed the crew/LinuxFlackyGuard/sse-slots-scope branch from b6fa42d to 841803b Compare November 17, 2026 06:27
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 17, 2026
@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 17, 2026
@bolichen97
bolichen97 force-pushed the crew/LinuxFlackyGuard/sse-slots-scope branch from 841803b to d0efd44 Compare November 17, 2026 07:32
@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 Nov 17, 2026
The dashboard SSE stream fanned every note to an app token with no
per-app scope: an app granted the route but no `slots:*` scope received
every slot row, title and chat message. The log stream admitted an app
that had not declared the `log` scope, and a reader carrying neither the
dashboard-user mark nor an app claim was served instead of refused.

Both doors now take the WebSocket gate's decisions from the shared
ws_event_scope helpers: slot rows through filter_slots_for_app, every
other note through ws_event_allowed, the owner-only status fields
stripped by one shared helper, the log scope re-checked before every
replayed and live entry, a disabled app or an unmarked reader refused
with the middleware's 403, and an unreadable declaration set failing
closed. Every grant and denial is audited.
@bolichen97
bolichen97 force-pushed the crew/LinuxFlackyGuard/sse-slots-scope branch from d0efd44 to 35ab218 Compare November 17, 2026 08:17
@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 17, 2026

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

I reviewed head 35ab218. The SSE stream and log stream now apply the same per-app scope decisions as the WebSocket. Every auth path that can reach either route sets the dashboard-user mark or the app claim, so the new refusal of unmarked readers locks out no real caller. The WebSocket keeps its current handling of unreadable declarations, and slot filtering copies rows, so the shared broadcast note is never modified. The related backend tests pass on this head (351 across the stream, scoping and staged-grant suites). Taking the new slot filter out turns the new scope tests red, so they really test it. Nothing blocks.

@KiroCrewCaptain
KiroCrewCaptain merged commit f7df019 into main Nov 17, 2026
100 of 105 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the crew/LinuxFlackyGuard/sse-slots-scope branch November 17, 2026 09:50
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 17, 2026
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.

2 participants