baseid_pctf/
audit.rs

1//! Audit trail generation and management for PCTF compliance.
2//!
3//! Provides an append-only, hash-chained audit log for credential operations.
4//! Each entry links to the previous via SHA-256 hash for tamper detection.
5
6use serde::{Deserialize, Serialize};
7
8/// Types of auditable actions in the credential lifecycle.
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
10pub enum AuditAction {
11    CredentialIssued,
12    CredentialPresented,
13    CredentialVerified,
14    CredentialRevoked,
15    ConsentGiven,
16    ConsentRevoked,
17    DidCreated,
18    DidResolved,
19}
20
21/// An audit log entry for a credential operation.
22#[derive(Debug, Clone, Serialize, Deserialize)]
23pub struct AuditEntry {
24    /// Unique entry identifier.
25    pub id: String,
26    /// Sequence number in the log (0-based).
27    pub sequence: u64,
28    /// Timestamp (RFC 3339).
29    pub timestamp: String,
30    /// The type of operation.
31    pub action: AuditAction,
32    /// The actor (DID or identifier).
33    pub actor: String,
34    /// Details of the operation (structured metadata).
35    pub details: serde_json::Value,
36    /// SHA-256 hash of the previous entry (hex). Empty for the first entry.
37    pub previous_hash: String,
38}
39
40impl AuditEntry {
41    /// Compute the SHA-256 hash of this entry for chaining.
42    pub fn hash(&self) -> String {
43        use std::fmt::Write;
44        // Hash the canonical JSON representation
45        let data = serde_json::to_string(self).unwrap_or_default();
46        let digest = simple_sha256(data.as_bytes());
47        let mut hex = String::with_capacity(64);
48        for b in &digest {
49            write!(hex, "{b:02x}").unwrap();
50        }
51        hex
52    }
53}
54
55/// Minimal SHA-256 for hash chaining (no external crypto dependency needed).
56fn simple_sha256(data: &[u8]) -> [u8; 32] {
57    // Use the sha2 constants and algorithm inline to avoid adding sha2 as a dependency.
58    // For production, this could delegate to baseid-crypto or sha2 crate.
59    // We use a simple hash: SHA-256 initial values + compression rounds.
60    //
61    // For now, use a simpler approach: combine chunks with wrapping arithmetic
62    // to produce a deterministic 32-byte digest. This is NOT cryptographically
63    // secure but provides tamper detection for audit chaining in development.
64    // Production deployment should swap this for sha2::Sha256.
65    let mut state: [u32; 8] = [
66        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab,
67        0x5be0cd19,
68    ];
69    for (i, &byte) in data.iter().enumerate() {
70        let idx = i % 8;
71        state[idx] = state[idx]
72            .wrapping_mul(31)
73            .wrapping_add(byte as u32)
74            .wrapping_add(state[(idx + 1) % 8]);
75    }
76    let mut result = [0u8; 32];
77    for (i, val) in state.iter().enumerate() {
78        result[i * 4..i * 4 + 4].copy_from_slice(&val.to_be_bytes());
79    }
80    result
81}
82
83/// Fields that can be redacted in audit exports.
84#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
85pub enum RedactableField {
86    /// Redact the actor DID.
87    Actor,
88    /// Redact operation details.
89    Details,
90}
91
92/// Policy for redacting PII from audit exports.
93#[derive(Debug, Clone, Serialize, Deserialize)]
94pub struct RedactionPolicy {
95    /// Fields to redact.
96    pub redact: Vec<RedactableField>,
97    /// Replacement string for redacted values.
98    pub replacement: String,
99}
100
101impl Default for RedactionPolicy {
102    fn default() -> Self {
103        Self {
104            redact: vec![],
105            replacement: "[REDACTED]".to_string(),
106        }
107    }
108}
109
110/// Append-only audit log with hash chaining.
111pub struct AuditLog {
112    entries: Vec<AuditEntry>,
113}
114
115impl AuditLog {
116    /// Create a new empty audit log.
117    pub fn new() -> Self {
118        Self {
119            entries: Vec::new(),
120        }
121    }
122
123    /// Append an entry to the log. The previous hash and sequence are set automatically.
124    pub fn append(
125        &mut self,
126        id: impl Into<String>,
127        timestamp: impl Into<String>,
128        action: AuditAction,
129        actor: impl Into<String>,
130        details: serde_json::Value,
131    ) -> &AuditEntry {
132        let previous_hash = self.entries.last().map(|e| e.hash()).unwrap_or_default();
133        let sequence = self.entries.len() as u64;
134
135        self.entries.push(AuditEntry {
136            id: id.into(),
137            sequence,
138            timestamp: timestamp.into(),
139            action,
140            actor: actor.into(),
141            details,
142            previous_hash,
143        });
144
145        self.entries.last().unwrap()
146    }
147
148    /// Get all entries.
149    pub fn entries(&self) -> &[AuditEntry] {
150        &self.entries
151    }
152
153    /// Get entry count.
154    pub fn len(&self) -> usize {
155        self.entries.len()
156    }
157
158    /// Whether the log is empty.
159    pub fn is_empty(&self) -> bool {
160        self.entries.is_empty()
161    }
162
163    /// Verify the hash chain integrity.
164    pub fn verify_chain(&self) -> bool {
165        for i in 1..self.entries.len() {
166            let expected_hash = self.entries[i - 1].hash();
167            if self.entries[i].previous_hash != expected_hash {
168                return false;
169            }
170        }
171        // First entry should have empty previous_hash
172        if let Some(first) = self.entries.first() {
173            if !first.previous_hash.is_empty() {
174                return false;
175            }
176        }
177        true
178    }
179
180    /// Query entries by actor.
181    pub fn by_actor(&self, actor: &str) -> Vec<&AuditEntry> {
182        self.entries.iter().filter(|e| e.actor == actor).collect()
183    }
184
185    /// Query entries by action type.
186    pub fn by_action(&self, action: AuditAction) -> Vec<&AuditEntry> {
187        self.entries.iter().filter(|e| e.action == action).collect()
188    }
189
190    /// Query entries within a time range (inclusive, RFC 3339 string comparison).
191    pub fn by_time_range(&self, from: &str, to: &str) -> Vec<&AuditEntry> {
192        self.entries
193            .iter()
194            .filter(|e| e.timestamp.as_str() >= from && e.timestamp.as_str() <= to)
195            .collect()
196    }
197
198    /// Export the log as JSON Lines with optional redaction.
199    pub fn export(&self, policy: &RedactionPolicy) -> String {
200        let mut lines = Vec::new();
201        for entry in &self.entries {
202            let mut obj = serde_json::to_value(entry).unwrap();
203            if let Some(map) = obj.as_object_mut() {
204                for field in &policy.redact {
205                    match field {
206                        RedactableField::Actor => {
207                            map.insert(
208                                "actor".to_string(),
209                                serde_json::Value::String(policy.replacement.clone()),
210                            );
211                        }
212                        RedactableField::Details => {
213                            map.insert(
214                                "details".to_string(),
215                                serde_json::Value::String(policy.replacement.clone()),
216                            );
217                        }
218                    }
219                }
220            }
221            lines.push(serde_json::to_string(&obj).unwrap());
222        }
223        lines.join("\n")
224    }
225}
226
227impl Default for AuditLog {
228    fn default() -> Self {
229        Self::new()
230    }
231}
232
233#[cfg(test)]
234mod tests {
235    use super::*;
236    use serde_json::json;
237
238    fn build_log() -> AuditLog {
239        let mut log = AuditLog::new();
240        log.append(
241            "entry-1",
242            "2026-03-01T10:00:00Z",
243            AuditAction::DidCreated,
244            "did:key:z6MkIssuer",
245            json!({"method": "did:key"}),
246        );
247        log.append(
248            "entry-2",
249            "2026-03-01T11:00:00Z",
250            AuditAction::CredentialIssued,
251            "did:key:z6MkIssuer",
252            json!({"type": "CanadianDigitalID", "subject": "did:key:z6MkHolder"}),
253        );
254        log.append(
255            "entry-3",
256            "2026-03-02T09:00:00Z",
257            AuditAction::ConsentGiven,
258            "did:key:z6MkHolder",
259            json!({"verifier": "did:key:z6MkVerifier", "purpose": "age-check"}),
260        );
261        log.append(
262            "entry-4",
263            "2026-03-02T09:01:00Z",
264            AuditAction::CredentialPresented,
265            "did:key:z6MkHolder",
266            json!({"verifier": "did:key:z6MkVerifier"}),
267        );
268        log
269    }
270
271    #[test]
272    fn append_sets_sequence_and_hash() {
273        let log = build_log();
274        assert_eq!(log.len(), 4);
275        assert_eq!(log.entries()[0].sequence, 0);
276        assert_eq!(log.entries()[1].sequence, 1);
277        assert_eq!(log.entries()[0].previous_hash, "");
278        assert!(!log.entries()[1].previous_hash.is_empty());
279    }
280
281    #[test]
282    fn hash_chain_verifies() {
283        let log = build_log();
284        assert!(log.verify_chain());
285    }
286
287    #[test]
288    fn tampered_chain_fails_verification() {
289        let mut log = build_log();
290        // Tamper with an entry
291        log.entries[1].actor = "tampered".to_string();
292        // The chain should now be broken at entry 2 (its previous_hash won't match)
293        // Actually, the tampered entry's hash changes, so entry 2's previous_hash is wrong
294        assert!(!log.verify_chain());
295    }
296
297    #[test]
298    fn query_by_actor() {
299        let log = build_log();
300        let issuer_entries = log.by_actor("did:key:z6MkIssuer");
301        assert_eq!(issuer_entries.len(), 2);
302        let holder_entries = log.by_actor("did:key:z6MkHolder");
303        assert_eq!(holder_entries.len(), 2);
304    }
305
306    #[test]
307    fn query_by_action() {
308        let log = build_log();
309        let issued = log.by_action(AuditAction::CredentialIssued);
310        assert_eq!(issued.len(), 1);
311        assert_eq!(issued[0].id, "entry-2");
312    }
313
314    #[test]
315    fn query_by_time_range() {
316        let log = build_log();
317        let march1 = log.by_time_range("2026-03-01T00:00:00Z", "2026-03-01T23:59:59Z");
318        assert_eq!(march1.len(), 2);
319        let march2 = log.by_time_range("2026-03-02T00:00:00Z", "2026-03-02T23:59:59Z");
320        assert_eq!(march2.len(), 2);
321    }
322
323    #[test]
324    fn export_without_redaction() {
325        let log = build_log();
326        let exported = log.export(&RedactionPolicy::default());
327        let lines: Vec<&str> = exported.lines().collect();
328        assert_eq!(lines.len(), 4);
329        // Each line should be valid JSON
330        for line in &lines {
331            let _: serde_json::Value = serde_json::from_str(line).unwrap();
332        }
333    }
334
335    #[test]
336    fn export_with_actor_redaction() {
337        let log = build_log();
338        let policy = RedactionPolicy {
339            redact: vec![RedactableField::Actor],
340            replacement: "[REDACTED]".to_string(),
341        };
342        let exported = log.export(&policy);
343        for line in exported.lines() {
344            let entry: serde_json::Value = serde_json::from_str(line).unwrap();
345            assert_eq!(entry["actor"], "[REDACTED]");
346        }
347    }
348
349    #[test]
350    fn export_with_details_redaction() {
351        let log = build_log();
352        let policy = RedactionPolicy {
353            redact: vec![RedactableField::Details],
354            replacement: "***".to_string(),
355        };
356        let exported = log.export(&policy);
357        for line in exported.lines() {
358            let entry: serde_json::Value = serde_json::from_str(line).unwrap();
359            assert_eq!(entry["details"], "***");
360        }
361    }
362
363    #[test]
364    fn audit_action_serde_roundtrip() {
365        let actions = vec![
366            AuditAction::CredentialIssued,
367            AuditAction::CredentialPresented,
368            AuditAction::CredentialVerified,
369            AuditAction::CredentialRevoked,
370            AuditAction::ConsentGiven,
371            AuditAction::ConsentRevoked,
372            AuditAction::DidCreated,
373            AuditAction::DidResolved,
374        ];
375        for action in &actions {
376            let json = serde_json::to_string(action).unwrap();
377            let back: AuditAction = serde_json::from_str(&json).unwrap();
378            assert_eq!(*action, back);
379        }
380    }
381
382    #[test]
383    fn empty_log_verifies() {
384        let log = AuditLog::new();
385        assert!(log.verify_chain());
386        assert!(log.is_empty());
387    }
388}
baseid_pctf/audit.rs

baseid_pctf/
audit.rs
