Repository navigation
fix(mcp-gateway): hand the dashboard control plane its per-session token - #12459
Conversation
|
Intent: Hand the gateway-pooled |
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Fix is name-scoped but the failure class is property-scoped: a pooled Watch
[DESIGN-REVIEWED] e158a11 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 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: |
Opus 4.8 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: |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The fix is real but point-patched: Not justified as shipped
What this change shipsInventory (7 items) — 6 justifiedIntent: FIX — a gateway-pooled dashboard backend's control-plane tools all answer 409 and refuse; hand it the per-session token so they work.
[FIRST-PRINCIPLES-REVIEWED] e158a11 |
|
span=e39d4f07c17b (First Principles Review, head
|
98b10e6 to
6bc8daf
Compare
|
Rebased onto main This head also carries the two round-1 repairs: the ratchet now pins the token-only set to exactly |
|
span=e249a2d196db (First Principles Review, head
|
gatewayd forwards the per-session attestation token only to backends named in CONTROL_PLANE_BACKENDS, and that set named kirocrew-core and kirocrew-cron. kirocrew-dashboard is the third backend that posts back to the gateway for the calling session (session_create, session_send, the folder and tag tools), so a gatewayd-spawned dashboard backend, whose process ancestry ends at systemd instead of kiro-cli, had neither identity channel and every one of its tools answered "execution identity is unavailable". Two gates stood in the way. The set membership test returned False silently, so the missing name never produced a log line. And managed_mcp_spec_entry answered None for any opt_in entry, which the dashboard is, so adding the name alone only turned the silent refusal into a logged one. - add kirocrew-dashboard to CONTROL_PLANE_BACKENDS - managed_mcp_spec_entry(name, include_opt_in=True) resolves an opt_in entry's invocation for the control-plane check only; a closed spec_gate still yields None, and neither spec writer passes the flag - log the not-in-set exit at DEBUG so the two False exits are distinguishable - the denial warning no longer names two specific servers acp.session_mcp.CONTROL_PLANE_SERVERS is deliberately unchanged: it decides which servers every session mounts and which survive a disabledTools entry, so naming the dashboard there would make an operator's decision to switch its tools off unenforceable. The ratchet now pins containment instead of equality and requires every token-only extra to be a managed opt_in server.
6bc8daf to
e158a11
Compare
|
Rebased onto main On |
|
span=2ae75641d45a (Design Review, head
|
|
span=5009e862a0f4 (First Principles Review, head
|
|
Tracking issue for the residual disclosed in the two dispositions above: #12464. That issue covers the class rather than the two siblings alone, and it is wider than this PR in two ways. It also names So this head is the pooled-path half of #12464 for one recipient. The ratchet added here pins the token-only set to exactly Posted as a comment rather than a body edit: editing the body would re-run the review lanes that list |
buluoray
left a comment
There was a problem hiding this comment.
Verified at e158a115. Note for anyone reading the PR comments: one of them claims a rebase to 6bc8daff, but gh reports head e158a115 and 6bc8daff does not exist in the repo, so every bot verdict and this review are scoped to e158a115.
The membership gate runs first and reads nothing before it: if server_name not in CONTROL_PLANE_BACKENDS at gatewayd.py:222, ahead of the lazy managed_mcp_spec_entry import at :237. The set is now frozenset({"kirocrew-core", "kirocrew-cron", "kirocrew-dashboard"}) (:169).
Membership is necessary and not sufficient — none of the real fences moved. After the set check, _spawns_own_control_plane still requires realpath(binary) == spec, argv == expected_argv exactly, an empty child PYTHON* env, and no import root shadowing kiro_crew (:241-:270), each denying to False.
include_opt_in skips only the opt_in disqualifier and keeps the spec gate: _mcp_server_emission_eligible has exactly two disqualifiers, and _mcp_spec_gate_open is still consulted, with a raising gate reading CLOSED. No third fence is bypassed.
The token cannot ride to a foreign child. backend.control_plane is assigned at :4412 from the _spawns_own_control_plane verdict computed at :4355, i.e. from the resolved command, not from the name the stub registered; _caller_for_backend attaches the token only when that flag is true (:307), never mutates caller, and each call site re-derives from the tokenless base.
Scoping holds: the attached value is conn.stub_session_token, bound to the calling stub connection rather than to caller-supplied input, so a frame carries only its own connection's token. Adding one name does not widen that path.
Nothing leaks: the new DEBUG line logs server_name only, the reworded WARNING logs server_name + reason, and the deny reasons log command/argv/paths but never the token. When conn.stub_session_token is falsy the tokenless base caller is returned and the post-back 409s rather than falling back to an ambient credential.
One correction to my own review premise — I went in looking for a token file write and owner-only permissions. There is none: this change forwards the token in-memory per frame via dataclasses.replace(caller, session_token=...) and adds no file I/O at all, so the at-rest questions belong to the pre-existing machinery, untouched here.
The Design and First Principles CONCERNS are both real: kirocrew-work is opt_in, posts back for the calling session, shares the same 409 shape, and stays excluded. But the consequence is a fail-closed functionality gap, not a security regression, and granting one backend at a time on live evidence is the conservative direction — the ratchet is by-property so a verified sibling costs one name plus one pin.
No vacuous guards found. Each of the four new tests reddens on a real mutation, and the log assertions use single-tuple unpacking so an empty log fails rather than passes — which is the trap this shape usually falls into.
An opt-in Crew server (kirocrew-dashboard, kirocrew-work, kirocrew-crew-log, kirocrew-panel) granted by a spec on the kiro backend was mounted straight from the spec with no session-valued environment, and gatewayd handed the per-frame token only to kirocrew-core, kirocrew-cron and (since #12459) kirocrew-dashboard. Since the tool-policy read requires an attestation, every call on any other such server refused as identity_unattested, and on the kiro backend the dashboard itself still did. kiro_control_plane_servers now re-emits every IDENTITY_BOUND_SERVERS element the spec grants, so the token attach reaches them; CONTROL_PLANE_BACKENDS is the same set, read from the mcp_cleanup leaf. Both paths resolve a granted opt-in name with managed_mcp_spec_entry(name, include_opt_in=True), the form #12459 introduced for the pooled check. The grant itself is unchanged: the spec's tools allowlist still decides what is mounted. Fixes #12464
An opt-in Crew server (kirocrew-dashboard, kirocrew-work, kirocrew-crew-log, kirocrew-panel) granted by a spec on the kiro backend was mounted straight from the spec with no session-valued environment, and gatewayd handed the per-frame token only to kirocrew-core, kirocrew-cron and (since #12459) kirocrew-dashboard. Since the tool-policy read requires an attestation, every call on any other such server refused as identity_unattested, and on the kiro backend the dashboard itself still did. kiro_control_plane_servers now re-emits every IDENTITY_BOUND_SERVERS element the spec grants, so the token attach reaches them; CONTROL_PLANE_BACKENDS is the same set, read from the mcp_cleanup leaf. Both paths resolve a granted opt-in name with managed_mcp_spec_entry(name, include_opt_in=True), the form #12459 introduced for the pooled check. The grant itself is unchanged: the spec's tools allowlist still decides what is mounted. Fixes #12464
An opt-in Crew server (kirocrew-dashboard, kirocrew-work, kirocrew-crew-log, kirocrew-panel) granted by a spec on the kiro backend was mounted straight from the spec with no session-valued environment, and gatewayd handed the per-frame token only to kirocrew-core, kirocrew-cron and (since #12459) kirocrew-dashboard. Since the tool-policy read requires an attestation, every call on any other such server refused as identity_unattested, and on the kiro backend the dashboard itself still did. kiro_control_plane_servers now re-emits every IDENTITY_BOUND_SERVERS element the spec grants, so the token attach reaches them; CONTROL_PLANE_BACKENDS is the same set, read from the mcp_cleanup leaf. Both paths resolve a granted opt-in name with managed_mcp_spec_entry(name, include_opt_in=True), the form #12459 introduced for the pooled check. The grant itself is unchanged: the spec's tools allowlist still decides what is mounted. Fixes #12464
An opt-in Crew server (kirocrew-dashboard, kirocrew-work, kirocrew-crew-log, kirocrew-panel) granted by a spec on the kiro backend was mounted straight from the spec with no session-valued environment, and gatewayd handed the per-frame token only to kirocrew-core, kirocrew-cron and (since #12459) kirocrew-dashboard. Since the tool-policy read requires an attestation, every call on any other such server refused as identity_unattested, and on the kiro backend the dashboard itself still did. kiro_control_plane_servers now re-emits every IDENTITY_BOUND_SERVERS element the spec grants, so the token attach reaches them; CONTROL_PLANE_BACKENDS is the same set, read from the mcp_cleanup leaf. Both paths resolve a granted opt-in name with managed_mcp_spec_entry(name, include_opt_in=True), the form #12459 introduced for the pooled check. The grant itself is unchanged: the spec's tools allowlist still decides what is mounted. Fixes #12464
#12476) An opt-in Crew server (kirocrew-dashboard, kirocrew-work, kirocrew-crew-log, kirocrew-panel) granted by a spec on the kiro backend was mounted straight from the spec with no session-valued environment, and gatewayd handed the per-frame token only to kirocrew-core, kirocrew-cron and (since #12459) kirocrew-dashboard. Since the tool-policy read requires an attestation, every call on any other such server refused as identity_unattested, and on the kiro backend the dashboard itself still did. kiro_control_plane_servers now re-emits every IDENTITY_BOUND_SERVERS element the spec grants, so the token attach reaches them; CONTROL_PLANE_BACKENDS is the same set, read from the mcp_cleanup leaf. Both paths resolve a granted opt-in name with managed_mcp_spec_entry(name, include_opt_in=True), the form #12459 introduced for the pooled check. The grant itself is unchanged: the spec's tools allowlist still decides what is mounted. Fixes #12464 Co-authored-by: Nicholas Bowers <NicholasRBowers@users.noreply.github.com>
…ken (kirodotdev#12459) gatewayd forwards the per-session attestation token only to backends named in CONTROL_PLANE_BACKENDS, and that set named kirocrew-core and kirocrew-cron. kirocrew-dashboard is the third backend that posts back to the gateway for the calling session (session_create, session_send, the folder and tag tools), so a gatewayd-spawned dashboard backend, whose process ancestry ends at systemd instead of kiro-cli, had neither identity channel and every one of its tools answered "execution identity is unavailable". Two gates stood in the way. The set membership test returned False silently, so the missing name never produced a log line. And managed_mcp_spec_entry answered None for any opt_in entry, which the dashboard is, so adding the name alone only turned the silent refusal into a logged one. - add kirocrew-dashboard to CONTROL_PLANE_BACKENDS - managed_mcp_spec_entry(name, include_opt_in=True) resolves an opt_in entry's invocation for the control-plane check only; a closed spec_gate still yields None, and neither spec writer passes the flag - log the not-in-set exit at DEBUG so the two False exits are distinguishable - the denial warning no longer names two specific servers acp.session_mcp.CONTROL_PLANE_SERVERS is deliberately unchanged: it decides which servers every session mounts and which survive a disabledTools entry, so naming the dashboard there would make an operator's decision to switch its tools off unenforceable. The ratchet now pins containment instead of equality and requires every token-only extra to be a managed opt_in server.
kirodotdev#12476) An opt-in Crew server (kirocrew-dashboard, kirocrew-work, kirocrew-crew-log, kirocrew-panel) granted by a spec on the kiro backend was mounted straight from the spec with no session-valued environment, and gatewayd handed the per-frame token only to kirocrew-core, kirocrew-cron and (since kirodotdev#12459) kirocrew-dashboard. Since the tool-policy read requires an attestation, every call on any other such server refused as identity_unattested, and on the kiro backend the dashboard itself still did. kiro_control_plane_servers now re-emits every IDENTITY_BOUND_SERVERS element the spec grants, so the token attach reaches them; CONTROL_PLANE_BACKENDS is the same set, read from the mcp_cleanup leaf. Both paths resolve a granted opt-in name with managed_mcp_spec_entry(name, include_opt_in=True), the form kirodotdev#12459 introduced for the pooled check. The grant itself is unchanged: the spec's tools allowlist still decides what is mounted. Fixes kirodotdev#12464 Co-authored-by: Nicholas Bowers <NicholasRBowers@users.noreply.github.com>
kirodotdev#12476) An opt-in Crew server (kirocrew-dashboard, kirocrew-work, kirocrew-crew-log, kirocrew-panel) granted by a spec on the kiro backend was mounted straight from the spec with no session-valued environment, and gatewayd handed the per-frame token only to kirocrew-core, kirocrew-cron and (since kirodotdev#12459) kirocrew-dashboard. Since the tool-policy read requires an attestation, every call on any other such server refused as identity_unattested, and on the kiro backend the dashboard itself still did. kiro_control_plane_servers now re-emits every IDENTITY_BOUND_SERVERS element the spec grants, so the token attach reaches them; CONTROL_PLANE_BACKENDS is the same set, read from the mcp_cleanup leaf. Both paths resolve a granted opt-in name with managed_mcp_spec_entry(name, include_opt_in=True), the form kirodotdev#12459 introduced for the pooled check. The grant itself is unchanged: the spec's tools allowlist still decides what is mounted. Fixes kirodotdev#12464 Co-authored-by: Nicholas Bowers <NicholasRBowers@users.noreply.github.com>
Problem / Motivation
#12445 (the fix for issue #12441) classifies a 409 from the gateway as
identity_unattestedand refuses the call. The refusal rests on a stated premise (mcp_shared.py, beside the branch): a legitimate pooled backend never lands there, because the gateway daemon hands it the token per frame and the resolver sends it. The same block records that a legitimate call still reaches the neighbouringresolution_failedarm in this deployment, keeps that arm permissive until the reason is understood, and calls that reason a gateway-side question.kirocrew-dashboardis where the premise breaks. It posts back to the control plane for the calling session, and it is not inCONTROL_PLANE_BACKENDSinmcp_gateway/gatewayd.py. So the daemon never hands a gateway-pooled dashboard backend the token, every one of its control-plane calls answers 409, lands in theidentity_unattestedbranch, and is refused:session_create,session_send,session_read_message, thechat_folder_*andchat_tag_*tools all fail, on every call, and restarting the session does not help.Why it matters
Any agent that coordinates other sessions -- a conductor standing up workers, a session filing itself into a folder -- loses its whole control surface. This change is the gateway-side answer the
mcp_shared.pyblock asks for: with the dashboard in the set, the premise holds for every backend the set names, so the refuse verdict of #12445 hits only the callers it means to hit. The other conceivable remedy, lettingidentity_unattestedthrough, was rejected on main and becomes unnecessary once no legitimate call lands in that branch.What changed (motivation -> approach -> change)
mcp_gateway/gatewayd.pyCONTROL_PLANE_BACKENDSkirocrew-core,kirocrew-cronkirocrew-dashboardagent.pymanaged_mcp_spec_entry(name)Nonefor everyopt_inentryinclude_opt_in=Trueresolves an opt_in invocation; a closedspec_gatestill yieldsNone; the default is unchanged_spawns_own_control_planeFalseFalseplus one DEBUG line naming the backend_deny_control_planewarningkirocrew-core/kirocrew-crontest/test_mcp_gateway_stub_session_token.pyCONTROL_PLANE_SERVERSis contained inCONTROL_PLANE_BACKENDS; the token-only extras are pinned to exactlykirocrew-dashboard; every extra must be a managedopt_inserverdocs/architecture/mcp.md, token forwardingCONTROL_PLANE_SERVERSinclude_opt_inresolutionA backend that posts back to the gateway for the calling session must prove which session it acts for. The gateway accepts two proofs: the process ancestry of a Unix socket peer, or the per-session attestation token. A dashboard backend spawned by kiro-cli has kiro-cli in its ancestry, so it passes. A dashboard backend spawned by the gateway daemon has systemd in its ancestry, so only the token can name its session, and the daemon hands the token only to backends named in
CONTROL_PLANE_BACKENDS.That set named two backends.
kirocrew-dashboardalso posts back for the calling session, and it was not in the set. Two gates hid this. The membership test returnsFalsewithout logging, so the missing name left no trace. Andmanaged_mcp_spec_entryreturnedNonefor everyopt_inentry, which the dashboard is, so adding the name alone turns the silent refusal into a logged one (no managed spec entry resolves for this name).The fix adds the name and lets the control-plane check resolve an opt_in invocation. The check still compares the spawned binary by realpath and the argv exactly against that invocation, refuses any non-empty
PYTHON*variable in the child environment, and refuses an import root that shadowskiro_crew. Membership is a necessary condition; none of those fences moved. Theinclude_opt_inflag skips exactly one of the two emission disqualifiers: an opt_in server that is running was granted per agent, so its invocation is still the one to compare against; a closedspec_gatestill yieldsNone, because the gate exists to keep that backend unspawned and a spawn under its name must not be handed a token. Neither spec writer passes the flag, so no opt_in entry is emitted that the base does not emit.acp.session_mcp.CONTROL_PLANE_SERVERSis deliberately unchanged. It decides which servers every session mounts and which survive adisabledToolsentry (session_mcpsubtracts it from the disabled set). Naming the dashboard there would mount it in every session and make an operator's decision to switch its tools off unenforceable. The two constants answer different questions, so the ratchet that pinned them equal now pins containment, the exact token-only set (kirocrew-dashboard), and the opt_in property of every extra. The token-forwarding section ofdocs/architecture/mcp.mddescribes that relationship instead of the mirror it described before.Backwards compatibility
Compatible: the only backend whose behavior changes is a gateway-pooled
kirocrew-dashboard, which now receives the token it needs. A kiro-cli-spawned dashboard, every third-party backend, both spec writers and thedisabledToolshandling are unchanged.managed_mcp_spec_entrygains a keyword-only flag with the old default, and every existing caller passes no flag.Tests
test/test_mcp_gateway_stub_session_token.py, run with-n0: 95 passed, 1 skipped.CONTROL_PLANE_SERVERSis contained inCONTROL_PLANE_BACKENDS, the token-only extras equal exactlykirocrew-dashboard, and every extra is a managedopt_inserver. A new token recipient has to update the pin in the same commit that adds it; a typo'd or third-party name fails the property check even if someone edits the pin.managed_mcp_spec_entrywithinclude_opt_in=True. Every test double in the file swallows keywords, so dropping the argument at the call site would otherwise leave the dashboard unverifiable with the whole file still green.TestTokenOnlyControlPlane: the real dashboard invocation matches itself; the same invocation with a foreign binary, different argv or a non-emptyPYTHONPATHis denied and each denial names its reason;managed_mcp_spec_entry("kirocrew-dashboard")without the flag is stillNone; the flag keeps a closed or raisingspec_gateclosed on a synthetic entry, and the real dashboard is denied the token under a closed gate through the production path; a name outside the set logs one DEBUG line and no WARNING, while a reserved name that fails logs the WARNING and never the DEBUG line.Mutation check on the new tests: removing
kirocrew-dashboardfrom the set reddens 4; droppinginclude_opt_in=Trueat the call site reddens 3; making the flag skip thespec_gatecheck reddens 2; raising the DEBUG line to WARNING reddens 1; widening the exact pin by a second name reddens 1 (the ratchet, with its message).Manual verification
On a gateway restarted with this change,
session_createfrom a pooled dashboard backend succeeded 3 of 3 times where every call failed before, and the gateway log recorded 0 token rejections and 0 resolver refusals for that backend.Related Issues
Related: #12445 (the resolver now sends the caller token and refuses
identity_unattestedon the premise that a legitimate pooled backend is always handed the token; this PR makes that premise hold for the dashboard) and #12441 (the report that #12445 addressed; the dashboard half of the same symptom is handled here).no linked issue: the dashboard case was reproduced on a live gateway and has no issue of its own; this PR carries the analysis.
Pattern harvest
Rule candidate: review-prompt
Pattern: a membership test that returns False without logging makes a member missing from the set indistinguishable from an ordinary non-member, so an allowlist of trusted names should log its rejections at least at DEBUG.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)