@wlfi-agent/cli 1.4.13 → 1.4.14

package/crates/vault-daemon/src/daemon_parts/core_helpers.rs

@@ -0,0 +1,1256 @@
+#[derive(Debug, Clone, Default)]
+struct AdminAuthState {
+    failed_attempts: u32,
+    locked_until: Option<OffsetDateTime>,
+}
+
+enum ManualApprovalResolution {
+    Approved(Option<Uuid>),
+    Pending {
+        approval_request_id: Uuid,
+        relay_config: RelayConfig,
+    },
+    Rejected(Uuid),
+}
+
+pub struct InMemoryDaemon<B>
+where
+    B: VaultSignerBackend,
+{
+    signer_backend: B,
+    policy_engine: PolicyEngine,
+    admin_password_hash: String,
+    config: DaemonConfig,
+    leases: Arc<RwLock<HashMap<Uuid, Lease>>>,
+    policies: Arc<RwLock<HashMap<Uuid, SpendingPolicy>>>,
+    vault_keys: Arc<RwLock<HashMap<Uuid, VaultKey>>>,
+    agent_keys: Arc<RwLock<HashMap<Uuid, AgentKey>>>,
+    agent_auth_tokens: Arc<RwLock<HashMap<Uuid, [u8; 32]>>>,
+    replay_ids: Arc<RwLock<HashMap<Uuid, OffsetDateTime>>>,
+    nonce_heads: Arc<RwLock<HashMap<Uuid, HashMap<u64, u64>>>>,
+    nonce_reservations: Arc<RwLock<HashMap<Uuid, NonceReservation>>>,
+    spend_log: Arc<RwLock<Vec<SpendEvent>>>,
+    manual_approval_requests: Arc<RwLock<HashMap<Uuid, ManualApprovalRequest>>>,
+    relay_config: Arc<RwLock<RelayConfig>>,
+    relay_private_key_hex: Arc<RwLock<String>>,
+    admin_auth_state: Arc<RwLock<AdminAuthState>>,
+    state_store: Option<EncryptedStateStore>,
+    signing_guard: tokio::sync::Mutex<()>,
+    state_persist_guard: tokio::sync::Mutex<()>,
+}
+
+impl<B> InMemoryDaemon<B>
+where
+    B: VaultSignerBackend,
+{
+    /// Builds daemon and hashes admin password using Argon2.
+    pub fn new(
+        admin_password: &str,
+        signer_backend: B,
+        config: DaemonConfig,
+    ) -> Result<Self, DaemonError> {
+        validate_config(&config)?;
+        validate_admin_password(admin_password)?;
+        let admin_password_hash = hash_password(admin_password, &config)?;
+        Self::new_with_loaded_state(
+            signer_backend,
+            admin_password_hash,
+            config,
+            PersistedDaemonState::default(),
+            None,
+        )
+    }
+
+    /// Builds daemon with encrypted persistent state on local filesystem.
+    pub fn new_with_persistent_store(
+        admin_password: &str,
+        signer_backend: B,
+        config: DaemonConfig,
+        store_config: PersistentStoreConfig,
+    ) -> Result<Self, DaemonError> {
+        validate_config(&config)?;
+        validate_admin_password(admin_password)?;
+        let admin_password_hash = hash_password(admin_password, &config)?;
+        let (state_store, state) =
+            EncryptedStateStore::open_or_initialize(admin_password, &config, store_config)
+                .map_err(DaemonError::Persistence)?;
+        Self::new_with_loaded_state(
+            signer_backend,
+            admin_password_hash,
+            config,
+            state,
+            Some(state_store),
+        )
+    }
+
+    fn new_with_loaded_state(
+        signer_backend: B,
+        admin_password_hash: String,
+        config: DaemonConfig,
+        mut state: PersistedDaemonState,
+        state_store: Option<EncryptedStateStore>,
+    ) -> Result<Self, DaemonError> {
+        ensure_relay_identity(&mut state);
+        validate_loaded_state(&state)?;
+        signer_backend
+            .restore_persistable_key_material(&state.software_signer_private_keys)
+            .map_err(DaemonError::Signer)?;
+        Ok(Self {
+            signer_backend,
+            policy_engine: PolicyEngine,
+            admin_password_hash,
+            config,
+            leases: Arc::new(RwLock::new(state.leases)),
+            policies: Arc::new(RwLock::new(state.policies)),
+            vault_keys: Arc::new(RwLock::new(state.vault_keys)),
+            agent_keys: Arc::new(RwLock::new(state.agent_keys)),
+            agent_auth_tokens: Arc::new(RwLock::new(state.agent_auth_tokens)),
+            replay_ids: Arc::new(RwLock::new(state.replay_ids)),
+            nonce_heads: Arc::new(RwLock::new(state.nonce_heads)),
+            nonce_reservations: Arc::new(RwLock::new(state.nonce_reservations)),
+            spend_log: Arc::new(RwLock::new(state.spend_log)),
+            manual_approval_requests: Arc::new(RwLock::new(state.manual_approval_requests)),
+            relay_config: Arc::new(RwLock::new(state.relay_config)),
+            relay_private_key_hex: Arc::new(RwLock::new(state.relay_private_key_hex)),
+            admin_auth_state: Arc::new(RwLock::new(AdminAuthState::default())),
+            state_store,
+            signing_guard: tokio::sync::Mutex::new(()),
+            state_persist_guard: tokio::sync::Mutex::new(()),
+        })
+    }
+
+    /// Handles a serialized daemon RPC call.
+    pub async fn handle_rpc(
+        &self,
+        request: DaemonRpcRequest,
+    ) -> Result<DaemonRpcResponse, DaemonError> {
+        match request {
+            DaemonRpcRequest::IssueLease { vault_password } => {
+                let mut vault_password = vault_password;
+                let result = async {
+                    Ok(DaemonRpcResponse::Lease(
+                        self.issue_lease(&vault_password).await?,
+                    ))
+                }
+                .await;
+                vault_password.zeroize();
+                result
+            }
+            DaemonRpcRequest::AddPolicy { session, policy } => {
+                let mut session = session;
+                let result = async {
+                    self.add_policy(&session, policy).await?;
+                    Ok(DaemonRpcResponse::Unit)
+                }
+                .await;
+                session.zeroize_secrets();
+                result
+            }
+            DaemonRpcRequest::ListPolicies { session } => {
+                let mut session = session;
+                let result = async {
+                    Ok(DaemonRpcResponse::Policies(
+                        self.list_policies(&session).await?,
+                    ))
+                }
+                .await;
+                session.zeroize_secrets();
+                result
+            }
+            DaemonRpcRequest::DisablePolicy { session, policy_id } => {
+                let mut session = session;
+                let result = async {
+                    self.disable_policy(&session, policy_id).await?;
+                    Ok(DaemonRpcResponse::Unit)
+                }
+                .await;
+                session.zeroize_secrets();
+                result
+            }
+            DaemonRpcRequest::CreateVaultKey { session, request } => {
+                let mut session = session;
+                let result = async {
+                    Ok(DaemonRpcResponse::VaultKey(
+                        self.create_vault_key(&session, request).await?,
+                    ))
+                }
+                .await;
+                session.zeroize_secrets();
+                result
+            }
+            DaemonRpcRequest::CreateAgentKey {
+                session,
+                vault_key_id,
+                attachment,
+            } => {
+                let mut session = session;
+                let result = async {
+                    Ok(DaemonRpcResponse::AgentCredentials(
+                        self.create_agent_key(&session, vault_key_id, attachment)
+                            .await?,
+                    ))
+                }
+                .await;
+                session.zeroize_secrets();
+                result
+            }
+            DaemonRpcRequest::ExportVaultPrivateKey {
+                session,
+                vault_key_id,
+            } => {
+                let mut session = session;
+                let result = async {
+                    Ok(DaemonRpcResponse::PrivateKey(
+                        self.export_vault_private_key(&session, vault_key_id).await?,
+                    ))
+                }
+                .await;
+                session.zeroize_secrets();
+                result
+            }
+            DaemonRpcRequest::RotateAgentAuthToken {
+                session,
+                agent_key_id,
+            } => {
+                let mut session = session;
+                let result = async {
+                    Ok(DaemonRpcResponse::AuthToken(
+                        self.rotate_agent_auth_token(&session, agent_key_id).await?,
+                    ))
+                }
+                .await;
+                session.zeroize_secrets();
+                result
+            }
+            DaemonRpcRequest::RevokeAgentKey {
+                session,
+                agent_key_id,
+            } => {
+                let mut session = session;
+                let result = async {
+                    self.revoke_agent_key(&session, agent_key_id).await?;
+                    Ok(DaemonRpcResponse::Unit)
+                }
+                .await;
+                session.zeroize_secrets();
+                result
+            }
+            DaemonRpcRequest::ListManualApprovalRequests { session } => {
+                let mut session = session;
+                let result = async {
+                    Ok(DaemonRpcResponse::ManualApprovalRequests(
+                        self.list_manual_approval_requests(&session).await?,
+                    ))
+                }
+                .await;
+                session.zeroize_secrets();
+                result
+            }
+            DaemonRpcRequest::DecideManualApprovalRequest {
+                session,
+                approval_request_id,
+                decision,
+                rejection_reason,
+            } => {
+                let mut session = session;
+                let result = async {
+                    Ok(DaemonRpcResponse::ManualApprovalRequest(
+                        self.decide_manual_approval_request(
+                            &session,
+                            approval_request_id,
+                            decision,
+                            rejection_reason,
+                        )
+                        .await?,
+                    ))
+                }
+                .await;
+                session.zeroize_secrets();
+                result
+            }
+            DaemonRpcRequest::SetRelayConfig {
+                session,
+                relay_url,
+                frontend_url,
+            } => {
+                let mut session = session;
+                let result = async {
+                    Ok(DaemonRpcResponse::RelayConfig(
+                        self.set_relay_config(&session, relay_url, frontend_url)
+                            .await?,
+                    ))
+                }
+                .await;
+                session.zeroize_secrets();
+                result
+            }
+            DaemonRpcRequest::GetRelayConfig { session } => {
+                let mut session = session;
+                let result = async {
+                    Ok(DaemonRpcResponse::RelayConfig(
+                        self.get_relay_config(&session).await?,
+                    ))
+                }
+                .await;
+                session.zeroize_secrets();
+                result
+            }
+            DaemonRpcRequest::EvaluateForAgent { request } => Ok(
+                DaemonRpcResponse::PolicyEvaluation(self.evaluate_for_agent(request).await?),
+            ),
+            DaemonRpcRequest::ExplainForAgent { request } => Ok(
+                DaemonRpcResponse::PolicyExplanation(self.explain_for_agent(request).await?),
+            ),
+            DaemonRpcRequest::ReserveNonce { request } => Ok(DaemonRpcResponse::NonceReservation(
+                self.reserve_nonce(request).await?,
+            )),
+            DaemonRpcRequest::ReleaseNonce { request } => {
+                self.release_nonce(request).await?;
+                Ok(DaemonRpcResponse::Unit)
+            }
+            DaemonRpcRequest::SignForAgent { request } => Ok(DaemonRpcResponse::Signature(
+                self.sign_for_agent(request).await?,
+            )),
+        }
+    }
+
+    fn authenticate(&self, session: &AdminSession, now: OffsetDateTime) -> Result<(), DaemonError> {
+        self.authenticate_password(&session.vault_password)?;
+
+        let lease = self
+            .leases
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .get(&session.lease.lease_id)
+            .cloned()
+            .ok_or(DaemonError::UnknownLease)?;
+
+        if !lease.is_valid_at(now) {
+            return Err(DaemonError::InvalidLease);
+        }
+
+        Ok(())
+    }
+
+    fn authenticate_password(&self, vault_password: &str) -> Result<(), DaemonError> {
+        let now = OffsetDateTime::now_utc();
+        self.enforce_admin_auth_lockout(now)?;
+
+        if vault_password.as_bytes().len() > MAX_AUTH_SECRET_BYTES {
+            self.record_failed_admin_auth(now)?;
+            return Err(DaemonError::AuthenticationFailed);
+        }
+
+        let parsed = PasswordHash::new(&self.admin_password_hash)
+            .map_err(|err| DaemonError::PasswordHash(format!("invalid hash in memory: {err}")))?;
+
+        let verification_result = Argon2::default()
+            .verify_password(vault_password.as_bytes(), &parsed)
+            .map_err(|_| DaemonError::AuthenticationFailed);
+
+        match verification_result {
+            Ok(()) => {
+                self.reset_admin_auth_state()?;
+                Ok(())
+            }
+            Err(err) => {
+                self.record_failed_admin_auth(now)?;
+                Err(err)
+            }
+        }
+    }
+
+    fn enforce_admin_auth_lockout(&self, now: OffsetDateTime) -> Result<(), DaemonError> {
+        let mut state = self
+            .admin_auth_state
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)?;
+
+        if let Some(locked_until) = state.locked_until {
+            if locked_until > now {
+                return Err(DaemonError::AuthenticationFailed);
+            }
+            state.locked_until = None;
+            state.failed_attempts = 0;
+        }
+
+        Ok(())
+    }
+
+    fn reset_admin_auth_state(&self) -> Result<(), DaemonError> {
+        let mut state = self
+            .admin_auth_state
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)?;
+        state.failed_attempts = 0;
+        state.locked_until = None;
+        Ok(())
+    }
+
+    fn record_failed_admin_auth(&self, now: OffsetDateTime) -> Result<(), DaemonError> {
+        let mut state = self
+            .admin_auth_state
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)?;
+
+        if let Some(locked_until) = state.locked_until {
+            if locked_until > now {
+                return Ok(());
+            }
+            state.locked_until = None;
+            state.failed_attempts = 0;
+        }
+
+        state.failed_attempts = state.failed_attempts.saturating_add(1);
+        if state.failed_attempts >= self.config.max_failed_admin_auth_attempts {
+            state.failed_attempts = 0;
+            state.locked_until = Some(now.checked_add(self.config.admin_auth_lockout).ok_or_else(
+                || {
+                    DaemonError::InvalidConfig(
+                        "admin_auth_lockout causes timestamp overflow".to_string(),
+                    )
+                },
+            )?);
+        }
+
+        Ok(())
+    }
+
+    fn validate_request_timestamps(
+        &self,
+        requested_at: OffsetDateTime,
+        expires_at: OffsetDateTime,
+        now: OffsetDateTime,
+    ) -> Result<(), DaemonError> {
+        if expires_at <= now {
+            return Err(DaemonError::RequestExpired);
+        }
+        if expires_at <= requested_at {
+            return Err(DaemonError::InvalidRequestTimestamps);
+        }
+        if requested_at > now + self.config.max_request_clock_skew {
+            return Err(DaemonError::InvalidRequestTimestamps);
+        }
+        let ttl = expires_at - requested_at;
+        if ttl > self.config.max_request_ttl {
+            return Err(DaemonError::InvalidRequestTimestamps);
+        }
+        Ok(())
+    }
+
+    fn authenticate_agent(
+        &self,
+        agent_key_id: Uuid,
+        agent_auth_token: &str,
+    ) -> Result<AgentKey, DaemonError> {
+        if agent_auth_token.as_bytes().len() > MAX_AUTH_SECRET_BYTES {
+            return Err(DaemonError::AgentAuthenticationFailed);
+        }
+
+        let expected_auth_hash = self
+            .agent_auth_tokens
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .get(&agent_key_id)
+            .copied()
+            .ok_or(DaemonError::AgentAuthenticationFailed)?;
+        let presented_auth_hash = hash_agent_auth_token(agent_auth_token);
+        if !constant_time_eq(&expected_auth_hash, &presented_auth_hash) {
+            return Err(DaemonError::AgentAuthenticationFailed);
+        }
+
+        self.agent_keys
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .get(&agent_key_id)
+            .cloned()
+            .ok_or(DaemonError::AgentAuthenticationFailed)
+    }
+
+    fn explain_authorized_request(
+        &self,
+        request: &SignRequest,
+        now: OffsetDateTime,
+    ) -> Result<(AgentKey, AgentAction, PolicyExplanation), DaemonError> {
+        self.validate_request_timestamps(request.requested_at, request.expires_at, now)?;
+        if request.payload.len() > self.config.max_sign_payload_bytes {
+            return Err(DaemonError::PayloadTooLarge {
+                max_bytes: self.config.max_sign_payload_bytes,
+            });
+        }
+
+        let agent_key = self.authenticate_agent(request.agent_key_id, &request.agent_auth_token)?;
+
+        let payload_action: AgentAction = serde_json::from_slice(&request.payload)
+            .map_err(|_| DaemonError::PayloadActionMismatch)?;
+        payload_action
+            .validate()
+            .map_err(|_| DaemonError::PayloadActionMismatch)?;
+        if payload_action != request.action {
+            return Err(DaemonError::PayloadActionMismatch);
+        }
+        let canonical_payload =
+            serde_json::to_vec(&request.action).map_err(|_| DaemonError::PayloadActionMismatch)?;
+        if request.payload != canonical_payload {
+            return Err(DaemonError::PayloadActionMismatch);
+        }
+
+        let policies: Vec<SpendingPolicy> = self
+            .policies
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .values()
+            .cloned()
+            .collect();
+
+        let retention_start = now - Duration::days(8);
+        let spend_history: Vec<SpendEvent> = self
+            .spend_log
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .iter()
+            .filter(|event| event.at >= retention_start)
+            .cloned()
+            .collect();
+
+        let policy_explanation = self.policy_engine.explain(
+            &policies,
+            &agent_key.policies,
+            &payload_action,
+            &spend_history,
+            request.agent_key_id,
+            now,
+        );
+
+        Ok((agent_key, payload_action, policy_explanation))
+    }
+
+    fn evaluate_authorized_request(
+        &self,
+        request: &SignRequest,
+        now: OffsetDateTime,
+    ) -> Result<(AgentKey, AgentAction, PolicyEvaluation), DaemonError> {
+        let (agent_key, payload_action, policy_explanation) =
+            self.explain_authorized_request(request, now)?;
+        match policy_explanation.decision {
+            PolicyDecision::Allow => Ok((
+                agent_key,
+                payload_action,
+                PolicyEvaluation {
+                    evaluated_policy_ids: policy_explanation.evaluated_policy_ids,
+                },
+            )),
+            PolicyDecision::Deny(err) => Err(DaemonError::Policy(err)),
+        }
+    }
+
+    fn prune_replay_ids(&self, now: OffsetDateTime) -> Result<(), DaemonError> {
+        self.replay_ids
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .retain(|_, expires_at| *expires_at > now);
+        Ok(())
+    }
+
+    fn register_replay_id(
+        &self,
+        request_id: Uuid,
+        expires_at: OffsetDateTime,
+        now: OffsetDateTime,
+    ) -> Result<(), DaemonError> {
+        self.prune_replay_ids(now)?;
+        let mut replay_ids = self
+            .replay_ids
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)?;
+        if replay_ids.contains_key(&request_id) {
+            return Err(DaemonError::RequestReplayDetected);
+        }
+        replay_ids.insert(request_id, expires_at);
+        Ok(())
+    }
+
+    fn prune_nonce_reservations(&self, now: OffsetDateTime) -> Result<(), DaemonError> {
+        let removed = {
+            let mut reservations = self
+                .nonce_reservations
+                .write()
+                .map_err(|_| DaemonError::LockPoisoned)?;
+            let removed = reservations
+                .values()
+                .filter(|reservation| reservation.expires_at <= now)
+                .cloned()
+                .collect::<Vec<_>>();
+            reservations.retain(|_, reservation| reservation.expires_at > now);
+            removed
+        };
+        self.reclaim_unused_nonce_heads(&removed)?;
+        Ok(())
+    }
+
+    fn reclaim_unused_nonce_heads(
+        &self,
+        removed: &[NonceReservation],
+    ) -> Result<(), DaemonError> {
+        if removed.is_empty() {
+            return Ok(());
+        }
+
+        let mut removed_by_scope = HashMap::<(Uuid, u64), std::collections::BTreeSet<u64>>::new();
+        for reservation in removed {
+            removed_by_scope
+                .entry((reservation.vault_key_id, reservation.chain_id))
+                .or_default()
+                .insert(reservation.nonce);
+        }
+
+        let mut nonce_heads = self
+            .nonce_heads
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)?;
+        for ((vault_key_id, chain_id), removed_nonces) in removed_by_scope {
+            let Some(chain_heads) = nonce_heads.get_mut(&vault_key_id) else {
+                continue;
+            };
+            let Some(head) = chain_heads.get_mut(&chain_id) else {
+                continue;
+            };
+
+            while *head > 0 {
+                let candidate = *head - 1;
+                if removed_nonces.contains(&candidate) {
+                    *head = candidate;
+                } else {
+                    break;
+                }
+            }
+        }
+        Ok(())
+    }
+
+    fn consume_nonce_reservation(
+        &self,
+        agent_key_id: Uuid,
+        vault_key_id: Uuid,
+        chain_id: u64,
+        nonce: u64,
+        now: OffsetDateTime,
+    ) -> Result<(), DaemonError> {
+        self.prune_nonce_reservations(now)?;
+        let mut reservations = self
+            .nonce_reservations
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)?;
+        let reservation_id = reservations
+            .iter()
+            .find_map(|(reservation_id, reservation)| {
+                if reservation.agent_key_id == agent_key_id
+                    && reservation.vault_key_id == vault_key_id
+                    && reservation.chain_id == chain_id
+                    && reservation.nonce == nonce
+                {
+                    Some(*reservation_id)
+                } else {
+                    None
+                }
+            })
+            .ok_or(DaemonError::MissingNonceReservation { chain_id, nonce })?;
+        reservations.remove(&reservation_id);
+        Ok(())
+    }
+
+    fn resolve_manual_approval_request(
+        &self,
+        agent_key: &AgentKey,
+        payload_action: &AgentAction,
+        payload_hash: &str,
+        triggered_by_policy_ids: Vec<Uuid>,
+        now: OffsetDateTime,
+    ) -> Result<ManualApprovalResolution, DaemonError> {
+        let relay_config = self
+            .relay_config
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .clone();
+        let mut requests = self
+            .manual_approval_requests
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)?;
+
+        let existing = requests
+            .values()
+            .filter(|existing| {
+                existing.agent_key_id == agent_key.id
+                    && existing.request_payload_hash_hex == payload_hash
+                    && existing.status != ManualApprovalStatus::Completed
+            })
+            .max_by(|left, right| left.created_at.cmp(&right.created_at))
+            .cloned();
+
+        if let Some(existing) = existing {
+            return Ok(match existing.status {
+                ManualApprovalStatus::Approved => {
+                    ManualApprovalResolution::Approved(Some(existing.id))
+                }
+                ManualApprovalStatus::Pending => ManualApprovalResolution::Pending {
+                    approval_request_id: existing.id,
+                    relay_config,
+                },
+                ManualApprovalStatus::Rejected => ManualApprovalResolution::Rejected(existing.id),
+                ManualApprovalStatus::Completed => ManualApprovalResolution::Approved(None),
+            });
+        }
+
+        let approval_request_id = Uuid::new_v4();
+        requests.insert(
+            approval_request_id,
+            ManualApprovalRequest {
+                id: approval_request_id,
+                agent_key_id: agent_key.id,
+                vault_key_id: agent_key.vault_key_id,
+                request_payload_hash_hex: payload_hash.to_string(),
+                action: payload_action.clone(),
+                chain_id: payload_action.chain_id(),
+                asset: payload_action.asset(),
+                recipient: payload_action.recipient(),
+                amount_wei: payload_action.amount_wei(),
+                created_at: now,
+                updated_at: now,
+                status: ManualApprovalStatus::Pending,
+                triggered_by_policy_ids,
+                completed_at: None,
+                rejection_reason: None,
+            },
+        );
+
+        Ok(ManualApprovalResolution::Pending {
+            approval_request_id,
+            relay_config,
+        })
+    }
+
+    fn complete_manual_approval_request(
+        &self,
+        approval_request_id: Uuid,
+        now: OffsetDateTime,
+    ) -> Result<(), DaemonError> {
+        let mut requests = self
+            .manual_approval_requests
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)?;
+        let request = requests.get_mut(&approval_request_id).ok_or(
+            DaemonError::UnknownManualApprovalRequest(approval_request_id),
+        )?;
+        request.status = ManualApprovalStatus::Completed;
+        request.updated_at = now;
+        request.completed_at = Some(now);
+        Ok(())
+    }
+
+    pub fn relay_registration_snapshot(&self) -> Result<RelayRegistrationSnapshot, DaemonError> {
+        let relay_config = self
+            .relay_config
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .clone();
+        let policies = self
+            .policies
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .values()
+            .cloned()
+            .collect::<Vec<_>>();
+        let agent_keys = self
+            .agent_keys
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .values()
+            .cloned()
+            .collect::<Vec<_>>();
+        let manual_approval_requests = self
+            .manual_approval_requests
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .values()
+            .cloned()
+            .collect::<Vec<_>>();
+        let latest_vault_key = self
+            .vault_keys
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .values()
+            .cloned()
+            .max_by(|left, right| left.created_at.cmp(&right.created_at));
+        let vault_public_key_hex = latest_vault_key
+            .as_ref()
+            .map(|key| key.public_key_hex.clone());
+        let ethereum_address = latest_vault_key
+            .as_ref()
+            .map(|key| ethereum_address_from_public_key_hex(&key.public_key_hex))
+            .transpose()?;
+
+        Ok(RelayRegistrationSnapshot {
+            relay_config,
+            relay_private_key_hex: self
+                .relay_private_key_hex
+                .read()
+                .map_err(|_| DaemonError::LockPoisoned)?
+                .clone(),
+            vault_public_key_hex,
+            ethereum_address,
+            policies,
+            agent_keys,
+            manual_approval_requests,
+        })
+    }
+
+    pub async fn apply_relay_manual_approval_decision(
+        &self,
+        vault_password: &str,
+        approval_request_id: Uuid,
+        decision: ManualApprovalDecision,
+        rejection_reason: Option<String>,
+    ) -> Result<ManualApprovalRequest, DaemonError> {
+        let lease = self.issue_lease(vault_password).await?;
+        let session = AdminSession {
+            vault_password: vault_password.to_string(),
+            lease,
+        };
+        self.decide_manual_approval_request(
+            &session,
+            approval_request_id,
+            decision,
+            rejection_reason,
+        )
+        .await
+    }
+
+    pub fn decrypt_relay_envelope(
+        &self,
+        algorithm: &str,
+        encapsulated_key_hex: &str,
+        nonce_hex: &str,
+        ciphertext_hex: &str,
+    ) -> Result<Vec<u8>, DaemonError> {
+        use chacha20poly1305::aead::Aead;
+        use chacha20poly1305::{KeyInit, XChaCha20Poly1305};
+
+        if algorithm.trim() != "x25519-xchacha20poly1305-v1" {
+            return Err(DaemonError::InvalidRelayConfig(format!(
+                "unsupported relay encryption algorithm: {algorithm}"
+            )));
+        }
+
+        let private_key_hex = self
+            .relay_private_key_hex
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .clone();
+        let private_key_bytes = hex::decode(private_key_hex.trim().trim_start_matches("0x"))
+            .map_err(|err| {
+                DaemonError::InvalidRelayConfig(format!("relay private key is invalid hex: {err}"))
+            })?;
+        if private_key_bytes.len() != 32 {
+            return Err(DaemonError::InvalidRelayConfig(
+                "relay private key must be 32 bytes".to_string(),
+            ));
+        }
+        let encapsulated_key = hex::decode(encapsulated_key_hex.trim().trim_start_matches("0x"))
+            .map_err(|err| {
+                DaemonError::InvalidRelayConfig(format!(
+                    "relay encapsulated key is invalid hex: {err}"
+                ))
+            })?;
+        if encapsulated_key.len() != 32 {
+            return Err(DaemonError::InvalidRelayConfig(
+                "relay encapsulated key must be 32 bytes".to_string(),
+            ));
+        }
+        let nonce = hex::decode(nonce_hex.trim().trim_start_matches("0x")).map_err(|err| {
+            DaemonError::InvalidRelayConfig(format!("relay nonce is invalid hex: {err}"))
+        })?;
+        if nonce.len() != 24 {
+            return Err(DaemonError::InvalidRelayConfig(
+                "relay nonce must be 24 bytes".to_string(),
+            ));
+        }
+        let ciphertext =
+            hex::decode(ciphertext_hex.trim().trim_start_matches("0x")).map_err(|err| {
+                DaemonError::InvalidRelayConfig(format!("relay ciphertext is invalid hex: {err}"))
+            })?;
+
+        let mut private_key = [0u8; 32];
+        private_key.copy_from_slice(&private_key_bytes);
+        let mut peer_public = [0u8; 32];
+        peer_public.copy_from_slice(&encapsulated_key);
+        let secret = x25519_dalek::StaticSecret::from(private_key);
+        let peer = x25519_dalek::PublicKey::from(peer_public);
+        let shared_secret = secret.diffie_hellman(&peer);
+        let cipher = XChaCha20Poly1305::new(shared_secret.as_bytes().into());
+
+        cipher
+            .decrypt(
+                chacha20poly1305::XNonce::from_slice(&nonce),
+                ciphertext.as_ref(),
+            )
+            .map_err(|_| {
+                DaemonError::InvalidRelayConfig(
+                    "failed to decrypt relay update payload".to_string(),
+                )
+            })
+    }
+
+    fn snapshot_state(&self) -> Result<PersistedDaemonState, DaemonError> {
+        let leases = self
+            .leases
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .clone();
+        let policies = self
+            .policies
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .clone();
+        let vault_keys = self
+            .vault_keys
+            .read()
+            .map_err(|_| DaemonError::LockPoisoned)?
+            .clone();
+        let vault_key_ids = vault_keys.keys().copied().collect::<Vec<_>>();
+        let software_signer_private_keys = self
+            .signer_backend
+            .export_persistable_key_material(&vault_key_ids)
+            .map_err(DaemonError::Signer)?;
+
+        Ok(PersistedDaemonState {
+            leases,
+            policies,
+            vault_keys,
+            software_signer_private_keys,
+            agent_keys: self
+                .agent_keys
+                .read()
+                .map_err(|_| DaemonError::LockPoisoned)?
+                .clone(),
+            agent_auth_tokens: self
+                .agent_auth_tokens
+                .read()
+                .map_err(|_| DaemonError::LockPoisoned)?
+                .clone(),
+            replay_ids: self
+                .replay_ids
+                .read()
+                .map_err(|_| DaemonError::LockPoisoned)?
+                .clone(),
+            nonce_heads: self
+                .nonce_heads
+                .read()
+                .map_err(|_| DaemonError::LockPoisoned)?
+                .clone(),
+            nonce_reservations: self
+                .nonce_reservations
+                .read()
+                .map_err(|_| DaemonError::LockPoisoned)?
+                .clone(),
+            spend_log: self
+                .spend_log
+                .read()
+                .map_err(|_| DaemonError::LockPoisoned)?
+                .clone(),
+            manual_approval_requests: self
+                .manual_approval_requests
+                .read()
+                .map_err(|_| DaemonError::LockPoisoned)?
+                .clone(),
+            relay_config: self
+                .relay_config
+                .read()
+                .map_err(|_| DaemonError::LockPoisoned)?
+                .clone(),
+            relay_private_key_hex: self
+                .relay_private_key_hex
+                .read()
+                .map_err(|_| DaemonError::LockPoisoned)?
+                .clone(),
+        })
+    }
+
+    fn restore_state(&self, snapshot: PersistedDaemonState) -> Result<(), DaemonError> {
+        let PersistedDaemonState {
+            leases,
+            policies,
+            vault_keys,
+            software_signer_private_keys,
+            agent_keys,
+            agent_auth_tokens,
+            replay_ids,
+            nonce_heads,
+            nonce_reservations,
+            spend_log,
+            manual_approval_requests,
+            relay_config,
+            relay_private_key_hex,
+        } = snapshot;
+        self.signer_backend
+            .restore_persistable_key_material(&software_signer_private_keys)
+            .map_err(DaemonError::Signer)?;
+        *self.leases.write().map_err(|_| DaemonError::LockPoisoned)? = leases;
+        *self
+            .policies
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)? = policies;
+        *self
+            .vault_keys
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)? = vault_keys;
+        *self
+            .agent_keys
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)? = agent_keys;
+        *self
+            .agent_auth_tokens
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)? = agent_auth_tokens;
+        *self
+            .replay_ids
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)? = replay_ids;
+        *self
+            .nonce_heads
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)? = nonce_heads;
+        *self
+            .nonce_reservations
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)? = nonce_reservations;
+        *self
+            .spend_log
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)? = spend_log;
+        *self
+            .manual_approval_requests
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)? = manual_approval_requests;
+        *self
+            .relay_config
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)? = relay_config;
+        *self
+            .relay_private_key_hex
+            .write()
+            .map_err(|_| DaemonError::LockPoisoned)? = relay_private_key_hex;
+        Ok(())
+    }
+
+    fn backup_state_if_persistent(&self) -> Result<Option<PersistedDaemonState>, DaemonError> {
+        if self.state_store.is_none() {
+            return Ok(None);
+        }
+        Ok(Some(self.snapshot_state()?))
+    }
+
+    fn persist_state_if_enabled(&self) -> Result<(), DaemonError> {
+        let Some(store) = &self.state_store else {
+            return Ok(());
+        };
+        let snapshot = self.snapshot_state()?;
+        store.save(&snapshot).map_err(DaemonError::Persistence)
+    }
+
+    fn persist_or_revert(&self, backup: Option<PersistedDaemonState>) -> Result<(), DaemonError> {
+        match self.persist_state_if_enabled() {
+            Ok(()) => Ok(()),
+            Err(err) => {
+                if let Some(snapshot) = backup {
+                    self.restore_state(snapshot)?;
+                }
+                Err(err)
+            }
+        }
+    }
+
+    async fn sign_typed_data_action(
+        &self,
+        vault_key: &VaultKey,
+        action: &AgentAction,
+    ) -> Result<Signature, DaemonError> {
+        let digest = action
+            .signing_hash()
+            .map_err(map_domain_to_signer_error)?
+            .ok_or_else(|| {
+                DaemonError::Signer(SignerError::Unsupported(
+                    "action does not produce an eip-712 signing digest".to_string(),
+                ))
+            })?;
+        self.sign_digest_with_recovery(vault_key, digest, "typed-data signing")
+            .await
+    }
+
+    async fn sign_digest_with_recovery(
+        &self,
+        vault_key: &VaultKey,
+        digest_bytes: [u8; 32],
+        operation: &str,
+    ) -> Result<Signature, DaemonError> {
+        let der_signature = self
+            .signer_backend
+            .sign_digest(vault_key.id, digest_bytes)
+            .await?;
+
+        let parsed = K256Signature::from_der(&der_signature.bytes).map_err(|err| {
+            DaemonError::Signer(SignerError::Internal(format!(
+                "backend returned invalid DER signature for {operation}: {err}"
+            )))
+        })?;
+        let parsed = parsed.normalize_s().unwrap_or(parsed);
+        let verifying_key = parse_verifying_key(&vault_key.public_key_hex)?;
+        let recovery_id =
+            RecoveryId::trial_recovery_from_prehash(&verifying_key, &digest_bytes, &parsed)
+                .map_err(|err| {
+                    DaemonError::Signer(SignerError::Internal(format!(
+                        "unable to derive signature recovery id for {operation}: {err}"
+                    )))
+                })?;
+
+        let mut compact = [0u8; 64];
+        compact.copy_from_slice(&parsed.to_bytes());
+        let mut r = [0u8; 32];
+        let mut s = [0u8; 32];
+        r.copy_from_slice(&compact[..32]);
+        s.copy_from_slice(&compact[32..]);
+        let v = u8::from(recovery_id);
+
+        Ok(Signature {
+            bytes: parsed.to_der().as_bytes().to_vec(),
+            r_hex: Some(format!("0x{}", hex::encode(r))),
+            s_hex: Some(format!("0x{}", hex::encode(s))),
+            v: Some(u64::from(v)),
+            raw_tx_hex: None,
+            tx_hash_hex: None,
+        })
+    }
+
+    async fn sign_broadcast_eip1559(
+        &self,
+        vault_key: &VaultKey,
+        tx: &vault_domain::BroadcastTx,
+    ) -> Result<Signature, DaemonError> {
+        let signing_message = tx
+            .eip1559_signing_message()
+            .map_err(map_domain_to_signer_error)?;
+        let digest_bytes = alloy_primitives::keccak256(&signing_message).0;
+
+        let mut signature = self
+            .sign_digest_with_recovery(vault_key, digest_bytes, "tx signing")
+            .await?;
+
+        let r_hex = signature.r_hex.clone().ok_or_else(|| {
+            DaemonError::Signer(SignerError::Internal("missing tx r value".to_string()))
+        })?;
+        let s_hex = signature.s_hex.clone().ok_or_else(|| {
+            DaemonError::Signer(SignerError::Internal("missing tx s value".to_string()))
+        })?;
+        let v = signature.v.ok_or_else(|| {
+            DaemonError::Signer(SignerError::Internal("missing tx recovery id".to_string()))
+        })? as u8;
+
+        let r_bytes = hex::decode(r_hex.trim_start_matches("0x")).map_err(|err| {
+            DaemonError::Signer(SignerError::Internal(format!(
+                "failed to decode tx r value: {err}"
+            )))
+        })?;
+        let s_bytes = hex::decode(s_hex.trim_start_matches("0x")).map_err(|err| {
+            DaemonError::Signer(SignerError::Internal(format!(
+                "failed to decode tx s value: {err}"
+            )))
+        })?;
+        let mut r = [0u8; 32];
+        let mut s = [0u8; 32];
+        r.copy_from_slice(&r_bytes);
+        s.copy_from_slice(&s_bytes);
+
+        let raw_tx = tx
+            .eip1559_signed_raw_transaction(v, r, s)
+            .map_err(map_domain_to_signer_error)?;
+        let tx_hash = alloy_primitives::keccak256(&raw_tx);
+        signature.raw_tx_hex = Some(format!("0x{}", hex::encode(raw_tx)));
+        signature.tx_hash_hex = Some(format!("0x{}", hex::encode(tx_hash)));
+        Ok(signature)
+    }
+}
+
+const DEFAULT_RELAY_URL: &str = "http://localhost:8787";
+
+fn ensure_relay_identity(state: &mut PersistedDaemonState) {
+    if state.relay_private_key_hex.trim().is_empty() {
+        let private_bytes = rand::random::<[u8; 32]>();
+        state.relay_private_key_hex = hex::encode(private_bytes);
+    }
+    if state
+        .relay_config
+        .relay_url
+        .as_deref()
+        .map_or(true, |value| value.trim().is_empty())
+    {
+        state.relay_config.relay_url = Some(DEFAULT_RELAY_URL.to_string());
+    }
+    if state.relay_config.daemon_id_hex.trim().is_empty() {
+        state.relay_config.daemon_id_hex = hex::encode(rand::random::<[u8; 32]>());
+    }
+    if state.relay_config.daemon_public_key_hex.trim().is_empty() {
+        let private_hex = state.relay_private_key_hex.trim().trim_start_matches("0x");
+        if let Ok(private_bytes) = hex::decode(private_hex) {
+            if private_bytes.len() == 32 {
+                let mut private_key = [0u8; 32];
+                private_key.copy_from_slice(&private_bytes);
+                let secret = x25519_dalek::StaticSecret::from(private_key);
+                let public = x25519_dalek::PublicKey::from(&secret);
+                state.relay_config.daemon_public_key_hex = hex::encode(public.as_bytes());
+            }
+        }
+    }
+}
+
+fn ethereum_address_from_public_key_hex(public_key_hex: &str) -> Result<String, DaemonError> {
+    let verifying_key = parse_verifying_key(public_key_hex)?;
+    let encoded = verifying_key.to_encoded_point(false);
+    let public_key = encoded.as_bytes();
+    if public_key.len() != 65 || public_key[0] != 0x04 {
+        return Err(DaemonError::Signer(SignerError::Internal(
+            "vault public key must be an uncompressed secp256k1 SEC1 point".to_string(),
+        )));
+    }
+    let digest = alloy_primitives::keccak256(&public_key[1..]);
+    let address = &digest.0[12..];
+    Ok(format!("0x{}", hex::encode(address)))
+}
+
+fn manual_approval_frontend_url(
+    relay_config: &RelayConfig,
+    approval_request_id: Uuid,
+    approval_capability: &str,
+) -> Option<String> {
+    relay_config
+        .frontend_url
+        .as_ref()
+        .or(relay_config.relay_url.as_ref())
+        .map(|frontend_url| {
+            let daemon_id = relay_config.daemon_id_hex.trim();
+            if daemon_id.is_empty() {
+                format!(
+                    "{}/approvals/{approval_request_id}?approvalCapability={approval_capability}",
+                    frontend_url.trim_end_matches('/')
+                )
+            } else {
+                format!(
+                    "{}/approvals/{approval_request_id}?daemonId={daemon_id}&approvalCapability={approval_capability}",
+                    frontend_url.trim_end_matches('/')
+                )
+            }
+        })
+}
+
+fn payload_hash_hex(payload: &[u8]) -> String {
+    let digest = Sha256::digest(payload);
+    hex::encode(digest)
+}