Truthlinked SDK (Rust)

Official Rust SDK for Truthlinked Authority Fabric - Zero-Trust Authorization System

Features

• ✅ Type-safe API - Compile-time guarantees, no runtime surprises
• ✅ Secure by default - HTTPS-only, TLS validation, memory protection
• ✅ Production-ready - Connection pooling, timeouts, error handling
• ✅ Zero server coupling - Standalone SDK, no dependencies on server code
• ✅ Memory safe - License keys automatically zeroized
• ✅ No credential leakage - Safe error messages, redacted logging

Installation

Add to your Cargo.toml:

[dependencies]
truthlinked-sdk = "0.1"
tokio = { version = "1.0", features = ["full"] }

Quick Start

use truthlinked_sdk::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client
    let client = Client::new(
        "https://api.truthlinked.org",
        "tl_free_..."  // Your license key
    )?;
    
    // Check health
    let health = client.health().await?;
    println!("Status: {}", health.status);
    
    // Get shadow decisions (breach detections)
    let decisions = client.get_shadow_decisions().await?;
    let breaches = decisions.iter()
        .filter(|d| d.breach_prevented)
        .count();
    println!("Breaches prevented: {}", breaches);
    
    // Get compliance report
    let sox = client.get_sox_report().await?;
    println!("SOX: {} events", sox.total_events);
    
    Ok(())
}

Examples

Run examples with your license key:

export TRUTHLINKED_LICENSE_KEY="tl_free_..."

# Health check
cargo run --example health_check

# Shadow mode (breach detection)
cargo run --example shadow_report

# Compliance reports
cargo run --example compliance_report

# Usage statistics
cargo run --example usage_stats

API Reference

Client Creation

let client = Client::new(base_url, license_key)?;

Security:

• Enforces HTTPS (rejects HTTP)
• Validates TLS certificates
• 30-second timeout
• Connection pooling

Health Check

let health = client.health().await?;

No authentication required.

Shadow Mode (Breach Detection)

// Get breach detections
let decisions = client.get_shadow_decisions().await?;

// Replay IAM logs
let result = client.replay_iam_logs(logs, "aws-cloudtrail").await?;

Supported adapters:

• aws-cloudtrail - AWS CloudTrail logs
• azure-ad - Azure AD logs
• gcp-audit - GCP Audit logs
• okta - Okta System Log
• auth0 - Auth0 logs

Token Exchange

use rand::Rng;

// Generate nonce and channel binding
let nonce: [u8; 32] = rand::thread_rng().gen();
let channel_binding: [u8; 32] = rand::thread_rng().gen();

// Exchange SSO token for AF token
let response = client.exchange_token(
    sso_token,
    vec!["read:users".to_string()],
    nonce,
    channel_binding,
).await?;

println!("AF Token: {}", response.af_token);

Requires: Professional tier or higher

Token Validation

let result = client.validate_token(token_id).await?;

if result.valid {
    println!("Subject: {:?}", result.subject);
    println!("Scope: {:?}", result.scope);
}

Compliance Reports

// SOX compliance
let sox = client.get_sox_report().await?;
println!("Period: {}", sox.period);
println!("Events: {}", sox.total_events);
println!("Complete: {}", sox.audit_trail_complete);

// PCI-DSS compliance
let pci = client.get_pci_report().await?;
println!("Access controls: {}", pci.access_controls_enforced);
println!("Encryption: {}", pci.encryption_verified);

Audit Logs

let logs = client.get_audit_logs().await?;

for log in logs {
    println!("{}: {} by {}", log.timestamp, log.action, log.subject);
}

Usage Statistics

let usage = client.get_usage().await?;

println!("Tier: {}", usage.tier);
println!("Usage: {} / {}", usage.usage, usage.limit);
println!("Days remaining: {}", usage.days_remaining);

Error Handling

use truthlinked_sdk::TruthlinkedError;

match client.get_shadow_decisions().await {
    Ok(decisions) => println!("Got {} decisions", decisions.len()),
    Err(TruthlinkedError::Unauthorized) => {
        eprintln!("Invalid license key");
    }
    Err(TruthlinkedError::Forbidden) => {
        eprintln!("Tier doesn't allow this operation");
    }
    Err(TruthlinkedError::RateLimitExceeded(msg)) => {
        eprintln!("Rate limit: {}", msg);
    }
    Err(e) => eprintln!("Error: {}", e),
}

Security

Threat Mitigations

✅ T1: Credential Leakage

• License keys zeroized from memory
• Redacted in logs and errors
• Never serialized in full

✅ T2: Man-in-the-Middle

• HTTPS enforced (no HTTP fallback)
• TLS certificate validation
• Uses rustls (no OpenSSL)

✅ T3: Replay Attacks

• Nonce required for token exchange
• Timestamp validation server-side

✅ T4: Dependency Vulnerabilities

• Minimal dependencies (6 total)
• All dependencies audited
• No transitive vulnerabilities

✅ T5: Memory Safety

• Rust memory safety guarantees
• Zeroize for sensitive data
• No use-after-free possible

✅ T6: Information Disclosure

• Safe error messages
• No internal details leaked
• No stack traces in production

Best Practices

// ✅ DO: Store license key in environment
let key = std::env::var("TRUTHLINKED_LICENSE_KEY")?;

// ❌ DON'T: Hardcode license key
let key = "tl_free_...";  // Never do this!

// ✅ DO: Use HTTPS
Client::new("https://api.truthlinked.org", key)?;

// ❌ DON'T: Use HTTP
Client::new("http://api.truthlinked.org", key)?;  // Rejected!

// ✅ DO: Handle errors properly
match client.health().await {
    Ok(health) => println!("OK: {}", health.status),
    Err(e) => eprintln!("Error: {}", e),
}

// ❌ DON'T: Unwrap in production
let health = client.health().await.unwrap();  // Can panic!

License Tiers

Support

• Documentation: https://docs.truthlinked.org
• API Reference: https://docs.rs/truthlinked-sdk
• Issues: https://github.com/truth-linked/truthlinked-sdk/issues
• Email: support@truthlinked.org

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Built with ❤️ by Truthlinked