libro 0.90.0

Cryptographic audit chain — tamper-proof event logging with hash-linked entries and verification
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

//! Chain verification — validate integrity of an audit chain.

use tracing::warn;

use crate::LibroError;
use crate::entry::AuditEntry;

/// Verify a sequence of audit entries forms a valid chain.
///
/// Checks two properties for each entry:
/// 1. **Self-hash integrity** — the entry's stored hash matches its recomputed hash.
/// 2. **Chain linkage** — each entry's `prev_hash` matches the preceding entry's hash.
///
/// Returns `Ok(())` if all entries are valid, or a [`LibroError::IntegrityViolation`]
/// identifying the first invalid entry.
///
/// An empty slice is considered valid.
pub fn verify_chain(entries: &[AuditEntry]) -> crate::Result<()> {
    if entries.is_empty() {
        return Ok(());
    }

    for (i, entry) in entries.iter().enumerate() {
        let expected_hash = entry.compute_hash();
        if entry.hash() != expected_hash {
            warn!(
                index = i,
                hash = entry.hash(),
                expected = %expected_hash,
                "entry self-hash verification failed"
            );
            return Err(LibroError::IntegrityViolation {
                index: i,
                expected: expected_hash,
                actual: entry.hash().to_owned(),
            });
        }
        if i > 0 && entry.prev_hash() != entries[i - 1].hash() {
            warn!(
                index = i,
                expected = entries[i - 1].hash(),
                actual = entry.prev_hash(),
                "chain linkage broken"
            );
            return Err(LibroError::IntegrityViolation {
                index: i,
                expected: entries[i - 1].hash().to_owned(),
                actual: entry.prev_hash().to_owned(),
            });
        }
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::entry::{AuditEntry, EventSeverity};

    #[test]
    fn verify_valid_chain() {
        let e1 = AuditEntry::new(EventSeverity::Info, "s", "a", serde_json::json!({}), "");
        let e2 = AuditEntry::new(
            EventSeverity::Info,
            "s",
            "b",
            serde_json::json!({}),
            e1.hash(),
        );
        assert!(verify_chain(&[e1, e2]).is_ok());
    }

    #[test]
    fn verify_broken_link() {
        let e1 = AuditEntry::new(EventSeverity::Info, "s", "a", serde_json::json!({}), "");
        let e2 = AuditEntry::new(
            EventSeverity::Info,
            "s",
            "b",
            serde_json::json!({}),
            "wrong",
        );
        assert!(verify_chain(&[e1, e2]).is_err());
    }

    #[test]
    fn verify_empty() {
        assert!(verify_chain(&[]).is_ok());
    }

    #[test]
    fn verify_tampered_self_hash() {
        let mut e1 = AuditEntry::new(EventSeverity::Info, "s", "a", serde_json::json!({}), "");
        e1.corrupt_hash("tampered");
        let err = verify_chain(&[e1]).unwrap_err();
        assert!(err.to_string().contains("entry 0"));
    }

    #[test]
    fn verify_single_valid_entry() {
        let e1 = AuditEntry::new(EventSeverity::Info, "s", "a", serde_json::json!({}), "");
        assert!(verify_chain(&[e1]).is_ok());
    }

    #[test]
    fn verify_long_chain() {
        let mut entries = Vec::new();
        let first = AuditEntry::new(EventSeverity::Info, "s", "e0", serde_json::json!({}), "");
        entries.push(first);
        for i in 1..50 {
            let prev = entries[i - 1].hash();
            entries.push(AuditEntry::new(
                EventSeverity::Info,
                "s",
                format!("e{i}"),
                serde_json::json!({}),
                prev,
            ));
        }
        assert!(verify_chain(&entries).is_ok());

        // Tamper in the middle
        entries[25].corrupt_action("hacked");
        assert!(verify_chain(&entries).is_err());
    }
}