zeph_config/

sanitizer.rs

// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
// SPDX-License-Identifier: MIT OR Apache-2.0

use crate::providers::ProviderName;
use serde::{Deserialize, Serialize};

use crate::defaults::default_true;

// ---------------------------------------------------------------------------
// ContentIsolationConfig
// ---------------------------------------------------------------------------

fn default_max_content_size() -> usize {
    65_536
}

/// Configuration for the embedding anomaly guard, nested under
/// `[security.content_isolation.embedding_guard]`.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct EmbeddingGuardConfig {
    /// Enable embedding-based anomaly detection (default: false — opt-in).
    #[serde(default)]
    pub enabled: bool,
    /// Cosine distance threshold above which outputs are flagged as anomalous.
    #[serde(
        default = "default_embedding_threshold",
        deserialize_with = "crate::de_helpers::de_unit_open"
    )]
    pub threshold: f64,
    /// Minimum clean samples before centroid-based detection activates.
    /// Before this count, regex fallback is used instead.
    #[serde(
        default = "default_embedding_min_samples",
        deserialize_with = "validate_min_samples"
    )]
    pub min_samples: usize,
    /// EMA alpha floor for centroid updates after stabilization (n >= `min_samples`).
    ///
    /// Once the centroid has accumulated `min_samples` clean outputs, each new sample
    /// can shift it by at most this fraction. Lower values make the centroid more
    /// resistant to slow drift attacks but slower to adapt to legitimate distribution
    /// changes. Default: 0.01 (1% per sample).
    #[serde(default = "default_ema_floor")]
    pub ema_floor: f32,
}

fn validate_min_samples<'de, D>(deserializer: D) -> Result<usize, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let value = <usize as serde::Deserialize>::deserialize(deserializer)?;
    if value == 0 {
        return Err(serde::de::Error::custom(
            "embedding_guard.min_samples must be >= 1",
        ));
    }
    Ok(value)
}

fn default_embedding_threshold() -> f64 {
    0.35
}

fn default_embedding_min_samples() -> usize {
    10
}

fn default_ema_floor() -> f32 {
    0.01
}

impl Default for EmbeddingGuardConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            threshold: default_embedding_threshold(),
            min_samples: default_embedding_min_samples(),
            ema_floor: default_ema_floor(),
        }
    }
}

/// Configuration for the content isolation pipeline, nested under
/// `[security.content_isolation]` in the agent config file.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[allow(clippy::struct_excessive_bools)] // config struct — boolean flags are idiomatic for TOML-deserialized configuration
pub struct ContentIsolationConfig {
    /// When `false`, the sanitizer is a no-op: content passes through unchanged.
    #[serde(default = "default_true")]
    pub enabled: bool,

    /// Maximum byte length of untrusted content before truncation.
    #[serde(default = "default_max_content_size")]
    pub max_content_size: usize,

    /// When `true`, injection patterns detected in content are recorded as
    /// flags and a warning is prepended to the spotlighting wrapper.
    #[serde(default = "default_true")]
    pub flag_injection_patterns: bool,

    /// When `true`, untrusted content is wrapped in spotlighting XML delimiters
    /// that instruct the LLM to treat the enclosed text as data, not instructions.
    #[serde(default = "default_true")]
    pub spotlight_untrusted: bool,

    /// Quarantine summarizer configuration.
    #[serde(default)]
    pub quarantine: QuarantineConfig,

    /// Embedding anomaly guard configuration.
    #[serde(default)]
    pub embedding_guard: EmbeddingGuardConfig,

    /// When `true`, MCP tool results flowing through ACP-serving sessions receive
    /// unconditional quarantine summarization and cross-boundary audit log entries.
    /// This prevents confused-deputy attacks where untrusted MCP output influences
    /// responses served to ACP clients (e.g. IDE integrations).
    #[serde(default = "default_true")]
    pub mcp_to_acp_boundary: bool,

    /// NLI entailment check stage configuration.
    #[serde(default)]
    pub nli: NliConfig,

    /// PAAC secret placeholder masking configuration.
    #[serde(default)]
    pub secret_masking: SecretMaskingConfig,
}

impl Default for ContentIsolationConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            max_content_size: default_max_content_size(),
            flag_injection_patterns: true,
            spotlight_untrusted: true,
            quarantine: QuarantineConfig::default(),
            embedding_guard: EmbeddingGuardConfig::default(),
            mcp_to_acp_boundary: true,
            nli: NliConfig::default(),
            secret_masking: SecretMaskingConfig::default(),
        }
    }
}

/// Configuration for the SONAR NLI entailment check stage, nested under
/// `[security.content_isolation.nli]` in the agent config file.
///
/// When `enabled = false` (the default), the NLI stage is skipped entirely.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct NliConfig {
    /// Enable NLI entailment-based injection detection (default: false — opt-in).
    #[serde(default)]
    pub enabled: bool,

    /// Provider name from `[[llm.providers]]` to use for NLI inference.
    ///
    /// An empty [`ProviderName`] falls back to the default provider. Prefer a fast, cheap model.
    #[serde(default)]
    pub provider: ProviderName,

    /// Entailment score threshold above which content is flagged (default: 0.75).
    #[serde(default = "default_nli_threshold")]
    pub threshold: f32,

    /// Maximum milliseconds to wait for the NLI provider response (default: 5000).
    #[serde(default = "default_nli_timeout_ms")]
    pub timeout_ms: u64,

    /// Maximum characters of content sent to the NLI provider (default: 2048).
    #[serde(default = "default_nli_max_content_len")]
    pub max_content_len: usize,
}

fn default_nli_threshold() -> f32 {
    0.75
}

fn default_nli_timeout_ms() -> u64 {
    5000
}

fn default_nli_max_content_len() -> usize {
    2048
}

impl Default for NliConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            provider: ProviderName::default(),
            threshold: default_nli_threshold(),
            timeout_ms: default_nli_timeout_ms(),
            max_content_len: default_nli_max_content_len(),
        }
    }
}

/// Configuration for PAAC secret placeholder masking, nested under
/// `[security.content_isolation.secret_masking]` in the agent config file.
///
/// Enabled by default: substitution is a cheap synchronous placeholder swap with no LLM
/// call, and keeps vault-resolved secrets out of LLM payloads, `SQLite` history, and debug
/// dumps (#6263).
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct SecretMaskingConfig {
    /// Enable secret placeholder masking (default: true).
    #[serde(default = "default_true")]
    pub enabled: bool,

    /// Minimum secret byte length to be eligible for masking (default: 8).
    ///
    /// Secrets shorter than this value are not substituted to avoid false matches
    /// on common short strings.
    #[serde(default = "default_min_secret_len")]
    pub min_secret_len: usize,
}

fn default_min_secret_len() -> usize {
    8
}

impl Default for SecretMaskingConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            min_secret_len: default_min_secret_len(),
        }
    }
}

/// Configuration for the quarantine summarizer, nested under
/// `[security.content_isolation.quarantine]` in the agent config file.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct QuarantineConfig {
    /// When `false`, quarantine summarization is disabled entirely.
    #[serde(default)]
    pub enabled: bool,

    /// Source kinds to route through the quarantine LLM.
    #[serde(default = "default_quarantine_sources")]
    pub sources: Vec<String>,

    /// Provider name passed to `create_named_provider`.
    #[serde(default = "default_quarantine_model")]
    pub model: String,

    /// Maximum time in milliseconds to wait for the quarantine LLM to respond.
    ///
    /// When the LLM does not respond within this window, `extract_facts` returns a timeout
    /// error so the agent can recover rather than stalling indefinitely.
    /// Defaults to 30 000 ms (30 s).
    #[serde(default = "default_quarantine_timeout_ms")]
    pub timeout_ms: u64,

    /// What to do when `extract_facts` fails (timeout, LLM error, or empty response).
    ///
    /// Mirrors [`GuardrailFailStrategy`]: `Closed` (the default) substitutes a fixed
    /// "content could not be safely processed" placeholder instead of falling through to
    /// the merely sanitized/spotlighted content, since quarantine sources are, by
    /// definition, the highest-risk content the agent handles. `Open` preserves the
    /// pre-#6495 behavior of falling back to the sanitized content for
    /// availability-sensitive deployments.
    #[serde(default = "default_fail_strategy")]
    pub fail_strategy: GuardrailFailStrategy,
}

fn default_quarantine_sources() -> Vec<String> {
    vec!["web_scrape".to_owned(), "a2a_message".to_owned()]
}

fn default_quarantine_model() -> String {
    "claude".to_owned()
}

fn default_quarantine_timeout_ms() -> u64 {
    30_000
}

impl Default for QuarantineConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            sources: default_quarantine_sources(),
            model: default_quarantine_model(),
            timeout_ms: default_quarantine_timeout_ms(),
            fail_strategy: default_fail_strategy(),
        }
    }
}

// ---------------------------------------------------------------------------
// ExfiltrationGuardConfig
// ---------------------------------------------------------------------------

/// Configuration for exfiltration guards, nested under
/// `[security.exfiltration_guard]` in the agent config file.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct ExfiltrationGuardConfig {
    /// Strip external markdown images from LLM output to prevent pixel-tracking exfiltration.
    #[serde(default = "default_true")]
    pub block_markdown_images: bool,

    /// Cross-reference tool call arguments against URLs seen in flagged untrusted content.
    #[serde(default = "default_true")]
    pub validate_tool_urls: bool,

    /// Skip Qdrant embedding for messages that contained injection-flagged content.
    #[serde(default = "default_true")]
    pub guard_memory_writes: bool,
}

impl Default for ExfiltrationGuardConfig {
    fn default() -> Self {
        Self {
            block_markdown_images: true,
            validate_tool_urls: true,
            guard_memory_writes: true,
        }
    }
}

// ---------------------------------------------------------------------------
// MemoryWriteValidationConfig
// ---------------------------------------------------------------------------

fn default_max_content_bytes() -> usize {
    4096
}

fn default_max_entity_name_bytes() -> usize {
    256
}

fn default_min_entity_name_bytes() -> usize {
    3
}

fn default_max_fact_bytes() -> usize {
    1024
}

fn default_max_entities() -> usize {
    50
}

fn default_max_edges() -> usize {
    100
}

/// Configuration for memory write validation, nested under `[security.memory_validation]`.
///
/// Enabled by default with conservative limits.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct MemoryWriteValidationConfig {
    /// Master switch. When `false`, validation is a no-op.
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Maximum byte length of content passed to `memory_save`.
    #[serde(default = "default_max_content_bytes")]
    pub max_content_bytes: usize,
    /// Minimum byte length of an entity name in graph extraction.
    #[serde(default = "default_min_entity_name_bytes")]
    pub min_entity_name_bytes: usize,
    /// Maximum byte length of a single entity name in graph extraction.
    #[serde(default = "default_max_entity_name_bytes")]
    pub max_entity_name_bytes: usize,
    /// Maximum byte length of an edge fact string in graph extraction.
    #[serde(default = "default_max_fact_bytes")]
    pub max_fact_bytes: usize,
    /// Maximum number of entities allowed per graph extraction result.
    #[serde(default = "default_max_entities")]
    pub max_entities_per_extraction: usize,
    /// Maximum number of edges allowed per graph extraction result.
    #[serde(default = "default_max_edges")]
    pub max_edges_per_extraction: usize,
    /// Forbidden substring patterns.
    #[serde(default)]
    pub forbidden_content_patterns: Vec<String>,
}

impl Default for MemoryWriteValidationConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            max_content_bytes: default_max_content_bytes(),
            min_entity_name_bytes: default_min_entity_name_bytes(),
            max_entity_name_bytes: default_max_entity_name_bytes(),
            max_fact_bytes: default_max_fact_bytes(),
            max_entities_per_extraction: default_max_entities(),
            max_edges_per_extraction: default_max_edges(),
            forbidden_content_patterns: Vec::new(),
        }
    }
}

// ---------------------------------------------------------------------------
// PiiFilterConfig
// ---------------------------------------------------------------------------

/// A single user-defined PII pattern.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct CustomPiiPattern {
    /// Human-readable name used in the replacement label.
    pub name: String,
    /// Regular expression pattern.
    pub pattern: String,
    /// Replacement text. Defaults to `[PII:custom]`.
    #[serde(default = "default_custom_replacement")]
    pub replacement: String,
}

fn default_custom_replacement() -> String {
    "[PII:custom]".to_owned()
}

/// Configuration for the PII filter, nested under `[security.pii_filter]` in the config file.
///
/// Enabled by default: filtering is a cheap synchronous regex substitution with no LLM
/// call, and keeps PII out of LLM payloads, `SQLite` history, and debug dumps (#6263).
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[allow(clippy::struct_excessive_bools)] // config struct — boolean flags are idiomatic for TOML-deserialized configuration
pub struct PiiFilterConfig {
    /// Master switch. When `false`, the filter is a no-op. Default: `true`.
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Scrub email addresses.
    #[serde(default = "default_true")]
    pub filter_email: bool,
    /// Scrub US phone numbers.
    #[serde(default = "default_true")]
    pub filter_phone: bool,
    /// Scrub US Social Security Numbers.
    #[serde(default = "default_true")]
    pub filter_ssn: bool,
    /// Scrub credit card numbers (16-digit patterns).
    #[serde(default = "default_true")]
    pub filter_credit_card: bool,
    /// Scrub personal names via a capitalized-word-sequence heuristic: 2+ consecutive
    /// ASCII Titlecase tokens excluding a stoplist of common capitalized non-name words.
    /// Compensating control for weak NER-model recall on free-text names (#5530).
    ///
    /// Defaults to `false` (opt-in), unlike the other `filter_*` flags: this is a high-recall,
    /// lower-precision heuristic that also flags common two-word technical/product terms (e.g.
    /// `"Docker Compose"`, `"Pull Request"`, `"New York"`) as candidate names, so it is not
    /// force-enabled for existing `pii_filter.enabled = true` deployments.
    #[serde(default)]
    pub filter_names: bool,
    /// Custom regex patterns to add on top of the built-ins.
    #[serde(default)]
    pub custom_patterns: Vec<CustomPiiPattern>,
}

impl Default for PiiFilterConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            filter_email: true,
            filter_phone: true,
            filter_ssn: true,
            filter_credit_card: true,
            filter_names: false,
            custom_patterns: Vec::new(),
        }
    }
}

// ---------------------------------------------------------------------------
// GuardrailConfig
// ---------------------------------------------------------------------------

/// What happens when the guardrail flags input.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum GuardrailAction {
    /// Block the input and return an error message to the user.
    #[default]
    Block,
    /// Allow the input but emit a warning message.
    Warn,
}

/// Behavior on timeout or LLM error.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum GuardrailFailStrategy {
    /// Block input on timeout/error (safe default for security-sensitive deployments).
    #[default]
    Closed,
    /// Allow input on timeout/error (for availability-sensitive deployments).
    Open,
}

/// Configuration for the LLM-based guardrail, nested under `[security.guardrail]`.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct GuardrailConfig {
    /// Enable the guardrail (default: false).
    #[serde(default)]
    pub enabled: bool,
    /// Provider to use for guardrail classification (e.g. `"ollama"`, `"claude"`).
    #[serde(default)]
    pub provider: Option<String>,
    /// Model to use (e.g. `"llama-guard-3:1b"`).
    #[serde(default)]
    pub model: Option<String>,
    /// Timeout for each guardrail LLM call in milliseconds (default: 500).
    #[serde(default = "default_guardrail_timeout_ms")]
    pub timeout_ms: u64,
    /// Action to take when a message is flagged (default: block).
    #[serde(default)]
    pub action: GuardrailAction,
    /// What to do on timeout or LLM error (default: closed — block).
    #[serde(default = "default_fail_strategy")]
    pub fail_strategy: GuardrailFailStrategy,
    /// When `true`, also scan tool outputs before they enter message history (default: false).
    #[serde(default)]
    pub scan_tool_output: bool,
    /// Maximum number of characters to send to the guard model (default: 4096).
    #[serde(default = "default_max_input_chars")]
    pub max_input_chars: usize,
}
fn default_guardrail_timeout_ms() -> u64 {
    500
}
fn default_max_input_chars() -> usize {
    4096
}
fn default_fail_strategy() -> GuardrailFailStrategy {
    GuardrailFailStrategy::Closed
}
impl Default for GuardrailConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            provider: None,
            model: None,
            timeout_ms: default_guardrail_timeout_ms(),
            action: GuardrailAction::default(),
            fail_strategy: default_fail_strategy(),
            scan_tool_output: false,
            max_input_chars: default_max_input_chars(),
        }
    }
}

// ---------------------------------------------------------------------------
// ResponseVerificationConfig
// ---------------------------------------------------------------------------

/// Configuration for post-LLM response verification, nested under
/// `[security.response_verification]` in the agent config file.
///
/// Scans LLM responses for injected instruction patterns before tool dispatch.
/// This is defense-in-depth layer 3 (after input sanitization and pre-execution verification).
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct ResponseVerificationConfig {
    /// Enable post-LLM response verification (default: true).
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Block tool dispatch when injection patterns are detected (default: false).
    ///
    /// When `false`, flagged responses are logged and shown in the TUI SEC panel
    /// but still delivered. When `true`, the response is suppressed and the user
    /// is notified.
    #[serde(default)]
    pub block_on_detection: bool,
    /// Optional LLM provider for async deep verification of flagged responses.
    ///
    /// When set: suspicious responses are delivered immediately with a `[FLAGGED]`
    /// annotation, and background LLM verification runs asynchronously. The verifier
    /// receives a sanitized summary (via `QuarantinedSummarizer`) to prevent recursive
    /// injection. Empty string = disabled (regex-only verification).
    #[serde(default)]
    pub verifier_provider: ProviderName,
}

impl Default for ResponseVerificationConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            block_on_detection: false,
            verifier_provider: ProviderName::default(),
        }
    }
}

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

    #[test]
    fn content_isolation_default_mcp_to_acp_boundary_true() {
        let cfg = ContentIsolationConfig::default();
        assert!(cfg.mcp_to_acp_boundary);
    }

    #[test]
    fn content_isolation_deserialize_mcp_to_acp_boundary_false() {
        let toml = r"
            mcp_to_acp_boundary = false
        ";
        let cfg: ContentIsolationConfig = toml::from_str(toml).unwrap();
        assert!(!cfg.mcp_to_acp_boundary);
    }

    #[test]
    fn content_isolation_deserialize_absent_defaults_true() {
        let cfg: ContentIsolationConfig = toml::from_str("").unwrap();
        assert!(cfg.mcp_to_acp_boundary);
    }

    // ── PiiFilterConfig / SecretMaskingConfig safe-default posture (#6263) ──────────────

    #[test]
    fn pii_filter_default_is_enabled() {
        assert!(PiiFilterConfig::default().enabled);
    }

    #[test]
    fn pii_filter_deserialize_absent_defaults_enabled_true() {
        // The whole [security.pii_filter] table is absent — falls back to struct Default.
        let cfg: PiiFilterConfig = toml::from_str("").unwrap();
        assert!(cfg.enabled);
    }

    #[test]
    fn pii_filter_deserialize_section_present_without_enabled_key_defaults_true() {
        // The section exists (e.g. only `filter_email` was set) but omits `enabled` — must
        // resolve via the field-level `default_true`, not `bool::default()`.
        let cfg: PiiFilterConfig = toml::from_str("filter_email = false").unwrap();
        assert!(cfg.enabled);
        assert!(!cfg.filter_email);
    }

    #[test]
    fn pii_filter_deserialize_explicit_false_is_respected() {
        let cfg: PiiFilterConfig = toml::from_str("enabled = false").unwrap();
        assert!(!cfg.enabled);
    }

    #[test]
    fn secret_masking_default_is_enabled() {
        assert!(SecretMaskingConfig::default().enabled);
    }

    #[test]
    fn secret_masking_deserialize_absent_defaults_enabled_true() {
        let cfg: SecretMaskingConfig = toml::from_str("").unwrap();
        assert!(cfg.enabled);
    }

    #[test]
    fn secret_masking_deserialize_section_present_without_enabled_key_defaults_true() {
        let cfg: SecretMaskingConfig = toml::from_str("min_secret_len = 12").unwrap();
        assert!(cfg.enabled);
        assert_eq!(cfg.min_secret_len, 12);
    }

    #[test]
    fn secret_masking_deserialize_explicit_false_is_respected() {
        let cfg: SecretMaskingConfig = toml::from_str("enabled = false").unwrap();
        assert!(!cfg.enabled);
    }

    fn de_guard(toml: &str) -> Result<EmbeddingGuardConfig, toml::de::Error> {
        toml::from_str(toml)
    }

    #[test]
    fn threshold_valid() {
        let cfg = de_guard("threshold = 0.35\nmin_samples = 5").unwrap();
        assert!((cfg.threshold - 0.35).abs() < f64::EPSILON);
    }

    #[test]
    fn threshold_one_valid() {
        let cfg = de_guard("threshold = 1.0\nmin_samples = 1").unwrap();
        assert!((cfg.threshold - 1.0).abs() < f64::EPSILON);
    }

    #[test]
    fn threshold_zero_rejected() {
        assert!(de_guard("threshold = 0.0\nmin_samples = 1").is_err());
    }

    #[test]
    fn threshold_above_one_rejected() {
        assert!(de_guard("threshold = 1.5\nmin_samples = 1").is_err());
    }

    #[test]
    fn threshold_negative_rejected() {
        assert!(de_guard("threshold = -0.1\nmin_samples = 1").is_err());
    }

    #[test]
    fn min_samples_zero_rejected() {
        assert!(de_guard("threshold = 0.35\nmin_samples = 0").is_err());
    }

    #[test]
    fn min_samples_one_valid() {
        let cfg = de_guard("threshold = 0.35\nmin_samples = 1").unwrap();
        assert_eq!(cfg.min_samples, 1);
    }
}

// ---------------------------------------------------------------------------
// CausalIpiConfig
// ---------------------------------------------------------------------------

fn default_causal_threshold() -> f32 {
    0.7
}

fn default_probe_max_tokens() -> u32 {
    100
}

fn default_probe_timeout_ms() -> u64 {
    3000
}

/// Temporal causal IPI analysis at tool-return boundaries.
///
/// When enabled, the agent generates behavioral probes before and after tool batch dispatch
/// and compares them to detect behavioral deviation caused by injected instructions in
/// tool outputs. Probes are per-batch (2 LLM calls total), not per individual tool.
///
/// Config section: `[security.causal_ipi]`
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct CausalIpiConfig {
    /// Master switch. Default: false (opt-in).
    #[serde(default)]
    pub enabled: bool,

    /// Causal attribution score threshold for flagging. Range: (0.0, 1.0]. Default 0.7.
    ///
    /// Scores above this value trigger a WARN log, metric increment, and `SecurityEvent`.
    /// Content is never blocked — this is an observation layer only.
    #[serde(
        default = "default_causal_threshold",
        deserialize_with = "crate::de_helpers::de_unit_open"
    )]
    pub threshold: f32,

    /// LLM provider name from `[[llm.providers]]` for probe calls.
    ///
    /// Should reference a fast/cheap provider — probes run on every tool batch return.
    /// When `None`, falls back to the agent's default provider.
    #[serde(default)]
    pub provider: Option<String>,

    /// Maximum tokens for each probe response. Limits cost per probe call. Default: 100.
    ///
    /// Two probes per batch = max `2 * probe_max_tokens` output tokens per tool batch.
    #[serde(default = "default_probe_max_tokens")]
    pub probe_max_tokens: u32,

    /// Timeout in milliseconds for each individual probe LLM call. Default: 3000.
    ///
    /// On timeout: WARN log, skip causal analysis for the batch (never block).
    #[serde(default = "default_probe_timeout_ms")]
    pub probe_timeout_ms: u64,

    /// Shadow memory configuration for cross-turn trajectory analysis.
    #[serde(default)]
    pub shadow_memory: ShadowMemoryConfig,
}

impl Default for CausalIpiConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            threshold: default_causal_threshold(),
            provider: None,
            probe_max_tokens: default_probe_max_tokens(),
            probe_timeout_ms: default_probe_timeout_ms(),
            shadow_memory: ShadowMemoryConfig::default(),
        }
    }
}

// ---------------------------------------------------------------------------
// ShadowMemoryConfig
// ---------------------------------------------------------------------------

fn default_shadow_window() -> usize {
    8
}

fn default_shadow_max_events() -> usize {
    64
}

fn default_shadow_drift_threshold() -> f32 {
    0.6
}

fn validate_shadow_window<'de, D>(deserializer: D) -> Result<usize, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let value = <usize as serde::Deserialize>::deserialize(deserializer)?;
    if value == 0 {
        return Err(serde::de::Error::custom(
            "shadow_memory.window_size must be >= 1",
        ));
    }
    Ok(value)
}

fn validate_shadow_max_events<'de, D>(deserializer: D) -> Result<usize, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let value = <usize as serde::Deserialize>::deserialize(deserializer)?;
    if value == 0 {
        return Err(serde::de::Error::custom(
            "shadow_memory.max_events must be >= 1",
        ));
    }
    Ok(value)
}

/// Per-session append-only event store for cross-turn trajectory analysis.
///
/// Detects multi-turn attacks that distribute payload across several turns —
/// invisible to the stateless [`CausalIpiConfig`] single-batch analysis.
///
/// Config section: `[security.causal_ipi.shadow_memory]`
///
/// # Examples
///
/// ```toml
/// [security.causal_ipi.shadow_memory]
/// enabled = true
/// window_size = 8
/// max_events = 64
/// drift_threshold = 0.6
/// ```
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
pub struct ShadowMemoryConfig {
    /// Enable shadow memory trajectory tracking. Default: false.
    #[serde(default)]
    pub enabled: bool,

    /// Sliding window size for drift computation. Must be >= 1. Default: 8.
    #[serde(
        default = "default_shadow_window",
        deserialize_with = "validate_shadow_window"
    )]
    pub window_size: usize,

    /// Maximum events retained before oldest are evicted. Must be >= 1. Default: 64.
    #[serde(
        default = "default_shadow_max_events",
        deserialize_with = "validate_shadow_max_events"
    )]
    pub max_events: usize,

    /// Goal drift score threshold for flagging. Range: (0.0, 1.0]. Default: 0.6.
    #[serde(
        default = "default_shadow_drift_threshold",
        deserialize_with = "crate::de_helpers::de_unit_open"
    )]
    pub drift_threshold: f32,
}

impl Default for ShadowMemoryConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            window_size: default_shadow_window(),
            max_events: default_shadow_max_events(),
            drift_threshold: default_shadow_drift_threshold(),
        }
    }
}

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

    #[test]
    fn causal_ipi_defaults() {
        let cfg = CausalIpiConfig::default();
        assert!(!cfg.enabled);
        assert!((cfg.threshold - 0.7).abs() < 1e-6);
        assert!(cfg.provider.is_none());
        assert_eq!(cfg.probe_max_tokens, 100);
        assert_eq!(cfg.probe_timeout_ms, 3000);
    }

    #[test]
    fn causal_ipi_deserialize_enabled() {
        let toml = r#"
            enabled = true
            threshold = 0.8
            provider = "fast"
            probe_max_tokens = 150
            probe_timeout_ms = 5000
        "#;
        let cfg: CausalIpiConfig = toml::from_str(toml).unwrap();
        assert!(cfg.enabled);
        assert!((cfg.threshold - 0.8).abs() < 1e-6);
        assert_eq!(cfg.provider.as_deref(), Some("fast"));
        assert_eq!(cfg.probe_max_tokens, 150);
        assert_eq!(cfg.probe_timeout_ms, 5000);
    }

    #[test]
    fn causal_ipi_threshold_zero_rejected() {
        let result: Result<CausalIpiConfig, _> = toml::from_str("threshold = 0.0");
        assert!(result.is_err());
    }

    #[test]
    fn causal_ipi_threshold_above_one_rejected() {
        let result: Result<CausalIpiConfig, _> = toml::from_str("threshold = 1.1");
        assert!(result.is_err());
    }

    #[test]
    fn causal_ipi_threshold_exactly_one_accepted() {
        let cfg: CausalIpiConfig = toml::from_str("threshold = 1.0").unwrap();
        assert!((cfg.threshold - 1.0).abs() < 1e-6);
    }
}

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

    #[test]
    fn shadow_memory_defaults() {
        let cfg = ShadowMemoryConfig::default();
        assert!(!cfg.enabled);
        assert_eq!(cfg.window_size, 8);
        assert_eq!(cfg.max_events, 64);
        assert!((cfg.drift_threshold - 0.6).abs() < 1e-6);
    }

    #[test]
    fn shadow_memory_window_zero_rejected() {
        let result: Result<ShadowMemoryConfig, _> = toml::from_str("window_size = 0");
        assert!(result.is_err());
    }

    #[test]
    fn shadow_memory_max_events_zero_rejected() {
        let result: Result<ShadowMemoryConfig, _> = toml::from_str("max_events = 0");
        assert!(result.is_err());
    }

    #[test]
    fn shadow_memory_drift_threshold_zero_rejected() {
        let result: Result<ShadowMemoryConfig, _> = toml::from_str("drift_threshold = 0.0");
        assert!(result.is_err());
    }

    #[test]
    fn shadow_memory_drift_threshold_above_one_rejected() {
        let result: Result<ShadowMemoryConfig, _> = toml::from_str("drift_threshold = 1.1");
        assert!(result.is_err());
    }

    #[test]
    fn shadow_memory_drift_threshold_exactly_one_accepted() {
        let cfg: ShadowMemoryConfig = toml::from_str("drift_threshold = 1.0").unwrap();
        assert!((cfg.drift_threshold - 1.0).abs() < 1e-6);
    }

    #[test]
    fn shadow_memory_full_deserialization() {
        let toml = r"
            enabled = true
            window_size = 4
            max_events = 32
            drift_threshold = 0.8
        ";
        let cfg: ShadowMemoryConfig = toml::from_str(toml).unwrap();
        assert!(cfg.enabled);
        assert_eq!(cfg.window_size, 4);
        assert_eq!(cfg.max_events, 32);
        assert!((cfg.drift_threshold - 0.8).abs() < 1e-6);
    }
}