1use std::path::{Path, PathBuf};
35use std::sync::Arc;
36
37use async_trait::async_trait;
38use cellos_core::ports::EventSink;
39use cellos_core::{
40 sign_event_with, verify_signed_event_envelope, CellosError, CloudEventV1,
41 SignedEventEnvelopeV1, Signer, TrustAnchorPublicKey,
42};
43use cellos_sink_jsonl::{AuditChain, AuditRow, ZERO_HASH};
44use std::collections::HashMap;
45use tokio::sync::Mutex;
46
47pub const SEGMENT_SEALED_EVENT_TYPE: &str = "dev.cellos.events.cell.audit.v1.segment-sealed";
49
50pub mod bundle;
51pub use bundle::{
52 export_bundle, import_bundle, verify_chain, AuditBundle, AuditBundleManifest, ChainStatus,
53};
54
55pub mod forwarder;
56pub use forwarder::{ChainForwarder, ForwardOutcome, RowPublisher};
57
58pub struct SpoolEventSink {
61 chain: AuditChain,
62 inner: Option<Arc<dyn EventSink>>,
63 lock: Mutex<()>,
66}
67
68impl SpoolEventSink {
69 pub fn new(audit_path: impl Into<PathBuf>) -> Result<Self, CellosError> {
76 let path = audit_path.into();
77 let chain = AuditChain::open(&path)
78 .map_err(|e| CellosError::EventSink(format!("spool open {}: {e}", path.display())))?;
79 Ok(Self {
80 chain,
81 inner: None,
82 lock: Mutex::new(()),
83 })
84 }
85
86 #[must_use]
89 pub fn with_inner(mut self, inner: Arc<dyn EventSink>) -> Self {
90 self.inner = Some(inner);
91 self
92 }
93
94 #[must_use]
96 pub fn jsonl_path(&self) -> &Path {
97 self.chain.jsonl_path()
98 }
99
100 pub fn verify(&self) -> std::io::Result<Vec<AuditRow>> {
106 self.chain.verify()
107 }
108
109 #[must_use]
111 pub fn sig_path(&self) -> PathBuf {
112 self.chain.jsonl_path().with_file_name("audit-trail.sig")
113 }
114
115 pub async fn seal(
127 &self,
128 chain_id: &str,
129 signer: &dyn Signer,
130 ) -> Result<SignedEventEnvelopeV1, CellosError> {
131 let _guard = self.lock.lock().await;
132 let rows = self
133 .chain
134 .verify()
135 .map_err(|e| CellosError::EventSink(format!("spool seal: chain verify: {e}")))?;
136 let head = rows
137 .last()
138 .map_or_else(|| ZERO_HASH.to_string(), |r| r.row_hash.clone());
139 let last_seq = rows.len() as u64;
140 let event = CloudEventV1 {
141 specversion: "1.0".into(),
142 id: format!("seal-{chain_id}-{last_seq}"),
143 source: "cellos-sink-spool".into(),
144 ty: SEGMENT_SEALED_EVENT_TYPE.into(),
145 datacontenttype: Some("application/json".into()),
146 data: Some(serde_json::json!({
147 "chainId": chain_id,
148 "lastSeq": last_seq,
149 "headRowHash": head,
150 "integrity": "blake3-chain+ed25519-head",
151 })),
152 time: None,
153 traceparent: None,
154 cex: None,
155 };
156 let envelope = sign_event_with(signer, &event)?;
157 let sig_json = serde_json::to_string(&envelope)
158 .map_err(|e| CellosError::EventSink(format!("spool seal: serialize sig: {e}")))?;
159 let tmp = self.sig_path().with_extension("sig.tmp");
161 std::fs::write(&tmp, sig_json)
162 .map_err(|e| CellosError::EventSink(format!("spool seal: write sig: {e}")))?;
163 std::fs::rename(&tmp, self.sig_path())
164 .map_err(|e| CellosError::EventSink(format!("spool seal: rename sig: {e}")))?;
165 Ok(envelope)
166 }
167
168 pub fn verify_sealed_head(
179 &self,
180 verifying_keys: &HashMap<String, TrustAnchorPublicKey>,
181 ) -> Result<(), CellosError> {
182 let rows = self
183 .chain
184 .verify()
185 .map_err(|e| CellosError::EventSink(format!("spool sealed-head: chain verify: {e}")))?;
186 let head = rows
187 .last()
188 .map_or_else(|| ZERO_HASH.to_string(), |r| r.row_hash.clone());
189 let raw = std::fs::read_to_string(self.sig_path())
190 .map_err(|e| CellosError::EventSink(format!("spool sealed-head: read sig: {e}")))?;
191 let envelope: SignedEventEnvelopeV1 = serde_json::from_str(&raw)
192 .map_err(|e| CellosError::EventSink(format!("spool sealed-head: parse sig: {e}")))?;
193 let empty: HashMap<String, Vec<u8>> = HashMap::new();
194 let event = verify_signed_event_envelope(&envelope, verifying_keys, &empty)?;
195 let sealed_head = event
196 .data
197 .as_ref()
198 .and_then(|d| d.get("headRowHash"))
199 .and_then(|v| v.as_str())
200 .unwrap_or_default();
201 if sealed_head != head {
202 return Err(CellosError::EventSink(format!(
203 "spool sealed-head: sealed head {sealed_head} != chain head {head} \
204 (chain advanced or tampered since seal)"
205 )));
206 }
207 Ok(())
208 }
209}
210
211#[async_trait]
212impl EventSink for SpoolEventSink {
213 async fn emit(&self, event: &CloudEventV1) -> Result<(), CellosError> {
214 let body = serde_json::to_value(event)
215 .map_err(|e| CellosError::EventSink(format!("spool serialize body: {e}")))?;
216 let ty = event.ty.clone();
217
218 {
221 let _guard = self.lock.lock().await;
222 self.chain
223 .append(&ty, body)
224 .map_err(|e| CellosError::EventSink(format!("spool append: {e}")))?;
225 }
226
227 if let Some(inner) = &self.inner {
231 if let Err(e) = inner.emit(event).await {
232 tracing::warn!(
233 error = %e,
234 "spool: inner transport emit failed; event is durably spooled"
235 );
236 }
237 }
238 Ok(())
239 }
240
241 async fn flush(&self) -> Result<(), CellosError> {
242 match &self.inner {
243 Some(inner) => inner.flush().await,
244 None => Ok(()),
245 }
246 }
247}
248
249#[cfg(test)]
250mod tests {
251 use super::*;
252 use serde_json::json;
253
254 fn ev(id: &str) -> CloudEventV1 {
255 CloudEventV1 {
256 specversion: "1.0".into(),
257 id: id.into(),
258 source: "cellos-test".into(),
259 ty: "dev.cellos.events.cell.lifecycle.v1.started".into(),
260 datacontenttype: Some("application/json".into()),
261 data: Some(json!({ "cellId": "c1", "specId": "s1" })),
262 time: Some("2026-06-23T00:00:00Z".into()),
263 traceparent: None,
264 cex: None,
265 }
266 }
267
268 struct FailingSink;
271 #[async_trait]
272 impl EventSink for FailingSink {
273 async fn emit(&self, _event: &CloudEventV1) -> Result<(), CellosError> {
274 Err(CellosError::EventSink("transport down".into()))
275 }
276 }
277
278 #[tokio::test]
279 async fn emit_persists_verifiable_row_even_when_inner_errs() {
280 let dir = tempfile::tempdir().expect("tmpdir");
281 let sink = SpoolEventSink::new(dir.path().join("spool"))
282 .expect("open spool")
283 .with_inner(Arc::new(FailingSink));
284
285 sink.emit(&ev("e1"))
287 .await
288 .expect("emit succeeds despite transport failure");
289
290 let rows = sink.verify().expect("chain verifies");
291 assert_eq!(rows.len(), 1, "one durable row persisted");
292 assert_eq!(rows[0].event, "dev.cellos.events.cell.lifecycle.v1.started");
293 }
294
295 #[tokio::test]
296 async fn second_emit_chains_prev_hash() {
297 let dir = tempfile::tempdir().expect("tmpdir");
298 let sink = SpoolEventSink::new(dir.path().join("spool")).expect("open spool");
299
300 sink.emit(&ev("e1")).await.expect("emit 1");
301 sink.emit(&ev("e2")).await.expect("emit 2");
302
303 let rows = sink.verify().expect("chain verifies");
304 assert_eq!(rows.len(), 2);
305 assert_eq!(
306 rows[1].prev_hash, rows[0].row_hash,
307 "the second row chains its prev_hash to the first row's row_hash"
308 );
309 }
310
311 #[tokio::test]
312 async fn row_is_on_disk_after_emit() {
313 let dir = tempfile::tempdir().expect("tmpdir");
316 let sink = SpoolEventSink::new(dir.path().join("spool")).expect("open spool");
317 sink.emit(&ev("e1")).await.expect("emit");
318
319 let reopened = AuditChain::open(&dir.path().join("spool")).expect("reopen");
320 let rows = reopened.verify().expect("reopened chain verifies");
321 assert_eq!(rows.len(), 1, "row durably on disk after emit");
322 }
323
324 #[tokio::test]
325 async fn sealed_segment_head_verifies_offline_and_tamper_fails() {
326 use cellos_core::SoftwareSigner;
327
328 let dir = tempfile::tempdir().expect("tmpdir");
329 let sink = SpoolEventSink::new(dir.path().join("spool")).expect("open spool");
330 sink.emit(&ev("e1")).await.expect("emit 1");
331 sink.emit(&ev("e2")).await.expect("emit 2");
332
333 let signer = SoftwareSigner::from_seed("org-root-2026", [9u8; 32]).expect("signer");
334 sink.seal("chain-A", &signer).await.expect("seal segment");
335
336 let mut keys = HashMap::new();
337 keys.insert("org-root-2026".to_string(), signer.verifying_key());
338
339 sink.verify_sealed_head(&keys)
341 .expect("sealed head verifies offline");
342
343 let jsonl = sink.jsonl_path().to_path_buf();
346 let content = std::fs::read_to_string(&jsonl).expect("read jsonl");
347 let tampered = content.replacen("\"c1\"", "\"EVIL\"", 1);
348 assert_ne!(content, tampered, "tamper must change the row body");
349 std::fs::write(&jsonl, tampered).expect("write tampered jsonl");
350
351 assert!(
352 sink.verify().is_err(),
353 "chain verify must fail after a row-body tamper"
354 );
355 assert!(
356 sink.verify_sealed_head(&keys).is_err(),
357 "sealed-head verify must fail after a row-body tamper"
358 );
359 }
360
361 #[tokio::test]
362 async fn flush_with_no_inner_is_ok() {
363 let dir = tempfile::tempdir().expect("tmpdir");
364 let sink = SpoolEventSink::new(dir.path().join("spool")).expect("open spool");
365 sink.flush().await.expect("flush no-op without inner");
366 }
367}