Serve other machines over TLS, trusted through the instance key (#20) b576d05cf862

//! The instance's word for its TLS certificate (spec §8.6): the

//! `instance.tls` event the daemon signs with the instance key, and the

//! check a client makes of it.

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

use oxy_core::identity::Identity;

use serde_json::{json, Value as Json};

use spectra_core::event::Event;

use spectra_core::keys::KeyPair;

use spectra_core::ledger::Ledger;

use spectra_core::proof::Proof;

/// The latest `instance.tls` event, if any.

pub async fn latest_tls(ledger: &Ledger) -> Result<Option<Event>> {

    let mut last = None;

    let mut from = 1;

    loop {

        let rows = ledger.events_of_kinds(from, &["instance.tls"], 1000).await?;

        match rows.last() {

            Some(e) => {

                from = e.seq + 1;

                last = Some(e.clone());

            }

            None => return Ok(last),

        }

    }

}

/// Record the certificate's pin, signed by the instance key, unless the

/// latest record already names it.

pub async fn record_tls(ledger: &Ledger, instance: &KeyPair, spki: &[u8; 32], names: &[String]) -> Result<bool> {

    let hex_spki = hex::encode(spki);

    if let Some(e) = latest_tls(ledger).await? {

        if e.json().get("spki_sha256").and_then(Json::as_str) == Some(hex_spki.as_str()) {

            return Ok(false);

        }

    }

    let payload = json!({ "spki_sha256": hex_spki, "names": names });

    ledger.append_one(spectra_core::principals::signed_event(instance, "system", "instance.tls", payload)).await?;

    Ok(true)

}

/// What `GET /api/v1/instance` told a client, checked.

#[derive(Clone, Debug)]

pub struct Checked {

    pub name: String,

    pub instance: Identity,

    pub owner: Option<String>,

    /// The certificate the instance key vouches for.

    pub spki_sha256: [u8; 32],

}

/// Check `/api/v1/instance`'s answer: the identity is whole, and the

/// instance key signed an `instance.tls` naming the certificate `seen`.

pub fn check(answer: &Json, seen: &[u8; 32]) -> Result<Checked> {

    let ip = answer.get("instance").context("no instance in the answer")?;

    let bytes = ip.get("identity").and_then(Json::as_str).and_then(|h| hex::decode(h).ok()).context("no instance identity")?;

    let instance = Identity::decode(&bytes).map_err(|e| anyhow::anyhow!("malformed instance identity: {e}"))?;

    let tls = answer.get("tls").filter(|t| !t.is_null()).context("the server has not signed a TLS certificate")?;

    let payload = tls.get("payload").context("no TLS payload")?;

    let proof = tls.get("proof").and_then(Json::as_str).and_then(|h| hex::decode(h).ok()).context("no TLS proof")?;

    let proof = Proof::decode(&proof).map_err(|e| anyhow::anyhow!(e))?;

    if proof.key() != instance.hash().0 || proof.method != "cli" {

        bail!("the certificate is not vouched for by the instance key");

    }

    proof

        .verify(&instance, Some(&spectra_core::event::canonical_json(payload)))

        .map_err(|e| anyhow::anyhow!("the instance's signature on its certificate: {e}"))?;

    let named = payload.get("spki_sha256").and_then(Json::as_str).context("no pin in the TLS record")?;

    if named != hex::encode(seen) {

        bail!("the server presented a certificate its instance key did not sign");

    }

    Ok(Checked {

        name: answer.get("name").and_then(Json::as_str).unwrap_or("").to_string(),

        instance,

        owner: answer.get("owner").and_then(Json::as_str).map(String::from),

        spki_sha256: *seen,

    })

}

//! TLS for client and server (spec §8.6). The server makes a certificate

//! of its own; the instance key vouches for it with an `instance.tls`

//! event; a client trusts that one certificate, pinned by the SHA-256 of

//! its SubjectPublicKeyInfo, and never a certificate authority.

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

use rustls::client::danger::{HandshakeSignatureValid, ServerCertVerified, ServerCertVerifier};

use rustls::pki_types::{CertificateDer, PrivateKeyDer, ServerName, UnixTime};

use rustls::{DigitallySignedStruct, SignatureScheme};

use std::net::SocketAddr;

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

use std::sync::{Arc, Mutex};

use std::time::Duration;

use tokio::net::{TcpListener, TcpStream};

/// The crypto provider: ring, as OxygenHub's.

pub fn provider() -> Arc<rustls::crypto::CryptoProvider> {

    Arc::new(rustls::crypto::ring::default_provider())

}

/// SHA-256 of a certificate's SubjectPublicKeyInfo: what a client pins.

pub fn spki_sha256(cert_der: &[u8]) -> Result<[u8; 32]> {

    let (_, cert) = x509_parser::parse_x509_certificate(cert_der).map_err(|e| anyhow::anyhow!("not an X.509 certificate: {e}"))?;

    let d = ring::digest::digest(&ring::digest::SHA256, cert.public_key().raw);

    Ok(d.as_ref().try_into().expect("SHA-256 is 32 bytes"))

}

/// Where a server's certificate comes from (`[server] tls`).

#[derive(Clone, Debug)]

pub enum CertSource {

    /// Made on first start in `<data>/keys/tls.{key,crt}`, naming these names.

    Own { names: Vec<String> },

    /// Files from elsewhere (PEM).

    Files { cert: PathBuf, key: PathBuf },

}

/// A server's TLS: its rustls configuration and the certificate's pin.

pub struct ServerTls {

    pub config: Arc<rustls::ServerConfig>,

    pub spki_sha256: [u8; 32],

    pub names: Vec<String>,

}

impl ServerTls {

    pub fn load(data: &Path, source: &CertSource) -> Result<ServerTls> {

        let (cert_pem, key_pem, names) = match source {

            CertSource::Own { names } => {

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

                let (crt, key) = (keys.join("tls.crt"), keys.join("tls.key"));

                if !crt.exists() || !key.exists() {

                    make_own(&crt, &key, names)?;

                }

                (std::fs::read_to_string(&crt)?, std::fs::read_to_string(&key)?, names.clone())

            }

            CertSource::Files { cert, key } => (

                std::fs::read_to_string(cert).with_context(|| format!("reading {}", cert.display()))?,

                std::fs::read_to_string(key).with_context(|| format!("reading {}", key.display()))?,

                vec![],

            ),

        };

        let chain: Vec<CertificateDer<'static>> = rustls_pemfile::certs(&mut cert_pem.as_bytes()).collect::<Result<_, _>>()?;

        let leaf = chain.first().context("no certificate in the PEM")?;

        let spki = spki_sha256(leaf)?;

        let key: PrivateKeyDer<'static> = rustls_pemfile::private_key(&mut key_pem.as_bytes())?.context("no private key in the PEM")?;

        let mut config = rustls::ServerConfig::builder_with_provider(provider())

            .with_safe_default_protocol_versions()?

            .with_no_client_auth()

            .with_single_cert(chain, key)?;

        config.alpn_protocols = vec![b"http/1.1".to_vec()];

        Ok(ServerTls { config: Arc::new(config), spki_sha256: spki, names })

    }

}

fn make_own(crt: &Path, key: &Path, names: &[String]) -> Result<()> {

    if names.is_empty() {

        bail!("a certificate needs at least one name ([server] names)");

    }

    let ck = rcgen::generate_simple_self_signed(names.to_vec())?;

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

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

    }

    write_private(key, ck.signing_key.serialize_pem().as_bytes())?;

    std::fs::write(crt, ck.cert.pem())?;

    Ok(())

}

fn write_private(path: &Path, bytes: &[u8]) -> Result<()> {

    #[cfg(unix)]

    {

        use std::io::Write;

        use std::os::unix::fs::OpenOptionsExt;

        let mut f = std::fs::OpenOptions::new().write(true).create(true).truncate(true).mode(0o600).open(path)?;

        f.write_all(bytes)?;

        Ok(())

    }

    #[cfg(not(unix))]

    {

        std::fs::write(path, bytes)?;

        Ok(())

    }

}

/// A TCP listener that hands axum connections once their TLS handshake is

/// done; handshakes run concurrently, so a slow one holds up nobody.

pub struct TlsListener {

    rx: tokio::sync::mpsc::Receiver<(tokio_rustls::server::TlsStream<TcpStream>, SocketAddr)>,

    addr: SocketAddr,

}

impl TlsListener {

    pub fn new(tcp: TcpListener, config: Arc<rustls::ServerConfig>) -> Result<TlsListener> {

        let addr = tcp.local_addr()?;

        let acceptor = tokio_rustls::TlsAcceptor::from(config);

        let (tx, rx) = tokio::sync::mpsc::channel(64);

        tokio::spawn(async move {

            loop {

                let (stream, peer) = match tcp.accept().await {

                    Ok(x) => x,

                    Err(e) => {

                        tracing::warn!("accept: {e}");

                        tokio::time::sleep(Duration::from_millis(50)).await;

                        continue;

                    }

                };

                let (acceptor, out) = (acceptor.clone(), tx.clone());

                tokio::spawn(async move {

                    match tokio::time::timeout(Duration::from_secs(10), acceptor.accept(stream)).await {

                        Ok(Ok(tls)) => {

                            let _ = out.send((tls, peer)).await;

                        }

                        Ok(Err(e)) => tracing::debug!(%peer, "TLS handshake failed: {e}"),

                        Err(_) => tracing::debug!(%peer, "TLS handshake timed out"),

                    }

                });

                if tx.is_closed() {

                    return;

                }

            }

        });

        Ok(TlsListener { rx, addr })

    }

}

impl axum::serve::Listener for TlsListener {

    type Io = tokio_rustls::server::TlsStream<TcpStream>;

    type Addr = SocketAddr;

    async fn accept(&mut self) -> (Self::Io, Self::Addr) {

        match self.rx.recv().await {

            Some(x) => x,

            // The accept loop never ends while we hold the receiver.

            None => std::future::pending().await,

        }

    }

    fn local_addr(&self) -> std::io::Result<Self::Addr> {

        Ok(self.addr)

    }

}

/// A server certificate verifier that accepts exactly one public key, or,

/// with no pin, any key, remembering it for the caller to check

/// (`spectra connect`). The handshake's signature is always checked, so

/// the server must hold the certificate's private key.

#[derive(Debug)]

pub struct Pinned {

    pin: Option<[u8; 32]>,

    seen: Mutex<Option<(Vec<u8>, [u8; 32])>>,

    algs: rustls::crypto::WebPkiSupportedAlgorithms,

}

impl Pinned {

    pub fn new(pin: Option<[u8; 32]>) -> Arc<Pinned> {

        Arc::new(Pinned { pin, seen: Mutex::new(None), algs: provider().signature_verification_algorithms })

    }

    /// The certificate (DER) and its pin from the last handshake.

    pub fn seen(&self) -> Option<(Vec<u8>, [u8; 32])> {

        self.seen.lock().unwrap().clone()

    }

    pub fn client_config(self: &Arc<Self>) -> Result<Arc<rustls::ClientConfig>> {

        let mut c = rustls::ClientConfig::builder_with_provider(provider())

            .with_safe_default_protocol_versions()?

            .dangerous()

            .with_custom_certificate_verifier(self.clone())

            .with_no_client_auth();

        c.alpn_protocols = vec![b"http/1.1".to_vec()];

        Ok(Arc::new(c))

    }

}

impl ServerCertVerifier for Pinned {

    fn verify_server_cert(

        &self,

        end_entity: &CertificateDer<'_>,

        _intermediates: &[CertificateDer<'_>],

        _server_name: &ServerName<'_>,

        _ocsp: &[u8],

        _now: UnixTime,

    ) -> Result<ServerCertVerified, rustls::Error> {

        let spki = spki_sha256(end_entity).map_err(|_| rustls::Error::InvalidCertificate(rustls::CertificateError::BadEncoding))?;

        *self.seen.lock().unwrap() = Some((end_entity.to_vec(), spki));

        match self.pin {

            Some(pin) if pin != spki => Err(rustls::Error::InvalidCertificate(rustls::CertificateError::ApplicationVerificationFailure)),

            _ => Ok(ServerCertVerified::assertion()),

        }

    }

    fn verify_tls12_signature(

        &self,

        message: &[u8],

        cert: &CertificateDer<'_>,

        dss: &DigitallySignedStruct,

    ) -> Result<HandshakeSignatureValid, rustls::Error> {

        rustls::crypto::verify_tls12_signature(message, cert, dss, &self.algs)

    }

    fn verify_tls13_signature(

        &self,

        message: &[u8],

        cert: &CertificateDer<'_>,

        dss: &DigitallySignedStruct,

    ) -> Result<HandshakeSignatureValid, rustls::Error> {

        rustls::crypto::verify_tls13_signature(message, cert, dss, &self.algs)

    }

    fn supported_verify_schemes(&self) -> Vec<SignatureScheme> {

        self.algs.supported_schemes()

    }

}

/// Connect to `host:port` over TLS with `config`.

pub async fn connect(addr: &str, config: Arc<rustls::ClientConfig>) -> Result<tokio_rustls::client::TlsStream<TcpStream>> {

    let tcp = tokio::time::timeout(Duration::from_secs(10), TcpStream::connect(addr))

        .await

        .with_context(|| format!("connecting to {addr}: timed out"))?

        .with_context(|| format!("connecting to {addr}"))?;

    tcp.set_nodelay(true).ok();

    let host = addr.rsplit_once(':').map(|(h, _)| h.trim_start_matches('[').trim_end_matches(']')).unwrap_or(addr);

    let name = ServerName::try_from(host.to_string()).unwrap_or_else(|_| ServerName::try_from("spectra").unwrap());

    let tls = tokio_rustls::TlsConnector::from(config).connect(name, tcp).await.with_context(|| format!("TLS with {addr}"))?;

    Ok(tls)

}

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    fn own_certificate_is_made_once_and_pinned() {

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

        let src = CertSource::Own { names: vec!["localhost".into()] };

        let a = ServerTls::load(dir.path(), &src).unwrap();

        let b = ServerTls::load(dir.path(), &src).unwrap();

        assert_eq!(a.spki_sha256, b.spki_sha256, "the certificate is kept between starts");

        #[cfg(unix)]

        {

            use std::os::unix::fs::PermissionsExt;

            let mode = std::fs::metadata(dir.path().join("keys/tls.key")).unwrap().permissions().mode();

            assert_eq!(mode & 0o777, 0o600);

        }

    }

}

//! The daemon over TLS (spec §8.6, spectra#20): a certificate of its own,

//! vouched for by the instance key; a client that trusts that, and only

//! that; signed MCP calls over the network; no uid-bound agent over TCP.

mod common;

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

use serde_json::json;

use spectra_core::keys::KeyPair;

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

use spectra_mcp::tls::Pinned;

fn unpinned(port: u16) -> (Client, std::sync::Arc<Pinned>) {

    let v = Pinned::new(None);

    let e = Endpoint::Tls { addr: format!("127.0.0.1:{port}"), config: v.client_config().unwrap() };

    (Client::at(e, None), v)

}

#[tokio::test]

async fn a_client_trusts_the_certificate_the_instance_key_signed() {

    let dir = setup();

    let d = dir.path();

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

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

    // Unauthenticated, before trusting anything: who is this?

    let (c, seen) = unpinned(port);

    let r = c.send("GET", "/api/v1/instance", &[], vec![]).await.unwrap();

    assert_eq!(r.status, 200, "{}", String::from_utf8_lossy(&r.body));

    let answer = r.json().unwrap();

    let (_, pin) = seen.seen().expect("the handshake showed a certificate");

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

    let instance = KeyPair::instance(&d.join("data"), "spectra").unwrap();

    assert_eq!(checked.instance.hash(), instance.key, "the instance key vouches for the certificate");

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

    assert_eq!(checked.owner.as_deref(), Some(owner.key.to_hex().as_str()));

    // A certificate the instance did not sign is not accepted.

    assert!(spectra_mcp::instance::check(&answer, &[7; 32]).is_err());

    // Pinned, an agent's signed MCP call works over the network.

    let c = Client::at(Endpoint::tls(&format!("https://127.0.0.1:{port}"), pin).unwrap(), Some(agent));

    let call = json!({ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "agents", "arguments": {},

        "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28" } } });

    let r = c.mcp("2026-07-28", &call).await.unwrap();

    let v = rpc_result(&r).unwrap();

    assert_eq!(v["result"]["isError"], false, "{v}");

    assert!(v["result"]["content"][0]["text"].as_str().unwrap().contains("claude-oxygen · Andy McCall's agent"));

    // Any other certificate is refused at the handshake.

    let wrong = Client::at(Endpoint::tls(&format!("https://127.0.0.1:{port}"), [0; 32]).unwrap(), None);

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

    srv.stop();

    // The certificate is kept, and recorded once, across restarts; verify

    // checks the instance's signature on it.

    let (srv, port2) = Serving::start_tls(d);

    let (c, seen) = unpinned(port2);

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

    assert_eq!(seen.seen().unwrap().1, pin);

    srv.stop();

    let o = run(d, &["admin", "verify"]);

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

}

#[tokio::test]

async fn an_agent_bound_to_a_uid_is_refused_over_the_network() {

    let dir = setup();

    let d = dir.path();

    let uid = unsafe { libc::getuid() }.to_string();

    let bound = add_agent(d, "bound", &["--uid", &uid]);

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

    let (probe, seen) = unpinned(port);

    probe.send("GET", "/api/v1/instance", &[], vec![]).await.unwrap();

    let pin = seen.seen().unwrap().1;

    let c = Client::at(Endpoint::tls(&format!("https://127.0.0.1:{port}"), pin).unwrap(), Some(bound.clone()));

    let r = c.mcp("2026-07-28", &json!({ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} })).await.unwrap();

    assert_eq!(r.status, 401);

    assert!(String::from_utf8_lossy(&r.body).contains("must come over the Unix socket"), "{}", String::from_utf8_lossy(&r.body));

    // Over the socket, from its own uid, it is welcome.

    let local = Client::new(&srv.socket, Some(bound));

    let r = local.mcp("2026-07-28", &json!({ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} })).await.unwrap();

    assert_eq!(r.status, 200);

    srv.stop();

    let o = run(d, &["admin", "verify"]);

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

    let log = spectra_core::ledger::Ledger::open_read_only(&d.join("data/spectra.db")).await.unwrap();

    let g = log.events_of_kinds(1, &["guard.impersonation"], 10).await.unwrap();

    assert_eq!(g.len(), 1, "recorded as an impersonation attempt");

}

#[test]

fn plain_http_beyond_loopback_is_refused() {

    let dir = setup();

    let o = run(dir.path(), &["serve", "--bind", "0.0.0.0:0", "--tls", "off"]);

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

    assert!(text(&o).contains("over TLS only"), "{}", text(&o));

}

- **Added: serving other machines over TLS (#20).** With `[server] bind` beyond loopback (or `spectra serve --bind ADDR`), the daemon serves HTTPS with a certificate of its own, made on first start and kept in `keys/tls.{crt,key}`, or with `[server] tls = { cert, key }`. No certificate authority is involved: the instance key vouches for the certificate with a signed `instance.tls` event, and `GET /api/v1/instance` tells a client, before it trusts anything, who the instance is, whose it is and which certificate it signed. Clients pin that one certificate and check the server's handshake signature. An agent bound to a Unix user is refused over TCP and recorded as `guard.impersonation`, since a network connection has no uid to check.

name = "asn1-rs"

version = "0.7.2"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "b7f43a50ac4fdca5df8e885c21b835997f0a1cdee65494a6847694a98652d9d8"

dependencies = [

 "asn1-rs-derive",

 "asn1-rs-impl",

 "displaydoc",

 "nom",

 "num-traits",

 "rusticata-macros",

 "thiserror 2.0.21",

 "time",

]

[[package]]

name = "asn1-rs-derive"

version = "0.6.0"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "3109e49b1e4909e9db6515a30c633684d68cdeaa252f215214cb4fa1a5bfee2c"

dependencies = [

 "proc-macro2",

 "quote",

 "syn 2.0.119",

 "synstructure 0.13.2",

]

[[package]]

name = "asn1-rs-impl"

version = "0.2.0"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "7b18050c2cd6fe86c3a76584ef5e0baf286d038cda203eb6223df2cc413565f7"

dependencies = [

 "proc-macro2",

 "quote",

 "syn 2.0.119",

]

[[package]]

name = "base64"

version = "0.23.1"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"

[[package]]

 "bit-vec 0.8.0",

name = "bit-vec"

version = "0.9.1"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "b71798fca2c1fe1086445a7258a4bc81e6e49dcd24c8d0dd9a1e57395b603f51"

dependencies = [

 "serde",

]

[[package]]

[[package]]

name = "data-encoding"

version = "2.11.1"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "4583a4551df46e2792f82ceeac45e850d2e2d5debba0b91f102385cda5b11f06"

]

[[package]]

name = "der-parser"

version = "10.0.0"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "07da5016415d5a3c4dd39b11ed26f915f52fc4e0dc197d87908bc916e51bc1a6"

dependencies = [

 "asn1-rs",

 "displaydoc",

 "nom",

 "num-bigint",

 "num-traits",

 "rusticata-macros",

[[package]]

name = "deranged"

version = "0.5.8"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"

 "windows-sys 0.59.0",

[[package]]

name = "minimal-lexical"

version = "0.2.1"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"

name = "nom"

version = "7.1.3"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"

dependencies = [

 "memchr",

 "minimal-lexical",

]

[[package]]

 "windows-sys 0.59.0",

name = "num-bigint"

version = "0.4.8"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "c89e69e7e0f03bea5ef08013795c25018e101932225a656383bd384495ecc367"

dependencies = [

 "num-integer",

 "num-traits",

]

[[package]]

name = "num-conv"

version = "0.2.2"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"

[[package]]

[[package]]

name = "oid-registry"

version = "0.8.1"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "12f40cff3dde1b6087cc5d5f5d4d65712f34016a03ed60e9c08dcc392736b5b7"

dependencies = [

 "asn1-rs",

]

]

[[package]]

name = "pem"

version = "4.0.0"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "d354a98a3d1251555de99e8fdd8afda05573c31b82f59063a7b0a29b5527f120"

dependencies = [

 "base64 0.23.1",

 "serde_core",

[[package]]

name = "powerfmt"

version = "0.2.1"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "4a6394b9e965e73d0a289ee54f589087e2c676aedf60885baf52c76b771e4958"

 "bit-vec 0.8.0",

]

[[package]]

name = "rcgen"

version = "0.14.10"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "8774e05a7d0de114588e6a28fe7e71694b82614ed569d86d8b389dfbc98b8ad8"

dependencies = [

 "pem",

 "ring",

 "rustls-pki-types",

 "time",

 "x509-parser",

 "yasna",

name = "rusticata-macros"

version = "4.1.0"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "faf0c4a6ece9950b9abdb62b1cfcf2a68b3b67a10ba445b3bb85be2a293d0632"

dependencies = [

 "nom",

]

[[package]]

 "windows-sys 0.59.0",

 "rcgen",

 "ring",

 "rustls",

 "rustls-pemfile",

 "tokio-rustls",

 "x509-parser",

 "base64 0.22.1",

 "base64 0.22.1",

 "base64 0.22.1",

version = "0.13.2"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"

dependencies = [

 "proc-macro2",

 "quote",

 "syn 2.0.119",

]

[[package]]

name = "synstructure"

 "getrandom 0.3.4",

 "windows-sys 0.59.0",

]

[[package]]

name = "time"

version = "0.3.55"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "cdb87b95ec50ddfa440816d227a17b2ccbdda963a316a727fda0fc4334f7d134"

dependencies = [

 "deranged",

 "num-conv",

 "powerfmt",

 "serde_core",

 "time-core",

 "time-macros",

]

[[package]]

name = "time-core"

version = "0.1.9"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109"

[[package]]

name = "time-macros"

version = "0.2.32"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "7e689342a48d2ea927c87ea50cabf8594854bf940e9310208848d680d668ed85"

dependencies = [

 "num-conv",

 "time-core",

name = "tokio-rustls"

version = "0.26.5"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "b0c85f2c3ef0b1cd58b36682f4b17aaa995f0e5db534d85692b4903abce21f67"

dependencies = [

 "rustls",

 "tokio",

]

[[package]]

 "base64 0.22.1",

 "windows-sys 0.48.0",

[[package]]

name = "x509-parser"

version = "0.18.1"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "d43b0f71ce057da06bc0851b23ee24f3f86190b07203dd8f567d0b706a185202"

dependencies = [

 "asn1-rs",

 "data-encoding",

 "der-parser",

 "lazy_static",

 "nom",

 "oid-registry",

 "ring",

 "rusticata-macros",

 "thiserror 2.0.21",

 "time",

]

[[package]]

name = "yasna"

version = "0.6.0"

source = "registry+https://github.com/rust-lang/crates.io-index"

checksum = "b5f6765e852b9b4dc8e2a76843e4d64d1cea8e79bcde0b6901aea8e7c7f08282"

dependencies = [

 "bit-vec 0.9.1",

 "time",

]

 "synstructure 0.14.0",

 "synstructure 0.14.0",

    /// The key is bound to a Unix user but came over TCP, where there is no

    /// peer uid to check (spec §8.6; logged as `guard.impersonation`).

    #[error("agent {agent}'s key is bound to uid {bound} and must come over the Unix socket, not the network")]

    BoundOverNetwork { agent: String, bound: u32 },

                (Some(bound), None) => return Err(Refusal::BoundOverNetwork { agent: name.clone(), bound: *bound }),

            Err(Refusal::BoundOverNetwork { agent, bound }) => {

                let e = NewEvent::system(

                    "guard.impersonation",

                    serde_json::json!({ "agent": agent, "bound_uid": bound, "from_uid": null, "over": "tcp", "method": method }),

                )

                .subject(agent.clone());

                let _ = self.ledger.append_one(e).await;

                tracing::warn!(agent, bound, "a uid-bound key used over the network");

            }

# TLS between machines (spec §8.6), as OxygenHub has it: rustls on ring.

rustls = { version = "0.23", default-features = false, features = ["ring", "std", "tls12"] }

tokio-rustls = { version = "0.26", default-features = false, features = ["ring", "tls12"] }

rustls-pemfile = "2"

rcgen = "0.14"

x509-parser = "0.18"

ring = "0.17"

/// Where the daemon is: its Unix socket, or a server over TLS with a

/// pinned certificate (spec §8.6).

#[derive(Clone)]

pub enum Endpoint {

    Unix(PathBuf),

    Tls { addr: String, config: std::sync::Arc<rustls::ClientConfig> },

}

impl Endpoint {

    /// `https://HOST:PORT` accepting exactly the certificate pinned by `pin`.

    pub fn tls(url: &str, pin: [u8; 32]) -> Result<Endpoint> {

        Ok(Endpoint::Tls { addr: host_port(url)?, config: crate::tls::Pinned::new(Some(pin)).client_config()? })

    }

    pub fn describe(&self) -> String {

        match self {

            Endpoint::Unix(p) => p.display().to_string(),

            Endpoint::Tls { addr, .. } => format!("https://{addr}"),

        }

    }

}

/// `host:port` of an `https://` URL.

pub fn host_port(url: &str) -> Result<String> {

    let rest = url.strip_prefix("https://").with_context(|| format!("{url} is not an https:// URL"))?;

    let hp = rest.split('/').next().unwrap_or("");

    if hp.is_empty() {

        anyhow::bail!("{url} names no host");

    }

    // The port defaults to Spectra's.

    let has_port = if hp.starts_with('[') { hp.contains("]:") } else { hp.contains(':') };

    Ok(if has_port { hp.to_string() } else { format!("{hp}:7350") })

}

trait Io: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin + Send {}

impl<T: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin + Send> Io for T {}

    endpoint: Endpoint,

        Client { endpoint: Endpoint::Unix(socket.to_path_buf()), signer }

    }

    pub fn at(endpoint: Endpoint, signer: Option<KeyPair>) -> Client {

        Client { endpoint, signer }

    }

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

        &self.endpoint

    }

    async fn io(&self) -> Result<Box<dyn Io>> {

        Ok(match &self.endpoint {

            Endpoint::Unix(socket) => Box::new(

                tokio::net::UnixStream::connect(socket)

                    .await

                    .with_context(|| format!("connecting to {} (is `spectra serve` running?)", socket.display()))?,

            ),

            Endpoint::Tls { addr, config } => Box::new(crate::tls::connect(addr, config.clone()).await?),

        })

    }

    /// Whether the daemon answers at the endpoint.

    pub async fn reachable(&self) -> bool {

        self.io().await.is_ok()

        let stream = self.io().await?;

        let stream = self.io().await?;

impl Connected<axum::serve::IncomingStream<'_, crate::tls::TlsListener>> for PeerInfo {

    fn connect_info(_: axum::serve::IncomingStream<'_, crate::tls::TlsListener>) -> Self {

        PeerInfo(None)

    }

}

        .route("/api/v1/instance", axum::routing::get(instance))

}

/// `GET /api/v1/instance`, unauthenticated (spec §8.6): who this Spectra

/// is, whose it is, and the instance key's word for its TLS certificate, so

/// a client can decide whether to trust it before it signs anything.

async fn instance(State(state): State<AppState>) -> Response {

    let (instance, owner) = {

        let p = state.daemon.principals.read().await;

        (p.instance().cloned(), p.owner().map(|o| o.hash().to_hex()))

    };

    let Some(instance) = instance else {

        return (StatusCode::SERVICE_UNAVAILABLE, axum::Json(json!({ "title": "this Spectra has no instance key" }))).into_response();

    };

    let tls = match crate::instance::latest_tls(&state.daemon.ledger).await {

        Ok(Some(e)) => json!({ "payload": e.json(), "proof": e.auth.proof.as_ref().map(hex::encode) }),

        _ => Json::Null,

    };

    axum::Json(json!({

        "name": instance.name,

        "instance": spectra_core::principals::identity_payload(&instance),

        "owner": owner,

        "tls": tls,

    }))

    .into_response()

pub mod instance;

pub mod tls;

- [x] #20 Server over TLS — done 2026-11-03: own certificate in keys/tls.*, vouched for by a signed instance.tls event; GET /api/v1/instance; pinned client transport; a uid-bound agent refused over TCP; tests/tls.rs.

**The server.** `[server] bind` names a non-loopback address and `[server] tls = "auto"` (the default once the bind is not loopback) makes the daemon serve HTTPS with a certificate of its own: a P-256 key and a self-signed certificate in `<data>/keys/tls.key` and `tls.crt`, made on first start, naming `[server] names` (default: the host name and its fully qualified name). The instance key vouches for the certificate with an `instance.tls` event, signed over its payload as CLI events are (§9.5), naming the SHA-256 of the certificate's SubjectPublicKeyInfo and its names; the daemon appends one whenever the certificate differs from the last recorded, and `spectra admin verify` checks it like any signed event. `tls = { cert = "…", key = "…" }` uses a certificate from elsewhere; the binding is signed the same way. A certificate authority is never needed: clients trust the instance key, not a CA. `GET /api/v1/instance` answers without authentication with the instance's name and identity, the owner's key, and the latest `instance.tls` payload with its proof.

        /// The address and port for browsers and HTTP clients (default:

        /// `[server] bind`, else 127.0.0.1:7350); beyond loopback, other

        /// machines connect over TLS (spec §8.6)

        #[arg(long)]

        bind: Option<String>,

        /// TLS on the TCP port: auto (beyond loopback only), on, or off

        /// (default: `[server] tls`, else auto)

        #[arg(long)]

        tls: Option<String>,

        Command::Serve { bind, tls, insecure, open } => {

            runtime()?.block_on(serve::serve(&ctx, bind, tls, insecure, open))

//! serves Tuner, the API and Radar on the Unix socket and on a TCP port,

//! over TLS beyond loopback (§8.6), and writes a checkpoint when it stops.

/// `[server]` of spectra.toml, with the command line's overrides.

struct ServerCfg {

    bind: String,

    tls: String,

    files: Option<(std::path::PathBuf, std::path::PathBuf)>,

    names: Vec<String>,

}

fn server_cfg(ctx: &Ctx, bind: Option<String>, tls: Option<String>) -> Result<ServerCfg> {

    let text = std::fs::read_to_string(ctx.data.join("spectra.toml")).unwrap_or_default();

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

    let server = t.get("server").and_then(|s| s.as_table()).cloned().unwrap_or_default();

    let (mut mode, mut files) = (String::from("auto"), None);

    match server.get("tls") {

        Some(toml::Value::String(m)) => mode = m.clone(),

        Some(toml::Value::Table(f)) => {

            let path = |k: &str| f.get(k).and_then(|v| v.as_str()).map(std::path::PathBuf::from);

            files = Some((path("cert").context("[server] tls needs cert")?, path("key").context("[server] tls needs key")?));

            mode = "on".into();

        }

        _ => {}

    }

    if let Some(m) = tls {

        mode = m;

    }

    if !matches!(mode.as_str(), "auto" | "on" | "off") {

        bail!("TLS is auto, on or off, not {mode}");

    }

    let names = match server.get("names").and_then(|n| n.as_array()) {

        Some(a) => a.iter().filter_map(|v| v.as_str().map(String::from)).collect(),

        None => default_names(),

    };

    let bind = bind.or_else(|| server.get("bind").and_then(|b| b.as_str()).map(String::from)).unwrap_or_else(|| "127.0.0.1:7350".into());

    Ok(ServerCfg { bind, tls: mode, files, names })

}

/// The host name, its fully qualified name, and localhost.

fn default_names() -> Vec<String> {

    let mut names = Vec::new();

    let short = std::fs::read_to_string("/etc/hostname").ok().map(|h| h.trim().to_string()).filter(|h| !h.is_empty());

    let fqdn = std::process::Command::new("hostname")

        .arg("--fqdn")

        .output()

        .ok()

        .filter(|o| o.status.success())

        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())

        .filter(|h| !h.is_empty());

    for n in [short, fqdn, Some("localhost".to_string())].into_iter().flatten() {

        if !names.contains(&n) {

            names.push(n);

        }