Lutra/crates/deploy/src/sftp.rs
danny a8ad74755c D2: remote browser operations, compare and sync in lutra-deploy
Remote trait gains remove_file, remove_dir and rename (SFTP, FTP,
folder; test servers too). browse: list, read as text (binary and size
caps), write, rename, mkdir, recursive delete that never takes the root.
job: compare (local only, server only, different by size then
contents) and sync (uploads plus explicitly listed deletions).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 19:49:59 +01:00

476 lines
17 KiB
Rust

//! SFTP over SSH with `russh` and `russh-sftp`, pure Rust with `ring`.
//!
//! The library is async; [`Sftp`] owns a single-threaded tokio runtime and
//! blocks on it, so callers stay synchronous like the other transports.
//! Every network wait races the job's [`Cancel`] flag (checked every 50
//! ms) and a timeout.
//!
//! The server's host key is checked against Lutra's known-hosts file
//! before any credential is sent. Sign-in uses a password from the
//! keychain, a private key file (with its passphrase from the keychain), or
//! the SSH agent.
use std::future::Future;
use std::io::{Read, Write};
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex, PoisonError};
use std::time::Duration;
use russh::client::{self, Handle};
use russh::keys::{HashAlg, PrivateKeyWithHashAlg, PublicKeyOrCertificate};
use russh_sftp::client::SftpSession;
use russh_sftp::protocol::StatusCode;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::runtime::Runtime;
use crate::config::{AuthKind, Server};
use crate::error::{DeployError, Result};
use crate::known_hosts::{self, HostKeyStatus};
use crate::remote::{CHUNK, Cancel, Entry, MAX_LISTING, Remote, Tick, safe_name};
use crate::secrets::Secret;
/// Longest wait for the TCP connection and the SSH handshake.
const CONNECT_TIMEOUT: Duration = Duration::from_secs(20);
/// Longest wait for one SFTP request or chunk.
const REQUEST_TIMEOUT: Duration = Duration::from_secs(60);
/// The SSH client's callbacks: checks the host key.
struct Client {
/// `host:port`.
host: String,
/// Lutra's known-hosts file.
known_hosts: PathBuf,
/// Why the key was refused, read after the handshake failed.
verdict: Arc<Mutex<Option<DeployError>>>,
}
impl Client {
/// Remembers why the key was refused.
fn refuse(&self, error: DeployError) -> bool {
*self.verdict.lock().unwrap_or_else(PoisonError::into_inner) = Some(error);
false
}
}
impl client::Handler for Client {
type Error = russh::Error;
async fn check_server_key(
&mut self,
offered: &PublicKeyOrCertificate,
) -> std::result::Result<bool, Self::Error> {
let PublicKeyOrCertificate::PublicKey { key, .. } = offered else {
return Ok(self.refuse(DeployError::Auth(format!(
"{} offered an SSH certificate as its host key; Lutra accepts plain host keys only",
self.host
))));
};
let fingerprint = key.fingerprint(HashAlg::Sha256).to_string();
let algorithm = key.algorithm().to_string();
Ok(
match known_hosts::check(&self.known_hosts, &self.host, &fingerprint) {
Ok(HostKeyStatus::Trusted) => true,
Ok(HostKeyStatus::Unknown) => self.refuse(DeployError::HostKeyUnknown {
host: self.host.clone(),
algorithm,
fingerprint,
}),
Ok(HostKeyStatus::Mismatch(known)) => self.refuse(DeployError::HostKeyMismatch {
host: self.host.clone(),
algorithm,
fingerprint,
known,
}),
Err(e) => self.refuse(e),
},
)
}
}
/// An open SFTP session.
pub struct Sftp {
/// Drives the async library.
runtime: Runtime,
/// The SSH connection.
handle: Handle<Client>,
/// The SFTP channel.
sftp: SftpSession,
/// The job's cancel flag.
cancel: Cancel,
}
/// Runs `fut` until it ends, `limit` passes or `cancel` is set.
async fn bounded<T, F: Future<Output = T>>(
cancel: &Cancel,
limit: Duration,
what: &str,
fut: F,
) -> Result<T> {
let watch = async {
loop {
if cancel.is_cancelled() {
return;
}
tokio::time::sleep(Duration::from_millis(50)).await;
}
};
tokio::select! {
out = tokio::time::timeout(limit, fut) => out.map_err(|_| {
DeployError::Transfer(format!("{what} timed out after {} s", limit.as_secs()))
}),
() = watch => Err(DeployError::Cancelled),
}
}
/// An SFTP library error as a transfer error.
fn sftp_error(what: &str, path: &str, e: &russh_sftp::client::error::Error) -> DeployError {
DeployError::Transfer(format!("{what} {path}: {e}"))
}
/// Whether `e` says the path does not exist.
fn is_missing(e: &russh_sftp::client::error::Error) -> bool {
matches!(e, russh_sftp::client::error::Error::Status(s) if s.status_code == StatusCode::NoSuchFile)
}
impl Sftp {
/// Connects to `server`, checks its host key against `known_hosts`,
/// signs in and opens the SFTP subsystem.
///
/// # Errors
/// [`DeployError::HostKeyUnknown`] or [`DeployError::HostKeyMismatch`]
/// before any credential is sent; [`DeployError::MissingSecret`] when a
/// password is needed but `secret` is `None`; [`DeployError::Auth`]
/// when the server refuses; [`DeployError::Connect`] when it cannot be
/// reached; [`DeployError::Cancelled`].
pub fn connect(
server: &Server,
secret: Option<&Secret>,
known_hosts: &Path,
cancel: &Cancel,
) -> Result<Self> {
let runtime = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.map_err(|e| DeployError::Transfer(format!("cannot start the SSH runtime: {e}")))?;
let host = server.address();
let verdict = Arc::new(Mutex::new(None));
let handler = Client {
host: host.clone(),
known_hosts: known_hosts.to_path_buf(),
verdict: Arc::clone(&verdict),
};
let config = Arc::new(client::Config {
inactivity_timeout: Some(Duration::from_secs(120)),
..Default::default()
});
let target = (server.host.clone(), server.effective_port());
let connected = runtime.block_on(bounded(
cancel,
CONNECT_TIMEOUT,
"connecting",
client::connect(config, target, handler),
))?;
let mut handle = match connected {
Ok(handle) => handle,
Err(e) => {
if let Some(refusal) = verdict
.lock()
.unwrap_or_else(PoisonError::into_inner)
.take()
{
return Err(refusal);
}
return Err(DeployError::Connect {
host,
message: e.to_string(),
});
}
};
let signed_in = runtime.block_on(bounded(
cancel,
CONNECT_TIMEOUT,
"signing in",
authenticate(&mut handle, server, secret),
))??;
if !signed_in {
let how = match server.auth {
AuthKind::Password => "the user name or password",
AuthKind::Key => "the user name or the key",
AuthKind::Agent => "the user name or the keys in the SSH agent",
};
return Err(DeployError::Auth(format!(
"{host} refused the sign-in; check {how}"
)));
}
let sftp = runtime
.block_on(bounded(cancel, CONNECT_TIMEOUT, "opening SFTP", async {
let channel = handle.channel_open_session().await?;
channel.request_subsystem(true, "sftp").await?;
Ok::<_, russh::Error>(channel.into_stream())
}))?
.map_err(|e| DeployError::Connect {
host: host.clone(),
message: format!("the server offers no SFTP: {e}"),
})?;
let sftp = runtime
.block_on(bounded(
cancel,
CONNECT_TIMEOUT,
"opening SFTP",
SftpSession::new(sftp),
))?
.map_err(|e| DeployError::Connect {
host,
message: format!("the SFTP session failed: {e}"),
})?;
Ok(Self {
runtime,
handle,
sftp,
cancel: cancel.clone(),
})
}
/// Runs one request with the request timeout and the cancel flag.
fn run<T, F: Future<Output = T>>(&self, what: &str, fut: F) -> Result<T> {
self.runtime
.block_on(bounded(&self.cancel, REQUEST_TIMEOUT, what, fut))
}
}
/// Signs in on `handle` the way `server` says. Returns whether the server
/// accepted.
async fn authenticate(
handle: &mut Handle<Client>,
server: &Server,
secret: Option<&Secret>,
) -> Result<bool> {
let user = server.user.clone();
let auth_error = |e: russh::Error| DeployError::Auth(format!("signing in failed: {e}"));
match server.auth {
AuthKind::Password => {
let Some(secret) = secret else {
return Err(DeployError::MissingSecret {
server: server.name.clone(),
kind: "password".into(),
});
};
let result = handle
.authenticate_password(user, secret.expose())
.await
.map_err(auth_error)?;
Ok(result.success())
}
AuthKind::Key => {
let path = server.key_path.clone().unwrap_or_default();
let key = match russh::keys::load_secret_key(&path, secret.map(Secret::expose)) {
Ok(key) => key,
Err(russh::keys::Error::KeyIsEncrypted) if secret.is_none() => {
return Err(DeployError::MissingSecret {
server: server.name.clone(),
kind: "passphrase".into(),
});
}
Err(e) => {
return Err(DeployError::Auth(format!(
"cannot read the private key {path}: {e}"
)));
}
};
let hash = handle
.best_supported_rsa_hash()
.await
.map_err(auth_error)?
.flatten();
let result = handle
.authenticate_publickey(user, PrivateKeyWithHashAlg::new(Arc::new(key), hash))
.await
.map_err(auth_error)?;
Ok(result.success())
}
AuthKind::Agent => agent(handle, &user).await,
}
}
/// Tries every key of the SSH agent.
#[cfg(windows)]
async fn agent(handle: &mut Handle<Client>, user: &str) -> Result<bool> {
use russh::keys::agent::client::AgentClient;
if let Ok(client) = AgentClient::connect_named_pipe(r"\\.\pipe\openssh-ssh-agent").await {
return agent_keys(handle, user, client).await;
}
match AgentClient::connect_pageant().await {
Ok(client) => agent_keys(handle, user, client).await,
Err(_) => Err(DeployError::Auth(
"no SSH agent is running: start the OpenSSH Authentication Agent service or Pageant and add your key".into(),
)),
}
}
/// Tries every key of the SSH agent.
#[cfg(unix)]
async fn agent(handle: &mut Handle<Client>, user: &str) -> Result<bool> {
use russh::keys::agent::client::AgentClient;
match AgentClient::connect_env().await {
Ok(client) => agent_keys(handle, user, client).await,
Err(_) => Err(DeployError::Auth(
"no SSH agent is reachable through SSH_AUTH_SOCK: start one and add your key (ssh-add)"
.into(),
)),
}
}
/// Tries each key the agent holds until the server accepts one.
async fn agent_keys<S>(
handle: &mut Handle<Client>,
user: &str,
mut client: russh::keys::agent::client::AgentClient<S>,
) -> Result<bool>
where
S: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin + Send + 'static,
{
let identities = client
.request_identities()
.await
.map_err(|e| DeployError::Auth(format!("the SSH agent did not answer: {e}")))?;
let hash = handle
.best_supported_rsa_hash()
.await
.ok()
.flatten()
.flatten();
for identity in identities {
let russh::keys::agent::AgentIdentity::PublicKey { key, .. } = identity else {
continue;
};
if let Ok(result) = handle
.authenticate_publickey_with(user, key, hash, &mut client)
.await
&& result.success()
{
return Ok(true);
}
}
Ok(false)
}
impl Remote for Sftp {
fn mkdir_all(&mut self, dir: &str) -> Result<()> {
let absolute = dir.starts_with('/');
let mut path = String::new();
for part in dir.split('/').filter(|p| !p.is_empty()) {
if absolute || !path.is_empty() {
path.push('/');
}
path.push_str(part);
let exists = self
.run("checking a folder", self.sftp.try_exists(path.clone()))?
.map_err(|e| sftp_error("cannot check", &path, &e))?;
if !exists {
self.run("creating a folder", self.sftp.create_dir(path.clone()))?
.map_err(|e| sftp_error("cannot create the folder", &path, &e))?;
}
}
Ok(())
}
fn put(&mut self, path: &str, data: &mut dyn Read, tick: Tick<'_>) -> Result<()> {
let mut file = self
.run("opening a file", self.sftp.create(path.to_string()))?
.map_err(|e| sftp_error("cannot write", path, &e))?;
let mut buf = vec![0u8; CHUNK];
loop {
let n = data
.read(&mut buf)
.map_err(|e| DeployError::Transfer(format!("read failed: {e}")))?;
if n == 0 {
break;
}
let chunk = buf.get(..n).unwrap_or_default();
self.run("uploading", file.write_all(chunk))?
.map_err(|e| DeployError::Transfer(format!("cannot write {path}: {e}")))?;
tick(n as u64)?;
}
self.run("closing a file", file.shutdown())?
.map_err(|e| DeployError::Transfer(format!("cannot finish {path}: {e}")))
}
fn get(&mut self, path: &str, out: &mut dyn Write, tick: Tick<'_>) -> Result<()> {
let mut file = self
.run("opening a file", self.sftp.open(path.to_string()))?
.map_err(|e| sftp_error("cannot read", path, &e))?;
let mut buf = vec![0u8; CHUNK];
loop {
let n = self
.run("downloading", file.read(&mut buf))?
.map_err(|e| DeployError::Transfer(format!("cannot read {path}: {e}")))?;
if n == 0 {
break;
}
out.write_all(buf.get(..n).unwrap_or_default())
.map_err(|e| DeployError::Transfer(format!("write failed: {e}")))?;
tick(n as u64)?;
}
Ok(())
}
fn kind(&mut self, path: &str) -> Result<Option<bool>> {
let target = if path.is_empty() { "." } else { path };
match self.run("checking a path", self.sftp.metadata(target.to_string()))? {
Ok(meta) => Ok(Some(meta.is_dir())),
Err(e) if is_missing(&e) => Ok(None),
Err(e) => Err(sftp_error("cannot check", path, &e)),
}
}
fn list(&mut self, path: &str) -> Result<Vec<Entry>> {
let target = if path.is_empty() { "." } else { path };
let dir = self
.run("listing a folder", self.sftp.read_dir(target.to_string()))?
.map_err(|e| sftp_error("cannot list", path, &e))?;
let mut entries: Vec<Entry> = dir
.filter(|e| safe_name(&e.file_name()))
.take(MAX_LISTING)
.map(|e| {
let meta = e.metadata();
Entry {
name: e.file_name(),
is_dir: meta.is_dir(),
size: meta.size,
}
})
.collect();
entries.sort_by(|a, b| a.name.cmp(&b.name));
Ok(entries)
}
fn remove_file(&mut self, path: &str) -> Result<()> {
self.run("removing a file", self.sftp.remove_file(path.to_string()))?
.map_err(|e| sftp_error("cannot remove", path, &e))
}
fn remove_dir(&mut self, path: &str) -> Result<()> {
self.run("removing a folder", self.sftp.remove_dir(path.to_string()))?
.map_err(|e| sftp_error("cannot remove the folder", path, &e))
}
fn rename(&mut self, from: &str, to: &str) -> Result<()> {
self.run(
"renaming",
self.sftp.rename(from.to_string(), to.to_string()),
)?
.map_err(|e| sftp_error(&format!("cannot rename to {to}:"), from, &e))
}
/// Closes the SFTP channel and the connection. Failures are ignored:
/// the connection is dropped right after.
fn close(&mut self) {
let _ = self.run("closing", self.sftp.close());
let _ = self.run(
"disconnecting",
self.handle
.disconnect(russh::Disconnect::ByApplication, "", "en"),
);
}
}