Struct AuditLog 

pub struct AuditLog { /* private fields */ }

Append-only JSONL audit log with within-session HMAC chain integrity.

The chain key is generated fresh at AuditLog::new() and is held only in memory for the lifetime of this handle. All entries appended through this handle form a verifiable chain via AuditLog::verify_chain(). Entries from prior sessions (different AuditLog instances) have prev_entry_hmac = None and act as chain anchors for the new session.

Implementations

impl AuditLog

pub fn new(path: &Path) -> Self

Create a handle to the audit log at path. The file is created lazily on first Self::append.

pub fn append(&self, entry: &AuditEntry) -> SafeResult<()>

Append an entry. The entry’s prev_entry_hmac is set to the HMAC of the previously written entry (within this session), then the entry is written and this handle’s chain state is advanced.

Errors here are non-fatal (caller should .ok() if audit is best-effort).

pub fn verify_chain(&self) -> Result<(), AuditVerifyError>

Verify the HMAC chain for all entries written by this session.

Reads the log file and replays the chain using this session’s key. Entries with prev_entry_hmac = None are treated as chain anchors (session boundaries or pre-v2 entries) — they reset the expected HMAC to None and verification continues from there.

Returns Ok(()) if every non-anchor entry’s prev_entry_hmac matches the HMAC computed from the previous entry. Returns AuditVerifyError::ChainBroken at the first mismatch.

pub fn read(&self, limit: Option<usize>) -> SafeResult<Vec<AuditEntry>>

Read entries, most recent first. Silently skip malformed lines.

pub fn explain(&self, limit: Option<usize>) -> SafeResult<AuditTimeline>

Read and project entries into plaintext-free explanation sessions.

pub fn last_successful_operation( &self, profile: &str, operation: &str, scan_limit: usize, ) -> SafeResult<Option<DateTime<Utc>>>

Most recent successful audit entry for this profile and operation, if any. Entries are scanned newest-first (up to scan_limit lines worth of entries).

pub fn filter_audit( &self, since: Option<DateTime<Utc>>, until: Option<DateTime<Utc>>, command: Option<&str>, ) -> SafeResult<Vec<AuditEntry>>

Return filtered audit entries.

All parameters are optional:

• since — only entries with timestamp >= since are returned.
• until — only entries with timestamp <= until are returned.
• command — only entries whose operation exactly matches this string.

Results are returned newest-first (matching read()).

pub fn prune_audit_before(&self, before: DateTime<Utc>) -> SafeResult<usize>

Remove all audit entries with timestamp < before (i.e. older than the cutoff).

Rewrites the log file atomically. Entries at or after before are kept. Returns the number of entries that were removed.

Note: pruning breaks the HMAC chain because it removes entries; the retained entries’ prev_entry_hmac values become invalid relative to the new session’s key. This is expected — prune is a privileged administrative operation.