kvlar-core 0.2.0

//! Policy definitions — rules that govern agent behavior.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

/// A security policy containing rules for evaluating agent actions.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Policy {
    /// Human-readable name for this policy.
    pub name: String,

    /// Description of what this policy enforces.
    pub description: String,

    /// Version of this policy (for tracking changes).
    pub version: String,

    /// Optional list of base policies to extend.
    /// Base policy rules are appended after this policy's rules,
    /// so this policy's rules take priority (first-match wins).
    /// Values can be built-in names ("postgres", "github", "slack", "shell",
    /// "default", "strict", "permissive", "filesystem") or file paths.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub extends: Vec<String>,

    /// The rules in this policy, evaluated in order.
    pub rules: Vec<Rule>,
}

/// A single rule within a policy.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Rule {
    /// Unique identifier for this rule.
    pub id: String,

    /// Human-readable description.
    pub description: String,

    /// What this rule matches on.
    pub match_on: MatchCriteria,

    /// What to do when this rule matches.
    pub effect: Effect,
}

/// Criteria for matching an action to a rule.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct MatchCriteria {
    /// Action types to match (e.g., "tool_call"). Empty = match all.
    #[serde(default)]
    pub action_types: Vec<String>,

    /// Resources to match (e.g., "bash", "send_email"). Empty = match all.
    #[serde(default)]
    pub resources: Vec<String>,

    /// Agent IDs to match. Empty = match all agents.
    #[serde(default)]
    pub agent_ids: Vec<String>,

    /// Parameter patterns to match (key = param name, value = regex pattern).
    #[serde(default)]
    pub parameters: std::collections::HashMap<String, String>,

    /// Conditional expressions for advanced parameter matching.
    /// Each condition must be satisfied for the rule to match.
    #[serde(default)]
    pub conditions: Vec<Condition>,
}

/// A conditional expression for matching action parameters.
///
/// Conditions allow more expressive matching than regex patterns,
/// supporting equality checks, containment, numeric comparisons, and more.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct Condition {
    /// The parameter key to check (dot-notation for nested: "args.path").
    pub field: String,

    /// The comparison operator.
    pub operator: ConditionOperator,

    /// The value to compare against.
    pub value: serde_json::Value,
}

/// Comparison operators for conditions.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ConditionOperator {
    /// Field equals value exactly.
    Equals,
    /// Field does not equal value.
    NotEquals,
    /// String field contains value as substring.
    Contains,
    /// String field starts with value.
    StartsWith,
    /// String field ends with value.
    EndsWith,
    /// Numeric field is greater than value.
    GreaterThan,
    /// Numeric field is less than value.
    LessThan,
    /// Field exists (value is ignored).
    Exists,
    /// Field does not exist (value is ignored).
    NotExists,
    /// String field matches one of the listed values.
    OneOf,
}

/// The effect of a matched rule.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum Effect {
    /// Allow the action.
    Allow,
    /// Deny the action with a reason.
    Deny { reason: String },
    /// Require human approval.
    RequireApproval { reason: String },
}

impl Policy {
    /// Loads a policy from a YAML string.
    pub fn from_yaml(yaml: &str) -> Result<Self, crate::error::KvlarError> {
        let policy: Policy = serde_yaml::from_str(yaml)?;
        Ok(policy)
    }

    /// Resolves the `extends` directive by loading base policies and merging rules.
    ///
    /// This policy's rules come first (higher priority), followed by each base
    /// policy's rules in the order they appear in `extends`. Since the engine
    /// uses first-match evaluation, this policy's rules override base rules.
    ///
    /// `resolve_fn` is called for each extends entry to load the base policy YAML.
    /// It receives the extends value (a built-in name or file path) and should
    /// return the YAML content, or an error if not found.
    pub fn resolve_extends(
        &mut self,
        resolve_fn: &dyn Fn(&str) -> Result<String, crate::error::KvlarError>,
    ) -> Result<(), crate::error::KvlarError> {
        if self.extends.is_empty() {
            return Ok(());
        }

        let extends = std::mem::take(&mut self.extends);
        for base_name in &extends {
            let base_yaml = resolve_fn(base_name)?;
            let mut base_policy = Policy::from_yaml(&base_yaml)?;
            // Recursively resolve nested extends
            base_policy.resolve_extends(resolve_fn)?;
            // Append base rules after this policy's rules
            self.rules.append(&mut base_policy.rules);
        }
        Ok(())
    }

    /// Serializes this policy to a YAML string.
    pub fn to_yaml(&self) -> Result<String, crate::error::KvlarError> {
        let yaml = serde_yaml::to_string(self)?;
        Ok(yaml)
    }

    /// Loads a policy from a YAML file on disk.
    pub fn from_file(path: &std::path::Path) -> Result<Self, crate::error::KvlarError> {
        let yaml = std::fs::read_to_string(path).map_err(|e| {
            crate::error::KvlarError::PolicyParse(format!(
                "failed to read {}: {}",
                path.display(),
                e
            ))
        })?;
        Self::from_yaml(&yaml)
    }

    /// Loads all policies from a directory (non-recursive, *.yaml and *.yml files).
    pub fn from_dir(dir: &std::path::Path) -> Result<Vec<Self>, crate::error::KvlarError> {
        let entries = std::fs::read_dir(dir).map_err(|e| {
            crate::error::KvlarError::PolicyParse(format!(
                "failed to read directory {}: {}",
                dir.display(),
                e
            ))
        })?;

        let mut policies = Vec::new();
        for entry in entries {
            let entry = entry.map_err(|e| {
                crate::error::KvlarError::PolicyParse(format!("failed to read entry: {}", e))
            })?;
            let path = entry.path();
            if path.is_file()
                && let Some(ext) = path.extension()
                && (ext == "yaml" || ext == "yml")
            {
                policies.push(Self::from_file(&path)?);
            }
        }
        Ok(policies)
    }

    /// Generates a JSON Schema for the Policy type.
    pub fn json_schema() -> schemars::schema::RootSchema {
        schemars::schema_for!(Policy)
    }

    /// Returns the JSON Schema as a pretty-printed JSON string.
    pub fn json_schema_string() -> Result<String, crate::error::KvlarError> {
        let schema = Self::json_schema();
        serde_json::to_string_pretty(&schema).map_err(crate::error::KvlarError::from)
    }
}

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

    #[test]
    fn test_policy_from_yaml() {
        let yaml = r#"
name: test-policy
description: A test policy
version: "1.0"
rules:
  - id: deny-bash
    description: Deny all bash commands
    match_on:
      action_types: ["tool_call"]
      resources: ["bash"]
    effect:
      type: deny
      reason: "Bash commands are not allowed"
"#;
        let policy = Policy::from_yaml(yaml).unwrap();
        assert_eq!(policy.name, "test-policy");
        assert_eq!(policy.rules.len(), 1);
        assert_eq!(policy.rules[0].id, "deny-bash");
    }

    #[test]
    fn test_policy_roundtrip() {
        let policy = Policy {
            name: "roundtrip".into(),
            description: "Test roundtrip".into(),
            version: "1.0".into(),
            extends: vec![],
            rules: vec![],
        };
        let yaml = policy.to_yaml().unwrap();
        let parsed = Policy::from_yaml(&yaml).unwrap();
        assert_eq!(parsed.name, "roundtrip");
    }

    #[test]
    fn test_json_schema_generation() {
        let schema_str = Policy::json_schema_string().unwrap();
        assert!(schema_str.contains("\"Policy\""));
        assert!(schema_str.contains("\"name\""));
        assert!(schema_str.contains("\"rules\""));
        assert!(schema_str.contains("\"effect\""));

        // Verify it parses as valid JSON
        let _: serde_json::Value = serde_json::from_str(&schema_str).unwrap();
    }

    #[test]
    fn test_json_schema_has_all_types() {
        let schema = Policy::json_schema();
        let json = serde_json::to_value(&schema).unwrap();
        let defs = json.get("definitions").unwrap();
        assert!(defs.get("Effect").is_some());
        assert!(defs.get("MatchCriteria").is_some());
        assert!(defs.get("Rule").is_some());
    }

    #[test]
    fn test_policy_from_file() {
        let dir = std::env::temp_dir().join("kvlar-test-policy-file");
        std::fs::create_dir_all(&dir).unwrap();
        let path = dir.join("test.yaml");
        std::fs::write(
            &path,
            r#"
name: file-policy
description: Loaded from file
version: "1.0"
rules: []
"#,
        )
        .unwrap();

        let policy = Policy::from_file(&path).unwrap();
        assert_eq!(policy.name, "file-policy");

        std::fs::remove_dir_all(&dir).unwrap();
    }

    #[test]
    fn test_policy_from_dir() {
        let dir = std::env::temp_dir().join("kvlar-test-policy-dir");
        std::fs::create_dir_all(&dir).unwrap();

        std::fs::write(
            dir.join("a.yaml"),
            "name: a\ndescription: A\nversion: '1'\nrules: []\n",
        )
        .unwrap();
        std::fs::write(
            dir.join("b.yml"),
            "name: b\ndescription: B\nversion: '1'\nrules: []\n",
        )
        .unwrap();
        std::fs::write(dir.join("c.txt"), "not a policy").unwrap();

        let policies = Policy::from_dir(&dir).unwrap();
        assert_eq!(policies.len(), 2);

        std::fs::remove_dir_all(&dir).unwrap();
    }

    #[test]
    fn test_policy_from_file_not_found() {
        let result = Policy::from_file(std::path::Path::new("/nonexistent/policy.yaml"));
        assert!(result.is_err());
    }

    #[test]
    fn test_extends_merges_rules() {
        let base_yaml = r#"
name: base
description: Base policy
version: "1.0"
rules:
  - id: base-deny
    description: Base deny rule
    match_on:
      resources: ["dangerous"]
    effect:
      type: deny
      reason: "Blocked by base"
"#;

        let mut policy = Policy::from_yaml(
            r#"
name: child
description: Child policy
version: "1.0"
extends:
  - base
rules:
  - id: child-allow
    description: Child allow rule
    match_on:
      resources: ["safe"]
    effect:
      type: allow
"#,
        )
        .unwrap();

        policy
            .resolve_extends(&|name| {
                if name == "base" {
                    Ok(base_yaml.to_string())
                } else {
                    Err(crate::error::KvlarError::PolicyParse(format!(
                        "unknown: {}",
                        name
                    )))
                }
            })
            .unwrap();

        // Child rules first, then base rules
        assert_eq!(policy.rules.len(), 2);
        assert_eq!(policy.rules[0].id, "child-allow");
        assert_eq!(policy.rules[1].id, "base-deny");
        // extends should be cleared after resolution
        assert!(policy.extends.is_empty());
    }

    #[test]
    fn test_extends_empty_is_noop() {
        let mut policy = Policy::from_yaml(
            r#"
name: standalone
description: No extends
version: "1.0"
rules:
  - id: my-rule
    description: A rule
    match_on:
      resources: ["*"]
    effect:
      type: allow
"#,
        )
        .unwrap();

        policy
            .resolve_extends(&|_| panic!("should not be called"))
            .unwrap();
        assert_eq!(policy.rules.len(), 1);
    }

    #[test]
    fn test_extends_multiple_bases() {
        let mut policy = Policy::from_yaml(
            r#"
name: multi
description: Extends two bases
version: "1.0"
extends:
  - alpha
  - beta
rules:
  - id: my-rule
    description: My rule
    match_on:
      resources: ["mine"]
    effect:
      type: allow
"#,
        )
        .unwrap();

        policy
            .resolve_extends(&|name| {
                let yaml = format!(
                    r#"
name: {name}
description: Base {name}
version: "1.0"
rules:
  - id: {name}-rule
    description: Rule from {name}
    match_on:
      resources: ["{name}"]
    effect:
      type: deny
      reason: "From {name}"
"#
                );
                Ok(yaml)
            })
            .unwrap();

        assert_eq!(policy.rules.len(), 3);
        assert_eq!(policy.rules[0].id, "my-rule");
        assert_eq!(policy.rules[1].id, "alpha-rule");
        assert_eq!(policy.rules[2].id, "beta-rule");
    }

    #[test]
    fn test_extends_serialization_skips_empty() {
        let policy = Policy {
            name: "test".into(),
            description: "Test".into(),
            version: "1.0".into(),
            extends: vec![],
            rules: vec![],
        };
        let yaml = policy.to_yaml().unwrap();
        assert!(!yaml.contains("extends"));
    }
}