mur_core/constitution/

mod.rs

//! Constitution system — the core safety mechanism for MUR Commander.
//!
//! The constitution defines what the agent is allowed to do, what requires
//! human approval, and what is absolutely forbidden. It is tamper-proof
//! via Ed25519 signatures and SHA-256 checksums.

pub mod signing;

use crate::types::{Action, ActionDecision};
use serde::{Deserialize, Serialize};
use std::path::Path;
use thiserror::Error;

/// Errors that can occur when loading or checking the constitution.
#[derive(Debug, Error)]
pub enum ConstitutionError {
    #[error("Failed to read constitution file: {0}")]
    ReadError(#[from] std::io::Error),

    #[error("Failed to parse constitution TOML: {0}")]
    ParseError(#[from] toml::de::Error),

    #[error("Constitution integrity check failed: {0}")]
    IntegrityError(String),

    #[error("Constitution signing error: {0}")]
    SigningError(String),
}

/// The parsed constitution configuration from TOML.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ConstitutionConfig {
    pub identity: Identity,
    pub boundaries: Boundaries,
    pub resource_limits: ResourceLimits,
    pub model_permissions: ModelPermissions,
}

/// Identity section — version and signing metadata.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Identity {
    pub version: String,
    /// SHA-256 hex digest of the constitution content (excluding identity section).
    #[serde(default)]
    pub checksum: String,
    /// Who signed this constitution.
    #[serde(default)]
    pub signed_by: String,
    /// Base64-encoded Ed25519 signature.
    #[serde(default)]
    pub signature: String,
}

/// Boundary rules — forbidden, requires_approval, auto_allowed patterns.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Boundaries {
    /// Patterns that are absolutely forbidden.
    pub forbidden: Vec<String>,
    /// Patterns that require user approval.
    pub requires_approval: Vec<String>,
    /// Patterns that are automatically allowed.
    pub auto_allowed: Vec<String>,
}

/// Resource limits to prevent runaway execution.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResourceLimits {
    /// Maximum API cost (USD) per workflow run.
    pub max_api_cost_per_run: f64,
    /// Maximum API cost (USD) per day.
    pub max_api_cost_per_day: f64,
    /// Maximum execution time in seconds per workflow.
    pub max_execution_time: u64,
    /// Maximum number of concurrent workflows.
    pub max_concurrent_workflows: u32,
    /// Maximum file write size (e.g. "10MB").
    pub max_file_write_size: String,
    /// Directories the agent is allowed to access.
    pub allowed_directories: Vec<String>,
    /// Directories the agent must never access.
    pub blocked_directories: Vec<String>,
}

/// Per-model-role permission flags.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelPermission {
    pub can_execute: bool,
    pub can_read: bool,
    #[serde(default)]
    pub sandbox_only: bool,
}

/// Model permissions section.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelPermissions {
    pub thinking_model: ModelPermission,
    pub coding_model: ModelPermission,
    pub task_model: ModelPermission,
}

/// The loaded constitution with parsed config.
#[derive(Debug, Clone)]
pub struct Constitution {
    /// Parsed configuration from the TOML file.
    pub config: ConstitutionConfig,
    /// Raw TOML content (used for checksum/signature verification).
    raw_content: String,
}

impl Constitution {
    /// Load a constitution from a TOML file path.
    pub fn load(path: &Path) -> Result<Self, ConstitutionError> {
        let raw_content = std::fs::read_to_string(path)?;
        let config: ConstitutionConfig = toml::from_str(&raw_content)?;
        Ok(Self {
            config,
            raw_content,
        })
    }

    /// Load a constitution from a raw TOML string (useful for testing).
    pub fn from_toml(content: &str) -> Result<Self, ConstitutionError> {
        let config: ConstitutionConfig = toml::from_str(content)?;
        Ok(Self {
            config,
            raw_content: content.to_string(),
        })
    }

    /// Get the raw TOML content.
    pub fn raw_content(&self) -> &str {
        &self.raw_content
    }

    /// Check whether a given action is allowed by the constitution.
    ///
    /// Decision priority:
    /// 1. Forbidden patterns → Blocked
    /// 2. Requires approval patterns → NeedsApproval
    /// 3. Auto-allowed patterns → Allowed
    /// 4. Unknown actions → NeedsApproval (safe default)
    pub fn check_action(&self, action: &Action) -> ActionDecision {
        let command = action.command.to_lowercase();
        let description = action.description.to_lowercase();

        // 1. Check forbidden patterns first (highest priority)
        for pattern in &self.config.boundaries.forbidden {
            if matches_pattern(&command, pattern) || matches_pattern(&description, pattern) {
                return ActionDecision::Blocked {
                    reason: format!("Forbidden by constitution: matches '{}'", pattern),
                };
            }
        }

        // 2. Check requires_approval patterns
        for pattern in &self.config.boundaries.requires_approval {
            if matches_pattern(&command, pattern) || matches_pattern(&description, pattern) {
                return ActionDecision::NeedsApproval {
                    prompt: format!(
                        "Action requires approval (matches '{}'): {}",
                        pattern, action.description
                    ),
                };
            }
        }

        // 3. Check auto_allowed patterns
        for pattern in &self.config.boundaries.auto_allowed {
            if matches_pattern(&command, pattern) || matches_pattern(&description, pattern) {
                return ActionDecision::Allowed;
            }
        }

        // 4. Default: unknown actions require approval (safe default)
        ActionDecision::NeedsApproval {
            prompt: format!(
                "Unknown action, requesting approval: {}",
                action.description
            ),
        }
    }

    /// Check whether a cost amount exceeds the per-run limit.
    pub fn check_cost_per_run(&self, cost: f64) -> bool {
        cost <= self.config.resource_limits.max_api_cost_per_run
    }

    /// Check whether a cost amount exceeds the daily limit.
    pub fn check_cost_per_day(&self, cost: f64) -> bool {
        cost <= self.config.resource_limits.max_api_cost_per_day
    }

    /// Check if a directory path is allowed by the constitution.
    pub fn is_directory_allowed(&self, path: &str) -> bool {
        // First check blocked directories (highest priority)
        for blocked in &self.config.resource_limits.blocked_directories {
            let expanded = expand_tilde(blocked);
            if path.starts_with(&expanded) {
                return false;
            }
        }

        // Then check allowed directories
        for allowed in &self.config.resource_limits.allowed_directories {
            let expanded = expand_tilde(allowed);
            if path.starts_with(&expanded) {
                return true;
            }
        }

        false
    }
}

/// Simple glob-like pattern matching for constitution rules.
///
/// Supports:
/// - `*` as a wildcard (matches any substring)
/// - Case-insensitive matching
/// - Word-boundary-aware matching (the first non-wildcard segment must
///   start at a word boundary to prevent "undeploy" matching "deploy *")
fn matches_pattern(text: &str, pattern: &str) -> bool {
    let text_lower = text.to_lowercase();
    let pattern_lower = pattern.to_lowercase();

    if pattern_lower.contains('*') {
        // Split on wildcards and check if all parts appear in order
        let parts: Vec<&str> = pattern_lower.split('*').collect();
        let mut search_from = 0;
        let mut is_first_part = true;
        for part in &parts {
            if part.is_empty() {
                is_first_part = false;
                continue;
            }
            match find_word_start(&text_lower[search_from..], part, is_first_part) {
                Some(pos) => search_from += pos + part.len(),
                None => return false,
            }
            is_first_part = false;
        }
        true
    } else {
        // Word-boundary-aware substring match
        find_word_start(&text_lower, &pattern_lower, true).is_some()
    }
}

/// Find a substring starting at a word boundary.
///
/// A word boundary means the match is either at position 0, or preceded by
/// a non-alphanumeric character (space, slash, hyphen, etc.).
/// If `require_word_boundary` is false, acts as a plain `find`.
fn find_word_start(text: &str, needle: &str, require_word_boundary: bool) -> Option<usize> {
    let mut start = 0;
    while let Some(pos) = text[start..].find(needle) {
        let abs_pos = start + pos;
        if !require_word_boundary || abs_pos == 0 || !text.as_bytes()[abs_pos - 1].is_ascii_alphanumeric() {
            return Some(abs_pos);
        }
        // Skip this match, try from the next character
        start = abs_pos + 1;
        if start >= text.len() {
            break;
        }
    }
    None
}

/// Expand `~` to the user's home directory.
fn expand_tilde(path: &str) -> String {
    if path.starts_with('~') {
        if let Some(home) = dirs_home() {
            return path.replacen('~', &home, 1);
        }
    }
    path.to_string()
}

fn dirs_home() -> Option<String> {
    directories::BaseDirs::new().map(|d| d.home_dir().to_string_lossy().to_string())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::{ActionType, Action};
    use chrono::Utc;
    use uuid::Uuid;

    fn make_action(command: &str, description: &str) -> Action {
        Action {
            id: Uuid::new_v4(),
            action_type: ActionType::Execute,
            description: description.to_string(),
            command: command.to_string(),
            working_dir: None,
            created_at: Utc::now(),
        }
    }

    fn sample_constitution() -> Constitution {
        let toml_str = r#"
[identity]
version = "1.0.0"
checksum = ""
signed_by = ""
signature = ""

[boundaries]
forbidden = [
    "rm -rf /",
    "sudo rm *",
    "DROP DATABASE",
    "format disk",
    "send email without approval",
    "access /etc/shadow",
    "modify constitution without re-sign",
]

requires_approval = [
    "git push",
    "deploy *",
    "send notification",
    "modify system config",
    "install package",
    "network request to unknown host",
    "spend > $1 on API calls",
]

auto_allowed = [
    "read files in project directory",
    "run tests",
    "git status",
    "git diff",
    "git log",
    "search patterns",
    "local HTTP on localhost",
]

[resource_limits]
max_api_cost_per_run = 5.0
max_api_cost_per_day = 50.0
max_execution_time = 3600
max_concurrent_workflows = 3
max_file_write_size = "10MB"
allowed_directories = ["~/Projects", "~/.mur", "/tmp"]
blocked_directories = ["/etc", "/System", "~/.ssh"]

[model_permissions]
thinking_model = { can_execute = false, can_read = true }
coding_model = { can_execute = true, can_read = true, sandbox_only = true }
task_model = { can_execute = true, can_read = true }
"#;
        Constitution::from_toml(toml_str).expect("Failed to parse sample constitution")
    }

    #[test]
    fn test_load_constitution_from_str() {
        let c = sample_constitution();
        assert_eq!(c.config.identity.version, "1.0.0");
        assert_eq!(c.config.boundaries.forbidden.len(), 7);
        assert_eq!(c.config.boundaries.requires_approval.len(), 7);
        assert_eq!(c.config.boundaries.auto_allowed.len(), 7);
    }

    #[test]
    fn test_check_action_forbidden() {
        let c = sample_constitution();
        let action = make_action("rm -rf /", "Delete everything");
        let decision = c.check_action(&action);
        assert!(matches!(decision, ActionDecision::Blocked { .. }));
    }

    #[test]
    fn test_check_action_forbidden_drop_database() {
        let c = sample_constitution();
        let action = make_action("DROP DATABASE production", "Drop the production database");
        let decision = c.check_action(&action);
        assert!(matches!(decision, ActionDecision::Blocked { .. }));
    }

    #[test]
    fn test_check_action_requires_approval() {
        let c = sample_constitution();
        let action = make_action("git push origin main", "Push to remote");
        let decision = c.check_action(&action);
        assert!(matches!(decision, ActionDecision::NeedsApproval { .. }));
    }

    #[test]
    fn test_check_action_requires_approval_deploy() {
        let c = sample_constitution();
        let action = make_action("deploy production", "Deploy to production");
        let decision = c.check_action(&action);
        assert!(matches!(decision, ActionDecision::NeedsApproval { .. }));
    }

    #[test]
    fn test_check_action_auto_allowed() {
        let c = sample_constitution();
        let action = make_action("git status", "Check git status");
        let decision = c.check_action(&action);
        assert!(matches!(decision, ActionDecision::Allowed));
    }

    #[test]
    fn test_check_action_auto_allowed_tests() {
        let c = sample_constitution();
        let action = make_action("cargo test", "run tests");
        let decision = c.check_action(&action);
        assert!(matches!(decision, ActionDecision::Allowed));
    }

    #[test]
    fn test_check_action_unknown_defaults_to_approval() {
        let c = sample_constitution();
        let action = make_action("some-unknown-command", "Do something weird");
        let decision = c.check_action(&action);
        assert!(matches!(decision, ActionDecision::NeedsApproval { .. }));
    }

    #[test]
    fn test_cost_limits() {
        let c = sample_constitution();
        assert!(c.check_cost_per_run(4.99));
        assert!(c.check_cost_per_run(5.0));
        assert!(!c.check_cost_per_run(5.01));

        assert!(c.check_cost_per_day(49.99));
        assert!(!c.check_cost_per_day(50.01));
    }

    #[test]
    fn test_matches_pattern_simple() {
        assert!(matches_pattern("git push origin main", "git push"));
        assert!(!matches_pattern("git pull origin main", "git push"));
    }

    #[test]
    fn test_matches_pattern_wildcard() {
        assert!(matches_pattern("deploy production", "deploy *"));
        assert!(matches_pattern("deploy staging", "deploy *"));
        assert!(!matches_pattern("undeploy staging", "deploy *"));
    }

    #[test]
    fn test_matches_pattern_case_insensitive() {
        assert!(matches_pattern("DROP DATABASE foo", "drop database"));
        assert!(matches_pattern("drop database foo", "DROP DATABASE"));
    }

    #[test]
    fn test_resource_limits_parsing() {
        let c = sample_constitution();
        assert_eq!(c.config.resource_limits.max_api_cost_per_run, 5.0);
        assert_eq!(c.config.resource_limits.max_execution_time, 3600);
        assert_eq!(c.config.resource_limits.max_concurrent_workflows, 3);
    }

    #[test]
    fn test_model_permissions() {
        let c = sample_constitution();
        assert!(!c.config.model_permissions.thinking_model.can_execute);
        assert!(c.config.model_permissions.thinking_model.can_read);
        assert!(c.config.model_permissions.coding_model.can_execute);
        assert!(c.config.model_permissions.coding_model.sandbox_only);
    }
}