D1: lutra-deploy crate: SFTP, FTP/FTPS and folder transports, keychain secrets, known hosts, path mappings
Pure Rust (D27): russh + russh-sftp with ring, suppaftp with rustls/ring, keyring (Windows Credential Manager, macOS Keychain). Lutra's own known-hosts file, refuse on mismatch. In-process SFTP and FTP test servers behind the testserver feature. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
33a7185d75
commit
0644b044f2
16 changed files with 5250 additions and 13 deletions
458
crates/deploy/src/sftp.rs
Normal file
458
crates/deploy/src/sftp.rs
Normal file
|
|
@ -0,0 +1,458 @@
|
|||
//! 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)
|
||||
}
|
||||
|
||||
/// 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"),
|
||||
);
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue