feat(tools/git): grant-reviewer.sh org-team reviewer grant with fail-closed read-back (#1415)

Conversation 2 Commits 2 Files Changed 5

+969 -1

2 Commits

Author	SHA1	Message	Date
veronica	b023b1a4dc	docs(tools): index grant-reviewer.sh in TOOLS.md and TOOLS-REFERENCE.md (#1415 ) ci/woodpecker/pr/ci Pipeline was successful Details Review finding B1 on PR #1417: the tool shipped without an index entry, so check-tools-index.sh failed (git suite 29/30) and pipeline 2659 went terminal-red at sanitization. Adds the suite row note in defaults/TOOLS.md and an Access grants table in guides/TOOLS-REFERENCE.md, both naming the official-approval limitation. check-tools-index.sh now rc=0 (git 30/30); format:check and the enumeration guard stay green.	2026-08-24 21:10:54 -05:00
veronica	deb4760b11	feat(tools/git): add grant-reviewer.sh org-team reviewer grant with fail-closed read-back (#1415 ) ci/woodpecker/pr/ci Pipeline failed Details Port the operator-tree grant-reviewer tool into the framework suite. grant-reviewer.sh -u <user> [-r <owner>/<repo>] [-t <team>] grants a reviewer code-read plus issues/pulls-write on an org-owned Gitea repository via an org team (default fleet-reviewers). Gitea only; on a GitHub remote it refuses with a clear error. Idempotent: exact-name team lookup before create (permission read, units_map: code read, issues write, pulls write); member and repo additions are idempotent puts. Fail-closed read-back: after the writes, the single member resource and the single team-repo resource are both fetched back and must confirm the grant or the run fails — a success status is an exit code, not evidence of a durable write (#865 defect class). HTTP 403 on any step surfaces as 'org admin required on <org>', never a silent partial grant. Identity follows issue-comment.sh: GITEA_LOGIN names a tea login whose host-matched token MUST resolve (fail closed, no downgrade to the host default); otherwise the detect-platform.sh identity ladder applies. The bearer token travels via a curl config file, never argv. Documented limitation (field finding, usc/infrastructure PR 273): under branch protection with required approvals, reviews from a read-permission team are official=false and do not count toward the required total; whitelisting the team on the protected branch is an operator review-policy decision this script deliberately does not automate, and official is computed at review submission. Hermetic suite test-grant-reviewer.sh models a real server with persistent on-disk state, exact-payload validation, a substring-named decoy team, write-without-persist sabotage modes, identity-per-request assertions, and token-not-in-argv plus temp-leak checks; enumerated in test:framework-shell.	2026-08-24 20:45:43 -05:00

Author

SHA1

Message

Date

veronica

b023b1a4dc

docs(tools): index grant-reviewer.sh in TOOLS.md and TOOLS-REFERENCE.md (#1415 )

ci/woodpecker/pr/ci Pipeline was successful

Details

Review finding B1 on PR #1417: the tool shipped without an index entry, so
check-tools-index.sh failed (git suite 29/30) and pipeline 2659 went
terminal-red at sanitization. Adds the suite row note in defaults/TOOLS.md
and an Access grants table in guides/TOOLS-REFERENCE.md, both naming the
official-approval limitation. check-tools-index.sh now rc=0 (git 30/30);
format:check and the enumeration guard stay green.

2026-08-24 21:10:54 -05:00

veronica

deb4760b11

feat(tools/git): add grant-reviewer.sh org-team reviewer grant with fail-closed read-back (#1415 )

ci/woodpecker/pr/ci Pipeline failed

Details

Port the operator-tree grant-reviewer tool into the framework suite.
grant-reviewer.sh -u <user> [-r <owner>/<repo>] [-t <team>] grants a
reviewer code-read plus issues/pulls-write on an org-owned Gitea
repository via an org team (default fleet-reviewers). Gitea only; on a
GitHub remote it refuses with a clear error.

Idempotent: exact-name team lookup before create (permission read,
units_map: code read, issues write, pulls write); member and repo
additions are idempotent puts. Fail-closed read-back: after the writes,
the single member resource and the single team-repo resource are both
fetched back and must confirm the grant or the run fails — a success
status is an exit code, not evidence of a durable write (#865 defect
class). HTTP 403 on any step surfaces as 'org admin required on <org>',
never a silent partial grant.

Identity follows issue-comment.sh: GITEA_LOGIN names a tea login whose
host-matched token MUST resolve (fail closed, no downgrade to the host
default); otherwise the detect-platform.sh identity ladder applies. The
bearer token travels via a curl config file, never argv.

Documented limitation (field finding, usc/infrastructure PR 273): under
branch protection with required approvals, reviews from a
read-permission team are official=false and do not count toward the
required total; whitelisting the team on the protected branch is an
operator review-policy decision this script deliberately does not
automate, and official is computed at review submission.

Hermetic suite test-grant-reviewer.sh models a real server with
persistent on-disk state, exact-payload validation, a substring-named
decoy team, write-without-persist sabotage modes, identity-per-request
assertions, and token-not-in-argv plus temp-leak checks; enumerated in
test:framework-shell.

2026-08-24 20:45:43 -05:00

feat(tools/git): grant-reviewer.sh org-team reviewer grant with fail-closed read-back (#1415) #1417