Skip to content

docs(rfc): amend per-person r5 and r9 for connection grants - #38142

Merged
buluoray merged 2 commits into
mainfrom
crew/slack/rfc-per-person-r5-r9
Nov 19, 2026
Merged

buluoray merged 2 commits into
mainfrom
crew/slack/rfc-per-person-r5-r9

Conversation

@buluoray

@buluoray buluoray commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Amend R5 and R9 of the accepted per-person execution RFC so that each person in a shared Crew can hold their own Connection sign-in under its rules.

Per-person Connection tokens in #39049 (split out of the sign-in redesign in #38119) give each person in a shared Crew their own Connection token (Slack, GitHub and the other Crew-signed-in providers). It builds on this RFC, but two rules do not fit as written:

  • R5 says the Crew never reads a person's credentials, with no exception. A Connection token is issued to the Crew's own OAuth app; the gateway runs its flow and its proxy is the only thing that adds it to a call. Keeping it in the person's home would put the token inside their runtime account, and Slack's refresh needs the app's client secret, so the gateway would see every refreshed token anyway.
  • R9 names cron jobs and channel answers. A Bot's own wake (patrol, check-in) can spend a person's token with no person sending, and needs the same consent.

Why it matters

Without these two amendments, the per-person design in #39049 either breaks R5 or keeps one shared token that every person's chat borrows, and a Bot wake could spend someone's token with no consent check.

Not a goal

  • No code.
  • No change to the RFC's status, author, other rules (R1 to R4, R6 to R11), roles, phases or decisions.
  • No change to how the Crew treats a person's own credentials (model login, cloud or ssh keys): it still never reads them.

What changed (motivation → approach → change)

  • R5 gains one sentence: a grant issued to the Crew's own OAuth app for a person is held by the gateway, used only in that person's runs, and never enters their runtime.
  • R9 names a Bot's own wake next to cron jobs and channel answers, checked against everyone who shaped the job or the Bot.
  • §3, §5 and §10 phase 3 follow the R9 change: a "Bot's own wake" row, Bots record creator and editors like cron jobs, and phase 3 covers Bot wakes. R5 also cites R11. §14 asks the UI to name the per-person Connection tokens among what the host owner can read.
  • A new §15 Amendments records what changed, why and what does not, in the decision-log style other RFCs here use. The header's status list and the README index row point at it.

Agreement. Proposed by @buluoray on 2026-11-16. It takes effect with an approving review by @bolichen97, the RFC's author; this PR waits for that review.

Backwards compatibility

Compatible: documentation only; nothing main accepts today changes.

Removes nothing: the change adds sentences to two rules and one section.

Tests

N/A — documentation only. scripts/docs-lint.sh passes.

Manual verification

N/A — no behaviour changes.

Related Issues

Part of #27006. Follows #38119; needed by #39049.

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.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners November 16, 2026 22:38
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 16, 2026
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 49037e011e9a1083f4b52aafd8ceba775558149c 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 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 49037e011e9a1083f4b52aafd8ceba775558149c ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: this is a documentation-only amendment to an RFC, it is consistent with its own sections, and it removes nothing.

Notes

[DESIGN-REVIEWED] 49037e0

Description read

[DESCRIPTION-READ] d35cb4d77c5a514bdbd86fa634e8607cbb895aa8f15108eb5b9d458e606cdd9b

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 49037e0

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

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

buluoray added a commit that referenced this pull request Nov 16, 2026
Mark open question 3's three points as ruled on 2026-11-16 and point
the R5 and R9 amendments, and phase 5b, at #38142.
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 49037e0

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

buluoray added a commit that referenced this pull request Nov 16, 2026
Mark open question 3's three points as ruled on 2026-11-16 and point
the R5 and R9 amendments, and phase 5b, at #38142. Let the owner,
tailnet collaborators and Kiro relay teammates each Connect, cancel,
paste and Disconnect their own sign-in, keyed by their own Principal,
since a relay teammate is not a collaborator. The relayed owner keeps
the owner's grant because no Connection route asks for local_operator
provenance.
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 16, 2026
buluoray added a commit that referenced this pull request Nov 17, 2026
Mark open question 3's three points as ruled on 2026-11-16 and point
the R5 and R9 amendments, and phase 5b, at #38142. Let the owner,
tailnet collaborators and Kiro relay teammates each Connect, cancel,
paste and Disconnect their own sign-in, keyed by their own Principal,
since a relay teammate is not a collaborator. The relayed owner keeps
the owner's grant because no Connection route asks for local_operator
provenance.
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 18, 2026
@buluoray
buluoray force-pushed the crew/slack/rfc-per-person-r5-r9 branch from 407cda0 to 13656a1 Compare November 18, 2026 00:08
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 18, 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 review found no blocking issues on 13656a1. The diff changes two markdown files under docs/request-for-change/ and no code. PR Readiness passed on this head. The link to rfc-crew-owned-oauth.md resolves, and its §3 supports the claim that only the gateway proxy adds the Connection token. One thing done well: §15 says what changed, why, and what stays the same, and it keeps the promise that the person's own model, cloud and ssh credentials are never read.

The amendment changes R5 (credential custody) and R9 (consent) of an accepted RFC. §15 says the RFC author's agreement is recorded by approving this pull request, and there is no review on this head yet. It should merge only after that approval. It may read best if it lands after #38119, or together with it, since the rationale points at that draft.

Optional:

  • R9 now covers a Bot's own wake, but §3 (no Bot wake row), §5 (only cron jobs record creator and editors) and the §10 phase 3 row still cover only cron. Consider naming where "who shaped the Bot" is recorded, or saying in §15 that this is deferred to docs(rfc): redesign the crew-owned mcp sign-in flow #38119.
  • §14 now asks the UI to name the per person Connection tokens the host owner can read. §15 and "What changed" do not list this change.
  • R5 could cite R11 next to R7 and R9, since R11's run-as account check is what keeps one person's token out of another person's run.

@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 18, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

Thanks. All three optional notes from the review of 13656a1 are fixed in cc3e10b:

  • Bot wake beyond R9: §3 gains a "Bot's own wake" row. §5 records a Bot's creator and editors the way it records a cron job's. Phase 3 in §10 now covers Bot wakes next to cron jobs.
  • §14 change not listed: §15 and the PR's "What changed" now list the §14 note about the per-person Connection tokens the host owner can read.
  • R5 and R11: R5 now cites R11 next to R7 and R9.

§15 lists each of these changes. The merge still waits for the maintainer's design sign-off and the RFC author's approval. The intended order is unchanged: this lands after #38119, or together with it.

@buluoray
buluoray force-pushed the crew/slack/rfc-per-person-r5-r9 branch from cc3e10b to 84c7676 Compare November 18, 2026 05:31
@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 18, 2026
@KiroCrewCaptain

KiroCrewCaptain commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, but it is held at tier 2: design-doc-gate: D.

Docs-only amendment to the accepted per-person execution RFC. R5 gains a narrow exception: a Connection token issued to the Crew's own OAuth app is held by the gateway, used only in that person's runs and never put in their runtime. This matches the existing Connection proxy design in rfc-crew-owned-oauth §3, where the gateway proxy adds the token over a peer-uid-checked socket. R9 extends consent checks to a Bot's own wake, with matching edits in §3, §5 and §10. §14 now names the tokens among what the host owner can read, and a new §15 records the amendment. The text is internally consistent and the trust boundary stays sound under run-as. No repository rule forbids amending an accepted RFC in place, and other RFCs carry dated in-place amendments. CI is green.

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 49037e011e · 61 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

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

Review of 84c7676858 against main d71da6862d. Docs-only amendment of an accepted RFC; I read the diff, the Captain review of 13656a12d1, the author's reply, the code-change-approver note on this head and the AI lanes (all PASS / no findings).

What holds

  • The three optional notes from the Captain's earlier review are fixed on this head: §3 has a "Bot's own wake" row, §5 records a Bot's creator and editors, phase 3 in §10 covers Bot wakes, R5 cites R11, and §15 lists the §14 note.
  • R11 (peer uid must equal the run-as account, docs/request-for-change/rfc-per-person-execution.md:178-182) does support "used only in that person's runs".
  • The R9 change only adds consent checks, so it narrows.
  • The R5 carve-out is narrow: it covers only grants issued to the Crew's own OAuth app, and keeps model logins and cloud or ssh keys unreadable.

Input before acceptance

  1. §15 should name who agreed, accurately. It says "Agreed by the repository owner (buluoray); the author's agreement is recorded by approving the pull request." The RFC's frontmatter says author: bolichen (rfc-per-person-execution.md:4), and the README row says it was accepted by the maintainer @bolichen97. So the agreement that makes this amendment binding is the RFC author's and a maintainer's. Please name the proposer (buluoray) and the agreeing maintainer by handle, and link the approving review, without a role title.
  2. It amends an accepted RFC to fit two drafts. The rationale rests on #38119 (draft) and on rfc-crew-owned-oauth.md, which is still status: draft (docs/request-for-change/rfc-crew-owned-oauth.md:3). If #38119's per-person token section changes or is split out, R5 would carry a carve-out with no design behind it. Merge this with #38119, or after it is accepted, as the author already proposes.
  3. Nit: the reflowed §5 paragraph has a line well over the file's wrap width ("moment. Revoking consent stops jobs and Bots already saved. Every use ...").

The substance is sound and I have no blocking finding. The amendment changes the custody rule of an accepted RFC, so the decision is a maintainer's.

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

@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 18, 2026
@buluoray
buluoray force-pushed the crew/slack/rfc-per-person-r5-r9 branch from 84c7676 to 89c2871 Compare November 18, 2026 08:46
@buluoray

Copy link
Copy Markdown
Contributor Author

Thanks, @bolichen97. Here is what changed in 89c2871:

  1. Who agreed. §15 now names @buluoray as the proposer, links this pull request, and says the amendment takes effect with your approving review as the RFC's author. It uses no role titles. The PR body says the same.
  2. Order. Agreed: this stays held until docs(rfc): redesign the crew-owned mcp sign-in flow #38119 is accepted, or lands with it. The rationale in §15 now points at docs(rfc): propose per-person connection tokens in a shared crew #39049, where the per-person token design moved after your review of docs(rfc): redesign the crew-owned mcp sign-in flow #38119.
  3. Line wrap. The §5 paragraph is rewrapped.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Nov 18, 2026
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.
…ections 3, 5 and 10, and list every change in section 15
@buluoray
buluoray force-pushed the crew/slack/rfc-per-person-r5-r9 branch from 89c2871 to 49037e0 Compare November 18, 2026 18:41
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 18, 2026

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

Agreement from @bolichen97, the per-person execution RFC's author, on 49037e0: the R5 and R9 amendments are accepted. R5's carve-out covers only grants issued to the Crew's own OAuth app, used only in that person's runs (R11); model logins and cloud or ssh keys stay unreadable. R9 only adds consent checks. This amendment rests on #39049, accepted above, and should merge after it.

AI-assisted, sent by Bolin Review bot at @bolichen97's direction

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Nov 19, 2026
@buluoray
buluoray merged commit bf34370 into main Nov 19, 2026
100 checks passed
@buluoray
buluoray deleted the crew/slack/rfc-per-person-r5-r9 branch November 19, 2026 10:35
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 19, 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.

3 participants