@wlfi-agent/cli 1.4.13 → 1.4.15

package/crates/vault-policy/src/engine.rs

@@ -0,0 +1,301 @@
+use time::{Duration, OffsetDateTime};
+use uuid::Uuid;
+use vault_domain::{AgentAction, PolicyAttachment, PolicyType, SpendEvent, SpendingPolicy};
+
+use crate::{PolicyDecision, PolicyError, PolicyEvaluation, PolicyExplanation};
+
+/// Stateless policy evaluator.
+#[derive(Debug, Default)]
+pub struct PolicyEngine;
+
+impl PolicyEngine {
+    /// Evaluates all applicable policies.
+    ///
+    /// A request is approved only if every applicable policy passes.
+    pub fn evaluate(
+        &self,
+        policies: &[SpendingPolicy],
+        attachment: &PolicyAttachment,
+        action: &AgentAction,
+        spend_history: &[SpendEvent],
+        agent_key_id: Uuid,
+        now: OffsetDateTime,
+    ) -> Result<PolicyEvaluation, PolicyError> {
+        let explanation = self.explain(
+            policies,
+            attachment,
+            action,
+            spend_history,
+            agent_key_id,
+            now,
+        );
+        match explanation.decision {
+            PolicyDecision::Allow => Ok(PolicyEvaluation {
+                evaluated_policy_ids: explanation.evaluated_policy_ids,
+            }),
+            PolicyDecision::Deny(err) => Err(err),
+        }
+    }
+
+    /// Builds a detailed explanation for policy evaluation.
+    #[must_use]
+    pub fn explain(
+        &self,
+        policies: &[SpendingPolicy],
+        attachment: &PolicyAttachment,
+        action: &AgentAction,
+        spend_history: &[SpendEvent],
+        agent_key_id: Uuid,
+        now: OffsetDateTime,
+    ) -> PolicyExplanation {
+        let mut attached: Vec<&SpendingPolicy> = policies
+            .iter()
+            .filter(|p| p.enabled && attachment.applies_to(p.id))
+            .collect();
+        attached.sort_by(|a, b| a.priority.cmp(&b.priority).then_with(|| a.id.cmp(&b.id)));
+        let attached_policy_ids = attached.iter().map(|p| p.id).collect::<Vec<_>>();
+        if attached.is_empty() {
+            return PolicyExplanation {
+                attached_policy_ids,
+                applicable_policy_ids: Vec::new(),
+                evaluated_policy_ids: Vec::new(),
+                decision: PolicyDecision::Deny(PolicyError::NoAttachedPolicies),
+            };
+        }
+
+        let action_asset = action.asset();
+        let action_recipient = action.recipient();
+        let action_chain_id = action.chain_id();
+
+        let applicable: Vec<&SpendingPolicy> = attached
+            .into_iter()
+            .filter(|p| {
+                p.assets.allows(&action_asset)
+                    && p.recipients.allows(&action_recipient)
+                    && p.networks.allows(&action_chain_id)
+            })
+            .collect();
+        let applicable_policy_ids = applicable.iter().map(|p| p.id).collect::<Vec<_>>();
+        if applicable.is_empty() {
+            return PolicyExplanation {
+                attached_policy_ids,
+                applicable_policy_ids,
+                evaluated_policy_ids: Vec::new(),
+                decision: PolicyDecision::Deny(PolicyError::NoApplicablePolicies),
+            };
+        }
+
+        let mut evaluated_policy_ids = Vec::with_capacity(applicable.len());
+        for policy in applicable {
+            evaluated_policy_ids.push(policy.id);
+            if let Err(err) =
+                self.evaluate_single_policy(policy, action, spend_history, agent_key_id, now)
+            {
+                return PolicyExplanation {
+                    attached_policy_ids,
+                    applicable_policy_ids,
+                    evaluated_policy_ids,
+                    decision: PolicyDecision::Deny(err),
+                };
+            }
+        }
+
+        PolicyExplanation {
+            attached_policy_ids,
+            applicable_policy_ids,
+            evaluated_policy_ids,
+            decision: PolicyDecision::Allow,
+        }
+    }
+
+    fn evaluate_single_policy(
+        &self,
+        policy: &SpendingPolicy,
+        action: &AgentAction,
+        spend_history: &[SpendEvent],
+        agent_key_id: Uuid,
+        now: OffsetDateTime,
+    ) -> Result<(), PolicyError> {
+        let requested_amount_wei = action.amount_wei();
+
+        match policy.policy_type {
+            PolicyType::PerTxMaxSpending => {
+                if requested_amount_wei > policy.max_amount_wei {
+                    return Err(PolicyError::PerTxLimitExceeded {
+                        policy_id: policy.id,
+                        max_amount_wei: policy.max_amount_wei,
+                        requested_amount_wei,
+                    });
+                }
+            }
+            PolicyType::PerTxMaxFeePerGas => {
+                if let Some(requested_max_fee_per_gas_wei) = action.max_fee_per_gas_wei() {
+                    if requested_max_fee_per_gas_wei > policy.max_amount_wei {
+                        return Err(PolicyError::MaxFeePerGasLimitExceeded {
+                            policy_id: policy.id,
+                            max_fee_per_gas_wei: policy.max_amount_wei,
+                            requested_max_fee_per_gas_wei,
+                        });
+                    }
+                }
+            }
+            PolicyType::PerTxMaxPriorityFeePerGas => {
+                if let Some(requested_max_priority_fee_per_gas_wei) =
+                    action.max_priority_fee_per_gas_wei()
+                {
+                    if requested_max_priority_fee_per_gas_wei > policy.max_amount_wei {
+                        return Err(PolicyError::PriorityFeePerGasLimitExceeded {
+                            policy_id: policy.id,
+                            max_priority_fee_per_gas_wei: policy.max_amount_wei,
+                            requested_max_priority_fee_per_gas_wei,
+                        });
+                    }
+                }
+            }
+            PolicyType::PerTxMaxCalldataBytes => {
+                if let Some(requested_calldata_bytes) = action.calldata_len_bytes() {
+                    let requested_calldata_bytes = requested_calldata_bytes as u128;
+                    if requested_calldata_bytes > policy.max_amount_wei {
+                        return Err(PolicyError::CalldataBytesLimitExceeded {
+                            policy_id: policy.id,
+                            max_calldata_bytes: policy.max_amount_wei,
+                            requested_calldata_bytes,
+                        });
+                    }
+                }
+            }
+            PolicyType::DailyMaxSpending => self.enforce_window_limit(
+                policy,
+                spend_history,
+                agent_key_id,
+                now - Duration::days(1),
+                requested_amount_wei,
+            )?,
+            PolicyType::DailyMaxTxCount => {
+                self.enforce_tx_count_window(
+                    policy,
+                    spend_history,
+                    agent_key_id,
+                    now - Duration::days(1),
+                )?;
+            }
+            PolicyType::WeeklyMaxSpending => self.enforce_window_limit(
+                policy,
+                spend_history,
+                agent_key_id,
+                now - Duration::weeks(1),
+                requested_amount_wei,
+            )?,
+            PolicyType::PerChainMaxGasSpend => {
+                if let Some(requested_gas_wei) = action.max_gas_spend_wei() {
+                    if requested_gas_wei > policy.max_amount_wei {
+                        return Err(PolicyError::GasLimitExceeded {
+                            policy_id: policy.id,
+                            max_gas_wei: policy.max_amount_wei,
+                            requested_gas_wei,
+                        });
+                    }
+                }
+            }
+            PolicyType::ManualApproval => {
+                let min_amount_wei = policy.min_amount_wei.unwrap_or(1);
+                if requested_amount_wei >= min_amount_wei
+                    && requested_amount_wei <= policy.max_amount_wei
+                {
+                    return Err(PolicyError::ManualApprovalRequired {
+                        policy_id: policy.id,
+                        min_amount_wei: policy.min_amount_wei,
+                        max_amount_wei: policy.max_amount_wei,
+                        requested_amount_wei,
+                    });
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    fn enforce_tx_count_window(
+        &self,
+        policy: &SpendingPolicy,
+        spend_history: &[SpendEvent],
+        agent_key_id: Uuid,
+        window_start: OffsetDateTime,
+    ) -> Result<(), PolicyError> {
+        let mut used_tx_count = 0u128;
+        for _event in spend_history.iter().filter(|event| {
+            event.agent_key_id == agent_key_id
+                && event.at >= window_start
+                && policy.assets.allows(&event.asset)
+                && policy.recipients.allows(&event.recipient)
+                && policy.networks.allows(&event.chain_id)
+        }) {
+            match used_tx_count.checked_add(1) {
+                Some(next) => used_tx_count = next,
+                None => {
+                    used_tx_count = u128::MAX;
+                    break;
+                }
+            }
+        }
+
+        let exceeds_window = used_tx_count
+            .checked_add(1)
+            .is_none_or(|total| total > policy.max_amount_wei);
+        if exceeds_window {
+            return Err(PolicyError::TxCountLimitExceeded {
+                policy_id: policy.id,
+                used_tx_count,
+                max_tx_count: policy.max_amount_wei,
+            });
+        }
+
+        Ok(())
+    }
+
+    fn enforce_window_limit(
+        &self,
+        policy: &SpendingPolicy,
+        spend_history: &[SpendEvent],
+        agent_key_id: Uuid,
+        window_start: OffsetDateTime,
+        requested_amount_wei: u128,
+    ) -> Result<(), PolicyError> {
+        let mut used_amount_wei = 0u128;
+        let mut overflowed = false;
+        for event in spend_history.iter().filter(|event| {
+            event.agent_key_id == agent_key_id
+                && event.at >= window_start
+                && policy.assets.allows(&event.asset)
+                && policy.recipients.allows(&event.recipient)
+                && policy.networks.allows(&event.chain_id)
+        }) {
+            match used_amount_wei.checked_add(event.amount_wei) {
+                Some(next) => used_amount_wei = next,
+                None => {
+                    // Overflow indicates history already exceeded representable
+                    // accounting bounds. Reject instead of undercounting.
+                    overflowed = true;
+                    used_amount_wei = u128::MAX;
+                    break;
+                }
+            }
+        }
+
+        let exceeds_window = overflowed
+            || used_amount_wei
+                .checked_add(requested_amount_wei)
+                .is_none_or(|total| total > policy.max_amount_wei);
+
+        if exceeds_window {
+            return Err(PolicyError::WindowLimitExceeded {
+                policy_id: policy.id,
+                used_amount_wei,
+                requested_amount_wei,
+                max_amount_wei: policy.max_amount_wei,
+            });
+        }
+
+        Ok(())
+    }
+}

package/crates/vault-policy/src/error.rs

@@ -0,0 +1,81 @@
+use serde::{Deserialize, Serialize};
+use thiserror::Error;
+use uuid::Uuid;
+
+#[derive(Debug, Error, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PolicyError {
+    #[error("no enabled policies attached to this agent key")]
+    NoAttachedPolicies,
+    #[error("no policy scope allows recipient/asset/network for this action")]
+    NoApplicablePolicies,
+    #[error(
+        "policy {policy_id} rejected request: per transaction max {max_amount_wei} < requested {requested_amount_wei}"
+    )]
+    PerTxLimitExceeded {
+        policy_id: Uuid,
+        max_amount_wei: u128,
+        requested_amount_wei: u128,
+    },
+    #[error(
+        "policy {policy_id} rejected request: window usage {used_amount_wei} + requested {requested_amount_wei} > max {max_amount_wei}"
+    )]
+    WindowLimitExceeded {
+        policy_id: Uuid,
+        used_amount_wei: u128,
+        requested_amount_wei: u128,
+        max_amount_wei: u128,
+    },
+    #[error(
+        "policy {policy_id} rejected request: gas max {max_gas_wei} < requested {requested_gas_wei}"
+    )]
+    GasLimitExceeded {
+        policy_id: Uuid,
+        max_gas_wei: u128,
+        requested_gas_wei: u128,
+    },
+    #[error(
+        "policy {policy_id} rejected request: max_fee_per_gas_wei {max_fee_per_gas_wei} < requested {requested_max_fee_per_gas_wei}"
+    )]
+    MaxFeePerGasLimitExceeded {
+        policy_id: Uuid,
+        max_fee_per_gas_wei: u128,
+        requested_max_fee_per_gas_wei: u128,
+    },
+    #[error(
+        "policy {policy_id} rejected request: max_priority_fee_per_gas_wei {max_priority_fee_per_gas_wei} < requested {requested_max_priority_fee_per_gas_wei}"
+    )]
+    PriorityFeePerGasLimitExceeded {
+        policy_id: Uuid,
+        max_priority_fee_per_gas_wei: u128,
+        requested_max_priority_fee_per_gas_wei: u128,
+    },
+    #[error(
+        "policy {policy_id} rejected request: calldata max bytes {max_calldata_bytes} < requested {requested_calldata_bytes}"
+    )]
+    CalldataBytesLimitExceeded {
+        policy_id: Uuid,
+        max_calldata_bytes: u128,
+        requested_calldata_bytes: u128,
+    },
+    #[error(
+        "policy {policy_id} rejected request: tx_count usage {used_tx_count} + 1 > max {max_tx_count}"
+    )]
+    TxCountLimitExceeded {
+        policy_id: Uuid,
+        used_tx_count: u128,
+        max_tx_count: u128,
+    },
+    #[error(
+        "policy {policy_id} rejected request: missing required transaction metadata ({metadata})"
+    )]
+    MissingTransactionMetadata { policy_id: Uuid, metadata: String },
+    #[error(
+        "policy {policy_id} requires manual approval for requested amount {requested_amount_wei} within range {min_amount_wei:?}..={max_amount_wei}"
+    )]
+    ManualApprovalRequired {
+        policy_id: Uuid,
+        min_amount_wei: Option<u128>,
+        max_amount_wei: u128,
+        requested_amount_wei: u128,
+    },
+}

package/crates/vault-policy/src/lib.rs

@@ -0,0 +1,17 @@
+//! Policy evaluation engine for agent signing requests.
+
+#![forbid(unsafe_code)]
+
+mod engine;
+mod error;
+mod report;
+
+pub use engine::PolicyEngine;
+pub use error::PolicyError;
+pub use report::{PolicyDecision, PolicyEvaluation, PolicyExplanation};
+
+#[cfg(test)]
+mod tests;
+
+#[cfg(test)]
+mod tests_explain;

package/crates/vault-policy/src/report.rs

@@ -0,0 +1,34 @@
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use crate::PolicyError;
+
+/// Successful policy evaluation details.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PolicyEvaluation {
+    /// Policies evaluated (priority order, low to high numeric priority).
+    pub evaluated_policy_ids: Vec<Uuid>,
+}
+
+/// Policy decision for an explanation report.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "decision", content = "reason", rename_all = "snake_case")]
+pub enum PolicyDecision {
+    /// Request satisfies all applicable policies.
+    Allow,
+    /// Request was denied by policy engine.
+    Deny(PolicyError),
+}
+
+/// Full policy explanation report.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct PolicyExplanation {
+    /// Enabled policy ids attached to the agent (priority order).
+    pub attached_policy_ids: Vec<Uuid>,
+    /// Attached policy ids whose recipient/asset/network scope matched the action.
+    pub applicable_policy_ids: Vec<Uuid>,
+    /// Policy ids evaluated in order up to decision point.
+    pub evaluated_policy_ids: Vec<Uuid>,
+    /// Final allow/deny decision.
+    pub decision: PolicyDecision,
+}