Hessra SDK

The primary interface for interacting with Hessra authentication services.

API Reference

This crate integrates functionality from these component crates:

• hessra-token: Token verification and attestation
• hessra-config: Configuration management
• hessra-api: HTTP client for the Hessra service

Detailed Usage

Creating a Client

use hessra_sdk::{HessraClient, Protocol};

// Basic client setup
let client = HessraClient::builder()
    .base_url("yourco.hessra.net")
    .protocol(Protocol::Http1)
    .build()?;

// More complete setup with mTLS certificates
let secure_client = HessraClient::builder()
    .base_url("yourco.hessra.net")
    .protocol(Protocol::Http1)
    .mtls_cert(include_str!("certs/client.crt"))
    .mtls_key(include_str!("certs/client.key"))
    .server_ca(include_str!("certs/ca.crt"))
    .build()?;

// Loading from environment variables
let env_client = HessraClient::from_env()?;

// Loading from a configuration file
let file_client = HessraClient::from_file("path/to/config.json")?;

Working with Tokens

// Request a token
let token = client.request_token("resource_name").await?;
println!("Token: {}", token);

// Simple token verification
let verification = client.verify_token(token.clone(), "resource_name").await?;
println!("Valid: {}", verification.is_valid);

// Local token verification (using cached public keys)
let local_verification = client.verify_token_local(token.clone(), "resource_name")?;
println!("Valid locally: {}", local_verification.is_valid);

// Update public keys cache for local verification
client.update_public_keys().await?;

Advanced: Service Chain Attestation

For services that need to verify tokens passed through multiple services:

use hessra_sdk::{ServiceChain, ServiceNode};

// Define the service chain (order matters!)
let service_chain = ServiceChain::builder()
    .add_node(ServiceNode {
        component: "gateway-service",
        public_key: "ed25519/abcdef1234567890",
    })
    .add_node(ServiceNode {
        component: "processing-service",
        public_key: "ed25519/0987654321fedcba",
    })
    .build();

// Verify a token with the service chain
client.verify_service_chain_token(
    token,
    "user:123",
    "data:read",
    &service_chain,
    None,
).await?;

// Local verification of service chain token
client.verify_service_chain_token_local(
    token,
    "user:123",
    "data:read",
    &service_chain,
    None,
)?;

Error Handling

The SDK provides a comprehensive error handling system:

use hessra_sdk::error::HessraError;

fn handle_token(token: &str) -> Result<(), HessraError> {
    match client.verify_token_local(token, "resource")? {
        verification if verification.is_valid => {
            println!("Token is valid!");
            Ok(())
        }
        _ => Err(HessraError::InvalidToken("Invalid token".to_string())),
    }
}

Feature Flags

• http3: Enables HTTP/3 protocol support via the hessra-api crate
• toml: Enables TOML configuration file support via the hessra-config crate
• wasm: Enables WebAssembly support for token verification via the hessra-token crate

Advanced Configuration

Customizing HTTP Clients

use hessra_sdk::{HessraClient, Protocol};
use std::time::Duration;

let client = HessraClient::builder()
    .base_url("yourco.hessra.net")
    .protocol(Protocol::Http1)
    .timeout(Duration::from_secs(30))
    .retry_attempts(3)
    .retry_backoff(Duration::from_millis(100))
    .build()?;

Using HTTP/3

When the http3 feature is enabled:

use hessra_sdk::{HessraClient, Protocol};

let client = HessraClient::builder()
    .base_url("yourco.hessra.net")
    .protocol(Protocol::Http3)
    .build()?;

License

Licensed under the Apache License, Version 2.0.