tw-cli 0.1.0

//! Where a pinned release comes from, and which credential may go with it.
//!
//! `.tooling/tooling-versions.json` names each tool's repository by URL. The
//! host of that URL says which forge serves it -- GitHub, GitLab or Forgejo
//! -- and so how a release asset is fetched and which token, if any, goes
//! with the request. github.com and gitlab.com are built in. Any other host
//! is declared by the corpus, under a top-level `"forges"` key of the same
//! file, so a pin and the forge it lives on are read from one place:
//!
//! ```json
//! "forges": {
//!   "git.example.com": {"type": "forgejo", "token_env": ["FORGEJO_TOKEN"]},
//!   "gitlab.example.com:8443": {"type": "gitlab", "token_env": "EXAMPLE_GITLAB_TOKEN"},
//!   "ghe.example.com": {"type": "github", "api": "https://ghe.example.com/api/v3"}
//! }
//! ```
//!
//! An entry for github.com or gitlab.com overrides the built-in one; the
//! fields it leaves out keep their built-in values. A pin on a host that is
//! neither built in nor declared is an error, said as one, rather than a
//! download attempted with a guess about what is on the other end.
//!
//! ## Where a token goes
//!
//! A token is a credential for one forge and nothing else. It is read from
//! the first variable `token_env` names that holds one (see [`token_value`]:
//! the rule writer-setup.sh, writer-setup.ps1 and the npm scripts share),
//! from the environment or else the corpus's `.env`, and sent only to that
//! forge, and only over https: to the origin of the pinned repository's URL and to
//! the origin of the forge's API -- same scheme, same host, same port, the
//! host compared as every URL is after parsing (lower case, IDNA), so a
//! look-alike such as `git.example.com.attacker.example` is another host.
//! Never to a URL that carries a user name or a password, never to a host
//! the file does not declare, and never on a redirect that leaves the origin
//! it was sent to: GitHub and GitLab both hand the bytes of a release asset
//! over from a storage host, and a token that followed would be given away
//! with them. So redirects are followed here, one hop at a time, and not by
//! the HTTP client, which knows that `Authorization` is a credential and not
//! that GitLab's `PRIVATE-TOKEN` is one.
//!
//! ## How each forge is asked
//!
//! * GitHub, no token: `{repo}/releases/download/{tag}/{asset}`, the public
//!   URL. With one: the API, `repos/{owner}/{repo}/releases/tags/{tag}` for
//!   the asset's id and then `releases/assets/{id}` as
//!   `application/octet-stream` -- the one route by which a token reaches a
//!   release asset on GitHub.
//! * GitLab, either way: `projects/{url-encoded path}/releases/{tag}` from
//!   the API, and the asset link of that name. Anonymously that is the
//!   route on which a private project answers 404, where its web permalink
//!   would answer with a sign-in page.
//! * Forgejo, either way: `{repo}/releases/download/{tag}/{asset}`, with the
//!   token when there is one.

#[cfg(test)]
use std::collections::HashMap;
use url::{Origin, Url};

/// Which software a forge runs, which decides the requests and the header.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Kind {
    GitHub,
    GitLab,
    Forgejo,
}

impl Kind {
    fn parse(value: &str) -> Option<Kind> {
        match value {
            "github" => Some(Kind::GitHub),
            "gitlab" => Some(Kind::GitLab),
            "forgejo" => Some(Kind::Forgejo),
            _ => None,
        }
    }

    pub fn label(self) -> &'static str {
        match self {
            Kind::GitHub => "github",
            Kind::GitLab => "gitlab",
            Kind::Forgejo => "forgejo",
        }
    }

    /// The header a token travels in, as each forge documents it.
    fn header(self, token: &str) -> (&'static str, String) {
        match self {
            Kind::GitHub => ("Authorization", format!("Bearer {token}")),
            Kind::GitLab => ("PRIVATE-TOKEN", token.to_string()),
            Kind::Forgejo => ("Authorization", format!("token {token}")),
        }
    }
}

/// A key of `"forges"`: a host, and a port when it is not the default one.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Host {
    /// As a URL's host reads after parsing: lower case, IDNA applied.
    name: String,
    /// `None` is the default port of whichever scheme the URL has.
    port: Option<u16>,
}

impl Host {
    /// `forge.example.com` or `forge.example.com:3000`, and nothing more: a
    /// key that is really a URL, or carries a user name, is refused rather
    /// than half-matched.
    pub fn parse(key: &str) -> Result<Host, String> {
        let refused = || {
            format!(
                "`{key}` is not a host. A key of \"forges\" is a host name, \
                 and a port when it is not the default: `forge.example.com` or \
                 `forge.example.com:3000`, with no scheme, user or path."
            )
        };
        if key.is_empty()
            || key
                .chars()
                .any(|c| c.is_whitespace() || c.is_control() || "/\\@?#%".contains(c))
        {
            return Err(refused());
        }
        // A plain ASCII host name -- letters, digits, dots and hyphens, a
        // letter or digit at each end -- and a port of 1 to 65535 when one
        // is written: what writer-setup.sh, writer-setup.ps1 and the npm
        // scripts take, so a key one of them refuses is no forge here either
        // (`*` was one: the URL parser takes it for a host).
        let (name, digits) = match key.split_once(':') {
            Some((name, digits)) => (name, Some(digits)),
            None => (key, None),
        };
        let plain = name.starts_with(|c: char| c.is_ascii_alphanumeric())
            && name.ends_with(|c: char| c.is_ascii_alphanumeric())
            && name
                .chars()
                .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '-');
        let port_ok = digits.is_none_or(|d| {
            (1..=5).contains(&d.len())
                && d.chars().all(|c| c.is_ascii_digit())
                && (1..=65535).contains(&d.parse::<u32>().unwrap_or(0))
        });
        if !plain || !port_ok {
            return Err(refused());
        }
        let url = Url::parse(&format!("https://{key}/")).map_err(|_| refused())?;
        let name = url.host_str().ok_or_else(refused)?.to_string();
        // Written out, the port is the one meant -- even 443, which the
        // parser folds away because it is https's default.
        let port = match key.rsplit_once(':') {
            Some((host, digits))
                if !digits.is_empty()
                    && digits.chars().all(|c| c.is_ascii_digit())
                    && (!host.starts_with('[') || host.ends_with(']')) =>
            {
                Some(digits.parse::<u16>().map_err(|_| refused())?)
            }
            _ => None,
        };
        Ok(Host { name, port })
    }

    /// Whether `url` is on this host: the same name after parsing, and the
    /// port written in the key -- or, with none written, the default port of
    /// the URL's scheme. A URL with a user name or password is on no host
    /// here, whatever follows its `@`.
    pub fn serves(&self, url: &Url) -> bool {
        no_userinfo(url)
            && url.host_str() == Some(self.name.as_str())
            && match self.port {
                Some(port) => url.port_or_known_default() == Some(port),
                None => url.port().is_none(),
            }
    }

    fn display(&self) -> String {
        match self.port {
            Some(port) => format!("{}:{port}", self.name),
            None => self.name.clone(),
        }
    }
}

fn no_userinfo(url: &Url) -> bool {
    url.username().is_empty() && url.password().is_none()
}

/// What a variable named in `token_env` holds, by the one rule tw,
/// writer-setup.sh, writer-setup.ps1 and the npm scripts' `lib/tools.ts`
/// share:
///
/// * spaces, tabs, carriage returns, line feeds, vertical tabs and form feeds
///   at either end are dropped -- a token pasted from a Windows file ends in
///   a carriage return;
/// * what is left empty counts as unset, and the next name is tried;
/// * what is left holding a control character (U+0000 to U+001F, U+007F) is
///   refused with an error that names the variable and never its value,
///   rather than sent in a header or skipped in favour of another token.
pub fn token_value(name: &str, value: Option<&str>) -> Result<Option<String>, String> {
    let Some(value) = value else {
        return Ok(None);
    };
    let value = value.trim_matches([' ', '\t', '\r', '\n', '\x0b', '\x0c']);
    if value.is_empty() {
        return Ok(None);
    }
    if value.chars().any(|c| c.is_ascii_control()) {
        return Err(format!(
            "{name} holds a control character, so it cannot be sent as a token"
        ));
    }
    Ok(Some(value.to_string()))
}

/// One forge, as declared or built in.
#[derive(Debug, Clone)]
pub struct Forge {
    pub host: Host,
    pub kind: Kind,
    /// Tried in order; the first that holds a token is the token.
    pub token_env: Vec<String>,
    /// The API's base URL, when it is not where `kind` puts it by default.
    api: Option<Url>,
}

impl Forge {
    fn builtin(host: &str, kind: Kind, token_env: &str, api: &str) -> Forge {
        Forge {
            host: Host::parse(host).expect("a built-in host parses"),
            kind,
            token_env: vec![token_env.to_string()],
            api: Some(Url::parse(api).expect("a built-in API URL parses")),
        }
    }

    /// The API's base URL for a repository at `repo`: the declared one, or
    /// where each forge serves it from its own origin.
    fn api_for(&self, repo: &Url) -> Url {
        if let Some(api) = &self.api {
            return api.clone();
        }
        let mut base = repo.clone();
        base.set_query(None);
        base.set_fragment(None);
        base.set_path(match self.kind {
            Kind::GitHub => "/api/v3",
            Kind::GitLab => "/api/v4",
            Kind::Forgejo => "/api/v1",
        });
        base
    }

    /// The token, with the name of the variable it came from: the first of
    /// `token_env` that holds one, by [`token_value`]. A variable holding a
    /// control character stops the search with an error naming it.
    pub fn token(&self, env: &Env) -> Result<Option<(String, String)>, String> {
        for name in &self.token_env {
            if let Some(value) = token_value(name, env.get(name).as_deref())? {
                return Ok(Some((name.clone(), value)));
            }
        }
        Ok(None)
    }

    /// The token's variables in words, for a message: `A`, `A or B`, ...
    fn token_names(&self) -> String {
        match self.token_env.as_slice() {
            [] => String::new(),
            [one] => one.clone(),
            [rest @ .., last] => format!("{} or {last}", rest.join(", ")),
        }
    }
}

/// Every forge a corpus can download from: the declared ones, then the
/// built-in ones nothing overrode.
#[derive(Debug, Clone)]
pub struct Forges {
    forges: Vec<Forge>,
}

/// The two forges every corpus can use without declaring them.
fn builtins() -> Vec<Forge> {
    vec![
        Forge::builtin(
            "github.com",
            Kind::GitHub,
            "GITHUB_TOKEN",
            "https://api.github.com",
        ),
        Forge::builtin(
            "gitlab.com",
            Kind::GitLab,
            "GITLAB_TOKEN",
            "https://gitlab.com/api/v4",
        ),
    ]
}

impl Default for Forges {
    fn default() -> Self {
        Forges { forges: builtins() }
    }
}

/// Whether a key is prose: `"//"` and anything starting with it.
pub fn is_note(key: &str) -> bool {
    key.starts_with("//")
}

/// `^[A-Za-z_][A-Za-z0-9_]*$`: a name every shell and CI can set.
fn is_variable_name(name: &str) -> bool {
    let mut chars = name.chars();
    chars
        .next()
        .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
        && chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
}

/// A JSON value as far as [`check_shape`] looks at it: an object's members
/// in the order the file gives them, a key given twice twice -- of which
/// `serde_json::Value` keeps one -- each key as JSON reads it, escapes
/// decoded; anything else is not an object.
enum Raw {
    Object(Vec<(String, Raw)>),
    Other,
}

impl<'de> serde::Deserialize<'de> for Raw {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Raw, D::Error> {
        struct Visitor;
        impl<'de> serde::de::Visitor<'de> for Visitor {
            type Value = Raw;
            fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
                f.write_str("a JSON value")
            }
            fn visit_map<A: serde::de::MapAccess<'de>>(self, mut map: A) -> Result<Raw, A::Error> {
                let mut members = Vec::new();
                while let Some(member) = map.next_entry::<String, Raw>()? {
                    members.push(member);
                }
                Ok(Raw::Object(members))
            }
            fn visit_seq<A: serde::de::SeqAccess<'de>>(self, mut seq: A) -> Result<Raw, A::Error> {
                while seq.next_element::<serde::de::IgnoredAny>()?.is_some() {}
                Ok(Raw::Other)
            }
            fn visit_bool<E>(self, _: bool) -> Result<Raw, E> {
                Ok(Raw::Other)
            }
            fn visit_i64<E>(self, _: i64) -> Result<Raw, E> {
                Ok(Raw::Other)
            }
            fn visit_u64<E>(self, _: u64) -> Result<Raw, E> {
                Ok(Raw::Other)
            }
            fn visit_f64<E>(self, _: f64) -> Result<Raw, E> {
                Ok(Raw::Other)
            }
            fn visit_str<E>(self, _: &str) -> Result<Raw, E> {
                Ok(Raw::Other)
            }
            fn visit_unit<E>(self) -> Result<Raw, E> {
                Ok(Raw::Other)
            }
        }
        deserializer.deserialize_any(Visitor)
    }
}

/// The `"forges"` of tooling-versions.json, every entry of it, checked on
/// the file's text before anything is read from it, as writer-setup.sh,
/// writer-setup.ps1 and the npm scripts check it, in the same order and,
/// but for a key that is no host, in the same words -- so that all four
/// refuse one file for one reason: `"forges"` once, an object; each key in
/// it a note or a plain ASCII host name, or `host:port`, that no other key
/// names; each forge an object of `"type"`, `"token_env"` and `"api"` (and
/// notes), none of them twice. Keys are compared as JSON spells them,
/// escapes decoded, case and all. A key given twice is valid JSON, and
/// always a mistake here: which one counts would be up to the reader.
///
/// A text that is not JSON, or not an object, passes: that is said where
/// the file is read.
pub fn check_shape(text: &str) -> Result<(), String> {
    let Ok(Raw::Object(top)) = serde_json::from_str::<Raw>(text) else {
        return Ok(());
    };
    let mut all = top.iter().filter(|(key, _)| key == "forges");
    let Some((_, forges)) = all.next() else {
        return Ok(());
    };
    if all.next().is_some() {
        return Err("\"forges\" is given twice".to_string());
    }
    check_forges(forges)
}

/// [`check_shape`] for the value of `"forges"`.
fn check_forges(forges: &Raw) -> Result<(), String> {
    let Raw::Object(entries) = forges else {
        return Err("\"forges\" is not an object of hosts".to_string());
    };
    let mut hosts: Vec<(String, u16)> = Vec::new();
    for (key, entry) in entries {
        if is_note(key) {
            continue;
        }
        let host = Host::parse(key).map_err(|e| format!("\"forges\": {e}"))?;
        let at = (host.name, host.port.unwrap_or(443));
        if hosts.contains(&at) {
            return Err(format!("forge {key}: declared twice"));
        }
        hosts.push(at);
        let Raw::Object(fields) = entry else {
            return Err(format!("forge {key}: not an object"));
        };
        let mut seen: Vec<&str> = Vec::new();
        for (field, _) in fields {
            if is_note(field) {
                continue;
            }
            if !FIELDS.contains(&field.as_str()) {
                return Err(format!(
                    "forge {key}: unknown field \"{field}\"; the fields are \"type\", \"token_env\" and \"api\""
                ));
            }
            if seen.contains(&field.as_str()) {
                return Err(format!("forge {key}: \"{field}\" is given twice"));
            }
            seen.push(field);
        }
    }
    Ok(())
}

/// The fields of a forge, beside notes.
const FIELDS: [&str; 3] = ["type", "token_env", "api"];

impl Forges {
    /// The `"forges"` value of tooling-versions.json, if it has one, over
    /// the built-in two.
    ///
    /// Strict where the pins are tolerant. A misspelt field here is not a
    /// comment, it is a token that quietly stops being sent -- which shows
    /// up as a 404 on a private repository and says nothing about why.
    pub fn parse(value: Option<&serde_json::Value>) -> Result<Forges, String> {
        let mut forges: Vec<Forge> = Vec::new();
        let Some(value) = value else {
            return Ok(Forges::default());
        };
        let object = value
            .as_object()
            .ok_or("\"forges\" is not an object of hosts")?;
        for (key, entry) in object {
            if is_note(key) {
                continue;
            }
            let host = Host::parse(key).map_err(|e| format!("\"forges\": {e}"))?;
            let at = |what: String| format!("\"forges\" -> \"{key}\": {what}");
            let fields = entry
                .as_object()
                .ok_or_else(|| format!("forge {key}: not an object"))?;
            for field in fields.keys() {
                if !is_note(field) && !FIELDS.contains(&field.as_str()) {
                    return Err(format!(
                        "forge {key}: unknown field \"{field}\"; the fields are \"type\", \"token_env\" and \"api\""
                    ));
                }
            }
            let kind = match fields.get("type") {
                Some(serde_json::Value::String(t)) => Kind::parse(t).ok_or_else(|| {
                    at(format!(
                        "\"type\" is `{t}`; it is \"github\", \"gitlab\" or \"forgejo\""
                    ))
                })?,
                Some(_) => return Err(at("\"type\" is not a string".to_string())),
                None => {
                    return Err(at(
                        "no \"type\"; it is \"github\", \"gitlab\" or \"forgejo\"".to_string(),
                    ));
                }
            };
            // What a built-in host's entry leaves out it keeps, as long as
            // it is still the same kind of forge.
            let builtin = builtins()
                .into_iter()
                .find(|b| b.host == host && b.kind == kind);
            let token_env = match fields.get("token_env") {
                None => builtin
                    .as_ref()
                    .map(|b| b.token_env.clone())
                    .unwrap_or_default(),
                Some(serde_json::Value::String(name)) => vec![name.clone()],
                Some(serde_json::Value::Array(names)) => names
                    .iter()
                    .map(|n| n.as_str().map(str::to_string))
                    .collect::<Option<Vec<_>>>()
                    .ok_or_else(|| at("\"token_env\" holds a non-string".to_string()))?,
                Some(_) => {
                    return Err(at(
                        "\"token_env\" is a variable's name or a list of them".to_string()
                    ));
                }
            };
            // `^[A-Za-z_][A-Za-z0-9_]*$`, in the words the corpus's own
            // readers (writer-setup.sh, .ps1, tools.ts) use for the same
            // refusal: a name a shell cannot export is a token never found.
            if let Some(bad) = token_env.iter().find(|n| !is_variable_name(n)) {
                return Err(format!(
                    "forge {key}: token_env \"{bad}\" is not an environment variable name"
                ));
            }
            let api = match fields.get("api") {
                None => builtin.and_then(|b| b.api),
                Some(serde_json::Value::String(api)) => Some(api_url(api).map_err(at)?),
                Some(_) => return Err(at("\"api\" is not a string".to_string())),
            };
            if forges.iter().any(|f| f.host == host) {
                return Err(format!("forge {key}: declared twice"));
            }
            forges.push(Forge {
                host,
                kind,
                token_env,
                api,
            });
        }
        for builtin in builtins() {
            if !forges.iter().any(|f| f.host == builtin.host) {
                forges.push(builtin);
            }
        }
        Ok(Forges { forges })
    }

    /// The forge serving `url`, if one is declared or built in.
    pub fn serving(&self, url: &Url) -> Option<&Forge> {
        self.forges.iter().find(|f| f.host.serves(url))
    }

    /// Where release `tag` of the repository at `repo` comes from.
    pub fn locate(&self, repo: &str) -> Result<Located, String> {
        let url = repo_url(repo)?;
        let forge = self.serving(&url).cloned().ok_or_else(|| {
            let host = match url.port() {
                Some(port) => format!("{}:{port}", url.host_str().unwrap_or("")),
                None => url.host_str().unwrap_or("").to_string(),
            };
            format!(
                "{repo} is on {host}, which .tooling/tooling-versions.json does \
                 not declare. tw knows github.com and gitlab.com; any other \
                 host is declared under \"forges\", with the software it runs \
                 and the variable that holds a token for it, if it needs one:\n  \
                 \"forges\": {{\"{host}\": {{\"type\": \"forgejo\", \"token_env\": \"FORGE_TOKEN\"}}}}\n  \
                 (\"type\" is \"github\", \"gitlab\" or \"forgejo\".)"
            )
        })?;
        let path: Vec<String> = url
            .path_segments()
            .map(|s| s.filter(|s| !s.is_empty()).map(str::to_string).collect())
            .unwrap_or_default();
        let fits = match forge.kind {
            // owner/repo, and nothing else, is what the API addresses.
            Kind::GitHub => path.len() == 2,
            // A group, any subgroups, and the project.
            Kind::GitLab => path.len() >= 2,
            // Appended to as it is, so only an owner and a repository's
            // worth of path is required; a forge served under a sub-path
            // keeps it.
            Kind::Forgejo => path.len() >= 2,
        };
        if !fits {
            return Err(format!(
                "{repo} is not a repository's URL on {} ({}): it wants \
                 https://{}/<owner>/<repository>",
                forge.host.display(),
                forge.kind.label(),
                forge.host.display(),
            ));
        }
        let api = forge.api_for(&url);
        Ok(Located {
            repo: url,
            path,
            api,
            forge,
        })
    }
}

/// A repository's URL, refused unless it is plainly one.
fn repo_url(repo: &str) -> Result<Url, String> {
    let url = Url::parse(repo.trim_end_matches('/'))
        .map_err(|e| format!("`{repo}` is not a URL: {e}"))?;
    // Over https only: a token read for this forge would otherwise cross
    // the network in clear, and so would the bytes it is about to run.
    if url.scheme() != "https" {
        return Err(format!(
            "`{repo}` is not an https:// URL. tw fetches only over https, so \
             that neither a token nor a download crosses the network in clear."
        ));
    }
    if !no_userinfo(&url) {
        return Err(format!(
            "`{repo}` carries a user name or password. A token goes in an \
             environment variable that \"forges\" names as \"token_env\", \
             never in a URL in a committed file."
        ));
    }
    if url.query().is_some() || url.fragment().is_some() || url.host_str().is_none() {
        return Err(format!("`{repo}` is not a repository's URL"));
    }
    Ok(url)
}

/// An `"api"` value: an https base URL with no user, query or fragment.
fn api_url(api: &str) -> Result<Url, String> {
    let url = Url::parse(api.trim_end_matches('/'))
        .map_err(|e| format!("\"api\" `{api}` is not a URL: {e}"))?;
    if url.scheme() != "https"
        || !no_userinfo(&url)
        || url.query().is_some()
        || url.fragment().is_some()
        || url.host_str().is_none()
    {
        return Err(format!(
            "\"api\" `{api}` is not an API's base URL, such as \
             https://forge.example.com/api/v4"
        ));
    }
    Ok(url)
}

/// A repository, the forge serving it, and that forge's API.
#[derive(Debug, Clone)]
pub struct Located {
    pub repo: Url,
    /// The repository's path, one segment each: owner and name, or a
    /// GitLab project's groups and name.
    path: Vec<String>,
    pub api: Url,
    pub forge: Forge,
}

impl Located {
    /// Where the token may go: this repository's origin, and its API's --
    /// both https, which `locate` made sure of.
    pub fn credential(&self, env: &Env) -> Result<Option<Credential>, String> {
        let Some((variable, token)) = self.forge.token(env)? else {
            return Ok(None);
        };
        let (header, value) = self.forge.kind.header(&token);
        Ok(Some(Credential {
            variable,
            header,
            value,
            origins: vec![self.repo.origin(), self.api.origin()],
        }))
    }

    /// `{repo}/releases/download/{tag}/{asset}`: GitHub's public URL and
    /// Forgejo's either way.
    pub fn download_url(&self, tag: &str, asset: &str) -> Url {
        let mut url = self.repo.clone();
        url.path_segments_mut()
            .expect("an http URL has a path")
            .pop_if_empty()
            .extend(["releases", "download", tag, asset]);
        url
    }

    /// An API URL under the base: each part one path segment, encoded as one.
    pub fn api_url(&self, parts: &[&str]) -> Url {
        let mut url = self.api.clone();
        url.path_segments_mut()
            .expect("an http URL has a path")
            .pop_if_empty()
            .extend(parts);
        url
    }

    /// GitHub: `repos/{owner}/{repo}/releases/tags/{tag}`.
    pub fn github_release(&self, tag: &str) -> Url {
        self.api_url(&[
            "repos",
            &self.path[0],
            &self.path[1],
            "releases",
            "tags",
            tag,
        ])
    }

    /// GitHub: `repos/{owner}/{repo}/releases/assets/{id}`.
    pub fn github_asset(&self, id: u64) -> Url {
        self.api_url(&[
            "repos",
            &self.path[0],
            &self.path[1],
            "releases",
            "assets",
            &id.to_string(),
        ])
    }

    /// GitLab: `projects/{group%2Fproject}/releases/{tag}`. The project's
    /// path is one segment, its slashes encoded, as GitLab's API takes it.
    pub fn gitlab_release(&self, tag: &str) -> Url {
        self.api_url(&["projects", &self.path.join("/"), "releases", tag])
    }

    /// The host as `"forges"` keys it, for messages.
    pub fn host(&self) -> String {
        self.forge.host.display()
    }

    /// The token's variables, in words.
    pub fn token_names(&self) -> String {
        self.forge.token_names()
    }
}

/// A token, the header it travels in, and the only origins it may reach.
#[derive(Clone)]
pub struct Credential {
    /// The variable it was read from, for messages. Never the value.
    pub variable: String,
    pub header: &'static str,
    value: String,
    origins: Vec<Origin>,
}

impl std::fmt::Debug for Credential {
    // Not derived: a token printed in a panic message is a token in a CI log.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Credential")
            .field("variable", &self.variable)
            .field("header", &self.header)
            .finish_non_exhaustive()
    }
}

impl Credential {
    /// Whether a request to `url` may carry this: one of its own origins
    /// exactly, and no user name or password in the URL.
    pub fn covers(&self, url: &Url) -> bool {
        no_userinfo(url) && self.origins.contains(&url.origin())
    }

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

/// The environment the tokens are read from: the process's, with the
/// corpus's `.env` under it (`dotenv::var`), or in a test a fixed set, so no
/// test has to set a variable another test can see.
#[derive(Debug, Clone, Default)]
pub enum Env {
    #[default]
    Process,
    #[cfg(test)]
    Fixed(HashMap<String, String>),
}

impl Env {
    pub fn get(&self, name: &str) -> Option<String> {
        match self {
            Env::Process => crate::dotenv::var(name),
            #[cfg(test)]
            Env::Fixed(vars) => vars.get(name).cloned(),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// `json` as the value of `"forges"`, read as tw reads it: its shape
    /// on the text first, then the forges.
    fn forges(json: &str) -> Result<Forges, String> {
        check_forges(&serde_json::from_str::<Raw>(json).unwrap())?;
        let value: serde_json::Value = serde_json::from_str(json).unwrap();
        Forges::parse(Some(&value))
    }

    fn env(vars: &[(&str, &str)]) -> Env {
        Env::Fixed(
            vars.iter()
                .map(|(k, v)| (k.to_string(), v.to_string()))
                .collect(),
        )
    }

    fn url(s: &str) -> Url {
        Url::parse(s).unwrap()
    }

    #[test]
    fn github_and_gitlab_need_no_declaring() {
        let forges = Forges::default();
        let github = forges.locate("https://github.com/markdoc-rs/tw").unwrap();
        assert_eq!(github.forge.kind, Kind::GitHub);
        assert_eq!(github.api.as_str(), "https://api.github.com/");
        assert_eq!(github.forge.token_env, ["GITHUB_TOKEN"]);
        let gitlab = forges
            .locate("https://gitlab.com/group/sub/project")
            .unwrap();
        assert_eq!(gitlab.forge.kind, Kind::GitLab);
        assert_eq!(gitlab.api.as_str(), "https://gitlab.com/api/v4");
        assert_eq!(gitlab.forge.token_env, ["GITLAB_TOKEN"]);
        assert_eq!(
            gitlab.gitlab_release("0.1.0").as_str(),
            "https://gitlab.com/api/v4/projects/group%2Fsub%2Fproject/releases/0.1.0"
        );
    }

    #[test]
    fn any_other_host_has_to_be_declared() {
        let err = Forges::default()
            .locate("https://git.example.com/docs/tool")
            .unwrap_err();
        assert!(err.contains("git.example.com"), "{err}");
        assert!(err.contains("\"forges\""), "{err}");
        assert!(err.contains("\"type\""), "{err}");
        // A port that is not the default is part of the host.
        let declared = forges(r#"{"git.example.com": {"type": "forgejo"}}"#).unwrap();
        assert!(declared.locate("https://git.example.com/docs/tool").is_ok());
        let err = declared
            .locate("https://git.example.com:3000/docs/tool")
            .unwrap_err();
        assert!(err.contains("git.example.com:3000"), "{err}");
    }

    #[test]
    fn a_declared_host_gets_its_type_its_tokens_and_its_api() {
        let declared = forges(
            r#"{
                "//": "notes are skipped",
                "git.example.com": {"type": "forgejo", "token_env": ["FORGEJO_TOKEN", "OLD_TOKEN"], "//": "a note"},
                "gitlab.example.com:8443": {"type": "gitlab", "token_env": "SELF_GITLAB_TOKEN"},
                "ghe.example.com": {"type": "github", "api": "https://ghe.example.com/api/v3/"}
            }"#,
        )
        .unwrap();
        let forgejo = declared
            .locate("https://git.example.com/docs/tool")
            .unwrap();
        assert_eq!(forgejo.forge.kind, Kind::Forgejo);
        assert_eq!(forgejo.forge.token_env, ["FORGEJO_TOKEN", "OLD_TOKEN"]);
        let gitlab = declared
            .locate("https://gitlab.example.com:8443/group/project")
            .unwrap();
        // Not declared: where GitLab serves it, on the repository's origin.
        assert_eq!(
            gitlab.api.as_str(),
            "https://gitlab.example.com:8443/api/v4"
        );
        let ghe = declared.locate("https://ghe.example.com/org/tool").unwrap();
        assert_eq!(ghe.api.as_str(), "https://ghe.example.com/api/v3");
        assert!(ghe.forge.token_env.is_empty());
        assert_eq!(
            ghe.github_release("1.2.3").as_str(),
            "https://ghe.example.com/api/v3/repos/org/tool/releases/tags/1.2.3"
        );
    }

    #[test]
    fn an_entry_for_a_built_in_host_overrides_it_field_by_field() {
        let declared =
            forges(r#"{"github.com": {"type": "github", "api": "https://api.github.example/v3"}}"#)
                .unwrap();
        let github = declared.locate("https://github.com/o/r").unwrap();
        assert_eq!(github.api.as_str(), "https://api.github.example/v3");
        // Left out, so kept.
        assert_eq!(github.forge.token_env, ["GITHUB_TOKEN"]);
        let declared =
            forges(r#"{"github.com": {"type": "github", "token_env": "MY_GH"}}"#).unwrap();
        let github = declared.locate("https://github.com/o/r").unwrap();
        assert_eq!(github.forge.token_env, ["MY_GH"]);
        assert_eq!(github.api.as_str(), "https://api.github.com/");
        // gitlab.com is still built in beside it.
        assert!(declared.locate("https://gitlab.com/g/p").is_ok());
    }

    #[test]
    fn a_malformed_declaration_is_an_error_and_names_itself() {
        for (json, says) in [
            (
                r#"{"git.example.com": {"type": "gitea"}}"#,
                "\"type\" is `gitea`",
            ),
            (r#"{"git.example.com": {}}"#, "no \"type\""),
            (
                r#"{"git.example.com": {"type": "forgejo", "token-env": "X"}}"#,
                "forge git.example.com: unknown field \"token-env\"; the fields are",
            ),
            (
                r#"{"git.example.com": {"type": "forgejo", "token_env": 7}}"#,
                "\"token_env\"",
            ),
            (
                r#"{"git.example.com": {"type": "forgejo", "token_env": ["A=B"]}}"#,
                "forge git.example.com: token_env \"A=B\" is not an environment variable name",
            ),
            (
                r#"{"git.example.com": {"type": "forgejo", "token_env": ["OK", "FORGE-TOKEN"]}}"#,
                "forge git.example.com: token_env \"FORGE-TOKEN\" is not an environment variable name",
            ),
            (
                r#"{"git.example.com:3000": {"type": "forgejo", "token_env": "1TOKEN"}}"#,
                "forge git.example.com:3000: token_env \"1TOKEN\" is not an environment variable name",
            ),
            (
                r#"{"git.example.com": {"type": "forgejo", "token_env": "MY.TOKEN"}}"#,
                "token_env \"MY.TOKEN\" is not an environment variable name",
            ),
            (
                r#"{"git.example.com": {"type": "forgejo", "token_env": " TOKEN"}}"#,
                "token_env \" TOKEN\" is not an environment variable name",
            ),
            (
                r#"{"git.example.com": {"type": "forgejo", "token_env": ""}}"#,
                "token_env \"\" is not an environment variable name",
            ),
            (
                r#"{"https://git.example.com": {"type": "forgejo"}}"#,
                "is not a host",
            ),
            (
                r#"{"user@git.example.com": {"type": "forgejo"}}"#,
                "is not a host",
            ),
            (
                r#"{"git.example.com/x": {"type": "forgejo"}}"#,
                "is not a host",
            ),
            (
                r#"{"git.example.com": {"type": "gitlab", "api": "ftp://x"}}"#,
                "not an API's base URL",
            ),
            (
                r#"{"github.com": {"type": "github", "api": "http://api.github.com"}}"#,
                "not an API's base URL",
            ),
            (
                r#"{"GIT.example.com": {"type": "forgejo"}, "git.example.com": {"type": "forgejo"}}"#,
                "declared twice",
            ),
            ("[1]", "not an object"),
        ] {
            let err = forges(json).unwrap_err();
            assert!(err.contains(says), "{json}: {err}");
        }
    }

    #[test]
    fn every_key_of_forges_is_checked_before_any_is_matched() {
        // Each of these went on, or was refused only after a forge had been
        // matched, in one of tw, writer-setup.sh, writer-setup.ps1 and
        // tools.ts; all four refuse each, the first bad key first.
        let real = r#""git.example.com": {"type": "forgejo", "token_env": "FORGEJO_TOKEN"}"#;
        for (json, says) in [
            // A key that is not a plain ASCII host name: `*` passed the URL
            // parser, and so did a name in another script.
            (format!(r#"{{"*": {{"type": "forgejo"}}, {real}}}"#), "`*` is not a host"),
            (format!(r#"{{"b\u00fccher.example": {{"type": "forgejo"}}, {real}}}"#), "is not a host"),
            (format!(r#"{{"forge.example:0": {{"type": "forgejo"}}, {real}}}"#), "is not a host"),
            (format!(r#"{{"forge.example:": {{"type": "forgejo"}}, {real}}}"#), "is not a host"),
            (format!(r#"{{"-forge.example": {{"type": "forgejo"}}, {real}}}"#), "is not a host"),
            // Whatever its value is, before the forge the pins use, or after.
            (format!(r#"{{"": {{}}, {real}}}"#), "`` is not a host"),
            (format!(r#"{{"": null, {real}}}"#), "`` is not a host"),
            (format!(r#"{{"": "x", {real}}}"#), "`` is not a host"),
            (format!(r#"{{"": [], {real}}}"#), "`` is not a host"),
            (format!(r#"{{"a b": {{}}, {real}}}"#), "`a b` is not a host"),
            (format!(r#"{{{real}, "": {{"type": "forgejo", "token_env": "FORGEJO_TOKEN"}}}}"#), "`` is not a host"),
            (format!(r#"{{{real}, "a b": {{"type": "forgejo"}}}}"#), "`a b` is not a host"),
            // A forge that is not an object, and one declared twice, as
            // JSON spells it or as the host compares.
            (format!(r#"{{"forge.example": "forgejo", {real}}}"#), "forge forge.example: not an object"),
            (format!(r#"{{{real}, {real}}}"#), "forge git.example.com: declared twice"),
            (format!(r#"{{{real}, "GIT.EXAMPLE.COM": {{"type": "forgejo"}}}}"#), "forge GIT.EXAMPLE.COM: declared twice"),
            (format!(r#"{{{real}, "git.example.com:443": {{"type": "forgejo"}}}}"#), "forge git.example.com:443: declared twice"),
            // A field: compared as written, case and all, and given once.
            (
                r#"{"git.example.com": {"type": "forgejo", "TOKEN_ENV": "x[$(touch probe)]", "token_env": "FORGEJO_TOKEN"}}"#.to_string(),
                "forge git.example.com: unknown field \"TOKEN_ENV\"; the fields are",
            ),
            (
                r#"{"git.example.com": {"type": "forgejo", "Token_Env": "FORGEJO_TOKEN"}}"#.to_string(),
                "forge git.example.com: unknown field \"Token_Env\"",
            ),
            (
                r#"{"git.example.com": {"type": "forgejo", "token_env": "FORGEJO_TOKEN", "token_env": "BAD-NAME"}}"#.to_string(),
                "forge git.example.com: \"token_env\" is given twice",
            ),
        ] {
            let err = forges(&json).unwrap_err();
            assert!(err.contains(says), "{json}: {err}");
        }
        // A key written with an escape is the key it spells.
        let escaped = forges(
            r#"{"git.example.com": {"type": "forgejo", "\u0074oken_env": "x[$(touch probe)]"}}"#,
        );
        assert!(
            escaped
                .unwrap_err()
                .contains("token_env \"x[$(touch probe)]\" is not an environment variable name")
        );
        // Notes, capitals and a written port are still keys a forge can have.
        let fine = forges(
            r#"{"//": "a note", "//x": {"any": "thing"}, "Forge.Example:8443": {"type": "forgejo", "//": "note"}, "k": {"type": "github"}}"#,
        )
        .unwrap();
        assert!(
            fine.serving(&url("https://forge.example:8443/o/r"))
                .is_some()
        );
    }

    #[test]
    fn a_token_env_name_is_one_a_shell_can_set() {
        for good in ["T", "_T", "FORGEJO_TOKEN", "t0k3n_2"] {
            assert!(is_variable_name(good), "{good}");
        }
        for bad in ["", "1T", "A-B", "A.B", "A B", "A=B", "T\u{e9}", "A\0"] {
            assert!(!is_variable_name(bad), "{bad:?}");
        }
    }

    #[test]
    fn a_repository_url_is_refused_unless_it_is_plainly_one() {
        let forges = Forges::default();
        for (repo, says) in [
            ("https://user:pw@github.com/o/r", "user name or password"),
            ("https://tok@github.com/o/r", "user name or password"),
            ("ftp://github.com/o/r", "not an https:// URL"),
            // A self-hosted Forgejo, and github.com, at http: refused before
            // a token is read, let alone sent in clear.
            ("http://git.example.com/docs/tool", "not an https:// URL"),
            ("http://github.com/o/r", "not an https:// URL"),
            ("HTTP://github.com/o/r", "not an https:// URL"),
            ("https://github.com/o/r?x=1", "not a repository's URL"),
            ("https://github.com/o", "<owner>/<repository>"),
            ("https://github.com/o/r/extra", "<owner>/<repository>"),
            ("not a url", "not a URL"),
        ] {
            let err = forges.locate(repo).unwrap_err();
            assert!(err.contains(says), "{repo}: {err}");
        }
        // A trailing slash is not part of the repository.
        let located = forges.locate("https://github.com/o/r/").unwrap();
        assert_eq!(
            located.download_url("0.1.0", "a").as_str(),
            "https://github.com/o/r/releases/download/0.1.0/a"
        );
    }

    #[test]
    fn the_token_is_the_first_variable_that_holds_one() {
        let declared =
            forges(r#"{"git.example.com": {"type": "forgejo", "token_env": ["FIRST", "SECOND"]}}"#)
                .unwrap();
        let located = declared.locate("https://git.example.com/o/r").unwrap();
        let pick = |vars: &[(&str, &str)]| {
            located
                .credential(&env(vars))
                .map(|c| c.map(|c| (c.variable.clone(), c.value().to_string())))
        };
        let got = |name: &str, value: &str| Ok(Some((name.to_string(), value.to_string())));
        // Unset, empty, or blank after trimming: unset, and the next is tried.
        assert_eq!(pick(&[]), Ok(None));
        assert_eq!(pick(&[("FIRST", "  ")]), Ok(None));
        assert_eq!(
            pick(&[("FIRST", ""), ("SECOND", "s2")]),
            got("SECOND", "token s2")
        );
        assert_eq!(
            pick(&[("FIRST", "   "), ("SECOND", "s2")]),
            got("SECOND", "token s2")
        );
        assert_eq!(
            pick(&[("FIRST", "\t\r\n"), ("SECOND", "s2")]),
            got("SECOND", "token s2")
        );
        // Spaces, tabs, CR and LF at the ends are dropped.
        assert_eq!(
            pick(&[("FIRST", " f1\n"), ("SECOND", "s2")]),
            got("FIRST", "token f1")
        );
        assert_eq!(
            pick(&[("FIRST", "f1\r"), ("SECOND", "s2")]),
            got("FIRST", "token f1")
        );
        assert_eq!(pick(&[("FIRST", "\tf1\r\n")]), got("FIRST", "token f1"));
        // A control character inside: refused, naming the variable only,
        // and the next variable is not tried in its place.
        for bad in ["f\r1", "f\x001", "f\x1b1", "f1\x7f", "f\n1"] {
            let err = pick(&[("FIRST", bad), ("SECOND", "s2")]).unwrap_err();
            assert!(err.contains("FIRST holds a control character"), "{err}");
            assert!(!err.contains(bad), "{err}");
        }
        // And Debug never prints it.
        let c = located
            .credential(&env(&[("FIRST", "f1")]))
            .unwrap()
            .unwrap();
        assert!(!format!("{c:?}").contains("f1"));
    }

    #[test]
    fn each_forge_writes_its_own_header() {
        let declared = forges(
            r#"{"git.example.com": {"type": "forgejo", "token_env": "T"},
                "gitlab.example.com": {"type": "gitlab", "token_env": "T"},
                "ghe.example.com": {"type": "github", "token_env": "T"}}"#,
        )
        .unwrap();
        let header = |repo: &str| {
            let c = declared
                .locate(repo)
                .unwrap()
                .credential(&env(&[("T", "abc")]))
                .unwrap()
                .unwrap();
            (c.header, c.value().to_string())
        };
        assert_eq!(
            header("https://git.example.com/o/r"),
            ("Authorization", "token abc".to_string())
        );
        assert_eq!(
            header("https://gitlab.example.com/g/p"),
            ("PRIVATE-TOKEN", "abc".to_string())
        );
        assert_eq!(
            header("https://ghe.example.com/o/r"),
            ("Authorization", "Bearer abc".to_string())
        );
    }

    #[test]
    fn a_token_reaches_its_own_origins_and_no_other() {
        let declared =
            forges(r#"{"git.example.com:3000": {"type": "forgejo", "token_env": "T"}}"#).unwrap();
        let c = declared
            .locate("https://git.example.com:3000/o/r")
            .unwrap()
            .credential(&env(&[("T", "abc")]))
            .unwrap()
            .unwrap();
        // Its own origin, whatever the case of the host or the path.
        assert!(c.covers(&url(
            "https://git.example.com:3000/o/r/releases/download/1/a"
        )));
        assert!(c.covers(&url("https://GIT.Example.COM:3000/attachments/x")));
        // Another port, another scheme, or the default port: another origin.
        assert!(!c.covers(&url("https://git.example.com/o/r")));
        assert!(!c.covers(&url("https://git.example.com:3001/o/r")));
        assert!(!c.covers(&url("http://git.example.com:3000/o/r")));
        // Look-alikes.
        for other in [
            "https://git.example.com.attacker.example:3000/o/r",
            "https://xgit.example.com:3000/o/r",
            "https://example.com:3000/git.example.com/o/r",
            "https://attacker.example:3000/?git.example.com:3000",
            "https://example.com:3000/o/r",
        ] {
            assert!(!c.covers(&url(other)), "{other}");
        }
        // A user name or password, on the real host or in front of another.
        assert!(!c.covers(&url("https://user@git.example.com:3000/o/r")));
        assert!(!c.covers(&url("https://git.example.com:3000@attacker.example/o/r")));
        assert!(!c.covers(&url(
            "https://git.example.com:3000:pw@attacker.example:3000/o/r"
        )));
        // A Unicode look-alike is its own (punycode) host. The full-width dot
        // is not a trick: IDNA reads it as a dot, and so does the request.
        assert!(!c.covers(&url("https://gіt.example.com:3000/o/r")));
        assert!(c.covers(&url("https://git\u{ff0e}example.com:3000/o/r")));
    }

    #[test]
    fn github_s_token_reaches_the_api_and_not_the_asset_storage() {
        let c = Forges::default()
            .locate("https://github.com/o/r")
            .unwrap()
            .credential(&env(&[("GITHUB_TOKEN", "ghp")]))
            .unwrap()
            .unwrap();
        assert_eq!(c.value(), "Bearer ghp");
        assert!(c.covers(&url("https://api.github.com/repos/o/r/releases/tags/1")));
        assert!(c.covers(&url("https://github.com/o/r/releases/download/1/a")));
        for other in [
            "https://objects.githubusercontent.com/github-production-release-asset/x",
            "https://release-assets.githubusercontent.com/x",
            "https://codeload.github.com/o/r",
            "http://api.github.com/repos/o/r",
            "https://api.github.com.attacker.example/repos/o/r",
            "https://gitlab.com/o/r",
        ] {
            assert!(!c.covers(&url(other)), "{other}");
        }
        // GITLAB_TOKEN is gitlab.com's, so it never reaches GitHub either.
        let gitlab = Forges::default()
            .locate("https://gitlab.com/g/p")
            .unwrap()
            .credential(&env(&[("GITLAB_TOKEN", "glpat")]))
            .unwrap()
            .unwrap();
        assert!(!gitlab.covers(&url("https://github.com/o/r")));
        assert!(gitlab.covers(&url("https://gitlab.com/api/v4/projects/g%2Fp/releases/1")));
    }

    #[test]
    fn a_host_key_matches_by_name_after_parsing_and_by_port() {
        let host = Host::parse("Forge.Example.com").unwrap();
        assert!(host.serves(&url("https://forge.example.com/o/r")));
        assert!(host.serves(&url("http://FORGE.example.com/o/r")));
        assert!(host.serves(&url("https://forge.example.com:443/o/r")));
        assert!(!host.serves(&url("https://forge.example.com:8443/o/r")));
        assert!(!host.serves(&url("https://u@forge.example.com/o/r")));
        let host = Host::parse("forge.example.com:443").unwrap();
        assert!(host.serves(&url("https://forge.example.com/o/r")));
        assert!(!host.serves(&url("http://forge.example.com/o/r")));
        // A key is a plain ASCII host name, as the corpus's own readers take
        // it: a name in another script is written as its punycode, which
        // serves the URL that spells it either way. No address literal.
        assert!(Host::parse("bücher.example").is_err());
        let host = Host::parse("xn--bcher-kva.example").unwrap();
        assert!(host.serves(&url("https://xn--bcher-kva.example/o/r")));
        assert!(host.serves(&url("https://bücher.example/o/r")));
        assert!(Host::parse("[::1]:8080").is_err());
    }
}