spectra connect: trust a server through the owner's delegation, pin it, claim it (#21) eca5af92279b

//! `spectra connect` and the client configuration (spec §8.6): trust a

//! Spectra on another machine because the owner's own identity delegates

//! to its instance key and that key vouches for its certificate; pin the

//! certificate; claim a server set up with `spectra init --owner`.

use super::{identity, ui, Ctx};

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

use oxy_core::identity::Identity;

use serde_json::Value as Json;

use spectra_core::daemon::WireEvent;

use spectra_core::keys::KeyPair;

use spectra_core::principals::{identity_payload, signed_event, DELEGATION_SCOPE};

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

use spectra_mcp::tls::Pinned;

use std::path::{Path, PathBuf};

/// The client configuration: which server, and what to trust there.

#[derive(Clone, Debug)]

pub struct ClientCfg {

    pub server: String,

    pub instance: String,

    pub tls_spki: [u8; 32],

}

impl ClientCfg {

    pub fn endpoint(&self) -> Result<Endpoint> {

        Endpoint::tls(&self.server, self.tls_spki)

    }

}

/// `SPECTRA_SERVER`, else `$XDG_CONFIG_HOME/spectra/client.toml`, else

/// `~/.config/spectra/client.toml`.

pub fn path() -> PathBuf {

    if let Some(p) = std::env::var_os("SPECTRA_SERVER").filter(|p| !p.is_empty()) {

        return PathBuf::from(p);

    }

    config_dir().join("client.toml")

}

fn config_dir() -> PathBuf {

    let base = std::env::var_os("XDG_CONFIG_HOME")

        .filter(|p| !p.is_empty())

        .map(PathBuf::from)

        .or_else(|| std::env::var_os("HOME").map(|h| PathBuf::from(h).join(".config")))

        .unwrap_or_else(|| PathBuf::from("."));

    base.join("spectra")

}

/// The client configuration, if this machine uses a Spectra elsewhere.

pub fn load() -> Result<Option<ClientCfg>> {

    let p = path();

    let text = match std::fs::read_to_string(&p) {

        Ok(t) => t,

        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),

        Err(e) => return Err(e).with_context(|| format!("reading {}", p.display())),

    };

    let t: toml::Table = text.parse().with_context(|| format!("reading {}", p.display()))?;

    let get = |k: &str| t.get(k).and_then(|v| v.as_str()).map(String::from).with_context(|| format!("{} has no {k}", p.display()));

    let spki = hex::decode(get("tls_spki")?).ok().and_then(|b| b.try_into().ok()).with_context(|| format!("{}: tls_spki", p.display()))?;

    Ok(Some(ClientCfg { server: get("server")?, instance: get("instance")?, tls_spki: spki }))

}

fn save(cfg: &ClientCfg) -> Result<PathBuf> {

    let p = path();

    if let Some(dir) = p.parent() {

        std::fs::create_dir_all(dir)?;

    }

    std::fs::write(

        &p,

        format!(

            "# Spectra on another machine (spec §8.6), written by `spectra connect`.\n\nserver = \"{}\"\ninstance = \"{}\"                    # the instance key, delegated by the owner\ntls_spki = \"{}\"   # the certificate the instance key vouches for\n",

            cfg.server,

            cfg.instance,

            hex::encode(cfg.tls_spki)

        ),

    )?;

    Ok(p)

}

/// The key pair of the identity `key` in the owner's home, if it is theirs.

fn own(home: &Path, key: &str) -> Option<KeyPair> {

    let keys = home.join("keys");

    KeyPair::load(&keys.join(format!("{key}.secret")), &keys.join(format!("{key}.identity"))).ok()

}

pub async fn connect(_ctx: &Ctx, url: &str, owner_home: Option<PathBuf>) -> Result<i32> {

    let server = format!("https://{}", host_port(url)?);

    let home = owner_home.unwrap_or_else(oxy_core::repo::default_home);

    let owner = KeyPair::load_home(&home)

        .with_context(|| format!("the owner connects with their own identity: none usable in {} (or --owner-home)", home.display()))?;

    // Who is there, before trusting anything.

    let probe = Pinned::new(None);

    let anon = Client::at(Endpoint::Tls { addr: host_port(url)?, config: probe.client_config()? }, None);

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

    if r.status != 200 {

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

    }

    let answer = r.json()?;

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

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

    let instance_key = checked.instance.hash();

    // Whose it is, or whose it is waiting for.

    let recorded = checked.owner.clone();

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

    match (&recorded, &named) {

        (Some(k), _) if *k != owner.key.to_hex() && own(&home, k).is_none() => {

            bail!("{server} belongs to someone else (owner {})", &k[..12.min(k.len())]);

        }

        (None, Some(k)) if own(&home, k).is_none() => {

            bail!("{server} was set up for {}, which is not an identity in {}", &k[..12.min(k.len())], home.display());

        }

        (None, None) => bail!("{server} has no owner and names none"),

        _ => {}

    }

    // Trust: the owner's own identity delegates to that instance key now.

    if !owner.identity.delegates_to(&instance_key, DELEGATION_SCOPE, spectra_core::ids::now_ms()) {

        let dir = config_dir();

        std::fs::create_dir_all(&dir)?;

        let file = dir.join(format!("{}-instance.identity", safe(&checked.name)));

        std::fs::write(&file, checked.instance.encode())?;

        println!("{} {} {}", ui::caution(), ui::subject(&server), ui::dim("is not yet yours to trust"));

        println!("{}", ui::kv("instance", format!("{}{}{}", checked.name, ui::sep(), ui::hash(instance_key.short(12)))));

        println!("  {} {}", ui::note(), ui::dim("your identity does not delegate to its instance key; if this is your server, run:"));

        println!("    {}", ui::id(format!("oxy identity delegate add {} --scope changes", file.display())));

        println!("  {} {}", ui::note(), ui::dim("then run spectra connect again"));

        return Ok(1);

    }

    let cfg = ClientCfg { server: server.clone(), instance: instance_key.to_hex(), tls_spki: seen };

    let saved = save(&cfg)?;

    let pinned = cfg.endpoint()?;

    // Claim it, or bring it up to the owner's current identity.

    let mut claimed = false;

    match (&recorded, &named) {

        (None, Some(k)) => {

            let named_pair = own(&home, k).expect("checked above");

            let mut events =

                vec![WireEvent::from_new(&signed_event(&named_pair, "human", "identity.owner", identity_payload(&named_pair.identity)))];

            if let Some(e) = identity::rotation(&named_pair.identity, &home)? {

                events.push(WireEvent::from_new(&e));

            }

            let r = Client::at(pinned.clone(), None).send("POST", "/api/v1/claim", &[], serde_json::to_vec(&events)?).await?;

            if r.status != 200 {

                bail!("{server} refused the claim: {}", problem(&r.body));

            }

            claimed = true;

        }

        (Some(k), _) if *k != owner.key.to_hex() => {

            let rec_pair = own(&home, k).expect("checked above");

            let rec_id: Identity = rec_pair.identity.clone();

            if let Some(e) = identity::rotation(&rec_id, &home)? {

                let body = serde_json::to_vec(&vec![WireEvent::from_new(&e)])?;

                let r = Client::at(pinned.clone(), Some(rec_pair)).send("POST", "/api/v1/ledger/events", &[], body).await?;

                if r.status != 200 {

                    bail!("{server} refused the owner's current identity: {}", problem(&r.body));

                }

            }

        }

        _ => {}

    }

    println!("{} {}  {}", ui::done(if claimed { "Claimed" } else { "Connected" }), ui::subject(&checked.name), ui::path(&server));

    println!("{}", ui::kv("owner", format!("{}{}{}", ui::author(&owner.identity.name), ui::sep(), ui::hash(owner.key.short(12)))));

    println!("{}", ui::kv("instance", format!("{}{}", ui::hash(instance_key.short(12)), ui::dim(" (delegated by you)"))));

    println!(

        "{}",

        ui::kv("certificate", format!("{}{}", ui::hash(hex::encode(&seen[..8])), ui::dim(" (pinned; vouched for by the instance key)")))

    );

    println!("{}", ui::kv("config", ui::path(saved.display())));

    Ok(0)

}

fn safe(name: &str) -> String {

    let s: String = name.chars().map(|c| if c.is_ascii_alphanumeric() || c == '-' { c } else { '_' }).collect();

    if s.is_empty() {

        "spectra".into()

    } else {

        s

    }

}

fn problem(body: &[u8]) -> String {

    serde_json::from_slice::<Json>(body)

        .ok()

        .and_then(|v| v.get("detail").or_else(|| v.get("title")).and_then(Json::as_str).map(String::from))

        .unwrap_or_else(|| String::from_utf8_lossy(body).into_owned())

}

//! `spectra connect` (spec §8.6, spectra#21): a workstation trusts a server

//! because the owner delegates to its instance key and that key vouches for

//! its certificate; it claims a server set up with `init --owner`, even

//! though delegating changed the owner's KeyId; a new certificate is

//! refused until connect runs again; someone else's server is refused.

mod common;

use common::{delegate, hermetic, run, text, Serving};

use spectra_core::keys::KeyPair;

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

use spectra_mcp::tls::Pinned;

use std::path::Path;

/// A server in `s` set up for the owner whose home is `owner_home`.

fn server_for(s: &Path, owner_home: &Path) -> (Serving, u16) {

    let owner = KeyPair::load_home(owner_home).unwrap();

    let o = run(s, &["init", "--owner", &owner.key.to_hex(), "--name", "earth"]);

    assert!(o.status.success(), "{}", text(&o));

    Serving::start_tls(s)

}

async fn instance_owner(port: u16) -> serde_json::Value {

    let p = Pinned::new(None);

    let c = Client::at(Endpoint::Tls { addr: format!("127.0.0.1:{port}"), config: p.client_config().unwrap() }, None);

    c.send("GET", "/api/v1/instance", &[], vec![]).await.unwrap().json().unwrap()["owner"].clone()

}

#[tokio::test]

async fn the_owner_connects_delegates_and_claims() {

    let (sd, cd) = (tempfile::tempdir().unwrap(), tempfile::tempdir().unwrap());

    let (s, c) = (sd.path(), cd.path());

    KeyPair::create_home(&c.join("owner"), "Andy McCall", "").unwrap();

    let (srv, port) = server_for(s, &c.join("owner"));

    let url = format!("https://127.0.0.1:{port}");

    // First contact: not yet delegated, so not trusted; told what to run.

    let o = run(c, &["connect", &url]);

    assert_eq!(o.status.code(), Some(1), "{}", text(&o));

    assert!(text(&o).contains("oxy identity delegate add"), "{}", text(&o));

    let saved = c.join(".config/spectra/earth-instance.identity");

    assert!(saved.exists(), "the instance's public identity is saved to delegate to");

    assert!(!c.join(".config/spectra/client.toml").exists(), "nothing trusted yet");

    // The owner delegates (which gives their identity a new KeyId) ...

    let instance = KeyPair::instance(&s.join("data"), "earth").unwrap();

    assert_eq!(oxy_core::identity::Identity::decode(&std::fs::read(&saved).unwrap()).unwrap().hash(), instance.key);

    delegate(&c.join("owner"), &instance);

    let current = KeyPair::load_home(&c.join("owner")).unwrap();

    // ... and connects again: trusted, pinned, and claimed as theirs.

    let o = run(c, &["connect", &url]);

    assert!(o.status.success(), "{}", text(&o));

    assert!(text(&o).contains("Claimed"), "{}", text(&o));

    let cfg = std::fs::read_to_string(c.join(".config/spectra/client.toml")).unwrap();

    assert!(cfg.contains(&instance.key.to_hex()) && cfg.contains("tls_spki"), "{cfg}");

    assert_eq!(instance_owner(port).await, current.key.to_hex(), "recorded at the owner's current identity");

    // Again: nothing to claim, still trusted.

    let o = run(c, &["connect", &url]);

    assert!(o.status.success(), "{}", text(&o));

    assert!(text(&o).contains("Connected"), "{}", text(&o));

    srv.stop();

    // A new certificate (the old one lost) is refused on the old pin ...

    std::fs::remove_file(s.join("data/keys/tls.crt")).unwrap();

    std::fs::remove_file(s.join("data/keys/tls.key")).unwrap();

    let (srv, port) = Serving::start_tls(s);

    let url = format!("https://127.0.0.1:{port}");

    let cfg = std::fs::read_to_string(c.join(".config/spectra/client.toml")).unwrap();

    let old_pin: [u8; 32] =

        hex::decode(cfg.lines().find(|l| l.starts_with("tls_spki")).unwrap().split('"').nth(1).unwrap()).unwrap().try_into().unwrap();

    let pinned = Client::at(Endpoint::tls(&url, old_pin).unwrap(), None);

    assert!(pinned.send("GET", "/api/v1/instance", &[], vec![]).await.is_err());

    // ... until connect checks that the same instance key vouches for it.

    let o = run(c, &["connect", &url]);

    assert!(o.status.success(), "{}", text(&o));

    let cfg2 = std::fs::read_to_string(c.join(".config/spectra/client.toml")).unwrap();

    assert_ne!(cfg, cfg2, "re-pinned");

    srv.stop();

    let o = hermetic(s).args(["admin", "verify"]).output().unwrap();

    assert!(o.status.success(), "{}", text(&o));

}

#[test]

fn someone_elses_server_is_refused() {

    let (sd, cd, md) = (tempfile::tempdir().unwrap(), tempfile::tempdir().unwrap(), tempfile::tempdir().unwrap());

    let (s, c, m) = (sd.path(), cd.path(), md.path());

    KeyPair::create_home(&c.join("owner"), "Andy McCall", "").unwrap();

    KeyPair::create_home(&m.join("owner"), "Mallory", "").unwrap();

    let (srv, port) = server_for(s, &m.join("owner"));

    let o = run(c, &["connect", &format!("https://127.0.0.1:{port}")]);

    assert!(!o.status.success());

    assert!(text(&o).contains("was set up for"), "{}", text(&o));

    srv.stop();

}

- **Added: `spectra connect https://HOST[:PORT]` (#21).** Uses a Spectra on another machine. It trusts the server only when your own identity delegates to its instance key and that key vouches for the certificate it presents; until you have delegated, it saves the instance's public identity and prints the `oxy identity delegate add` to run. Then it pins the certificate in `~/.config/spectra/client.toml` (or `SPECTRA_SERVER`), claims a server set up with `spectra init --owner`, and brings the server up to your current identity. A certificate that changes is refused until `connect` checks it again. The stdio shim uses the configured server (with `--home`).

    /// (spec §8.6): the named identity, signed by itself over its payload,

    /// then any successors up to the owner's current identity, each a

    /// rotation as `identity refresh` makes. Accepted only while no owner

    /// is recorded, and only from the key init named.

    pub async fn claim(&self, events: Vec<WireEvent>) -> Result<Vec<u64>> {

        let mut out = Vec::new();

        for (i, w) in events.into_iter().enumerate() {

            let n = w.into_new_event()?;

            let want = if i == 0 { "identity.owner" } else { "identity.rotated" };

            if n.kind != want || n.actor != "human" {

                bail!("a claim is the owner's identity.owner, then their rotations");

            }

            if i == 0 {

                let key = n.payload.get("key").and_then(|k| k.as_str()).unwrap_or("").to_ascii_lowercase();

                if key != named || n.auth.key.map(hex::encode) != Some(named.clone()) {

                    bail!("this Spectra was set up for another owner");

                }

            }

            principals.check(&probe_event(&n)).map_err(|why| anyhow::anyhow!("refused the claim: {why}"))?;

            out.push(n);

        }

        if out.is_empty() {

            bail!("an empty claim");

        let appended = self.ledger.append(out).await?;

        Ok(appended.iter().map(|e| e.seq).collect())

    let owner_missing = owner.is_none();

        // Until claimed: the KeyId `spectra init --owner` named.

        "named_owner": if owner_missing { state.daemon.named_owner() } else { None },

    let events: Vec<WireEvent> = match serde_json::from_slice(&body) {

        Err(e) => return (StatusCode::BAD_REQUEST, axum::Json(json!({ "title": format!("not a list of events: {e}") }))).into_response(),

    match state.daemon.claim(events).await {

        Ok(seqs) => axum::Json(json!({ "seqs": seqs })).into_response(),

**Remote setup.** `spectra init --owner KEYID` on the server makes the instance key and the ledger without the owner's secret key: the ledger starts with `identity.instance`, and the daemon serves `/api/v1/instance` and nothing else until the owner claims it. The first `spectra connect` from the owner claims it: `identity.owner` for the identity `--owner` named, signed by it over its payload as every CLI event is (§9.5), followed by the `identity.rotated` that brings it to the owner's current identity (delegating to the instance key makes a new one). The daemon accepts the claim only while it has no owner and only for the named key, and `/api/v1/instance` says which key it waits for. Until then every other request is refused with the reason "this Spectra has no owner yet".

    rotation(&recorded, home)

}

/// The `identity.rotated` that takes `recorded` to the owner's current

/// identity in `home`, with the identities between, or none if it is

/// current.

pub fn rotation(recorded: &Identity, home: &Path) -> Result<Option<spectra_core::event::NewEvent>> {

        None if ctx.remote()?.is_some() => {

            bail!("with Spectra on another machine, name the agent's home: spectra mcp --agent {agent} --home DIR")

        }

    let client = Arc::new(Client::at(ctx.endpoint()?, Some(key)));

pub mod connect;

    /// Use a Spectra on another machine: trust it through your delegation to

    /// its instance key, pin its certificate, and claim it if it is new

    Connect {

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

        url: String,

        /// The owner's OXY_HOME (default: $OXY_HOME, else ~/.config/oxy)

        #[arg(long)]

        owner_home: Option<PathBuf>,

    },

    }

    /// The Spectra on another machine this one uses, if any (spec §8.6).

    pub fn remote(&self) -> Result<Option<connect::ClientCfg>> {

        connect::load()

    }

    /// Where the daemon is: the configured server, else the local socket.

    pub fn endpoint(&self) -> Result<spectra_mcp::client::Endpoint> {

        Ok(match self.remote()? {

            Some(c) => c.endpoint()?,

            None => spectra_mcp::client::Endpoint::Unix(self.socket()),

        })

        Command::Connect { url, owner_home } => runtime()?.block_on(connect::connect(&ctx, &url, owner_home)),

    serde_json::to_vec(&vec![WireEvent::from_new(&e)]).unwrap()

    assert_eq!(info["named_owner"], owner.key.to_hex(), "says whose it waits for");

    let r = anon.send("POST", "/api/v1/claim", &[], serde_json::to_vec(&vec![WireEvent::from_new(&forged)]).unwrap()).await.unwrap();