@wlfi-agent/cli 1.4.13 → 1.4.14

package/crates/vault-cli-daemon/src/relay_sync.rs

@@ -0,0 +1,894 @@
+use std::collections::BTreeMap;
+use std::path::Path;
+use std::sync::Arc;
+
+use ::time::format_description::well_known::Rfc3339;
+use ::time::OffsetDateTime;
+use anyhow::{Context, Result};
+use reqwest::header::CONTENT_TYPE;
+use reqwest::Client;
+use serde::{Deserialize, Serialize};
+use tokio::task::JoinHandle;
+use tokio::time::{self, MissedTickBehavior};
+use uuid::Uuid;
+use vault_daemon::{InMemoryDaemon, RelayRegistrationSnapshot};
+use vault_domain::{
+    manual_approval_capability_hash, manual_approval_capability_token, AgentAction, AssetId,
+    EntityScope, ManualApprovalDecision, ManualApprovalStatus, PolicyType, SpendingPolicy,
+};
+use vault_signer::VaultSignerBackend;
+
+const DEFAULT_RELAY_POLL_LIMIT: u32 = 25;
+const DEFAULT_RELAY_LEASE_SECONDS: u32 = 30;
+const ZERO_ADDRESS: &str = "0x0000000000000000000000000000000000000000";
+const RELAY_DAEMON_TOKEN_ENV: &str = "WLFI_RELAY_DAEMON_TOKEN";
+const RELAY_DAEMON_TOKEN_FILE_ENV: &str = "WLFI_RELAY_DAEMON_TOKEN_FILE";
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct RelayDaemonProfilePayload {
+    daemon_id: String,
+    daemon_public_key: String,
+    ethereum_address: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    label: Option<String>,
+    last_seen_at: String,
+    registered_at: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    relay_url: Option<String>,
+    signer_backend: String,
+    status: &'static str,
+    updated_at: String,
+    version: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct RelayPolicyPayload {
+    action: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    amount_max_wei: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    amount_min_wei: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    chain_id: Option<u64>,
+    destination: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    metadata: Option<BTreeMap<String, String>>,
+    policy_id: String,
+    requires_manual_approval: bool,
+    scope: &'static str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    token_address: Option<String>,
+    updated_at: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct RelayAgentKeyPayload {
+    agent_key_id: String,
+    created_at: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    label: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    metadata: Option<BTreeMap<String, String>>,
+    status: &'static str,
+    updated_at: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct RelayApprovalRequestPayload {
+    agent_key_id: String,
+    amount_wei: String,
+    approval_request_id: String,
+    chain_id: u64,
+    destination: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    metadata: Option<BTreeMap<String, String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    network: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    reason: Option<String>,
+    requested_at: String,
+    status: &'static str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    token_address: Option<String>,
+    transaction_type: String,
+    updated_at: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct RelayRegisterRequest {
+    daemon: RelayDaemonProfilePayload,
+    policies: Vec<RelayPolicyPayload>,
+    agent_keys: Vec<RelayAgentKeyPayload>,
+    approval_requests: Vec<RelayApprovalRequestPayload>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct RelayPollRequest<'a> {
+    daemon_id: &'a str,
+    lease_seconds: u32,
+    limit: u32,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct RelayEncryptedPayload {
+    algorithm: String,
+    ciphertext_base64: String,
+    encapsulated_key_base64: String,
+    nonce_base64: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct RelayEncryptedUpdateRecord {
+    claim_token: Option<String>,
+    daemon_id: String,
+    payload: RelayEncryptedPayload,
+    target_approval_request_id: Option<String>,
+    r#type: String,
+    update_id: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct RelayPollResponse {
+    items: Vec<RelayEncryptedUpdateRecord>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct RelayFeedbackRequest<'a> {
+    claim_token: &'a str,
+    daemon_id: &'a str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    details: Option<BTreeMap<String, String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    message: Option<String>,
+    status: &'a str,
+    update_id: &'a str,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct RelayManualApprovalUpdatePayload {
+    approval_id: String,
+    daemon_id: String,
+    decision: RelayDecision,
+    #[serde(default)]
+    note: Option<String>,
+    vault_password: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "snake_case")]
+enum RelayDecision {
+    Approve,
+    Reject,
+}
+
+struct ProcessedFeedback {
+    details: Option<BTreeMap<String, String>>,
+    message: Option<String>,
+    status: &'static str,
+}
+
+pub fn spawn_relay_sync_task<B>(
+    daemon: Arc<InMemoryDaemon<B>>,
+    signer_backend: &'static str,
+) -> JoinHandle<()>
+where
+    B: VaultSignerBackend + Send + Sync + 'static,
+{
+    tokio::spawn(async move {
+        if let Err(error) = run_relay_sync_loop(daemon, signer_backend).await {
+            eprintln!("==> relay sync terminated: {error:#}");
+        }
+    })
+}
+
+async fn run_relay_sync_loop<B>(
+    daemon: Arc<InMemoryDaemon<B>>,
+    signer_backend: &'static str,
+) -> Result<()>
+where
+    B: VaultSignerBackend + Send + Sync + 'static,
+{
+    let client = Client::builder()
+        .user_agent(format!("wlfi-agent-daemon/{}", env!("CARGO_PKG_VERSION")))
+        .build()
+        .context("failed to initialize relay sync HTTP client")?;
+    let registered_at = format_time(OffsetDateTime::now_utc())?;
+    let mut interval = time::interval(std::time::Duration::from_secs(1));
+    interval.set_missed_tick_behavior(MissedTickBehavior::Skip);
+
+    loop {
+        interval.tick().await;
+        if let Err(error) =
+            sync_once(&client, daemon.as_ref(), signer_backend, &registered_at).await
+        {
+            eprintln!("==> relay sync warning: {error:#}");
+        }
+    }
+}
+
+async fn sync_once<B>(
+    client: &Client,
+    daemon: &InMemoryDaemon<B>,
+    signer_backend: &'static str,
+    registered_at: &str,
+) -> Result<()>
+where
+    B: VaultSignerBackend + Send + Sync + 'static,
+{
+    let snapshot = daemon
+        .relay_registration_snapshot()
+        .context("failed to snapshot daemon relay registration state")?;
+    let Some(relay_url) = snapshot.relay_config.relay_url.clone() else {
+        return Ok(());
+    };
+    let Some(ethereum_address) = snapshot.ethereum_address.clone() else {
+        return Ok(());
+    };
+
+    register_snapshot(
+        client,
+        &relay_url,
+        signer_backend,
+        registered_at,
+        &snapshot,
+        &ethereum_address,
+    )
+    .await
+    .context("failed to register daemon snapshot with relay")?;
+
+    let poll_response = poll_updates(client, &relay_url, &snapshot.relay_config.daemon_id_hex)
+        .await
+        .context("failed to poll relay for encrypted updates")?;
+
+    for update in poll_response.items {
+        let feedback = process_update(daemon, &snapshot.relay_config.daemon_id_hex, &update).await;
+        let claim_token = update
+            .claim_token
+            .as_deref()
+            .context("relay returned update without claim token")?;
+        submit_feedback(
+            client,
+            &relay_url,
+            claim_token,
+            &snapshot.relay_config.daemon_id_hex,
+            &update.update_id,
+            feedback,
+        )
+        .await
+        .with_context(|| {
+            format!(
+                "failed to submit feedback for relay update {}",
+                update.update_id
+            )
+        })?;
+    }
+
+    Ok(())
+}
+
+async fn register_snapshot(
+    client: &Client,
+    relay_url: &str,
+    signer_backend: &'static str,
+    registered_at: &str,
+    snapshot: &RelayRegistrationSnapshot,
+    ethereum_address: &str,
+) -> Result<()> {
+    let now = format_time(OffsetDateTime::now_utc())?;
+    let request = RelayRegisterRequest {
+        daemon: RelayDaemonProfilePayload {
+            daemon_id: snapshot.relay_config.daemon_id_hex.clone(),
+            daemon_public_key: snapshot.relay_config.daemon_public_key_hex.clone(),
+            ethereum_address: ethereum_address.to_string(),
+            label: std::env::var("HOSTNAME")
+                .ok()
+                .filter(|value| !value.trim().is_empty()),
+            last_seen_at: now.clone(),
+            registered_at: registered_at.to_string(),
+            relay_url: snapshot.relay_config.relay_url.clone(),
+            signer_backend: signer_backend.to_string(),
+            status: "active",
+            updated_at: now.clone(),
+            version: env!("CARGO_PKG_VERSION").to_string(),
+        },
+        policies: flatten_policy_records(&snapshot.policies, &now),
+        agent_keys: snapshot
+            .agent_keys
+            .iter()
+            .map(|agent_key| RelayAgentKeyPayload {
+                agent_key_id: agent_key.id.to_string(),
+                created_at: format_time(agent_key.created_at).unwrap_or_else(|_| now.clone()),
+                label: None,
+                metadata: None,
+                status: "active",
+                updated_at: now.clone(),
+            })
+            .collect(),
+        approval_requests: snapshot
+            .manual_approval_requests
+            .iter()
+            .map(|request| RelayApprovalRequestPayload {
+                agent_key_id: request.agent_key_id.to_string(),
+                amount_wei: request.amount_wei.to_string(),
+                approval_request_id: request.id.to_string(),
+                chain_id: request.chain_id,
+                destination: request.recipient.to_string(),
+                metadata: approval_metadata(request, &snapshot.relay_private_key_hex),
+                network: Some(request.chain_id.to_string()),
+                reason: request.rejection_reason.clone(),
+                requested_at: format_time(request.created_at).unwrap_or_else(|_| now.clone()),
+                status: map_approval_status(request.status),
+                token_address: asset_token_address(&request.asset),
+                transaction_type: action_name(&request.action).to_string(),
+                updated_at: format_time(request.updated_at).unwrap_or_else(|_| now.clone()),
+            })
+            .collect(),
+    };
+
+    apply_daemon_auth(
+        client
+            .post(format!(
+                "{}/v1/daemon/register",
+                relay_url.trim_end_matches('/')
+            ))
+            .header(CONTENT_TYPE, "application/json")
+            .json(&request),
+    )
+    .send()
+    .await
+    .context("relay register request failed")?
+    .error_for_status()
+    .context("relay register request was rejected")?;
+
+    Ok(())
+}
+
+async fn poll_updates(
+    client: &Client,
+    relay_url: &str,
+    daemon_id: &str,
+) -> Result<RelayPollResponse> {
+    let response = apply_daemon_auth(
+        client
+            .post(format!(
+                "{}/v1/daemon/poll-updates",
+                relay_url.trim_end_matches('/')
+            ))
+            .header(CONTENT_TYPE, "application/json")
+            .json(&RelayPollRequest {
+                daemon_id,
+                lease_seconds: DEFAULT_RELAY_LEASE_SECONDS,
+                limit: DEFAULT_RELAY_POLL_LIMIT,
+            }),
+    )
+    .send()
+    .await
+    .context("relay poll request failed")?
+    .error_for_status()
+    .context("relay poll request was rejected")?;
+
+    response
+        .json::<RelayPollResponse>()
+        .await
+        .context("failed to deserialize relay poll response")
+}
+
+async fn submit_feedback(
+    client: &Client,
+    relay_url: &str,
+    claim_token: &str,
+    daemon_id: &str,
+    update_id: &str,
+    feedback: ProcessedFeedback,
+) -> Result<()> {
+    apply_daemon_auth(
+        client
+            .post(format!(
+                "{}/v1/daemon/submit-feedback",
+                relay_url.trim_end_matches('/')
+            ))
+            .header(CONTENT_TYPE, "application/json")
+            .json(&RelayFeedbackRequest {
+                claim_token,
+                daemon_id,
+                details: feedback.details,
+                message: feedback.message,
+                status: feedback.status,
+                update_id,
+            }),
+    )
+    .send()
+    .await
+    .context("relay feedback request failed")?
+    .error_for_status()
+    .context("relay feedback request was rejected")?;
+
+    Ok(())
+}
+
+async fn process_update<B>(
+    daemon: &InMemoryDaemon<B>,
+    expected_daemon_id: &str,
+    update: &RelayEncryptedUpdateRecord,
+) -> ProcessedFeedback
+where
+    B: VaultSignerBackend + Send + Sync + 'static,
+{
+    if update.daemon_id != expected_daemon_id {
+        return ProcessedFeedback {
+            details: None,
+            message: Some(format!(
+                "relay update daemon_id '{}' does not match '{}'",
+                update.daemon_id, expected_daemon_id
+            )),
+            status: "rejected",
+        };
+    }
+
+    if update.r#type != "manual_approval_decision" {
+        return ProcessedFeedback {
+            details: None,
+            message: Some(format!("unsupported relay update type '{}'", update.r#type)),
+            status: "failed",
+        };
+    }
+
+    let plaintext = match daemon.decrypt_relay_envelope(
+        &update.payload.algorithm,
+        &update.payload.encapsulated_key_base64,
+        &update.payload.nonce_base64,
+        &update.payload.ciphertext_base64,
+    ) {
+        Ok(value) => value,
+        Err(error) => {
+            return ProcessedFeedback {
+                details: None,
+                message: Some(error.to_string()),
+                status: "failed",
+            };
+        }
+    };
+
+    let payload = match serde_json::from_slice::<RelayManualApprovalUpdatePayload>(&plaintext) {
+        Ok(value) => value,
+        Err(error) => {
+            return ProcessedFeedback {
+                details: None,
+                message: Some(format!("invalid relay update payload: {error}")),
+                status: "failed",
+            };
+        }
+    };
+
+    if payload.daemon_id != expected_daemon_id {
+        return ProcessedFeedback {
+            details: None,
+            message: Some(format!(
+                "payload daemon_id '{}' does not match '{}'",
+                payload.daemon_id, expected_daemon_id
+            )),
+            status: "rejected",
+        };
+    }
+
+    if let Some(target_approval_request_id) = &update.target_approval_request_id {
+        if target_approval_request_id != &payload.approval_id {
+            return ProcessedFeedback {
+                details: None,
+                message: Some(format!(
+                    "payload approval_id '{}' does not match relay target '{}'",
+                    payload.approval_id, target_approval_request_id
+                )),
+                status: "rejected",
+            };
+        }
+    }
+
+    let approval_request_id = match Uuid::parse_str(&payload.approval_id) {
+        Ok(value) => value,
+        Err(error) => {
+            return ProcessedFeedback {
+                details: None,
+                message: Some(format!("approval_id is not a UUID: {error}")),
+                status: "failed",
+            };
+        }
+    };
+
+    let decision = match payload.decision {
+        RelayDecision::Approve => ManualApprovalDecision::Approve,
+        RelayDecision::Reject => ManualApprovalDecision::Reject,
+    };
+    let rejection_reason = if matches!(decision, ManualApprovalDecision::Reject) {
+        payload
+            .note
+            .clone()
+            .filter(|value| !value.trim().is_empty())
+    } else {
+        None
+    };
+
+    match daemon
+        .apply_relay_manual_approval_decision(
+            &payload.vault_password,
+            approval_request_id,
+            decision,
+            rejection_reason.clone(),
+        )
+        .await
+    {
+        Ok(request) => {
+            let mut details = BTreeMap::new();
+            details.insert("approvalRequestId".to_string(), request.id.to_string());
+            details.insert(
+                "manualApprovalStatus".to_string(),
+                map_approval_status(request.status).to_string(),
+            );
+            if let Some(note) = payload.note.filter(|value| !value.trim().is_empty()) {
+                details.insert("note".to_string(), note);
+            }
+            ProcessedFeedback {
+                details: Some(details),
+                message: Some(format!(
+                    "manual approval {} applied to {}",
+                    match decision {
+                        ManualApprovalDecision::Approve => "approve",
+                        ManualApprovalDecision::Reject => "reject",
+                    },
+                    request.id
+                )),
+                status: "applied",
+            }
+        }
+        Err(error) => ProcessedFeedback {
+            details: None,
+            message: Some(error.to_string()),
+            status: if matches!(decision, ManualApprovalDecision::Reject) {
+                "rejected"
+            } else {
+                "failed"
+            },
+        },
+    }
+}
+
+fn apply_daemon_auth(request: reqwest::RequestBuilder) -> reqwest::RequestBuilder {
+    let token = resolve_relay_daemon_token();
+    match token {
+        Some(token) => request.header("x-relay-daemon-token", token),
+        None => request,
+    }
+}
+
+fn resolve_relay_daemon_token() -> Option<String> {
+    resolve_relay_daemon_token_with(
+        |name| std::env::var(name).ok(),
+        |path| std::fs::read_to_string(path),
+    )
+}
+
+fn resolve_relay_daemon_token_with<Env, ReadFile>(
+    read_env: Env,
+    read_file: ReadFile,
+) -> Option<String>
+where
+    Env: Fn(&str) -> Option<String>,
+    ReadFile: Fn(&Path) -> std::io::Result<String>,
+{
+    if let Some(token) = read_env(RELAY_DAEMON_TOKEN_ENV).and_then(|value| normalize_secret(&value))
+    {
+        return Some(token);
+    }
+
+    let token_path = read_env(RELAY_DAEMON_TOKEN_FILE_ENV)?;
+    let trimmed_path = token_path.trim();
+    if trimmed_path.is_empty() {
+        return None;
+    }
+
+    read_file(Path::new(trimmed_path))
+        .ok()
+        .and_then(|value| normalize_secret(&value))
+}
+
+fn normalize_secret(value: &str) -> Option<String> {
+    let trimmed = value.trim();
+    (!trimmed.is_empty()).then(|| trimmed.to_string())
+}
+
+fn flatten_policy_records(
+    policies: &[SpendingPolicy],
+    updated_at: &str,
+) -> Vec<RelayPolicyPayload> {
+    let mut records = Vec::new();
+
+    for policy in policies.iter().filter(|policy| policy.enabled) {
+        let recipients = match &policy.recipients {
+            EntityScope::All => vec![(ZERO_ADDRESS.to_string(), "default")],
+            EntityScope::Set(values) => values
+                .iter()
+                .cloned()
+                .map(|value| (value.to_string(), "override"))
+                .collect::<Vec<_>>(),
+        };
+        let assets = match &policy.assets {
+            EntityScope::All => vec![None],
+            EntityScope::Set(values) => values.iter().cloned().map(Some).collect::<Vec<_>>(),
+        };
+        let networks = match &policy.networks {
+            EntityScope::All => vec![None],
+            EntityScope::Set(values) => values.iter().copied().map(Some).collect::<Vec<_>>(),
+        };
+
+        for (destination, scope) in &recipients {
+            for asset in &assets {
+                for chain_id in &networks {
+                    records.push(RelayPolicyPayload {
+                        action: policy_name(policy).to_string(),
+                        amount_max_wei: Some(policy.max_amount_wei.to_string()),
+                        amount_min_wei: policy.min_amount_wei.map(|value| value.to_string()),
+                        chain_id: *chain_id,
+                        destination: destination.clone(),
+                        metadata: Some(policy_metadata(policy, asset.as_ref(), *chain_id, scope)),
+                        policy_id: policy.id.to_string(),
+                        requires_manual_approval: matches!(
+                            policy.policy_type,
+                            PolicyType::ManualApproval
+                        ),
+                        scope,
+                        token_address: asset.as_ref().and_then(asset_token_address),
+                        updated_at: updated_at.to_string(),
+                    });
+                }
+            }
+        }
+    }
+
+    records
+}
+
+fn policy_metadata(
+    policy: &SpendingPolicy,
+    asset: Option<&AssetId>,
+    chain_id: Option<u64>,
+    scope: &str,
+) -> BTreeMap<String, String> {
+    let mut metadata = BTreeMap::new();
+    metadata.insert("policyType".to_string(), policy_name(policy).to_string());
+    metadata.insert("scope".to_string(), scope.to_string());
+    metadata.insert(
+        "recipientScope".to_string(),
+        match policy.recipients {
+            EntityScope::All => "all".to_string(),
+            EntityScope::Set(_) => "set".to_string(),
+        },
+    );
+    metadata.insert(
+        "assetScope".to_string(),
+        match policy.assets {
+            EntityScope::All => "all".to_string(),
+            EntityScope::Set(_) => "set".to_string(),
+        },
+    );
+    metadata.insert(
+        "networkScope".to_string(),
+        match policy.networks {
+            EntityScope::All => "all".to_string(),
+            EntityScope::Set(_) => "set".to_string(),
+        },
+    );
+    if let Some(asset) = asset {
+        metadata.insert("asset".to_string(), asset.to_string());
+    }
+    if let Some(chain_id) = chain_id {
+        metadata.insert("chainId".to_string(), chain_id.to_string());
+    }
+    metadata
+}
+
+fn approval_metadata(
+    request: &vault_domain::ManualApprovalRequest,
+    relay_private_key_hex: &str,
+) -> Option<BTreeMap<String, String>> {
+    let mut metadata = BTreeMap::new();
+    metadata.insert(
+        "triggeredPolicyIds".to_string(),
+        request
+            .triggered_by_policy_ids
+            .iter()
+            .map(Uuid::to_string)
+            .collect::<Vec<_>>()
+            .join(","),
+    );
+    metadata.insert("asset".to_string(), request.asset.to_string());
+    if matches!(request.status, ManualApprovalStatus::Pending) {
+        if let Ok(token) = manual_approval_capability_token(relay_private_key_hex, request.id) {
+            metadata.insert("approvalCapabilityToken".to_string(), token.clone());
+            if let Ok(hash) = manual_approval_capability_hash(&token) {
+                metadata.insert("approvalCapabilityHash".to_string(), hash);
+            }
+        }
+    }
+    Some(metadata)
+}
+
+fn policy_name(policy: &SpendingPolicy) -> &'static str {
+    match policy.policy_type {
+        PolicyType::DailyMaxSpending => "daily_max_spending",
+        PolicyType::DailyMaxTxCount => "daily_max_tx_count",
+        PolicyType::WeeklyMaxSpending => "weekly_max_spending",
+        PolicyType::PerTxMaxSpending => "per_tx_max_spending",
+        PolicyType::PerTxMaxFeePerGas => "per_tx_max_fee_per_gas",
+        PolicyType::PerTxMaxPriorityFeePerGas => "per_tx_max_priority_fee_per_gas",
+        PolicyType::PerTxMaxCalldataBytes => "per_tx_max_calldata_bytes",
+        PolicyType::PerChainMaxGasSpend => "per_chain_max_gas_spend",
+        PolicyType::ManualApproval => "manual_approval",
+    }
+}
+
+fn action_name(action: &AgentAction) -> &'static str {
+    match action {
+        AgentAction::Approve { .. } => "approve",
+        AgentAction::Transfer { .. } => "transfer",
+        AgentAction::TransferNative { .. } => "transfer_native",
+        AgentAction::Permit2Permit { .. } => "permit2_permit",
+        AgentAction::Eip3009TransferWithAuthorization { .. } => {
+            "eip3009_transfer_with_authorization"
+        }
+        AgentAction::Eip3009ReceiveWithAuthorization { .. } => "eip3009_receive_with_authorization",
+        AgentAction::BroadcastTx { .. } => "broadcast_tx",
+    }
+}
+
+fn asset_token_address(asset: &AssetId) -> Option<String> {
+    match asset {
+        AssetId::NativeEth => None,
+        AssetId::Erc20(token) => Some(token.to_string()),
+    }
+}
+
+fn map_approval_status(status: ManualApprovalStatus) -> &'static str {
+    match status {
+        ManualApprovalStatus::Pending => "pending",
+        ManualApprovalStatus::Approved => "approved",
+        ManualApprovalStatus::Rejected => "rejected",
+        ManualApprovalStatus::Completed => "completed",
+    }
+}
+
+fn format_time(value: OffsetDateTime) -> Result<String> {
+    value
+        .format(&Rfc3339)
+        .context("failed to format timestamp as RFC3339")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{approval_metadata, resolve_relay_daemon_token_with};
+    use std::collections::BTreeMap;
+    use std::fs;
+    use std::path::Path;
+    use std::time::{SystemTime, UNIX_EPOCH};
+    use time::OffsetDateTime;
+    use uuid::Uuid;
+    use vault_domain::{AgentAction, AssetId, ManualApprovalRequest, ManualApprovalStatus};
+
+    #[test]
+    fn approval_metadata_includes_admin_reissue_token_and_public_hash_for_pending_requests() {
+        let request = ManualApprovalRequest {
+            id: Uuid::parse_str("aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa").expect("uuid"),
+            agent_key_id: Uuid::nil(),
+            vault_key_id: Uuid::nil(),
+            request_payload_hash_hex: "11".repeat(32),
+            action: AgentAction::TransferNative {
+                chain_id: 56,
+                to: "0x2222222222222222222222222222222222222222"
+                    .parse()
+                    .expect("address"),
+                amount_wei: 1,
+            },
+            chain_id: 56,
+            asset: AssetId::NativeEth,
+            recipient: "0x2222222222222222222222222222222222222222"
+                .parse()
+                .expect("address"),
+            amount_wei: 1,
+            created_at: OffsetDateTime::UNIX_EPOCH,
+            updated_at: OffsetDateTime::UNIX_EPOCH,
+            status: ManualApprovalStatus::Pending,
+            triggered_by_policy_ids: vec![Uuid::nil()],
+            completed_at: None,
+            rejection_reason: None,
+        };
+
+        let metadata = approval_metadata(&request, &"11".repeat(32)).expect("metadata");
+        let token = metadata
+            .get("approvalCapabilityToken")
+            .expect("capability token");
+        let hash = metadata
+            .get("approvalCapabilityHash")
+            .expect("capability hash");
+
+        assert_eq!(token.len(), 64);
+        assert_eq!(hash.len(), 64);
+    }
+
+    fn temp_path(prefix: &str) -> std::path::PathBuf {
+        std::env::temp_dir().join(format!(
+            "{prefix}-{}-{}",
+            std::process::id(),
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .expect("system time before unix epoch")
+                .as_nanos()
+        ))
+    }
+
+    #[test]
+    fn resolve_relay_daemon_token_prefers_explicit_env_value() {
+        let env = BTreeMap::from([
+            (
+                "WLFI_RELAY_DAEMON_TOKEN".to_string(),
+                " env-token ".to_string(),
+            ),
+            (
+                "WLFI_RELAY_DAEMON_TOKEN_FILE".to_string(),
+                "/should/not/be/read".to_string(),
+            ),
+        ]);
+
+        let token = resolve_relay_daemon_token_with(
+            |name| env.get(name).cloned(),
+            |_path| -> std::io::Result<String> { panic!("file token should not be read") },
+        );
+
+        assert_eq!(token.as_deref(), Some("env-token"));
+    }
+
+    #[test]
+    fn resolve_relay_daemon_token_reads_root_only_file_path_when_env_token_is_absent() {
+        let token_path = temp_path("wlfi-relay-daemon-token");
+        fs::write(&token_path, " file-token \n").expect("write relay token file");
+        let env = BTreeMap::from([(
+            "WLFI_RELAY_DAEMON_TOKEN_FILE".to_string(),
+            token_path.display().to_string(),
+        )]);
+
+        let token = resolve_relay_daemon_token_with(
+            |name| env.get(name).cloned(),
+            |path| fs::read_to_string(path),
+        );
+
+        assert_eq!(token.as_deref(), Some("file-token"));
+        let _ = fs::remove_file(token_path);
+    }
+
+    #[test]
+    fn resolve_relay_daemon_token_ignores_blank_or_unreadable_sources() {
+        let env = BTreeMap::from([
+            ("WLFI_RELAY_DAEMON_TOKEN".to_string(), "   ".to_string()),
+            (
+                "WLFI_RELAY_DAEMON_TOKEN_FILE".to_string(),
+                "/missing/token-file".to_string(),
+            ),
+        ]);
+
+        let token = resolve_relay_daemon_token_with(
+            |name| env.get(name).cloned(),
+            |_path: &Path| Err(std::io::Error::from(std::io::ErrorKind::NotFound)),
+        );
+
+        assert_eq!(token, None);
+    }
+}