Crate hessra_context_token 

Hessra Context Token

Context token implementation for information flow control (taint 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 taint labels as append-only Biscuit blocks, which downstream systems use to restrict available capabilities.

Key Properties

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

Authority Block

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

Taint Blocks

Each taint addition appends a block with:

taint("PII:SSN");
taint_source("data:user-ssn");
taint_time(1234567890);

Example

use hessra_context_token::{HessraContext, ContextVerifier, add_taint, extract_taint_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 taint labels
let tainted = add_taint(
    &token,
    public_key,
    &["PII:SSN".to_string()],
    "data:user-ssn".to_string(),
).expect("Failed to add taint");

// Extract taint labels
let labels = extract_taint_labels(&tainted, public_key)
    .expect("Failed to extract taint");
assert_eq!(labels, vec!["PII:SSN".to_string()]);

// Verify the context token
ContextVerifier::new(tainted, 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_taint

Add taint 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_taint_labels

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

fork_context

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

inspect_context_token

Inspects a context token to extract session and taint information.

parse_token

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

public_key_from_pem_file