road-runner-common 0.24.0

//! Snapshot envelope parsing, signature verification, and monotonic version
//! enforcement.
//!
//! The envelope's signature is an **HMAC-SHA256 over the payload string**,
//! keyed by the platform's existing gateway shared secret
//! (`AUTH_GATEWAY_HMAC_SECRET`) — the same secret every service already holds
//! for gateway identity-header verification, so adopting snapshot verification
//! needs no new key distribution. The MAC is domain-separated from the gateway
//! header contract by prefixing `cex.authz.snapshot.v1\n` to the message, so a
//! MAC minted for one protocol can never satisfy the other.
//!
//! Verification posture comes from `AUTHZ_SNAPSHOT_VERIFY`:
//!
//! - `off` (default): parse only — the historical channel-trusted posture
//!   (mesh mTLS / broker ACLs), unchanged for services that have not opted in.
//! - `warn`: verify and log a loud warning on a missing/invalid signature, but
//!   accept the snapshot. The rollout bake mode.
//! - `enforce`: a missing or invalid signature rejects the snapshot; the PDP
//!   keeps its last-good state, exactly like a `Stale` version.
//!
//! Trust note (deliberate trade): a shared-secret MAC means any holder of the
//! gateway secret can mint a valid snapshot signature — the property bought is
//! "a Kafka-only attacker cannot forge authz", not "only cex-iam can". The
//! secret's blast radius already includes gateway identity, so the two stand
//! or fall together, and rotation rides the existing gateway-secret rotation.

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

use super::model::{SnapshotEnvelope, SnapshotPayload};

const SCHEMA: &str = "cex.authz.snapshot.v1";
/// Domain separator so a snapshot MAC and a gateway-header MAC are never
/// interchangeable, even under the same key.
const MAC_DOMAIN: &str = "cex.authz.snapshot.v1\n";

#[derive(Debug, thiserror::Error)]
pub enum VerifyError {
    #[error("envelope parse failed: {0}")]
    Envelope(String),
    #[error("payload parse failed: {0}")]
    Payload(String),
    #[error("unexpected schema: {0}")]
    Schema(String),
    #[error("stale version: {got} <= current {current}")]
    Stale { got: u64, current: u64 },
    #[error("signature rejected: {0}")]
    Signature(String),
}

/// How strictly the payload signature is checked.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum VerifyMode {
    Off,
    Warn,
    Enforce,
}

/// Parses authz snapshot envelopes, verifies the publisher's HMAC per the
/// configured [`VerifyMode`], and enforces schema + monotonic version.
#[derive(Clone, Default)]
pub struct SnapshotVerifier {
    mode: Option<VerifyMode>,
    secret: Option<Vec<u8>>,
}

/// The signature the publisher puts on the wire: lowercase-hex HMAC-SHA256
/// over `MAC_DOMAIN ‖ payload`. Exposed so cex-iam signs with the exact
/// function consumers verify with.
pub fn snapshot_mac(secret: &[u8], payload_str: &str) -> String {
    let mut mac =
        <Hmac<Sha256> as Mac>::new_from_slice(secret).expect("HMAC accepts keys of any size");
    mac.update(MAC_DOMAIN.as_bytes());
    mac.update(payload_str.as_bytes());
    hex::encode(mac.finalize().into_bytes())
}

fn macs_match(expected_hex: &str, provided_hex: &str) -> bool {
    use subtle::ConstantTimeEq;
    let (Ok(a), Ok(b)) = (hex::decode(expected_hex), hex::decode(provided_hex)) else {
        return false;
    };
    a.len() == b.len() && a.ct_eq(&b).into()
}

impl SnapshotVerifier {
    /// Keyless verifier (mode `Off`) — the historical constructor, kept so
    /// existing call sites keep their exact behavior until they opt in via
    /// [`SnapshotVerifier::from_env`].
    pub fn new() -> Self {
        Self { mode: Some(VerifyMode::Off), secret: None }
    }

    pub fn with_secret(mode: VerifyMode, secret: Vec<u8>) -> Self {
        Self { mode: Some(mode), secret: Some(secret) }
    }

    /// Resolve the mode from `AUTHZ_SNAPSHOT_VERIFY` and the key from the
    /// gateway shared secret (`AUTH_GATEWAY_HMAC_SECRET`) the service already
    /// holds.
    ///
    /// Fails loudly on a mode that names verification but has no secret — a
    /// `warn`/`enforce` verifier without a key would report every snapshot as
    /// unsigned, which is indistinguishable from an attack.
    pub fn from_env() -> Result<Self, String> {
        let mode = match std::env::var("AUTHZ_SNAPSHOT_VERIFY")
            .unwrap_or_default()
            .trim()
            .to_lowercase()
            .as_str()
        {
            "" | "off" => VerifyMode::Off,
            "warn" => VerifyMode::Warn,
            "enforce" => VerifyMode::Enforce,
            other => {
                return Err(format!("invalid AUTHZ_SNAPSHOT_VERIFY '{other}' (off|warn|enforce)"))
            }
        };
        let secret = std::env::var("AUTH_GATEWAY_HMAC_SECRET")
            .ok()
            .filter(|s| !s.trim().is_empty())
            .map(|s| s.into_bytes());
        if mode != VerifyMode::Off && secret.is_none() {
            return Err(
                "AUTHZ_SNAPSHOT_VERIFY is warn/enforce but AUTH_GATEWAY_HMAC_SECRET is not set"
                    .to_string(),
            );
        }
        Ok(Self { mode: Some(mode), secret })
    }

    fn mode(&self) -> VerifyMode {
        self.mode.unwrap_or(VerifyMode::Off)
    }

    /// Parse a raw envelope and its payload. `current_version` is what the PDP
    /// already holds; a snapshot must strictly advance it.
    pub fn verify(
        &self,
        envelope_bytes: &[u8],
        current_version: u64,
    ) -> Result<SnapshotPayload, VerifyError> {
        let envelope: SnapshotEnvelope = serde_json::from_slice(envelope_bytes)
            .map_err(|e| VerifyError::Envelope(e.to_string()))?;

        if self.mode() != VerifyMode::Off {
            if let Err(reason) = self.check_signature(&envelope) {
                match self.mode() {
                    VerifyMode::Enforce => return Err(VerifyError::Signature(reason)),
                    _ => tracing::warn!(
                        target: "security",
                        reason = %reason,
                        "authz snapshot signature rejected (warn mode: accepted)"
                    ),
                }
            }
        }

        let payload: SnapshotPayload = serde_json::from_str(&envelope.payload)
            .map_err(|e| VerifyError::Payload(e.to_string()))?;

        if payload.schema != SCHEMA {
            return Err(VerifyError::Schema(payload.schema));
        }
        if payload.policy_version <= current_version && current_version != 0 {
            return Err(VerifyError::Stale {
                got: payload.policy_version,
                current: current_version,
            });
        }
        Ok(payload)
    }

    fn check_signature(&self, envelope: &SnapshotEnvelope) -> Result<(), String> {
        let provided = envelope
            .signature
            .as_deref()
            .filter(|s| !s.is_empty())
            .ok_or_else(|| "envelope carries no signature".to_string())?;
        let secret = self
            .secret
            .as_deref()
            .ok_or_else(|| "verifier has no secret configured".to_string())?;
        let expected = snapshot_mac(secret, &envelope.payload);
        if macs_match(&expected, provided) {
            Ok(())
        } else {
            Err("HMAC verification failed".to_string())
        }
    }
}

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

    const SECRET: &[u8] = b"test-gateway-secret";

    fn payload_str(version: u64) -> String {
        serde_json::json!({
            "schema": SCHEMA,
            "policy_version": version,
            "issued_at": "2026-07-08T00:00:00Z",
            "permissions": [],
            "roles": [],
            "grants": [],
            "bindings": []
        })
        .to_string()
    }

    fn make_envelope(version: u64) -> Vec<u8> {
        serde_json::to_vec(&serde_json::json!({
            "payload": payload_str(version),
            "signature": ""
        }))
        .unwrap()
    }

    fn signed_envelope(version: u64, secret: &[u8]) -> Vec<u8> {
        let payload = payload_str(version);
        let signature = snapshot_mac(secret, &payload);
        serde_json::to_vec(&serde_json::json!({
            "payload": payload,
            "signature": signature
        }))
        .unwrap()
    }

    #[test]
    fn parses_and_enforces_monotonic_version() {
        let v = SnapshotVerifier::new();
        let p = v.verify(&make_envelope(5), 0).expect("first snapshot");
        assert_eq!(p.policy_version, 5);
        // Strictly-newer required.
        assert!(matches!(
            v.verify(&make_envelope(5), 5),
            Err(VerifyError::Stale { .. })
        ));
        assert!(v.verify(&make_envelope(6), 5).is_ok());
    }

    #[test]
    fn rejects_wrong_schema() {
        let v = SnapshotVerifier::new();
        let bad = serde_json::to_vec(&serde_json::json!({
            "payload": serde_json::json!({"schema":"nope","policy_version":1,"permissions":[],"roles":[],"grants":[],"bindings":[]}).to_string(),
            "signature": ""
        })).unwrap();
        assert!(matches!(v.verify(&bad, 0), Err(VerifyError::Schema(_))));
    }

    #[test]
    fn enforce_accepts_valid_mac_and_rejects_missing_or_forged() {
        let v = SnapshotVerifier::with_secret(VerifyMode::Enforce, SECRET.to_vec());

        assert!(v.verify(&signed_envelope(3, SECRET), 0).is_ok());
        // Unsigned envelope rejected.
        assert!(matches!(
            v.verify(&make_envelope(3), 0),
            Err(VerifyError::Signature(_))
        ));
        // MAC under a different secret rejected.
        assert!(matches!(
            v.verify(&signed_envelope(3, b"other-secret"), 0),
            Err(VerifyError::Signature(_))
        ));
    }

    #[test]
    fn warn_mode_accepts_but_off_mode_never_checks() {
        let v = SnapshotVerifier::with_secret(VerifyMode::Warn, SECRET.to_vec());
        assert!(v.verify(&make_envelope(4), 0).is_ok());
        let off = SnapshotVerifier::new();
        assert!(off.verify(&make_envelope(4), 0).is_ok());
    }

    #[test]
    fn tampered_payload_fails_enforce() {
        let v = SnapshotVerifier::with_secret(VerifyMode::Enforce, SECRET.to_vec());
        // Sign version 3, then swap the payload for version 4 — MAC must fail.
        let signature = snapshot_mac(SECRET, &payload_str(3));
        let tampered = serde_json::to_vec(&serde_json::json!({
            "payload": payload_str(4),
            "signature": signature
        }))
        .unwrap();
        assert!(matches!(
            v.verify(&tampered, 0),
            Err(VerifyError::Signature(_))
        ));
    }

    /// The domain separator keeps a gateway-header MAC (same key, no prefix)
    /// from satisfying the snapshot check.
    #[test]
    fn a_mac_without_the_domain_separator_is_rejected() {
        use hmac::{Hmac, Mac};
        use sha2::Sha256;
        let payload = payload_str(3);
        let mut mac = <Hmac<Sha256> as Mac>::new_from_slice(SECRET).unwrap();
        mac.update(payload.as_bytes()); // no MAC_DOMAIN prefix
        let undomained = hex::encode(mac.finalize().into_bytes());
        let envelope = serde_json::to_vec(&serde_json::json!({
            "payload": payload,
            "signature": undomained
        }))
        .unwrap();
        let v = SnapshotVerifier::with_secret(VerifyMode::Enforce, SECRET.to_vec());
        assert!(matches!(v.verify(&envelope, 0), Err(VerifyError::Signature(_))));
    }
}