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 | No |
15//! | `ffi` | C header generation | No |
16//!
17//! ## Quick Start
18//!
19//! ```rust,no_run
20//! use cachekit_core::ByteStorage;
21//!
22//! let storage = ByteStorage::new(None);
23//! let data = b"Hello, cachekit!";
24//!
25//! // Store: compress + checksum
26//! let envelope = storage.store(data, None).unwrap();
27//!
28//! // Retrieve: decompress + verify
29//! let (retrieved, _format) = storage.retrieve(&envelope).unwrap();
30//! assert_eq!(data.as_slice(), retrieved.as_slice());
31//! ```
32//!
33//! ## With Encryption
34//!
35//! ```rust,ignore
36//! use cachekit_core::{ZeroKnowledgeEncryptor, derive_domain_key};
37//!
38//! // Derive tenant-isolated key
39//! let master_key = [0u8; 32]; // Use secure key in production!
40//! let tenant_key = derive_domain_key(&master_key, "cache", b"tenant-123").unwrap();
41//!
42//! // Encrypt
43//! let encryptor = ZeroKnowledgeEncryptor::new();
44//! let ciphertext = encryptor.encrypt_aes_gcm(b"secret", &tenant_key, b"tenant-123").unwrap();
45//!
46//! // Decrypt
47//! let plaintext = encryptor.decrypt_aes_gcm(&ciphertext, &tenant_key, b"tenant-123").unwrap();
48//! ```
49//!
50//! ## Security Properties
51//!
52//! - **AES-256-GCM**: Authenticated encryption via `ring`
53//! - **HKDF-SHA256**: Key derivation with tenant isolation (RFC 5869)
54//! - **xxHash3-64**: Fast non-cryptographic checksums (corruption detection)
55//! - **Nonce safety**: Counter-based + random IV prevents reuse
56//! - **Memory safety**: `zeroize` on drop for all key material
57
58// Metrics and observability
59pub mod metrics;
60pub use metrics::OperationMetrics;
61
62// Core byte storage layer
63pub mod byte_storage;
64pub use byte_storage::{ByteStorage, StorageEnvelope};
65
66// Encryption module (feature-gated)
67#[cfg(feature = "encryption")]
68pub mod encryption;
69#[cfg(feature = "encryption")]
70pub use encryption::{
71 EncryptionError, EncryptionHeader, KeyDerivationError, KeyDomain, KeyRotationState,
72 RotationAwareHeader, ZeroKnowledgeEncryptor, derive_domain_key,
73};
74
75// C FFI layer (feature-gated)
76#[cfg(feature = "ffi")]
77pub mod ffi;
78#[cfg(feature = "ffi")]
79pub use ffi::CachekitError;