Read-only Team grants: pull and triage mint a read-tier token (0.11.0)

[immakermatty]

Why

An Organization wants roles by GitHub rights. Regular people and the Team Environment get read-only access to some repositories, for example the knowledge base, planning data or the Organization root. Only owners write, from their own Environments under their own GitHub accounts. Agents without write propose changes as issues instead of pull requests.

Until now the broker minted a token only when the Workspace's Team held a push, maintain or admin grant on the repository. A pull or triage grant was refused as 403 team_grant_missing. So the moment an Organization lowered a Team to read, that Team Environment lost the repository completely: no clone, no pull, no issues. This PR makes read grants work. It also lets write-capable Environments open issues once the Organization accepts the permission, for the escalation issues the Lazurio Folder asks for.

Target behaviour

On every mint, the live Team grant selects the tier. Policy schema v3 does not change and names no tier.

Live Team grant	Tier	Token asks for (GitHub adds metadata: read)	With the policy's issues: write declared
push, maintain, admin	write	actions: write, checks: read, contents: write, members: read (new), pull_requests: write (+ workflows: write if declared)	+ issues: write
pull, triage	read (new)	actions: read, checks: read, contents: read, members: read, pull_requests: read	+ issues: write
none, Team missing or drifted, foreign owner	refused: unchanged	nothing: 403 team_grant_missing / repository_denied	nothing

• Read tier: no write except the optional issues: write. There is no contents, pull request, Checks, Actions or workflow write. People in a read-only Environment can list and view pull requests, check runs and GitHub Actions workflow runs.
• Why actions: read. gh pr checks and gh pr list/view --json statusCheckRollup (which T3's pull request panel uses) read the workflow run behind each Actions check. That field is Actions data, so without actions: read those views could fail on repositories whose CI runs in GitHub Actions. This repository originally added actions: read to tokens (commit 8454be9) for the same reason. Honest scope: actions: read also lets the token read that repository's workflow run logs and artifacts, as a person with read access can.
• Both tiers read Organization membership (members: read). The Lazurio Folder (LazurioPlatform#198) tells an agent without write to mention the Organization Owners in its proposal issue, found with gh api "orgs/<org>/members?role=admin". A live check from a Team Environment with today's write-tier token (no members) got 200 [] for that list and for repos/<repo>/collaborators (GitHub's accepted-permission headers: members=read and metadata=read; the collaborator list is filtered empty), so the agent silently found nobody. The installation already holds members: read (the Team gate requires it), so this needs no new App permission or acceptance. It reads the Organization's members and Teams, as any member can; it changes nothing.
• Write tier otherwise unchanged unless the policy declares issues: write. Then it also asks for issues: write, so write-capable Environments can open escalation issues. workflows: write stays write-tier only.
• triage maps to the same read tier as pull. Pull request triage would need pull_requests: write, which also lets a token open and edit pull requests. An Environment without write access proposes through issues, so the tier stays minimal. Issue triage comes with issues: write anyway (next point).
• Honest scope of issues: write. It is GitHub's smallest installation permission that can open an issue, and GitHub has no create-only variant. The same permission also lets the token edit, label, close, reopen and comment on existing issues of that repository. The docs and the AGENTS invariant say so explicitly, as they already do for actions: write.
• Response. POST /v1/token adds "access": "read" | "write". The change is additive.
• Readback. policy check (offline) prints the exact permission set each tier asks for under the policy. policy check --live lists read and triage grants too, with an ACCESS column and a (W write, R read) summary.
• No default tier. mintToken(policy, repositoryId, access) requires the tier and fails before any GitHub call without it, so a lost tier can never become the write set. The handler also checks that the minted tier equals the verified one.

Adapter (brokered-gh / credential helper)

• No tier-based refusals. The allow-list refuses nothing up front by tier. Only auth, alias, config, extension, search, --show-token and host overrides are denied, as before. Official gh runs with whatever token the broker minted, and GitHub decides.
• Clone, fetch and pull work. With a read-tier token, git clone/fetch/pull go through the credential helper. The helper lives in the Workspace image and only uses requestGitHubAppToken().token, so it needs no change.
• Reads work. gh repo view, gh api reads, gh pr list, gh pr view, gh pr checks and gh run view work, and so does gh issue create where declared.
• Pushes fail with GitHub's error. A git push fails with GitHub's own 403.
• Failed gh commands get a conditional explanation. Any failed gh command under the read tier keeps gh's own error and exit code; nothing is pre-blocked. The adapter cannot tell a refusal from a bad argument or an outage, so it adds one conditional stderr line: "Lazurio for GitHub: this Team Environment has read access to OWNER/REPO. If GitHub refused a change above (a push, pull request or other write), that is the reason; any other error above is GitHub's own. A change can be proposed in an issue (gh issue create) once the Organization has accepted the app's Issues permission, or by someone with write access." Tests cover a refused write and an unrelated failed read.
• Discovery inside a checkout now succeeds for a read-only repository.
• requestGitHubAppToken returns access. A missing value means write, because older brokers mint only that tier. Any other value is an invalid response.

What does not change

• Write tier, apart from members: read and, when declared, issues: write. The rest of the broker is also unchanged: the workflows: write opt-in, the probe (members: read + metadata: read), the request budget, the error codes, and POST /v1/workspace.
• Policy schema v3. installation_permissions.issues: write is just another accepted-permission declaration, like workflows: write.
• Public repositories without a Team grant are still refused. I checked that GitHub's Team-repository endpoint answers 404 for a Team without a grant even on a public repository.

App-permission prerequisite (only for issues, either tier)

Yes, an App change is needed for issues. The Lazurio for GitHub App currently requests no issues permission (public GET /apps/lazurio-for-github: actions, administration, checks, contents, emails, members, metadata, pull_requests, workflows). Without it, both tiers work as described minus issue creation, and the write tier mints exactly what it minted before.

1. Once: an App owner adds Repository permissions → Issues: Read and write. GitHub then asks every installation to accept. Installations that have not accepted keep their current permissions.
2. Per Organization: an owner reviews and accepts the request. Accepting also accepts any other permission the App requests at that moment.
3. Per Organization, in the same short window: the policy declares the whole newly accepted set, including installation_permissions.issues: write. The installation gate compares permissions exactly, so until this deploy the Worker returns 502 token_unavailable and the Node adapter refuses to start and fails --verify-only. This is the same procedure as workflows: write in 0.9.0. From then on, tokens of both tiers carry issues: write.

Rollout (order matters)

1. Release v0.11.0.
2. Deploy broker 0.11.0 for each Organization's broker. No policy change is needed; write grants mint what they did before plus members: read, which every installation already holds. Use policy check --live as the deploy gate.
3. (Optional) Pin the 0.11.0 adapter in the Workspace image, so a refused write is explained. The 0.10.0 adapter already works with read-tier tokens.
4. (Where the Organization wants issues: proposals from read-only Environments, escalations from write-capable ones) do the App-permission prerequisite above.
5. Only then does the Organization lower Team grants on GitHub. Run policy check --live first to see every Team's current grants and tiers. A lowered repository mints the read tier on the next request. A write-tier token minted earlier stays valid until it expires (at most one hour). If a grant is lowered before step 2, the Environment is cut off the repository.

Rolling the broker back to 0.10.0 refuses read-only Teams again with team_grant_missing. It never widens access.

Verification

• npm test: 88/88 pass (77 before). New and updated tests cover:
  • Grant readback per tier. read/triage → read and write/maintain/admin → write, in both body forms, through one revoked probe.
  • Read tier mint. It asks for exactly actions: read, checks: read, contents: read, members: read, pull_requests: read, plus issues: write only when declared (not for issues: read, never workflows). It refuses any over- or under-scoped answer: any write (including Actions write), an undeclared issues grant, or a missing Actions, checks, members or PR read (and a members: write answer).
  • Write tier mint. It asks for members: read and refuses an answer without it. It adds issues: write only when declared, alone or together with workflows: write. It refuses an undeclared issues grant and a declared-but-missing one.
  • No default tier. A missing or unknown tier never reaches GitHub.
  • End to end through the real core client. pull/triage mint the read set, push mints write, no grant mints nothing, and cross-Workspace is still team_grant_missing.
  • team_grant_missing unchanged for 404, a payload without any permission, a missing permissions object, id mismatch (both tiers), a missing full name and 204.
  • Lost tier fails closed. The handler fails closed when the gate or the mint loses or changes the tier. The Worker passes the read tier through.
  • Adapter. It parses access. The allow-list refuses no write command up front. With a read token, issue create, api, pr view, pr checks and run view run silently, while pr create runs official gh, keeps its exit code and gets the conditional notice; an unrelated failed read (api …/contents/missing) also keeps gh's exit code and gets the same conditional notice, which never claims a refusal and names the Issues-permission prerequisite. No token appears in any output. A read-tier discovery proof succeeds.
• npm run check: pass. This covers the license check, syntax checks and the Wrangler dry-run.
• Offline policy check. I ran node src/broker.mjs policy check on the example policy, with and without issues: write; it prints the tier lines as documented.
• Live evidence for members: read. From the Team Environment of a pilot Organization, with today's brokered write-tier token: gh api orgs/<org>/members?role=admin → 200 [] (accepted permission members=read) and gh api repos/<org>/<repo>/collaborators → 200 [] (accepted metadata=read), although the Organization has five Owners.
• Not verified live. I did not mint against a real installation, because that needs the App key, which stays in the deployment's custody. The per-Organization smoke after deploy (step 2) covers it.

🤖 Generated with Claude Code

[agentrozjedemeai]

Review of exact head 9d32c67.

Changes requested — one finding (also raised in the open review thread):

• adapter/brokered-gh.mjs:260-271: Any nonzero exit from official gh with a read-tier token produces the definitive notice that GitHub refuses pushes, pull requests and other changes, and recommends gh issue create. A failed read (bad arguments, nonexistent resource, network/API outage) receives the same misleading diagnosis; without the optional issues: write declaration, the proposed command is itself unavailable. Please distinguish a permission refusal from other failures, or make the notice explicitly conditional and mention that creating issues requires the installation's accepted Issues permission. Cover both a permission failure and an unrelated failed read / missing Issues permission in tests. Keep the official gh error and exit code and do not pre-block commands.

The other requested boundaries checked out on this head: grant-to-tier mapping, optional Issues permission, exact returned permission set, additive access, no grant refusal, and rollout order. Local npm test passed 88/88, npm run check and git diff --check origin/main...HEAD passed. No live installation token was minted or deployment performed.

[agentrozjedemeai]

Exact-head re-review of 0ba2f2a: APPROVED. The prior notice finding is addressed: after official gh fails, the read-tier notice is conditional and states the Issues-permission prerequisite; official gh still runs and its exit code/error are retained. I checked the members: read addition in both requested tier sets and exact minted permission validation, grant-to-tier routing and fail-closed tests, documentation and rollout order. Locally on this detached SHA: npm test 88/88, npm run check, git diff --check all pass; CI test and image checks pass on this SHA. The prior thread is resolved. No live installation mint, release or deployment was performed.