libro 0.92.0

//! The audit chain — append-only, hash-linked sequence of entries.

use serde::{Deserialize, Serialize};
use tracing::{debug, info, warn};

use crate::LibroError;
use crate::entry::{AuditEntry, EventSeverity};
use crate::query::QueryFilter;
use crate::retention::RetentionPolicy;
use crate::verify::verify_chain;

/// An append-only audit chain with hash-linked entries.
///
/// Optionally enforces a maximum capacity. When set, appending beyond the
/// limit triggers automatic rotation — excess entries are drained into a
/// [`ChainArchive`] before the new entry is appended. Use
/// [`with_capacity`](AuditChain::with_capacity) to enable this.
#[derive(Debug, Default)]
pub struct AuditChain {
    pub(crate) entries: Vec<AuditEntry>,
    /// After rotation, holds the head hash of the previous chain for continuity.
    pub(crate) prev_chain_hash: Option<String>,
    /// Optional maximum number of entries before auto-rotation.
    max_capacity: Option<usize>,
    /// Accumulates archives produced by auto-rotation.
    overflow_archives: Vec<ChainArchive>,
}

/// Archived entries from a chain rotation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct ChainArchive {
    /// The drained entries.
    pub entries: Vec<AuditEntry>,
    /// The head hash of the archived chain (used to link the next chain).
    pub head_hash: String,
}

impl AuditChain {
    pub fn new() -> Self {
        Self::default()
    }

    /// Create a chain with a maximum entry capacity.
    ///
    /// When the chain reaches `max_entries`, the next append triggers an
    /// automatic rotation. Archived entries are accessible via
    /// [`take_overflow`](AuditChain::take_overflow).
    ///
    /// A capacity of `0` is treated as unlimited (no auto-rotation).
    pub fn with_capacity(max_entries: usize) -> Self {
        Self {
            max_capacity: if max_entries == 0 {
                None
            } else {
                Some(max_entries)
            },
            ..Self::default()
        }
    }

    /// Returns the configured maximum capacity, if any.
    #[inline]
    #[must_use]
    pub fn max_capacity(&self) -> Option<usize> {
        self.max_capacity
    }

    /// Drain and return all archives produced by auto-rotation.
    ///
    /// After calling this, the internal overflow buffer is empty until the
    /// next auto-rotation occurs.
    pub fn take_overflow(&mut self) -> Vec<ChainArchive> {
        std::mem::take(&mut self.overflow_archives)
    }

    /// Auto-rotate if at capacity. Called before each append.
    fn auto_rotate_if_full(&mut self) {
        if let Some(max) = self.max_capacity
            && self.entries.len() >= max
        {
            info!(
                max_capacity = max,
                entries = self.entries.len(),
                "auto-rotating chain at capacity"
            );
            let archive = self.rotate();
            self.overflow_archives.push(archive);
        }
    }

    /// Append an event to the chain. Automatically links to the previous entry's hash.
    ///
    /// If the chain has a configured [`max_capacity`](AuditChain::with_capacity)
    /// and is at the limit, the current entries are auto-rotated into an archive
    /// before appending. Retrieve archives with [`take_overflow`](AuditChain::take_overflow).
    pub fn append(
        &mut self,
        severity: EventSeverity,
        source: impl Into<String>,
        action: impl Into<String>,
        details: serde_json::Value,
    ) -> &AuditEntry {
        self.auto_rotate_if_full();
        let prev_hash = self
            .entries
            .last()
            .map(|e| e.hash().to_owned())
            .or_else(|| self.prev_chain_hash.clone())
            .unwrap_or_default();
        let entry = AuditEntry::new(severity, source, action, details, prev_hash);
        debug!(
            hash = entry.hash(),
            source = entry.source(),
            action = entry.action(),
            severity = entry.severity().as_str(),
            index = self.entries.len(),
            "chain entry appended"
        );
        self.entries.push(entry);
        self.entries.last().unwrap()
    }

    /// Append an event with an agent ID to the chain.
    pub fn append_with_agent(
        &mut self,
        severity: EventSeverity,
        source: impl Into<String>,
        action: impl Into<String>,
        details: serde_json::Value,
        agent_id: impl Into<String>,
    ) -> &AuditEntry {
        self.auto_rotate_if_full();
        let prev_hash = self
            .entries
            .last()
            .map(|e| e.hash().to_owned())
            .or_else(|| self.prev_chain_hash.clone())
            .unwrap_or_default();
        let entry =
            AuditEntry::new(severity, source, action, details, prev_hash).with_agent(agent_id);
        debug!(
            hash = entry.hash(),
            source = entry.source(),
            action = entry.action(),
            severity = entry.severity().as_str(),
            agent = entry.agent_id().unwrap_or(""),
            index = self.entries.len(),
            "chain entry appended"
        );
        self.entries.push(entry);
        self.entries.last().unwrap()
    }

    /// Number of entries in the chain.
    #[inline]
    #[must_use]
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    #[inline]
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

    /// Get all entries.
    #[inline]
    #[must_use]
    pub fn entries(&self) -> &[AuditEntry] {
        &self.entries
    }

    /// Get the last entry's hash (chain head).
    #[inline]
    #[must_use]
    pub fn head_hash(&self) -> Option<&str> {
        self.entries.last().map(|e| e.hash())
    }

    /// Verify the entire chain's integrity.
    ///
    /// Checks the genesis entry links to the expected previous chain hash
    /// (empty string for a fresh chain, or the archived head after rotation),
    /// then delegates entry-level hash and linkage verification to [`verify_chain`].
    pub fn verify(&self) -> crate::Result<()> {
        if self.entries.is_empty() {
            return Ok(());
        }

        // Verify genesis entry links correctly (accounts for rotation)
        let expected_genesis_prev = self.prev_chain_hash.as_deref().unwrap_or("");
        if self.entries[0].prev_hash() != expected_genesis_prev {
            return Err(LibroError::IntegrityViolation {
                index: 0,
                expected: expected_genesis_prev.to_owned(),
                actual: self.entries[0].prev_hash().to_owned(),
            });
        }

        let result = verify_chain(&self.entries);
        match &result {
            Ok(()) => info!(entries = self.entries.len(), "chain verification passed"),
            Err(e) => warn!(error = %e, "chain verification failed"),
        }
        result
    }

    /// Append multiple events in one call. Each entry is chained to the previous.
    /// Returns a slice of the newly appended entries.
    pub fn append_batch(
        &mut self,
        events: impl IntoIterator<Item = (EventSeverity, String, String, serde_json::Value)>,
    ) -> &[AuditEntry] {
        let start = self.entries.len();
        for (severity, source, action, details) in events {
            self.append(severity, source, action, details);
        }
        &self.entries[start..]
    }

    /// Query entries by source.
    pub fn by_source(&self, source: &str) -> Vec<&AuditEntry> {
        self.entries
            .iter()
            .filter(|e| e.source() == source)
            .collect()
    }

    /// Query entries by severity.
    pub fn by_severity(&self, severity: EventSeverity) -> Vec<&AuditEntry> {
        self.entries
            .iter()
            .filter(|e| e.severity() == severity)
            .collect()
    }

    /// Query entries by agent ID.
    pub fn by_agent(&self, agent_id: &str) -> Vec<&AuditEntry> {
        self.entries
            .iter()
            .filter(|e| e.agent_id() == Some(agent_id))
            .collect()
    }

    /// Return a page of entries: `offset` entries skipped, up to `limit` returned.
    pub fn page(&self, offset: usize, limit: usize) -> &[AuditEntry] {
        let start = offset.min(self.entries.len());
        let end = (start + limit).min(self.entries.len());
        &self.entries[start..end]
    }

    /// Query entries using a composable [`QueryFilter`].
    pub fn query(&self, filter: &QueryFilter) -> Vec<&AuditEntry> {
        filter.apply(&self.entries)
    }

    /// Rotate the chain: drain all current entries and return them as an archive.
    /// The next entry appended will link to the previous chain's head hash,
    /// preserving continuity across rotations.
    pub fn rotate(&mut self) -> ChainArchive {
        let head_hash = self.head_hash().unwrap_or("").to_owned();
        let entries = std::mem::take(&mut self.entries);
        if !head_hash.is_empty() {
            self.prev_chain_hash = Some(head_hash.clone());
        }
        info!(
            archived = entries.len(),
            head_hash = %head_hash,
            "chain rotated"
        );
        ChainArchive { entries, head_hash }
    }

    /// Restore a chain from an archive (e.g. for verification of historical data).
    pub fn from_entries(entries: Vec<AuditEntry>) -> Self {
        Self {
            entries,
            prev_chain_hash: None,
            max_capacity: None,
            overflow_archives: Vec::new(),
        }
    }

    /// Apply a retention policy, archiving entries that fall outside the
    /// retention window. Returns the archived entries (if any).
    ///
    /// The chain maintains integrity: the first retained entry links to
    /// the last archived entry's hash via `prev_chain_hash`.
    ///
    /// Returns `None` if no entries need archiving.
    pub fn apply_retention(&mut self, policy: &RetentionPolicy) -> Option<ChainArchive> {
        let split = policy.split_index(self.entries());
        if split == 0 {
            return None;
        }

        let mut all_entries = std::mem::take(&mut self.entries);
        let retained = all_entries.split_off(split);

        let head_hash = all_entries
            .last()
            .map(|e| e.hash().to_owned())
            .unwrap_or_default();

        self.entries = retained;
        self.prev_chain_hash = Some(head_hash.clone());

        info!(
            archived = all_entries.len(),
            retained = self.entries.len(),
            "retention policy applied"
        );

        Some(ChainArchive {
            entries: all_entries,
            head_hash,
        })
    }
}

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

    #[test]
    fn chain_append_and_verify() {
        let mut chain = AuditChain::new();
        chain.append(
            EventSeverity::Info,
            "daimon",
            "agent.start",
            serde_json::json!({}),
        );
        chain.append(
            EventSeverity::Info,
            "daimon",
            "agent.stop",
            serde_json::json!({}),
        );
        assert_eq!(chain.len(), 2);
        assert!(chain.verify().is_ok());
    }

    #[test]
    fn chain_detects_tamper() {
        let mut chain = AuditChain::new();
        chain.append(EventSeverity::Info, "src", "act", serde_json::json!({}));
        chain.append(EventSeverity::Info, "src", "act2", serde_json::json!({}));

        // Tamper with first entry
        chain.entries[0].corrupt_action("hacked");
        assert!(chain.verify().is_err());
    }

    #[test]
    fn chain_query() {
        let mut chain = AuditChain::new();
        chain.append(
            EventSeverity::Info,
            "daimon",
            "start",
            serde_json::json!({}),
        );
        chain.append(
            EventSeverity::Security,
            "aegis",
            "alert",
            serde_json::json!({}),
        );
        chain.append(EventSeverity::Info, "daimon", "stop", serde_json::json!({}));

        assert_eq!(chain.by_source("daimon").len(), 2);
        assert_eq!(chain.by_severity(EventSeverity::Security).len(), 1);
    }

    #[test]
    fn empty_chain_valid() {
        let chain = AuditChain::new();
        assert!(chain.verify().is_ok());
        assert!(chain.is_empty());
    }

    #[test]
    fn head_hash() {
        let mut chain = AuditChain::new();
        assert!(chain.head_hash().is_none());
        chain.append(EventSeverity::Info, "src", "act", serde_json::json!({}));
        assert!(chain.head_hash().is_some());
    }

    #[test]
    fn rotate_archives_and_continues() {
        let mut chain = AuditChain::new();
        chain.append(EventSeverity::Info, "src", "first", serde_json::json!({}));
        chain.append(EventSeverity::Info, "src", "second", serde_json::json!({}));
        let head_before = chain.head_hash().unwrap().to_owned();

        let archive = chain.rotate();
        assert_eq!(archive.entries.len(), 2);
        assert_eq!(archive.head_hash, head_before);
        assert!(chain.is_empty());

        // New entry links to the archived chain's head
        let entry = chain.append(EventSeverity::Info, "src", "third", serde_json::json!({}));
        assert_eq!(entry.prev_hash(), head_before);
        assert!(chain.verify().is_ok());
    }

    #[test]
    fn rotate_empty_chain() {
        let mut chain = AuditChain::new();
        let archive = chain.rotate();
        assert!(archive.entries.is_empty());
        assert_eq!(archive.head_hash, "");
        // Empty rotation should NOT set prev_chain_hash
        assert!(chain.prev_chain_hash.is_none());
    }

    #[test]
    fn from_entries_verifies() {
        let mut chain = AuditChain::new();
        chain.append(EventSeverity::Info, "s", "a", serde_json::json!({}));
        chain.append(EventSeverity::Info, "s", "b", serde_json::json!({}));
        let entries = chain.entries().to_vec();

        let restored = AuditChain::from_entries(entries);
        assert_eq!(restored.len(), 2);
        assert!(restored.verify().is_ok());
    }

    #[test]
    fn multiple_rotations() {
        let mut chain = AuditChain::new();
        chain.append(EventSeverity::Info, "src", "gen1", serde_json::json!({}));
        let archive1 = chain.rotate();

        chain.append(EventSeverity::Info, "src", "gen2", serde_json::json!({}));
        assert!(chain.verify().is_ok());
        assert_eq!(chain.entries()[0].prev_hash(), archive1.head_hash);

        let archive2 = chain.rotate();
        chain.append(EventSeverity::Info, "src", "gen3", serde_json::json!({}));
        assert!(chain.verify().is_ok());
        assert_eq!(chain.entries()[0].prev_hash(), archive2.head_hash);
    }

    #[test]
    fn by_agent() {
        let mut chain = AuditChain::new();
        chain.append(
            EventSeverity::Info,
            "daimon",
            "start",
            serde_json::json!({}),
        );
        chain.append_with_agent(
            EventSeverity::Info,
            "daimon",
            "task",
            serde_json::json!({}),
            "agent-01",
        );

        assert_eq!(chain.by_agent("agent-01").len(), 1);
        assert_eq!(chain.by_agent("nonexistent").len(), 0);
    }

    #[test]
    fn query_with_filter() {
        let mut chain = AuditChain::new();
        chain.append(
            EventSeverity::Info,
            "daimon",
            "start",
            serde_json::json!({}),
        );
        chain.append(
            EventSeverity::Security,
            "aegis",
            "alert",
            serde_json::json!({}),
        );
        chain.append(EventSeverity::Info, "daimon", "stop", serde_json::json!({}));

        let results = chain.query(
            &QueryFilter::new()
                .source("daimon")
                .severity(EventSeverity::Info),
        );
        assert_eq!(results.len(), 2);

        let results = chain.query(&QueryFilter::new().action("alert"));
        assert_eq!(results.len(), 1);
    }

    #[test]
    fn append_batch_chains_correctly() {
        let mut chain = AuditChain::new();
        let events = vec![
            (
                EventSeverity::Info,
                "daimon".to_owned(),
                "start".to_owned(),
                serde_json::json!({}),
            ),
            (
                EventSeverity::Security,
                "aegis".to_owned(),
                "alert".to_owned(),
                serde_json::json!({}),
            ),
            (
                EventSeverity::Info,
                "daimon".to_owned(),
                "stop".to_owned(),
                serde_json::json!({}),
            ),
        ];
        let appended = chain.append_batch(events);
        assert_eq!(appended.len(), 3);
        assert_eq!(chain.len(), 3);
        assert!(chain.verify().is_ok());
    }

    #[test]
    fn page_returns_slice() {
        let mut chain = AuditChain::new();
        for i in 0..10 {
            chain.append(
                EventSeverity::Info,
                "s",
                format!("e{i}"),
                serde_json::json!({}),
            );
        }
        assert_eq!(chain.page(0, 3).len(), 3);
        assert_eq!(chain.page(0, 3)[0].action(), "e0");
        assert_eq!(chain.page(3, 3).len(), 3);
        assert_eq!(chain.page(3, 3)[0].action(), "e3");
        assert_eq!(chain.page(8, 5).len(), 2); // only 2 left
        assert_eq!(chain.page(20, 5).len(), 0); // past end
    }

    #[test]
    fn verify_detects_bad_genesis_prev_hash() {
        // Manually construct a chain where genesis has wrong prev_hash
        let entry = AuditEntry::new(
            EventSeverity::Info,
            "s",
            "a",
            serde_json::json!({}),
            "bogus",
        );
        let chain = AuditChain::from_entries(vec![entry]);
        // from_entries sets prev_chain_hash to None, so expected genesis prev is ""
        let err = chain.verify().unwrap_err();
        assert!(err.to_string().contains("entry 0"));
    }

    #[test]
    fn verify_detects_broken_linkage() {
        let e1 = AuditEntry::new(EventSeverity::Info, "s", "a", serde_json::json!({}), "");
        let e2 = AuditEntry::new(
            EventSeverity::Info,
            "s",
            "b",
            serde_json::json!({}),
            "wrong-hash",
        );
        let chain = AuditChain::from_entries(vec![e1, e2]);
        let err = chain.verify().unwrap_err();
        assert!(err.to_string().contains("entry 1"));
    }

    #[test]
    fn verify_detects_tampered_self_hash() {
        let mut chain = AuditChain::new();
        chain.append(EventSeverity::Info, "s", "a", serde_json::json!({}));
        chain.append(EventSeverity::Info, "s", "b", serde_json::json!({}));
        // Tamper with the hash directly (not the content)
        chain.entries[1].corrupt_hash("tampered");
        let err = chain.verify().unwrap_err();
        assert!(err.to_string().contains("entry 1"));
    }

    #[test]
    fn append_with_agent_on_chain() {
        let mut chain = AuditChain::new();
        chain.append(
            EventSeverity::Info,
            "daimon",
            "start",
            serde_json::json!({}),
        );
        let head = chain.head_hash().unwrap().to_owned();
        let entry = chain.append_with_agent(
            EventSeverity::Info,
            "daimon",
            "task",
            serde_json::json!({}),
            "agent-007",
        );
        assert_eq!(entry.agent_id(), Some("agent-007"));
        assert_eq!(entry.prev_hash(), head);
        assert!(entry.verify());
        assert!(chain.verify().is_ok());
    }

    #[test]
    fn capacity_auto_rotates() {
        let mut chain = AuditChain::with_capacity(3);
        for i in 0..3 {
            chain.append(
                EventSeverity::Info,
                "s",
                format!("e{i}"),
                serde_json::json!({}),
            );
        }
        assert_eq!(chain.len(), 3);
        assert!(chain.take_overflow().is_empty());

        // 4th append triggers auto-rotation
        chain.append(EventSeverity::Info, "s", "e3", serde_json::json!({}));
        assert_eq!(chain.len(), 1);
        assert_eq!(chain.entries()[0].action(), "e3");

        let archives = chain.take_overflow();
        assert_eq!(archives.len(), 1);
        assert_eq!(archives[0].entries.len(), 3);

        // Chain still verifies
        assert!(chain.verify().is_ok());

        // New entry links to the archived chain's head
        assert_eq!(chain.entries()[0].prev_hash(), archives[0].head_hash);
    }

    #[test]
    fn capacity_zero_means_unlimited() {
        let mut chain = AuditChain::with_capacity(0);
        assert!(chain.max_capacity().is_none());
        for i in 0..100 {
            chain.append(
                EventSeverity::Info,
                "s",
                format!("e{i}"),
                serde_json::json!({}),
            );
        }
        assert_eq!(chain.len(), 100);
        assert!(chain.take_overflow().is_empty());
    }

    #[test]
    fn capacity_multiple_auto_rotations() {
        let mut chain = AuditChain::with_capacity(2);
        for i in 0..7 {
            chain.append(
                EventSeverity::Info,
                "s",
                format!("e{i}"),
                serde_json::json!({}),
            );
        }
        // 7 entries with capacity 2: rotations at 3rd, 5th, 7th append
        let archives = chain.take_overflow();
        assert_eq!(archives.len(), 3);
        assert!(chain.verify().is_ok());
    }

    #[test]
    fn capacity_with_agent_auto_rotates() {
        let mut chain = AuditChain::with_capacity(1);
        chain.append(EventSeverity::Info, "s", "e0", serde_json::json!({}));
        chain.append_with_agent(
            EventSeverity::Info,
            "s",
            "e1",
            serde_json::json!({}),
            "agent-01",
        );
        assert_eq!(chain.len(), 1);
        assert_eq!(chain.entries()[0].agent_id(), Some("agent-01"));
        assert_eq!(chain.take_overflow().len(), 1);
    }
}