tryaudex_core/

integrity.rs

use hmac::{Hmac, Mac};
use sha2::Sha256;

use crate::error::{AvError, Result};

type HmacSha256 = Hmac<Sha256>;

const HMAC_KEY_ENV: &str = "AUDEX_HMAC_KEY";

static WARNED_DEFAULT_KEY: std::sync::Once = std::sync::Once::new();

/// Returns true if the HMAC key is the hardcoded default (publicly known).
pub fn is_using_default_key() -> bool {
    std::env::var(HMAC_KEY_ENV).is_err()
}

/// Emit a one-time warning if the default key is in use.
/// Called on every audit write so the operator is aware.
pub fn warn_if_default_key() {
    if is_using_default_key() {
        WARNED_DEFAULT_KEY.call_once(|| {
            tracing::warn!(
                "AUDEX_HMAC_KEY is not set — audit log integrity uses a publicly known \
                 default key. Anyone with source access can forge a valid chain. \
                 Set AUDEX_HMAC_KEY to a secret value for tamper-evident logging."
            );
        });
    }
}

/// R6-M56: minimum length for an explicit AUDEX_HMAC_KEY. HMAC-SHA256
/// is technically secure with any key length, but a 1-byte key has only
/// 8 bits of entropy. 16 bytes (128 bits) is a reasonable floor.
const MIN_HMAC_KEY_LEN: usize = 16;

/// Get the HMAC key from env, or derive from the per-machine keystore
/// encryption key. The hardcoded default is only used if the keystore
/// key itself cannot be obtained (should not happen in practice).
pub(crate) fn get_hmac_key() -> Vec<u8> {
    if let Ok(k) = std::env::var(HMAC_KEY_ENV) {
        // R6-M56: reject trivially short keys.
        if k.len() < MIN_HMAC_KEY_LEN {
            tracing::error!(
                "AUDEX_HMAC_KEY is set but only {} bytes — minimum is {}. \
                 Falling back to keystore-derived key.",
                k.len(),
                MIN_HMAC_KEY_LEN
            );
        } else {
            return k.into_bytes();
        }
    }

    // Derive from the keystore encryption key (per-machine entropy)
    let enc_key = crate::keystore::get_or_create_key();
    let mut mac = HmacSha256::new_from_slice(&enc_key).expect("HMAC accepts any key length");
    mac.update(b"audex-hmac-key-derivation-v1");
    mac.finalize().into_bytes().to_vec()
}

/// Compute the HMAC for an audit line, chained with the previous hash.
/// Chain formula: HMAC(key, previous_hash || line_content)
pub fn compute_chain_hmac(line: &str, previous_hash: &str) -> String {
    let key = get_hmac_key();
    let mut mac = HmacSha256::new_from_slice(&key).expect("HMAC accepts any key length");
    mac.update(previous_hash.as_bytes());
    mac.update(line.as_bytes());
    hex::encode(mac.finalize().into_bytes())
}

/// Append integrity hash to an audit JSONL line.
/// Format: original_json\t#HMAC:hexhash
pub fn sign_line(line: &str, previous_hash: &str) -> String {
    let hash = compute_chain_hmac(line, previous_hash);
    format!("{}\t#HMAC:{}", line, hash)
}

/// Extract the content and HMAC from a signed line.
/// Returns (content, hmac_hex) or (content, None) for unsigned lines.
///
/// R6-M55: validate that the hash suffix is well-formed hex of the
/// expected length. Without this, a garbage suffix (e.g. from a
/// corrupted file or an injected `\t#HMAC:` in the JSON body) would
/// pass through as `Some("garbage")`, then fail the equality check
/// in verify and be counted as "tampered" — which is technically
/// correct but masks the real problem and pollutes error messages.
pub fn parse_line(line: &str) -> (&str, Option<&str>) {
    if let Some(pos) = line.rfind("\t#HMAC:") {
        let content = &line[..pos];
        let hash = &line[pos + 7..];
        // SHA-256 hex is exactly 64 lowercase hex chars.
        if hash.len() == 64 && hash.bytes().all(|b| b.is_ascii_hexdigit()) {
            (content, Some(hash))
        } else {
            // Malformed HMAC suffix — treat as unsigned rather than
            // silently comparing garbage against a valid hash.
            (content, None)
        }
    } else {
        (line, None)
    }
}

/// R6-M54: constant-time comparison of two hex-encoded HMAC strings.
/// `==` on strings short-circuits on the first differing byte, leaking
/// information about which prefix of the expected hash is correct.
/// For audit-log integrity this is a low-severity finding (an attacker
/// who can submit lines and observe timing already has log write access),
/// but constant-time comparison is cheap and eliminates the class.
fn ct_eq(a: &str, b: &str) -> bool {
    let a = a.as_bytes();
    let b = b.as_bytes();
    if a.len() != b.len() {
        return false;
    }
    a.iter()
        .zip(b.iter())
        .fold(0u8, |acc, (x, y)| acc | (x ^ y))
        == 0
}

/// Verification result for a single line.
#[derive(Debug)]
pub struct LineVerification {
    pub line_number: usize,
    pub valid: bool,
    pub signed: bool,
    pub error: Option<String>,
}

/// Verification result for the entire audit log.
#[derive(Debug)]
pub struct VerificationResult {
    pub total_lines: usize,
    pub signed_lines: usize,
    pub unsigned_lines: usize,
    pub valid_lines: usize,
    pub tampered_lines: Vec<usize>,
    pub errors: Vec<LineVerification>,
}

impl VerificationResult {
    pub fn is_valid(&self) -> bool {
        self.tampered_lines.is_empty() && self.errors.is_empty()
    }
}

/// Verify the integrity of an audit log file.
///
/// R6-M53: stream the file line-by-line via BufRead instead of reading
/// the entire log into memory. Audit logs grow without bound in long-
/// running deployments; a 500 MB log would pin 500 MB of RAM during
/// verification under the old approach.
pub fn verify_audit_log(path: &std::path::Path) -> Result<VerificationResult> {
    use std::io::BufRead;

    if is_using_default_key() {
        eprintln!(
            "  \x1b[33m⚠\x1b[0m AUDEX_HMAC_KEY is not set — using the hardcoded default key. \
             Anyone with source access can forge a valid audit chain. \
             Set AUDEX_HMAC_KEY to a secret value for tamper-evident logging."
        );
    }

    if !path.exists() {
        return Err(AvError::InvalidPolicy("Audit log not found".to_string()));
    }

    let file = std::fs::File::open(path)?;
    let reader = std::io::BufReader::new(file);

    let mut result = VerificationResult {
        total_lines: 0,
        signed_lines: 0,
        unsigned_lines: 0,
        valid_lines: 0,
        tampered_lines: Vec::new(),
        errors: Vec::new(),
    };

    let mut previous_hash = "genesis".to_string();

    for line_result in reader.lines() {
        let line = line_result?;
        if line.trim().is_empty() {
            continue;
        }
        result.total_lines += 1;
        let line_num = result.total_lines;
        let (content, hmac) = parse_line(&line);

        match hmac {
            Some(expected_hash) => {
                result.signed_lines += 1;
                let computed = compute_chain_hmac(content, &previous_hash);
                if ct_eq(&computed, expected_hash) {
                    result.valid_lines += 1;
                    previous_hash = computed;
                } else {
                    result.tampered_lines.push(line_num);
                    result.errors.push(LineVerification {
                        line_number: line_num,
                        valid: false,
                        signed: true,
                        error: Some("HMAC mismatch — line may have been tampered with".to_string()),
                    });
                    // Continue chain with the *recomputed* hash from actual content,
                    // not the attacker-provided expected_hash. Using the attacker's
                    // hash would let a forged chain splice from the tampered line onward.
                    previous_hash = computed;
                }
            }
            None => {
                result.unsigned_lines += 1;
                // Unsigned lines (legacy) — skip chain validation but note them
                // Use content hash as chain input so future signed lines still chain
                previous_hash = compute_chain_hmac(content, &previous_hash);
            }
        }
    }

    Ok(result)
}

/// Read the last HMAC hash from an audit log file for chaining.
/// Returns "genesis" if the file is empty or has no signed lines.
///
/// R6-M53: stream line-by-line like verify_audit_log.
pub fn last_chain_hash(path: &std::path::Path) -> String {
    use std::io::BufRead;

    if !path.exists() {
        return "genesis".to_string();
    }

    let file = match std::fs::File::open(path) {
        Ok(f) => f,
        Err(_) => return "genesis".to_string(),
    };
    let reader = std::io::BufReader::new(file);

    let mut previous_hash = "genesis".to_string();

    // Recompute the chain from content rather than trusting stored HMACs,
    // so a tampered line cannot infect the chain going forward.
    for line_result in reader.lines() {
        let line = match line_result {
            Ok(l) => l,
            Err(_) => break,
        };
        if line.trim().is_empty() {
            continue;
        }
        let (content, _) = parse_line(&line);
        previous_hash = compute_chain_hmac(content, &previous_hash);
    }

    previous_hash
}

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

    #[test]
    fn test_sign_and_parse_line() {
        let line = r#"{"timestamp":"2026-04-05T10:00:00Z","session_id":"abc","provider":"aws","event":{"type":"session_created"}}"#;
        let signed = sign_line(line, "genesis");

        let (content, hmac) = parse_line(&signed);
        assert_eq!(content, line);
        assert!(hmac.is_some());
        assert_eq!(hmac.unwrap().len(), 64); // SHA256 hex
    }

    #[test]
    fn test_chain_deterministic() {
        let hash1 = compute_chain_hmac("line1", "genesis");
        let hash2 = compute_chain_hmac("line1", "genesis");
        assert_eq!(hash1, hash2);
    }

    #[test]
    fn test_chain_depends_on_previous() {
        let hash_a = compute_chain_hmac("line2", "hash_a");
        let hash_b = compute_chain_hmac("line2", "hash_b");
        assert_ne!(hash_a, hash_b);
    }

    #[test]
    fn test_unsigned_line_parsing() {
        let line = r#"{"timestamp":"2026-04-05T10:00:00Z","session_id":"abc"}"#;
        let (content, hmac) = parse_line(line);
        assert_eq!(content, line);
        assert!(hmac.is_none());
    }

    #[test]
    fn test_verify_valid_log() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("audit.jsonl");
        let mut file = std::fs::File::create(&path).unwrap();

        let line1 = r#"{"event":"one"}"#;
        let signed1 = sign_line(line1, "genesis");
        writeln!(file, "{}", signed1).unwrap();

        let hash1 = compute_chain_hmac(line1, "genesis");
        let line2 = r#"{"event":"two"}"#;
        let signed2 = sign_line(line2, &hash1);
        writeln!(file, "{}", signed2).unwrap();

        let result = verify_audit_log(&path).unwrap();
        assert_eq!(result.total_lines, 2);
        assert_eq!(result.signed_lines, 2);
        assert_eq!(result.valid_lines, 2);
        assert!(result.tampered_lines.is_empty());
        assert!(result.is_valid());
    }

    #[test]
    fn test_verify_tampered_log() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("audit.jsonl");
        let mut file = std::fs::File::create(&path).unwrap();

        let line1 = r#"{"event":"one"}"#;
        let signed1 = sign_line(line1, "genesis");
        writeln!(file, "{}", signed1).unwrap();

        // Write a tampered second line (wrong HMAC)
        let line2 = r#"{"event":"two"}"#;
        writeln!(
            file,
            "{}\t#HMAC:0000000000000000000000000000000000000000000000000000000000000000",
            line2
        )
        .unwrap();

        let result = verify_audit_log(&path).unwrap();
        assert_eq!(result.total_lines, 2);
        assert_eq!(result.tampered_lines, vec![2]);
        assert!(!result.is_valid());
    }

    #[test]
    fn test_verify_mixed_signed_unsigned() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("audit.jsonl");
        let mut file = std::fs::File::create(&path).unwrap();

        // Unsigned legacy line
        writeln!(file, r#"{{"event":"legacy"}}"#).unwrap();

        // Signed line after legacy
        let prev_hash = compute_chain_hmac(r#"{"event":"legacy"}"#, "genesis");
        let line2 = r#"{"event":"new"}"#;
        let signed2 = sign_line(line2, &prev_hash);
        writeln!(file, "{}", signed2).unwrap();

        let result = verify_audit_log(&path).unwrap();
        assert_eq!(result.total_lines, 2);
        assert_eq!(result.unsigned_lines, 1);
        assert_eq!(result.signed_lines, 1);
        assert_eq!(result.valid_lines, 1);
        assert!(result.is_valid());
    }

    #[test]
    fn test_last_chain_hash_empty() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("nonexistent.jsonl");
        assert_eq!(last_chain_hash(&path), "genesis");
    }

    #[test]
    fn test_last_chain_hash_with_entries() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("audit.jsonl");
        let mut file = std::fs::File::create(&path).unwrap();

        let line1 = r#"{"event":"one"}"#;
        let signed1 = sign_line(line1, "genesis");
        writeln!(file, "{}", signed1).unwrap();

        let expected_hash = compute_chain_hmac(line1, "genesis");
        assert_eq!(last_chain_hash(&path), expected_hash);
    }

    #[test]
    fn test_parse_line_rejects_malformed_hex() {
        // R6-M55: garbage after \t#HMAC: should be treated as unsigned.
        let line = "{\"event\":\"x\"}\t#HMAC:not_valid_hex_at_all";
        let (content, hmac) = parse_line(line);
        assert_eq!(content, "{\"event\":\"x\"}");
        assert!(
            hmac.is_none(),
            "malformed hex should be treated as unsigned"
        );

        // Wrong length (32 chars instead of 64).
        let short = format!("{{\"e\":1}}\t#HMAC:{}", "ab".repeat(16));
        let (_, hmac) = parse_line(&short);
        assert!(hmac.is_none(), "short hex should be treated as unsigned");

        // Valid 64-char hex passes through.
        let valid = format!("{{\"e\":1}}\t#HMAC:{}", "ab".repeat(32));
        let (_, hmac) = parse_line(&valid);
        assert!(hmac.is_some());
    }

    #[test]
    fn test_ct_eq() {
        // R6-M54: constant-time comparison.
        assert!(ct_eq("abcdef", "abcdef"));
        assert!(!ct_eq("abcdef", "abcdeg"));
        assert!(!ct_eq("abc", "abcd"));
        assert!(!ct_eq("", "a"));
        assert!(ct_eq("", ""));
    }
}