Hessra Token

Unified token library for Hessra authentication and authorization.

This crate provides a combined interface for both authorization tokens and identity tokens used in the Hessra system. It re-exports functionality from the specialized token crates and is designed to be WASM-compatible with no networking dependencies.

Crate Structure

This is an umbrella crate that re-exports:

hessra-token-core: Shared utilities and types
hessra-token-authz: Authorization token functionality
hessra-token-identity: Identity token functionality

Features

Authorization Tokens

Token creation: Create new tokens with configurable time settings and operations
Multi-party tokens: Create tokens that require signoffs from multiple authorization services
Token verification: Verify tokens without contacting the authorization server
Token attestation: Add service node attestations to tokens
Multi-party attestation: Add attestations for multi-party authorization workflows

Identity Tokens

Hierarchical identities: URI-based identity system with delegation support
Identity token creation: Create identity tokens for authentication
Identity delegation: Attenuate tokens to sub-identities with restricted permissions
Offline verification: Verify identity tokens locally using public keys

General

WASM compatibility: Can be compiled to WebAssembly for use in browsers (via the wasm feature)
No network dependencies: Pure token operations without requiring network access

Usage

Creating Tokens

use hessra_token::{create_biscuit, create_service_chain_biscuit, TokenTimeConfig, KeyPair};

fn main() -> Result<(), hessra_token::TokenError> {
    // Create a key pair for token signing
    let keypair = KeyPair::new();

    // Create a basic token with default time settings (5 minutes)
    let token = create_biscuit(
        "user123".to_string(),
        "resource456".to_string(),
        "read".to_string(),
        keypair,
        TokenTimeConfig::default(),
    )?;

    // Create a token with custom time settings
    let custom_time = TokenTimeConfig {
        start_time: Some(chrono::Utc::now().timestamp()),
        duration: 3600, // 1 hour
    };

    let custom_token = create_biscuit(
        "user123".to_string(),
        "resource456".to_string(),
        "read".to_string(),
        keypair,
        custom_time,
    )?;

    println!("Tokens created successfully!");
    Ok(())
}

Creating Service Chain Tokens

use hessra_token::{create_service_chain_biscuit, ServiceNode, KeyPair};

fn main() -> Result<(), hessra_token::TokenError> {
    let keypair = KeyPair::new();

    // Define service nodes in the chain
    let service_nodes = vec![
        ServiceNode {
            component: "auth_service".to_string(),
            public_key: "ed25519/service1key".to_string(),
        },
        ServiceNode {
            component: "payment_service".to_string(),
            public_key: "ed25519/service2key".to_string(),
        },
    ];

    // Create a service chain token
    let token = create_service_chain_biscuit(
        "user123".to_string(),
        "resource456".to_string(),
        "read".to_string(),
        keypair,
        &service_nodes,
    )?;

    println!("Service chain token created successfully!");
    Ok(())
}

Basic Token Verification

use hessra_token::{verify_token, biscuit_key_from_string};

fn main() -> Result<(), hessra_token::TokenError> {
    // Your URL-safe base64-encoded token
    let token_base64 = "YOUR_TOKEN_STRING";

    // Parse public key from string format (ed25519/{hex} or secp256r1/{hex})
    let public_key = biscuit_key_from_string("ed25519/01234567890abcdef".to_string())?;

    // Verify the token
    verify_token(token_base64, public_key, "user123", "resource456", "read")?;

    println!("Token verification successful!");
    Ok(())
}

Service Chain Verification

For tokens that need to be verified against a chain of service nodes:

use hessra_token::{verify_service_chain_token, biscuit_key_from_string, ServiceNode};

fn main() -> Result<(), hessra_token::TokenError> {
    let token_base64 = "YOUR_TOKEN_STRING";
    let public_key = biscuit_key_from_string("ed25519/01234567890abcdef".to_string())?;

    // Define the service chain
    let service_nodes = vec![
        ServiceNode {
            component: "service1".to_string(),
            public_key: "ed25519/service1pubkey".to_string(),
        },
        ServiceNode {
            component: "service2".to_string(),
            public_key: "ed25519/service2pubkey".to_string(),
        },
    ];

    // Verify the token with service chain
    verify_service_chain_token(
        token_base64,
        public_key,
        "user123",
        "resource456",
        "write",
        service_nodes,
        None, // Verify full chain, or specify a component to verify up to
    )?;

    println!("Token verification successful!");
    Ok(())
}

Multi-Party Token Creation

Create tokens that require signoffs from multiple authorization services:

use hessra_token::{create_multi_party_token, ServiceNode, KeyPair, TokenTimeConfig};

fn main() -> Result<(), hessra_token::TokenError> {
    let keypair = KeyPair::new();

    // Define multi-party signers
    let multi_party_nodes = vec![
        ServiceNode {
            component: "finance_approval".to_string(),
            public_key: "ed25519/finance_service_key".to_string(),
        },
        ServiceNode {
            component: "security_approval".to_string(),
            public_key: "ed25519/security_service_key".to_string(),
        },
    ];

    // Create a multi-party token
    let token = create_multi_party_token(
        "user123".to_string(),
        "sensitive_resource".to_string(),
        "admin".to_string(),
        keypair,
        &multi_party_nodes,
    )?;

    println!("Multi-party token created: {}", token);
    Ok(())
}

Token Attestation

To add service node attestations to tokens:

use hessra_token::{add_service_node_attestation, decode_token, encode_token, KeyPair, PublicKey};

fn main() -> Result<(), hessra_token::TokenError> {
    let token_base64 = "YOUR_TOKEN_STRING";
    let token_bytes = decode_token(token_base64)?;

    // Public key for token verification
    let public_key = PublicKey::from_bytes(b"example_key", biscuit_auth::Algorithm::Ed25519)?;

    // Service node key pair
    let service_keypair = KeyPair::new();

    // Add service node attestation
    let attested_token = add_service_node_attestation(
        token_bytes,
        public_key,
        "my-service",
        &service_keypair,
    )?;

    // Encode back to URL-safe base64 for storage or transmission
    let attested_token_base64 = encode_token(&attested_token);

    println!("Token attestation: {}", attested_token_base64);
    Ok(())
}

Multi-Party Token Attestation

Add attestations for multi-party authorization workflows:

use hessra_token::{add_multi_party_attestation_to_token, KeyPair};

fn main() -> Result<(), hessra_token::TokenError> {
    let token_base64 = "YOUR_MULTI_PARTY_TOKEN";

    // Service key pair for attestation
    let service_keypair = KeyPair::new();

    // Add multi-party attestation
    let attested_token = add_multi_party_attestation_to_token(
        token_base64,
        service_keypair.public(),
        "finance_approval",
        &service_keypair,
    )?;

    println!("Multi-party attested token: {}", attested_token);
    Ok(())
}

WebAssembly Support

To compile with WebAssembly support, enable the wasm feature:

[dependencies]
hessra-token = { version = "0.6", features = ["wasm"] }

Lower-level API

If you need more control, lower-level functions are also available:

verify_biscuit_local - Directly verify binary token data
verify_service_chain_biscuit_local - Verify binary token data with service chain
parse_token - Parse a URL-safe base64 token string into a Biscuit for inspection
decode_token - Convert URL-safe base64 encoded token to binary data
encode_token - Convert binary token data to URL-safe base64 string

Development

This crate is part of the Hessra SDK refactoring project. It provides the token functionality that was previously part of the monolithic SDK.

Token Operations

The library supports specifying operations when creating and verifying tokens. Common operations include:

read: Read access to a resource
write: Write access to a resource
delete: Delete access to a resource
admin: Administrative access to a resource

You can define your own operations as needed for your application.

Service Chain Tokens

For service chain tokens, you can specify operations in the same way:

use hessra_token::{create_service_chain_token, verify_service_chain_token_local, ServiceNode};

let nodes = vec![
    ServiceNode {
        component: "auth_service".to_string(),
        public_key: "ed25519/...".to_string(),
    }
];

let token = create_service_chain_token(
    "user123".to_string(),
    "resource456".to_string(),
    "read".to_string(),
    keypair,
    &nodes,
)?;

verify_service_chain_token_local(
    &token,
    public_key,
    "user123",
    "resource456",
    "read",
    nodes,
    None,
)?;

Low-Level Functions

If you need more control, lower-level functions are also available:

verify_biscuit_local - Directly verify binary token data
verify_service_chain_biscuit_local - Verify binary token data with service chain
parse_token - Parse a URL-safe base64 token string into a Biscuit for inspection
decode_token - Convert URL-safe base64 encoded token to binary data
encode_token - Convert binary token data to URL-safe base64 string

Development

This crate is part of the Hessra SDK refactoring project. It provides the token functionality that was previously part of the monolithic SDK.

hessra-token 0.6.3

Hessra Token

Crate Structure

Features

Authorization Tokens

Identity Tokens

General

Usage

Creating Tokens

Creating Service Chain Tokens

Basic Token Verification

Service Chain Verification

Multi-Party Token Creation

Token Attestation

Multi-Party Token Attestation

WebAssembly Support

Lower-level API

Development

Token Operations

Service Chain Tokens

Low-Level Functions

Development