fix(config): reject backend-owned extra headers

Signed-off-by: Elyas Mehtabuddin <emehtabuddin@nvidia.com>

Author: elyasmnvidian

crates/libsy-llm-client/README.md

@@ -212,7 +212,9 @@ fn build_multi_format_client(
   `host`, `content-length`, `connection`, and the backend-owned
   `authorization` / `x-api-key` / `anthropic-version` / `content-type`. So a
   caller's placeholder credential never overrides the backend's real key.
-- Per-backend static headers go in `HttpBackendConfig::extra_headers`.
+- Per-backend custom headers go in `HttpBackendConfig::extra_headers`. Set credentials with
+  `api_key`; the client rejects `Authorization`, `x-api-key`, and `anthropic-version`
+  case-insensitively because the backend sets those headers.
 - Per-target top-level request defaults go in `HttpBackendConfig::extra_body`.
   The merge is shallow and fields already present in the request take precedence.
 - `HttpBackendConfig::max_retries` controls additional attempts after retryable

crates/libsy-llm-client/src/backend.rs

@@ -9,9 +9,10 @@ use reqwest::RequestBuilder;
 use serde_json::Value;
 use switchyard_protocol::WireFormat;
 
-use crate::error::is_overflow_body;
+use crate::error::{LlmClientError, Result, is_overflow_body};
 
 const ANTHROPIC_VERSION: &str = "2023-06-01";
+const RESERVED_EXTRA_HEADERS: &[&str] = &["authorization", "x-api-key", "anthropic-version"];
 
 /// Default number of retries for server-configured upstream calls.
 pub const DEFAULT_MAX_RETRIES: u32 = 2;
@@ -42,7 +43,10 @@ pub struct HttpBackendConfig {
     pub base_url: String,
     /// API key for the provider, loaded by the caller. `None` sends no auth.
     pub api_key: Option<String>,
-    /// Static headers added to every outbound call to this backend.
+    /// Custom headers added to every outbound call to this backend.
+    ///
+    /// Authentication and protocol headers are set by the backend and are
+    /// rejected when the client is built.
     pub extra_headers: BTreeMap<String, String>,
     /// Default top-level request fields, applied only when the request omits the key.
     pub extra_body: BTreeMap<String, Value>,
@@ -77,6 +81,22 @@ pub enum Backend {
 }
 
 impl Backend {
+    // Rejects backend-owned headers before building any request.
+    pub(crate) fn validate_extra_headers(&self, model_name: &str) -> Result<()> {
+        if let Some(name) = self.config().extra_headers.keys().find(|name| {
+            RESERVED_EXTRA_HEADERS
+                .iter()
+                .any(|reserved| name.eq_ignore_ascii_case(reserved))
+        }) {
+            return Err(LlmClientError::Configuration {
+                message: format!(
+                    "model {model_name:?} extra_headers cannot set reserved header {name:?}; the backend sets authentication and protocol headers"
+                ),
+            });
+        }
+        Ok(())
+    }
+
     /// The wire format the request IR is encoded to for this backend.
     pub fn wire_format(&self) -> WireFormat {
         match self {

crates/libsy-llm-client/src/client.rs

@@ -94,6 +94,14 @@ impl TranslatingLlmClient {
     /// Builds a client over the given [`ModelConfig`]s, with a fresh shared HTTP
     /// client and the built-in translation codecs.
     pub fn new(model_configs: &[ModelConfig]) -> Result<Self> {
+        for config in model_configs {
+            config
+                .default_backend
+                .validate_extra_headers(&config.model_name)?;
+            for backend in config.other_backends.iter().flatten() {
+                backend.validate_extra_headers(&config.model_name)?;
+            }
+        }
         let client =
             reqwest::Client::builder()
                 .build()
@@ -956,6 +964,30 @@ mod tests {
         request
     }
 
+    #[test]
+    fn client_rejects_reserved_headers_on_alternate_backends() {
+        for header in ["Authorization", "X-Api-Key", "ANTHROPIC-VERSION"] {
+            let mut alternate = config("https://example.test");
+            alternate
+                .extra_headers
+                .insert(header.to_string(), "injected".to_string());
+            let models = [ModelConfig::new(
+                "gpt",
+                Backend::OpenAiChat(config("https://example.test/v1")),
+                Some(vec![Backend::Anthropic(alternate)]),
+            )];
+
+            let Err(error) = TranslatingLlmClient::new(&models) else {
+                panic!("expected {header} to be rejected");
+            };
+            assert!(matches!(
+                error,
+                LlmClientError::Configuration { message }
+                    if message.contains(&format!("reserved header {header:?}"))
+            ));
+        }
+    }
+
     #[tokio::test]
     async fn missing_model_errors()
     -> std::result::Result<(), Box<dyn Error + Sync + Send + 'static>> {

crates/switchyard-server/src/config.rs

@@ -1459,6 +1459,52 @@ target = "azure"
         Ok(())
     }
 
+    #[test]
+    fn backend_owned_extra_headers_are_rejected_case_insensitively() {
+        let cases = [
+            (
+                "base_url = \"https://example.test/v1\"",
+                "base_url = \"https://example.test/v1\"\n\
+                 extra_headers = { Authorization = \"injected\" }",
+                "Authorization",
+            ),
+            (
+                "base_url = \"https://example.test\"",
+                "base_url = \"https://example.test\"\n\
+                 extra_headers = { \"X-Api-Key\" = \"injected\" }",
+                "X-Api-Key",
+            ),
+            (
+                "base_url = \"https://example.test\"",
+                "base_url = \"https://example.test\"\n\
+                 extra_headers = { \"ANTHROPIC-VERSION\" = \"injected\" }",
+                "ANTHROPIC-VERSION",
+            ),
+        ];
+
+        for (original, replacement, header) in cases {
+            let configured = VALID_CONFIG.replacen(original, replacement, 1);
+            let error = error_message(&configured);
+            assert!(
+                error.contains(&format!("reserved header {header:?}")),
+                "expected {header} to be rejected, got: {error}"
+            );
+        }
+    }
+
+    #[test]
+    fn custom_extra_headers_remain_valid() -> ServerResult<()> {
+        let configured = VALID_CONFIG.replacen(
+            "base_url = \"https://example.test/v1\"",
+            "base_url = \"https://example.test/v1\"\n\
+             extra_headers = { X-Inference-Priority = \"batch\" }",
+            1,
+        );
+
+        server_state_from_toml(&configured)?;
+        Ok(())
+    }
+
     #[test]
     fn retry_budget_defaults_and_accepts_an_override() -> ServerResult<()> {
         let default: ServerConfig = toml::from_str(VALID_CONFIG).map_err(|error| {

docs/reference/toml_schema.md

@@ -45,7 +45,7 @@ route reaches no upstream. A file without a `[targets]` table is rejected with
 | `format` | Yes | — | `openai_chat`, `openai_responses`, or `anthropic_messages`. |
 | `base_url` | Yes | — | Upstream base URL. |
 | `api_key_env` | No | unset | Name of the environment variable holding the key. Omit to send no authentication. |
-| `extra_headers` | No | `{}` | Extra HTTP headers sent upstream. |
+| `extra_headers` | No | `{}` | Custom HTTP headers sent upstream. Set credentials with `api_key_env`; `Authorization`, `x-api-key`, and `anthropic-version` are rejected case-insensitively because the backend sets them. |
 | `max_retries` | No | `2` | Retry budget, `0`–`10`. |
 
 The TOML never contains the secret itself. `api_key_env` names a variable that