Agent grants: agents act for their owner with no key (keyless step 5) 8aa5ef384ef1

-- Agent grants (oxygenhub#241, keyless step 5): an account lets an agent

-- act for it. `grant` is the Oxygen grant its owner's key signed (spec

-- §14.7), which every certificate issued under it carries; the agent

-- holds only the token, which it exchanges for ten-minute certificates

-- and which signs nothing itself. Revoking stops the certificates.

CREATE TABLE agent_grants (

    id           BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,

    account_id   BIGINT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,

    agent        TEXT NOT NULL,

    subject      TEXT NOT NULL,

    grantor      TEXT NOT NULL,

    scope        TEXT NOT NULL,

    signed       BYTEA NOT NULL,

    token_hash   TEXT NOT NULL UNIQUE,

    created_ms   BIGINT NOT NULL,

    expires_ms   BIGINT NOT NULL,

    revoked_ms   BIGINT,

    last_used_ms BIGINT

);

CREATE INDEX agent_grants_account ON agent_grants(account_id);

-- Agent grants (oxygenhub#241, keyless step 5): an account lets an agent

-- act for it. `grant` is the Oxygen grant its owner's key signed (spec

-- §14.7), which every certificate issued under it carries; the agent

-- holds only the token, which it exchanges for ten-minute certificates

-- and which signs nothing itself. Revoking stops the certificates.

CREATE TABLE agent_grants (

    id           INTEGER PRIMARY KEY,

    account_id   INTEGER NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,

    agent        TEXT NOT NULL,

    subject      TEXT NOT NULL,

    grantor      TEXT NOT NULL,

    scope        TEXT NOT NULL,

    signed       BLOB NOT NULL,

    token_hash   TEXT NOT NULL UNIQUE,

    created_ms   INTEGER NOT NULL,

    expires_ms   INTEGER NOT NULL,

    revoked_ms   INTEGER,

    last_used_ms INTEGER

);

CREATE INDEX agent_grants_account ON agent_grants(account_id);

 "serde_json",

        .route("/agents/grants", get(crate::keyless::grants_list).post(crate::keyless::grants_create))

        .route("/agents/grants/{id}", axum::routing::delete(crate::keyless::grants_revoke))

// ------------------------------------------------------------ agent grants

/// An agent an account lets act for it (oxygenhub#241, migration 0075).

#[derive(Clone, Debug, FromRow)]

pub struct AgentGrant {

    pub id: i64,

    pub account_id: i64,

    pub agent: String,

    pub subject: String,

    /// The owner's KeyId (hex) that signed the grant.

    pub grantor: String,

    pub scope: String,

    /// The signed Oxygen grant, as certificates carry it.

    pub signed: Vec<u8>,

    pub token_hash: String,

    pub created_ms: i64,

    pub expires_ms: i64,

    pub revoked_ms: Option<i64>,

    pub last_used_ms: Option<i64>,

}

impl AgentGrant {

    /// Whether certificates may still be issued under it at `now`.

    pub fn live(&self, now: i64) -> bool {

        self.revoked_ms.is_none() && now < self.expires_ms

    }

}

pub struct NewAgentGrant<'a> {

    pub account_id: i64,

    pub agent: &'a str,

    pub subject: &'a str,

    pub grantor: &'a str,

    pub scope: &'a str,

    pub signed: &'a [u8],

    pub token_hash: &'a str,

    pub expires_ms: i64,

}

pub async fn create_agent_grant(pool: &Pool, g: NewAgentGrant<'_>) -> sqlx::Result<i64> {

    sqlx::query_scalar(

        "INSERT INTO agent_grants (account_id, agent, subject, grantor, scope, signed, token_hash, created_ms, expires_ms) \

         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9) RETURNING id",

    )

    .bind(g.account_id)

    .bind(g.agent)

    .bind(g.subject)

    .bind(g.grantor)

    .bind(g.scope)

    .bind(g.signed)

    .bind(g.token_hash)

    .bind(now_ms())

    .bind(g.expires_ms)

    .fetch_one(pool)

    .await

}

pub async fn agent_grants_of(pool: &Pool, account_id: i64) -> sqlx::Result<Vec<AgentGrant>> {

    sqlx::query_as("SELECT * FROM agent_grants WHERE account_id = $1 ORDER BY created_ms DESC, id DESC")

        .bind(account_id)

        .fetch_all(pool)

        .await

}

pub async fn agent_grant_by_token(pool: &Pool, token_hash: &str) -> sqlx::Result<Option<AgentGrant>> {

    sqlx::query_as("SELECT * FROM agent_grants WHERE token_hash = $1").bind(token_hash).fetch_optional(pool).await

}

pub async fn touch_agent_grant(pool: &Pool, id: i64) -> sqlx::Result<()> {

    sqlx::query("UPDATE agent_grants SET last_used_ms = $1 WHERE id = $2").bind(now_ms()).bind(id).execute(pool).await?;

    Ok(())

}

/// Revoke one of the account's grants; true when this call revoked it.

pub async fn revoke_agent_grant(pool: &Pool, account_id: i64, id: i64) -> sqlx::Result<bool> {

    let r = sqlx::query("UPDATE agent_grants SET revoked_ms = $1 WHERE id = $2 AND account_id = $3 AND revoked_ms IS NULL")

        .bind(now_ms())

        .bind(id)

        .bind(account_id)

        .execute(pool)

        .await?;

    Ok(r.rows_affected() == 1)

}

//!

//! An agent asks with a grant token instead (step 5): its owner signed an

//! Oxygen grant letting `agent:NAME@ACCOUNT` act for them (spec §14.7),

//! and every certificate issued under it carries that grant, so the

//! agent's fresh keys sign in the owner's name with nothing kept on disk

//! but the token. Revoking the grant stops the certificates.

use axum::extract::Path;

use oxy_core::cert::{certify_challenge, Certificate, SignedCertificate, SignedGrant};

/// What an agent holds in place of a key: `oxyagent_` and 32 random bytes.

pub const GRANT_TOKEN_PREFIX: &str = "oxyagent_";

    /// The most the certificate may give.

    allowed: Scope,

    /// The owner's grant the certificate carries, for an agent.

    grant: Option<SignedGrant>,

        allowed: Scope::CHANGES | Scope::REFS | Scope::SEAL,

        grant: None,

        allowed: Scope::CHANGES | Scope::REFS | Scope::SEAL,

        grant: None,

/// An agent's grant token: the owner's live grant.

async fn grant_proof(app: &Shared, token: &str, now: i64) -> Result<Proven, ApiError> {

    let invalid = || bad(StatusCode::UNAUTHORIZED, "this agent grant is not valid (revoked, ended or unknown)");

    let g = db::accounts::agent_grant_by_token(&app.db, &crate::auth::token_hash(token))

        .await

        .map_err(|e| bad(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?

        .filter(|g| g.live(now))

        .ok_or_else(invalid)?;

    let signed = SignedGrant::decode(&g.signed).map_err(|e| bad(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;

    db::accounts::touch_agent_grant(&app.db, g.id).await.ok();

    Ok(Proven {

        subject: g.subject.clone(),

        claims: vec![("agent".to_string(), g.agent.clone()), ("grant".to_string(), g.id.to_string())],

        until_ms: g.expires_ms,

        target: g.subject,

        allowed: signed.grant.scope,

        grant: Some(signed),

    })

}

    } else if token.starts_with(GRANT_TOKEN_PREFIX) {

        grant_proof(&app, &token, now).await?

    // What was asked, within what the credential allows (an agent's grant

    // may leave out `refs`, say): a key asks for all it might sign.

    let asked = Scope::parse(&req.scope).map_err(|e| bad(StatusCode::BAD_REQUEST, e))?;

    let scope =

        asked.names().into_iter().filter_map(|n| Scope::parse(n).ok()).filter(|s| proven.allowed.has(*s)).fold(Scope::NONE, |a, s| a | s);

    if scope.is_empty() {

        return Err(bad(StatusCode::FORBIDDEN, format!("{} may be certified for {} only", proven.subject, proven.allowed)));

    }

        grant: proven.grant,

}

#[derive(Deserialize)]

pub struct GrantRequest {

    /// The signed Oxygen grant (`[grant, signature]`), base64.

    pub grant: String,

}

#[derive(Serialize)]

pub struct GrantView {

    pub id: i64,

    pub agent: String,

    pub subject: String,

    pub grantor: String,

    pub scope: String,

    pub created_ms: i64,

    pub expires_ms: i64,

    pub revoked_ms: Option<i64>,

    pub last_used_ms: Option<i64>,

    /// Shown once, when the grant is made.

    #[serde(skip_serializing_if = "Option::is_none")]

    pub token: Option<String>,

}

impl From<db::accounts::AgentGrant> for GrantView {

    fn from(g: db::accounts::AgentGrant) -> Self {

        GrantView {

            id: g.id,

            agent: g.agent,

            subject: g.subject,

            grantor: g.grantor,

            scope: g.scope,

            created_ms: g.created_ms,

            expires_ms: g.expires_ms,

            revoked_ms: g.revoked_ms,

            last_used_ms: g.last_used_ms,

            token: None,

        }

    }

}

/// The account behind a personal token. A grant needs no token scope:

/// what makes it is the owner's signature, by a key linked to the account.

async fn owner(app: &Shared, headers: &HeaderMap) -> Result<db::accounts::Account, ApiError> {

    let c = crate::api::caller(app, headers).await?;

    c.account.ok_or_else(|| bad(StatusCode::UNAUTHORIZED, "a personal access token is required"))

}

/// An agent's name: what follows `agent:` and precedes `@`.

fn agent_name_ok(name: &str) -> bool {

    !name.is_empty() && name.len() <= 64 && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_' || c == '.')

}

/// `POST /api/v1/agents/grants`: keep an owner's signed grant to one of

/// their agents and give the agent its token.

pub async fn grants_create(

    State(app): State<Shared>,

    headers: HeaderMap,

    Json(req): Json<GrantRequest>,

) -> Result<(StatusCode, Json<GrantView>), ApiError> {

    let account = owner(&app, &headers).await?;

    let bytes = oxy_core::dsse::base64_decode(req.grant.trim()).ok_or_else(|| bad(StatusCode::BAD_REQUEST, "the grant is not base64"))?;

    let signed = SignedGrant::decode(&bytes).map_err(|e| bad(StatusCode::BAD_REQUEST, format!("grant: {e}")))?;

    let g = &signed.grant;

    let suffix = format!("@{}", account.username);

    let agent = g

        .subject

        .strip_prefix("agent:")

        .and_then(|r| r.strip_suffix(&suffix))

        .filter(|n| agent_name_ok(n))

        .ok_or_else(|| bad(StatusCode::BAD_REQUEST, format!("a grant here is for agent:NAME{suffix}, not {}", g.subject)))?

        .to_string();

    if g.issuer != app.hub_key.key {

        return Err(bad(StatusCode::BAD_REQUEST, "the grant names another issuer than this hub's key (/.well-known/oxyhub-key)"));

    }

    let grantor = g.grantor.to_hex();

    let linked = db::accounts::identity_by_key(&app.db, &grantor)

        .await

        .map_err(|e| bad(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?

        .filter(|i| i.account_id == account.id)

        .ok_or_else(|| bad(StatusCode::FORBIDDEN, format!("key {} is not linked to your account: link it first", g.grantor.short(12))))?;

    let identity = Identity::decode(&linked.object).map_err(|e| bad(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;

    signed.verify(&identity).map_err(|e| bad(StatusCode::BAD_REQUEST, format!("the grant does not verify: {e}")))?;

    let now = db::now_ms();

    if (g.expires as i64) <= now {

        return Err(bad(StatusCode::BAD_REQUEST, "the grant has already ended"));

    }

    let token = format!("{GRANT_TOKEN_PREFIX}{}", crate::auth::random_hex(32));

    let hash = crate::auth::token_hash(&token);

    let scope = g.scope.to_string();

    let id = db::accounts::create_agent_grant(

        &app.db,

        db::accounts::NewAgentGrant {

            account_id: account.id,

            agent: &agent,

            subject: &g.subject,

            grantor: &grantor,

            scope: &scope,

            signed: &bytes,

            token_hash: &hash,

            expires_ms: g.expires as i64,

        },

    )

    .await

    .map_err(|e| bad(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;

    db::accounts::audit(&app.db, Some(&account), "agent.granted", &g.subject, &format!("grant {id}, {scope}, until {}", g.expires))

        .await

        .ok();

    Ok((

        StatusCode::CREATED,

        Json(GrantView {

            id,

            agent,

            subject: g.subject.clone(),

            grantor,

            scope,

            created_ms: now,

            expires_ms: g.expires as i64,

            revoked_ms: None,

            last_used_ms: None,

            token: Some(token),

        }),

    ))

}

/// `GET /api/v1/agents/grants`: the caller's grants, without tokens.

pub async fn grants_list(State(app): State<Shared>, headers: HeaderMap) -> Result<Json<Vec<GrantView>>, ApiError> {

    let account = owner(&app, &headers).await?;

    let grants =

        db::accounts::agent_grants_of(&app.db, account.id).await.map_err(|e| bad(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;

    Ok(Json(grants.into_iter().map(GrantView::from).collect()))

}

/// `DELETE /api/v1/agents/grants/{id}`: stop certifying under a grant.

pub async fn grants_revoke(State(app): State<Shared>, headers: HeaderMap, Path(id): Path<i64>) -> Result<StatusCode, ApiError> {

    let account = owner(&app, &headers).await?;

    let done = db::accounts::revoke_agent_grant(&app.db, account.id, id)

        .await

        .map_err(|e| bad(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;

    if !done {

        return Err(bad(StatusCode::NOT_FOUND, "no such live grant of yours"));

    }

    db::accounts::audit(&app.db, Some(&account), "agent.revoked", &format!("grant {id}"), "").await.ok();

    Ok(StatusCode::NO_CONTENT)

            grant: None,

/// Keyless step 5 (oxygenhub#241): Andy grants an agent with his own key;

/// the agent, holding only the grant token, commits and pushes in Andy's

/// name with fresh keys the hub certifies under the grant. A grant by a

/// key not linked to the account, or for another account's agent, is

/// refused; a revoked grant certifies no more.

#[tokio::test(flavor = "multi_thread")]

async fn an_agent_with_a_grant_pushes_in_its_owner_s_name() {

    use oxy_core::cert::{Grant, SignedGrant};

    use oxy_core::identity::{Identity, Scope, SecretKey};

    use oxy_core::repo::{IdentityScope, SignatureStatus};

    let h = hub().await;

    let andy = db::accounts::create_account(&h.app.db, "andy", "[email protected]", "x", "salt", true).await.unwrap();

    let (pat, pat_hash) = oxygenhub::auth::new_token();

    db::accounts::create_token(&h.app.db, andy.id, "cli", &pat_hash, "repo:write", "", None).await.unwrap();

    create(&h.app, "andy", "demo").await;

    let url = format!("{}/andy/demo", h.base);

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

    // Andy's checkout, its policy granting the agent's subject.

    let mut a = client(&url, &work.path().join("a")).with_home(work.path().join("home-a"));

    let (andy_key, andy_id) = a.create_identity("Andy", "[email protected]", IdentityScope::User).unwrap();

    db::accounts::link_identity(&h.app.db, andy.id, &andy_key.to_hex(), "Andy", "[email protected]", &andy_id.encode()).await.unwrap();

    write(&work.path().join("a"), "a.txt", "a\n");

    a.commit("a", &[]).unwrap();

    a.policy_init().unwrap();

    assert!(a.push("origin", false).unwrap().iter().all(|r| r.ok));

    let hub_id = h.app.hub_key.identity.clone();

    a.policy_grant_subject("agent:claude@andy", hub_id.clone(), Scope::CHANGES | Scope::REFS, None).unwrap();

    assert!(a.push("origin", false).unwrap().iter().all(|r| r.ok));

    // Andy grants the agent, as `oh agent grant claude` does.

    let (_, andy_sk) = a.secret_key().unwrap().unwrap();

    let now = db::now_ms() as u64;

    let grant = |by: &Identity, sk: &SecretKey, subject: &str| {

        SignedGrant::sign(

            Grant {

                grantor: by.hash(),

                subject: subject.into(),

                issuer: hub_id.hash(),

                scope: Scope::CHANGES | Scope::SEAL | Scope::REFS,

                not_before: now - 60_000,

                expires: now + 86_400_000,

            },

            by,

            sk,

        )

    };

    let post = |g: SignedGrant| {

        let (app, pat) = (h.app.clone(), pat.clone());

        let body = serde_json::json!({ "grant": oxy_core::dsse::base64(&g.encode()) }).to_string();

        async move { call(&app, "POST", "/api/v1/agents/grants", Some(&pat), Some(body)).await }

    };

    let stray_sk = SecretKey::generate();

    let stray = stray_sk.identity("stray", "[email protected]", 1);

    let (st, body) = post(grant(&stray, &stray_sk, "agent:claude@andy")).await;

    assert_eq!(st, StatusCode::FORBIDDEN, "a key not linked to the account: {body}");

    let (st, body) = post(grant(&andy_id, &andy_sk, "agent:claude@mallory")).await;

    assert_eq!(st, StatusCode::BAD_REQUEST, "another account's agent: {body}");

    let (st, body) = post(grant(&andy_id, &andy_sk, "agent:claude@andy")).await;

    assert_eq!(st, StatusCode::CREATED, "{body}");

    let v: serde_json::Value = serde_json::from_str(&body).unwrap();

    let token = v["token"].as_str().unwrap().to_string();

    assert!(token.starts_with("oxyagent_"));

    let grant_id = v["id"].as_i64().unwrap();

    // The agent: a home holding only the grant token, Andy the author.

    let agent_home = work.path().join("home-claude");

    oxy_core::credentials::Credentials::at(&agent_home).save_grant(&h.base, &token).unwrap();

    let agent = || {

        let n = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos();

        let dir = work.path().join(format!("claude-{n}"));

        let mut r = Repo::clone(&url, &dir).unwrap().with_home(agent_home.clone());

        r.config.set("remote.origin.token", "site").unwrap();

        r.save_config().unwrap();

        r.set_user_config("author.key", &andy_key.to_hex()).unwrap();

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

        (r, dir)

    };

    let (claude, dir) = agent();

    assert!(!agent_home.join("keys").exists(), "no key on disk");

    write(&dir, "work.txt", "agent work\n");

    let change = claude.commit("Agent work", &[]).unwrap();

    let r = claude.push("origin", false).unwrap();

    assert!(r.iter().all(|x| x.ok), "{r:?}");

    let signer = claude.signing_key().expect("a certified key");

    assert_ne!(signer, andy_key);

    assert!(!agent_home.join("keys").exists(), "still no key on disk");

    // The hub holds it in Andy's name, sealed by the certified key, and

    // countersigned when it accepted the update.

    let host = h.app.repos.open(&RepoName::parse("andy/demo").unwrap()).unwrap();

    assert_eq!(host.store().get_change_meta(&change).unwrap().author, andy_key);

    assert!(matches!(

        host.authenticate_change(&change).unwrap(),

        SignatureStatus::Valid { key, sealed: true, .. } if key == signer

    ));

    let refs = open_remote(&url, &RemoteOptions::default()).unwrap().refs().unwrap();

    assert!(refs.refs.iter().find(|r| r.name == "main").unwrap().accepted.is_some());

    a.pull("origin").unwrap();

    assert!(matches!(a.authenticate_change(&change).unwrap(), SignatureStatus::Valid { .. }));

    // Revoked: the next command gets no certificate.

    let (st, _) = call(&h.app, "DELETE", &format!("/api/v1/agents/grants/{grant_id}"), Some(&pat), None).await;

    assert_eq!(st, StatusCode::NO_CONTENT);

    let (late, dir) = agent();

    write(&dir, "late.txt", "after the revocation\n");

    late.commit("Late", &[]).unwrap();

    let err = late.push("origin", false).unwrap_err().to_string();

    assert!(err.contains("would not certify"), "{err}");

    let (_, body) = call(&h.app, "GET", "/api/v1/agents/grants", Some(&pat), None).await;

    let list: Vec<serde_json::Value> = serde_json::from_str(&body).unwrap();

    assert!(list[0]["revoked_ms"].is_i64() && list[0].get("token").is_none(), "{body}");

}

    /// GET a path at the hub's root, outside the API (`/.well-known/…`).

    pub fn get_root_bytes(&self, path: &str) -> Result<Vec<u8>> {

        let hub = self.base.trim_end_matches("/api/v1");

        let r = self.agent.get(&format!("{hub}{path}")).call().with_context(|| format!("GET {path}"))?;

        let mut out = Vec::new();

        std::io::Read::read_to_end(&mut r.into_reader(), &mut out)?;

        Ok(out)

    }

    /// Agents that act for you without a key of their own (keyless

    /// signing): grant, list, revoke

    Agent {

        #[command(subcommand)]

        cmd: AgentCmd,

    },

enum AgentCmd {

    /// Let an agent act for you: your oxy key (the one your oxy home names

    /// as author.key) signs a grant to agent:NAME@YOU, and the hub gives

    /// the agent a token it exchanges for ten-minute certificates. The

    /// token is printed once: give it to the agent (`oxy auth grant`)

    Grant {

        /// The agent's name, as in agent:NAME@YOU

        name: String,

        /// What its keys may do for you: changes, seal, refs

        #[arg(long, default_value = "changes,seal,refs")]

        scope: String,

        /// How long the grant lasts: 30d, 12h, 90m

        #[arg(long = "for", value_name = "DURATION", default_value = "30d")]

        lasts: String,

    },

    /// Your grants, live and past

    List,

    /// Stop a grant at once: no more certificates under it

    Revoke { id: i64 },

}

#[derive(Subcommand)]

        Cmd::Agent { cmd } => agent(&c, cmd, json),

    }

}

/// `30d`, `12h`, `90m` in milliseconds.

fn duration_ms(s: &str) -> Result<i64> {

    let s = s.trim();

    let (n, unit) = s.split_at(s.find(|c: char| !c.is_ascii_digit()).unwrap_or(s.len()));

    let n: i64 = n.parse().with_context(|| format!("{s:?} is not a duration such as 30d, 12h or 90m"))?;

    let per = match unit {

        "d" => 86_400_000,

        "h" => 3_600_000,

        "m" => 60_000,

        _ => bail!("{s:?} is not a duration such as 30d, 12h or 90m"),

    };

    if n <= 0 {

        bail!("a grant must last some time");

    }

    Ok(n * per)

}

fn agent(c: &Client, cmd: AgentCmd, json: bool) -> Result<i32> {

    use oxy_core::cert::{Grant, SignedGrant};

    use oxy_core::identity::{Identity, Scope};

    match cmd {

        AgentCmd::Grant { name, scope, lasts } => {

            let home = oxy_core::repo::default_home();

            let (me_id, sk) = oxy_core::repo::home_key(&home).map_err(|e| anyhow::anyhow!("{e}"))?.with_context(|| {

                format!(

                    "{} names no key of yours (author.key) with its secret: the grant is signed with your own key, in your own shell",

                    home.display()

                )

            })?;

            let me: serde_json::Value = c.get("/user")?;

            let username = me["username"].as_str().context("the hub did not say who you are")?;

            let hub = Identity::decode(&c.get_root_bytes("/.well-known/oxyhub-key")?).map_err(|e| anyhow::anyhow!("the hub's key: {e}"))?;

            let scope = Scope::parse(&scope).map_err(|e| anyhow::anyhow!("{e}"))?;

            let now = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH)?.as_millis() as i64;

            let grant = Grant {

                grantor: me_id.hash(),

                subject: format!("agent:{name}@{username}"),

                issuer: hub.hash(),

                scope,

                not_before: (now - 60_000) as u64,

                expires: (now + duration_ms(&lasts)?) as u64,

            };

            let signed = SignedGrant::sign(grant, &me_id, &sk);

            let r: serde_json::Value =

                c.send("POST", "/agents/grants", &serde_json::json!({ "grant": oxy_core::dsse::base64(&signed.encode()) }))?;

            if json {

                println!("{r}");

                return Ok(0);

            }

            println!(

                "{} {} to act for you as {} ({}), until {}",

                ui::ok("✔ granted"),

                ui::strong(&name),

                r["subject"].as_str().unwrap_or(""),

                r["scope"].as_str().unwrap_or(""),

                ui::date(r["expires_ms"].as_i64().unwrap_or(0))

            );

            println!("  token (shown once): {}", r["token"].as_str().unwrap_or(""));

            println!(

                "  {}",

                ui::dim("in the agent's shell: oxy auth grant, paste the token; then oxy config --user author.signer keyless")

            );

            println!("  {}", ui::dim(&format!("revoke it with: oh agent revoke {}", r["id"])));

            Ok(0)

        }

        AgentCmd::List => {

            let grants: Vec<serde_json::Value> = c.get("/agents/grants")?;

            if json {

                println!("{}", serde_json::to_string(&grants)?);

                return Ok(0);

            }

            if grants.is_empty() {

                println!("{}", ui::dim("no agent grants"));

            }

            let now = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH)?.as_millis() as i64;

            for g in grants {

                let state = if g["revoked_ms"].is_i64() {

                    ui::bad("revoked")

                } else if g["expires_ms"].as_i64().unwrap_or(0) <= now {

                    ui::dim("ended")

                } else {

                    ui::ok("live")

                };

                let used = g["last_used_ms"].as_i64().map(|t| format!("used {}", ui::ago(t))).unwrap_or_else(|| "never used".into());

                println!(

                    "#{:<4} {:<8} {} · {} · until {} · {}",

                    g["id"],

                    state,

                    ui::strong(g["subject"].as_str().unwrap_or("")),

                    g["scope"].as_str().unwrap_or(""),

                    ui::date(g["expires_ms"].as_i64().unwrap_or(0)),

                    ui::dim(&used)

                );

            }

            Ok(0)

        }

        AgentCmd::Revoke { id } => {

            c.send_text("DELETE", &format!("/agents/grants/{id}"), &serde_json::json!({}))?;

            println!("{} grant #{id}: no more certificates under it", ui::ok("✔ revoked"));

            Ok(0)

        }

/// A wall time as its UTC date and minute, `2026-11-16 09:30Z`.

pub fn date(ms: i64) -> String {

    let secs = ms.div_euclid(1000);

    let (days, rem) = (secs.div_euclid(86_400), secs.rem_euclid(86_400));

    // Days since 1970-01-01 to a civil date (Howard Hinnant's algorithm).

    let z = days + 719_468;

    let era = z.div_euclid(146_097);

    let doe = z - era * 146_097;

    let yoe = (doe - doe / 1_460 + doe / 36_524 - doe / 146_096) / 365;

    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);

    let mp = (5 * doy + 2) / 153;

    let d = doy - (153 * mp + 2) / 5 + 1;

    let m = if mp < 10 { mp + 3 } else { mp - 9 };

    let y = yoe + era * 400 + i64::from(m <= 2);

    format!("{y:04}-{m:02}-{d:02} {:02}:{:02}Z", rem / 3_600, rem % 3_600 / 60)

}

#[cfg(test)]

mod date_tests {

    #[test]

    fn dates_are_utc_civil_dates() {

        assert_eq!(super::date(0), "1970-01-01 00:00Z");

        assert_eq!(super::date(1_792_229_400_000), "2026-10-17 09:30Z");

        assert_eq!(super::date(951_782_400_000), "2000-02-29 00:00Z");

    }

}

steps 1 to 5 of the order of work and the hub's acceptance attestation

(step 6's first half, Oxygen spec §14.7); the log's time is next. Agents'

grants are signed by their owner's key (Andy's choice, 2026-10-17), so a

certified key's changes count in the owner's name without trusting the

hub for authorship. It builds on the hub's

### 13.5.2 Certificates for short-lived keys (oxygenhub#241, docs/keyless.md, steps 2 to 5 built 2026-10-17)

`POST /api/v1/keyless/certify` gives a fresh key a certificate (Oxygen spec §14.7) for ten minutes, signed with the hub's key. The bearer is the credential: a running job's token (subject `repo:OWNER/NAME:bookmark:B`, claims `repository`, `bookmark`, `run`, `job`, `runner`, and `environment` with `approved_by` once an approved job may deploy), or one of this hub's OIDC tokens for the audience `{base_url}/keyless` (its `sub` the subject, and the same claims it carries). The body is `{"identity": base64 identity object, "proof": base64 CBOR Signature, "scope": "changes,refs"}`, the proof the fresh key's challenge signature (§14.3) over `certify_challenge(credential)` (`"oxy1 certify "` and the BLAKE3 of the credential), so it cannot be replayed with another credential. The answer is `{"certificate": base64 [certificate, signature], "subject", "expires_ms"}`; a certificate never outlives its credential, and it starts 30 s back for clocks a little behind. Each one is audited (`keyless.certified`). A runner may sign a job's receipt with such a key, certified just before it signs (scope `seal`): the receipt carries the certificate (Oxygen spec §14.6), and the hub keeps it when the certificate is this hub's, its subject is the run's repository and bookmark, its `run` and `job` claims are the run's and the job's, and it covers the moment the hub accepts it; no runner key is bound then, and the run names the signer as the runner's name with "(short-lived key)". Which issuers and subjects a repository trusts for changes and references is its policy's (docs/keyless.md, step 4). When a key it certified moves a bookmark, the hub signs an `accepted` attestation of the update with its own clock and serves it with the bookmark (Oxygen spec §14.7, step 4c), so fetches check the certificate at the hub's time. The scope given is what was asked within what the credential allows; asking for none of it is refused.

**Agent grants** (step 5, built 2026-10-17). An agent holds no key: its owner signs an Oxygen grant (§14.7) letting `agent:NAME@ACCOUNT` act for them, with the key their oxy home names (`oh agent grant NAME [--scope changes,seal,refs] [--for 30d]`), and `POST /api/v1/agents/grants {"grant": base64 signed grant}` keeps it and answers with the agent's token (`oxyagent_…`, shown once, kept as its BLAKE3 hash). The hub accepts a grant only for the caller's own `agent:NAME@USERNAME`, naming this hub's key as issuer, signed by a key linked to the caller's account and not yet ended; any personal token of the account may send it, since the signature is what authorises it. The agent exchanges the token at `keyless/certify` for ten-minute certificates carrying the grant (claims `agent` and `grant`, scope at most the grant's, never past its end), so what its fresh keys sign counts in the owner's name; oxy does this itself with `author.signer = keyless` and the token from `oxy auth grant`. `GET /api/v1/agents/grants` lists the caller's grants without tokens; `DELETE /api/v1/agents/grants/{id}` revokes one at once (`oh agent list`, `oh agent revoke ID`). Migration 0075 (`agent_grants`); audited as `agent.granted` and `agent.revoked`.