Set a server up without the owner's key: spectra init --owner and the claim (#22) 77df591d5a2f

//! Setting a server up without the owner's secret key (spec §8.6,

//! spectra#22): `spectra init --owner KEYID`, nothing served but who it

//! is until the named owner claims it, and nobody else may.

mod common;

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

use spectra_core::daemon::WireEvent;

use spectra_core::keys::KeyPair;

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

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

use spectra_mcp::tls::Pinned;

fn claim_body(pair: &KeyPair) -> Vec<u8> {

    let e = signed_event(pair, "human", "identity.owner", identity_payload(&pair.identity));

    serde_json::to_vec(&WireEvent::from_new(&e)).unwrap()

}

#[tokio::test]

async fn the_named_owner_claims_a_server_and_nobody_else_can() {

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

    let d = dir.path();

    // The owner's key is on another machine: here there is only its KeyId.

    let owner = KeyPair::generate("Andy McCall", "");

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

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

    assert!(text(&o).contains("not yet claimed"), "{}", text(&o));

    assert!(!d.join("owner").exists(), "no owner home was read or made");

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

    let probe = Pinned::new(None);

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

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

    assert_eq!(info["name"], "earth");

    assert!(info["owner"].is_null(), "unclaimed");

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

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

    // Before the claim, even the owner's signed requests are refused, and say why.

    let as_owner = Client::at(Endpoint::tls(&url, pin).unwrap(), Some(owner.clone()));

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

    assert_eq!(r.status, 401);

    assert!(String::from_utf8_lossy(&r.body).contains("no owner yet"), "{}", String::from_utf8_lossy(&r.body));

    // Someone else cannot claim it.

    let mallory = KeyPair::generate("Mallory", "");

    let r = anon.send("POST", "/api/v1/claim", &[], claim_body(&mallory)).await.unwrap();

    assert_eq!(r.status, 403);

    assert!(String::from_utf8_lossy(&r.body).contains("another owner"));

    // Nor can a claim naming the owner but signed by another key.

    let mut forged = signed_event(&mallory, "human", "identity.owner", identity_payload(&owner.identity));

    forged.payload = identity_payload(&owner.identity);

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

    assert_eq!(r.status, 403);

    // The owner can, once.

    let r = anon.send("POST", "/api/v1/claim", &[], claim_body(&owner)).await.unwrap();

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

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

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

    let r = anon.send("POST", "/api/v1/claim", &[], claim_body(&owner)).await.unwrap();

    assert_eq!(r.status, 403);

    assert!(String::from_utf8_lossy(&r.body).contains("already has an owner"));

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

    assert_eq!(info["owner"], owner.key.to_hex());

    srv.stop();

    // An owner recorded after the instance verifies, and rebuilds.

    for args in [["admin", "verify"], ["admin", "rebuild"], ["admin", "check"]] {

        let o = hermetic(d).args(args).output().unwrap();

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

    }

}

#[test]

fn init_refuses_what_is_not_a_key_id() {

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

    let o = run(dir.path(), &["init", "--owner", "andy"]);

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

    assert!(text(&o).contains("not a KeyId"), "{}", text(&o));

}

- **Added: setting a server up without the owner's key (#22).** `spectra init --owner KEYID` makes the instance key and the ledger with only the owner's KeyId named. Until that owner claims it, the daemon answers who it is and refuses everything else, saying it has no owner yet; the claim is the owner's identity signed by itself, and is accepted from no other key. A signed request the API refuses is now told why.

            if p.owner().is_none() {

                return Err(Refusal::NotAPrincipal("this Spectra has no owner yet: its owner claims it with `spectra connect`".into()));

            }

    }

    /// The owner `spectra init --owner` named, while none is recorded.

    pub fn named_owner(&self) -> Option<String> {

        let text = std::fs::read_to_string(self.data.join("spectra.toml")).ok()?;

        let t: toml::Table = text.parse().ok()?;

        t.get("owner")?.get("key")?.as_str().map(|k| k.to_ascii_lowercase())

    }

    /// The owner claims a Spectra set up with `spectra init --owner`

    /// (spec §8.6): their identity, signed by itself over its payload, and

    /// accepted only when no owner is recorded and the key is the one named.

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

        let n = w.into_new_event()?;

        if n.kind != "identity.owner" || n.actor != "human" {

            bail!("a claim is the owner's identity.owner");

        }

        let mut principals = self.principals.read().await.clone();

        if principals.owner().is_some() {

            bail!("this Spectra already has an owner");

        }

        let named = self.named_owner().context("this Spectra names no owner (spectra init --owner)")?;

        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}"))?;

        let appended = self.ledger.append(vec![n]).await?;

        let _ = self.ledger.checkpoint().await;

        *self.principals.write().await = Principals::load(&self.ledger).await?;

        Ok(appended.first().map(|e| e.seq).unwrap_or(0))

use crate::http::{AppState, PeerInfo};

    let signed = headers.get("spectra-key").is_some();

    crate::http::authenticate_why(st, peer, headers, method_path, body).await.map_err(|(status, why)| {

        if status == StatusCode::FORBIDDEN {

            problem(status, "this origin may not call Spectra", None)

        } else if signed {

            // A signed request is told why its signature was not enough.

            problem(StatusCode::UNAUTHORIZED, "not authenticated", Some(why))

        } else {

            problem(

                StatusCode::UNAUTHORIZED,

                "not authenticated",

                Some("sign the request with your key (spectra's client does), or open Radar with `spectra open`".into()),

            )

        }

        .route("/api/v1/claim", post(claim))

/// `POST /api/v1/claim`: the owner named by `spectra init --owner` records

/// their identity (spec §8.6). The event proves itself: it is signed by

/// the identity it records, over its payload.

async fn claim(State(state): State<AppState>, body: Bytes) -> Response {

    let w: WireEvent = match serde_json::from_slice(&body) {

        Ok(v) => v,

        Err(e) => return (StatusCode::BAD_REQUEST, axum::Json(json!({ "title": format!("not an event: {e}") }))).into_response(),

    };

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

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

        Err(e) => (StatusCode::FORBIDDEN, axum::Json(json!({ "title": format!("{e:#}") }))).into_response(),

    }

}

/// Authenticate a request, or the status and reason that refuse it.

pub async fn authenticate_why(

) -> Result<Caller, (StatusCode, String)> {

        return Err((StatusCode::FORBIDDEN, "this origin may not call Spectra".into()));

        (StatusCode::UNAUTHORIZED, why.to_string())

    })

}

/// Authenticate a request, or the JSON-RPC response that refuses it.

pub async fn authenticate(

    state: &AppState,

    peer: PeerInfo,

    headers: &HeaderMap,

    method_path: &str,

    body: &[u8],

) -> Result<Caller, Response> {

    authenticate_why(state, peer, headers, method_path, body).await.map_err(|(status, why)| {

        let (code, msg) = if status == StatusCode::FORBIDDEN {

            (protocol::INVALID_REQUEST, why)

        } else {

            (protocol::UNAUTHENTICATED, format!("not authenticated: {why}"))

        };

        (status, axum::Json(protocol::error(&Json::Null, code, &msg))).into_response()

- [x] #22 Remote setup — done 2026-11-03: spectra init --owner KEYID; unowned daemon refuses all but /api/v1/instance and POST /api/v1/claim, which takes only the named key; tests/remote.rs. Found: a failing end-to-end test left its daemon running, which held the output open and looked like a hang; Serving now kills it on drop.

/// `spectra init --owner KEYID` (spec §8.6): a server's instance key and

/// ledger, with the owner named but not yet recorded; the owner claims it

/// from their own machine, so their secret key never comes here.

pub async fn init_for(ctx: &Ctx, owner_key: &str, name: Option<String>) -> Result<i32> {

    let key = owner_key.trim().to_ascii_lowercase();

    if key.len() != 64 || hex::decode(&key).is_err() {

        bail!("{owner_key} is not a KeyId (64 hex digits; the owner's `oxy identity show` prints it)");

    }

    let data = &ctx.data;

    let db = data.join("spectra.db");

    if db.exists() {

        bail!("{} already holds a Spectra (spectra identity show)", data.display());

    }

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

    #[cfg(unix)]

    {

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

        std::fs::set_permissions(data, std::fs::Permissions::from_mode(0o700))?;

    }

    let name = name.unwrap_or_else(hostname);

    let instance = KeyPair::instance(data, &name)?;

    let ledger = Ledger::open(&db, Some(instance.clone())).await?;

    let mut first = vec![signed_event(&instance, "system", "identity.instance", identity_payload(&instance.identity))];

    first.extend(spectra_core::conversation::default_channel_events());

    ledger.append(first).await?;

    ledger.checkpoint().await?;

    std::fs::write(

        data.join("spectra.toml"),

        format!(

            "# Spectra's configuration (spec §22.1).\n\n[owner]\nkey = \"{key}\"     # claimed from the owner's machine with `spectra connect`\n\n[server]\n# bind = \"[::]:7350\"   # serve other machines over TLS (spec §8.6)\n"

        ),

    )?;

    println!("{} {}  {}", ui::done("Initialised"), ui::subject("Spectra"), ui::path(data.display()));

    println!("{}", ui::kv("owner", format!("{}{}", ui::hash(&key[..12]), ui::dim(" (named; not yet claimed)"))));

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

    println!();

    println!("  {} {}", ui::note(), ui::dim("serve it to other machines: set [server] bind in spectra.toml, then spectra serve"));

    println!("  {} {}", ui::note(), ui::dim("then, on the owner's machine:"));

    println!("    {}", ui::id("spectra connect https://HOST:7350"));

    Ok(0)

}

        /// Set up a server without the owner's secret key: name the owner's

        /// KeyId, and they claim it from their machine with `spectra

        /// connect` (spec §8.6)

        #[arg(long, value_name = "KEYID", conflicts_with = "owner_home")]

        owner: Option<String>,

        Command::Init { owner_home, name, owner: Some(key) } => {

            let _ = owner_home;

            runtime()?.block_on(identity::init_for(&ctx, &key, name))

        }

        Command::Init { owner_home, name, owner: None } => runtime()?.block_on(identity::init(&ctx, owner_home, name)),

/// A test that fails mid-way must not leave its daemon running: an orphan

/// holds the test's output open and looks like a hang.

impl Drop for Serving {

    fn drop(&mut self) {

        if let Ok(None) = self.child.try_wait() {

            let _ = self.child.kill();

            let _ = self.child.wait();

        }

    }

}