289 lines
14 KiB
Markdown
289 lines
14 KiB
Markdown
---
|
|
phase: 02-core-archiver
|
|
plan: 01
|
|
type: execute
|
|
wave: 1
|
|
depends_on: []
|
|
files_modified:
|
|
- Cargo.toml
|
|
- src/main.rs
|
|
- src/cli.rs
|
|
- src/key.rs
|
|
- src/format.rs
|
|
- src/crypto.rs
|
|
- src/compression.rs
|
|
autonomous: true
|
|
requirements: [FMT-01, FMT-02, FMT-03, FMT-04, ENC-01, ENC-02, ENC-03, ENC-04, ENC-05, CMP-01, CMP-02, INT-01, CLI-01]
|
|
|
|
must_haves:
|
|
truths:
|
|
- "cargo build compiles the project with zero errors and zero warnings"
|
|
- "All binary format types (Header, TocEntry) match FORMAT.md byte-for-byte field definitions"
|
|
- "encrypt then decrypt with known key/IV produces original data"
|
|
- "compress then decompress produces original data"
|
|
- "HMAC computed over IV||ciphertext matches recomputation"
|
|
- "SHA-256 of original data is correctly computed and stored"
|
|
artifacts:
|
|
- path: "Cargo.toml"
|
|
provides: "Project manifest with all dependencies"
|
|
contains: "aes"
|
|
- path: "src/main.rs"
|
|
provides: "CLI entry point with clap dispatch"
|
|
contains: "clap"
|
|
- path: "src/cli.rs"
|
|
provides: "Clap derive structs for Pack/Unpack/Inspect subcommands"
|
|
exports: ["Cli", "Commands"]
|
|
- path: "src/key.rs"
|
|
provides: "Hardcoded 32-byte encryption key"
|
|
exports: ["KEY"]
|
|
- path: "src/format.rs"
|
|
provides: "Header and TocEntry structs with serialize/deserialize"
|
|
exports: ["Header", "TocEntry", "MAGIC", "VERSION"]
|
|
- path: "src/crypto.rs"
|
|
provides: "AES-256-CBC encrypt/decrypt, HMAC-SHA-256, SHA-256"
|
|
exports: ["encrypt_data", "decrypt_data", "compute_hmac", "verify_hmac", "sha256_hash"]
|
|
- path: "src/compression.rs"
|
|
provides: "Gzip compress/decompress and should_compress heuristic"
|
|
exports: ["compress", "decompress", "should_compress"]
|
|
key_links:
|
|
- from: "src/crypto.rs"
|
|
to: "src/key.rs"
|
|
via: "imports KEY constant"
|
|
pattern: "use crate::key::KEY"
|
|
- from: "src/format.rs"
|
|
to: "docs/FORMAT.md"
|
|
via: "byte-for-byte field layout match"
|
|
pattern: "0x00.*0xEA.*0x72.*0x63"
|
|
- from: "src/main.rs"
|
|
to: "src/cli.rs"
|
|
via: "clap parse and dispatch"
|
|
pattern: "Cli::parse"
|
|
---
|
|
|
|
<objective>
|
|
Create the Rust project foundation with all library modules: CLI skeleton, binary format types, crypto pipeline, and compression.
|
|
|
|
Purpose: Establish the complete module structure and all building-block functions that the pack/unpack/inspect commands will orchestrate. Every individual operation (encrypt, decrypt, compress, decompress, HMAC, SHA-256, serialize header, serialize TOC entry) must work correctly in isolation before being wired together.
|
|
|
|
Output: A compiling Rust project with 7 source files covering CLI parsing, binary format types, cryptographic operations, compression, and the hardcoded key.
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@/home/nick/.claude/get-shit-done/workflows/execute-plan.md
|
|
@/home/nick/.claude/get-shit-done/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@.planning/PROJECT.md
|
|
@.planning/ROADMAP.md
|
|
@.planning/STATE.md
|
|
@.planning/phases/02-core-archiver/02-RESEARCH.md
|
|
@docs/FORMAT.md
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: Project scaffolding with Cargo, CLI skeleton, and key module</name>
|
|
<files>Cargo.toml, src/main.rs, src/cli.rs, src/key.rs</files>
|
|
<action>
|
|
1. Initialize the Rust project:
|
|
```
|
|
cargo init --name encrypted_archive /home/nick/Projects/Rust/encrypted_archive
|
|
```
|
|
If Cargo.toml already exists, just update it.
|
|
|
|
2. Set up Cargo.toml with exact dependency versions from research:
|
|
```toml
|
|
[package]
|
|
name = "encrypted_archive"
|
|
version = "0.1.0"
|
|
edition = "2021"
|
|
|
|
[dependencies]
|
|
aes = "0.8"
|
|
cbc = "0.1"
|
|
hmac = "0.12"
|
|
sha2 = "0.10"
|
|
flate2 = "1.1"
|
|
clap = { version = "4.5", features = ["derive"] }
|
|
rand = "0.9"
|
|
anyhow = "1.0"
|
|
```
|
|
|
|
3. Create `src/cli.rs` with clap derive structs matching the research pattern:
|
|
- `Cli` struct with `#[command(subcommand)]`
|
|
- `Commands` enum with three variants:
|
|
- `Pack { files: Vec<PathBuf>, output: PathBuf, no_compress: Vec<String> }`
|
|
- `Unpack { archive: PathBuf, output_dir: PathBuf }` (output_dir defaults to ".")
|
|
- `Inspect { archive: PathBuf }`
|
|
- Use `#[arg(required = true)]` for files in Pack
|
|
- Use `#[arg(short, long)]` for output paths
|
|
- Use `#[arg(long)]` for no_compress (Vec<String> of filename patterns to skip compression for)
|
|
|
|
4. Create `src/key.rs` with the hardcoded 32-byte key:
|
|
```rust
|
|
/// Hardcoded 32-byte AES-256 key.
|
|
/// Same key is used for AES-256-CBC encryption and HMAC-SHA-256 authentication (v1).
|
|
/// v2 will derive separate subkeys using HKDF.
|
|
pub const KEY: [u8; 32] = [
|
|
0x7A, 0x35, 0xC1, 0xD9, 0x4F, 0xE8, 0x2B, 0x6A,
|
|
0x91, 0x0D, 0xF3, 0x58, 0xBC, 0x74, 0xA6, 0x1E,
|
|
0x42, 0x8F, 0xD0, 0x63, 0xE5, 0x17, 0x9B, 0x2C,
|
|
0xFA, 0x84, 0x06, 0xCD, 0x3E, 0x79, 0xB5, 0x50,
|
|
];
|
|
```
|
|
Use a non-trivial key (not the example key 00 01 02 ... 1F from FORMAT.md worked example).
|
|
|
|
5. Create `src/main.rs`:
|
|
- Parse CLI with `Cli::parse()`
|
|
- Match on `Commands` variants, calling placeholder functions that print "not implemented yet" and return `Ok(())`
|
|
- Use `anyhow::Result<()>` as the return type for main
|
|
- Declare modules: `mod cli; mod key; mod format; mod crypto; mod compression; mod archive;`
|
|
|
|
IMPORTANT: Use Context7 to verify clap 4.5 derive API before writing cli.rs. Call `mcp__context7__resolve-library-id` for "clap" and then `mcp__context7__query-docs` for the derive subcommand pattern.
|
|
|
|
Do NOT use `rand::thread_rng()` -- it was renamed to `rand::rng()` in rand 0.9.
|
|
Do NOT use `block-modes` crate -- it is deprecated; use `cbc` directly.
|
|
</action>
|
|
<verify>
|
|
<automated>cd /home/nick/Projects/Rust/encrypted_archive && cargo build 2>&1</automated>
|
|
<manual>Verify Cargo.toml has correct dependencies, src/main.rs declares all modules, CLI help text shows pack/unpack/inspect</manual>
|
|
<sampling_rate>run after this task commits</sampling_rate>
|
|
</verify>
|
|
<done>
|
|
- cargo build succeeds with no errors
|
|
- `cargo run -- --help` shows three subcommands: pack, unpack, inspect
|
|
- `cargo run -- pack --help` shows files (required), --output, --no-compress arguments
|
|
- All 7 module files exist (main.rs, cli.rs, key.rs, format.rs, crypto.rs, compression.rs, archive.rs) even if some are stubs
|
|
</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 2: Format types, crypto pipeline, and compression module</name>
|
|
<files>src/format.rs, src/crypto.rs, src/compression.rs</files>
|
|
<action>
|
|
1. Create `src/format.rs` implementing the binary format from FORMAT.md:
|
|
|
|
Constants:
|
|
```rust
|
|
pub const MAGIC: [u8; 4] = [0x00, 0xEA, 0x72, 0x63];
|
|
pub const VERSION: u8 = 1;
|
|
pub const HEADER_SIZE: u32 = 40;
|
|
```
|
|
|
|
Structs:
|
|
- `Header` with fields: version (u8), flags (u8), file_count (u16), toc_offset (u32), toc_size (u32), toc_iv ([u8; 16]), reserved ([u8; 8])
|
|
- `TocEntry` with fields: name (String), original_size (u32), compressed_size (u32), encrypted_size (u32), data_offset (u32), iv ([u8; 16]), hmac ([u8; 32]), sha256 ([u8; 32]), compression_flag (u8), padding_after (u16)
|
|
|
|
Serialization (write functions):
|
|
- `write_header(writer: &mut impl Write, header: &Header) -> anyhow::Result<()>`:
|
|
Writes all 40 bytes in exact FORMAT.md order. Magic bytes first, then version, flags, file_count (LE), toc_offset (LE), toc_size (LE), toc_iv (16 bytes), reserved (8 bytes of zero).
|
|
- `write_toc_entry(writer: &mut impl Write, entry: &TocEntry) -> anyhow::Result<()>`:
|
|
Writes: name_length (u16 LE) + name bytes + original_size (u32 LE) + compressed_size (u32 LE) + encrypted_size (u32 LE) + data_offset (u32 LE) + iv (16 bytes) + hmac (32 bytes) + sha256 (32 bytes) + compression_flag (u8) + padding_after (u16 LE).
|
|
Entry size = 101 + name.len() bytes.
|
|
|
|
Deserialization (read functions):
|
|
- `read_header(reader: &mut impl Read) -> anyhow::Result<Header>`:
|
|
Reads 40 bytes, verifies magic == MAGIC, verifies version == 1, checks flags bits 4-7 are zero (reject if not). Returns parsed Header.
|
|
- `read_toc_entry(reader: &mut impl Read) -> anyhow::Result<TocEntry>`:
|
|
Reads name_length (u16 LE), then name_length bytes as UTF-8 string, then all fixed fields. Uses `from_le_bytes()` for all multi-byte integers.
|
|
- `read_toc(reader: &mut impl Read, file_count: u16) -> anyhow::Result<Vec<TocEntry>>`:
|
|
Reads file_count entries sequentially.
|
|
|
|
Helper:
|
|
- `entry_size(entry: &TocEntry) -> u32`: Returns `101 + entry.name.len() as u32`
|
|
- `compute_toc_size(entries: &[TocEntry]) -> u32`: Sum of all entry_size values
|
|
|
|
ALL multi-byte fields MUST use `to_le_bytes()` for writing and `from_le_bytes()` for reading. Do NOT use `to_ne_bytes()` or `to_be_bytes()`.
|
|
Filenames: Use `name.len()` (byte count) NOT `name.chars().count()` (character count). FORMAT.md specifies byte count.
|
|
|
|
2. Create `src/crypto.rs` implementing the encryption pipeline:
|
|
|
|
Type aliases:
|
|
```rust
|
|
use aes::cipher::{block_padding::Pkcs7, BlockDecryptMut, BlockEncryptMut, KeyIvInit};
|
|
type Aes256CbcEnc = cbc::Encryptor<aes::Aes256>;
|
|
type Aes256CbcDec = cbc::Decryptor<aes::Aes256>;
|
|
type HmacSha256 = hmac::Hmac<sha2::Sha256>;
|
|
```
|
|
|
|
Functions:
|
|
- `generate_iv() -> [u8; 16]`:
|
|
Uses `rand::rng().fill(&mut iv)` (NOT thread_rng -- renamed in rand 0.9).
|
|
- `encrypt_data(plaintext: &[u8], key: &[u8; 32], iv: &[u8; 16]) -> Vec<u8>`:
|
|
Computes encrypted_size = ((plaintext.len() / 16) + 1) * 16.
|
|
Allocates buffer of encrypted_size, copies plaintext to start.
|
|
Calls `Aes256CbcEnc::new(key.into(), iv.into()).encrypt_padded_mut::<Pkcs7>(&mut buf, plaintext.len())`.
|
|
Returns the buffer (full encrypted_size bytes).
|
|
- `decrypt_data(ciphertext: &[u8], key: &[u8; 32], iv: &[u8; 16]) -> anyhow::Result<Vec<u8>>`:
|
|
Allocates mutable buffer from ciphertext.
|
|
Calls `Aes256CbcDec::new(key.into(), iv.into()).decrypt_padded_mut::<Pkcs7>(&mut buf)`.
|
|
Returns decrypted data as Vec<u8>.
|
|
- `compute_hmac(key: &[u8; 32], iv: &[u8; 16], ciphertext: &[u8]) -> [u8; 32]`:
|
|
Creates HmacSha256, updates with iv then ciphertext. Returns `finalize().into_bytes().into()`.
|
|
HMAC input = IV (16 bytes) || ciphertext (encrypted_size bytes). Nothing else.
|
|
- `verify_hmac(key: &[u8; 32], iv: &[u8; 16], ciphertext: &[u8], expected: &[u8; 32]) -> bool`:
|
|
Creates HmacSha256, updates with iv then ciphertext. Uses `verify_slice(expected)` for constant-time comparison. Returns true on success.
|
|
- `sha256_hash(data: &[u8]) -> [u8; 32]`:
|
|
Returns `sha2::Sha256::digest(data).into()`.
|
|
|
|
CRITICAL: Use `hmac::Mac` trait for `new_from_slice()`, `update()`, `finalize()`, `verify_slice()`.
|
|
CRITICAL: encrypted_size formula: `((input_len / 16) + 1) * 16` -- PKCS7 ALWAYS adds at least 1 byte.
|
|
|
|
3. Create `src/compression.rs`:
|
|
|
|
Functions:
|
|
- `compress(data: &[u8]) -> anyhow::Result<Vec<u8>>`:
|
|
Uses `flate2::write::GzEncoder` with `Compression::default()`.
|
|
IMPORTANT: Use `GzBuilder::new().mtime(0)` to zero the gzip timestamp for reproducible output in tests.
|
|
Writes all data, finishes encoder, returns compressed bytes.
|
|
- `decompress(data: &[u8]) -> anyhow::Result<Vec<u8>>`:
|
|
Uses `flate2::read::GzDecoder`. Reads all bytes to a Vec<u8>.
|
|
- `should_compress(filename: &str, no_compress_list: &[String]) -> bool`:
|
|
Returns false if filename matches any entry in no_compress_list (by suffix or exact match).
|
|
Returns false for known compressed extensions: apk, zip, gz, bz2, xz, zst, png, jpg, jpeg, gif, webp, mp4, mp3, aac, ogg, flac, 7z, rar, jar.
|
|
Returns true otherwise.
|
|
Uses `filename.rsplit('.').next()` for extension extraction.
|
|
|
|
IMPORTANT: Use Context7 to verify the `aes`, `cbc`, `hmac`, `sha2`, `flate2`, and `rand` crate APIs before writing. Resolve library IDs and query docs for encrypt/decrypt patterns, HMAC usage, and GzEncoder/GzDecoder usage.
|
|
</action>
|
|
<verify>
|
|
<automated>cd /home/nick/Projects/Rust/encrypted_archive && cargo build 2>&1 && cargo run -- --help 2>&1</automated>
|
|
<manual>Review format.rs field order against FORMAT.md sections 4 and 5 to confirm byte-level match</manual>
|
|
<sampling_rate>run after this task commits</sampling_rate>
|
|
</verify>
|
|
<done>
|
|
- cargo build succeeds with no errors
|
|
- format.rs exports Header, TocEntry, MAGIC, VERSION, HEADER_SIZE, and all read/write functions
|
|
- crypto.rs exports encrypt_data, decrypt_data, compute_hmac, verify_hmac, sha256_hash, generate_iv
|
|
- compression.rs exports compress, decompress, should_compress
|
|
- Header serialization writes exactly 40 bytes with correct field order per FORMAT.md Section 4
|
|
- TocEntry serialization writes exactly (101 + name_length) bytes per FORMAT.md Section 5
|
|
- All multi-byte integers use little-endian encoding
|
|
- encrypt_data output size matches formula: ((input_len / 16) + 1) * 16
|
|
</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
- `cargo build` succeeds with zero errors
|
|
- `cargo run -- --help` shows pack, unpack, inspect subcommands
|
|
- All 7 source files exist: main.rs, cli.rs, key.rs, format.rs, crypto.rs, compression.rs, archive.rs
|
|
- format.rs Header struct has fields matching FORMAT.md Section 4 (magic, version, flags, file_count, toc_offset, toc_size, toc_iv, reserved)
|
|
- format.rs TocEntry struct has fields matching FORMAT.md Section 5 (name, original_size, compressed_size, encrypted_size, data_offset, iv, hmac, sha256, compression_flag, padding_after)
|
|
- crypto.rs uses `cbc::Encryptor<aes::Aes256>` (NOT deprecated block-modes)
|
|
- crypto.rs uses `rand::rng()` (NOT thread_rng)
|
|
- crypto.rs HMAC input is IV || ciphertext only
|
|
- compression.rs uses `GzBuilder::new().mtime(0)` for reproducible gzip
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
A compiling Rust project with complete module structure where every building-block operation (format read/write, encrypt/decrypt, HMAC compute/verify, SHA-256 hash, compress/decompress) is implemented and ready for the pack/unpack/inspect commands to orchestrate.
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/02-core-archiver/02-01-SUMMARY.md`
|
|
</output>
|