truthlinked_sdk/
lib.rs

1//! # Truthlinked SDK
2//!
3//! Official Rust SDK for **Truthlinked Authority Fabric** - Zero-Trust Authorization System
4//!
5//! ## Overview
6//!
7//! The Truthlinked Authority Fabric is a zero-trust authorization system that sits above
8//! traditional IAM systems (AWS IAM, Azure AD, Okta, etc.) as a final enforcement layer.
9//! It can override any IAM decision with cryptographic proof and provides breach detection
10//! through shadow mode analysis.
11//!
12//! ## Features
13//!
14//! - **Type-safe API**: Compile-time guarantees, no runtime surprises
15//! - **Secure by default**: HTTPS-only, TLS certificate validation, memory protection
16//! - **Production-ready**: Connection pooling, automatic retries, timeout handling
17//! - **Zero dependencies on server**: Standalone SDK, no coupling
18//! - **Memory safety**: License keys automatically zeroized from memory
19//! - **No credential leakage**: Safe error messages, redacted logging
20//!
21//! ## Security Architecture
22//!
23//! ### Threat Mitigations
24//!
25//! | Threat | Mitigation |
26//! |--------|------------|
27//! | **Credential Leakage** | License keys zeroized from memory, redacted in logs/errors |
28//! | **Man-in-the-Middle** | HTTPS enforced, TLS certificate validation, rustls |
29//! | **Replay Attacks** | Nonce support for token exchange, server-side validation |
30//! | **Dependency Vulnerabilities** | Minimal dependencies (6 total), all audited |
31//! | **Memory Safety** | Rust guarantees + zeroize for sensitive data |
32//! | **Information Disclosure** | Safe error messages, no internal details leaked |
33//!
34//! ### Security Guarantees
35//!
36//! - **HTTPS Enforcement**: HTTP requests are rejected at client creation
37//! - **Certificate Validation**: Self-signed certificates are rejected
38//! - **Memory Protection**: Sensitive data is zeroized when no longer needed
39//! - **Safe Error Handling**: Error messages never contain credentials or internal details
40//! - **Constant-Time Operations**: Where applicable, operations are constant-time
41//!
42//! ## Quick Start
43//!
44//! Add to your `Cargo.toml`:
45//! ```toml
46//! [dependencies]
47//! truthlinked-sdk = "0.1"
48//! tokio = { version = "1.0", features = ["full"] }
49//! ```
50//!
51//! Basic usage:
52//! ```rust,no_run
53//! use truthlinked_sdk::Client;
54//!
55//! #[tokio::main]
56//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
57//!     // Create client (enforces HTTPS)
58//!     let client = Client::new(
59//!         "https://api.truthlinked.org",
60//!         std::env::var("TRUTHLINKED_LICENSE_KEY")?
61//!     )?;
62//!     
63//!     // Check server health
64//!     let health = client.health().await?;
65//!     println!("Server status: {}", health.status);
66//!     
67//!     // Get shadow decisions (breach detections)
68//!     let decisions = client.get_shadow_decisions().await?;
69//!     let breaches = decisions.iter()
70//!         .filter(|d| d.breach_prevented)
71//!         .count();
72//!     println!("Breaches prevented: {}", breaches);
73//!     
74//!     // Get compliance reports
75//!     let sox = client.get_sox_report().await?;
76//!     println!("SOX compliance: {} events", sox.total_events);
77//!     
78//!     Ok(())
79//! }
80//! ```
81//!
82//! ## License Tiers
83//!
84//! | Tier | Price | Features |
85//! |------|-------|----------|
86//! | **Free** | $0/mo | Shadow mode, compliance reports, 1k requests/mo |
87//! | **Professional** | $2,500/mo | + Token exchange, 500k requests/mo |
88//! | **Enterprise** | $25,000/mo | + Full enforcement, unlimited requests |
89//! | **Government** | $100,000/mo | + Air-gapped deployment |
90//!
91//! ## Error Handling
92//!
93//! All errors implement `std::error::Error` and provide safe, actionable error messages:
94//!
95//! ```rust,no_run
96//! # use truthlinked_sdk::{Client, TruthlinkedError};
97//! # #[tokio::main]
98//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
99//! # let client = Client::new("https://api.truthlinked.org", "key")?;
100//! match client.get_shadow_decisions().await {
101//!     Ok(decisions) => println!("Got {} decisions", decisions.len()),
102//!     Err(TruthlinkedError::Unauthorized) => {
103//!         eprintln!("Invalid license key - check TRUTHLINKED_LICENSE_KEY");
104//!     }
105//!     Err(TruthlinkedError::Forbidden) => {
106//!         eprintln!("License tier doesn't support this operation");
107//!     }
108//!     Err(TruthlinkedError::RateLimitExceeded(msg)) => {
109//!         eprintln!("Rate limit exceeded: {}", msg);
110//!     }
111//!     Err(e) => eprintln!("Error: {}", e),
112//! }
113//! # Ok(())
114//! # }
115//! ```
116//!
117//! ## Best Practices
118//!
119//! ### Secure Configuration
120//! ```rust,no_run
121//! use truthlinked_sdk::Client;
122//! 
123//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
124//! // ✅ DO: Store license key in environment variable
125//! let key = std::env::var("TRUTHLINKED_LICENSE_KEY")?;
126//! let client = Client::new("https://api.truthlinked.org", key)?;
127//!
128//! // ❌ DON'T: Hardcode license keys
129//! let client = Client::new("https://api.truthlinked.org", "tl_free_...")?;
130//! # Ok(())
131//! # }
132//! ```
133//!
134//! ### Error Handling
135//! ```rust,no_run
136//! # use truthlinked_sdk::Client;
137//! # #[tokio::main]
138//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
139//! # let client = Client::new("https://api.truthlinked.org", "key")?;
140//! // ✅ DO: Handle errors gracefully
141//! match client.health().await {
142//!     Ok(health) => println!("Status: {}", health.status),
143//!     Err(e) => eprintln!("Health check failed: {}", e),
144//! }
145//!
146//! // ❌ DON'T: Use unwrap() in production
147//! let health = client.health().await.unwrap();  // Can panic!
148//! # Ok(())
149//! # }
150//! ```
151//!
152//! ### Thread Safety
153//! ```rust,no_run
154//! # use truthlinked_sdk::Client;
155//! # use std::sync::Arc;
156//! # #[tokio::main]
157//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
158//! // ✅ DO: Share client across threads with Arc
159//! let client = Arc::new(Client::new("https://api.truthlinked.org", "key")?);
160//! let client_clone = client.clone();
161//!
162//! tokio::spawn(async move {
163//!     let _ = client_clone.health().await;
164//! });
165//! # Ok(())
166//! # }
167//! ```
168//!
169//! ## Support
170//!
171//! - **Documentation**: <https://docs.truthlinked.org>
172//! - **API Reference**: <https://docs.rs/truthlinked-sdk>
173//! - **Issues**: <https://github.com/truthlinked/sdk/issues>
174//! - **Email**: support@truthlinked.org
175
176mod builder;
177mod client;
178mod error;
179mod license;
180mod logging;
181mod retry;
182mod signing;
183mod types;
184
185pub use builder::ClientBuilder;
186pub use client::Client;
187pub use error::{TruthlinkedError, Result};
188pub use logging::{LoggingConfig, LogLevel};
189pub use retry::RetryConfig;
190pub use types::*;
191
192// Re-export for convenience
193pub use license::LicenseKey;
194
195// Re-export specific items for testing
196pub use signing::RequestSigner;
197pub use retry::RetryExecutor;
198pub use logging::RequestLogger;
truthlinked_sdk/lib.rs

truthlinked_sdk/
lib.rs
