hessra_context_token/
lib.rs

1//! # Hessra Context Token
2//!
3//! Context token implementation for information flow control (exposure tracking)
4//! in the Hessra authorization system.
5//!
6//! Context tokens track what data an object (typically an AI agent) has been
7//! exposed to during a session. Each data access adds exposure labels as
8//! append-only Biscuit blocks, which downstream systems use to restrict
9//! available capabilities.
10//!
11//! ## Key Properties
12//!
13//! - **Append-only**: Exposure labels accumulate and cannot be removed within a session
14//! - **Cryptographically enforced**: Each exposure block is signed, preventing forgery
15//! - **Inheritable**: Child contexts inherit parent exposure via `fork_context`
16//! - **Stateless verification**: Only a public key is needed to verify
17//!
18//! ## Authority Block
19//!
20//! ```datalog
21//! context(subject);
22//! check if time($time), $time < expiration;
23//! ```
24//!
25//! ## Exposure Blocks
26//!
27//! Each exposure addition appends a block with:
28//! ```datalog
29//! exposure("PII:SSN");
30//! exposure_source("data:user-ssn");
31//! exposure_time(1234567890);
32//! ```
33//!
34//! ## Example
35//!
36//! ```rust
37//! use hessra_context_token::{HessraContext, ContextVerifier, add_exposure, extract_exposure_labels};
38//! use hessra_token_core::{KeyPair, TokenTimeConfig};
39//!
40//! let keypair = KeyPair::new();
41//! let public_key = keypair.public();
42//!
43//! // Mint a fresh context token
44//! let token = HessraContext::new("agent:openclaw".to_string(), TokenTimeConfig::default())
45//!     .issue(&keypair)
46//!     .expect("Failed to create context token");
47//!
48//! // Add exposure labels
49//! let exposed = add_exposure(
50//!     &token,
51//!     public_key,
52//!     &["PII:SSN".to_string()],
53//!     "data:user-ssn".to_string(),
54//! ).expect("Failed to add exposure");
55//!
56//! // Extract exposure labels (diagnostic only)
57//! let labels = extract_exposure_labels(&exposed, public_key)
58//!     .expect("Failed to extract exposure");
59//! assert_eq!(labels, vec!["PII:SSN".to_string()]);
60//!
61//! // Verify the context token
62//! ContextVerifier::new(exposed, public_key)
63//!     .verify()
64//!     .expect("Failed to verify context token");
65//! ```
66
67mod exposure;
68mod inspect;
69mod mint;
70mod verify;
71
72pub use exposure::{add_exposure, extract_exposure_labels, fork_context};
73pub use inspect::{ContextInspectResult, inspect_context_token};
74pub use mint::HessraContext;
75pub use verify::ContextVerifier;
76
77// Re-export commonly needed types from core
78pub use hessra_token_core::{
79    Biscuit, KeyPair, PublicKey, TokenError, TokenTimeConfig, decode_token, encode_token,
80    parse_token, public_key_from_pem_file,
81};
hessra_context_token/lib.rs

hessra_context_token/
lib.rs
