spectra status, probe and bridge: what the VS Code extension drives (#31) c7161ec1a607

//! The bridge (spec §18.1): a loopback proxy that signs as the owner, for a

//! program that cannot sign itself (the VS Code extension). It answers only

//! requests that carry its per-run token, from its own loopback host and

//! with no `Origin`, so no web page can use it, and it signs each with the

//! owner's key before forwarding it to the daemon, wherever that is.

use crate::client::{sign_headers, Client};

use axum::body::{Body, Bytes};

use axum::extract::{Request, State};

use axum::http::{header, StatusCode};

use axum::response::{IntoResponse, Response};

use http_body_util::{BodyExt, Full};

use std::sync::Arc;

struct Bridge {

    upstream: Client,

    token: String,

    hosts: Vec<String>,

}

/// The bridge's routes, forwarding to `upstream` (which signs) for the

/// holder of `token`, at `127.0.0.1:port`.

pub fn router(upstream: Client, token: String, port: u16) -> axum::Router {

    let b = Arc::new(Bridge { upstream, token, hosts: vec![format!("127.0.0.1:{port}"), format!("localhost:{port}")] });

    axum::Router::new().fallback(forward).with_state(b)

}

/// A fresh random token.

pub fn token() -> String {

    let mut b = [0u8; 32];

    rand::RngCore::fill_bytes(&mut rand::rngs::OsRng, &mut b);

    hex::encode(b)

}

fn refuse(status: StatusCode, why: &str) -> Response {

    (status, axum::Json(serde_json::json!({ "title": why }))).into_response()

}

async fn forward(State(b): State<Arc<Bridge>>, req: Request) -> Response {

    let h = req.headers();

    let host = h.get(header::HOST).and_then(|v| v.to_str().ok()).unwrap_or("");

    if !b.hosts.iter().any(|x| x == host) || h.contains_key(header::ORIGIN) {

        return refuse(StatusCode::FORBIDDEN, "the bridge serves the program that started it, not web pages");

    }

    let given = h.get(header::AUTHORIZATION).and_then(|v| v.to_str().ok()).and_then(|v| v.strip_prefix("Bearer ")).unwrap_or("");

    if !subtle_eq(given.as_bytes(), b.token.as_bytes()) {

        return refuse(StatusCode::UNAUTHORIZED, "the bridge's token is missing or wrong");

    }

    let (parts, body) = req.into_parts();

    let body: Bytes = match body.collect().await {

        Ok(x) => x.to_bytes(),

        Err(_) => return refuse(StatusCode::BAD_REQUEST, "an unreadable body"),

    };

    let path = parts.uri.path_and_query().map(|p| p.as_str()).unwrap_or("/").to_string();

    let method = parts.method.as_str().to_string();

    let mut up = hyper::Request::builder()

        .method(parts.method.clone())

        .uri(&path)

        .header(header::HOST, "spectra")

        .header(header::CONNECTION, "close");

    for k in [header::CONTENT_TYPE, header::ACCEPT, header::IF_NONE_MATCH] {

        if let Some(v) = parts.headers.get(&k) {

            up = up.header(k, v);

        }

    }

    if let Some(pair) = b.upstream.signer() {

        for (k, v) in sign_headers(pair, &format!("{method} {path}"), &body) {

            up = up.header(k, v);

        }

    }

    let up = match up.body(Full::new(body)) {

        Ok(r) => r,

        Err(_) => return refuse(StatusCode::BAD_REQUEST, "not a request the bridge can pass on"),

    };

    match b.upstream.forward(up).await {

        Ok(resp) => {

            let (parts, incoming) = resp.into_parts();

            let mut out = Response::new(Body::new(incoming));

            *out.status_mut() = parts.status;

            for (k, v) in parts.headers.iter() {

                if !matches!(k.as_str(), "connection" | "transfer-encoding" | "keep-alive") {

                    out.headers_mut().append(k, v.clone());

                }

            }

            out

        }

        Err(e) => refuse(StatusCode::BAD_GATEWAY, &format!("Spectra did not answer: {e:#}")),

    }

}

/// Compare in time that does not depend on where the first difference is.

fn subtle_eq(a: &[u8], b: &[u8]) -> bool {

    if a.len() != b.len() {

        return false;

    }

    a.iter().zip(b).fold(0u8, |acc, (x, y)| acc | (x ^ y)) == 0

}

#[cfg(test)]

mod tests {

    #[test]

    fn tokens_are_fresh_and_compared_whole() {

        assert_ne!(super::token(), super::token());

        assert!(super::subtle_eq(b"abc", b"abc"));

        assert!(!super::subtle_eq(b"abc", b"abd"));

        assert!(!super::subtle_eq(b"abc", b"ab"));

    }

}

//! Commands a program uses to set Spectra up and to talk to it (spec

//! §18.1): `spectra status` says what is set up, `spectra probe` what a

//! server is before trusting it, and `spectra bridge` signs for a program

//! that cannot (the VS Code extension).

use super::identity::owner_home;

use super::{ui, Ctx};

use anyhow::{bail, Context, Result};

use serde_json::{json, Value};

use spectra_mcp::client::{host_port, Client, Endpoint};

use spectra_mcp::tls::Pinned;

use std::path::PathBuf;

/// `spectra status [--json]`: the identity, the server or local Spectra.

pub async fn status(ctx: &Ctx, as_json: bool) -> Result<i32> {

    let home = owner_home(ctx, None);

    let identity = spectra_core::keys::KeyPair::load_home(&home).ok();

    let remote = ctx.remote()?;

    let initialised = ctx.data.join("spectra.db").exists();

    let serving = initialised && Client::alive(&ctx.socket()).await;

    let reachable = match &remote {

        Some(c) => Client::at(c.endpoint()?, None).send("GET", "/api/v1/health", &[], vec![]).await.is_ok_and(|r| r.status < 500),

        None => serving,

    };

    let v = json!({

        "version": env!("SPECTRA_VERSION_LONG"),

        "home": home.display().to_string(),

        "identity": identity.as_ref().map(|p| json!({ "name": p.identity.name, "key": p.key.to_hex() })),

        "server": remote.as_ref().map(|c| json!({ "url": c.server, "instance": c.instance })),

        "local": { "data": ctx.data.display().to_string(), "initialised": initialised, "serving": serving },

        "reachable": reachable,

    });

    if as_json {

        println!("{v}");

        return Ok(0);

    }

    println!("{}", ui::kv("version", env!("SPECTRA_VERSION_LONG")));

    match &identity {

        Some(p) => println!("{}", ui::kv("you", format!("{}{}{}", ui::author(&p.identity.name), ui::sep(), ui::hash(p.key.short(12))))),

        None => println!("{}", ui::kv("you", ui::warn("no identity yet: spectra identity create --name NAME"))),

    }

    match &remote {

        Some(c) => println!("{}", ui::kv("spectra", format!("{}{}", ui::path(&c.server), if reachable { "" } else { " (not answering)" }))),

        None if initialised => println!(

            "{}",

            ui::kv("spectra", format!("{}{}", ui::path(ctx.data.display()), if serving { " (serving)" } else { " (not serving)" }))

        ),

        None => println!("{}", ui::kv("spectra", ui::warn("none yet: spectra init here, or spectra connect https://HOST:7350"))),

    }

    Ok(0)

}

/// `spectra probe URL [--json]`: who a server says it is, checked against

/// its certificate, without trusting it.

pub async fn probe(url: &str, as_json: bool) -> Result<i32> {

    let addr = host_port(url)?;

    let seen = Pinned::new(None);

    let c = Client::at(Endpoint::Tls { addr: addr.clone(), config: seen.client_config()? }, None);

    let r = c.send("GET", "/api/v1/instance", &[], vec![]).await.with_context(|| format!("reaching https://{addr}"))?;

    if r.status != 200 {

        bail!("https://{addr} answered {} to /api/v1/instance: is it a Spectra?", r.status);

    }

    let answer = r.json()?;

    let (_, pin) = seen.seen().context("the server showed no certificate")?;

    let checked = spectra_mcp::instance::check(&answer, &pin)?;

    let mine = spectra_core::keys::KeyPair::load_home(&spectra_core::keys::default_home()).ok();

    let waiting = answer.get("named_owner").and_then(Value::as_str).map(String::from);

    let v = json!({

        "url": format!("https://{addr}"),

        "name": checked.name,

        "instance": checked.instance.hash().to_hex(),

        "owner": checked.owner,

        "waiting_for": waiting,

        "yours": mine.as_ref().is_some_and(|m| {

            let me = m.key.to_hex();

            checked.owner.as_deref() == Some(me.as_str()) || waiting.as_deref() == Some(me.as_str())

                || [checked.owner.as_deref(), waiting.as_deref()].into_iter().flatten()

                    .any(|k| spectra_core::identity::KeyId::from_hex(k).is_some_and(|k| spectra_core::keys::identity_in(&spectra_core::keys::default_home(), &k).is_some()))

        }),

        "tls_spki": hex::encode(pin),

    });

    if as_json {

        println!("{v}");

    } else {

        println!("{}", ui::kv("server", ui::path(v["url"].as_str().unwrap_or(""))));

        println!("{}", ui::kv("name", v["name"].as_str().unwrap_or("")));

        println!("{}", ui::kv("instance", ui::hash(v["instance"].as_str().unwrap_or(""))));

        let whose = match (v["owner"].as_str(), v["waiting_for"].as_str()) {

            (Some(o), _) => format!("owned by {}", &o[..12.min(o.len())]),

            (None, Some(w)) => format!("waiting to be claimed by {}", &w[..12.min(w.len())]),

            _ => "no owner".into(),

        };

        println!("{}", ui::kv("owner", whose));

    }

    Ok(0)

}

/// `spectra bridge [--port 0]`: sign as the owner for the program that

/// started it; prints `{ "url", "token" }` and ends with standard input.

pub async fn bridge(ctx: &Ctx, port: u16, owner_home_flag: Option<PathBuf>) -> Result<i32> {

    let home = owner_home(ctx, owner_home_flag);

    let client =

        ctx.owner_client(&home).await?.context("no Spectra to bridge to: spectra init here, or spectra connect https://HOST:7350")?;

    let listener = tokio::net::TcpListener::bind(("127.0.0.1", port)).await.with_context(|| format!("binding 127.0.0.1:{port}"))?;

    let port = listener.local_addr()?.port();

    let token = spectra_mcp::bridge::token();

    println!("{}", json!({ "url": format!("http://127.0.0.1:{port}"), "token": token }));

    use std::io::Write;

    std::io::stdout().flush().ok();

    let app = spectra_mcp::bridge::router(client, token, port);

    axum::serve(listener, app)

        .with_graceful_shutdown(async {

            // Ends when the program that started it closes our input, or on Ctrl-C.

            let stdin = async {

                let mut buf = [0u8; 256];

                let mut input = tokio::io::stdin();

                loop {

                    match tokio::io::AsyncReadExt::read(&mut input, &mut buf).await {

                        Ok(0) | Err(_) => return,

                        Ok(_) => {}

                    }

                }

            };

            tokio::select! {

                _ = stdin => {}

                _ = tokio::signal::ctrl_c() => {}

            }

        })

        .await?;

    Ok(0)

}

//! What the VS Code extension drives (spec §18.1): `spectra status` and

//! `spectra probe` say what is set up and what a server is, and `spectra

//! bridge` signs for the extension, refusing anyone without its token and

//! any web page.

mod common;

use common::{add_agent, hermetic, run, setup, text, Serving};

use serde_json::Value;

use std::io::{BufRead, BufReader, Read, Write};

use std::process::Stdio;

fn http(url: &str, method: &str, path: &str, headers: &[(&str, &str)], body: &str) -> (u16, String) {

    let hp = url.strip_prefix("http://").unwrap();

    let mut s = std::net::TcpStream::connect(hp).unwrap();

    s.set_read_timeout(Some(std::time::Duration::from_secs(10))).unwrap();

    let mut req = format!("{method} {path} HTTP/1.1\r\nconnection: close\r\ncontent-length: {}\r\n", body.len());

    if !headers.iter().any(|(k, _)| k.eq_ignore_ascii_case("host")) {

        req.push_str(&format!("host: {hp}\r\n"));

    }

    for (k, v) in headers {

        req.push_str(&format!("{k}: {v}\r\n"));

    }

    req.push_str("\r\n");

    req.push_str(body);

    s.write_all(req.as_bytes()).unwrap();

    let mut out = String::new();

    let _ = s.read_to_string(&mut out);

    let status = out.split_whitespace().nth(1).and_then(|c| c.parse().ok()).unwrap_or(0);

    (status, out.split_once("\r\n\r\n").map(|x| x.1.to_string()).unwrap_or_default())

}

#[test]

fn status_says_what_is_set_up() {

    let dir = tempfile::tempdir().unwrap();

    let d = dir.path();

    let v: Value = serde_json::from_slice(&run(d, &["status", "--json"]).stdout).unwrap();

    assert!(v["identity"].is_null() && v["server"].is_null() && v["local"]["initialised"] == false, "{v}");

    let made: Value = serde_json::from_slice(&run(d, &["identity", "create", "--name", "Andy McCall", "--json"]).stdout).unwrap();

    assert_eq!(made["key"].as_str().unwrap().len(), 64);

    assert!(run(d, &["init"]).status.success());

    let v: Value = serde_json::from_slice(&run(d, &["status", "--json"]).stdout).unwrap();

    assert_eq!(v["identity"]["name"], "Andy McCall", "init made a successor (it delegates to the instance), so the key moved on");

    assert_ne!(v["identity"]["key"], made["key"]);

    assert_eq!(v["local"]["initialised"], true);

    assert_eq!(v["reachable"], false, "not serving");

}

#[tokio::test]

async fn the_bridge_signs_for_its_holder_only() {

    let dir = setup();

    let d = dir.path();

    add_agent(d, "claude-oxygen", &[]);

    let srv = Serving::start(d);

    let mut child = hermetic(d).args(["bridge"]).stdin(Stdio::piped()).stdout(Stdio::piped()).spawn().unwrap();

    let mut line = String::new();

    BufReader::new(child.stdout.take().unwrap()).read_line(&mut line).unwrap();

    let hello: Value = serde_json::from_str(&line).unwrap();

    let (url, token) = (hello["url"].as_str().unwrap().to_string(), hello["token"].as_str().unwrap().to_string());

    let bearer = format!("Bearer {token}");

    // Signed as the owner, so the API answers as for the human.

    let (status, body) = http(&url, "GET", "/api/v1/brief", &[("authorization", &bearer)], "");

    assert_eq!(status, 200, "{body}");

    assert_eq!(serde_json::from_str::<Value>(&body).unwrap()["actor"], "human");

    let (status, body) = http(

        &url,

        "PUT",

        "/api/v1/briefs",

        &[("authorization", &bearer), ("content-type", "application/json")],

        r#"{"text":"From the editor."}"#,

    );

    assert_eq!(status, 200, "{body}");

    assert!(text(&run(d, &["brief", "show"])).contains("From the editor."));

    // No token, a wrong one, a web page's Origin, or another Host: refused.

    assert_eq!(http(&url, "GET", "/api/v1/brief", &[], "").0, 401);

    assert_eq!(http(&url, "GET", "/api/v1/brief", &[("authorization", "Bearer nope")], "").0, 401);

    assert_eq!(http(&url, "GET", "/api/v1/brief", &[("authorization", &bearer), ("origin", "http://evil.example")], "").0, 403);

    assert_eq!(http(&url, "GET", "/api/v1/brief", &[("authorization", &bearer), ("host", "evil.example")], "").0, 403);

    // It ends when its input closes.

    drop(child.stdin.take());

    let status = tokio::task::spawn_blocking(move || child.wait()).await.unwrap().unwrap();

    assert!(status.success());

    srv.stop();

}

- **Added: `spectra status`, `spectra probe` and `spectra bridge` (#31).** `status [--json]` says what is set up here: your identity, and the Spectra you use and whether it answers. `probe URL [--json]` says what a server is (its name, instance key and owner, or the identity it waits for) without trusting it. `bridge` serves a loopback address that signs requests as you, for a program that cannot sign itself: it prints its address and a one-run token, refuses anything without the token or from a web page, passes streams through, and ends when its input closes. `identity create --json` prints the new key. This is how the VS Code extension sets Spectra up and talks to it.

    /// The key this client signs with, if any.

    pub fn signer(&self) -> Option<&KeyPair> {

        self.signer.as_ref()

    }

pub mod bridge;

- [x] #31 bridge, probe, status — done 2026-11-03: spectra-mcp::bridge (token, loopback Host, no Origin, ends with stdin), spectra status --json, spectra probe --json, identity create --json; tests/bridge.rs and a probe check in tests/connect.rs.

pub fn create(name: &str, contact: &str, home: Option<PathBuf>, as_json: bool) -> Result<i32> {

    if as_json {

        println!("{}", serde_json::json!({ "name": pair.identity.name, "key": pair.key.to_hex(), "home": home.display().to_string() }));

        return Ok(0);

    }

pub mod setup;

    /// What is set up here: your identity, and the Spectra you use

    Status {

        #[arg(long)]

        json: bool,

    },

    /// What a server is (its name and instance key), without trusting it

    Probe {

        /// The server, https://HOST[:PORT]

        url: String,

        #[arg(long)]

        json: bool,

    },

    /// Sign as you for a program that cannot (the VS Code extension): a

    /// loopback proxy that ends when its input closes

    Bridge {

        #[arg(long, default_value_t = 0)]

        port: u16,

        #[arg(long)]

        owner_home: Option<PathBuf>,

    },

        #[arg(long)]

        json: bool,

        Command::Status { json } => runtime()?.block_on(setup::status(&ctx, json)),

        Command::Probe { url, json } => runtime()?.block_on(setup::probe(&url, json)),

        Command::Bridge { port, owner_home } => runtime()?.block_on(setup::bridge(&ctx, port, owner_home)),

                IdentityCmd::Create { name, contact, home, json } => identity::create(&name, &contact, home, json),

    // `probe` says what the server is, without trusting it.

    let p: serde_json::Value = serde_json::from_slice(&run(c, &["probe", &url, "--json"]).stdout).unwrap();

    assert_eq!(p["instance"], instance.key.to_hex());

    assert_eq!(p["waiting_for"], before.key.to_hex());

    assert_eq!(p["yours"], true, "{p}");

    assert!(!c.join("owner/client.toml").exists(), "probing trusts nothing");