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.