1use crate::onboard::{LadderChoice, Provider, Shape, render_config};
19use firstpass_core::{GENESIS_HASH, Mode, Trace, verify_chain};
20use serde_json::{Value, json};
21use std::path::{Path, PathBuf};
22use std::sync::Arc;
23
24type Fail = Box<dyn std::error::Error>;
27
28#[derive(Debug, Clone, Copy, PartialEq, Eq)]
30pub struct Pick {
31 pub provider: Provider,
33 pub key_env: &'static str,
35}
36
37const CANDIDATES: [(Provider, &str); 3] = [
39 (Provider::Anthropic, "ANTHROPIC_API_KEY"),
40 (Provider::OpenAi, "OPENAI_API_KEY"),
41 (Provider::Google, "GEMINI_API_KEY"),
42];
43
44pub fn pick_provider(env: impl Fn(&str) -> Option<String>) -> Option<Pick> {
50 CANDIDATES.iter().find_map(|&(provider, key_env)| {
51 env(key_env)
52 .filter(|v| !v.trim().is_empty())
53 .map(|_| Pick { provider, key_env })
54 })
55}
56
57#[must_use]
60pub fn kiosk_config(pick: Pick) -> String {
61 render_config(&LadderChoice {
62 provider: pick.provider,
63 shape: Shape::Json,
64 mode: Mode::Enforce,
65 })
66}
67
68pub fn print_receipt(trace: &Trace) {
71 println!("\x1b[1m── audit receipt ──────────────────────────────────\x1b[0m");
72 for a in &trace.attempts {
73 let verdict = match a.verdict {
74 firstpass_core::Verdict::Pass => "\x1b[32mPASS\x1b[0m",
75 firstpass_core::Verdict::Fail => "\x1b[31mFAIL\x1b[0m",
76 firstpass_core::Verdict::Abstain => "\x1b[33mABSTAIN\x1b[0m",
77 };
78 println!(
79 " rung {} · {:<28} · {verdict} · ${:.4}",
80 a.rung, a.model, a.cost_usd
81 );
82 }
83 let f = &trace.final_;
84 println!(" ─────────────────────────────────────────────────");
85 println!(" total ${:.4}", f.total_cost_usd);
86 println!(
87 " baseline ${:.4} (always top-tier)",
88 f.counterfactual_baseline_usd
89 );
90 let pct = if f.counterfactual_baseline_usd > 0.0 {
91 f.savings_usd / f.counterfactual_baseline_usd * 100.0
92 } else {
93 0.0
94 };
95 println!(
96 " \x1b[32mSAVED ${:.4} ({pct:.0}% cheaper at proven quality)\x1b[0m",
97 f.savings_usd
98 );
99 println!(" trace_id {}", trace.trace_id);
100 println!(
101 " chain {}\n",
102 if verify_chain(std::slice::from_ref(trace), &trace.prev_hash).is_ok() {
103 "verified ✓"
104 } else {
105 "BROKEN"
106 }
107 );
108}
109
110pub async fn run() -> Result<(), Fail> {
116 let Some(pick) = pick_provider(|k| std::env::var(k).ok()) else {
117 println!("\n\x1b[1mFirstpass kiosk\x1b[0m");
118 println!(
119 "no provider key in the environment (looked for {}).",
120 CANDIDATES
121 .iter()
122 .map(|(_, k)| *k)
123 .collect::<Vec<_>>()
124 .join(", ")
125 );
126 println!("running the keyless demo instead — same proxy, same receipt, local upstream.\n");
127 return crate::demo::run().await;
128 };
129
130 crate::run::init_tracing();
133
134 println!("\n\x1b[1mFirstpass kiosk\x1b[0m");
135 println!(
136 "found {} — routing one real request through a real enforce ladder\n",
137 pick.key_env
138 );
139
140 let path = PathBuf::from("firstpass.toml");
143 let toml = kiosk_config(pick);
144 let config_note = if path.exists() {
145 "firstpass.toml already exists — using it unchanged".to_owned()
146 } else {
147 std::fs::write(&path, &toml)?;
148 format!("wrote {}", path.display())
149 };
150 println!("config : {config_note}");
151 let toml = std::fs::read_to_string(&path)?;
152
153 let db = std::env::temp_dir().join(format!("firstpass-kiosk-{}.db", uuid::Uuid::now_v7()));
154 let (proxy, _writer) = spawn(&toml, &db).await?;
155 println!("proxy : {proxy}\n");
156
157 let key = std::env::var(pick.key_env).unwrap_or_default();
159 let client = reqwest::Client::new();
160 let served: Value = client
161 .post(format!("{proxy}/v1/messages"))
162 .header("x-api-key", &key)
163 .header("authorization", format!("Bearer {key}"))
164 .json(&json!({
165 "model": "claude-haiku-4-5",
166 "max_tokens": 256,
167 "messages": [{
168 "role": "user",
169 "content": "Reply with ONLY a JSON object with keys \"id\" (string) and \"total\" (number). No prose, no code fence.",
170 }],
171 }))
172 .send()
173 .await?
174 .json()
175 .await?;
176
177 if served.get("error").is_some() {
178 return Err(format!(
185 "the {} call failed — see the `provider rejected the call` line above for the \
186 provider's own message (a rejected key is the usual cause). `firstpass doctor` \
187 checks the key and config.",
188 pick.key_env
189 )
190 .into());
191 }
192 println!("served : {}", served["content"][0]["text"]);
193 println!("model : {}\n", served["model"]);
194
195 let trace = wait_for_trace(&db).await.ok_or("no receipt was recorded")?;
196 print_receipt(&trace);
197
198 let all = crate::store::load_all_traces(&db)?;
199 println!(
200 "chain : {}",
201 if verify_chain(&all, GENESIS_HASH).is_ok() {
202 "\x1b[32mverified ✓\x1b[0m — re-derivable by anyone holding the log"
203 } else {
204 "BROKEN"
205 }
206 );
207 println!("panel : {proxy}/panel");
208 println!("\nkeep it: FIRSTPASS_CONFIG=./firstpass.toml firstpass up");
209 println!("route your agent: export ANTHROPIC_BASE_URL={proxy}");
210 println!("undo everything : unset ANTHROPIC_BASE_URL\n");
211
212 let _ = std::fs::remove_file(&db);
213 Ok(())
214}
215
216pub async fn handshake() -> Value {
227 let mut doc = handshake_static();
228 doc["selftest"] = selftest().await;
229 doc
230}
231
232#[must_use]
236pub fn handshake_static() -> Value {
237 let pick = pick_provider(|k| std::env::var(k).ok());
238 let detected: Vec<&str> = CANDIDATES
239 .iter()
240 .filter(|(_, k)| std::env::var(k).is_ok_and(|v| !v.trim().is_empty()))
241 .map(|(_, k)| *k)
242 .collect();
243 let selftest = json!({
244 "ok": null,
245 "reason": "not run here — `firstpass handshake` runs the keyless self-test",
246 });
247 json!({
248 "product": "firstpass",
249 "version": env!("CARGO_PKG_VERSION"),
250 "provider": {
251 "picked": pick.map(|p| p.provider.id()),
252 "key_env": pick.map(|p| p.key_env),
253 "keys_present": detected,
254 },
255 "config": {
256 "path": "firstpass.toml",
257 "exists": std::path::Path::new("firstpass.toml").exists(),
258 "toml": pick.map(kiosk_config),
261 },
262 "selftest": selftest,
263 "route_your_agent": { "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:8080" } },
264 "offboard": { "unset": ["ANTHROPIC_BASE_URL"] },
265 "next": [
266 "firstpass kiosk — write the config and put one real request through it",
267 "firstpass up — run the proxy",
268 "firstpass doctor — validate config, key, and gate binaries",
269 ],
270 })
271}
272
273async fn selftest() -> Value {
277 if let Ok(upstream) = crate::demo::spawn_upstream().await {
278 let db =
279 std::env::temp_dir().join(format!("firstpass-handshake-{}.db", uuid::Uuid::now_v7()));
280 if let Ok((proxy, _w)) = crate::demo::spawn_proxy(&upstream, &db).await {
281 let served = reqwest::Client::new()
282 .post(format!("{proxy}/v1/messages"))
283 .header("x-api-key", "keyless-selftest")
284 .json(&json!({
285 "model": "claude-haiku-4-5",
286 "max_tokens": 64,
287 "messages": [{ "role": "user", "content": "selftest" }],
288 }))
289 .send()
290 .await;
291 let ok_http = served.is_ok_and(|r| r.status().is_success());
292 let trace = wait_for_trace(&db).await;
293 let chain_ok = trace
294 .as_ref()
295 .is_some_and(|t| verify_chain(std::slice::from_ref(t), &t.prev_hash).is_ok());
296 let out = json!({
297 "ok": ok_http && trace.is_some() && chain_ok,
298 "keyless": true,
299 "served": ok_http,
300 "receipt": trace.is_some(),
301 "escalated": trace.as_ref().is_some_and(|t| t.attempts.len() > 1),
302 "chain_verified": chain_ok,
303 });
304 let _ = std::fs::remove_file(&db);
305 return out;
306 }
307 let _ = std::fs::remove_file(&db);
308 }
309 json!({ "ok": false, "keyless": true, "reason": "could not stand up the local self-test" })
310}
311
312async fn spawn(toml: &str, db: &Path) -> Result<(String, tokio::task::JoinHandle<()>), Fail> {
314 let toml = toml.to_owned();
315 let db_str = db.to_string_lossy().into_owned();
316 let config = crate::ProxyConfig::from_lookup(move |k| match k {
317 "FIRSTPASS_CONFIG_TOML" => Some(toml.clone()),
318 "FIRSTPASS_MODE" => Some("enforce".to_owned()),
319 "FIRSTPASS_DB" => Some(db_str.clone()),
320 _ => None,
321 })?;
322 let provider_defs = config
323 .routing
324 .as_ref()
325 .map(|r| r.providers.as_slice())
326 .unwrap_or_default();
327 let providers = crate::provider::ProviderRegistry::from_config(
328 provider_defs,
329 &config.upstream_anthropic,
330 &config.upstream_openai,
331 );
332 let (traces, writer) = crate::store::open(db)?;
333 let state = crate::proxy::AppState {
334 config: Arc::new(config),
335 http: reqwest::Client::new(),
336 providers,
337 gate_health: Arc::new(crate::gate::GateHealthRegistry::new()),
338 shadow_ledger: Arc::new(crate::shadow::ShadowLedger::new()),
339 guardrails: Arc::new(crate::guard::GuardrailRegistry::new()),
340 traces,
341 adaptive: None,
342 bandit: None,
343 predictor: None,
344 tenant_rate_limiter: None,
345 spill: None,
346 };
347 let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await?;
348 let addr = listener.local_addr()?;
349 let app = crate::app(state)?;
350 tokio::spawn(async move {
351 let _ = axum::serve(listener, app).await;
352 });
353 Ok((format!("http://{addr}"), writer))
354}
355
356async fn wait_for_trace(db: &Path) -> Option<Trace> {
358 for _ in 0..50 {
359 tokio::time::sleep(std::time::Duration::from_millis(100)).await;
360 if let Ok(traces) = crate::store::load_all_traces(db)
361 && let Some(t) = traces.into_iter().next()
362 {
363 return Some(t);
364 }
365 }
366 None
367}
368
369#[cfg(test)]
370mod tests {
371 use super::*;
372
373 #[test]
374 fn picks_the_first_provider_whose_key_is_present() {
375 let pick = pick_provider(|k| (k == "OPENAI_API_KEY").then(|| "sk-x".to_owned()))
376 .expect("openai key must be found");
377 assert_eq!(pick.provider, Provider::OpenAi);
378 assert_eq!(pick.key_env, "OPENAI_API_KEY");
379
380 let both = pick_provider(|k| {
382 matches!(k, "OPENAI_API_KEY" | "ANTHROPIC_API_KEY").then(|| "sk-x".to_owned())
383 })
384 .expect("a key must be found");
385 assert_eq!(both.provider, Provider::Anthropic);
386
387 assert_eq!(
388 pick_provider(|_| None),
389 None,
390 "no key at all is a supported state, not an error"
391 );
392 }
393
394 #[test]
397 fn a_blank_key_counts_as_absent() {
398 assert_eq!(
399 pick_provider(|k| (k == "ANTHROPIC_API_KEY").then(|| " ".to_owned())),
400 None
401 );
402 }
403
404 #[test]
407 fn handshake_is_machine_readable_and_writes_nothing() {
408 let before = std::path::Path::new("firstpass.toml").exists();
409 let doc = handshake_static();
410
411 assert_eq!(doc["product"], "firstpass");
413 assert!(doc["version"].is_string());
414 assert!(doc["provider"]["keys_present"].is_array());
415 assert!(doc["config"]["exists"].is_boolean());
416 assert!(doc["route_your_agent"]["env"]["ANTHROPIC_BASE_URL"].is_string());
417 assert_eq!(doc["offboard"]["unset"][0], "ANTHROPIC_BASE_URL");
419 assert!(doc["selftest"]["ok"].is_null());
421
422 assert_eq!(
423 std::path::Path::new("firstpass.toml").exists(),
424 before,
425 "handshake must not create or remove config"
426 );
427 }
428
429 #[test]
432 fn every_pickable_provider_yields_a_parseable_enforcing_config() {
433 for (provider, key_env) in CANDIDATES {
434 let toml = kiosk_config(Pick { provider, key_env });
435 let cfg = firstpass_core::Config::parse(&toml)
436 .unwrap_or_else(|e| panic!("{provider:?} kiosk config must parse: {e}"));
437 assert_eq!(
438 cfg.routes[0].mode,
439 Mode::Enforce,
440 "{provider:?} must enforce, or the receipt shows no decision"
441 );
442 assert!(
445 cfg.routes[0].ladder.len() >= 2,
446 "{provider:?} needs a rung to escalate to"
447 );
448 }
449 }
450}