envseal 0.3.14

//! Append-only audit log with SHA-256 hash chaining.
//!
//! Each entry stores `chain = SHA256(prev_chain || payload_json)`. On every
//! append we re-walk the entire log and verify the chain end-to-end before
//! adding a new line. Tampering with any historic line invalidates the
//! chain from that point forward.
//!
//! On Linux we additionally try to flip the file's `+a` (append-only)
//! attribute via `chattr`, which makes overwrites by the same UID
//! impossible without root.

use sha2::{Digest, Sha256};
use std::collections::HashMap;
use std::io::Write;
use std::path::PathBuf;
use std::sync::{Mutex, OnceLock};

use super::events::AuditEvent;
use crate::error::Error;

/// Per-vault-root mutex guarding the verify→hash→append critical
/// section of [`log_at`]. Two threads racing in the same process
/// for the same root would otherwise both read the same `prev`
/// chain hash and write entries whose `prev` values disagree —
/// the next verifier would see a "hash-chain mismatch" at the
/// later entry and rotate the log.
///
/// Map keyed by the canonicalized root path so distinct vaults
/// (multi-vault deployments, parallel tests under unique
/// tempdirs) don't serialize against each other unnecessarily.
/// LRU cap on the per-vault append-lock map. A long-running daemon
/// (desktop GUI, hosted MCP server) that touches many distinct
/// vault roots over its lifetime would otherwise grow this map
/// without bound. 256 vault roots per process is well above any
/// realistic deployment.
const APPEND_LOCK_CAP: usize = 256;

struct AppendLockEntry {
    lock: std::sync::Arc<Mutex<()>>,
    last_used: u64,
}

fn append_locks() -> &'static Mutex<HashMap<PathBuf, AppendLockEntry>> {
    static LOCKS: OnceLock<Mutex<HashMap<PathBuf, AppendLockEntry>>> = OnceLock::new();
    LOCKS.get_or_init(|| Mutex::new(HashMap::new()))
}

fn next_lock_tick() -> u64 {
    static TICK: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
    TICK.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
}

/// Hard cap on bytes read from `audit.log` for any single forensic
/// query. Beyond this, callers tail-truncate the read so a hostile
/// attacker with append access can't pin RAM by writing a multi-GB
/// log. 256 MiB is well past every realistic operator's audit
/// history (a busy vault generates a few MB / month of entries).
const AUDIT_LOG_MAX_READ: u64 = 256 * 1024 * 1024;

/// Read at most [`AUDIT_LOG_MAX_READ`] bytes from `path`, taken
/// from the **tail** of the file so the freshest entries always
/// win when we have to truncate. Used by every reader path that
/// needs to scan the log; the chain verifier still walks from the
/// genesis but operates on this truncated tail when the file is
/// oversized — a deliberate trade: we'd rather verify the recent
/// chain than refuse to verify at all.
fn read_audit_log_tail(path: &std::path::Path) -> std::io::Result<String> {
    use std::io::{Read, Seek, SeekFrom};
    // TOCTOU-free: refuse symlinks/reparse points at open time so a
    // hostile mid-race symlink can't redirect a forensic read away
    // from the real audit log. Convert envseal's typed refusal into
    // an io::Error so the function's signature stays unchanged.
    let mut file = crate::file::atomic_open::open_read_no_traverse(path).map_err(|e| match e {
        crate::error::Error::PolicyTampered(msg) => {
            std::io::Error::new(std::io::ErrorKind::PermissionDenied, msg)
        }
        crate::error::Error::StorageIo(io) => io,
        other => std::io::Error::other(format!("audit log open failed: {other}")),
    })?;
    let len = file.metadata()?.len();
    if len <= AUDIT_LOG_MAX_READ {
        let mut s = String::new();
        file.read_to_string(&mut s)?;
        return Ok(s);
    }
    file.seek(SeekFrom::Start(len - AUDIT_LOG_MAX_READ))?;
    let cap = usize::try_from(AUDIT_LOG_MAX_READ).unwrap_or(usize::MAX);
    let mut buf = Vec::with_capacity(cap);
    file.take(AUDIT_LOG_MAX_READ).read_to_end(&mut buf)?;
    // Drop the partial first line (we seeked into the middle of
    // one) so chain verification doesn't trip on it.
    let s = String::from_utf8_lossy(&buf).to_string();
    let trimmed = s.split_once('\n').map_or("", |(_, rest)| rest).to_string();
    Ok(trimmed)
}

fn append_lock_for(root: &std::path::Path) -> std::sync::Arc<Mutex<()>> {
    let key = std::fs::canonicalize(root).unwrap_or_else(|_| root.to_path_buf());
    let mut map = append_locks()
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    let tick = next_lock_tick();
    if let Some(existing) = map.get_mut(&key) {
        existing.last_used = tick;
        return existing.lock.clone();
    }
    if map.len() >= APPEND_LOCK_CAP {
        // Evict the least-recently-used entry. An in-flight append
        // holding a clone of the Arc keeps its mutex alive — the
        // eviction only drops the map's reference, not the live
        // mutex; the next call for the evicted root simply creates
        // a fresh mutex.
        if let Some(victim) = map
            .iter()
            .min_by_key(|(_, v)| v.last_used)
            .map(|(k, _)| k.clone())
        {
            map.remove(&victim);
        }
    }
    let lock = std::sync::Arc::new(Mutex::new(()));
    map.insert(
        key,
        AppendLockEntry {
            lock: lock.clone(),
            last_used: tick,
        },
    );
    lock
}

/// Append an event to the audit log of the *default* vault.
///
/// Convenience wrapper around [`log_at`] for callers that operate
/// against the default vault root (CLI, MCP, desktop GUI). Functions
/// that already hold a [`crate::vault::Vault`] handle should prefer
/// [`log_at`] with `vault.root()` so the audit trail and the vault
/// it audits stay co-located — important for tests that use temp
/// vault roots and for any future multi-vault deployment.
///
/// # Errors
///
/// Returns [`Error::AuditLogFailed`] if the log directory or file cannot be
/// created/opened/written, or if the existing chain fails to verify.
pub fn log(event: &AuditEvent) -> Result<(), Error> {
    let dir = default_audit_dir()?;
    log_at(&dir, event)
}

/// Append an event to the audit log under a specific vault root.
///
/// The audit log lives at `<root>/audit.log`. Each append re-walks
/// the existing chain to verify integrity before adding the new
/// entry — see the module-level docs.
///
/// # Errors
/// Same as [`log`].
pub fn log_at(root: &std::path::Path, event: &AuditEvent) -> Result<(), Error> {
    std::fs::create_dir_all(root)
        .map_err(|e| Error::AuditLogFailed(format!("failed to create audit directory: {e}")))?;

    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        std::fs::set_permissions(root, std::fs::Permissions::from_mode(0o700)).map_err(|e| {
            Error::AuditLogFailed(format!("failed to set audit directory permissions: {e}"))
        })?;
    }

    let log_path = root.join("audit.log");
    crate::guard::verify_not_symlink(&log_path)?;

    // Serialize concurrent appends to the same vault's log so the
    // verify → compute-chain → append sequence is atomic per
    // vault root. Without this two threads can both read the same
    // `prev` and produce divergent chains.
    //
    // Two-tier locking:
    //   1. In-process Arc<Mutex<()>> keyed by the canonical root path.
    //      Cheap, threads-only, never blocks if a single process
    //      drives the audit log.
    //   2. Cross-process flock / LockFileEx on `<root>/audit.log.lock`.
    //      Closes the gap when two CLI invocations from the same
    //      shell (or CLI + MCP + GUI under the same user) extend
    //      the chain concurrently.
    let lock = append_lock_for(root);
    let _append_guard = lock
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    let lock_path = root.join("audit.log.lock");
    // Defense in depth: refuse to lock through a symlink. An attacker
    // who is vault-owner-equivalent could otherwise plant a symlink
    // at `audit.log.lock` that redirects to a file in another vault's
    // directory; concurrent writers would then think they were
    // serializing against each other while actually holding unrelated
    // locks. The 0o700 audit dir already gates this on Unix, but the
    // check is cheap and runs symmetrically on Windows where the
    // parent-dir DACL enforcement varies by host.
    crate::guard::verify_not_symlink(&lock_path)?;
    let _xprocess_lock = crate::config::persistence::advisory_lock::acquire(&lock_path, true)
        .map_err(|e| {
            Error::AuditLogFailed(format!("audit cross-process lock acquire failed: {e}"))
        })?;

    // Canonicalize the chain-input payload so it matches the form
    // the verifier produces. `serde_json::to_string(event)` emits
    // fields in declaration order; `serde_json::to_string(&Value)`
    // emits fields in alphabetical order (BTreeMap iteration). For
    // any AuditEvent variant whose declaration order isn't
    // alphabetical (e.g. `SignalRecorded { tier, classification }`,
    // `SupervisorLeakDetected { secret, binary, leak_count }`) those
    // two paths produce different bytes → different SHA-256 → every
    // single append fails verify on the next read → rotate-corrupted
    // fires for entries the writer just produced. We were masking the
    // bug with the rotation failsafe; this fixes it by making both
    // sides hash the same canonical bytes.
    // Hold the canonical event JSON in a Zeroizing wrapper so the
    // heap allocation is wiped on drop — the body contains secret
    // names, binary paths, and signal classifications that the
    // encryption layer exists to keep off disk; we shouldn't leave
    // them lingering in process memory after the encrypt step
    // either.
    let event_plaintext = zeroize::Zeroizing::new(canonical_event_json(event)?);
    let sealed_hex = super::cipher::encrypt_event(root, event_plaintext.as_bytes())?;
    // Chain hashes the canonical body (everything except ts/pid/chain),
    // matching what the verifier in `check_one` reconstructs by
    // stripping those three envelope fields.
    let body_payload = canonical_sealed_payload(&sealed_hex);
    verify_chain_if_exists(&log_path)?;
    let prev = last_chain(&log_path).unwrap_or_else(|| "genesis".to_string());
    let chain = compute_chain(&prev, &body_payload);

    let mut line = build_entry_line(&now_iso8601(), std::process::id(), &chain, &sealed_hex)?;
    line.push('\n');

    let was_new = !log_path.exists();
    // TOCTOU-free open: the verify_not_symlink check above is
    // racy on Windows because the OS would otherwise follow a
    // reparse point planted between the check and the open.
    // open_append_no_traverse opens with FILE_FLAG_OPEN_REPARSE_POINT
    // and post-checks the handle's attribute bits, so an attacker
    // who slips a junction/symlink in during the race is refused
    // by the integrity check rather than redirected.
    let mut file = crate::file::atomic_open::open_append_no_traverse(&log_path)
        .map_err(|e| Error::AuditLogFailed(format!("failed to open audit log: {e}")))?;
    // Windows DACL is now applied at create time inside
    // `create_owner_only_append` via SECURITY_ATTRIBUTES — the
    // post-open `set_owner_only_dacl` call this used to make is
    // redundant and only widened the (already-closed) race window.
    #[cfg(target_os = "linux")]
    {
        let _ = std::process::Command::new("chattr")
            .args(["+a", "--", log_path.to_string_lossy().as_ref()])
            .output();
    }

    file.write_all(line.as_bytes())
        .map_err(|e| Error::AuditLogFailed(format!("failed to write audit log: {e}")))?;
    // fsync so a crash between this append and the next one cannot
    // leave a half-written line — which would later trip the
    // verifier and trigger a forensic-only chain rotation. Best-
    // effort: filesystems that don't honor sync_data still get the
    // write, just without the durability guarantee.
    let _ = file.sync_data();
    // On the first-write transition, fsync the parent directory too
    // so the new dirent for `audit.log` survives a crash. NTFS
    // journals metadata so this is a no-op on Windows; on
    // ext4/xfs/zfs the directory entry can be lost without an
    // explicit dir-fsync even though the file's data is on disk.
    if was_new {
        fsync_dir_best_effort(root);
    }

    Ok(())
}

/// Best-effort `fsync` of a directory. On Unix the kernel only
/// persists newly-created dirents after an explicit dir-fsync;
/// without it, a crash between create-file and the next dir
/// metadata flush can leave the file's data on disk but its name
/// missing. On Windows NTFS journals metadata so this is a no-op.
/// Errors are swallowed — durability is best-effort and we never
/// want to refuse a write because dir-fsync failed.
#[allow(unused_variables)]
fn fsync_dir_best_effort(dir: &std::path::Path) {
    #[cfg(unix)]
    {
        if let Ok(d) = std::fs::File::open(dir) {
            let _ = d.sync_all();
        }
    }
}

/// Append an audit record under the default vault, or return
/// [`Error::AuditLogFailed`].
///
/// Security-sensitive operations must use this (not [`log`] directly) so a
/// full disk or permission failure cannot complete a secret access without a
/// forensic record.
///
/// # Errors
/// See [`log`].
pub fn log_required(event: &AuditEvent) -> Result<(), Error> {
    log(event)
}

/// Like [`log_required`] but writes to a specific vault root. Use
/// when you hold a [`crate::vault::Vault`] handle.
///
/// # Errors
/// Same as [`log_at`].
pub fn log_required_at(root: &std::path::Path, event: &AuditEvent) -> Result<(), Error> {
    log_at(root, event)
}

/// Extract the value of a string-typed JSON field from a single
/// audit-log line, without pulling in `serde_json` for every caller
/// that just wants a status surface.
///
/// This is the deliberate counterpart to the heavier
/// `serde_json::from_str` path used by chain verification: the log
/// renderer needs only the `ts`, `event`, `binary`, and `secret`
/// fields and knows the lines are well-formed JSON because we
/// produced them. Returns `None` if the field is absent or its
/// value isn't a string literal.
#[must_use]
pub fn extract_json_field(json: &str, key: &str) -> Option<String> {
    let pattern = format!("\"{key}\":\"");
    let start = json.find(&pattern)? + pattern.len();
    let bytes = json.as_bytes();
    let mut end = start;
    while end < bytes.len() {
        let b = bytes[end];
        if b == b'\\' && end + 1 < bytes.len() {
            if bytes[end + 1] == b'u' && end + 5 < bytes.len() {
                // RFC 8259 §7: a non-BMP codepoint is encoded as a
                // surrogate pair `\uD8XX\uDCXX` (12 chars total). If
                // we only consumed 6 we'd stop in the middle of the
                // pair and the next iteration would see `\uDCXX`,
                // producing garbled-but-not-truncating output. When
                // the high half is in the surrogate range
                // (D800–DBFF) and a low half follows, consume both.
                let h0 = hex_nibble(bytes[end + 2]);
                let h1 = hex_nibble(bytes[end + 3]);
                let is_high_surrogate = matches!((h0, h1), (Some(0xD), Some(0x8..=0xB)));
                if is_high_surrogate
                    && end + 11 < bytes.len()
                    && bytes[end + 6] == b'\\'
                    && bytes[end + 7] == b'u'
                {
                    let l0 = hex_nibble(bytes[end + 8]);
                    let l1 = hex_nibble(bytes[end + 9]);
                    let is_low_surrogate = matches!((l0, l1), (Some(0xD), Some(0xC..=0xF)));
                    if is_low_surrogate {
                        end += 12;
                        continue;
                    }
                }
                end += 6;
            } else {
                end += 2; // skip escaped character
            }
        } else if b == b'"' {
            break;
        } else {
            end += 1;
        }
    }
    if end >= bytes.len() || bytes[end] != b'"' {
        return None;
    }
    Some(json[start..end].to_string())
}

fn hex_nibble(b: u8) -> Option<u8> {
    match b {
        b'0'..=b'9' => Some(b - b'0'),
        b'a'..=b'f' => Some(b - b'a' + 10),
        b'A'..=b'F' => Some(b - b'A' + 10),
        _ => None,
    }
}

/// One audit log entry, parsed from a single JSON line. The
/// envelope fields (`ts`, `pid`, `chain`) are visible in plaintext
/// so a forensic verifier can walk the hash chain without holding
/// the audit key. The event itself is decrypted on the fly when the
/// per-vault audit key is available, and surfaced as
/// [`AuditEvent`].
///
/// On a different machine — or with a missing/rotated `audit.key` —
/// `event` will be `None` and the entry is reported with its
/// envelope only; the chain still verifies because chaining is
/// over the ciphertext, not the plaintext event.
#[derive(Debug)]
pub struct ParsedEntry {
    /// ISO 8601 timestamp.
    pub ts: String,
    /// Process ID that wrote the entry.
    pub pid: u32,
    /// SHA-256 chain hash for tamper detection.
    pub chain: String,
    /// The decrypted event payload. When the audit key is unavailable
    /// on the reading device this is the synthetic
    /// [`super::AuditEvent::EncryptedUnreadable`] placeholder so
    /// renderers can show a row instead of dropping the entry.
    pub event: super::AuditEvent,
    /// Encryption status — surfaced so a UI can flag "encrypted /
    /// can't decrypt" versus "legacy plaintext entry, please rotate".
    pub envelope: EnvelopeKind,
}

/// Distinguishes the two shapes of entry the reader may encounter:
/// the post-0.3.13 sealed envelope, or a legacy plaintext entry from
/// before the encrypted-audit-log migration.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EnvelopeKind {
    /// Sealed AES-256-GCM envelope under the per-vault audit key.
    Sealed,
    /// Legacy unencrypted entry (pre-0.3.13). Still chain-verifiable
    /// but exposes secret/binary names to anyone with read access.
    LegacyPlaintext,
}

/// Default vault root used when [`parse_entry`] is called without
/// one. Same resolution as [`default_audit_dir`], so the standalone
/// helper matches the writer's default.
fn parse_entry_default_root() -> Option<std::path::PathBuf> {
    default_audit_dir().ok()
}

/// Parse one JSON line into a typed [`ParsedEntry`], decrypting the
/// event payload using the audit key under the *default* vault root.
/// Returns `None` on lines that don't look like an audit entry at all.
#[must_use]
pub fn parse_entry(line: &str) -> Option<ParsedEntry> {
    let root = parse_entry_default_root()?;
    parse_entry_at(&root, line)
}

/// Like [`parse_entry`] but uses an explicit vault root for audit-key
/// lookup. Tests and multi-vault callers must use this form so the
/// entry is decrypted under the same key it was written with.
#[must_use]
pub fn parse_entry_at(root: &std::path::Path, line: &str) -> Option<ParsedEntry> {
    // A single legitimate audit line is a few hundred bytes. Cap
    // the parser at 8 MiB so a malicious append (or a corrupted
    // log with an unterminated line) cannot force serde_json into
    // a multi-gigabyte tree allocation during a forensic read.
    if line.len() > 8 * 1024 * 1024 {
        return None;
    }
    let value: serde_json::Value = serde_json::from_str(line).ok()?;
    let obj = value.as_object()?;
    let ts = obj.get("ts")?.as_str()?.to_string();
    let pid = u32::try_from(obj.get("pid")?.as_u64()?).ok()?;
    let chain = obj.get("chain")?.as_str()?.to_string();

    if let Some(sealed_hex) = obj.get("sealed").and_then(serde_json::Value::as_str) {
        let event = super::cipher::decrypt_event(root, sealed_hex)
            .ok()
            .and_then(|pt| serde_json::from_slice::<super::AuditEvent>(&pt).ok())
            .unwrap_or_else(|| super::AuditEvent::EncryptedUnreadable {
                reason: "audit key unavailable or entry corrupt on this device".to_string(),
            });
        return Some(ParsedEntry {
            ts,
            pid,
            chain,
            event,
            envelope: EnvelopeKind::Sealed,
        });
    }

    // Legacy plaintext entry — flatten-decode the event from the
    // remaining fields. Strip envelope fields so the typed enum's
    // tag-based decoder sees only the event body.
    let mut body = obj.clone();
    body.remove("ts");
    body.remove("pid");
    body.remove("chain");
    let event = serde_json::from_value::<super::AuditEvent>(serde_json::Value::Object(body))
        .unwrap_or_else(|_| super::AuditEvent::EncryptedUnreadable {
            reason: "legacy entry failed to parse".to_string(),
        });
    Some(ParsedEntry {
        ts,
        pid,
        chain,
        event,
        envelope: EnvelopeKind::LegacyPlaintext,
    })
}

/// Read the last `n` entries from the audit log under a specific
/// vault root, parsed into typed [`ParsedEntry`] values. Lines that
/// fail to parse are dropped from the result (reported through the
/// returned `dropped_lines` count so a UI can flag a corrupted
/// chain without locking up).
#[must_use]
pub fn read_last_parsed_at(root: &std::path::Path, n: usize) -> ParsedReadResult {
    let raw = read_last_at(root, n);
    let mut entries = Vec::with_capacity(raw.len());
    let mut dropped = 0_usize;
    for line in &raw {
        match parse_entry_at(root, line) {
            Some(p) => entries.push(p),
            None => dropped += 1,
        }
    }
    ParsedReadResult {
        entries,
        dropped_lines: dropped,
    }
}

/// Result of [`read_last_parsed_at`].
#[derive(Debug, Default)]
pub struct ParsedReadResult {
    /// Successfully parsed entries (newest first, same order as
    /// [`read_last_at`]).
    pub entries: Vec<ParsedEntry>,
    /// Count of lines that failed to parse — non-zero implies log
    /// corruption that the chain-verifier will catch on next write.
    pub dropped_lines: usize,
}

/// Read the last `n` entries from the *default* vault's audit log.
/// Returns entries in reverse chronological order (newest first).
#[must_use]
pub fn read_last(n: usize) -> Vec<String> {
    let Ok(dir) = default_audit_dir() else {
        return Vec::new();
    };
    read_last_at(&dir, n)
}

/// Read the last `n` entries from the audit log under a specific vault root.
#[must_use]
pub fn read_last_at(root: &std::path::Path, n: usize) -> Vec<String> {
    let log_path = root.join("audit.log");
    let Ok(contents) = read_audit_log_tail(&log_path) else {
        return Vec::new();
    };
    contents.lines().rev().take(n).map(String::from).collect()
}

/// Filter criteria for audit log queries.
///
/// All fields are optional — an empty filter matches everything. When
/// multiple fields are set, they are `ANDed` (every condition must match).
#[derive(Debug, Default, Clone)]
pub struct AuditFilter {
    /// Case-insensitive substring match against the full JSON line.
    /// Matches secret names, binary paths, signal IDs, event types — any
    /// text in the log entry.
    pub query: Option<String>,
    /// Restrict to a specific event type tag (the `event` JSON field).
    /// Exact match, case-insensitive. Examples: `secret_stored`,
    /// `approval_result`, `signal_recorded`.
    pub event_type: Option<String>,
}

impl AuditFilter {
    /// Returns `true` if this filter has no constraints at all.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.query.is_none() && self.event_type.is_none()
    }

    /// Test whether a raw JSON log line passes all filter predicates.
    #[must_use]
    pub fn matches_line(&self, line: &str) -> bool {
        if let Some(q) = &self.query {
            let q_lower = q.to_ascii_lowercase();
            if !line.to_ascii_lowercase().contains(&q_lower) {
                return false;
            }
        }
        if let Some(et) = &self.event_type {
            let et_lower = et.to_ascii_lowercase();
            // Match the "event":"<type>" JSON field
            let pattern = format!("\"event\":\"{et_lower}\"");
            if !line.to_ascii_lowercase().contains(&pattern) {
                return false;
            }
        }
        true
    }
}

/// Read up to `n` entries from the default vault's audit log,
/// applying `filter` to each line before collection.
#[must_use]
pub fn read_last_filtered(n: usize, filter: &AuditFilter) -> Vec<String> {
    let Ok(dir) = default_audit_dir() else {
        return Vec::new();
    };
    read_last_filtered_at(&dir, n, filter)
}

/// Read up to `n` entries from the audit log under a specific vault
/// root, applying `filter` to each line. Newest-first order is
/// preserved; lines that don't match are skipped without counting
/// toward `n`.
#[must_use]
pub fn read_last_filtered_at(
    root: &std::path::Path,
    n: usize,
    filter: &AuditFilter,
) -> Vec<String> {
    if filter.is_empty() {
        return read_last_at(root, n);
    }
    let log_path = root.join("audit.log");
    let Ok(contents) = read_audit_log_tail(&log_path) else {
        return Vec::new();
    };
    contents
        .lines()
        .rev()
        .filter(|line| filter.matches_line(&decrypted_view_for_filter(root, line)))
        .take(n)
        .map(String::from)
        .collect()
}

/// Render the matchable view of a log line for [`AuditFilter`]. For
/// sealed entries this temporarily decrypts the inner event so a
/// substring filter on `secret` / `binary` names still works for the
/// vault's owner; failure to decrypt falls back to the raw line so
/// we never *hide* an entry from the operator.
fn decrypted_view_for_filter(root: &std::path::Path, line: &str) -> String {
    let Some(parsed) = parse_entry_at(root, line) else {
        return line.to_string();
    };
    if parsed.envelope == EnvelopeKind::LegacyPlaintext {
        return line.to_string();
    }
    // Build the view via serde_json::Value so the result is always
    // valid JSON — the previous string-concat path produced a
    // trailing comma when the event body serialized to `{}` (e.g.
    // a future zero-field variant), which would silently break any
    // downstream consumer that re-parses the synthesized line.
    let Ok(event_value) = serde_json::to_value(&parsed.event) else {
        return line.to_string();
    };
    let Some(event_obj) = event_value.as_object() else {
        return line.to_string();
    };
    let mut out = serde_json::Map::new();
    out.insert("ts".into(), serde_json::Value::String(parsed.ts.clone()));
    out.insert("pid".into(), serde_json::Value::Number(parsed.pid.into()));
    out.insert(
        "chain".into(),
        serde_json::Value::String(parsed.chain.clone()),
    );
    for (k, v) in event_obj {
        out.insert(k.clone(), v.clone());
    }
    serde_json::to_string(&serde_json::Value::Object(out)).unwrap_or_else(|_| line.to_string())
}

/// Like [`read_last_parsed_at`] but with filter support.
#[must_use]
pub fn read_last_parsed_filtered_at(
    root: &std::path::Path,
    n: usize,
    filter: &AuditFilter,
) -> ParsedReadResult {
    let raw = read_last_filtered_at(root, n, filter);
    let mut entries = Vec::with_capacity(raw.len());
    let mut dropped = 0_usize;
    for line in &raw {
        match parse_entry_at(root, line) {
            Some(p) => entries.push(p),
            None => dropped += 1,
        }
    }
    ParsedReadResult {
        entries,
        dropped_lines: dropped,
    }
}

/// Resolve the audit log directory for the default vault.
///
/// Co-located with the vault at `$XDG_CONFIG_HOME/envseal/` (Unix) or
/// `$HOME/.config/envseal/` so a single `~/.config/envseal/` directory
/// holds vault, security config, audit log, and policy. Matches
/// `crate::ops::vault_root` exactly so a vault and its audit trail
/// never end up in different parent directories.
pub(crate) fn default_audit_dir() -> Result<std::path::PathBuf, Error> {
    // Re-use the validated path logic from the vault so the audit log
    // and the vault it audits are co-located AND the same XDG_CONFIG_HOME
    // poisoning guards apply.
    crate::vault::store::default_vault_root()
        .map_err(|e| Error::AuditLogFailed(format!("cannot determine audit directory: {e}")))
}

/// Current time as ISO 8601 string (no external deps).
fn now_iso8601() -> String {
    let duration = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap_or_default();
    let secs = duration.as_secs();

    let days = secs / 86400;
    let time_of_day = secs % 86400;
    let hours = time_of_day / 3600;
    let minutes = (time_of_day % 3600) / 60;
    let seconds = time_of_day % 60;

    let mut y = 1970_i64;
    #[allow(clippy::cast_possible_wrap)]
    let mut remaining = days as i64;
    loop {
        let year_days = if is_leap(y) { 366 } else { 365 };
        if remaining < year_days {
            break;
        }
        remaining -= year_days;
        y += 1;
    }
    let leap = is_leap(y);
    let month_days: [i64; 12] = [
        31,
        if leap { 29 } else { 28 },
        31,
        30,
        31,
        30,
        31,
        31,
        30,
        31,
        30,
        31,
    ];
    let mut m = 0;
    for days_in_month in &month_days {
        if remaining < *days_in_month {
            break;
        }
        remaining -= days_in_month;
        m += 1;
    }

    format!(
        "{y:04}-{:02}-{:02}T{hours:02}:{minutes:02}:{seconds:02}Z",
        m + 1,
        remaining + 1,
    )
}

fn is_leap(y: i64) -> bool {
    (y % 4 == 0 && y % 100 != 0) || y % 400 == 0
}

/// Canonicalize an [`AuditEvent`] to its sorted-keys JSON form.
///
/// Both writer and verifier hash this same form so the chain
/// matches across roundtrips. Without this, the writer hashes
/// declaration-order JSON while the verifier hashes alphabetical-
/// order JSON (because the verifier roundtrips through
/// `serde_json::Value`, which uses `BTreeMap` internally) — every
/// non-alphabetically-declared variant produces a chain mismatch
/// the moment it's verified, and only the rotate-corrupted failsafe
/// kept the system usable.
fn canonical_event_json(event: &super::AuditEvent) -> Result<String, Error> {
    // Roundtrip through Value → forces fields into the same
    // alphabetical order the verifier sees. Failures here mean a
    // schema bug in `AuditEvent`, not user data — propagate them
    // as `AuditLogFailed` so the writer fails loudly instead of
    // appending an `{"error":"serialize"}` line that a forensic
    // reader can't make sense of.
    let raw = serde_json::to_string(event)
        .map_err(|e| Error::AuditLogFailed(format!("audit event serialize: {e}")))?;
    let value: serde_json::Value = serde_json::from_str(&raw)
        .map_err(|e| Error::AuditLogFailed(format!("audit event roundtrip parse: {e}")))?;
    serde_json::to_string(&value)
        .map_err(|e| Error::AuditLogFailed(format!("audit event roundtrip serialize: {e}")))
}

/// Canonical JSON for the chain-input body of a sealed entry.
/// Matches what `check_one` reconstructs by stripping ts/pid/chain
/// and re-serializing through `serde_json::Value` (`BTreeMap` ⇒
/// alphabetical keys).
fn canonical_sealed_payload(sealed_hex: &str) -> String {
    let mut obj = serde_json::Map::new();
    obj.insert(
        "sealed".to_string(),
        serde_json::Value::String(sealed_hex.to_string()),
    );
    serde_json::to_string(&serde_json::Value::Object(obj)).unwrap_or_default()
}

/// Serialize the full on-disk entry: envelope (`ts`, `pid`, `chain`)
/// alongside the sealed body. Field order in the JSON does not affect
/// chain computation (which only sees the body half) but kept stable
/// for human-readable forensics.
fn build_entry_line(ts: &str, pid: u32, chain: &str, sealed_hex: &str) -> Result<String, Error> {
    let mut obj = serde_json::Map::new();
    obj.insert("ts".to_string(), serde_json::Value::String(ts.to_string()));
    obj.insert("pid".to_string(), serde_json::Value::Number(pid.into()));
    obj.insert(
        "chain".to_string(),
        serde_json::Value::String(chain.to_string()),
    );
    obj.insert(
        "sealed".to_string(),
        serde_json::Value::String(sealed_hex.to_string()),
    );
    serde_json::to_string(&serde_json::Value::Object(obj))
        .map_err(|e| Error::AuditLogFailed(format!("failed to serialize audit entry: {e}")))
}

fn compute_chain(prev: &str, payload: &str) -> String {
    let mut hasher = Sha256::new();
    hasher.update(prev.as_bytes());
    hasher.update(payload.as_bytes());
    format!("{:x}", hasher.finalize())
}

fn last_chain(path: &std::path::Path) -> Option<String> {
    // Tail-bounded read so a multi-GB log doesn't force a full slurp
    // just to grab the previous chain hash on every append.
    let content = read_audit_log_tail(path).ok()?;
    content
        .lines()
        .rev()
        .find_map(|line| serde_json::from_str::<serde_json::Value>(line).ok())
        .and_then(|v| {
            v.get("chain")
                .and_then(serde_json::Value::as_str)
                .map(str::to_string)
        })
}

/// Walk the on-disk chain. On any mismatch (corruption, tamper, or
/// schema drift between writer versions), rotate the file to a
/// `audit.log.corrupted-<unix_ts>` sibling for forensics and return
/// `Ok` so the caller can start a fresh chain — refusing to continue
/// would otherwise lock the user out of the vault permanently the
/// moment ANY corruption sneaks in. The corrupted file is NEVER
/// deleted; it stays alongside the new chain for hand inspection.
/// Per-line cap for streaming chain verification. A multi-GB
/// unterminated line in `audit.log` would otherwise pin RAM during
/// `read_line`. 8 MiB is well above any legitimate sealed entry
/// (events are bounded enums).
const PER_LINE_CAP: u64 = 8 * 1024 * 1024;

fn verify_chain_if_exists(path: &std::path::Path) -> Result<(), Error> {
    use std::io::{BufRead, Read};
    if !path.exists() {
        return Ok(());
    }
    // Stream the file line-by-line via BufReader instead of slurping
    // the whole log into memory. A long-running vault accumulates
    // tens of MB of audit history; reading via read_to_string forced
    // the whole thing into a single String allocation and was the
    // slowest call on the append hot path. BufReader with a per-line
    // cap keeps peak memory bounded regardless of log size.
    //
    // TOCTOU: open via the no-traverse helper so an attacker-planted
    // symlink between the exists() check and the open is refused
    // rather than silently redirecting verification to attacker-
    // controlled content. A NotFound on this open (someone unlinked
    // the file mid-race) is treated the same as the path not
    // existing — there is nothing to verify.
    let file = match crate::file::atomic_open::open_read_no_traverse(path) {
        Ok(f) => f,
        Err(Error::StorageIo(e)) if e.kind() == std::io::ErrorKind::NotFound => return Ok(()),
        Err(e) => return Err(e),
    };
    let reader = std::io::BufReader::new(file);
    let mut prev = "genesis".to_string();
    let mut line_no = 0_usize;
    let mut buf = String::new();
    let mut br = reader;
    loop {
        buf.clear();
        // Hard cap the per-line read so a multi-GB unterminated
        // line cannot pin RAM during chain verification.
        let mut limited = (&mut br).take(PER_LINE_CAP);
        let n = limited.read_line(&mut buf)?;
        if n == 0 {
            break;
        }
        line_no += 1;
        let trimmed = buf.trim_end_matches('\n').trim_end_matches('\r');
        match check_one(&prev, trimmed) {
            Ok(next_chain) => prev = next_chain,
            Err(reason) => {
                rotate_corrupted(path, line_no, &reason)?;
                return Ok(());
            }
        }
    }
    Ok(())
}

/// Verify a single entry against the previous chain hash.
/// Returns the new chain value on success, or a human-readable
/// reason on failure.
fn check_one(prev: &str, line: &str) -> Result<String, String> {
    let value: serde_json::Value =
        serde_json::from_str(line).map_err(|e| format!("parse failure: {e}"))?;
    let chain = value
        .get("chain")
        .and_then(serde_json::Value::as_str)
        .ok_or_else(|| "chain field missing".to_string())?
        .to_string();
    let mut obj = value
        .as_object()
        .ok_or_else(|| "entry is not a JSON object".to_string())?
        .clone();
    obj.remove("chain");
    obj.remove("ts");
    obj.remove("pid");
    let payload = serde_json::to_string(&serde_json::Value::Object(obj)).unwrap_or_default();
    let expected = compute_chain(prev, &payload);
    if crate::guard::constant_time_eq(expected.as_bytes(), chain.as_bytes()) {
        Ok(chain)
    } else {
        Err("hash-chain mismatch".to_string())
    }
}

/// Rotate a corrupted audit log to a timestamped sibling so the
/// forensic record survives, then return success — the caller will
/// start a fresh chain at the original path on its next append.
fn rotate_corrupted(path: &std::path::Path, bad_line: usize, reason: &str) -> Result<(), Error> {
    let ts = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map_or(0, |d| d.as_secs());
    let corrupted = path.with_file_name(format!("audit.log.corrupted-{ts}"));
    std::fs::rename(path, &corrupted)
        .map_err(|e| Error::AuditLogFailed(format!("failed to rotate corrupted audit log: {e}")))?;
    // Preserve append-only protection on the rotated file so an
    // attacker cannot destroy forensic evidence after triggering a
    // rotation via tampering.
    #[cfg(target_os = "linux")]
    {
        let _ = std::process::Command::new("chattr")
            .args(["+a", "--", corrupted.to_string_lossy().as_ref()])
            .output();
    }
    // Surface the rotation through the unified Signal pipeline so the
    // user's `security.toml` can demote this to `log` (don't bother
    // me about it — quiet vault) or promote it to `block` (paranoid
    // setup that wants any chain disturbance to halt operations).
    let _ = crate::guard::emit_signal_inline(
        crate::guard::Signal::new(
            crate::guard::SignalId::new("audit.chain.rotated_corruption"),
            crate::guard::Category::AuditFailure,
            crate::guard::Severity::Warn,
            "audit log corruption rotated",
            format!(
                "audit log corruption detected at line {bad_line} ({reason}). \
                 rotated to {corrupted_path} and started a fresh chain — the \
                 corrupted file is preserved for hand inspection; new entries \
                 continue under {original_path}",
                corrupted_path = corrupted.display(),
                original_path = path.display()
            ),
            "inspect the rotated file for forensic evidence; the chain itself is back to clean",
        ),
        &crate::security_config::load_system_defaults(),
    );
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::audit::events::AuditEvent;

    #[test]
    fn end_to_end_seal_chain_verify_decrypt() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();

        // Two writes with distinct events — chain must extend.
        log_at(
            root,
            &AuditEvent::SecretStored {
                name: "OPENAI_API_KEY".to_string(),
            },
        )
        .unwrap();
        log_at(
            root,
            &AuditEvent::ApprovalResult {
                binary: "/usr/bin/cat".to_string(),
                secret: "DB_URL".to_string(),
                decision: "AllowOnce".to_string(),
            },
        )
        .unwrap();

        // Raw lines must NOT contain the plaintext secret name — the
        // confidentiality property the encryption was added for.
        let raw = std::fs::read_to_string(root.join("audit.log")).unwrap();
        assert!(
            !raw.contains("OPENAI_API_KEY"),
            "plaintext secret name leaked into audit log: {raw}"
        );
        assert!(!raw.contains("/usr/bin/cat"));
        assert!(!raw.contains("DB_URL"));

        // Reader must decrypt under the same vault root.
        let parsed = read_last_parsed_at(root, 10);
        assert_eq!(parsed.dropped_lines, 0);
        assert_eq!(parsed.entries.len(), 2);
        for entry in &parsed.entries {
            assert_eq!(entry.envelope, EnvelopeKind::Sealed);
        }
        // newest first → ApprovalResult was last written
        match &parsed.entries[0].event {
            AuditEvent::ApprovalResult {
                binary,
                secret,
                decision,
            } => {
                assert_eq!(binary, "/usr/bin/cat");
                assert_eq!(secret, "DB_URL");
                assert_eq!(decision, "AllowOnce");
            }
            other => panic!("unexpected event: {other:?}"),
        }

        // Chain must verify — third append with no prior corruption
        // would silently rotate if the chain were broken.
        log_at(
            root,
            &AuditEvent::SecretRevoked {
                name: "DB_URL".to_string(),
            },
        )
        .unwrap();
        let after = read_last_at(root, 10);
        assert_eq!(after.len(), 3);
        assert!(
            !root
                .join("audit.log")
                .parent()
                .unwrap()
                .read_dir()
                .unwrap()
                .any(|e| {
                    e.unwrap()
                        .file_name()
                        .to_string_lossy()
                        .starts_with("audit.log.corrupted-")
                }),
            "chain corruption rotation fired on a clean write sequence"
        );
    }

    #[test]
    fn filter_matches_decrypted_event_body() {
        let dir = tempfile::tempdir().unwrap();
        let root = dir.path();
        log_at(
            root,
            &AuditEvent::SecretStored {
                name: "PROD_DB_PASSWORD".to_string(),
            },
        )
        .unwrap();
        log_at(
            root,
            &AuditEvent::SecretStored {
                name: "STAGING_API_KEY".to_string(),
            },
        )
        .unwrap();
        let filter = AuditFilter {
            query: Some("PROD_DB".to_string()),
            event_type: None,
        };
        let results = read_last_filtered_at(root, 10, &filter);
        assert_eq!(
            results.len(),
            1,
            "filter should decrypt to match event body, got {results:?}"
        );
    }

    #[test]
    fn concurrent_appends_produce_no_chain_corruption() {
        // Hammer log_at from many threads against the same vault
        // root. Without the per-root append lock, two threads can
        // both read the same prev_chain and write entries with
        // disagreeing chain values — the next verifier rotates the
        // log to `audit.log.corrupted-*`. The lock guarantees the
        // verify→hash→append sequence is atomic per root.
        use std::sync::Arc;
        let dir = tempfile::tempdir().unwrap();
        let root = Arc::new(dir.path().to_path_buf());
        let mut handles = Vec::new();
        for i in 0..16 {
            let r = Arc::clone(&root);
            handles.push(std::thread::spawn(move || {
                for j in 0..8 {
                    log_at(
                        &r,
                        &AuditEvent::SecretStored {
                            name: format!("k-{i}-{j}"),
                        },
                    )
                    .unwrap();
                }
            }));
        }
        for h in handles {
            h.join().unwrap();
        }
        // No rotation must have fired: a single audit.log with
        // exactly the 128 expected entries, no `audit.log.corrupted-*`
        // siblings.
        let rotated = std::fs::read_dir(&*root)
            .unwrap()
            .filter_map(Result::ok)
            .filter(|e| {
                e.file_name()
                    .to_string_lossy()
                    .starts_with("audit.log.corrupted-")
            })
            .count();
        assert_eq!(rotated, 0, "race produced corrupted-rotation siblings");
        let n = read_last_at(&root, 1024).len();
        assert_eq!(n, 16 * 8, "lost an entry under contention");
    }

    #[test]
    fn parse_entry_rejects_oversized_line() {
        let dir = tempfile::tempdir().unwrap();
        let huge = "x".repeat(9 * 1024 * 1024);
        assert!(parse_entry_at(dir.path(), &huge).is_none());
    }

    #[test]
    fn now_iso8601_format() {
        let ts = now_iso8601();
        assert!(
            ts.starts_with("20"),
            "timestamp should start with 20xx: {ts}"
        );
        assert!(ts.ends_with('Z'), "timestamp should end with Z: {ts}");
        assert!(ts.contains('T'), "timestamp should contain T: {ts}");
    }
}