car_policy/

lib.rs

//! Policy engine — rules that govern what actions the runtime will allow.
//!
//! Two complementary mechanisms live here:
//!
//! 1. [`PolicyEngine`] — evaluates static policies against `(Action, StateStore)`
//!    and collects every violation. Designed for pre-execution batch validation.
//! 2. [`inspectors::InspectorChain`] — evaluates a short-circuiting chain of
//!    inspectors against `(tool_name, params)` at dispatch time. Stops on the
//!    first Deny. Designed for hot-path guardrails (egress, repetition,
//!    adversary review).

/// Whether a track record has degraded: failures outrun successes by more than
/// `threshold`.
///
/// **One definition, three callers.** `car-memgine` auto-degrades a skill on
/// this rule, `skill_trust` demotes a skill's trust tier on it — its own doc
/// said it was "the same rule car-memgine uses" while hardcoding a second copy
/// of the threshold — and peer standing is the third. Three copies of a
/// predicate that must agree is how they stop agreeing; `car-policy` is the
/// only legal home because `car-memgine` already depends on it and never the
/// reverse.
///
/// Deliberately asymmetric: it takes more than a bare majority of failures to
/// degrade, so a new record with one failure and no successes is not condemned
/// on its first bad day.
pub fn degrades(success_count: u64, fail_count: u64, threshold: u64) -> bool {
    fail_count > success_count + threshold
}

/// The threshold every degradation check uses unless a caller has a reason.
pub const DEGRADE_THRESHOLD: u64 = 2;

pub mod agent_permissions;
pub mod flow_gate;
pub mod inspectors;
pub mod intent_gate;
pub mod permission;
pub mod rules;
pub mod skill_trust;
pub mod tool_gate;

pub use agent_permissions::{AgentPermissionPolicy, ApprovalMode, ApprovalPreset, TierPosture};
pub use flow_gate::{enforce_flow, flow_fingerprint, FlowEnforcement, PendingFlowApproval};
pub use intent_gate::{
    enforce_intent, intent_fingerprint, IntentEnforcement, PendingIntentApproval,
};

pub use inspectors::{
    load_adversary_rules_from, AdversaryInspector, EgressInspector, InspectionResult, Inspector,
    InspectorChain, RepetitionInspector,
};
pub use permission::{
    action_fingerprint, action_text, classify_reversibility, classify_reversibility_with_haystack,
    ActionAxes, ApprovalDecision, ApprovalLedger, ApprovalRecord, GateDecision, PermissionGate,
    PermissionTier, RiskClassifier,
};
pub use rules::{load_policy_dir, DenyToolParam, PolicyLoadError, PolicyRules};

use car_ir::Action;
use car_state::StateStore;
use std::collections::BTreeSet;
use std::panic::{self, AssertUnwindSafe};

/// A policy violation found during checking.
#[derive(Debug, Clone)]
pub struct PolicyViolation {
    pub policy_name: String,
    pub action_id: String,
    pub reason: String,
}

/// Policy check function: `(action, state) -> Option<violation_reason>`
pub type PolicyCheck = Box<dyn Fn(&Action, &StateStore) -> Option<String> + Send + Sync>;

/// Evaluates actions against registered policies.
pub struct PolicyEngine {
    policies: Vec<(String, String, PolicyCheck)>, // (name, description, check_fn)
    /// `(policy name, tool)` for every check registered through
    /// [`PolicyEngine::register_tool_deny`] — the checks that forbid a tool
    /// outright. Recorded structurally rather than recovered by parsing
    /// `policies`' names: a name is caller-chosen on some registration paths,
    /// so a convention would both miss real denies and let an unrelated check
    /// registered under the right-looking name claim to be one.
    blanket_tool_denies: Vec<(String, String)>,
}

impl PolicyEngine {
    pub fn new() -> Self {
        Self {
            policies: Vec::new(),
            blanket_tool_denies: Vec::new(),
        }
    }

    pub fn register(&mut self, name: &str, check: PolicyCheck, description: &str) {
        self.policies
            .push((name.to_string(), description.to_string(), check));
    }

    /// [`Self::register`], plus the standing fact that `check` forbids `tool`
    /// **outright** — whatever the arguments.
    ///
    /// Use this for a rule that denies a whole tool, so it can be read back by
    /// [`Self::blanket_denied_tools`]. The check itself is still the caller's,
    /// deliberately: a file-loaded rule and a host-registered one word their
    /// refusal differently, and centralizing the closure here would make one of
    /// those messages wrong.
    ///
    /// Registering a *conditional* check through this door mislabels it and
    /// will hide a tool that is only sometimes denied. There is no way to check
    /// that from here — the check is an opaque closure — so the contract is on
    /// the caller.
    pub fn register_tool_deny(
        &mut self,
        name: &str,
        tool: &str,
        check: PolicyCheck,
        description: &str,
    ) {
        self.register(name, check, description);
        self.blanket_tool_denies
            .push((name.to_string(), tool.to_string()));
    }

    /// Check an action against all policies.
    ///
    /// If a policy check panics, the panic is caught and treated as a violation.
    pub fn check(&self, action: &Action, state: &StateStore) -> Vec<PolicyViolation> {
        let mut violations = Vec::new();

        for (name, _, check_fn) in &self.policies {
            let result = panic::catch_unwind(AssertUnwindSafe(|| check_fn(action, state)));

            match result {
                Ok(Some(reason)) => {
                    violations.push(PolicyViolation {
                        policy_name: name.clone(),
                        action_id: action.id.clone(),
                        reason,
                    });
                }
                Ok(None) => {} // passed
                Err(_) => {
                    violations.push(PolicyViolation {
                        policy_name: name.clone(),
                        action_id: action.id.clone(),
                        reason: format!("policy '{}' panicked during check", name),
                    });
                }
            }
        }

        violations
    }

    /// Remove every policy registered under `name`. Returns how many were
    /// dropped — 0 when nothing matched, so the caller can distinguish "removed"
    /// from "there was nothing by that name".
    ///
    /// [`Self::register`] appends without de-duplicating, so the same name can
    /// legitimately appear more than once; this removes all of them rather than
    /// leaving a shadowed copy still enforcing (Parslee-ai/car#623).
    pub fn unregister(&mut self, name: &str) -> usize {
        let before = self.policies.len();
        self.policies.retain(|(n, _, _)| n != name);
        // Lifting the rule must lift the concealment with it, or a tool stays
        // hidden from the model that the engine no longer blocks.
        self.blanket_tool_denies.retain(|(n, _)| n != name);
        before - self.policies.len()
    }

    /// Drop every registered policy. Returns how many were removed.
    pub fn clear(&mut self) -> usize {
        let n = self.policies.len();
        self.policies.clear();
        self.blanket_tool_denies.clear();
        n
    }

    /// The tools this engine forbids **outright**, whatever the arguments —
    /// the `deny_tool` rule kind, and only that kind.
    ///
    /// For callers that assemble the tool list a model is shown. A tool no
    /// call can ever satisfy is worth removing from that list rather than
    /// advertising and then refusing: the refusal is correct but costs a turn
    /// and a schema's worth of context on every request.
    ///
    /// # Why only `deny_tool`
    ///
    /// Not because the other kinds are "argument-dependent" — several of them
    /// can forbid a tool outright too:
    ///
    /// - `allow_tool_param` with an empty `allow` permits nothing.
    /// - `rate_limit_tool` with `max_calls = 0` denies every call.
    /// - `deny_tool_param_matching` whose pattern fails to compile denies the
    ///   whole tool, fail-closed.
    /// - `deny_tool_param` with neither `equals` nor `contains` denies on the
    ///   parameter's mere presence, which is total for a required parameter.
    ///
    /// The property that actually separates them is **whether totality is
    /// decidable from the rule kind alone, without reading the rule's
    /// contents**. `deny_tool` is the only kind where it is. The others are
    /// total only by inspection, and a caller assembling a tool list has no
    /// business inspecting them — so this deliberately under-reports rather
    /// than guess. Under-reporting is the safe direction: the tool is
    /// advertised and then refused, which is exactly the old behavior.
    ///
    /// A narrow-but-not-total `allow_tool_param` is the case this leaves on
    /// the table. Hiding is the wrong remedy there (the tool *is* callable,
    /// just not that way); narrowing the advertised parameter schema to the
    /// permitted values is, and that is a separate change.
    ///
    /// Populated by [`Self::register_tool_deny`] and emptied in step with
    /// [`Self::unregister`] and [`Self::clear`], so it cannot name a tool the
    /// engine no longer blocks. A stale entry here would hide a tool that is
    /// actually allowed, which is the one failure mode worth engineering
    /// against.
    pub fn blanket_denied_tools(&self) -> BTreeSet<String> {
        self.blanket_tool_denies
            .iter()
            .map(|(_, tool)| tool.clone())
            .collect()
    }

    /// Registered policy names, in registration order. May contain duplicates —
    /// see [`Self::unregister`].
    pub fn policy_names(&self) -> Vec<String> {
        self.policies.iter().map(|(n, _, _)| n.clone()).collect()
    }

    /// Registered policies as `(name, description)` pairs, in registration
    /// order. The description is what `register` was given.
    pub fn policy_details(&self) -> Vec<(String, String)> {
        self.policies
            .iter()
            .map(|(n, d, _)| (n.clone(), d.clone()))
            .collect()
    }

    pub fn is_empty(&self) -> bool {
        self.policies.is_empty()
    }
}

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

#[cfg(test)]
mod tests {
    use super::*;
    use car_ir::ActionType;
    use serde_json::Value;

    fn make_action(tool: &str) -> Action {
        {
            let mut a = Action::new(ActionType::ToolCall);
            a.id = "test".to_string();
            a.tool = Some(tool.to_string());
            a
        }
    }

    #[test]
    fn no_policies_passes() {
        let engine = PolicyEngine::new();
        let state = StateStore::new();
        let violations = engine.check(&make_action("echo"), &state);
        assert!(violations.is_empty());
    }

    #[test]
    fn policy_blocks_action() {
        let mut engine = PolicyEngine::new();
        engine.register(
            "no_echo",
            Box::new(|action, _state| {
                if action.tool.as_deref() == Some("echo") {
                    Some("echo is forbidden".to_string())
                } else {
                    None
                }
            }),
            "Block echo tool",
        );

        let state = StateStore::new();
        let violations = engine.check(&make_action("echo"), &state);
        assert_eq!(violations.len(), 1);
        assert!(violations[0].reason.contains("forbidden"));
    }

    #[test]
    fn policy_allows_other_tools() {
        let mut engine = PolicyEngine::new();
        engine.register(
            "no_echo",
            Box::new(|action, _state| {
                if action.tool.as_deref() == Some("echo") {
                    Some("forbidden".to_string())
                } else {
                    None
                }
            }),
            "",
        );

        let state = StateStore::new();
        let violations = engine.check(&make_action("add"), &state);
        assert!(violations.is_empty());
    }

    #[test]
    fn policy_checks_state() {
        let mut engine = PolicyEngine::new();
        engine.register(
            "require_auth",
            Box::new(|_action, state| {
                if state.get("auth") != Some(Value::Bool(true)) {
                    Some("auth required".to_string())
                } else {
                    None
                }
            }),
            "",
        );

        let state = StateStore::new();
        let violations = engine.check(&make_action("deploy"), &state);
        assert_eq!(violations.len(), 1);

        state.set("auth", Value::Bool(true), "setup");
        let violations2 = engine.check(&make_action("deploy"), &state);
        assert!(violations2.is_empty());
    }

    #[test]
    fn panicking_policy_caught() {
        let mut engine = PolicyEngine::new();
        engine.register(
            "crasher",
            Box::new(|_action, _state| {
                panic!("policy crashed");
            }),
            "",
        );

        let state = StateStore::new();
        let violations = engine.check(&make_action("anything"), &state);
        assert_eq!(violations.len(), 1);
        assert!(violations[0].reason.contains("panicked"));
    }

    #[test]
    fn multiple_policies() {
        let mut engine = PolicyEngine::new();
        engine.register("p1", Box::new(|_, _| Some("fail 1".to_string())), "");
        engine.register("p2", Box::new(|_, _| None), "");
        engine.register("p3", Box::new(|_, _| Some("fail 3".to_string())), "");

        let state = StateStore::new();
        let violations = engine.check(&make_action("x"), &state);
        assert_eq!(violations.len(), 2);
    }

    #[test]
    fn policy_names() {
        let mut engine = PolicyEngine::new();
        engine.register("alpha", Box::new(|_, _| None), "");
        engine.register("beta", Box::new(|_, _| None), "");
        assert_eq!(engine.policy_names(), vec!["alpha", "beta"]);
    }

    /// Parslee-ai/car#623 — a registered policy had no way back out.
    #[test]
    fn unregister_removes_the_policy_and_stops_enforcement() {
        let mut engine = PolicyEngine::new();
        engine.register("deny", Box::new(|_, _| Some("nope".to_string())), "");
        engine.register("keep", Box::new(|_, _| None), "");
        let state = StateStore::new();
        assert_eq!(engine.check(&make_action("x"), &state).len(), 1);

        assert_eq!(engine.unregister("deny"), 1);
        assert_eq!(engine.policy_names(), vec!["keep"]);
        assert!(
            engine.check(&make_action("x"), &state).is_empty(),
            "an unregistered policy must stop being enforced"
        );
    }

    #[test]
    fn unregister_reports_zero_when_nothing_matched() {
        let mut engine = PolicyEngine::new();
        engine.register("alpha", Box::new(|_, _| None), "");
        assert_eq!(engine.unregister("nosuch"), 0);
        assert_eq!(engine.policy_names(), vec!["alpha"]);
    }

    /// `register` appends without de-duplicating, so the same name can appear
    /// twice; removing only one would leave a shadowed copy still enforcing.
    #[test]
    fn unregister_removes_every_policy_sharing_the_name() {
        let mut engine = PolicyEngine::new();
        engine.register("dup", Box::new(|_, _| Some("a".to_string())), "");
        engine.register("dup", Box::new(|_, _| Some("b".to_string())), "");
        let state = StateStore::new();
        assert_eq!(engine.check(&make_action("x"), &state).len(), 2);

        assert_eq!(engine.unregister("dup"), 2);
        assert!(engine.is_empty());
        assert!(engine.check(&make_action("x"), &state).is_empty());
    }

    #[test]
    fn clear_drops_everything() {
        let mut engine = PolicyEngine::new();
        engine.register("a", Box::new(|_, _| None), "");
        engine.register("b", Box::new(|_, _| None), "");
        assert_eq!(engine.clear(), 2);
        assert!(engine.is_empty());
    }

    /// The engine is built by the REAL producer — `PolicyRules::apply` — not by
    /// hand-registering a `deny_tool:` name here. A fixture that spells the
    /// name itself agrees with any spelling `apply` happens to use, including a
    /// wrong one.
    fn engine_from_toml(src: &str) -> PolicyEngine {
        let mut engine = PolicyEngine::new();
        PolicyRules::from_toml(src)
            .expect("fixture policy must parse")
            .apply(&mut engine);
        engine
    }

    #[test]
    fn blanket_denied_tools_reads_back_what_apply_registered() {
        let engine = engine_from_toml("deny_tool = [\"shell\", \"deploy\"]\n");
        let denied = engine.blanket_denied_tools();
        assert!(denied.contains("shell"), "got {denied:?}");
        assert!(denied.contains("deploy"), "got {denied:?}");
        // Positive control: the set is not simply "everything".
        assert!(!denied.contains("read_file"), "got {denied:?}");
        assert_eq!(denied.len(), 2, "got {denied:?}");
    }

    #[test]
    fn blanket_denied_tools_excludes_argument_dependent_rules() {
        // Every rule kind that turns on the ARGUMENTS of a specific call. None
        // of them forbids the tool, so none may hide it from a model.
        let engine = engine_from_toml(
            "deny_keyword = [\"rm -rf /\"]\n\n\
             [[deny_tool_param]]\n\
             tool = \"shell\"\n\
             param = \"command\"\n\
             contains = \"sudo\"\n\n\
             [[allow_tool_param]]\n\
             tool = \"deploy\"\n\
             param = \"env\"\n\
             allow = [\"staging\"]\n",
        );
        assert!(
            engine.blanket_denied_tools().is_empty(),
            "argument-dependent rules must not hide their tool: {:?}",
            engine.blanket_denied_tools()
        );

        // Positive control: those rules really did load and really do deny, so
        // the emptiness above is about the RULE KIND and not about a fixture
        // that quietly failed to register anything.
        let state = StateStore::new();
        let mut sudo = make_action("shell");
        sudo.parameters.insert(
            "command".to_string(),
            Value::String("sudo reboot".to_string()),
        );
        assert!(
            !engine.check(&sudo, &state).is_empty(),
            "deny_tool_param must still refuse the offending call"
        );

        // And the NARROWNESS control, which is the whole reason these tools
        // stay advertised: the allowlisted call is genuinely permitted, so
        // hiding `deploy` would withdraw a capability that works.
        //
        // `AllowToolParam`'s field is `allow`. An earlier draft of this fixture
        // spelled it `values`; nothing in this crate sets `deny_unknown_fields`,
        // so serde discarded it, `allow` defaulted to empty, and the rule became
        // "deny every call to deploy" — a TOTAL prohibition, in the test
        // asserting no total prohibition is present. It still passed, because
        // the assertion above only reads rule kinds. Keep both controls.
        let mut staging = make_action("deploy");
        staging
            .parameters
            .insert("env".to_string(), Value::String("staging".to_string()));
        assert!(
            engine.check(&staging, &state).is_empty(),
            "the allowlisted value must be permitted"
        );
        let mut prod = make_action("deploy");
        prod.parameters
            .insert("env".to_string(), Value::String("prod".to_string()));
        assert!(
            !engine.check(&prod, &state).is_empty(),
            "a value outside the allowlist must be refused"
        );
    }

    #[test]
    fn blanket_denied_tools_follows_unregister() {
        // The set is derived, never cached, so lifting a rule must lift the
        // concealment with it — otherwise a tool stays hidden from the model
        // that the engine no longer blocks.
        let mut engine = engine_from_toml("deny_tool = [\"shell\"]\n");
        assert!(engine.blanket_denied_tools().contains("shell"));

        // Take the name from the producer rather than spelling it here — a
        // hand-written name agrees with whatever `apply` happens to use,
        // including a wrong one.
        let name = engine
            .policy_names()
            .into_iter()
            .find(|n| n.contains("shell"))
            .expect("apply must register a named check for the denied tool");
        assert_eq!(engine.unregister(&name), 1);
        assert!(engine.blanket_denied_tools().is_empty());

        // Positive control: the action is genuinely allowed again.
        let state = StateStore::new();
        assert!(engine.check(&make_action("shell"), &state).is_empty());
    }

    /// The daemon registers a `deny_tool` rule under a name the CLIENT chose
    /// (`policy.register {name: "no_shell", rule: "deny_tool", ...}`), and the
    /// cookbook teaches that call. An earlier draft recovered the denied tool
    /// by parsing a `deny_tool:` name prefix, so this identical rule was
    /// invisible — one rule kind, two behaviours depending on how it was
    /// registered. Recording the tool structurally is what makes the name
    /// irrelevant.
    #[test]
    fn a_tool_deny_is_found_under_any_policy_name() {
        let mut engine = PolicyEngine::new();
        engine.register_tool_deny(
            "no_shell",
            "shell",
            Box::new(|action, _| {
                (action.tool.as_deref() == Some("shell")).then(|| "tool 'shell' denied".to_string())
            }),
            "",
        );
        assert!(engine.blanket_denied_tools().contains("shell"));

        // The converse: a check registered through the ORDINARY door under a
        // name that merely looks like one must NOT hide a tool. Under the
        // prefix scheme this spoofed a blanket deny, concealing a tool the
        // engine only conditionally blocks.
        let mut spoof = PolicyEngine::new();
        spoof.register("deny_tool:shell", Box::new(|_, _| None), "");
        assert!(
            spoof.blanket_denied_tools().is_empty(),
            "a name is not a declaration"
        );
    }

    /// The exact typo that bit this file's own fixture: `values` instead of
    /// `allow`. Serde used to discard it, `allow` defaulted to empty, and an
    /// empty allowlist permits nothing — so a rule meant to permit `staging`
    /// silently became "deny every call to deploy". A policy file is a security
    /// control; a misspelling in one must fail loudly, the way an unparseable
    /// file already does.
    #[test]
    fn a_misspelled_policy_field_is_refused_not_reinterpreted() {
        let err = PolicyRules::from_toml(
            "[[allow_tool_param]]\n\
             tool = \"deploy\"\n\
             param = \"env\"\n\
             values = [\"staging\"]\n",
        )
        .expect_err("an unknown field must be an error");
        let msg = err.to_string();
        assert!(
            msg.contains("values"),
            "the error must name the field: {msg}"
        );

        // Positive control: the correctly-spelled rule still parses, so the
        // rejection is about the unknown field and not about the shape.
        PolicyRules::from_toml(
            "[[allow_tool_param]]\n\
             tool = \"deploy\"\n\
             param = \"env\"\n\
             allow = [\"staging\"]\n",
        )
        .expect("the correct spelling must still parse");
    }

    #[test]
    fn policy_details_carries_descriptions() {
        let mut engine = PolicyEngine::new();
        engine.register("alpha", Box::new(|_, _| None), "first one");
        assert_eq!(
            engine.policy_details(),
            vec![("alpha".to_string(), "first one".to_string())]
        );
    }
}