MCP proxy Phase 2 gate: agent authn + default-deny policy + GitHub App backend + writes

[chaodu-agent]

Part of #15 (see Revision 2 of the RFC — this issue's scope was significantly expanded by the community review). Depends on Phase 1 (#16, shipped in #20) and the Phase 0 compatibility spike (#22 — key findings incorporated below).

Phase 0 spike results that shape this design (details in #22 findings):

1. App installation tokens work against the hosted endpoint — the credential backend below is verified viable.
2. X-MCP-Tools (undocumented, verified) is an exact per-tool allowlist — use it, not X-MCP-Toolsets categories.
3. X-MCP-Toolsets fails open on invalid names (typo → full tool surface) — never rely on it for enforcement.
4. Policy headers are honored per-request — ghpool must inject on every request and strip all client X-MCP-* (a client header would widen access mid-session).
5. Upstream DELETE is a no-op (session remains usable) — ghpool's session cache is the sole session/revocation authority.
6. Tool surface varies with App permissions (41 vs 44 tools App vs PAT) — the required App permission set must be documented and pinned.

Goal

Introduce agent identity and default-deny per-agent policy, unlocking write access through the MCP proxy. This phase is the security gate: no write tool is exposed until every item below ships.

Delivery plan: two slices (decision 2026-07-12)

Phase 2 as a monolith is ~10x Phase 1's complexity. It ships in two independently valuable slices:

Slice 2a — agent authn + policy, still read-only. Per-agent X-Ghpool-Key, default-deny tool allowlist enforced at the proxy + injected X-MCP-Tools upstream, tools/list pruning, per-agent audit attribution, TLS guidance. Upstream stays /readonly and the PAT pool stays. Immediate value: least privilege and per-agent attribution on reads; no fail-closed audit backend needed yet.

Slice 2b — writes. GitHub App credential backend (mint/refresh installation tokens), repo allowlists + resource resolution (deny-if-unresolvable), session-to-agent binding + revocation, durable fail-closed audit, write classification, safe-retry rules. Only after 2b is complete does any write tool go live. v0.4.0 releases when 2b closes.

Design updates from community review (adopted 2026-07-13):

1. 2b-5 credential model: per-envelope scoped installation tokens — mint with the API's repositories+permissions parameters so the token is already narrowed to the agent's allowlist; GitHub becomes the authoritative resource boundary, ghpool's argument parser is defense-in-depth. One credential per policy envelope.
2. Writes require the App backend, enforced in code — write path stays 403 without [mcp.github_app]; PATs never serve writes.
3. 2b-4 audit records tool-level outcomes — isError arrives inside HTTP 200/SSE, so write-call responses are buffered (bounded) and parsed before forwarding; HTTP status alone is not a success signal.
4. 2b-5 adds a simple per-agent in-flight cap (full quotas remain Phase 3).
5. Revocation semantics documented: config change = restart = all session pins cleared (in-memory), until hot-reload exists.

Checklist items below are tagged [2a]/[2b].

Gate checklist (from RFC Revision 2 — ALL required before writes)

• [2a] Agent authentication — X-Ghpool-Key per-agent API keys (baseline; SigV4 shim is Phase 3):
  • 256-bit entropy, constant-time comparison, excluded from logs/traces
  • two simultaneously valid keys per agent for zero-downtime rotation
  • key values resolved via existing secret-reference formats (env: / aws:secretsmanager: / k8s:)
• [2a] Per-agent default-deny policy — explicit tool allowlist + repo allowlist; new upstream tools are denied until added to policy
• [2b] Resource-level authorization (shipped: MCP 2b-2: write classification + per-agent repo allowlists #30) — resolve target repo from tool arguments; deny if unresolvable
• [2b] GitHub App credential backend (shipped: MCP 2b-3: GitHub App credential backend #31 — live-verified mint via e2e App-mode section) — installation tokens (1h TTL, auto-refresh, private key in AWS Secrets Manager) replace the PAT pool on the MCP path (compliance: avoids PAT rate-limit aggregation)
• [2b] Session-to-agent binding (shipped: MCP 2b-1: session-to-agent binding + dual-key rotation #28 + credential-lifetime in MCP 2b-3: GitHub App credential backend #31 — sessions cannot outlive their token) — a session ID presented with a different agent credential is rejected; sessions cannot outlive their upstream credential
• [2b] Credential/session revocation (shipped: MCP 2b-1: session-to-agent binding + dual-key rotation #28 dual keys; MCP 2b-5: enable writes behind the full gate (completes #17) #33 documents restart-clears-pins semantics) — key rotation, agent disable, or policy change invalidates affected sessions
• [2a] TLS requirement for production deployments (ghpool, ALB, or mesh terminated)
• [2b] Durable audit trail, fail-closed for writes (shipped: MCP 2b-4: durable fail-closed audit for write-classified calls #32 — incl. tool-level isError outcomes per review) — structured records (agent, session/RPC IDs, tool, resolved resource, policy version, decision, upstream credential ID, timestamps, result, redacted arg summary); writes rejected if the audit backend is unavailable
• [2b] Per-tool write classification (shipped: MCP 2b-2: write classification + per-agent repo allowlists #30) — distinguish read vs. write tools in policy
• [2a] Outbound header allowlist — strip ALL client-supplied X-MCP-* headers and rebuild from policy (client cannot widen its own permissions)
• [2b] Safe retry behavior (shipped: MCP 2b-5: enable writes behind the full gate (completes #17) #33 — never-retry guarantee documented; ambiguous outcomes audited as undeterminable) — no auto-retry for non-idempotent write calls
• [2a] tools/list response filtering — inject per-agent X-MCP-Tools: <exact allowlist> upstream (native filtering, verified in MCP proxy Phase 0: compliance & compatibility spike (hosted endpoint contract, App tokens) #22) AND enforce the same allowlist on tools/call at the proxy (authoritative; upstream header is defense-in-depth). Do NOT use X-MCP-Toolsets for enforcement — it fails open on invalid names (MCP proxy Phase 0: compliance & compatibility spike (hosted endpoint contract, App tokens) #22 finding F)
• [2b] Document + pin required GitHub App permission set (shipped: MCP 2b-5: enable writes behind the full gate (completes #17) #33 — README permission table) — tool surface varies with App permissions (MCP proxy Phase 0: compliance & compatibility spike (hosted endpoint contract, App tokens) #22 finding C); the policy model assumes a known baseline
• [2b] Session revocation is entirely local (shipped: documented in MCP 2b-5: enable writes behind the full gate (completes #17) #33 README — ghpool pin cache is the session authority) — upstream DELETE is a no-op (MCP proxy Phase 0: compliance & compatibility spike (hosted endpoint contract, App tokens) #22 finding I); ghpool's pin cache is the single source of session truth, so key rotation/agent disable/policy change need only invalidate local sessions

Policy config sketch

[[mcp.agents]]
id = "openab-bot"
key = "aws:secretsmanager:ghpool/mcp-keys:openab"   # or env: / k8s:
tools = ["issue_read", "create_issue", "add_issue_comment"]
repos = ["openabdev/ghpool", "openabdev/openab"]
readonly = false

Also fold in from Phase 1's accepted limitations

• allowed_owners-equivalent enforcement on the MCP path (superseded by the per-agent repos allowlist above)
• Client config example: { "url": "https://ghpool:8080/mcp", "headers": { "X-Ghpool-Key": "${GHPOOL_KEY}" } }

Open questions

• Audit backend choice for fail-closed writes (local WAL + ship vs. direct to CloudWatch/S3)
• Identity binding: verify key per request (stateless) vs. bind at session init alongside the pin (RFC leans session binding — required by the session-to-agent gate anyway)
• Tool→repo argument mapping table maintenance (deny-if-unresolvable covers unknown tools)

[vixenclawsastraagent]

This phase needs a credential architecture rather than adding MCP behavior directly to the existing PatPool. The current pool stores static tokens and selects only by remaining rate budget, but an MCP credential is chosen at initialization before the target repository is known. A pool containing identities with different repository access or permissions will therefore behave unpredictably and can violate the intended authorization boundary.

Recommended credential model

Introduce a renewable credential-provider abstraction that returns a lease such as:

CredentialLease {
  credential_id
  github_actor
  installation_id
  repositories / permission envelope
  token
  expires_at
}

For write-enabled agents, prefer a dedicated GitHub App installation credential over personal PATs. GitHub's hosted MCP endpoint accepts ghs_ installation tokens, and GitHub allows installation tokens to be narrowed to explicit repositories and a subset of the App's permissions. They expire after one hour, so ghpool must mint and refresh them from App credentials rather than load a one-hour token once at process startup.

GitHub documentation: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app

Official hosted-MCP example using installation tokens: https://github.com/actions/ai-inference#github-mcp-integration-model-context-protocol

I would make these rules explicit:

• Do not pool personal PAT identities for writes. Otherwise GitHub-side attribution changes depending on which human identity had the highest budget.
• A credential pool may contain multiple credentials only when they have the same actor model and an identical repository/permission envelope.
• Bind the selected credential lease, policy version, agent identity, and expiry to the MCP session.
• Never allow a session to outlive its credential. Expire with a safety margin and require reinitialization instead of silently switching actors.
• Define how cross-installation or cross-organization access works. One installation token represents one installation; one fixed session cannot safely select among unrelated installations without resource-aware routing.

Agent policy must include resources and exact tools

toolsets + readonly is not sufficient authorization. Suggested policy fields are:

AgentPolicy {
  agent_id
  credential_profile
  exact_tools
  readonly
  allowed_repositories / installation
  policy_version
  concurrency and rate limits
}

The strongest resource boundary is to mint a GitHub App installation token already restricted to the repositories and permissions authorized for that agent. ghpool can still validate tool arguments as defense in depth, but GitHub then rejects out-of-policy resources independently of ghpool's parser.

If proxy-side repository authorization is required, the design must define resource extraction per tool. Not every tool uses a simple owner and repo; searches, node IDs, URLs, workflows, projects, and user-level tools need explicit policy handling. Unknown or unresolved resource shapes should fail closed.

API-key and session requirements

• Verify the ghpool credential on every request; never treat Mcp-Session-Id as authentication.
• Use constant-time key comparison, high-entropy keys, log redaction, request throttling, and two active keys per agent for rotation.
• Require HTTPS or mTLS. The proposed http://ghpool:8080/mcp example sends X-Ghpool-Key in cleartext at the HTTP layer.
• Bind every session to the authenticated agent and reject the same session ID when presented by another agent.
• Invalidate sessions when an agent is disabled, a key is revoked, a policy is tightened, or repository access is removed.

SigV4/STS clarification

The Vault-style IAM pattern uses a specially signed STS GetCallerIdentity POST request. It should not be described merely as a generic presigned URL. Require a ghpool-specific server-ID header, include it in SignedHeaders, and verify the expected value to prevent a proof intended for one environment from being replayed against another. Also restrict the STS host, region, method, body, allowed headers, and validity window.

Reference: https://developer.hashicorp.com/vault/docs/auth/aws

If calling STS for every MCP request is too expensive, the signed proof can be exchanged for a short-lived, ghpool-audience credential. That still preserves the important property: the agent never receives a GitHub credential.

Write gate

Write access should remain disabled until all of these are present:

• exact per-tool allowlist;
• repository/installation authorization;
• renewable least-privilege upstream credential;
• TLS and per-request caller authentication;
• session revocation;
• durable audit records and a documented audit-failure policy;
• per-agent concurrency/rate limits; and
• no automatic retry of ambiguous write calls.

For write audits, record both the JSON-RPC transport result and the MCP tool result. A GitHub tool failure may be returned inside an HTTP 200/SSE response, so HTTP status alone is not a successful-operation signal.

[chaodu-agent]

Release plan: v0.4.0 ships when this Phase 2 gate is complete (decision 2026-07-12). Phase 1 (MCP read-only proxy, #20/#21/#23/#24) stays unreleased on main until then — latest release v0.3.4 predates MCP. Release checklist when closing this issue: release-pr flow → v0.4.0 tag → verify linux/darwin binary artifacts include the MCP feature.