feat(plugins): Add top-level API header injection

[carderne]

Add plugin-level API header injection for providers that authenticate through host-managed HTTP headers. Header-authenticated plugins now declare api-domains and api-headers at the manifest top level, keeping real header values in deployment env and out of sandbox env vars.

Manifest Shape

Header-only providers no longer use a credential type. Env-backed header values use declared ${NAME} placeholders, and API header env vars cannot define defaults.

Before, header auth was modeled as a credential type:

credentials:
  type: static-headers
  api-domains:
    - api.example.com
  api-headers:
    Authorization: ${EXAMPLE_AUTH_HEADER}

After, headers are plugin-level request metadata:

env-vars:
  EXAMPLE_AUTH_HEADER:

api-domains:
  - api.example.com

api-headers:
  Authorization: ${EXAMPLE_AUTH_HEADER}

Credential Interaction

credentials.type stays limited to oauth-bearer and github-app. Existing credentials.api-headers remains only as extra token-backed headers, while top-level API headers can stand alone or combine with token credentials; token credential headers win on overlap.

Runtime Safety

Header transforms are attached by the capability runtime to sandbox bash executions; the model-facing bash schema remains command-only. Eval mode uses deterministic dummy header values so test brokers never read deployment secrets.

[vercel]

@carderne is attempting to deploy a commit to the Sentry Team on Vercel.

A member of the Team first needs to authorize it.

[dcramer]

tbqh i think the goal of this is totally reasonable. will take a look at make sure it hits our stability reqs as sometimes the test suite here isnt capable enough still

[carderne]

@dcramer great. Happy for you to implement this however you like, or equally happy to take some nudges on this PR (just mention because going by commit history it seems a relatively private project).

Either way I'll look a bit closer at the code this week, since I'm using this in production now.

Two notes:

1. The name static-headers is a bit weird since they're actually dynamic (just less dynamic than the others).
2. It doesn't interpolate, just replace. Might be worth extending to support that, probably expected...

  api-headers:
    Authorization: "Bearer $TOKEN" // DOES NOT work
    Authorization: "$AUTH_HEADER"  // works

[dcramer]

im dropping the credentials bit here and just allow headers to be configured like this - should simplify the whole thing

dont think there's any reason to require the extra step. just working through quality checks rn

[dcramer]

Final implementation outcome after the cleanup pass:

This PR no longer adds a new credential type. The final manifest shape is top-level API header injection:

env-vars:
  EXAMPLE_AUTH_HEADER:

api-domains:
  - api.example.com

api-headers:
  Authorization: ${EXAMPLE_AUTH_HEADER}
  X-Api-Version: "2026-01-01"

Key contract:

• credentials.type remains limited to oauth-bearer and github-app.
• Header-only providers use top-level api-headers and api-domains; if headers exist, the runtime creates a broker and injects matching sandbox header transforms.
• Header values can reference declared ${ENV_VAR} placeholders, matching the MCP env-var pattern. API header env vars cannot declare defaults because they may carry secrets.
• Literal header values are also supported.
• Existing credentials.api-headers still works only as extra headers alongside token-backed credentials, with Authorization reserved there.
• When top-level headers are combined with token-backed credentials, credential headers are applied last and win on duplicate header names for the same domain.

Security/runtime notes:

• Real secret values stay host-side and are delivered only through Vercel Sandbox network header transforms.
• The model-facing bash tool still only accepts command; header transforms are attached by the runtime, not by model input.
• Eval mode uses deterministic dummy header values instead of reading deployment secrets.

Validation done locally:

• targeted plugin/capability tests: 8 files, 44 tests passed
• pnpm typecheck passed
• pnpm docs:check passed after docs changes

Remaining check noise is external to this patch: Vercel requires fork deploy authorization, and Warden can fail on fork PRs when required app secrets are unavailable.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 5 additional findings.