crates/oxy-core/src/credentials.rs at 028545dfa7a4 · andymccall/oxygen

# 028545dfa7a4 oxygen / crates / oxy-core / src / credentials.rs

22.7 KiB · Rust · last changed Agents sign keyless: author.signer = keyless (keyless step 5c) 18 days ago source blame history raw

//! Per-user credentials for hubs: one sign-in serves every repository on a
//! hub, and nothing secret is written into a checkout.
//!
//! The store is `credentials.toml` in the user's oxy directory (see
//! [`crate::repo::default_home`]), one section per hub:
//!
//! ```text
//! [https://oxygenhub.io]
//! account = "andymccall"
//! token = "oxyhub_…"
//! ```
//!
//! A hub is a scheme, host and port: a token is only ever sent to the hub
//! it was stored for. The file is written readable by its owner only, and
//! is ignored with a warning when anyone else can read it. With
//! `auth.helper` set in the user's `config.toml`, tokens go to that helper
//! instead (Git's credential-helper protocol, so `libsecret`,
//! `osxkeychain` and `manager` keep them in the system keyring) and the
//! file keeps only what is not secret.
//!
//! A token is sent over `https`, or over plain `http` to this machine only
//! ([`token_allowed`]); hub transports drop it on any redirect.

use crate::protocol::RemoteOptions;
use std::collections::{BTreeMap, HashMap};
use std::io::Write;
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use std::sync::{Mutex, OnceLock};

/// The user name oxy's tokens are stored under in a credential helper, so
/// they stay apart from Git credentials for the same host.
const HELPER_USER: &str = "oxy-token";

/// The hub of a URL: `scheme://host[:port]`, lower case, for `http` and
/// `https` URLs only.
pub fn hub_of(url: &str) -> Option<String> {
    let (scheme, rest) = url.split_once("://")?;
    let scheme = scheme.to_ascii_lowercase();
    if scheme != "http" && scheme != "https" {
        return None;
    }
    let host = rest.split(['/', '?', '#']).next()?;
    // Never key a hub on credentials embedded in the URL.
    let host = host.rsplit('@').next()?;
    if host.is_empty() {
        return None;
    }
    Some(format!("{scheme}://{}", host.to_ascii_lowercase()))
}

/// Whether a token may be sent to `url`: always over `https`, and over
/// plain `http` only to this machine (a hub under test, or a runner's own).
pub fn token_allowed(url: &str) -> bool {
    let Some(hub) = hub_of(url) else {
        return true;
    };
    match hub.split_once("://") {
        Some(("https", _)) => true,
        Some((_, host)) => {
            let name = match host.strip_prefix('[') {
                Some(v6) => v6.split(']').next().unwrap_or(""),
                None => host.rsplit_once(':').map_or(host, |(h, _)| h),
            };
            name == "localhost"
                || name == "::1"
                || name
                    .parse::<std::net::Ipv4Addr>()
                    .is_ok_and(|a| a.is_loopback())
        }
        None => false,
    }
}

/// What the store holds for one hub.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct HubEntry {
    /// `scheme://host[:port]`.
    pub hub: String,
    /// The account the token signs in as, recorded at sign-in.
    pub account: Option<String>,
    /// The token, when it is in the file (not with a helper).
    pub token: Option<String>,
    /// Extra roots to trust for this hub (a self-signed hub).
    pub ca: Option<PathBuf>,
    /// An agent's grant token for keyless signing (oxygenhub#241), when it
    /// is in the file (not with a helper).
    pub grant: Option<String>,
}

/// Where a saved token went.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Stored {
    /// The credentials file, owner-only.
    File(PathBuf),
    /// A credential helper, by its `auth.helper` value.
    Helper(String),
}

/// The credential store of one oxy home directory.
#[derive(Clone, Debug)]
pub struct Credentials {
    home: PathBuf,
}

impl Credentials {
    /// The store in `home` (an oxy home directory).
    pub fn at(home: impl Into<PathBuf>) -> Credentials {
        Credentials { home: home.into() }
    }

    /// The store in the user's oxy home directory.
    pub fn user() -> Credentials {
        Credentials::at(crate::repo::default_home())
    }

    /// `credentials.toml` in the home directory.
    pub fn path(&self) -> PathBuf {
        self.home.join("credentials.toml")
    }

    /// The configured credential helper (`auth.helper` in the user file).
    pub fn helper(&self) -> Option<String> {
        crate::repo::read_config_file(&self.home.join("config.toml"))
            .ok()?
            .remove("auth.helper")
            .filter(|h| !h.trim().is_empty())
    }

    /// Every hub in the file, tokens as stored there (none with a helper).
    pub fn entries(&self) -> Result<Vec<HubEntry>, String> {
        Ok(self.read()?.into_values().collect())
    }

    /// Whether the file can be read by anyone but its owner, in which case
    /// lookups ignore it.
    pub fn too_open(&self) -> bool {
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            if let Ok(m) = std::fs::metadata(self.path()) {
                return m.permissions().mode() & 0o077 != 0;
            }
        }
        false
    }

    /// The entry for `hub`, its token fetched from the helper if one is set.
    pub fn get(&self, hub: &str) -> Result<Option<HubEntry>, String> {
        let entry = self.read()?.remove(hub);
        let helper = self.helper();
        let mut entry = match (entry, &helper) {
            (Some(e), _) => e,
            // A helper may hold a token stored before the file was cleared.
            (None, Some(_)) => HubEntry {
                hub: hub.to_string(),
                ..HubEntry::default()
            },
            (None, None) => return Ok(None),
        };
        if entry.token.is_none() {
            if let Some(h) = &helper {
                entry.token = run_helper(h, "get", hub, None)?;
            }
        }
        if entry.token.is_none()
            && entry.account.is_none()
            && entry.ca.is_none()
            && entry.grant.is_none()
        {
            return Ok(None);
        }
        Ok(Some(entry))
    }

    /// Save a token (and what is known about it) for `hub`.
    pub fn save(
        &self,
        hub: &str,
        token: &str,
        account: Option<&str>,
        ca: Option<&Path>,
    ) -> Result<Stored, String> {
        let mut all = self.read()?;
        let helper = self.helper();
        let entry = all.entry(hub.to_string()).or_insert_with(|| HubEntry {
            hub: hub.to_string(),
            ..HubEntry::default()
        });
        entry.account = account.map(String::from).or(entry.account.take());
        if let Some(ca) = ca {
            entry.ca = Some(ca.to_path_buf());
        }
        let stored = match &helper {
            Some(h) => {
                run_helper(h, "store", hub, Some(token))?;
                entry.token = None;
                Stored::Helper(h.clone())
            }
            None => {
                entry.token = Some(token.to_string());
                Stored::File(self.path())
            }
        };
        self.write(&all)?;
        forget_cached();
        Ok(stored)
    }

    /// Save an agent's grant token for `hub` (keyless signing, spec §14.7):
    /// in the file, or the helper under its own user name.
    pub fn save_grant(&self, hub: &str, token: &str) -> Result<Stored, String> {
        let mut all = self.read()?;
        let entry = all.entry(hub.to_string()).or_insert_with(|| HubEntry {
            hub: hub.to_string(),
            ..HubEntry::default()
        });
        let stored = match self.helper() {
            Some(h) => {
                run_helper_as(&h, "store", hub, GRANT_USER, Some(token))?;
                entry.grant = None;
                Stored::Helper(h)
            }
            None => {
                entry.grant = Some(token.to_string());
                Stored::File(self.path())
            }
        };
        self.write(&all)?;
        Ok(stored)
    }

    /// The agent grant token kept for `hub`, if any.
    pub fn grant(&self, hub: &str) -> Result<Option<String>, String> {
        if let Some(g) = self.read()?.get(hub).and_then(|e| e.grant.clone()) {
            return Ok(Some(g));
        }
        match self.helper() {
            Some(h) => run_helper_as(&h, "get", hub, GRANT_USER, None),
            None => Ok(None),
        }
    }

    /// Remove `hub` from the file and the helper; returns what it held,
    /// with the token, so the caller can revoke it.
    pub fn remove(&self, hub: &str) -> Result<Option<HubEntry>, String> {
        let found = self.get(hub)?;
        let mut all = self.read()?;
        if all.remove(hub).is_some() {
            self.write(&all)?;
        }
        if let Some(h) = self.helper() {
            run_helper(&h, "erase", hub, None)?;
        }
        forget_cached();
        Ok(found)
    }

    fn read(&self) -> Result<BTreeMap<String, HubEntry>, String> {
        let path = self.path();
        let text = match std::fs::read_to_string(&path) {
            Ok(t) => t,
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(BTreeMap::new()),
            Err(e) => return Err(format!("reading {}: {e}", path.display())),
        };
        let mut out = BTreeMap::new();
        let mut current: Option<HubEntry> = None;
        for (n, line) in text.lines().enumerate() {
            let line = line.trim();
            if line.is_empty() || line.starts_with('#') {
                continue;
            }
            if let Some(hub) = line.strip_prefix('[').and_then(|l| l.strip_suffix(']')) {
                if let Some(e) = current.take() {
                    out.insert(e.hub.clone(), e);
                }
                current = Some(HubEntry {
                    hub: hub.trim().to_string(),
                    ..HubEntry::default()
                });
                continue;
            }
            let bad = || {
                format!(
                    "{} line {}: expected key = \"value\"",
                    path.display(),
                    n + 1
                )
            };
            let (k, v) = line.split_once('=').ok_or_else(bad)?;
            let v = unquote(v.trim()).ok_or_else(bad)?;
            let Some(e) = current.as_mut() else {
                return Err(format!(
                    "{} line {}: a key before any [hub] section",
                    path.display(),
                    n + 1
                ));
            };
            match k.trim() {
                "account" => e.account = Some(v),
                "token" => e.token = Some(v),
                "ca" => e.ca = Some(PathBuf::from(v)),
                "grant" => e.grant = Some(v),
                // Unknown keys are kept out of lookups, not fatal.
                _ => {}
            }
        }
        if let Some(e) = current {
            out.insert(e.hub.clone(), e);
        }
        Ok(out)
    }

    fn write(&self, all: &BTreeMap<String, HubEntry>) -> Result<(), String> {
        let mut text =
            String::from("# oxy credentials: a token for each hub. Keep this file private.\n");
        for e in all.values() {
            text.push_str(&format!("\n[{}]\n", e.hub));
            if let Some(a) = &e.account {
                text.push_str(&format!("account = {}\n", quote(a)));
            }
            if let Some(t) = &e.token {
                text.push_str(&format!("token = {}\n", quote(t)));
            }
            if let Some(c) = &e.ca {
                text.push_str(&format!("ca = {}\n", quote(&c.to_string_lossy())));
            }
            if let Some(g) = &e.grant {
                text.push_str(&format!("grant = {}\n", quote(g)));
            }
        }
        let path = self.path();
        std::fs::create_dir_all(&self.home)
            .map_err(|e| format!("creating {}: {e}", self.home.display()))?;
        crate::durable::write_atomic_private(&path, text.as_bytes())
            .map_err(|e| format!("writing {}: {e}", path.display()))
    }

    /// The stored token and CA for `url`'s hub, if any: memoized, so a
    /// helper runs once per hub in a process. A file anyone else can read
    /// is ignored, with a warning.
    pub fn lookup(&self, url: &str) -> (Option<String>, Option<PathBuf>) {
        let Some(hub) = hub_of(url) else {
            return (None, None);
        };
        let key = (self.home.clone(), hub.clone());
        if let Some(hit) = cache().lock().unwrap().get(&key) {
            return hit.clone();
        }
        let found = if self.too_open() {
            warn_once(&format!(
                "warning: {} can be read by other users, so oxy ignores it; run chmod 600 on it",
                self.path().display()
            ));
            (None, None)
        } else {
            match self.get(&hub) {
                Ok(Some(e)) => (e.token, e.ca),
                Ok(None) => (None, None),
                Err(e) => {
                    warn_once(&format!("warning: credentials for {hub}: {e}"));
                    (None, None)
                }
            }
        };
        cache().lock().unwrap().insert(key, found.clone());
        found
    }

    /// Options for reaching `url` without a configured remote: `$OXY_TOKEN`
    /// and `$OXY_CA`, else what this store holds for its hub.
    pub fn options_for(&self, url: &str) -> RemoteOptions {
        let env_token = std::env::var("OXY_TOKEN").ok().filter(|t| !t.is_empty());
        let env_ca = std::env::var("OXY_CA").ok().map(PathBuf::from);
        let (token, ca) = match (&env_token, &env_ca) {
            (Some(_), Some(_)) => (None, None),
            _ => self.lookup(url),
        };
        RemoteOptions {
            token: env_token.or(token),
            ca: env_ca.or(ca),
            ..RemoteOptions::default()
        }
    }
}

type Cache = Mutex<HashMap<(PathBuf, String), (Option<String>, Option<PathBuf>)>>;

fn cache() -> &'static Cache {
    static CACHE: OnceLock<Cache> = OnceLock::new();
    CACHE.get_or_init(Default::default)
}

fn forget_cached() {
    cache().lock().unwrap().clear();
}

pub(crate) fn warn_once(message: &str) {
    static SEEN: OnceLock<Mutex<std::collections::HashSet<String>>> = OnceLock::new();
    if SEEN
        .get_or_init(Default::default)
        .lock()
        .unwrap()
        .insert(message.to_string())
    {
        eprintln!("{message}");
    }
}

fn quote(v: &str) -> String {
    let mut out = String::from('"');
    for c in v.chars() {
        match c {
            '"' => out.push_str("\\\""),
            '\\' => out.push_str("\\\\"),
            '\n' => out.push_str("\\n"),
            c => out.push(c),
        }
    }
    out.push('"');
    out
}

fn unquote(v: &str) -> Option<String> {
    let inner = v.strip_prefix('"')?.strip_suffix('"')?;
    let mut out = String::new();
    let mut chars = inner.chars();
    while let Some(c) = chars.next() {
        if c == '\\' {
            match chars.next()? {
                'n' => out.push('\n'),
                c => out.push(c),
            }
        } else {
            out.push(c);
        }
    }
    Some(out)
}

/// Run a credential helper (Git's protocol): `get`, `store` or `erase` for
/// `hub`. `get` returns the password the helper answered with.
///
/// `auth.helper` is a helper name (run as `git credential-NAME`), an
/// absolute path, or a shell command after `!`, as in Git.
fn run_helper(
    helper: &str,
    action: &str,
    hub: &str,
    token: Option<&str>,
) -> Result<Option<String>, String> {
    run_helper_as(helper, action, hub, HELPER_USER, token)
}

/// The helper's user name for an agent's grant token, beside the hub's
/// own token.
const GRANT_USER: &str = "oxy-agent-grant";

fn run_helper_as(
    helper: &str,
    action: &str,
    hub: &str,
    user: &str,
    token: Option<&str>,
) -> Result<Option<String>, String> {
    let (protocol, host) = hub
        .split_once("://")
        .ok_or_else(|| format!("{hub} is not a hub URL"))?;
    let mut cmd = if let Some(shell) = helper.strip_prefix('!') {
        let mut c = Command::new("sh");
        c.arg("-c").arg(format!("{shell} {action}"));
        c
    } else if Path::new(helper).is_absolute() {
        let mut c = Command::new(helper);
        c.arg(action);
        c
    } else {
        let mut c = Command::new("git");
        c.arg(format!("credential-{helper}")).arg(action);
        c
    };
    let mut input = format!("protocol={protocol}\nhost={host}\nusername={user}\n");
    if let Some(t) = token {
        input.push_str(&format!("password={t}\n"));
    }
    input.push('\n');
    let mut child = cmd
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .stderr(Stdio::inherit())
        .spawn()
        .map_err(|e| format!("running credential helper {helper:?}: {e}"))?;
    child
        .stdin
        .take()
        .expect("piped")
        .write_all(input.as_bytes())
        .map_err(|e| format!("credential helper {helper:?}: {e}"))?;
    let out = child
        .wait_with_output()
        .map_err(|e| format!("credential helper {helper:?}: {e}"))?;
    if !out.status.success() {
        return Err(format!("credential helper {helper:?} {action} failed"));
    }
    if action != "get" {
        return Ok(None);
    }
    Ok(String::from_utf8_lossy(&out.stdout)
        .lines()
        .find_map(|l| l.strip_prefix("password="))
        .map(String::from)
        .filter(|p| !p.is_empty()))
}

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

    /// oxygenhub#241: an agent's grant token is kept beside the hub's own
    /// token, owner-only, and read back without disturbing it.
    #[test]
    fn a_grant_token_is_kept_beside_the_hub_token() {
        let dir = tempfile::tempdir().unwrap();
        let store = Credentials::at(dir.path());
        let hub = "https://oxygenhub.io";
        assert_eq!(store.grant(hub).unwrap(), None);
        store.save(hub, "oxyhub_t", Some("andy"), None).unwrap();
        store.save_grant(hub, "oxyagent_g").unwrap();
        assert_eq!(store.grant(hub).unwrap().as_deref(), Some("oxyagent_g"));
        let e = store.get(hub).unwrap().unwrap();
        assert_eq!(e.token.as_deref(), Some("oxyhub_t"));
        assert_eq!(e.account.as_deref(), Some("andy"));
        // A grant alone is an entry too.
        store
            .save_grant("https://elsewhere.example", "oxyagent_h")
            .unwrap();
        assert!(store.get("https://elsewhere.example").unwrap().is_some());
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mode = std::fs::metadata(store.path())
                .unwrap()
                .permissions()
                .mode();
            assert_eq!(mode & 0o077, 0, "owner only");
        }
    }

    #[test]
    fn hubs_are_scheme_host_and_port() {
        assert_eq!(
            hub_of("https://OxygenHub.io/doomsdayone/metalgear").as_deref(),
            Some("https://oxygenhub.io")
        );
        assert_eq!(
            hub_of("http://127.0.0.1:7300/a/b").as_deref(),
            Some("http://127.0.0.1:7300")
        );
        assert_eq!(
            hub_of("https://user:[email protected]/x").as_deref(),
            Some("https://hub.example")
        );
        assert_eq!(hub_of("/srv/repo"), None);
        assert_eq!(hub_of("file:///srv/repo"), None);
    }

    #[test]
    fn tokens_go_over_https_or_to_this_machine() {
        assert!(token_allowed("https://oxygenhub.io/a/b"));
        assert!(token_allowed("http://127.0.0.1:7300/a/b"));
        assert!(token_allowed("http://localhost/a"));
        assert!(token_allowed("http://[::1]:8080/a"));
        assert!(!token_allowed("http://oxygenhub.io/a/b"));
        assert!(!token_allowed("http://10.0.0.1/a"));
        assert!(!token_allowed("http://127.0.0.1.evil.example/a"));
    }

    #[test]
    fn save_get_and_remove_round_trip_privately() {
        let dir = tempfile::tempdir().unwrap();
        let store = Credentials::at(dir.path());
        assert_eq!(store.get("https://hub.example").unwrap(), None);
        let stored = store
            .save("https://hub.example", "tok\"en", Some("andy"), None)
            .unwrap();
        assert_eq!(stored, Stored::File(store.path()));
        store
            .save(
                "http://127.0.0.1:7300",
                "local",
                None,
                Some(Path::new("/ca.pem")),
            )
            .unwrap();
        let e = store.get("https://hub.example").unwrap().unwrap();
        assert_eq!(e.token.as_deref(), Some("tok\"en"));
        assert_eq!(e.account.as_deref(), Some("andy"));
        assert!(!store.too_open());
        assert_eq!(
            store.lookup("https://hub.example/o/r"),
            (Some("tok\"en".into()), None)
        );
        // Another host, scheme or port gets nothing.
        assert_eq!(store.lookup("https://other.example/o/r"), (None, None));
        assert_eq!(store.lookup("http://hub.example/o/r"), (None, None));
        assert_eq!(store.lookup("https://hub.example:8443/o/r"), (None, None));
        let gone = store.remove("https://hub.example").unwrap().unwrap();
        assert_eq!(gone.token.as_deref(), Some("tok\"en"));
        assert_eq!(store.lookup("https://hub.example/o/r"), (None, None));
        assert_eq!(store.entries().unwrap().len(), 1);
    }

    #[cfg(unix)]
    #[test]
    fn a_file_others_can_read_is_ignored() {
        use std::os::unix::fs::PermissionsExt;
        let dir = tempfile::tempdir().unwrap();
        let store = Credentials::at(dir.path());
        store.save("https://open.example", "t", None, None).unwrap();
        let mode = std::fs::metadata(store.path())
            .unwrap()
            .permissions()
            .mode();
        assert_eq!(mode & 0o777, 0o600);
        std::fs::set_permissions(store.path(), std::fs::Permissions::from_mode(0o644)).unwrap();
        assert!(store.too_open());
        assert_eq!(store.lookup("https://open.example/o/r"), (None, None));
    }

    #[cfg(unix)]
    #[test]
    fn a_helper_keeps_the_token_out_of_the_file() {
        let dir = tempfile::tempdir().unwrap();
        let vault = dir.path().join("vault");
        // A helper that keeps one password in a file, as a keyring would.
        let helper = format!(
            "!f() {{ case $1 in get) [ -f {v} ] && echo password=$(cat {v});; store) sed -n 's/^password=//p' > {v};; erase) rm -f {v};; esac; }}; f",
            v = vault.display()
        );
        std::fs::write(
            dir.path().join("config.toml"),
            format!("auth.helper = \"{helper}\"\n"),
        )
        .unwrap();
        let store = Credentials::at(dir.path());
        assert!(store.helper().is_some());
        let stored = store
            .save("https://hub.example", "secret", Some("andy"), None)
            .unwrap();
        assert!(matches!(stored, Stored::Helper(_)));
        let text = std::fs::read_to_string(store.path()).unwrap();
        assert!(!text.contains("secret"), "{text}");
        assert_eq!(
            store
                .get("https://hub.example")
                .unwrap()
                .unwrap()
                .token
                .as_deref(),
            Some("secret")
        );
        store.remove("https://hub.example").unwrap();
        assert!(!vault.exists());
    }
}

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

1	//! Per-user credentials for hubs: one sign-in serves every repository on a
2	//! hub, and nothing secret is written into a checkout.
3	//!
4	//! The store is `credentials.toml` in the user's oxy directory (see
5	//! [`crate::repo::default_home`]), one section per hub:
6	//!
7	//! ```text
8	//! [https://oxygenhub.io]
9	//! account = "andymccall"
10	//! token = "oxyhub_…"
11	//! ```
12	//!
13	//! A hub is a scheme, host and port: a token is only ever sent to the hub
14	//! it was stored for. The file is written readable by its owner only, and
15	//! is ignored with a warning when anyone else can read it. With
16	//! `auth.helper` set in the user's `config.toml`, tokens go to that helper
17	//! instead (Git's credential-helper protocol, so `libsecret`,
18	//! `osxkeychain` and `manager` keep them in the system keyring) and the
19	//! file keeps only what is not secret.
20	//!
21	//! A token is sent over `https`, or over plain `http` to this machine only
22	//! ([`token_allowed`]); hub transports drop it on any redirect.
23
24	use crate::protocol::RemoteOptions;
25	use std::collections::{BTreeMap, HashMap};
26	use std::io::Write;
27	use std::path::{Path, PathBuf};
28	use std::process::{Command, Stdio};
29	use std::sync::{Mutex, OnceLock};
30
31	/// The user name oxy's tokens are stored under in a credential helper, so
32	/// they stay apart from Git credentials for the same host.
33	const HELPER_USER: &str = "oxy-token";
34
35	/// The hub of a URL: `scheme://host[:port]`, lower case, for `http` and
36	/// `https` URLs only.
37	pub fn hub_of(url: &str) -> Option<String> {
38	let (scheme, rest) = url.split_once("://")?;
39	let scheme = scheme.to_ascii_lowercase();
40	if scheme != "http" && scheme != "https" {
41	return None;
42	}
43	let host = rest.split(['/', '?', '#']).next()?;
44	// Never key a hub on credentials embedded in the URL.
45	let host = host.rsplit('@').next()?;
46	if host.is_empty() {
47	return None;
48	}
49	Some(format!("{scheme}://{}", host.to_ascii_lowercase()))
50	}
51
52	/// Whether a token may be sent to `url`: always over `https`, and over
53	/// plain `http` only to this machine (a hub under test, or a runner's own).
54	pub fn token_allowed(url: &str) -> bool {
55	let Some(hub) = hub_of(url) else {
56	return true;
57	};
58	match hub.split_once("://") {
59	Some(("https", _)) => true,
60	Some((_, host)) => {
61	let name = match host.strip_prefix('[') {
62	Some(v6) => v6.split(']').next().unwrap_or(""),
63	None => host.rsplit_once(':').map_or(host, \|(h, _)\| h),
64	};
65	name == "localhost"
66	\|\| name == "::1"
67	\|\| name
68	.parse::<std::net::Ipv4Addr>()
69	.is_ok_and(\|a\| a.is_loopback())
70	}
71	None => false,
72	}
73	}
74
75	/// What the store holds for one hub.
76	#[derive(Clone, Debug, Default, PartialEq, Eq)]
77	pub struct HubEntry {
78	/// `scheme://host[:port]`.
79	pub hub: String,
80	/// The account the token signs in as, recorded at sign-in.
81	pub account: Option<String>,
82	/// The token, when it is in the file (not with a helper).
83	pub token: Option<String>,
84	/// Extra roots to trust for this hub (a self-signed hub).
85	pub ca: Option<PathBuf>,
86	/// An agent's grant token for keyless signing (oxygenhub#241), when it
87	/// is in the file (not with a helper).
88	pub grant: Option<String>,
89	}
90
91	/// Where a saved token went.
92	#[derive(Clone, Debug, PartialEq, Eq)]
93	pub enum Stored {
94	/// The credentials file, owner-only.
95	File(PathBuf),
96	/// A credential helper, by its `auth.helper` value.
97	Helper(String),
98	}
99
100	/// The credential store of one oxy home directory.
101	#[derive(Clone, Debug)]
102	pub struct Credentials {
103	home: PathBuf,
104	}
105
106	impl Credentials {
107	/// The store in `home` (an oxy home directory).
108	pub fn at(home: impl Into<PathBuf>) -> Credentials {
109	Credentials { home: home.into() }
110	}
111
112	/// The store in the user's oxy home directory.
113	pub fn user() -> Credentials {
114	Credentials::at(crate::repo::default_home())
115	}
116
117	/// `credentials.toml` in the home directory.
118	pub fn path(&self) -> PathBuf {
119	self.home.join("credentials.toml")
120	}
121
122	/// The configured credential helper (`auth.helper` in the user file).
123	pub fn helper(&self) -> Option<String> {
124	crate::repo::read_config_file(&self.home.join("config.toml"))
125	.ok()?
126	.remove("auth.helper")
127	.filter(\|h\| !h.trim().is_empty())
128	}
129
130	/// Every hub in the file, tokens as stored there (none with a helper).
131	pub fn entries(&self) -> Result<Vec<HubEntry>, String> {
132	Ok(self.read()?.into_values().collect())
133	}
134
135	/// Whether the file can be read by anyone but its owner, in which case
136	/// lookups ignore it.
137	pub fn too_open(&self) -> bool {
138	#[cfg(unix)]
139	{
140	use std::os::unix::fs::PermissionsExt;
141	if let Ok(m) = std::fs::metadata(self.path()) {
142	return m.permissions().mode() & 0o077 != 0;
143	}
144	}
145	false
146	}
147
148	/// The entry for `hub`, its token fetched from the helper if one is set.
149	pub fn get(&self, hub: &str) -> Result<Option<HubEntry>, String> {
150	let entry = self.read()?.remove(hub);
151	let helper = self.helper();
152	let mut entry = match (entry, &helper) {
153	(Some(e), _) => e,
154	// A helper may hold a token stored before the file was cleared.
155	(None, Some(_)) => HubEntry {
156	hub: hub.to_string(),
157	..HubEntry::default()
158	},
159	(None, None) => return Ok(None),
160	};
161	if entry.token.is_none() {
162	if let Some(h) = &helper {
163	entry.token = run_helper(h, "get", hub, None)?;
164	}
165	}
166	if entry.token.is_none()
167	&& entry.account.is_none()
168	&& entry.ca.is_none()
169	&& entry.grant.is_none()
170	{
171	return Ok(None);
172	}
173	Ok(Some(entry))
174	}
175
176	/// Save a token (and what is known about it) for `hub`.
177	pub fn save(
178	&self,
179	hub: &str,
180	token: &str,
181	account: Option<&str>,
182	ca: Option<&Path>,
183	) -> Result<Stored, String> {
184	let mut all = self.read()?;
185	let helper = self.helper();
186	let entry = all.entry(hub.to_string()).or_insert_with(\|\| HubEntry {
187	hub: hub.to_string(),
188	..HubEntry::default()
189	});
190	entry.account = account.map(String::from).or(entry.account.take());
191	if let Some(ca) = ca {
192	entry.ca = Some(ca.to_path_buf());
193	}
194	let stored = match &helper {
195	Some(h) => {
196	run_helper(h, "store", hub, Some(token))?;
197	entry.token = None;
198	Stored::Helper(h.clone())
199	}
200	None => {
201	entry.token = Some(token.to_string());
202	Stored::File(self.path())
203	}
204	};
205	self.write(&all)?;
206	forget_cached();
207	Ok(stored)
208	}
209
210	/// Save an agent's grant token for `hub` (keyless signing, spec §14.7):
211	/// in the file, or the helper under its own user name.
212	pub fn save_grant(&self, hub: &str, token: &str) -> Result<Stored, String> {
213	let mut all = self.read()?;
214	let entry = all.entry(hub.to_string()).or_insert_with(\|\| HubEntry {
215	hub: hub.to_string(),
216	..HubEntry::default()
217	});
218	let stored = match self.helper() {
219	Some(h) => {
220	run_helper_as(&h, "store", hub, GRANT_USER, Some(token))?;
221	entry.grant = None;
222	Stored::Helper(h)
223	}
224	None => {
225	entry.grant = Some(token.to_string());
226	Stored::File(self.path())
227	}
228	};
229	self.write(&all)?;
230	Ok(stored)
231	}
232
233	/// The agent grant token kept for `hub`, if any.
234	pub fn grant(&self, hub: &str) -> Result<Option<String>, String> {
235	if let Some(g) = self.read()?.get(hub).and_then(\|e\| e.grant.clone()) {
236	return Ok(Some(g));
237	}
238	match self.helper() {
239	Some(h) => run_helper_as(&h, "get", hub, GRANT_USER, None),
240	None => Ok(None),
241	}
242	}
243
244	/// Remove `hub` from the file and the helper; returns what it held,
245	/// with the token, so the caller can revoke it.
246	pub fn remove(&self, hub: &str) -> Result<Option<HubEntry>, String> {
247	let found = self.get(hub)?;
248	let mut all = self.read()?;
249	if all.remove(hub).is_some() {
250	self.write(&all)?;
251	}
252	if let Some(h) = self.helper() {
253	run_helper(&h, "erase", hub, None)?;
254	}
255	forget_cached();
256	Ok(found)
257	}
258
259	fn read(&self) -> Result<BTreeMap<String, HubEntry>, String> {
260	let path = self.path();
261	let text = match std::fs::read_to_string(&path) {
262	Ok(t) => t,
263	Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(BTreeMap::new()),
264	Err(e) => return Err(format!("reading {}: {e}", path.display())),
265	};
266	let mut out = BTreeMap::new();
267	let mut current: Option<HubEntry> = None;
268	for (n, line) in text.lines().enumerate() {
269	let line = line.trim();
270	if line.is_empty() \|\| line.starts_with('#') {
271	continue;
272	}
273	if let Some(hub) = line.strip_prefix('[').and_then(\|l\| l.strip_suffix(']')) {
274	if let Some(e) = current.take() {
275	out.insert(e.hub.clone(), e);
276	}
277	current = Some(HubEntry {
278	hub: hub.trim().to_string(),
279	..HubEntry::default()
280	});
281	continue;
282	}
283	let bad = \|\| {
284	format!(
285	"{} line {}: expected key = \"value\"",
286	path.display(),
287	n + 1
288	)
289	};
290	let (k, v) = line.split_once('=').ok_or_else(bad)?;
291	let v = unquote(v.trim()).ok_or_else(bad)?;
292	let Some(e) = current.as_mut() else {
293	return Err(format!(
294	"{} line {}: a key before any [hub] section",
295	path.display(),
296	n + 1
297	));
298	};
299	match k.trim() {
300	"account" => e.account = Some(v),
301	"token" => e.token = Some(v),
302	"ca" => e.ca = Some(PathBuf::from(v)),
303	"grant" => e.grant = Some(v),
304	// Unknown keys are kept out of lookups, not fatal.
305	_ => {}
306	}
307	}
308	if let Some(e) = current {
309	out.insert(e.hub.clone(), e);
310	}
311	Ok(out)
312	}
313
314	fn write(&self, all: &BTreeMap<String, HubEntry>) -> Result<(), String> {
315	let mut text =
316	String::from("# oxy credentials: a token for each hub. Keep this file private.\n");
317	for e in all.values() {
318	text.push_str(&format!("\n[{}]\n", e.hub));
319	if let Some(a) = &e.account {
320	text.push_str(&format!("account = {}\n", quote(a)));
321	}
322	if let Some(t) = &e.token {
323	text.push_str(&format!("token = {}\n", quote(t)));
324	}
325	if let Some(c) = &e.ca {
326	text.push_str(&format!("ca = {}\n", quote(&c.to_string_lossy())));
327	}
328	if let Some(g) = &e.grant {
329	text.push_str(&format!("grant = {}\n", quote(g)));
330	}
331	}
332	let path = self.path();
333	std::fs::create_dir_all(&self.home)
334	.map_err(\|e\| format!("creating {}: {e}", self.home.display()))?;
335	crate::durable::write_atomic_private(&path, text.as_bytes())
336	.map_err(\|e\| format!("writing {}: {e}", path.display()))
337	}
338
339	/// The stored token and CA for `url`'s hub, if any: memoized, so a
340	/// helper runs once per hub in a process. A file anyone else can read
341	/// is ignored, with a warning.
342	pub fn lookup(&self, url: &str) -> (Option<String>, Option<PathBuf>) {
343	let Some(hub) = hub_of(url) else {
344	return (None, None);
345	};
346	let key = (self.home.clone(), hub.clone());
347	if let Some(hit) = cache().lock().unwrap().get(&key) {
348	return hit.clone();
349	}
350	let found = if self.too_open() {
351	warn_once(&format!(
352	"warning: {} can be read by other users, so oxy ignores it; run chmod 600 on it",
353	self.path().display()
354	));
355	(None, None)
356	} else {
357	match self.get(&hub) {
358	Ok(Some(e)) => (e.token, e.ca),
359	Ok(None) => (None, None),
360	Err(e) => {
361	warn_once(&format!("warning: credentials for {hub}: {e}"));
362	(None, None)
363	}
364	}
365	};
366	cache().lock().unwrap().insert(key, found.clone());
367	found
368	}
369
370	/// Options for reaching `url` without a configured remote: `$OXY_TOKEN`
371	/// and `$OXY_CA`, else what this store holds for its hub.
372	pub fn options_for(&self, url: &str) -> RemoteOptions {
373	let env_token = std::env::var("OXY_TOKEN").ok().filter(\|t\| !t.is_empty());
374	let env_ca = std::env::var("OXY_CA").ok().map(PathBuf::from);
375	let (token, ca) = match (&env_token, &env_ca) {
376	(Some(_), Some(_)) => (None, None),
377	_ => self.lookup(url),
378	};
379	RemoteOptions {
380	token: env_token.or(token),
381	ca: env_ca.or(ca),
382	..RemoteOptions::default()
383	}
384	}
385	}
386
387	type Cache = Mutex<HashMap<(PathBuf, String), (Option<String>, Option<PathBuf>)>>;
388
389	fn cache() -> &'static Cache {
390	static CACHE: OnceLock<Cache> = OnceLock::new();
391	CACHE.get_or_init(Default::default)
392	}
393
394	fn forget_cached() {
395	cache().lock().unwrap().clear();
396	}
397
398	pub(crate) fn warn_once(message: &str) {
399	static SEEN: OnceLock<Mutex<std::collections::HashSet<String>>> = OnceLock::new();
400	if SEEN
401	.get_or_init(Default::default)
402	.lock()
403	.unwrap()
404	.insert(message.to_string())
405	{
406	eprintln!("{message}");
407	}
408	}
409
410	fn quote(v: &str) -> String {
411	let mut out = String::from('"');
412	for c in v.chars() {
413	match c {
414	'"' => out.push_str("\\\""),
415	'\\' => out.push_str("\\\\"),
416	'\n' => out.push_str("\\n"),
417	c => out.push(c),
418	}
419	}
420	out.push('"');
421	out
422	}
423
424	fn unquote(v: &str) -> Option<String> {
425	let inner = v.strip_prefix('"')?.strip_suffix('"')?;
426	let mut out = String::new();
427	let mut chars = inner.chars();
428	while let Some(c) = chars.next() {
429	if c == '\\' {
430	match chars.next()? {
431	'n' => out.push('\n'),
432	c => out.push(c),
433	}
434	} else {
435	out.push(c);
436	}
437	}
438	Some(out)
439	}
440
441	/// Run a credential helper (Git's protocol): `get`, `store` or `erase` for
442	/// `hub`. `get` returns the password the helper answered with.
443	///
444	/// `auth.helper` is a helper name (run as `git credential-NAME`), an
445	/// absolute path, or a shell command after `!`, as in Git.
446	fn run_helper(
447	helper: &str,
448	action: &str,
449	hub: &str,
450	token: Option<&str>,
451	) -> Result<Option<String>, String> {
452	run_helper_as(helper, action, hub, HELPER_USER, token)
453	}
454
455	/// The helper's user name for an agent's grant token, beside the hub's
456	/// own token.
457	const GRANT_USER: &str = "oxy-agent-grant";
458
459	fn run_helper_as(
460	helper: &str,
461	action: &str,
462	hub: &str,
463	user: &str,
464	token: Option<&str>,
465	) -> Result<Option<String>, String> {
466	let (protocol, host) = hub
467	.split_once("://")
468	.ok_or_else(\|\| format!("{hub} is not a hub URL"))?;
469	let mut cmd = if let Some(shell) = helper.strip_prefix('!') {
470	let mut c = Command::new("sh");
471	c.arg("-c").arg(format!("{shell} {action}"));
472	c
473	} else if Path::new(helper).is_absolute() {
474	let mut c = Command::new(helper);
475	c.arg(action);
476	c
477	} else {
478	let mut c = Command::new("git");
479	c.arg(format!("credential-{helper}")).arg(action);
480	c
481	};
482	let mut input = format!("protocol={protocol}\nhost={host}\nusername={user}\n");
483	if let Some(t) = token {
484	input.push_str(&format!("password={t}\n"));
485	}
486	input.push('\n');
487	let mut child = cmd
488	.stdin(Stdio::piped())
489	.stdout(Stdio::piped())
490	.stderr(Stdio::inherit())
491	.spawn()
492	.map_err(\|e\| format!("running credential helper {helper:?}: {e}"))?;
493	child
494	.stdin
495	.take()
496	.expect("piped")
497	.write_all(input.as_bytes())
498	.map_err(\|e\| format!("credential helper {helper:?}: {e}"))?;
499	let out = child
500	.wait_with_output()
501	.map_err(\|e\| format!("credential helper {helper:?}: {e}"))?;
502	if !out.status.success() {
503	return Err(format!("credential helper {helper:?} {action} failed"));
504	}
505	if action != "get" {
506	return Ok(None);
507	}
508	Ok(String::from_utf8_lossy(&out.stdout)
509	.lines()
510	.find_map(\|l\| l.strip_prefix("password="))
511	.map(String::from)
512	.filter(\|p\| !p.is_empty()))
513	}
514
515	#[cfg(test)]
516	mod tests {
517	use super::*;
518
519	/// oxygenhub#241: an agent's grant token is kept beside the hub's own
520	/// token, owner-only, and read back without disturbing it.
521	#[test]
522	fn a_grant_token_is_kept_beside_the_hub_token() {
523	let dir = tempfile::tempdir().unwrap();
524	let store = Credentials::at(dir.path());
525	let hub = "https://oxygenhub.io";
526	assert_eq!(store.grant(hub).unwrap(), None);
527	store.save(hub, "oxyhub_t", Some("andy"), None).unwrap();
528	store.save_grant(hub, "oxyagent_g").unwrap();
529	assert_eq!(store.grant(hub).unwrap().as_deref(), Some("oxyagent_g"));
530	let e = store.get(hub).unwrap().unwrap();
531	assert_eq!(e.token.as_deref(), Some("oxyhub_t"));
532	assert_eq!(e.account.as_deref(), Some("andy"));
533	// A grant alone is an entry too.
534	store
535	.save_grant("https://elsewhere.example", "oxyagent_h")
536	.unwrap();
537	assert!(store.get("https://elsewhere.example").unwrap().is_some());
538	#[cfg(unix)]
539	{
540	use std::os::unix::fs::PermissionsExt;
541	let mode = std::fs::metadata(store.path())
542	.unwrap()
543	.permissions()
544	.mode();
545	assert_eq!(mode & 0o077, 0, "owner only");
546	}
547	}
548
549	#[test]
550	fn hubs_are_scheme_host_and_port() {
551	assert_eq!(
552	hub_of("https://OxygenHub.io/doomsdayone/metalgear").as_deref(),
553	Some("https://oxygenhub.io")
554	);
555	assert_eq!(
556	hub_of("http://127.0.0.1:7300/a/b").as_deref(),
557	Some("http://127.0.0.1:7300")
558	);
559	assert_eq!(
560	hub_of("https://user:[email protected]/x").as_deref(),
561	Some("https://hub.example")
562	);
563	assert_eq!(hub_of("/srv/repo"), None);
564	assert_eq!(hub_of("file:///srv/repo"), None);
565	}
566
567	#[test]
568	fn tokens_go_over_https_or_to_this_machine() {
569	assert!(token_allowed("https://oxygenhub.io/a/b"));
570	assert!(token_allowed("http://127.0.0.1:7300/a/b"));
571	assert!(token_allowed("http://localhost/a"));
572	assert!(token_allowed("http://[::1]:8080/a"));
573	assert!(!token_allowed("http://oxygenhub.io/a/b"));
574	assert!(!token_allowed("http://10.0.0.1/a"));
575	assert!(!token_allowed("http://127.0.0.1.evil.example/a"));
576	}
577
578	#[test]
579	fn save_get_and_remove_round_trip_privately() {
580	let dir = tempfile::tempdir().unwrap();
581	let store = Credentials::at(dir.path());
582	assert_eq!(store.get("https://hub.example").unwrap(), None);
583	let stored = store
584	.save("https://hub.example", "tok\"en", Some("andy"), None)
585	.unwrap();
586	assert_eq!(stored, Stored::File(store.path()));
587	store
588	.save(
589	"http://127.0.0.1:7300",
590	"local",
591	None,
592	Some(Path::new("/ca.pem")),
593	)
594	.unwrap();
595	let e = store.get("https://hub.example").unwrap().unwrap();
596	assert_eq!(e.token.as_deref(), Some("tok\"en"));
597	assert_eq!(e.account.as_deref(), Some("andy"));
598	assert!(!store.too_open());
599	assert_eq!(
600	store.lookup("https://hub.example/o/r"),
601	(Some("tok\"en".into()), None)
602	);
603	// Another host, scheme or port gets nothing.
604	assert_eq!(store.lookup("https://other.example/o/r"), (None, None));
605	assert_eq!(store.lookup("http://hub.example/o/r"), (None, None));
606	assert_eq!(store.lookup("https://hub.example:8443/o/r"), (None, None));
607	let gone = store.remove("https://hub.example").unwrap().unwrap();
608	assert_eq!(gone.token.as_deref(), Some("tok\"en"));
609	assert_eq!(store.lookup("https://hub.example/o/r"), (None, None));
610	assert_eq!(store.entries().unwrap().len(), 1);
611	}
612
613	#[cfg(unix)]
614	#[test]
615	fn a_file_others_can_read_is_ignored() {
616	use std::os::unix::fs::PermissionsExt;
617	let dir = tempfile::tempdir().unwrap();
618	let store = Credentials::at(dir.path());
619	store.save("https://open.example", "t", None, None).unwrap();
620	let mode = std::fs::metadata(store.path())
621	.unwrap()
622	.permissions()
623	.mode();
624	assert_eq!(mode & 0o777, 0o600);
625	std::fs::set_permissions(store.path(), std::fs::Permissions::from_mode(0o644)).unwrap();
626	assert!(store.too_open());
627	assert_eq!(store.lookup("https://open.example/o/r"), (None, None));
628	}
629
630	#[cfg(unix)]
631	#[test]
632	fn a_helper_keeps_the_token_out_of_the_file() {
633	let dir = tempfile::tempdir().unwrap();
634	let vault = dir.path().join("vault");
635	// A helper that keeps one password in a file, as a keyring would.
636	let helper = format!(
637	"!f() {{ case $1 in get) [ -f {v} ] && echo password=$(cat {v});; store) sed -n 's/^password=//p' > {v};; erase) rm -f {v};; esac; }}; f",
638	v = vault.display()
639	);
640	std::fs::write(
641	dir.path().join("config.toml"),
642	format!("auth.helper = \"{helper}\"\n"),
643	)
644	.unwrap();
645	let store = Credentials::at(dir.path());
646	assert!(store.helper().is_some());
647	let stored = store
648	.save("https://hub.example", "secret", Some("andy"), None)
649	.unwrap();
650	assert!(matches!(stored, Stored::Helper(_)));
651	let text = std::fs::read_to_string(store.path()).unwrap();
652	assert!(!text.contains("secret"), "{text}");
653	assert_eq!(
654	store
655	.get("https://hub.example")
656	.unwrap()
657	.unwrap()
658	.token
659	.as_deref(),
660	Some("secret")
661	);
662	store.remove("https://hub.example").unwrap();
663	assert!(!vault.exists());
664	}
665	}

Keyboard