event.rs 94.2%

161 of 171 lines run, 50 of 61 functions · run #8 on main · run missed

//! The event envelope (spec §9.1) and how it is encoded and hashed (§9.5).
//!
//! An event's body is deterministic CBOR with integer keys, through
//! `oxy-core`'s encoder, exactly as Oxygen encodes its objects (oxygen spec
//! §5.1); its hash is `BLAKE3("spectra1 event " || len || 0x00 || body)`, the
//! domain-separated form of oxygen spec §5.2. The hash and the proof are not
//! in the body: signatures sit outside what they sign (oxygen spec §5.4).
//!
//! The envelope is frozen from the first release: fields may be added at new
//! keys, never changed or removed, so a hub merges logs from any version.

use crate::hlc::Hlc;
use oxy_core::cbor::{self, Value};

/// The envelope's version, key 0 of the body.
pub const ENVELOPE_VERSION: u64 = 1;

/// The field names of the envelope, in order: the frozen set (spec §9.1).
pub const ENVELOPE_FIELDS: &[&str] =
    &["seq", "id", "at_ms", "hlc", "prev", "hash", "auth", "kind", "actor", "session", "project", "subject", "payload", "trace"];

/// How the event's cause was authenticated (spec §8.5).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Method {
    /// Made by Spectra itself (presence timers, checkpoints of its own);
    /// covered by the next checkpoint's signature.
    System = 0,
    /// A bearer token: possession only.
    Token = 1,
    /// A request signed with a key on disk.
    Signature = 2,
    /// A passkey assertion with user presence.
    Passkey = 3,
}

impl Method {
    pub fn from_u8(n: u8) -> Option<Method> {
        Some(match n {
            0 => Method::System,
            1 => Method::Token,
            2 => Method::Signature,
            3 => Method::Passkey,
            _ => return None,
        })
    }
    pub fn name(self) -> &'static str {
        match self {
            Method::System => "system",
            Method::Token => "token",
            Method::Signature => "signature",
            Method::Passkey => "passkey",
        }
    }
}

/// Who caused an event and the proof of it. `key` and the assurance level
/// are hashed; `proof` is carried beside the hash.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Auth {
    pub key: Option<[u8; 32]>,
    pub method: Method,
    /// 0 for system events, else 1 to 3 (spec §8.5).
    pub assurance: u8,
    pub proof: Option<Vec<u8>>,
}

impl Auth {
    /// An event Spectra makes itself.
    pub fn system() -> Auth {
        Auth { key: None, method: Method::System, assurance: 0, proof: None }
    }
}

/// An event before it is appended: what the caller decides.
#[derive(Clone, Debug)]
pub struct NewEvent {
    pub kind: String,
    pub actor: String,
    pub session: Option<String>,
    pub project: Option<String>,
    pub subject: Option<String>,
    pub payload: serde_json::Value,
    pub trace: Option<String>,
    pub auth: Auth,
}

impl NewEvent {
    /// A system event of `kind` with `payload`.
    pub fn system(kind: &str, payload: serde_json::Value) -> NewEvent {
        NewEvent {
            kind: kind.into(),
            actor: "system".into(),
            session: None,
            project: None,
            subject: None,
            payload,
            trace: None,
            auth: Auth::system(),
        }
    }
    pub fn subject(mut self, s: impl Into<String>) -> NewEvent {
        self.subject = Some(s.into());
        self
    }
    pub fn project(mut self, p: impl Into<String>) -> NewEvent {
        self.project = Some(p.into());
        self
    }
    pub fn session(mut self, s: impl Into<String>) -> NewEvent {
        self.session = Some(s.into());
        self
    }
    pub fn by(mut self, actor: impl Into<String>, auth: Auth) -> NewEvent {
        self.actor = actor.into();
        self.auth = auth;
        self
    }
}

/// An event in the ledger.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Event {
    pub seq: u64,
    pub id: String,
    pub at_ms: u64,
    pub hlc: Hlc,
    pub prev: [u8; 32],
    pub hash: [u8; 32],
    pub auth: Auth,
    pub kind: String,
    pub actor: String,
    pub session: Option<String>,
    pub project: Option<String>,
    pub subject: Option<String>,
    /// Canonical JSON (sorted keys, no whitespace), hashed as stored;
    /// `None` once pruned to a stub.
    pub payload: Option<Vec<u8>>,
    pub trace: Option<String>,
}

impl Event {
    /// The payload as JSON (`null` for a stub).
    pub fn json(&self) -> serde_json::Value {
        self.payload.as_deref().and_then(|b| serde_json::from_slice(b).ok()).unwrap_or(serde_json::Value::Null)
    }

    /// The canonical body: every envelope field but `hash` and the proof.
    pub fn body(&self) -> Vec<u8> {
        let opt = |s: &Option<String>| s.as_ref().map(|t| Value::Text(t.clone())).unwrap_or(Value::Null);
        cbor::encode(&Value::map([
            (0, Value::Uint(ENVELOPE_VERSION)),
            (1, Value::Uint(self.seq)),
            (2, Value::Text(self.id.clone())),
            (3, Value::Uint(self.at_ms)),
            (4, Value::Array(vec![Value::Uint(self.hlc.wall_ms), Value::Uint(self.hlc.logical as u64)])),
            (5, Value::Bytes(self.prev.to_vec())),
            (
                6,
                Value::map([
                    (0, self.auth.key.map(|k| Value::Bytes(k.to_vec())).unwrap_or(Value::Null)),
                    (1, Value::Uint(self.auth.method as u64)),
                    (2, Value::Uint(self.auth.assurance as u64)),
                ]),
            ),
            (7, Value::Text(self.kind.clone())),
            (8, Value::Text(self.actor.clone())),
            (9, opt(&self.session)),
            (10, opt(&self.project)),
            (11, opt(&self.subject)),
            (12, self.payload.as_ref().map(|p| Value::Bytes(p.clone())).unwrap_or(Value::Null)),
            (13, opt(&self.trace)),
        ]))
    }

    /// The hash this event's fields give; equal to `hash` unless edited.
    pub fn computed_hash(&self) -> [u8; 32] {
        hash_body(&self.body())
    }
}

/// `BLAKE3("spectra1 event " || decimal(len) || 0x00 || body)`.
pub fn hash_body(body: &[u8]) -> [u8; 32] {
    let mut h = blake3::Hasher::new();
    h.update(b"spectra1 event ");
    h.update(body.len().to_string().as_bytes());
    h.update(&[0]);
    h.update(body);
    *h.finalize().as_bytes()
}

/// Plain BLAKE3 of some bytes (a request body's hash in a proof).
pub fn hash_body_plain(b: &[u8]) -> Box<[u8; 32]> {
    Box::new(*blake3::hash(b).as_bytes())
}

/// JSON with object keys sorted at every level and no whitespace, so equal
/// payloads are equal bytes whatever built them.
pub fn canonical_json(v: &serde_json::Value) -> Vec<u8> {
    fn sort(v: &serde_json::Value) -> serde_json::Value {
        match v {
            serde_json::Value::Object(m) => {
                let mut keys: Vec<&String> = m.keys().collect();
                keys.sort();
                let mut out = serde_json::Map::new();
                for k in keys {
                    out.insert(k.clone(), sort(&m[k]));
                }
                serde_json::Value::Object(out)
            }
            serde_json::Value::Array(a) => serde_json::Value::Array(a.iter().map(sort).collect()),
            other => other.clone(),
        }
    }
    serde_json::to_vec(&sort(v)).expect("JSON values always serialise")
}

#[cfg(test)]
mod tests {
    use super::*;

    fn sample() -> Event {
        Event {
            seq: 7,
            id: "01J0000000000000000000000Z".into(),
            at_ms: 1_700_000_000_000,
            hlc: Hlc { wall_ms: 1_700_000_000_000, logical: 2 },
            prev: [9; 32],
            hash: [0; 32],
            auth: Auth { key: Some([1; 32]), method: Method::Signature, assurance: 2, proof: Some(vec![5, 5]) },
            kind: "message.posted".into(),
            actor: "agent:claude-oxygen".into(),
            session: None,
            project: Some("oxygen".into()),
            subject: Some("m1".into()),
            payload: Some(canonical_json(&serde_json::json!({"b": 1, "a": [{"z": 1, "y": 2}]}))),
            trace: None,
        }
    }

    #[test]
    fn every_field_but_the_proof_changes_the_hash() {
        let e = sample();
        let h = e.computed_hash();
        let mut p = e.clone();
        p.auth.proof = None;
        assert_eq!(p.computed_hash(), h, "the proof is outside the hash");
        type Edit = Box<dyn Fn(&mut Event)>;
        let edits: Vec<Edit> = vec![
            Box::new(|e| e.seq += 1),
            Box::new(|e| e.id.push('X')),
            Box::new(|e| e.at_ms += 1),
            Box::new(|e| e.hlc.logical += 1),
            Box::new(|e| e.prev[0] ^= 1),
            Box::new(|e| e.auth.key = None),
            Box::new(|e| e.auth.assurance = 3),
            Box::new(|e| e.auth.method = Method::Token),
            Box::new(|e| e.kind.push('x')),
            Box::new(|e| e.actor.push('x')),
            Box::new(|e| e.session = Some("s".into())),
            Box::new(|e| e.project = None),
            Box::new(|e| e.subject = None),
            Box::new(|e| e.payload = Some(b"{}".to_vec())),
            Box::new(|e| e.trace = Some("t".into())),
        ];
        for edit in edits {
            let mut x = e.clone();
            edit(&mut x);
            assert_ne!(x.computed_hash(), h);
        }
    }

    #[test]
    fn canonical_json_sorts_keys_at_every_level() {
        let a = canonical_json(&serde_json::json!({"b": 1, "a": {"d": 1, "c": 2}}));
        assert_eq!(a, br#"{"a":{"c":2,"d":1},"b":1}"#);
    }

    #[test]
    fn the_envelope_is_frozen() {
        assert_eq!(
            ENVELOPE_FIELDS.join(","),
            "seq,id,at_ms,hlc,prev,hash,auth,kind,actor,session,project,subject,payload,trace",
            "the envelope is frozen at 0.1: add fields at new keys, never change these (spec §9.1)"
        );
        assert_eq!(ENVELOPE_VERSION, 1);
    }
}

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

1		//! The event envelope (spec §9.1) and how it is encoded and hashed (§9.5).
2		//!
3		//! An event's body is deterministic CBOR with integer keys, through
4		//! `oxy-core`'s encoder, exactly as Oxygen encodes its objects (oxygen spec
5		//! §5.1); its hash is `BLAKE3("spectra1 event " \|\| len \|\| 0x00 \|\| body)`, the
6		//! domain-separated form of oxygen spec §5.2. The hash and the proof are not
7		//! in the body: signatures sit outside what they sign (oxygen spec §5.4).
8		//!
9		//! The envelope is frozen from the first release: fields may be added at new
10		//! keys, never changed or removed, so a hub merges logs from any version.
11
12		use crate::hlc::Hlc;
13		use oxy_core::cbor::{self, Value};
14
15		/// The envelope's version, key 0 of the body.
16		pub const ENVELOPE_VERSION: u64 = 1;
17
18		/// The field names of the envelope, in order: the frozen set (spec §9.1).
19		pub const ENVELOPE_FIELDS: &[&str] =
20		&["seq", "id", "at_ms", "hlc", "prev", "hash", "auth", "kind", "actor", "session", "project", "subject", "payload", "trace"];
21
22		/// How the event's cause was authenticated (spec §8.5).
23		#[derive(Clone, Copy, Debug, PartialEq, Eq)]
24		pub enum Method {
25		/// Made by Spectra itself (presence timers, checkpoints of its own);
26		/// covered by the next checkpoint's signature.
27		System = 0,
28		/// A bearer token: possession only.
29		Token = 1,
30		/// A request signed with a key on disk.
31		Signature = 2,
32		/// A passkey assertion with user presence.
33		Passkey = 3,
34		}
35
36		impl Method {
37	41257×	pub fn from_u8(n: u8) -> Option<Method> {
38	41257×	Some(match n {
39	40658×	0 => Method::System,
40	0×	1 => Method::Token,
41	599×	2 => Method::Signature,
42	0×	3 => Method::Passkey,
43	0×	_ => return None,
44		})
45	41257×	}
46	0×	pub fn name(self) -> &'static str {
47	0×	match self {
48	0×	Method::System => "system",
49	0×	Method::Token => "token",
50	0×	Method::Signature => "signature",
51	0×	Method::Passkey => "passkey",
52		}
53	0×	}
54		}
55
56		/// Who caused an event and the proof of it. `key` and the assurance level
57		/// are hashed; `proof` is carried beside the hash.
58		#[derive(Clone, Debug, PartialEq, Eq)]
59		pub struct Auth {
60		pub key: Option<[u8; 32]>,
61		pub method: Method,
62		/// 0 for system events, else 1 to 3 (spec §8.5).
63		pub assurance: u8,
64		pub proof: Option<Vec<u8>>,
65		}
66
67		impl Auth {
68		/// An event Spectra makes itself.
69	11666×	pub fn system() -> Auth {
70	11666×	Auth { key: None, method: Method::System, assurance: 0, proof: None }
71	11666×	}
72		}
73
74		/// An event before it is appended: what the caller decides.
75		#[derive(Clone, Debug)]
76		pub struct NewEvent {
77		pub kind: String,
78		pub actor: String,
79		pub session: Option<String>,
80		pub project: Option<String>,
81		pub subject: Option<String>,
82		pub payload: serde_json::Value,
83		pub trace: Option<String>,
84		pub auth: Auth,
85		}
86
87		impl NewEvent {
88		/// A system event of `kind` with `payload`.
89	11665×	pub fn system(kind: &str, payload: serde_json::Value) -> NewEvent {
90	11665×	NewEvent {
91	11665×	kind: kind.into(),
92	11665×	actor: "system".into(),
93	11665×	session: None,
94	11665×	project: None,
95	11665×	subject: None,
96	11665×	payload,
97	11665×	trace: None,
98	11665×	auth: Auth::system(),
99	11665×	}
100	11665×	}
101	1414×	pub fn subject(mut self, s: impl Into<String>) -> NewEvent {
102	1414×	self.subject = Some(s.into());
103	1414×	self
104	1414×	}
105	10×	pub fn project(mut self, p: impl Into<String>) -> NewEvent {
106	10×	self.project = Some(p.into());
107	10×	self
108	10×	}
109	8×	pub fn session(mut self, s: impl Into<String>) -> NewEvent {
110	8×	self.session = Some(s.into());
111	8×	self
112	8×	}
113	211×	pub fn by(mut self, actor: impl Into<String>, auth: Auth) -> NewEvent {
114	211×	self.actor = actor.into();
115	211×	self.auth = auth;
116	211×	self
117	211×	}
118		}
119
120		/// An event in the ledger.
121		#[derive(Clone, Debug, PartialEq, Eq)]
122		pub struct Event {
123		pub seq: u64,
124		pub id: String,
125		pub at_ms: u64,
126		pub hlc: Hlc,
127		pub prev: [u8; 32],
128		pub hash: [u8; 32],
129		pub auth: Auth,
130		pub kind: String,
131		pub actor: String,
132		pub session: Option<String>,
133		pub project: Option<String>,
134		pub subject: Option<String>,
135		/// Canonical JSON (sorted keys, no whitespace), hashed as stored;
136		/// `None` once pruned to a stub.
137		pub payload: Option<Vec<u8>>,
138		pub trace: Option<String>,
139		}
140
141		impl Event {
142		/// The payload as JSON (`null` for a stub).
143	88358×	pub fn json(&self) -> serde_json::Value {
144	88358×	self.payload.as_deref().and_then(\|b\| serde_json::from_slice(b).ok()).unwrap_or(serde_json::Value::Null)
145	88358×	}
146
147		/// The canonical body: every envelope field but `hash` and the proof.
148	22346×	pub fn body(&self) -> Vec<u8> {
149	89384×	let opt = \|s: &Option<String>\| s.as_ref().map(\|t\| Value::Text(t.clone())).unwrap_or(Value::Null);
150	22346×	cbor::encode(&Value::map([
151	22346×	(0, Value::Uint(ENVELOPE_VERSION)),
152	22346×	(1, Value::Uint(self.seq)),
153	22346×	(2, Value::Text(self.id.clone())),
154	22346×	(3, Value::Uint(self.at_ms)),
155	22346×	(4, Value::Array(vec![Value::Uint(self.hlc.wall_ms), Value::Uint(self.hlc.logical as u64)])),
156	22346×	(5, Value::Bytes(self.prev.to_vec())),
157		(
158		6,
159	22346×	Value::map([
160	22346×	(0, self.auth.key.map(\|k\| Value::Bytes(k.to_vec())).unwrap_or(Value::Null)),
161	22346×	(1, Value::Uint(self.auth.method as u64)),
162	22346×	(2, Value::Uint(self.auth.assurance as u64)),
163		]),
164		),
165	22346×	(7, Value::Text(self.kind.clone())),
166	22346×	(8, Value::Text(self.actor.clone())),
167	22346×	(9, opt(&self.session)),
168	22346×	(10, opt(&self.project)),
169	22346×	(11, opt(&self.subject)),
170	22346×	(12, self.payload.as_ref().map(\|p\| Value::Bytes(p.clone())).unwrap_or(Value::Null)),
171	22346×	(13, opt(&self.trace)),
172		]))
173	22346×	}
174
175		/// The hash this event's fields give; equal to `hash` unless edited.
176	22346×	pub fn computed_hash(&self) -> [u8; 32] {
177	22346×	hash_body(&self.body())
178	22346×	}
179		}
180
181		/// `BLAKE3("spectra1 event " \|\| decimal(len) \|\| 0x00 \|\| body)`.
182	22346×	pub fn hash_body(body: &[u8]) -> [u8; 32] {
183	22346×	let mut h = blake3::Hasher::new();
184	22346×	h.update(b"spectra1 event ");
185	22346×	h.update(body.len().to_string().as_bytes());
186	22346×	h.update(&[0]);
187	22346×	h.update(body);
188	22346×	*h.finalize().as_bytes()
189	22346×	}
190
191		/// Plain BLAKE3 of some bytes (a request body's hash in a proof).
192	12×	pub fn hash_body_plain(b: &[u8]) -> Box<[u8; 32]> {
193	12×	Box::new(*blake3::hash(b).as_bytes())
194	12×	}
195
196		/// JSON with object keys sorted at every level and no whitespace, so equal
197		/// payloads are equal bytes whatever built them.
198	11789×	pub fn canonical_json(v: &serde_json::Value) -> Vec<u8> {
199	36569×	fn sort(v: &serde_json::Value) -> serde_json::Value {
200	36569×	match v {
201	11802×	serde_json::Value::Object(m) => {
202	11802×	let mut keys: Vec<&String> = m.keys().collect();
203	11802×	keys.sort();
204	11802×	let mut out = serde_json::Map::new();
205	24536×	for k in keys {
206	24536×	out.insert(k.clone(), sort(&m[k]));
207	24536×	}
208	11802×	serde_json::Value::Object(out)
209		}
210	231×	serde_json::Value::Array(a) => serde_json::Value::Array(a.iter().map(sort).collect()),
211	24536×	other => other.clone(),
212		}
213	36569×	}
214	11789×	serde_json::to_vec(&sort(v)).expect("JSON values always serialise")
215	11789×	}
216
217		#[cfg(test)]
218		mod tests {
219		use super::*;
220
221	1×	fn sample() -> Event {
222	1×	Event {
223	1×	seq: 7,
224	1×	id: "01J0000000000000000000000Z".into(),
225	1×	at_ms: 1_700_000_000_000,
226	1×	hlc: Hlc { wall_ms: 1_700_000_000_000, logical: 2 },
227	1×	prev: [9; 32],
228	1×	hash: [0; 32],
229	1×	auth: Auth { key: Some([1; 32]), method: Method::Signature, assurance: 2, proof: Some(vec![5, 5]) },
230	1×	kind: "message.posted".into(),
231	1×	actor: "agent:claude-oxygen".into(),
232	1×	session: None,
233	1×	project: Some("oxygen".into()),
234	1×	subject: Some("m1".into()),
235	1×	payload: Some(canonical_json(&serde_json::json!({"b": 1, "a": [{"z": 1, "y": 2}]}))),
236	1×	trace: None,
237	1×	}
238	1×	}
239
240		#[test]
241	1×	fn every_field_but_the_proof_changes_the_hash() {
242	1×	let e = sample();
243	1×	let h = e.computed_hash();
244	1×	let mut p = e.clone();
245	1×	p.auth.proof = None;
246	1×	assert_eq!(p.computed_hash(), h, "the proof is outside the hash");
247		type Edit = Box<dyn Fn(&mut Event)>;
248	1×	let edits: Vec<Edit> = vec![
249	1×	Box::new(\|e\| e.seq += 1),
250	1×	Box::new(\|e\| e.id.push('X')),
251	1×	Box::new(\|e\| e.at_ms += 1),
252	1×	Box::new(\|e\| e.hlc.logical += 1),
253	1×	Box::new(\|e\| e.prev[0] ^= 1),
254	1×	Box::new(\|e\| e.auth.key = None),
255	1×	Box::new(\|e\| e.auth.assurance = 3),
256	1×	Box::new(\|e\| e.auth.method = Method::Token),
257	1×	Box::new(\|e\| e.kind.push('x')),
258	1×	Box::new(\|e\| e.actor.push('x')),
259	1×	Box::new(\|e\| e.session = Some("s".into())),
260	1×	Box::new(\|e\| e.project = None),
261	1×	Box::new(\|e\| e.subject = None),
262	1×	Box::new(\|e\| e.payload = Some(b"{}".to_vec())),
263	1×	Box::new(\|e\| e.trace = Some("t".into())),
264		];
265	15×	for edit in edits {
266	15×	let mut x = e.clone();
267	15×	edit(&mut x);
268	15×	assert_ne!(x.computed_hash(), h);
269		}
270	1×	}
271
272		#[test]
273	1×	fn canonical_json_sorts_keys_at_every_level() {
274	1×	let a = canonical_json(&serde_json::json!({"b": 1, "a": {"d": 1, "c": 2}}));
275	1×	assert_eq!(a, br#"{"a":{"c":2,"d":1},"b":1}"#);
276	1×	}
277
278		#[test]
279	1×	fn the_envelope_is_frozen() {
280	1×	assert_eq!(
281	1×	ENVELOPE_FIELDS.join(","),
282		"seq,id,at_ms,hlc,prev,hash,auth,kind,actor,session,project,subject,payload,trace",
283		"the envelope is frozen at 0.1: add fields at new keys, never change these (spec §9.1)"
284		);
285	1×	assert_eq!(ENVELOPE_VERSION, 1);
286	1×	}
287		}

Coverage / crates/spectra-core/src/event.rs 94.2%

Keyboard