feat(server): forward inbound Anthropic auth

[elyasmnvidian]

[llm_clients.claude]
format = "anthropic_messages"
base_url = "https://api.anthropic.com"

When Claude Code sends an Authorization header to /v1/messages, Switchyard removes the header before it calls this upstream. The same happens to x-api-key.

The regression test records the upstream rejection:

assertion `left == right` failed
  left: 401
 right: 200

This PR adds an opt-in forward_auth = true setting for anthropic_messages clients. Switchyard then forwards the caller's Authorization or x-api-key header instead of using api_key_env. Claude subscription OAuth also keeps oauth-* markers from anthropic-beta; other inbound beta markers remain filtered.

forward_auth stays disabled by default. Configuration loading rejects it for non-Anthropic clients and rejects competing credentials from api_key_env or extra_headers.

After enabling the setting, anthropic_client_forwards_inbound_auth_when_configured sends requests through /v1/messages to a local Anthropic stub. The stub returns HTTP 200 for both an OAuth bearer credential and an x-api-key. The test also verifies that Switchyard sets anthropic-version and removes an unrelated inbound beta marker.

Closes #164

Summary by CodeRabbit

• New Features

  • Added optional authentication forwarding for Anthropic Messages clients.
  • Caller authorization or API-key credentials can now be forwarded upstream.
  • Claude subscription OAuth beta markers are preserved when applicable.
  • Added validation to prevent incompatible authentication configurations.

• Documentation

  • Updated setup guides, configuration references, and client documentation with forwarding instructions and requirements.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://NVIDIA-NeMo.github.io/Switchyard/pr-preview/pr-372/
Built to branch gh-pages at 2026-08-11 20:39 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[coderabbitai]

Walkthrough

The change adds forward_auth for Anthropic clients. It forwards caller credentials and selected OAuth beta markers, validates incompatible configuration, adds integration coverage, and documents the setting.

Changes

Anthropic authentication forwarding

Layer / File(s)	Summary
Client authentication forwarding crates/libsy-llm-client/src/backend.rs, crates/libsy-llm-client/src/client.rs	Adds forward_auth and conditionally forwards authorization, x-api-key, and oauth-* Anthropic beta markers.
Server configuration and validation crates/switchyard-server/src/config.rs	Adds the setting, validates supported combinations, and passes it to HttpBackendConfig.
End-to-end forwarding tests crates/switchyard-server/tests/server.rs	Adds an authenticated Anthropic mock endpoint and tests OAuth and API-key forwarding.
Configuration documentation crates/libsy-llm-client/README.md, crates/switchyard-server/README.md, docs/getting_started.md, docs/reference/toml_schema.md	Documents the setting, default behavior, supported credentials, and incompatible options.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Poem

I’m a small rabbit guarding the gate,
OAuth and API keys now travel straight.
Beta markers shed what should not stay,
Tests watch each credential on its way.
Hop, hop—Anthropic calls obey!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: forwarding inbound Anthropic authentication through the server.
Linked Issues check	✅ Passed	The changes implement inbound Anthropic credential forwarding, OAuth marker filtering, validation, documentation, and regression coverage requested by issue #164.
Out of Scope Changes check	✅ Passed	The code, tests, and documentation changes directly support the requested Anthropic authentication forwarding feature.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/libsy-llm-client/README.md`:
- Around line 216-220: Update the HttpBackendConfig::forward_auth documentation
to explicitly scope credential and anthropic-beta forwarding behavior to
Anthropic backends, particularly anthropic_messages clients, and clarify that it
does not apply to OpenAI backends.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 40554ecd-43d1-4be7-ac4e-166ad0b5b978

📥 Commits

Reviewing files that changed from the base of the PR and between 58f355a and 4de6f1b.

📒 Files selected for processing (8)

• crates/libsy-llm-client/README.md
• crates/libsy-llm-client/src/backend.rs
• crates/libsy-llm-client/src/client.rs
• crates/switchyard-server/README.md
• crates/switchyard-server/src/config.rs
• crates/switchyard-server/tests/server.rs
• docs/getting_started.md
• docs/reference/toml_schema.md

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Limit this behavior to Anthropic backends.

HttpBackendConfig is shared by OpenAI and Anthropic backends, but forward_auth = true is supported for anthropic_messages clients. As written, this text can imply that OpenAI backends also forward caller credentials.

Proposed wording

-- `HttpBackendConfig::forward_auth` forwards the caller's `authorization` or
+- For an Anthropic backend, `HttpBackendConfig::forward_auth` forwards the caller's `authorization` or
  `x-api-key` header instead of using the backend's configured key.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- `HttpBackendConfig::forward_auth` forwards the caller's `authorization` or
	`x-api-key` header instead of using the backend's configured key. Leave it
	disabled unless the configured upstream should receive each caller's credential.
	It also forwards `oauth-*` markers from `anthropic-beta` while removing other
	caller-supplied beta values.
	- For an Anthropic backend, `HttpBackendConfig::forward_auth` forwards the caller's `authorization` or
	`x-api-key` header instead of using the backend's configured key. Leave it
	disabled unless the configured upstream should receive each caller's credential.
	It also forwards `oauth-*` markers from `anthropic-beta` while removing other
	caller-supplied beta values.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/libsy-llm-client/README.md` around lines 216 - 220, Update the
HttpBackendConfig::forward_auth documentation to explicitly scope credential and
anthropic-beta forwarding behavior to Anthropic backends, particularly
anthropic_messages clients, and clarify that it does not apply to OpenAI
backends.