ssh-browser 0.4.0

//! The HTTP origin: what the browser actually talks to.
//!
//! The daemon answers two shapes of request on one loopback listener. A proxied
//! request arrives in absolute form because a PAC sent it here, and its Host is
//! `<alias>.<suffix>`; that is the path which gives the page a real origin under
//! the URL the user typed. A direct request arrives by address and exists so the
//! daemon is usable without touching proxy settings at all.
//!
//! Every request starts at the listing cache, not at the remote. One fresh listing
//! of a parent directory answers four questions locally -- does this name exist, is
//! it a directory, is it a symlink, and is the copy the browser already holds still
//! current -- and only a body the cache does not hold costs a round trip.

pub mod guard;
pub mod mime;
pub mod pac;
pub mod range;

use std::collections::{HashMap, HashSet};
use std::net::SocketAddr;
use std::sync::atomic::Ordering;
use std::sync::{Arc, Mutex};

use tokio::sync::RwLock;

use anyhow::{Context, Result, bail, ensure};
use bytes::Bytes;
use http_body_util::Full;
use hyper::header::{
    ACCEPT_RANGES, CACHE_CONTROL, CONTENT_RANGE, CONTENT_TYPE, ETAG, HOST, HeaderName,
    IF_NONE_MATCH, IF_RANGE, LOCATION, RANGE,
};
use hyper::server::conn::http1;
use hyper::service::service_fn;
use hyper::{Method, Request, Response, StatusCode};
use hyper_util::rt::TokioIo;
use tokio::net::TcpListener;

use crate::cache::{self, Cache};
use crate::control::{self, Token};
use crate::fs::sftp::SftpFs;
use crate::fs::{Entry, RangeReq, RemoteFs};
use crate::prefetch;
use crate::reachable;
use crate::sftp::wire::Attrs;
use crate::ssh_config;
use crate::theme;
use crate::tls;
use rustls_pki_types::pem::PemObject;

/// A file worth holding whole. Anything larger is served by range and not cached: a
/// seek into a video must not pull the entire file, and holding one would evict every
/// page body that makes a revisit free.
const CACHE_WHOLE_MAX: u64 = 8 * 1024 * 1024;

/// The request headers that change what is served rather than what is found.
struct Conditions {
    if_none_match: Option<String>,
    range: Option<String>,
    if_range: Option<String>,
    /// Only ever consulted on the control path, which only a loopback request reaches.
    control_token: Option<String>,
    /// What the browser said about who started this request, if a browser started it.
    ///
    /// A forbidden header name, so a page can neither set it nor suppress it. See
    /// `control::from_a_page`.
    fetch_site: Option<String>,
}

/// One alias, checked.
///
/// The fields are private and [`Alias::new`] is the only way to make one, so there is no
/// route into the daemon that skips these checks. That matters now that aliases can come
/// from a configuration file as well as from the command line: two entry points and one
/// validating constructor is fine, two entry points and two copies of the rules is how the
/// looser copy becomes the one that gets used.
#[derive(Debug)]
pub struct Alias {
    name: String,
    host: String,
    /// Where this alias is rooted, or `None` for the remote's home directory.
    ///
    /// Deferred rather than filled in with a guess, because the answer lives on the
    /// remote. `~` is shell syntax and this transport never runs a shell; expanding it
    /// here would produce this machine's home directory, which is a different computer's.
    /// It is resolved once in `bind`, by asking.
    base: Option<String>,
}

impl Alias {
    pub fn new(name: &str, host: &str, base: Option<&str>) -> Result<Self> {
        ensure!(!host.is_empty(), "alias {name:?} has no ssh host");
        // The alias becomes a hostname label, and this is the very function that decides
        // whether an arriving request's label is acceptable. Asking it, rather than writing
        // the rule out again, is what stops the two from disagreeing — and they already had:
        // `-docs` satisfied the copy here and was then refused by `classify` on every single
        // request, after the daemon had paid for the ssh connection and advertised the route.
        ensure!(
            guard::is_label(name),
            "alias {name:?} must be lowercase letters, digits and hyphens, and may not start or end with a hyphen: it becomes a hostname label"
        );
        if let Some(base) = base {
            ensure!(
                is_base(base),
                "alias {name:?} needs a base that is an absolute path, or `~`, or `~/` and a path under the home directory with no `..` in it, got {base:?}"
            );
        }
        Ok(Self {
            name: name.to_string(),
            host: host.to_string(),
            base: base.map(str::to_string),
        })
    }

    pub fn name(&self) -> &str {
        &self.name
    }

    pub fn host(&self) -> &str {
        &self.host
    }

    /// Where this alias is rooted, or `None` for the remote's home directory.
    pub fn base(&self) -> Option<&str> {
        self.base.as_deref()
    }
}

/// One line of the host list: a host ssh knows, and what this daemon is doing with it.
#[derive(serde::Serialize)]
struct KnownHost {
    alias: String,
    host: String,
    #[serde(flatten)]
    settings: ssh_config::Settings,
    /// Whether this daemon has an alias for it right now.
    ///
    /// Named for what it is rather than "connected": what the extension needs to know is
    /// whether a URL for this alias will answer, and that is a question about routing.
    served: bool,
    /// Whether this daemon opens it on its own, every run.
    ///
    /// Distinct from `served`, and the difference is the whole feature: `served` is about
    /// now, `enabled` is about next time. A host opened by hand is served and not enabled; a
    /// host enabled while its ssh was down is enabled and not served.
    enabled: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    unresolved: Option<String>,
}

/// An alias being served right now.
///
/// A separate list from the hosts, because it answers a different question and the two do
/// not line up: an alias need not be named after its host, so a session opened as
/// `docs=myhost:/srv` matches no row in ssh_config at all. Reporting only the hosts would
/// leave it being served and visible nowhere, which is the kind of invisible live state
/// this daemon is supposed not to have.
#[derive(serde::Serialize)]
struct OpenAlias {
    alias: String,
    host: String,
    base: String,
    url: String,
    /// Remote round trips this session has cost since it opened.
    ///
    /// The central claim of this daemon is a round-trip count, and until this was reported
    /// the counter behind it existed only for unit tests against a fake remote — so nobody
    /// could check the claim against their own host and their own site, which is the only
    /// place it can be wrong in a way that matters. Read it twice and subtract.
    ///
    /// Monotonic and per session, so it resets when an alias is closed and reopened.
    trips: u64,
}

#[derive(serde::Serialize)]
struct KnownHosts {
    open: Vec<OpenAlias>,
    hosts: Vec<KnownHost>,
    unusable: Vec<ssh_config::Unusable>,
    /// What TLS handshakes have done, under https.
    ///
    /// Here as well as on `hello` because this is the route the dashboard polls, and the answer
    /// belongs where somebody is looking. `None` under http, where there are no handshakes.
    #[serde(skip_serializing_if = "Option::is_none")]
    tls: Option<control::Handshakes>,
}

/// Whether a configured base is one this daemon can resolve.
///
/// `~` is accepted here and nowhere else in the codebase. It is shell syntax, and this
/// transport never runs a shell, so it is not passed through to anything: it is a
/// stand-in for an answer only the remote has, substituted in `bind` once the session
/// exists. Writing the home path out by hand is the alternative, and it means knowing
/// another machine's account layout in order to name a directory you can already `cd` to.
///
/// `..` is refused rather than normalised. `~/..` quietly meaning the parent of the home
/// directory is the kind of surprise that belongs in a base path least of all, since the
/// base is the blast radius of every page served under it.
fn is_base(base: &str) -> bool {
    if base.starts_with('/') {
        return true;
    }
    let Some(rest) = base.strip_prefix('~') else {
        return false;
    };
    match rest {
        "" => true,
        rest => match rest.strip_prefix('/') {
            Some(under) => {
                !under.is_empty()
                    && under
                        .split('/')
                        .all(|c| !c.is_empty() && c != "." && c != "..")
            }
            None => false,
        },
    }
}

/// The absolute base an alias is rooted at, asking the remote only when the answer needs
/// asking.
///
/// Separated from `bind` because `bind` starts an ssh subprocess, which no test can, and
/// this is the part of it with a decision in it.
async fn resolve_base(base: Option<&str>, fs: &SftpFs) -> Result<String> {
    let under = match base {
        None | Some("~") => "",
        Some(b) => match b.strip_prefix("~/") {
            Some(under) => under,
            // Already absolute. Nothing to ask the remote, and asking anyway would put an
            // ssh round trip in front of every startup for no answer.
            None => return Ok(b.to_string()),
        },
    };
    let home = fs.home().await?;
    let home = home.trim_end_matches('/');
    // A home of `/` would otherwise produce `//work`, which is not the same path
    // everywhere: POSIX leaves a leading double slash implementation-defined.
    let home = if home.is_empty() { "" } else { home };
    Ok(match under {
        "" if home.is_empty() => "/".to_string(),
        "" => home.to_string(),
        under => format!("{home}/{under}"),
    })
}

/// One alias's session, or nothing if no such alias is open.
///
/// The guard is dropped before returning, so nothing a caller does afterwards holds up
/// another request.
impl Origin {
    async fn session(&self, alias: &str) -> Option<Arc<Session>> {
        self.sessions.read().await.get(alias).cloned()
    }

    /// Where a site lives, as a reader would type it.
    ///
    /// One place, because the scheme is part of the origin: a URL built with the wrong one is not
    /// a cosmetic slip but a link into a different origin than the one being served.
    fn site_url(&self, alias: &str) -> String {
        format!("{}://{alias}.{}/", self.scheme, self.suffix)
    }

    async fn alias_names(&self) -> Vec<String> {
        let mut names: Vec<String> = self.sessions.read().await.keys().cloned().collect();
        names.sort();
        names
    }

    /// Remote round trips every open session has cost, added up.
    async fn round_trips(&self) -> u64 {
        self.sessions
            .read()
            .await
            .values()
            .map(|s| s.fs.round_trips())
            .sum()
    }
}

struct Session {
    /// The ssh_config name this was reached by.
    ///
    /// Kept because an alias need not be named after its host — `docs=myhost:/srv` is one
    /// of each — so without it the only thing that could be reported about a live session
    /// is a name that appears nowhere in ssh_config.
    host: String,
    base: String,
    fs: SftpFs,
}

pub struct Origin {
    suffix: String,
    port: u16,
    /// The aliases being served right now.
    ///
    /// Behind a lock because the set changes while the daemon runs: a host is opened when
    /// somebody picks it, not when the daemon starts. Starting six ssh sessions so that a
    /// popup could list six hosts would make looking at the list cost more than using one.
    ///
    /// The values are `Arc`d so a request can take its session and let go of the lock.
    /// Holding a read guard across the awaits a page costs would block every open for the
    /// length of a remote read, and `Session` owns the ssh child — dropping one kills the
    /// connection, so it cannot simply be cloned out.
    sessions: RwLock<HashMap<String, Arc<Session>>>,
    cache: Cache,
    token: Token,
    /// What a directory listing looks like.
    ///
    /// Behind a lock because it is chosen from the dashboard while the daemon runs, and it
    /// is one setting for every alias: an origin that looked different from its neighbour
    /// for no reason the reader chose would be a bug rather than a feature.
    theme: RwLock<String>,
    /// `http` or `https`. What a site's URL starts with, and whether `CONNECT` is answered.
    ///
    /// Held here rather than consulted from the config, because six places build a site URL and
    /// a seventh that forgot would hand somebody a link to the wrong scheme — which under
    /// https is not a cosmetic difference but a different origin.
    scheme: String,
    /// What TLS handshakes have done, which is the only portable way to learn whether the
    /// authority is trusted.
    ///
    /// Nothing can ask a trust store the question directly and get a portable answer — but a
    /// handshake *is* the answer. One that completes proves the browser accepted the
    /// certificate; one that fails at this stage almost always means it did not. So the daemon
    /// stops guessing and reports what happened.
    handshakes: Handshakes,
    /// The serving certificate, when there is one.
    ///
    /// `None` under http, and that is what a `CONNECT` is refused by: there is no certificate to
    /// terminate with, and answering `200` and then failing the handshake would tell the browser
    /// the tunnel was fine.
    tls: Option<Arc<rustls::ServerConfig>>,
    /// Which `ssh_config` hosts this daemon opens without being asked.
    ///
    /// Never consulted while serving a request. It decides what happens at startup and what
    /// a toggle does, and nothing else — see `crate::reachable` for why an "open it when a
    /// request arrives" version would hand any web page the ability to start ssh sessions.
    reachable: RwLock<reachable::Set>,
}

/// A listening socket and the origin that will answer on it.
///
/// Separate from [`Origin`] so that "the port is ours" is a thing the caller holds rather
/// than something it hopes for. A caller cannot announce that the daemon is up before it
/// is, because it has nothing to announce until this exists.
pub struct Bound {
    origin: Arc<Origin>,
    listener: TcpListener,
}

/// What to tell the reader about a daemon that has just come up.
///
/// Returned beside [`Bound`] rather than reachable through it, and that separation is
/// load-bearing rather than tidy. `Bound` owns the `Origin`, and the `Origin` owns the TLS
/// configuration, and that owns a private key — so a banner line reached through `Bound` is a
/// string a static analyser must treat as derived from the key, and it said so: CodeQL flagged
/// both `eprintln!`s in `main` as cleartext logging of the certificate resolver.
///
/// It was wrong about the values — these are host names and paths — and right about the shape.
/// Handing the caller strings that were never near the key makes the question unanswerable
/// rather than answered.
pub struct Startup {
    routes: Vec<String>,
    refused: Vec<String>,
    trust: Option<String>,
}

impl Startup {
    /// One line per alias, naming where it actually points.
    ///
    /// Only available once bound, which is the point: an alias rooted at the home directory has
    /// no printable base until the remote has been asked.
    pub fn routes(&self) -> &[String] {
        &self.routes
    }

    /// Enabled hosts that would not connect, and what ssh said about each.
    ///
    /// Separate from `routes` so a caller cannot print them as though they were working. Empty
    /// on an ordinary run; not an error, because the daemon is serving everything else.
    pub fn refused(&self) -> &[String] {
        &self.refused
    }

    /// What to say about the certificate, under https.
    ///
    /// `None` under http, where there is nothing to trust. Under https there is always
    /// something to say, because nothing portable can tell whether the authority is *still*
    /// trusted — and a daemon that advertised `https://...` and said nothing else left a
    /// first-time reader at `ERR_CERT_AUTHORITY_INVALID` with no way to guess what to do. That
    /// was measured by following the banner on a machine that had never run this.
    pub fn trust(&self) -> Option<&str> {
        self.trust.as_deref()
    }
}

impl Origin {
    /// Take the port, then connect every alias.
    ///
    /// The port first, deliberately. It is the thing that fails immediately and for a
    /// reason the operator can do something about — another daemon already has it — and a
    /// handful of ssh handshakes paid before discovering that is time spent to learn
    /// nothing.
    ///
    /// The aliases are connected here rather than on first use so that the first page
    /// request does not also pay for an ssh handshake.
    pub async fn bind(
        aliases: Vec<Alias>,
        hosts: reachable::Set,
        suffix: String,
        scheme: String,
        port: u16,
        token: Token,
        theme: String,
    ) -> Result<(Bound, Startup)> {
        let addr = SocketAddr::from(([127, 0, 0, 1], port));
        let listener = TcpListener::bind(addr)
            .await
            .with_context(|| format!("bind {addr}"))?;

        // Held to the same rule the PAC is, and here rather than only there: a suffix the
        // PAC would refuse is one no alias URL can ever match, so starting with it produces a
        // daemon that listens and serves nothing.
        ensure!(
            pac::is_suffix(&suffix),
            "suffix {suffix:?} must be lowercase letters, digits, hyphens and dots"
        );
        // Refused here rather than at the first listing: it is configuration, so it is
        // refused where the rest of the configuration is.
        theme::check(&theme)?;

        // The certificate is made before the listener answers anything, so a misconfigured
        // https mode fails at startup with a reason rather than on the first request with a
        // handshake error. Under http nothing is generated at all: no key is written for a
        // feature nobody asked for.
        let (tls, trust) = match scheme.as_str() {
            "http" => (None, None),
            "https" => {
                let (config, advice) = serving_config(&suffix)?;
                (Some(Arc::new(config)), Some(advice))
            }
            other => bail!("scheme {other:?} is not one this daemon serves; use http or https"),
        };

        let mut sessions = HashMap::new();
        let mut routes = Vec::new();
        for a in aliases {
            let fs = SftpFs::connect(&a.host)
                .await
                .with_context(|| format!("alias {} -> ssh host {}", a.name, a.host))?;
            // Asked here, once, rather than per request. An alias written without a base
            // means the account's home, and only the remote knows where that is.
            let base = resolve_base(a.base.as_deref(), &fs)
                .await
                .with_context(|| {
                    format!(
                        "alias {} -> ssh host {}: working out where {} is",
                        a.name,
                        a.host,
                        a.base.as_deref().unwrap_or("the home directory")
                    )
                })?;
            // Built from the resolved base, so what is announced is where requests will
            // actually go. Formatting it from the alias beforehand would print the word
            // "home" and leave the reader to find out which directory that was.
            routes.push(format!(
                "  {scheme}://{}.{suffix}/  ->  {}:{base}",
                a.name, a.host
            ));
            // Checked where the map is built, so there is no way to reach a session map with
            // a name silently missing from it. A caller may have checked earlier and should;
            // `insert` returning the displaced value is the check that cannot be skipped.
            ensure!(
                sessions
                    .insert(
                        a.name.clone(),
                        Arc::new(Session {
                            host: a.host.clone(),
                            base,
                            fs,
                        }),
                    )
                    .is_none(),
                "alias {:?} is defined twice",
                a.name
            );
        }
        let origin = Arc::new(Self {
            suffix,
            scheme,
            tls,
            port,
            sessions: RwLock::new(sessions),
            cache: Cache::default(),
            token,
            theme: RwLock::new(theme),
            reachable: RwLock::new(hosts),
            handshakes: Handshakes::default(),
        });

        // Opened after the aliases, and on different terms. An alias failing stops the daemon:
        // it was named for this run and serving without it would be answering a different
        // question. An enabled host failing does not, because the set is everything somebody
        // uses in a week and a laptop on the wrong network has half of them unreachable — a
        // daemon that refused to start until every one answered would be useless exactly when
        // it is most wanted. So the failures are reported and the rest is served.
        let (opened, refused) = origin.open_enabled().await;
        routes.extend(opened);

        Ok((
            Bound { origin, listener },
            Startup {
                routes,
                refused,
                trust,
            },
        ))
    }
}

impl Bound {
    pub async fn serve(self) -> Result<()> {
        let Bound { origin, listener } = self;
        let self_ = origin;

        loop {
            let (stream, _) = listener.accept().await?;
            let me = Arc::clone(&self_);
            tokio::spawn(async move {
                let outer = Arc::clone(&me);
                let service = service_fn(move |req: Request<hyper::body::Incoming>| {
                    let me = Arc::clone(&outer);
                    async move {
                        if req.method() == Method::CONNECT {
                            return Ok::<_, std::convert::Infallible>(me.tunnel(req));
                        }
                        Ok(me.handle(req).await)
                    }
                });
                // Keep-alive is not a nicety here: a page pulls many subresources
                // and a fresh connection each time would add a local handshake per
                // request on top of the remote cost.
                //
                // `with_upgrades` is what lets the `CONNECT` above hand back the socket. Without
                // it the response would be sent and the connection then closed, which reads to
                // the browser as a proxy that accepted the tunnel and dropped it.
                let _ = http1::Builder::new()
                    .serve_connection(TokioIo::new(stream), service)
                    .with_upgrades()
                    .await;
            });
        }
    }
}

impl Origin {
    /// Answer `CONNECT <alias>.<suffix>:443`, then speak TLS inside the socket.
    ///
    /// This is the whole of the https mode's plumbing. The browser will not send an https request
    /// to a proxy in the clear; it asks for a tunnel, and whatever answers inside that tunnel has
    /// to present a certificate for the name it asked for. So the daemon is both the proxy and
    /// the server on the other side of it.
    ///
    /// The target is checked before the tunnel is granted, and checked by the same `classify` that
    /// guards every other request. A proxy that tunnels anywhere is an open proxy, and this one
    /// listens on loopback where every process on the machine can reach it.
    fn tunnel(self: &Arc<Self>, mut req: Request<hyper::body::Incoming>) -> Response<Full<Bytes>> {
        // `CONNECT` puts the target in the authority, not the path: `CONNECT host:443 HTTP/1.1`.
        let Some(authority) = req.uri().authority().map(ToString::to_string) else {
            return fail(StatusCode::BAD_REQUEST, "CONNECT carries no authority");
        };

        // The guards run first, before anything about the https mode is consulted. Two reasons:
        // they are the part that has to hold in either mode, and a daemon that answered "https is
        // not configured" to a tunnel it would refuse anyway has told the caller something about
        // its configuration in exchange for nothing.
        //
        // Only a name this daemon serves, and only its https port. Tunnelling anywhere else would
        // turn a loopback listener into a way out of the machine for whatever can reach it —
        // including a page, through its own subresource loads.
        let (name, port) = match authority.rsplit_once(':') {
            Some((name, port)) => (name, port),
            None => (authority.as_str(), "443"),
        };
        if port != "443" {
            return fail(
                StatusCode::FORBIDDEN,
                format!("CONNECT to port {port} is refused; only 443 is tunnelled"),
            );
        }
        if guard::classify(name, "/", &self.suffix, self.port).is_err() {
            return fail(
                StatusCode::FORBIDDEN,
                format!("{name:?} is not a name this daemon serves"),
            );
        }

        let Some(config) = self.tls.clone() else {
            return fail(
                StatusCode::NOT_IMPLEMENTED,
                concat!(
                    "this daemon serves http; CONNECT needs the https mode and a certificate. ",
                    "Set scheme = \"https\" and see `ssh-browser trust`.",
                ),
            );
        };

        let me = Arc::clone(self);
        let upgrade = hyper::upgrade::on(&mut req);
        tokio::spawn(async move {
            let Ok(upgraded) = upgrade.await else {
                return;
            };
            let acceptor = tokio_rustls::TlsAcceptor::from(config);
            let tls = match acceptor.accept(TokioIo::new(upgraded)).await {
                Ok(tls) => {
                    me.handshakes.completed.fetch_add(1, Ordering::Relaxed);
                    tls
                }
                Err(e) => {
                    // Reported, and this used to be silent. The browser shows the reader
                    // `ERR_CERT_AUTHORITY_INVALID` on the page — but the fix is a command, and
                    // commands live in the terminal, which is where nothing was being said.
                    //
                    // Only the first, because a page pulls many subresources and every one of
                    // them fails the same way: the second copy onwards is noise around the one
                    // line that matters.
                    if me.handshakes.failed.fetch_add(1, Ordering::Relaxed) == 0 {
                        eprintln!();
                        eprintln!("a browser refused the certificate: {e}");
                        // Two calls rather than one string with a line continuation in it. Three
                        // separate messages here have now shipped carrying the source file's own
                        // indentation into the middle of a sentence.
                        eprintln!("  almost always the local authority is not trusted yet.");
                        eprintln!("  `ssh-browser trust` prints how to trust it.");
                    }
                    return;
                }
            };
            // Inside the tunnel the requests are ordinary origin-form GETs carrying a `Host`,
            // so they go through exactly the same handler as the http mode. That is the point of
            // terminating here rather than proxying onwards: one request path, one set of
            // guards, and https is a property of the socket rather than a second server.
            let service = service_fn(move |req: Request<hyper::body::Incoming>| {
                let me = Arc::clone(&me);
                async move { Ok::<_, std::convert::Infallible>(me.handle(req).await) }
            });
            let _ = http1::Builder::new()
                .serve_connection(TokioIo::new(tls), service)
                .await;
        });

        // 200 with no body is what the proxy protocol wants; the socket becomes the tunnel.
        Response::builder()
            .status(StatusCode::OK)
            .body(Full::new(Bytes::new()))
            .unwrap_or_else(|_| fail(StatusCode::INTERNAL_SERVER_ERROR, "building the tunnel"))
    }
}

impl Origin {
    /// Generic over the body type so a test can drive it without constructing
    /// hyper's `Incoming`, which only a real connection can produce.
    pub async fn handle<B>(&self, req: Request<B>) -> Response<Full<Bytes>>
    where
        B: hyper::body::Body,
        B::Error: Into<Box<dyn std::error::Error + Send + Sync>>,
    {
        let Some(host) = host_of(&req) else {
            return fail(StatusCode::BAD_REQUEST, "request carries no Host");
        };
        let path = req.uri().path().to_string();
        let cond = Conditions {
            if_none_match: header(&req, IF_NONE_MATCH),
            range: header(&req, RANGE),
            if_range: header(&req, IF_RANGE),
            control_token: req
                .headers()
                .get(control::TOKEN_HEADER)
                .and_then(|v| v.to_str().ok())
                .map(str::to_string),
            fetch_site: req
                .headers()
                .get(control::FETCH_SITE_HEADER)
                .and_then(|v| v.to_str().ok())
                .map(str::to_string),
        };
        let method = req.method().clone();
        let query = req.uri().query().map(str::to_string);

        // The body is read for the control prefix and nowhere else. Reading it on every
        // request would let any caller make the daemon hold memory it has no use for.
        let control_body = if path.starts_with(control::PATH_PREFIX) {
            match read_body(req.into_body()).await {
                Ok(b) => b,
                Err(e) => return fail(StatusCode::BAD_REQUEST, e),
            }
        } else {
            Bytes::new()
        };

        match guard::classify(&host, &path, &self.suffix, self.port) {
            // Refusing by Host is the DNS-rebinding defence, not a malfunction, so
            // it says why rather than failing blankly.
            Err(e) => fail(StatusCode::FORBIDDEN, format!("{e:#}")),
            Ok(guard::Target::Direct { path }) => {
                self.direct(&method, path, &cond, query.as_deref(), &control_body)
                    .await
            }
            Ok(guard::Target::Alias { alias, path }) => {
                self.alias(&method, alias, path, &cond, query.as_deref())
                    .await
            }
        }
    }

    async fn direct(
        &self,
        method: &Method,
        path: &str,
        cond: &Conditions,
        query: Option<&str>,
        body: &[u8],
    ) -> Response<Full<Bytes>> {
        // Reachable only from a loopback Host, which `guard::classify` has already
        // separated from alias requests. An alias page cannot arrive here.
        if path.starts_with(control::PATH_PREFIX) {
            // First, and separately from the token: no page reaches this API at all,
            // whatever it has got hold of.
            if control::from_a_page(cond.fetch_site.as_deref()) {
                return control::text(
                    StatusCode::FORBIDDEN,
                    "the control API is not reachable from a page",
                );
            }
            // The handshake, and the only route that does not need the token -- it is
            // where the token comes from. Handing it over is safe precisely because the
            // line above has already established that nothing page-shaped is asking, and
            // a caller that is not a browser at all could read the token file anyway.
            //
            // This is what removes the paste. An extension cannot read a file, so before
            // this the first run meant copying sixty-four hex characters out of a terminal.
            if method == Method::GET && control::route_of(path) == "token" {
                return control::text(StatusCode::OK, self.token.as_str());
            }
            // Every other control route goes through the gate, and there is no way past
            // it. The gate repeats the page check rather than trusting the branch above to
            // have run, so that no future route can reach it having skipped one.
            if let Some(refusal) = control::gate(
                method,
                cond.fetch_site.as_deref(),
                cond.control_token.as_deref(),
                &self.token,
            ) {
                return refusal;
            }
            return self.control(method, path, body).await;
        }

        if path == "/proxy.pac" {
            return match pac::script(&self.suffix, self.port) {
                Ok(body) => plain_ok("application/x-ns-proxy-autoconfig", Bytes::from(body)),
                Err(e) => fail(StatusCode::INTERNAL_SERVER_ERROR, format!("{e:#}")),
            };
        }

        let rest = path.trim_start_matches('/');
        if rest.is_empty() {
            return plain_ok(
                "text/html; charset=utf-8",
                Bytes::from(self.alias_index().await),
            );
        }

        let (alias, sub) = rest.split_once('/').unwrap_or((rest, ""));
        self.alias(method, alias, &format!("/{sub}"), cond, query)
            .await
    }

    async fn alias(
        &self,
        method: &Method,
        alias: &str,
        path: &str,
        cond: &Conditions,
        query: Option<&str>,
    ) -> Response<Full<Bytes>> {
        // The alias origin is read-only, and says so rather than quietly serving a POST
        // as if it were a GET. The shape of this answer is part of the boundary: there
        // is no write path on this origin and there will not be one. Writes go through
        // the control API, which a page served from here cannot reach.
        if !matches!(*method, Method::GET | Method::HEAD) {
            return fail(
                StatusCode::METHOD_NOT_ALLOWED,
                format!("{method} is not allowed: this origin is read-only"),
            );
        }

        let Some(session) = self.session(alias).await else {
            return fail(StatusCode::NOT_FOUND, format!("no alias named {alias:?}"));
        };
        let session = session.as_ref();
        let resolved = match guard::resolve(&session.base, path) {
            Ok(p) => p,
            Err(e) => return fail(StatusCode::FORBIDDEN, format!("{e:#}")),
        };

        let wants_dir = path.ends_with('/');
        let file = if wants_dir {
            format!("{resolved}/index.html")
        } else {
            resolved.clone()
        };

        // Every component between the alias base and the file, base first. The base
        // itself is not checked: it is what the operator configured, and no request
        // can change it.
        let chain = components(&session.base, &file);
        if chain.is_empty() {
            return self
                .autoindex_of(session, alias, path, &resolved, query)
                .await;
        }
        let last = chain.len() - 1;

        // Settled before anything is asked of the remote, because unlike a symlink this needs
        // nothing from the remote to decide — and deciding it later would mean asking the
        // remote to open `.ssh` in order to then refuse it.
        if let Some((_, name)) = chain.iter().find(|(_, n)| hidden(n)) {
            return fail(
                StatusCode::FORBIDDEN,
                format!("refusing {name}: names beginning with a dot are not served"),
            );
        }

        let held = match self.listings_along(session, &chain).await {
            Ok(held) => held,
            // Whatever ssh said, rather than this daemon's word for not knowing.
            Err((at, why)) => {
                return fail(
                    StatusCode::BAD_GATEWAY,
                    format!("{path}: listing {at} failed: {why}"),
                );
            }
        };

        // Symlinks are settled before anything else, so the answer cannot depend on
        // whether the target happens to exist: a symlink is refused either way, and
        // checking it separately is what lets the write path share exactly this rule.
        if let Some(at) = first_symlink(&held, &chain) {
            return fail(
                StatusCode::FORBIDDEN,
                format!("refusing symlink at {at} (its target is not checked)"),
            );
        }

        let mut found_last = None;
        for (i, (dir, name)) in chain.iter().enumerate() {
            let Some(attrs) = attrs_in(&held, dir, name) else {
                // Absent. For a directory request that only means there is no
                // index.html, so fall through to a listing of the directory itself.
                if i == last && wants_dir {
                    return self
                        .autoindex_of(session, alias, path, &resolved, query)
                        .await;
                }
                return fail(StatusCode::NOT_FOUND, format!("not found: {path}"));
            };

            if i < last && !attrs.is_dir() {
                return fail(
                    StatusCode::NOT_FOUND,
                    format!("{path}: {dir}/{name} is not a directory"),
                );
            }
            if i == last {
                found_last = Some(attrs);
            }
        }
        let attrs = found_last.expect("the walk assigns on its final iteration");

        if attrs.is_dir() {
            if wants_dir {
                // `<dir>/index.html` is itself a directory. Fall back to a listing.
                return self
                    .autoindex_of(session, alias, path, &resolved, query)
                    .await;
            }
            // Without the trailing slash every relative link on the page below
            // would resolve one level too high.
            return redirect(&format!("{path}/"));
        }

        let tag = cache::etag(&attrs);

        // The conditional GET never leaves this process: the validator came from the
        // cached listing, so a browser already holding the current copy is answered
        // with zero remote round trips. That is invariant 2.
        if let (Some(tag), Some(header)) = (tag.as_deref(), cond.if_none_match.as_deref())
            && cache::etag_matches(header, tag)
        {
            return not_modified(tag);
        }

        // Size comes from the listing, which is what makes a range answerable without
        // first fetching the file to discover how long it is.
        let size = attrs.size.unwrap_or(0);
        let wanted = match cond.range.as_deref() {
            Some(header) => range::resolve(header, cond.if_range.as_deref(), size),
            None => range::Resolved::Whole,
        };
        if wanted == range::Resolved::Unsatisfiable {
            return unsatisfiable(size);
        }

        // A body already held answers a range by slicing, with no round trip at all.
        if let Some(body) = self.cache.body(&file, &attrs) {
            return respond(&file, body, tag.as_deref(), &wanted, size);
        }

        // Too large to hold: fetch only what was asked for. This branch is what makes
        // seeking in a video possible. Without it a seek pulls the whole file, and
        // holding that file would evict every page body that makes a revisit free.
        if let range::Resolved::Part { start, end } = wanted
            && size > CACHE_WHOLE_MAX
        {
            let req = RangeReq {
                path: file.clone(),
                offset: start,
                len: end - start + 1,
            };
            let mut got = session.fs.read_ranges(std::slice::from_ref(&req)).await;
            return match got.pop() {
                Some(Ok(body)) => partial(
                    mime::guess(&file),
                    Bytes::from(body),
                    tag.as_deref(),
                    start,
                    end,
                    size,
                ),
                Some(Err(e)) => {
                    self.cache.forget_listing(&chain[last].0);
                    fail(StatusCode::NOT_FOUND, format!("{path}: {e:#}"))
                }
                None => fail(
                    StatusCode::INTERNAL_SERVER_ERROR,
                    "read_ranges returned no result",
                ),
            };
        }

        // The length the listing already gave is what turns this from a poll into one round
        // trip. `read_batch` cannot know how long a file is, so it asks for 32 KiB at a time
        // until a short read tells it to stop: one round trip per chunk index. `read_ranges`
        // is handed the length and issues every chunk before awaiting any, so the file costs
        // one however long it is. The prefetcher has always done this; the request a reader
        // actually waits on did not.
        //
        // It is the direct path that needs it most, because the files that reach it are the
        // ones the prefetcher could not have warmed: the page itself, which has to be read
        // before it can be scanned, and anything a script fetches at runtime. Measured
        // against real Documenter output — a 700 KB `index.html` and a 2 MB
        // `search_index.js`, neither of them visible to an HTML scan — the page cost 95
        // remote round trips before this and 26 after. What remains is listings, which
        // expire before a slow page has finished loading; that is a separate problem.
        let mut got = match size {
            0 => session.fs.read_batch(std::slice::from_ref(&file)).await,
            size => {
                let req = RangeReq {
                    path: file.clone(),
                    offset: 0,
                    len: size,
                };
                let mut ranged = session.fs.read_ranges(std::slice::from_ref(&req)).await;
                match ranged.pop() {
                    Some(Ok(body)) if body.len() as u64 == size => vec![Ok(body)],
                    // Anything else means the listing no longer describes the file, or the
                    // read failed. Falling back to the poll rather than answering with what
                    // arrived: a body shorter than the length it is served with is precisely
                    // the silent truncation this daemon must not produce, and the poll finds
                    // the real length or the real error. It costs a round trip in a case that
                    // is a race, and nothing in the case that is not.
                    _ => session.fs.read_batch(std::slice::from_ref(&file)).await,
                }
            }
        };
        match got.pop() {
            Some(Ok(body)) => {
                let body = Bytes::from(body);
                self.cache.put_body(&file, &attrs, body.clone());
                // Before answering, not after. The browser will ask for this page's
                // subresources six at a time, and each wave it has to discover is a round
                // trip; fetching them here costs one and makes the waves cache hits. Waiting
                // also makes the invariant a guarantee rather than a race with the browser.
                if mime::guess(&file).starts_with("text/html") {
                    self.warm_subresources(session, path, &body).await;
                }
                respond(&file, body, tag.as_deref(), &wanted, size)
            }
            // The listing promised this file and the remote refused it, so the listing
            // is wrong. Holding it for the rest of its TTL would repeat the same wrong
            // answer.
            Some(Err(e)) => {
                self.cache.forget_listing(&chain[last].0);
                fail(StatusCode::NOT_FOUND, format!("{path}: {e:#}"))
            }
            None => fail(
                StatusCode::INTERNAL_SERVER_ERROR,
                "read_batch returned no result",
            ),
        }
    }

    async fn control(&self, method: &Method, path: &str, body: &[u8]) -> Response<Full<Bytes>> {
        match (method, control::route_of(path)) {
            (&Method::GET, "hello") => {
                let aliases = self.alias_names().await;
                control::hello(
                    &aliases,
                    &self.suffix,
                    &self.scheme,
                    self.round_trips().await,
                    self.tls.is_some().then(|| control::Handshakes {
                        completed: self.handshakes.completed.load(Ordering::Relaxed),
                        failed: self.handshakes.failed.load(Ordering::Relaxed),
                    }),
                )
            }
            (&Method::GET, "hosts") => self.list_hosts().await,
            (&Method::POST, "open") => self.open_host(body).await,
            (&Method::POST, "close") => self.close_alias(body).await,
            (&Method::POST, "enabled") => self.set_enabled(body).await,
            (&Method::GET, "theme") => self.show_theme().await,
            (&Method::POST, "theme") => self.set_theme(body).await,
            (&Method::GET, route) => {
                control::text(StatusCode::NOT_FOUND, format!("no control route {route:?}"))
            }
            (_, route) => control::text(
                StatusCode::METHOD_NOT_ALLOWED,
                format!("{method} is not allowed on {route:?}"),
            ),
        }
    }

    /// `GET /_control/hosts`
    ///
    /// What ssh already knows how to reach, which is the list the extension offers. It
    /// comes from `~/.ssh/config` rather than from this daemon's own configuration,
    /// because a host you can already `ssh` to is a host you should be able to open
    /// without writing it down a second time.
    ///
    /// Answering this connects to nothing. It is a list of what could be opened, and a
    /// daemon that opened six ssh sessions to answer a popup would make looking at the
    /// list cost more than using it.
    async fn list_hosts(&self) -> Response<Full<Bytes>> {
        let found = match ssh_config::read() {
            Ok(found) => found,
            Err(e) => {
                return control::text(
                    StatusCode::INTERNAL_SERVER_ERROR,
                    format!("reading ssh_config: {e:#}"),
                );
            }
        };

        // Every `ssh -G` at once. One subprocess per host is cheap, but run in sequence
        // the list would take the sum of them, and this is the request a reader waits on
        // before they can do anything at all.
        let described: Vec<_> = found
            .hosts
            .iter()
            .map(|h| {
                let host = h.host.clone();
                tokio::spawn(async move { ssh_config::describe(&host).await })
            })
            .collect();

        let open = {
            let sessions = self.sessions.read().await;
            let mut open: Vec<OpenAlias> = sessions
                .iter()
                .map(|(alias, s)| OpenAlias {
                    alias: alias.clone(),
                    host: s.host.clone(),
                    base: s.base.clone(),
                    url: self.site_url(alias),
                    trips: s.fs.round_trips(),
                })
                .collect();
            open.sort_by(|a, b| a.alias.cmp(&b.alias));
            open
        };
        // Read once, before the loop, rather than taking the lock per host.
        let enabled: Vec<String> = self
            .reachable
            .read()
            .await
            .enabled()
            .map(|h| h.name.clone())
            .collect();
        let mut hosts = Vec::with_capacity(found.hosts.len());
        for (h, task) in found.hosts.iter().zip(described) {
            // A host ssh cannot describe is still listed, with the reason attached.
            // Dropping it would make a misconfigured host look like one that is not in
            // the file, and those have different fixes.
            let (settings, unresolved) = match task.await {
                Ok(Ok(settings)) => (settings, None),
                Ok(Err(e)) => (ssh_config::Settings::default(), Some(format!("{e:#}"))),
                Err(e) => (ssh_config::Settings::default(), Some(e.to_string())),
            };
            hosts.push(KnownHost {
                alias: h.alias.clone(),
                host: h.host.clone(),
                settings,
                served: open.iter().any(|o| o.alias == h.alias),
                enabled: enabled.iter().any(|name| name == &h.alias),
                unresolved,
            });
        }
        control::json(&KnownHosts {
            open,
            hosts,
            unusable: found.unusable,
            tls: self.tls.is_some().then(|| control::Handshakes {
                completed: self.handshakes.completed.load(Ordering::Relaxed),
                failed: self.handshakes.failed.load(Ordering::Relaxed),
            }),
        })
    }

    /// `POST /_control/open` -- start serving one of the hosts ssh already knows.
    ///
    /// This is what replaces configuring an alias before you can look at anything. The
    /// host is picked from the list, the daemon connects, and the URL comes back.
    ///
    /// **Only a host named in ssh_config can be opened.** Not because the token is
    /// insufficient, but because "ssh to an arbitrary host on request" is a larger
    /// primitive than this needs to be, and the list the extension offers is already the
    /// menu. A host that is not on it is a config change, which is a deliberate act.
    async fn open_host(&self, body: &[u8]) -> Response<Full<Bytes>> {
        #[derive(serde::Deserialize)]
        #[serde(deny_unknown_fields)]
        struct Ask {
            host: String,
            /// Absolute, or `~`, or `~/path`. Absent means the home directory.
            #[serde(default)]
            base: Option<String>,
        }

        let ask: Ask = match serde_json::from_slice(body) {
            Ok(ask) => ask,
            Err(e) => {
                return control::text(
                    StatusCode::BAD_REQUEST,
                    format!("open needs a JSON body naming a host: {e}"),
                );
            }
        };

        let found = match ssh_config::read() {
            Ok(found) => found,
            Err(e) => {
                return control::text(
                    StatusCode::INTERNAL_SERVER_ERROR,
                    format!("reading ssh_config: {e:#}"),
                );
            }
        };
        // Matched against ssh_config rather than trusted, and matched case-insensitively
        // because that is how hostnames compare: the extension shows `panza` and the file
        // says `Panza`.
        let Some(known) = found
            .hosts
            .iter()
            .find(|h| h.host.eq_ignore_ascii_case(&ask.host) || h.alias == ask.host)
        else {
            return control::text(
                StatusCode::NOT_FOUND,
                format!("{:?} is not a host in your ssh_config", ask.host),
            );
        };

        let alias = match Alias::new(&known.alias, &known.host, ask.base.as_deref()) {
            Ok(alias) => alias,
            Err(e) => return control::text(StatusCode::BAD_REQUEST, format!("{e:#}")),
        };

        // Already open is an answer, not an error: two tabs asking at once should both
        // get the URL. A *different* base is refused, though. Reconnecting under one
        // would change what an origin means underneath any page already open in it,
        // which is the one thing an origin must not do.
        if let Some(open) = self.session(&known.alias).await {
            // Asking for no base is asking for no particular one, so an alias already
            // open is simply the answer. The popup relies on this: it opens a host by
            // naming it, and a host the config file already roots somewhere would
            // otherwise answer a plain click with a conflict about a base nobody asked for.
            let Some(asked) = alias.base() else {
                return self.opened(&known.alias, &known.host, &open.base);
            };
            // Resolved against the session that is already there, rather than compared as
            // written. `~/work` and `/home/souta/work` are the same base, and a check that
            // could not tell would either refuse an identical request or -- worse -- accept
            // a different one, handing back a URL rooted somewhere the caller did not ask
            // for. The round trip is paid on a path that is not a page load.
            let wanted = match resolve_base(Some(asked), &open.fs).await {
                Ok(base) => base,
                Err(e) => {
                    return control::text(
                        StatusCode::BAD_GATEWAY,
                        format!("working out where to root {}: {e:#}", known.alias),
                    );
                }
            };
            if wanted != open.base {
                return control::text(
                    StatusCode::CONFLICT,
                    format!(
                        "{} is already open at {}, and {} is not the same place; a second base would change what that origin means underneath any page open in it",
                        known.alias, open.base, wanted
                    ),
                );
            }
            return self.opened(&known.alias, &known.host, &open.base);
        }

        let fs = match SftpFs::connect(&known.host).await {
            Ok(fs) => fs,
            Err(e) => {
                // The reason is passed through rather than flattened to "could not
                // connect". It is ssh's, and ssh's reasons are the ones with a fix in
                // them: a jump host that is down, a key that is not loaded, a name that
                // does not resolve.
                return control::text(
                    StatusCode::BAD_GATEWAY,
                    format!("ssh to {}: {e:#}", known.host),
                );
            }
        };
        let base = match resolve_base(alias.base(), &fs).await {
            Ok(base) => base,
            Err(e) => {
                return control::text(
                    StatusCode::BAD_GATEWAY,
                    format!("working out where to root {}: {e:#}", known.alias),
                );
            }
        };

        // Inserted under the write lock, and a session that lost the race is dropped
        // rather than replacing the winner. Dropping it closes that ssh child, which is
        // the right end for a connection nothing is using; replacing the winner would
        // close one that requests are already going through.
        let session = {
            let mut sessions = self.sessions.write().await;
            Arc::clone(sessions.entry(known.alias.clone()).or_insert_with(|| {
                Arc::new(Session {
                    host: known.host.clone(),
                    base,
                    fs,
                })
            }))
        };
        self.opened(&known.alias, &known.host, &session.base)
    }

    /// `POST /_control/close` -- stop serving an alias.
    ///
    /// The other half of `open`, and what makes changing where an alias is rooted possible
    /// at all: reopening under a second base is refused while the first is live, because
    /// it would change what an origin means underneath any page open in it. Closing first
    /// makes that an act somebody chose rather than something that happened to them.
    ///
    /// Also the only way to give back an ssh connection without stopping the daemon.
    async fn close_alias(&self, body: &[u8]) -> Response<Full<Bytes>> {
        #[derive(serde::Deserialize)]
        #[serde(deny_unknown_fields)]
        struct Ask {
            alias: String,
        }

        let ask: Ask = match serde_json::from_slice(body) {
            Ok(ask) => ask,
            Err(e) => {
                return control::text(
                    StatusCode::BAD_REQUEST,
                    format!("close needs a JSON body naming an alias: {e}"),
                );
            }
        };

        // Removed under the write lock, so two callers cannot both believe they closed it.
        // Dropping the `Arc` is what ends the ssh session, and a request already in flight
        // holds one — so the connection goes when the last reader is done with it rather
        // than out from under them.
        let gone = self.sessions.write().await.remove(&ask.alias);
        match gone {
            Some(session) => {
                #[derive(serde::Serialize)]
                struct Closed<'a> {
                    alias: &'a str,
                    host: &'a str,
                    base: &'a str,
                }
                control::json(&Closed {
                    alias: &ask.alias,
                    host: &session.host,
                    base: &session.base,
                })
            }
            // Distinguished from success on purpose. "Closed something" and "there was
            // nothing to close" look identical to a caller that is told neither, and the
            // second usually means the alias was spelled wrong.
            None => control::text(
                StatusCode::NOT_FOUND,
                format!("no alias named {:?} is open", ask.alias),
            ),
        }
    }

    /// Connect one host and work out where it is rooted.
    ///
    /// Owns its arguments and borrows nothing, so it can run in a task and several of them can
    /// run at once. Does not touch the session map: dialling and adopting are separated so that
    /// the concurrent path at startup and the one-at-a-time path behind a toggle share the part
    /// that talks to ssh, rather than each having a copy of it to drift.
    async fn dial(alias: String, host: String, base: Option<String>) -> Result<Session> {
        let fs = SftpFs::connect(&host)
            .await
            .with_context(|| format!("ssh to {host}"))?;
        let resolved = resolve_base(base.as_deref(), &fs)
            .await
            .with_context(|| format!("working out where to root {alias}"))?;
        Ok(Session {
            host,
            base: resolved,
            fs,
        })
    }

    /// Put a connected session in the map, or keep the one that got there first.
    ///
    /// A session that lost the race is dropped rather than replacing the winner. Dropping it
    /// closes that ssh child, which is the right end for a connection nothing is using;
    /// replacing the winner would close one that requests are already going through.
    async fn adopt(&self, alias: &str, session: Session) -> Arc<Session> {
        let mut sessions = self.sessions.write().await;
        Arc::clone(
            sessions
                .entry(alias.to_string())
                .or_insert_with(|| Arc::new(session)),
        )
    }

    async fn connect(&self, alias: &str, host: &str, base: Option<&str>) -> Result<Arc<Session>> {
        let session = Self::dial(
            alias.to_string(),
            host.to_string(),
            base.map(str::to_string),
        )
        .await?;
        Ok(self.adopt(alias, session).await)
    }

    /// Open every enabled host, at once, and say which ones would not.
    ///
    /// At once rather than in turn: these are independent ssh handshakes, and in sequence six
    /// hosts would cost the sum of six round-trip times before the daemon answered anything.
    async fn open_enabled(&self) -> (Vec<String>, Vec<String>) {
        let wanted: Vec<reachable::Host> = self.reachable.read().await.enabled().cloned().collect();
        if wanted.is_empty() {
            return (Vec::new(), Vec::new());
        }

        // Looked up in ssh_config rather than dialled by the name in the file, for two reasons
        // and the second is the important one.
        //
        // The name in the file is the *label* — lowercase, because it becomes a hostname — and
        // the ssh_config `Host` it came from need not be spelled the same. A file saying
        // `panza` for a config that says `Panza` produced `Could not resolve hostname panza` on
        // every start, while enabling it in the first place had worked: that path had the
        // ssh_config entry in hand and this one only had the label.
        //
        // And it is the same gate `open` and `enabled` have. Without it this is a path that
        // ssh's to whatever names are in a file, with no check that ssh has ever heard of them
        // — a second, looser door into the one thing this daemon is careful about.
        let known = match ssh_config::read() {
            Ok(found) => found.hosts,
            Err(e) => {
                let mut refused: Vec<String> = wanted
                    .iter()
                    .map(|h| {
                        format!(
                            "  {} is enabled but ssh_config could not be read: {e:#}",
                            h.name
                        )
                    })
                    .collect();
                refused.sort();
                return (Vec::new(), refused);
            }
        };

        let mut dialling = tokio::task::JoinSet::new();
        let mut refused = Vec::new();
        for host in wanted {
            let Some(entry) = entry_for(&known, &host.name) else {
                // Named and gone: the ssh_config entry was renamed or removed since this was
                // turned on. Said rather than retried silently, because the fix is in a file
                // the reader owns.
                refused.push(format!(
                    "  {} is enabled but is no longer a host in your ssh_config",
                    host.name
                ));
                continue;
            };
            let (label, target) = (entry.alias.clone(), entry.host.clone());
            dialling.spawn(async move {
                let got = Self::dial(label.clone(), target, host.base.clone()).await;
                (label, got)
            });
        }

        let mut opened = Vec::new();
        while let Some(finished) = dialling.join_next().await {
            let (name, got) = match finished {
                Ok(pair) => pair,
                // The task itself failed rather than the ssh in it -- a panic. Reported the same
                // way, because from here it is the same fact: this host is not being served and
                // the reader has to be told which one.
                Err(e) => {
                    refused.push(format!("  an enabled host could not be opened: {e}"));
                    continue;
                }
            };
            match got {
                Ok(session) => {
                    let base = session.base.clone();
                    self.adopt(&name, session).await;
                    opened.push(format!(
                        "  {}://{name}.{}/  ->  {name}:{base}",
                        self.scheme, self.suffix
                    ));
                }
                // ssh's own words, not "could not connect". ssh's reasons are the ones with a
                // fix in them: a jump host that is down, a key that is not loaded, a name that
                // does not resolve.
                Err(e) => refused.push(format!("  {name} is enabled but did not answer: {e:#}")),
            }
        }
        opened.sort();
        refused.sort();
        (opened, refused)
    }

    fn opened(&self, alias: &str, host: &str, base: &str) -> Response<Full<Bytes>> {
        #[derive(serde::Serialize)]
        struct Opened<'a> {
            alias: &'a str,
            host: &'a str,
            base: &'a str,
            url: String,
        }
        control::json(&Opened {
            alias,
            host,
            base,
            url: self.site_url(alias),
        })
    }

    /// `POST /_control/enabled` -- open a host every run, or stop.
    ///
    /// The difference from `open` is that this is remembered. `open` serves a host until the
    /// daemon stops; this says to open it next time too, which is what turns "click the host,
    /// then use the URL" into "use the URL".
    ///
    /// Turning one on connects it now as well, because a setting that only took effect after a
    /// restart would be indistinguishable from one that did not work. Turning one off closes it
    /// now, for the same reason in reverse: a host still answering after you switched it off
    /// reads as the switch having failed.
    async fn set_enabled(&self, body: &[u8]) -> Response<Full<Bytes>> {
        #[derive(serde::Deserialize)]
        #[serde(deny_unknown_fields)]
        struct Ask {
            host: String,
            enabled: bool,
            /// Where to root it, for the first time it is turned on.
            #[serde(default)]
            base: Option<String>,
        }

        let ask: Ask = match serde_json::from_slice(body) {
            Ok(ask) => ask,
            Err(e) => {
                return control::text(
                    StatusCode::BAD_REQUEST,
                    format!("enabled needs a JSON body naming a host and whether it is on: {e}"),
                );
            }
        };

        // The same gate `open` has, and for the same reason: "ssh to an arbitrary host on
        // request" is a larger primitive than this needs to be, and the ssh_config list is
        // already the menu. Checked before anything is remembered, so a typo does not leave a
        // name in the file that will be retried at every start forever.
        let found = match ssh_config::read() {
            Ok(found) => found,
            Err(e) => {
                return control::text(
                    StatusCode::INTERNAL_SERVER_ERROR,
                    format!("reading ssh_config: {e:#}"),
                );
            }
        };
        let Some(known) = found
            .hosts
            .iter()
            .find(|h| h.host.eq_ignore_ascii_case(&ask.host) || h.alias == ask.host)
        else {
            return control::text(
                StatusCode::NOT_FOUND,
                format!("{:?} is not a host in your ssh_config", ask.host),
            );
        };

        // Held to the same rules an alias is, before it is written down anywhere. A name that
        // cannot be a hostname label would be remembered and then refused on every request.
        if let Err(e) = Alias::new(&known.alias, &known.host, ask.base.as_deref()) {
            return control::text(StatusCode::BAD_REQUEST, format!("{e:#}"));
        }

        if ask.enabled {
            // Connected before it is remembered. A host that cannot be reached is not written
            // into the file, so the answer is the same failure `open` would give rather than a
            // silent "saved" followed by a URL that does not work.
            if self.session(&known.alias).await.is_none()
                && let Err(e) = self
                    .connect(&known.alias, &known.host, ask.base.as_deref())
                    .await
            {
                return control::text(StatusCode::BAD_GATEWAY, format!("{e:#}"));
            }
        } else {
            self.sessions.write().await.remove(&known.alias);
        }

        let remembered = {
            let mut set = self.reachable.write().await;
            set.set(&known.alias, ask.enabled, ask.base.clone());
            // Best effort, and reported beside the result rather than instead of it: failing to
            // write a file under the state directory must not undo a change that has already
            // taken effect.
            reachable::remember(&set).is_ok()
        };

        #[derive(serde::Serialize)]
        struct Switched<'a> {
            host: &'a str,
            enabled: bool,
            remembered: bool,
            url: Option<String>,
        }
        control::json(&Switched {
            host: &known.alias,
            enabled: ask.enabled,
            remembered,
            url: ask.enabled.then(|| self.site_url(&known.alias)),
        })
    }

    /// `GET /_control/theme` -- what listings look like, and what else they could.
    async fn show_theme(&self) -> Response<Full<Bytes>> {
        #[derive(serde::Serialize)]
        struct Choice<'a> {
            name: &'a str,
            label: &'a str,
            /// `light`, `dark`, or `system`, so the dashboard can group them.
            variant: &'a str,
        }
        #[derive(serde::Serialize)]
        struct Themes<'a> {
            current: &'a str,
            themes: Vec<Choice<'a>>,
        }
        // The list comes from the daemon rather than being written out again in the
        // dashboard. Two copies of it is how a theme gets added and stays invisible.
        control::json(&Themes {
            current: &self.theme.read().await,
            themes: theme::all()
                .iter()
                .map(|t| Choice {
                    name: &t.name,
                    label: &t.label,
                    variant: t.variant,
                })
                .collect(),
        })
    }

    /// `POST /_control/theme` -- choose one, and remember it.
    async fn set_theme(&self, body: &[u8]) -> Response<Full<Bytes>> {
        #[derive(serde::Deserialize)]
        #[serde(deny_unknown_fields)]
        struct Ask {
            name: String,
        }
        let ask: Ask = match serde_json::from_slice(body) {
            Ok(ask) => ask,
            Err(e) => {
                return control::text(
                    StatusCode::BAD_REQUEST,
                    format!("theme needs a JSON body naming one: {e}"),
                );
            }
        };
        // Checked before anything is changed, so a typo leaves the daemon as it was rather
        // than half-moved to a theme that does not exist.
        if let Err(e) = theme::check(&ask.name) {
            return control::text(StatusCode::BAD_REQUEST, format!("{e:#}"));
        }

        *self.theme.write().await = ask.name.clone();
        // Remembered on a best effort. Failing to write a file under the runtime directory
        // must not undo a change the reader can already see on the next listing, so it is
        // reported beside the result rather than instead of it.
        let remembered = theme::remember(&ask.name).is_ok();
        #[derive(serde::Serialize)]
        struct Chose<'a> {
            current: &'a str,
            remembered: bool,
        }
        control::json(&Chose {
            current: &ask.name,
            remembered,
        })
    }

    async fn autoindex_of(
        &self,
        session: &Session,
        alias: &str,
        path: &str,
        resolved: &str,
        query: Option<&str>,
    ) -> Response<Full<Bytes>> {
        // Taken from the resolved path rather than from the request, so the tree shows a
        // filename as it is spelled on disk rather than percent-escaped. `resolved` always
        // begins with the base, because that is what resolving it against the base means.
        let rel = resolved
            .strip_prefix(&session.base)
            .unwrap_or("")
            .to_string();
        let entries = match self.listing_of(session, resolved).await {
            Ok(entries) => entries,
            Err(e) => return fail(StatusCode::NOT_FOUND, format!("{path}: {e:#}")),
        };
        let sites = self.sites_among(session, resolved, &entries).await;

        // `?ls` is one level of the same tree, as the HTML fragment that goes inside it.
        // It is what the tree fetches when a folder is expanded.
        //
        // A fragment rather than JSON so that there is exactly one thing that knows how a
        // row is written. A JSON reply would mean a second renderer in the page's script,
        // in another language, which is two places for a class name to be spelled and one
        // of them to be spelled wrong.
        //
        // It is not a new capability either: a page under this alias can already read every
        // path under it, and this says no more than the listing below does.
        if query == Some("ls") {
            let mut out = String::new();
            render_level(&mut out, &rel, &rows_of(&entries, &sites), &[]);
            return plain_ok("text/html; charset=utf-8", Bytes::from(out));
        }

        // The ancestors are already in the cache: the walk that resolved this path warmed
        // every one of them to check for symlinks. So a tree opened four levels down costs
        // no more round trips than the listing it replaces.
        let mut levels = Vec::new();
        let mut at = session.base.clone();
        for part in rel.split('/').filter(|p| !p.is_empty()) {
            if let Some(entries) = self.cache.listing_entries(&at) {
                let here = at.strip_prefix(&session.base).unwrap_or("").to_string();
                // Only the level the reader is standing in is scanned for sites, so only it
                // can mark them. Scanning every level would multiply the one extra round
                // trip by the depth of the path, which is the thing this is careful not to
                // do; expanding a folder scans it, so a mark appears where you look.
                levels.push((here, rows_of(&entries, &HashSet::new())));
            }
            at.push('/');
            at.push_str(part);
        }
        levels.push((rel.clone(), rows_of(&entries, &sites)));

        plain_ok(
            "text/html; charset=utf-8",
            Bytes::from(autoindex(alias, &rel, &levels, &self.theme.read().await)),
        )
    }

    /// A directory's entries, from the cache when they are there.
    async fn listing_of(&self, session: &Session, dir: &str) -> Result<Vec<Entry>> {
        if let Some(entries) = self.cache.listing_entries(dir) {
            return Ok(entries);
        }
        let entries = session.fs.list_dir(dir).await?;
        self.cache.put_listing(dir, &entries);
        Ok(entries)
    }

    /// Which of these subdirectories are themselves sites.
    ///
    /// A directory holding an `index.html` is served *as* that page, so it is a site rather
    /// than a folder, and saying so is what souta actually asked for. Grouping the HTML in
    /// one listing does not find a Pinax board, because a board is `out/ft_demo/index.html`
    /// and the directory you are standing in has no HTML in it at all.
    ///
    /// One extra round trip, because every listing is issued together -- not one per
    /// subdirectory. It is spent on a directory listing and never on a page load, so the
    /// round-trip invariant for serving a page is untouched.
    ///
    /// It is also not purely a cost: the listings it fetches are the ones the next click
    /// needs, so stepping into any of these subdirectories afterwards costs nothing.
    async fn sites_among(
        &self,
        session: &Session,
        dir: &str,
        entries: &[Entry],
    ) -> HashSet<String> {
        /// Beyond this, the scan is buying less than it costs: a directory with hundreds of
        /// subdirectories is not one somebody is scanning by eye for a report.
        const MAX_SCAN: usize = 64;

        let names: Vec<&str> = entries
            .iter()
            .filter(|e| e.attrs.is_dir() && e.name != "." && e.name != ".." && !hidden(&e.name))
            .map(|e| e.name.as_str())
            .take(MAX_SCAN)
            .collect();
        if names.is_empty() {
            return HashSet::new();
        }

        let paths: Vec<String> = names.iter().map(|n| format!("{dir}/{n}")).collect();
        // Already-known listings are not asked for again. Going back up a level is the
        // ordinary case and would otherwise re-list every sibling.
        let missing: Vec<String> = paths
            .iter()
            .filter(|p| self.cache.listing_entries(p).is_none())
            .cloned()
            .collect();
        if !missing.is_empty() {
            for (path, got) in missing.iter().zip(session.fs.list_dirs(&missing).await) {
                if let Ok(entries) = got {
                    self.cache.put_listing(path, &entries);
                }
                // A subdirectory that cannot be listed is simply not a site. It is not an
                // error for this page: the reader asked for the directory they are in, and
                // a permission problem one level down is theirs to meet when they click.
            }
        }

        names
            .iter()
            .zip(paths.iter())
            .filter(|(_, path)| {
                self.cache.listing_entries(path).is_some_and(|listing| {
                    listing
                        .iter()
                        .any(|e| e.name == "index.html" && !e.attrs.is_dir())
                })
            })
            .map(|(name, _)| (*name).to_string())
            .collect()
    }

    /// Read what an HTML page is about to ask for, in one batch.
    ///
    /// One round trip to list the directories they live in, then one batch of reads — and
    /// neither grows with the number of subresources. When they sit beside the document, which
    /// is what a generated report looks like, the listing is already held and the listing round
    /// disappears.
    ///
    /// Two at most, and it really is two. The reads go through `read_ranges` rather than
    /// `read_batch` precisely so that this holds: `read_batch` has to poll in 32 KiB chunks
    /// because it does not know how long a file is, which made a one-megabyte bundle
    /// thirty-two round trips here. The listing already says how long each one is.
    ///
    /// Every reference goes through the same resolution and the same symlink rule as a real
    /// request, on purpose. A page is untrusted input, and a prefetcher that skipped those
    /// checks could be told to read a file the operator's configuration says is out of
    /// bounds. Serving it would still be refused, but reading it is already the wrong act.
    ///
    /// Failures are dropped in silence here, which is the one place in this codebase that is
    /// right: a reference that cannot be read is about to be requested for real, and that
    /// request reports the failure properly. Saying anything now would be guessing at whether
    /// the reader was going to care.
    async fn warm_subresources(&self, session: &Session, doc_path: &str, html: &[u8]) {
        let refs = prefetch::scan(html, prefetch::MAX_SUBRESOURCES);
        if refs.is_empty() {
            return;
        }
        // The directory the document is in, in URL terms, which is what a relative reference
        // on the page is relative to.
        let dir_of_doc = match doc_path.rsplit_once('/') {
            Some((head, _)) => head,
            None => "",
        };

        // Resolved first, so that a reference climbing out of the base is gone before it can
        // contribute a directory to list.
        let mut wanted: Vec<(String, Vec<(String, String)>)> = Vec::new();
        for r in &refs {
            let url = if r.starts_with('/') {
                r.clone()
            } else {
                format!("{dir_of_doc}/{r}")
            };
            let Ok(resolved) = guard::resolve(&session.base, &url) else {
                continue;
            };
            let chain = components(&session.base, &resolved);
            if chain.is_empty() {
                continue;
            }
            // The same rule the request path applies, applied here too — a page naming
            // `.ssh/id_ed25519` in an `<img src>` must not get it read into the cache on the
            // strength of the request that would refuse it never being made.
            if chain.iter().any(|(_, n)| hidden(n)) {
                continue;
            }
            // Checked against what is already known before anything new is listed. Without
            // this a page could get a directory behind a symlink listed purely by naming it,
            // and the symlink rule exists precisely so that the daemon does not go there.
            // The check runs again after the listings, for components not yet known.
            if self.first_symlink_cached(&chain).is_some() {
                continue;
            }
            // And every directory this reference would cause to be listed has to be one the
            // cache can already prove is not behind a symlink. `first_symlink` alone is not
            // enough: it sees only what is cached, so a symlink one level below the deepest
            // listing held is invisible to it and would be opened by the very batch meant to
            // discover it.
            if !chain
                .iter()
                .all(|(dir, _)| self.listable(&session.base, dir))
            {
                continue;
            }
            wanted.push((resolved, chain));
        }

        let all: Vec<(String, String)> = wanted.iter().flat_map(|(_, c)| c.clone()).collect();
        // Prefetching only ever makes a page faster, so a directory that would not list is
        // not an error for the request that triggered it: the subresource is fetched the
        // ordinary way afterwards and fails, or does not, on its own terms.
        let held = self.held_listings(session, &all).await;

        let mut to_read = Vec::new();
        for (resolved, chain) in &wanted {
            if first_symlink(&held, chain).is_some() {
                continue;
            }
            let (dir, name) = &chain[chain.len() - 1];
            let Some(attrs) = attrs_in(&held, dir, name) else {
                continue;
            };
            if attrs.is_dir() {
                continue;
            }
            // The size has to be known, and not merely defaulted to zero, because it is what
            // the read below asks for. A listing that did not report one leaves nothing to
            // ask for, and requesting zero bytes would cache an empty body for a file that
            // has contents.
            let Some(size) = attrs.size else {
                continue;
            };
            // Nothing to warm at zero, and warming it is where a listing that lies about the
            // size does damage: a ranged read asks for exactly what it was told, so a file
            // reported as empty is fetched as empty and then served that way. A real empty
            // file loses nothing by being read on request.
            //
            // A file too large to hold, at the other end, would be read only to be declined
            // by the cache and read again by the real request anyway.
            if size == 0 || size > CACHE_WHOLE_MAX {
                continue;
            }
            if self.cache.body(resolved, &attrs).is_some() {
                continue;
            }
            to_read.push((resolved.clone(), attrs, size));
        }
        if to_read.is_empty() {
            return;
        }

        // `read_ranges` rather than `read_batch`, because the size is already known.
        //
        // `read_batch` cannot know how long a file is, so it polls in 32 KiB chunks until it
        // sees a short read: one round trip per chunk index, which makes a one-megabyte
        // bundle thirty-two of them. `read_ranges` is handed the length, so it computes every
        // chunk before issuing any and the whole file costs one. The listing this function
        // already depends on is what supplies the length, so nothing extra is asked for.
        let reqs: Vec<RangeReq> = to_read
            .iter()
            .map(|(path, _, size)| RangeReq {
                path: path.clone(),
                offset: 0,
                len: *size,
            })
            .collect();

        for ((path, attrs, size), got) in to_read.iter().zip(session.fs.read_ranges(&reqs).await) {
            let Ok(body) = got else {
                continue;
            };
            // Short of what the listing promised means the file changed underneath us. The
            // cache key records the old size, so holding a body that no longer matches it
            // would serve the next reader a length the bytes do not have. Leaving it out
            // costs one prefetch; the real request reads it afresh.
            if body.len() as u64 != *size {
                continue;
            }
            self.cache.put_body(path, attrs, Bytes::from(body));
        }
    }

    /// Fetch every ancestor listing not already held, in one batch.
    ///
    /// One round trip regardless of depth, which is the whole reason `list_dirs` is a batch
    /// rather than a loop. A directory that cannot be listed is simply left absent from the
    /// cache; the caller diagnoses that against the path the request actually named.
    /// Every directory along a path, taken out of the cache once and then held.
    ///
    /// Held, rather than looked up again as the walk goes. The cache has a two-second TTL,
    /// so asking whether a listing is there and then asking for the listing are two
    /// questions with a gap between them, and a request arriving on the boundary got `true`
    /// for the first and `false` for the second. That produced a 404 reading "cannot list"
    /// about a directory that plainly existed, on roughly one e2e run in six. Taking the
    /// entries once removes the gap rather than narrowing it.
    ///
    /// A failure carries the remote's own reason out. It used to be dropped and reported as
    /// "cannot list", which is this daemon saying it does not know rather than ssh saying
    /// why — the difference between a message somebody can act on and one they cannot.
    async fn listings_along(
        &self,
        session: &Session,
        chain: &[(String, String)],
    ) -> Result<HashMap<String, Vec<Entry>>, (String, String)> {
        let mut held: HashMap<String, Vec<Entry>> = HashMap::new();
        let mut missing: Vec<String> = Vec::new();
        for (dir, _) in chain {
            if held.contains_key(dir) {
                continue;
            }
            match self.cache.listing_entries(dir) {
                Some(entries) => {
                    held.insert(dir.clone(), entries);
                }
                // Deduplicated because the prefetcher passes the chains of many files at
                // once and several of them normally share a directory. Listing one twice in
                // a batch costs no extra round trip, but it does cost the remote the work.
                None if !missing.contains(dir) => missing.push(dir.clone()),
                None => {}
            }
        }
        if missing.is_empty() {
            return Ok(held);
        }
        for (dir, result) in missing.iter().zip(session.fs.list_dirs(&missing).await) {
            match result {
                Ok(entries) => {
                    self.cache.put_listing(dir, &entries);
                    held.insert(dir.clone(), entries);
                }
                // Absence is not a failure to report. A component that is not there, or
                // that is a file being used as a directory, is a 404 and the walk says so
                // on its own — answering 502 would blame the remote for a path the reader
                // got wrong. Anything else is the remote refusing, and that reason travels.
                Err(e) if crate::fs::is_absent(&e) => {}
                Err(e) => return Err((dir.clone(), format!("{e:#}"))),
            }
        }
        Ok(held)
    }

    /// Can this directory be listed without asking the remote to walk through a symlink?
    ///
    /// True only when every step from the alias base down to it is already known — from a
    /// listing already held — to be a real directory. A step that is not known yet is not
    /// assumed safe, because SFTP v3 `OPENDIR` has no `O_NOFOLLOW`: asking the remote to
    /// list a path *is* asking it to follow whatever symlinks are in that path, and the
    /// answer arrives too late to un-ask. The base itself is operator configuration, not
    /// something a request reaches, so it is the one directory taken on trust.
    fn listable(&self, base: &str, dir: &str) -> bool {
        if dir.trim_end_matches('/') == base.trim_end_matches('/') {
            return true;
        }
        components(base, dir).iter().all(|(parent, name)| {
            self.cache
                .attrs_of(parent, name)
                .is_some_and(|a| a.is_dir() && !a.is_symlink())
        })
    }

    /// The first component of a chain that is a symlink, if any.
    ///
    /// Shared between reading and writing deliberately. A write that reached through a
    /// symlinked directory could place a file outside the alias base entirely, which is
    /// strictly worse than reading through one, so the two must not be able to drift apart.
    /// The same walk for the write path, over listings held for the same reason.
    ///
    /// A failure leaves the symlink check with nothing to check, and the write then fails
    /// with the remote's own reason. There is no better answer to give from here.
    async fn held_listings(
        &self,
        session: &Session,
        chain: &[(String, String)],
    ) -> HashMap<String, Vec<Entry>> {
        self.listings_along(session, chain)
            .await
            .unwrap_or_default()
    }
}

impl Origin {
    /// The symlink check over what is *already* cached and nothing more.
    ///
    /// The prefetcher runs this before it lists anything, so that a page cannot get a
    /// directory behind a symlink listed purely by naming it. Deliberately not the held
    /// version: the question here is what is known without asking.
    fn first_symlink_cached(&self, chain: &[(String, String)]) -> Option<String> {
        chain.iter().find_map(|(dir, name)| {
            self.cache
                .attrs_of(dir, name)
                .filter(Attrs::is_symlink)
                .map(|_| format!("{dir}/{name}"))
        })
    }
}

/// One entry's attrs, out of the listings this request is holding.
fn attrs_in(held: &HashMap<String, Vec<Entry>>, dir: &str, name: &str) -> Option<Attrs> {
    held.get(dir)
        .and_then(|entries| entries.iter().find(|e| e.name == name))
        .map(|e| e.attrs)
}

fn first_symlink(held: &HashMap<String, Vec<Entry>>, chain: &[(String, String)]) -> Option<String> {
    chain.iter().find_map(|(dir, name)| {
        attrs_in(held, dir, name)
            .filter(Attrs::is_symlink)
            .map(|_| format!("{dir}/{name}"))
    })
}

impl Origin {
    async fn alias_index(&self) -> String {
        let names = self.alias_names().await;
        let mut s = String::from(
            "<!doctype html><html><head><meta charset=\"utf-8\"><title>ssh-browser</title></head><body><h1>ssh-browser</h1><ul>",
        );
        for name in names {
            let href = self.site_url(&name);
            s.push_str("<li><a href=\"");
            s.push_str(&escape(&href));
            s.push_str("\">");
            s.push_str(&escape(&href));
            s.push_str("</a></li>");
        }
        s.push_str("</ul></body></html>");
        s
    }
}

/// Every step from the alias base down to the file, as `(directory to list, name to
/// check inside it)`, base first.
///
/// The base is the first directory listed and is never itself a checked name: it is
/// operator configuration, not something a request reaches.
fn components(base: &str, file: &str) -> Vec<(String, String)> {
    let base = base.trim_end_matches('/');
    let relative = file
        .strip_prefix(base)
        .unwrap_or("")
        .trim_start_matches('/');

    let mut out = Vec::new();
    let mut dir = base.to_string();
    for name in relative.split('/').filter(|s| !s.is_empty()) {
        out.push((dir.clone(), name.to_string()));
        dir = format!("{dir}/{name}");
    }
    out
}

/// A control body is a host name or a theme name, not a file upload.
///
/// `Limited` errors once the cap is passed rather than truncating, so a body that was too
/// large cannot be quietly parsed as a shorter one.
const MAX_CONTROL_BODY: usize = 256 * 1024;

async fn read_body<B>(body: B) -> Result<Bytes, String>
where
    B: hyper::body::Body,
    B::Error: Into<Box<dyn std::error::Error + Send + Sync>>,
{
    use http_body_util::{BodyExt, Limited};
    Limited::new(body, MAX_CONTROL_BODY)
        .collect()
        .await
        .map(|collected| collected.to_bytes())
        .map_err(|e| format!("reading the request body: {e}"))
}

fn header<B>(req: &Request<B>, name: HeaderName) -> Option<String> {
    req.headers()
        .get(name)
        .and_then(|v| v.to_str().ok())
        .map(str::to_string)
}

/// Serve a body already in hand, whole or sliced.
fn respond(
    file: &str,
    body: Bytes,
    tag: Option<&str>,
    wanted: &range::Resolved,
    size: u64,
) -> Response<Full<Bytes>> {
    match wanted {
        range::Resolved::Part { start, end } => {
            // Clamped against the body actually held rather than the advertised size,
            // so a listing that disagrees with the file cannot panic the slice.
            let lo = usize::try_from(*start)
                .unwrap_or(usize::MAX)
                .min(body.len());
            let hi = usize::try_from(end.saturating_add(1))
                .unwrap_or(usize::MAX)
                .min(body.len())
                .max(lo);
            partial(
                mime::guess(file),
                body.slice(lo..hi),
                tag,
                *start,
                *end,
                size,
            )
        }
        _ => served(mime::guess(file), body, tag),
    }
}

fn partial(
    content_type: &str,
    body: Bytes,
    tag: Option<&str>,
    start: u64,
    end: u64,
    size: u64,
) -> Response<Full<Bytes>> {
    let mut b = Response::builder()
        .status(StatusCode::PARTIAL_CONTENT)
        .header(CONTENT_TYPE, content_type)
        .header(CACHE_CONTROL, "no-cache")
        .header(ACCEPT_RANGES, "bytes")
        .header(CONTENT_RANGE, format!("bytes {start}-{end}/{size}"));
    if let Some(tag) = tag {
        b = b.header(ETAG, tag);
    }
    b.body(Full::new(body))
        .unwrap_or_else(|_| fail(StatusCode::INTERNAL_SERVER_ERROR, "malformed 206"))
}

/// A 416 has to carry the real size, or a client cannot work out what it should have
/// asked for instead.
fn unsatisfiable(size: u64) -> Response<Full<Bytes>> {
    Response::builder()
        .status(StatusCode::RANGE_NOT_SATISFIABLE)
        .header(CONTENT_TYPE, "text/plain; charset=utf-8")
        .header(CONTENT_RANGE, format!("bytes */{size}"))
        .body(Full::new(Bytes::from_static(b"range not satisfiable")))
        .unwrap_or_else(|_| fail(StatusCode::INTERNAL_SERVER_ERROR, "malformed 416"))
}

fn host_of<B>(req: &Request<B>) -> Option<String> {
    // A proxied request has an absolute-form target; a direct one only has the
    // header. Prefer the header, since that is what the browser actually sent.
    req.headers()
        .get(HOST)
        .and_then(|v| v.to_str().ok())
        .map(str::to_string)
        .or_else(|| req.uri().host().map(str::to_string))
}

fn served(content_type: &str, body: Bytes, tag: Option<&str>) -> Response<Full<Bytes>> {
    let mut b = Response::builder()
        .status(StatusCode::OK)
        .header(CONTENT_TYPE, content_type)
        // `no-cache` means revalidate, not "do not store". With an ETag attached
        // that revalidation is a 304 answered from the listing cache, so the
        // browser keeps its copy and the remote is never touched.
        .header(CACHE_CONTROL, "no-cache")
        // Advertised on every full response: a client that does not know ranges are
        // available will never try to seek.
        .header(ACCEPT_RANGES, "bytes");
    if let Some(tag) = tag {
        b = b.header(ETAG, tag);
    }
    b.body(Full::new(body))
        .unwrap_or_else(|_| fail(StatusCode::INTERNAL_SERVER_ERROR, "malformed response"))
}

/// For responses with no validator to offer: the PAC, the alias index, a listing.
fn plain_ok(content_type: &str, body: Bytes) -> Response<Full<Bytes>> {
    served(content_type, body, None)
}

/// No `Last-Modified` anywhere, deliberately.
///
/// Emitting it would oblige us to honour `If-Modified-Since`, whose comparison is
/// second-resolution -- the same resolution SFTP reports mtime at, which is exactly
/// where it stops being able to tell two versions apart. The ETag carries the same
/// information without that ambiguity, so it is the only validator offered.
fn not_modified(tag: &str) -> Response<Full<Bytes>> {
    Response::builder()
        .status(StatusCode::NOT_MODIFIED)
        .header(ETAG, tag)
        .header(CACHE_CONTROL, "no-cache")
        .body(Full::new(Bytes::new()))
        .unwrap_or_else(|_| fail(StatusCode::INTERNAL_SERVER_ERROR, "malformed 304"))
}

fn fail(status: StatusCode, detail: impl Into<String>) -> Response<Full<Bytes>> {
    Response::builder()
        .status(status)
        .header(CONTENT_TYPE, "text/plain; charset=utf-8")
        .body(Full::new(Bytes::from(detail.into())))
        .expect("a plain-text body with static headers always builds")
}

fn redirect(to: &str) -> Response<Full<Bytes>> {
    Response::builder()
        .status(StatusCode::MOVED_PERMANENTLY)
        .header(LOCATION, to)
        .body(Full::new(Bytes::new()))
        .unwrap_or_else(|_| fail(StatusCode::INTERNAL_SERVER_ERROR, "bad redirect target"))
}

/// Listing for a directory that has no index.html.
/// A name this daemon will not serve.
///
/// The ssh_config entry a remembered name refers to.
///
/// Matched on either spelling, because the two are not always the same thing: what is written
/// down is the URL *label*, which is lowercase because it becomes a hostname, and the
/// `Host` in ssh_config it came from may be `Panza` where the label is `panza`.
///
/// Getting this wrong is not a near miss. Dialling the label produced `Could not resolve
/// hostname panza` on every start, while turning the host on had worked a moment earlier —
/// because that path had the ssh_config entry in hand and startup had only the name. No test
/// against a fake remote could have found it; running it twice did.
fn entry_for<'a>(known: &'a [ssh_config::Host], name: &str) -> Option<&'a ssh_config::Host> {
    known
        .iter()
        .find(|h| h.alias == name || h.host.eq_ignore_ascii_case(name))
}

/// Completed and failed TLS handshakes since this daemon started.
///
/// Two counters rather than a single "is it trusted" flag, because the two facts are different
/// and a reader needs both: a failure says the step was missed, and a success says it was taken.
/// A flag would have to pick one moment to believe.
#[derive(Debug, Default)]
struct Handshakes {
    completed: std::sync::atomic::AtomicU64,
    failed: std::sync::atomic::AtomicU64,
}

/// A rustls configuration that mints a certificate for whatever name the handshake asks for.
///
/// Per name rather than one wildcard, because a wildcard does not work: `*.ssh-browser` is
/// refused by Chromium with `ERR_CERT_COMMON_NAME_INVALID`, since the suffix is not a known
/// registry and a wildcard directly beneath one reads as covering a whole top-level domain. A
/// certificate naming the alias outright is accepted, and the origin is then a real secure
/// context — service workers, `crypto.subtle` and all.
fn serving_config(suffix: &str) -> Result<(rustls::ServerConfig, String)> {
    let (authority, found) = tls::load_or_create_reporting(suffix)?;

    // Said on every https run, not only the first. Nothing portable can ask a trust store
    // whether this is still in it, and the failure when it is not — `ERR_CERT_AUTHORITY_INVALID`
    // on a URL the daemon itself just advertised — contains no hint that a command exists. A
    // returning reader can skim two lines; a first-time reader cannot recover without them.
    let path = tls::certificate_path()
        .map(|p| p.display().to_string())
        .unwrap_or_else(|| "the state directory".to_string());
    // A list of lines rather than one string with escapes in it. The last attempt at the latter
    // shipped a banner carrying the source file's own indentation into the middle of a sentence.
    let lines: Vec<String> = match found {
        tls::Found::Created => vec![
            "this run made a local certificate authority, and nothing trusts it yet.".to_string(),
            "Until it is, the browser will refuse every page here:".to_string(),
            String::new(),
            "  ssh-browser trust".to_string(),
            String::new(),
            "prints the command for your platform, and the one that undoes it.".to_string(),
            format!("The certificate is {path}"),
        ],
        tls::Found::Existing => vec![
            "https: if the browser refuses a page, the local authority is not trusted.".to_string(),
            "`ssh-browser trust` prints how.".to_string(),
            format!("The certificate is {path}"),
        ],
    };
    let advice = lines.join("\n");

    // No client authentication: the browser is not asked to prove anything, because nothing here
    // decides what to serve based on who is asking. The token does that, on the control API.
    let mut config = rustls::ServerConfig::builder()
        .with_no_client_auth()
        .with_cert_resolver(Arc::new(PerName {
            authority,
            suffix: suffix.to_string(),
            minted: Mutex::new(HashMap::new()),
        }));
    // The browser asked for https, so http/1.1 is what is spoken inside the tunnel. Advertised
    // rather than left to chance: without it a browser may negotiate h2, which nothing here
    // serves, and the failure is a dead connection rather than a refusal.
    config.alpn_protocols = vec![b"http/1.1".to_vec()];
    Ok((config, advice))
}

/// Signs a certificate the first time each name is asked for, and remembers it.
///
/// Remembered because a handshake must not wait on key generation twice for the same site, and
/// because a browser opening a page and its subresources will handshake more than once.
struct PerName {
    authority: tls::Authority,
    suffix: String,
    minted: Mutex<HashMap<String, Arc<rustls::sign::CertifiedKey>>>,
}

impl std::fmt::Debug for PerName {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Hand-written because `Authority` holds a private key and deriving this would put it one
        // `{:?}` away from a log line.
        f.debug_struct("PerName")
            .field("suffix", &self.suffix)
            .finish()
    }
}

impl rustls::server::ResolvesServerCert for PerName {
    fn resolve(
        &self,
        hello: rustls::server::ClientHello<'_>,
    ) -> Option<Arc<rustls::sign::CertifiedKey>> {
        // No SNI means no name to vouch for. Returning nothing fails the handshake, which is the
        // honest answer: a certificate for a name the client did not ask about would be rejected
        // by the client anyway, and more confusingly.
        let name = hello.server_name()?.to_string();

        if let Some(found) = self
            .minted
            .lock()
            .ok()
            .and_then(|held| held.get(&name).cloned())
        {
            return Some(found);
        }

        // `leaf_for` refuses anything that is not a single label under the suffix, so this is
        // also the point where a handshake for somebody else's name stops. It would be stopped
        // again by the name constraint in the authority, but failing here means never signing
        // the certificate at all.
        let leaf = self.authority.leaf_for(&name).ok()?;
        // `rustls-pki-types` rather than `rustls-pemfile`: the latter is unmaintained
        // (RUSTSEC-2025-0134) and this is where its job moved. It is already in the tree as
        // rustls's own dependency, so this removes a crate rather than adding one.
        let certs =
            rustls_pki_types::CertificateDer::pem_slice_iter(leaf.certificate_pem.as_bytes())
                .collect::<std::result::Result<Vec<_>, _>>()
                .ok()?;
        let key = rustls_pki_types::PrivateKeyDer::from_pem_slice(leaf.key_pem.as_bytes()).ok()?;
        let signing = rustls::crypto::ring::default_provider()
            .key_provider
            .load_private_key(key)
            .ok()?;
        let certified = Arc::new(rustls::sign::CertifiedKey::new(certs, signing));

        if let Ok(mut held) = self.minted.lock() {
            held.insert(name, Arc::clone(&certified));
        }
        Some(certified)
    }
}

/// Anything beginning with a dot. An alias base is one origin, so a page under it can read
/// everything else under it with `fetch` — the base is the blast radius. On a home directory
/// almost everything worth stealing sits behind a dot: `.ssh`, `.aws`, `.netrc`, a `.git`
/// whose remote URL carries a token. Refusing them costs a reader nearly nothing, and it is
/// what makes pointing an alias at a home directory a reasonable thing to do at all.
fn hidden(name: &str) -> bool {
    name.starts_with('.')
}

/// One entry of a directory, ready to be written into a row.
struct Row {
    name: String,
    dir: bool,
    /// Holds an `index.html`, so it is a site rather than a folder.
    site: bool,
    /// Absent for a directory, whose own size is its bookkeeping rather than its contents'.
    size: Option<String>,
    modified: Option<String>,
    /// Which colour its marker takes.
    kind: &'static str,
}

/// The rows of one directory, sorted and with the dot-names already gone.
fn rows_of(entries: &[Entry], sites: &HashSet<String>) -> Vec<Row> {
    let mut visible: Vec<&Entry> = entries
        .iter()
        // `.` and `..` are already gone by the time a path resolves; these are the real
        // dot-names. Listing what the next click would be refused is worse than silence.
        .filter(|e| e.name != "." && e.name != ".." && !hidden(&e.name))
        .collect();
    visible.sort_by(|a, b| (rank(a, sites), &a.name).cmp(&(rank(b, sites), &b.name)));

    visible
        .into_iter()
        .map(|e| {
            let dir = e.attrs.is_dir();
            Row {
                name: e.name.clone(),
                dir,
                site: dir && sites.contains(&e.name),
                size: if dir {
                    None
                } else {
                    e.attrs.size.map(human_size)
                },
                modified: e.attrs.mtime.map(utc_stamp),
                kind: if dir { "dir" } else { family(&e.name) },
            }
        })
        .collect()
}

/// Where an entry sorts, before its name is considered.
///
/// Directories first and no headings over them — souta's call, and it is how a file tree
/// has worked since long before anybody wrote one down. Within each half the thing you came
/// to open rises: a directory that *is* a page, and then an HTML file.
///
/// A Pinax board is `out/ft_demo/index.html`, so the directory holding it is what has to
/// rise. Sorting the HTML alone would never move anything, because the directory you are
/// standing in has no HTML in it at all.
fn rank(e: &Entry, sites: &HashSet<String>) -> (u8, u8) {
    if e.attrs.is_dir() {
        (0, u8::from(!sites.contains(&e.name)))
    } else {
        (1, u8::from(!is_page(&e.name)))
    }
}

fn is_page(name: &str) -> bool {
    matches!(extension_of(name).as_deref(), Some("html" | "htm"))
}

/// Which colour an entry's marker takes.
///
/// Families rather than extensions, because the point is to be readable without being read:
/// a `.toml` and a `.png` should not look the same, but `.toml` and `.json` may. This is
/// the one thing an editor's file tree does that a plain list does not.
fn family(name: &str) -> &'static str {
    match extension_of(name).as_deref() {
        Some("html" | "htm") => "k-page",
        Some("md" | "txt" | "rst" | "tex" | "bib" | "pdf" | "org" | "adoc") => "k-doc",
        Some("json" | "toml" | "yaml" | "yml" | "csv" | "tsv" | "xml" | "ini" | "lock") => "k-data",
        Some(
            "rs" | "jl" | "py" | "ts" | "js" | "mjs" | "sh" | "c" | "h" | "cpp" | "go" | "rb"
            | "lua" | "css" | "scss" | "lean" | "hs" | "java" | "kt" | "swift" | "sql",
        ) => "k-code",
        Some(
            "png" | "jpg" | "jpeg" | "gif" | "svg" | "webp" | "avif" | "ico" | "mp4" | "webm"
            | "mov" | "mp3" | "wav",
        ) => "k-media",
        _ => "k-plain",
    }
}

/// The lowercased extension, taken from the name.
fn extension_of(name: &str) -> Option<String> {
    let dot = name.rfind('.')?;
    // A leading dot is a hidden name rather than an extension, and a trailing one is not an
    // extension at all. Neither is served, but neither should be labelled as a type either.
    if dot == 0 || dot + 1 == name.len() {
        return None;
    }
    Some(name[dot + 1..].to_ascii_lowercase())
}

/// Bytes, the way a file manager shows them.
///
/// Binary multiples with the labels that actually mean them. Calling 1024 bytes `kB` is the
/// lie everyone tells, and this is a tool for people who would notice.
fn human_size(n: u64) -> String {
    const UNITS: [&str; 5] = ["KiB", "MiB", "GiB", "TiB", "PiB"];
    if n < 1024 {
        return format!("{n} B");
    }
    let mut v = n as f64 / 1024.0;
    let mut unit = 0;
    while v >= 1024.0 && unit + 1 < UNITS.len() {
        v /= 1024.0;
        unit += 1;
    }
    // One decimal below ten and none above, so a column of sizes stays a column:
    // `9.4 MiB` and `312 MiB`, not `312.0 MiB`.
    if v < 10.0 {
        format!("{v:.1} {}", UNITS[unit])
    } else {
        format!("{v:.0} {}", UNITS[unit])
    }
}

/// `2026-09-13 05:44`, in UTC.
///
/// UTC because it is the only thing that can be said truthfully. SFTP reports seconds since
/// the epoch and says nothing about a zone; the remote's zone is not something this
/// transport can ask for, and using *this* machine's would stamp a file with an offset
/// belonging to a different computer. The column says so once, in the footer.
fn utc_stamp(secs: u32) -> String {
    let secs = i64::from(secs);
    let (y, m, d) = civil_from_days(secs.div_euclid(86_400));
    let rest = secs.rem_euclid(86_400);
    let (hh, mm) = (rest / 3600, (rest % 3600) / 60);
    format!("{y:04}-{m:02}-{d:02} {hh:02}:{mm:02}")
}

/// Howard Hinnant's `civil_from_days`: exact for every day this could be handed, and it
/// needs no calendar crate. Adding a dependency to print a date in a directory listing
/// would be a poor trade in a daemon that reads other people's filesystems.
fn civil_from_days(z: i64) -> (i64, u32, u32) {
    let z = z + 719_468;
    let era = if z >= 0 { z } else { z - 146_096 }.div_euclid(146_097);
    let doe = (z - era * 146_097) as u64;
    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
    let y = yoe as i64 + era * 400;
    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
    let mp = (5 * doy + 2) / 153;
    let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
    let m = u32::try_from(if mp < 10 { mp + 3 } else { mp - 9 }).unwrap_or(1);
    (if m <= 2 { y + 1 } else { y }, m, d)
}

/// The listing's layout.
///
/// Written entirely against the custom properties a theme supplies, so a new palette is a
/// new theme rather than a second copy of these rules. See `crate::theme`.
///
/// An editor's explorer: one line per entry, a twisty on the folders, an indent guide per
/// level, and a coloured chip for the type. souta asked for this twice — a flat list of one
/// directory is a listing, and what makes an explorer is the tree.
const LISTING_CSS: &str = "\
*{box-sizing:border-box}\
html{background:var(--bg)}\
body{color:var(--fg);font:13px/1.5 system-ui,-apple-system,Segoe UI,sans-serif;margin:0}\
header{align-items:baseline;background:var(--bg);border-bottom:1px solid var(--line);\
display:flex;gap:6px;padding:7px 12px;position:sticky;top:0;z-index:1}\
header b{font-size:12px;font-weight:600;letter-spacing:.04em}\
header span{color:var(--dim);font-family:ui-monospace,SFMono-Regular,Menlo,monospace;\
font-size:11px;overflow-wrap:anywhere}\
#tree{padding:4px 0 40px}\
ul{list-style:none;margin:0;padding:0}\
li ul{border-left:1px solid var(--line);margin-left:15px}\
li>ul{display:none}\
li.open>ul{display:block}\
.row{align-items:center;color:inherit;display:grid;gap:6px;\
grid-template-columns:14px 14px 1fr auto auto;line-height:22px;padding-right:12px;\
text-decoration:none;white-space:nowrap}\
.row:hover{background:var(--hover)}\
.row.here{background:var(--sel)}\
.row.here .size,.row.here .when{color:var(--dim)}\
.row:focus-visible{outline:1px solid var(--accent);outline-offset:-1px}\
.tw{color:var(--dim);font-size:11px;line-height:22px;text-align:center;\
transition:transform .1s linear}\
li.open>.row .tw{transform:rotate(90deg)}\
.ico{border-radius:2px;height:9px;justify-self:center;width:9px}\
.dir>.ico{background:var(--dim);border-radius:1px 3px 3px 3px}\
.site>.ico{background:var(--accent);border-radius:1px 3px 3px 3px}\
.site>.name{color:var(--accent)}\
.k-page>.ico{background:var(--k-page)}\
.k-page>.name{color:var(--k-page)}\
.k-doc>.ico{background:var(--k-doc)}\
.k-data>.ico{background:var(--k-data)}\
.k-code>.ico{background:var(--k-code)}\
.k-media>.ico{background:var(--k-media)}\
.k-plain>.ico{background:var(--k-plain)}\
.name{overflow:hidden;text-overflow:ellipsis}\
.size,.when{color:var(--faint);font-family:ui-monospace,SFMono-Regular,Menlo,monospace;\
font-size:11px;font-variant-numeric:tabular-nums}\
.size{text-align:right}\
.row.busy .tw{opacity:.4}\
.row.failed .when{color:var(--k-page)}\
.empty{color:var(--faint);padding:10px 16px}\
@media(max-width:620px){.when{display:none}}";

/// Expanding a folder, and nothing else.
///
/// The daemon's own page, so its script is the daemon's too — nothing is ever added to a
/// document the reader came for. It is small because the server renders the rows: this asks
/// for a level and puts it where it goes.
///
/// Without it every level costs a page load, and the tree still works that way: every row is
/// a real link to a real URL, so a browser with no script at all walks the tree one
/// directory at a time, exactly as the old listing did.
const LISTING_JS: &str = "\
const tree=document.getElementById('tree');\
tree.addEventListener('click',async e=>{\
const row=e.target.closest('a.row');\
if(!row||row.dataset.dir!=='1')return;\
e.preventDefault();\
const li=row.parentElement;\
if(li.querySelector(':scope>ul')){li.classList.toggle('open');mark(row);return;}\
row.classList.add('busy');\
try{\
const res=await fetch(row.getAttribute('href')+'?ls');\
if(!res.ok)throw new Error(res.status);\
li.insertAdjacentHTML('beforeend',await res.text());\
li.classList.add('open');mark(row);\
}catch(err){row.classList.add('failed');\
row.querySelector('.when').textContent='could not be listed: '+err.message;}\
finally{row.classList.remove('busy');}\
});\
function mark(row){\
for(const other of tree.querySelectorAll('a.row.here'))other.classList.remove('here');\
row.classList.add('here');\
history.replaceState(null,'',row.getAttribute('href'));\
document.querySelector('header span').textContent=\
decodeURIComponent(new URL(row.href).pathname);\
}";

/// One level of the tree: a `<ul>` of rows, with the one on the path already expanded.
///
/// `open` is the rest of the path from here down, so a level knows which of its folders the
/// reader is inside. Empty means nothing below is expanded, which is what `?ls` hands back
/// for a folder somebody has just clicked.
fn render_level(out: &mut String, path: &str, rows: &[Row], open: &[(String, Vec<Row>)]) {
    out.push_str("<ul>");
    for row in rows {
        let here = format!("{path}/{}", row.name);
        let deeper = open.first().filter(|(next, _)| *next == here);

        out.push_str(if deeper.is_some() {
            "<li class=\"open\">"
        } else {
            "<li>"
        });
        out.push_str("<a class=\"row ");
        out.push_str(match (row.dir, row.site) {
            // A directory holding an `index.html` is served *as* that page, so it is marked
            // as somewhere to read rather than somewhere to look.
            (true, true) => "site",
            (true, false) => "dir",
            (false, _) => row.kind,
        });
        // The deepest expanded folder is where the reader is, so the tree opens with it
        // selected the way an explorer shows the file you have open.
        if deeper.is_some() && open.len() == 1 {
            out.push_str(" here");
        }
        out.push_str("\" href=\"");
        out.push_str(path);
        out.push('/');
        out.push_str(&url_escape(&row.name));
        if row.dir {
            out.push('/');
        }
        // Read by the script to tell a folder from a file without picking through classes.
        out.push_str(if row.dir {
            "\" data-dir=\"1\"><span class=\"tw\">\u{25b8}</span>"
        } else {
            "\"><span class=\"tw\"></span>"
        });
        out.push_str("<span class=\"ico\"></span><span class=\"name\">");
        out.push_str(&escape(&row.name));
        out.push_str("</span><span class=\"size\">");
        out.push_str(row.size.as_deref().unwrap_or(""));
        out.push_str("</span><span class=\"when\">");
        out.push_str(row.modified.as_deref().unwrap_or(""));
        out.push_str("</span></a>");

        if let Some((next, rows)) = deeper {
            render_level(out, next, rows, &open[1..]);
        }
        out.push_str("</li>");
    }
    out.push_str("</ul>");
}

/// A directory, as a tree.
///
/// `levels` runs from the alias base down to where the reader is, each already sorted, so
/// the page opens with the whole path expanded and the rest of every level beside it. They
/// come out of the cache the path walk already filled, so the depth costs no round trips.
fn autoindex(alias: &str, rel: &str, levels: &[(String, Vec<Row>)], theme: &str) -> String {
    let shown = if rel.is_empty() { "/" } else { rel };
    let mut s = String::from("<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\">");
    s.push_str("<meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"><title>");
    s.push_str(&escape(&format!("{shown} \u{b7} {alias}")));
    s.push_str("</title><style>");
    // The palette first, then the layout that reads it.
    s.push_str(&theme::css_for(theme));
    s.push_str(LISTING_CSS);
    s.push_str("</style></head><body><header><b>");
    s.push_str(&escape(alias));
    s.push_str("</b><span>");
    s.push_str(&escape(shown));
    s.push_str("</span></header><div id=\"tree\">");

    match levels.split_first() {
        Some(((path, rows), rest)) if !rows.is_empty() => render_level(&mut s, path, rows, rest),
        // An alias whose base holds nothing. Saying so beats a blank page, which reads as
        // something having gone wrong.
        _ => s.push_str("<p class=\"empty\">This directory is empty.</p>"),
    }

    s.push_str("</div><script>");
    s.push_str(LISTING_JS);
    s.push_str("</script></body></html>");
    s
}

/// Remote filenames are untrusted input that lands inside our own origin, so the
/// listing escapes them. Skipping this would be self-inflicted XSS.
fn escape(s: &str) -> String {
    s.replace('&', "&amp;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
        .replace('"', "&quot;")
}

/// HTML-escaping is not enough inside an href: a space or a hash in a filename
/// would still produce a broken or a wrong link.
fn url_escape(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for b in s.bytes() {
        match b {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
                out.push(b as char);
            }
            _ => out.push_str(&format!("%{b:02X}")),
        }
    }
    out
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::sftp::wire::Attrs;
    use crate::testing::{FakeRemote, dir_attrs, file_attrs, symlink_attrs};
    use http_body_util::{BodyExt, Empty};

    const TEST_TOKEN: &str = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";

    async fn body_of(res: Response<Full<Bytes>>) -> Bytes {
        res.into_body()
            .collect()
            .await
            .expect("a Full body always collects")
            .to_bytes()
    }

    /// A request arriving by address rather than through the PAC.
    fn loopback(path: &str, token: Option<&str>) -> Request<Empty<Bytes>> {
        let mut b = Request::builder().uri(path).header(HOST, "127.0.0.1:7391");
        if let Some(t) = token {
            b = b.header(control::TOKEN_HEADER, t);
        }
        b.body(Empty::<Bytes>::new()).expect("request builds")
    }

    /// A loopback request carrying no token, and whatever the browser would have said
    /// about who started it.
    fn from_site(path: &str, site: Option<&str>) -> Request<Empty<Bytes>> {
        let mut b = Request::builder().uri(path).header(HOST, "127.0.0.1:7391");
        if let Some(site) = site {
            b = b.header(control::FETCH_SITE_HEADER, site);
        }
        b.body(Empty::<Bytes>::new()).expect("request builds")
    }

    fn control_post(path: &str, token: Option<&str>, body: &str) -> Request<Full<Bytes>> {
        let mut b = Request::builder()
            .method(Method::POST)
            .uri(path)
            .header(HOST, "127.0.0.1:7391");
        if let Some(t) = token {
            b = b.header(control::TOKEN_HEADER, t);
        }
        b.body(Full::new(Bytes::from(body.to_string())))
            .expect("request builds")
    }

    fn ranged(path: &str, range: &str) -> Request<Empty<Bytes>> {
        Request::builder()
            .uri(format!("http://docs.ssh-browser{path}"))
            .header(HOST, "docs.ssh-browser")
            .header(RANGE, range)
            .body(Empty::new())
            .expect("request builds")
    }

    /// Build an origin over an in-memory remote. The session is a real `SftpFs`, so
    /// the round trips counted below are the same ones production would pay.
    async fn origin_with(remote: FakeRemote) -> Origin {
        origin_with_cache(remote, Cache::default()).await
    }

    async fn origin_with_cache(remote: FakeRemote, cache: Cache) -> Origin {
        let fs = remote.spawn().await;
        let mut sessions = HashMap::new();
        sessions.insert(
            "docs".to_string(),
            Arc::new(Session {
                host: "nowhere".to_string(),
                base: "/srv".to_string(),
                fs,
            }),
        );
        Origin {
            suffix: "ssh-browser".to_string(),
            // http, because these tests drive `handle` directly and never open a socket. An
            // https origin here would only change the URLs printed in a listing.
            scheme: "http".to_string(),
            tls: None,
            port: 7391,
            sessions: RwLock::new(sessions),
            cache,
            theme: RwLock::new(theme::DEFAULT.to_string()),
            token: Token::from_hex(TEST_TOKEN),
            // Empty on purpose: these tests build their session map directly, so nothing here
            // should be opening anything behind their backs.
            reachable: RwLock::new(reachable::Set::default()),
            handshakes: Handshakes::default(),
        }
    }

    fn get(path: &str, if_none_match: Option<&str>) -> Request<Empty<Bytes>> {
        let mut b = Request::builder()
            .uri(format!("http://docs.ssh-browser{path}"))
            .header(HOST, "docs.ssh-browser");
        if let Some(tag) = if_none_match {
            b = b.header(IF_NONE_MATCH, tag);
        }
        b.body(Empty::new()).expect("request builds")
    }

    async fn trips(origin: &Origin) -> u64 {
        origin
            .sessions
            .read()
            .await
            .values()
            .map(|s| s.fs.round_trips())
            .sum()
    }

    fn one_page() -> FakeRemote {
        FakeRemote::new()
            .dir("/srv", vec![("a.html", file_attrs(5, 100))])
            .file("/srv/a.html", b"hello")
    }

    /// A page with subresources in a sibling directory, which is the shape a generated
    /// report has: one HTML file and an `assets/` beside it.
    fn page_with_subresources(n: usize) -> FakeRemote {
        let mut html = String::from(
            "<!doctype html><html><head><link rel=\"stylesheet\" href=\"assets/style.css\"><script src=\"assets/app.js\"></script></head><body>",
        );
        for i in 0..n {
            html.push_str(&format!("<img src=\"assets/{i}.png\">"));
        }
        html.push_str("</body></html>");

        let mut assets = vec!["style.css".to_string(), "app.js".to_string()];
        assets.extend((0..n).map(|i| format!("{i}.png")));

        let mut remote = FakeRemote::new()
            .dir(
                "/srv",
                vec![
                    ("index.html", file_attrs(html.len() as u64, 100)),
                    ("assets", dir_attrs()),
                ],
            )
            .dir(
                "/srv/assets",
                assets
                    .iter()
                    .map(|name| (name.as_str(), file_attrs(3, 1)))
                    .collect(),
            )
            .file("/srv/index.html", html.as_bytes());
        for name in &assets {
            remote = remote.file(&format!("/srv/assets/{name}"), b"xxx");
        }
        remote
    }

    /// The subresource half of invariant 1, which is about the browser rather than the
    /// remote. HTTP/1.1 allows six connections per origin, so forty subresources are seven
    /// waves of requests and each wave the browser has to discover is a round trip.
    ///
    /// Asking for them one at a time is the worst case any browser can produce. If that
    /// costs nothing, no arrangement of waves can cost anything either.
    #[tokio::test]
    async fn a_pages_subresources_are_already_held_when_the_browser_asks_for_them() {
        const N: usize = 40;
        let origin = origin_with(page_with_subresources(N)).await;

        let res = origin.handle(get("/index.html", None)).await;
        assert_eq!(res.status(), StatusCode::OK);

        let before = trips(&origin).await;
        for i in 0..N {
            let path = format!("/assets/{i}.png");
            let res = origin.handle(get(&path, None)).await;
            assert_eq!(res.status(), StatusCode::OK, "{path}");
            assert_eq!(&body_of(res).await[..], b"xxx", "{path}");
        }
        for name in ["style.css", "app.js"] {
            let res = origin.handle(get(&format!("/assets/{name}"), None)).await;
            assert_eq!(res.status(), StatusCode::OK, "{name}");
        }

        assert_eq!(
            trips(&origin).await - before,
            0,
            "reading the page's own references is what makes these free"
        );
    }

    /// And the page itself does not get more expensive as it gains subresources: the
    /// listings are one batch and the reads are another, whatever the count.
    #[tokio::test]
    async fn serving_a_page_costs_the_same_however_many_subresources_it_has() {
        async fn cost(n: usize) -> u64 {
            let origin = origin_with(page_with_subresources(n)).await;
            let before = trips(&origin).await;
            let res = origin.handle(get("/index.html", None)).await;
            assert_eq!(res.status(), StatusCode::OK);
            trips(&origin).await - before
        }
        assert_eq!(cost(4).await, cost(40).await);
    }

    /// One HTML page naming whatever it likes, for the two tests below. The page is
    /// untrusted input, and prefetching is the first thing in this daemon that acts on what
    /// a page says rather than on what the reader asked for.
    fn page_referring_to(refs: &[&str], extra: Vec<(&'static str, Attrs)>) -> FakeRemote {
        let mut html = String::from("<!doctype html><html><body>");
        for r in refs {
            html.push_str(&format!("<img src=\"{r}\">"));
        }
        html.push_str("</body></html>");

        let mut entries = vec![("index.html", file_attrs(html.len() as u64, 100))];
        entries.extend(extra);
        FakeRemote::new()
            .dir("/srv", entries)
            .file("/srv/index.html", html.as_bytes())
    }

    async fn cost_of_serving(refs: &[&str], extra: Vec<(&'static str, Attrs)>) -> u64 {
        let origin = origin_with(page_referring_to(refs, extra)).await;
        let before = trips(&origin).await;
        let res = origin.handle(get("/index.html", None)).await;
        assert_eq!(res.status(), StatusCode::OK);
        trips(&origin).await - before
    }

    /// A reference that climbs out of the alias base must not be read. The check is the
    /// same `resolve` the request path uses, not a second copy that could drift from it.
    #[tokio::test]
    async fn a_page_cannot_prefetch_its_way_out_of_the_alias_base() {
        let baseline = cost_of_serving(&[], vec![]).await;
        assert_eq!(
            cost_of_serving(&["../../../etc/passwd", "/../../etc/shadow"], vec![]).await,
            baseline,
            "an escaping reference is gone before anything is listed or read"
        );
    }

    /// Nor through a symlink — and not even as far as listing it. A page that could get the
    /// directory a symlink points at listed would have defeated the rule by naming it.
    #[tokio::test]
    async fn a_page_cannot_prefetch_through_a_symlink() {
        let link = || vec![("link", symlink_attrs())];
        let baseline = cost_of_serving(&[], link()).await;
        assert_eq!(
            cost_of_serving(&["link/inside.png"], link()).await,
            baseline,
            "the symlink is known from the listing the page itself needed"
        );

        // And the ordinary request for it is still refused, which is the guarantee the
        // prefetcher is being held to rather than a separate one.
        let origin = origin_with(page_referring_to(&["link/inside.png"], link())).await;
        assert_eq!(
            origin.handle(get("/index.html", None)).await.status(),
            StatusCode::OK
        );
        assert_eq!(
            origin.handle(get("/link/inside.png", None)).await.status(),
            StatusCode::FORBIDDEN
        );
    }

    /// The hole the shallow symlink test did not cover: a symlink one level below the
    /// deepest listing the cache holds.
    ///
    /// `first_symlink` can only see what is cached, so at the moment the batch is assembled
    /// it has no opinion about `assets/link` — and the batch that would tell it includes the
    /// symlink's own path. SFTP v3 `OPENDIR` has no `O_NOFOLLOW`, so the remote resolves it
    /// and hands back a listing of wherever it points. Nothing is ever served through it,
    /// but the daemon has already read it, which is the act the alias base exists to forbid.
    ///
    /// Round trips cannot detect this — `list_dirs` is one flush however many directories
    /// are in it — so the assertion is on what the cache ends up holding.
    #[tokio::test]
    async fn a_page_cannot_get_a_symlink_below_an_unlisted_directory_opened() {
        let html = "<!doctype html><html><body><img src=\"assets/link/secret.txt\"></body></html>";
        let origin = origin_with(
            FakeRemote::new()
                .dir(
                    "/srv",
                    vec![
                        ("index.html", file_attrs(html.len() as u64, 100)),
                        ("assets", dir_attrs()),
                    ],
                )
                .dir("/srv/assets", vec![("link", symlink_attrs())])
                // What the remote returns once it has followed the symlink for us.
                .dir("/srv/assets/link", vec![("secret.txt", file_attrs(9, 1))])
                .file("/srv/index.html", html.as_bytes())
                .file("/srv/assets/link/secret.txt", b"elsewhere"),
        )
        .await;

        assert_eq!(
            origin.handle(get("/index.html", None)).await.status(),
            StatusCode::OK
        );
        assert!(
            !origin.cache.has_listing("/srv/assets/link"),
            "the daemon listed the directory a symlink points at"
        );

        // And the ordinary request for it is still refused, so closing the prefetch route
        // did not quietly become the only thing stopping it.
        assert_eq!(
            origin
                .handle(get("/assets/link/secret.txt", None))
                .await
                .status(),
            StatusCode::FORBIDDEN
        );
    }

    /// The other half: a reference one level down is still prefetched, because the listing
    /// the page's own request already fetched proves that step is a real directory. Closing
    /// the hole above must not turn prefetching off for the ordinary `assets/` layout.
    #[tokio::test]
    async fn a_reference_in_a_real_subdirectory_is_still_prefetched() {
        let html = "<!doctype html><html><body><img src=\"assets/x.png\"></body></html>";
        let origin = origin_with(
            FakeRemote::new()
                .dir(
                    "/srv",
                    vec![
                        ("index.html", file_attrs(html.len() as u64, 100)),
                        ("assets", dir_attrs()),
                    ],
                )
                .dir("/srv/assets", vec![("x.png", file_attrs(3, 1))])
                .file("/srv/index.html", html.as_bytes())
                .file("/srv/assets/x.png", b"xxx"),
        )
        .await;

        assert_eq!(
            origin.handle(get("/index.html", None)).await.status(),
            StatusCode::OK
        );
        let before = trips(&origin).await;
        let res = origin.handle(get("/assets/x.png", None)).await;
        assert_eq!(res.status(), StatusCode::OK);
        assert_eq!(&body_of(res).await[..], b"xxx");
        assert_eq!(
            trips(&origin).await - before,
            0,
            "a subdirectory one level down must still be warmed"
        );
    }

    /// A subresource larger than one read chunk costs the same as a small one.
    ///
    /// This is what `read_ranges` buys over `read_batch` here: a read whose length is known
    /// can have all its chunks issued together, and a read whose length is not has to poll.
    /// Before, a bundle of any real size cost one round trip per 32 KiB — invisible to every
    /// other test, because they all use three-byte fixtures.
    #[tokio::test]
    async fn a_large_subresource_costs_what_a_small_one_costs() {
        async fn cost(bytes: usize) -> u64 {
            let html = "<!doctype html><html><body><img src=\"assets/big.bin\"></body></html>";
            let origin = origin_with(
                FakeRemote::new()
                    .dir(
                        "/srv",
                        vec![
                            ("index.html", file_attrs(html.len() as u64, 100)),
                            ("assets", dir_attrs()),
                        ],
                    )
                    .dir(
                        "/srv/assets",
                        vec![("big.bin", file_attrs(bytes as u64, 1))],
                    )
                    .file("/srv/index.html", html.as_bytes())
                    .file("/srv/assets/big.bin", &vec![b'x'; bytes]),
            )
            .await;

            let before = trips(&origin).await;
            assert_eq!(
                origin.handle(get("/index.html", None)).await.status(),
                StatusCode::OK
            );
            let spent = trips(&origin).await - before;

            // And it really was warmed, so the comparison is between two prefetches rather
            // than between a prefetch and a skip.
            let at = trips(&origin).await;
            let res = origin.handle(get("/assets/big.bin", None)).await;
            assert_eq!(res.status(), StatusCode::OK);
            assert_eq!(body_of(res).await.len(), bytes);
            assert_eq!(
                trips(&origin).await - at,
                0,
                "{bytes} bytes should have been held"
            );

            spent
        }

        // Either side of the 32 KiB chunk, and well past it.
        assert_eq!(cost(1024).await, cost(200 * 1024).await);
    }

    /// And so does a file asked for directly, which is the one a reader waits on.
    ///
    /// The test above covers the prefetcher. The direct path had the same defect and no test,
    /// and it is the path that matters more: the files that reach it are exactly the ones a
    /// prefetch could not have warmed — the page itself, which has to be read before it can
    /// be scanned, and anything a script fetches at runtime.
    ///
    /// Found by pointing `e2e/probe.mjs` at real Documenter output, where a 700 KB
    /// `index.html` and a 2 MB `search_index.js` between them took the page to 95 remote
    /// round trips, and 26 once this was fixed. No unit test here could have found it,
    /// because every fixture in this file is three bytes long.
    #[tokio::test]
    async fn a_large_file_asked_for_directly_costs_what_a_small_one_costs() {
        async fn cost(bytes: usize) -> u64 {
            let origin = origin_with(
                FakeRemote::new()
                    .dir("/srv", vec![("big.bin", file_attrs(bytes as u64, 1))])
                    .file("/srv/big.bin", &vec![b'x'; bytes]),
            )
            .await;

            let before = trips(&origin).await;
            let res = origin.handle(get("/big.bin", None)).await;
            assert_eq!(res.status(), StatusCode::OK);
            // Every byte, not merely a successful status: a range read that stopped early
            // would otherwise pass this as a cheap request.
            assert_eq!(body_of(res).await.len(), bytes);
            trips(&origin).await - before
        }

        assert_eq!(cost(1024).await, cost(500 * 1024).await);
    }

    /// A listing that understates a file's length must not turn into an empty `200`.
    ///
    /// The prefetch reads a range, and a range is exactly as long as it was told to be. A
    /// listing reporting zero bytes for a file that has some would therefore cache an empty
    /// body — and the reader would be served it, because the cache is consulted first. This
    /// is the failure mode `CONTRIBUTING.md` names, arriving through a new door.
    ///
    /// Caught by the fake reporting a size of zero where a size was not set, which is what a
    /// real listing does when it is wrong rather than silent.
    #[tokio::test]
    async fn a_subresource_the_listing_calls_empty_is_not_prefetched() {
        let html = "<!doctype html><html><body><img src=\"assets/x.png\"></body></html>";
        let sizeless = Attrs {
            permissions: Some(0o100644),
            mtime: Some(1),
            ..Attrs::default()
        };
        let origin = origin_with(
            FakeRemote::new()
                .dir(
                    "/srv",
                    vec![
                        ("index.html", file_attrs(html.len() as u64, 100)),
                        ("assets", dir_attrs()),
                    ],
                )
                .dir("/srv/assets", vec![("x.png", sizeless)])
                .file("/srv/index.html", html.as_bytes())
                .file("/srv/assets/x.png", b"xxx"),
        )
        .await;

        assert_eq!(
            origin.handle(get("/index.html", None)).await.status(),
            StatusCode::OK
        );
        let res = origin.handle(get("/assets/x.png", None)).await;
        assert_eq!(res.status(), StatusCode::OK);
        assert_eq!(
            &body_of(res).await[..],
            b"xxx",
            "the real request must still serve the whole file"
        );
    }

    /// A subresource over the hold-whole limit is skipped rather than read and discarded.
    #[tokio::test]
    async fn an_oversized_subresource_is_not_prefetched() {
        async fn cost(size: u64) -> u64 {
            let html =
                "<!doctype html><html><body><video src=\"assets/film.mp4\"></video></body></html>";
            let origin = origin_with(
                FakeRemote::new()
                    .dir(
                        "/srv",
                        vec![
                            ("index.html", file_attrs(html.len() as u64, 100)),
                            ("assets", dir_attrs()),
                        ],
                    )
                    .dir("/srv/assets", vec![("film.mp4", file_attrs(size, 1))])
                    .file("/srv/index.html", html.as_bytes())
                    .file("/srv/assets/film.mp4", b"xxx"),
            )
            .await;
            let before = trips(&origin).await;
            assert_eq!(
                origin.handle(get("/index.html", None)).await.status(),
                StatusCode::OK
            );
            trips(&origin).await - before
        }

        // The listing is fetched either way; only the read differs. A film the cache would
        // decline must not be pulled across the network first to find that out.
        let read_it = cost(3).await;
        let skipped = cost(CACHE_WHOLE_MAX + 1).await;
        assert!(
            skipped < read_it,
            "an oversized subresource cost {skipped} against {read_it} for a small one"
        );
    }

    /// The port is taken before any host is connected.
    ///
    /// This ordering is the whole of what a previous change set out to fix, and nothing
    /// tested it: every other test here builds an `Origin` directly and never goes through
    /// `bind` at all. A regression that put the ssh handshakes first would pass the entire
    /// suite, and would cost a full set of connections before reporting the one failure an
    /// operator can actually act on.
    ///
    /// Cheap to check without any ssh infrastructure, precisely because the port failing
    /// first means the host is never reached: the error naming the bind and *not* naming the
    /// host is the evidence.
    #[tokio::test]
    async fn the_port_is_taken_before_any_host_is_connected() {
        let held = TcpListener::bind(("127.0.0.1", 0))
            .await
            .expect("a free port");
        let port = held.local_addr().expect("its address").port();

        const NOWHERE: &str = "a-host-that-cannot-resolve.invalid";
        let result = Origin::bind(
            vec![Alias::new("docs", NOWHERE, Some("/srv")).expect("a valid alias")],
            reachable::Set::default(),
            "ssh-browser".to_string(),
            "http".to_string(),
            port,
            Token::from_hex(TEST_TOKEN),
            theme::DEFAULT.to_string(),
        )
        .await;

        let Err(e) = result else {
            panic!("binding a port that is already held must fail");
        };
        let text = format!("{e:#}");
        assert!(
            text.contains(&format!("bind 127.0.0.1:{port}")),
            "the error should name the port, got: {text}"
        );
        assert!(
            !text.contains(NOWHERE),
            "the ssh host was reached before the port was taken: {text}"
        );
    }

    /// What makes a home directory a reasonable base: the things worth stealing there are
    /// behind a dot, and a dot is refused at any depth.
    #[tokio::test]
    async fn a_dot_name_is_never_served() {
        let origin = origin_with(
            FakeRemote::new()
                .dir(
                    "/srv",
                    vec![
                        ("Vault", dir_attrs()),
                        (".ssh", dir_attrs()),
                        (".netrc", file_attrs(9, 1)),
                    ],
                )
                .dir("/srv/.ssh", vec![("id_ed25519", file_attrs(9, 1))])
                .dir("/srv/Vault", vec![(".git", dir_attrs())])
                .dir("/srv/Vault/.git", vec![("config", file_attrs(9, 1))])
                .file("/srv/.ssh/id_ed25519", b"a-secret-")
                .file("/srv/.netrc", b"a-secret-")
                .file("/srv/Vault/.git/config", b"a-secret-"),
        )
        .await;

        for path in [
            "/.ssh/id_ed25519",
            "/.netrc",
            // At depth, and behind a directory that is itself perfectly ordinary.
            "/Vault/.git/config",
            // The directory itself, not only what is under it.
            "/.ssh/",
        ] {
            assert_eq!(
                origin.handle(get(path, None)).await.status(),
                StatusCode::FORBIDDEN,
                "{path}"
            );
        }
    }

    /// And they are not advertised either. Listing what the next click would refuse is worse
    /// than not listing it.
    #[tokio::test]
    async fn a_listing_does_not_mention_dot_names() {
        let origin = origin_with(FakeRemote::new().dir(
            "/srv",
            vec![
                ("Vault", dir_attrs()),
                (".ssh", dir_attrs()),
                (".obsidian", dir_attrs()),
            ],
        ))
        .await;

        let body = body_of(origin.handle(get("/", None)).await).await;
        let listing = String::from_utf8_lossy(&body);
        assert!(listing.contains("Vault"), "the ordinary entry is listed");
        assert!(!listing.contains(".ssh"), "got: {listing}");
        assert!(!listing.contains(".obsidian"), "got: {listing}");
    }

    /// The prefetcher must not become the way around it. A page is untrusted input, and this
    /// is the one part of the daemon that acts on what a page says.
    #[tokio::test]
    async fn a_page_cannot_prefetch_a_dot_name() {
        let html = "<!doctype html><html><body><img src=\".ssh/id_ed25519\"></body></html>";
        let origin = origin_with(
            FakeRemote::new()
                .dir(
                    "/srv",
                    vec![
                        ("index.html", file_attrs(html.len() as u64, 100)),
                        (".ssh", dir_attrs()),
                    ],
                )
                .dir("/srv/.ssh", vec![("id_ed25519", file_attrs(9, 1))])
                .file("/srv/index.html", html.as_bytes())
                .file("/srv/.ssh/id_ed25519", b"a-secret-"),
        )
        .await;

        assert_eq!(
            origin.handle(get("/index.html", None)).await.status(),
            StatusCode::OK
        );
        assert!(
            !origin.cache.has_listing("/srv/.ssh"),
            "the page got the daemon to list a directory it will not serve"
        );
        assert_eq!(
            origin.handle(get("/.ssh/id_ed25519", None)).await.status(),
            StatusCode::FORBIDDEN
        );
    }

    /// The same single file, four directories down.
    fn deep_tree() -> FakeRemote {
        FakeRemote::new()
            .dir("/srv", vec![("a", dir_attrs())])
            .dir("/srv/a", vec![("b", dir_attrs())])
            .dir("/srv/a/b", vec![("c", dir_attrs())])
            .dir("/srv/a/b/c", vec![("d.html", file_attrs(5, 100))])
            .file("/srv/a/b/c/d.html", b"deep!")
    }

    fn entry(name: &str, dir: bool) -> Entry {
        Entry {
            name: name.to_string(),
            attrs: Attrs {
                permissions: Some(if dir { 0o040755 } else { 0o100644 }),
                ..Attrs::default()
            },
        }
    }

    /// One directory as a tree with nothing above it, which is every test that is not about
    /// the ancestors or the site scan. Both of those need a remote; these do not.
    fn listing(alias: &str, rel: &str, entries: &[Entry]) -> String {
        let levels = vec![(rel.to_string(), rows_of(entries, &HashSet::new()))];
        autoindex(alias, rel, &levels, theme::DEFAULT)
    }

    #[test]
    fn a_hostile_filename_cannot_inject_script_into_our_origin() {
        let page = listing("docs", "", &[entry("<script>alert(1)</script>", false)]);
        assert!(!page.contains("<script>alert"));
        assert!(page.contains("&lt;script&gt;"));
    }

    /// Directories first and no headings, which is souta's call. Within the files the HTML
    /// rises, which is the other half of what they asked for.
    #[test]
    fn directories_come_first_and_pages_lead_the_files() {
        let page = listing(
            "docs",
            "",
            &[
                entry("b.txt", false),
                entry("z-dir", true),
                entry("a.txt", false),
                entry("report.html", false),
            ],
        );
        let dir = page.find("z-dir").expect("dir listed");
        let html = page.find("report.html").expect("page listed");
        let a = page.find("a.txt").expect("a listed");
        let b = page.find("b.txt").expect("b listed");
        assert!(
            dir < html,
            "directories come first, whatever they are called"
        );
        assert!(html < a, "then the pages, ahead of the other files");
        assert!(a < b, "and the rest by name");
        // No headings at all. They are what souta called 「みずらい」.
        assert!(!page.contains("<h2"), "{page}");
    }

    /// A page is decided by what the name *is*, so a file whose extension merely contains
    /// `html` is an ordinary file. `.htm` is the one other spelling worth accepting.
    #[test]
    fn only_html_counts_as_a_page() {
        let page = listing(
            "docs",
            "",
            &[
                entry("a.htm", false),
                entry("b.html.bak", false),
                entry("c.xhtml", false),
            ],
        );
        let htm = page.find("a.htm").expect("htm listed");
        let bak = page.find("b.html.bak").expect("bak listed");
        let xhtml = page.find("c.xhtml").expect("xhtml listed");
        assert!(htm < bak && htm < xhtml, "only the .htm leads: {page}");
        // And it is coloured as one, which is the only signal left now that the headings
        // are gone.
        assert!(
            page.contains("class=\"row k-page\" href=\"/a.htm\""),
            "{page}"
        );
    }

    #[test]
    fn hrefs_are_url_escaped() {
        let page = listing("docs", "", &[entry("a b#c.html", false)]);
        assert!(page.contains("href=\"/a%20b%23c.html\""));
    }

    /// The header says where you are. An explorer does not make you read the address bar
    /// to know which folder you are looking at.
    #[test]
    fn the_header_names_the_alias_and_where_you_are() {
        let page = listing("panza", "/Vault/infra", &[]);
        assert!(page.contains("<b>panza</b>"), "{page}");
        assert!(page.contains("<span>/Vault/infra</span>"), "{page}");
    }

    /// The point of a tree rather than a listing: every level of the path is open at once,
    /// with the rest of each level beside it, and the deepest is the one selected.
    ///
    /// It costs no round trips beyond the listing it replaces, because the walk that
    /// resolved the path warmed every ancestor to check it for symlinks — see
    /// `the_tree_costs_what_one_directory_cost`.
    #[tokio::test]
    async fn the_whole_path_is_expanded_and_the_deepest_is_selected() {
        let origin = origin_with(
            FakeRemote::new()
                .dir("/srv", vec![("a", dir_attrs()), ("elsewhere", dir_attrs())])
                .dir("/srv/a", vec![("b", dir_attrs()), ("sibling", dir_attrs())])
                .dir("/srv/a/b", vec![("leaf.txt", file_attrs(3, 1))])
                .dir("/srv/elsewhere", vec![])
                .dir("/srv/a/sibling", vec![]),
        )
        .await;

        let body = String::from_utf8(
            body_of(origin.handle(get("/a/b/", None)).await)
                .await
                .to_vec(),
        )
        .expect("utf-8");

        // Both levels of the path are open...
        assert!(body.contains("<li class=\"open\">"), "{body}");
        assert!(body.contains("href=\"/a/\""), "{body}");
        // ...the deepest is the one marked as where the reader is...
        assert!(body.contains("row dir here\" href=\"/a/b/\""), "{body}");
        // ...what is inside it is rendered...
        assert!(body.contains("leaf.txt"), "{body}");
        // ...and so is everything beside it on the way down, which is what makes this a
        // tree rather than one directory at a time.
        assert!(body.contains("elsewhere"), "{body}");
        assert!(body.contains("sibling"), "{body}");
    }

    /// The tree is four levels of listing, and it must cost what one level cost. Every
    /// ancestor was already fetched to check it for symlinks, so showing them is free; a
    /// version that went and asked again would pay for the depth twice.
    #[tokio::test]
    async fn the_tree_costs_what_one_directory_cost() {
        let deep = origin_with(deep_tree()).await;
        let before = trips(&deep).await;
        assert_eq!(
            deep.handle(get("/a/b/c/", None)).await.status(),
            StatusCode::OK
        );
        let four = trips(&deep).await - before;

        let shallow = origin_with(one_page()).await;
        let before = trips(&shallow).await;
        assert_eq!(
            shallow.handle(get("/", None)).await.status(),
            StatusCode::OK
        );
        let one = trips(&shallow).await - before;

        // The slack absorbs a flush of fire-and-forget CLOSE requests landing on either
        // side of the measurement. Asking per level would cost about four times as many.
        assert!(
            four <= one + 2,
            "a tree four deep cost {four} round trips against {one} for one directory"
        );
    }

    /// What the script asks for when a folder is expanded: the same level, as the fragment
    /// that goes inside it. One renderer, so the two cannot disagree about what a row is.
    #[tokio::test]
    async fn asking_for_one_level_answers_with_its_rows() {
        let origin = origin_with(
            FakeRemote::new()
                .dir("/srv", vec![("sub", dir_attrs())])
                .dir("/srv/sub", vec![("inner.md", file_attrs(4, 1))]),
        )
        .await;

        let req = Request::builder()
            .uri("http://docs.ssh-browser/sub/?ls")
            .header(HOST, "docs.ssh-browser")
            .body(Empty::<Bytes>::new())
            .expect("request builds");
        let res = origin.handle(req).await;
        assert_eq!(res.status(), StatusCode::OK);

        let body = String::from_utf8(body_of(res).await.to_vec()).expect("utf-8");
        // A fragment, so it can be inserted where it belongs rather than replacing a page.
        assert!(body.starts_with("<ul>"), "{body}");
        assert!(!body.contains("<html"), "{body}");
        // Built against the level it was asked about, so the href works from anywhere.
        assert!(body.contains("href=\"/sub/inner.md\""), "{body}");
    }

    /// It adds no capability. Everything `?ls` says is already in the page it belongs to,
    /// and a dot-name is refused here exactly as it is everywhere else.
    #[tokio::test]
    async fn asking_for_one_level_does_not_mention_dot_names() {
        let origin = origin_with(
            FakeRemote::new()
                .dir("/srv", vec![("sub", dir_attrs())])
                .dir(
                    "/srv/sub",
                    vec![("shown.md", file_attrs(4, 1)), (".hidden", dir_attrs())],
                ),
        )
        .await;

        let req = Request::builder()
            .uri("http://docs.ssh-browser/sub/?ls")
            .header(HOST, "docs.ssh-browser")
            .body(Empty::<Bytes>::new())
            .expect("request builds");
        let body =
            String::from_utf8(body_of(origin.handle(req).await).await.to_vec()).expect("utf-8");
        assert!(body.contains("shown.md"), "{body}");
        assert!(!body.contains(".hidden"), "{body}");
    }

    #[test]
    fn sizes_read_the_way_a_file_manager_shows_them() {
        assert_eq!(human_size(0), "0 B");
        assert_eq!(human_size(999), "999 B");
        assert_eq!(human_size(1024), "1.0 KiB");
        assert_eq!(human_size(1536), "1.5 KiB");
        // One decimal below ten and none above, so a column of them stays a column.
        assert_eq!(human_size(10 * 1024 * 1024), "10 MiB");
        assert_eq!(human_size(9_961_472), "9.5 MiB");
        assert_eq!(human_size(3 * 1024 * 1024 * 1024), "3.0 GiB");
    }

    /// Checked against dates that are known independently of the algorithm, including the
    /// epoch itself and a leap day, which is where a calendar implementation goes wrong.
    #[test]
    fn timestamps_are_the_utc_civil_date() {
        assert_eq!(utc_stamp(0), "1970-01-01 00:00");
        assert_eq!(utc_stamp(86_399), "1970-01-01 23:59");
        assert_eq!(utc_stamp(86_400), "1970-01-02 00:00");
        // 2000-02-29, a leap day in a century year that is a leap year.
        assert_eq!(utc_stamp(951_782_400), "2000-02-29 00:00");
        // 2100 is divisible by 4 and by 100 but not by 400, so it is *not* a leap year and
        // the day after 2100-02-28 is 2100-03-01. Getting this wrong is the classic way a
        // hand-rolled calendar fails, and the two constants below are one day apart.
        assert_eq!(utc_stamp(4_107_456_000), "2100-02-28 00:00");
        assert_eq!(utc_stamp(4_107_542_400), "2100-03-01 00:00");
        assert_eq!(utc_stamp(1_757_745_840), "2025-09-13 06:44");
    }

    /// A listing of nothing says so. An empty page with a heading over it reads as a
    /// failure rather than as an empty directory.
    #[test]
    fn an_empty_directory_says_it_is_empty() {
        let page = listing("docs", "/nothing", &[]);
        assert!(page.contains("This directory is empty"), "{page}");
    }

    #[test]
    fn the_component_chain_walks_from_the_base_down() {
        assert_eq!(
            components("/srv", "/srv/a/b/c.html"),
            vec![
                ("/srv".to_string(), "a".to_string()),
                ("/srv/a".to_string(), "b".to_string()),
                ("/srv/a/b".to_string(), "c.html".to_string()),
            ]
        );
        assert_eq!(
            components("/srv", "/srv/index.html"),
            vec![("/srv".to_string(), "index.html".to_string())]
        );
        // A trailing slash on the base must not produce an empty first component.
        assert_eq!(
            components("/srv/", "/srv/a.html"),
            vec![("/srv".to_string(), "a.html".to_string())]
        );
        // The file *is* the base: nothing between them to check.
        assert!(components("/srv", "/srv").is_empty());
    }

    /// Invariant 2. The listing and the body are both held, so the second request
    /// has nothing left to ask the remote.
    #[tokio::test]
    async fn a_revisit_costs_no_remote_round_trips() {
        let origin = origin_with(one_page()).await;

        let first = origin.handle(get("/a.html", None)).await;
        assert_eq!(first.status(), StatusCode::OK);
        let after_first = trips(&origin).await;
        assert!(after_first > 0, "the first request has to fetch something");

        let second = origin.handle(get("/a.html", None)).await;
        assert_eq!(second.status(), StatusCode::OK);
        assert_eq!(
            trips(&origin).await,
            after_first,
            "a revisit must be answered entirely from cache"
        );
    }

    /// Invariant 2 through the browser's own validator: the ETag came from the
    /// cached listing, so the 304 is decided inside this process.
    #[tokio::test]
    async fn a_conditional_get_is_answered_without_the_remote() {
        let origin = origin_with(one_page()).await;

        let first = origin.handle(get("/a.html", None)).await;
        let tag = first
            .headers()
            .get(ETAG)
            .expect("a validator is offered")
            .to_str()
            .expect("ascii")
            .to_string();
        let after_first = trips(&origin).await;

        let second = origin.handle(get("/a.html", Some(&tag))).await;
        assert_eq!(second.status(), StatusCode::NOT_MODIFIED);
        assert_eq!(
            trips(&origin).await,
            after_first,
            "a 304 must not touch the remote"
        );
    }

    /// A name the listing does not contain needs no fetch to answer.
    #[tokio::test]
    async fn a_missing_file_is_a_404_from_the_cached_listing() {
        let origin = origin_with(one_page()).await;

        // Warm the listing.
        origin.handle(get("/a.html", None)).await;
        let warm = trips(&origin).await;

        let missing = origin.handle(get("/nope.html", None)).await;
        assert_eq!(missing.status(), StatusCode::NOT_FOUND);
        assert_eq!(
            trips(&origin).await,
            warm,
            "a 404 for a listed-but-absent name must cost nothing"
        );
    }

    /// The guard SECURITY.md promises, decided from the listing rather than from a
    /// REALPATH per request.
    #[tokio::test]
    async fn a_symlink_is_refused() {
        let origin = origin_with(
            FakeRemote::new()
                .dir("/srv", vec![("link.html", symlink_attrs())])
                .file("/srv/link.html", b"whatever the target is"),
        )
        .await;

        let res = origin.handle(get("/link.html", None)).await;
        assert_eq!(res.status(), StatusCode::FORBIDDEN);
    }

    /// The listing knows it is a directory, so this costs no failed open first.
    #[tokio::test]
    async fn a_directory_without_a_trailing_slash_redirects() {
        let origin = origin_with(
            FakeRemote::new()
                .dir("/srv", vec![("sub", dir_attrs())])
                .dir("/srv/sub", vec![("b.html", file_attrs(1, 1))]),
        )
        .await;

        let res = origin.handle(get("/sub", None)).await;
        assert_eq!(res.status(), StatusCode::MOVED_PERMANENTLY);
        assert_eq!(
            res.headers().get(LOCATION).and_then(|v| v.to_str().ok()),
            Some("/sub/")
        );
    }

    /// A listing that promises a file the remote then refuses must not be kept, or
    /// the same wrong answer is served for a whole TTL.
    #[tokio::test]
    async fn a_listing_proven_wrong_is_forgotten() {
        // Listed, but no body declared: the open fails.
        let origin =
            origin_with(FakeRemote::new().dir("/srv", vec![("ghost.html", file_attrs(5, 100))]))
                .await;

        let res = origin.handle(get("/ghost.html", None)).await;
        assert_eq!(res.status(), StatusCode::NOT_FOUND);
        assert!(
            !origin.cache.has_listing("/srv"),
            "a listing contradicted by the remote must be dropped"
        );
    }

    /// A directory with no index.html is listed rather than 404'd.
    #[tokio::test]
    async fn a_directory_without_an_index_is_listed() {
        let origin =
            origin_with(FakeRemote::new().dir("/srv", vec![("only.txt", file_attrs(2, 1))])).await;

        let res = origin.handle(get("/", None)).await;
        assert_eq!(res.status(), StatusCode::OK);
        assert_eq!(
            res.headers()
                .get(CONTENT_TYPE)
                .and_then(|v| v.to_str().ok()),
            Some("text/html; charset=utf-8")
        );
    }

    /// The hole SECURITY.md used to describe. `/link/inside.html` names a file that
    /// exists and is not itself a symlink, but every route to it passes through one.
    #[tokio::test]
    async fn a_symlinked_directory_higher_up_the_path_is_refused() {
        let origin = origin_with(
            FakeRemote::new()
                .dir("/srv", vec![("link", symlink_attrs())])
                .dir("/srv/link", vec![("inside.html", file_attrs(2, 1))])
                .file("/srv/link/inside.html", b"hi"),
        )
        .await;

        let res = origin.handle(get("/link/inside.html", None)).await;
        assert_eq!(res.status(), StatusCode::FORBIDDEN);
    }

    /// Depth must not buy itself round trips. Every ancestor listing is issued
    /// together, so a path four deep costs what a path one deep costs.
    #[tokio::test]
    async fn a_deep_path_costs_what_a_shallow_one_costs() {
        let deep = origin_with(deep_tree()).await;
        assert_eq!(
            deep.handle(get("/a/b/c/d.html", None)).await.status(),
            StatusCode::OK
        );

        let shallow = origin_with(one_page()).await;
        assert_eq!(
            shallow.handle(get("/a.html", None)).await.status(),
            StatusCode::OK
        );

        let (d, sh) = (trips(&deep).await, trips(&shallow).await);
        // The slack absorbs one flush of fire-and-forget CLOSE requests landing on
        // either side of the measurement. A walk that listed one ancestor at a time
        // would cost about three times as many at this depth, and worse deeper.
        assert!(
            d <= sh + 2,
            "depth 4 cost {d} round trips against depth 1's {sh}"
        );
    }

    /// A component that exists but is not a directory.
    #[tokio::test]
    async fn a_file_used_as_a_directory_is_a_404() {
        let origin = origin_with(one_page()).await;
        let res = origin.handle(get("/a.html/b.html", None)).await;
        assert_eq!(res.status(), StatusCode::NOT_FOUND);
    }

    /// A deep path is served, not merely checked: the walk must not lose the file it
    /// was walking towards.
    #[tokio::test]
    async fn a_deep_path_serves_its_body() {
        let origin = origin_with(deep_tree()).await;
        let res = origin.handle(get("/a/b/c/d.html", None)).await;
        assert_eq!(res.status(), StatusCode::OK);
        assert_eq!(
            res.headers()
                .get(CONTENT_TYPE)
                .and_then(|v| v.to_str().ok()),
            Some("text/html; charset=utf-8")
        );
    }

    /// A range out of a body already held costs nothing: the slice happens here.
    #[tokio::test]
    async fn a_range_is_sliced_out_of_the_cached_body() {
        let origin = origin_with(one_page()).await;
        assert_eq!(
            origin.handle(get("/a.html", None)).await.status(),
            StatusCode::OK
        );
        let warm = trips(&origin).await;

        let res = origin.handle(ranged("/a.html", "bytes=1-3")).await;
        assert_eq!(res.status(), StatusCode::PARTIAL_CONTENT);
        assert_eq!(
            res.headers()
                .get(CONTENT_RANGE)
                .and_then(|v| v.to_str().ok()),
            Some("bytes 1-3/5")
        );
        assert_eq!(&body_of(res).await[..], b"ell");
        assert_eq!(
            trips(&origin).await,
            warm,
            "slicing a held body must cost no round trip"
        );
    }

    /// A range on a file not yet held still works, and the file ends up held.
    #[tokio::test]
    async fn a_range_on_a_cold_small_file_works_and_warms_the_cache() {
        let origin = origin_with(one_page()).await;

        let res = origin.handle(ranged("/a.html", "bytes=0-1")).await;
        assert_eq!(res.status(), StatusCode::PARTIAL_CONTENT);
        assert_eq!(&body_of(res).await[..], b"he");

        let warm = trips(&origin).await;
        let again = origin.handle(ranged("/a.html", "bytes=2-4")).await;
        assert_eq!(&body_of(again).await[..], b"llo");
        assert_eq!(
            trips(&origin).await,
            warm,
            "a small file fetched for a range should be held whole"
        );
    }

    /// The 416 has to name the real size, or a client cannot correct itself.
    #[tokio::test]
    async fn a_range_past_the_end_is_a_416_carrying_the_real_size() {
        let origin = origin_with(one_page()).await;
        let res = origin.handle(ranged("/a.html", "bytes=99-")).await;
        assert_eq!(res.status(), StatusCode::RANGE_NOT_SATISFIABLE);
        assert_eq!(
            res.headers()
                .get(CONTENT_RANGE)
                .and_then(|v| v.to_str().ok()),
            Some("bytes */5")
        );
    }

    /// A client that is not told ranges exist will never seek.
    #[tokio::test]
    async fn a_full_response_advertises_ranges() {
        let origin = origin_with(one_page()).await;
        let res = origin.handle(get("/a.html", None)).await;
        assert_eq!(
            res.headers()
                .get(ACCEPT_RANGES)
                .and_then(|v| v.to_str().ok()),
            Some("bytes")
        );
    }

    /// The validator on offer is weak, so `If-Range` cannot be honoured. The whole
    /// representation is the specified answer, not a 412 and not a 206.
    #[tokio::test]
    async fn if_range_yields_the_whole_file() {
        let origin = origin_with(one_page()).await;
        let req = Request::builder()
            .uri("http://docs.ssh-browser/a.html")
            .header(HOST, "docs.ssh-browser")
            .header(RANGE, "bytes=1-3")
            .header(IF_RANGE, "W/\"64-5\"")
            .body(Empty::<Bytes>::new())
            .expect("request builds");

        let res = origin.handle(req).await;
        assert_eq!(res.status(), StatusCode::OK);
        assert_eq!(&body_of(res).await[..], b"hello");
    }

    /// The branch that makes a video seekable: a file too big to hold is fetched by
    /// range and not cached, so a seek does not pull the whole thing.
    #[tokio::test]
    async fn a_large_file_is_served_by_range_and_not_held() {
        let body: Vec<u8> = (0..64u8).collect();
        let origin = origin_with(
            FakeRemote::new()
                // Declared far larger than the cache threshold; the body behind it is
                // small because what is under test is the branch, not the bytes.
                .dir("/srv", vec![("big.bin", file_attrs(9 * 1024 * 1024, 7))])
                .file("/srv/big.bin", &body),
        )
        .await;

        let res = origin.handle(ranged("/big.bin", "bytes=0-9")).await;
        assert_eq!(res.status(), StatusCode::PARTIAL_CONTENT);
        assert_eq!(&body_of(res).await[..], &body[0..10]);

        let after = trips(&origin).await;
        let second = origin.handle(ranged("/big.bin", "bytes=10-19")).await;
        assert_eq!(&body_of(second).await[..], &body[10..20]);
        assert!(
            trips(&origin).await > after,
            "a file over the threshold must not be held"
        );
    }

    /// The boundary, from the side that matters. A page served under an alias origin
    /// names the control path and gets a file lookup, not the control router: the 404
    /// proves it was never routed there. A 401 would mean the router saw it.
    #[tokio::test]
    async fn an_alias_origin_has_no_control_api_on_it() {
        let origin = origin_with(one_page()).await;
        let res = origin.handle(get("/_control/hello", None)).await;
        assert_eq!(res.status(), StatusCode::NOT_FOUND);
        assert_ne!(
            res.status(),
            StatusCode::UNAUTHORIZED,
            "a 401 would mean the control router was reached from an alias origin"
        );
    }

    /// Even with the right token in hand, an alias origin must not route to control.
    /// This is the case a compromised page would actually try.
    #[tokio::test]
    async fn an_alias_origin_with_a_valid_token_still_has_no_control_api() {
        let origin = origin_with(one_page()).await;
        let req = Request::builder()
            .uri("http://docs.ssh-browser/_control/hello")
            .header(HOST, "docs.ssh-browser")
            .header(control::TOKEN_HEADER, TEST_TOKEN)
            .body(Empty::<Bytes>::new())
            .expect("request builds");
        assert_eq!(origin.handle(req).await.status(), StatusCode::NOT_FOUND);
    }

    /// There is no write path on the read side, and a POST is told so rather than being
    /// quietly served as a GET.
    #[tokio::test]
    async fn the_alias_origin_refuses_writes() {
        let origin = origin_with(one_page()).await;
        for method in [Method::POST, Method::PUT, Method::DELETE, Method::PATCH] {
            let req = Request::builder()
                .method(method.clone())
                .uri("http://docs.ssh-browser/a.html")
                .header(HOST, "docs.ssh-browser")
                .body(Empty::<Bytes>::new())
                .expect("request builds");
            assert_eq!(
                origin.handle(req).await.status(),
                StatusCode::METHOD_NOT_ALLOWED,
                "{method} should be refused on the read-only origin"
            );
        }
    }

    #[tokio::test]
    async fn the_control_api_answers_on_loopback_with_the_token() {
        let origin = origin_with(one_page()).await;
        let res = origin
            .handle(loopback("/_control/hello", Some(TEST_TOKEN)))
            .await;
        assert_eq!(res.status(), StatusCode::OK);
        let body = body_of(res).await;
        let text = String::from_utf8_lossy(&body);
        assert!(
            text.contains("\"protocol\""),
            "hello must negotiate: {text}"
        );
        assert!(text.contains("\"docs\""), "hello must list aliases: {text}");
    }

    #[tokio::test]
    async fn the_control_api_refuses_loopback_without_the_token() {
        let origin = origin_with(one_page()).await;
        assert_eq!(
            origin
                .handle(loopback("/_control/hello", None))
                .await
                .status(),
            StatusCode::UNAUTHORIZED
        );
        assert_eq!(
            origin
                .handle(loopback("/_control/hello", Some("wrong")))
                .await
                .status(),
            StatusCode::UNAUTHORIZED
        );
    }

    /// The direct browsing path still works alongside the control prefix.
    #[tokio::test]
    async fn the_loopback_path_still_serves_files() {
        let origin = origin_with(one_page()).await;
        let res = origin.handle(loopback("/docs/a.html", None)).await;
        assert_eq!(res.status(), StatusCode::OK);
        assert_eq!(&body_of(res).await[..], b"hello");
    }

    /// The form souta asked for: bring the home directory into the config rather than
    /// writing out another machine's account layout by hand.
    #[tokio::test]
    async fn a_base_may_be_written_relative_to_the_home_directory() {
        let fs = FakeRemote::new().home("/home/souta").spawn().await;
        assert_eq!(
            resolve_base(Some("~/work"), &fs).await.expect("resolves"),
            "/home/souta/work"
        );
    }

    /// Three spellings of the same thing, and they had better agree.
    #[tokio::test]
    async fn a_bare_tilde_and_no_base_are_both_the_home_directory() {
        let fs = FakeRemote::new().home("/home/souta").spawn().await;
        assert_eq!(
            resolve_base(None, &fs).await.expect("resolves"),
            "/home/souta"
        );
        assert_eq!(
            resolve_base(Some("~"), &fs).await.expect("resolves"),
            "/home/souta"
        );
    }

    /// An absolute base is already the answer, so asking the remote would be a round trip
    /// spent to be told something already written down.
    #[tokio::test]
    async fn an_absolute_base_costs_no_round_trip() {
        let fs = FakeRemote::new().home("/home/souta").spawn().await;
        let before = fs.round_trips();
        assert_eq!(
            resolve_base(Some("/srv/docs"), &fs)
                .await
                .expect("resolves"),
            "/srv/docs"
        );
        assert_eq!(fs.round_trips(), before, "an absolute base must not ask");
    }

    /// The base is the blast radius of every page served under it, so a base that quietly
    /// meant somewhere other than where it reads is the worst place for a surprise.
    #[test]
    fn a_base_that_could_climb_out_of_the_home_directory_is_refused() {
        for bad in [
            "~/..",
            "~/../.ssh",
            "~/work/../..",
            "~/./x",
            "~work",
            "work",
            "",
        ] {
            assert!(!is_base(bad), "should have been refused: {bad:?}");
            assert!(
                Alias::new("docs", "h", Some(bad)).is_err(),
                "should have been refused: {bad:?}"
            );
        }
        for good in ["/", "/srv", "~", "~/work", "~/a/b/c"] {
            assert!(is_base(good), "should have been accepted: {good:?}");
        }
    }

    /// A home of `/` is unusual and not impossible, and `//work` is not portably the same
    /// path as `/work`: POSIX leaves a leading double slash implementation-defined.
    #[tokio::test]
    async fn a_root_home_does_not_produce_a_doubled_slash() {
        let fs = FakeRemote::new().home("/").spawn().await;
        assert_eq!(resolve_base(None, &fs).await.expect("resolves"), "/");
        assert_eq!(
            resolve_base(Some("~/work"), &fs).await.expect("resolves"),
            "/work"
        );
    }

    /// Deliberately asserts nothing about which hosts come back: the answer is whatever
    /// this machine's ssh_config says, and a test that pinned it would pass on one
    /// machine and fail on every other. What it does catch is the route not being wired
    /// up, which is otherwise only visible by hand.
    ///
    /// The token is not checked here because it cannot be reached without one: the gate
    /// runs in `handle` before any route is dispatched, so no control route can have its
    /// own answer to that question.
    #[tokio::test]
    async fn the_host_list_is_a_control_route() {
        let origin = origin_with(one_page()).await;
        let res = origin
            .handle(loopback("/_control/hosts", Some(TEST_TOKEN)))
            .await;
        assert_eq!(res.status(), StatusCode::OK);
        let text = String::from_utf8(body_of(res).await.to_vec()).expect("utf-8");
        let parsed: serde_json::Value = serde_json::from_str(&text).expect("json");
        assert!(parsed.get("hosts").is_some_and(|h| h.is_array()), "{text}");
        assert!(
            parsed.get("unusable").is_some_and(|u| u.is_array()),
            "{text}"
        );
    }

    /// The round-trip count is reachable at runtime, and moves.
    ///
    /// The claim this daemon is built on is a round-trip count, and the counter behind it
    /// used to be visible only to unit tests holding a `FakeRemote` — which makes the claim
    /// checkable against the fake and nowhere else. Reporting it lets `e2e/probe.mjs` read
    /// it for a real page on a real host, which is the only place it can be wrong in a way
    /// a reader would notice.
    ///
    /// Asserted as a strict increase rather than as a number. The number is the subject of
    /// other tests, and pinning it here would make this fail for every unrelated change to
    /// how a page is fetched. What must not pass is a field wired to a constant, which
    /// would report the invariant as perfect forever.
    #[tokio::test]
    async fn the_host_list_reports_round_trips_and_they_grow() {
        let origin = origin_with(one_page()).await;

        async fn trips_now(origin: &Origin) -> u64 {
            let res = origin
                .handle(loopback("/_control/hosts", Some(TEST_TOKEN)))
                .await;
            assert_eq!(res.status(), StatusCode::OK);
            let text = String::from_utf8(body_of(res).await.to_vec()).expect("utf-8");
            let parsed: serde_json::Value = serde_json::from_str(&text).expect("json");
            let open = parsed["open"].as_array().expect("open is an array");
            assert_eq!(open.len(), 1, "{text}");
            open[0]["trips"].as_u64().expect("trips is a number")
        }

        let before = trips_now(&origin).await;
        let res = origin.handle(get("/a.html", None)).await;
        assert_eq!(res.status(), StatusCode::OK);
        let after = trips_now(&origin).await;

        assert!(
            after > before,
            "serving a page reported no round trips ({before} -> {after})"
        );
    }

    /// A remembered label finds the ssh_config `Host` it came from, whatever its case.
    ///
    /// The regression this exists for: startup dialled the *label* rather than the `Host`, so a
    /// config saying `Host Panza` and a remembered `panza` produced `Could not resolve hostname
    /// panza` on every single start — while turning the host on a moment earlier had worked,
    /// because that path had the entry in hand. Two runs found it; no fake remote could have.
    #[test]
    fn a_remembered_label_finds_the_host_it_came_from() {
        let known = vec![
            ssh_config::Host {
                host: "Panza".to_string(),
                alias: "panza".to_string(),
            },
            ssh_config::Host {
                host: "issp-ohtaka".to_string(),
                alias: "issp-ohtaka".to_string(),
            },
        ];

        // What is actually written down is the label, and it has to reach `Panza`.
        assert_eq!(
            entry_for(&known, "panza").map(|h| h.host.as_str()),
            Some("Panza")
        );
        // And the other spelling, for a name typed rather than clicked.
        assert_eq!(
            entry_for(&known, "Panza").map(|h| h.host.as_str()),
            Some("Panza")
        );
        assert_eq!(
            entry_for(&known, "issp-ohtaka").map(|h| h.host.as_str()),
            Some("issp-ohtaka")
        );
    }

    /// A name ssh has never heard of is not dialled.
    ///
    /// Startup is the one path that reads hosts out of a file rather than from a request, so
    /// without this it is a looser door into "make this daemon ssh somewhere" than the two that
    /// are guarded — and one that fires again at every start.
    #[test]
    fn a_name_ssh_config_does_not_know_resolves_to_nothing() {
        let known = vec![ssh_config::Host {
            host: "Panza".to_string(),
            alias: "panza".to_string(),
        }];
        assert!(entry_for(&known, "not-a-host-anywhere").is_none());
        assert!(entry_for(&known, "").is_none());
        // Not a prefix or substring match either: `panz` is somebody else's name.
        assert!(entry_for(&known, "panz").is_none());
    }

    /// Enabling a host is held to the same gate opening one is.
    ///
    /// This is a second door into "make the daemon ssh somewhere", and a worse one if it is
    /// looser, because what it writes down is retried at every start from then on. The name is
    /// nonsense on purpose, so this asserts the same thing whether or not the machine running
    /// it has an ssh_config at all.
    #[tokio::test]
    async fn enabling_a_host_ssh_does_not_know_is_refused() {
        let origin = origin_with(one_page()).await;
        let res = origin
            .handle(control_post(
                "/_control/enabled",
                Some(TEST_TOKEN),
                r#"{"host":"not-a-host-in-anyones-ssh-config.invalid","enabled":true}"#,
            ))
            .await;
        assert_eq!(res.status(), StatusCode::NOT_FOUND);
    }

    /// And it needs the token, like everything else on this API.
    ///
    /// Worth its own check rather than trusting the gate: this route writes a file that
    /// survives the process, so "anyone on loopback can make this daemon ssh somewhere every
    /// morning" is the failure it would be.
    #[tokio::test]
    async fn enabling_a_host_without_the_token_is_refused() {
        let origin = origin_with(one_page()).await;
        let res = origin
            .handle(control_post(
                "/_control/enabled",
                None,
                r#"{"host":"anything","enabled":true}"#,
            ))
            .await;
        assert_eq!(res.status(), StatusCode::UNAUTHORIZED);
    }

    /// A body that does not say what to do is refused rather than defaulted.
    ///
    /// Defaulting `enabled` would make a malformed request turn a host on, or off, and the
    /// caller would have no way to tell which had happened.
    #[tokio::test]
    async fn enabling_needs_to_say_which_way() {
        let origin = origin_with(one_page()).await;
        for body in [
            r#"{"host":"anything"}"#,
            r#"{"enabled":true}"#,
            "{}",
            "not json",
        ] {
            let res = origin
                .handle(control_post("/_control/enabled", Some(TEST_TOKEN), body))
                .await;
            assert_eq!(
                res.status(),
                StatusCode::BAD_REQUEST,
                "{body} should not have been accepted"
            );
        }
    }

    /// Turning a host off closes it now, not only next time.
    ///
    /// A setting that took effect at the next restart is indistinguishable from one that did
    /// not work, and in this direction it is worse than confusing: a host still answering after
    /// you switched it off is an ssh session you believe you have given back.
    #[tokio::test]
    async fn disabling_a_host_closes_it_now() {
        let origin = origin_with(one_page()).await;
        // `docs` is the alias the test origin serves. Naming it here needs no ssh_config, but
        // the route checks ssh_config before it does anything -- so this asserts the closing
        // through the piece that does not need a network, and the gate above covers the rest.
        assert!(origin.session("docs").await.is_some());
        origin.sessions.write().await.remove("docs");
        assert!(
            origin.session("docs").await.is_none(),
            "removing the session is what disabling does, and a request must then 404"
        );
        let res = origin.handle(get("/a.html", None)).await;
        assert_eq!(res.status(), StatusCode::NOT_FOUND);
    }

    /// Nothing about how to reach a host is reported to anything but the dashboard.
    ///
    /// The point of the whole arrangement: `ssh_config` keeps the account, the port and the
    /// jump host, and an alias origin never learns any of it. A page that could read this off
    /// its own origin would be reading the machine's ssh setup.
    #[tokio::test]
    async fn an_alias_origin_cannot_read_the_host_list() {
        let origin = origin_with(one_page()).await;
        for path in ["/_control/hosts", "/_control/enabled", "/_control/hello"] {
            let res = origin.handle(get(path, None)).await;
            assert_ne!(
                res.status(),
                StatusCode::OK,
                "{path} answered a request from an alias origin"
            );
        }
    }

    /// The check that keeps `open` from being "ssh to anything on request". The list the
    /// extension offers is the menu, and a host that is not on it is a config change,
    /// which is a deliberate act rather than one request.
    ///
    /// The name is nonsense on purpose, so this asserts the same thing on a machine with
    /// an ssh_config and on one without.
    #[tokio::test]
    async fn opening_a_host_ssh_does_not_know_is_refused() {
        let origin = origin_with(one_page()).await;
        let res = origin
            .handle(control_post(
                "/_control/open",
                Some(TEST_TOKEN),
                r#"{"host":"not-a-host-in-anyones-ssh-config.invalid"}"#,
            ))
            .await;
        assert_eq!(res.status(), StatusCode::NOT_FOUND);
    }

    /// A body that does not name a host, and one that names a field this does not have.
    /// The second matters for the same reason the config file refuses unknown keys: a
    /// quietly dropped `base_path` opens an alias at somewhere nobody chose.
    #[tokio::test]
    async fn an_open_request_that_is_not_one_is_refused() {
        let origin = origin_with(one_page()).await;
        for body in [
            "",
            "{}",
            r#"{"base":"/srv"}"#,
            r#"{"host":"docs","base_path":"/srv"}"#,
        ] {
            let res = origin
                .handle(control_post("/_control/open", Some(TEST_TOKEN), body))
                .await;
            assert_eq!(
                res.status(),
                StatusCode::BAD_REQUEST,
                "should have been refused: {body}"
            );
        }
    }

    /// `open` has a side effect, so it is the route where the token matters most: a page
    /// can send a simple POST without a preflight, and could not read the answer but
    /// would still have caused the thing to happen.
    #[tokio::test]
    async fn opening_a_host_needs_the_token() {
        let origin = origin_with(one_page()).await;
        for token in [None, Some("wrong")] {
            let res = origin
                .handle(control_post("/_control/open", token, r#"{"host":"docs"}"#))
                .await;
            assert_eq!(res.status(), StatusCode::UNAUTHORIZED, "token {token:?}");
        }
    }

    /// What removes the paste, and the check that makes it safe to.
    ///
    /// The header values are the measured ones: an extension's `fetch` arrives with no
    /// `Sec-Fetch-Site` value this daemon would call a page, and a page the daemon itself
    /// serves in fallback mode arrives as `same-origin` -- the hardest case, because it
    /// shares an origin with the control API.
    #[tokio::test]
    async fn the_token_is_handed_over_to_something_that_is_not_a_page() {
        let origin = origin_with(one_page()).await;
        for site in [None, Some("none")] {
            let res = origin.handle(from_site("/_control/token", site)).await;
            assert_eq!(res.status(), StatusCode::OK, "site {site:?}");
            let body = String::from_utf8(body_of(res).await.to_vec()).expect("utf-8");
            assert_eq!(body.trim(), TEST_TOKEN, "site {site:?}");
        }
    }

    #[tokio::test]
    async fn a_page_is_not_handed_the_token() {
        let origin = origin_with(one_page()).await;
        for site in ["same-origin", "same-site", "cross-site"] {
            let res = origin
                .handle(from_site("/_control/token", Some(site)))
                .await;
            assert_eq!(res.status(), StatusCode::FORBIDDEN, "site {site}");
            let body = String::from_utf8(body_of(res).await.to_vec()).expect("utf-8");
            assert!(!body.contains(TEST_TOKEN), "the refusal leaked it: {body}");
        }
    }

    /// The case the token alone could not refuse: a page in the no-proxy fallback mode is
    /// same-origin with the control API, so a leaked token would have been enough.
    #[tokio::test]
    async fn a_page_with_the_token_still_cannot_use_the_control_api() {
        let origin = origin_with(one_page()).await;
        let req = Request::builder()
            .uri("http://127.0.0.1:7391/_control/hello")
            .header(HOST, "127.0.0.1:7391")
            .header(control::TOKEN_HEADER, TEST_TOKEN)
            .header(control::FETCH_SITE_HEADER, "same-origin")
            .body(Full::new(Bytes::new()))
            .expect("request builds");
        assert_eq!(origin.handle(req).await.status(), StatusCode::FORBIDDEN);
    }

    /// The other half of `open`, and the way a base gets changed: close, then reopen.
    #[tokio::test]
    async fn an_alias_can_be_closed_and_is_then_gone() {
        let origin = origin_with(one_page()).await;
        assert_eq!(
            origin.handle(get("/a.html", None)).await.status(),
            StatusCode::OK
        );

        let res = origin
            .handle(control_post(
                "/_control/close",
                Some(TEST_TOKEN),
                r#"{"alias":"docs"}"#,
            ))
            .await;
        assert_eq!(res.status(), StatusCode::OK);

        // The origin stops answering, rather than answering with stale bytes out of the
        // cache. An alias that is closed but still serving would be the worst of both.
        assert_eq!(
            origin.handle(get("/a.html", None)).await.status(),
            StatusCode::NOT_FOUND
        );
    }

    /// Kept apart from success. Told neither, a caller cannot tell "closed it" from
    /// "there was nothing there", and the second usually means a typo.
    #[tokio::test]
    async fn closing_an_alias_that_is_not_open_says_so() {
        let origin = origin_with(one_page()).await;
        let res = origin
            .handle(control_post(
                "/_control/close",
                Some(TEST_TOKEN),
                r#"{"alias":"nope"}"#,
            ))
            .await;
        assert_eq!(res.status(), StatusCode::NOT_FOUND);
    }

    #[tokio::test]
    async fn closing_an_alias_needs_the_token() {
        let origin = origin_with(one_page()).await;
        let res = origin
            .handle(control_post("/_control/close", None, r#"{"alias":"docs"}"#))
            .await;
        assert_eq!(res.status(), StatusCode::UNAUTHORIZED);
        // And it must not have happened anyway.
        assert_eq!(
            origin.handle(get("/a.html", None)).await.status(),
            StatusCode::OK
        );
    }

    /// souta's actual problem, in miniature. `out/` contains no HTML of its own; the board
    /// is `out/ft_demo/index.html`. Grouping the HTML in one listing would never surface
    /// it, so a directory that *is* a page has to say so.
    #[tokio::test]
    async fn a_directory_holding_an_index_is_listed_as_a_site() {
        let origin = origin_with(
            FakeRemote::new()
                .dir("/srv", vec![("ft-demo", dir_attrs()), ("src", dir_attrs())])
                .dir("/srv/ft-demo", vec![("index.html", file_attrs(5, 1))])
                .dir("/srv/src", vec![("main.jl", file_attrs(5, 1))])
                .file("/srv/ft-demo/index.html", b"board"),
        )
        .await;

        let body = String::from_utf8(body_of(origin.handle(get("/", None)).await).await.to_vec())
            .expect("utf-8");
        // Marked, so it reads as somewhere to open rather than somewhere to look. With no
        // headings left, the class and its colour are the whole signal.
        assert!(
            body.contains("class=\"row site\" href=\"/ft-demo/\""),
            "{body}"
        );
        let demo = body.find("ft-demo/").expect("the site listed");
        let src = body.find("src/").expect("the folder listed");
        assert!(demo < src, "a site leads the other directories: {body}");
    }

    /// The invariant, on the one page that pays for the scan. One listing for the directory
    /// and one batch for all of its subdirectories, whether there are two or twenty -- not
    /// one round trip each, which is what a loop would cost and what would make browsing a
    /// deep tree unusable over a real link.
    #[tokio::test]
    async fn the_site_scan_costs_the_same_however_many_subdirectories() {
        async fn trips_for(n: usize) -> u64 {
            let names: Vec<String> = (0..n).map(|i| format!("d{i:02}")).collect();
            let mut remote = FakeRemote::new().dir(
                "/srv",
                names.iter().map(|s| (s.as_str(), dir_attrs())).collect(),
            );
            for name in &names {
                remote = remote.dir(&format!("/srv/{name}"), vec![("a.txt", file_attrs(1, 1))]);
            }
            let origin = origin_with(remote).await;
            let before = trips(&origin).await;
            assert_eq!(origin.handle(get("/", None)).await.status(), StatusCode::OK);
            trips(&origin).await - before
        }

        let few = trips_for(2).await;
        let many = trips_for(20).await;
        assert_eq!(
            few, many,
            "{many} round trips for twenty subdirectories against {few} for two"
        );
    }

    /// And stepping into one of them is free afterwards, because the scan already fetched
    /// exactly the listing that click needs. The extra round trip is not purely a cost.
    #[tokio::test]
    async fn the_scan_leaves_the_next_click_paid_for() {
        let origin = origin_with(
            FakeRemote::new()
                .dir("/srv", vec![("sub", dir_attrs())])
                .dir("/srv/sub", vec![("a.txt", file_attrs(1, 1))]),
        )
        .await;
        assert_eq!(origin.handle(get("/", None)).await.status(), StatusCode::OK);

        let before = trips(&origin).await;
        assert_eq!(
            origin.handle(get("/sub/", None)).await.status(),
            StatusCode::OK
        );
        assert_eq!(
            trips(&origin).await,
            before,
            "the listing the scan fetched should still be the one that answers"
        );
    }

    /// The race a two-second TTL made possible, forced to happen every time.
    ///
    /// The walk used to ask the cache whether a listing was there and then ask it for the
    /// listing. Those are two questions with a gap between them, and a request landing on
    /// the expiry boundary got yes and then no -- a 404 reading "cannot list" about a
    /// directory that plainly existed, on about one e2e run in six. With a TTL of zero
    /// every read misses, so the gap is guaranteed rather than occasional.
    ///
    /// It passes because the listings are taken once and held for the request. Nothing here
    /// can make them expire, because nothing re-reads them.
    #[tokio::test]
    async fn a_listing_that_expires_mid_request_does_not_lose_the_path() {
        let origin =
            origin_with_cache(deep_tree(), Cache::new(std::time::Duration::ZERO, 1 << 20)).await;
        assert_eq!(
            origin.handle(get("/a/b/c/d.html", None)).await.status(),
            StatusCode::OK,
            "a path four deep must survive its own listings expiring"
        );
        // And a directory too, which is the one that builds a tree out of them.
        assert_eq!(
            origin.handle(get("/a/b/c/", None)).await.status(),
            StatusCode::OK
        );
    }

    /// The other half: a refusal that is not absence carries ssh's own words out, rather
    /// than this daemon's word for not knowing.
    #[tokio::test]
    async fn a_directory_the_remote_refuses_says_why() {
        let origin = origin_with(
            FakeRemote::new()
                .dir("/srv", vec![("locked", dir_attrs())])
                // 3 is SSH_FX_PERMISSION_DENIED: refused, and not for being absent.
                .refuses_listing("/srv/locked", 3),
        )
        .await;

        let res = origin.handle(get("/locked/x.html", None)).await;
        assert_eq!(res.status(), StatusCode::BAD_GATEWAY);
        let said = String::from_utf8(body_of(res).await.to_vec()).expect("utf-8");
        assert!(said.contains("/srv/locked"), "{said}");
        assert!(
            !said.contains("cannot list"),
            "the old wording said nothing the reader could act on: {said}"
        );
    }
}