Repository navigation
docs(rfc): redesign the crew-owned mcp sign-in flow - #38119
Conversation
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS A docs-only draft RFC with nothing irreversible in it. Each fix reuses an existing seam: Notes
[DESIGN-REVIEWED] 1969650 Description read[DESCRIPTION-READ] 57f559aedcb3f5c15ea491bf16b72a24ea9224d35cb24cb435439464bbfe0ca2 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 |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Review detailsNo findings. This PR only adds an RFC and an index row, so no code path changes. None of the candidate inconsistencies in the draft has an outcome that reaches a user, an operator, data or a security boundary. Notes:
[OPUS-REVIEWED] 1969650 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
d99f502 to
62399f2
Compare
b2d2b97 to
4635e70
Compare
8574b29 to
d345902
Compare
Code change approver recommendation: A person should decideWhy: the decider estimates an 8% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 612 lines, more than the 400 it may approve on its own. Docs-only draft RFC plus one README index row. Code claims I spot-checked hold: the sign-in-off slugs, live-session marks, grant fingerprint, off-dashboard codes, public origin and browser-open helpers all exist; Slack's registry smoke_fixture is slack_read_user_profile; the relay route exists. The trust design holds up. The one-click enable uses the same setPreviewFlag persister and route as the Settings row, so it gets the same gate. The /reachable probe stays on the existing loopback listener while a sign-in is pending, and the Security section lists its one leak. The agent only shows the card and never sees a secret, code or token. Per-person tokens are moved out of scope. CI and the review lanes are green. The remaining issues are wording drift and don't block. Tier: 2, held for a person: design-doc-gate: D. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
|
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. Review result: this is a docs-only draft RFC plus one row in the request-for-change index. There is no code or test change. PR Readiness is green on this head. No blocking finding came out of the review. We spot-checked the RFC's current-state claims against the commit it was audited at, and they hold: the order of Optional:
|
R5 now names a grant issued to the Crew's own OAuth app for a person as gateway-held, used only in that person's runs and never in their runtime. R9 names a Bot's own wake next to cron jobs and channel answers. Both come from the per-person sign-in design in #38119.
R5 now names a grant issued to the Crew's own OAuth app for a person as gateway-held, used only in that person's runs and never in their runtime. R9 names a Bot's own wake next to cron jobs and channel answers. Both come from the per-person sign-in design in #38119.
bolichen97
left a comment
There was a problem hiding this comment.
Review of d34590201f against main d71da6862d. Docs-only draft RFC; I read the full text, the Captain review, the code-change-approver note and the AI lanes (all PASS; Opus left one note).
What holds on main: _crew_sign_in_off_slugs (src/kiro_crew/connections/status.py:618), callback_port_busy (src/kiro_crew/connections/crew_oauth.py:802), holds_grant / token_entry_name (crew_oauth.py:472, :486), _public_origin (src/kiro_crew/connections/crew_oauth_dcr.py:62), _connection_grant_fingerprint (src/kiro_crew/dashboard/change_cards_readers.py:1011), _OFF_DASHBOARD_CODES (src/kiro_crew/mcp_guide.py:106), _browser_open_supported (src/kiro_crew/cloud/connect.py:500) and the Slack redirect localhost:48106 (src/kiro_crew/connections/registry.json:40).
1. "Owner-only today" is stale on current main (re-audit needed). The Captain and the Opus lane disagree on this. Both were right at different commits. Since #38437 (a1ac53ec4f, 2026-11-17), is_owner_dashboard_request also admits a Shared Crew teammate through teammate_passes_owner_gate (src/kiro_crew/dashboard/handlers/source_providers.py:976-987, src/kiro_crew/shared_crew/teammate_access.py:225-227). Mint (src/kiro_crew/dashboard/handlers/connections.py:556), relay (:270), cancel (:851) and the OAuth client save (:1472) all use that gate. is_owner_only_for_teammates (teammate_access.py:119-133) does not list them. I evaluated it on main: it returns False for POST /api/connections/mint and POST /api/mcp/oauth/relay. So on main a teammate can already start a sign-in for the Crew's one shared grant, and that grant then serves everyone. Three consequences for the RFC:
- §7.4 "Who may start a sign-in", Backward compatibility and Security ("widens who may call them") should say Phase 5a narrows each call to the caller's own principal. It does not open the routes.
- The single-grant borrowing the RFC wants to close is reachable now, not only after Phase 5a. The maintainer may want a stop-gap (add the mint, relay and client-save routes to the teammate owner-only set) before 5a lands.
- "Saving it keeps today's gate" for the OAuth app now means teammates can replace the Client Secret. Please say whether that is intended.
Please bump audited-at to current main after the re-audit.
2. Scope. I agree with the Captain: §7.4 and Phases 5a/5b are a custody and identity change (vault key, proxy lookup, approvals). The Goal and "Not a goal" exclude those areas. Phase 6 (chat card) now depends on 5a. Splitting §7.4 into a companion RFC beside #38142 would let Phases 0–5 be signed on their own merits.
3. Decisions recorded in the RFC. Open question 3 and §7.4 record rulings "by the repository owner" made by the RFC's own author. A maintainer should confirm those rulings in the sign-off, so the record does not rest on the author alone.
Open questions
- Q1 one-click enable: agree, if it reuses
setPreviewFlagbehind the same gate and never flips the previews main switch or an edition lock. Given point 1, the same gate now admits teammates. Say whether a teammate may flip it. - Q2 gateway-raised card: agree, with the one-per-chat-provider-person bound and dashboard turns only.
- Q4 expiry warning: 3 days is fine; key it on
refresh_lifetime_daysas proposed. - Q5
/reachable: acceptable. One false "local" case: the person's own laptop runs a Crew with a pending sign-in on 48106. Signal 2 (non-loopback dashboard host) should win over the probe when they disagree. - Q6 https return: agree to defer until after Phases 1–7.
- Section 6 (Connected means it works):
tools/listproves the token authenticates, not that the scopes work. Slack can list tools and still answermissing_scopeon a call. The registry already carries a read-onlysmoke_fixture(slack_read_user_profile,registry.json:40), which Test uses. Consider running that one read call as the post-grant check, or explain whytools/listis enough. - Q9 prefilled link: agree, Copy manifest only.
- Q10 departed person: tie token delete and revoke to invite revocation in Phase 5a. It needs no roles, and otherwise a revoked person's token stays in the vault for up to 30 days.
No blocking defect in the text; point 1 is a factual correction with security weight.
A Kiro Crew team member must sign off on this design before it merges. This review does not approve it.
AI-assisted, sent by Bolin Review bot
Propose fixes for seven problems seen setting up Slack through Settings > Connections on a remote gateway: the hidden preview switch, the five-step Slack app, a lost consent pop-up, the failed-looking return page, jargon on the paste box, Connected before a working call, and no way to connect from inside a chat. In a shared Crew each person connects their own account, built on rfc-per-person-execution. Changes no code.
d345902 to
683d7f0
Compare
|
Thanks, @bolichen97. Here is what changed in 683d7f0 (rebased on main and re-audited at
|
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Thanks for the careful current-state audit. Most claims match main down to the symbol. One point needs a fix before a maintainer can decide section 2 and Phase 3.
docs/request-for-change/rfc-crew-oauth-sign-in-redesign.md:199(also lines 219-221, 564-565 and Q9 at 604-605). Section 2 designs a new registry-driven Slack manifest generator (app_manifest: "slack",redirect_urls_extra). It also says a prefilled create link "is not documented by Slack" and is "not built", and Q9 recommends Copy manifest only. Main already has both.src/kiro_crew/slack_manifest.pyis the single source for the Slack app manifest. Itsdeep_link()returnshttps://api.slack.com/apps?new_app=1&manifest_yaml=<encoded>.kirocrew manifestandGET /api/slack/manifestserve that link, and the exfil redactor exempts only that exact rebuilt link. Open PR #38169 adds the MCP redirect (localhost:48106/callback),pkce_enabledand the Slack MCP user scopes to that same manifest. The RFC names neither. Trigger: a maintainer decides section 2, Q9 and Phase 3 from the RFC as written. Outcome: two parallel designs for one Slack MCP manifest, and a second generator whose deep link the redactor would block. Smallest fix: add a current-state bullet that namesslack_manifest.pyand its shipped deep link, and name #38169. Then choose one path: extend that generator for a no-bot Connections shape, or defer to #38169's one-app design. Drop theapp_manifestfield if it is no longer needed, and restate Q9 and the Alternatives bullet.
Optional notes (not required for this round):
- Section 6 (around line 364) has the gateway send a
tools/callforsmoke_fixtureafter the grant and calls it "the same call Test uses". On main, Test never readssmoke_fixtureand is refused for Crew-owned slugs (crew_oauth_test_unsupported). The Connections spec ("The sweep never calls a tool") rules out a gateway-madetools/call, because it skips the policy and profile ceiling and the SEL record. Either route the call through the governed gate, or stop attools/listand check the granted scopes. Then align the Phase 5 exit criterion. - The Security line around 527 says only the person who pressed Connect gets the consent URL. In a Shared Crew, any admitted teammate can read the pending URL from
GET /api/connections/mint. Consider narrowing the sentence and pointing to #39049. - Section 7.3's gateway-raised card has a simpler option that the RFC does not weigh: the proxy's
needs_authrefusal text could nameconnection.connectand the slug. Listing it as an alternative would let Q2 compare the two.
683d7f0 to
17035c9
Compare
|
Thanks for the review of 683d7f0. These changes are in 17035c9:
@bolichen97, your note was "Connected only after a real read call". The governed route above is meant to keep that without the ungoverned |
17035c9 to
1969650
Compare
|
Update in 1969650. This replaces the section 6 design in my previous comment.
@bolichen97, your "Connected only after a real read call" note became a granted-scope check. The gateway never calls a tool on its own, because that call would skip the tool approval and the security log ( |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Re-review of 1969650 after my change request on 683d7f0. This PR is a docs-only draft RFC plus one README index row. PR Readiness is green on this head, and both AI review lanes report no blocking findings.
Earlier items:
- Section 2, the Slack manifest (the blocking item): fixed. Current state names
slack_manifest.pyand itsdeep_link(). Section 2 builds no second generator.app_manifestandredirect_urls_extraare gone. Phase 3 waits for #38169, and Q9 and the Alternatives bullet now match. - Optional note on the
smoke_fixturecall: fixed. Section 6 now makes no tool call. It checkstools/list, thesmoke_fixturename and the granted scopes. - Optional note on the consent URL: fixed. The Security line now says any admitted teammate can read a pending URL, and it points to #39049.
- Optional note on the
needs_authalternative: fixed. It is listed under Alternatives, and Q2 points to it.
The review checked the RFC's code claims against main: _crew_sign_in_off_slugs, crewSignInSetup, startMint opening the tab before its first await, _OFF_DASHBOARD_CODES, _connection_grant_fingerprint, tokens_from_response and slack_manifest.deep_link are all where the RFC says. No blocking repository rule matches the two changed files. One strength: the RFC reuses the existing connection.connect card kind and the shipped manifest link instead of adding parallel paths. It also refuses a gateway-side tools/call because that call would skip the tool approval and the SEL record.
The design is signed off under the standing maintainer sign-off for changes by team members.
Optional:
- Section 6 keeps a pair stored after a failed check. On main,
_classifyinconnections/status.pyreturns Connected whenever a grant is held, and the card'sprobeIndicatesConnectedreadsgrantPresent. Consider saying how a failed check reachesholds_grantandgrantPresent(for example, anunprovenmark stored with the pair). Also add those readers to the Phase 5 list, so the exit criterion at line 491 holds. - The Security line at 546-547 says the relay "delivers only into a sign-in the same person started". On main the relay has no per-person binding. Consider "delivers only into the gateway's own pending loopback listener", with #39049 for the per-person binding.
- Some per-person wording stayed after the split: line 447 ("for you"), lines 466-469 ("that person's grant"), and lines 461 and 551-552 ("per chat, provider and person"). Q2 at line 607 says "per chat and provider". Consider using the one-grant form here and leaving the per-person form to #39049.
R5 now names a grant issued to the Crew's own OAuth app for a person as gateway-held, used only in that person's runs and never in their runtime. R9 names a Bot's own wake next to cron jobs and channel answers. Both come from the per-person sign-in design in #38119.
* docs(rfc): amend per-person r5 and r9 for connection grants R5 now names a grant issued to the Crew's own OAuth app for a person as gateway-held, used only in that person's runs and never in their runtime. R9 names a Bot's own wake next to cron jobs and channel answers. Both come from the per-person sign-in design in #38119. * docs(rfc): fix the unchanged-rules list, carry the Bot wake through sections 3, 5 and 10, and list every change in section 15
Problem / Motivation
Goal: Propose a design that lets a person connect Slack (and the other Crew-signed-in providers) from the card or from chat, on a local or a remote gateway, without hidden settings, jargon or a false "Connected".
Setting up Slack through Settings → Connections on a remote gateway (a server with no browser, reached from a laptop) hit seven problems: the Connect button hides behind a preview switch on another page; making the Slack app takes five places; Connect can look like it did nothing; after Allow the browser says "This site can't be reached"; the paste box is labelled "Return address"; the card said Connected but the first tool call failed; and an agent that needs a connection can only send the person to Settings.
Why it matters
Every new Slack user meets these on first use, and every remote-gateway user meets the "can't be reached" page on every sign-in. A Connected badge that is not true sends people to debug the wrong thing.
Not a goal
rfc-crew-owned-oauth.md).What changed (motivation → approach → change)
docs/request-for-change/rfc-crew-oauth-sign-in-redesign.md(status: draft). It reads main at3c9f33cdc80(re-audited at224959b4ade) and designs one fix per problem: a one-click enable on the card, a Create the Slack app button that reuses the shippedslack_manifest.pydeep link, with the MCP fields that feat(slack): opt-in Slack MCP switch in the generated app manifest #38169 adds, a primary consent button for a refused tab, remote detection before Connect with the paste box open at once, an optional https return for gateways with an httpsdashboard.url, plain wording, a post-granttools/listand a check that the token holds every needed scope before Connected (no tool call) plus live-session refresh, and the existingconnection.connectchange card extended so the agent (or the gateway, onneeds_auth) can show the Connect card in chat. The agent only shows the card; it never sees a secret, code or token, and only a person's own click starts their sign-in.docs/request-for-change/README.md.slack_manifest.pyand defers the MCP fields to feat(slack): opt-in Slack MCP switch in the generated app manifest #38169. Q9 is answered. Accepted from review: Connected also waits for the granted scopes to match the registry's (section 6; no tool call, because the gateway never calls a tool on its own), and the dashboard origin wins over the probe when they disagree (section 4.1).Backwards compatibility
Compatible: documentation only; nothing main accepts today changes.
Removes nothing: the PR adds two documentation lines and a new file.
Tests
N/A — documentation only.
scripts/docs-lint.shpasses.Manual verification
N/A — no behaviour changes. Every code claim in the RFC was read at
3c9f33cdc80.Related Issues
None. Follows #34811.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license.