docs(forgejo-agent-operations): Keychain PAT + direct-curl pattern #214

Merged

pdurlej merged 1 commit from claude/orders/forgejo-agent-keychain-pattern into main

2026-05-12 01:31:53 +02:00

claude commented

2026-05-12 01:29:21 +02:00

Collaborator

Canary status: missing — fire canary via python -m platformctl.tools.run_review before merge

Summary

Document how agents extract their actor-specific PAT on the operator's Mac without requiring an interactive bw unlock, plus the direct-curl + tempfile pattern as the canonical replacement for Forgejo MCP write actions.

Closes a documentation gap discovered 2026-05-12 night — an agent-souls session (issue #37) had to ask the operator to unlock Bitwarden interactively just to call a Forgejo write API as claude, while macOS Keychain already had the PAT pre-loaded the whole time.

Changes

docs/forgejo-agent-operations.md: new section Agent PATs On The Operator's Mac inserted between Identity Rules and Issue Rules, with two subsections:

macOS Keychain is the canonical local source — security find-internet-password extraction for claude, codex, glm under service git.pdurlej.com; identity-verification curl against /api/v1/user; explicit non-coverage rationale for iskra (VPS runtime / Infisical) and pdurlej (operator merge gate); Bitwarden fallback rule.
Direct-curl is the canonical write path — canonical tempfile + jq -n + curl -d @file POST pattern; identity check on response; same pattern applies to comment / PR / PATCH / review endpoints; PAT-non-paste rule.

Trailing sentence of Identity Rules now cross-references the new section.

Verification

Verified on the operator's Mac, 2026-05-12:

Keychain has accounts claude, codex, glm under service git.pdurlej.com; each returns a 40-character PAT via security find-internet-password -s git.pdurlej.com -a <actor> -w.
Each PAT against /api/v1/user resolves to the expected identity: login=claude id=3, login=codex id=4, login=glm id=5.
iskra and pdurlej are intentionally NOT in Keychain (confirmed).
This PR was opened using the documented direct-curl pattern (dogfood). The branch was pushed via git -c "http.extraheader=Authorization: token \$CLAUDE_PAT" using the claude Keychain PAT, no operator credentials touched.

Test plan

Operator readback: new section reads naturally between Identity Rules and Issue Rules
Operator confirms the Keychain extraction commands match the local Mac setup
(after merge) Next agent session attempting a Forgejo write as claude follows this section instead of asking for bw unlock

Tier (ADR-0007)

Lite. Diff = 66 additions, 1 deletion (LoC change = 67, ≤100). Single docs file. No schema, runtime, sacred-path, CI workflow, or ADR touched. No class/security-sensitive content (PAT extraction commands are documented; no PAT values appear in the diff or this PR body).

Note: tier/lite label does not yet exist on the repo (ADR-0007 still Proposed). Operator may add the label or proceed without — flagging here for visibility.

Spec sources read

docs/forgejo-agent-operations.md (existing, before edit)
practices/credential-management.md in pdurlej/agent-souls — canonical credential hierarchy, direct-curl > MCP rule, per-agent identity table; this PR is consistent with that doc and intentionally avoids duplicating its content beyond what platform-side agents need on-Mac
decisions/0007-risk-proportional-canary.md (tier classification, sensitive-paths list)
.forgejo/pull_request_template.md (PR shape)

Out of scope

No changes to practices/credential-management.md in agent-souls (different repo, different scope). That doc already covers the broader hierarchy; this PR adds the Mac-local Keychain shortcut and the canonical write-API pattern to the platform-facing operations doc only.
No new labels created. No CI workflow changes.
No PAT rotation or new PAT issuance.

Canary status: missing — fire canary via `python -m platformctl.tools.run_review` before merge ## Summary Document how agents extract their actor-specific PAT on the operator's Mac without requiring an interactive `bw unlock`, plus the direct-curl + tempfile pattern as the canonical replacement for Forgejo MCP write actions. Closes a documentation gap discovered 2026-05-12 night — an `agent-souls` session (issue #37) had to ask the operator to unlock Bitwarden interactively just to call a Forgejo write API as `claude`, while macOS Keychain already had the PAT pre-loaded the whole time. ## Changes `docs/forgejo-agent-operations.md`: new section **Agent PATs On The Operator's Mac** inserted between **Identity Rules** and **Issue Rules**, with two subsections: - **macOS Keychain is the canonical local source** — `security find-internet-password` extraction for `claude`, `codex`, `glm` under service `git.pdurlej.com`; identity-verification curl against `/api/v1/user`; explicit non-coverage rationale for `iskra` (VPS runtime / Infisical) and `pdurlej` (operator merge gate); Bitwarden fallback rule. - **Direct-curl is the canonical write path** — canonical tempfile + `jq -n` + `curl -d @file` POST pattern; identity check on response; same pattern applies to comment / PR / PATCH / review endpoints; PAT-non-paste rule. Trailing sentence of **Identity Rules** now cross-references the new section. ## Verification Verified on the operator's Mac, 2026-05-12: - Keychain has accounts `claude`, `codex`, `glm` under service `git.pdurlej.com`; each returns a 40-character PAT via `security find-internet-password -s git.pdurlej.com -a <actor> -w`. - Each PAT against `/api/v1/user` resolves to the expected identity: `login=claude id=3`, `login=codex id=4`, `login=glm id=5`. - `iskra` and `pdurlej` are intentionally NOT in Keychain (confirmed). - This PR was opened using the documented direct-curl pattern (dogfood). The branch was pushed via `git -c "http.extraheader=Authorization: token \$CLAUDE_PAT"` using the claude Keychain PAT, no operator credentials touched. ## Test plan - [ ] Operator readback: new section reads naturally between Identity Rules and Issue Rules - [ ] Operator confirms the Keychain extraction commands match the local Mac setup - [ ] (after merge) Next agent session attempting a Forgejo write as `claude` follows this section instead of asking for `bw unlock` ## Tier (ADR-0007) **Lite.** Diff = 66 additions, 1 deletion (LoC change = 67, ≤100). Single docs file. No schema, runtime, sacred-path, CI workflow, or ADR touched. No `class/security-sensitive` content (PAT extraction *commands* are documented; no PAT values appear in the diff or this PR body). Note: `tier/lite` label does not yet exist on the repo (ADR-0007 still **Proposed**). Operator may add the label or proceed without — flagging here for visibility. ## Spec sources read - `docs/forgejo-agent-operations.md` (existing, before edit) - `practices/credential-management.md` in `pdurlej/agent-souls` — canonical credential hierarchy, direct-curl > MCP rule, per-agent identity table; this PR is consistent with that doc and intentionally avoids duplicating its content beyond what platform-side agents need on-Mac - `decisions/0007-risk-proportional-canary.md` (tier classification, sensitive-paths list) - `.forgejo/pull_request_template.md` (PR shape) ## Out of scope - No changes to `practices/credential-management.md` in `agent-souls` (different repo, different scope). That doc already covers the broader hierarchy; this PR adds the Mac-local Keychain shortcut and the canonical write-API pattern to the platform-facing operations doc only. - No new labels created. No CI workflow changes. - No PAT rotation or new PAT issuance.

claude added 1 commit

2026-05-12 01:29:21 +02:00

docs(forgejo-agent-operations): document Keychain PAT extraction + direct-curl write pattern

canary-required / collect-diff (pull_request) Failing after 3s

Details

pyfallow / Pyfallow gate (control-plane) (pull_request) Successful in 17s

Details

python-ci / Python 3.11 (pull_request) Successful in 43s

Details

python-ci / Python 3.12 (pull_request) Successful in 43s

Details

python-ci / Python 3.13 (pull_request) Successful in 43s

Details

canary-required / canary (pull_request) Has been skipped

Details

545149cbbd

Closes documentation gap discovered 2026-05-12 when an agent-souls session
(issue #37) had to ask the operator to run `bw unlock` interactively just
to call a Forgejo write API as `claude`. The operator's macOS Keychain
already has cousin PATs pre-loaded for claude/codex/glm under service
`git.pdurlej.com`, extractable without a prompt via `security
find-internet-password`. Verified 2026-05-12: all three resolve to the
expected identity via `/api/v1/user`.

Also documents the tempfile + jq + curl -d @file pattern as the canonical
replacement for Forgejo MCP write actions, which authenticate as `pdurlej`
and silently violate per-agent identity isolation.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>