orcs_runtime/auth/

checker.rs

//! Permission checking types and policies.
//!
//! This module provides the [`PermissionChecker`] trait for policy-based
//! permission decisions, and [`DefaultPolicy`] as a standard implementation.
//!
//! # Design
//!
//! Permission checking is separated from the types themselves:
//!
//! - [`Session`](crate::Session): Holds identity and privilege level
//! - [`SignalScope`](orcs_types::SignalScope): Defines affected scope
//! - [`PermissionChecker`]: Decides if session can act on scope
//!
//! This separation allows:
//!
//! - Different policies for different environments
//! - Testing with mock policies
//! - Policy changes without modifying core types
//!
//! # Example
//!
//! ```
//! use orcs_runtime::{Principal, Session, PermissionChecker, DefaultPolicy};
//! use orcs_auth::PermissionPolicy;
//! use orcs_types::{PrincipalId, SignalScope, ChannelId};
//! use std::time::Duration;
//!
//! let policy = DefaultPolicy;
//! let session = Session::new(Principal::User(PrincipalId::new()));
//!
//! // Standard session cannot signal Global scope
//! assert!(!policy.can_signal(&session, &SignalScope::Global));
//!
//! // But can signal Channel scope
//! let channel = ChannelId::new();
//! assert!(policy.can_signal(&session, &SignalScope::Channel(channel)));
//!
//! // Elevated session can signal Global scope
//! let elevated = session.elevate(Duration::from_secs(60));
//! assert!(policy.can_signal(&elevated, &SignalScope::Global));
//! ```

use super::command_check::CommandCheckResult;
use super::Session;
use crate::components::ApprovalRequest;
use orcs_auth::{GrantPolicy, PermissionPolicy};
use orcs_types::SignalScope;

/// Runtime-level permission checker with HIL integration.
///
/// Extends [`PermissionPolicy`] (from `orcs-auth`) with
/// [`check_command`](PermissionChecker::check_command) that returns
/// [`CommandCheckResult`] (including `ApprovalRequest` for HIL flow).
///
/// # Architecture
///
/// ```text
/// PermissionPolicy (orcs-auth)     <- abstract, no runtime deps
///        ↑ supertrait
/// PermissionChecker (THIS TRAIT)   <- adds check_command(CommandCheckResult)
///        │
///        └── DefaultPolicy         <- concrete impl
/// ```
///
/// # Example Implementation
///
/// ```
/// use orcs_runtime::{PermissionChecker, Session};
/// use orcs_auth::PermissionPolicy;
/// use orcs_types::SignalScope;
///
/// struct StrictPolicy;
///
/// impl PermissionPolicy for StrictPolicy {
///     fn can_signal(&self, session: &Session, _scope: &SignalScope) -> bool {
///         session.is_elevated()
///     }
///
///     fn can_destructive(&self, session: &Session, _action: &str) -> bool {
///         session.is_elevated()
///     }
///
///     fn can_execute_command(&self, session: &Session, _cmd: &str) -> bool {
///         session.is_elevated()
///     }
///
///     fn can_spawn_child(&self, session: &Session) -> bool {
///         session.is_elevated()
///     }
///
///     fn can_spawn_runner(&self, session: &Session) -> bool {
///         session.is_elevated()
///     }
/// }
///
/// impl PermissionChecker for StrictPolicy {}
/// ```
pub trait PermissionChecker: PermissionPolicy {
    /// Check command with granular result including HIL approval flow.
    ///
    /// This is the preferred method for command checking as it supports:
    ///
    /// - Dynamic grants (previously approved commands via [`GrantPolicy`])
    /// - HIL approval flow (RequiresApproval)
    /// - Detailed denial reasons
    ///
    /// # Arguments
    ///
    /// * `session` - The current session (identity + privilege level)
    /// * `grants` - Dynamic command grants (previously approved patterns)
    /// * `cmd` - The command to check
    ///
    /// # Default Implementation
    ///
    /// Wraps `can_execute_command`:
    /// - Returns `Allowed` if `can_execute_command` returns true
    /// - Returns `Denied` otherwise
    ///
    /// Override this method to implement HIL integration.
    fn check_command(
        &self,
        session: &Session,
        grants: &dyn GrantPolicy,
        cmd: &str,
    ) -> CommandCheckResult {
        let granted = grants.is_granted(cmd).unwrap_or_else(|e| {
            tracing::error!("grant check failed in default check_command: {e}");
            false
        });
        if self.can_execute_command(session, cmd) || granted {
            CommandCheckResult::Allowed
        } else {
            CommandCheckResult::Denied("permission denied".to_string())
        }
    }
}

/// Default permission policy.
///
/// # Rules
///
/// | Scope/Action | Standard | Elevated |
/// |--------------|----------|----------|
/// | Global signal | Denied | Allowed |
/// | Channel signal | Allowed | Allowed |
/// | Destructive ops | Denied | Allowed |
/// | Command exec | Denied | Allowed |
/// | Spawn child/runner | Denied | Allowed |
///
/// # Security Model
///
/// Command safety is enforced at the OS sandbox layer (SandboxPolicy),
/// not by pattern-matching commands. This policy controls WHO can act
/// (session-based), while SandboxPolicy controls WHERE actions reach.
///
/// # Audit Logging
///
/// All permission checks are logged for audit:
/// - Allowed operations: debug level
/// - Denied operations: warn level
#[derive(Debug, Clone, Copy, Default)]
pub struct DefaultPolicy;

impl PermissionPolicy for DefaultPolicy {
    fn can_signal(&self, session: &Session, scope: &SignalScope) -> bool {
        let allowed = match scope {
            SignalScope::Global => session.is_elevated(),
            SignalScope::Channel(_) | SignalScope::WithChildren(_) => true,
        };

        // Audit logging
        if allowed {
            tracing::debug!(
                principal = ?session.principal(),
                elevated = session.is_elevated(),
                scope = ?scope,
                "signal allowed"
            );
        } else {
            tracing::warn!(
                principal = ?session.principal(),
                elevated = session.is_elevated(),
                scope = ?scope,
                "signal denied: requires elevation"
            );
        }

        allowed
    }

    fn can_destructive(&self, session: &Session, action: &str) -> bool {
        let allowed = session.is_elevated();

        // Audit logging
        if allowed {
            tracing::info!(
                principal = ?session.principal(),
                action = action,
                "destructive operation allowed"
            );
        } else {
            tracing::warn!(
                principal = ?session.principal(),
                action = action,
                "destructive operation denied: requires elevation"
            );
        }

        allowed
    }

    fn can_execute_command(&self, session: &Session, cmd: &str) -> bool {
        let allowed = session.is_elevated();

        if allowed {
            tracing::debug!(
                principal = ?session.principal(),
                cmd = cmd,
                "command allowed"
            );
        } else {
            tracing::warn!(
                principal = ?session.principal(),
                cmd = cmd,
                "command denied: requires elevation"
            );
        }

        allowed
    }

    fn can_spawn_child(&self, session: &Session) -> bool {
        let allowed = session.is_elevated();

        // Audit logging
        if allowed {
            tracing::debug!(
                principal = ?session.principal(),
                "spawn_child allowed"
            );
        } else {
            tracing::warn!(
                principal = ?session.principal(),
                "spawn_child denied: requires elevation"
            );
        }

        allowed
    }

    fn can_spawn_runner(&self, session: &Session) -> bool {
        let allowed = session.is_elevated();

        // Audit logging
        if allowed {
            tracing::debug!(
                principal = ?session.principal(),
                "spawn_runner allowed"
            );
        } else {
            tracing::warn!(
                principal = ?session.principal(),
                "spawn_runner denied: requires elevation"
            );
        }

        allowed
    }
}

impl PermissionChecker for DefaultPolicy {
    /// Check command with dynamic grants and HIL approval support.
    ///
    /// Flow:
    /// 1. Reject empty commands
    /// 2. Check dynamic grants (via [`GrantPolicy`]) -> Allowed
    /// 3. Check elevated session -> Allowed
    /// 4. Otherwise -> RequiresApproval (non-elevated session)
    ///
    /// Command safety is enforced at the OS sandbox layer, not here.
    /// This method only controls WHO can execute, not WHAT can be executed.
    fn check_command(
        &self,
        session: &Session,
        grants: &dyn GrantPolicy,
        cmd: &str,
    ) -> CommandCheckResult {
        let cmd_trimmed = cmd.trim();
        if cmd_trimmed.is_empty() {
            tracing::debug!("command denied: empty command");
            return CommandCheckResult::Denied("empty command".to_string());
        }

        // Step 1: Check dynamic grants (previously approved via HIL)
        let granted = grants.is_granted(cmd).unwrap_or_else(|e| {
            tracing::error!("grant check failed: {e}");
            false
        });
        if granted {
            tracing::debug!(
                principal = ?session.principal(),
                cmd = cmd,
                "command allowed: previously granted"
            );
            return CommandCheckResult::Allowed;
        }

        // Step 2: Delegate to can_execute_command (elevation check + audit logging)
        if self.can_execute_command(session, cmd) {
            return CommandCheckResult::Allowed;
        }

        // Step 3: Non-elevated sessions require approval
        let cmd_base = cmd.split_whitespace().next().unwrap_or(cmd);
        tracing::info!(
            principal = ?session.principal(),
            cmd = cmd,
            pattern = cmd_base,
            "command requires approval (non-elevated session)"
        );

        let request = ApprovalRequest::new(
            "exec",
            format!("Execute command: {}", cmd),
            serde_json::json!({
                "command": cmd,
                "pattern": cmd_base,
            }),
        );

        CommandCheckResult::RequiresApproval {
            request,
            grant_pattern: cmd_base.to_string(),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::auth::DefaultGrantStore;
    use orcs_auth::CommandGrant;
    use orcs_types::{ChannelId, Principal, PrincipalId};
    use std::time::Duration;

    fn standard_session() -> Session {
        Session::new(Principal::User(PrincipalId::new()))
    }

    fn elevated_session() -> Session {
        standard_session().elevate(Duration::from_secs(60))
    }

    fn empty_grants() -> DefaultGrantStore {
        DefaultGrantStore::new()
    }

    #[test]
    fn standard_cannot_signal_global() {
        let policy = DefaultPolicy;
        let session = standard_session();

        assert!(!policy.can_signal(&session, &SignalScope::Global));
    }

    #[test]
    fn standard_can_signal_channel() {
        let policy = DefaultPolicy;
        let session = standard_session();
        let channel = ChannelId::new();

        assert!(policy.can_signal(&session, &SignalScope::Channel(channel)));
    }

    #[test]
    fn elevated_can_signal_global() {
        let policy = DefaultPolicy;
        let session = elevated_session();

        assert!(policy.can_signal(&session, &SignalScope::Global));
    }

    #[test]
    fn elevated_can_signal_channel() {
        let policy = DefaultPolicy;
        let session = elevated_session();
        let channel = ChannelId::new();

        assert!(policy.can_signal(&session, &SignalScope::Channel(channel)));
    }

    #[test]
    fn standard_cannot_destructive() {
        let policy = DefaultPolicy;
        let session = standard_session();

        assert!(!policy.can_destructive(&session, "git reset --hard"));
        assert!(!policy.can_destructive(&session, "rm -rf"));
    }

    #[test]
    fn elevated_can_destructive() {
        let policy = DefaultPolicy;
        let session = elevated_session();

        assert!(policy.can_destructive(&session, "git reset --hard"));
        assert!(policy.can_destructive(&session, "rm -rf"));
    }

    #[test]
    fn system_session_standard() {
        let policy = DefaultPolicy;
        let session = Session::new(Principal::System);

        // System is also Standard by default
        assert!(!policy.can_signal(&session, &SignalScope::Global));
        assert!(policy.can_signal(&session, &SignalScope::Channel(ChannelId::new())));
    }

    #[test]
    fn dropped_privilege_cannot_global() {
        let policy = DefaultPolicy;
        let session = elevated_session().drop_privilege();

        assert!(!policy.can_signal(&session, &SignalScope::Global));
    }

    #[test]
    fn standard_cannot_execute_command() {
        let policy = DefaultPolicy;
        let session = standard_session();

        assert!(!policy.can_execute_command(&session, "ls -la"));
        assert!(!policy.can_execute_command(&session, "rm -rf ./temp"));
    }

    #[test]
    fn elevated_can_execute_any_command() {
        let policy = DefaultPolicy;
        let session = elevated_session();

        // Elevated can execute any command — safety is enforced by OS sandbox
        assert!(policy.can_execute_command(&session, "ls -la"));
        assert!(policy.can_execute_command(&session, "rm -rf ./target"));
        assert!(policy.can_execute_command(&session, "rm -rf /"));
        assert!(policy.can_execute_command(&session, "git push --force"));
    }

    #[test]
    fn standard_cannot_spawn_child() {
        let policy = DefaultPolicy;
        let session = standard_session();

        assert!(!policy.can_spawn_child(&session));
    }

    #[test]
    fn elevated_can_spawn_child() {
        let policy = DefaultPolicy;
        let session = elevated_session();

        assert!(policy.can_spawn_child(&session));
    }

    #[test]
    fn standard_cannot_spawn_runner() {
        let policy = DefaultPolicy;
        let session = standard_session();

        assert!(!policy.can_spawn_runner(&session));
    }

    #[test]
    fn elevated_can_spawn_runner() {
        let policy = DefaultPolicy;
        let session = elevated_session();

        assert!(policy.can_spawn_runner(&session));
    }

    // =========================================================================
    // check_command Tests
    // =========================================================================

    #[test]
    fn check_command_requires_approval_when_not_elevated() {
        let policy = DefaultPolicy;
        let session = standard_session();
        let grants = empty_grants();

        let result = policy.check_command(&session, &grants, "ls -la");
        assert!(result.requires_approval());
        assert_eq!(result.grant_pattern(), Some("ls"));
    }

    #[test]
    fn check_command_elevated_session_allowed() {
        let policy = DefaultPolicy;
        let session = elevated_session();
        let grants = empty_grants();

        // Elevated sessions can execute any command
        let result = policy.check_command(&session, &grants, "rm -rf ./temp");
        assert!(result.is_allowed());

        let result = policy.check_command(&session, &grants, "rm -rf /");
        assert!(result.is_allowed());
    }

    #[test]
    fn check_command_granted_command_allowed() {
        let policy = DefaultPolicy;
        let session = standard_session();
        let grants = DefaultGrantStore::new();

        grants
            .grant(CommandGrant::persistent("rm -rf"))
            .expect("grant persistent for check_command test");

        let result = policy.check_command(&session, &grants, "rm -rf ./temp");
        assert!(result.is_allowed());
    }

    #[test]
    fn check_command_empty_returns_denied() {
        let policy = DefaultPolicy;
        let session = elevated_session();
        let grants = empty_grants();

        let result = policy.check_command(&session, &grants, "  ");
        assert!(result.is_denied());
    }

    #[test]
    fn check_command_any_cmd_requires_approval_for_standard() {
        let policy = DefaultPolicy;
        let session = standard_session();
        let grants = empty_grants();

        // All commands require approval for standard sessions
        let result = policy.check_command(&session, &grants, "git push --force origin main");
        assert!(result.requires_approval());
        assert_eq!(result.grant_pattern(), Some("git"));
    }
}