@wlfi-agent/cli 1.4.13 → 1.4.14

package/crates/vault-domain/src/address.rs

@@ -0,0 +1,51 @@
+use std::fmt::{Display, Formatter};
+use std::str::FromStr;
+
+use serde::{Deserialize, Deserializer, Serialize};
+
+use crate::DomainError;
+
+/// Canonical lower-case EVM address (`0x` + 40 hex chars).
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
+pub struct EvmAddress(String);
+
+impl EvmAddress {
+    /// Returns the normalized address string.
+    #[must_use]
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl Display for EvmAddress {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl FromStr for EvmAddress {
+    type Err = DomainError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let normalized = s.to_ascii_lowercase();
+        let payload = normalized
+            .strip_prefix("0x")
+            .ok_or(DomainError::InvalidAddress)?;
+
+        if payload.len() != 40 || !payload.chars().all(|c| c.is_ascii_hexdigit()) {
+            return Err(DomainError::InvalidAddress);
+        }
+
+        Ok(Self(normalized))
+    }
+}
+
+impl<'de> Deserialize<'de> for EvmAddress {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let value = String::deserialize(deserializer)?;
+        Self::from_str(&value).map_err(serde::de::Error::custom)
+    }
+}

package/crates/vault-domain/src/approval.rs

@@ -0,0 +1,90 @@
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use time::OffsetDateTime;
+use uuid::Uuid;
+
+use crate::{AgentAction, AssetId, DomainError, EvmAddress};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ManualApprovalDecision {
+    Approve,
+    Reject,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ManualApprovalStatus {
+    Pending,
+    Approved,
+    Rejected,
+    Completed,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ManualApprovalRequest {
+    pub id: Uuid,
+    pub agent_key_id: Uuid,
+    pub vault_key_id: Uuid,
+    pub request_payload_hash_hex: String,
+    pub action: AgentAction,
+    pub chain_id: u64,
+    pub asset: AssetId,
+    pub recipient: EvmAddress,
+    #[serde(with = "crate::u128_as_decimal_string")]
+    pub amount_wei: u128,
+    pub created_at: OffsetDateTime,
+    pub updated_at: OffsetDateTime,
+    pub status: ManualApprovalStatus,
+    pub triggered_by_policy_ids: Vec<Uuid>,
+    pub completed_at: Option<OffsetDateTime>,
+    pub rejection_reason: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
+pub struct RelayConfig {
+    pub relay_url: Option<String>,
+    pub frontend_url: Option<String>,
+    pub daemon_id_hex: String,
+    pub daemon_public_key_hex: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RelayFeedbackStatus {
+    pub update_id: String,
+    pub status: String,
+    pub detail: Option<String>,
+}
+
+pub fn manual_approval_capability_token(
+    relay_private_key_hex: &str,
+    approval_request_id: Uuid,
+) -> Result<String, DomainError> {
+    let normalized = relay_private_key_hex.trim().trim_start_matches("0x");
+    if normalized.is_empty() {
+        return Err(DomainError::InvalidRelayCapabilitySecret);
+    }
+
+    let secret_bytes =
+        hex::decode(normalized).map_err(|_| DomainError::InvalidRelayCapabilitySecret)?;
+    if secret_bytes.len() != 32 {
+        return Err(DomainError::InvalidRelayCapabilitySecret);
+    }
+
+    let mut hasher = Sha256::new();
+    hasher.update(b"wlfi:manual-approval-capability:v1");
+    hasher.update(secret_bytes);
+    hasher.update(approval_request_id.as_bytes());
+    Ok(hex::encode(hasher.finalize()))
+}
+
+pub fn manual_approval_capability_hash(token: &str) -> Result<String, DomainError> {
+    let normalized = token.trim();
+    if normalized.is_empty() {
+        return Err(DomainError::InvalidRelayCapabilityToken);
+    }
+
+    let mut hasher = Sha256::new();
+    hasher.update(normalized.as_bytes());
+    Ok(hex::encode(hasher.finalize()))
+}

package/crates/vault-domain/src/constants.rs

@@ -0,0 +1,4 @@
+/// EIP-7702 transaction type id.
+pub const EIP7702_TX_TYPE: u8 = 0x04;
+/// Default max gas spend per chain in wei (0.001 native token).
+pub const DEFAULT_MAX_GAS_SPEND_PER_CHAIN_WEI: u128 = 1_000_000_000_000_000;

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

@@ -0,0 +1,54 @@
+use thiserror::Error;
+
+/// Errors returned by domain constructors and parsers.
+#[derive(Debug, Error)]
+pub enum DomainError {
+    /// Provided address was malformed.
+    #[error("address must start with 0x and contain exactly 40 hex characters")]
+    InvalidAddress,
+    /// Spending amount was zero.
+    #[error("amount must be greater than zero")]
+    InvalidAmount,
+    /// Numeric value could not fit target type.
+    #[error("numeric value exceeds supported range")]
+    AmountOutOfRange,
+    /// Chain ID must be greater than zero.
+    #[error("chain_id must be greater than zero")]
+    InvalidChainId,
+    /// ERC-20 calldata was invalid or unsupported.
+    #[error("invalid erc20 calldata: {0}")]
+    InvalidErc20Calldata(String),
+    /// Transaction data hex was malformed.
+    #[error("invalid transaction data hex")]
+    InvalidTransactionDataHex,
+    /// Gas fields were invalid.
+    #[error("invalid gas configuration")]
+    InvalidGasConfiguration,
+    /// Delegation is not permitted for broadcast transactions.
+    #[error("delegation is not allowed for broadcast transactions")]
+    DelegationNotAllowed,
+    /// ERC-20 approve/transfer calldata must not include native value.
+    #[error("erc20 approve/transfer transactions must set value_wei to 0")]
+    Erc20CallWithNativeValue,
+    /// A policy attachment set was empty.
+    #[error("policy set cannot be empty")]
+    EmptyPolicySet,
+    /// Transaction type is unsupported for a requested operation.
+    #[error("unsupported transaction type for operation: 0x{0:02x}")]
+    UnsupportedTransactionType(u8),
+    /// Invalid ECDSA recovery parity.
+    #[error("invalid signature parity; must be 0 or 1")]
+    InvalidSignatureParity,
+    /// Authorization time window is malformed.
+    #[error("authorization window is invalid")]
+    InvalidAuthorizationWindow,
+    /// Typed-data domain or nonce field is malformed.
+    #[error("invalid typed-data domain: {0}")]
+    InvalidTypedDataDomain(String),
+    /// Relay capability secret could not derive a secure approval token.
+    #[error("invalid relay approval capability secret")]
+    InvalidRelayCapabilitySecret,
+    /// Relay capability token was missing or malformed.
+    #[error("invalid relay approval capability token")]
+    InvalidRelayCapabilityToken,
+}

package/crates/vault-domain/src/keys.rs

@@ -0,0 +1,71 @@
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+use time::OffsetDateTime;
+use uuid::Uuid;
+use zeroize::Zeroize;
+
+use crate::PolicyAttachment;
+
+/// Source of private key material.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum KeySource {
+    /// Key generated by backend.
+    Generated,
+    /// Key imported by backend.
+    Imported,
+}
+
+/// Public metadata for a vault signing key.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct VaultKey {
+    /// Stable key identifier.
+    pub id: Uuid,
+    /// How key was created.
+    pub source: KeySource,
+    /// Uncompressed SEC1 public key bytes encoded as lowercase hex.
+    pub public_key_hex: String,
+    /// Creation timestamp.
+    pub created_at: OffsetDateTime,
+}
+
+/// Agent key metadata.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AgentKey {
+    /// Stable agent key identifier.
+    pub id: Uuid,
+    /// Linked vault key identifier.
+    pub vault_key_id: Uuid,
+    /// Policy attachment.
+    pub policies: PolicyAttachment,
+    /// Creation timestamp.
+    pub created_at: OffsetDateTime,
+}
+
+/// Agent authentication material returned at provisioning time.
+///
+/// The `auth_token` is a bearer credential and must be treated like a secret:
+/// it should be stored securely and never logged.
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AgentCredentials {
+    /// Public metadata for the provisioned agent key.
+    pub agent_key: AgentKey,
+    /// Secret bearer token required for signing requests.
+    pub auth_token: String,
+}
+
+impl fmt::Debug for AgentCredentials {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("AgentCredentials")
+            .field("agent_key", &self.agent_key)
+            .field("auth_token", &"<redacted>")
+            .finish()
+    }
+}
+
+impl AgentCredentials {
+    pub fn zeroize_secrets(&mut self) {
+        self.auth_token.zeroize();
+    }
+}

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

@@ -0,0 +1,42 @@
+//! Domain model for the vault daemon, policy engine, and agent SDK.
+//!
+//! This crate is intentionally dependency-light and transport-agnostic so that
+//! all higher-level crates share a single, strongly typed model.
+
+#![forbid(unsafe_code)]
+
+mod action;
+mod address;
+mod approval;
+mod constants;
+mod error;
+mod keys;
+mod nonce;
+mod policy;
+mod request;
+mod scope;
+mod session;
+mod signature;
+mod u128_as_decimal_string;
+
+pub use action::{
+    action_from_erc20_calldata, parse_erc20_call, AgentAction, BroadcastTx, Eip3009Transfer,
+    Erc20Call, Permit2Permit,
+};
+pub use address::EvmAddress;
+pub use approval::{
+    manual_approval_capability_hash, manual_approval_capability_token, ManualApprovalDecision,
+    ManualApprovalRequest, ManualApprovalStatus, RelayConfig, RelayFeedbackStatus,
+};
+pub use constants::{DEFAULT_MAX_GAS_SPEND_PER_CHAIN_WEI, EIP7702_TX_TYPE};
+pub use error::DomainError;
+pub use keys::{AgentCredentials, AgentKey, KeySource, VaultKey};
+pub use nonce::{NonceReleaseRequest, NonceReservation, NonceReservationRequest};
+pub use policy::{AssetId, PolicyAttachment, PolicyType, SpendEvent, SpendingPolicy};
+pub use request::SignRequest;
+pub use scope::EntityScope;
+pub use session::{AdminSession, Lease};
+pub use signature::Signature;
+
+#[cfg(test)]
+mod tests;

package/crates/vault-domain/src/nonce.rs

@@ -0,0 +1,102 @@
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+use time::OffsetDateTime;
+use uuid::Uuid;
+use zeroize::Zeroize;
+
+/// Agent request for reserving a unique broadcast nonce.
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct NonceReservationRequest {
+    /// Client-generated unique request identifier for replay protection.
+    pub request_id: Uuid,
+    /// Agent key used for authorization.
+    pub agent_key_id: Uuid,
+    /// Bearer token bound to `agent_key_id`.
+    pub agent_auth_token: String,
+    /// EVM chain id for nonce scope.
+    pub chain_id: u64,
+    /// Minimum nonce the caller is willing to reserve.
+    pub min_nonce: u64,
+    /// Request timestamp.
+    pub requested_at: OffsetDateTime,
+    /// Request expiry timestamp.
+    pub expires_at: OffsetDateTime,
+}
+
+impl fmt::Debug for NonceReservationRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("NonceReservationRequest")
+            .field("request_id", &self.request_id)
+            .field("agent_key_id", &self.agent_key_id)
+            .field("agent_auth_token", &"<redacted>")
+            .field("chain_id", &self.chain_id)
+            .field("min_nonce", &self.min_nonce)
+            .field("requested_at", &self.requested_at)
+            .field("expires_at", &self.expires_at)
+            .finish()
+    }
+}
+
+impl NonceReservationRequest {
+    pub fn zeroize_secrets(&mut self) {
+        self.agent_auth_token.zeroize();
+    }
+}
+
+/// Reserved nonce lease for a specific agent and chain.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct NonceReservation {
+    /// Unique reservation identifier.
+    pub reservation_id: Uuid,
+    /// Agent key that owns this reservation.
+    pub agent_key_id: Uuid,
+    /// Backing vault key used for signing scope.
+    pub vault_key_id: Uuid,
+    /// EVM chain id for nonce scope.
+    pub chain_id: u64,
+    /// Reserved nonce value.
+    pub nonce: u64,
+    /// Lease issuance timestamp.
+    pub issued_at: OffsetDateTime,
+    /// Lease expiry timestamp.
+    pub expires_at: OffsetDateTime,
+}
+
+/// Agent request for explicitly releasing a nonce reservation.
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct NonceReleaseRequest {
+    /// Client-generated unique request identifier for replay protection.
+    pub request_id: Uuid,
+    /// Agent key used for authorization.
+    pub agent_key_id: Uuid,
+    /// Bearer token bound to `agent_key_id`.
+    pub agent_auth_token: String,
+    /// Reservation id to release.
+    pub reservation_id: Uuid,
+    /// Request timestamp.
+    pub requested_at: OffsetDateTime,
+    /// Request expiry timestamp.
+    pub expires_at: OffsetDateTime,
+}
+
+impl fmt::Debug for NonceReleaseRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("NonceReleaseRequest")
+            .field("request_id", &self.request_id)
+            .field("agent_key_id", &self.agent_key_id)
+            .field("agent_auth_token", &"<redacted>")
+            .field("reservation_id", &self.reservation_id)
+            .field("requested_at", &self.requested_at)
+            .field("expires_at", &self.expires_at)
+            .finish()
+    }
+}
+
+impl NonceReleaseRequest {
+    pub fn zeroize_secrets(&mut self) {
+        self.agent_auth_token.zeroize();
+    }
+}

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

@@ -0,0 +1,172 @@
+use std::collections::BTreeSet;
+use std::fmt::{Display, Formatter};
+
+use serde::{Deserialize, Serialize};
+use time::OffsetDateTime;
+use uuid::Uuid;
+
+use crate::u128_as_decimal_string;
+use crate::{DomainError, EntityScope, EvmAddress};
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+#[serde(tag = "kind", content = "value", rename_all = "snake_case")]
+pub enum AssetId {
+    NativeEth,
+    Erc20(EvmAddress),
+}
+
+impl Display for AssetId {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::NativeEth => f.write_str("native_eth"),
+            Self::Erc20(token) => write!(f, "erc20:{token}"),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PolicyType {
+    DailyMaxSpending,
+    DailyMaxTxCount,
+    WeeklyMaxSpending,
+    PerTxMaxSpending,
+    PerTxMaxFeePerGas,
+    PerTxMaxPriorityFeePerGas,
+    PerTxMaxCalldataBytes,
+    PerChainMaxGasSpend,
+    ManualApproval,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SpendingPolicy {
+    pub id: Uuid,
+    pub priority: u32,
+    pub policy_type: PolicyType,
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        with = "crate::u128_as_decimal_string::option"
+    )]
+    pub min_amount_wei: Option<u128>,
+    #[serde(with = "u128_as_decimal_string")]
+    pub max_amount_wei: u128,
+    pub recipients: EntityScope<EvmAddress>,
+    pub assets: EntityScope<AssetId>,
+    pub networks: EntityScope<u64>,
+    pub enabled: bool,
+}
+
+impl SpendingPolicy {
+    pub fn new(
+        priority: u32,
+        policy_type: PolicyType,
+        max_amount_wei: u128,
+        recipients: EntityScope<EvmAddress>,
+        assets: EntityScope<AssetId>,
+        networks: EntityScope<u64>,
+    ) -> Result<Self, DomainError> {
+        Self::new_with_range(
+            priority,
+            policy_type,
+            None,
+            max_amount_wei,
+            recipients,
+            assets,
+            networks,
+        )
+    }
+
+    pub fn new_manual_approval(
+        priority: u32,
+        min_amount_wei: u128,
+        max_amount_wei: u128,
+        recipients: EntityScope<EvmAddress>,
+        assets: EntityScope<AssetId>,
+        networks: EntityScope<u64>,
+    ) -> Result<Self, DomainError> {
+        Self::new_with_range(
+            priority,
+            PolicyType::ManualApproval,
+            Some(min_amount_wei),
+            max_amount_wei,
+            recipients,
+            assets,
+            networks,
+        )
+    }
+
+    pub fn new_with_range(
+        priority: u32,
+        policy_type: PolicyType,
+        min_amount_wei: Option<u128>,
+        max_amount_wei: u128,
+        recipients: EntityScope<EvmAddress>,
+        assets: EntityScope<AssetId>,
+        networks: EntityScope<u64>,
+    ) -> Result<Self, DomainError> {
+        if max_amount_wei == 0 {
+            return Err(DomainError::InvalidAmount);
+        }
+        if matches!(min_amount_wei, Some(0)) {
+            return Err(DomainError::InvalidAmount);
+        }
+        if let Some(min_amount_wei) = min_amount_wei {
+            if min_amount_wei > max_amount_wei {
+                return Err(DomainError::InvalidAmount);
+            }
+        }
+
+        if let EntityScope::Set(values) = &networks {
+            if values.is_empty() || values.contains(&0) {
+                return Err(DomainError::InvalidChainId);
+            }
+        }
+
+        Ok(Self {
+            id: Uuid::new_v4(),
+            priority,
+            policy_type,
+            min_amount_wei,
+            max_amount_wei,
+            recipients,
+            assets,
+            networks,
+            enabled: true,
+        })
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PolicyAttachment {
+    AllPolicies,
+    PolicySet(BTreeSet<Uuid>),
+}
+
+impl PolicyAttachment {
+    pub fn policy_set(policies: BTreeSet<Uuid>) -> Result<Self, DomainError> {
+        if policies.is_empty() {
+            return Err(DomainError::EmptyPolicySet);
+        }
+
+        Ok(Self::PolicySet(policies))
+    }
+
+    #[must_use]
+    pub fn applies_to(&self, policy_id: Uuid) -> bool {
+        match self {
+            Self::AllPolicies => true,
+            Self::PolicySet(ids) => ids.contains(&policy_id),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SpendEvent {
+    pub agent_key_id: Uuid,
+    pub chain_id: u64,
+    pub asset: AssetId,
+    pub recipient: EvmAddress,
+    #[serde(with = "u128_as_decimal_string")]
+    pub amount_wei: u128,
+    pub at: OffsetDateTime,
+}

package/crates/vault-domain/src/request.rs

@@ -0,0 +1,53 @@
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+use time::OffsetDateTime;
+use uuid::Uuid;
+use zeroize::Zeroize;
+
+use crate::AgentAction;
+
+/// Request sent by an agent to receive signature approval.
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SignRequest {
+    /// Client-generated unique request identifier for replay protection.
+    pub request_id: Uuid,
+    /// Agent key used for authorization.
+    pub agent_key_id: Uuid,
+    /// Bearer token bound to `agent_key_id`.
+    pub agent_auth_token: String,
+    /// Payload to sign.
+    ///
+    /// Security contract: payload must be the canonical
+    /// `serde_json::to_vec(&action)` encoding of [`AgentAction`]; daemon rejects
+    /// semantic or byte-level mismatches.
+    pub payload: Vec<u8>,
+    /// Semantic action details used by policy checks.
+    pub action: AgentAction,
+    /// Request timestamp.
+    pub requested_at: OffsetDateTime,
+    /// Request expiry timestamp.
+    pub expires_at: OffsetDateTime,
+}
+
+impl fmt::Debug for SignRequest {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("SignRequest")
+            .field("request_id", &self.request_id)
+            .field("agent_key_id", &self.agent_key_id)
+            .field("agent_auth_token", &"<redacted>")
+            .field("payload", &self.payload)
+            .field("action", &self.action)
+            .field("requested_at", &self.requested_at)
+            .field("expires_at", &self.expires_at)
+            .finish()
+    }
+}
+
+impl SignRequest {
+    pub fn zeroize_secrets(&mut self) {
+        self.agent_auth_token.zeroize();
+        self.payload.zeroize();
+    }
+}

package/crates/vault-domain/src/scope.rs

@@ -0,0 +1,24 @@
+use std::collections::BTreeSet;
+
+use serde::{Deserialize, Serialize};
+
+/// Scope matcher for recipients, assets, and networks.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "mode", content = "values")]
+pub enum EntityScope<T: Ord> {
+    /// Match all values.
+    All,
+    /// Match a specific set of values.
+    Set(BTreeSet<T>),
+}
+
+impl<T: Ord> EntityScope<T> {
+    /// Returns whether `value` is allowed by this scope.
+    #[must_use]
+    pub fn allows(&self, value: &T) -> bool {
+        match self {
+            Self::All => true,
+            Self::Set(set) => set.contains(value),
+        }
+    }
+}