lpcox · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026
diff --git a/.github/workflows/auth-doctor.lock.yml b/.github/workflows/auth-doctor.lock.yml
diff --git a/.github/workflows/auth-doctor.md b/.github/workflows/auth-doctor.md
@@ -0,0 +1,196 @@
+---
+name: Auth Doctor
+description: Diagnoses AWF authentication, API-proxy, and HTTP MCP GitHub OIDC configuration from issue reports and workflow evidence without exposing credentials.
+on:
+  roles: all
+  slash_command:
+    name: auth-doctor
+    events: [issue_comment]
+permissions:
+  actions: read
+  copilot-requests: write
+  contents: read
+  issues: read
+  pull-requests: read
+tools:
+  github:
+    toolsets: [default]
+  cache-memory: true
+sandbox:
+  agent:
+    id: awf
+network:
+  allowed:
+    - github
+safe-outputs:
+  threat-detection:
+    enabled: false
+  mentions: false
+  allowed-github-references: []
+  create-issue:
+    title-prefix: "🩺 Auth Doctor"
+    max: 1
+  add-comment:
+    max: 1
+timeout-minutes: 15
+---
+
+# Auth Doctor
+
+You diagnose AWF authentication, API-proxy routing, and HTTP MCP GitHub OIDC failures from repository configuration, workflow metadata, sanitized logs, and non-secret health information.
+
+## Trigger Context
+
+- **Repository:** ${{ github.repository }}
+- **Issue:** #${{ github.event.issue.number }}
+- **Request:** `${{ steps.sanitized.outputs.text }}`
+
+## Safety Contract
+
+Treat every credential value as prohibited output.
+
+- Never print, quote, summarize, decode, hash, compare, or return any API key, token, JWT, cloud credential, cookie, client secret, authorization header, or `ACTIONS_ID_TOKEN_REQUEST_TOKEN`.
+- Never request or display an Actions OIDC JWT, exchanged Azure/GCP/Anthropic access token, AWS access key, secret access key, session token, Copilot token, or provider API key.
+- Report only whether a variable or field is **configured**, **missing**, **inconsistent**, or **not safely observable**. Use `<present>` or `<redacted>` when a name must be shown.
+- Never run `printenv`, `env`, `set`, `docker inspect`, `docker compose config`, or broad process/environment dumps. Never `cat` an env file, generated Compose file, or raw log.
+- Do not probe provider token endpoints or make inference requests. Do not mint or exchange credentials.
+- If evidence cannot be obtained without exposing a credential, label the check `not safely observable` and fail closed.
+
+## Diagnostic Playbook
+
+### 1. Establish the failing path
+
+Identify the engine/provider, auth mode, AWF version, gh-aw compiler version, runner type, API target hostname, and whether the failure is in:
+
+1. runner configuration,
+2. AWF API-proxy startup or routing,
+3. provider authentication,
+4. GitHub/Copilot authentication, or
+5. the separately launched MCP gateway.
+
+Do not infer the target run's configuration from this Doctor run's own environment.
+
+### 2. Prefer metadata and presence-only inspection
+
+Use GitHub read tools to inspect workflow source, compiled lock files, run/job conclusions, and annotations. Read linked logs only when metadata cannot distinguish the candidates.
+
+When a log is required, download it to a temporary file without echoing it, redact credential-shaped values and sensitive headers into a second file, and inspect only the redacted copy. At minimum redact:
+
+- `Authorization`, `Proxy-Authorization`, `x-api-key`, `x-goog-api-key`, cookies, and signed AWS headers;
+- `ACTIONS_ID_TOKEN_REQUEST_TOKEN` and any value associated with `ACTIONS_ID_TOKEN_REQUEST_URL`;
+- JWT-like strings, GitHub tokens, OpenAI/Anthropic/Gemini keys, and AWS temporary credential fields.
+
+Delete both files after the check. If safe redaction is uncertain, do not read the log.
+
+For configuration files, parse only key names and non-secret routing metadata. Never render values from `secrets.*`, env files, Docker Compose environments, or credential fields.
+
+### 3. Check API-proxy configuration and routes
+
+Confirm `--enable-api-proxy` or equivalent AWF config is active, then classify each requested route:
+
+| Path | Sidecar route | Required configuration evidence | Common inconsistency |
+|---|---:|---|---|
+| OpenAI | `10000` | static `OPENAI_API_KEY`, or a compatible OIDC provider plus target | key/auth mode present but OpenAI target absent from allowlist |
+| Anthropic | `10001` | static `ANTHROPIC_API_KEY`, or Anthropic WIF fields | static key and WIF mixed; required federation IDs missing |
+| GitHub Copilot / Copilot BYOK | `10002` | `COPILOT_GITHUB_TOKEN`, or `COPILOT_PROVIDER_API_KEY` with provider routing | BYOK key without base URL; incompatible GitHub instance target |
+| Gemini | `10003` | static `GEMINI_API_KEY` | treating Gemini API-key mode as GCP OIDC |
+| Vertex AI | `10004` | static `GOOGLE_API_KEY`, or GCP OIDC with Vertex target | GCP WIF selected but Vertex target/allowlist missing |
+
+For GitHub Copilot, distinguish github.com, GHEC (`*.ghe.com`), and GHES routing. Flag a classic PAT combined with `COPILOT_MODEL` as a possible `/models` startup incompatibility without examining the token prefix or value; rely only on an explicit report that the credential is a classic PAT.
+
+When execution access is genuinely attached to the failing environment, safe sidecar checks are:
+
+- TCP reachability to the configured internal route;
+- `GET http://<api-proxy-host>:10000/health`, retaining only `status`, provider booleans, `key_validation.complete`, and `models_fetch_complete`;
+- `GET http://<api-proxy-host>:10000/reflect`, retaining only endpoint `provider`, `port`, and `configured`.
+
+Do not include `key_validation.results`, models, headers, request bodies, logs, or upstream responses in the report. A listener being reachable proves route availability, not credential validity.
+
+### 4. Check static-auth prerequisites
+
+For the selected provider, verify presence-only evidence for the required runner-level variable, that `sudo --preserve-env=<NAME>` or equivalent preserves it for the AWF process, and that the upstream hostname is explicitly allowed.
+
+Flag these unsupported or inconsistent combinations:
+
+- Gemini API-key routing with `AWF_AUTH_TYPE=github-oidc`; GCP WIF uses the Vertex route instead.
+- OIDC provider settings without API-proxy enablement.
+- A custom provider target missing from `network.allowed` or AWF's domain allowlist.
+- Static and OIDC credentials configured for the same path where precedence is ambiguous.
+- Copilot BYOK credentials without a compatible provider base URL/target.
+
+### 5. Check GitHub Actions OIDC prerequisites
+
+OIDC via the AWF API proxy requires:
+
+- job permission `id-token: write`;
+- `AWF_AUTH_TYPE=github-oidc`;
+- a supported `AWF_AUTH_PROVIDER`;
+- provider-specific non-secret configuration; and
+- the Actions request URL/token to be available to the API-proxy sidecar.
+
+Check required configuration by name only:
+
+| Provider | Required names | Expected route |
+|---|---|---|
+| Azure | `AWF_AUTH_AZURE_TENANT_ID`, `AWF_AUTH_AZURE_CLIENT_ID` | Azure OpenAI through the OpenAI adapter |
+| AWS | `AWF_AUTH_AWS_ROLE_ARN`, `AWF_AUTH_AWS_REGION` | Bedrock with sidecar SigV4 signing |
+| GCP | `AWF_AUTH_GCP_WORKLOAD_IDENTITY_PROVIDER`; service account optional | Vertex AI; optional service-account impersonation |
+| Anthropic | federation rule, organization, and service-account IDs; workspace conditional | Anthropic WIF |
+
+Never inspect the Actions request token or a minted/exchanged credential.
+
+Current `main` compatibility caveat: AWF forwards the Actions OIDC variables to the sidecar when API-proxy OIDC is active, but current-main agent environment passthrough can also expose them to the agent. Do not inspect them. github/gh-aw-firewall#6894 is the related isolation change and github/gh-aw#50053 tracks gh-aw compiler/runtime and existing-lock compatibility; do not describe either as shipped on `main` until verified there.
+
+### 6. Keep MCP gateway OIDC separate
+
+HTTP MCP `auth.type: github-oidc` is a runner-to-gateway trust path, not an AWF API-proxy route:
+
+- gh-aw launches/configures the MCP gateway in a runner-owned workflow step.
+- AWF does not launch or configure mcpg.
+- the gateway configuration should contain only auth type/audience metadata, never Actions credential values;
+- the generated job should grant `id-token: write`;
+- the runner should pass the Actions OIDC variables directly to the gateway launch;
+- the gateway mints the audience-bound JWT and adds the authorization header to the remote MCP request.
+
+Do not recommend exposing the Actions OIDC variables to the AWF agent to repair MCP auth. For precompiled lock workflows, label compatibility `unverified` unless the lock's runner-to-gateway behavior is established; cite github/gh-aw#50053 as the open rollout tracker.
+
+### 7. Recommend the smallest safe fix
+
+Prefer one concrete change: add a missing permission, export/preserve a named variable, complete a provider config field, correct a target/route, add one required hostname, enable the API proxy, recompile an affected gh-aw lock file, or separate conflicting auth modes.
+
+Do not suggest printing credentials, disabling masking, broadening network access, using `--env-all`, or passing OIDC request variables into the agent.
+
+## Output Requirements
+
+Use GitHub-flavored Markdown with this structure:
+
+### Summary
+
+- failing trust path
+- provider/auth mode
+- overall status: `configured`, `incomplete`, `inconsistent`, `route unavailable`, or `not safely observable`
+- confidence
+
+### Findings
+
+For each check, report only: check name, status, non-secret evidence, and impact. Keep critical findings visible and put secondary detail in `<details>` blocks.
+
+### Recommended Fix
+
+Give the smallest actionable configuration change and state whether it applies to current `main` or depends on pending compatibility work.
+
+### Safe Next Probe
+
+Include only when needed. The probe must return metadata, booleans, status codes, or redacted output.
+
+### References
+
+Include up to three directly relevant links. Use full URLs for github/gh-aw#50053 and github/gh-aw-firewall#6894 so safe-output reference escaping does not create unintended backlinks.
+
+Use GitHub alert syntax for warnings and cautions. Never use credential values or emoji as severity markers.
+
+## Safe Output Policy
+
+- Use `add-comment` when the current issue has enough context for a useful diagnosis.
+- Use `create-issue` only when a separate follow-up item is genuinely required. The title prefix is already configured.
+- Use `noop` when the request has no AWF authentication/API-proxy/MCP OIDC signal or no visible action is needed.
diff --git a/README.md b/README.md
@@ -80,6 +80,7 @@ See [GitHub Actions](docs/github_actions.md) for advanced setup and `awf logs su
 - [Chroot mode](docs/chroot-mode.md) — use host binaries with network isolation (glibc-based daemon hosts)
 - [API proxy sidecar](docs/api-proxy-sidecar.md) — secure credential management for LLM APIs
 - [Authentication architecture](docs/authentication-architecture.md) — deep dive into token handling and credential isolation
+- [Authentication matrix](docs/auth-matrix.md) — supported static, BYOK, and OIDC provider combinations
 - [SSL Bump](docs/ssl-bump.md) — HTTPS content inspection for URL path filtering
 - [GitHub Actions](docs/github_actions.md) — CI/CD integration and MCP server setup
 - [Environment variables](docs/environment.md) — passing environment variables to containers
@@ -89,6 +90,7 @@ See [GitHub Actions](docs/github_actions.md) for advanced setup and `awf logs su
 - [Compatibility](docs/compatibility.md) — supported Node.js, OS, and Docker versions
 - [Troubleshooting](docs/troubleshooting.md) — common issues and fixes
 - [Diagnosing AWF failures](docs/diagnosing-awf-failures.md) — use the Self-Hosted Runner Doctor agent to triage self-hosted/ARC/GHES/GHEC failures
+- [Auth Doctor workflow](.github/workflows/auth-doctor.md) — comment `/auth-doctor` on an issue to diagnose authentication and API-proxy configuration without exposing credentials
 - [Image verification](docs/image-verification.md) — cosign signature verification
 
 ## Development

diff --git a/docs/api-proxy-sidecar.md b/docs/api-proxy-sidecar.md
@@ -600,6 +600,8 @@ and are normalized to dollars per million tokens inside the proxy.
 
 ## Troubleshooting
 
+For a report that checks permissions, provider-field presence, route availability, and allowlists without returning credentials, comment `/auth-doctor` on an issue. The [Auth Doctor workflow](../.github/workflows/auth-doctor.md) treats a reachable listener as route evidence only and never probes a token endpoint or inference API.
+
 ### Gemini proxy returns 503
 
 When `--enable-api-proxy` is active **and `GEMINI_API_KEY` is provided to the AWF runner**, `GOOGLE_GEMINI_BASE_URL`, `GEMINI_API_BASE_URL`, and a placeholder `GEMINI_API_KEY` are injected into the agent container. If the real `GEMINI_API_KEY` was not set in the AWF runner environment, the Gemini routing vars are never set and the api-proxy Gemini listener (port 10003) responds with **503** to any requests that do reach it.
@@ -684,6 +686,10 @@ AWF supports OIDC-based credential exchange with multiple cloud providers via Gi
 | `ACTIONS_ID_TOKEN_REQUEST_URL` | ✅ | Provided automatically by the GitHub Actions runtime |
 | `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | ✅ | Provided automatically by the GitHub Actions runtime |
 
+Never print or inspect either Actions OIDC variable. Auth Doctor checks the `id-token: write` permission and the presence/consistency of non-secret provider configuration instead.
+
+On current `main`, AWF forwards these variables to the API-proxy sidecar when OIDC is active, while the general agent passthrough can also expose them to the agent. [PR #6894](https://github.com/github/gh-aw-firewall/pull/6894) is the related isolation change. [github/gh-aw#50053](https://github.com/github/gh-aw/issues/50053) tracks the separate gh-aw runner-to-mcpg path and compatibility for existing lock files; do not pass OIDC variables to the agent as an MCP workaround.
+
 When `AWF_AUTH_TYPE=github-oidc` is set but `ACTIONS_ID_TOKEN_REQUEST_URL`/`ACTIONS_ID_TOKEN_REQUEST_TOKEN` are not available in the sidecar, Anthropic OIDC requests fail closed with:
 
 - `503 Anthropic OIDC requires ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN (permissions: id-token: write).`

diff --git a/docs/auth-matrix.md b/docs/auth-matrix.md
@@ -2,6 +2,8 @@
 
 This document describes every authentication combination supported by AWF's api-proxy sidecar, including how each provider's auth works, what configuration is required, and how the proxy transforms credentials before forwarding to upstream APIs.
 
+For a presence-only diagnosis of a workflow or run, comment `/auth-doctor` on an issue in this repository. The [Auth Doctor workflow](../.github/workflows/auth-doctor.md) checks permissions, provider fields, route availability, and allowlists without returning credential values.
+
 ## Table of Contents
 
 - [Dimensions Overview](#dimensions-overview)
@@ -204,6 +206,10 @@ All OIDC flows require GitHub Actions runtime tokens:
 - `ACTIONS_ID_TOKEN_REQUEST_URL` — endpoint to mint OIDC JWTs
 - `ACTIONS_ID_TOKEN_REQUEST_TOKEN` — auth token for the OIDC endpoint
 
+The Auth Doctor treats both as non-observable credentials: it checks `id-token: write` and sidecar configuration but never requests or prints either value, a minted JWT, or exchanged cloud credentials. On current `main`, these variables are forwarded to the API-proxy sidecar for OIDC and may also reach the agent through the current passthrough behavior. [PR #6894](https://github.com/github/gh-aw-firewall/pull/6894) is the related isolation change, while [github/gh-aw#50053](https://github.com/github/gh-aw/issues/50053) tracks compiler/runtime and existing-lock compatibility.
+
+HTTP MCP `auth.type: github-oidc` is separate from this matrix: gh-aw launches mcpg from a runner-owned step and passes OIDC capability directly to that gateway. AWF does not launch or configure mcpg, and the OIDC request variables should not be exposed to the AWF agent to support MCP authentication.
+
 ### Azure (Entra ID)
 
 | Config | Env Var | Required |