cortexai_agents/

scope_guard.rs

//! Scope-based security guards for tool execution.
//!
//! Tools declare required scopes (e.g. "fs:read", "network:external").
//! Agents have a set of granted scopes. The scope guard checks that all
//! required scopes are satisfied before allowing tool execution.
//!
//! # Scope Syntax
//!
//! Scopes follow a `namespace:action` pattern:
//! - `"fs:read"` — read from the filesystem
//! - `"fs:write"` — write to the filesystem
//! - `"fs:*"` — wildcard: grants all `fs:` sub-scopes
//! - `"network:external"` — call external network endpoints
//! - `"finance:write"` — modify financial records
//!
//! # Default Behaviour
//!
//! A tool with no `required_scopes` is always allowed regardless of the policy.
//! If no `ScopeGuard` is configured on the executor, all tools are allowed
//! (backward compatible).

use std::collections::HashSet;

use cortexai_core::ToolSchema;
use tracing::debug;

use crate::approvals::{
    ApprovalDecision, ApprovalHandler, ApprovalReason, ApprovalRequest,
};

// ---------------------------------------------------------------------------
// Scope type
// ---------------------------------------------------------------------------

/// A scope string such as `"fs:read"` or `"network:*"`.
pub type Scope = String;

// ---------------------------------------------------------------------------
// ScopePolicy
// ---------------------------------------------------------------------------

/// Per-agent scope policy: the set of scopes that an agent has been granted.
///
/// An empty `granted` set combined with `default_deny = true` means the agent
/// cannot execute any tool that requires a scope.  With `default_deny = false`
/// (the default) all tools are allowed unless they declare required scopes.
#[derive(Debug, Clone)]
pub struct ScopePolicy {
    /// Scopes granted to the agent.
    granted: HashSet<Scope>,
    /// When `true`, a tool with no required scopes is still blocked unless
    /// the policy explicitly grants a wildcard `"*"`.  Defaults to `false`
    /// (no restriction on scope-free tools).
    pub default_deny: bool,
}

impl ScopePolicy {
    /// Create a policy with an empty granted set and `default_deny = false`.
    pub fn new() -> Self {
        Self {
            granted: HashSet::new(),
            default_deny: false,
        }
    }

    /// Add a granted scope.
    pub fn grant(mut self, scope: impl Into<Scope>) -> Self {
        self.granted.insert(scope.into());
        self
    }

    /// Replace the granted set.
    pub fn with_scopes(mut self, scopes: impl IntoIterator<Item = impl Into<Scope>>) -> Self {
        self.granted = scopes.into_iter().map(Into::into).collect();
        self
    }

    /// Set `default_deny`.
    pub fn with_default_deny(mut self, value: bool) -> Self {
        self.default_deny = value;
        self
    }

    /// Check whether a single required scope is satisfied by this policy.
    ///
    /// Matching rules (first match wins):
    /// 1. Exact match: `"fs:read"` satisfies `"fs:read"`.
    /// 2. Namespace wildcard: `"fs:*"` satisfies `"fs:read"`, `"fs:write"`, etc.
    /// 3. Global wildcard: `"*"` satisfies any scope.
    pub fn is_scope_granted(&self, required: &str) -> bool {
        if self.granted.contains(required) {
            return true;
        }
        // Global wildcard
        if self.granted.contains("*") {
            return true;
        }
        // Namespace wildcard: "ns:*" satisfies "ns:anything"
        if let Some(ns) = required.split(':').next() {
            let wildcard = format!("{}:*", ns);
            if self.granted.contains(&wildcard) {
                return true;
            }
        }
        false
    }

    /// Return the list of required scopes that are NOT granted.
    pub fn missing_scopes<'a>(&self, required: &'a [String]) -> Vec<&'a str> {
        required
            .iter()
            .filter(|s| !self.is_scope_granted(s))
            .map(String::as_str)
            .collect()
    }
}

impl Default for ScopePolicy {
    fn default() -> Self {
        Self::new()
    }
}

// ---------------------------------------------------------------------------
// ScopeCheckResult
// ---------------------------------------------------------------------------

/// Outcome of a scope check.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ScopeCheckResult {
    /// All required scopes are satisfied — proceed.
    Allowed,
    /// One or more required scopes are missing.
    Denied { missing: Vec<String> },
}

impl ScopeCheckResult {
    pub fn is_allowed(&self) -> bool {
        matches!(self, Self::Allowed)
    }
}

// ---------------------------------------------------------------------------
// ScopeGuard
// ---------------------------------------------------------------------------

/// Checks tool scope requirements against an agent's `ScopePolicy`.
///
/// Integrate with the executor by calling [`ScopeGuard::check`] before
/// executing a tool.  If the check fails and an `ApprovalHandler` is provided,
/// the guard escalates to the handler so a human operator can override.
#[derive(Debug, Clone)]
pub struct ScopeGuard {
    policy: ScopePolicy,
}

impl ScopeGuard {
    pub fn new(policy: ScopePolicy) -> Self {
        Self { policy }
    }

    /// Check whether `tool_schema` may be executed under the current policy.
    ///
    /// - If the schema has no `required_scopes`, the result is always `Allowed`
    ///   (unless `default_deny` is set — that case is handled separately).
    /// - If all required scopes are granted, `Allowed` is returned.
    /// - Otherwise, `Denied` is returned with the list of missing scopes.
    pub fn check(&self, tool_schema: &ToolSchema) -> ScopeCheckResult {
        if tool_schema.required_scopes.is_empty() {
            return ScopeCheckResult::Allowed;
        }

        let missing = self.policy.missing_scopes(&tool_schema.required_scopes);
        if missing.is_empty() {
            ScopeCheckResult::Allowed
        } else {
            debug!(
                "Scope check failed for tool '{}': missing {:?}",
                tool_schema.name, missing
            );
            ScopeCheckResult::Denied {
                missing: missing.into_iter().map(str::to_owned).collect(),
            }
        }
    }

    /// Check scope and, on denial, escalate to the provided `ApprovalHandler`.
    ///
    /// Returns `Ok(true)` if execution should proceed (allowed or overridden by
    /// the approval handler), `Ok(false)` if denied, or an error if the handler
    /// itself failed.
    pub async fn check_with_escalation<H: ApprovalHandler>(
        &self,
        tool_schema: &ToolSchema,
        tool_call: &cortexai_core::ToolCall,
        handler: &H,
    ) -> Result<bool, crate::approvals::ApprovalError> {
        match self.check(tool_schema) {
            ScopeCheckResult::Allowed => Ok(true),
            ScopeCheckResult::Denied { missing } => {
                let reason = format!("Missing required scopes: {}", missing.join(", "));
                debug!("Escalating scope denial for '{}': {}", tool_call.name, reason);

                let request = ApprovalRequest {
                    tool_call: tool_call.clone(),
                    tool_schema: Some(tool_schema.clone()),
                    reason: ApprovalReason::Custom(reason),
                    timestamp: chrono::Utc::now(),
                    context: None,
                };

                match handler.request_approval(request).await? {
                    ApprovalDecision::Approved | ApprovalDecision::Modify { .. } => Ok(true),
                    ApprovalDecision::Denied { .. } | ApprovalDecision::Skip => Ok(false),
                }
            }
        }
    }
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use crate::approvals::TestApprovalHandler;
    use cortexai_core::{ToolCall, ToolSchema};
    use serde_json::json;
    use std::collections::HashMap;

    fn make_tool_schema(name: &str, scopes: Vec<&str>) -> ToolSchema {
        ToolSchema {
            name: name.to_string(),
            description: "test tool".to_string(),
            parameters: json!({}),
            dangerous: false,
            metadata: HashMap::new(),
            required_scopes: scopes.into_iter().map(str::to_owned).collect(),
        }
    }

    fn make_tool_call(name: &str) -> ToolCall {
        ToolCall {
            id: "call-1".to_string(),
            name: name.to_string(),
            arguments: json!({}),
        }
    }

    // ------------------------------------------------------------------
    // ScopePolicy unit tests
    // ------------------------------------------------------------------

    #[test]
    fn test_exact_scope_granted() {
        let policy = ScopePolicy::new().grant("fs:read");
        assert!(policy.is_scope_granted("fs:read"));
    }

    #[test]
    fn test_exact_scope_not_granted() {
        let policy = ScopePolicy::new().grant("fs:read");
        assert!(!policy.is_scope_granted("fs:write"));
    }

    #[test]
    fn test_namespace_wildcard_grants_subscopes() {
        let policy = ScopePolicy::new().grant("fs:*");
        assert!(policy.is_scope_granted("fs:read"));
        assert!(policy.is_scope_granted("fs:write"));
        assert!(policy.is_scope_granted("fs:delete"));
    }

    #[test]
    fn test_namespace_wildcard_does_not_grant_other_namespaces() {
        let policy = ScopePolicy::new().grant("fs:*");
        assert!(!policy.is_scope_granted("network:external"));
    }

    #[test]
    fn test_global_wildcard_grants_all() {
        let policy = ScopePolicy::new().grant("*");
        assert!(policy.is_scope_granted("fs:read"));
        assert!(policy.is_scope_granted("network:external"));
        assert!(policy.is_scope_granted("finance:write"));
    }

    // ------------------------------------------------------------------
    // ScopeGuard check() tests
    // ------------------------------------------------------------------

    #[test]
    fn test_tool_without_scopes_is_always_allowed() {
        let guard = ScopeGuard::new(ScopePolicy::new());
        let schema = make_tool_schema("no_scopes_tool", vec![]);
        assert_eq!(guard.check(&schema), ScopeCheckResult::Allowed);
    }

    #[test]
    fn test_agent_with_required_scope_allowed() {
        let policy = ScopePolicy::new().grant("fs:read");
        let guard = ScopeGuard::new(policy);
        let schema = make_tool_schema("read_file", vec!["fs:read"]);
        assert_eq!(guard.check(&schema), ScopeCheckResult::Allowed);
    }

    #[test]
    fn test_agent_without_required_scope_denied() {
        let policy = ScopePolicy::new().grant("fs:read");
        let guard = ScopeGuard::new(policy);
        let schema = make_tool_schema("write_file", vec!["fs:write"]);
        assert!(matches!(guard.check(&schema), ScopeCheckResult::Denied { .. }));
    }

    #[test]
    fn test_denied_result_lists_missing_scopes() {
        let policy = ScopePolicy::new().grant("fs:read");
        let guard = ScopeGuard::new(policy);
        let schema = make_tool_schema("write_file", vec!["fs:write"]);
        match guard.check(&schema) {
            ScopeCheckResult::Denied { missing } => {
                assert_eq!(missing, vec!["fs:write"]);
            }
            ScopeCheckResult::Allowed => panic!("expected Denied"),
        }
    }

    #[test]
    fn test_wildcard_scope_grants_required_subscope() {
        let policy = ScopePolicy::new().grant("fs:*");
        let guard = ScopeGuard::new(policy);
        let schema = make_tool_schema("read_file", vec!["fs:read"]);
        assert_eq!(guard.check(&schema), ScopeCheckResult::Allowed);

        let write_schema = make_tool_schema("write_file", vec!["fs:write"]);
        assert_eq!(guard.check(&write_schema), ScopeCheckResult::Allowed);
    }

    #[test]
    fn test_multiple_required_scopes_all_must_be_granted() {
        let policy = ScopePolicy::new().grant("fs:read");
        let guard = ScopeGuard::new(policy);
        let schema = make_tool_schema("rw_tool", vec!["fs:read", "fs:write"]);
        assert!(matches!(guard.check(&schema), ScopeCheckResult::Denied { .. }));
    }

    #[test]
    fn test_multiple_required_scopes_all_granted() {
        let policy = ScopePolicy::new()
            .grant("fs:read")
            .grant("fs:write");
        let guard = ScopeGuard::new(policy);
        let schema = make_tool_schema("rw_tool", vec!["fs:read", "fs:write"]);
        assert_eq!(guard.check(&schema), ScopeCheckResult::Allowed);
    }

    // ------------------------------------------------------------------
    // Escalation tests
    // ------------------------------------------------------------------

    #[tokio::test]
    async fn test_scope_denial_triggers_approval_escalation() {
        let policy = ScopePolicy::new(); // no scopes granted
        let guard = ScopeGuard::new(policy);
        let schema = make_tool_schema("write_file", vec!["fs:write"]);
        let call = make_tool_call("write_file");

        // Handler that denies the escalation
        let handler = TestApprovalHandler::deny_all();

        let result = guard
            .check_with_escalation(&schema, &call, &handler)
            .await
            .unwrap();

        assert!(!result, "should be denied");
        assert_eq!(handler.request_count(), 1, "escalation should have been called");
    }

    #[tokio::test]
    async fn test_scope_denial_escalation_can_be_approved() {
        let policy = ScopePolicy::new(); // no scopes granted
        let guard = ScopeGuard::new(policy);
        let schema = make_tool_schema("write_file", vec!["fs:write"]);
        let call = make_tool_call("write_file");

        // Handler that approves the escalation
        let handler = TestApprovalHandler::approve_all();

        let result = guard
            .check_with_escalation(&schema, &call, &handler)
            .await
            .unwrap();

        assert!(result, "escalation approval should allow execution");
    }

    #[tokio::test]
    async fn test_allowed_tool_does_not_escalate() {
        let policy = ScopePolicy::new().grant("fs:read");
        let guard = ScopeGuard::new(policy);
        let schema = make_tool_schema("read_file", vec!["fs:read"]);
        let call = make_tool_call("read_file");

        let handler = TestApprovalHandler::deny_all();

        let result = guard
            .check_with_escalation(&schema, &call, &handler)
            .await
            .unwrap();

        assert!(result, "allowed tool should proceed without escalation");
        assert_eq!(handler.request_count(), 0, "no escalation for allowed tool");
    }
}