1use 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;
31pub const MAX_OPERATION_BYTES: usize = 64 * 1024;
33pub const MAX_SUMMARY_BYTES: usize = 16 * 1024;
35
36pub const SYNC_INBOX_FILE: &str = "wellfair/sync_inbox.jsonl";
37
38#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
40pub struct SyncOperation {
41 pub protocol_version: u16,
42 pub schema_version: u16,
43 pub operation_id: String,
45 pub record_id: String,
46 pub kind: String,
47 pub content_hash: String,
49 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 pub sensitivity: String,
56 pub payload_summary: String,
58 pub committed_unix: u32,
59 #[serde(default, skip_serializing_if = "Option::is_none")]
62 pub signature: Option<String>,
63}
64
65#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
67#[serde(rename_all = "snake_case", tag = "state", content = "reason")]
68pub enum AdmitOutcome {
69 Validated,
71 Duplicate,
73 Rejected(String),
75}
76
77impl AdmitOutcome {
78 pub fn is_validated(&self) -> bool {
80 matches!(self, AdmitOutcome::Validated)
81 }
82 pub fn is_rejected(&self) -> bool {
84 matches!(self, AdmitOutcome::Rejected(_))
85 }
86}
87
88pub fn sha256_hex(bytes: &[u8]) -> String {
90 hex::encode(Sha256::digest(bytes))
91}
92
93impl SyncOperation {
94 #[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 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 pub fn with_signature(mut self, signature_hex: impl Into<String>) -> Self {
136 self.signature = Some(signature_hex.into());
137 self
138 }
139}
140
141pub fn validate_operation(op: &SyncOperation, seen_ids: &HashSet<String>) -> AdmitOutcome {
144 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 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 match &op.signature {
170 Some(sig) if !sig.is_empty() => {}
171 _ => return AdmitOutcome::Rejected("missing signature (fail closed)".into()),
172 }
173 if op.content_hash != sha256_hex(op.payload_summary.as_bytes()) {
175 return AdmitOutcome::Rejected("content hash does not match payload".into());
176 }
177 if op.sensitivity == "Classified" {
179 return AdmitOutcome::Rejected(
180 "Classified/Sanctuary operations are excluded from the ordinary sync lane".into(),
181 );
182 }
183 if seen_ids.contains(&op.operation_id) {
185 return AdmitOutcome::Duplicate;
186 }
187 AdmitOutcome::Validated
188}
189
190pub fn lamport_next(local: u64, observed: u64) -> u64 {
192 local.max(observed).saturating_add(1)
193}
194
195pub 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#[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
223pub struct SyncInbox {
226 path: PathBuf,
227}
228
229impl SyncInbox {
230 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 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 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 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 Ok(merge_operations(&ops.split_off(0), &[]))
296 }
297
298 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(); 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), ];
400 let merged = merge_operations(&a, &incoming);
401 assert_eq!(merged.len(), 3);
402 assert_eq!(merged[0].operation_id, "b");
404 assert_eq!(merged[1].operation_id, "a");
405 assert_eq!(merged[2].operation_id, "c");
406 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 assert_eq!(inbox.admit(&op, 11).unwrap(), AdmitOutcome::Duplicate);
422 assert_eq!(inbox.admit(&op, 12).unwrap(), AdmitOutcome::Duplicate);
423
424 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"); assert_eq!(ops[1].operation_id, "z");
445 }
446
447 #[test]
448 fn two_node_partition_rejoin_converges() {
449 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}