1use std::collections::BTreeMap;
7use std::fs::{self, File, OpenOptions};
8use std::io::{self, Read, Seek, SeekFrom, Write};
9use std::path::{Path, PathBuf};
10use std::time::{Instant, SystemTime, UNIX_EPOCH};
11
12use crate::digest::{hex, sha256};
13
14const DOMAIN: &str = "cobolwork-evidence/v1\n";
15const ZERO: &str = "0000000000000000000000000000000000000000000000000000000000000000";
16pub const LEDGER: &str = "ledger.jsonl";
17const LOCK: &str = "ledger.lock";
18
19#[derive(Clone, Debug, PartialEq, Eq)]
20pub enum Value {
21 Null,
22 Bool(bool),
23 Int(i64),
24 Str(String),
25 Arr(Vec<Value>),
26 Obj(BTreeMap<String, Value>),
27}
28
29impl From<&str> for Value {
30 fn from(s: &str) -> Self {
31 Self::Str(s.to_string())
32 }
33}
34impl From<String> for Value {
35 fn from(s: String) -> Self {
36 Self::Str(s)
37 }
38}
39impl From<i64> for Value {
40 fn from(n: i64) -> Self {
41 Self::Int(n)
42 }
43}
44impl From<u64> for Value {
45 fn from(n: u64) -> Self {
46 Self::Int(i64::try_from(n).unwrap_or(i64::MAX))
47 }
48}
49impl From<bool> for Value {
50 fn from(b: bool) -> Self {
51 Self::Bool(b)
52 }
53}
54
55pub fn fields<const N: usize>(pairs: [(&str, Value); N]) -> BTreeMap<String, Value> {
57 pairs.into_iter().map(|(k, v)| (k.to_string(), v)).collect()
58}
59
60fn escape(s: &str, out: &mut String) {
62 out.push('"');
63 for c in s.chars() {
64 match c {
65 '"' => out.push_str("\\\""),
66 '\\' => out.push_str("\\\\"),
67 '\u{8}' => out.push_str("\\b"),
68 '\u{c}' => out.push_str("\\f"),
69 '\n' => out.push_str("\\n"),
70 '\r' => out.push_str("\\r"),
71 '\t' => out.push_str("\\t"),
72 c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)),
73 c => out.push(c),
74 }
75 }
76 out.push('"');
77}
78
79pub fn canonical(value: &Value) -> String {
81 let mut out = String::new();
82 write(value, &mut out);
83 out
84}
85
86fn write(value: &Value, out: &mut String) {
87 match value {
88 Value::Null => out.push_str("null"),
89 Value::Bool(b) => out.push_str(if *b { "true" } else { "false" }),
90 Value::Int(n) => out.push_str(&n.to_string()),
91 Value::Str(s) => escape(s, out),
92 Value::Arr(items) => {
93 out.push('[');
94 for (i, item) in items.iter().enumerate() {
95 if i > 0 {
96 out.push(',');
97 }
98 write(item, out);
99 }
100 out.push(']');
101 }
102 Value::Obj(map) => {
103 let mut keys: Vec<&String> = map.keys().collect();
104 keys.sort_by(|a, b| a.encode_utf16().cmp(b.encode_utf16()));
105 out.push('{');
106 for (i, k) in keys.into_iter().enumerate() {
107 if i > 0 {
108 out.push(',');
109 }
110 escape(k, out);
111 out.push(':');
112 write(&map[k], out);
113 }
114 out.push('}');
115 }
116 }
117}
118
119pub fn record_hash(record: &BTreeMap<String, Value>) -> String {
120 let mut body = record.clone();
121 body.remove("hash");
122 let mut text = String::from(DOMAIN);
123 text.push_str(&canonical(&Value::Obj(body)));
124 hex(&sha256(text.as_bytes()))
125}
126
127fn kind_fields(kind: &str) -> Option<(&'static [&'static str], &'static [&'static str])> {
129 Some(match kind {
130 "open" => (&["tool", "toolVersion", "toolRevision", "command", "argv", "roots", "platform"], &["tool", "toolVersion", "command", "argv", "roots"]),
131 "input" => (&["root", "path", "sha256", "bytes"], &["root", "path", "sha256"]),
132 "dd" => (&["dd", "event", "mode", "sha256", "bytes"], &["dd", "event"]),
133 "call" => (&["program", "from", "sha256"], &["program"]),
134 "abend" => (&["code", "file", "line"], &["code"]),
135 "step" => (&["step", "pgm", "outcome"], &["step", "pgm", "outcome"]),
136 "sink" => (&["sink", "file", "line", "marker", "reached"], &["sink", "file", "line", "marker", "reached"]),
137 "output" => (&["name", "sha256", "bytes", "path", "stdout"], &["name", "sha256"]),
138 "close" => (&["exit", "counts", "durationMs", "ledger"], &["exit"]),
139 "genesis" => (&["createdAt", "rotatedFrom"], &["createdAt"]),
140 "run" => (&["run", "runChain", "runLength", "runTip"], &["run", "runChain", "runLength", "runTip"]),
141 "lock-broken" => (&["holderPid", "ageMs"], &["holderPid", "ageMs"]),
142 _ => return None,
143 })
144}
145
146fn check(kind: &str, record: &BTreeMap<String, Value>) -> io::Result<()> {
147 let bad = |m: String| io::Error::new(io::ErrorKind::InvalidInput, m);
148 let (allowed, required) = kind_fields(kind).ok_or_else(|| bad(format!("no evidence record kind {kind}")))?;
149 for k in record.keys() {
150 if !allowed.contains(&k.as_str()) {
151 return Err(bad(format!("{kind}: no field {k}")));
152 }
153 }
154 for k in required {
155 if !record.contains_key(*k) {
156 return Err(bad(format!("{kind}: {k} is required")));
157 }
158 }
159 Ok(())
160}
161
162pub fn iso_now() -> String {
164 let d = SystemTime::now().duration_since(UNIX_EPOCH).unwrap_or_default();
165 iso(d.as_secs() as i64, d.subsec_millis())
166}
167
168pub fn iso(seconds: i64, millis: u32) -> String {
169 let c = crate::calendar::civil(seconds);
170 format!("{:04}-{:02}-{:02}T{:02}:{:02}:{:02}.{:03}Z", c.year, c.month, c.day, c.hour, c.minute, c.second, millis)
171}
172
173fn random(n: usize) -> Vec<u8> {
176 let mut buf = vec![0u8; n];
177 if File::open("/dev/urandom").and_then(|mut f| f.read_exact(&mut buf)).is_ok() {
178 return buf;
179 }
180 use std::hash::{BuildHasher, Hasher};
181 let d = SystemTime::now().duration_since(UNIX_EPOCH).unwrap_or_default();
182 let mut keyed = std::collections::hash_map::RandomState::new().build_hasher();
183 keyed.write_u128(d.as_nanos());
184 let seed = format!("{}:{}:{:p}:{}", d.as_nanos(), std::process::id(), &buf, keyed.finish());
185 sha256(seed.as_bytes())[..n.min(32)].to_vec()
186}
187
188fn open_new(path: &Path) -> io::Result<File> {
189 let mut o = OpenOptions::new();
190 o.write(true).create_new(true);
191 #[cfg(unix)]
192 {
193 use std::os::unix::fs::OpenOptionsExt;
194 o.mode(0o600);
195 }
196 o.open(path)
197}
198
199fn refuse_link(path: &Path) -> io::Result<()> {
200 match fs::symlink_metadata(path) {
201 Ok(m) if m.file_type().is_symlink() => Err(io::Error::new(io::ErrorKind::InvalidInput, format!("{} is a symbolic link, which evidence is not written through", path.display()))),
202 _ => Ok(()),
203 }
204}
205
206pub fn prepare(dir: &Path, reads: &[PathBuf]) -> io::Result<PathBuf> {
209 let absolute = std::path::absolute(dir)?;
210 let mut existing = absolute.clone();
211 let mut rest = Vec::new();
212 while !existing.exists() {
213 match (existing.file_name().map(|n| n.to_os_string()), existing.parent()) {
214 (Some(name), Some(parent)) => {
215 rest.push(name);
216 existing = parent.to_path_buf();
217 }
218 _ => break,
219 }
220 }
221 let mut intended = fs::canonicalize(&existing)?;
222 for name in rest.iter().rev() {
223 intended.push(name);
224 }
225 for root in reads {
226 if let Ok(r) = fs::canonicalize(root)
227 && intended.starts_with(&r)
228 {
229 return Err(io::Error::new(io::ErrorKind::InvalidInput, format!("the evidence directory {} is inside {}, which this run reads", dir.display(), root.display())));
230 }
231 }
232 for p in [absolute.clone(), absolute.join("runs"), absolute.join("seals")] {
233 refuse_link(&p)?;
234 if !p.exists() {
235 fs::create_dir_all(&p)?;
236 #[cfg(unix)]
237 {
238 use std::os::unix::fs::PermissionsExt;
239 fs::set_permissions(&p, fs::Permissions::from_mode(0o700))?;
240 }
241 }
242 refuse_link(&p)?;
243 }
244 let made = fs::canonicalize(&absolute)?;
245 if made != intended {
246 return Err(io::Error::new(io::ErrorKind::InvalidInput, format!("the evidence directory {} resolved to {} while it was made", dir.display(), made.display())));
247 }
248 Ok(made)
249}
250
251struct Chain {
252 chain: String,
253 seq: i64,
254 prev: String,
255}
256
257impl Chain {
258 fn record(&mut self, kind: &str, mut fields: BTreeMap<String, Value>, at: &str) -> io::Result<String> {
259 check(kind, &fields)?;
260 fields.insert("v".into(), Value::Int(1));
261 fields.insert("chain".into(), Value::Str(self.chain.clone()));
262 fields.insert("seq".into(), Value::Int(self.seq));
263 fields.insert("at".into(), Value::Str(at.to_string()));
264 fields.insert("kind".into(), Value::Str(kind.to_string()));
265 fields.insert("prev".into(), Value::Str(self.prev.clone()));
266 let hash = record_hash(&fields);
267 fields.insert("hash".into(), Value::Str(hash.clone()));
268 self.prev = hash;
269 self.seq += 1;
270 Ok(format!("{}\n", canonical(&Value::Obj(fields))))
271 }
272}
273
274pub struct Journal {
275 pub id: String,
276 pub path: PathBuf,
277 dir: PathBuf,
278 file: File,
279 chain: Chain,
280 counts: BTreeMap<String, i64>,
281 started: Instant,
282}
283
284#[derive(Debug, PartialEq, Eq)]
286pub enum Ledger {
287 Recorded,
288 Unrecorded(String),
289}
290
291impl Journal {
292 pub fn create(dir: &Path, reads: &[PathBuf], command: &str, argv: &[String], tool_version: &str) -> io::Result<Self> {
293 let dir = prepare(dir, reads)?;
294 let now = iso_now();
295 let stamp: String = now.chars().filter(|c| c.is_ascii_digit() || *c == 'T').take(15).collect();
296 let id = format!("{stamp}Z-{}", hex(&random(8)));
297 let path = dir.join("runs").join(format!("{id}.jsonl"));
298 let file = open_new(&path)?;
299 let mut journal = Self { id, path, dir, file, chain: Chain { chain: hex(&random(16)), seq: 0, prev: ZERO.into() }, counts: BTreeMap::new(), started: Instant::now() };
300 let roots = reads.iter().map(|r| Value::Str(r.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default())).collect();
301 journal.append_at(
302 "open",
303 fields([
304 ("tool", "ironwork".into()),
305 ("toolVersion", tool_version.into()),
306 ("command", command.into()),
307 ("argv", Value::Arr(argv.iter().map(|a| Value::Str(a.clone())).collect())),
308 ("roots", Value::Arr(roots)),
309 ("platform", std::env::consts::OS.into()),
310 ]),
311 &now,
312 )?;
313 Ok(journal)
314 }
315
316 fn append_at(&mut self, kind: &str, fields: BTreeMap<String, Value>, at: &str) -> io::Result<()> {
317 let line = self.chain.record(kind, fields, at)?;
318 self.file.write_all(line.as_bytes())?;
319 *self.counts.entry(kind.to_string()).or_default() += 1;
320 Ok(())
321 }
322
323 pub fn tip(&self) -> &str {
325 &self.chain.prev
326 }
327
328 pub fn append(&mut self, kind: &str, fields: BTreeMap<String, Value>) -> io::Result<()> {
329 self.append_at(kind, fields, &iso_now())
330 }
331
332 pub fn close(mut self, exit: Option<i64>) -> io::Result<Ledger> {
334 let lock = self.dir.join(LOCK);
335 let held = take_lock(&lock);
336 let counts = self.counts.iter().map(|(k, v)| (k.clone(), Value::Int(*v))).collect();
337 let ledger = if held.is_ok() { "recorded" } else { "unrecorded" };
338 let duration = i64::try_from(self.started.elapsed().as_millis()).unwrap_or(i64::MAX);
339 self.append("close", fields([("exit", exit.map_or(Value::Null, Value::Int)), ("counts", Value::Obj(counts)), ("durationMs", Value::Int(duration)), ("ledger", ledger.into())]))?;
340 self.file.sync_all()?;
341 let broken = match held {
342 Ok(broken) => broken,
343 Err(reason) => return Ok(Ledger::Unrecorded(reason)),
344 };
345 let result = append_ledger(&self.dir, &self.id, &self.chain, broken);
346 let _ = fs::remove_file(&lock);
347 match result {
348 Ok(()) => Ok(Ledger::Recorded),
349 Err(e) => Ok(Ledger::Unrecorded(e.to_string())),
350 }
351 }
352}
353
354struct Broken {
356 pid: i64,
357 age_ms: i64,
358}
359
360fn take_lock(path: &Path) -> Result<Option<Broken>, String> {
363 let mut broken = None;
364 let deadline = Instant::now() + std::time::Duration::from_secs(5);
365 loop {
366 match open_new(path) {
367 Ok(mut f) => {
368 let _ = writeln!(f, "{} {}", std::process::id(), SystemTime::now().duration_since(UNIX_EPOCH).unwrap_or_default().as_millis());
369 return Ok(broken);
370 }
371 Err(e) if e.kind() == io::ErrorKind::AlreadyExists => {
372 let age = fs::symlink_metadata(path).and_then(|m| m.modified()).ok().and_then(|t| t.elapsed().ok());
373 if let Some(age) = age.filter(|a| *a > std::time::Duration::from_secs(60)) {
374 let pid = fs::read_to_string(path).ok().and_then(|t| t.split_whitespace().next().and_then(|p| p.parse().ok())).unwrap_or(0);
375 if fs::remove_file(path).is_ok() {
376 broken = Some(Broken { pid, age_ms: i64::try_from(age.as_millis()).unwrap_or(i64::MAX) });
377 continue;
378 }
379 }
380 if Instant::now() >= deadline {
381 return Err("the ledger lock could not be had".into());
382 }
383 std::thread::sleep(std::time::Duration::from_millis(25));
384 }
385 Err(e) => return Err(e.to_string()),
386 }
387 }
388}
389
390fn ledger_tail(path: &Path) -> io::Result<Option<String>> {
393 let mut f = match File::open(path) {
394 Ok(f) => f,
395 Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(None),
396 Err(e) => return Err(e),
397 };
398 let size = f.metadata()?.len();
399 if size == 0 {
400 return Ok(None);
401 }
402 let window = size.min(65536);
403 f.seek(SeekFrom::Start(size - window))?;
404 let mut buf = Vec::new();
405 f.take(window).read_to_end(&mut buf)?;
406 let text = String::from_utf8_lossy(&buf);
407 let body = text.strip_suffix('\n').ok_or_else(|| io::Error::new(io::ErrorKind::InvalidData, "ledger.jsonl ends in a partial line"))?;
408 match body.rsplit_once('\n') {
409 Some((_, last)) => Ok(Some(last.to_string())),
410 None if window < size => Err(io::Error::new(io::ErrorKind::InvalidData, "the ledger's last line is longer than any ledger record")),
411 None => Ok(Some(body.to_string())),
412 }
413}
414
415fn field_of(line: &str, key: &str) -> Option<String> {
417 let needle = format!("\"{key}\":");
418 let at = line.find(&needle)? + needle.len();
419 let rest = &line[at..];
420 if let Some(s) = rest.strip_prefix('"') {
421 return s.find('"').map(|end| s[..end].to_string());
422 }
423 Some(rest.chars().take_while(|c| c.is_ascii_digit()).collect())
424}
425
426fn append_ledger(dir: &Path, run: &str, journal: &Chain, broken: Option<Broken>) -> io::Result<()> {
427 let path = dir.join(LEDGER);
428 refuse_link(&path)?;
429 let mut chain = match ledger_tail(&path)? {
430 Some(line) => {
431 let bad = || io::Error::new(io::ErrorKind::InvalidData, "the ledger's last line is not a ledger record");
432 let hex_of = |key: &str, len: usize| field_of(&line, key).filter(|v| v.len() == len && v.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)));
433 let seq: i64 = field_of(&line, "seq").and_then(|s| s.parse().ok()).ok_or_else(bad)?;
434 Chain { chain: hex_of("chain", 32).ok_or_else(bad)?, seq: seq + 1, prev: hex_of("hash", 64).ok_or_else(bad)? }
435 }
436 None => Chain { chain: hex(&random(16)), seq: 0, prev: ZERO.into() },
437 };
438 let mut out = String::new();
439 let now = iso_now();
440 if chain.seq == 0 {
441 out.push_str(&chain.record("genesis", fields([("createdAt", now.clone().into())]), &now)?);
442 }
443 if let Some(b) = broken {
444 out.push_str(&chain.record("lock-broken", fields([("holderPid", Value::Int(b.pid)), ("ageMs", Value::Int(b.age_ms))]), &now)?);
445 }
446 out.push_str(&chain.record(
447 "run",
448 fields([("run", run.into()), ("runChain", journal.chain.clone().into()), ("runLength", Value::Int(journal.seq)), ("runTip", journal.prev.clone().into())]),
449 &now,
450 )?);
451 let mut f = OpenOptions::new().append(true).create(true).open(&path)?;
452 f.write_all(out.as_bytes())?;
453 f.sync_all()
454}
455
456#[cfg(test)]
457mod tests {
458 use super::*;
459
460 fn temp() -> PathBuf {
461 let p = std::env::temp_dir().join(format!("iw-evidence-{}", hex(&random(6))));
462 fs::create_dir_all(&p).unwrap();
463 p
464 }
465
466 #[test]
467 fn canonical_form_matches_javascript() {
468 let v = Value::Obj(fields([("b", Value::Int(2)), ("a", "q\"\\\n\u{1}é".into()), ("Z", Value::Arr(vec![Value::Null, Value::Bool(true)]))]));
469 assert_eq!(canonical(&v), "{\"Z\":[null,true],\"a\":\"q\\\"\\\\\\n\\u0001é\",\"b\":2}");
470 }
471
472 #[test]
473 fn the_hash_is_over_the_domain_tag_and_the_record_without_its_hash() {
474 let r = fields([("kind", "abend".into()), ("code", "S0C7".into()), ("hash", "ignored".into())]);
475 assert_eq!(record_hash(&r), hex(&sha256(b"cobolwork-evidence/v1\n{\"code\":\"S0C7\",\"kind\":\"abend\"}")));
476 }
477
478 #[test]
479 fn a_closed_journal_chains_and_reaches_the_ledger() {
480 let dir = temp();
481 let mut j = Journal::create(&dir.join("ev"), &[], "run", &["run".into()], "0.0.0").unwrap();
482 j.append("dd", fields([("dd", "IN".into()), ("event", "open".into()), ("mode", "INPUT".into()), ("sha256", hex(&sha256(b"x")).into()), ("bytes", Value::Int(1))])).unwrap();
483 let path = j.path.clone();
484 let id = j.id.clone();
485 assert_eq!(j.close(Some(0)).unwrap(), Ledger::Recorded);
486 let lines: Vec<String> = fs::read_to_string(&path).unwrap().lines().map(String::from).collect();
487 assert_eq!(lines.len(), 3);
488 let mut prev = ZERO.to_string();
489 for (i, line) in lines.iter().enumerate() {
490 assert_eq!(field_of(line, "seq").unwrap(), i.to_string());
491 assert_eq!(field_of(line, "prev").unwrap(), prev);
492 prev = field_of(line, "hash").unwrap();
493 }
494 let ledger = fs::read_to_string(dir.join("ev").join(LEDGER)).unwrap();
495 let run = ledger.lines().last().unwrap();
496 assert_eq!(field_of(run, "run").unwrap(), id);
497 assert_eq!(field_of(run, "runTip").unwrap(), prev);
498 assert_eq!(field_of(run, "runLength").unwrap(), "3");
499 fs::remove_dir_all(dir).unwrap();
500 }
501
502 #[test]
503 fn an_unknown_field_is_refused() {
504 let dir = temp();
505 let mut j = Journal::create(&dir.join("ev"), &[], "run", &[], "0.0.0").unwrap();
506 assert!(j.append("dd", fields([("dd", "IN".into()), ("event", "open".into()), ("record", "SECRET".into())])).is_err());
507 fs::remove_dir_all(dir).unwrap();
508 }
509
510 #[test]
511 fn an_evidence_directory_inside_a_tree_read_is_refused() {
512 let dir = temp();
513 assert!(prepare(&dir.join("src").join("ev"), std::slice::from_ref(&dir)).is_err());
514 assert!(!dir.join("src").exists());
515 fs::remove_dir_all(dir).unwrap();
516 }
517
518 fn closed(ev: &Path) -> Ledger {
519 Journal::create(ev, &[], "run", &[], "0.0.0").unwrap().close(Some(0)).unwrap()
520 }
521
522 #[test]
523 fn a_lock_left_by_a_dead_writer_is_broken_after_a_minute() {
524 let dir = temp();
525 let ev = dir.join("ev");
526 prepare(&ev, &[]).unwrap();
527 let lock = File::create(ev.join(LOCK)).unwrap();
528 lock.set_modified(SystemTime::now() - std::time::Duration::from_secs(120)).unwrap();
529 drop(lock);
530 assert_eq!(closed(&ev), Ledger::Recorded);
531 assert!(!ev.join(LOCK).exists());
532 let kinds: Vec<String> = fs::read_to_string(ev.join(LEDGER)).unwrap().lines().map(|l| field_of(l, "kind").unwrap()).collect();
533 assert_eq!(kinds, ["genesis", "lock-broken", "run"]);
534 fs::remove_dir_all(dir).unwrap();
535 }
536
537 #[test]
538 fn a_ledger_whose_last_line_is_no_ledger_record_is_not_extended() {
539 let dir = temp();
540 let ev = dir.join("ev");
541 prepare(&ev, &[]).unwrap();
542 for tail in ["{\"seq\":0}\n".to_string(), format!("{{\"chain\":\"{}\",\"hash\":\"{}\",\"seq\":0}}\n", "a".repeat(31), "b".repeat(64)), format!("{}\n", "x".repeat(70_000))] {
543 fs::write(ev.join(LEDGER), &tail).unwrap();
544 assert!(matches!(closed(&ev), Ledger::Unrecorded(_)), "{}", &tail[..20]);
545 assert_eq!(fs::read_to_string(ev.join(LEDGER)).unwrap(), tail);
546 }
547 fs::remove_dir_all(dir).unwrap();
548 }
549}