cachekit_core/lib.rs
1//! # cachekit-core
2//!
3//! LZ4 compression, xxHash3 integrity, AES-256-GCM encryption — for arbitrary byte payloads.
4//!
5//! This crate transforms bytes: compress them, verify their integrity, encrypt them.
6//! Bytes in, bytes out.
7//!
8//! ## Features
9//!
10//! | Feature | Description | Default |
11//! |:--------|:------------|:-------:|
12//! | `compression` | LZ4 compression via `lz4_flex` | Yes |
13//! | `checksum` | xxHash3-64 integrity verification | Yes |
14//! | `encryption` | AES-256-GCM + HKDF-SHA256 (ring on native, aes-gcm on wasm32) | No |
15//! | `ffi` | C header generation | No |
16//!
17//! ## Platform Support
18//!
19//! Compiles on both native targets and `wasm32-unknown-unknown` (Cloudflare Workers).
20//! On wasm32, encryption uses RustCrypto's `aes-gcm` (pure Rust) instead of `ring`.
21//! Both backends produce identical AES-256-GCM wire format.
22//!
23//! ## Quick Start
24//!
25//! ```rust,no_run
26//! use cachekit_core::ByteStorage;
27//!
28//! let storage = ByteStorage::new(None);
29//! let data = b"Hello, cachekit!";
30//!
31//! // Store: compress + checksum
32//! let envelope = storage.store(data, None).unwrap();
33//!
34//! // Retrieve: decompress + verify
35//! let (retrieved, _format) = storage.retrieve(&envelope).unwrap();
36//! assert_eq!(data.as_slice(), retrieved.as_slice());
37//! ```
38//!
39//! ## With Encryption
40//!
41//! ```rust,ignore
42//! use cachekit_core::{ZeroKnowledgeEncryptor, derive_domain_key};
43//!
44//! // Derive tenant-isolated key
45//! let master_key = [0u8; 32]; // Use secure key in production!
46//! let tenant_key = derive_domain_key(&master_key, "cache", b"tenant-123").unwrap();
47//!
48//! // Encrypt
49//! let encryptor = ZeroKnowledgeEncryptor::new();
50//! let ciphertext = encryptor.encrypt_aes_gcm(b"secret", &tenant_key, b"tenant-123").unwrap();
51//!
52//! // Decrypt
53//! let plaintext = encryptor.decrypt_aes_gcm(&ciphertext, &tenant_key, b"tenant-123").unwrap();
54//! ```
55//!
56//! ## Security Properties
57//!
58//! - **AES-256-GCM**: Authenticated encryption via `ring`
59//! - **HKDF-SHA256**: Key derivation with tenant isolation (RFC 5869)
60//! - **xxHash3-64**: Fast non-cryptographic checksums (corruption detection)
61//! - **Nonce safety**: Counter-based + random IV prevents reuse
62//! - **Memory safety**: `zeroize` on drop for all key material
63
64// Metrics and observability
65pub mod metrics;
66pub use metrics::OperationMetrics;
67
68// Core byte storage layer
69pub mod byte_storage;
70pub use byte_storage::{ByteStorage, StorageEnvelope};
71
72// Encryption module (feature-gated)
73#[cfg(feature = "encryption")]
74pub mod encryption;
75#[cfg(feature = "encryption")]
76pub use encryption::{
77 derive_domain_key, EncryptionError, EncryptionHeader, KeyDerivationError, KeyDomain,
78 KeyRotationState, RotationAwareHeader, ZeroKnowledgeEncryptor,
79};
80
81// C FFI layer (feature-gated)
82#[cfg(feature = "ffi")]
83pub mod ffi;
84#[cfg(feature = "ffi")]
85pub use ffi::CachekitError;