Agents sign keyless: author.signer = keyless (keyless step 5c) c895bc52e4e0

//! Signing with short-lived keys (spec §14.7, oxygenhub#241): with

//! `author.signer = keyless`, oxy asks the hub to certify a fresh key

//! whenever it must sign, with the agent's grant token as the credential,

//! and keeps the key in memory for its certificate's minutes. Nothing that

//! signs is ever written to disk: the home holds only the grant token,

//! which its owner revokes on the hub. The certificate carries the owner's

//! grant, so what the key signs counts in the owner's name.

use super::*;

use crate::cert::{certify_challenge, SignedCertificate};

use crate::credentials::{hub_of, Credentials};

use crate::protocol::{http_get, http_json, RemoteOptions};

/// A certified key is used until this long before its certificate ends,

/// so a push started near the end does not outlive it.

const MARGIN_MS: u64 = 2 * 60 * 1000;

impl Repo {

    /// The hub that certifies keys: `keyless.hub`, else the default

    /// remote's.

    fn keyless_hub(&self) -> Result<String> {

        let url = match &self.config.keyless_hub {

            Some(h) => h.clone(),

            None => self

                .config

                .remotes

                .get(&self.default_remote())

                .cloned()

                .ok_or_else(|| {

                    RepoError::Msg(

                        "author.signer is keyless, but neither keyless.hub nor a default remote names the hub that certifies keys"

                            .into(),

                    )

                })?,

        };

        hub_of(&url).ok_or_else(|| RepoError::Msg(format!("{url} is not a hub URL")))

    }

    /// The key to sign with now: the one certified last while it has more

    /// than a couple of minutes left, else a fresh one the hub certifies.

    pub(crate) fn keyless_secret(&self) -> Result<(KeyId, SecretKey)> {

        let now = Hlc::now().wall_ms;

        if let Some((k, sk, until)) = self.keyless_key.borrow().as_ref() {

            if now + MARGIN_MS < *until {

                return Ok((*k, sk.clone()));

            }

        }

        let hub = self.keyless_hub()?;

        let home = self

            .user_config

            .parent()

            .map(Path::to_path_buf)

            .unwrap_or_else(default_home);

        let creds = Credentials::at(home);

        let token = creds.grant(&hub).map_err(RepoError::Msg)?.ok_or_else(|| {

            RepoError::Msg(format!(

                "author.signer is keyless, but there is no agent grant for {hub}: its owner makes one with `oh agent grant NAME`, and `oxy auth grant TOKEN` keeps it"

            ))

        })?;

        let options = RemoteOptions {

            token: Some(token.clone()),

            ca: creds.get(&hub).map_err(RepoError::Msg)?.and_then(|e| e.ca),

            ..RemoteOptions::default()

        };

        let sk = SecretKey::generate();

        let id = sk.identity(&self.config.author_name, &self.config.author_email, now);

        let key = id.hash();

        let proof = sk

            .sign_challenge(&key, &certify_challenge(&token))

            .map_err(|e| RepoError::Msg(e.to_string()))?;

        let body = serde_json::json!({

            "identity": crate::dsse::base64(&id.encode()),

            "proof": crate::dsse::base64(&crate::cbor::encode(&proof.to_value())),

            "scope": "changes,refs,seal",

        });

        let (code, answer) = http_json(

            "POST",

            &format!("{hub}/api/v1/keyless/certify"),

            Some(&body.to_string()),

            &options,

        )?;

        let reply: serde_json::Value = serde_json::from_str(&answer).unwrap_or_default();

        if !(200..300).contains(&code) {

            let why = reply["error"].as_str().unwrap_or(answer.trim());

            return fail(format!(

                "{hub} would not certify a key (HTTP {code}): {why}"

            ));

        }

        let cert = reply["certificate"]

            .as_str()

            .and_then(crate::dsse::base64_decode)

            .ok_or_else(|| RepoError::Msg(format!("{hub} answered with no certificate")))?;

        let cert = SignedCertificate::decode(&cert)

            .map_err(|e| RepoError::Msg(format!("{hub}'s certificate: {e}")))?;

        if cert.cert.key_id() != key {

            return fail(format!(

                "{hub} certified another key than the one it was asked for"

            ));

        }

        // The issuer's identity, so this repository (and whoever it pushes

        // to) can check the certificate: the hub's own, as it publishes it.

        let issuer = match self.store.get_identity(&cert.cert.issuer) {

            Ok(i) => i,

            Err(_) => {

                let bytes = http_get(

                    &format!("{hub}/.well-known/oxyhub-key"),

                    &RemoteOptions {

                        token: None,

                        ..options.clone()

                    },

                )?;

                let i = Identity::decode(&bytes)?;

                if i.hash() != cert.cert.issuer {

                    return fail(format!(

                        "{hub}'s published key is not the one that signed its certificate"

                    ));

                }

                i

            }

        };

        cert.verify(&issuer)

            .map_err(|e| RepoError::Msg(format!("{hub}'s certificate: {e}")))?;

        self.store.put_identity(&issuer)?;

        self.store.put_identity(&id)?;

        self.store.put_certificate(&cert)?;

        *self.keyless_key.borrow_mut() = Some((key, sk.clone(), cert.cert.expires));

        Ok((key, sk))

    }

}

/// The key a home names as its author (`author.key` in its

/// `config.toml`), with its secret from the home's `keys/`: what signs

/// outside any repository, such as a grant to an agent (`oh agent grant`).

/// `None` when the home names no key or does not hold its secret.

pub fn home_key(home: &Path) -> Result<Option<(Identity, SecretKey)>> {

    let config = read_config_file(&home.join("config.toml"))?;

    let Some(hex) = config.get("author.key").filter(|v| !v.is_empty()) else {

        return Ok(None);

    };

    let key = KeyId::from_hex(hex)

        .ok_or_else(|| RepoError::Msg("author.key must be a 64-character hex KeyId".into()))?;

    let keys = home.join("keys");

    let secret = match fs::read(keys.join(format!("{hex}.secret"))) {

        Ok(b) => b,

        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),

        Err(e) => return Err(e.into()),

    };

    let (k, sk) = SecretKey::decode(&secret)?;

    let id = Identity::decode(&fs::read(keys.join(format!("{hex}.identity")))?)?;

    if k != key || id.hash() != key {

        return fail(format!(

            "{} holds another key than author.key",

            keys.display()

        ));

    }

    Ok(Some((id, sk)))

}

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    fn a_home_s_key_signs_outside_any_repository() {

        static HOME: std::sync::OnceLock<tempfile::TempDir> = std::sync::OnceLock::new();

        HOME.get_or_init(|| {

            let d = tempfile::tempdir().unwrap();

            std::env::set_var("OXY_HOME", d.path());

            d

        });

        let dir = tempfile::tempdir().unwrap();

        let home = dir.path().join("home");

        assert!(home_key(&home).unwrap().is_none(), "no config, no key");

        let mut r = Repo::init(&dir.path().join("work"))

            .unwrap()

            .with_home(home.clone());

        let (key, id) = r

            .create_identity("Andy", "[email protected]", IdentityScope::User)

            .unwrap();

        let (got, sk) = home_key(&home).unwrap().expect("the home's author key");

        assert_eq!(got, id);

        let sig = sk.sign(Domain::Grant, &key, &ObjectRef([1; 32]));

        assert!(verify_signature(&id, &sig, Domain::Grant, &ObjectRef([1; 32])).is_ok());

        // An agent whose signer is keyless signs nothing until it asks.

        r.set_user_config("author.signer", "keyless").unwrap();

        assert!(r.config.signer_keyless && r.config.signer_key.is_none());

        assert_eq!(r.signing_key(), None);

        let err = r.secret_key().unwrap_err().to_string();

        assert!(err.contains("keyless.hub nor a default remote"), "{err}");

    }

}

 "serde_json",

serde_json = "1"

    /// An agent's grant token for keyless signing (oxygenhub#241), when it

    /// is in the file (not with a helper).

    pub grant: Option<String>,

        if entry.token.is_none()

            && entry.account.is_none()

            && entry.ca.is_none()

            && entry.grant.is_none()

        {

    /// 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),

        }

    }

                "grant" => e.grant = Some(v),

            }

            if let Some(g) = &e.grant {

                text.push_str(&format!("grant = {}\n", quote(g)));

    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 mut input = format!("protocol={protocol}\nhost={host}\nusername={user}\n");

    /// 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");

        }

    }

    /// `author.signer = "keyless"`: sign with fresh keys the hub certifies

    /// under the agent's grant, keeping no key on disk (spec §14.7,

    /// oxygenhub#241).

    pub signer_keyless: bool,

    /// `keyless.hub`: the hub that certifies them (default: the default

    /// remote's hub).

    pub keyless_hub: Option<String>,

            signer_keyless: std::env::var("OXY_SIGNER").is_ok_and(|v| v == "keyless"),

            keyless_hub: None,

                self.signer_keyless = value == "keyless";

                self.signer_key = if value.is_empty() || self.signer_keyless {

                        RepoError::Msg(

                            "author.signer must be a 64-character hex KeyId, or \"keyless\"".into(),

                        )

            "keyless.hub" => self.keyless_hub = (!value.is_empty()).then(|| value.to_string()),

        if self.config.signer_keyless {

            // The key certified last, once this command has signed.

            return self.keyless_key.borrow().as_ref().map(|(k, _, _)| *k);

        }

        if self.config.signer_keyless {

            return self.keyless_secret().map(Some);

        }

            || ((self.config.signer_key.is_some() || self.config.signer_keyless)

                && self.config.author_key == Some(*author))

mod keyless;

pub use keyless::home_key;

    /// With `author.signer = keyless`, the fresh key the hub last

    /// certified and when its certificate ends (spec §14.7): kept in memory

    /// only, for one command.

    pub(crate) keyless_key: std::cell::RefCell<Option<(KeyId, crate::identity::SecretKey, u64)>>,

            keyless_key: Default::default(),

            keyless_key: Default::default(),

                    keyless_key: Default::default(),

                    keyless_key: Default::default(),

**Keyless agents** (on an OxygenHub) hold no key at all. You give the

agent a grant instead, signed by your key, and the hub certifies a fresh

key for it each time it signs:

```

oh agent grant claude --for 30d       # your shell: prints the agent's token, once

oxy auth grant < token                # the agent's shell (its own OXY_HOME)

oxy config --user author.key    <YOUR KeyId>

oxy config --user author.signer keyless

```

Each certificate lasts ten minutes and carries your grant, so the

agent's commits count as yours, and a push seals them with the fresh

key. A repository with a trust policy also names the agent:

`oxy policy grant-subject agent:claude@YOU --issuer hub.identity --scope

changes` (add `refs` to let it push), with the hub's identity from

`/.well-known/oxyhub-key`. `oh agent list` shows your grants and `oh

agent revoke ID` stops one at once; there is no key to rotate.

| `author.signer` | the key that signs instead of `author.key`: an agent's own key, which your identity lists as a delegate; or `keyless`, for fresh keys the hub certifies under the agent's grant (also `$OXY_SIGNER`) |

| `keyless.hub` | the hub that certifies keyless keys (default: the default remote's hub) |

  scope       [4]: [text]         // what certificates under it may give: changes, seal, refs

| `~/.config/oxy/config.toml` | User settings, the same keys as `.oxy/config`: `author.name`, `author.email`, `author.key`, `author.signer` (the key that signs and seals in place of `author.key`, which must list it as a delegate: an agent's own key; or `keyless`, for fresh keys the hub certifies under an agent's grant, §14.7, from the grant token `oxy auth grant` keeps; also `$OXY_SIGNER`), `keyless.hub` (the hub that certifies them; default the default remote's), `core.sign`, and `remote.<name>.token`; also `auth.helper`. Overridden by `$OXY_HOME/config.toml` when `$OXY_HOME` is set. |

/// `oxy auth grant`: keep an agent's grant token (oxygenhub#241) for

/// keyless signing, read from standard input.

pub fn grant(hub: Option<&str>) -> Result<i32> {

    use std::io::IsTerminal;

    let hub = resolve_hub(hub)?;

    if !token_allowed(&hub) {

        bail!("{hub} is plain http: a token would cross the network unencrypted; use its https address");

    }

    if std::io::stdin().is_terminal() {

        eprint!("Agent grant token for {hub}: ");

    }

    let mut line = String::new();

    std::io::stdin()

        .lock()

        .read_line(&mut line)

        .context("reading the token from standard input")?;

    let token = line.trim();

    if !token.starts_with("oxyagent_") {

        bail!("that is not an agent grant token (they start oxyagent_; `oh agent grant NAME` makes one)");

    }

    let stored = Credentials::user()

        .save_grant(&hub, token)

        .map_err(|e| anyhow::anyhow!("{e}"))?;

    println!(

        "{} for {}",

        ui::done("Kept the agent grant"),

        ui::path(&hub)

    );

    println!(

        "  {} {}",

        ui::note(),

        ui::dim(format!(

            "token in {}; sign with it: oxy config author.signer keyless",

            where_stored(&stored)

        ))

    );

    Ok(0)

}

    /// Keep an agent grant token (from `oh agent grant`) for keyless

    /// signing: with `author.signer = keyless`, commits and pushes are

    /// signed by fresh keys the hub certifies, in the grantor's name

    /// (the token is read from standard input, so it stays out of the

    /// shell's history)

    Grant {

        /// The hub (default: this checkout's origin)

        hub: Option<String>,

    },

            AuthCmd::Grant { hub } => auth::grant(hub.as_deref()),