Split agent read auth from publication write auth

[romgenie]

Local source: coven-github/issues/03-split-agent-read-auth-from-publication-write-auth.md

Summary

coven-github should stop passing a general installation token into session-brief.json and should separate agent context hydration from deterministic GitHub publication. The agent should receive only the minimum read capability needed to inspect the target repository, while comments, Check Runs, branch pushes, and PR creation should remain under the adapter's publication gate.

Current Evidence

• crates/worker/src/brief.rs defines AuthBrief { token: String }.
• build() writes both auth.token and a tokenized repo.clone_url into the session brief.
• docs/security.md explicitly notes that the current session brief includes clone auth and says the production target should prefer GIT_ASKPASS or environment-based git auth, avoid writing installation tokens to durable stores, and redact tokens from outputs.
• crates/worker/src/lib.rs uses the same installation token for Check Runs, comments, session brief construction, PR creation, and task updates.

Problem

Passing the installation token into the agent context weakens the security boundary. If coven-code tools, prompts, logs, model transcripts, or memory extraction mishandle the brief, the token can leak. It also gives the agent direct ambient authority rather than making the adapter decide what gets published.

The earlier architecture assumed the agent does not receive GitHub write authority. The current implementation is a pragmatic development shortcut that degrades that boundary.

Impact

• Installation tokens can appear in JSON files, logs, transcripts, memory, or model context.
• A compromised or misbehaving agent can perform GitHub operations outside the intended publication flow.
• Token redaction must become perfect across every downstream tool and log path.
• Hosted customers cannot confidently reason about who had write authority.

Proposed Design

Split authority into phases:

1. Adapter mints installation token.
2. Adapter fetches repo/diff/context, or provides git auth through a narrow helper.
3. Agent receives a tokenless session brief plus repository workspace.
4. Agent emits a structured result envelope with proposed changes/findings.
5. Adapter validates the result.
6. Adapter mints or reuses a write-capable installation token only for deterministic publication.

For clone/fetch:

• Prefer GIT_ASKPASS, credential helper, or short-lived env injection that never appears in JSON.
• Redact token values from child process environment capture.
• Consider a separate read-only installation token or GitHub App permission split if feasible.

Acceptance Criteria

• session-brief.json no longer contains auth.token.
• repo.clone_url no longer embeds x-access-token.
• Agent-visible logs and result envelopes are scanned for token patterns before persistence/publication.
• Publication code obtains write authority after agent execution and after policy validation.
• Tests fail if a session brief serializes token-like fields.
• Security docs are updated with the actual implemented token flow.

Test Notes

Add serialization tests for SessionBrief asserting no token/auth field exists. Add integration tests that run the worker with a fake token and verify the token does not appear in the brief, result file, task API response, comments, PR body, or Check Run output.

---

Wave 1 grooming

• Size: M–L · Intra-wave rank: 1 — critical-path spine (#4 → #10 → #13 → #19) and closes the token-leak boundary.
• Depends on: Add durable task queue and GitHub delivery idempotency #2. Unblocks: Implement PR, push, and commit review triggers #10.
• In scope: remove auth.token from session-brief.json; strip x-access-token from repo.clone_url; git auth via GIT_ASKPASS/credential-helper/env; mint write token only post-validation for publication; token-pattern scan before persist/publish; serialization guard test.
• Out of scope: publication-gate policy (Add structured review output and deterministic publication gates #11) and review triggers (Implement PR, push, and commit review triggers #10) — this issue only relocates authority, not the gate logic.
• Ready checklist:
  1. Drop token field from AuthBrief/SessionBrief in crates/worker/src/brief.rs; remove tokenized clone URL.
  2. Add GIT_ASKPASS/credential-helper clone path that never serializes to JSON; redact from captured child env.
  3. Restructure crates/worker/src/lib.rs into phases: mint-read → hydrate → tokenless brief → agent → validate → mint-write → publish.
  4. Add token-pattern scanner over brief, result envelope, and logs before persistence/publication.
  5. Serialization test: SessionBrief must not serialize any token-like field.
  6. Update docs/security.md with the implemented token flow.
• Done when: with a fake token, no token appears in brief/result/task-API/comment/PR body/Check Run; serialization test fails on a token field; cargo check --all-targets + cargo clippy --all-targets -- -D warnings + cargo test --all green.

Owner: Cody (engineering lane) · Approval gate: Val · GitHub assignee: @BunsDev