feature: safely forward an authenticated caller credential to a trusted upstream gateway

Use case

Some deployments place Semantic Router in front of a trusted gateway such as LiteLLM:

client credential -> vLLM Semantic Router -> trusted gateway -> model provider

They want the downstream gateway to retain per-caller spend, quota, and rate-limit attribution, including each internal Looper call.

Audited upstream baseline (2026-07-15)

Current main already supports per-user provider credentials injected by an external authorization service through pkg/authz; those dedicated headers are resolved for the selected provider and stripped to prevent leakage. It does not expose a generic forward_authorization_header backend field that copies the request's inbound Authorization value to an upstream.

Those are different trust contracts. The inbound bearer token may authenticate the caller to Semantic Router and may not be valid or safe to disclose to a model provider. Passthrough must therefore be limited to a separately configured, trusted upstream gateway.

Scope

• Define an explicit backend/profile option for forwarding a reviewed caller credential to an allowlisted trusted gateway.
• Distinguish the router-authentication credential, ext-authz-injected provider credentials, and the credential intended for the downstream gateway.
• Require a trusted authentication result before forwarding; never trust an arbitrary client-selected tenant or target.
• Apply the same credential resolution to direct calls and every Looper/Flow/Fusion/ReMoM leg.
• Fail closed when the required forwarded credential is missing or invalid.
• Redact the credential from logs, traces, metrics, Replay, errors, and dashboard state.

Boundaries

• Disabled by default.
• Do not forward Authorization verbatim to arbitrary model endpoints.
• Do not silently fall back to a shared service credential, because that changes attribution and can bypass caller budgets.
• Do not let request input choose the backend or enable passthrough.
• Keep existing static/provider and ext-authz-injected credential behavior unchanged.

Acceptance criteria

• Only allowlisted trusted backend profiles can enable caller-credential forwarding.
• Direct and internal multi-call paths propagate the intended credential consistently.
• Missing/denied credentials fail before an upstream call.
• No credential value appears in logs, Replay, traces, metrics, config projection, or errors.
• Tests cover disabled/default behavior, trusted forwarding, untrusted target rejection, Looper fan-out, redirects, and provider-profile interaction.
• Security and deployment docs describe the trust boundary and rotation/revocation behavior.

Relevant surfaces

src/semantic-router/pkg/authz, src/semantic-router/pkg/extproc, provider/backend profiles, multi-tenancy (#2342/#2362), diagnostics, and E2E tests.