feat(proxy): inject GitHub authorization at the MITM proxy so agents never hold usable tokens (#1861)

[clubanderson]

What this ships

The core of #1861, item 1 as re-scoped by triage: GitHub authorization is injected at the MITM proxy, per identified agent, so that with the flag on, nothing an agent holds authenticates anywhere. Opt-in via HIVE_PROXY_INJECT_GH_AUTH=true, default OFF — with the flag unset, token delivery and proxy behavior are byte-identical to today. The fleet keeps working while this soaks; do not flip the default here.

Both prerequisites the triage recorded are honored:

• Identity is UID-authoritative (fix(proxy): stop trusting self-asserted agent identity as a fallback (N7, #3841) #3888, merged): injection keys off identifyAgentFromConn's UID-map resolution. The self-asserted fallback this issue's triage flagged as Blocker A is gone, so a spoofed name can no longer become a minted token.
• No new minting lane: the proxy consumes tokens the existing 🐛 fix(agents): mint the per-agent GitHub token on every relaunch path, not only Start #3967 per-agent scoped lane (WriteAgentToken, refreshed hourly and on every relaunch) already maintains.

Mechanism

Hub side (pkg/github/proxy_token_source.go, WriteAgentToken): under the flag, the freshly-minted tier-scoped token is diverted to an in-memory registry only the hub process can read, and the agent-visible cache file — the single choke point that gh-wrapper.sh (GH_TOKEN), git-credential-hive.sh (password), and the manager's GITHUB_TOKEN env push for the MCP server all read — receives the visibly-fake placeholder hive-proxy-injected-<agent> instead. No bash/manager changes needed: every agent-side consumer is converted by that one divert, tooling keeps functioning (syntactically-valid credential in place), and any leak of the placeholder is inert and self-diagnosing. The registry is package-level, not on AppAuth, because appAuth is replaced at runtime on key rotation and a proxy closure over one instance would strand it on the stale map.

Proxy side (rewriteGitHubAuth, called after the ACMM/repo/canary gates and before both forwarding branches):

• Strip: any agent-supplied Authorization header is deleted unconditionally under the flag — even a credential smuggled to an agent through a side channel cannot be spent through the proxy. (Survey note: Authorization is the only header GitHub honors for API/git auth today; the old ?access_token= query param was removed by GitHub in 2020 and no X-*-token request-auth variant exists, so header stripping covers the surface.)
• Inject: the UID-identified agent's hub-held scoped token — token <t> for REST/GraphQL, Basic x-access-token:<t> for git smart HTTP paths (the exact shape git-credential-hive.sh produced before, so upstream sees nothing new).
• Unknown agent = no credential, fail loud: when UID attribution fails, the request goes upstream with no Authorization and 401s at GitHub. Deliberate: any fallback (shared cache, hive token) would let an unattributable process ride a real credential, recreating the pre-fix(proxy): stop trusting self-asserted agent identity as a fallback (N7, #3841) #3888 identity hole. The token source is not even consulted (tested).
• Internal caller passthrough: the hive's own control-plane requests (hive-internal, assigned only via UIDMap.IsInternalUID, unspoofable) pass untouched — they legitimately carry the hive's own App credentials for mint/heartbeat/relay fulfillment.
• OAuth device-flow endpoints (/login/…) are strip-only — those authenticate the flow via the form body, and an App token there would be wrong.
• Logging: agent name + injected yes/no only; never token bytes, not even prefixes.

Survey finding: MITM widens under the flag (and why)

Today the proxy MITMs only api.github.com; github.com and registered GHE hosts are opaque tunnels (NeedsMITM). That is fine without injection, but with it an opaque tunnel is a hole: the agent's git credential helper now serves the placeholder, so a git push through an un-decrypted tunnel would reach GitHub carrying the placeholder and 401 — and a smuggled real credential would transit un-stripped. So under the flag (only), hostNeedsMITM widens interception to every GitHub-family host. Injected git requests are additionally marked Connection: close, because the git branch switches to a raw relay after the first request's headers — a keep-alive follow-up on the same conn would stream past the rewrite; forcing per-request connections makes every git exchange re-enter the rewrite. Flag off: interception surface unchanged.

Soak watch-items (why the default must stay off for now)

• Copilot CLI device flow: with github.com MITM'd, the Copilot CLI's /login traffic is intercepted; if that CLI does not trust the hive CA the flow breaks (the existing GIT_SSL_CAINFO-not-SSL_CERT_FILE comment suggests sensitivity here). First flag-on spoke should verify Copilot login.
• ioscan fail-closed hives: MITM'd git-receive-pack hits the pre-existing "canary scan unavailable for git push" deny when ioscan.fail_closed is set — loud, but worth knowing before enabling both together.
• Hub restart: the in-memory registry is empty until the next launch/relaunch/hourly mint; identified agents get fail-loud 401s (WARN names the mint lane) for at most one refresh interval.

Explicitly out of scope (the follow-up that closes #1861)

• Flipping HIVE_PROXY_INJECT_GH_AUTH default ON and removing agent-side token delivery entirely (cache files, GITHUB_TOKEN env push) once soaked — the issue closes there, not here.
• The contributor lanes (contribute_ws.go / contributor-relay.sh) and the opt-in pushbroker/mint WIF lane — separate credential paths, untouched.
• Perimeter items already shipped and not redone: cache 0600, no tokens in kick prompts (🔒 fix(scheduler): stop handing every agent a live GitHub token in its kick prompt (#1861) #3931), kick-agents cache-cat removal (fix(agents): stop instructing native-install agents to cat the shared App token (N14, #3842) #3889), --scoped bypass fix (🐛 fix(credentials): stop --scoped serving the full App token from the shared cache #3947), per-agent minting on relaunch (🐛 fix(agents): mint the per-agent GitHub token on every relaunch path, not only Start #3967).

Test evidence (fail-first / mutation-checked)

New tests: pkg/proxy/auth_inject_test.go (7 tests, httptest-style fake upstream capturing raw bytes), pkg/github/proxy_token_source_test.go (2), pkg/config/proxy_inject_test.go (1). Each guard was mutation-checked — the guard removed, the suite re-run, the failure observed, the guard restored:

Mutation (guard removed)	Detecting test	Result
Authorization strip deleted	…AgentSuppliedAuthorizationNeverReachesUpstream	FAIL: agent-supplied credential reached upstream
Flag gate deleted (always rewrite)	…FlagOffByteIdenticalPassthrough	FAIL: header mutated + source consulted with flag off
Unknown-agent fallback added	…UnknownAgentNoInjectionNoFallback	FAIL: credential injected + source consulted for ""
WriteAgentToken divert deleted	…InjectionDivertsRealTokenToRegistry	FAIL: agent-readable cache contains the REAL token
MITM widening deleted	TestHostNeedsMITM_InjectionWidensInterception	FAIL: github.com/GHE not intercepted under flag
Injection deleted (strip kept)	…IdentifiedAgentGetsScopedToken	FAIL: upstream saw no Authorization

Suite runs (macOS, -count=1):

• go test ./pkg/proxy/ -race — ok (51s, full package)
• go test ./pkg/github/ — ok (46s, full package)
• go test ./pkg/config/ — new TestProxyInjectGHAuth passes; TestExportEmitsShellExportOnBothPaths + TestSharedCacheIsCreatedPrivate fail identically on clean origin/v4 @ 9f9a65f2 (verified in a pristine worktree) — pre-existing, unrelated (gh-app-token.sh script tests).

Part of #1861

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[clubanderson]

On hold — do not merge. This changes the GitHub credential path for every agent (behind a default-OFF flag), and the operator wants it reviewed deliberately before it lands even dormant. Leaving the branch and CI as-is; no auto-merge watcher is armed on it.

[kubestellar-prow]

PR needs rebase.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[clubanderson]

Superseded by #5876 — this feature targets the v5 line, and the port (with v5 adaptations: NeedsInspection composition, proxyHTTP capabilities param, atomic tunnelHalfCloseDrain, hivecommons module path) is now up there. Closing this v4-based PR.