lex_runtime/

policy.rs

//! Capability/policy layer per spec §7.4.
//!
//! Operators specify what effects are allowed before any execution starts.
//! The runtime walks the program's declared effects and aborts with a
//! structured violation if the program would exceed the policy. During
//! execution, individual effect calls are also gated through the same
//! policy so that scoped effects (fs paths, budget consumption) are caught
//! at call time.

use indexmap::IndexMap;
use lex_bytecode::program::{DeclaredEffect, EffectArg, Program};
use serde::{Deserialize, Serialize};
use std::collections::BTreeSet;
use std::path::{Path, PathBuf};

/// Policy a program is run under. Empty `allow_effects` = pure-only
/// execution.
///
/// **Wildcard scopes (read before embedding):** the scope lists
/// (`allow_fs_read`, `allow_fs_write`, `allow_net_host`, `allow_proc`)
/// follow an **empty = allow ANY** convention, *not* empty = deny.
/// Granting a scoped effect in `allow_effects` while leaving its scope
/// list empty therefore opens the *unrestricted* form (any path / host
/// / binary). That's intentional for trusted local use (`lex run`),
/// but it's a footgun for embedders that build a `Policy` from
/// untrusted input. Such embedders should populate the scope list for
/// every kind they grant, or call [`Policy::wildcard_scoped_grants`]
/// to detect the wide-open ones and refuse them. (#552)
#[derive(Debug, Clone, Default)]
pub struct Policy {
    pub allow_effects: BTreeSet<String>,
    /// Path scope for the `[fs_read]` effect. **Empty = any path**
    /// (wildcard), not deny — see the type-level note above (#552).
    pub allow_fs_read: Vec<PathBuf>,
    /// Path scope for the `[fs_write]` effect. **Empty = any path**
    /// (wildcard), not deny — see the type-level note above (#552).
    pub allow_fs_write: Vec<PathBuf>,
    /// Per-host scope on the [net] effect. Empty = any host (when
    /// [net] is in `allow_effects`); non-empty = only requests to
    /// these hosts succeed. Hosts compare against the URL's host
    /// substring (port-agnostic). Lets a tool be granted [net] but
    /// scoped to e.g. `api.openai.com` only — without this, [net]
    /// is a blank check to exfiltrate anywhere.
    pub allow_net_host: Vec<String>,
    /// Per-binary scope on the [proc] effect. Empty = ANY binary
    /// allowed once [proc] is granted (treat as a global escape
    /// hatch; only acceptable for trusted code). Non-empty =
    /// `proc.spawn(cmd, args)` must match `cmd` against the
    /// basename portion of one of these entries. Per-arg validation
    /// is the *caller's* responsibility — see SECURITY.md's
    /// "argument injection" note.
    pub allow_proc: Vec<String>,
    pub budget: Option<u64>,
}

impl Policy {
    pub fn pure() -> Self { Self::default() }

    /// Report the granted *scoped* effects whose scope list is empty —
    /// i.e. the ones the runtime treats as unrestricted ("any"):
    /// `proc` (any binary), `net` (any host), `fs_read` / `fs_write`
    /// (any path). Returns an empty vec when no granted kind is left
    /// wide open.
    ///
    /// Intended for embedders that expose execution to untrusted
    /// callers: build the effective `Policy`, then refuse to run (or
    /// loudly log) if this returns non-empty. Pure / `time` / `rand`
    /// grants never appear here — they have no scope. (#552)
    pub fn wildcard_scoped_grants(&self) -> Vec<&'static str> {
        let mut open = Vec::new();
        if self.allow_effects.contains("proc") && self.allow_proc.is_empty() {
            open.push("proc");
        }
        if self.allow_effects.contains("net") && self.allow_net_host.is_empty() {
            open.push("net");
        }
        if self.allow_effects.contains("fs_read") && self.allow_fs_read.is_empty() {
            open.push("fs_read");
        }
        if self.allow_effects.contains("fs_write") && self.allow_fs_write.is_empty() {
            open.push("fs_write");
        }
        open
    }

    pub fn permissive() -> Self {
        let mut s = BTreeSet::new();
        for k in [
            "io", "net", "time", "llm", "proc", "panic",
            "fs_read", "fs_write", "budget",
            // #184: agent-runtime effects.
            "llm_local", "llm_cloud", "a2a", "mcp",
            // #216: env-var access. Per-var scoping (`[env(NAME)]`)
            // arrives with the per-capability effect parameterization
            // work (#207); the flat `[env]` is the v1 surface.
            "env",
            // #399: keep this set in sync with every effect declared
            // in `crates/lex-types/src/builtins.rs`. The "permissive"
            // contract is "everything stdlib knows about"; missing
            // entries here cause valid stdlib calls to fail under
            // `lex test` / `lex repl` / any other consumer that opts
            // into the permissive policy.
            "sql",         // std.sql (#362, #379)
            "random",      // crypto.random / crypto.random_str_hex (#382)
            "chat",        // chat.broadcast / chat.send (#359)
            "log",         // std.log structured logging
            "kv",          // std.kv key-value store
            "stream",      // std.stream
            "fs_walk",     // std.fs directory traversal
            "concurrent",  // conc.spawn / conc.ask / conc.tell (#381)
            "crypto",      // std.crypto hashing / signing (#562, #582)
        ] {
            s.insert(k.to_string());
        }
        Self {
            allow_effects: s,
            allow_fs_read: Vec::new(),
            allow_fs_write: Vec::new(),
            allow_net_host: Vec::new(),
            allow_proc: Vec::new(),
            budget: None,
        }
    }
}

/// Structured policy violation, formatted to match spec §6.7's JSON shape.
#[derive(Debug, Clone, Serialize, Deserialize, thiserror::Error)]
#[error("policy violation: {kind} {detail}")]
pub struct PolicyViolation {
    pub kind: String,
    pub detail: String,
    /// Effect kind that was disallowed, or `null`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub effect: Option<String>,
    /// Path that fell outside the allowlist, or `null`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
    /// NodeId or function name; precise location of the offense.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub at: Option<String>,
}

impl PolicyViolation {
    pub fn effect_not_allowed(effect: &str, at: impl Into<String>) -> Self {
        Self {
            kind: "effect_not_allowed".into(),
            detail: format!("effect `{effect}` not in --allow-effects"),
            effect: Some(effect.into()),
            path: None,
            at: Some(at.into()),
        }
    }
    pub fn fs_path_not_allowed(effect: &str, path: &str, at: impl Into<String>) -> Self {
        Self {
            kind: "fs_path_not_allowed".into(),
            detail: format!("path `{path}` outside --allow-{effect}"),
            effect: Some(effect.into()),
            path: Some(path.into()),
            at: Some(at.into()),
        }
    }
    pub fn budget_exceeded(declared: u64, ceiling: u64) -> Self {
        Self {
            kind: "budget_exceeded".into(),
            detail: format!("declared budget {declared} exceeds ceiling {ceiling}"),
            effect: Some("budget".into()),
            path: None,
            at: None,
        }
    }
}

/// Walk the program's declared effects (gathered from fn signatures) and
/// verify them against `policy`. Run before any execution.
pub fn check_program(program: &Program, policy: &Policy) -> Result<PolicyReport, Vec<PolicyViolation>> {
    let mut violations = Vec::new();
    let mut total_budget: u64 = 0;
    let mut declared_effects: IndexMap<String, Vec<DeclaredEffect>> = IndexMap::new();

    for f in &program.functions {
        for e in &f.effects {
            declared_effects.entry(f.name.clone()).or_default().push(e.clone());

            // Effect-kind allowlist (#207). A grant like `mcp:ocpp`
            // permits `[mcp("ocpp")]` only; bare `mcp` permits any
            // `[mcp(...)]`. Subsumption follows the type-system rule
            // in `lex-types::EffectKind::subsumes`. The CLI wire
            // format stays plain strings for backward compat.
            if !is_effect_allowed(&policy.allow_effects, e) {
                violations.push(PolicyViolation::effect_not_allowed(
                    &declared_effect_pretty(e), &f.name));
                continue;
            }

            // Scoped fs paths.
            if e.kind == "fs_read" || e.kind == "fs_write" {
                if let Some(EffectArg::Str(path)) = &e.arg {
                    let allowlist = if e.kind == "fs_read" {
                        &policy.allow_fs_read
                    } else {
                        &policy.allow_fs_write
                    };
                    if !path_under_any(path, allowlist) {
                        violations.push(PolicyViolation::fs_path_not_allowed(&e.kind, path, &f.name));
                    }
                }
            }

            // Budget aggregation.
            if e.kind == "budget" {
                if let Some(EffectArg::Int(n)) = &e.arg {
                    if *n >= 0 { total_budget = total_budget.saturating_add(*n as u64); }
                }
            }
        }
    }

    if let Some(ceiling) = policy.budget {
        if total_budget > ceiling {
            violations.push(PolicyViolation::budget_exceeded(total_budget, ceiling));
        }
    }

    if violations.is_empty() {
        Ok(PolicyReport { declared_effects, total_budget })
    } else {
        Err(violations)
    }
}

#[derive(Debug, Clone)]
pub struct PolicyReport {
    pub declared_effects: IndexMap<String, Vec<DeclaredEffect>>,
    pub total_budget: u64,
}

fn path_under_any(p: &str, list: &[PathBuf]) -> bool {
    let candidate = Path::new(p);
    list.iter().any(|allowed| candidate.starts_with(allowed))
}

/// Render a `DeclaredEffect` for diagnostic output, matching the
/// `EffectKind::pretty` form used by the type checker (#207).
fn declared_effect_pretty(e: &DeclaredEffect) -> String {
    match &e.arg {
        None => e.kind.clone(),
        Some(EffectArg::Str(s)) => format!("{}(\"{}\")", e.kind, s),
        Some(EffectArg::Int(n)) => format!("{}({})", e.kind, n),
        Some(EffectArg::Ident(s)) => format!("{}({})", e.kind, s),
    }
}

/// Decide whether `e` is permitted by `grants` (#207).
///
/// Grant strings come from `--allow-effects` and may be either:
///   - `name`           (bare wildcard, accepts any arg)
///   - `name:arg`       (string-arg specific grant — the colon is
///     a CLI-friendly separator)
///   - `name(arg)`      (matches the canonical pretty form for
///     grants written by hand or copy-pasted from
///     error messages)
///
/// Bare absorbs specific; specific matches only an exactly-equal
/// string arg. Int/Ident args on the declaration side are accepted
/// only by their bare-name grants (no CLI form for them in v1 —
/// they're rare in practice and can be added later).
pub fn is_effect_allowed(grants: &BTreeSet<String>, e: &DeclaredEffect) -> bool {
    grants.iter().any(|g| grant_subsumes(g, e))
}

fn grant_subsumes(grant: &str, e: &DeclaredEffect) -> bool {
    // Accept three forms: "name", "name:arg", "name(arg)".
    let (g_name, g_arg) = parse_grant(grant);
    if g_name != e.kind { return false; }
    match (g_arg, &e.arg) {
        (None, _) => true,                                 // bare absorbs anything
        (Some(_), None) => false,                          // specific can't grant bare
        (Some(g), Some(EffectArg::Str(d))) => g == d,
        // Int / Ident args have no CLI form in v1; only bare grants
        // satisfy them (handled by the (None, _) branch above).
        (Some(_), Some(_)) => false,
    }
}

/// Split `"mcp:ocpp"` or `"mcp(ocpp)"` into `("mcp", Some("ocpp"))`.
/// Plain `"mcp"` returns `("mcp", None)`.
fn parse_grant(s: &str) -> (&str, Option<&str>) {
    if let Some((name, rest)) = s.split_once('(') {
        if let Some(arg) = rest.strip_suffix(')') {
            return (name, Some(arg.trim_matches('"')));
        }
    }
    if let Some((name, arg)) = s.split_once(':') {
        return (name, Some(arg));
    }
    (s, None)
}

#[cfg(test)]
mod wildcard_tests {
    use super::*;

    fn effects(kinds: &[&str]) -> BTreeSet<String> {
        kinds.iter().map(|s| s.to_string()).collect()
    }

    #[test]
    fn flags_scoped_grants_left_open() {
        let p = Policy {
            allow_effects: effects(&["proc", "fs_read", "time"]),
            ..Policy::default()
        };
        let open = p.wildcard_scoped_grants();
        assert!(open.contains(&"proc"), "empty allow_proc + [proc] is wide open");
        assert!(open.contains(&"fs_read"), "empty allow_fs_read + [fs_read] is wide open");
        // `time` has no scope and `net` wasn't granted.
        assert!(!open.contains(&"time"));
        assert!(!open.contains(&"net"));
    }

    #[test]
    fn populated_scope_is_not_flagged() {
        let p = Policy {
            allow_effects: effects(&["fs_read", "net"]),
            allow_fs_read: vec![PathBuf::from("/srv/data")],
            allow_net_host: vec!["api.example.com".into()],
            ..Policy::default()
        };
        assert!(p.wildcard_scoped_grants().is_empty());
    }

    #[test]
    fn pure_and_unscoped_effects_are_clean() {
        assert!(Policy::pure().wildcard_scoped_grants().is_empty());
        let p = Policy {
            allow_effects: effects(&["time", "random", "panic"]),
            ..Policy::default()
        };
        assert!(p.wildcard_scoped_grants().is_empty());
    }
}