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.
• Reject-based enforcement: Each label is recorded as a reject if exposure({label}) rule. A verifier asserts the labels it cares about as exposure({label}) facts; a matching reject rule fails authorization. Reject rules are monotonic and apply to the whole token regardless of which key signed them – any party (even an ephemeral key) can tighten a token, and no trusting scope is needed on the authz path.
• Enumerable: Each label is also recorded as an exposed_label({label}) metadata fact (a separate predicate the reject rules never test), queried with trusting authority, {pubkey} so only issuer-attested labels are reported.
• Block-stacked: All labels added in a single call land in the same block.
• Inheritable: Child contexts inherit parent exposure via fork_context.

Authority Block

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

Third-party exposure blocks (one per add_exposure call)

reject if exposure(label_a);
exposed_label(label_a);
reject if exposure(label_b);
exposed_label(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