cachekit-core 0.2.0

LZ4 compression, xxHash3 integrity, AES-256-GCM encryption for byte payloads
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

//! # cachekit-core
//!
//! LZ4 compression, xxHash3 integrity, AES-256-GCM encryption — for arbitrary byte payloads.
//!
//! This crate transforms bytes: compress them, verify their integrity, encrypt them.
//! Bytes in, bytes out.
//!
//! ## Features
//!
//! | Feature | Description | Default |
//! |:--------|:------------|:-------:|
//! | `compression` | LZ4 compression via `lz4_flex` | Yes |
//! | `checksum` | xxHash3-64 integrity verification | Yes |
//! | `encryption` | AES-256-GCM + HKDF-SHA256 (ring on native, aes-gcm on wasm32) | No |
//! | `ffi` | C header generation | No |
//!
//! ## Platform Support
//!
//! Compiles on both native targets and `wasm32-unknown-unknown` (Cloudflare Workers).
//! On wasm32, encryption uses RustCrypto's `aes-gcm` (pure Rust) instead of `ring`.
//! Both backends produce identical AES-256-GCM wire format.
//!
//! ## Quick Start
//!
//! ```rust,no_run
//! use cachekit_core::ByteStorage;
//!
//! let storage = ByteStorage::new(None);
//! let data = b"Hello, cachekit!";
//!
//! // Store: compress + checksum
//! let envelope = storage.store(data, None).unwrap();
//!
//! // Retrieve: decompress + verify
//! let (retrieved, _format) = storage.retrieve(&envelope).unwrap();
//! assert_eq!(data.as_slice(), retrieved.as_slice());
//! ```
//!
//! ## With Encryption
//!
//! ```rust,ignore
//! use cachekit_core::{ZeroKnowledgeEncryptor, derive_domain_key};
//!
//! // Derive tenant-isolated key
//! let master_key = [0u8; 32]; // Use secure key in production!
//! let tenant_key = derive_domain_key(&master_key, "cache", b"tenant-123").unwrap();
//!
//! // Encrypt
//! let encryptor = ZeroKnowledgeEncryptor::new();
//! let ciphertext = encryptor.encrypt_aes_gcm(b"secret", &tenant_key, b"tenant-123").unwrap();
//!
//! // Decrypt
//! let plaintext = encryptor.decrypt_aes_gcm(&ciphertext, &tenant_key, b"tenant-123").unwrap();
//! ```
//!
//! ## Security Properties
//!
//! - **AES-256-GCM**: Authenticated encryption via `ring`
//! - **HKDF-SHA256**: Key derivation with tenant isolation (RFC 5869)
//! - **xxHash3-64**: Fast non-cryptographic checksums (corruption detection)
//! - **Nonce safety**: Counter-based + random IV prevents reuse
//! - **Memory safety**: `zeroize` on drop for all key material

// Metrics and observability
pub mod metrics;
pub use metrics::OperationMetrics;

// Core byte storage layer
pub mod byte_storage;
pub use byte_storage::{ByteStorage, StorageEnvelope};

// Encryption module (feature-gated)
#[cfg(feature = "encryption")]
pub mod encryption;
#[cfg(feature = "encryption")]
pub use encryption::{
    derive_domain_key, EncryptionError, EncryptionHeader, KeyDerivationError, KeyDomain,
    KeyRotationState, RotationAwareHeader, ZeroKnowledgeEncryptor,
};

// C FFI layer (feature-gated)
#[cfg(feature = "ffi")]
pub mod ffi;
#[cfg(feature = "ffi")]
pub use ffi::CachekitError;