feat: git-over-HTTPS credentials via App tokens (#43)

* feat: git-over-HTTPS credentials via App tokens (/git-credential + ghp helper)

Closes the last long-lived GitHub credential gap for agents: git push
now authenticates with a short-lived, single-repo GitHub App installation
token instead of a PAT or user OAuth session.

Server (/git-credential, GET, opt-in via [mcp].enable_git_credentials):
- Same hard gate as MCP writes: [[mcp.agents]] + App backend + [mcp.audit],
  validated at startup
- Policy stack, all fail-closed: X-Ghpool-Key auth → repository-scoped
  agents only → repo allowlist → installation routing (multi-app by owner,
  single-app owner match) → fail-closed audit record → single-repo token
  mint (GitHub enforces the boundary)
- Response { username: x-access-token, password, expires_at } with
  cache-control: no-store; token value never audited

Client (ghp git-credential):
- Standard git credential helper protocol (get/store/erase); get exchanges
  GHPOOL_KEY for a token, store/erase are no-ops
- Declines quietly (exit 1) on missing key/path/non-github hosts so git
  can fall through to other helpers; requires credential.useHttpPath

Verified: ghpool clippy -D warnings clean, 105 passed / 0 failed (6 new);
ghp clippy clean, 14 passed / 0 failed (2 new)

* fix(git-credential): bind installations to owners, downscope tokens, fail closed everywhere

Hardening from self-review of #43:

- BLOCKER: verify_owner() binds explicit installation IDs to the actual
  installation account (GET /app/installations/{id}) before any issuance;
  mislabeled config entries are refused (403) and audited
- MAJOR: git tokens mint with permissions={contents:write} and a
  git-specific cache namespace — never the App's full permission set,
  never shared with MCP token cache entries
- MAJOR: ghp helper emits quit=true for every unservable recognized
  github.com request (missing key/path, policy denial, network failure)
  so git never falls through to broader stored helpers; non-GitHub hosts
  still decline quietly; gist.github.com unsupported
- MAJOR: two-phase audit — durable request preflight BEFORE owner
  verification/mint/cache lookup, result record before the token is
  returned; either write failing rejects the credential (503)
- singular [mcp.github_app] now requires owner when git credentials are
  enabled (startup validation + defense-in-depth in the handler)
- /git-credential always registered before the /{*path} catch-all;
  disabled mode answers 404 locally instead of proxying to GitHub

Tests: mint-envelope/cache-isolation, owner verification (unit +
endpoint mismatch), two-phase audit records, no-mint-on-preflight-
failure, production route precedence, helper plan/fetch fail-closed
matrix, config validation gates. README/config.example document the
--replace-all helper reset and quit=true semantics.

* fix(git-credential): normalize helper host matching, TTL owner re-verification, strict charset, CI for ghp

Round-2 review fixes:

- BLOCKER: helper host matching is now case-insensitive and
  port-aware — host=GitHub.com and github.com:443 are recognized
  github.com requests (Fetch/Quit), never declined to a broader
  helper; github.com on a non-443 port quits (recognized but
  unsupported)
- MAJOR: verify_owner caches with a 1h TTL and re-checks the
  installation account with GitHub after expiry (orgs can rename)
- MAJOR: strict charset validation of repo owner/name on the server
  (400 before allowlist/preflight/mint) and in the helper's
  repo_from_path (quit) — percent-encoded/exotic input never reaches
  the audit log, the mint path, or an unencoded query string
- MAJOR: CI now builds/lints/tests the ghp crate, plus an
  integration test suite that spawns the real binary and asserts
  quit=true on stdout for recognized-github failure modes and quiet
  decline (exit 1) for other hosts
- MINOR: token mint is singleflight — concurrent cache misses for
  the same key mint exactly once (asserted by test)

Tests: ghpool 111, ghp 20 unit + 5 integration, clippy clean both.

* fix(app-token): key-scoped singleflight and hard mint timeout

Round-3 review: the per-provider singleflight mutex was held across
mint network I/O, serializing distinct cache keys (different repos,
MCP vs git purposes) behind one another — and the reqwest client had
no timeout, so one stalled mint could block all issuance for an owner
indefinitely.

- Singleflight is now per cache key (Arc<tokio::sync::Mutex> map):
  same-key misses still mint exactly once; distinct keys mint in
  parallel
- App API client now has a 30s hard timeout (MINT_TIMEOUT) covering
  mint, installation resolution, and owner verification calls
- New test: a stalled mint for one key must not delay another key
  (test_distinct_keys_mint_in_parallel); same-key singleflight test
  retained

Tests: ghpool 112, ghp 20 unit + 5 integration, clippy clean both.

* fix(app-token): evict singleflight lock entries when mints complete

Round-4 review: mint_locks entries were never removed, so unique
request-supplied repo names (e.g. failed mints under a wildcard
allowlist) accumulated lock entries for the process lifetime —
unbounded memory growth on an authenticated path.

Entries are now evicted after the mint completes (success or
failure): waiters already holding the Arc still serialize and
re-check the cache; the next fresh miss creates a new lock. The map
is bounded by in-flight mints.

Test: test_mint_locks_evicted_after_success_and_failure (success,
repeated failures, and the parallel test now asserts an empty map).

Tests: ghpool 113, ghp 20 unit + 5 integration, clippy clean.

* fix(app-token): generation-guard singleflight eviction

Round-5 review: unconditional remove(&key) let a stale waiter from an
evicted generation remove a NEWER generation's in-flight lock,
re-opening the duplicate-mint race repeatedly.

evict_mint_lock() now removes the entry only when the map still holds
the caller's own Arc (ptr_eq guard): each generation removes at most
itself, bounding duplicate mints to one per evicted generation while
keeping the map bounded by in-flight mints.

Test: test_evict_mint_lock_is_generation_guarded (stale generation
cannot evict, owner can, absent-key no-op).

Tests: ghpool 114, ghp 20 unit + 5 integration, clippy clean.

---------

Co-authored-by: chaodu-agent <chaodu-agent@users.noreply.github.com>

Author: chaodu-agent

.github/workflows/ci.yml

@@ -6,6 +6,8 @@ on:
       - "src/**"
       - "Cargo.toml"
       - "Cargo.lock"
+      - "ghp/**"
+      - ".github/workflows/ci.yml"
 
 env:
   CARGO_TERM_COLOR: always
@@ -19,9 +21,21 @@ jobs:
         with:
           components: clippy
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2 (2026-03-12)
+        with:
+          workspaces: |
+            .
+            ghp
       - name: cargo check
         run: cargo check
       - name: cargo clippy
         run: cargo clippy -- -D warnings
       - name: cargo test
         run: cargo test
+      # ghp is a separate crate (not a workspace member): the git credential
+      # helper's fail-closed contract must be enforced in CI too.
+      - name: ghp clippy
+        run: cargo clippy --all-targets -- -D warnings
+        working-directory: ghp
+      - name: ghp test
+        run: cargo test
+        working-directory: ghp

README.md

@@ -459,6 +459,74 @@ Trade-off vs. one key per org: a leaked key reaches the allowlisted repos of
 **all** configured installations. Prefer separate agents/keys when you want
 per-org blast-radius isolation.
 
+#### Git over HTTPS via App tokens (`/git-credential`)
+
+MCP covers issues and PRs, but `git push` speaks the Git protocol — it needs
+a real credential at push time. `enable_git_credentials` lets a
+repository-scoped agent exchange its ghpool key for a **short-lived,
+single-repo** App installation token, eliminating the last long-lived GitHub
+credential in the agent container:
+
+```toml
+[mcp]
+enable_git_credentials = true   # same hard gate as writes:
+                                # agents + App backend + [mcp.audit]
+```
+
+The App needs **Contents: Read & write** on the target repositories. With
+the singular `[mcp.github_app]` form, `owner` is **required** when git
+credentials are enabled — the explicit `installation_id` is verified against
+the installation's actual account before any token is issued.
+
+Agent side, `ghp` doubles as a standard git credential helper. Register it
+as the **only** helper for `github.com` — `--replace-all` with an empty
+first entry clears any inherited helpers (osxkeychain, GCM, `gh auth
+git-credential`) that would otherwise supply broader credentials:
+
+```sh
+git config --global --replace-all credential."https://github.com".helper ""
+git config --global --add credential."https://github.com".helper "!ghp git-credential"
+git config --global credential."https://github.com".useHttpPath true
+```
+
+Every `git push` then flows:
+
+```
+git push → ghp git-credential (GHPOOL_KEY from env)
+         → GET /git-credential?repo=owner/name   (X-Ghpool-Key)
+         → key auth → repo allowlist → installation routing
+         → durable audit preflight (phase: git_credential_request)
+         → installation owner verified against GitHub
+         → Contents-only single-repo token (~1h, GitHub-enforced scope)
+         → audit result (phase: git_credential_result)
+         → push authenticated as <app>[bot]
+```
+
+Properties:
+
+- **Single-repo, Contents-only tokens** — each credential is minted with
+  exactly the repo being pushed and `contents: write` only, never the App's
+  full permission set; GitHub itself enforces both boundaries. Git tokens
+  are cached separately from MCP tokens.
+- **Owner binding** — the configured owner label is verified against the
+  actual installation account (`GET /app/installations/{id}`) before
+  issuance and re-verified hourly (accounts can rename); a mislabeled
+  installation ID is refused.
+- **Fail-closed audit** — a request record is persisted *before* any mint or
+  cache lookup, and a result record before the token is returned; if either
+  write fails, no credential (503). The token value is never written to the
+  audit log.
+- **Deny-by-default** — repo-less agents, off-allowlist repos, and owners
+  without an installation are refused before any mint.
+- **Fail-closed helper** — once a request is recognized as `github.com`
+  HTTPS, any failure (missing `GHPOOL_KEY`, missing path, policy denial,
+  network error) makes `ghp` emit `quit=true`, telling git to stop the
+  helper cascade instead of falling through to broader stored credentials
+  or prompting. Non-GitHub hosts are declined quietly so other helpers can
+  serve them. `gist.github.com` is not supported.
+- **Nothing to store** — `store`/`erase` are no-ops; tokens expire on their
+  own. `cache-control: no-store` on the response.
+
 Deployment notes:
 
 - Requires egress to `api.githubcopilot.com` (the only additional external dependency).

config.example.toml

@@ -47,6 +47,18 @@ enabled = false
 # PATs, and are always fail-closed audited. When set, the default upstream
 # switches to the full write-capable surface.
 # enable_writes = false
+# Enable GET /git-credential: repository-scoped agents exchange their
+# X-Ghpool-Key for a short-lived GitHub App installation token scoped to
+# EXACTLY ONE repository with Contents-only permissions, usable as a
+# git-over-HTTPS credential (username `x-access-token`). Closes the
+# long-lived-PAT gap for `git push`. Same hard gate as writes: agents +
+# App backend + audit (durable preflight before mint, result before the
+# token is returned). The App needs Contents: read/write for pushes. With
+# the singular [mcp.github_app] form, `owner` is REQUIRED — the explicit
+# installation_id is verified against the installation's actual account
+# before issuance. Client side: `ghp git-credential` is a drop-in git
+# credential helper (see README for the fail-closed helper setup).
+# enable_git_credentials = false
 # Max concurrent write calls per agent (0 = unlimited).
 # max_inflight_writes = 4
 # Upstream MCP endpoint. Default: hosted read-only variant, or the full