Identities instead of tokens: init, owned agents as delegates, verified replay of identities, request authentication, one writer (#4) 09752034b5a8

-- Projections of who is who (spec §8): identities the ledger knows, by

-- role, and agents with their owner and delegation.

CREATE TABLE identities (

    key       TEXT PRIMARY KEY,           -- KeyId, hex

    role      TEXT NOT NULL,              -- owner | instance | agent

    name      TEXT NOT NULL,

    identity  BLOB NOT NULL,              -- the encoded identity object

    previous  TEXT,                       -- the identity it succeeds

    current   INTEGER NOT NULL DEFAULT 1, -- 0 once succeeded

    seq       INTEGER NOT NULL

);

CREATE TABLE agents (

    name         TEXT PRIMARY KEY,

    key          TEXT NOT NULL UNIQUE,

    owner        TEXT NOT NULL,           -- the owner's KeyId when added

    owner_name   TEXT NOT NULL,

    kind         TEXT NOT NULL,

    project      TEXT NOT NULL,

    home         TEXT NOT NULL,

    uid          INTEGER,

    learn_uid    INTEGER NOT NULL DEFAULT 0,

    scopes       TEXT NOT NULL,

    created_ms   INTEGER NOT NULL,

    disabled_ms  INTEGER,

    seq          INTEGER NOT NULL

);

//! Authenticating a request (spec §8.5): a signature by a known key over the

//! method, the body, a time within five minutes and a nonce not seen in

//! that window, from a key the owner delegates to now, and, when the agent

//! is bound to a Unix user, from that user. What it returns becomes the

//! `auth` of every event the request causes.

use crate::event::{Auth, Method};

use crate::principals::{Principal, Principals};

use crate::proof::{Proof, WINDOW_MS};

use std::collections::HashMap;

use std::sync::Mutex;

/// Why a request was refused.

#[derive(Debug, PartialEq, Eq, thiserror::Error)]

pub enum Refusal {

    #[error("the request is not signed")]

    Unsigned,

    #[error("the signature is for {0}, not this request")]

    WrongMethod(String),

    #[error("the request's time is {0} s from the server's: check the clock")]

    Stale(i64),

    #[error("the request's nonce was used before: a replay")]

    Replay,

    #[error("{0}")]

    NotAPrincipal(String),

    #[error("{0}")]

    BadSignature(String),

    /// The key is bound to another Unix user (logged as `guard.impersonation`).

    #[error("agent {agent}'s key is bound to uid {bound}, used from uid {from}")]

    WrongUid { agent: String, bound: u32, from: u32 },

}

/// The outcome: who, and the `auth` for their events.

#[derive(Clone, Debug)]

pub struct Caller {

    pub principal: Principal,

    pub auth: Auth,

    /// The agent asked for its uid to be learnt and has none yet: the

    /// caller records `agent.uid_bound` with this uid.

    pub learn_uid: Option<u32>,

}

/// Remembers nonces for the window.

#[derive(Debug, Default)]

pub struct Authenticator {

    nonces: Mutex<HashMap<[u8; 16], u64>>,

}

impl Authenticator {

    pub fn authenticate(

        &self,

        principals: &Principals,

        proof: Option<&Proof>,

        method: &str,

        body: &[u8],

        now_ms: u64,

        peer_uid: Option<u32>,

    ) -> Result<Caller, Refusal> {

        let proof = proof.ok_or(Refusal::Unsigned)?;

        if proof.method != method {

            return Err(Refusal::WrongMethod(proof.method.clone()));

        }

        let skew = proof.time_ms as i64 - now_ms as i64;

        if skew.unsigned_abs() > WINDOW_MS {

            return Err(Refusal::Stale(skew / 1000));

        }

        let key = oxy_core::hash::ObjectRef(proof.key());

        let principal = principals.principal(&key, now_ms).map_err(Refusal::NotAPrincipal)?;

        let identity = principals.identity(&key).ok_or_else(|| Refusal::NotAPrincipal("an unknown key".into()))?;

        proof.verify(identity, Some(body)).map_err(Refusal::BadSignature)?;

        let mut learn_uid = None;

        if let Principal::Agent { name, uid, learn_uid: learn, .. } = &principal {

            match (uid, peer_uid) {

                (Some(bound), Some(from)) if *bound != from => return Err(Refusal::WrongUid { agent: name.clone(), bound: *bound, from }),

                (None, Some(from)) if *learn => learn_uid = Some(from),

                _ => {}

            }

        }

        {

            let mut seen = self.nonces.lock().unwrap();

            seen.retain(|_, t| now_ms.saturating_sub(*t) <= 2 * WINDOW_MS);

            if seen.insert(proof.nonce, now_ms).is_some() {

                return Err(Refusal::Replay);

            }

        }

        Ok(Caller {

            principal,

            auth: Auth { key: Some(proof.key()), method: Method::Signature, assurance: 2, proof: Some(proof.encode()) },

            learn_uid,

        })

    }

}

//! Who is who (spec §8): the owner, the instance, and agents, each an Oxygen

//! identity; an agent is valid while the owner's current identity delegates

//! to its key (oxygen spec §14.2). Everything here is derived from the

//! ledger, and every claim in it was proven when it was recorded:

//!

//! - `identity.owner` and `identity.rotated` are signed by the identity they

//!   record, so only the holder of its secret key can name it the owner.

//!   A successor must keep the key pair and chain back, by `previous`, to

//!   the owner already known; a fresh key pair needs `oxy identity rotate`'s

//!   attestation, which 0.1 does not accept yet.

//! - `identity.instance` is signed by the instance key.

//! - `agent.added` and `agent.disabled` are signed by the owner, and an

//!   agent is added only while the owner's identity delegates to it.

//!

//! [`Principals`] replays these in ledger order, so `spectra admin verify`

//! checks every signed event against who was who at that moment.

use crate::event::{Event, Method};

use crate::ledger::KeyResolver;

use crate::proof::Proof;

use oxy_core::hash::KeyId;

use oxy_core::identity::{Identity, Scope};

use serde_json::Value as Json;

use sqlx::SqliteConnection;

use std::collections::HashMap;

/// The scopes a new agent gets (spec §8.4).

pub const DEFAULT_SCOPES: &[&str] = &["read", "say", "tasks", "claims", "decisions", "status", "search", "schedule:self"];

/// The Oxygen delegation scope an agent's key needs from its owner.

pub const DELEGATION_SCOPE: Scope = Scope::CHANGES;

/// Who caused something.

#[derive(Clone, Debug, PartialEq, Eq)]

pub enum Principal {

    Owner { key: KeyId, name: String },

    Agent { name: String, key: KeyId, owner_name: String, uid: Option<u32>, learn_uid: bool, project: String, scopes: Vec<String> },

    Instance { key: KeyId },

}

impl Principal {

    /// The `actor` events carry: `human`, `agent:NAME` or `system`.

    pub fn actor(&self) -> String {

        match self {

            Principal::Owner { .. } => "human".into(),

            Principal::Agent { name, .. } => format!("agent:{name}"),

            Principal::Instance { .. } => "system".into(),

        }

    }

    /// How it is shown to people: `claude-oxygen · Andy McCall's agent`.

    pub fn display(&self) -> String {

        match self {

            Principal::Owner { name, .. } => name.clone(),

            Principal::Agent { name, owner_name, .. } => format!("{name} · {owner_name}'s agent"),

            Principal::Instance { .. } => "Spectra".into(),

        }

    }

}

#[derive(Clone, Debug)]

struct AgentRec {

    name: String,

    identity: Identity,

    owner_name: String,

    uid: Option<u32>,

    learn_uid: bool,

    project: String,

    scopes: Vec<String>,

    disabled: bool,

}

/// The principals as of some point in the ledger.

#[derive(Clone, Debug, Default)]

pub struct Principals {

    /// The owner's identities, oldest first; the last is current.

    owner: Vec<Identity>,

    instance: Option<Identity>,

    agents: HashMap<KeyId, AgentRec>,

    by_name: HashMap<String, KeyId>,

}

impl Principals {

    /// Replay every identity and agent event of the ledger.

    pub async fn load(ledger: &crate::ledger::Ledger) -> anyhow::Result<Principals> {

        let mut p = Principals::default();

        let mut from = 1;

        loop {

            let rows = ledger

                .events_of_kinds(from, &["identity.owner", "identity.rotated", "identity.instance", "agent.added", "agent.disabled"], 1000)

                .await?;

            if rows.is_empty() {

                break;

            }

            for e in &rows {

                // Recorded facts were checked when written; `verify` checks them again.

                let _ = p.observe(e);

            }

            from = rows.last().map(|e| e.seq + 1).unwrap_or(from);

        }

        Ok(p)

    }

    /// The owner's current identity.

    pub fn owner(&self) -> Option<&Identity> {

        self.owner.last()

    }

    pub fn instance(&self) -> Option<&Identity> {

        self.instance.as_ref()

    }

    /// The agent named `name`, whatever its state.

    pub fn agent_key(&self, name: &str) -> Option<KeyId> {

        self.by_name.get(name).copied()

    }

    /// Who `key` is at `at_ms`, if anyone may act with it then: the owner

    /// (any of its identities' KeyIds), the instance, or an agent that is

    /// not disabled and that the owner's current identity delegates to.

    pub fn principal(&self, key: &KeyId, at_ms: u64) -> Result<Principal, String> {

        if let Some(owner) = self.owner.iter().rev().find(|i| &i.hash() == key) {

            return Ok(Principal::Owner { key: *key, name: owner.name.clone() });

        }

        if self.instance.as_ref().is_some_and(|i| &i.hash() == key) {

            return Ok(Principal::Instance { key: *key });

        }

        let a = self.agents.get(key).ok_or("an unknown key")?;

        if a.disabled {

            return Err(format!("agent {} is disabled", a.name));

        }

        let owner = self.owner().ok_or("no owner is recorded")?;

        if !owner.delegates_to(key, DELEGATION_SCOPE, at_ms) {

            return Err(match owner.delegate(key) {

                Some(d) if d.expires.is_some_and(|x| at_ms > x) => format!("agent {}'s delegation from {} has expired", a.name, owner.name),

                Some(_) => format!("{}'s delegation to agent {} does not include `changes`", owner.name, a.name),

                None => format!("{}'s current identity does not delegate to agent {}", owner.name, a.name),

            });

        }

        Ok(Principal::Agent {

            name: a.name.clone(),

            key: *key,

            owner_name: a.owner_name.clone(),

            uid: a.uid,

            learn_uid: a.learn_uid,

            project: a.project.clone(),

            scopes: a.scopes.clone(),

        })

    }

    /// The identity behind `key`, for checking its signatures.

    pub fn identity(&self, key: &KeyId) -> Option<&Identity> {

        self.owner

            .iter()

            .find(|i| &i.hash() == key)

            .or_else(|| self.instance.as_ref().filter(|i| &i.hash() == key))

            .or_else(|| self.agents.get(key).map(|a| &a.identity))

    }

    /// Take one event into account, checking what it claims first.

    pub fn observe(&mut self, e: &Event) -> Result<(), String> {

        let p = e.json();

        match e.kind.as_str() {

            "identity.owner" => {

                if !self.owner.is_empty() {

                    return Err("an owner is already recorded".into());

                }

                let id = identity_of(&p)?;

                self_signed(e, &id)?;

                self.owner.push(id);

            }

            "identity.rotated" => {

                let new = identity_of(&p)?;

                let cur = self.owner().ok_or("no owner to succeed")?.clone();

                accept_successor(&cur, &new, &p)?;

                self_signed(e, &new)?;

                self.owner.push(new);

            }

            "identity.instance" => {

                let id = identity_of(&p)?;

                self_signed(e, &id)?;

                self.instance = Some(id);

            }

            "agent.added" => {

                let id = identity_of(&p)?;

                let key = id.hash();

                let owner = self.owner_signed(e)?;

                if !owner.delegates_to(&key, DELEGATION_SCOPE, e.hlc.wall_ms) {

                    return Err("added without the owner's delegation to its key".into());

                }

                let name = text(&p, "name")?;

                if self.by_name.get(&name).is_some_and(|k| *k != key) {

                    return Err(format!("agent {name} already exists with another key"));

                }

                self.by_name.insert(name.clone(), key);

                self.agents.insert(

                    key,

                    AgentRec {

                        name,

                        identity: id,

                        owner_name: owner.name.clone(),

                        uid: p.get("uid").and_then(Json::as_u64).map(|u| u as u32),

                        learn_uid: p.get("learn_uid").and_then(Json::as_bool).unwrap_or(false),

                        project: text(&p, "project")?,

                        scopes: p

                            .get("scopes")

                            .and_then(Json::as_array)

                            .map(|a| a.iter().filter_map(|s| s.as_str().map(String::from)).collect())

                            .unwrap_or_default(),

                        disabled: false,

                    },

                );

            }

            "agent.disabled" => {

                self.owner_signed(e)?;

                let name = text(&p, "name")?;

                let key = *self.by_name.get(&name).ok_or("an unknown agent")?;

                if let Some(a) = self.agents.get_mut(&key) {

                    a.disabled = true;

                }

            }

            _ => {}

        }

        Ok(())

    }

    /// Check that `e` is signed by the owner's current identity; returns it.

    fn owner_signed(&self, e: &Event) -> Result<Identity, String> {

        let owner = self.owner().ok_or("no owner is recorded")?.clone();

        if e.auth.key != Some(owner.hash().0) {

            return Err("not signed by the owner's current identity".into());

        }

        check_proof(e, &owner)?;

        Ok(owner)

    }

    /// Check a signed event's proof against the principal its key was at

    /// the event's time.

    pub fn check_signed(&self, e: &Event) -> Result<(), String> {

        let key = oxy_core::hash::ObjectRef(e.auth.key.ok_or("signed, but names no key")?);

        let who = self.principal(&key, e.hlc.wall_ms)?;

        // The actor an event names must be the principal that signed it:

        // an agent's key never makes an event in another's name.

        if who.actor() != e.actor {

            return Err(format!("names {} as its actor but is signed by {}", e.actor, who.display()));

        }

        let identity = self.identity(&key).ok_or("an unknown key")?;

        check_proof(e, identity)

    }

}

impl KeyResolver for Principals {

    fn check(&mut self, e: &Event) -> Result<(), String> {

        match e.kind.as_str() {

            "identity.owner" | "identity.rotated" | "identity.instance" | "agent.added" | "agent.disabled" => {

                if e.auth.method != Method::Signature {

                    return Err(format!("{} must be signed", e.kind));

                }

                self.observe(e)

            }

            _ if matches!(e.auth.method, Method::Signature | Method::Passkey) => self.check_signed(e),

            _ => Ok(()),

        }

    }

}

/// Apply identity and agent events to the projection tables.

pub async fn project(conn: &mut SqliteConnection, e: &Event) -> sqlx::Result<()> {

    let p = e.json();

    let id = |p: &Json| identity_of(p).ok();

    match e.kind.as_str() {

        "identity.owner" | "identity.rotated" | "identity.instance" => {

            let Some(identity) = id(&p) else { return Ok(()) };

            let role = if e.kind == "identity.instance" { "instance" } else { "owner" };

            sqlx::query("UPDATE identities SET current = 0 WHERE role = ?").bind(role).execute(&mut *conn).await?;

            sqlx::query(

                "INSERT OR REPLACE INTO identities (key, role, name, identity, previous, current, seq) VALUES (?, ?, ?, ?, ?, 1, ?)",

            )

            .bind(identity.hash().to_hex())

            .bind(role)

            .bind(&identity.name)

            .bind(identity.encode())

            .bind(identity.previous.map(|k| k.to_hex()))

            .bind(e.seq as i64)

            .execute(&mut *conn)

            .await?;

        }

        "agent.added" => {

            let Some(identity) = id(&p) else { return Ok(()) };

            let s = |k: &str| p.get(k).and_then(Json::as_str).unwrap_or("").to_string();

            sqlx::query(

                "INSERT OR REPLACE INTO agents (name, key, owner, owner_name, kind, project, home, uid, learn_uid, scopes, created_ms, disabled_ms, seq) \

                 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?)",

            )

            .bind(s("name"))

            .bind(identity.hash().to_hex())

            .bind(s("owner"))

            .bind(s("owner_name"))

            .bind(s("kind"))

            .bind(s("project"))

            .bind(s("home"))

            .bind(p.get("uid").and_then(Json::as_i64))

            .bind(p.get("learn_uid").and_then(Json::as_bool).unwrap_or(false))

            .bind(p.get("scopes").map(|v| v.to_string()).unwrap_or_else(|| "[]".into()))

            .bind(e.at_ms as i64)

            .bind(e.seq as i64)

            .execute(&mut *conn)

            .await?;

            sqlx::query(

                "INSERT OR REPLACE INTO identities (key, role, name, identity, previous, current, seq) VALUES (?, 'agent', ?, ?, ?, 1, ?)",

            )

            .bind(identity.hash().to_hex())

            .bind(&identity.name)

            .bind(identity.encode())

            .bind(identity.previous.map(|k| k.to_hex()))

            .bind(e.seq as i64)

            .execute(&mut *conn)

            .await?;

        }

        "agent.disabled" => {

            sqlx::query("UPDATE agents SET disabled_ms = ? WHERE name = ?")

                .bind(e.at_ms as i64)

                .bind(p.get("name").and_then(Json::as_str))

                .execute(&mut *conn)

                .await?;

        }

        _ => {}

    }

    Ok(())

}

/// The payload of an identity event for `identity`.

pub fn identity_payload(identity: &Identity) -> Json {

    serde_json::json!({ "key": identity.hash().to_hex(), "name": identity.name, "identity": hex::encode(identity.encode()) })

}

fn identity_of(p: &Json) -> Result<Identity, String> {

    let b = p.get("identity").and_then(Json::as_str).and_then(|h| hex::decode(h).ok()).ok_or("no identity in the event")?;

    Identity::decode(&b).map_err(|e| format!("malformed identity: {e}"))

}

fn text(p: &Json, k: &str) -> Result<String, String> {

    p.get(k).and_then(Json::as_str).map(String::from).ok_or_else(|| format!("no {k}"))

}

fn self_signed(e: &Event, id: &Identity) -> Result<(), String> {

    if e.auth.key != Some(id.hash().0) {

        return Err("not signed by the identity it records".into());

    }

    check_proof(e, id)

}

/// The event's proof verifies against `identity`, and a CLI proof covers

/// exactly the event's payload.

fn check_proof(e: &Event, identity: &Identity) -> Result<(), String> {

    let proof = Proof::decode(e.auth.proof.as_deref().ok_or("no proof")?)?;

    if proof.key() != identity.hash().0 {

        return Err("the proof is by another key".into());

    }

    let body = (proof.method == "cli").then(|| e.payload.as_deref().unwrap_or(b""));

    proof.verify(identity, body)

}

/// A successor of the owner must keep the key pair and chain back to the

/// current identity through `previous` (the intermediate identities, if

/// any, are carried in the event as `chain`).

fn accept_successor(cur: &Identity, new: &Identity, p: &Json) -> Result<(), String> {

    if new.ed25519_pk != cur.ed25519_pk || new.mldsa65_pk != cur.mldsa65_pk {

        return Err("a successor with a fresh key pair needs `oxy identity rotate`'s attestation, not accepted in 0.1".into());

    }

    let chain: Vec<Identity> = p

        .get("chain")

        .and_then(Json::as_array)

        .map(|a| a.iter().filter_map(|h| h.as_str().and_then(|h| hex::decode(h).ok()).and_then(|b| Identity::decode(&b).ok())).collect())

        .unwrap_or_default();

    let mut at = new.clone();

    for _ in 0..=chain.len() {

        match at.previous {

            Some(prev) if prev == cur.hash() => return Ok(()),

            Some(prev) => match chain.iter().find(|i| i.hash() == prev) {

                Some(i) if i.ed25519_pk == cur.ed25519_pk => at = i.clone(),

                _ => break,

            },

            None => break,

        }

    }

    Err("does not succeed the recorded owner".into())

}

/// An event signed by `pair` from the command line: its proof covers the

/// canonical payload, so the event's content is bound to the signature.

pub fn signed_event(pair: &crate::keys::KeyPair, actor: &str, kind: &str, payload: Json) -> crate::event::NewEvent {

    let body = crate::event::canonical_json(&payload);

    let proof = Proof::sign(pair, "cli", &body);

    crate::event::NewEvent::system(kind, payload)

        .by(actor, crate::event::Auth { key: Some(pair.key.0), method: Method::Signature, assurance: 2, proof: Some(proof.encode()) })

}

//! Signed requests and the proofs events carry (spec §8.5, §9.5).

//!

//! A principal signs `"spectra1 request " || method || 0x00 || BLAKE3(body)

//! || time (8 bytes) || nonce (16 bytes)` with its key, through `oxy-core`'s

//! challenge signing. The signature, with what it covered, is the proof

//! kept on every event the request causes, so a verifier can check later,

//! from the ledger alone, which key asked for it.

//!

//! The CLI, writing to the ledger itself, signs with `method = "cli"` and

//! `body` = the event's canonical payload, so its proof also binds the

//! event's content.

use crate::keys::KeyPair;

use oxy_core::cbor::{self, Value};

use oxy_core::identity::{Identity, Signature};

use rand::RngCore;

/// How far a request's time may be from the server's clock (spec §8.5).

pub const WINDOW_MS: u64 = 5 * 60 * 1000;

/// A signature with everything it covered except the body itself.

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Proof {

    pub sig: Signature,

    pub method: String,

    pub body_hash: [u8; 32],

    pub time_ms: u64,

    pub nonce: [u8; 16],

}

impl Proof {

    /// Sign `method` and `body` now with `pair`.

    pub fn sign(pair: &KeyPair, method: &str, body: &[u8]) -> Proof {

        let mut nonce = [0u8; 16];

        rand::rngs::OsRng.fill_bytes(&mut nonce);

        Proof::sign_at(pair, method, body, crate::ids::now_ms(), nonce)

    }

    pub fn sign_at(pair: &KeyPair, method: &str, body: &[u8], time_ms: u64, nonce: [u8; 16]) -> Proof {

        let body_hash = *blake3::hash(body).as_bytes();

        let sig = pair.sign(&message(method, &body_hash, time_ms, &nonce));

        Proof { sig, method: method.into(), body_hash, time_ms, nonce }

    }

    /// The signing key's KeyId.

    pub fn key(&self) -> [u8; 32] {

        self.sig.key.0

    }

    /// Check the signature against `identity` and, when given, the body.

    pub fn verify(&self, identity: &Identity, body: Option<&[u8]>) -> Result<(), String> {

        if let Some(b) = body {

            if *blake3::hash(b).as_bytes() != self.body_hash {

                return Err("the signature covers a different body".into());

            }

        }

        let msg = message(&self.method, &self.body_hash, self.time_ms, &self.nonce);

        oxy_core::identity::verify_challenge(identity, &self.sig, &msg).map_err(|e| format!("signature does not verify: {e}"))

    }

    pub fn encode(&self) -> Vec<u8> {

        cbor::encode(&Value::map([

            (0, self.sig.to_value()),

            (1, Value::Text(self.method.clone())),

            (2, Value::Bytes(self.body_hash.to_vec())),

            (3, Value::Uint(self.time_ms)),

            (4, Value::Bytes(self.nonce.to_vec())),

        ]))

    }

    pub fn decode(b: &[u8]) -> Result<Proof, String> {

        let v = cbor::decode(b).map_err(|e| format!("malformed proof: {e}"))?;

        let m = v.as_map().ok_or("malformed proof")?;

        let get = |k: u64| m.get(&k).ok_or_else(|| format!("proof lacks field {k}"));

        Ok(Proof {

            sig: Signature::from_value(get(0)?).map_err(|e| format!("malformed signature: {e}"))?,

            method: get(1)?.as_text().ok_or("proof method")?.to_string(),

            body_hash: get(2)?.as_bytes().and_then(|b| b.try_into().ok()).ok_or("proof body hash")?,

            time_ms: get(3)?.as_uint().ok_or("proof time")?,

            nonce: get(4)?.as_bytes().and_then(|b| b.try_into().ok()).ok_or("proof nonce")?,

        })

    }

}

/// `"spectra1 request " || method || 0 || body_hash || time || nonce`.

pub fn message(method: &str, body_hash: &[u8; 32], time_ms: u64, nonce: &[u8; 16]) -> Vec<u8> {

    let mut m = b"spectra1 request ".to_vec();

    m.extend_from_slice(method.as_bytes());

    m.push(0);

    m.extend_from_slice(body_hash);

    m.extend_from_slice(&time_ms.to_be_bytes());

    m.extend_from_slice(nonce);

    m

}

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    fn a_proof_round_trips_and_binds_key_method_body_and_time() {

        let a = KeyPair::generate("a", "");

        let b = KeyPair::generate("b", "");

        let p = Proof::sign(&a, "POST /mcp", b"{\"x\":1}");

        let q = Proof::decode(&p.encode()).unwrap();

        assert_eq!(p, q);

        q.verify(&a.identity, Some(b"{\"x\":1}")).unwrap();

        assert!(q.verify(&a.identity, Some(b"{\"x\":2}")).is_err(), "another body");

        assert!(q.verify(&b.identity, None).is_err(), "another key");

        let mut r = q.clone();

        r.method = "POST /api".into();

        assert!(r.verify(&a.identity, None).is_err(), "another method");

        let mut t = q.clone();

        t.time_ms += 1;

        assert!(t.verify(&a.identity, None).is_err(), "another time");

    }

}

//! Who may act as whom (spec §5.2 G1, G7; §8): an agent is its owner's

//! delegate or nothing, may not act in another's name, stops when its

//! delegation expires or is disabled, and a request is refused unless

//! signed, fresh, unreplayed and from the bound Unix user.

use oxy_core::durable::{write_atomic, write_atomic_private};

use oxy_core::identity::{Delegate, Identity, SecretKey};

use spectra_core::authn::{Authenticator, Refusal};

use spectra_core::event::NewEvent;

use spectra_core::ids::now_ms;

use spectra_core::keys::KeyPair;

use spectra_core::ledger::{Ledger, Problem};

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

use spectra_core::proof::Proof;

use std::path::Path;

/// What `oxy identity delegate add KEY --scope changes [--expires]` does to

/// the owner's home: a successor with the same key pair, its own secret

/// file, and `author.key` naming it. Only the owner's tools do this.

fn delegate(owner_home: &Path, agent: &Identity, expires: Option<u64>) -> KeyPair {

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

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

    let secret_file = std::fs::read(keys.join(format!("{}.secret", cur.key.to_hex()))).unwrap();

    let (_, secret) = SecretKey::decode(&secret_file).unwrap();

    let mut delegates = cur.identity.delegates.clone();

    delegates.retain(|d| d.key != agent.hash());

    delegates.push(Delegate { key: agent.hash(), scope: DELEGATION_SCOPE, expires });

    let next = cur.identity.successor(delegates, None, now_ms());

    let key = next.hash();

    write_atomic_private(&keys.join(format!("{}.secret", key.to_hex())), &secret.encode(&key)).unwrap();

    write_atomic(&keys.join(format!("{}.identity", key.to_hex())), &next.encode()).unwrap();

    oxy_core::repo::Config::set_user(&owner_home.join("config.toml"), "author.key", &key.to_hex()).unwrap();

    KeyPair::load_home(owner_home).unwrap()

}

struct World {

    _dir: tempfile::TempDir,

    owner_home: std::path::PathBuf,

    ledger: Ledger,

    owner: KeyPair,

}

async fn world() -> World {

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

    let owner_home = dir.path().join("owner");

    let owner = KeyPair::create_home(&owner_home, "Andy McCall", "[email protected]").unwrap();

    let data = dir.path().join("data");

    std::fs::create_dir_all(&data).unwrap();

    let instance = KeyPair::instance(&data, "laptop").unwrap();

    let ledger = Ledger::open(&data.join("spectra.db"), Some(instance.clone())).await.unwrap();

    ledger.append_one(signed_event(&owner, "human", "identity.owner", identity_payload(&owner.identity))).await.unwrap();

    ledger.append_one(signed_event(&instance, "system", "identity.instance", identity_payload(&instance.identity))).await.unwrap();

    World { _dir: dir, owner_home, ledger, owner }

}

/// Add `name` as the owner would: delegate, record the successor, add.

async fn add_agent(w: &mut World, name: &str, expires: Option<u64>) -> KeyPair {

    let agent = KeyPair::generate(name, "");

    let prev = w.owner.identity.clone();

    w.owner = delegate(&w.owner_home, &agent.identity, expires);

    let mut rotated = identity_payload(&w.owner.identity);

    rotated["chain"] = serde_json::json!([]);

    assert_eq!(w.owner.identity.previous, Some(prev.hash()));

    w.ledger.append_one(signed_event(&w.owner, "human", "identity.rotated", rotated)).await.unwrap();

    let mut p = identity_payload(&agent.identity);

    p["name"] = name.into();

    p["kind"] = "claude-code".into();

    p["project"] = "oxygen".into();

    p["owner"] = w.owner.key.to_hex().into();

    p["owner_name"] = "Andy McCall".into();

    w.ledger.append_one(signed_event(&w.owner, "human", "agent.added", p)).await.unwrap();

    agent

}

fn said(agent: &KeyPair, actor: &str, body: &str) -> NewEvent {

    signed_event(agent, actor, "message.posted", serde_json::json!({ "body": body }))

}

#[tokio::test]

async fn an_owned_agent_acts_and_the_ledger_verifies_every_signature() {

    let mut w = world().await;

    let a = add_agent(&mut w, "claude-oxygen", None).await;

    w.ledger.append_one(said(&a, "agent:claude-oxygen", "hello")).await.unwrap();

    w.ledger.checkpoint().await.unwrap();

    let mut p = Principals::default();

    let v = w.ledger.verify(&mut p).await.unwrap();

    assert!(v.clean(), "{:?}", v.findings);

    let who = p.principal(&a.key, now_ms()).unwrap();

    assert_eq!(who.display(), "claude-oxygen · Andy McCall's agent");

    // The projection agrees, and so does a fresh load.

    assert!(w.ledger.check().await.unwrap().is_empty());

    let loaded = Principals::load(&w.ledger).await.unwrap();

    assert!(matches!(loaded.principal(&a.key, now_ms()), Ok(Principal::Agent { .. })));

}

#[tokio::test]

async fn an_agent_without_the_owners_delegation_cannot_be_added() {

    let w = world().await;

    let stray = KeyPair::generate("stray", "");

    let mut p = identity_payload(&stray.identity);

    p["name"] = "stray".into();

    p["project"] = "oxygen".into();

    w.ledger.append_one(signed_event(&w.owner, "human", "agent.added", p)).await.unwrap();

    w.ledger.append_one(said(&stray, "agent:stray", "I am somebody's")).await.unwrap();

    let v = w.ledger.verify(&mut Principals::default()).await.unwrap();

    let bad: Vec<_> = v.findings.iter().filter(|f| f.problem == Problem::BadProof).collect();

    assert_eq!(bad.len(), 2, "the addition and the message: {:?}", v.findings);

    assert!(bad[0].detail.contains("without the owner's delegation"), "{}", bad[0].detail);

}

#[tokio::test]

async fn an_agent_cannot_act_in_another_agents_name_or_the_owners() {

    let mut w = world().await;

    let a = add_agent(&mut w, "claude-oxygen", None).await;

    let _b = add_agent(&mut w, "antigravity-hub", None).await;

    w.ledger.append_one(said(&a, "agent:antigravity-hub", "I am antigravity")).await.unwrap();

    w.ledger.append_one(said(&a, "human", "I am Andy")).await.unwrap();

    let v = w.ledger.verify(&mut Principals::default()).await.unwrap();

    assert_eq!(v.findings.len(), 2, "{:?}", v.findings);

    assert!(v.findings.iter().all(|f| f.detail.contains("is signed by claude-oxygen")));

}

#[tokio::test]

async fn an_agent_cannot_record_itself_as_the_owner_or_a_successor() {

    let mut w = world().await;

    let a = add_agent(&mut w, "claude-oxygen", None).await;

    // A successor of the owner that the agent made: it has no owner key to sign it with.

    let forged =

        w.owner.identity.successor(vec![Delegate { key: a.key, scope: oxy_core::identity::Scope::ALL, expires: None }], None, now_ms());

    let mut p = identity_payload(&forged);

    p["chain"] = serde_json::json!([]);

    w.ledger.append_one(signed_event(&a, "human", "identity.rotated", p)).await.unwrap();

    // And a second owner, signed by itself.

    w.ledger.append_one(signed_event(&a, "human", "identity.owner", identity_payload(&a.identity))).await.unwrap();

    let v = w.ledger.verify(&mut Principals::default()).await.unwrap();

    assert_eq!(v.findings.len(), 2, "{:?}", v.findings);

}

#[tokio::test]

async fn an_expired_or_disabled_agent_is_refused_and_flagged() {

    let mut w = world().await;

    let a = add_agent(&mut w, "overnight", Some(now_ms() + 60_000)).await;

    let principals = Principals::load(&w.ledger).await.unwrap();

    assert!(principals.principal(&a.key, now_ms()).is_ok());

    let later = now_ms() + 120_000;

    let why = principals.principal(&a.key, later).unwrap_err();

    assert!(why.contains("expired"), "{why}");

    let b = add_agent(&mut w, "claude-oxygen", None).await;

    w.ledger.append_one(signed_event(&w.owner, "human", "agent.disabled", serde_json::json!({ "name": "claude-oxygen" }))).await.unwrap();

    w.ledger.append_one(said(&b, "agent:claude-oxygen", "still here?")).await.unwrap();

    let v = w.ledger.verify(&mut Principals::default()).await.unwrap();

    assert_eq!(v.findings.len(), 1, "{:?}", v.findings);

    assert!(v.findings[0].detail.contains("disabled"));

}

#[tokio::test]

async fn a_proof_swapped_from_another_event_is_caught() {

    let mut w = world().await;

    let a = add_agent(&mut w, "claude-oxygen", None).await;

    let first = w.ledger.append_one(said(&a, "agent:claude-oxygen", "one")).await.unwrap();

    let second = w.ledger.append_one(said(&a, "agent:claude-oxygen", "two")).await.unwrap();

    let pool = w.ledger.pool().clone();

    sqlx::query("UPDATE events SET auth_proof = ? WHERE seq = ?")

        .bind(first.auth.proof.clone())

        .bind(second.seq as i64)

        .execute(&pool)

        .await

        .unwrap();

    let v = w.ledger.verify(&mut Principals::default()).await.unwrap();

    assert_eq!(v.findings.len(), 1, "{:?}", v.findings);

    assert!(v.findings[0].detail.contains("different body"));

}

#[tokio::test]

async fn requests_are_refused_unless_signed_fresh_unreplayed_and_from_the_bound_uid() {

    let mut w = world().await;

    let a = add_agent(&mut w, "claude-oxygen", None).await;

    let principals = Principals::load(&w.ledger).await.unwrap();

    let auth = Authenticator::default();

    let now = now_ms();

    let body = br#"{"jsonrpc":"2.0","id":1,"method":"tools/list"}"#;

    assert_eq!(auth.authenticate(&principals, None, "POST /mcp", body, now, Some(1000)).unwrap_err(), Refusal::Unsigned);

    let good = Proof::sign(&a, "POST /mcp", body);

    let caller = auth.authenticate(&principals, Some(&good), "POST /mcp", body, now, Some(1000)).unwrap();

    assert_eq!(caller.principal.actor(), "agent:claude-oxygen");

    assert_eq!(caller.auth.assurance, 2);

    assert_eq!(auth.authenticate(&principals, Some(&good), "POST /mcp", body, now, Some(1000)).unwrap_err(), Refusal::Replay);

    let other_body = Proof::sign(&a, "POST /mcp", body);

    assert!(matches!(auth.authenticate(&principals, Some(&other_body), "POST /mcp", b"{}", now, None), Err(Refusal::BadSignature(_))));

    let old = Proof::sign_at(&a, "POST /mcp", body, now - 10 * 60_000, [7; 16]);

    assert!(matches!(auth.authenticate(&principals, Some(&old), "POST /mcp", body, now, None), Err(Refusal::Stale(_))));

    let wrong = Proof::sign(&a, "POST /api/v1/channels", body);

    assert!(matches!(auth.authenticate(&principals, Some(&wrong), "POST /mcp", body, now, None), Err(Refusal::WrongMethod(_))));

    let stranger = KeyPair::generate("stranger", "");

    assert!(matches!(

        auth.authenticate(&principals, Some(&Proof::sign(&stranger, "POST /mcp", body)), "POST /mcp", body, now, None),

        Err(Refusal::NotAPrincipal(_))

    ));

    let owner = auth.authenticate(&principals, Some(&Proof::sign(&w.owner, "POST /mcp", body)), "POST /mcp", body, now, None).unwrap();

    assert_eq!(owner.principal.actor(), "human");

    // An agent bound to a Unix user, used from another.

    let b = add_agent_bound(&mut w, "bound", 1001).await;

    let principals = Principals::load(&w.ledger).await.unwrap();

    let r = auth.authenticate(&principals, Some(&Proof::sign(&b, "POST /mcp", body)), "POST /mcp", body, now, Some(1000));

    assert_eq!(r.unwrap_err(), Refusal::WrongUid { agent: "bound".into(), bound: 1001, from: 1000 });

    assert!(auth.authenticate(&principals, Some(&Proof::sign(&b, "POST /mcp", body)), "POST /mcp", body, now, Some(1001)).is_ok());

}

async fn add_agent_bound(w: &mut World, name: &str, uid: u32) -> KeyPair {

    let agent = KeyPair::generate(name, "");

    w.owner = delegate(&w.owner_home, &agent.identity, None);

    let mut rotated = identity_payload(&w.owner.identity);

    rotated["chain"] = serde_json::json!([]);

    w.ledger.append_one(signed_event(&w.owner, "human", "identity.rotated", rotated)).await.unwrap();

    let mut p = identity_payload(&agent.identity);

    p["name"] = name.into();

    p["project"] = "oxygen".into();

    p["uid"] = uid.into();

    w.ledger.append_one(signed_event(&w.owner, "human", "agent.added", p)).await.unwrap();

    agent

}

//! `spectra agent`: agents as their owner's delegates (spec §8.1).

//!

//! `add` makes the agent's key pair in its own home, prints the one `oxy`

//! command that makes it the owner's, and records the agent only once the

//! owner's identity delegates to it. There is no agent without an owner.

use super::identity::{owner_home, refresh_owner};

use super::{ui, Ctx};

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

use spectra_core::ids::now_ms;

use spectra_core::keys::{home_identity, KeyPair};

use spectra_core::ledger::Ledger;

use spectra_core::principals::{identity_payload, signed_event, Principal, Principals, DEFAULT_SCOPES, DELEGATION_SCOPE};

use std::path::PathBuf;

use std::time::Duration;

pub const KINDS: &[&str] = &["claude-code", "antigravity", "kimi-code", "codex", "other"];

pub struct Add {

    pub name: String,

    pub kind: String,

    pub project: String,

    pub home: PathBuf,

    pub uid: Option<u32>,

    pub learn_uid: bool,

    pub wait_secs: u64,

    pub owner_home: Option<PathBuf>,

}

pub async fn add(ctx: &Ctx, a: Add) -> Result<i32> {

    if !valid_name(&a.name) {

        bail!("an agent's name is lower-case letters, digits and dashes, starting with a letter or digit, at most 64");

    }

    if !KINDS.contains(&a.kind.as_str()) {

        bail!("--kind is one of {}", KINDS.join(", "));

    }

    {

        let ledger = Ledger::open_read_only(&ctx.db()?).await?;

        let p = Principals::load(&ledger).await?;

        if p.agent_key(&a.name).is_some() {

            bail!("an agent named {} already exists (spectra agent list)", a.name);

        }

    }

    let home = owner_home(ctx, a.owner_home.clone());

    // The agent's key, made once in its own home and reused if `add` is run again.

    let agent = if a.home.join("keys").exists() {

        KeyPair::load_home(&a.home).with_context(|| format!("reading the agent's key in {}", a.home.display()))?

    } else {

        let pair = KeyPair::create_home(&a.home, &a.name, "")?;

        println!("{} made {}'s key in {}", ui::done(ui::glyph("✔", "ok")), a.name, ui::path(a.home.display()));

        pair

    };

    let delegated = |id: &oxy_core::identity::Identity| id.delegates_to(&agent.key, DELEGATION_SCOPE, now_ms());

    if !delegated(&home_identity(&home)?) {

        println!("To make {} yours, delegate to its key (as yourself):", a.name);

        println!(

            "  {}",

            ui::id(format!(

                "oxy identity delegate add {} --scope changes --expires 8h",

                a.home.join("keys").join(format!("{}.identity", agent.key.to_hex())).display()

            ))

        );

        println!(

            "{}",

            ui::dim(format!("waiting up to {} s for the delegation; Ctrl-C stops, and running this again resumes", a.wait_secs))

        );

        let deadline = std::time::Instant::now() + Duration::from_secs(a.wait_secs);

        loop {

            if home_identity(&home).is_ok_and(|id| delegated(&id)) {

                break;

            }

            if std::time::Instant::now() >= deadline {

                bail!("{}'s key is not delegated yet: run the command above, then this again", a.name);

            }

            tokio::time::sleep(Duration::from_secs(2)).await;

        }

    }

    let ledger = ctx.writer().await?;

    refresh_owner(&ledger, &home).await?;

    let owner = KeyPair::load_home(&home)?;

    let mut p = identity_payload(&agent.identity);

    p["name"] = a.name.clone().into();

    p["kind"] = a.kind.into();

    p["project"] = a.project.into();

    p["home"] = a.home.display().to_string().into();

    p["owner"] = owner.key.to_hex().into();

    p["owner_name"] = owner.identity.name.clone().into();

    p["scopes"] = DEFAULT_SCOPES.into();

    if let Some(u) = a.uid {

        p["uid"] = u.into();

    }

    p["learn_uid"] = a.learn_uid.into();

    let d = owner.identity.delegate(&agent.key).context("the delegation vanished")?;

    p["delegation"] = serde_json::json!({ "scope": d.scope.names(), "expires": d.expires });

    ledger.append_one(signed_event(&owner, "human", "agent.added", p)).await?;

    ledger.checkpoint().await?;

    println!("{} {} · {}'s agent", ui::done(ui::glyph("✔", "ok")), a.name, owner.identity.name);

    println!("Connect its client with {}.", ui::id(format!("spectra mcp --agent {}", a.name)));

    Ok(0)

}

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

    let ledger = Ledger::open_read_only(&ctx.db()?).await?;

    let p = Principals::load(&ledger).await?;

    let rows: Vec<(String, String, String, String, Option<i64>)> =

        sqlx::query_as("SELECT name, key, kind, project, disabled_ms FROM agents ORDER BY name").fetch_all(ledger.pool()).await?;

    let owner = p.owner();

    let now = now_ms();

    let mut out = Vec::new();

    for (name, key, kind, project, disabled) in rows {

        let k = oxy_core::hash::ObjectRef::from_hex(&key).context("a stored key")?;

        let state = match p.principal(&k, now) {

            Ok(_) => "ok".to_string(),

            Err(why) => why,

        };

        let expires = owner.and_then(|o| o.delegate(&k)).and_then(|d| d.expires);

        let who = match p.principal(&k, now) {

            Ok(pr @ Principal::Agent { .. }) => pr.display(),

            _ => format!("{name} · {}'s agent", owner.map(|o| o.name.as_str()).unwrap_or("?")),

        };

        out.push(serde_json::json!({ "name": name, "display": who, "key": key, "kind": kind, "project": project, "state": state, "delegation_expires": expires, "disabled": disabled.is_some() }));

    }

    if json {

        println!("{}", serde_json::Value::Array(out));

        return Ok(0);

    }

    if out.is_empty() {

        println!("No agents yet: {}", ui::id("spectra agent add NAME --kind KIND --project PROJECT --home DIR"));

    }

    for a in out {

        let state = a["state"].as_str().unwrap_or("");

        let mark = if state == "ok" { ui::ok(ui::glyph("●", "*")) } else { ui::warn(ui::glyph("○", "o")) };

        let until = a["delegation_expires"].as_u64().map(|e| format!(" until {}", super::format::when(e))).unwrap_or_default();

        println!(

            "{mark} {}  {}  {}  {}{until}",

            a["display"].as_str().unwrap_or(""),

            a["kind"].as_str().unwrap_or(""),

            a["project"].as_str().unwrap_or(""),

            ui::hash(&a["key"].as_str().unwrap_or("")[..12])

        );

        if state != "ok" {

            println!("    {}", ui::warn(state));

        }

    }

    Ok(0)

}

pub async fn disable(ctx: &Ctx, name: &str, owner_home_flag: Option<PathBuf>) -> Result<i32> {

    let ledger = ctx.writer().await?;

    let p = Principals::load(&ledger).await?;

    p.agent_key(name).with_context(|| format!("no agent named {name}"))?;

    let home = owner_home(ctx, owner_home_flag);

    refresh_owner(&ledger, &home).await?;

    let owner = KeyPair::load_home(&home)?;

    ledger.append_one(signed_event(&owner, "human", "agent.disabled", serde_json::json!({ "name": name }))).await?;

    ledger.checkpoint().await?;

    println!("{} {name} is disabled; its key is refused from now on", ui::done(ui::glyph("✔", "ok")));

    Ok(0)

}

pub fn valid_name(n: &str) -> bool {

    !n.is_empty()

        && n.len() <= 64

        && n.bytes().next().is_some_and(|b| b.is_ascii_lowercase() || b.is_ascii_digit())

        && n.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')

}

//! `spectra init` and `spectra identity`: the owner and the instance

//! (spec §8.3, §9.5). The owner proves possession of their identity by

//! signing with it; Spectra never holds the owner's secret key.

use super::{ui, Ctx};

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

use oxy_core::identity::Identity;

use spectra_core::keys::KeyPair;

use spectra_core::ledger::Ledger;

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

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

/// The owner's `OXY_HOME`: `--owner-home`, else `[owner] home` in

/// spectra.toml, else oxy's own default.

pub fn owner_home(ctx: &Ctx, flag: Option<PathBuf>) -> PathBuf {

    flag.or_else(|| ctx.config_owner_home()).unwrap_or_else(oxy_core::repo::default_home)

}

pub async fn init(ctx: &Ctx, owner_home_flag: Option<PathBuf>, name: Option<String>) -> Result<i32> {

    let data = &ctx.data;

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

    if db.exists() {

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

    }

    let home = owner_home(ctx, owner_home_flag);

    let owner = KeyPair::load_home(&home).with_context(|| {

        format!("the owner signs with their own identity: none usable in {} (oxy identity create, or --owner-home)", home.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?;

    ledger

        .append(vec![

            signed_event(&owner, "human", "identity.owner", identity_payload(&owner.identity)),

            signed_event(&instance, "system", "identity.instance", identity_payload(&instance.identity)),

        ])

        .await?;

    ledger.checkpoint().await?;

    let home_s = home.display().to_string();

    std::fs::write(

        data.join("spectra.toml"),

        format!("# Spectra's configuration (spec §22.1).\n\n[owner]\nkey = \"{}\"\nhome = {}\n", owner.key.to_hex(), toml_str(&home_s)),

    )?;

    println!("{} Spectra initialised in {}", ui::done(ui::glyph("✔", "ok")), ui::path(data.display()));

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

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

    println!();

    println!("So that checkpoints are verifiably from your machine, delegate to the instance key:");

    println!(

        "  {}",

        ui::id(format!("oxy identity delegate add {} --scope changes", data.join("keys").join("instance.identity").display()))

    );

    println!("Then add agents with {}.", ui::id("spectra agent add NAME --kind KIND --project PROJECT --home DIR"));

    Ok(0)

}

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

    let ledger = Ledger::open_read_only(&ctx.db()?).await?;

    let p = Principals::load(&ledger).await?;

    let owner = p.owner().context("no owner is recorded")?;

    let instance = p.instance();

    let delegated =

        instance.is_some_and(|i| owner.delegates_to(&i.hash(), spectra_core::principals::DELEGATION_SCOPE, spectra_core::ids::now_ms()));

    if json {

        println!(

            "{}",

            serde_json::json!({

                "owner": { "name": owner.name, "key": owner.hash().to_hex() },

                "instance": instance.map(|i| serde_json::json!({ "name": i.name, "key": i.hash().to_hex(), "delegated": delegated })),

            })

        );

        return Ok(0);

    }

    println!("{}", ui::kv("owner", format!("{} <{}> {}", owner.name, owner.email, ui::hash(owner.hash().to_hex()))));

    if let Some(i) = instance {

        let note = if delegated { ui::ok("delegated by the owner") } else { ui::warn("not delegated by the owner yet") };

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

    }

    Ok(0)

}

/// Record the owner's current identity when it has moved on (a delegation

/// added or removed): `spectra identity refresh`.

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

    let ledger = ctx.writer().await?;

    let outcome = refresh_owner(&ledger, &owner_home(ctx, owner_home_flag)).await?;

    ledger.checkpoint().await?;

    match outcome {

        Some(id) => println!("{} recorded the owner's current identity {}", ui::done(ui::glyph("✔", "ok")), ui::hash(id.hash().short(12))),

        None => println!("{} the owner's identity is current", ui::done(ui::glyph("✔", "ok"))),

    }

    Ok(0)

}

/// If the owner's home names a successor of the recorded owner, record it,

/// signed with it, with the identities between. Returns the new identity.

pub async fn refresh_owner(ledger: &Ledger, home: &Path) -> Result<Option<Identity>> {

    let p = Principals::load(ledger).await?;

    let recorded = p.owner().context("no owner is recorded (spectra init)")?.clone();

    let pair = KeyPair::load_home(home)?;

    if pair.key == recorded.hash() {

        return Ok(None);

    }

    let mut chain = Vec::new();

    let mut at = pair.identity.clone();

    while let Some(prev) = at.previous {

        if prev == recorded.hash() {

            break;

        }

        let file = home.join("keys").join(format!("{}.identity", prev.to_hex()));

        at = Identity::decode(

            &std::fs::read(&file).with_context(|| format!("{} is not a successor of the recorded owner", pair.identity.name))?,

        )

        .map_err(|e| anyhow::anyhow!("{}: {e}", file.display()))?;

        chain.push(hex::encode(at.encode()));

        if chain.len() > 1000 {

            bail!("the owner's identity chain is too long to follow");

        }

    }

    if at.previous != Some(recorded.hash()) && pair.identity.previous != Some(recorded.hash()) {

        bail!("{} in {} is not a successor of the recorded owner {}", pair.identity.name, home.display(), recorded.hash().short(12));

    }

    let mut payload = identity_payload(&pair.identity);

    payload["chain"] = chain.into();

    ledger.append_one(signed_event(&pair, "human", "identity.rotated", payload)).await?;

    Ok(Some(pair.identity))

}

fn hostname() -> String {

    std::fs::read_to_string("/etc/hostname")

        .ok()

        .map(|h| h.trim().to_string())

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

        .unwrap_or_else(|| "spectra".into())

}

fn toml_str(s: &str) -> String {

    serde_json::to_string(s).unwrap_or_default()

}

//! The owner and agents from the command line (spec §8.1, §8.3), as the

//! built binary in a hermetic environment: `init` proves the owner's

//! identity, `agent add` refuses until the owner delegates, ownership is

//! shown, and the ledger verifies throughout.

use oxy_core::durable::{write_atomic, write_atomic_private};

use oxy_core::identity::{Delegate, Identity, SecretKey};

use spectra_core::keys::KeyPair;

use spectra_core::principals::DELEGATION_SCOPE;

use std::path::Path;

use std::process::{Command, Output};

fn hermetic(dir: &Path) -> Command {

    let mut c = Command::new(env!("CARGO_BIN_EXE_spectra"));

    c.env("SPECTRA_DATA", dir.join("data"))

        .env("OXY_HOME", dir.join("owner"))

        .env("HOME", dir)

        .env("XDG_DATA_HOME", dir.join("xdg"))

        .env("NO_COLOR", "1");

    c

}

fn run(dir: &Path, args: &[&str]) -> Output {

    hermetic(dir).args(args).output().unwrap()

}

fn text(o: &Output) -> String {

    format!("{}{}", String::from_utf8_lossy(&o.stdout), String::from_utf8_lossy(&o.stderr))

}

/// `oxy identity delegate add IDENTITY --scope changes` in the owner's home.

fn delegate(owner_home: &Path, agent: &Identity) {

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

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

    let (_, secret) = SecretKey::decode(&std::fs::read(keys.join(format!("{}.secret", cur.key.to_hex()))).unwrap()).unwrap();

    let mut d = cur.identity.delegates.clone();

    d.push(Delegate { key: agent.hash(), scope: DELEGATION_SCOPE, expires: None });

    let next = cur.identity.successor(d, None, spectra_core::ids::now_ms());

    let k = next.hash();

    write_atomic_private(&keys.join(format!("{}.secret", k.to_hex())), &secret.encode(&k)).unwrap();

    write_atomic(&keys.join(format!("{}.identity", k.to_hex())), &next.encode()).unwrap();

    oxy_core::repo::Config::set_user(&owner_home.join("config.toml"), "author.key", &k.to_hex()).unwrap();

}

fn verify_clean(dir: &Path) {

    let o = run(dir, &["admin", "verify", "--json"]);

    let v: serde_json::Value = serde_json::from_slice(&o.stdout).unwrap_or_else(|_| panic!("{}", text(&o)));

    assert!(o.status.success() && v["findings"].as_array().unwrap().is_empty(), "{v}");

}

#[test]

fn init_then_an_owned_agent_end_to_end() {

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

    let d = dir.path();

    KeyPair::create_home(&d.join("owner"), "Andy McCall", "[email protected]").unwrap();

    let o = run(d, &["init", "--name", "laptop"]);

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

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

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

    verify_clean(d);

    let home = d.join("agents/claude-oxygen");

    let home_s = home.to_str().unwrap();

    let args = ["agent", "add", "claude-oxygen", "--kind", "claude-code", "--project", "oxygen", "--home", home_s, "--wait", "0"];

    let o = run(d, &args);

    assert!(!o.status.success(), "refused until delegated");

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

    let agent = KeyPair::load_home(&home).unwrap();

    delegate(&d.join("owner"), &agent.identity);

    let o = run(d, &args);

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

    assert!(text(&o).contains("claude-oxygen · Andy McCall's agent"), "{}", text(&o));

    assert_eq!(KeyPair::load_home(&home).unwrap().key, agent.key, "the key made first is the key recorded");

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

    assert_eq!(list[0]["display"], "claude-oxygen · Andy McCall's agent");

    assert_eq!(list[0]["state"], "ok");

    verify_clean(d);

    assert!(run(d, &["agent", "disable", "claude-oxygen"]).status.success());

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

    assert!(list[0]["state"].as_str().unwrap().contains("disabled"), "{list}");

    verify_clean(d);

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

}

#[test]

fn an_owner_without_a_secret_key_cannot_init() {

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

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

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

    assert!(text(&o).contains("the owner signs with their own identity"), "{}", text(&o));

}

#[tokio::test]

async fn a_second_writer_is_refused() {

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

    let d = dir.path();

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

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

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

    let held = spectra_core::ledger::Ledger::open(&d.join("data/spectra.db"), Some(instance)).await.unwrap();

    let o = run(d, &["agent", "disable", "nobody"]);

    assert!(text(&o).contains("another process is writing"), "{}", text(&o));

    assert!(run(d, &["admin", "verify"]).status.success(), "reading needs no lock");

    drop(held);

}

- **Added: identities instead of tokens (#4).** `spectra init` records the owner's Oxygen identity, proven by signing with it, and makes the instance key. `spectra agent add` makes an agent's key pair in its own home and records the agent only once the owner's identity delegates to it (`oxy identity delegate add`), so every agent is somebody's: `claude-oxygen · Andy McCall's agent`. Expiry and `spectra agent disable` stop an agent's key. `spectra admin verify` replays identities and delegations and checks every signed event, refusing an event whose actor is not its signer. Requests are authenticated by signature, a five-minute window, single-use nonces and an optional Unix-user binding. One process writes a ledger at a time.

 "toml",

toml.workspace = true

sqlx.workspace = true