principals.rs 92.0%

343 of 373 lines run, 47 of 110 functions · run #33 on main · run missed

//! 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::identity::Identity;
use crate::identity::KeyId;
use crate::ledger::KeyResolver;
use crate::proof::Proof;
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"];

/// 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", "agent.scoped"],
                    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, 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, 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.uid_bound" => {
                // The daemon binds a learning agent to the uid of its first
                // signed connection; covered by the next checkpoint.
                let name = text(&p, "name")?;
                let uid = p.get("uid").and_then(Json::as_u64).ok_or("no uid")? as u32;
                let key = *self.by_name.get(&name).ok_or("an unknown agent")?;
                if let Some(a) = self.agents.get_mut(&key) {
                    if a.uid.is_none() {
                        a.uid = Some(uid);
                    }
                }
            }
            "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;
                }
            }
            // The owner grants or takes back one scope (spec §8.4), such
            // as `channel:NAME` to post in another project's channel.
            "agent.scoped" => {
                self.owner_signed(e)?;
                let name = text(&p, "name")?;
                let scope = text(&p, "scope")?;
                if !grantable(&scope) {
                    return Err(format!("{scope} is not a scope an agent may be given"));
                }
                let grant = p.get("grant").and_then(Json::as_bool).unwrap_or(true);
                let key = *self.by_name.get(&name).ok_or("an unknown agent")?;
                if let Some(a) = self.agents.get_mut(&key) {
                    a.scopes.retain(|s| s != &scope);
                    if grant {
                        a.scopes.push(scope);
                    }
                }
            }
            _ => {}
        }
        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)
    }

    /// An event from a Radar session: its proof is the owner's signed
    /// request for the sign-in link, so it must verify against the owner,
    /// and only the owner acts this way.
    pub fn check_session(&self, e: &Event) -> Result<(), String> {
        let key = crate::identity::KeyId(e.auth.key.ok_or("a session event names no key")?);
        if !matches!(self.principal(&key, e.hlc.wall_ms)?, Principal::Owner { .. }) || e.actor != "human" {
            return Err("only the owner acts through a Radar session".into());
        }
        let identity = self.identity(&key).ok_or("an unknown key")?;
        let proof = Proof::decode(e.auth.proof.as_deref().ok_or("no proof")?)?;
        if proof.key() != key.0 || proof.method != "POST /radar/link" {
            return Err("the session's proof is not the owner's sign-in request".into());
        }
        proof.verify(identity, None)
    }

    /// 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 = crate::identity::KeyId(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" | "agent.scoped" => {
                if e.auth.method != Method::Signature {
                    return Err(format!("{} must be signed", e.kind));
                }
                self.observe(e)
            }
            "agent.uid_bound" => self.observe(e),
            _ if matches!(e.auth.method, Method::Signature | Method::Passkey) => self.check_signed(e),
            _ if e.auth.method == Method::Session => self.check_session(e),
            _ => Ok(()),
        }
    }
}

/// Apply identity and agent events to the projection tables.
pub async fn project(conn: &mut SqliteConnection, e: &Event) -> sqlx::Result<()> {
    if e.kind == "agent.uid_bound" {
        let p = e.json();
        sqlx::query("UPDATE agents SET uid = ? WHERE name = ? AND uid IS NULL")
            .bind(p.get("uid").and_then(Json::as_i64))
            .bind(p.get("name").and_then(Json::as_str))
            .execute(&mut *conn)
            .await?;
        return Ok(());
    }
    // Who is who is only ever said by a signature; `verify` checks which.
    if e.auth.method != Method::Signature {
        return Ok(());
    }
    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(()) };
            if p.get("name").and_then(Json::as_str).is_none_or(str::is_empty) {
                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?;
        }
        "agent.scoped" if e.actor == "human" => {
            let (Some(name), Some(scope)) = (p.get("name").and_then(Json::as_str), p.get("scope").and_then(Json::as_str)) else {
                return Ok(());
            };
            if !grantable(scope) {
                return Ok(());
            }
            let grant = p.get("grant").and_then(Json::as_bool).unwrap_or(true);
            let current: Option<String> =
                sqlx::query_scalar("SELECT scopes FROM agents WHERE name = ?").bind(name).fetch_optional(&mut *conn).await?;
            let mut scopes: Vec<String> = current.and_then(|s| serde_json::from_str(&s).ok()).unwrap_or_default();
            scopes.retain(|s| s != scope);
            if grant {
                scopes.push(scope.to_string());
            }
            sqlx::query("UPDATE agents SET scopes = ? WHERE name = ?")
                .bind(serde_json::to_string(&scopes).unwrap_or_default())
                .bind(name)
                .execute(&mut *conn)
                .await?;
        }
        _ => {}
    }
    Ok(())
}

/// A scope the owner may give an agent (spec §8.4): never the owner's own
/// authority, only reach.
pub fn grantable(scope: &str) -> bool {
    match scope.strip_prefix("channel:") {
        Some(ch) => !ch.is_empty() && ch.len() <= 64 && ch.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-'),
        None => matches!(scope, "projects:all" | "schedule:any" | "webhooks:read"),
    }
}

/// 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()) })
}

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

1		//! Who is who (spec §8): the owner, the instance, and agents, each an Oxygen
2		//! identity; an agent is valid while the owner's current identity delegates
3		//! to its key (oxygen spec §14.2). Everything here is derived from the
4		//! ledger, and every claim in it was proven when it was recorded:
5		//!
6		//! - `identity.owner` and `identity.rotated` are signed by the identity they
7		//! record, so only the holder of its secret key can name it the owner.
8		//! A successor must keep the key pair and chain back, by `previous`, to
9		//! the owner already known; a fresh key pair needs `oxy identity rotate`'s
10		//! attestation, which 0.1 does not accept yet.
11		//! - `identity.instance` is signed by the instance key.
12		//! - `agent.added` and `agent.disabled` are signed by the owner, and an
13		//! agent is added only while the owner's identity delegates to it.
14		//!
15		//! [`Principals`] replays these in ledger order, so `spectra admin verify`
16		//! checks every signed event against who was who at that moment.
17
18		use crate::event::{Event, Method};
19		use crate::identity::Identity;
20		use crate::identity::KeyId;
21		use crate::ledger::KeyResolver;
22		use crate::proof::Proof;
23		use serde_json::Value as Json;
24		use sqlx::SqliteConnection;
25		use std::collections::HashMap;
26
27		/// The scopes a new agent gets (spec §8.4).
28		pub const DEFAULT_SCOPES: &[&str] = &["read", "say", "tasks", "claims", "decisions", "status", "search", "schedule:self"];
29
30		/// Who caused something.
31		#[derive(Clone, Debug, PartialEq, Eq)]
32		pub enum Principal {
33		Owner { key: KeyId, name: String },
34		Agent { name: String, key: KeyId, owner_name: String, uid: Option<u32>, learn_uid: bool, project: String, scopes: Vec<String> },
35		Instance { key: KeyId },
36		}
37
38		impl Principal {
39		/// The `actor` events carry: `human`, `agent:NAME` or `system`.
40	442×	pub fn actor(&self) -> String {
41	442×	match self {
42	74×	Principal::Owner { .. } => "human".into(),
43	360×	Principal::Agent { name, .. } => format!("agent:{name}"),
44	8×	Principal::Instance { .. } => "system".into(),
45		}
46	442×	}
47		/// How it is shown to people: `claude-oxygen · Andy McCall's agent`.
48	40×	pub fn display(&self) -> String {
49	40×	match self {
50	28×	Principal::Owner { name, .. } => name.clone(),
51	12×	Principal::Agent { name, owner_name, .. } => format!("{name} · {owner_name}'s agent"),
52	0×	Principal::Instance { .. } => "Spectra".into(),
53		}
54	40×	}
55		}
56
57		#[derive(Clone, Debug)]
58		struct AgentRec {
59		name: String,
60		identity: Identity,
61		owner_name: String,
62		uid: Option<u32>,
63		learn_uid: bool,
64		project: String,
65		scopes: Vec<String>,
66		disabled: bool,
67		}
68
69		/// The principals as of some point in the ledger.
70		#[derive(Clone, Debug, Default)]
71		pub struct Principals {
72		/// The owner's identities, oldest first; the last is current.
73		owner: Vec<Identity>,
74		instance: Option<Identity>,
75		agents: HashMap<KeyId, AgentRec>,
76		by_name: HashMap<String, KeyId>,
77		}
78
79		impl Principals {
80		/// Replay every identity and agent event of the ledger.
81	218×	pub async fn load(ledger: &crate::ledger::Ledger) -> anyhow::Result<Principals> {
82	218×	let mut p = Principals::default();
83	218×	let mut from = 1;
84		loop {
85	436×	let rows = ledger
86	436×	.events_of_kinds(
87	436×	from,
88	436×	&["identity.owner", "identity.rotated", "identity.instance", "agent.added", "agent.disabled", "agent.scoped"],
89	436×	1000,
90	436×	)
91	436×	.await?;
92	432×	if rows.is_empty() {
93	214×	break;
94	218×	}
95	825×	for e in &rows {
96	825×	// Recorded facts were checked when written; `verify` checks them again.
97	825×	let _ = p.observe(e);
98	825×	}
99	218×	from = rows.last().map(\|e\| e.seq + 1).unwrap_or(from);
100		}
101	214×	Ok(p)
102	214×	}
103
104		/// The owner's current identity.
105	1003×	pub fn owner(&self) -> Option<&Identity> {
106	1003×	self.owner.last()
107	1003×	}
108
109	32×	pub fn instance(&self) -> Option<&Identity> {
110	32×	self.instance.as_ref()
111	32×	}
112
113		/// The agent named `name`, whatever its state.
114	32×	pub fn agent_key(&self, name: &str) -> Option<KeyId> {
115	32×	self.by_name.get(name).copied()
116	32×	}
117
118		/// Who `key` is at `at_ms`, if anyone may act with it then: the owner
119		/// (any of its identities' KeyIds), the instance, or an agent that is
120		/// not disabled and that the owner's current identity delegates to.
121	376×	pub fn principal(&self, key: &KeyId, at_ms: u64) -> Result<Principal, String> {
122	754×	if let Some(owner) = self.owner.iter().rev().find(\|i\| &i.hash() == key) {
123	150×	return Ok(Principal::Owner { key: *key, name: owner.name.clone() });
124	226×	}
125	226×	if self.instance.as_ref().is_some_and(\|i\| &i.hash() == key) {
126	8×	return Ok(Principal::Instance { key: *key });
127	218×	}
128	218×	let a = self.agents.get(key).ok_or("an unknown key")?;
129	215×	if a.disabled {
130	6×	return Err(format!("agent {} is disabled", a.name));
131	209×	}
132	209×	let owner = self.owner().ok_or("no owner is recorded")?;
133	209×	if !owner.delegates_to(key, at_ms) {
134	1×	return Err(match owner.delegate(key) {
135	1×	Some(d) if d.expires.is_some_and(\|x\| at_ms > x) => format!("agent {}'s delegation from {} has expired", a.name, owner.name),
136	0×	Some(_) => format!("{}'s delegation to agent {} does not include `changes`", owner.name, a.name),
137	0×	None => format!("{}'s current identity does not delegate to agent {}", owner.name, a.name),
138		});
139	208×	}
140	208×	Ok(Principal::Agent {
141	208×	name: a.name.clone(),
142	208×	key: *key,
143	208×	owner_name: a.owner_name.clone(),
144	208×	uid: a.uid,
145	208×	learn_uid: a.learn_uid,
146	208×	project: a.project.clone(),
147	208×	scopes: a.scopes.clone(),
148	208×	})
149	376×	}
150
151		/// The identity behind `key`, for checking its signatures.
152	294×	pub fn identity(&self, key: &KeyId) -> Option<&Identity> {
153	294×	self.owner
154	294×	.iter()
155	722×	.find(\|i\| &i.hash() == key)
156	294×	.or_else(\|\| self.instance.as_ref().filter(\|i\| &i.hash() == key))
157	294×	.or_else(\|\| self.agents.get(key).map(\|a\| &a.identity))
158	294×	}
159
160		/// Take one event into account, checking what it claims first.
161	997×	pub fn observe(&mut self, e: &Event) -> Result<(), String> {
162	997×	let p = e.json();
163	997×	match e.kind.as_str() {
164	997×	"identity.owner" => {
165	250×	if !self.owner.is_empty() {
166	1×	return Err("an owner is already recorded".into());
167	249×	}
168	249×	let id = identity_of(&p)?;
169	249×	self_signed(e, &id)?;
170	249×	self.owner.push(id);
171		}
172	747×	"identity.rotated" => {
173	258×	let new = identity_of(&p)?;
174	258×	let cur = self.owner().ok_or("no owner to succeed")?.clone();
175	258×	accept_successor(&cur, &new, &p)?;
176	258×	self_signed(e, &new)?;
177	257×	self.owner.push(new);
178		}
179	489×	"identity.instance" => {
180	252×	let id = identity_of(&p)?;
181	252×	self_signed(e, &id)?;
182	252×	self.instance = Some(id);
183		}
184	237×	"agent.added" => {
185	213×	let id = identity_of(&p)?;
186	213×	let key = id.hash();
187	213×	let owner = self.owner_signed(e)?;
188	213×	if !owner.delegates_to(&key, e.hlc.wall_ms) {
189	1×	return Err("added without the owner's delegation to its key".into());
190	212×	}
191	212×	let name = text(&p, "name")?;
192	212×	if self.by_name.get(&name).is_some_and(\|k\| *k != key) {
193	0×	return Err(format!("agent {name} already exists with another key"));
194	212×	}
195	212×	self.by_name.insert(name.clone(), key);
196	212×	self.agents.insert(
197	212×	key,
198		AgentRec {
199	212×	name,
200	212×	identity: id,
201	212×	owner_name: owner.name.clone(),
202	212×	uid: p.get("uid").and_then(Json::as_u64).map(\|u\| u as u32),
203	212×	learn_uid: p.get("learn_uid").and_then(Json::as_bool).unwrap_or(false),
204	212×	project: text(&p, "project")?,
205	212×	scopes: p
206	212×	.get("scopes")
207	212×	.and_then(Json::as_array)
208	1600×	.map(\|a\| a.iter().filter_map(\|s\| s.as_str().map(String::from)).collect())
209	212×	.unwrap_or_default(),
210		disabled: false,
211		},
212		);
213		}
214	24×	"agent.uid_bound" => {
215		// The daemon binds a learning agent to the uid of its first
216		// signed connection; covered by the next checkpoint.
217	1×	let name = text(&p, "name")?;
218	1×	let uid = p.get("uid").and_then(Json::as_u64).ok_or("no uid")? as u32;
219	1×	let key = *self.by_name.get(&name).ok_or("an unknown agent")?;
220	1×	if let Some(a) = self.agents.get_mut(&key) {
221	1×	if a.uid.is_none() {
222	1×	a.uid = Some(uid);
223	1×	}
224	0×	}
225		}
226	23×	"agent.disabled" => {
227	11×	self.owner_signed(e)?;
228	11×	let name = text(&p, "name")?;
229	11×	let key = *self.by_name.get(&name).ok_or("an unknown agent")?;
230	11×	if let Some(a) = self.agents.get_mut(&key) {
231	11×	a.disabled = true;
232	11×	}
233		}
234		// The owner grants or takes back one scope (spec §8.4), such
235		// as `channel:NAME` to post in another project's channel.
236	12×	"agent.scoped" => {
237	12×	self.owner_signed(e)?;
238	12×	let name = text(&p, "name")?;
239	12×	let scope = text(&p, "scope")?;
240	12×	if !grantable(&scope) {
241	0×	return Err(format!("{scope} is not a scope an agent may be given"));
242	12×	}
243	12×	let grant = p.get("grant").and_then(Json::as_bool).unwrap_or(true);
244	12×	let key = *self.by_name.get(&name).ok_or("an unknown agent")?;
245	12×	if let Some(a) = self.agents.get_mut(&key) {
246	100×	a.scopes.retain(\|s\| s != &scope);
247	12×	if grant {
248	8×	a.scopes.push(scope);
249	8×	}
250	0×	}
251		}
252	0×	_ => {}
253		}
254	994×	Ok(())
255	997×	}
256
257		/// Check that `e` is signed by the owner's current identity; returns it.
258	236×	fn owner_signed(&self, e: &Event) -> Result<Identity, String> {
259	236×	let owner = self.owner().ok_or("no owner is recorded")?.clone();
260	236×	if e.auth.key != Some(owner.hash().0) {
261	0×	return Err("not signed by the owner's current identity".into());
262	236×	}
263	236×	check_proof(e, &owner)?;
264	236×	Ok(owner)
265	236×	}
266
267		/// An event from a Radar session: its proof is the owner's signed
268		/// request for the sign-in link, so it must verify against the owner,
269		/// and only the owner acts this way.
270	7×	pub fn check_session(&self, e: &Event) -> Result<(), String> {
271	7×	let key = crate::identity::KeyId(e.auth.key.ok_or("a session event names no key")?);
272	7×	if !matches!(self.principal(&key, e.hlc.wall_ms)?, Principal::Owner { .. }) \|\| e.actor != "human" {
273	0×	return Err("only the owner acts through a Radar session".into());
274	7×	}
275	7×	let identity = self.identity(&key).ok_or("an unknown key")?;
276	7×	let proof = Proof::decode(e.auth.proof.as_deref().ok_or("no proof")?)?;
277	7×	if proof.key() != key.0 \|\| proof.method != "POST /radar/link" {
278	0×	return Err("the session's proof is not the owner's sign-in request".into());
279	7×	}
280	7×	proof.verify(identity, None)
281	7×	}
282
283		/// Check a signed event's proof against the principal its key was at
284		/// the event's time.
285	137×	pub fn check_signed(&self, e: &Event) -> Result<(), String> {
286	137×	let key = crate::identity::KeyId(e.auth.key.ok_or("signed, but names no key")?);
287	137×	let who = self.principal(&key, e.hlc.wall_ms)?;
288		// The actor an event names must be the principal that signed it:
289		// an agent's key never makes an event in another's name.
290	135×	if who.actor() != e.actor {
291	2×	return Err(format!("names {} as its actor but is signed by {}", e.actor, who.display()));
292	133×	}
293	133×	let identity = self.identity(&key).ok_or("an unknown key")?;
294	133×	check_proof(e, identity)
295	137×	}
296		}
297
298		impl KeyResolver for Principals {
299	517×	fn check(&mut self, e: &Event) -> Result<(), String> {
300	517×	match e.kind.as_str() {
301	517×	"identity.owner" \| "identity.rotated" \| "identity.instance" \| "agent.added" \| "agent.disabled" \| "agent.scoped" => {
302	173×	if e.auth.method != Method::Signature {
303	2×	return Err(format!("{} must be signed", e.kind));
304	171×	}
305	171×	self.observe(e)
306		}
307	344×	"agent.uid_bound" => self.observe(e),
308	343×	_ if matches!(e.auth.method, Method::Signature \| Method::Passkey) => self.check_signed(e),
309	206×	_ if e.auth.method == Method::Session => self.check_session(e),
310	199×	_ => Ok(()),
311		}
312	517×	}
313		}
314
315		/// Apply identity and agent events to the projection tables.
316	42903×	pub async fn project(conn: &mut SqliteConnection, e: &Event) -> sqlx::Result<()> {
317	42903×	if e.kind == "agent.uid_bound" {
318	1×	let p = e.json();
319	1×	sqlx::query("UPDATE agents SET uid = ? WHERE name = ? AND uid IS NULL")
320	1×	.bind(p.get("uid").and_then(Json::as_i64))
321	1×	.bind(p.get("name").and_then(Json::as_str))
322	1×	.execute(&mut *conn)
323	1×	.await?;
324	1×	return Ok(());
325	42902×	}
326		// Who is who is only ever said by a signature; `verify` checks which.
327	42902×	if e.auth.method != Method::Signature {
328	42046×	return Ok(());
329	856×	}
330	856×	let p = e.json();
331	856×	let id = \|p: &Json\| identity_of(p).ok();
332	856×	match e.kind.as_str() {
333	856×	"identity.owner" \| "identity.rotated" \| "identity.instance" => {
334	185×	let Some(identity) = id(&p) else { return Ok(()) };
335	185×	let role = if e.kind == "identity.instance" { "instance" } else { "owner" };
336	185×	sqlx::query("UPDATE identities SET current = 0 WHERE role = ?").bind(role).execute(&mut *conn).await?;
337	185×	sqlx::query(
338	185×	"INSERT OR REPLACE INTO identities (key, role, name, identity, previous, current, seq) VALUES (?, ?, ?, ?, ?, 1, ?)",
339		)
340	185×	.bind(identity.hash().to_hex())
341	185×	.bind(role)
342	185×	.bind(&identity.name)
343	185×	.bind(identity.encode())
344	185×	.bind(identity.previous.map(\|k\| k.to_hex()))
345	185×	.bind(e.seq as i64)
346	185×	.execute(&mut *conn)
347	185×	.await?;
348		}
349	671×	"agent.added" => {
350	64×	let Some(identity) = id(&p) else { return Ok(()) };
351	64×	if p.get("name").and_then(Json::as_str).is_none_or(str::is_empty) {
352	0×	return Ok(());
353	64×	}
354	384×	let s = \|k: &str\| p.get(k).and_then(Json::as_str).unwrap_or("").to_string();
355	64×	sqlx::query(
356	64×	"INSERT OR REPLACE INTO agents (name, key, owner, owner_name, kind, project, home, uid, learn_uid, scopes, created_ms, disabled_ms, seq) \
357	64×	VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?)",
358		)
359	64×	.bind(s("name"))
360	64×	.bind(identity.hash().to_hex())
361	64×	.bind(s("owner"))
362	64×	.bind(s("owner_name"))
363	64×	.bind(s("kind"))
364	64×	.bind(s("project"))
365	64×	.bind(s("home"))
366	64×	.bind(p.get("uid").and_then(Json::as_i64))
367	64×	.bind(p.get("learn_uid").and_then(Json::as_bool).unwrap_or(false))
368	64×	.bind(p.get("scopes").map(\|v\| v.to_string()).unwrap_or_else(\|\| "[]".into()))
369	64×	.bind(e.at_ms as i64)
370	64×	.bind(e.seq as i64)
371	64×	.execute(&mut *conn)
372	64×	.await?;
373	64×	sqlx::query(
374	64×	"INSERT OR REPLACE INTO identities (key, role, name, identity, previous, current, seq) VALUES (?, 'agent', ?, ?, ?, 1, ?)",
375		)
376	64×	.bind(identity.hash().to_hex())
377	64×	.bind(&identity.name)
378	64×	.bind(identity.encode())
379	64×	.bind(identity.previous.map(\|k\| k.to_hex()))
380	64×	.bind(e.seq as i64)
381	64×	.execute(&mut *conn)
382	64×	.await?;
383		}
384	607×	"agent.disabled" => {
385	4×	sqlx::query("UPDATE agents SET disabled_ms = ? WHERE name = ?")
386	4×	.bind(e.at_ms as i64)
387	4×	.bind(p.get("name").and_then(Json::as_str))
388	4×	.execute(&mut *conn)
389	4×	.await?;
390		}
391	603×	"agent.scoped" if e.actor == "human" => {
392	6×	let (Some(name), Some(scope)) = (p.get("name").and_then(Json::as_str), p.get("scope").and_then(Json::as_str)) else {
393	0×	return Ok(());
394		};
395	6×	if !grantable(scope) {
396	0×	return Ok(());
397	6×	}
398	6×	let grant = p.get("grant").and_then(Json::as_bool).unwrap_or(true);
399	6×	let current: Option<String> =
400	6×	sqlx::query_scalar("SELECT scopes FROM agents WHERE name = ?").bind(name).fetch_optional(&mut *conn).await?;
401	6×	let mut scopes: Vec<String> = current.and_then(\|s\| serde_json::from_str(&s).ok()).unwrap_or_default();
402	51×	scopes.retain(\|s\| s != scope);
403	6×	if grant {
404	3×	scopes.push(scope.to_string());
405	3×	}
406	6×	sqlx::query("UPDATE agents SET scopes = ? WHERE name = ?")
407	6×	.bind(serde_json::to_string(&scopes).unwrap_or_default())
408	6×	.bind(name)
409	6×	.execute(&mut *conn)
410	6×	.await?;
411		}
412	597×	_ => {}
413		}
414	856×	Ok(())
415	42903×	}
416
417		/// A scope the owner may give an agent (spec §8.4): never the owner's own
418		/// authority, only reach.
419	21×	pub fn grantable(scope: &str) -> bool {
420	21×	match scope.strip_prefix("channel:") {
421	241×	Some(ch) => !ch.is_empty() && ch.len() <= 64 && ch.bytes().all(\|b\| b.is_ascii_lowercase() \|\| b.is_ascii_digit() \|\| b == b'-'),
422	0×	None => matches!(scope, "projects:all" \| "schedule:any" \| "webhooks:read"),
423		}
424	21×	}
425
426		/// The payload of an identity event for `identity`.
427	224×	pub fn identity_payload(identity: &Identity) -> Json {
428	224×	serde_json::json!({ "key": identity.hash().to_hex(), "name": identity.name, "identity": hex::encode(identity.encode()) })
429	224×	}
430
431	1221×	fn identity_of(p: &Json) -> Result<Identity, String> {
432	1221×	let b = p.get("identity").and_then(Json::as_str).and_then(\|h\| hex::decode(h).ok()).ok_or("no identity in the event")?;
433	1221×	Identity::decode(&b).map_err(\|e\| format!("malformed identity: {e}"))
434	1221×	}
435
436	460×	fn text(p: &Json, k: &str) -> Result<String, String> {
437	460×	p.get(k).and_then(Json::as_str).map(String::from).ok_or_else(\|\| format!("no {k}"))
438	460×	}
439
440	759×	fn self_signed(e: &Event, id: &Identity) -> Result<(), String> {
441	759×	if e.auth.key != Some(id.hash().0) {
442	1×	return Err("not signed by the identity it records".into());
443	758×	}
444	758×	check_proof(e, id)
445	759×	}
446
447		/// The event's proof verifies against `identity`, and a CLI proof covers
448		/// exactly the event's payload.
449	1127×	fn check_proof(e: &Event, identity: &Identity) -> Result<(), String> {
450	1127×	let proof = Proof::decode(e.auth.proof.as_deref().ok_or("no proof")?)?;
451	1127×	if proof.key() != identity.hash().0 {
452	0×	return Err("the proof is by another key".into());
453	1127×	}
454	1127×	let body = (proof.method == "cli").then(\|\| e.payload.as_deref().unwrap_or(b""));
455	1127×	proof.verify(identity, body)
456	1127×	}
457
458		/// A successor of the owner must keep the key pair and chain back to the
459		/// current identity through `previous` (the intermediate identities, if
460		/// any, are carried in the event as `chain`).
461	258×	fn accept_successor(cur: &Identity, new: &Identity, p: &Json) -> Result<(), String> {
462	258×	if new.ed25519_pk != cur.ed25519_pk \|\| new.mldsa65_pk != cur.mldsa65_pk {
463	0×	return Err("a successor with a fresh key pair needs `oxy identity rotate`'s attestation, not accepted in 0.1".into());
464	258×	}
465	258×	let chain: Vec<Identity> = p
466	258×	.get("chain")
467	258×	.and_then(Json::as_array)
468	258×	.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())
469	258×	.unwrap_or_default();
470	258×	let mut at = new.clone();
471	258×	for _ in 0..=chain.len() {
472	258×	match at.previous {
473	258×	Some(prev) if prev == cur.hash() => return Ok(()),
474	0×	Some(prev) => match chain.iter().find(\|i\| i.hash() == prev) {
475	0×	Some(i) if i.ed25519_pk == cur.ed25519_pk => at = i.clone(),
476	0×	_ => break,
477		},
478	0×	None => break,
479		}
480		}
481	0×	Err("does not succeed the recorded owner".into())
482	258×	}
483
484		/// An event signed by `pair` from the command line: its proof covers the
485		/// canonical payload, so the event's content is bound to the signature.
486	275×	pub fn signed_event(pair: &crate::keys::KeyPair, actor: &str, kind: &str, payload: Json) -> crate::event::NewEvent {
487	275×	let body = crate::event::canonical_json(&payload);
488	275×	let proof = Proof::sign(pair, "cli", &body);
489	275×	crate::event::NewEvent::system(kind, payload)
490	275×	.by(actor, crate::event::Auth { key: Some(pair.key.0), method: Method::Signature, assurance: 2, proof: Some(proof.encode()) })
491	275×	}

Coverage / crates/spectra-core/src/principals.rs 92.0%

Keyboard