cert.rs 93.8%

305 of 325 lines run, 44 of 70 functions · run #381 on main · run missed

//! Certificates for short-lived keys (spec §14.7, oxygenhub#241,
//! oxygenhub docs/keyless.md). An issuer, a hub's key, binds a fresh key
//! to the identity that proved itself (an OIDC subject) for minutes: a Flow
//! job or an agent signs with that key and throws it away. The certificate
//! is signed with the issuer's composite key, so it is post-quantum like
//! every other signature in Oxygen.
//!
//! Whether to trust an issuer, and for which subjects, is the trust
//! policy's (§14.5); whether a signature was made inside the certificate's
//! window needs time the signer does not choose, which the caller passes
//! in (the transparency log's integrated time, §14.8, else a host's
//! acceptance).

use crate::cbor::{self, Value};
use crate::hash::{hash_object, KeyId, ObjectRef, ObjectType};
use crate::identity::{verify, Domain, Identity, Scope, SecretKey, Signature};
use crate::objects::{array, bytes, check_version, field, map, oref, text, uint, ObjectError};

/// The longest a certificate may be valid. Jobs get ten minutes; an hour
/// leaves room for an issuer that rounds up, and no more.
pub const MAX_LIFETIME_MS: u64 = 60 * 60 * 1000;

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Certificate {
    /// The short-lived key's public identity.
    pub key: Identity,
    /// The issuer's KeyId (a hub's key).
    pub issuer: KeyId,
    /// Who proved it: `repo:OWNER/NAME:bookmark:B`, `agent:NAME@ACCOUNT`.
    pub subject: String,
    /// What else the proof said (environment, run, job), sorted by name.
    pub claims: Vec<(String, String)>,
    /// What the key may sign: changes, refs, seals.
    pub scope: Scope,
    /// Valid from and until, in wall milliseconds.
    pub not_before: u64,
    pub expires: u64,
    /// 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>,
}

impl Certificate {
    pub fn to_value(&self) -> Value {
        let mut claims = self.claims.clone();
        claims.sort();
        let mut v = Value::map([
            (0, Value::Uint(1)),
            (1, Value::Bytes(self.key.encode())),
            (2, Value::Bytes(self.issuer.0.to_vec())),
            (3, Value::Text(self.subject.clone())),
            (
                4,
                Value::Array(
                    claims
                        .into_iter()
                        .map(|(k, v)| Value::Array(vec![Value::Text(k), Value::Text(v)]))
                        .collect(),
                ),
            ),
            (
                5,
                Value::Array(
                    self.scope
                        .names()
                        .into_iter()
                        .map(|n| Value::Text(n.to_string()))
                        .collect(),
                ),
            ),
            (6, Value::Uint(self.not_before)),
            (7, Value::Uint(self.expires)),
        ]);
        if let (Some(g), Value::Map(m)) = (&self.grant, &mut v) {
            m.insert(8, Value::Bytes(g.encode()));
        }
        v
    }

    pub fn encode(&self) -> Vec<u8> {
        cbor::encode(&self.to_value())
    }

    pub fn hash(&self) -> ObjectRef {
        hash_object(ObjectType::Certificate, &self.encode())
    }

    /// The short-lived key's KeyId: what its signatures name.
    pub fn key_id(&self) -> KeyId {
        self.key.hash()
    }

    pub fn decode(b: &[u8]) -> Result<Certificate, ObjectError> {
        let v = cbor::decode(b)?;
        let m = map(&v, "certificate")?;
        check_version(m)?;
        let key = Identity::decode(bytes(field(m, 1, "key")?, "key")?)?;
        let mut claims = Vec::new();
        for c in array(field(m, 4, "claims")?, "claims")? {
            let pair = array(c, "claim")?;
            if pair.len() != 2 {
                return Err(ObjectError::Schema("claim: expected [name, value]".into()));
            }
            claims.push((
                text(&pair[0], "claim name")?.to_owned(),
                text(&pair[1], "claim value")?.to_owned(),
            ));
        }
        let mut scope = Scope::NONE;
        for n in array(field(m, 5, "scope")?, "scope")? {
            let n = text(n, "scope")?;
            scope = scope
                | Scope::named(n).ok_or_else(|| {
                    ObjectError::Schema(format!("certificate: unknown scope {n:?}"))
                })?;
        }
        Ok(Certificate {
            key,
            issuer: oref(field(m, 2, "issuer")?, "issuer")?,
            subject: text(field(m, 3, "subject")?, "subject")?.to_owned(),
            claims,
            scope,
            not_before: uint(field(m, 6, "not_before")?, "not_before")?,
            expires: uint(field(m, 7, "expires")?, "expires")?,
            grant: match m.get(&8) {
                Some(g) => Some(
                    SignedGrant::decode(bytes(g, "grant")?)
                        .map_err(|e| ObjectError::Schema(format!("grant: {e}")))?,
                ),
                None => None,
            },
        })
    }

    /// Whether the key may sign within `scope` at `at_ms`, a time the
    /// signer did not choose.
    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
    }

    /// The claim called `name`, if the certificate has one.
    pub fn claim(&self, name: &str) -> Option<&str> {
        self.claims
            .iter()
            .find(|(k, _)| k == name)
            .map(|(_, v)| v.as_str())
    }
}

/// 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])?,
        })
    }
}

/// What a fresh key signs (a challenge, §14.3) to show its holder asks for
/// the certificate: bound to the credential it is asked with, so the
/// proof cannot be replayed with another.
pub fn certify_challenge(credential: &str) -> Vec<u8> {
    let mut c = b"oxy1 certify ".to_vec();
    c.extend_from_slice(blake3::hash(credential.as_bytes()).as_bytes());
    c
}

#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
pub enum CertError {
    #[error("the certificate names issuer {0}, not this one")]
    WrongIssuer(String),
    #[error("the issuer's signature does not verify: {0}")]
    BadSignature(String),
    #[error("the certificate is valid for no time, or for longer than an hour")]
    BadLifetime,
    #[error("the certificate gives no scope")]
    NoScope,
    #[error("{0}")]
    Schema(String),
}

impl From<ObjectError> for CertError {
    fn from(e: ObjectError) -> Self {
        CertError::Schema(e.to_string())
    }
}

/// A certificate with its issuer's signature over its ObjectRef.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SignedCertificate {
    pub cert: Certificate,
    pub sig: Signature,
}

impl SignedCertificate {
    /// Issue `cert`, signed by the issuer `issuer` holds the secret of.
    pub fn sign(mut cert: Certificate, issuer: &Identity, sk: &SecretKey) -> SignedCertificate {
        // Claims in their canonical order, as encoded.
        cert.claims.sort();
        let sig = sk.sign(Domain::Certificate, &issuer.hash(), &cert.hash());
        SignedCertificate { cert, sig }
    }

    /// Signed by `issuer`, which it names, and well formed. Whether to
    /// trust the issuer for its subject is the policy's question.
    pub fn verify(&self, issuer: &Identity) -> Result<(), CertError> {
        let c = &self.cert;
        if issuer.hash() != c.issuer || self.sig.key != c.issuer {
            return Err(CertError::WrongIssuer(c.issuer.short(12)));
        }
        verify(issuer, &self.sig, Domain::Certificate, &c.hash())
            .map_err(|e| CertError::BadSignature(e.to_string()))?;
        if c.expires <= c.not_before || c.expires - c.not_before > MAX_LIFETIME_MS {
            return Err(CertError::BadLifetime);
        }
        if c.scope.is_empty() {
            return Err(CertError::NoScope);
        }
        Ok(())
    }

    /// `[certificate bytes, signature]`.
    pub fn encode(&self) -> Vec<u8> {
        cbor::encode(&Value::Array(vec![
            Value::Bytes(self.cert.encode()),
            self.sig.to_value(),
        ]))
    }

    pub fn decode(b: &[u8]) -> Result<SignedCertificate, CertError> {
        let v = cbor::decode(b).map_err(ObjectError::from)?;
        let a = array(&v, "signed certificate")?;
        if a.len() != 2 {
            return Err(CertError::Schema(
                "signed certificate: expected [certificate, signature]".into(),
            ));
        }
        Ok(SignedCertificate {
            cert: Certificate::decode(bytes(&a[0], "certificate")?)?,
            sig: Signature::from_value(&a[1])?,
        })
    }
}

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

    fn issue(
        issuer_sk: &SecretKey,
        issuer: &Identity,
        minutes: u64,
    ) -> (SecretKey, SignedCertificate) {
        let job_sk = SecretKey::generate();
        let cert = Certificate {
            key: job_sk.identity("job 12 build", "[email protected]", 1_000),
            issuer: issuer.hash(),
            subject: "repo:andy/demo:bookmark:main".into(),
            claims: vec![
                ("run".into(), "12".into()),
                ("environment".into(), "prod".into()),
            ],
            scope: Scope::CHANGES | Scope::REFS,
            not_before: 1_000,
            expires: 1_000 + minutes * 60_000,
            grant: None,
        };
        (job_sk, SignedCertificate::sign(cert, issuer, issuer_sk))
    }

    #[test]
    fn a_certificate_round_trips_and_verifies_with_its_issuer_only() {
        let hub_sk = SecretKey::generate();
        let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
        let (_, sc) = issue(&hub_sk, &hub, 10);
        let back = SignedCertificate::decode(&sc.encode()).unwrap();
        assert_eq!(back, sc);
        assert_eq!(back.cert.claims[0].0, "environment", "claims kept sorted");
        assert_eq!(back.cert.claim("run"), Some("12"));
        assert!(back.verify(&hub).is_ok());
        let other_sk = SecretKey::generate();
        let other = other_sk.identity("elsewhere", "[email protected]", 1);
        assert!(matches!(
            back.verify(&other),
            Err(CertError::WrongIssuer(_))
        ));
        // Changed after signing: the signature no longer covers it.
        let mut forged = back.clone();
        forged.cert.subject = "repo:andy/demo:bookmark:release".into();
        assert!(matches!(
            forged.verify(&hub),
            Err(CertError::BadSignature(_))
        ));
        // Signed by another key in the issuer's name.
        let mut stolen = back.clone();
        stolen.sig = other_sk.sign(Domain::Certificate, &hub.hash(), &back.cert.hash());
        assert!(matches!(
            stolen.verify(&hub),
            Err(CertError::BadSignature(_))
        ));
    }

    #[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());
    }

    #[test]
    fn it_covers_its_scope_and_window_only() {
        let hub_sk = SecretKey::generate();
        let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
        let (_, sc) = issue(&hub_sk, &hub, 10);
        let c = &sc.cert;
        assert!(c.covers(Scope::CHANGES, 1_000) && c.covers(Scope::REFS, 1_000 + 10 * 60_000));
        assert!(!c.covers(Scope::SEAL, 2_000), "not a scope it gives");
        assert!(!c.covers(Scope::CHANGES, 999), "before it");
        assert!(
            !c.covers(Scope::CHANGES, 1_000 + 10 * 60_000 + 1),
            "after it"
        );
        assert!(!c.covers(Scope::NONE, 2_000));
        let (_, long) = issue(&hub_sk, &hub, 61);
        assert_eq!(long.verify(&hub), Err(CertError::BadLifetime));
    }

    #[test]
    fn the_proof_of_possession_is_bound_to_its_credential() {
        let sk = SecretKey::generate();
        let id = sk.identity("job", "[email protected]", 1);
        let proof = sk
            .sign_challenge(&id.hash(), &certify_challenge("flowjob_aaa"))
            .unwrap();
        assert!(
            crate::identity::verify_challenge(&id, &proof, &certify_challenge("flowjob_aaa"))
                .is_ok()
        );
        assert!(
            crate::identity::verify_challenge(&id, &proof, &certify_challenge("flowjob_bbb"))
                .is_err()
        );
    }

    #[test]
    fn a_signature_by_the_short_lived_key_names_it() {
        let hub_sk = SecretKey::generate();
        let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
        let (job_sk, sc) = issue(&hub_sk, &hub, 10);
        let target = ObjectRef([5; 32]);
        let sig = job_sk.sign(Domain::Change, &sc.cert.key_id(), &target);
        assert_eq!(sig.key, sc.cert.key_id());
        assert!(verify(&sc.cert.key, &sig, Domain::Change, &target).is_ok());
    }
}

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

1		//! Certificates for short-lived keys (spec §14.7, oxygenhub#241,
2		//! oxygenhub docs/keyless.md). An issuer, a hub's key, binds a fresh key
3		//! to the identity that proved itself (an OIDC subject) for minutes: a Flow
4		//! job or an agent signs with that key and throws it away. The certificate
5		//! is signed with the issuer's composite key, so it is post-quantum like
6		//! every other signature in Oxygen.
7		//!
8		//! Whether to trust an issuer, and for which subjects, is the trust
9		//! policy's (§14.5); whether a signature was made inside the certificate's
10		//! window needs time the signer does not choose, which the caller passes
11		//! in (the transparency log's integrated time, §14.8, else a host's
12		//! acceptance).
13
14		use crate::cbor::{self, Value};
15		use crate::hash::{hash_object, KeyId, ObjectRef, ObjectType};
16		use crate::identity::{verify, Domain, Identity, Scope, SecretKey, Signature};
17		use crate::objects::{array, bytes, check_version, field, map, oref, text, uint, ObjectError};
18
19		/// The longest a certificate may be valid. Jobs get ten minutes; an hour
20		/// leaves room for an issuer that rounds up, and no more.
21		pub const MAX_LIFETIME_MS: u64 = 60 * 60 * 1000;
22
23		#[derive(Clone, Debug, PartialEq, Eq)]
24		pub struct Certificate {
25		/// The short-lived key's public identity.
26		pub key: Identity,
27		/// The issuer's KeyId (a hub's key).
28		pub issuer: KeyId,
29		/// Who proved it: `repo:OWNER/NAME:bookmark:B`, `agent:NAME@ACCOUNT`.
30		pub subject: String,
31		/// What else the proof said (environment, run, job), sorted by name.
32		pub claims: Vec<(String, String)>,
33		/// What the key may sign: changes, refs, seals.
34		pub scope: Scope,
35		/// Valid from and until, in wall milliseconds.
36		pub not_before: u64,
37		pub expires: u64,
38		/// The grant that lets the subject act for an author, when an agent
39		/// asked with one (field 8, only when present).
40		pub grant: Option<SignedGrant>,
41		}
42
43		impl Certificate {
44	233×	pub fn to_value(&self) -> Value {
45	233×	let mut claims = self.claims.clone();
46	233×	claims.sort();
47	233×	let mut v = Value::map([
48	233×	(0, Value::Uint(1)),
49	233×	(1, Value::Bytes(self.key.encode())),
50	233×	(2, Value::Bytes(self.issuer.0.to_vec())),
51	233×	(3, Value::Text(self.subject.clone())),
52		(
53		4,
54		Value::Array(
55	233×	claims
56	233×	.into_iter()
57	233×	.map(\|(k, v)\| Value::Array(vec![Value::Text(k), Value::Text(v)]))
58	233×	.collect(),
59		),
60		),
61		(
62		5,
63		Value::Array(
64	233×	self.scope
65	233×	.names()
66	233×	.into_iter()
67	499×	.map(\|n\| Value::Text(n.to_string()))
68	233×	.collect(),
69		),
70		),
71	233×	(6, Value::Uint(self.not_before)),
72	233×	(7, Value::Uint(self.expires)),
73		]);
74	233×	if let (Some(g), Value::Map(m)) = (&self.grant, &mut v) {
75	48×	m.insert(8, Value::Bytes(g.encode()));
76	185×	}
77	233×	v
78	233×	}
79
80	233×	pub fn encode(&self) -> Vec<u8> {
81	233×	cbor::encode(&self.to_value())
82	233×	}
83
84	169×	pub fn hash(&self) -> ObjectRef {
85	169×	hash_object(ObjectType::Certificate, &self.encode())
86	169×	}
87
88		/// The short-lived key's KeyId: what its signatures name.
89	114×	pub fn key_id(&self) -> KeyId {
90	114×	self.key.hash()
91	114×	}
92
93	184×	pub fn decode(b: &[u8]) -> Result<Certificate, ObjectError> {
94	184×	let v = cbor::decode(b)?;
95	184×	let m = map(&v, "certificate")?;
96	184×	check_version(m)?;
97	184×	let key = Identity::decode(bytes(field(m, 1, "key")?, "key")?)?;
98	184×	let mut claims = Vec::new();
99	184×	for c in array(field(m, 4, "claims")?, "claims")? {
100	5×	let pair = array(c, "claim")?;
101	5×	if pair.len() != 2 {
102	0×	return Err(ObjectError::Schema("claim: expected [name, value]".into()));
103	5×	}
104	5×	claims.push((
105	5×	text(&pair[0], "claim name")?.to_owned(),
106	5×	text(&pair[1], "claim value")?.to_owned(),
107		));
108		}
109	184×	let mut scope = Scope::NONE;
110	394×	for n in array(field(m, 5, "scope")?, "scope")? {
111	394×	let n = text(n, "scope")?;
112	394×	scope = scope
113	394×	\| Scope::named(n).ok_or_else(\|\| {
114	0×	ObjectError::Schema(format!("certificate: unknown scope {n:?}"))
115	0×	})?;
116		}
117		Ok(Certificate {
118	184×	key,
119	184×	issuer: oref(field(m, 2, "issuer")?, "issuer")?,
120	184×	subject: text(field(m, 3, "subject")?, "subject")?.to_owned(),
121	184×	claims,
122	184×	scope,
123	184×	not_before: uint(field(m, 6, "not_before")?, "not_before")?,
124	184×	expires: uint(field(m, 7, "expires")?, "expires")?,
125	184×	grant: match m.get(&8) {
126	30×	Some(g) => Some(
127	30×	SignedGrant::decode(bytes(g, "grant")?)
128	30×	.map_err(\|e\| ObjectError::Schema(format!("grant: {e}")))?,
129		),
130	154×	None => None,
131		},
132		})
133	184×	}
134
135		/// Whether the key may sign within `scope` at `at_ms`, a time the
136		/// signer did not choose.
137	64×	pub fn covers(&self, scope: Scope, at_ms: u64) -> bool {
138	64×	!scope.is_empty()
139	63×	&& self.scope.has(scope)
140	61×	&& self.not_before <= at_ms
141	60×	&& at_ms <= self.expires
142	64×	}
143
144		/// The claim called `name`, if the certificate has one.
145	1×	pub fn claim(&self, name: &str) -> Option<&str> {
146	1×	self.claims
147	1×	.iter()
148	2×	.find(\|(k, _)\| k == name)
149	1×	.map(\|(_, v)\| v.as_str())
150	1×	}
151		}
152
153		/// An author's grant (spec §14.7): it lets the keys an issuer certifies
154		/// for `subject` act for the author, as a delegate does, without a key of
155		/// their own. An agent's fresh keys then sign and seal changes in the
156		/// author's name while the grant lasts; the grant travels inside their
157		/// certificates, so a verifier needs nothing else. Signed by the author.
158		#[derive(Clone, Debug, PartialEq, Eq)]
159		pub struct Grant {
160		/// The author's KeyId, which signs the grant.
161		pub grantor: KeyId,
162		/// The subject whose certified keys act for it: `agent:NAME@ACCOUNT`.
163		pub subject: String,
164		/// The issuer whose certificates count.
165		pub issuer: KeyId,
166		/// What they may do for the author: changes, seal.
167		pub scope: Scope,
168		/// Valid from and until, in wall milliseconds.
169		pub not_before: u64,
170		pub expires: u64,
171		}
172
173		impl Grant {
174	62×	pub fn to_value(&self) -> Value {
175	62×	Value::map([
176	62×	(0, Value::Uint(1)),
177	62×	(1, Value::Bytes(self.grantor.0.to_vec())),
178	62×	(2, Value::Text(self.subject.clone())),
179	62×	(3, Value::Bytes(self.issuer.0.to_vec())),
180		(
181		4,
182		Value::Array(
183	62×	self.scope
184	62×	.names()
185	62×	.into_iter()
186	124×	.map(\|n\| Value::Text(n.to_string()))
187	62×	.collect(),
188		),
189		),
190	62×	(5, Value::Uint(self.not_before)),
191	62×	(6, Value::Uint(self.expires)),
192		])
193	62×	}
194
195	62×	pub fn encode(&self) -> Vec<u8> {
196	62×	cbor::encode(&self.to_value())
197	62×	}
198
199	14×	pub fn hash(&self) -> ObjectRef {
200	14×	hash_object(ObjectType::Grant, &self.encode())
201	14×	}
202
203	30×	pub fn decode(b: &[u8]) -> Result<Grant, ObjectError> {
204	30×	let v = cbor::decode(b)?;
205	30×	let m = map(&v, "grant")?;
206	30×	check_version(m)?;
207	30×	let mut scope = Scope::NONE;
208	60×	for n in array(field(m, 4, "scope")?, "scope")? {
209	60×	let n = text(n, "scope")?;
210	60×	scope = scope
211	60×	\| Scope::named(n)
212	60×	.ok_or_else(\|\| ObjectError::Schema(format!("grant: unknown scope {n:?}")))?;
213		}
214		Ok(Grant {
215	30×	grantor: oref(field(m, 1, "grantor")?, "grantor")?,
216	30×	subject: text(field(m, 2, "subject")?, "subject")?.to_owned(),
217	30×	issuer: oref(field(m, 3, "issuer")?, "issuer")?,
218	30×	scope,
219	30×	not_before: uint(field(m, 5, "not_before")?, "not_before")?,
220	30×	expires: uint(field(m, 6, "expires")?, "expires")?,
221		})
222	30×	}
223
224		/// Whether it lets its subject do `scope` for the author at `at_ms`
225		/// (the change's own time, as for a delegation).
226	10×	pub fn covers(&self, scope: Scope, at_ms: u64) -> bool {
227	10×	!scope.is_empty()
228	10×	&& self.scope.has(scope)
229	9×	&& self.not_before <= at_ms
230	9×	&& at_ms <= self.expires
231	10×	}
232		}
233
234		/// A grant with its author's signature over its ObjectRef.
235		#[derive(Clone, Debug, PartialEq, Eq)]
236		pub struct SignedGrant {
237		pub grant: Grant,
238		pub sig: Signature,
239		}
240
241		impl SignedGrant {
242		/// Grant `grant`, signed by the author `grantor` holds the secret of.
243	6×	pub fn sign(grant: Grant, grantor: &Identity, sk: &SecretKey) -> SignedGrant {
244	6×	let sig = sk.sign(Domain::Grant, &grantor.hash(), &grant.hash());
245	6×	SignedGrant { grant, sig }
246	6×	}
247
248		/// Signed by `grantor`, which it names, and well formed.
249	9×	pub fn verify(&self, grantor: &Identity) -> Result<(), CertError> {
250	9×	let g = &self.grant;
251	9×	if grantor.hash() != g.grantor \|\| self.sig.key != g.grantor {
252	1×	return Err(CertError::WrongIssuer(g.grantor.short(12)));
253	8×	}
254	8×	verify(grantor, &self.sig, Domain::Grant, &g.hash())
255	8×	.map_err(\|e\| CertError::BadSignature(e.to_string()))?;
256	8×	if g.expires <= g.not_before {
257	0×	return Err(CertError::BadLifetime);
258	8×	}
259	8×	if g.scope.is_empty() {
260	0×	return Err(CertError::NoScope);
261	8×	}
262	8×	Ok(())
263	9×	}
264
265		/// `[grant bytes, signature]`.
266	48×	pub fn encode(&self) -> Vec<u8> {
267	48×	cbor::encode(&Value::Array(vec![
268	48×	Value::Bytes(self.grant.encode()),
269	48×	self.sig.to_value(),
270	48×	]))
271	48×	}
272
273	30×	pub fn decode(b: &[u8]) -> Result<SignedGrant, CertError> {
274	30×	let v = cbor::decode(b).map_err(ObjectError::from)?;
275	30×	let a = array(&v, "signed grant")?;
276	30×	if a.len() != 2 {
277	0×	return Err(CertError::Schema(
278	0×	"signed grant: expected [grant, signature]".into(),
279	0×	));
280	30×	}
281		Ok(SignedGrant {
282	30×	grant: Grant::decode(bytes(&a[0], "grant")?)?,
283	30×	sig: Signature::from_value(&a[1])?,
284		})
285	30×	}
286		}
287
288		/// What a fresh key signs (a challenge, §14.3) to show its holder asks for
289		/// the certificate: bound to the credential it is asked with, so the
290		/// proof cannot be replayed with another.
291	3×	pub fn certify_challenge(credential: &str) -> Vec<u8> {
292	3×	let mut c = b"oxy1 certify ".to_vec();
293	3×	c.extend_from_slice(blake3::hash(credential.as_bytes()).as_bytes());
294	3×	c
295	3×	}
296
297		#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
298		pub enum CertError {
299		#[error("the certificate names issuer {0}, not this one")]
300		WrongIssuer(String),
301		#[error("the issuer's signature does not verify: {0}")]
302		BadSignature(String),
303		#[error("the certificate is valid for no time, or for longer than an hour")]
304		BadLifetime,
305		#[error("the certificate gives no scope")]
306		NoScope,
307		#[error("{0}")]
308		Schema(String),
309		}
310
311		impl From<ObjectError> for CertError {
312	0×	fn from(e: ObjectError) -> Self {
313	0×	CertError::Schema(e.to_string())
314	0×	}
315		}
316
317		/// A certificate with its issuer's signature over its ObjectRef.
318		#[derive(Clone, Debug, PartialEq, Eq)]
319		pub struct SignedCertificate {
320		pub cert: Certificate,
321		pub sig: Signature,
322		}
323
324		impl SignedCertificate {
325		/// Issue `cert`, signed by the issuer `issuer` holds the secret of.
326	29×	pub fn sign(mut cert: Certificate, issuer: &Identity, sk: &SecretKey) -> SignedCertificate {
327		// Claims in their canonical order, as encoded.
328	29×	cert.claims.sort();
329	29×	let sig = sk.sign(Domain::Certificate, &issuer.hash(), &cert.hash());
330	29×	SignedCertificate { cert, sig }
331	29×	}
332
333		/// Signed by `issuer`, which it names, and well formed. Whether to
334		/// trust the issuer for its subject is the policy's question.
335	111×	pub fn verify(&self, issuer: &Identity) -> Result<(), CertError> {
336	111×	let c = &self.cert;
337	111×	if issuer.hash() != c.issuer \|\| self.sig.key != c.issuer {
338	2×	return Err(CertError::WrongIssuer(c.issuer.short(12)));
339	109×	}
340	109×	verify(issuer, &self.sig, Domain::Certificate, &c.hash())
341	109×	.map_err(\|e\| CertError::BadSignature(e.to_string()))?;
342	107×	if c.expires <= c.not_before \|\| c.expires - c.not_before > MAX_LIFETIME_MS {
343	1×	return Err(CertError::BadLifetime);
344	106×	}
345	106×	if c.scope.is_empty() {
346	0×	return Err(CertError::NoScope);
347	106×	}
348	106×	Ok(())
349	111×	}
350
351		/// `[certificate bytes, signature]`.
352	10×	pub fn encode(&self) -> Vec<u8> {
353	10×	cbor::encode(&Value::Array(vec![
354	10×	Value::Bytes(self.cert.encode()),
355	10×	self.sig.to_value(),
356	10×	]))
357	10×	}
358
359	10×	pub fn decode(b: &[u8]) -> Result<SignedCertificate, CertError> {
360	10×	let v = cbor::decode(b).map_err(ObjectError::from)?;
361	10×	let a = array(&v, "signed certificate")?;
362	10×	if a.len() != 2 {
363	0×	return Err(CertError::Schema(
364	0×	"signed certificate: expected [certificate, signature]".into(),
365	0×	));
366	10×	}
367		Ok(SignedCertificate {
368	10×	cert: Certificate::decode(bytes(&a[0], "certificate")?)?,
369	10×	sig: Signature::from_value(&a[1])?,
370		})
371	10×	}
372		}
373
374		#[cfg(test)]
375		mod tests {
376		use super::*;
377
378	5×	fn issue(
379	5×	issuer_sk: &SecretKey,
380	5×	issuer: &Identity,
381	5×	minutes: u64,
382	5×	) -> (SecretKey, SignedCertificate) {
383	5×	let job_sk = SecretKey::generate();
384	5×	let cert = Certificate {
385	5×	key: job_sk.identity("job 12 build", "[email protected]", 1_000),
386	5×	issuer: issuer.hash(),
387	5×	subject: "repo:andy/demo:bookmark:main".into(),
388	5×	claims: vec![
389	5×	("run".into(), "12".into()),
390	5×	("environment".into(), "prod".into()),
391	5×	],
392	5×	scope: Scope::CHANGES \| Scope::REFS,
393	5×	not_before: 1_000,
394	5×	expires: 1_000 + minutes * 60_000,
395	5×	grant: None,
396	5×	};
397	5×	(job_sk, SignedCertificate::sign(cert, issuer, issuer_sk))
398	5×	}
399
400		#[test]
401	1×	fn a_certificate_round_trips_and_verifies_with_its_issuer_only() {
402	1×	let hub_sk = SecretKey::generate();
403	1×	let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
404	1×	let (_, sc) = issue(&hub_sk, &hub, 10);
405	1×	let back = SignedCertificate::decode(&sc.encode()).unwrap();
406	1×	assert_eq!(back, sc);
407	1×	assert_eq!(back.cert.claims[0].0, "environment", "claims kept sorted");
408	1×	assert_eq!(back.cert.claim("run"), Some("12"));
409	1×	assert!(back.verify(&hub).is_ok());
410	1×	let other_sk = SecretKey::generate();
411	1×	let other = other_sk.identity("elsewhere", "[email protected]", 1);
412	1×	assert!(matches!(
413	1×	back.verify(&other),
414		Err(CertError::WrongIssuer(_))
415		));
416		// Changed after signing: the signature no longer covers it.
417	1×	let mut forged = back.clone();
418	1×	forged.cert.subject = "repo:andy/demo:bookmark:release".into();
419	1×	assert!(matches!(
420	1×	forged.verify(&hub),
421		Err(CertError::BadSignature(_))
422		));
423		// Signed by another key in the issuer's name.
424	1×	let mut stolen = back.clone();
425	1×	stolen.sig = other_sk.sign(Domain::Certificate, &hub.hash(), &back.cert.hash());
426	1×	assert!(matches!(
427	1×	stolen.verify(&hub),
428		Err(CertError::BadSignature(_))
429		));
430	1×	}
431
432		#[test]
433	1×	fn a_grant_rides_in_its_certificate_and_verifies_with_its_author_only() {
434	1×	let hub_sk = SecretKey::generate();
435	1×	let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
436	1×	let ada_sk = SecretKey::generate();
437	1×	let ada = ada_sk.identity("Ada", "[email protected]", 1);
438	1×	let g = SignedGrant::sign(
439	1×	Grant {
440	1×	grantor: ada.hash(),
441	1×	subject: "agent:claude@ada".into(),
442	1×	issuer: hub.hash(),
443	1×	scope: Scope::CHANGES \| Scope::SEAL,
444	1×	not_before: 1_000,
445	1×	expires: 2_000,
446	1×	},
447	1×	&ada,
448	1×	&ada_sk,
449		);
450	1×	assert!(g.verify(&ada).is_ok());
451	1×	assert!(g.verify(&hub).is_err(), "only its author's");
452	1×	assert!(g.grant.covers(Scope::SEAL, 1_500));
453	1×	assert!(!g.grant.covers(Scope::REFS, 1_500));
454	1×	assert!(!g.grant.covers(Scope::SEAL, 2_001));
455	1×	let (_, plain) = issue(&hub_sk, &hub, 10);
456	1×	assert!(
457	1×	!matches!(cbor::decode(&plain.cert.encode()).unwrap(), Value::Map(m) if m.contains_key(&8)),
458		"no grant, no field 8"
459		);
460	1×	let mut with = plain.cert.clone();
461	1×	with.grant = Some(g.clone());
462	1×	let sc = SignedCertificate::sign(with, &hub, &hub_sk);
463	1×	let back = SignedCertificate::decode(&sc.encode()).unwrap();
464	1×	assert_eq!(back.cert.grant, Some(g));
465	1×	assert!(back.verify(&hub).is_ok());
466	1×	assert_ne!(back.cert.hash(), plain.cert.hash());
467	1×	}
468
469		#[test]
470	1×	fn it_covers_its_scope_and_window_only() {
471	1×	let hub_sk = SecretKey::generate();
472	1×	let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
473	1×	let (_, sc) = issue(&hub_sk, &hub, 10);
474	1×	let c = &sc.cert;
475	1×	assert!(c.covers(Scope::CHANGES, 1_000) && c.covers(Scope::REFS, 1_000 + 10 * 60_000));
476	1×	assert!(!c.covers(Scope::SEAL, 2_000), "not a scope it gives");
477	1×	assert!(!c.covers(Scope::CHANGES, 999), "before it");
478	1×	assert!(
479	1×	!c.covers(Scope::CHANGES, 1_000 + 10 * 60_000 + 1),
480		"after it"
481		);
482	1×	assert!(!c.covers(Scope::NONE, 2_000));
483	1×	let (_, long) = issue(&hub_sk, &hub, 61);
484	1×	assert_eq!(long.verify(&hub), Err(CertError::BadLifetime));
485	1×	}
486
487		#[test]
488	1×	fn the_proof_of_possession_is_bound_to_its_credential() {
489	1×	let sk = SecretKey::generate();
490	1×	let id = sk.identity("job", "[email protected]", 1);
491	1×	let proof = sk
492	1×	.sign_challenge(&id.hash(), &certify_challenge("flowjob_aaa"))
493	1×	.unwrap();
494	1×	assert!(
495	1×	crate::identity::verify_challenge(&id, &proof, &certify_challenge("flowjob_aaa"))
496	1×	.is_ok()
497		);
498	1×	assert!(
499	1×	crate::identity::verify_challenge(&id, &proof, &certify_challenge("flowjob_bbb"))
500	1×	.is_err()
501		);
502	1×	}
503
504		#[test]
505	1×	fn a_signature_by_the_short_lived_key_names_it() {
506	1×	let hub_sk = SecretKey::generate();
507	1×	let hub = hub_sk.identity("oxygenhub.io", "[email protected]", 1);
508	1×	let (job_sk, sc) = issue(&hub_sk, &hub, 10);
509	1×	let target = ObjectRef([5; 32]);
510	1×	let sig = job_sk.sign(Domain::Change, &sc.cert.key_id(), &target);
511	1×	assert_eq!(sig.key, sc.cert.key_id());
512	1×	assert!(verify(&sc.cert.key, &sig, Domain::Change, &target).is_ok());
513	1×	}
514		}

Coverage / crates/oxy-core/src/cert.rs 93.8%

Keyboard