Struct AgentService 

pub struct AgentService<'a> { /* private fields */ }

SSH agent operations.

Obtained from SshManager::agent().

Implementations

impl<'a> AgentService<'a>

pub fn new(paths: &'a SshPaths, runner: &'a dyn CliRunner) -> Self

pub async fn status(&self) -> Result<bool>

Check if the SSH agent is reachable.

Returns true when SSH_AUTH_SOCK points to an existing socket and we can successfully connect to the agent.

Errors

Returns an error if the agent check command itself fails unexpectedly (not merely because the agent is unavailable).

pub async fn list_keys(&self) -> Result<Vec<SshKey>>

List all keys currently loaded in the SSH agent.

Errors

Returns Error::AgentNotAvailable if the agent is not running, or Error::AgentOperationFailed if the agent protocol fails.

pub async fn add_key(&self, key_path: &Path) -> Result<()>

Add a private key to the SSH agent.

Errors

Returns Error::AgentOperationFailed if the key cannot be added (e.g. passphrase required, agent rejects the key).

pub async fn remove_key(&self, key_path: &Path) -> Result<()>

Remove a key from the SSH agent.

Errors

Returns Error::AgentOperationFailed if the key cannot be removed.

pub async fn test_key_usability(&self, key_path: &Path) -> Result<bool>

Test whether a key is usable by the SSH agent (ssh-add -T).

Returns true if the key is usable (already decrypted/loaded or accessible via hardware token), false otherwise.

Errors

Returns Error::AgentOperationFailed if the test command itself cannot be executed.

pub async fn destination_constrained_add( &self, key_path: &Path, hosts: &[&str], ) -> Result<()>

Add a key restricted to specific destination hosts (ssh-add -h).

The key will only be authorized for connections to the listed hosts. At least one host must be provided.

Errors

Returns Error::AgentOperationFailed if hosts is empty or if the command fails.

pub async fn remove_all(&self) -> Result<()>

Remove all keys from the SSH agent (ssh-add -D).

Returns the number of keys removed (best-effort; some agents don’t report count).

Errors

Returns Error::CommandFailed if the command fails.

pub async fn add_key_with_lifetime( &self, key_path: &Path, lifetime_seconds: u32, ) -> Result<()>

Add a key to the SSH agent with a lifetime limit (ssh-add -t).

lifetime_seconds specifies how long the key should remain loaded.

Errors

Returns Error::CommandFailed if the key cannot be added or the lifetime argument is invalid.

pub async fn add_key_with_confirmation(&self, key_path: &Path) -> Result<()>

Add a key to the SSH agent with confirmation required (ssh-add -c).

The agent will request user confirmation each time the key is used.

Errors

Returns Error::CommandFailed if the key cannot be added.

pub async fn add_key_with_passphrase( &self, key_path: &Path, passphrase: &str, ) -> Result<()>

Add a passphrase-protected key to the SSH agent using SSH_ASKPASS.

This creates a temporary askpass script that supplies the passphrase non-interactively, which is useful when loading keys from a TUI or other automated context where terminal input is not available.

The temporary script is cleaned up automatically when this method returns (on success or failure).

Errors

Returns Error::CommandFailed if the key cannot be added, or Error::Io if the temporary askpass script cannot be created.

pub async fn list_sessions(&self) -> Result<Vec<ControlSession>>

List active ControlMaster sessions.

Scans for control socket files in the SSH directory and /tmp, verifying each is still alive.

Errors

Returns Error::TaskFailed if the background scan task panics or is cancelled.