openlatch-client 0.5.4

use chrono::{DateTime, Utc};
use serde::Serialize;

use super::CloudEvent;

#[derive(Debug, Clone, Serialize)]
pub struct TamperEvent {
    pub ocsf: OcsfHeader,
    pub tamper: TamperPayload,
}

#[derive(Debug, Clone, Serialize)]
pub struct OcsfHeader {
    pub class_uid: u32,
    pub activity_id: u32,
    pub type_uid: u32,
    pub severity_id: u32,
    pub time: DateTime<Utc>,
}

#[derive(Debug, Clone, Serialize)]
pub struct TamperPayload {
    pub event_id: String,
    pub entry_id: String,
    pub agent_type: String,
    pub settings_path_hash: String,
    pub hook_event: String,
    pub detection_method: String,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub field_deltas: Vec<FieldDelta>,
    pub heal: HealOutcome,
    /// Set on the follow-up `tamper_healed` event to the detection event's
    /// `event_id` so the platform can stitch the two halves together.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub related_event_id: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
pub struct FieldDelta {
    /// Dotted path of the changed field (e.g. `"hooks[0].url"`, `"timeout"`).
    /// Paths only — values are never serialised so the wire message cannot
    /// leak URLs, tokens, or other entry contents.
    pub field: String,
    /// One of `"modified" | "added" | "removed"`.
    pub change: String,
}

#[derive(Debug, Clone, Serialize)]
pub struct HealOutcome {
    pub outcome: String,
    pub attempt: u32,
    pub circuit: String,
}

/// Which half of the tamper event pair is being emitted. The OCSF `type_uid`
/// stays `200402` for both — differentiation is purely at the CloudEvent
/// `type` attribute so the platform can route them separately.
#[derive(Debug, Clone, Copy)]
pub enum TamperCloudEventKind {
    Detected,
    Healed,
}

impl TamperCloudEventKind {
    fn type_string(self) -> &'static str {
        match self {
            Self::Detected => "ai.openlatch.security.tamper_detected",
            Self::Healed => "ai.openlatch.security.tamper_healed",
        }
    }
}

/// A provider slot was wired to its relay endpoint, but the running editor
/// still holds the URL it read at start. Informational; healed once the editor
/// is proven to use the endpoint.
pub const DETECTION_RELAY_WIRING_PENDING: &str = "relay_wiring_pending";

/// Something put a provider slot's old URL back over the relay URL — a running
/// editor saving its in-memory settings, most often. Healed when the relay URL
/// is re-applied.
pub const DETECTION_RELAY_URL_REVERTED: &str = "relay_url_reverted";

/// The editor provably loaded the relay URL and is using the provider, yet no
/// traffic reaches the endpoint: something upstream of the file (an
/// organisation's remote configuration) is overriding it.
pub const DETECTION_RELAY_WIRING_MISCONFIGURED: &str = "relay_wiring_misconfigured";

/// The `hook_event` a relay wiring event carries. The slot is not a hook
/// registration; the slot key rides in `entry_id`.
pub const RELAY_WIRING_HOOK_EVENT: &str = "model_relay_endpoint";

/// Whether `detection_method` describes relay WIRING state rather than a hook
/// entry someone rewrote.
///
/// The local tamper log carries both, and `doctor`'s integrity section folds
/// the log into "hook entries still unhealed" — a pending wiring is not one.
/// Those states are reported by the model relay's own rows instead.
pub fn is_relay_wiring_method(detection_method: &str) -> bool {
    matches!(
        detection_method,
        DETECTION_RELAY_WIRING_PENDING
            | DETECTION_RELAY_URL_REVERTED
            | DETECTION_RELAY_WIRING_MISCONFIGURED
    )
}

impl TamperEvent {
    pub fn new(
        entry_id: String,
        agent_type: String,
        settings_path_hash: String,
        hook_event: String,
        detection_method: String,
    ) -> Self {
        // OCSF severity: 1 informational, 3 medium, 4 high. A wiring waiting on
        // an editor restart is expected; wiring that is provably overridden is
        // the one case where capture silently does not happen.
        let severity = match detection_method.as_str() {
            "legacy_marker_upgrade" | DETECTION_RELAY_WIRING_PENDING => 1,
            DETECTION_RELAY_WIRING_MISCONFIGURED => 4,
            _ => 3,
        };

        Self {
            ocsf: OcsfHeader {
                class_uid: 2004,
                activity_id: 2,
                type_uid: 200402,
                severity_id: severity,
                time: Utc::now(),
            },
            tamper: TamperPayload {
                event_id: uuid::Uuid::now_v7().to_string(),
                entry_id,
                agent_type,
                settings_path_hash,
                hook_event,
                detection_method,
                field_deltas: Vec::new(),
                heal: HealOutcome {
                    outcome: "pending".into(),
                    attempt: 0,
                    circuit: "closed".into(),
                },
                related_event_id: None,
            },
        }
    }

    pub fn with_heal(mut self, outcome: &str, attempt: u32, circuit: &str) -> Self {
        self.tamper.heal = HealOutcome {
            outcome: outcome.into(),
            attempt,
            circuit: circuit.into(),
        };
        self
    }

    /// Carry `event_id` instead of a fresh one.
    ///
    /// For re-building a detection event a previous process emitted, so its
    /// heal can link to it after a restart: the wiring pass persists the
    /// pending event's id, never the event.
    pub fn with_event_id(mut self, event_id: &str) -> Self {
        self.tamper.event_id = event_id.to_string();
        self
    }

    pub fn with_field_deltas(mut self, deltas: Vec<FieldDelta>) -> Self {
        self.tamper.field_deltas = deltas;
        self
    }

    /// Build the follow-up heal-outcome event from a detection event. Keeps
    /// `entry_id`, `agent_type`, `settings_path_hash`, `hook_event`, and
    /// `detection_method` aligned; assigns a fresh `event_id`; links back to
    /// the detection event via `related_event_id`.
    pub fn new_healed(original: &TamperEvent, outcome: &str, attempt: u32, circuit: &str) -> Self {
        Self {
            ocsf: OcsfHeader {
                time: Utc::now(),
                ..original.ocsf.clone()
            },
            tamper: TamperPayload {
                event_id: uuid::Uuid::now_v7().to_string(),
                heal: HealOutcome {
                    outcome: outcome.into(),
                    attempt,
                    circuit: circuit.into(),
                },
                related_event_id: Some(original.tamper.event_id.clone()),
                ..original.tamper.clone()
            },
        }
    }

    /// Wrap the tamper event in a CloudEvents v1.0.2 structured-mode envelope
    /// so it can travel through the existing cloud forwarding pipeline. The
    /// worker will stamp the `agentid` extension just before POST — we only
    /// populate the passthrough fields here.
    ///
    /// **No `subject`.** It used to carry `entry_id`, which is the id of a hook
    /// *registration*, not of a session — and the platform indexes `subject` as
    /// the session (`idx_unified_events_org_subject`), so every tamper event
    /// minted a fresh phantom session that nothing else could ever join. The id
    /// is not lost: it stays in `data.tamper.entry_id`, and a detected/healed
    /// pair still links through `data.tamper.related_event_id`. Leaving the
    /// attribute absent is also what lets the single egress
    /// (`cloud::worker::stamp_extensions`) fill it with a real session id —
    /// that stamp never overwrites a subject a producer set.
    pub fn to_cloud_event(
        &self,
        agent_id: &str,
        client_version: &str,
        os: &str,
        kind: TamperCloudEventKind,
    ) -> CloudEvent {
        let payload = serde_json::json!({
            "ocsf": self.ocsf,
            "tamper": self.tamper,
        });

        let envelope = serde_json::json!({
            "specversion": "1.0",
            "id": format!("evt_{}", self.tamper.event_id),
            "source": self.tamper.agent_type.as_str(),
            "type": kind.type_string(),
            "time": self.ocsf.time.to_rfc3339(),
            "datacontenttype": "application/json",
            "data": payload,
            "clientversion": client_version,
            "os": os,
        });

        CloudEvent {
            envelope,
            agent_id: agent_id.to_string(),
        }
    }
}

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

    fn make_event() -> TamperEvent {
        TamperEvent::new(
            "entry-id-123".into(),
            "claude-code".into(),
            "sha256:abc123".into(),
            "PreToolUse".into(),
            "hmac_mismatch".into(),
        )
    }

    #[test]
    fn ocsf_class_uid_is_2004() {
        let e = make_event();
        assert_eq!(e.ocsf.class_uid, 2004);
        assert_eq!(e.ocsf.activity_id, 2);
        assert_eq!(e.ocsf.type_uid, 200402);
    }

    #[test]
    fn severity_is_info_for_legacy_upgrade() {
        let e = TamperEvent::new(
            "id".into(),
            "claude-code".into(),
            "sha256:x".into(),
            "PreToolUse".into(),
            "legacy_marker_upgrade".into(),
        );
        assert_eq!(e.ocsf.severity_id, 1);
    }

    #[test]
    fn relay_wiring_severities_follow_what_they_mean() {
        let of = |method: &str| {
            TamperEvent::new(
                "cline:gs:shared:geminiBaseUrl".into(),
                "cline".into(),
                "sha256:x".into(),
                RELAY_WIRING_HOOK_EVENT.into(),
                method.into(),
            )
            .ocsf
            .severity_id
        };
        assert_eq!(of(DETECTION_RELAY_WIRING_PENDING), 1);
        assert_eq!(of(DETECTION_RELAY_URL_REVERTED), 3);
        assert_eq!(of(DETECTION_RELAY_WIRING_MISCONFIGURED), 4);
        assert!(is_relay_wiring_method(DETECTION_RELAY_URL_REVERTED));
        assert!(!is_relay_wiring_method("hmac_mismatch"));
    }

    #[test]
    fn severity_is_medium_for_hmac_mismatch() {
        let e = make_event();
        assert_eq!(e.ocsf.severity_id, 3);
    }

    #[test]
    fn no_settings_values_in_serialized_event() {
        let e = make_event();
        let json = serde_json::to_string(&e).unwrap();
        assert!(!json.contains("http://attacker"));
        assert!(!json.contains("Bearer "));
        assert!(!json.contains("OPENLATCH_TOKEN"));
    }

    #[test]
    fn no_settings_path_literal_in_serialized_event() {
        let e = TamperEvent::new(
            "id".into(),
            "claude-code".into(),
            "sha256:abc123def456".into(),
            "PreToolUse".into(),
            "hmac_mismatch".into(),
        );
        let json = serde_json::to_string(&e).unwrap();
        assert!(!json.contains(".claude"));
        assert!(!json.contains("settings.json"));
        assert!(json.contains("sha256:abc123def456"));
    }

    #[test]
    fn with_heal_sets_outcome() {
        let e = make_event().with_heal("succeeded", 2, "closed");
        assert_eq!(e.tamper.heal.outcome, "succeeded");
        assert_eq!(e.tamper.heal.attempt, 2);
    }

    #[test]
    fn event_id_is_uuid_v7() {
        let e = make_event();
        assert!(!e.tamper.event_id.is_empty());
    }

    #[test]
    fn related_event_id_absent_on_detection_event() {
        let e = make_event();
        let json = serde_json::to_string(&e).unwrap();
        assert!(
            !json.contains("related_event_id"),
            "detection events must not serialise related_event_id"
        );
    }

    #[test]
    fn new_healed_links_to_original() {
        let original = make_event();
        let healed = TamperEvent::new_healed(&original, "succeeded", 1, "closed");
        assert_eq!(
            healed.tamper.related_event_id.as_deref(),
            Some(original.tamper.event_id.as_str())
        );
        assert_ne!(healed.tamper.event_id, original.tamper.event_id);
        assert_eq!(healed.tamper.entry_id, original.tamper.entry_id);
        assert_eq!(healed.tamper.heal.outcome, "succeeded");
    }

    #[test]
    fn new_healed_preserves_detection_metadata() {
        let original = make_event();
        let healed = TamperEvent::new_healed(&original, "failed", 3, "open");
        assert_eq!(
            healed.tamper.detection_method,
            original.tamper.detection_method
        );
        assert_eq!(healed.tamper.agent_type, original.tamper.agent_type);
        assert_eq!(healed.tamper.hook_event, original.tamper.hook_event);
        assert_eq!(
            healed.tamper.settings_path_hash,
            original.tamper.settings_path_hash
        );
    }

    #[test]
    fn with_field_deltas_populates_vec() {
        let deltas = vec![
            FieldDelta {
                field: "hooks[0].url".into(),
                change: "modified".into(),
            },
            FieldDelta {
                field: "timeout".into(),
                change: "removed".into(),
            },
        ];
        let e = make_event().with_field_deltas(deltas);
        assert_eq!(e.tamper.field_deltas.len(), 2);
        assert_eq!(e.tamper.field_deltas[0].field, "hooks[0].url");
        assert_eq!(e.tamper.field_deltas[0].change, "modified");

        let json = serde_json::to_string(&e).unwrap();
        assert!(json.contains("hooks[0].url"));
        assert!(json.contains("modified"));
    }

    #[test]
    fn field_deltas_omitted_when_empty() {
        let e = make_event();
        let json = serde_json::to_string(&e).unwrap();
        assert!(
            !json.contains("field_deltas"),
            "empty field_deltas must be skipped in serialisation"
        );
    }

    #[test]
    fn to_cloud_event_detected_has_correct_type() {
        let e = make_event();
        let ce = e.to_cloud_event("agt_xyz", "0.2.0", "linux", TamperCloudEventKind::Detected);

        assert_eq!(ce.agent_id, "agt_xyz");
        assert_eq!(
            ce.envelope["type"].as_str(),
            Some("ai.openlatch.security.tamper_detected")
        );
        assert_eq!(ce.envelope["specversion"].as_str(), Some("1.0"));
        assert_eq!(ce.envelope["source"].as_str(), Some("claude-code"));
        // No subject from the builder: a hook-registration id is not a session
        // id, and the egress fills the field with one that is.
        assert!(ce.envelope.get("subject").is_none());
        assert_eq!(
            ce.envelope["data"]["tamper"]["entry_id"].as_str(),
            Some("entry-id-123"),
            "the entry id is kept where it belongs, in the payload"
        );
        assert_eq!(ce.envelope["clientversion"].as_str(), Some("0.2.0"));
        assert_eq!(ce.envelope["os"].as_str(), Some("linux"));
        assert_eq!(
            ce.envelope["datacontenttype"].as_str(),
            Some("application/json")
        );
    }

    #[test]
    fn to_cloud_event_healed_has_correct_type() {
        let e = TamperEvent::new_healed(&make_event(), "succeeded", 1, "closed");
        let ce = e.to_cloud_event("agt_xyz", "0.2.0", "macos", TamperCloudEventKind::Healed);
        assert_eq!(
            ce.envelope["type"].as_str(),
            Some("ai.openlatch.security.tamper_healed")
        );
    }

    #[test]
    fn to_cloud_event_id_has_evt_prefix() {
        let e = make_event();
        let ce = e.to_cloud_event("agt_xyz", "0.2.0", "linux", TamperCloudEventKind::Detected);
        let id = ce.envelope["id"].as_str().unwrap();
        assert!(
            id.starts_with("evt_"),
            "CloudEvent id must have evt_ prefix: {id}"
        );
        assert!(id.contains(&e.tamper.event_id));
    }

    #[test]
    fn to_cloud_event_payload_contains_ocsf_and_tamper() {
        let e = make_event();
        let ce = e.to_cloud_event("agt_xyz", "0.2.0", "linux", TamperCloudEventKind::Detected);
        let data = &ce.envelope["data"];
        assert_eq!(data["ocsf"]["class_uid"].as_u64(), Some(2004));
        assert_eq!(
            data["tamper"]["detection_method"].as_str(),
            Some("hmac_mismatch")
        );
        assert_eq!(data["tamper"]["entry_id"].as_str(), Some("entry-id-123"));
    }

    #[test]
    fn to_cloud_event_never_stamps_agentid_in_envelope() {
        // The worker stamps `agentid` onto the envelope immediately before
        // POST. If we stamped it here too, the worker's insert would be a
        // no-op instead of the expected overwrite — and more importantly, the
        // tamper CloudEvent would diverge from how hook CloudEvents are shaped
        // on their way into the channel.
        let e = make_event();
        let ce = e.to_cloud_event("agt_xyz", "0.2.0", "linux", TamperCloudEventKind::Detected);
        assert!(
            ce.envelope.get("agentid").is_none(),
            "to_cloud_event must leave agentid stamping to the worker"
        );
    }
}