use crate::onboard::{LadderChoice, Provider, Shape, render_config};
use firstpass_core::{GENESIS_HASH, Mode, Trace, verify_chain};
use serde_json::{Value, json};
use std::path::{Path, PathBuf};
use std::sync::Arc;
type Fail = Box<dyn std::error::Error>;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Pick {
pub provider: Provider,
pub key_env: &'static str,
}
const CANDIDATES: [(Provider, &str); 3] = [
(Provider::Anthropic, "ANTHROPIC_API_KEY"),
(Provider::OpenAi, "OPENAI_API_KEY"),
(Provider::Google, "GEMINI_API_KEY"),
];
pub fn pick_provider(env: impl Fn(&str) -> Option<String>) -> Option<Pick> {
CANDIDATES.iter().find_map(|&(provider, key_env)| {
env(key_env)
.filter(|v| !v.trim().is_empty())
.map(|_| Pick { provider, key_env })
})
}
#[must_use]
pub fn kiosk_config(pick: Pick) -> String {
render_config(&LadderChoice {
provider: pick.provider,
shape: Shape::Json,
mode: Mode::Enforce,
})
}
pub fn print_receipt(trace: &Trace) {
println!("\x1b[1m── audit receipt ──────────────────────────────────\x1b[0m");
for a in &trace.attempts {
let verdict = match a.verdict {
firstpass_core::Verdict::Pass => "\x1b[32mPASS\x1b[0m",
firstpass_core::Verdict::Fail => "\x1b[31mFAIL\x1b[0m",
firstpass_core::Verdict::Abstain => "\x1b[33mABSTAIN\x1b[0m",
};
println!(
" rung {} · {:<28} · {verdict} · ${:.4}",
a.rung, a.model, a.cost_usd
);
}
let f = &trace.final_;
println!(" ─────────────────────────────────────────────────");
println!(" total ${:.4}", f.total_cost_usd);
println!(
" baseline ${:.4} (always top-tier)",
f.counterfactual_baseline_usd
);
let pct = if f.counterfactual_baseline_usd > 0.0 {
f.savings_usd / f.counterfactual_baseline_usd * 100.0
} else {
0.0
};
println!(
" \x1b[32mSAVED ${:.4} ({pct:.0}% cheaper at proven quality)\x1b[0m",
f.savings_usd
);
println!(" trace_id {}", trace.trace_id);
println!(
" chain {}\n",
if verify_chain(std::slice::from_ref(trace), &trace.prev_hash).is_ok() {
"verified ✓"
} else {
"BROKEN"
}
);
}
pub async fn run() -> Result<(), Fail> {
let Some(pick) = pick_provider(|k| std::env::var(k).ok()) else {
println!("\n\x1b[1mFirstpass kiosk\x1b[0m");
println!(
"no provider key in the environment (looked for {}).",
CANDIDATES
.iter()
.map(|(_, k)| *k)
.collect::<Vec<_>>()
.join(", ")
);
println!("running the keyless demo instead — same proxy, same receipt, local upstream.\n");
return crate::demo::run().await;
};
crate::run::init_tracing();
println!("\n\x1b[1mFirstpass kiosk\x1b[0m");
println!(
"found {} — routing one real request through a real enforce ladder\n",
pick.key_env
);
let path = PathBuf::from("firstpass.toml");
let toml = kiosk_config(pick);
let config_note = if path.exists() {
"firstpass.toml already exists — using it unchanged".to_owned()
} else {
std::fs::write(&path, &toml)?;
format!("wrote {}", path.display())
};
println!("config : {config_note}");
let toml = std::fs::read_to_string(&path)?;
let db = std::env::temp_dir().join(format!("firstpass-kiosk-{}.db", uuid::Uuid::now_v7()));
let (proxy, _writer) = spawn(&toml, &db).await?;
println!("proxy : {proxy}\n");
let key = std::env::var(pick.key_env).unwrap_or_default();
let client = reqwest::Client::new();
let served: Value = client
.post(format!("{proxy}/v1/messages"))
.header("x-api-key", &key)
.header("authorization", format!("Bearer {key}"))
.json(&json!({
"model": "claude-haiku-4-5",
"max_tokens": 256,
"messages": [{
"role": "user",
"content": "Reply with ONLY a JSON object with keys \"id\" (string) and \"total\" (number). No prose, no code fence.",
}],
}))
.send()
.await?
.json()
.await?;
if served.get("error").is_some() {
return Err(format!(
"the {} call failed — see the `provider rejected the call` line above for the \
provider's own message (a rejected key is the usual cause). `firstpass doctor` \
checks the key and config.",
pick.key_env
)
.into());
}
println!("served : {}", served["content"][0]["text"]);
println!("model : {}\n", served["model"]);
let trace = wait_for_trace(&db).await.ok_or("no receipt was recorded")?;
print_receipt(&trace);
let all = crate::store::load_all_traces(&db)?;
println!(
"chain : {}",
if verify_chain(&all, GENESIS_HASH).is_ok() {
"\x1b[32mverified ✓\x1b[0m — re-derivable by anyone holding the log"
} else {
"BROKEN"
}
);
println!("panel : {proxy}/panel");
println!("\nkeep it: FIRSTPASS_CONFIG=./firstpass.toml firstpass up");
println!("route your agent: export ANTHROPIC_BASE_URL={proxy}");
println!("undo everything : unset ANTHROPIC_BASE_URL\n");
let _ = std::fs::remove_file(&db);
Ok(())
}
pub async fn handshake() -> Value {
let mut doc = handshake_static();
doc["selftest"] = selftest().await;
doc
}
#[must_use]
pub fn handshake_static() -> Value {
let pick = pick_provider(|k| std::env::var(k).ok());
let detected: Vec<&str> = CANDIDATES
.iter()
.filter(|(_, k)| std::env::var(k).is_ok_and(|v| !v.trim().is_empty()))
.map(|(_, k)| *k)
.collect();
let selftest = json!({
"ok": null,
"reason": "not run here — `firstpass handshake` runs the keyless self-test",
});
json!({
"product": "firstpass",
"version": env!("CARGO_PKG_VERSION"),
"provider": {
"picked": pick.map(|p| p.provider.id()),
"key_env": pick.map(|p| p.key_env),
"keys_present": detected,
},
"config": {
"path": "firstpass.toml",
"exists": std::path::Path::new("firstpass.toml").exists(),
"toml": pick.map(kiosk_config),
},
"selftest": selftest,
"route_your_agent": { "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:8080" } },
"offboard": { "unset": ["ANTHROPIC_BASE_URL"] },
"next": [
"firstpass kiosk — write the config and put one real request through it",
"firstpass up — run the proxy",
"firstpass doctor — validate config, key, and gate binaries",
],
})
}
async fn selftest() -> Value {
if let Ok(upstream) = crate::demo::spawn_upstream().await {
let db =
std::env::temp_dir().join(format!("firstpass-handshake-{}.db", uuid::Uuid::now_v7()));
if let Ok((proxy, _w)) = crate::demo::spawn_proxy(&upstream, &db).await {
let served = reqwest::Client::new()
.post(format!("{proxy}/v1/messages"))
.header("x-api-key", "keyless-selftest")
.json(&json!({
"model": "claude-haiku-4-5",
"max_tokens": 64,
"messages": [{ "role": "user", "content": "selftest" }],
}))
.send()
.await;
let ok_http = served.is_ok_and(|r| r.status().is_success());
let trace = wait_for_trace(&db).await;
let chain_ok = trace
.as_ref()
.is_some_and(|t| verify_chain(std::slice::from_ref(t), &t.prev_hash).is_ok());
let out = json!({
"ok": ok_http && trace.is_some() && chain_ok,
"keyless": true,
"served": ok_http,
"receipt": trace.is_some(),
"escalated": trace.as_ref().is_some_and(|t| t.attempts.len() > 1),
"chain_verified": chain_ok,
});
let _ = std::fs::remove_file(&db);
return out;
}
let _ = std::fs::remove_file(&db);
}
json!({ "ok": false, "keyless": true, "reason": "could not stand up the local self-test" })
}
async fn spawn(toml: &str, db: &Path) -> Result<(String, tokio::task::JoinHandle<()>), Fail> {
let toml = toml.to_owned();
let db_str = db.to_string_lossy().into_owned();
let config = crate::ProxyConfig::from_lookup(move |k| match k {
"FIRSTPASS_CONFIG_TOML" => Some(toml.clone()),
"FIRSTPASS_MODE" => Some("enforce".to_owned()),
"FIRSTPASS_DB" => Some(db_str.clone()),
_ => None,
})?;
let provider_defs = config
.routing
.as_ref()
.map(|r| r.providers.as_slice())
.unwrap_or_default();
let providers = crate::provider::ProviderRegistry::from_config(
provider_defs,
&config.upstream_anthropic,
&config.upstream_openai,
);
let (traces, writer) = crate::store::open(db)?;
let state = crate::proxy::AppState {
config: Arc::new(config),
http: reqwest::Client::new(),
providers,
gate_health: Arc::new(crate::gate::GateHealthRegistry::new()),
shadow_ledger: Arc::new(crate::shadow::ShadowLedger::new()),
paired_ledger: Arc::new(crate::shadow::ShadowLedger::new()),
experiments: Arc::default(),
guardrails: Arc::new(crate::guard::GuardrailRegistry::new()),
traces,
adaptive: None,
eprocess: None,
promoter: None,
verified_cache: None,
bandit: None,
predictor: None,
prior: None,
tenant_rate_limiter: None,
spill: None,
};
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await?;
let addr = listener.local_addr()?;
let app = crate::app(state)?;
tokio::spawn(async move {
let _ = axum::serve(listener, app).await;
});
Ok((format!("http://{addr}"), writer))
}
async fn wait_for_trace(db: &Path) -> Option<Trace> {
for _ in 0..50 {
tokio::time::sleep(std::time::Duration::from_millis(100)).await;
if let Ok(traces) = crate::store::load_all_traces(db)
&& let Some(t) = traces.into_iter().next()
{
return Some(t);
}
}
None
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn picks_the_first_provider_whose_key_is_present() {
let pick = pick_provider(|k| (k == "OPENAI_API_KEY").then(|| "sk-x".to_owned()))
.expect("openai key must be found");
assert_eq!(pick.provider, Provider::OpenAi);
assert_eq!(pick.key_env, "OPENAI_API_KEY");
let both = pick_provider(|k| {
matches!(k, "OPENAI_API_KEY" | "ANTHROPIC_API_KEY").then(|| "sk-x".to_owned())
})
.expect("a key must be found");
assert_eq!(both.provider, Provider::Anthropic);
assert_eq!(
pick_provider(|_| None),
None,
"no key at all is a supported state, not an error"
);
}
#[test]
fn a_blank_key_counts_as_absent() {
assert_eq!(
pick_provider(|k| (k == "ANTHROPIC_API_KEY").then(|| " ".to_owned())),
None
);
}
#[test]
fn handshake_is_machine_readable_and_writes_nothing() {
let before = std::path::Path::new("firstpass.toml").exists();
let doc = handshake_static();
assert_eq!(doc["product"], "firstpass");
assert!(doc["version"].is_string());
assert!(doc["provider"]["keys_present"].is_array());
assert!(doc["config"]["exists"].is_boolean());
assert!(doc["route_your_agent"]["env"]["ANTHROPIC_BASE_URL"].is_string());
assert_eq!(doc["offboard"]["unset"][0], "ANTHROPIC_BASE_URL");
assert!(doc["selftest"]["ok"].is_null());
assert_eq!(
std::path::Path::new("firstpass.toml").exists(),
before,
"handshake must not create or remove config"
);
}
#[test]
fn every_pickable_provider_yields_a_parseable_enforcing_config() {
for (provider, key_env) in CANDIDATES {
let toml = kiosk_config(Pick { provider, key_env });
let cfg = firstpass_core::Config::parse(&toml)
.unwrap_or_else(|e| panic!("{provider:?} kiosk config must parse: {e}"));
assert_eq!(
cfg.routes[0].mode,
Mode::Enforce,
"{provider:?} must enforce, or the receipt shows no decision"
);
assert!(
cfg.routes[0].ladder.len() >= 2,
"{provider:?} needs a rung to escalate to"
);
}
}
}