Skip to content

Commit 6dbe9b1

Browse files
27Bslash627Bslash6
committed
feat: initial release
LZ4 compression, xxHash3 integrity, AES-256-GCM encryption for byte payloads. - ByteStorage: LZ4 compression with xxHash3-64 checksums - ZeroKnowledgeEncryptor: AES-256-GCM with counter-based nonces - Key derivation: HKDF-SHA256 (RFC 5869) - C FFI layer with auto-generated headers - Fuzz targets and property-based tests
0 parents  commit 6dbe9b1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+14139
-0
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
7+
jobs:
8+
test:
9+
runs-on: ${{ matrix.os }}
10+
strategy:
11+
fail-fast: false
12+
matrix:
13+
os: [ubuntu-latest, macos-latest, windows-latest]
14+
steps:
15+
- uses: actions/checkout@v5
16+
17+
- name: Install Rust toolchain
18+
uses: dtolnay/rust-toolchain@stable
19+
with:
20+
components: rustfmt, clippy
21+
22+
- name: Cache cargo registry
23+
uses: Swatinem/rust-cache@v2
24+
with:
25+
cache-all-crates: true
26+
27+
- name: Check formatting
28+
run: cargo fmt --check
29+
30+
- name: Run clippy
31+
run: cargo clippy --all-features -- -D warnings
32+
33+
- name: Run tests (all features)
34+
run: cargo test --all-features
35+
36+
- name: Run FFI tests
37+
run: cargo test --features ffi
38+
39+
security:
40+
runs-on: ubuntu-latest
41+
steps:
42+
- uses: actions/checkout@v5
43+
44+
- name: Install Rust toolchain
45+
uses: dtolnay/rust-toolchain@stable
46+
47+
- name: Cache cargo registry
48+
uses: Swatinem/rust-cache@v2
49+
with:
50+
cache-all-crates: true
51+
52+
- name: Install security tools
53+
run: cargo install cargo-deny cargo-audit
54+
55+
- name: Check dependencies (licenses & security advisories)
56+
run: cargo deny check
57+
58+
- name: Run cargo audit
59+
run: cargo audit

‎.github/workflows/release.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: write
10+
pull-requests: write
11+
12+
jobs:
13+
release-please:
14+
runs-on: ubuntu-latest
15+
outputs:
16+
release_created: ${{ steps.release.outputs.release_created }}
17+
tag_name: ${{ steps.release.outputs.tag_name }}
18+
steps:
19+
- uses: actions/create-github-app-token@v1
20+
id: app-token
21+
with:
22+
app-id: ${{ secrets.APP_ID }}
23+
private-key: ${{ secrets.APP_PRIVATE_KEY }}
24+
25+
- uses: googleapis/release-please-action@v4
26+
id: release
27+
with:
28+
token: ${{ steps.app-token.outputs.token }}
29+
30+
publish:
31+
needs: release-please
32+
if: ${{ needs.release-please.outputs.release_created }}
33+
runs-on: ubuntu-latest
34+
steps:
35+
- uses: actions/checkout@v4
36+
37+
- name: Install Rust toolchain
38+
uses: dtolnay/rust-toolchain@stable
39+
40+
- name: Cache cargo registry
41+
uses: Swatinem/rust-cache@v2
42+
43+
- name: Run tests before publish
44+
run: cargo test --all-features
45+
46+
- name: Publish to crates.io
47+
run: cargo publish
48+
env:
49+
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

‎.gitignore‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Rust build artifacts
2+
/target/
3+
Cargo.lock
4+
5+
# Generated files (keep .gitkeep but ignore generated header)
6+
include/cachekit.h
7+
8+
# Editor files
9+
*.swp
10+
*.swo
11+
*~
12+
.idea/
13+
.vscode/
14+
15+
# OS files
16+
.DS_Store
17+
Thumbs.db

‎.release-please-manifest.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
".": "0.0.1"
3+
}

‎CHANGELOG.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
12+
- **ByteStorage**: LZ4 compression with xxHash3-64 checksums
13+
- Automatic compression/decompression
14+
- Integrity verification on retrieval
15+
- Decompression bomb protection (512MB limit, 1000x ratio limit)
16+
17+
- **ZeroKnowledgeEncryptor**: AES-256-GCM encryption
18+
- Counter-based nonce generation (prevents reuse)
19+
- Hardware acceleration detection (AES-NI, ARM Crypto)
20+
- Operation metrics for observability
21+
22+
- **Key Derivation**: HKDF-SHA256 (RFC 5869)
23+
- Domain separation for multi-use keys
24+
- Tenant isolation via salt
25+
- Key fingerprinting for rotation support
26+
27+
- **C FFI Layer**: Multi-language support
28+
- Opaque handle management
29+
- Panic-safe error handling
30+
- Auto-generated `cachekit.h` header
31+
32+
- **Security Infrastructure**
33+
- 16 fuzz targets covering all attack surfaces
34+
- Kani formal verification proofs
35+
- Property-based testing with proptest
36+
- `cargo-deny` supply chain security
37+
38+
### Security
39+
40+
- All key material zeroized on drop
41+
- Constant-time operations for encryption via `ring`
42+
- No panics in library code (Result-based error handling)
43+
- FFI boundary hardened with `catch_unwind`
44+
45+
[Unreleased]: https://github.com/cachekit-io/cachekit-core/compare/main...HEAD

‎Cargo.toml‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
[package]
2+
name = "cachekit-core"
3+
version = "0.0.1"
4+
edition = "2024"
5+
authors = ["cachekit Contributors"]
6+
description = "LZ4 compression, xxHash3 integrity, AES-256-GCM encryption for byte payloads"
7+
rust-version = "1.85"
8+
license = "MIT"
9+
repository = "https://github.com/cachekit-io/cachekit-core"
10+
homepage = "https://github.com/cachekit-io/cachekit-core"
11+
documentation = "https://docs.rs/cachekit-core"
12+
readme = "README.md"
13+
keywords = ["lz4", "xxhash", "aes-gcm", "encryption", "compression"]
14+
categories = ["compression", "cryptography"]
15+
16+
[lib]
17+
name = "cachekit_core"
18+
# cdylib for C FFI, rlib for Rust crates, staticlib for static linking
19+
crate-type = ["cdylib", "rlib", "staticlib"]
20+
21+
[dependencies]
22+
# Error handling
23+
thiserror = "1.0"
24+
25+
# Core serialization
26+
serde = { version = "1.0", features = ["derive"] }
27+
serde_bytes = "0.11"
28+
29+
# MessagePack serialization (optional)
30+
rmp-serde = { version = "1.3", optional = true }
31+
32+
# High-performance LZ4 compression (optional)
33+
lz4_flex = { version = "0.11", features = ["frame", "std"], optional = true }
34+
35+
# Fast non-cryptographic hashing for data integrity (optional)
36+
# xxHash3-64: ~36 GB/s, sufficient for corruption detection (security via AES-GCM auth tag)
37+
xxhash-rust = { version = "0.8", features = ["xxh3"], optional = true }
38+
39+
40+
# Encryption dependencies (all optional, gated by encryption feature)
41+
# Uses HKDF-SHA256 for key derivation (NOT Blake2b - that's only for Python cache keys)
42+
ring = { version = "0.17", optional = true }
43+
zeroize = { version = "1.8", features = ["derive"], optional = true }
44+
hkdf = { version = "0.12", optional = true }
45+
sha2 = { version = "0.10", optional = true }
46+
hmac = { version = "0.12", optional = true }
47+
generic-array = { version = "0.14", optional = true }
48+
49+
# Byte utilities
50+
bytes = "1.5"
51+
byteorder = "1.5"
52+
53+
[build-dependencies]
54+
# C header generation (required for ffi feature)
55+
cbindgen = "0.29"
56+
57+
[dev-dependencies]
58+
proptest = "1.4"
59+
serde_json = "1.0"
60+
blake2 = "0.10"
61+
hex = "0.4"
62+
63+
[features]
64+
default = ["compression", "checksum", "messagepack"]
65+
66+
# Core features
67+
compression = ["dep:lz4_flex"]
68+
checksum = ["dep:xxhash-rust"]
69+
messagepack = ["dep:rmp-serde"]
70+
71+
# Encryption (AES-256-GCM with HKDF-SHA256 key derivation)
72+
encryption = [
73+
"dep:ring",
74+
"dep:zeroize",
75+
"dep:hkdf",
76+
"dep:sha2",
77+
"dep:hmac",
78+
"dep:generic-array",
79+
]
80+
81+
# C FFI layer (generates include/cachekit.h)
82+
ffi = []
83+
84+
# Kani formal verification configuration
85+
# Provides mathematical proofs of memory safety for unsafe code and FFI boundaries
86+
[package.metadata.kani]
87+
default-unwind = 10
88+
output-format = "terse"
89+
concrete-playback = "print"
90+
enable-unstable = false
91+
solver = "cadical"
92+
93+
[package.metadata.kani.unstable]
94+
stubbing = false
95+
96+
# Lint configuration
97+
[lints.rust]
98+
# Suppress benign warnings about cfg(kani) which is set by Kani verifier
99+
unexpected_cfgs = { level = "warn", check-cfg = ['cfg(kani)'] }

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024-2025 cachekit Contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)