Grants let certified keys act for an author (keyless step 5a) a2387d547373

    /// The grant that lets the subject act for an author, when an agent

    /// asked with one (field 8, only when present).

    pub grant: Option<SignedGrant>,

        let mut v = Value::map([

        ]);

        if let (Some(g), Value::Map(m)) = (&self.grant, &mut v) {

            m.insert(8, Value::Bytes(g.encode()));

        }

        v

            grant: match m.get(&8) {

                Some(g) => Some(

                    SignedGrant::decode(bytes(g, "grant")?)

                        .map_err(|e| ObjectError::Schema(format!("grant: {e}")))?,

                ),

                None => None,

            },

}

/// An author's grant (spec §14.7): it lets the keys an issuer certifies

/// for `subject` act for the author, as a delegate does, without a key of

/// their own. An agent's fresh keys then sign and seal changes in the

/// author's name while the grant lasts; the grant travels inside their

/// certificates, so a verifier needs nothing else. Signed by the author.

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Grant {

    /// The author's KeyId, which signs the grant.

    pub grantor: KeyId,

    /// The subject whose certified keys act for it: `agent:NAME@ACCOUNT`.

    pub subject: String,

    /// The issuer whose certificates count.

    pub issuer: KeyId,

    /// What they may do for the author: changes, seal.

    pub scope: Scope,

    /// Valid from and until, in wall milliseconds.

    pub not_before: u64,

    pub expires: u64,

impl Grant {

    pub fn to_value(&self) -> Value {

        Value::map([

            (0, Value::Uint(1)),

            (1, Value::Bytes(self.grantor.0.to_vec())),

            (2, Value::Text(self.subject.clone())),

            (3, Value::Bytes(self.issuer.0.to_vec())),

            (

                4,

                Value::Array(

                    self.scope

                        .names()

                        .into_iter()

                        .map(|n| Value::Text(n.to_string()))

                        .collect(),

                ),

            ),

            (5, Value::Uint(self.not_before)),

            (6, Value::Uint(self.expires)),

        ])

    }

    pub fn encode(&self) -> Vec<u8> {

        cbor::encode(&self.to_value())

    }

    pub fn hash(&self) -> ObjectRef {

        hash_object(ObjectType::Grant, &self.encode())

    }

    pub fn decode(b: &[u8]) -> Result<Grant, ObjectError> {

        let v = cbor::decode(b)?;

        let m = map(&v, "grant")?;

        check_version(m)?;

        let mut scope = Scope::NONE;

        for n in array(field(m, 4, "scope")?, "scope")? {

            let n = text(n, "scope")?;

            scope = scope

                | Scope::named(n)

                    .ok_or_else(|| ObjectError::Schema(format!("grant: unknown scope {n:?}")))?;

        }

        Ok(Grant {

            grantor: oref(field(m, 1, "grantor")?, "grantor")?,

            subject: text(field(m, 2, "subject")?, "subject")?.to_owned(),

            issuer: oref(field(m, 3, "issuer")?, "issuer")?,

            scope,

            not_before: uint(field(m, 5, "not_before")?, "not_before")?,

            expires: uint(field(m, 6, "expires")?, "expires")?,

        })

    }

    /// Whether it lets its subject do `scope` for the author at `at_ms`

    /// (the change's own time, as for a delegation).

    pub fn covers(&self, scope: Scope, at_ms: u64) -> bool {

        !scope.is_empty()

            && self.scope.has(scope)

            && self.not_before <= at_ms

            && at_ms <= self.expires

    }

}

/// A grant with its author's signature over its ObjectRef.

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct SignedGrant {

    pub grant: Grant,

    pub sig: Signature,

}

impl SignedGrant {

    /// Grant `grant`, signed by the author `grantor` holds the secret of.

    pub fn sign(grant: Grant, grantor: &Identity, sk: &SecretKey) -> SignedGrant {

        let sig = sk.sign(Domain::Grant, &grantor.hash(), &grant.hash());

        SignedGrant { grant, sig }

    }

    /// Signed by `grantor`, which it names, and well formed.

    pub fn verify(&self, grantor: &Identity) -> Result<(), CertError> {

        let g = &self.grant;

        if grantor.hash() != g.grantor || self.sig.key != g.grantor {

            return Err(CertError::WrongIssuer(g.grantor.short(12)));

        }

        verify(grantor, &self.sig, Domain::Grant, &g.hash())

            .map_err(|e| CertError::BadSignature(e.to_string()))?;

        if g.expires <= g.not_before {

            return Err(CertError::BadLifetime);

        }

        if g.scope.is_empty() {

            return Err(CertError::NoScope);

        }

        Ok(())

    }

    /// `[grant bytes, signature]`.

    pub fn encode(&self) -> Vec<u8> {

        cbor::encode(&Value::Array(vec![

            Value::Bytes(self.grant.encode()),

            self.sig.to_value(),

        ]))

    }

    pub fn decode(b: &[u8]) -> Result<SignedGrant, CertError> {

        let v = cbor::decode(b).map_err(ObjectError::from)?;

        let a = array(&v, "signed grant")?;

        if a.len() != 2 {

            return Err(CertError::Schema(

                "signed grant: expected [grant, signature]".into(),

            ));

        }

        Ok(SignedGrant {

            grant: Grant::decode(bytes(&a[0], "grant")?)?,

            sig: Signature::from_value(&a[1])?,

        })

    }

}

            grant: None,

    }

    #[test]

    fn a_grant_rides_in_its_certificate_and_verifies_with_its_author_only() {

        let hub_sk = SecretKey::generate();

        let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);

        let ada_sk = SecretKey::generate();

        let ada = ada_sk.identity("Ada", "[email protected]", 1);

        let g = SignedGrant::sign(

            Grant {

                grantor: ada.hash(),

                subject: "agent:claude@ada".into(),

                issuer: hub.hash(),

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

                not_before: 1_000,

                expires: 2_000,

            },

            &ada,

            &ada_sk,

        );

        assert!(g.verify(&ada).is_ok());

        assert!(g.verify(&hub).is_err(), "only its author's");

        assert!(g.grant.covers(Scope::SEAL, 1_500));

        assert!(!g.grant.covers(Scope::REFS, 1_500));

        assert!(!g.grant.covers(Scope::SEAL, 2_001));

        let (_, plain) = issue(&hub_sk, &hub, 10);

        assert!(

            !matches!(cbor::decode(&plain.cert.encode()).unwrap(), Value::Map(m) if m.contains_key(&8)),

            "no grant, no field 8"

        );

        let mut with = plain.cert.clone();

        with.grant = Some(g.clone());

        let sc = SignedCertificate::sign(with, &hub, &hub_sk);

        let back = SignedCertificate::decode(&sc.encode()).unwrap();

        assert_eq!(back.cert.grant, Some(g));

        assert!(back.verify(&hub).is_ok());

        assert_ne!(back.cert.hash(), plain.cert.hash());

    /// An author's grant to a certified subject (§14.7).

    Grant,

    pub const ALL: [ObjectType; 12] = [

        ObjectType::Grant,

            ObjectType::Grant => "grant",

    /// An author's grant to a certified subject (§14.7).

    Grant,

            Domain::Grant => "grant",

                grant: None,

                    grant: None,

        ObjectType::Grant => crate::cert::Grant::decode(body).map(|_| ()),

    /// Whether `signer` is a short-lived key acting for `author` under a

    /// grant (spec §14.7): its certificate verifies with its issuer and

    /// carries a grant `author` signed, for the certificate's subject and

    /// issuer, giving `needed` at `at_ms` (the change's time, as for a

    /// delegation). Whether the certificate covered the time it signed is

    /// the policy's check, at a time the signer did not choose. `None`

    /// when it does; otherwise why not.

    fn granted(

        &self,

        author: &KeyId,

        signer: &KeyId,

        needed: Scope,

        at_ms: u64,

    ) -> std::result::Result<Option<String>, String> {

        let neither = || {

            Some(format!(

                "key {} is neither the author nor a delegate",

                signer.short(12)

            ))

        };

        let Ok(Some(c)) = self.store.certificate_of(signer) else {

            return Ok(neither());

        };

        let Ok(sc) = self.store.get_certificate(&c) else {

            return Ok(neither());

        };

        let Some(g) = &sc.cert.grant else {

            return Ok(neither());

        };

        let who = signer.short(12);

        let issuer = self

            .store

            .get_identity(&sc.cert.issuer)

            .map_err(|_| format!("key {who}'s certificate names an unknown issuer"))?;

        sc.verify(&issuer)

            .map_err(|e| format!("key {who}'s certificate: {e}"))?;

        if g.grant.grantor != *author {

            return Ok(neither());

        }

        let grantor = self

            .store

            .get_identity(author)

            .map_err(|_| format!("key {who}'s grant is by an unknown author"))?;

        g.verify(&grantor)

            .map_err(|e| format!("key {who}'s grant: {e}"))?;

        if g.grant.subject != sc.cert.subject || g.grant.issuer != sc.cert.issuer {

            return Err(format!(

                "key {who}'s grant is for {} from issuer {}, not its certificate's",

                g.grant.subject,

                g.grant.issuer.short(12)

            ));

        }

        if !sc.cert.scope.has(needed) || !g.grant.scope.has(needed) {

            return Err(format!("key {who} is not granted {needed}"));

        }

        if !g.grant.covers(needed, at_ms) {

            return Err(format!(

                "key {who}'s grant did not cover the time the change was made"

            ));

        }

        Ok(None)

    }

                // A certified key acting under the author's grant (§14.7).

                    if let Some(why) =

                        self.granted(&change.author, &sig.key, needed, change.hlc.wall_ms)?

                    {

                        return Err(why);

                    }

    }

    /// Whether `signer` seals changes by `author`: its own, anonymous ones

    /// (§14.4), and, when it signs for the configured author (a delegate,

    /// or a short-lived key under the author's grant, §14.7), the

    /// author's. A receiver still checks it may.

    pub(crate) fn seals_for_author(&self, author: &KeyId, signer: &KeyId) -> bool {

        author == signer

            || author.is_zero()

            || (self.config.signer_key.is_some() && self.config.author_key == Some(*author))

    /// but has not: its own unsigned ones, anonymous ones, and the

    /// author's when it signs for them.

            if self.seals_for_author(&meta.author, &key)

                if self.seals_for_author(&c.author, &key)

                grant: None,

/// Keyless step 5 (oxygenhub#241): an agent's fresh key, certified for a

/// subject the author granted, seals changes in the author's name; with

/// no grant, a stranger's, or one that had ended, it is neither the

/// author nor a delegate.

fn a_certified_key_acts_for_its_author_under_a_grant() {

    use crate::cert::{Certificate, Grant, SignedCertificate, SignedGrant};

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

    hermetic();

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

    let root = dir.path();

    let _origin = Repo::init(&root.join("origin")).unwrap();

    let url = root.join("origin").to_string_lossy().to_string();

    let mut a = Repo::clone(&url, &root.join("a"))

        .unwrap()

        .with_home(root.join("home-a"));

    let (ada, _) = a

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

        .unwrap();

    write(&root.join("a"), "a.txt", b"a\n");

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

    a.policy_init().unwrap();

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

    let hub_sk = SecretKey::generate();

    let hub = hub_sk.identity("hub", "[email protected]", 1);

    a.policy_grant_subject(

        "agent:claude@ada",

        hub.clone(),

        Scope::CHANGES | Scope::REFS,

        None,

    )

    .unwrap();

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

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

    let ada_id = a.identity(&ada).unwrap();

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

    let grant = |by: &Identity, sk: &SecretKey, from: u64, to: u64| {

        SignedGrant::sign(

            Grant {

                grantor: by.hash(),

                subject: "agent:claude@ada".into(),

                issuer: hub.hash(),

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

                not_before: from,

                expires: to,

            },

            by,

            sk,

        )

    };

    // Ada's work as an agent runs it: Ada the author, a fresh key the hub

    // certified (with `g` inside) the signer.

    let agent = |name: &str, g: Option<SignedGrant>| {

        let mut r = Repo::clone(&url, &root.join(name))

            .unwrap()

            .with_home(root.join(format!("home-{name}")));

        let (key, id) = r

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

            .unwrap();

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

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

        let cert = SignedCertificate::sign(

            Certificate {

                key: id,

                issuer: hub.hash(),

                subject: "agent:claude@ada".into(),

                claims: vec![],

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

                not_before: now - 60_000,

                expires: now + 600_000,

                grant: g,

            },

            &hub,

            &hub_sk,

        );

        r.store().put_identity(&hub).unwrap();

        r.store().put_certificate(&cert).unwrap();

        write(&root.join(name), &format!("{name}.txt"), b"agent work\n");

        let h = r.commit("work", &[]).unwrap();

        assert_eq!(r.store().get_change_meta(&h).unwrap().author, ada);

        (r, key, h)

    };

    let (claude, key, h) = agent(

        "claude",

        Some(grant(&ada_id, &ada_sk, now - 60_000, now + 86_400_000)),

    );

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

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

    let host = Repo::open(&root.join("origin")).unwrap();

    assert!(matches!(

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

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

    ));

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

    assert!(matches!(

        a.authenticate_change(&h).unwrap(),

        SignatureStatus::Valid { key: k, .. } if k == key

    ));

    let (none, _, _) = agent("none", None);

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

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

    let mallory_sk = SecretKey::generate();

    let mallory = mallory_sk.identity("Mallory", "[email protected]", 1);

    let (stranger, _, _) = agent(

        "stranger",

        Some(grant(&mallory, &mallory_sk, now - 60_000, now + 600_000)),

    );

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

    assert!(r.iter().all(|x| !x.ok), "a stranger's grant: {r:?}");

    let (ended, _, eh) = agent(

        "ended",

        Some(grant(&ada_id, &ada_sk, now - 7_200_000, now - 3_600_000)),

    );

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

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

    assert!(matches!(

        ended.authenticate_change(&eh).unwrap(),

        SignatureStatus::Invalid(e) if e.contains("grant did not cover")

    ));

}

#[test]

            grant: None,

domain  = "change" | "attest" | "policy" | "certificate" | "grant"

**Verification.** A sealed change `C` is authenticated iff a seal `S` exists such that `hash(C) ∈ S.body.hashes`, `S` carries a valid signature from key `K`, and `K` equals `C.author` or is listed in `C.author`'s identity as a delegate with the `seal` scope, not expired at `C.hlc.wall_ms` (§14.2). The same author-or-delegate rule applies to individual change signatures, with the `changes` scope. This rule is what stops a collaborator from sealing a change whose `author` field names someone else (§3.1). A change whose `author` is the zero KeyId names nobody (history imported from Git, §21, or made before an identity existed), so a seal from any key authenticates it: the sealer **adopts** it, and policy authorizes the sealer for the reference as usual. A push seals the pusher's own unauthenticated changes and adopts anonymous ones in the same seal; a pusher that signs for its configured author (`author.signer`: a delegate, or a short-lived key under the author's grant, §14.7) seals the author's as well, and the receiver checks it may. A seal's signer must additionally be authorized by policy for the reference being pushed.

  grant       [8]: bytes          // optional: a signed grant (below), only when present

**Grants.** An author lets the keys an issuer certifies for a subject act for it, as a delegate does but without a key of their own (an agent's fresh keys, oxygenhub docs/keyless.md):

```

Grant {

  version     [0]: 1

  grantor     [1]: KeyId          // the author, whose key signs the grant

  subject     [2]: text           // "agent:NAME@ACCOUNT"

  issuer      [3]: KeyId          // whose certificates for the subject count

  scope       [4]: [text]         // changes, seal

  not_before  [5]: u64            // wall milliseconds

  expires     [6]: u64

}

```

A signed grant is `[grant bytes, Signature]`: the grantor's composite signature, in domain `grant`, over the grant's ObjectRef (type `grant`). It needs no maximum lifetime: it gives nothing until an issuer certifies a key under it, and the grantor revokes it by asking the issuer to stop. The issuer puts it in each certificate it issues under it (field 8), so it travels with the certificate and a verifier needs nothing else. A signature by a key that is neither a change's author nor its delegate (§14.4) still satisfies the author-or-delegate rule when the key's certificate verifies with its issuer and carries a grant that verifies with the change's author, names the certificate's subject and issuer, gives the scope needed (`changes` for a change signature, `seal` for a seal) in both the grant and the certificate, and covers the change's `hlc.wall_ms`, as a delegation does. Whether the certificate covered the time the key signed is the policy's check (§14.5), at a time the signer did not choose.