mur_core/

audit.rs

//! Audit logging with hash chain for tamper detection.
//!
//! Every action taken by MUR Commander is recorded in an append-only audit log.
//! Each entry is linked to the previous via SHA-256, forming a hash chain that
//! makes any tampering immediately detectable.

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use std::path::{Path, PathBuf};
use uuid::Uuid;

use crate::types::{ActionDecision, ActionType};

/// Errors specific to the audit system.
#[derive(Debug, thiserror::Error)]
pub enum AuditError {
    #[error("Failed to read audit log: {0}")]
    ReadError(#[from] std::io::Error),

    #[error("Failed to parse audit log: {0}")]
    ParseError(#[from] serde_json::Error),

    #[error("Hash chain broken at entry {index}: expected {expected}, got {actual}")]
    ChainBroken {
        index: usize,
        expected: String,
        actual: String,
    },
}

/// A single audit log entry with hash chain linkage.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AuditEntry {
    /// Unique ID for this audit entry.
    pub id: Uuid,
    /// Timestamp of this entry.
    pub timestamp: DateTime<Utc>,
    /// Session that generated this entry.
    pub session_id: String,
    /// Workflow being executed (if any).
    pub workflow_id: Option<String>,
    /// Type of action performed.
    pub action_type: ActionType,
    /// Human-readable description of the action.
    pub action_detail: String,
    /// AI model used (if any).
    pub model_used: Option<String>,
    /// API cost incurred (if any).
    pub cost: Option<f64>,
    /// SHA-256 hash of the input (privacy: don't store raw input).
    pub input_hash: String,
    /// Summary of the output.
    pub output_summary: String,
    /// Constitution decision for this action.
    pub decision: ActionDecision,
    /// Who approved this action ("user", "auto", "constitution").
    pub approved_by: Option<String>,
    /// Duration in milliseconds.
    pub duration_ms: u64,
    /// Whether the action succeeded.
    pub success: bool,
    /// Error message if the action failed.
    pub error: Option<String>,
    /// SHA-256 hash of the previous entry (forms the hash chain).
    pub prev_hash: String,
    /// SHA-256 hash of this entry's content + prev_hash.
    pub entry_hash: String,
}

/// Parameters for creating a new audit log entry.
#[derive(Debug, Clone)]
pub struct AuditLogParams {
    pub session_id: String,
    pub workflow_id: Option<String>,
    pub action_type: ActionType,
    pub action_detail: String,
    pub model_used: Option<String>,
    pub cost: Option<f64>,
    pub input_hash: String,
    pub output_summary: String,
    pub decision: ActionDecision,
    pub approved_by: Option<String>,
    pub duration_ms: u64,
    pub success: bool,
    pub error: Option<String>,
}

impl AuditEntry {
    /// Compute the hash for this entry based on its content and the previous hash.
    ///
    /// The hash covers all meaningful fields to ensure any modification is detected.
    #[allow(clippy::too_many_arguments)]
    fn compute_hash(
        id: &Uuid,
        timestamp: &DateTime<Utc>,
        session_id: &str,
        action_type: &ActionType,
        action_detail: &str,
        decision: &ActionDecision,
        success: bool,
        prev_hash: &str,
    ) -> String {
        let mut hasher = Sha256::new();
        hasher.update(id.to_string().as_bytes());
        hasher.update(timestamp.to_rfc3339().as_bytes());
        hasher.update(session_id.as_bytes());
        hasher.update(serde_json::to_string(action_type).unwrap_or_default().as_bytes());
        hasher.update(action_detail.as_bytes());
        hasher.update(serde_json::to_string(decision).unwrap_or_default().as_bytes());
        hasher.update(if success { &b"true"[..] } else { &b"false"[..] });
        hasher.update(prev_hash.as_bytes());
        let result = hasher.finalize();
        result.iter().map(|b| format!("{:02x}", b)).collect()
    }
}

/// Append-only audit store backed by a JSON file.
///
/// In a future phase, this will be backed by LanceDB for vector search
/// capabilities. For now, JSON file storage is sufficient and simple.
pub struct AuditStore {
    /// Path to the JSON audit log file.
    path: PathBuf,
    /// Cached last hash for append-only writes (avoids full reload).
    last_hash: std::sync::Mutex<Option<String>>,
}

impl AuditStore {
    /// Create a new audit store at the given path.
    pub fn new(path: &Path) -> Self {
        Self {
            path: path.to_path_buf(),
            last_hash: std::sync::Mutex::new(None),
        }
    }

    /// Create an audit store using a temporary file (for tests).
    pub fn new_memory() -> Self {
        let path = std::env::temp_dir()
            .join(format!("mur-audit-{}.jsonl", uuid::Uuid::new_v4()));
        Self {
            path,
            last_hash: std::sync::Mutex::new(None),
        }
    }

    /// Convenience: log an action with minimal params.
    pub fn log_action(&self, action: &crate::types::Action, status: &str, output: &str) {
        let params = AuditLogParams {
            session_id: "workflow".into(),
            workflow_id: None,
            action_type: action.action_type.clone(),
            action_detail: action.command.clone(),
            model_used: None,
            cost: None,
            input_hash: String::new(),
            output_summary: output.chars().take(200).collect(),
            decision: if status == "blocked" {
                crate::types::ActionDecision::Blocked {
                    reason: output.to_string(),
                }
            } else {
                crate::types::ActionDecision::Allowed
            },
            approved_by: None,
            duration_ms: 0,
            success: status != "blocked",
            error: if status == "blocked" {
                Some(output.to_string())
            } else {
                None
            },
        };
        if let Err(e) = self.log(params) {
            tracing::warn!("Failed to write audit log: {}", e);
        }
    }

    /// Append a new entry to the audit log.
    ///
    /// Automatically computes the hash chain linkage from the last entry.
    pub fn log(&self, params: AuditLogParams) -> Result<AuditEntry, AuditError> {
        // Get prev_hash from cache or read last line from file
        let prev_hash = {
            let mut cached = self.last_hash.lock().unwrap_or_else(|e| e.into_inner());
            if let Some(ref h) = *cached {
                h.clone()
            } else {
                // Read last line to get prev_hash (avoid loading entire file)
                let h = self.read_last_hash().unwrap_or_else(|| "0".repeat(64));
                *cached = Some(h.clone());
                h
            }
        };

        let id = Uuid::new_v4();
        let timestamp = Utc::now();

        let entry_hash = AuditEntry::compute_hash(
            &id,
            &timestamp,
            &params.session_id,
            &params.action_type,
            &params.action_detail,
            &params.decision,
            params.success,
            &prev_hash,
        );

        let entry = AuditEntry {
            id,
            timestamp,
            session_id: params.session_id,
            workflow_id: params.workflow_id,
            action_type: params.action_type,
            action_detail: params.action_detail,
            model_used: params.model_used,
            cost: params.cost,
            input_hash: params.input_hash,
            output_summary: params.output_summary,
            decision: params.decision,
            approved_by: params.approved_by,
            duration_ms: params.duration_ms,
            success: params.success,
            error: params.error,
            prev_hash,
            entry_hash: entry_hash.clone(),
        };

        // Append-only: write single JSON line
        self.append_entry(&entry)?;

        // Update cached last hash
        if let Ok(mut cached) = self.last_hash.lock() {
            *cached = Some(entry_hash);
        }

        Ok(entry)
    }

    /// Append a single entry as a JSON line (append-only, O(1)).
    fn append_entry(&self, entry: &AuditEntry) -> Result<(), AuditError> {
        use std::io::Write;
        if let Some(parent) = self.path.parent() {
            std::fs::create_dir_all(parent)?;
        }
        let mut file = std::fs::OpenOptions::new()
            .create(true)
            .append(true)
            .open(&self.path)?;
        let json = serde_json::to_string(entry)?;
        writeln!(file, "{}", json)?;
        Ok(())
    }

    /// Read the last entry's hash from the file without loading everything.
    fn read_last_hash(&self) -> Option<String> {
        if !self.path.exists() {
            return None;
        }
        // Read file and get last non-empty line
        let content = std::fs::read_to_string(&self.path).ok()?;
        let last_line = content.lines().rev().find(|l| !l.trim().is_empty())?;
        let entry: AuditEntry = serde_json::from_str(last_line).ok()?;
        Some(entry.entry_hash)
    }

    /// Load all audit entries from the log file.
    pub fn load_all(&self) -> Result<Vec<AuditEntry>, AuditError> {
        if !self.path.exists() {
            return Ok(Vec::new());
        }
        let content = std::fs::read_to_string(&self.path)?;
        if content.trim().is_empty() {
            return Ok(Vec::new());
        }
        // Support both JSONL (one entry per line) and legacy JSON array format
        if content.trim_start().starts_with('[') {
            let entries: Vec<AuditEntry> = serde_json::from_str(&content)?;
            Ok(entries)
        } else {
            let mut entries = Vec::new();
            for line in content.lines() {
                let line = line.trim();
                if line.is_empty() {
                    continue;
                }
                let entry: AuditEntry = serde_json::from_str(line)?;
                entries.push(entry);
            }
            Ok(entries)
        }
    }

    /// Query entries by workflow ID.
    pub fn query_by_workflow(&self, workflow_id: &str) -> Result<Vec<AuditEntry>, AuditError> {
        let entries = self.load_all()?;
        Ok(entries
            .into_iter()
            .filter(|e| e.workflow_id.as_deref() == Some(workflow_id))
            .collect())
    }

    /// Query entries within a time range.
    pub fn query_by_time_range(
        &self,
        from: DateTime<Utc>,
        to: DateTime<Utc>,
    ) -> Result<Vec<AuditEntry>, AuditError> {
        let entries = self.load_all()?;
        Ok(entries
            .into_iter()
            .filter(|e| e.timestamp >= from && e.timestamp <= to)
            .collect())
    }

    /// Get the most recent N entries.
    pub fn recent(&self, limit: usize) -> Result<Vec<AuditEntry>, AuditError> {
        let entries = self.load_all()?;
        let start = entries.len().saturating_sub(limit);
        Ok(entries[start..].to_vec())
    }

    /// Verify the integrity of the entire hash chain.
    ///
    /// Returns Ok(true) if the chain is valid, or an error describing
    /// where the chain was broken.
    pub fn verify_chain(&self) -> Result<bool, AuditError> {
        let entries = self.load_all()?;
        verify_chain(&entries)
    }

    /// Save all entries to the JSON file.
    /// Overwrite entire file (used for tamper simulation in tests).
    #[cfg(test)]
    fn save_all(&self, entries: &[AuditEntry]) -> Result<(), AuditError> {
        use std::io::Write;
        if let Some(parent) = self.path.parent() {
            std::fs::create_dir_all(parent)?;
        }
        let mut file = std::fs::File::create(&self.path)?;
        for entry in entries {
            let json = serde_json::to_string(entry)?;
            writeln!(file, "{}", json)?;
        }
        Ok(())
    }
}

/// Verify a hash chain given a slice of audit entries.
///
/// This is a pure function that can be used independently of the store.
pub fn verify_chain(entries: &[AuditEntry]) -> Result<bool, AuditError> {
    let genesis_hash = "0".repeat(64);

    for (i, entry) in entries.iter().enumerate() {
        // Check prev_hash linkage
        let expected_prev = if i == 0 {
            &genesis_hash
        } else {
            &entries[i - 1].entry_hash
        };

        if entry.prev_hash != *expected_prev {
            return Err(AuditError::ChainBroken {
                index: i,
                expected: expected_prev.clone(),
                actual: entry.prev_hash.clone(),
            });
        }

        // Recompute entry hash and verify
        let recomputed = AuditEntry::compute_hash(
            &entry.id,
            &entry.timestamp,
            &entry.session_id,
            &entry.action_type,
            &entry.action_detail,
            &entry.decision,
            entry.success,
            &entry.prev_hash,
        );

        if entry.entry_hash != recomputed {
            return Err(AuditError::ChainBroken {
                index: i,
                expected: recomputed,
                actual: entry.entry_hash.clone(),
            });
        }
    }

    Ok(true)
}

#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::TempDir;

    fn make_store() -> (AuditStore, TempDir) {
        let dir = TempDir::new().unwrap();
        let path = dir.path().join("audit.json");
        let store = AuditStore::new(&path);
        (store, dir)
    }

    fn log_test_entry(store: &AuditStore, detail: &str) -> AuditEntry {
        store
            .log(AuditLogParams {
                session_id: "test-session".into(),
                workflow_id: Some("test-workflow".into()),
                action_type: ActionType::Execute,
                action_detail: detail.to_string(),
                model_used: None,
                cost: None,
                input_hash: "input-hash-placeholder".into(),
                output_summary: "output summary".into(),
                decision: ActionDecision::Allowed,
                approved_by: Some("auto".into()),
                duration_ms: 100,
                success: true,
                error: None,
            })
            .expect("Failed to log entry")
    }

    #[test]
    fn test_log_single_entry() {
        let (store, _dir) = make_store();
        let entry = log_test_entry(&store, "test action");

        assert_eq!(entry.session_id, "test-session");
        assert_eq!(entry.action_detail, "test action");
        assert!(entry.success);
        // Genesis entry links to all-zero hash
        assert_eq!(entry.prev_hash, "0".repeat(64));
    }

    #[test]
    fn test_hash_chain_linkage() {
        let (store, _dir) = make_store();

        let entry1 = log_test_entry(&store, "first action");
        let entry2 = log_test_entry(&store, "second action");
        let entry3 = log_test_entry(&store, "third action");

        // Each entry's prev_hash should point to the previous entry's hash
        assert_eq!(entry2.prev_hash, entry1.entry_hash);
        assert_eq!(entry3.prev_hash, entry2.entry_hash);

        // All hashes should be unique
        assert_ne!(entry1.entry_hash, entry2.entry_hash);
        assert_ne!(entry2.entry_hash, entry3.entry_hash);
    }

    #[test]
    fn test_verify_chain_valid() {
        let (store, _dir) = make_store();

        log_test_entry(&store, "action 1");
        log_test_entry(&store, "action 2");
        log_test_entry(&store, "action 3");

        assert!(store.verify_chain().unwrap());
    }

    #[test]
    fn test_verify_chain_detects_tampered_entry() {
        let (store, _dir) = make_store();

        log_test_entry(&store, "action 1");
        log_test_entry(&store, "action 2");
        log_test_entry(&store, "action 3");

        // Tamper with an entry
        let mut entries = store.load_all().unwrap();
        entries[1].action_detail = "TAMPERED ACTION".into();
        store.save_all(&entries).unwrap();

        // Verify should fail
        let result = store.verify_chain();
        assert!(result.is_err());
        if let Err(AuditError::ChainBroken { index, .. }) = result {
            assert_eq!(index, 1);
        }
    }

    #[test]
    fn test_verify_chain_detects_broken_linkage() {
        let (store, _dir) = make_store();

        log_test_entry(&store, "action 1");
        log_test_entry(&store, "action 2");
        log_test_entry(&store, "action 3");

        // Break the chain by modifying prev_hash
        let mut entries = store.load_all().unwrap();
        entries[2].prev_hash = "0000000000000000000000000000000000000000000000000000000000000000".into();
        store.save_all(&entries).unwrap();

        let result = store.verify_chain();
        assert!(result.is_err());
    }

    #[test]
    fn test_verify_empty_chain() {
        let (store, _dir) = make_store();
        assert!(store.verify_chain().unwrap());
    }

    #[test]
    fn test_query_by_workflow() {
        let (store, _dir) = make_store();

        store
            .log(AuditLogParams {
                session_id: "sess1".into(),
                workflow_id: Some("workflow-a".into()),
                action_type: ActionType::Execute,
                action_detail: "action for A".into(),
                model_used: None,
                cost: None,
                input_hash: String::new(),
                output_summary: String::new(),
                decision: ActionDecision::Allowed,
                approved_by: None,
                duration_ms: 100,
                success: true,
                error: None,
            })
            .unwrap();

        store
            .log(AuditLogParams {
                session_id: "sess1".into(),
                workflow_id: Some("workflow-b".into()),
                action_type: ActionType::Read,
                action_detail: "action for B".into(),
                model_used: None,
                cost: None,
                input_hash: String::new(),
                output_summary: String::new(),
                decision: ActionDecision::Allowed,
                approved_by: None,
                duration_ms: 50,
                success: true,
                error: None,
            })
            .unwrap();

        let results = store.query_by_workflow("workflow-a").unwrap();
        assert_eq!(results.len(), 1);
        assert_eq!(results[0].action_detail, "action for A");
    }

    #[test]
    fn test_recent_entries() {
        let (store, _dir) = make_store();

        for i in 0..5 {
            log_test_entry(&store, &format!("action {}", i));
        }

        let recent = store.recent(2).unwrap();
        assert_eq!(recent.len(), 2);
        assert_eq!(recent[0].action_detail, "action 3");
        assert_eq!(recent[1].action_detail, "action 4");
    }

    #[test]
    fn test_persistence() {
        let dir = TempDir::new().unwrap();
        let path = dir.path().join("audit.json");

        // Write with one store instance
        {
            let store = AuditStore::new(&path);
            log_test_entry(&store, "persisted action");
        }

        // Read with a new store instance
        {
            let store = AuditStore::new(&path);
            let entries = store.load_all().unwrap();
            assert_eq!(entries.len(), 1);
            assert_eq!(entries[0].action_detail, "persisted action");
            assert!(store.verify_chain().unwrap());
        }
    }
}