Crate hessra_context_token 

Hessra Context Token

Context token implementation for information flow control (exposure tracking) in the Hessra authorization system.

Context tokens track what data an object (typically an AI agent) has been exposed to during a session. Each data access adds exposure labels as append-only Biscuit blocks, which downstream systems use to restrict available capabilities.

Key Properties

• Append-only: Exposure labels accumulate and cannot be removed within a session
• Cryptographically enforced: Each exposure block is signed, preventing forgery
• Inheritable: Child contexts inherit parent exposure via fork_context
• Stateless verification: Only a public key is needed to verify

Authority Block

context(subject);
check if time($time), $time < expiration;

Exposure Blocks

Each exposure addition appends a block with:

exposure("PII:SSN");
exposure_source("data:user-ssn");
exposure_time(1234567890);

Example

use hessra_context_token::{HessraContext, ContextVerifier, add_exposure, extract_exposure_labels};
use hessra_token_core::{KeyPair, TokenTimeConfig};

let keypair = KeyPair::new();
let public_key = keypair.public();

// Mint a fresh context token
let token = HessraContext::new("agent:openclaw".to_string(), TokenTimeConfig::default())
    .issue(&keypair)
    .expect("Failed to create context token");

// Add exposure labels
let exposed = add_exposure(
    &token,
    public_key,
    &["PII:SSN".to_string()],
    "data:user-ssn".to_string(),
).expect("Failed to add exposure");

// Extract exposure labels (diagnostic only)
let labels = extract_exposure_labels(&exposed, public_key)
    .expect("Failed to extract exposure");
assert_eq!(labels, vec!["PII:SSN".to_string()]);

// Verify the context token
ContextVerifier::new(exposed, public_key)
    .verify()
    .expect("Failed to verify context token");

Structs

Biscuit

This structure represents a valid Biscuit token

ContextInspectResult

Result of inspecting a context token.

ContextVerifier

Verifier for context tokens.

HessraContext

Builder for creating Hessra context tokens.

TokenTimeConfig

TokenTimeConfig allows control over token creation times and durations This is used to create tokens with custom start times and durations for testing purposes. In the future, this can be enhanced to support variable length tokens, such as long-lived bearer tokens.

Enums

KeyPair

pair of cryptographic keys used to sign a token’s block

PublicKey

the public part of a KeyPair

TokenError

Detailed error type for hessra-token operations with specific failure information

Functions

add_exposure

Add exposure labels to a context token.

decode_token

Decode a URL-safe base64 encoded token string to binary

encode_token

Encode binary token data to URL-safe base64 string

extract_exposure_labels

Extract all exposure labels from a context token by parsing its Biscuit blocks.

fork_context

Fork a context token for a sub-agent, inheriting the parent’s exposure.

inspect_context_token

Inspects a context token to extract session and exposure information.

parse_token

Extracts and parses a Biscuit token from a URL-safe base64 string

public_key_from_pem_file