Skip to main content

qualia_client_core/wellfair/
sync_protocol.rs

1//! Versioned, replay-safe sync-operation protocol and quarantined inbox.
2//!
3//! This is the delivery layer that lets Projects/Finance (and any domain) converge across
4//! nodes without duplicating money or obligations. It implements the master plan's SyncService
5//! (§4.2), link-protocol framing (§9.5), and the money-safety invariants (§17):
6//!
7//! - every operation is **versioned** (protocol + schema) and **content-hashed**;
8//! - the inbox is **quarantined**: untrusted frames are decoded into this DTO and validated
9//!   before anything is admitted — oversized, malformed, unsigned, wrong-hash, wrong-version,
10//!   and Sanctuary-classified frames are **rejected fail-closed**;
11//! - admission is **idempotent**: a replayed `operation_id` is recorded as `Duplicate`, never
12//!   applied twice;
13//! - [`merge_operations`] is **add-wins by operation id** and **order-independent**, so
14//!   duplicate/reordered/replayed frames converge to the same set — the same discipline the
15//!   domain layers (`finance::derived_balance`, `projects::derive_obligations`) use to derive
16//!   totals purely over the unique-id set.
17//!
18//! Full signature *verification* is the identity/key-vault layer's job (it holds the actor
19//! public keys); this layer verifies presence + integrity and enforces the routing lane.
20
21use std::collections::HashSet;
22use std::fs::{self, OpenOptions};
23use std::io::{BufRead, BufReader, Write};
24use std::path::{Path, PathBuf};
25
26use serde::{Deserialize, Serialize};
27use sha2::{Digest, Sha256};
28
29pub const CURRENT_PROTOCOL_VERSION: u16 = 1;
30pub const CURRENT_SCHEMA_VERSION: u16 = 1;
31/// Hard cap on a single serialized operation (defends the quarantine against oversized frames).
32pub const MAX_OPERATION_BYTES: usize = 64 * 1024;
33/// Hard cap on the payload summary carried inline.
34pub const MAX_SUMMARY_BYTES: usize = 16 * 1024;
35
36pub const SYNC_INBOX_FILE: &str = "wellfair/sync_inbox.jsonl";
37
38/// A single versioned, content-addressed sync operation (the wire DTO).
39#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
40pub struct SyncOperation {
41    pub protocol_version: u16,
42    pub schema_version: u16,
43    /// Stable operation identifier — the dedup/idempotency anchor.
44    pub operation_id: String,
45    pub record_id: String,
46    pub kind: String,
47    /// SHA-256 (hex) of `payload_summary` — integrity check on receipt.
48    pub content_hash: String,
49    /// Lamport clock for causal ordering across nodes.
50    pub lamport: u64,
51    #[serde(default, skip_serializing_if = "Option::is_none")]
52    pub parent_op_id: Option<String>,
53    pub actor_did: String,
54    /// Routing lane: "Public" | "Restricted" | "Classified".
55    pub sensitivity: String,
56    /// Approved projection / journal summary carried inline (no sensitive plaintext for Sanctuary).
57    pub payload_summary: String,
58    pub committed_unix: u32,
59    /// Detached signature (hex) over [`SyncOperation::signing_payload`]. Presence is required
60    /// (fail-closed); cryptographic verification is performed by the identity layer.
61    #[serde(default, skip_serializing_if = "Option::is_none")]
62    pub signature: Option<String>,
63}
64
65/// Outcome of validating/admitting an inbound operation.
66#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
67#[serde(rename_all = "snake_case", tag = "state", content = "reason")]
68pub enum AdmitOutcome {
69    /// Passed all checks and is newly admitted.
70    Validated,
71    /// A prior operation with this id was already admitted; ignored (idempotent replay).
72    Duplicate,
73    /// Failed a validation check; carries the reason.
74    Rejected(String),
75}
76
77impl AdmitOutcome {
78    /// `true` when validated.
79    pub fn is_validated(&self) -> bool {
80        matches!(self, AdmitOutcome::Validated)
81    }
82    /// `true` when rejected.
83    pub fn is_rejected(&self) -> bool {
84        matches!(self, AdmitOutcome::Rejected(_))
85    }
86}
87
88/// SHA-256 as hex.
89pub fn sha256_hex(bytes: &[u8]) -> String {
90    hex::encode(Sha256::digest(bytes))
91}
92
93impl SyncOperation {
94    /// Build a well-formed, content-hashed operation (signature filled in by the host layer).
95    #[allow(clippy::too_many_arguments)]
96    pub fn new(
97        operation_id: impl Into<String>,
98        record_id: impl Into<String>,
99        kind: impl Into<String>,
100        actor_did: impl Into<String>,
101        sensitivity: impl Into<String>,
102        payload_summary: impl Into<String>,
103        lamport: u64,
104        committed_unix: u32,
105    ) -> Self {
106        let payload_summary = payload_summary.into();
107        let content_hash = sha256_hex(payload_summary.as_bytes());
108        Self {
109            protocol_version: CURRENT_PROTOCOL_VERSION,
110            schema_version: CURRENT_SCHEMA_VERSION,
111            operation_id: operation_id.into(),
112            record_id: record_id.into(),
113            kind: kind.into(),
114            content_hash,
115            lamport,
116            parent_op_id: None,
117            actor_did: actor_did.into(),
118            sensitivity: sensitivity.into(),
119            payload_summary,
120            committed_unix,
121            signature: None,
122        }
123    }
124
125    /// The bytes a signature must cover: id + record + content hash (binds identity to content).
126    pub fn signing_payload(&self) -> Vec<u8> {
127        format!(
128            "{}|{}|{}",
129            self.operation_id, self.record_id, self.content_hash
130        )
131        .into_bytes()
132    }
133
134    /// Builder — sets signature.
135    pub fn with_signature(mut self, signature_hex: impl Into<String>) -> Self {
136        self.signature = Some(signature_hex.into());
137        self
138    }
139}
140
141/// Validate an inbound operation fail-closed. `seen_ids` is the set of already-admitted
142/// operation ids (for replay detection). Returns the admission outcome without persisting.
143pub fn validate_operation(op: &SyncOperation, seen_ids: &HashSet<String>) -> AdmitOutcome {
144    // Version gate: refuse anything we don't understand.
145    if op.protocol_version != CURRENT_PROTOCOL_VERSION {
146        return AdmitOutcome::Rejected(format!(
147            "unsupported protocol version {} (expected {CURRENT_PROTOCOL_VERSION})",
148            op.protocol_version
149        ));
150    }
151    if op.schema_version != CURRENT_SCHEMA_VERSION {
152        return AdmitOutcome::Rejected(format!(
153            "unsupported schema version {} (expected {CURRENT_SCHEMA_VERSION})",
154            op.schema_version
155        ));
156    }
157    // Size bounds (quarantine defense).
158    if op.payload_summary.len() > MAX_SUMMARY_BYTES {
159        return AdmitOutcome::Rejected("payload summary exceeds size cap".into());
160    }
161    match serde_json::to_string(op) {
162        Ok(s) if s.len() > MAX_OPERATION_BYTES => {
163            return AdmitOutcome::Rejected("operation exceeds size cap".into());
164        }
165        Err(e) => return AdmitOutcome::Rejected(format!("operation not serializable: {e}")),
166        _ => {}
167    }
168    // Signature must be present (fail closed); full verification is the identity layer's job.
169    match &op.signature {
170        Some(sig) if !sig.is_empty() => {}
171        _ => return AdmitOutcome::Rejected("missing signature (fail closed)".into()),
172    }
173    // Integrity: the content hash must match the carried payload.
174    if op.content_hash != sha256_hex(op.payload_summary.as_bytes()) {
175        return AdmitOutcome::Rejected("content hash does not match payload".into());
176    }
177    // Routing lane: Sanctuary/Classified operations must never traverse the ordinary inbox (§5.2).
178    if op.sensitivity == "Classified" {
179        return AdmitOutcome::Rejected(
180            "Classified/Sanctuary operations are excluded from the ordinary sync lane".into(),
181        );
182    }
183    // Replay: a previously-admitted id is idempotently ignored.
184    if seen_ids.contains(&op.operation_id) {
185        return AdmitOutcome::Duplicate;
186    }
187    AdmitOutcome::Validated
188}
189
190/// Next Lamport clock value given the local counter and an observed remote value.
191pub fn lamport_next(local: u64, observed: u64) -> u64 {
192    local.max(observed).saturating_add(1)
193}
194
195/// Merge two operation sets **add-wins by operation id** (never re-apply), returning a
196/// deterministically ordered union (by Lamport clock, then id). Idempotent and order-independent.
197pub fn merge_operations(
198    existing: &[SyncOperation],
199    incoming: &[SyncOperation],
200) -> Vec<SyncOperation> {
201    let mut merged: Vec<SyncOperation> = Vec::with_capacity(existing.len() + incoming.len());
202    for op in existing.iter().chain(incoming.iter()) {
203        if !merged.iter().any(|e| e.operation_id == op.operation_id) {
204            merged.push(op.clone());
205        }
206    }
207    merged.sort_by(|a, b| {
208        a.lamport
209            .cmp(&b.lamport)
210            .then_with(|| a.operation_id.cmp(&b.operation_id))
211    });
212    merged
213}
214
215/// A persisted inbox record: the operation plus its admission outcome and time.
216#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
217pub struct InboxRecord {
218    pub operation: SyncOperation,
219    pub outcome: AdmitOutcome,
220    pub admitted_unix: u32,
221}
222
223/// Durable quarantined inbox (append-only jsonl). Admission validates, dedupes by operation id,
224/// and records the outcome; only `Validated` records represent applicable operations.
225pub struct SyncInbox {
226    path: PathBuf,
227}
228
229impl SyncInbox {
230    /// Opens.
231    pub fn open(storage_root: impl AsRef<Path>) -> std::io::Result<Self> {
232        let path = storage_root.as_ref().join(SYNC_INBOX_FILE);
233        if let Some(parent) = path.parent() {
234            fs::create_dir_all(parent)?;
235        }
236        if !path.exists() {
237            OpenOptions::new().create(true).write(true).open(&path)?;
238        }
239        Ok(Self { path })
240    }
241
242    fn load_all(&self) -> std::io::Result<Vec<InboxRecord>> {
243        let file = fs::File::open(&self.path)?;
244        let reader = BufReader::new(file);
245        let mut records = Vec::new();
246        for line in reader.lines() {
247            let line = line?;
248            if line.trim().is_empty() {
249                continue;
250            }
251            if let Ok(rec) = serde_json::from_str::<InboxRecord>(&line) {
252                records.push(rec);
253            }
254        }
255        Ok(records)
256    }
257
258    /// The set of operation ids already admitted as Validated (for replay detection).
259    fn admitted_ids(records: &[InboxRecord]) -> HashSet<String> {
260        records
261            .iter()
262            .filter(|r| r.outcome.is_validated())
263            .map(|r| r.operation.operation_id.clone())
264            .collect()
265    }
266
267    /// Validate and durably record an inbound operation. Idempotent: a replayed id yields
268    /// `Duplicate` and is not applied again. Returns the admission outcome.
269    pub fn admit(&self, op: &SyncOperation, now_unix: u32) -> std::io::Result<AdmitOutcome> {
270        let existing = self.load_all()?;
271        let seen = Self::admitted_ids(&existing);
272        let outcome = validate_operation(op, &seen);
273        let record = InboxRecord {
274            operation: op.clone(),
275            outcome: outcome.clone(),
276            admitted_unix: now_unix,
277        };
278        let line =
279            serde_json::to_string(&record).map_err(|e| std::io::Error::other(e.to_string()))?;
280        let mut file = OpenOptions::new().append(true).open(&self.path)?;
281        writeln!(file, "{line}")?;
282        file.sync_all()?;
283        Ok(outcome)
284    }
285
286    /// All admitted-`Validated` operations, in Lamport order (the applicable set).
287    pub fn validated_operations(&self) -> std::io::Result<Vec<SyncOperation>> {
288        let mut ops: Vec<SyncOperation> = self
289            .load_all()?
290            .into_iter()
291            .filter(|r| r.outcome.is_validated())
292            .map(|r| r.operation)
293            .collect();
294        // Collapse any accidental duplicates and order deterministically.
295        Ok(merge_operations(&ops.split_off(0), &[]))
296    }
297
298    /// Lists recent entries.
299    pub fn list_recent(&self, limit: usize) -> std::io::Result<Vec<InboxRecord>> {
300        let mut all = self.load_all()?;
301        if all.len() > limit {
302            all.drain(0..all.len() - limit);
303        }
304        all.reverse();
305        Ok(all)
306    }
307}
308
309#[cfg(test)]
310mod tests {
311    use super::*;
312
313    fn signed(id: &str, kind: &str, summary: &str, lamport: u64) -> SyncOperation {
314        SyncOperation::new(
315            id,
316            format!("urn:wellfair:{kind}:{id}"),
317            kind,
318            "did:wf:remote",
319            "Restricted",
320            summary,
321            lamport,
322            1_700_000_000,
323        )
324        .with_signature("deadbeef")
325    }
326
327    #[test]
328    fn valid_operation_admitted() {
329        let seen = HashSet::new();
330        let op = signed("op1", "ledger_entry", "{\"amount_cents\":100}", 1);
331        assert_eq!(validate_operation(&op, &seen), AdmitOutcome::Validated);
332    }
333
334    #[test]
335    fn replayed_id_is_duplicate() {
336        let mut seen = HashSet::new();
337        seen.insert("op1".to_string());
338        let op = signed("op1", "ledger_entry", "x", 1);
339        assert_eq!(validate_operation(&op, &seen), AdmitOutcome::Duplicate);
340    }
341
342    #[test]
343    fn missing_signature_rejected() {
344        let seen = HashSet::new();
345        let mut op = signed("op2", "ledger_entry", "x", 1);
346        op.signature = None;
347        assert!(validate_operation(&op, &seen).is_rejected());
348    }
349
350    #[test]
351    fn tampered_content_hash_rejected() {
352        let seen = HashSet::new();
353        let mut op = signed("op3", "ledger_entry", "original", 1);
354        op.payload_summary = "tampered".into(); // hash no longer matches
355        assert!(validate_operation(&op, &seen).is_rejected());
356    }
357
358    #[test]
359    fn classified_operation_rejected_from_ordinary_lane() {
360        let seen = HashSet::new();
361        let mut op = signed("op4", "sanctuary_note", "x", 1);
362        op.sensitivity = "Classified".into();
363        assert!(validate_operation(&op, &seen).is_rejected());
364    }
365
366    #[test]
367    fn wrong_protocol_version_rejected() {
368        let seen = HashSet::new();
369        let mut op = signed("op5", "ledger_entry", "x", 1);
370        op.protocol_version = 99;
371        assert!(validate_operation(&op, &seen).is_rejected());
372    }
373
374    #[test]
375    fn oversized_summary_rejected() {
376        let seen = HashSet::new();
377        let big = "a".repeat(MAX_SUMMARY_BYTES + 1);
378        let op = signed("op6", "ledger_entry", &big, 1);
379        assert!(validate_operation(&op, &seen).is_rejected());
380    }
381
382    #[test]
383    fn lamport_next_is_monotonic() {
384        assert_eq!(lamport_next(3, 5), 6);
385        assert_eq!(lamport_next(7, 2), 8);
386        assert!(lamport_next(u64::MAX, u64::MAX) >= u64::MAX);
387    }
388
389    #[test]
390    fn merge_is_idempotent_and_order_independent() {
391        let a = vec![
392            signed("a", "ledger_entry", "1", 2),
393            signed("b", "ledger_entry", "2", 1),
394        ];
395        let incoming = vec![
396            signed("b", "ledger_entry", "2", 1),
397            signed("c", "ledger_entry", "3", 3),
398            signed("b", "ledger_entry", "2", 1), // duplicate
399        ];
400        let merged = merge_operations(&a, &incoming);
401        assert_eq!(merged.len(), 3);
402        // Lamport order: b(1), a(2), c(3)
403        assert_eq!(merged[0].operation_id, "b");
404        assert_eq!(merged[1].operation_id, "a");
405        assert_eq!(merged[2].operation_id, "c");
406        // Order independence + idempotency.
407        let other = merge_operations(&incoming, &a);
408        assert_eq!(merged, other);
409        let twice = merge_operations(&merge_operations(&a, &incoming), &incoming);
410        assert_eq!(merged, twice);
411    }
412
413    #[test]
414    fn inbox_dedupes_replayed_operations() {
415        let dir = tempfile::tempdir().unwrap();
416        let inbox = SyncInbox::open(dir.path()).unwrap();
417        let op = signed("op-replay", "ledger_entry", "{\"amount_cents\":500}", 1);
418
419        assert_eq!(inbox.admit(&op, 10).unwrap(), AdmitOutcome::Validated);
420        // Replay of the same op id is idempotent.
421        assert_eq!(inbox.admit(&op, 11).unwrap(), AdmitOutcome::Duplicate);
422        assert_eq!(inbox.admit(&op, 12).unwrap(), AdmitOutcome::Duplicate);
423
424        // Only one validated operation exists despite three admissions.
425        assert_eq!(inbox.validated_operations().unwrap().len(), 1);
426    }
427
428    #[test]
429    fn inbox_survives_reopen_and_orders_by_lamport() {
430        let dir = tempfile::tempdir().unwrap();
431        {
432            let inbox = SyncInbox::open(dir.path()).unwrap();
433            inbox
434                .admit(&signed("z", "ledger_entry", "z", 5), 1)
435                .unwrap();
436            inbox
437                .admit(&signed("y", "ledger_entry", "y", 2), 1)
438                .unwrap();
439        }
440        let reopened = SyncInbox::open(dir.path()).unwrap();
441        let ops = reopened.validated_operations().unwrap();
442        assert_eq!(ops.len(), 2);
443        assert_eq!(ops[0].operation_id, "y"); // lamport 2 before 5
444        assert_eq!(ops[1].operation_id, "z");
445    }
446
447    #[test]
448    fn two_node_partition_rejoin_converges() {
449        // Node A and Node B each admit a disjoint op plus a shared op; after exchanging
450        // operation sets both nodes hold the identical validated set.
451        let shared = signed("shared", "contribution", "s", 1);
452        let a_only = signed("a1", "contribution", "a", 2);
453        let b_only = signed("b1", "contribution", "b", 3);
454
455        let node_a = vec![shared.clone(), a_only.clone()];
456        let node_b = vec![shared.clone(), b_only.clone()];
457
458        let a_after = merge_operations(&node_a, &node_b);
459        let b_after = merge_operations(&node_b, &node_a);
460        assert_eq!(a_after, b_after);
461        assert_eq!(a_after.len(), 3);
462    }
463}