diff --git a/crates/harness-gateway-client/src/broker-tests.rs b/crates/harness-gateway-client/src/broker-tests.rs index 0d1ca5336..43a30cf46 100644 --- a/crates/harness-gateway-client/src/broker-tests.rs +++ b/crates/harness-gateway-client/src/broker-tests.rs @@ -220,6 +220,30 @@ fn debug_never_leaks_the_bearer_key() { ); } +#[test] +fn debug_redacts_a_plan_proof_the_same_way_it_redacts_the_key() { + let proof = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"; + let broker = GatewayBroker::new( + GatewayEndpoint::new("http://127.0.0.1:8081/v1").expect("valid test endpoint"), + SecretString::new("super-secret-token").expect("non-empty test key"), + ) + .with_plan_proof(SecretString::new(proof).expect("non-empty test proof")); + let rendered = format!("{broker:?}"); + assert!( + !rendered.contains(proof), + "the plan proof leaked: {rendered}" + ); + assert!( + !rendered.contains("super-secret-token"), + "the bearer key leaked: {rendered}" + ); + assert!(rendered.contains(""), "got: {rendered}"); + assert!( + !rendered.contains("Some") && !rendered.contains("None"), + "presence of the proof must not leak, got: {rendered}" + ); +} + #[tokio::test] async fn models_lists_the_catalog_the_gateway_serves_under_the_brokers_key() { use axum::Router; @@ -257,3 +281,87 @@ async fn models_lists_the_catalog_the_gateway_serves_under_the_brokers_key() { assert_eq!(info.context().get(), 131_072); assert_eq!(info.thinking(), ThinkingMode::Switchable); } + +#[tokio::test] +async fn models_sends_the_plan_proof_only_when_the_host_passed_one() { + use std::sync::{Arc, Mutex}; + + use axum::Router; + use axum::http::{HeaderMap, StatusCode}; + use axum::routing::get; + + use crate::{PLAN_PROOF_HEADER, fetch_model_catalog, fetch_model_catalog_with_plan_proof}; + + const PROOF: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"; + + let seen: Arc>>> = Arc::new(Mutex::new(Vec::new())); + let slot = Arc::clone(&seen); + let app = Router::new().route( + "/v1/models", + get(move |headers: HeaderMap| { + let slot = Arc::clone(&slot); + async move { + let proofs = headers + .get_all(PLAN_PROOF_HEADER) + .iter() + .filter_map(|value| value.to_str().ok().map(str::to_owned)) + .collect(); + slot.lock().expect("capture lock").push(proofs); + if headers + .get(axum::http::header::AUTHORIZATION) + .and_then(|value| value.to_str().ok()) + != Some("Bearer tok") + { + return Err(StatusCode::UNAUTHORIZED); + } + Ok(axum::Json(serde_json::json!({ + "data": [{ + "id": "mock-model", + "description": "the mock model", + "context": 131_072, + "thinking": "switchable", + }] + }))) + } + }), + ); + let base = serve(app).await; + let endpoint = GatewayEndpoint::new(&base).expect("valid test endpoint"); + let key = SecretString::new(KEY).expect("non-empty test key"); + let without = GatewayBroker::new(endpoint.clone(), key.clone()); + without + .models() + .await + .expect("the catalog loads without a plan proof"); + let with = GatewayBroker::new(endpoint.clone(), key.clone()) + .with_plan_proof(SecretString::new(PROOF).expect("non-empty test proof")); + let catalog = with + .models() + .await + .expect("the catalog loads with a plan proof"); + assert!( + !format!("{catalog:?}").contains(PROOF), + "the catalog value must not carry the proof" + ); + fetch_model_catalog(&base, key.expose()) + .await + .expect("the free function loads the catalog"); + fetch_model_catalog_with_plan_proof( + &base, + key.expose(), + &SecretString::new(PROOF).expect("non-empty"), + ) + .await + .expect("the free function sends the proof"); + let captured = seen.lock().expect("capture lock").clone(); + assert_eq!( + captured, + [ + Vec::::new(), + vec![PROOF.to_owned()], + Vec::::new(), + vec![PROOF.to_owned()], + ], + "absent stays absent, and a passed proof is exactly one header" + ); +} diff --git a/crates/harness-gateway-client/src/broker.rs b/crates/harness-gateway-client/src/broker.rs index 2df08de80..5ca91db5d 100644 --- a/crates/harness-gateway-client/src/broker.rs +++ b/crates/harness-gateway-client/src/broker.rs @@ -19,7 +19,7 @@ use runvil::model::{ }; use runvil::{BoxFuture, Error}; -use crate::catalog::fetch_model_catalog; +use crate::catalog::{fetch_model_catalog, fetch_model_catalog_with_plan_proof}; use crate::config::{GatewayEndpoint, SecretString}; use crate::transport::GatewayChat; use crate::wire::delta::StreamDelta; @@ -31,7 +31,10 @@ use crate::wire::delta::StreamDelta; /// The broker performs each `Chat` effect from the Engine as one model /// round on a [`GatewayChat`]. It lists the Gateway's models through /// [`fetch_model_catalog`]. Both kinds of request go to the same API root -/// and authenticate with the same bearer key. +/// and authenticate with the same bearer key. A Host may also pass a plan +/// proof. That value is not a bearer: it is sent as +/// `X-Runvil-Plan-Proof` on those same requests, and only when the Host +/// passed one. /// /// Every round uses the client's own request limits: a 120 second wait for /// each receive and a 16 MiB cap on each reply. @@ -45,6 +48,9 @@ pub struct GatewayBroker { client: GatewayChat, endpoint: GatewayEndpoint, key: SecretString, + /// The plan proof a Host passed, or `None` when the model list sends + /// no plan-proof header. Model rounds read the copy on `client`. + plan_proof: Option, } impl fmt::Debug for GatewayBroker { @@ -55,6 +61,7 @@ impl fmt::Debug for GatewayBroker { .field("client", &self.client) .field("api_root", &self.endpoint.url()) .field("key", &"") + .field("plan_proof", &"") .finish() } } @@ -72,9 +79,23 @@ impl GatewayBroker { client, endpoint, key, + plan_proof: None, } } + /// Sends `plan_proof` as `X-Runvil-Plan-Proof` on this broker's model + /// rounds and on its model list. + /// + /// A Host passes the proof explicitly. The client does not read a file + /// or an environment variable to obtain it, and a broker without this + /// call sends no such header. + #[must_use] + pub fn with_plan_proof(mut self, plan_proof: SecretString) -> Self { + self.client = self.client.with_plan_proof(plan_proof.clone()); + self.plan_proof = Some(plan_proof); + self + } + /// Runs one model round and passes each piece of the reply to /// `on_piece` as it arrives. /// @@ -120,7 +141,15 @@ impl InferenceBroker for GatewayBroker { fn models(&self) -> BoxFuture<'static, Result> { let api_root = self.endpoint.url().to_owned(); let key = self.key.clone(); - Box::pin(async move { fetch_model_catalog(&api_root, key.expose()).await }) + let plan_proof = self.plan_proof.clone(); + Box::pin(async move { + match &plan_proof { + Some(proof) => { + fetch_model_catalog_with_plan_proof(&api_root, key.expose(), proof).await + } + None => fetch_model_catalog(&api_root, key.expose()).await, + } + }) } fn chat( diff --git a/crates/harness-gateway-client/src/catalog.rs b/crates/harness-gateway-client/src/catalog.rs index 562412cef..d3a924375 100644 --- a/crates/harness-gateway-client/src/catalog.rs +++ b/crates/harness-gateway-client/src/catalog.rs @@ -6,7 +6,9 @@ use runvil::Error; use runvil::model::{ModelCatalog, ModelId, ModelInfo, ThinkingMode}; use serde::Deserialize; +use crate::config::{GatewayEndpoint, SecretString}; use crate::failure::{make_malformed_error, make_transport_failure_error, with_detail}; +use crate::transport::PLAN_PROOF_HEADER; use crate::wire::classify::make_classify_http_failure_error; use crate::wire::stream::escape_controls; @@ -119,15 +121,23 @@ async fn read_error_body_bounded( Ok(escaped) } -/// Returns the process-wide catalog HTTP client, building it once on first use. +/// Returns the process-wide catalog HTTP client for `loopback` or for any +/// other address, building each once on first use. /// -/// A single reusable client (MODEL-018) lets catalog fetches share one -/// connection pool and transport configuration rather than each constructing a -/// throwaway client with its own pool. The returned handle is a cheap clone of -/// the shared client (its state is reference-counted internally). -fn catalog_client() -> reqwest::Client { - static CATALOG_CLIENT: std::sync::OnceLock = std::sync::OnceLock::new(); - CATALOG_CLIENT.get_or_init(reqwest::Client::new).clone() +/// A loopback catalog fetch uses the same direct, no-redirect client as a +/// loopback [`crate::GatewayChat`]. The two pools stay separate so a remote +/// catalog can still follow a redirect and use a proxy. Neither client +/// carries a default header: the proof is set on the single request. +fn catalog_client(loopback: bool) -> reqwest::Client { + static LOCAL: std::sync::OnceLock = std::sync::OnceLock::new(); + static REMOTE: std::sync::OnceLock = std::sync::OnceLock::new(); + if loopback { + LOCAL + .get_or_init(|| crate::transport::http_client(true)) + .clone() + } else { + REMOTE.get_or_init(reqwest::Client::new).clone() + } } /// Sends a bearer-authed GET through the shared client (MODEL-018) and @@ -138,13 +148,17 @@ fn catalog_client() -> reqwest::Client { /// `Transport` (or `Timeout`) when that error body cannot be read, appending /// the [`reqwest::Error`] to the message under the same timeout marking as a /// send failure. -async fn get_authed(url: String, token: &str) -> std::result::Result { - let response = catalog_client() - .get(url) - .bearer_auth(token) - .send() - .await - .map_err(make_transport_failure_error)?; +async fn get_authed( + url: String, + loopback: bool, + token: &str, + plan_proof: Option<&str>, +) -> std::result::Result { + let mut request = catalog_client(loopback).get(url).bearer_auth(token); + if let Some(proof) = plan_proof { + request = request.header(PLAN_PROOF_HEADER, proof); + } + let response = request.send().await.map_err(make_transport_failure_error)?; let status = response.status(); if status.is_success() { return Ok(response); @@ -160,11 +174,13 @@ async fn get_authed(url: String, token: &str) -> std::result::Result std::result::Result { - let base = base_url.trim_end_matches('/'); - let response = get_authed(format!("{base}/models"), token).await?; + fetch_catalog(base_url, token, None).await +} + +/// Fetches a [`ModelCatalog`] the way [`fetch_model_catalog`] does, and +/// sends `plan_proof` as [`PLAN_PROOF_HEADER`] on that one request. +/// +/// The proof is not a bearer. The request still sends `token` as its +/// bearer token. This client does not read the proof from a file or an +/// environment variable. +/// +/// # Errors +/// Returns the same [`Error`]s [`fetch_model_catalog`] returns. +pub async fn fetch_model_catalog_with_plan_proof( + base_url: &str, + token: &str, + plan_proof: &SecretString, +) -> std::result::Result { + fetch_catalog(base_url, token, Some(plan_proof.expose())).await +} + +/// The shared body of the two catalog fetches. `plan_proof` of `None` +/// leaves the request without a plan-proof header. +async fn fetch_catalog( + base_url: &str, + token: &str, + plan_proof: Option<&str>, +) -> std::result::Result { + // The validation a chat endpoint gets, before any request. An API root + // that names the local machine but is not a bare root (a query, a + // fragment, embedded credentials) is refused here, so it can never be + // sent with the client that follows redirects and uses the process proxy. + let endpoint = GatewayEndpoint::new(base_url)?; + let response = get_authed( + format!("{}/models", endpoint.url()), + endpoint.is_loopback(), + token, + plan_proof, + ) + .await?; // Bound the success body BEFORE decoding so an oversized (or unbounded) // model list cannot exhaust memory, matching the bound the error path applies. let body = read_catalog_body_capped(response, MAX_CATALOG_BODY).await?; diff --git a/crates/harness-gateway-client/src/config.rs b/crates/harness-gateway-client/src/config.rs index 8d54a4e9c..983718417 100644 --- a/crates/harness-gateway-client/src/config.rs +++ b/crates/harness-gateway-client/src/config.rs @@ -40,13 +40,14 @@ fn make_setup_error(reason: &'static str, message: String) -> Error { error } -/// A bearer credential whose contents never appear in `Debug` or `Display` -/// output or in logs. +/// A secret whose contents never appear in `Debug` or `Display` output or +/// in logs. /// -/// Wrap a secret, such as the gateway bearer key, in a `SecretString` as soon -/// as you read it, so an accidental `{:?}` or log line cannot leak it. The -/// client reads the value only to set the `Authorization` header of its -/// requests. +/// Wrap a secret, such as the gateway bearer key or a Host-supplied plan +/// proof, in a `SecretString` as soon as you read it, so an accidental +/// `{:?}` or log line cannot leak it. The client reads a bearer only to set +/// the `Authorization` header, and a plan proof only to set +/// `X-Runvil-Plan-Proof`. A plan proof is not a bearer. #[derive(Clone)] #[non_exhaustive] pub struct SecretString(String); @@ -57,7 +58,7 @@ impl SecretString { /// # Errors /// Returns an [`InvalidValue`](ErrorCode::InvalidValue) error with the /// reason `empty_secret` when `secret` is empty, so a client can never be - /// built to authenticate with a blank bearer credential. + /// built with a blank secret. pub fn new(secret: impl Into) -> std::result::Result { let secret = secret.into(); if secret.is_empty() { diff --git a/crates/harness-gateway-client/src/lib.rs b/crates/harness-gateway-client/src/lib.rs index a72869a76..9f68500ae 100644 --- a/crates/harness-gateway-client/src/lib.rs +++ b/crates/harness-gateway-client/src/lib.rs @@ -19,7 +19,11 @@ //! completion the round produced. [`fetch_model_catalog`] fetches the //! Gateway's model list as a typed `ModelCatalog`. The client holds no //! credential except the Gateway's shared key. The model vendor's -//! credential stays in the Gateway. +//! credential stays in the Gateway. A Host may pass a plan proof, which +//! is not a bearer and which this crate never reads from a file or an +//! environment variable. When one was passed it is sent as +//! [`PLAN_PROOF_HEADER`] on a model round and on the model list, and +//! nowhere else. //! //! [`GatewaySearch`] is the [`plugin_web::SearchProvider`] that a Host //! using the Gateway supplies for web search. It sends each search through @@ -55,7 +59,7 @@ //! validating constructors, so the Engine's model-independent reply //! checks run on every decoded turn. //! - A Gateway bearer key is never written to logs, `Debug`, `Display`, or -//! error text. +//! error text. A Host-supplied plan proof is redacted the same way. //! - A backend error body is bounded and control-escaped before it is //! kept. A chat round keeps it only in the error's message, never in its //! prose, and a search keeps it in its error's message and prose. @@ -75,10 +79,12 @@ mod wire; pub use broker::GatewayBroker; pub use catalog::fetch_model_catalog; +pub use catalog::fetch_model_catalog_with_plan_proof; pub use config::GatewayEndpoint; pub use config::SecretString; pub use search::GatewaySearch; pub use transport::GatewayChat; +pub use transport::PLAN_PROOF_HEADER; pub use wire::classify::make_classify_http_failure_error; pub use wire::classify::make_classify_stream_error; pub use wire::delta::StreamDelta; diff --git a/crates/harness-gateway-client/src/search.rs b/crates/harness-gateway-client/src/search.rs index 5646682d3..a8c4e459c 100644 --- a/crates/harness-gateway-client/src/search.rs +++ b/crates/harness-gateway-client/src/search.rs @@ -139,8 +139,9 @@ impl GatewaySearch { key: SecretString, timeout: Duration, ) -> GatewaySearch { + let http = crate::transport::http_client(endpoint.is_loopback()); GatewaySearch { - http: reqwest::Client::new(), + http, base_url: endpoint.url, key, timeout, diff --git a/crates/harness-gateway-client/src/transport.rs b/crates/harness-gateway-client/src/transport.rs index 35c968f50..656c2d6fd 100644 --- a/crates/harness-gateway-client/src/transport.rs +++ b/crates/harness-gateway-client/src/transport.rs @@ -24,12 +24,20 @@ use crate::wire::read::{ChunkSource, read_body_capped, read_completion_stream}; use crate::wire::request::build_request_body; use crate::wire::stream::escape_controls; +/// Header a Host-supplied plan proof is sent in. +/// +/// A client that holds no proof omits the header, so the request bytes are +/// the ones this client sent before a proof existed. +pub const PLAN_PROOF_HEADER: &str = "X-Runvil-Plan-Proof"; + /// A client that sends chat completion requests to one gateway URL. /// /// The client usually presents the gateway's shared bearer key on every /// request. The key is optional: by default, a gateway on the same machine /// admits keyless loopback callers. A keyless client /// ([`GatewayChat::keyless`]) omits the `Authorization` header entirely. +/// A Host may also pass a plan proof. That value is not a bearer: it is +/// sent only as [`PLAN_PROOF_HEADER`], and only when the Host passed one. #[derive(Clone)] #[non_exhaustive] pub struct GatewayChat { @@ -37,6 +45,8 @@ pub struct GatewayChat { base_url: String, /// The bearer presented on every request, or `None` to present nothing. key: Option, + /// The plan proof a Host passed, or `None` to send no plan-proof header. + plan_proof: Option, /// Longest wait for the response headers, and then for each next body /// chunk; a stream that keeps arriving is never cut off. receive_timeout: Duration, @@ -49,6 +59,28 @@ const DEFAULT_RECEIVE_TIMEOUT: Duration = Duration::from_secs(120); /// Default response-body ceiling. const DEFAULT_MAX_RESPONSE_BYTES: u64 = 16 * 1024 * 1024; +/// The HTTP client for one Gateway. +/// +/// A loopback Gateway is reached directly and a redirect is returned as +/// its own status. Any other address keeps reqwest's defaults, including a +/// proxy when the process has one. +pub(crate) fn http_client(loopback: bool) -> reqwest::Client { + if !loopback { + return reqwest::Client::new(); + } + // A failed build must not fall back to a client that follows + // redirects or uses a proxy. `Client::new` panics on the same TLS + // failure this build can hit. + match reqwest::Client::builder() + .redirect(reqwest::redirect::Policy::none()) + .no_proxy() + .build() + { + Ok(client) => client, + Err(error) => panic!("the loopback gateway client builds: {error}"), + } +} + #[derive(Clone)] enum GatewayTransport { Http(reqwest::Client), @@ -81,6 +113,7 @@ impl fmt::Debug for GatewayChat { f.debug_struct("GatewayChat") .field("base_url", &self.base_url) .field("key", &"") + .field("plan_proof", &"") .finish_non_exhaustive() } } @@ -91,13 +124,16 @@ impl GatewayChat { /// /// The endpoint is a validated [`GatewayEndpoint`], and the key is a /// [`SecretString`], which keeps it redacted. [`GatewayChat::from_env`] - /// builds its client this way when a key is set. + /// builds its client this way when a key is set. A loopback endpoint + /// is contacted directly and a redirect is not followed. #[must_use] pub fn new(endpoint: GatewayEndpoint, key: SecretString) -> GatewayChat { + let transport = GatewayTransport::Http(http_client(endpoint.is_loopback())); GatewayChat { - transport: GatewayTransport::Http(reqwest::Client::new()), + transport, base_url: endpoint.url, key: Some(key), + plan_proof: None, receive_timeout: DEFAULT_RECEIVE_TIMEOUT, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES, } @@ -117,10 +153,12 @@ impl GatewayChat { /// [`GatewayChat::from_env`] decides by [`GatewayEndpoint::is_loopback`]. #[must_use] pub fn keyless(endpoint: GatewayEndpoint) -> GatewayChat { + let transport = GatewayTransport::Http(http_client(endpoint.is_loopback())); GatewayChat { - transport: GatewayTransport::Http(reqwest::Client::new()), + transport, base_url: endpoint.url, key: None, + plan_proof: None, receive_timeout: DEFAULT_RECEIVE_TIMEOUT, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES, } @@ -138,6 +176,7 @@ impl GatewayChat { transport: GatewayTransport::Disabled, base_url: String::new(), key: None, + plan_proof: None, receive_timeout: DEFAULT_RECEIVE_TIMEOUT, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES, } @@ -171,6 +210,18 @@ impl GatewayChat { self } + /// Sends `plan_proof` as [`PLAN_PROOF_HEADER`] on this client's model + /// rounds. + /// + /// A Host passes the proof explicitly. The client does not read a file + /// or an environment variable to obtain it, and a client without this + /// call sends no such header. + #[must_use] + pub fn with_plan_proof(mut self, plan_proof: SecretString) -> GatewayChat { + self.plan_proof = Some(plan_proof); + self + } + /// Builds a client from environment variables. /// /// - `RUNVIL_GATEWAY_URL` holds the gateway URL. It is required. @@ -274,6 +325,9 @@ impl GatewayChat { if let Some(key) = &self.key { request = request.bearer_auth(key.expose()); } + if let Some(proof) = &self.plan_proof { + request = request.header(PLAN_PROOF_HEADER, proof.expose()); + } let response = tokio::time::timeout(self.receive_timeout, request.send()) .await .map_err(make_elapsed_error)? diff --git a/crates/harness-gateway-client/src/transport/tests.rs b/crates/harness-gateway-client/src/transport/tests.rs index d13abc9ae..7dbed0eac 100644 --- a/crates/harness-gateway-client/src/transport/tests.rs +++ b/crates/harness-gateway-client/src/transport/tests.rs @@ -8,6 +8,7 @@ use super::*; mod env; mod limits; +mod plan_proof; mod streaming; /// Serves `app` on a loopback port and returns its `/v1` root. diff --git a/crates/harness-gateway-client/src/transport/tests/env.rs b/crates/harness-gateway-client/src/transport/tests/env.rs index be2144db0..f3dc01885 100644 --- a/crates/harness-gateway-client/src/transport/tests/env.rs +++ b/crates/harness-gateway-client/src/transport/tests/env.rs @@ -113,12 +113,19 @@ fn from_env_missing_gateway_key_is_fine_for_a_loopback_gateway() { ); } -/// Spawns a gateway that records the `Authorization` header of each -/// completion request (as `Some(value)` or `None`) and answers a minimal -/// stop-finished stream, returning its `/v1` base and the capture slot. +/// The headers one completion request presented. +#[derive(Clone, Debug)] +struct SeenHeaders { + authorization: Option, + plan_proof: Option, +} + +/// Spawns a gateway that records the `Authorization` and plan-proof headers +/// of each completion request and answers a minimal stop-finished stream, +/// returning its `/v1` base and the capture slot. async fn spawn_auth_capturing_gateway() -> ( String, - std::sync::Arc>>>, + std::sync::Arc>>, ) { use std::sync::{Arc, Mutex}; @@ -126,18 +133,25 @@ async fn spawn_auth_capturing_gateway() -> ( use axum::http::HeaderMap; use axum::routing::post; - let captured: Arc>>> = Arc::new(Mutex::new(None)); + let captured: Arc>> = Arc::new(Mutex::new(None)); let slot = Arc::clone(&captured); let app = Router::new().route( "/v1/chat/completions", post(move |headers: HeaderMap| { let slot = Arc::clone(&slot); async move { - let auth = headers + let authorization = headers .get(axum::http::header::AUTHORIZATION) .and_then(|value| value.to_str().ok()) .map(str::to_owned); - *slot.lock().expect("capture lock") = Some(auth); + let plan_proof = headers + .get(crate::PLAN_PROOF_HEADER) + .and_then(|value| value.to_str().ok()) + .map(str::to_owned); + *slot.lock().expect("capture lock") = Some(SeenHeaders { + authorization, + plan_proof, + }); ( [(axum::http::header::CONTENT_TYPE, "text/event-stream")], ok_stream(), @@ -170,9 +184,13 @@ async fn keyless_client_sends_no_authorization_header() { .clone() .expect("the gateway saw the request"); assert_eq!( - seen, None, + seen.authorization, None, "a keyless client must send no Authorization header, got {seen:?}" ); + assert_eq!( + seen.plan_proof, None, + "a client with no plan proof sends no plan-proof header, got {seen:?}" + ); } #[tokio::test] @@ -188,7 +206,11 @@ async fn keyed_client_still_sends_the_bearer_header() { .expect("capture lock") .clone() .expect("the gateway saw the request"); - assert_eq!(seen.as_deref(), Some("Bearer tok")); + assert_eq!(seen.authorization.as_deref(), Some("Bearer tok")); + assert_eq!( + seen.plan_proof, None, + "a keyed client with no plan proof sends no plan-proof header, got {seen:?}" + ); } #[test] diff --git a/crates/harness-gateway-client/src/transport/tests/plan_proof.rs b/crates/harness-gateway-client/src/transport/tests/plan_proof.rs new file mode 100644 index 000000000..d93843420 --- /dev/null +++ b/crates/harness-gateway-client/src/transport/tests/plan_proof.rs @@ -0,0 +1,130 @@ +//! A Host-supplied plan proof is one header on a model round, redacted in +//! `Debug`, and absent unless the Host passed it. The client has no path +//! argument and reads no private file. + +use std::sync::{Arc, Mutex}; + +use axum::Router; +use axum::http::HeaderMap; +use axum::routing::post; +use runvil::model::Message; + +use super::{keyed_client, ok_stream, openai_options}; +use crate::config::{GatewayEndpoint, SecretString}; +use crate::{GatewayChat, PLAN_PROOF_HEADER}; + +const PROOF: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"; + +/// Records every plan-proof header value the mock saw, in arrival order, +/// beside the authorization header. +async fn spawn_capturing() -> (String, Arc, Vec)>>>) { + let captured = Arc::new(Mutex::new(Vec::new())); + let slot = Arc::clone(&captured); + let app = Router::new().route( + "/v1/chat/completions", + post(move |headers: HeaderMap| { + let slot = Arc::clone(&slot); + async move { + let authorization = headers + .get(axum::http::header::AUTHORIZATION) + .and_then(|value| value.to_str().ok()) + .map(str::to_owned); + let plan_proof = headers + .get_all(PLAN_PROOF_HEADER) + .iter() + .filter_map(|value| value.to_str().ok().map(str::to_owned)) + .collect(); + slot.lock() + .expect("capture lock") + .push((authorization, plan_proof)); + ( + [(axum::http::header::CONTENT_TYPE, "text/event-stream")], + ok_stream(), + ) + } + }), + ); + let listener = tokio::net::TcpListener::bind("127.0.0.1:0") + .await + .expect("a loopback listener binds"); + let addr = listener + .local_addr() + .expect("a bound listener has a local address"); + tokio::spawn(async move { + axum::serve(listener, app) + .await + .expect("the mock gateway serves cleanly"); + }); + (format!("http://{addr}/v1"), captured) +} + +fn proof() -> SecretString { + SecretString::new(PROOF).expect("the test proof is non-empty") +} + +async fn complete(client: &GatewayChat) { + client + .complete(&[Message::user("hi")], None, &openai_options(), |_| {}) + .await + .expect("the completion succeeds"); +} + +#[tokio::test] +async fn a_passed_proof_is_one_header_on_the_round_and_the_bearer_stays() { + let (base, captured) = spawn_capturing().await; + let client = keyed_client(&base).with_plan_proof(proof()); + complete(&client).await; + let seen = captured.lock().expect("capture lock").clone(); + assert_eq!(seen.len(), 1, "one round, one request"); + assert_eq!(seen[0].0.as_deref(), Some("Bearer tok")); + assert_eq!(seen[0].1, [PROOF], "exactly one plan-proof header"); +} + +#[tokio::test] +async fn a_keyless_client_with_a_proof_omits_authorization_and_sends_the_header() { + let (base, captured) = spawn_capturing().await; + let client = GatewayChat::keyless(GatewayEndpoint::new(&base).expect("valid endpoint")) + .with_plan_proof(proof()); + complete(&client).await; + let seen = captured.lock().expect("capture lock").clone(); + assert_eq!(seen[0].0, None, "keyless still omits Authorization"); + assert_eq!(seen[0].1, [PROOF]); +} + +#[test] +fn debug_redacts_the_plan_proof_whether_or_not_one_was_passed() { + let endpoint = GatewayEndpoint::new("http://127.0.0.1:8081/v1").expect("valid"); + let plain = GatewayChat::keyless(endpoint.clone()); + let holding = GatewayChat::keyless(endpoint).with_plan_proof(proof()); + for rendered in [format!("{plain:?}"), format!("{holding:?}")] { + assert!( + !rendered.contains(PROOF), + "the plan proof must never appear in Debug output, got: {rendered}" + ); + assert!(rendered.contains(""), "got: {rendered}"); + assert!( + !rendered.contains("Some") && !rendered.contains("None"), + "presence of the proof must not leak, got: {rendered}" + ); + } +} + +#[tokio::test] +async fn from_env_sends_no_plan_proof_header() { + // Constructors take an endpoint and, when keyed, a bearer. None takes a + // path, and the environment constructor reads only the URL and the key. + let (base, captured) = spawn_capturing().await; + let client = super::super::from_env_with(super::lookup_from(&[ + ("RUNVIL_GATEWAY_URL", &base), + ("RUNVIL_GATEWAY_API_KEY", "tok"), + ])) + .expect("a URL and a key build"); + complete(&client).await; + let seen = captured.lock().expect("capture lock").clone(); + assert_eq!(seen[0].0.as_deref(), Some("Bearer tok")); + assert!( + seen[0].1.is_empty(), + "from_env must not invent a plan proof, got {:?}", + seen[0].1 + ); +} diff --git a/crates/harness-gateway-client/tests/loopback_direct.rs b/crates/harness-gateway-client/tests/loopback_direct.rs new file mode 100644 index 000000000..6f3dbcd9b --- /dev/null +++ b/crates/harness-gateway-client/tests/loopback_direct.rs @@ -0,0 +1,503 @@ +//! A loopback Gateway is contacted directly. A redirect is not followed, +//! and an `HTTP_PROXY` / `ALL_PROXY` listener receives nothing beyond the +//! canary that proves the variable is live. The proof is set so a followed +//! redirect or a proxy would have carried it. + +// clippy.toml's allow-expect-in-tests covers #[test] functions only, not +// integration-test helpers. Failing one of these by panicking names the +// invariant the helper exists to check. +#![expect( + clippy::expect_used, + reason = "test helpers fail by panicking with the invariant named" +)] +#![expect( + clippy::unwrap_used, + reason = "test helpers fail by panicking with the invariant named" +)] + +use std::io::{Read, Write}; +use std::process::{Command, ExitStatus}; +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::time::Duration; + +use axum::Router; +use axum::extract::Request; +use axum::http::{HeaderMap, StatusCode}; +use axum::middleware::{self, Next}; +use axum::response::Response; +use axum::routing::{get, post}; +use harness_gateway_client::{ + GatewayChat, GatewayEndpoint, GatewaySearch, SecretString, fetch_model_catalog_with_plan_proof, +}; +use plugin_web::{SearchProvider, SearchQuery}; +use runvil::ErrorCode; +use runvil::model::{CompletionOptions, Message}; + +const PROOF: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"; +const SEARCH_KEY: &str = "search-secret-key"; +const ROLE: &str = "LOOPBACK_DIRECT_ROLE"; +const SIGNAL: &str = "LOOPBACK_DIRECT_SIGNAL"; + +async fn bind() -> (String, tokio::net::TcpListener) { + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let addr = listener.local_addr().unwrap(); + (format!("http://{addr}"), listener) +} + +fn spawn(listener: tokio::net::TcpListener, app: Router) { + tokio::spawn(async move { + axum::serve(listener, app).await.unwrap(); + }); +} + +fn proof() -> SecretString { + SecretString::new(PROOF).expect("non-empty") +} + +fn chat(base: &str) -> GatewayChat { + GatewayChat::new( + GatewayEndpoint::new(base).expect("loopback endpoint"), + SecretString::new("tok").expect("non-empty"), + ) + .with_plan_proof(proof()) +} + +fn presented_proof(headers: &HeaderMap) -> bool { + headers + .get("x-runvil-plan-proof") + .and_then(|value| value.to_str().ok()) + == Some(PROOF) +} + +fn ok_sse() -> &'static str { + "data: {\"model\":\"m\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"ok\"},\"finish_reason\":null}]}\n\n\ + data: {\"model\":\"m\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}]}\n\n\ + data: [DONE]\n\n" +} + +const CATALOG_BODY: &str = r#"{"data":[{"id":"mock-model","description":"the mock model","context":131072,"thinking":"never"}]}"#; + +/// Accepts every connection, counts it, and closes. A client that honors +/// the proxy variable finishes instead of hanging on an unread request. +async fn proxy_listener() -> (String, Arc) { + let hits = Arc::new(AtomicUsize::new(0)); + let recorded = Arc::clone(&hits); + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let addr = listener.local_addr().unwrap(); + tokio::spawn(async move { + loop { + let Ok((socket, _)) = listener.accept().await else { + break; + }; + recorded.fetch_add(1, Ordering::SeqCst); + drop(socket); + } + }); + (format!("http://{addr}"), hits) +} + +/// Reads the child's canary mark and returns how many proxy connections +/// existed at that moment. The ack is what lets the child send the +/// loopback request only after this count is stored. +async fn canary_hits(listener: tokio::net::TcpListener, hits: Arc) -> usize { + let (socket, _) = listener.accept().await.expect("the child marks the canary"); + let _ = socket.readable().await; + let mut buf = [0_u8; 1]; + let _ = socket.try_read(&mut buf); + let seen = hits.load(Ordering::SeqCst); + let _ = socket.writable().await; + let _ = socket.try_write(b"k"); + seen +} + +fn run_child(role: &str, proxy: &str, signal: &str, test_name: &str) -> ExitStatus { + Command::new(std::env::current_exe().expect("the test executable")) + .args(["--exact", test_name, "--test-threads=1", "--nocapture"]) + .env(ROLE, role) + .env(SIGNAL, signal) + .env("HTTP_PROXY", proxy) + .env("ALL_PROXY", proxy) + .env_remove("NO_PROXY") + .env_remove("no_proxy") + .env_remove("REQUEST_METHOD") + .status() + .expect("the proxy child starts") +} + +async fn prove_canary(origin: &str) { + let client = reqwest::Client::builder() + .retry(reqwest::retry::never()) + .build() + .expect("canary client"); + let finished = tokio::time::timeout(Duration::from_secs(5), client.get(origin).send()).await; + assert!( + finished.is_ok(), + "the canary hung instead of finishing through HTTP_PROXY" + ); +} + +fn wait_until_counted() { + let addr = std::env::var(SIGNAL).expect("the parent publishes the canary signal"); + let mut stream = std::net::TcpStream::connect(addr).expect("canary signal"); + stream + .set_read_timeout(Some(Duration::from_secs(5))) + .expect("read timeout"); + stream + .set_write_timeout(Some(Duration::from_secs(5))) + .expect("write timeout"); + stream.write_all(b"c").expect("canary signal"); + let mut buf = [0_u8; 1]; + stream.read_exact(&mut buf).expect("the canary was counted"); +} + +async fn drive_proxy_check(role: &str, test_name: &str) { + let (proxy, hits) = proxy_listener().await; + let gate = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let gate_addr = gate.local_addr().unwrap().to_string(); + let recorded = Arc::clone(&hits); + let marked = tokio::spawn(canary_hits(gate, recorded)); + let proxy_for_child = proxy.clone(); + let role = role.to_owned(); + let test_name = test_name.to_owned(); + let status = tokio::task::spawn_blocking(move || { + run_child(&role, &proxy_for_child, &gate_addr, &test_name) + }) + .await + .expect("the child join"); + assert!(status.success(), "the proxy child exited {status}"); + let canary = marked.await.expect("the canary mark"); + assert!( + canary >= 1, + "HTTP_PROXY was not consulted, so the direct-client check proves nothing" + ); + assert_eq!( + hits.load(Ordering::SeqCst), + canary, + "the loopback client contacted the proxy" + ); +} + +#[tokio::test] +async fn a_loopback_chat_does_not_follow_a_redirect() { + let hits = Arc::new(AtomicUsize::new(0)); + let recorded = Arc::clone(&hits); + let (dest_base, dest_listener) = bind().await; + // Count before routing. A followed 302 arrives as GET and would miss a + // POST-only route, so the counter has to see every method. + let count_every_request = move |request: Request, next: Next| { + let recorded = Arc::clone(&recorded); + async move { + recorded.fetch_add(1, Ordering::SeqCst); + let response: Response = next.run(request).await; + response + } + }; + spawn( + dest_listener, + Router::new() + .route("/chat/completions", post(|| async { StatusCode::OK })) + .layer(middleware::from_fn(count_every_request)), + ); + let (origin, origin_listener) = bind().await; + let location = format!("{dest_base}/chat/completions"); + spawn( + origin_listener, + Router::new().route( + "/v1/chat/completions", + post(move |headers: HeaderMap| { + let location = location.clone(); + async move { + assert!( + presented_proof(&headers), + "the direct request arrived without the plan proof" + ); + // 307 keeps the method. A 302 that was followed would + // arrive at the target as GET and still be counted. + (StatusCode::TEMPORARY_REDIRECT, [("location", location)]) + } + }), + ), + ); + let error = chat(&format!("{origin}/v1")) + .complete( + &[Message::user("hi")], + None, + &CompletionOptions::new("m"), + |_| {}, + ) + .await + .expect_err("a redirect is not a completed round"); + assert!( + !error.to_string().contains(PROOF) && !error.message.contains(PROOF), + "the redirect error contains the plan proof" + ); + assert_eq!( + hits.load(Ordering::SeqCst), + 0, + "the redirect target received a request" + ); +} + +#[tokio::test] +async fn a_loopback_catalog_does_not_follow_a_redirect() { + let hits = Arc::new(AtomicUsize::new(0)); + let recorded = Arc::clone(&hits); + let (dest_base, dest_listener) = bind().await; + spawn( + dest_listener, + Router::new().route( + "/models", + get(move || { + let recorded = Arc::clone(&recorded); + async move { + recorded.fetch_add(1, Ordering::SeqCst); + StatusCode::OK + } + }), + ), + ); + let (origin, origin_listener) = bind().await; + let location = format!("{dest_base}/models"); + spawn( + origin_listener, + Router::new().route( + "/models", + get(move |headers: HeaderMap| { + let location = location.clone(); + async move { + assert!( + presented_proof(&headers), + "the direct request arrived without the plan proof" + ); + (StatusCode::FOUND, [("location", location)]) + } + }), + ), + ); + let error = fetch_model_catalog_with_plan_proof(&origin, "tok", &proof()) + .await + .expect_err("a redirect is not a catalog"); + assert!( + !error.to_string().contains(PROOF) && !error.message.contains(PROOF), + "the redirect error contains the plan proof" + ); + assert_eq!(hits.load(Ordering::SeqCst), 0); +} + +#[tokio::test] +async fn a_loopback_chat_does_not_use_an_http_proxy() { + if std::env::var(ROLE).ok().as_deref() == Some("chat") { + let (base, listener) = bind().await; + spawn( + listener, + Router::new().route( + "/v1/chat/completions", + post(move |headers: HeaderMap| async move { + assert!( + presented_proof(&headers), + "the direct request arrived without the plan proof" + ); + ( + [(axum::http::header::CONTENT_TYPE, "text/event-stream")], + ok_sse(), + ) + }), + ), + ); + prove_canary(&format!("{base}/v1/chat/completions")).await; + wait_until_counted(); + chat(&format!("{base}/v1")) + .complete( + &[Message::user("hi")], + None, + &CompletionOptions::new("m"), + |_| {}, + ) + .await + .expect("the loopback round completes directly"); + return; + } + drive_proxy_check("chat", "a_loopback_chat_does_not_use_an_http_proxy").await; +} + +#[tokio::test] +async fn a_loopback_catalog_does_not_use_an_http_proxy() { + if std::env::var(ROLE).ok().as_deref() == Some("catalog") { + let (base, listener) = bind().await; + spawn( + listener, + Router::new().route( + "/models", + get(move |headers: HeaderMap| async move { + assert!( + presented_proof(&headers), + "the direct request arrived without the plan proof" + ); + ( + [(axum::http::header::CONTENT_TYPE, "application/json")], + CATALOG_BODY, + ) + }), + ), + ); + prove_canary(&format!("{base}/models")).await; + wait_until_counted(); + fetch_model_catalog_with_plan_proof(&base, "tok", &proof()) + .await + .expect("the loopback catalog completes directly"); + return; + } + drive_proxy_check("catalog", "a_loopback_catalog_does_not_use_an_http_proxy").await; +} + +const SEARCH_BODY: &str = r#"{"query":"hi","results":[]}"#; + +/// An API root that names the local machine but is not a bare root is +/// refused before any request. It must never reach the client that follows +/// redirects and uses the process proxy, and its error names the rule, not +/// the input. +#[tokio::test] +async fn an_invalid_loopback_catalog_root_is_refused_before_any_request() { + const SECRET: &str = "synthetic-credential-4f1c"; + let hits = Arc::new(AtomicUsize::new(0)); + let recorded = Arc::clone(&hits); + let (base, listener) = bind().await; + spawn( + listener, + Router::new().fallback(move || { + let recorded = Arc::clone(&recorded); + async move { + recorded.fetch_add(1, Ordering::SeqCst); + StatusCode::OK + } + }), + ); + let authority = base.trim_start_matches("http://"); + let roots = [ + format!("{base}#{SECRET}"), + format!("{base}?key={SECRET}"), + format!("http://user:{SECRET}@{authority}"), + ]; + for root in roots { + let error = fetch_model_catalog_with_plan_proof(&root, "tok", &proof()) + .await + .expect_err("an API root with a query, fragment or credentials is refused"); + assert_eq!(error.code, ErrorCode::InvalidValue); + let shown = format!("{error} {} {error:?}", error.message); + assert!( + !shown.contains(SECRET) && !shown.contains(PROOF), + "the refusal repeats part of the input or the plan proof" + ); + } + assert_eq!( + hits.load(Ordering::SeqCst), + 0, + "a refused root was requested" + ); +} + +fn search(base: &str) -> GatewaySearch { + GatewaySearch::new( + GatewayEndpoint::new(base).expect("loopback endpoint"), + SecretString::new(SEARCH_KEY).expect("non-empty"), + ) +} + +fn search_query() -> SearchQuery { + SearchQuery { + query: "hi".to_owned(), + ..SearchQuery::default() + } +} + +fn presented_search_key(headers: &HeaderMap) -> bool { + headers + .get(axum::http::header::AUTHORIZATION) + .and_then(|value| value.to_str().ok()) + == Some(&format!("Bearer {SEARCH_KEY}")) +} + +#[tokio::test] +async fn a_loopback_search_does_not_follow_a_redirect() { + let hits = Arc::new(AtomicUsize::new(0)); + let recorded = Arc::clone(&hits); + let (dest_base, dest_listener) = bind().await; + let count_every_request = move |request: Request, next: Next| { + let recorded = Arc::clone(&recorded); + async move { + recorded.fetch_add(1, Ordering::SeqCst); + let response: Response = next.run(request).await; + response + } + }; + spawn( + dest_listener, + Router::new() + .route("/tools/web_search", post(|| async { StatusCode::OK })) + .layer(middleware::from_fn(count_every_request)), + ); + let (origin, origin_listener) = bind().await; + let location = format!("{dest_base}/tools/web_search"); + spawn( + origin_listener, + Router::new().route( + "/v1/tools/web_search", + post(move |headers: HeaderMap| { + let location = location.clone(); + async move { + assert!( + presented_search_key(&headers), + "the direct request arrived without the search bearer key" + ); + (StatusCode::TEMPORARY_REDIRECT, [("location", location)]) + } + }), + ), + ); + let error = SearchProvider::search(&search(&format!("{origin}/v1")), search_query()) + .await + .expect_err("a redirect is not a completed search"); + let source_text = std::error::Error::source(&error) + .map(ToString::to_string) + .unwrap_or_default(); + assert!( + !error.to_string().contains(SEARCH_KEY) && !source_text.contains(SEARCH_KEY), + "the redirect error contains the search bearer key" + ); + assert_eq!( + hits.load(Ordering::SeqCst), + 0, + "the redirect target received a request" + ); +} + +#[tokio::test] +async fn a_loopback_search_does_not_use_an_http_proxy() { + if std::env::var(ROLE).ok().as_deref() == Some("search") { + let (base, listener) = bind().await; + spawn( + listener, + Router::new().route( + "/v1/tools/web_search", + post(move |headers: HeaderMap| async move { + assert!( + presented_search_key(&headers), + "the direct request arrived without the search bearer key" + ); + ( + [(axum::http::header::CONTENT_TYPE, "application/json")], + SEARCH_BODY, + ) + }), + ), + ); + prove_canary(&format!("{base}/v1/tools/web_search")).await; + wait_until_counted(); + SearchProvider::search(&search(&format!("{base}/v1")), search_query()) + .await + .expect("the loopback search completes directly"); + return; + } + drive_proxy_check("search", "a_loopback_search_does_not_use_an_http_proxy").await; +} diff --git a/plan/2026-11-14-1-plan-proof-and-direct-loopback.plan.md b/plan/2026-11-14-1-plan-proof-and-direct-loopback.plan.md new file mode 100644 index 000000000..289af8d18 --- /dev/null +++ b/plan/2026-11-14-1-plan-proof-and-direct-loopback.plan.md @@ -0,0 +1,83 @@ +--- +name: Plan Proof And Direct Loopback +overview: "`harness-gateway-client` sends a plan proof that a Host passes to it, as `X-Runvil-Plan-Proof` on model rounds and on the model list, and it contacts a Gateway on the local machine with no proxy and without following a redirect." +todos: + - id: plan-proof + content: "harness-gateway-client: `PLAN_PROOF_HEADER`, `with_plan_proof` on `GatewayChat` and `GatewayBroker`, `fetch_model_catalog_with_plan_proof`; header and redaction tests" + status: completed + - id: loopback + content: "harness-gateway-client: `transport::http_client`, used by chat, the catalog, and search; the catalog validates its API root; `tests/loopback_direct.rs`" + status: completed + - id: verify + content: "runvil-harness: run every check in AGENTS.md on each commit" + status: completed +isProject: false +--- + +# A Host-supplied plan proof, and a direct path to a loopback Gateway + +## Why + +The ChatGPT plan extension proposed for `runvil-gateway` serves a plan model only to a caller that presents the plan proof of the Gateway's current boot. The Gateway writes that proof to a private file, and a Host on the same machine reads it. This crate is the Host's client, so it has to carry the proof. It could not. + +The second gap was there before. Every client in the crate was `reqwest::Client::new()`. That client uses the process's proxy settings and follows redirects. So a request to a Gateway on the local machine could leave the machine through `HTTP_PROXY` or `ALL_PROXY`, or be sent on by a redirect. A followed redirect drops `Authorization` when the host changes, but it keeps any other header. A proof header makes that worth closing. + +## The rule + +- **A Host passes the proof.** The crate reads no file and no environment variable to find one. `GatewayChat::from_env` still reads only the URL and the key. +- **No proof, no header.** A client that was given no proof sends the requests it sent before. +- **The proof is not a bearer.** `Authorization` is unchanged, with or without a key. +- **It goes on a model round and on the model list, and nowhere else.** `GatewaySearch` sends none. +- **It is redacted like the key.** The value is a `SecretString`, and `Debug` prints `` for it on `GatewayChat` and on `GatewayBroker`. +- **A loopback Gateway is contacted directly.** No proxy is used, and a redirect comes back as its own status. +- **Any other address keeps reqwest's defaults**, a proxy and redirects included. +- **The catalog validates its API root** the way a chat endpoint is validated, before any request. + +Decisions: + +- **The proof is sent to whatever Gateway the Host configured**, loopback or not. Whether to pass it is the Host's decision, and a Host that reads the proof from a local file has a local Gateway. +- **A loopback redirect is an error, not a hop.** A Gateway does not redirect its API, so a redirect there is a fault or an attack. +- **A loopback client that cannot be built panics.** Falling back to the default client would bring the proxy and the redirects back without a sign. `Client::new` already panics on the same TLS failure. +- **No change to `runvil` or to `build_request_body`.** The proof is a header, so the chat-completions body is still shaped in one place. + +## Commit 1: the plan proof + +- [transport.rs](../crates/harness-gateway-client/src/transport.rs): the public constant `PLAN_PROOF_HEADER`, re-exported from the crate root; the `plan_proof` field on `GatewayChat`; `GatewayChat::with_plan_proof`; and the header on the one request that `complete` sends. +- [broker.rs](../crates/harness-gateway-client/src/broker.rs): `GatewayBroker::with_plan_proof` gives the proof to its `GatewayChat` and keeps a copy for `models`. +- [catalog.rs](../crates/harness-gateway-client/src/catalog.rs): `fetch_model_catalog_with_plan_proof(base_url, token, plan_proof)` beside `fetch_model_catalog(base_url, token)`. Both call the private `fetch_catalog`, which sets the header on the single request when a proof was passed. +- [config.rs](../crates/harness-gateway-client/src/config.rs) and [lib.rs](../crates/harness-gateway-client/src/lib.rs): the docs of `SecretString` and of the crate say what a plan proof is and where it is sent. + +## Commit 2: the direct loopback path + +- [transport.rs](../crates/harness-gateway-client/src/transport.rs): `http_client(loopback)` builds the client. For a loopback endpoint it sets `no_proxy()` and `redirect::Policy::none()`. `GatewayChat::new` and `GatewayChat::keyless` call it with `GatewayEndpoint::is_loopback`. +- [search.rs](../crates/harness-gateway-client/src/search.rs): `GatewaySearch` calls it the same way. +- [catalog.rs](../crates/harness-gateway-client/src/catalog.rs): `catalog_client(loopback)` keeps two process-wide clients, one for a loopback Gateway and one for any other, so a remote catalog fetch still follows a redirect and uses a proxy. `fetch_catalog` builds a `GatewayEndpoint` from `base_url` first. + +One behavior change comes with that last point. `fetch_model_catalog` took any string and sent it. It now returns `InvalidValue` for a root that `GatewayEndpoint::new` refuses: not http or https, no host, embedded credentials, a query, or a fragment. A root such as `http://127.0.0.1:8081/v1?x` is refused, not classified, so it cannot be sent with the client that uses a proxy and follows redirects. + +## Tests + +- **The header.** `a_passed_proof_is_one_header_on_the_round_and_the_bearer_stays`, `a_keyless_client_with_a_proof_omits_authorization_and_sends_the_header`, and `from_env_sends_no_plan_proof_header` in `transport/tests/plan_proof.rs`; `models_sends_the_plan_proof_only_when_the_host_passed_one` in `broker-tests.rs`. +- **Redaction.** `debug_redacts_the_plan_proof_whether_or_not_one_was_passed` and `debug_redacts_a_plan_proof_the_same_way_it_redacts_the_key`. +- **No redirect.** In [loopback_direct.rs](../crates/harness-gateway-client/tests/loopback_direct.rs), a chat round, a catalog fetch, and a search each get a redirect from a loopback Gateway, and the target must receive nothing. For the chat round and the search the target counts every method, because a followed redirect can change the method. The error must not contain the proof, or the key for the search. +- **No proxy.** The same three run in a child process with `HTTP_PROXY` and `ALL_PROXY` set to a listener that counts connections. A plain reqwest client is sent through first as a canary. The test fails if the canary did not reach the listener, and fails if anything after it did. +- **The invalid root.** `an_invalid_loopback_catalog_root_is_refused_before_any_request` gives the catalog a loopback root with a query, with a fragment, and with credentials. Each returns `InvalidValue`, and a catch-all fixture receives nothing. + +The redirect, proxy, and invalid-root tests were each checked by removing the line they guard and watching them fail. + +## Left alone + +- **Error text.** A proof is never formatted into an error by this crate. The crate still keeps a bounded, control-escaped piece of a backend's error body, as it did, so a backend that echoes a header would put it there. +- **HTTPS proxies and TLS.** The fixtures are plain HTTP. +- **`GatewayChat::from_env`.** It gains no variable for the proof. + +## Verification + +Every command in [AGENTS.md](../AGENTS.md) on each commit: format, clippy, nextest, both doc builds, `cargo test -p build-xtask`, the wording check, `xtask api --check`, and dylint. Also `cargo deny check` and `cargo audit`. + +## What the build found + +- **The public API listings are unchanged.** `xtask api --check` reports no violation, and neither `public-api.txt` lists this crate. +- **No manifest changes.** The integration test's canary client is the `reqwest` the crate already depends on. +- **One test fails on macOS, with and without this change.** `lifecycle::the_fixture_is_loaded_invoked_unloaded_once_and_closed` in `harness-test-plugin` fails the same way on `9dd953b5`. The other 3,647 tests pass. +- **Run on macOS arm64 only.** The Windows job was not run.