entropy-auth 2026.7.31

//! HMAC-SHA-256 request signing and verification.
//!
//! Provides [`HmacRequestSigner`] and [`HmacRequestVerifier`] for signing
//! and verifying HTTP requests using HMAC-SHA-256. The canonical string
//! format ensures that the method, path, timestamp, and body are all
//! covered by the signature, preventing tampering and replay attacks.
//!
//! # Canonical String Format
//!
//! The message signed is:
//!
//! ```text
//! {METHOD}\n{path}\n{timestamp}\n{body_sha256_hex}
//! ```
//!
//! where `body_sha256_hex` is the lowercase hex-encoded SHA-256 hash of the
//! request body. Hashing the body (rather than including it directly)
//! ensures the canonical string has bounded size regardless of body length.
//!
//! # Security
//!
//! - The shared secret is wrapped in [`Zeroizing`] and cleared from memory
//!   on drop.
//! - Signature verification uses constant-time comparison to prevent
//!   timing side-channel attacks.
//! - An optional `max_age_secs` parameter rejects requests with stale
//!   timestamps, mitigating replay attacks.

use core::fmt;

use crate::crypto::constant_time::constant_time_eq;
use crate::crypto::zeroize::Zeroizing;
use crate::crypto::{HmacSha256, Sha256};
use crate::encoding::{hex_decode, hex_encode};
use crate::util::log::{debug, trace, warn};
use crate::util::timestamp::Timestamp;

// ---------------------------------------------------------------------------
// Error type
// ---------------------------------------------------------------------------

/// The kind of error encountered during HMAC request verification.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum HmacAuthErrorKind {
    /// The provided signature is not valid hex.
    InvalidSignature,
    /// The signature does not match the computed HMAC.
    SignatureMismatch,
    /// The request timestamp is too old (replay protection).
    TimestampExpired,
    /// The timestamp string could not be parsed as a Unix epoch seconds value.
    InvalidTimestamp,
}

/// Error returned when HMAC request verification fails.
///
/// Error messages describe the failure category without revealing the
/// expected signature or secret material.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HmacAuthError {
    kind: HmacAuthErrorKind,
}

impl HmacAuthError {
    const fn new(kind: HmacAuthErrorKind) -> Self {
        Self { kind }
    }

    /// Returns `true` if the signature format was invalid.
    #[must_use]
    pub fn is_invalid_signature(&self) -> bool {
        self.kind == HmacAuthErrorKind::InvalidSignature
    }

    /// Returns `true` if the signature did not match.
    #[must_use]
    pub fn is_signature_mismatch(&self) -> bool {
        self.kind == HmacAuthErrorKind::SignatureMismatch
    }

    /// Returns `true` if the timestamp was too old.
    #[must_use]
    pub fn is_timestamp_expired(&self) -> bool {
        self.kind == HmacAuthErrorKind::TimestampExpired
    }

    /// Returns `true` if the timestamp could not be parsed.
    #[must_use]
    pub fn is_invalid_timestamp(&self) -> bool {
        self.kind == HmacAuthErrorKind::InvalidTimestamp
    }
}

impl fmt::Display for HmacAuthError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.kind {
            HmacAuthErrorKind::InvalidSignature => {
                write!(f, "hmac_auth: signature is not valid hex")
            }
            HmacAuthErrorKind::SignatureMismatch => {
                write!(f, "hmac_auth: signature does not match")
            }
            HmacAuthErrorKind::TimestampExpired => {
                write!(f, "hmac_auth: request timestamp has expired")
            }
            HmacAuthErrorKind::InvalidTimestamp => {
                write!(f, "hmac_auth: timestamp is not a valid integer")
            }
        }
    }
}

impl std::error::Error for HmacAuthError {}

// ---------------------------------------------------------------------------
// Canonical string construction
// ---------------------------------------------------------------------------

/// Builds the canonical string for HMAC signing.
///
/// Format: `{method}\n{path}\n{timestamp}\n{body_hash_hex}`
///
/// The body is hashed with SHA-256 to keep the canonical string at a
/// bounded size regardless of the body length.
///
/// SECURITY: fields are newline-delimited without escaping, so `method` and
/// `path` MUST NOT contain a newline (or other control character) — otherwise
/// a value could shift the field boundaries and let two semantically distinct
/// requests share one canonical string. Valid HTTP request lines never contain
/// control characters; callers passing raw attacker input as `method`/`path`
/// must reject control characters first. `timestamp` (decimal) and the
/// SHA-256 `body_hash_hex` are inherently free of delimiters.
fn build_canonical_string(method: &str, path: &str, timestamp: &str, body: &[u8]) -> String {
    let body_hash = Sha256::digest(body);
    let body_hash_hex = hex_encode(&body_hash);
    format!("{method}\n{path}\n{timestamp}\n{body_hash_hex}")
}

// ---------------------------------------------------------------------------
// HmacRequestSigner
// ---------------------------------------------------------------------------

/// Signs HTTP requests using HMAC-SHA-256.
///
/// The signer holds a shared secret and produces hex-encoded signatures
/// over the canonical representation of a request (method, path,
/// timestamp, body hash).
pub struct HmacRequestSigner {
    // SECURITY: The shared secret is zeroized on drop to prevent it
    // from lingering in process memory.
    secret: Zeroizing<Vec<u8>>,
}

impl HmacRequestSigner {
    /// Creates a new signer with the given shared secret.
    #[must_use]
    pub fn new(secret: Vec<u8>) -> Self {
        Self {
            secret: Zeroizing::new(secret),
        }
    }

    /// Signs a request and returns the hex-encoded HMAC-SHA-256 signature.
    ///
    /// The canonical string signed is:
    /// `{method}\n{path}\n{timestamp}\n{body_sha256_hex}`
    ///
    /// The returned signature is a public authentication tag (it is sent on
    /// the wire); the secret it is derived from never leaves the signer.
    ///
    /// # Examples
    ///
    /// ```
    /// use entropy_auth::{HmacRequestSigner, HmacRequestVerifier};
    ///
    /// let signer = HmacRequestSigner::new(b"shared-secret".to_vec());
    /// let sig = signer.sign("POST", "/api/v1/resource", "1700000000", b"{}");
    ///
    /// let verifier = HmacRequestVerifier::new(b"shared-secret".to_vec());
    /// assert!(verifier.verify("POST", "/api/v1/resource", "1700000000", b"{}", &sig).is_ok());
    /// ```
    #[must_use]
    pub fn sign(&self, method: &str, path: &str, timestamp: &str, body: &[u8]) -> String {
        let canonical = build_canonical_string(method, path, timestamp, body);
        // SECURITY: Log only the method and path — never the secret or signature.
        trace!(method, path, "hmac_auth: canonical string computed");
        let mac = HmacSha256::mac(&self.secret, canonical.as_bytes());
        let signature = hex_encode(&mac);
        debug!(method, path, "hmac_auth: signed request");
        signature
    }
}

// SECURITY: Debug does not reveal the secret or logger internals.
impl fmt::Debug for HmacRequestSigner {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("HmacRequestSigner")
            .field("secret", &"[REDACTED]")
            .finish_non_exhaustive()
    }
}

// ---------------------------------------------------------------------------
// HmacRequestVerifier
// ---------------------------------------------------------------------------

/// Verifies HMAC-SHA-256 signed HTTP requests.
///
/// The verifier holds the same shared secret as the signer and checks
/// that a provided signature matches the canonical representation of the
/// request. Optional replay protection rejects requests whose timestamp
/// is older than a configured maximum age.
pub struct HmacRequestVerifier {
    // SECURITY: The shared secret is zeroized on drop.
    secret: Zeroizing<Vec<u8>>,
    /// Maximum age of a request in seconds. `None` disables replay
    /// protection (useful for testing).
    max_age_secs: Option<u64>,
}

impl HmacRequestVerifier {
    /// Creates a new verifier with the given shared secret and no replay
    /// protection.
    #[must_use]
    pub fn new(secret: Vec<u8>) -> Self {
        Self {
            secret: Zeroizing::new(secret),
            max_age_secs: None,
        }
    }

    /// Sets the maximum age (in seconds) for request timestamps.
    ///
    /// Verification compares the absolute difference between the request
    /// timestamp and the current time, so a request is rejected with
    /// [`HmacAuthError::is_timestamp_expired`] when its timestamp is *either*
    /// older *or* more than `max_age_secs` in the future (the future bound
    /// tolerates modest clock skew while still bounding replay windows).
    #[must_use]
    pub fn with_max_age(mut self, max_age_secs: u64) -> Self {
        self.max_age_secs = Some(max_age_secs);
        self
    }

    /// Verifies the HMAC-SHA-256 signature of a request.
    ///
    /// # Arguments
    ///
    /// - `method` — HTTP method (e.g., `"POST"`).
    /// - `path` — Request path (e.g., `"/api/v1/resource"`).
    /// - `timestamp` — Unix epoch seconds as a decimal string.
    /// - `body` — Raw request body bytes.
    /// - `signature` — Hex-encoded HMAC-SHA-256 signature to verify.
    ///
    /// # Errors
    ///
    /// Returns [`HmacAuthError`] if:
    /// - The signature is not valid hex.
    /// - The signature does not match the computed HMAC (constant-time).
    /// - The timestamp has expired (if `max_age_secs` is configured).
    /// - The timestamp cannot be parsed as a `u64`.
    ///
    /// # Examples
    ///
    /// ```
    /// use entropy_auth::{HmacRequestSigner, HmacRequestVerifier};
    ///
    /// let signer = HmacRequestSigner::new(b"k".to_vec());
    /// let sig = signer.sign("GET", "/health", "1700000000", b"");
    ///
    /// let verifier = HmacRequestVerifier::new(b"k".to_vec());
    /// assert!(verifier.verify("GET", "/health", "1700000000", b"", &sig).is_ok());
    /// // A tampered path fails verification.
    /// assert!(verifier.verify("GET", "/admin", "1700000000", b"", &sig).is_err());
    /// ```
    pub fn verify(
        &self,
        method: &str,
        path: &str,
        timestamp: &str,
        body: &[u8],
        signature: &str,
    ) -> Result<(), HmacAuthError> {
        // Decode the provided signature from hex.
        let sig_bytes = hex_decode(signature).map_err(|_| {
            warn!(method, path, "hmac_auth: verification failed: invalid hex");
            HmacAuthError::new(HmacAuthErrorKind::InvalidSignature)
        })?;

        // SECURITY: Verify the signature BEFORE inspecting the timestamp. The
        // timestamp is covered by the signature, so a valid signature already
        // proves it is authentic; checking freshness first would let an
        // attacker with no valid signature distinguish InvalidTimestamp /
        // TimestampExpired from SignatureMismatch and so probe the accepted
        // clock window on unauthenticated input.
        let canonical = build_canonical_string(method, path, timestamp, body);
        let expected = HmacSha256::mac(&self.secret, canonical.as_bytes());

        // SECURITY: constant_time_eq prevents timing side-channel attacks.
        // An attacker must not be able to determine how many leading bytes
        // of their forged signature are correct.
        if !constant_time_eq(&sig_bytes, &expected) {
            warn!(
                method,
                path, "hmac_auth: verification failed: signature mismatch"
            );
            return Err(HmacAuthError::new(HmacAuthErrorKind::SignatureMismatch));
        }

        // Signature is valid; now enforce freshness on the (authenticated)
        // timestamp if replay protection is enabled.
        if let Some(max_age) = self.max_age_secs {
            let request_secs: u64 = timestamp.parse().map_err(|_| {
                warn!(
                    method,
                    path, "hmac_auth: verification failed: invalid timestamp"
                );
                HmacAuthError::new(HmacAuthErrorKind::InvalidTimestamp)
            })?;

            let now = Timestamp::now().unix_epoch_secs();

            // Allow for slight clock skew: reject if the request is
            // older than max_age seconds or more than max_age seconds
            // in the future.
            let age = now.abs_diff(request_secs);
            if age > max_age {
                warn!(method, path, "hmac_auth: request timestamp expired");
                return Err(HmacAuthError::new(HmacAuthErrorKind::TimestampExpired));
            }
        }

        debug!(method, path, "hmac_auth: request verified");

        Ok(())
    }
}

// SECURITY: Debug does not reveal the secret or logger internals.
impl fmt::Debug for HmacRequestVerifier {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("HmacRequestVerifier")
            .field("secret", &"[REDACTED]")
            .field("max_age_secs", &self.max_age_secs)
            .finish_non_exhaustive()
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    /// Shared test secret for deterministic tests.
    fn test_secret() -> Vec<u8> {
        b"test-shared-secret-key-for-hmac".to_vec()
    }

    // --- Sign and Verify Round-Trip ---

    #[test]
    fn sign_and_verify_round_trip() {
        let secret = test_secret();

        let signer = HmacRequestSigner::new(secret.clone());
        let verifier = HmacRequestVerifier::new(secret);

        let method = "POST";
        let path = "/api/v1/users";
        let timestamp = "1700000000";
        let body = b"hello world";

        let signature = signer.sign(method, path, timestamp, body);
        verifier
            .verify(method, path, timestamp, body, &signature)
            .expect("valid signature should verify");
    }

    #[test]
    fn sign_and_verify_empty_body() {
        let secret = test_secret();

        let signer = HmacRequestSigner::new(secret.clone());
        let verifier = HmacRequestVerifier::new(secret);

        let signature = signer.sign("GET", "/health", "1700000000", b"");
        verifier
            .verify("GET", "/health", "1700000000", b"", &signature)
            .expect("empty body should verify");
    }

    #[test]
    fn signature_is_deterministic() {
        let secret = test_secret();

        let signer = HmacRequestSigner::new(secret);

        let sig1 = signer.sign("POST", "/api", "1700000000", b"data");
        let sig2 = signer.sign("POST", "/api", "1700000000", b"data");
        assert_eq!(sig1, sig2, "same inputs should produce the same signature");
    }

    #[test]
    fn signature_is_hex_encoded() {
        let signer = HmacRequestSigner::new(test_secret());
        let sig = signer.sign("GET", "/", "0", b"");
        // HMAC-SHA-256 produces 32 bytes = 64 hex characters.
        assert_eq!(sig.len(), 64, "signature should be 64 hex chars");
        assert!(
            sig.chars().all(|c| c.is_ascii_hexdigit()),
            "signature should be valid hex: {sig}",
        );
    }

    // --- Tampered Body ---

    #[test]
    fn tampered_body_fails() {
        let secret = test_secret();

        let signer = HmacRequestSigner::new(secret.clone());
        let verifier = HmacRequestVerifier::new(secret);

        let signature = signer.sign("POST", "/api", "1700000000", b"original body");

        let err = verifier
            .verify("POST", "/api", "1700000000", b"tampered body", &signature)
            .unwrap_err();
        assert!(
            err.is_signature_mismatch(),
            "tampered body should produce SignatureMismatch",
        );
    }

    // --- Tampered Path ---

    #[test]
    fn tampered_path_fails() {
        let secret = test_secret();

        let signer = HmacRequestSigner::new(secret.clone());
        let verifier = HmacRequestVerifier::new(secret);

        let signature = signer.sign("POST", "/api/v1/users", "1700000000", b"body");

        let err = verifier
            .verify("POST", "/api/v1/admin", "1700000000", b"body", &signature)
            .unwrap_err();
        assert!(
            err.is_signature_mismatch(),
            "tampered path should produce SignatureMismatch",
        );
    }

    // --- Tampered Method ---

    #[test]
    fn tampered_method_fails() {
        let secret = test_secret();

        let signer = HmacRequestSigner::new(secret.clone());
        let verifier = HmacRequestVerifier::new(secret);

        let signature = signer.sign("POST", "/api", "1700000000", b"body");

        let err = verifier
            .verify("DELETE", "/api", "1700000000", b"body", &signature)
            .unwrap_err();
        assert!(err.is_signature_mismatch());
    }

    // --- Tampered Timestamp ---

    #[test]
    fn tampered_timestamp_fails() {
        let secret = test_secret();

        let signer = HmacRequestSigner::new(secret.clone());
        let verifier = HmacRequestVerifier::new(secret);

        let signature = signer.sign("POST", "/api", "1700000000", b"body");

        let err = verifier
            .verify("POST", "/api", "1700000001", b"body", &signature)
            .unwrap_err();
        assert!(err.is_signature_mismatch());
    }

    // --- Wrong Secret ---

    #[test]
    fn wrong_secret_fails() {
        let signer = HmacRequestSigner::new(b"secret-A".to_vec());
        let verifier = HmacRequestVerifier::new(b"secret-B".to_vec());

        let signature = signer.sign("GET", "/", "1700000000", b"");

        let err = verifier
            .verify("GET", "/", "1700000000", b"", &signature)
            .unwrap_err();
        assert!(
            err.is_signature_mismatch(),
            "wrong secret should produce SignatureMismatch",
        );
    }

    // --- Invalid Signature Format ---

    #[test]
    fn invalid_hex_signature_rejected() {
        let verifier = HmacRequestVerifier::new(test_secret());

        let err = verifier
            .verify("GET", "/", "1700000000", b"", "not-valid-hex!!!")
            .unwrap_err();
        assert!(
            err.is_invalid_signature(),
            "non-hex signature should produce InvalidSignature",
        );
    }

    // --- Replay Protection ---

    #[test]
    fn expired_timestamp_rejected() {
        let secret = test_secret();

        let signer = HmacRequestSigner::new(secret.clone());
        let verifier = HmacRequestVerifier::new(secret).with_max_age(300);

        // Use a timestamp from the distant past.
        let signature = signer.sign("GET", "/", "1000000000", b"");

        let err = verifier
            .verify("GET", "/", "1000000000", b"", &signature)
            .unwrap_err();
        assert!(
            err.is_timestamp_expired(),
            "stale timestamp should produce TimestampExpired",
        );
    }

    #[test]
    fn recent_timestamp_accepted_with_max_age() {
        let secret = test_secret();

        let signer = HmacRequestSigner::new(secret.clone());
        let verifier = HmacRequestVerifier::new(secret).with_max_age(300);

        // Use the current time as the timestamp.
        let now = Timestamp::now().unix_epoch_secs().to_string();
        let signature = signer.sign("GET", "/", &now, b"");

        verifier
            .verify("GET", "/", &now, b"", &signature)
            .expect("current timestamp should be accepted");
    }

    #[test]
    fn invalid_timestamp_string_rejected() {
        let signer = HmacRequestSigner::new(test_secret());
        let verifier = HmacRequestVerifier::new(test_secret()).with_max_age(300);

        // A VALID signature over a non-numeric timestamp: the signature passes,
        // then the (authenticated) timestamp fails to parse. An *invalid*
        // signature is rejected first — see `signature_checked_before_timestamp`.
        let sig = signer.sign("GET", "/", "not-a-number", b"");
        let err = verifier
            .verify("GET", "/", "not-a-number", b"", &sig)
            .unwrap_err();
        assert!(
            err.is_invalid_timestamp(),
            "non-numeric timestamp should produce InvalidTimestamp",
        );
    }

    #[test]
    fn signature_checked_before_timestamp() {
        // SECURITY: an unauthenticated request must not be able to learn
        // anything about the accepted clock window — a bad signature yields
        // SignatureMismatch regardless of how malformed/stale the timestamp is.
        let verifier = HmacRequestVerifier::new(test_secret()).with_max_age(300);
        let bogus_sig = "aa".repeat(32);

        for ts in ["not-a-number", "0", "9999999999"] {
            let err = verifier
                .verify("GET", "/", ts, b"", &bogus_sig)
                .unwrap_err();
            assert!(
                err.is_signature_mismatch(),
                "ts={ts}: bad signature must be rejected before timestamp checks",
            );
        }
    }

    // --- Debug Redaction ---

    #[test]
    fn signer_debug_redacts_secret() {
        let signer = HmacRequestSigner::new(b"super-secret".to_vec());
        let debug = format!("{signer:?}");
        assert!(debug.contains("[REDACTED]"));
        assert!(!debug.contains("super-secret"));
    }

    #[test]
    fn verifier_debug_redacts_secret() {
        let verifier = HmacRequestVerifier::new(b"super-secret".to_vec());
        let debug = format!("{verifier:?}");
        assert!(debug.contains("[REDACTED]"));
        assert!(!debug.contains("super-secret"));
    }

    // --- Error Display ---

    #[test]
    fn error_display_messages() {
        let cases = [
            (
                HmacAuthError::new(HmacAuthErrorKind::InvalidSignature),
                "hmac_auth: signature is not valid hex",
            ),
            (
                HmacAuthError::new(HmacAuthErrorKind::SignatureMismatch),
                "hmac_auth: signature does not match",
            ),
            (
                HmacAuthError::new(HmacAuthErrorKind::TimestampExpired),
                "hmac_auth: request timestamp has expired",
            ),
            (
                HmacAuthError::new(HmacAuthErrorKind::InvalidTimestamp),
                "hmac_auth: timestamp is not a valid integer",
            ),
        ];
        for (err, expected) in &cases {
            assert_eq!(err.to_string(), *expected);
        }
    }

    #[test]
    fn error_implements_std_error() {
        let err: Box<dyn std::error::Error> =
            Box::new(HmacAuthError::new(HmacAuthErrorKind::SignatureMismatch));
        let _ = err.to_string();
    }
}