Document Gecko GitHub token architecture and security model

[bwalsh]

Document Gecko GitHub token architecture and security model

Summary

This PR adds a new design document describing how Gecko handles GitHub credentials through Fence and what Git-related state Gecko persists.

What Changed

• Added git-token-design.md.
• Documented end-to-end read and write token flows:

1. User auth in Gecko
2. Project/org authorization
3. Fence token brokerage via /credentials/github
4. GitHub API/git operations with short-lived installation tokens
5. Persistence of non-secret Git state only

• Added architecture diagrams and sequence flows for:

1. Core component boundaries
2. Token minting lifecycle
3. Upload finalize/write flow
4. Expanded security model

• Clarified storage boundaries:

1. What Gecko owns (repo/install/sync/upload metadata)
2. What Fence owns (GitHub App private key + token minting)
3. What Gecko must not store (app keys/tokens/user tokens)

Why

• Make the credential boundary between Gecko and Fence explicit.
• Provide a reviewable source of truth for GitHub token handling and persistence rules.
• Align documentation with the current implementation direction from PR switch to fiber/v3, add in project configuration #4.

Risk / Impact

• Low risk: documentation-only change.
• No runtime code path changes.

Testing

• Not applicable (docs-only change).

Reviewer Checklist

1. Validate described token flow matches current Fence broker integration.
2. Confirm “must not store” guidance aligns with current DB/logging behavior.
3. Confirm read vs write token usage reflects real Gecko workflows.

[Copilot]

Pull request overview

Adds a new design document (docs/git-token-design.md) that describes Gecko’s GitHub credential boundary with Fence, including read/write token flows, persisted Git state, and a security model intended to match the implementation direction from PR #4.

Changes:

• Added a design doc documenting Fence-brokered GitHub installation token flows (read vs write) and where tokens/keys must not be stored.
• Documented Gecko’s persisted Git-related state (Postgres config_schema tables + local mirror layout under GIT_DATA_DIR).
• Included architecture/security diagrams and operational configuration notes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.