@wlfi-agent/cli 1.4.12 → 1.4.14

package/crates/vault-sdk-agent/src/lib.rs

@@ -0,0 +1,711 @@
+//! Agent-side SDK for daemon-mediated token operations.
+
+#![forbid(unsafe_code)]
+
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use thiserror::Error;
+use time::{Duration, OffsetDateTime};
+use uuid::Uuid;
+use vault_daemon::{DaemonError, KeyManagerDaemonApi};
+use vault_domain::{
+    action_from_erc20_calldata, AgentAction, AgentCredentials, BroadcastTx, DomainError,
+    Eip3009Transfer, EvmAddress, NonceReleaseRequest, NonceReservation, NonceReservationRequest,
+    Permit2Permit, SignRequest, Signature,
+};
+use zeroize::Zeroizing;
+
+/// Errors returned by the agent SDK.
+#[derive(Debug, Error)]
+pub enum AgentSdkError {
+    /// Upstream daemon call failed.
+    #[error("daemon call failed: {0}")]
+    Daemon(#[from] DaemonError),
+    /// Invalid action payload.
+    #[error("invalid action: {0}")]
+    Domain(#[from] DomainError),
+    /// Failed to serialize action payload for daemon verification.
+    #[error("failed to serialize action payload: {0}")]
+    Serialization(String),
+}
+
+/// High-level agent operations.
+#[async_trait]
+pub trait AgentOperations: Send + Sync {
+    /// Requests an ERC-20 `approve` signature.
+    async fn approve(
+        &self,
+        chain_id: u64,
+        token: EvmAddress,
+        spender: EvmAddress,
+        amount_wei: u128,
+    ) -> Result<Signature, AgentSdkError>;
+
+    /// Requests an ERC-20 `transfer` signature.
+    async fn transfer(
+        &self,
+        chain_id: u64,
+        token: EvmAddress,
+        to: EvmAddress,
+        amount_wei: u128,
+    ) -> Result<Signature, AgentSdkError>;
+
+    /// Requests a native ETH transfer signature.
+    async fn transfer_native(
+        &self,
+        chain_id: u64,
+        to: EvmAddress,
+        amount_wei: u128,
+    ) -> Result<Signature, AgentSdkError>;
+
+    /// Requests a Permit2 `PermitSingle` signature.
+    async fn permit2_permit(&self, permit: Permit2Permit) -> Result<Signature, AgentSdkError>;
+
+    /// Requests an EIP-3009 `transferWithAuthorization` signature.
+    async fn eip3009_transfer_with_authorization(
+        &self,
+        authorization: Eip3009Transfer,
+    ) -> Result<Signature, AgentSdkError>;
+
+    /// Requests an EIP-3009 `receiveWithAuthorization` signature.
+    async fn eip3009_receive_with_authorization(
+        &self,
+        authorization: Eip3009Transfer,
+    ) -> Result<Signature, AgentSdkError>;
+
+    /// Parses ERC-20 calldata and signs derived action (`approve` / `transfer`).
+    async fn sign_erc20_calldata(
+        &self,
+        chain_id: u64,
+        token: EvmAddress,
+        calldata: Vec<u8>,
+    ) -> Result<Signature, AgentSdkError>;
+
+    /// Requests signature authorization for a raw broadcast transaction.
+    async fn broadcast_tx(&self, tx: BroadcastTx) -> Result<Signature, AgentSdkError>;
+
+    /// Reserves a nonce lease for a future broadcast transaction.
+    async fn reserve_broadcast_nonce(
+        &self,
+        chain_id: u64,
+        min_nonce: u64,
+    ) -> Result<NonceReservation, AgentSdkError>;
+
+    /// Explicitly releases an unused nonce reservation.
+    async fn release_broadcast_nonce(
+        &self,
+        reservation_id: uuid::Uuid,
+    ) -> Result<(), AgentSdkError>;
+}
+
+/// Default SDK implementation backed by a daemon API client.
+pub struct AgentSdk<D>
+where
+    D: KeyManagerDaemonApi + ?Sized,
+{
+    daemon: Arc<D>,
+    agent_key_id: Uuid,
+    agent_auth_token: Zeroizing<String>,
+}
+
+impl<D> AgentSdk<D>
+where
+    D: KeyManagerDaemonApi + ?Sized,
+{
+    const REQUEST_TTL: Duration = Duration::minutes(2);
+
+    /// Creates SDK bound to agent credentials.
+    #[must_use]
+    pub fn new(daemon: Arc<D>, agent_credentials: AgentCredentials) -> Self {
+        Self {
+            daemon,
+            agent_key_id: agent_credentials.agent_key.id,
+            agent_auth_token: Zeroizing::new(agent_credentials.auth_token),
+        }
+    }
+
+    /// Creates SDK from raw agent key id and auth token.
+    ///
+    /// This constructor is useful for CLIs and integrations where only the
+    /// stable key id + bearer token are persisted.
+    #[must_use]
+    pub fn new_with_key_id_and_token(
+        daemon: Arc<D>,
+        agent_key_id: Uuid,
+        agent_auth_token: String,
+    ) -> Self {
+        Self {
+            daemon,
+            agent_key_id,
+            agent_auth_token: Zeroizing::new(agent_auth_token),
+        }
+    }
+
+    async fn sign_action(&self, action: AgentAction) -> Result<Signature, AgentSdkError> {
+        action.validate()?;
+        let now = OffsetDateTime::now_utc();
+        let payload = serde_json::to_vec(&action)
+            .map_err(|err| AgentSdkError::Serialization(err.to_string()))?;
+        let request = SignRequest {
+            request_id: uuid::Uuid::new_v4(),
+            agent_key_id: self.agent_key_id,
+            agent_auth_token: self.agent_auth_token.as_str().to_owned(),
+            payload,
+            action,
+            requested_at: now,
+            expires_at: now + Self::REQUEST_TTL,
+        };
+
+        Ok(self.daemon.sign_for_agent(request).await?)
+    }
+}
+
+#[async_trait]
+impl<D> AgentOperations for AgentSdk<D>
+where
+    D: KeyManagerDaemonApi + ?Sized,
+{
+    async fn approve(
+        &self,
+        chain_id: u64,
+        token: EvmAddress,
+        spender: EvmAddress,
+        amount_wei: u128,
+    ) -> Result<Signature, AgentSdkError> {
+        self.sign_action(AgentAction::Approve {
+            chain_id,
+            token,
+            spender,
+            amount_wei,
+        })
+        .await
+    }
+
+    async fn transfer(
+        &self,
+        chain_id: u64,
+        token: EvmAddress,
+        to: EvmAddress,
+        amount_wei: u128,
+    ) -> Result<Signature, AgentSdkError> {
+        self.sign_action(AgentAction::Transfer {
+            chain_id,
+            token,
+            to,
+            amount_wei,
+        })
+        .await
+    }
+
+    async fn transfer_native(
+        &self,
+        chain_id: u64,
+        to: EvmAddress,
+        amount_wei: u128,
+    ) -> Result<Signature, AgentSdkError> {
+        self.sign_action(AgentAction::TransferNative {
+            chain_id,
+            to,
+            amount_wei,
+        })
+        .await
+    }
+
+    async fn permit2_permit(&self, permit: Permit2Permit) -> Result<Signature, AgentSdkError> {
+        self.sign_action(AgentAction::Permit2Permit { permit })
+            .await
+    }
+
+    async fn eip3009_transfer_with_authorization(
+        &self,
+        authorization: Eip3009Transfer,
+    ) -> Result<Signature, AgentSdkError> {
+        self.sign_action(AgentAction::Eip3009TransferWithAuthorization { authorization })
+            .await
+    }
+
+    async fn eip3009_receive_with_authorization(
+        &self,
+        authorization: Eip3009Transfer,
+    ) -> Result<Signature, AgentSdkError> {
+        self.sign_action(AgentAction::Eip3009ReceiveWithAuthorization { authorization })
+            .await
+    }
+
+    async fn sign_erc20_calldata(
+        &self,
+        chain_id: u64,
+        token: EvmAddress,
+        calldata: Vec<u8>,
+    ) -> Result<Signature, AgentSdkError> {
+        let action = action_from_erc20_calldata(chain_id, token, &calldata)?;
+        self.sign_action(action).await
+    }
+
+    async fn broadcast_tx(&self, mut tx: BroadcastTx) -> Result<Signature, AgentSdkError> {
+        let reservation = self.reserve_broadcast_nonce(tx.chain_id, tx.nonce).await?;
+        tx.nonce = reservation.nonce;
+
+        match self.sign_action(AgentAction::BroadcastTx { tx }).await {
+            Ok(signature) => Ok(signature),
+            Err(err) => {
+                let _ = self
+                    .release_broadcast_nonce(reservation.reservation_id)
+                    .await;
+                Err(err)
+            }
+        }
+    }
+
+    async fn reserve_broadcast_nonce(
+        &self,
+        chain_id: u64,
+        min_nonce: u64,
+    ) -> Result<NonceReservation, AgentSdkError> {
+        let now = OffsetDateTime::now_utc();
+        let request = NonceReservationRequest {
+            request_id: uuid::Uuid::new_v4(),
+            agent_key_id: self.agent_key_id,
+            agent_auth_token: self.agent_auth_token.to_string(),
+            chain_id,
+            min_nonce,
+            requested_at: now,
+            expires_at: now + Self::REQUEST_TTL,
+        };
+        Ok(self.daemon.reserve_nonce(request).await?)
+    }
+
+    async fn release_broadcast_nonce(
+        &self,
+        reservation_id: uuid::Uuid,
+    ) -> Result<(), AgentSdkError> {
+        let now = OffsetDateTime::now_utc();
+        let request = NonceReleaseRequest {
+            request_id: uuid::Uuid::new_v4(),
+            agent_key_id: self.agent_key_id,
+            agent_auth_token: self.agent_auth_token.to_string(),
+            reservation_id,
+            requested_at: now,
+            expires_at: now + Self::REQUEST_TTL,
+        };
+        Ok(self.daemon.release_nonce(request).await?)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::{Arc, Mutex};
+
+    use async_trait::async_trait;
+    use time::OffsetDateTime;
+    use uuid::Uuid;
+    use vault_daemon::{DaemonError, KeyManagerDaemonApi};
+    use vault_domain::{
+        AdminSession, AgentAction, AgentCredentials, AgentKey, BroadcastTx, EvmAddress, Lease,
+        ManualApprovalDecision, ManualApprovalRequest, NonceReleaseRequest, NonceReservation,
+        NonceReservationRequest, PolicyAttachment, RelayConfig, SignRequest, Signature,
+        SpendingPolicy, VaultKey,
+    };
+    use vault_policy::PolicyEvaluation;
+    use vault_signer::KeyCreateRequest;
+
+    use super::{AgentOperations, AgentSdk, AgentSdkError};
+
+    #[derive(Default)]
+    pub(super) struct RecordingDaemon {
+        pub(super) request: Mutex<Option<SignRequest>>,
+        fail_sign: bool,
+        reserved_nonce_override: Option<u64>,
+    }
+
+    #[async_trait]
+    impl KeyManagerDaemonApi for RecordingDaemon {
+        async fn issue_lease(&self, _vault_password: &str) -> Result<Lease, DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn add_policy(
+            &self,
+            _session: &AdminSession,
+            _policy: SpendingPolicy,
+        ) -> Result<(), DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn list_policies(
+            &self,
+            _session: &AdminSession,
+        ) -> Result<Vec<SpendingPolicy>, DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn disable_policy(
+            &self,
+            _session: &AdminSession,
+            _policy_id: Uuid,
+        ) -> Result<(), DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn create_vault_key(
+            &self,
+            _session: &AdminSession,
+            _request: KeyCreateRequest,
+        ) -> Result<VaultKey, DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn export_vault_private_key(
+            &self,
+            _session: &AdminSession,
+            _vault_key_id: Uuid,
+        ) -> Result<Option<String>, DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn create_agent_key(
+            &self,
+            _session: &AdminSession,
+            _vault_key_id: Uuid,
+            _attachment: PolicyAttachment,
+        ) -> Result<AgentCredentials, DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn rotate_agent_auth_token(
+            &self,
+            _session: &AdminSession,
+            _agent_key_id: Uuid,
+        ) -> Result<String, DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn revoke_agent_key(
+            &self,
+            _session: &AdminSession,
+            _agent_key_id: Uuid,
+        ) -> Result<(), DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn list_manual_approval_requests(
+            &self,
+            _session: &AdminSession,
+        ) -> Result<Vec<ManualApprovalRequest>, DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn decide_manual_approval_request(
+            &self,
+            _session: &AdminSession,
+            _approval_request_id: Uuid,
+            _decision: ManualApprovalDecision,
+            _rejection_reason: Option<String>,
+        ) -> Result<ManualApprovalRequest, DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn set_relay_config(
+            &self,
+            _session: &AdminSession,
+            _relay_url: Option<String>,
+            _frontend_url: Option<String>,
+        ) -> Result<RelayConfig, DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn get_relay_config(
+            &self,
+            _session: &AdminSession,
+        ) -> Result<RelayConfig, DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn evaluate_for_agent(
+            &self,
+            _request: SignRequest,
+        ) -> Result<PolicyEvaluation, DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn explain_for_agent(
+            &self,
+            _request: SignRequest,
+        ) -> Result<vault_policy::PolicyExplanation, DaemonError> {
+            Err(DaemonError::Transport("not used".to_string()))
+        }
+
+        async fn reserve_nonce(
+            &self,
+            request: NonceReservationRequest,
+        ) -> Result<NonceReservation, DaemonError> {
+            Ok(NonceReservation {
+                reservation_id: Uuid::new_v4(),
+                agent_key_id: request.agent_key_id,
+                vault_key_id: Uuid::new_v4(),
+                chain_id: request.chain_id,
+                nonce: self.reserved_nonce_override.unwrap_or(request.min_nonce),
+                issued_at: OffsetDateTime::now_utc(),
+                expires_at: OffsetDateTime::now_utc() + time::Duration::minutes(2),
+            })
+        }
+
+        async fn release_nonce(&self, _request: NonceReleaseRequest) -> Result<(), DaemonError> {
+            Ok(())
+        }
+
+        async fn sign_for_agent(&self, request: SignRequest) -> Result<Signature, DaemonError> {
+            *self.request.lock().expect("lock") = Some(request);
+            if self.fail_sign {
+                return Err(DaemonError::AgentAuthenticationFailed);
+            }
+            Ok(Signature::from_der(vec![0x11, 0x22]))
+        }
+    }
+
+    pub(super) fn test_credentials() -> AgentCredentials {
+        AgentCredentials {
+            agent_key: AgentKey {
+                id: Uuid::new_v4(),
+                vault_key_id: Uuid::new_v4(),
+                policies: PolicyAttachment::AllPolicies,
+                created_at: OffsetDateTime::now_utc(),
+            },
+            auth_token: "agent-secret-token".to_string(),
+        }
+    }
+
+    #[tokio::test]
+    async fn approve_sends_canonical_action_payload_and_auth_token() {
+        let daemon = Arc::new(RecordingDaemon::default());
+        let credentials = test_credentials();
+        let key_id = credentials.agent_key.id;
+        let auth_token = credentials.auth_token.clone();
+        let sdk = AgentSdk::new(daemon.clone(), credentials);
+
+        let token: EvmAddress = "0x1000000000000000000000000000000000000000"
+            .parse()
+            .expect("token");
+        let spender: EvmAddress = "0x2000000000000000000000000000000000000000"
+            .parse()
+            .expect("spender");
+
+        let signature = sdk
+            .approve(1, token.clone(), spender.clone(), 42)
+            .await
+            .expect("approve");
+        assert_eq!(signature.bytes, vec![0x11, 0x22]);
+
+        let captured = daemon
+            .request
+            .lock()
+            .expect("lock")
+            .clone()
+            .expect("captured request");
+        assert_eq!(captured.agent_key_id, key_id);
+        assert_eq!(captured.agent_auth_token, auth_token);
+        assert_eq!(
+            captured.action,
+            AgentAction::Approve {
+                chain_id: 1,
+                token,
+                spender,
+                amount_wei: 42
+            }
+        );
+        let decoded: AgentAction = serde_json::from_slice(&captured.payload).expect("decode");
+        assert_eq!(decoded, captured.action);
+    }
+
+    #[tokio::test]
+    async fn transfer_propagates_daemon_errors() {
+        let daemon = Arc::new(RecordingDaemon {
+            request: Mutex::new(None),
+            fail_sign: true,
+            reserved_nonce_override: None,
+        });
+        let sdk = AgentSdk::new(daemon, test_credentials());
+
+        let token: EvmAddress = "0x3000000000000000000000000000000000000000"
+            .parse()
+            .expect("token");
+        let recipient: EvmAddress = "0x4000000000000000000000000000000000000000"
+            .parse()
+            .expect("recipient");
+
+        let err = sdk
+            .transfer(1, token, recipient, 7)
+            .await
+            .expect_err("must fail");
+        assert!(matches!(
+            err,
+            AgentSdkError::Daemon(DaemonError::AgentAuthenticationFailed)
+        ));
+    }
+
+    #[tokio::test]
+    async fn broadcast_tx_sends_canonical_action_payload() {
+        let daemon = Arc::new(RecordingDaemon::default());
+        let credentials = test_credentials();
+        let sdk = AgentSdk::new(daemon.clone(), credentials);
+
+        let tx = BroadcastTx {
+            chain_id: 1,
+            nonce: 0,
+            to: "0x5000000000000000000000000000000000000000"
+                .parse()
+                .expect("to"),
+            value_wei: 0,
+            data_hex: "0xdeadbeef".to_string(),
+            gas_limit: 50_000,
+            max_fee_per_gas_wei: 1_000_000_000,
+            max_priority_fee_per_gas_wei: 1_000_000_000,
+            tx_type: 0x02,
+            delegation_enabled: false,
+        };
+
+        let signature = sdk.broadcast_tx(tx.clone()).await.expect("broadcast");
+        assert_eq!(signature.bytes, vec![0x11, 0x22]);
+
+        let captured = daemon
+            .request
+            .lock()
+            .expect("lock")
+            .clone()
+            .expect("captured request");
+        assert_eq!(captured.action, AgentAction::BroadcastTx { tx: tx.clone() });
+        let decoded: AgentAction = serde_json::from_slice(&captured.payload).expect("decode");
+        assert_eq!(decoded, AgentAction::BroadcastTx { tx });
+    }
+
+    #[tokio::test]
+    async fn broadcast_tx_uses_reserved_nonce_from_daemon() {
+        let daemon = Arc::new(RecordingDaemon {
+            request: Mutex::new(None),
+            fail_sign: false,
+            reserved_nonce_override: Some(1),
+        });
+        let sdk = AgentSdk::new(daemon.clone(), test_credentials());
+
+        let tx = BroadcastTx {
+            chain_id: 56,
+            nonce: 0,
+            to: "0x5000000000000000000000000000000000000000"
+                .parse()
+                .expect("to"),
+            value_wei: 0,
+            data_hex: "0xdeadbeef".to_string(),
+            gas_limit: 50_000,
+            max_fee_per_gas_wei: 1_000_000_000,
+            max_priority_fee_per_gas_wei: 1_000_000_000,
+            tx_type: 0x02,
+            delegation_enabled: false,
+        };
+
+        sdk.broadcast_tx(tx.clone()).await.expect("broadcast");
+
+        let captured = daemon
+            .request
+            .lock()
+            .expect("lock")
+            .clone()
+            .expect("captured request");
+        match captured.action {
+            AgentAction::BroadcastTx { tx: signed_tx } => {
+                assert_eq!(signed_tx.nonce, 1);
+                assert_eq!(signed_tx.chain_id, tx.chain_id);
+                assert_eq!(signed_tx.to, tx.to);
+            }
+            other => panic!("unexpected action: {other:?}"),
+        }
+    }
+}
+
+#[cfg(test)]
+mod typed_data_tests {
+    use std::sync::Arc;
+
+    use super::tests::{test_credentials, RecordingDaemon};
+    use super::{AgentOperations, AgentSdk};
+    use vault_domain::{AgentAction, Eip3009Transfer, Permit2Permit};
+
+    #[tokio::test]
+    async fn permit2_sends_canonical_action_payload() {
+        let daemon = Arc::new(RecordingDaemon::default());
+        let sdk = AgentSdk::new(daemon.clone(), test_credentials());
+        let permit = Permit2Permit {
+            chain_id: 1,
+            permit2_contract: "0x000000000022d473030f116ddee9f6b43ac78ba3"
+                .parse()
+                .expect("permit2"),
+            token: "0x1000000000000000000000000000000000000000"
+                .parse()
+                .expect("token"),
+            spender: "0x2000000000000000000000000000000000000000"
+                .parse()
+                .expect("spender"),
+            amount_wei: 42,
+            expiration: 100,
+            nonce: 1,
+            sig_deadline: 200,
+        };
+
+        let signature = sdk.permit2_permit(permit.clone()).await.expect("permit2");
+        assert_eq!(signature.bytes, vec![0x11, 0x22]);
+
+        let captured = daemon
+            .request
+            .lock()
+            .expect("lock")
+            .clone()
+            .expect("captured request");
+        assert_eq!(captured.action, AgentAction::Permit2Permit { permit });
+        let decoded: AgentAction = serde_json::from_slice(&captured.payload).expect("decode");
+        assert_eq!(decoded, captured.action);
+    }
+
+    #[tokio::test]
+    async fn eip3009_receive_sends_canonical_action_payload() {
+        let daemon = Arc::new(RecordingDaemon::default());
+        let sdk = AgentSdk::new(daemon.clone(), test_credentials());
+        let authorization = Eip3009Transfer {
+            chain_id: 1,
+            token: "0x3000000000000000000000000000000000000000"
+                .parse()
+                .expect("token"),
+            token_name: "USD Coin".to_string(),
+            token_version: Some("2".to_string()),
+            from: "0x4000000000000000000000000000000000000000"
+                .parse()
+                .expect("from"),
+            to: "0x5000000000000000000000000000000000000000"
+                .parse()
+                .expect("to"),
+            amount_wei: 9,
+            valid_after: 1,
+            valid_before: 2,
+            nonce_hex: "0x5555555555555555555555555555555555555555555555555555555555555555"
+                .to_string(),
+        };
+
+        let signature = sdk
+            .eip3009_receive_with_authorization(authorization.clone())
+            .await
+            .expect("eip3009 receive");
+        assert_eq!(signature.bytes, vec![0x11, 0x22]);
+
+        let captured = daemon
+            .request
+            .lock()
+            .expect("lock")
+            .clone()
+            .expect("captured request");
+        assert_eq!(
+            captured.action,
+            AgentAction::Eip3009ReceiveWithAuthorization { authorization }
+        );
+        let decoded: AgentAction = serde_json::from_slice(&captured.payload).expect("decode");
+        assert_eq!(decoded, captured.action);
+    }
+}