enya-agent 0.1.0

package/crates/enact-core/src/policy/mod.rs

@@ -0,0 +1,193 @@
+//! Policy - Execution constraints and guardrails
+//!
+//! Policies define what is ALLOWED during execution:
+//! - Execution policies: limits, timeouts, retries
+//! - Tool policies: permissions, network/fs access, PII handling
+//! - Tenant policies: quotas, feature flags, isolation
+//! - Input processors: pre-execution validation (PII, prompt injection)
+//!
+//! ## Architecture
+//!
+//! Policies are evaluated BEFORE execution, not during business logic.
+//! This ensures:
+//! - Clear separation of concerns
+//! - Auditable policy decisions
+//! - No policy logic scattered in execution code
+//!
+//! ```text
+//! ┌─────────────────────────────────────────────┐
+//! │              Policy Evaluator               │
+//! │  ┌─────────────────────────────────────┐    │
+//! │  │ ExecutionPolicy │ ToolPolicy │ ...  │    │
+//! │  └─────────────────────────────────────┘    │
+//! │                     │                       │
+//! │                     ▼                       │
+//! │           Allow / Deny / Warn              │
+//! └─────────────────────────────────────────────┘
+//!                       │
+//!                       ▼
+//!              ExecutionKernel
+//! ```
+//!
+//! @see docs/TECHNICAL/17-GUARDRAILS-PROTECTION.md
+//! @see docs/TECHNICAL/25-STREAM-PROCESSORS.md
+
+mod execution_policy;
+mod filters;
+mod tenant_policy;
+mod tool_policy;
+
+// Input processors (feat-09: Guardrails)
+mod input_processor;
+mod long_running;
+mod pii_input;
+
+pub use execution_policy::{ExecutionLimits, ExecutionPolicy};
+pub use filters::{ContentFilter, FilterAction, FilterResult};
+pub use long_running::{
+    CheckpointPolicy, ContextStrategy, LongRunningExecutionPolicy, WorkingMemoryPolicy,
+};
+pub use tenant_policy::{FeatureFlags, TenantLimits, TenantPolicy};
+pub use tool_policy::{ToolPermissions, ToolPolicy, ToolTrustLevel};
+
+// Input processor exports
+pub use input_processor::{InputProcessor, InputProcessorPipeline, InputProcessorResult};
+pub use pii_input::{PiiInputMode, PiiInputProcessor};
+
+/// Policy decision result
+#[derive(Debug, Clone)]
+pub enum PolicyDecision {
+    /// Action is allowed
+    Allow,
+    /// Action is denied with reason
+    Deny { reason: String },
+    /// Action is allowed but logged/warned
+    Warn { message: String },
+}
+
+impl PolicyDecision {
+    pub fn is_allowed(&self) -> bool {
+        matches!(self, PolicyDecision::Allow | PolicyDecision::Warn { .. })
+    }
+
+    pub fn is_denied(&self) -> bool {
+        matches!(self, PolicyDecision::Deny { .. })
+    }
+}
+
+/// Trait for policy evaluators
+pub trait PolicyEvaluator: Send + Sync {
+    /// Evaluate a policy for the given context
+    fn evaluate(&self, context: &PolicyContext) -> PolicyDecision;
+}
+
+/// Context for policy evaluation
+#[derive(Debug, Clone)]
+pub struct PolicyContext {
+    /// Tenant ID (if multi-tenant)
+    pub tenant_id: Option<String>,
+    /// User ID
+    pub user_id: Option<String>,
+    /// Current action being evaluated
+    pub action: PolicyAction,
+    /// Additional metadata
+    pub metadata: std::collections::HashMap<String, String>,
+}
+
+/// Actions that can be evaluated by policies
+#[derive(Debug, Clone)]
+pub enum PolicyAction {
+    /// Starting an execution
+    StartExecution { graph_id: Option<String> },
+    /// Invoking a tool
+    InvokeTool { tool_name: String },
+    /// Making an LLM call
+    LlmCall { model: String },
+    /// Accessing external resource
+    ExternalAccess { resource: String },
+    /// Outputting content
+    OutputContent { content_type: String },
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // ============ PolicyDecision Tests ============
+
+    #[test]
+    fn test_policy_decision_allow() {
+        let decision = PolicyDecision::Allow;
+        assert!(decision.is_allowed());
+        assert!(!decision.is_denied());
+    }
+
+    #[test]
+    fn test_policy_decision_deny() {
+        let decision = PolicyDecision::Deny {
+            reason: "Not authorized".to_string(),
+        };
+        assert!(!decision.is_allowed());
+        assert!(decision.is_denied());
+    }
+
+    #[test]
+    fn test_policy_decision_warn() {
+        let decision = PolicyDecision::Warn {
+            message: "Proceed with caution".to_string(),
+        };
+        // Warn is allowed but logged
+        assert!(decision.is_allowed());
+        assert!(!decision.is_denied());
+    }
+
+    // ============ PolicyContext Tests ============
+
+    #[test]
+    fn test_policy_context_creation() {
+        let mut metadata = std::collections::HashMap::new();
+        metadata.insert("key".to_string(), "value".to_string());
+
+        let context = PolicyContext {
+            tenant_id: Some("tenant-123".to_string()),
+            user_id: Some("user-456".to_string()),
+            action: PolicyAction::StartExecution {
+                graph_id: Some("graph-789".to_string()),
+            },
+            metadata,
+        };
+
+        assert_eq!(context.tenant_id.as_ref().unwrap(), "tenant-123");
+        assert_eq!(context.user_id.as_ref().unwrap(), "user-456");
+        assert!(matches!(
+            context.action,
+            PolicyAction::StartExecution { .. }
+        ));
+    }
+
+    #[test]
+    fn test_policy_action_variants() {
+        let start = PolicyAction::StartExecution { graph_id: None };
+        assert!(matches!(start, PolicyAction::StartExecution { .. }));
+
+        let invoke = PolicyAction::InvokeTool {
+            tool_name: "web_search".to_string(),
+        };
+        assert!(matches!(invoke, PolicyAction::InvokeTool { .. }));
+
+        let llm = PolicyAction::LlmCall {
+            model: "gpt-4".to_string(),
+        };
+        assert!(matches!(llm, PolicyAction::LlmCall { .. }));
+
+        let external = PolicyAction::ExternalAccess {
+            resource: "https://api.example.com".to_string(),
+        };
+        assert!(matches!(external, PolicyAction::ExternalAccess { .. }));
+
+        let output = PolicyAction::OutputContent {
+            content_type: "text/plain".to_string(),
+        };
+        assert!(matches!(output, PolicyAction::OutputContent { .. }));
+    }
+}

package/crates/enact-core/src/policy/pii_input.rs

@@ -0,0 +1,274 @@
+//! PII Input Processor
+//!
+//! Detects PII in user input before execution.
+//! Can block, warn, or allow based on configuration.
+
+use super::input_processor::{InputProcessor, InputProcessorResult};
+use super::PolicyContext;
+use async_trait::async_trait;
+
+#[cfg(feature = "guardrails")]
+use enact_guardrails::{PiiClass, PiiDetector};
+
+/// PII detection mode
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PiiInputMode {
+    /// Allow all input (no PII checking)
+    Allow,
+    /// Warn if PII detected but allow
+    Warn,
+    /// Block if Direct PII detected (email, SSN, etc.)
+    BlockDirect,
+    /// Block if any PII detected
+    BlockAll,
+}
+
+impl Default for PiiInputMode {
+    fn default() -> Self {
+        Self::Warn
+    }
+}
+
+/// PII Input Processor
+///
+/// Detects PII in user input before sending to LLM.
+/// Behavior is configurable via `PiiInputMode`.
+pub struct PiiInputProcessor {
+    mode: PiiInputMode,
+    #[cfg(feature = "guardrails")]
+    detector: PiiDetector,
+}
+
+impl PiiInputProcessor {
+    /// Create a new PII input processor with default mode (Warn)
+    #[cfg(feature = "guardrails")]
+    pub fn new() -> Self {
+        Self {
+            mode: PiiInputMode::default(),
+            detector: PiiDetector::new(),
+        }
+    }
+
+    /// Create a new PII input processor (no-op when guardrails disabled)
+    #[cfg(not(feature = "guardrails"))]
+    pub fn new() -> Self {
+        Self {
+            mode: PiiInputMode::Allow,
+        }
+    }
+
+    /// Set the detection mode
+    pub fn with_mode(mut self, mode: PiiInputMode) -> Self {
+        self.mode = mode;
+        self
+    }
+
+    /// Check input for PII
+    #[cfg(feature = "guardrails")]
+    fn check_pii(&self, input: &str) -> Option<(PiiClass, Vec<String>)> {
+        let matches = self.detector.detect(input);
+        if matches.is_empty() {
+            return None;
+        }
+
+        // Get highest classification from matches
+        let highest = matches
+            .iter()
+            .fold(PiiClass::None, |acc, m| acc.max(m.class));
+
+        // Collect pattern names for reporting
+        let patterns: Vec<String> = matches.iter().map(|m| m.pattern_name.clone()).collect();
+
+        Some((highest, patterns))
+    }
+
+    /// Check input for PII (no-op when guardrails disabled)
+    #[cfg(not(feature = "guardrails"))]
+    #[allow(dead_code)]
+    fn check_pii(&self, _input: &str) -> Option<((), Vec<String>)> {
+        None
+    }
+}
+
+impl Default for PiiInputProcessor {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait]
+impl InputProcessor for PiiInputProcessor {
+    fn name(&self) -> &str {
+        "pii-input"
+    }
+
+    fn priority(&self) -> u32 {
+        50 // Run early in the pipeline
+    }
+
+    #[cfg(feature = "guardrails")]
+    async fn process(
+        &self,
+        input: &str,
+        _ctx: &PolicyContext,
+    ) -> anyhow::Result<InputProcessorResult> {
+        // Skip if mode is Allow
+        if self.mode == PiiInputMode::Allow {
+            return Ok(InputProcessorResult::Pass);
+        }
+
+        // Check for PII
+        if let Some((class, patterns)) = self.check_pii(input) {
+            let pattern_list = patterns.join(", ");
+
+            match self.mode {
+                PiiInputMode::Allow => {
+                    // Already handled above
+                    Ok(InputProcessorResult::Pass)
+                }
+                PiiInputMode::Warn => {
+                    // Log warning but allow
+                    tracing::warn!(
+                        pii_class = ?class,
+                        patterns = %pattern_list,
+                        "PII detected in input"
+                    );
+                    Ok(InputProcessorResult::Pass)
+                }
+                PiiInputMode::BlockDirect => {
+                    // Block only Direct PII
+                    if class == PiiClass::Direct {
+                        Ok(InputProcessorResult::Block {
+                            reason: format!("Direct PII detected in input: {}", pattern_list),
+                            processor: self.name().to_string(),
+                        })
+                    } else {
+                        tracing::warn!(
+                            pii_class = ?class,
+                            patterns = %pattern_list,
+                            "Indirect/Sensitive PII detected in input (allowed)"
+                        );
+                        Ok(InputProcessorResult::Pass)
+                    }
+                }
+                PiiInputMode::BlockAll => {
+                    // Block any PII
+                    Ok(InputProcessorResult::Block {
+                        reason: format!("PII detected in input ({:?}): {}", class, pattern_list),
+                        processor: self.name().to_string(),
+                    })
+                }
+            }
+        } else {
+            Ok(InputProcessorResult::Pass)
+        }
+    }
+
+    #[cfg(not(feature = "guardrails"))]
+    async fn process(
+        &self,
+        _input: &str,
+        _ctx: &PolicyContext,
+    ) -> anyhow::Result<InputProcessorResult> {
+        // No guardrails feature, always pass
+        Ok(InputProcessorResult::Pass)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::policy::PolicyAction;
+    use std::collections::HashMap;
+
+    fn test_context() -> PolicyContext {
+        PolicyContext {
+            tenant_id: None,
+            user_id: None,
+            action: PolicyAction::StartExecution { graph_id: None },
+            metadata: HashMap::new(),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_pii_input_processor_name() {
+        let processor = PiiInputProcessor::new();
+        assert_eq!(processor.name(), "pii-input");
+    }
+
+    #[tokio::test]
+    async fn test_pii_input_processor_priority() {
+        let processor = PiiInputProcessor::new();
+        assert_eq!(processor.priority(), 50);
+    }
+
+    #[cfg(feature = "guardrails")]
+    #[tokio::test]
+    async fn test_pii_input_allow_mode() {
+        let processor = PiiInputProcessor::new().with_mode(PiiInputMode::Allow);
+        let ctx = test_context();
+
+        // Even with PII, should pass
+        let result = processor
+            .process("Email: user@example.com", &ctx)
+            .await
+            .unwrap();
+        assert!(result.should_proceed());
+    }
+
+    #[cfg(feature = "guardrails")]
+    #[tokio::test]
+    async fn test_pii_input_warn_mode() {
+        let processor = PiiInputProcessor::new().with_mode(PiiInputMode::Warn);
+        let ctx = test_context();
+
+        // With PII, should warn but pass
+        let result = processor
+            .process("Email: user@example.com", &ctx)
+            .await
+            .unwrap();
+        assert!(result.should_proceed());
+    }
+
+    #[cfg(feature = "guardrails")]
+    #[tokio::test]
+    async fn test_pii_input_block_direct() {
+        let processor = PiiInputProcessor::new().with_mode(PiiInputMode::BlockDirect);
+        let ctx = test_context();
+
+        // Direct PII (email) should block
+        let result = processor
+            .process("Email: user@example.com", &ctx)
+            .await
+            .unwrap();
+        assert!(result.is_blocked());
+
+        // No PII should pass
+        let result = processor.process("Hello world", &ctx).await.unwrap();
+        assert!(result.should_proceed());
+    }
+
+    #[cfg(feature = "guardrails")]
+    #[tokio::test]
+    async fn test_pii_input_block_all() {
+        let processor = PiiInputProcessor::new().with_mode(PiiInputMode::BlockAll);
+        let ctx = test_context();
+
+        // Any PII should block
+        let result = processor.process("IP: 192.168.1.1", &ctx).await.unwrap();
+        assert!(result.is_blocked());
+    }
+
+    #[tokio::test]
+    async fn test_pii_input_no_pii() {
+        let processor = PiiInputProcessor::new();
+        let ctx = test_context();
+
+        // No PII should always pass
+        let result = processor
+            .process("Hello, how can I help?", &ctx)
+            .await
+            .unwrap();
+        assert!(result.should_proceed());
+    }
+}