antoinezambelli
diff --git a/‎CHANGELOG.md‎
Lines changed: 13 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 13 additions & 0 deletions
diff --git a/‎docs/BACKEND_SETUP.md‎
Lines changed: 97 additions & 0 deletions b/‎docs/BACKEND_SETUP.md‎
Lines changed: 97 additions & 0 deletions
diff --git a/‎pyproject.toml‎
Lines changed: 1 addition & 1 deletion b/‎pyproject.toml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎scripts/integration_test_proxy.py‎
Lines changed: 3 additions & 3 deletions b/‎scripts/integration_test_proxy.py‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎scripts/smoke_test_proxy.py‎
Lines changed: 118 additions & 1 deletion b/‎scripts/smoke_test_proxy.py‎
Lines changed: 118 additions & 1 deletion
@@ -2,6 +2,19 @@
 
 All notable changes to forge are documented here.
 
+## [0.8.0] — 2026-06-27
+
+First-class authentication across all proxy modes and backends. forge now forwards exactly one credential to the backend — a static `--backend-api-key` or a single inbound auth header — relocating it across protocols (`x-api-key` ↔ `Authorization: Bearer`) when the frontend and backend differ. Gated OpenAI-compatible backends (LM Studio, hosted vLLM, service accounts) work without monkey-patching. Closes #119.
+
+### Added
+- **`--backend-api-key` / `FORGE_BACKEND_API_KEY`** — a static credential forge sends to the backend in its native auth slot (LM Studio, hosted providers, service accounts — the case where the caller sends nothing). Baked into the backend client at startup and relocated to the backend's protocol slot. When set, an inbound auth header is refused as a second credential.
+- **Cross-protocol credential relocation** — an inbound `x-api-key` ↔ `Authorization: Bearer` is rewritten to the backend's protocol when frontend and backend differ (the SSO/forwarded-token case). Frontend protocol is by path (`/v1/chat/completions` = openai, `/v1/messages` = anthropic); backend by `--backend-protocol`. See the auth section in [Backend Setup](docs/BACKEND_SETUP.md).
+- **Deferred backend discovery for gated external backends.** The context-length / served-model-name probe (llama.cpp `/props`, vLLM `/v1/models`) now runs on the **first request**, authenticated by that request's credential, instead of unauthenticated at startup — which previously 401'd and crashed boot against a gated backend. Managed mode and the Anthropic external path are unaffected. New `LLMClient.discover_backend_metadata(extra_headers)`; vLLM collapses its two `/v1/models` round-trips into one.
+
+### Changed
+- **BREAKING — credential handling for auth-required backends.** This only affects backends that *require* auth. **Ungated local backends are unchanged — leave `--backend-api-key` unset and send no auth header, exactly as before; zero credentials is the normal local path and still works.** What changed: when a backend *does* require a credential, a request carrying **zero** now fails loud (401) instead of sending an empty/garbage header that produced an opaque downstream error; and **two** credentials at once (static + inbound, or two inbound auth headers) are refused with **400** rather than one silently winning. Migration: nothing to do for local/ungated backends. For gated backends, supply exactly one credential — set `--backend-api-key` (or `FORGE_BACKEND_API_KEY`), *or* forward an inbound auth header, not both.
+- **Removed the silent `extra_headers`-overrides-`api_key` merge.** A per-call auth header in `extra_headers` no longer shadows a client's configured `api_key`; that combination is now a two-credential conflict (400). Migration: pass the credential one way only. (Undocumented prior behavior, unlikely to be relied on.)
+
 ## [0.7.6] — 2026-06-20
 
 A bug-fix release for the Ollama backend and inline reasoning capture. Multi-turn tool sessions and multi-part message content no longer 400 against Ollama's native API, and chain-of-thought emitted inline in `content` is now captured on vLLM and Ollama as it already was on the structured-field path.
 
@@ -15,6 +15,103 @@ Install instructions for each backend live with the upstream project. Below is w
 
 ---
 
+## Authentication
+
+forge carries **exactly one credential** to the backend, placed in the backend's
+native auth header. forge does not validate the credential, manage its lifecycle
+(expiry/refresh), or form any opinion on its value — it only relocates it into
+the correct header slot for the target backend. Auth failures therefore surface
+as the backend's own error (401/403), not a forge error.
+
+**The one rule:** exactly one credential reaches the backend. If two are present
+anywhere, forge **refuses the request** — it never merges, never picks a winner,
+never silently drops one. (Design Principle #1: fail fast, fail loud.)
+
+### WorkflowRunner (library use)
+
+Supply the credential at construction, or per call for a rotating token:
+
+```python
+# Static credential (API key, service account): set once at construction.
+client = OpenAICompatClient(model=..., base_url=..., api_key=API_KEY)
+
+# Rotating credential (e.g. an SSO token refreshed out of band): per call.
+await client.send(messages, extra_headers={"Authorization": f"Bearer {token()}"})
+```
+
+A construction credential **and** a per-call auth header on the same call is two
+credentials → raises `MultipleCredentialsError`. Pass auth through one channel.
+
+For a non-Bearer scheme, pass `extra_headers` alone (omit `api_key`); supplying
+both `api_key` and an auth header at construction is also refused.
+
+### Proxy
+
+The proxy gets its one credential from one of two sources — never both:
+
+1. **Inbound passthrough.** The caller's request already carries a credential;
+   forge forwards it, relocating the header to the backend's protocol when they
+   differ (see the table below). This is the SSO/forwarded-token case.
+2. **Static `--backend-api-key`** (or the `FORGE_BACKEND_API_KEY` env var) for
+   backends where the caller sends nothing — LM Studio, hosted providers,
+   service accounts. Baked into the backend client at startup.
+
+If an inbound auth header **and** `--backend-api-key` are both present, or a
+single request carries **two** auth headers, the proxy refuses it with **HTTP
+400** (a client error — the message names the conflicting slots, never a secret).
+This holds for **streaming** requests too: the credential is resolved (and a
+gated backend's context discovered) *before* the `200 OK` / SSE headers are
+flushed, so a *conflict* (two credentials) or a discovery failure returns the
+real status (400/401) rather than a stream that opens `200 OK` and then carries
+an error event.
+
+One streaming case is unavoidable today: an error that surfaces only when the
+backend is actually called — the backend **rejecting the credential** (401), or
+refusing a request with no credential — happens *after* the SSE headers are
+flushed, because the proxy buffers the response rather than streaming it
+incrementally. Such failures arrive as an error *event* inside the already-open
+`200` stream, not as a `401` status. (Non-streaming requests always get the real
+status; and the direct `WorkflowRunner` library path streams incrementally, so
+this is specific to the buffered proxy.)
+
+**Cross-protocol relocation.** forge moves the one credential into the target
+backend's canonical auth slot (it never reads the secret value):
+
+| Target backend | forge writes |
+|---|---|
+| OpenAI-wire (llama.cpp, vLLM, Ollama, hosted) | `Authorization: Bearer <token>` |
+| Anthropic-wire | `x-api-key: <token>` (forge pins its own `anthropic-version`) |
+
+Same protocol both ends → forwarded verbatim. Cross-protocol → the token is
+normalized (a leading `Bearer ` is stripped/added as needed) and written to the
+target slot. The common case — Claude Code (Anthropic-wire) in front of an
+OpenAI backend — relocates `x-api-key` → `Authorization: Bearer` unambiguously.
+
+> **One documented limitation:** an Anthropic *OAuth* token (which must ride
+> `Authorization: Bearer`, not `x-api-key`) pushed through forge's *OpenAI*
+> endpoint to an Anthropic backend is relocated to `x-api-key` and rejected by
+> Anthropic. Coherent setups never hit this — OAuth callers use the Anthropic
+> endpoint (`/v1/messages`), which is same-protocol passthrough.
+
+forge forwards **only** the one credential header; it does not forward the rest
+of the inbound header set (so client-set `anthropic-beta`, `OpenAI-Organization`,
+etc. do not reach the backend — a future `--backend-header` may add this).
+
+### Notes
+
+- **Ambient `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`** are read by the
+  Anthropic SDK only for *direct* `AnthropicClient()` use (the eval path) — your
+  deliberate single credential. The **proxy** neutralizes these env vars at
+  construction so an ambient value can't become a hidden second credential.
+- **Keyless passthrough to an auth-required backend:** the proxy discovers the
+  backend's context length at startup, before any inbound credential exists. If
+  that endpoint requires auth, pass `--budget-tokens` so startup doesn't need to
+  call it.
+- **DEBUG logging** (proxy `-v`) emits the forwarded credential's header *name*
+  with the value redacted (`x-api-key: ***`). A raw secret is never logged.
+
+---
+
 ## llama-server (recommended)
 
 Upstream: [llama.cpp releases](https://github.com/ggml-org/llama.cpp/releases)
 
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forge-guardrails"
-version = "0.7.6"
+version = "0.8.0"
 description = "A reliability layer for self-hosted LLM tool-calling. Guardrails, context management, and backend adapters for multi-step agentic workflows."
 requires-python = ">=3.12"
 license = "MIT"
 
@@ -395,7 +395,7 @@ async def phase_external(
         proxy = ProxyServer(
             backend_url=f"http://127.0.0.1:{EXTERNAL_BACKEND_PORT}",
             port=EXTERNAL_PROXY_PORT,
-            mode=mode,
+            backend_capability=mode,
             backend_protocol="openai",
         )
         proxy.start()
@@ -430,7 +430,7 @@ async def phase_managed(
         backend_port=MANAGED_BACKEND_PORT,
         port=MANAGED_PROXY_PORT,
         budget_mode=BudgetMode.BACKEND,
-        mode=mode,
+        backend_capability=mode,
         extra_flags=extra_flags,
     )
     proxy.start()
@@ -462,7 +462,7 @@ async def phase_external_vllm(vllm_url: str) -> list[tuple[str, str, str]]:
         backend_url=vllm_url,
         backend="vllm",
         port=VLLM_PROXY_PORT,
-        mode="native",
+        backend_capability="native",
         backend_protocol="openai",
     )
     proxy.start()
 
@@ -59,15 +59,28 @@ async def _read_request(
 
 
 def _write_json_response(body: str) -> bytes:
+    return _write_response(200, "OK", body)
+
+
+def _write_response(status: int, reason: str, body: str) -> bytes:
+    # Connection: close — these mocks serve one request per connection and close
+    # it, so tell the client not to pool it. The deferred-discovery flow makes
+    # two backend hits (/props then /v1/chat/completions); without this, httpx
+    # may reuse the just-closed keep-alive connection and the second hit flakes.
     return (
-        "HTTP/1.1 200 OK\r\n"
+        f"HTTP/1.1 {status} {reason}\r\n"
         "Content-Type: application/json\r\n"
         f"Content-Length: {len(body)}\r\n"
+        "Connection: close\r\n"
         "\r\n"
         f"{body}"
     ).encode()
 
 
+# Credential a gated backend (test 4) requires — mirrors `llama-server --api-key`.
+GATED_KEY = "TESTKEY"
+
+
 # ── Mock backends ─────────────────────────────────────────────────────
 
 async def openai_mock_backend(
@@ -108,6 +121,48 @@ async def openai_mock_backend(
     await writer.wait_closed()
 
 
+async def gated_openai_mock_backend(
+    reader: asyncio.StreamReader, writer: asyncio.StreamWriter,
+) -> None:
+    """OpenAI-shape mock that GATES on ``Authorization: Bearer TESTKEY``.
+
+    Mirrors ``llama-server --api-key``: a missing/wrong credential gets 401 on
+    *every* path — crucially including the ``/props`` context-length probe. This
+    lets the deferred-discovery path (finding #2) be exercised without a real
+    gated backend: the proxy can't probe at startup (it has no credential then),
+    so it must defer to the first request and use that request's inbound key.
+    """
+    path, headers, _body = await _read_request(reader)
+
+    if headers.get("authorization") != f"Bearer {GATED_KEY}":
+        body = json.dumps({"error": {"message": "missing/invalid api key", "type": "auth"}})
+        writer.write(_write_response(401, "Unauthorized", body))
+        await writer.drain()
+        writer.close()
+        await writer.wait_closed()
+        return
+
+    if "/props" in path:
+        body = json.dumps({"default_generation_settings": {"n_ctx": 8192}})
+    else:
+        body = json.dumps({
+            "id": "chatcmpl-gated",
+            "object": "chat.completion",
+            "model": "mock",
+            "choices": [{
+                "index": 0,
+                "message": {"role": "assistant", "content": "OK"},
+                "finish_reason": "stop",
+            }],
+            "usage": {"prompt_tokens": 5, "completion_tokens": 1, "total_tokens": 6},
+        })
+
+    writer.write(_write_json_response(body))
+    await writer.drain()
+    writer.close()
+    await writer.wait_closed()
+
+
 # Captured request bodies from the Anthropic mock, used by path-1 assertions.
 _anthropic_mock_seen: list[dict[str, Any]] = []
 
@@ -255,6 +310,61 @@ async def test_openai() -> None:
         await mock.wait_closed()
 
 
+# ── Test 1b: Gated passthrough → deferred discovery (finding #2) ─────
+
+async def test_gated_passthrough_deferred_discovery() -> None:
+    print("\n=== test_gated_passthrough_deferred_discovery (deferred probe vs gated backend) ===")
+    mock = await asyncio.start_server(gated_openai_mock_backend, "127.0.0.1", 18090)
+    # Pure passthrough: no --backend-api-key, no --budget-tokens → discovery is
+    # deferred to the first request. Against a GATED backend this used to crash
+    # at startup (the unauthenticated /props probe); now the proxy must just start.
+    proxy = _start_proxy(backend_url="http://127.0.0.1:18090", port=18091)
+    print("[setup] gated mock=:18090 proxy=:18091 (no backend_api_key, no budget_tokens)")
+    print("[ok] proxy started against a gated backend (deferred — no startup probe/crash)")
+
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            # Negative: no inbound credential → the deferred /props probe is
+            # unauthenticated → backend 401 → clean 401, discovery NOT latched.
+            r0 = await client.post(
+                "http://127.0.0.1:18091/v1/chat/completions",
+                json={
+                    "model": "test",
+                    "messages": [{"role": "user", "content": "hi"}],
+                    "stream": False,
+                },
+            )
+            assert r0.status_code == 401, (
+                f"no-cred: expected 401, got {r0.status_code} {r0.text[:200]}"
+            )
+            print("[ok] no-credential first request → 401 (probe rejected, not latched)")
+
+            # Positive: same request WITH the credential → the deferred probe
+            # authenticates with the inbound key, context is discovered, request
+            # completes. Also proves no-latch-on-failure: the prior 401 didn't
+            # poison discovery — this retry succeeds.
+            r1 = await client.post(
+                "http://127.0.0.1:18091/v1/chat/completions",
+                headers={"Authorization": f"Bearer {GATED_KEY}"},
+                json={
+                    "model": "test",
+                    "messages": [{"role": "user", "content": "hi"}],
+                    "stream": False,
+                },
+            )
+            assert r1.status_code == 200, (
+                f"with-cred: expected 200, got {r1.status_code} {r1.text[:200]}"
+            )
+            assert r1.json()["choices"][0]["message"]["content"] == "OK"
+            print("[ok] credentialed request → deferred discovery succeeded, 200 "
+                  "(retry after the 401 works → no-latch-on-failure)")
+
+    finally:
+        proxy.stop()
+        mock.close()
+        await mock.wait_closed()
+
+
 # ── Test 2: Path 2 (Anthropic inbound → OpenAI backend) ──────────────
 
 async def test_path2_anthropic_to_openai() -> None:
@@ -388,6 +498,12 @@ async def test_path1_anthropic_passthrough() -> None:
             cache_marker = {"type": "ephemeral"}
             resp = await client.post(
                 "http://127.0.0.1:18085/v1/messages",
+                # v0.8.0 one-credential rule: this proxy is pure passthrough (no
+                # --backend-api-key), so the request must carry a credential —
+                # forge relocates this single inbound x-api-key to the Anthropic
+                # backend's native slot. Without it forge fails loud (401), which
+                # is correct: you can't reach an Anthropic backend with no key.
+                headers={"x-api-key": "smoke-anthropic-key"},
                 json={
                     "model": "claude-mock",
                     "max_tokens": 1024,
@@ -459,6 +575,7 @@ async def test_path1_anthropic_passthrough() -> None:
 
 async def main() -> None:
     await test_openai()
+    await test_gated_passthrough_deferred_discovery()
     await test_path2_anthropic_to_openai()
     await test_path1_anthropic_passthrough()
     print("\n[PASS] All proxy smoke tests passed.")