Skip to main content

cellos_sink_spool/
lib.rs

1//! Durable spool [`EventSink`] (S14, ADR-0029 — air-gapped audit).
2//!
3//! [`SpoolEventSink`] makes the BLAKE3-chained [`AuditChain`] a *first-class
4//! emission sink* rather than a failure-only spill. Every emitted
5//! [`CloudEventV1`] is appended to the chain and **fsync'd to disk before
6//! `emit` returns** (the durability contract `AuditChain::append` now provides),
7//! and only then is it best-effort forwarded to an optional inner transport.
8//!
9//! This inverts the dead-letter model (write-on-failure): the audit row is
10//! durable *first*, so a disconnected or failing transport never loses the
11//! record — the row is on disk and verifiable offline, and the forwarder (S17)
12//! reconciles it to the broker later.
13//!
14//! ## Ordering and failure semantics
15//!
16//! 1. Append to the chain (durable, fsync). A chain-append failure **fails**
17//!    `emit` — losing the durable record is fatal.
18//! 2. Best-effort `inner.emit`. A transport failure is logged and **does NOT
19//!    fail** `emit` — the durable row already exists.
20//! 3. [`SpoolEventSink::flush`] forwards to the inner transport.
21//!
22//! ## Redaction
23//!
24//! Redaction MUST run upstream of the spool (compose `Redact -> Spool`,
25//! ADR-0018): the spool writes the event verbatim as the chain row body, so any
26//! credential redaction must already have happened before it reaches here.
27//!
28//! ## Integrity mode
29//!
30//! Rows are `integrity: blake3-chain` and **unsigned** at this tier (`signed:
31//! false`): the chain is tamper-evident but not per-row signed. Sealed-segment
32//! Ed25519 head signing is S15; this crate lands the durable chain-first sink.
33
34use 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
47/// CloudEvent `type` of a sealed-segment head signature (S15, ADR-0029).
48pub 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
58/// A durable, chain-first [`EventSink`]. See the module docs for the ordering
59/// and failure semantics.
60pub struct SpoolEventSink {
61    chain: AuditChain,
62    inner: Option<Arc<dyn EventSink>>,
63    /// Serialize appends so concurrent `emit` calls cannot interleave a
64    /// read-head / write-row race (every append re-reads the head under lock).
65    lock: Mutex<()>,
66}
67
68impl SpoolEventSink {
69    /// Open (or create) a spool whose trail lives in the parent directory of
70    /// `audit_path` (`<dir>/audit-trail.jsonl` + `<dir>/audit-trail.head`).
71    ///
72    /// # Errors
73    ///
74    /// Returns [`CellosError::EventSink`] if the trail cannot be opened.
75    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    /// Attach an inner transport that each emitted event is best-effort
87    /// forwarded to after the durable chain append.
88    #[must_use]
89    pub fn with_inner(mut self, inner: Arc<dyn EventSink>) -> Self {
90        self.inner = Some(inner);
91        self
92    }
93
94    /// The JSONL trail path this spool writes.
95    #[must_use]
96    pub fn jsonl_path(&self) -> &Path {
97        self.chain.jsonl_path()
98    }
99
100    /// Re-read and verify the on-disk chain, returning the verified rows.
101    ///
102    /// # Errors
103    ///
104    /// Returns an [`std::io::Error`] describing the first integrity break.
105    pub fn verify(&self) -> std::io::Result<Vec<AuditRow>> {
106        self.chain.verify()
107    }
108
109    /// The sealed-segment-head signature path (`<dir>/audit-trail.sig`).
110    #[must_use]
111    pub fn sig_path(&self) -> PathBuf {
112        self.chain.jsonl_path().with_file_name("audit-trail.sig")
113    }
114
115    /// Seal the current segment (S15, ADR-0029): Ed25519-sign the chain head as a
116    /// purpose-built CloudEvent (`chainId`/`lastSeq`/`headRowHash`) via `signer`
117    /// and write `<dir>/audit-trail.sig`. This closes the ADR-0025 chain-vs-sig
118    /// exclusion for the spool: the trail is BLAKE3-chained AND its sealed head is
119    /// offline-verifiable under the org-root key (`integrity:
120    /// blake3-chain+ed25519-head`).
121    ///
122    /// # Errors
123    ///
124    /// Returns [`CellosError`] if the chain does not verify, signing fails, or the
125    /// signature file cannot be written.
126    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        // Atomic write: tmp + rename so a crash never leaves a half-written sig.
160        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    /// Verify a sealed segment offline (S15): the chain is internally intact, the
169    /// `audit-trail.sig` signature verifies under `verifying_keys` (org-root), and
170    /// its `headRowHash` still describes the current chain head. A tampered row
171    /// fails the chain check; a chain advanced/truncated since the seal fails the
172    /// head-match check.
173    ///
174    /// # Errors
175    ///
176    /// Returns [`CellosError`] on any chain-integrity, signature, or head-mismatch
177    /// failure.
178    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        // (1) Durable chain append FIRST (fsync before Ok). Failure here is fatal
219        // — losing the durable record is not acceptable.
220        {
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        // (2) Best-effort forward to the optional inner transport. A transport
228        // failure does NOT fail emit — the durable row is already on disk and
229        // the forwarder (S17) will reconcile it later.
230        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    /// An inner transport that always fails — proves the spool stays durable and
269    /// `emit` still succeeds when the transport is down.
270    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        // Inner always Errs, but emit succeeds because the durable row landed.
286        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        // The fsync contract: after emit returns, the row is readable from a
314        // freshly opened chain over the same path (proxy for crash durability).
315        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        // S15 acceptance: the sealed head verifies offline under the org-root key.
340        sink.verify_sealed_head(&keys)
341            .expect("sealed head verifies offline");
342
343        // Flip one row byte on disk: BOTH the chain verify and the sealed-head
344        // verify must fail.
345        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}