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>
476 lines
17 KiB
Rust
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"),
|
|
);
|
|
}
|
|
}
|