agent_uri_attestation/
lib.rs

1//! PASETO v4.public attestation for agent-uri.
2//!
3//! This crate provides cryptographic attestation of agent URIs using
4//! PASETO v4.public tokens (Ed25519 signatures). Attestations bind an
5//! agent URI to a set of capabilities, signed by a trust root.
6//!
7//! # Overview
8//!
9//! Attestation tokens enable:
10//! - Cryptographic binding of agent URIs to capabilities
11//! - Prevention of spoofing and DHT poisoning
12//! - Bearer token verification without callbacks
13//!
14//! # Example
15//!
16//! ```rust
17//! use agent_uri_attestation::{Issuer, Verifier, SigningKey};
18//! use agent_uri::AgentUri;
19//! use std::time::Duration;
20//!
21//! // Issuer side: create attestation
22//! let signing_key = SigningKey::generate();
23//! let issuer = Issuer::new("acme.com", signing_key.clone(), Duration::from_secs(86400));
24//!
25//! let uri = AgentUri::parse(
26//!     "agent://acme.com/workflow/approval/rule_01h455vb4pex5vsknk084sn02q"
27//! ).unwrap();
28//! let token = issuer.issue(&uri, vec!["workflow.approval.read".into()]).unwrap();
29//!
30//! // Verifier side: validate attestation
31//! let mut verifier = Verifier::new();
32//! verifier.add_trusted_root("acme.com", signing_key.verifying_key());
33//!
34//! let claims = verifier.verify(&token).unwrap();
35//! assert_eq!(claims.agent_uri, uri.to_string());
36//! assert_eq!(claims.capabilities, vec!["workflow.approval.read"]);
37//! ```
38//!
39//! # Token Structure
40//!
41//! Attestation tokens are PASETO v4.public tokens containing:
42//!
43//! - `agent_uri`: The full agent URI being attested
44//! - `capabilities`: Array of capability strings granted
45//! - `iss`: Issuer (trust root) that created the attestation
46//! - `iat`: Issued-at timestamp
47//! - `exp`: Expiration timestamp
48//! - `aud`: Optional audience restriction
49//!
50//! # Security Properties
51//!
52//! | Property | How Achieved |
53//! |----------|--------------|
54//! | No algorithm confusion | PASETO v4 is Ed25519-only |
55//! | Replay protection | `exp` claim validated automatically |
56//! | Trust root binding | `iss` must match trusted roots |
57//! | URI binding | `agent_uri` claim verified against expected |
58//! | Tamper detection | Ed25519 signature verification |
59//!
60//! # Grammar Specification
61//!
62//! This crate includes a formal ABNF grammar specification in `grammar.abnf`
63//! that defines:
64//!
65//! - PASETO v4.public token format (`v4.public.<payload>[.<footer>]`)
66//! - [`AttestationClaims`] JSON structure
67//! - Field formats and constraints
68//!
69//! The grammar follows RFC 5234 and references the agent-uri ABNF for
70//! the `agent_uri` field format.
71//!
72//! ## Length Constraints
73//!
74//! | Component | Max Length |
75//! |-----------|------------|
76//! | Total token | 8192 chars |
77//! | agent_uri | 512 chars |
78//! | capabilities | 64 items |
79//! | Each capability | 128 chars |
80//! | issuer | 128 chars |
81//! | audience | 128 chars |
82
83#![deny(missing_docs)]
84#![deny(clippy::all)]
85#![deny(clippy::pedantic)]
86#![allow(clippy::module_name_repetitions)]
87
88mod claims;
89mod error;
90mod issuer;
91mod keys;
92#[cfg(kani)]
93mod proofs;
94mod verification;
95mod verifier;
96
97pub use claims::{AttestationClaims, AttestationClaimsBuilder};
98pub use error::AttestationError;
99pub use issuer::Issuer;
100pub use keys::{SigningKey, VerifyingKey};
101pub use verification::{
102    capability_covers, check_capability_coverage, check_expiration, validate_issuer,
103    validate_subject,
104};
105pub use verifier::Verifier;
106
107/// A prelude module for convenient imports.
108///
109/// # Example
110///
111/// ```rust
112/// use agent_uri_attestation::prelude::*;
113/// ```
114pub mod prelude {
115    pub use crate::{
116        capability_covers, check_capability_coverage, check_expiration, validate_issuer,
117        validate_subject, AttestationClaims, AttestationClaimsBuilder, AttestationError, Issuer,
118        SigningKey, Verifier, VerifyingKey,
119    };
120}
agent_uri_attestation/lib.rs

agent_uri_attestation/
lib.rs
