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.
• Issuer-attested: Each exposure block is a third-party biscuit block signed by the issuer’s keypair. Verifier rules and queries use trusting authority, {pubkey} to scope authorization decisions to issuer-attested facts only.
• Block-stacked: All labels added in a single call land in the same block.
• Inheritable: Child contexts inherit parent exposure via fork_context.
• Pure Datalog authorization: Exclusion checks run as biscuit deny policies. No string parsing on the authz path.

Authority Block

context(subject);
check if time($time), $time < expiration;
// optional, only if mint-time exposures supplied:
exposure(label_1);
exposure(label_2);
exposure_source(source);
exposure_time(timestamp);

Third-party exposure blocks (one per add_exposure call)

exposure(label_a);
exposure(label_b);
exposure_source(source);
exposure_time(timestamp);

Example

use hessra_context_token::{HessraContext, ContextVerifier, add_exposure};
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 (stacked into one third-party block, signed by the issuer)
let exposed = add_exposure(
    &token,
    &keypair,
    &["PII:SSN".to_string()],
    "data:user-ssn".to_string(),
).expect("Failed to add exposure");

// Verify with chained exclusion checks
ContextVerifier::new(exposed.clone(), public_key)
    .excludes("PII:email")
    .verify()
    .expect("PII:email is not attested");

assert!(ContextVerifier::new(exposed, public_key)
    .excludes("PII:SSN")
    .verify()
    .is_err());

Structs

Biscuit

This structure represents a valid Biscuit token

ContextInspectResult

Result of inspecting a context token.

ContextVerifier

Verifier for context tokens with a fluent builder for exclusion checks.

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

Append a batch of exposure labels to a context token in one third-party block.

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 attested by the issuer from a context token.

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