Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 108 additions & 0 deletions crates/harness-gateway-client/src/broker-tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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("<redacted>"), "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;
Expand Down Expand Up @@ -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<Mutex<Vec<Vec<String>>>> = 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::<String>::new(),
vec![PROOF.to_owned()],
Vec::<String>::new(),
vec![PROOF.to_owned()],
],
"absent stays absent, and a passed proof is exactly one header"
);
}
35 changes: 32 additions & 3 deletions crates/harness-gateway-client/src/broker.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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.
Expand All @@ -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<SecretString>,
}

impl fmt::Debug for GatewayBroker {
Expand All @@ -55,6 +61,7 @@ impl fmt::Debug for GatewayBroker {
.field("client", &self.client)
.field("api_root", &self.endpoint.url())
.field("key", &"<redacted>")
.field("plan_proof", &"<redacted>")
.finish()
}
}
Expand All @@ -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.
///
Expand Down Expand Up @@ -120,7 +141,15 @@ impl InferenceBroker for GatewayBroker {
fn models(&self) -> BoxFuture<'static, Result<ModelCatalog, Error>> {
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(
Expand Down
89 changes: 71 additions & 18 deletions crates/harness-gateway-client/src/catalog.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -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<reqwest::Client> = 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<reqwest::Client> = std::sync::OnceLock::new();
static REMOTE: std::sync::OnceLock<reqwest::Client> = 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
Expand All @@ -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<reqwest::Response, Error> {
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<reqwest::Response, Error> {
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);
Expand All @@ -160,11 +174,13 @@ async fn get_authed(url: String, token: &str) -> std::result::Result<reqwest::Re
///
/// `base_url` is the root of the Gateway's OpenAI-compatible API, for
/// example `http://127.0.0.1:8081/v1`. The request sends `token` as a
/// bearer token.
/// bearer token and sends no plan-proof header.
///
/// # Errors
/// Returns an [`Error`]. Its [`code`](Error::code) is:
///
/// - `InvalidValue` when `base_url` is not a valid API root, as
/// [`GatewayEndpoint::new`] defines one; no request is sent;
/// - `Transport` or `Timeout` when the HTTP request or a response read fails;
/// - the code [`make_classify_http_failure_error`] picks for the response when the
/// Gateway returns a status outside the 2xx range;
Expand All @@ -173,8 +189,45 @@ pub async fn fetch_model_catalog(
base_url: &str,
token: &str,
) -> std::result::Result<ModelCatalog, Error> {
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<ModelCatalog, Error> {
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<ModelCatalog, Error> {
// 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?;
Expand Down
15 changes: 8 additions & 7 deletions crates/harness-gateway-client/src/config.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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<String>) -> std::result::Result<SecretString, Error> {
let secret = secret.into();
if secret.is_empty() {
Expand Down
10 changes: 8 additions & 2 deletions crates/harness-gateway-client/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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;
Expand Down
Loading
Loading