instruction-md 0.3.0

Read, check, resolve and verify instruction.md documents (the specification's first edition, instruction/1): the reader, the agent text, composition and signature verification
Documentation
//! Attestations: JWS/EdDSA author and delivery signatures (Ed25519, by `ring`). An author signature binds a
//! version's authored digest; a delivery signature binds what one reader received — the delivered text's digest — and
//! the resolution it came from (its manifest: the resolved artifact's format, status, document, dependencies and
//! digest, never its body), with the author signature embedded so the chain is checked in one place.

use std::time::{SystemTime, UNIX_EPOCH};

use ring::signature::{ED25519, Ed25519KeyPair, KeyPair, UnparsedPublicKey};
use serde_json::{Map, Value};

use crate::digest::digest;
use crate::js::{is_str, js_number, js_value};
use crate::types::Object;

/// A JSON Web Key (OKP / Ed25519 keys are what a registry publishes).
pub type Jwk = Object;

/// A verification's outcome: ok with the claims, or not ok with a stable code and the reason.
#[derive(Clone, Debug, PartialEq)]
pub struct VerifyResult {
    pub ok: bool,
    /// What happened, for a program to match on (one of [`VERIFY_CODES`]): `ok`, or why not.
    pub code: &'static str,
    /// The verified claims: the author attestation's, or the delivery attestation's.
    pub claims: Option<Object>,
    /// A verified delivery's embedded author attestation's claims ([`verify_delivery`] only).
    pub author: Option<Object>,
    /// For a person: why not (the TypeScript reference's wording); empty when ok.
    pub reason: String,
}

/// Every [`VerifyResult::code`]:
///
/// | Code | When |
/// |---|---|
/// | `ok` | verified |
/// | `malformed` | not a compact JWS, or a part that is not base64url JSON |
/// | `unknown-key` | no key in the set is an Ed25519 JWK to try (an empty set, or none usable) |
/// | `bad-algorithm` | the header's `alg` is not EdDSA |
/// | `bad-signature` | no key in the set verifies the signature |
/// | `unknown-format` | the `spec` claim is not `instruction/1` |
/// | `typ-mismatch` | the `typ` claim (or the header's) is not the attestation expected (author, delivery) |
/// | `expired` | the `exp` claim is past |
/// | `digest-mismatch` | a digest is not the bytes': the authored bytes' (author), the delivered bytes' (delivery), or the resolved document's (the embedded author's) |
/// | `doc-mismatch` | the author's `doc` is not the one expected, or the embedded author's doc or version is not the delivery's |
/// | `unpinned-publisher` | the publisher (`pub`) is not the pinned one |
/// | `audience-mismatch` | the delivery's `aud` is not this reader |
/// | `manifest-invalid` | the delivery does not name its resolution (format instruction-resolved/1, document, dependencies, resolved_digest) |
/// | `author-missing` | the delivery embeds no author signature |
/// | `capabilities-exceeded` | the delivery's capabilities exceed the author attestation's |
///
/// A delivery whose embedded author signature fails has that signature's code (`bad-signature`, `expired`…).
pub const VERIFY_CODES: &[&str] = &[
    "ok",
    "malformed",
    "unknown-key",
    "bad-algorithm",
    "bad-signature",
    "unknown-format",
    "typ-mismatch",
    "expired",
    "digest-mismatch",
    "doc-mismatch",
    "unpinned-publisher",
    "audience-mismatch",
    "manifest-invalid",
    "author-missing",
    "capabilities-exceeded",
];

impl VerifyResult {
    fn fail(code: &'static str, reason: impl Into<String>) -> VerifyResult {
        VerifyResult { ok: false, code, claims: None, author: None, reason: reason.into() }
    }
}

const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";

/// Base64url without padding.
pub fn b64url_encode(data: &[u8]) -> String {
    let mut out = String::with_capacity(data.len().div_ceil(3) * 4);
    for chunk in data.chunks(3) {
        let n = chunk.iter().enumerate().fold(0u32, |acc, (i, &b)| acc | (b as u32) << (16 - 8 * i));
        let chars = chunk.len() + 1;
        for k in 0..chars {
            out.push(ALPHABET[((n >> (18 - 6 * k)) & 63) as usize] as char);
        }
    }
    out
}

/// Base64url, padding optional.
pub fn b64url_decode(s: &str) -> Result<Vec<u8>, String> {
    let s = s.trim_end_matches('=');
    let mut out = Vec::with_capacity(s.len() * 3 / 4);
    let mut acc = 0u32;
    let mut bits = 0;
    for (i, c) in s.bytes().enumerate() {
        let v = match c {
            b'A'..=b'Z' => c - b'A',
            b'a'..=b'z' => c - b'a' + 26,
            b'0'..=b'9' => c - b'0' + 52,
            b'-' => 62,
            b'_' => 63,
            _ => return Err(format!("illegal base64 data at input byte {i}")),
        };
        acc = acc << 6 | v as u32;
        bits += 6;
        if bits >= 8 {
            bits -= 8;
            out.push((acc >> bits) as u8);
            acc &= (1 << bits) - 1;
        }
    }
    if s.len() % 4 == 1 {
        return Err(format!("illegal base64 data at input byte {}", s.len()));
    }
    Ok(out)
}

fn ed25519_public_key(jwk: &Jwk) -> Result<Vec<u8>, String> {
    let x = jwk.get("x").and_then(Value::as_str).unwrap_or("");
    if !is_str(jwk.get("kty"), "OKP") || !is_str(jwk.get("crv"), "Ed25519") || x.is_empty() {
        return Err("not an Ed25519 JWK".into());
    }
    match b64url_decode(x) {
        Ok(raw) if raw.len() == 32 => Ok(raw),
        _ => Err("bad Ed25519 public key".into()),
    }
}

fn claim(claims: &Object, key: &str) -> String {
    js_value(claims.get(key))
}

fn now() -> i64 {
    SystemTime::now().duration_since(UNIX_EPOCH).map_or(0, |d| d.as_secs() as i64)
}

fn verify_jws(jws: &str, keys: &[Jwk], expected_typ: &str, now: i64) -> VerifyResult {
    let parts: Vec<&str> = jws.split('.').collect();
    if parts.len() != 3 {
        return VerifyResult::fail("malformed", "signature: Invalid Compact JWS");
    }
    let mut last_err = ("unknown-key", "no key verified the signature".to_string());
    let malformed = |e: String| ("malformed", e);
    for jwk in keys {
        let attempt = || -> Result<VerifyResult, (&'static str, String)> {
            let key = ed25519_public_key(jwk).map_err(|e| ("unknown-key", e))?;
            let hb = b64url_decode(parts[0]).map_err(malformed)?;
            let header: Map<String, Value> = serde_json::from_slice(&hb).map_err(|e| malformed(e.to_string()))?;
            if !is_str(header.get("alg"), "EdDSA") {
                return Err(("bad-algorithm", "\"alg\" (Algorithm) Header Parameter value not allowed".into()));
            }
            let sig = b64url_decode(parts[2]).map_err(malformed)?;
            let signing = format!("{}.{}", parts[0], parts[1]);
            UnparsedPublicKey::new(&ED25519, &key)
                .verify(signing.as_bytes(), &sig)
                .map_err(|_| ("bad-signature", "signature verification failed".to_string()))?;
            let pb = b64url_decode(parts[1]).map_err(malformed)?;
            let claims: Map<String, Value> = serde_json::from_slice(&pb).map_err(|e| malformed(e.to_string()))?;
            if !is_str(claims.get("spec"), "instruction/1") {
                return Ok(VerifyResult::fail(
                    "unknown-format",
                    format!("signature: unknown attestation format \"{}\"", claim(&claims, "spec")),
                ));
            }
            if !is_str(claims.get("typ"), expected_typ) {
                return Ok(VerifyResult::fail(
                    "typ-mismatch",
                    format!("signature: expected typ \"{expected_typ}\", found \"{}\"", claim(&claims, "typ")),
                ));
            }
            if let Some(Value::String(ht)) = header.get("typ")
                && !ht.is_empty()
                && ht != expected_typ
            {
                return Ok(VerifyResult::fail("typ-mismatch", format!("signature: header typ \"{ht}\" disagrees with the claim")));
            }
            if let Some(exp) = claims.get("exp").and_then(Value::as_f64)
                && exp < now as f64
            {
                return Ok(VerifyResult::fail("expired", format!("signature: expired at {}", js_number(exp))));
            }
            Ok(VerifyResult { ok: true, code: "ok", claims: Some(claims), author: None, reason: String::new() })
        };
        match attempt() {
            Ok(r) => return r,
            Err(e) => last_err = e,
        }
    }
    VerifyResult::fail(last_err.0, format!("signature: {}", last_err.1))
}

/// What narrows an author verification: the expected doc, the pinned publisher, the clock.
#[derive(Clone, Debug, Default)]
pub struct VerifyOptions {
    /// The document the signature must name (its `doc` claim); empty: any.
    pub doc: String,
    /// The pinned publisher (its `pub` claim); empty: any.
    pub publisher: String,
    /// Unix seconds; `None`: now.
    pub now: Option<i64>,
}

/// Verifies an author signature over the authored bytes with a pinned publisher key set.
pub fn verify_author(jws: &str, authored: &[u8], keys: &[Jwk], o: &VerifyOptions) -> VerifyResult {
    let r = verify_jws(jws, keys, "author", o.now.unwrap_or_else(now));
    let Some(c) = r.claims.as_ref().filter(|_| r.ok) else { return r };
    if !is_str(c.get("digest"), &digest(authored)) {
        return VerifyResult::fail("digest-mismatch", "author: digest does not match the authored bytes");
    }
    if !o.doc.is_empty() && !is_str(c.get("doc"), &o.doc) {
        return VerifyResult::fail("doc-mismatch", format!("author: doc \"{}\" is not \"{}\"", claim(c, "doc"), o.doc));
    }
    if !o.publisher.is_empty() && !is_str(c.get("pub"), &o.publisher) {
        return VerifyResult::fail("unpinned-publisher", format!("publisher \"{}\" is not pinned in instruction_sources", claim(c, "pub")));
    }
    r
}

/// What a delivery verification checks beyond the signatures.
#[derive(Clone, Debug, Default)]
pub struct DeliveryVerifyOptions {
    /// This reader's audience (required): the delivery's `aud` claim must be it.
    pub aud: String,
    /// The authored bytes, when known: the author claim's digest must be theirs.
    pub authored: Option<Vec<u8>>,
    /// The pinned publisher; empty: any.
    pub publisher: String,
    /// Unix seconds; `None`: now.
    pub now: Option<i64>,
}

/// Verifies a delivery signature over the delivered bytes, then the embedded author signature (§7.6 steps 2–3). The
/// delivery's manifest names its resolution — `{format: instruction-resolved/1, status, document: {uri, sha256,
/// version?}, dependencies, resolved_digest}` ([`crate::Manifest`]) — and the author's digest is the resolved
/// document's sha256. When ok, `claims` are the delivery's and `author` the embedded author attestation's, both
/// verified.
pub fn verify_delivery(jws: &str, delivered: &[u8], delivery_keys: &[Jwk], author_keys: &[Jwk], o: &DeliveryVerifyOptions) -> VerifyResult {
    let now = o.now.unwrap_or_else(now);
    let r = verify_jws(jws, delivery_keys, "delivery", now);
    let Some(c) = r.claims.as_ref().filter(|_| r.ok) else { return r };
    if !is_str(c.get("aud"), &o.aud) {
        return VerifyResult::fail("audience-mismatch", format!("delivery: aud \"{}\" is not this reader", claim(c, "aud")));
    }
    if !is_str(c.get("digest"), &digest(delivered)) {
        return VerifyResult::fail("digest-mismatch", "delivery: digest does not match the received bytes");
    }
    let manifest = c.get("manifest").and_then(Value::as_object);
    let document_digest = manifest.and_then(|m| m.get("document")).and_then(|d| d.get("sha256")).and_then(Value::as_str);
    let has_resolved = manifest.and_then(|m| m.get("resolved_digest")).is_some_and(Value::is_string);
    let has_dependencies = manifest.and_then(|m| m.get("dependencies")).is_some_and(Value::is_array);
    let (Some(_), Some(document_digest)) = (manifest.filter(|m| is_str(m.get("format"), "instruction-resolved/1")), document_digest) else {
        return VerifyResult::fail(
            "manifest-invalid",
            "manifest: the delivery names its resolution (format instruction-resolved/1, document, dependencies, resolved_digest)",
        );
    };
    if !has_resolved || !has_dependencies {
        return VerifyResult::fail(
            "manifest-invalid",
            "manifest: the delivery names its resolution (format instruction-resolved/1, document, dependencies, resolved_digest)",
        );
    }
    let Some(Value::String(author)) = c.get("author") else {
        return VerifyResult::fail("author-missing", "delivery: embedded author signature is required");
    };
    let a = verify_jws(author, author_keys, "author", now);
    let Some(ac) = a.claims.as_ref().filter(|_| a.ok) else { return a };
    if !crate::js::same_scalar(ac.get("doc"), c.get("doc")) || !crate::js::same_scalar(ac.get("version"), c.get("version")) {
        return VerifyResult::fail("doc-mismatch", "author: doc/version disagree with the delivery claims");
    }
    if !is_str(ac.get("digest"), document_digest) {
        return VerifyResult::fail("digest-mismatch", "author: digest does not equal the resolved document's sha256");
    }
    if let Some(authored) = &o.authored
        && !is_str(ac.get("digest"), &digest(authored))
    {
        return VerifyResult::fail("digest-mismatch", "author: digest does not match the authored bytes");
    }
    if !o.publisher.is_empty() && !is_str(ac.get("pub"), &o.publisher) {
        return VerifyResult::fail(
            "unpinned-publisher",
            format!("publisher \"{}\" is not pinned in instruction_sources", claim(ac, "pub")),
        );
    }
    let author_caps = capabilities(ac.get("capabilities"));
    let mut excess = Vec::new();
    if let Some(Value::Array(delivered)) = c.get("capabilities") {
        for x in delivered {
            let s = js_value(Some(x));
            if !author_caps.contains(&s) {
                excess.push(s);
            }
        }
    }
    if !excess.is_empty() {
        return VerifyResult::fail(
            "capabilities-exceeded",
            format!("delivery: capabilities [{}] exceed the author attestation [{}]", excess.join(", "), author_caps.join(", ")),
        );
    }
    let author = Some(ac.clone());
    VerifyResult { author, ..r }
}

/// A claim's capability list as text, each once, in order (a set's).
fn capabilities(v: Option<&Value>) -> Vec<String> {
    let mut out: Vec<String> = Vec::new();
    if let Some(Value::Array(list)) = v {
        for x in list {
            let s = js_value(Some(x));
            if !out.contains(&s) {
                out.push(s);
            }
        }
    }
    out
}

/// An Ed25519 signing key — for tests and tooling; a registry signs with its own keys.
pub struct SigningKey {
    pair: Ed25519KeyPair,
}

impl SigningKey {
    /// The key of a 32-byte seed (an Ed25519 private key).
    pub fn from_seed(seed: &[u8]) -> Result<SigningKey, String> {
        Ed25519KeyPair::from_seed_unchecked(seed).map(|pair| SigningKey { pair }).map_err(|_| "an Ed25519 seed is 32 bytes".to_string())
    }

    /// A new random key.
    pub fn generate() -> Result<SigningKey, String> {
        let rng = ring::rand::SystemRandom::new();
        let pkcs8 = Ed25519KeyPair::generate_pkcs8(&rng).map_err(|_| "no randomness".to_string())?;
        Ed25519KeyPair::from_pkcs8(pkcs8.as_ref()).map(|pair| SigningKey { pair }).map_err(|_| "a bad key".to_string())
    }

    /// The public key's 32 bytes.
    pub fn public_key(&self) -> Vec<u8> {
        self.pair.public_key().as_ref().to_vec()
    }

    /// The public key as a JWK (OKP, Ed25519), with a key id when one is given.
    pub fn public_jwk(&self, kid: &str) -> Jwk {
        public_jwk(&self.public_key(), kid)
    }
}

/// The JWK of an Ed25519 public key.
pub fn public_jwk(public_key: &[u8], kid: &str) -> Jwk {
    let mut jwk = Jwk::new();
    jwk.insert("kty".into(), "OKP".into());
    jwk.insert("crv".into(), "Ed25519".into());
    jwk.insert("x".into(), b64url_encode(public_key).into());
    if !kid.is_empty() {
        jwk.insert("kid".into(), kid.into());
    }
    jwk
}

/// Signs claims as a compact EdDSA JWS.
pub fn sign_jws(claims: &Object, key: &SigningKey, typ: &str) -> String {
    let mut header = Map::new();
    header.insert("alg".into(), "EdDSA".into());
    if !typ.is_empty() {
        header.insert("typ".into(), typ.into());
    }
    let hb = serde_json::to_vec(&Value::Object(header)).unwrap_or_default();
    let pb = serde_json::to_vec(&Value::Object(claims.clone())).unwrap_or_default();
    let signing = format!("{}.{}", b64url_encode(&hb), b64url_encode(&pb));
    let sig = key.pair.sign(signing.as_bytes());
    format!("{signing}.{}", b64url_encode(sig.as_ref()))
}

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

    #[test]
    fn base64url() {
        for data in [&b""[..], b"f", b"fo", b"foo", b"foob", b"fooba", b"foobar", &[0xff, 0xfe, 0x00]] {
            assert_eq!(b64url_decode(&b64url_encode(data)).unwrap(), data);
        }
        assert_eq!(b64url_encode(b"foobar"), "Zm9vYmFy");
        assert_eq!(b64url_encode(&[0xfb, 0xff]), "-_8");
        assert!(b64url_decode("a!b").is_err());
    }
}