@wlfi-agent/cli 1.4.13 → 1.4.15

package/crates/vault-cli-agent/src/main.rs

@@ -0,0 +1,833 @@
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use anyhow::{Context, Result};
+use clap::{Parser, Subcommand, ValueEnum};
+use serde::Serialize;
+use uuid::Uuid;
+use vault_daemon::{DaemonError, KeyManagerDaemonApi};
+use vault_domain::{AgentAction, BroadcastTx, EvmAddress};
+use vault_sdk_agent::{AgentOperations, AgentSdk, AgentSdkError};
+use vault_transport_unix::{assert_root_owned_daemon_socket_path, UnixDaemonClient};
+
+mod io_utils;
+
+use io_utils::*;
+
+#[derive(Debug, Parser)]
+#[command(name = "wlfi-agent-agent")]
+#[command(about = "Agent CLI for sending signing requests through daemon policy checks")]
+struct Cli {
+    #[arg(
+        long,
+        default_value_t = false,
+        help = "Do not prompt for missing secrets; require WLFI_AGENT_AUTH_TOKEN or --agent-auth-token-stdin"
+    )]
+    non_interactive: bool,
+    #[arg(
+        long,
+        env = "WLFI_AGENT_KEY_ID",
+        value_name = "UUID",
+        help = "Provisioned agent key id"
+    )]
+    agent_key_id: Uuid,
+    #[arg(
+        long,
+        value_name = "TOKEN",
+        conflicts_with = "agent_auth_token_stdin",
+        help = "Legacy insecure agent auth token flag (disabled by default); use --agent-auth-token-stdin or WLFI_AGENT_AUTH_TOKEN"
+    )]
+    agent_auth_token: Option<String>,
+    #[arg(
+        long,
+        default_value_t = false,
+        help = "Read agent auth token from stdin (trailing newlines are trimmed)"
+    )]
+    agent_auth_token_stdin: bool,
+    #[arg(
+        long,
+        env = "WLFI_DAEMON_SOCKET",
+        value_name = "PATH",
+        help = "Always-on daemon unix socket path (default: $WLFI_HOME/daemon.sock or ~/.wlfi_agent/daemon.sock)"
+    )]
+    daemon_socket: Option<PathBuf>,
+    #[arg(
+        long,
+        short = 'f',
+        value_enum,
+        value_name = "text|json",
+        help = "Output format"
+    )]
+    format: Option<OutputFormat>,
+    #[arg(
+        long,
+        short = 'j',
+        default_value_t = false,
+        help = "Shortcut for --format json"
+    )]
+    json: bool,
+    #[arg(
+        long,
+        short = 'q',
+        default_value_t = false,
+        help = "Suppress non-essential status messages in text mode"
+    )]
+    quiet: bool,
+    #[arg(
+        long,
+        short = 'o',
+        value_name = "PATH",
+        help = "Write final command output to PATH (use '-' for stdout)"
+    )]
+    output: Option<PathBuf>,
+    #[arg(
+        long,
+        default_value_t = false,
+        requires = "output",
+        help = "Allow replacing an existing output file"
+    )]
+    overwrite: bool,
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+enum OutputFormat {
+    Text,
+    Json,
+}
+
+#[derive(Debug)]
+enum OutputTarget {
+    Stdout,
+    File { path: PathBuf, overwrite: bool },
+}
+
+#[derive(Debug, Subcommand)]
+enum Commands {
+    #[command(about = "Submit an ERC-20 transfer request through policy checks")]
+    Transfer {
+        #[arg(long, value_parser = parse_positive_u64)]
+        network: u64,
+        #[arg(long)]
+        token: EvmAddress,
+        #[arg(long)]
+        to: EvmAddress,
+        #[arg(long, value_parser = parse_positive_u128)]
+        amount_wei: u128,
+    },
+    #[command(about = "Submit a native ETH transfer request through policy checks")]
+    TransferNative {
+        #[arg(long, value_parser = parse_positive_u64)]
+        network: u64,
+        #[arg(long)]
+        to: EvmAddress,
+        #[arg(long, value_parser = parse_positive_u128)]
+        amount_wei: u128,
+    },
+    #[command(about = "Submit an ERC-20 approve request through policy checks")]
+    Approve {
+        #[arg(long, value_parser = parse_positive_u64)]
+        network: u64,
+        #[arg(long)]
+        token: EvmAddress,
+        #[arg(long)]
+        spender: EvmAddress,
+        #[arg(long, value_parser = parse_positive_u128)]
+        amount_wei: u128,
+    },
+    #[command(about = "Submit a raw transaction broadcast request through policy checks")]
+    Broadcast {
+        #[arg(long, value_parser = parse_positive_u64)]
+        network: u64,
+        #[arg(long, default_value_t = 0u64, value_parser = parse_non_negative_u64)]
+        nonce: u64,
+        #[arg(long)]
+        to: EvmAddress,
+        #[arg(long, default_value_t = 0u128, value_parser = parse_non_negative_u128)]
+        value_wei: u128,
+        #[arg(long, default_value = "0x")]
+        data_hex: String,
+        #[arg(long, value_parser = parse_positive_u64)]
+        gas_limit: u64,
+        #[arg(long, value_parser = parse_positive_u128)]
+        max_fee_per_gas_wei: u128,
+        #[arg(
+            long,
+            default_value_t = 0u128,
+            value_parser = parse_non_negative_u128
+        )]
+        max_priority_fee_per_gas_wei: u128,
+        #[arg(long, default_value_t = 0x02u8, value_parser = parse_tx_type_u8)]
+        tx_type: u8,
+        #[arg(long, default_value_t = false)]
+        delegation_enabled: bool,
+    },
+}
+
+#[derive(Debug, Serialize)]
+struct AgentCommandOutput {
+    command: String,
+    network: String,
+    asset: String,
+    counterparty: String,
+    amount_wei: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    estimated_max_gas_spend_wei: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    tx_type: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    delegation_enabled: Option<bool>,
+    signature_hex: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    r_hex: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    s_hex: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    v: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    raw_tx_hex: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    tx_hash_hex: Option<String>,
+}
+
+#[derive(Debug, Serialize)]
+struct ManualApprovalRequiredOutput {
+    command: String,
+    approval_request_id: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    relay_url: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    frontend_url: Option<String>,
+    cli_approval_command: String,
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let cli = Cli::parse();
+    let output_format = resolve_output_format(cli.format, cli.json)?;
+    let output_target = resolve_output_target(cli.output, cli.overwrite)?;
+    let daemon_socket = resolve_daemon_socket_path(cli.daemon_socket)?;
+    let agent_auth_token = resolve_agent_auth_token(
+        cli.agent_auth_token,
+        std::env::var("WLFI_AGENT_AUTH_TOKEN").ok(),
+        cli.agent_auth_token_stdin,
+        cli.non_interactive,
+    )?;
+    print_status("connecting to daemon socket", output_format, cli.quiet);
+    let daemon: Arc<dyn KeyManagerDaemonApi> =
+        Arc::new(UnixDaemonClient::new_with_expected_server_euid(
+            daemon_socket.clone(),
+            std::time::Duration::from_secs(10),
+            0,
+        ));
+
+    let sdk = AgentSdk::new_with_key_id_and_token(daemon, cli.agent_key_id, agent_auth_token);
+
+    match cli.command {
+        Commands::Transfer {
+            network,
+            token,
+            to,
+            amount_wei,
+        } => {
+            let token_str = token.to_string();
+            let to_str = to.to_string();
+            print_status("submitting transfer request", output_format, cli.quiet);
+            let signature = match await_signature_or_handle_manual_approval(
+                "transfer",
+                &daemon_socket,
+                output_format,
+                &output_target,
+                sdk.transfer(network, token, to, amount_wei),
+            )
+            .await?
+            {
+                Some(signature) => signature,
+                None => std::process::exit(2),
+            };
+            let output = AgentCommandOutput {
+                command: "transfer".to_string(),
+                network: network.to_string(),
+                asset: format!("erc20:{token_str}"),
+                counterparty: to_str,
+                amount_wei: amount_wei.to_string(),
+                estimated_max_gas_spend_wei: None,
+                tx_type: None,
+                delegation_enabled: None,
+                signature_hex: format!("0x{}", hex::encode(signature.bytes)),
+                r_hex: None,
+                s_hex: None,
+                v: None,
+                raw_tx_hex: None,
+                tx_hash_hex: None,
+            };
+            print_status("transfer request signed", output_format, cli.quiet);
+            print_agent_output(&output, output_format, &output_target)?;
+        }
+        Commands::TransferNative {
+            network,
+            to,
+            amount_wei,
+        } => {
+            let to_str = to.to_string();
+            print_status(
+                "submitting native transfer request",
+                output_format,
+                cli.quiet,
+            );
+            let signature = match await_signature_or_handle_manual_approval(
+                "transfer-native",
+                &daemon_socket,
+                output_format,
+                &output_target,
+                sdk.transfer_native(network, to, amount_wei),
+            )
+            .await?
+            {
+                Some(signature) => signature,
+                None => std::process::exit(2),
+            };
+            let output = AgentCommandOutput {
+                command: "transfer-native".to_string(),
+                network: network.to_string(),
+                asset: "native_eth".to_string(),
+                counterparty: to_str,
+                amount_wei: amount_wei.to_string(),
+                estimated_max_gas_spend_wei: None,
+                tx_type: None,
+                delegation_enabled: None,
+                signature_hex: format!("0x{}", hex::encode(signature.bytes)),
+                r_hex: None,
+                s_hex: None,
+                v: None,
+                raw_tx_hex: None,
+                tx_hash_hex: None,
+            };
+            print_status("native transfer request signed", output_format, cli.quiet);
+            print_agent_output(&output, output_format, &output_target)?;
+        }
+        Commands::Approve {
+            network,
+            token,
+            spender,
+            amount_wei,
+        } => {
+            let token_str = token.to_string();
+            let spender_str = spender.to_string();
+            print_status("submitting approve request", output_format, cli.quiet);
+            let signature = match await_signature_or_handle_manual_approval(
+                "approve",
+                &daemon_socket,
+                output_format,
+                &output_target,
+                sdk.approve(network, token, spender, amount_wei),
+            )
+            .await?
+            {
+                Some(signature) => signature,
+                None => std::process::exit(2),
+            };
+            let output = AgentCommandOutput {
+                command: "approve".to_string(),
+                network: network.to_string(),
+                asset: format!("erc20:{token_str}"),
+                counterparty: spender_str,
+                amount_wei: amount_wei.to_string(),
+                estimated_max_gas_spend_wei: None,
+                tx_type: None,
+                delegation_enabled: None,
+                signature_hex: format!("0x{}", hex::encode(signature.bytes)),
+                r_hex: None,
+                s_hex: None,
+                v: None,
+                raw_tx_hex: None,
+                tx_hash_hex: None,
+            };
+            print_status("approve request signed", output_format, cli.quiet);
+            print_agent_output(&output, output_format, &output_target)?;
+        }
+        Commands::Broadcast {
+            network,
+            nonce,
+            to,
+            value_wei,
+            data_hex,
+            gas_limit,
+            max_fee_per_gas_wei,
+            max_priority_fee_per_gas_wei,
+            tx_type,
+            delegation_enabled,
+        } => {
+            let tx = BroadcastTx {
+                chain_id: network,
+                nonce,
+                to,
+                value_wei,
+                data_hex,
+                gas_limit,
+                max_fee_per_gas_wei,
+                max_priority_fee_per_gas_wei,
+                tx_type,
+                delegation_enabled,
+            };
+            let action = AgentAction::BroadcastTx { tx: tx.clone() };
+            action
+                .validate()
+                .context("invalid broadcast transaction payload")?;
+            let estimated_max_gas_spend_wei = tx.max_gas_spend_wei()?;
+            let asset = action.asset();
+            let counterparty = action.recipient();
+
+            print_status("submitting broadcast request", output_format, cli.quiet);
+            let signature = match await_signature_or_handle_manual_approval(
+                "broadcast",
+                &daemon_socket,
+                output_format,
+                &output_target,
+                sdk.broadcast_tx(tx),
+            )
+            .await?
+            {
+                Some(signature) => signature,
+                None => std::process::exit(2),
+            };
+            let output = AgentCommandOutput {
+                command: "broadcast".to_string(),
+                network: network.to_string(),
+                asset: asset.to_string(),
+                counterparty: counterparty.to_string(),
+                amount_wei: action.amount_wei().to_string(),
+                estimated_max_gas_spend_wei: Some(estimated_max_gas_spend_wei.to_string()),
+                tx_type: Some(format!("0x{tx_type:02x}")),
+                delegation_enabled: Some(delegation_enabled),
+                signature_hex: format!("0x{}", hex::encode(&signature.bytes)),
+                r_hex: signature.r_hex,
+                s_hex: signature.s_hex,
+                v: signature.v,
+                raw_tx_hex: signature.raw_tx_hex,
+                tx_hash_hex: signature.tx_hash_hex,
+            };
+            print_status("broadcast request signed", output_format, cli.quiet);
+            print_agent_output(&output, output_format, &output_target)?;
+        }
+    }
+
+    Ok(())
+}
+
+async fn await_signature_or_handle_manual_approval(
+    command: &str,
+    daemon_socket: &Path,
+    format: OutputFormat,
+    target: &OutputTarget,
+    future: impl std::future::Future<Output = Result<vault_domain::Signature, AgentSdkError>>,
+) -> Result<Option<vault_domain::Signature>> {
+    match future.await {
+        Ok(signature) => Ok(Some(signature)),
+        Err(AgentSdkError::Daemon(DaemonError::ManualApprovalRequired {
+            approval_request_id,
+            relay_url,
+            frontend_url,
+        })) => {
+            let output = ManualApprovalRequiredOutput {
+                command: command.to_string(),
+                approval_request_id: approval_request_id.to_string(),
+                relay_url,
+                frontend_url,
+                cli_approval_command: format!(
+                    "wlfi-agent admin approve-manual-approval-request --approval-request-id {} --daemon-socket {}",
+                    approval_request_id,
+                    daemon_socket.display()
+                ),
+            };
+            print_manual_approval_required_output(&output, format, target)?;
+            Ok(None)
+        }
+        Err(err) => Err(err.into()),
+    }
+}
+
+fn print_manual_approval_required_output(
+    output: &ManualApprovalRequiredOutput,
+    format: OutputFormat,
+    target: &OutputTarget,
+) -> Result<()> {
+    let rendered = match format {
+        OutputFormat::Json => {
+            serde_json::to_string_pretty(output).context("failed to serialize output")?
+        }
+        OutputFormat::Text => {
+            let mut lines = vec![
+                format!("Command: {}", output.command),
+                format!("Approval Request ID: {}", output.approval_request_id),
+            ];
+            if let Some(frontend_url) = &output.frontend_url {
+                lines.push(format!("Frontend Approval URL: {frontend_url}"));
+            }
+            if let Some(relay_url) = &output.relay_url {
+                lines.push(format!("Relay URL: {relay_url}"));
+            }
+            lines.push(format!(
+                "CLI Approval Command: {}",
+                output.cli_approval_command
+            ));
+            lines.join(
+                "
+",
+            )
+        }
+    };
+    emit_output(&rendered, target)
+}
+
+fn resolve_daemon_socket_path(cli_value: Option<PathBuf>) -> Result<PathBuf> {
+    let path = match cli_value {
+        Some(path) => path,
+        None => wlfi_home_dir()?.join("daemon.sock"),
+    };
+
+    assert_root_owned_daemon_socket_path(&path).map_err(anyhow::Error::msg)
+}
+
+fn wlfi_home_dir() -> Result<PathBuf> {
+    if let Some(path) = std::env::var_os("WLFI_HOME") {
+        let candidate = PathBuf::from(path);
+        if candidate.as_os_str().is_empty() {
+            return Err(anyhow::anyhow!("WLFI_HOME must not be empty").into());
+        }
+        return Ok(candidate);
+    }
+
+    let Some(home) = std::env::var_os("HOME") else {
+        return Err(
+            anyhow::anyhow!("HOME is not set; use WLFI_HOME to choose config directory").into(),
+        );
+    };
+    Ok(PathBuf::from(home).join(".wlfi_agent"))
+}
+
+fn parse_positive_u128(input: &str) -> Result<u128, String> {
+    let parsed = input
+        .parse::<u128>()
+        .map_err(|_| "must be a valid unsigned integer".to_string())?;
+    if parsed == 0 {
+        return Err("must be greater than zero".to_string());
+    }
+    Ok(parsed)
+}
+
+fn parse_non_negative_u128(input: &str) -> Result<u128, String> {
+    input
+        .parse::<u128>()
+        .map_err(|_| "must be a valid unsigned integer".to_string())
+}
+
+fn parse_tx_type_u8(input: &str) -> Result<u8, String> {
+    let trimmed = input.trim();
+    let parsed = if let Some(hex_value) = trimmed
+        .strip_prefix("0x")
+        .or_else(|| trimmed.strip_prefix("0X"))
+    {
+        u8::from_str_radix(hex_value, 16)
+    } else {
+        trimmed.parse::<u8>()
+    };
+    parsed.map_err(|_| "must be a valid u8 (decimal or 0x-prefixed hex)".to_string())
+}
+
+fn parse_positive_u64(input: &str) -> Result<u64, String> {
+    let parsed = input
+        .parse::<u64>()
+        .map_err(|_| "must be a valid unsigned integer".to_string())?;
+    if parsed == 0 {
+        return Err("must be greater than zero".to_string());
+    }
+    Ok(parsed)
+}
+
+fn parse_non_negative_u64(input: &str) -> Result<u64, String> {
+    input
+        .parse::<u64>()
+        .map_err(|_| "must be a valid unsigned integer".to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        ensure_output_parent, resolve_agent_auth_token, resolve_output_format,
+        resolve_output_target, should_print_status, write_output_file, Cli, Commands, OutputFormat,
+        OutputTarget,
+    };
+    use clap::Parser;
+    use std::fs;
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    const TEST_AGENT_KEY_ID: &str = "11111111-1111-1111-1111-111111111111";
+
+    #[test]
+    fn resolve_output_format_defaults_to_text() {
+        let format = resolve_output_format(None, false).expect("format");
+        assert!(matches!(format, OutputFormat::Text));
+    }
+
+    #[test]
+    fn resolve_output_format_json_shortcut() {
+        let format = resolve_output_format(None, true).expect("format");
+        assert!(matches!(format, OutputFormat::Json));
+    }
+
+    #[test]
+    fn resolve_output_format_rejects_text_conflict_with_json_shortcut() {
+        let err = resolve_output_format(Some(OutputFormat::Text), true).expect_err("must fail");
+        assert!(err.to_string().contains("--format text"));
+    }
+
+    #[test]
+    fn resolve_output_format_allows_json_redundancy() {
+        let format = resolve_output_format(Some(OutputFormat::Json), true).expect("format");
+        assert!(matches!(format, OutputFormat::Json));
+    }
+
+    #[test]
+    fn resolve_agent_auth_token_rejects_whitespace_only() {
+        let err = resolve_agent_auth_token(Some(" \t ".to_string()), None, false, false)
+            .expect_err("must fail");
+        assert!(err.to_string().contains("must not be empty or whitespace"));
+    }
+
+    #[test]
+    fn resolve_agent_auth_token_rejects_cli_argument_source() {
+        let err = resolve_agent_auth_token(Some("secret".to_string()), None, false, false)
+            .expect_err("must fail");
+        assert!(err
+            .to_string()
+            .contains("--agent-auth-token is disabled for security"));
+    }
+
+    #[test]
+    fn resolve_agent_auth_token_accepts_environment_source() {
+        let token = resolve_agent_auth_token(None, Some("secret".to_string()), false, false)
+            .expect("environment token");
+        assert_eq!(token, "secret");
+    }
+
+    #[test]
+    fn status_printing_only_in_text_when_not_quiet() {
+        assert!(should_print_status(OutputFormat::Text, false));
+        assert!(!should_print_status(OutputFormat::Text, true));
+        assert!(!should_print_status(OutputFormat::Json, false));
+    }
+
+    #[test]
+    fn resolve_output_target_maps_dash_to_stdout() {
+        let target = resolve_output_target(Some("-".into()), false).expect("target");
+        assert!(matches!(target, OutputTarget::Stdout));
+    }
+
+    #[test]
+    fn resolve_output_target_rejects_overwrite_with_stdout() {
+        let err = resolve_output_target(Some("-".into()), true).expect_err("must fail");
+        assert!(err.to_string().contains("--overwrite cannot be used"));
+    }
+
+    #[test]
+    fn output_file_write_respects_overwrite_flag() {
+        let unique = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("time")
+            .as_nanos();
+        let path = std::env::temp_dir().join(format!(
+            "wlfi-agent-cli-output-{}-{}.txt",
+            std::process::id(),
+            unique
+        ));
+        std::fs::write(&path, "existing\n").expect("seed");
+
+        let err = write_output_file(&path, "next", false).expect_err("must fail");
+        assert!(err.to_string().contains("already exists"));
+
+        write_output_file(&path, "next", true).expect("overwrite");
+        let updated = std::fs::read_to_string(&path).expect("read");
+        assert_eq!(updated, "next\n");
+
+        std::fs::remove_file(&path).expect("cleanup");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn output_file_write_rejects_symlink_target() {
+        use std::os::unix::fs::symlink;
+
+        let unique = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("time")
+            .as_nanos();
+        let target = std::env::temp_dir().join(format!(
+            "wlfi-agent-cli-symlink-target-{}-{}.txt",
+            std::process::id(),
+            unique
+        ));
+        let link = std::env::temp_dir().join(format!(
+            "wlfi-agent-cli-symlink-link-{}-{}.txt",
+            std::process::id(),
+            unique
+        ));
+        std::fs::write(&target, "seed\n").expect("seed");
+        symlink(&target, &link).expect("symlink");
+
+        let err = ensure_output_parent(&link).expect_err("must fail");
+        assert!(err.to_string().contains("must not be a symlink"));
+
+        std::fs::remove_file(&link).expect("cleanup link");
+        std::fs::remove_file(&target).expect("cleanup target");
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn resolve_daemon_socket_path_rejects_non_socket_files() {
+        use std::os::unix::fs::PermissionsExt;
+
+        let unique = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("time")
+            .as_nanos();
+        let root = std::env::temp_dir().join(format!("wg-{unique:x}"));
+        fs::create_dir_all(&root).expect("create root directory");
+        fs::set_permissions(&root, fs::Permissions::from_mode(0o700))
+            .expect("secure root directory permissions");
+
+        let socket_path = root.join("daemon.sock");
+        fs::write(&socket_path, "not a socket").expect("write file");
+
+        let err = super::resolve_daemon_socket_path(Some(socket_path)).expect_err("must reject");
+        assert!(err.to_string().contains("must be a unix socket"));
+
+        fs::remove_dir_all(&root).expect("cleanup temp tree");
+    }
+
+    #[test]
+    fn canonical_transfer_command_is_accepted() {
+        let cli = Cli::try_parse_from([
+            "wlfi-agent-agent",
+            "--agent-key-id",
+            TEST_AGENT_KEY_ID,
+            "--agent-auth-token",
+            "test-auth-token",
+            "--daemon-socket",
+            "/tmp/wlfi.sock",
+            "transfer",
+            "--network",
+            "1",
+            "--token",
+            "0x1000000000000000000000000000000000000000",
+            "--to",
+            "0x2000000000000000000000000000000000000000",
+            "--amount-wei",
+            "1",
+        ])
+        .expect("parse");
+        assert!(matches!(cli.command, Commands::Transfer { .. }));
+    }
+
+    #[test]
+    fn canonical_transfer_native_command_is_accepted() {
+        let cli = Cli::try_parse_from([
+            "wlfi-agent-agent",
+            "--agent-key-id",
+            TEST_AGENT_KEY_ID,
+            "--agent-auth-token",
+            "test-auth-token",
+            "--daemon-socket",
+            "/tmp/wlfi.sock",
+            "transfer-native",
+            "--network",
+            "1",
+            "--to",
+            "0x2000000000000000000000000000000000000000",
+            "--amount-wei",
+            "1",
+        ])
+        .expect("parse");
+        assert!(matches!(cli.command, Commands::TransferNative { .. }));
+    }
+
+    #[test]
+    fn canonical_approve_command_is_accepted() {
+        let cli = Cli::try_parse_from([
+            "wlfi-agent-agent",
+            "--agent-key-id",
+            TEST_AGENT_KEY_ID,
+            "--agent-auth-token",
+            "test-auth-token",
+            "--daemon-socket",
+            "/tmp/wlfi.sock",
+            "approve",
+            "--network",
+            "1",
+            "--token",
+            "0x1000000000000000000000000000000000000000",
+            "--spender",
+            "0x3000000000000000000000000000000000000000",
+            "--amount-wei",
+            "1",
+        ])
+        .expect("parse");
+        assert!(matches!(cli.command, Commands::Approve { .. }));
+    }
+
+    #[test]
+    fn canonical_broadcast_command_is_accepted() {
+        let cli = Cli::try_parse_from([
+            "wlfi-agent-agent",
+            "--agent-key-id",
+            TEST_AGENT_KEY_ID,
+            "--agent-auth-token",
+            "test-auth-token",
+            "--daemon-socket",
+            "/tmp/wlfi.sock",
+            "broadcast",
+            "--network",
+            "1",
+            "--to",
+            "0x3000000000000000000000000000000000000000",
+            "--value-wei",
+            "0",
+            "--data-hex",
+            "0xdeadbeef",
+            "--gas-limit",
+            "21000",
+            "--max-fee-per-gas-wei",
+            "1000000000",
+            "--tx-type",
+            "0x02",
+        ])
+        .expect("parse");
+        assert!(matches!(cli.command, Commands::Broadcast { .. }));
+    }
+
+    #[test]
+    fn agent_auth_token_flag_conflicts_with_stdin_flag() {
+        let err = Cli::try_parse_from([
+            "wlfi-agent-agent",
+            "--agent-key-id",
+            TEST_AGENT_KEY_ID,
+            "--daemon-socket",
+            "/tmp/wlfi.sock",
+            "--agent-auth-token",
+            "test-auth-token",
+            "--agent-auth-token-stdin",
+            "transfer-native",
+            "--network",
+            "1",
+            "--to",
+            "0x2000000000000000000000000000000000000000",
+            "--amount-wei",
+            "1",
+        ])
+        .expect_err("must fail");
+        let rendered = err.to_string();
+        assert!(rendered.contains("--agent-auth-token"));
+        assert!(rendered.contains("--agent-auth-token-stdin"));
+    }
+}