Skip to content

Harden and document the mcp gateway Authorization header contract against workspace credential exposure #7794

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lpcox merged 3 commits into from
Aug 28, 2026
Merged

Harden and document the mcp gateway Authorization header contract against workspace credential exposure #7794

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2e5a0f8
Initial plan
Copilot Aug 27, 2026
ee5bbec
docs: document mcp gateway authorization header template invariant
Copilot Aug 27, 2026
48b1745
docs: clarify mcp gateway authorization hops
Copilot Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/awf-config-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1825,6 +1825,19 @@ the first supporting AWF release. Older AWF versions reject the closed

While the backend is still starting, mcpg may return retryable HTTP `503 backend_unavailable`. AWF retries `initialize` with bounded backoff until `AWF_ENCLAVE_MCP_READINESS_TIMEOUT_MS` expires, then fails closed before the primary agent starts.

The gateway has two separate authorization hops. AWF's upstream
`Authorization` header authenticates mcpg to the AWF-owned enclave server with
`AWF_ENCLAVE_MCP_CAPABILITY`. mcpg then generates the client-facing gateway
`Authorization` header from its gateway agent ID/API key; this is the header
present in mcpg's rewritten gateway output consumed by engine config adapters.
That downstream credential is distinct from the AWF capability.

Adapters consuming mcpg's rewritten output MUST keep the client-facing
`Authorization` value runtime-only: they must not resolve it while generating
configuration or persist the resolved credential under `GITHUB_WORKSPACE` (or
any other agent-readable path). The AWF upstream contract cannot enforce this
requirement on the downstream output/converter path.

For `issues-read-v1`, the compiler supplies
`AWF_ENCLAVE_GITHUB_PROXY_CONTAINER`,
`AWF_ENCLAVE_GITHUB_PROXY_IDENTITY`,
Expand Down
15 changes: 15 additions & 0 deletions docs/enclaves-architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,21 @@ executor tools. The compiler generates a fresh 64-character lowercase
hexadecimal capability, substitutes it into the mcpg authorization header, and
passes it to AWF without exposing it to the primary agent.

### Gateway authorization boundaries

There are two separate authorization hops. AWF's upstream contract
authenticates mcpg to the AWF-owned enclave server with the
`AWF_ENCLAVE_MCP_CAPABILITY`. mcpg independently authenticates the client-facing
gateway endpoint with its gateway agent ID/API key; that is the credential
returned in mcpg's rewritten gateway output.

Engine config adapters consume mcpg's rewritten output, not AWF's upstream
contract. Therefore adapters MUST treat the client-facing `Authorization`
header as a runtime-only value: they must not resolve it while generating
configuration, and must never persist the resolved gateway credential under
`GITHUB_WORKSPACE` or any other agent-readable path. AWF's upstream template
does not enforce this downstream requirement.

`gh-aw-mcpg` may start before the enclave server. While the backend is
unavailable, mcpg returns retryable HTTP `503 backend_unavailable`; AWF retries
the complete `initialize` handshake with bounded 500 ms backoff until
Expand Down
Loading