docs(02-core-archiver): create phase plan
This commit is contained in:
NikitolProject
225
.planning/phases/02-core-archiver/02-02-PLAN.md
Normal file
225
.planning/phases/02-core-archiver/02-02-PLAN.md
Normal file
@@ -0,0 +1,225 @@
|
||||
---
|
||||
phase: 02-core-archiver
|
||||
plan: 02
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on: ["02-01"]
|
||||
files_modified:
|
||||
- src/archive.rs
|
||||
- src/main.rs
|
||||
autonomous: true
|
||||
requirements: [CLI-02, CLI-03]
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "Running `encrypted_archive pack file1 file2 -o out.bin` produces a valid archive file"
|
||||
- "The output archive file starts with magic bytes 0x00 0xEA 0x72 0x63"
|
||||
- "Running `encrypted_archive inspect out.bin` shows file count, names, and sizes without decryption"
|
||||
- "Running `encrypted_archive unpack out.bin -o outdir/` extracts files identical to originals"
|
||||
- "Each file in the archive has a unique random IV (no IV reuse)"
|
||||
- "HMAC is verified before decryption during unpack (reject tampered files)"
|
||||
- "SHA-256 is verified after decompression during unpack (detect corruption)"
|
||||
- "The output file is not recognized by `file` command (no standard signatures)"
|
||||
- "Already-compressed files (APK) are stored without gzip compression"
|
||||
artifacts:
|
||||
- path: "src/archive.rs"
|
||||
provides: "pack(), unpack(), inspect() orchestration functions"
|
||||
exports: ["pack", "unpack", "inspect"]
|
||||
min_lines: 150
|
||||
- path: "src/main.rs"
|
||||
provides: "CLI dispatch wiring commands to archive functions"
|
||||
contains: "archive::pack"
|
||||
key_links:
|
||||
- from: "src/archive.rs"
|
||||
to: "src/format.rs"
|
||||
via: "writes header and TOC entries using format module"
|
||||
pattern: "format::write_header|format::write_toc_entry|format::read_header"
|
||||
- from: "src/archive.rs"
|
||||
to: "src/crypto.rs"
|
||||
via: "encrypts/decrypts file data and computes/verifies HMAC"
|
||||
pattern: "crypto::encrypt_data|crypto::decrypt_data|crypto::compute_hmac|crypto::verify_hmac"
|
||||
- from: "src/archive.rs"
|
||||
to: "src/compression.rs"
|
||||
via: "compresses/decompresses file data based on should_compress"
|
||||
pattern: "compression::compress|compression::decompress|compression::should_compress"
|
||||
- from: "src/main.rs"
|
||||
to: "src/archive.rs"
|
||||
via: "dispatches CLI commands to archive functions"
|
||||
pattern: "archive::pack|archive::unpack|archive::inspect"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Implement the three archive commands (pack, unpack, inspect) and wire them to the CLI, producing a fully functional encrypted archive tool.
|
||||
|
||||
Purpose: This is the core deliverable of Phase 2 -- the working archiver. Pack produces archives conforming to FORMAT.md, inspect reads metadata without decryption, and unpack extracts files with full HMAC and SHA-256 verification.
|
||||
|
||||
Output: A working `encrypted_archive` binary with pack, unpack, and inspect commands that produce and consume archives matching the FORMAT.md specification.
|
||||
</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
|
||||
@.planning/phases/02-core-archiver/02-01-SUMMARY.md
|
||||
@docs/FORMAT.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Implement pack and inspect commands</name>
|
||||
<files>src/archive.rs, src/main.rs</files>
|
||||
<action>
|
||||
1. Implement `pack()` in `src/archive.rs`:
|
||||
|
||||
Signature: `pub fn pack(files: &[PathBuf], output: &Path, no_compress: &[String]) -> anyhow::Result<()>`
|
||||
|
||||
Algorithm (two-pass archive writing per research Pattern 2):
|
||||
|
||||
**Pass 1 -- Process all files:**
|
||||
For each input file:
|
||||
a. Read entire file into memory (per Out of Scope: no streaming).
|
||||
b. Validate file size <= u32::MAX. If exceeded, return error: "File too large: {name} ({size} bytes exceeds 4 GB limit)".
|
||||
c. Compute SHA-256 of original data: `crypto::sha256_hash(&data)`.
|
||||
d. Determine compression: `compression::should_compress(&filename, no_compress)`.
|
||||
e. If compressing: `compressed = compression::compress(&data)?`. Else: `compressed = data.clone()`, set compression_flag = 0.
|
||||
f. Generate random IV: `crypto::generate_iv()`.
|
||||
g. Encrypt: `ciphertext = crypto::encrypt_data(&compressed, &KEY, &iv)`.
|
||||
h. Compute HMAC: `hmac = crypto::compute_hmac(&KEY, &iv, &ciphertext)`.
|
||||
i. Store results in a `ProcessedFile` struct (or equivalent) with: name, original_size, compressed_size, encrypted_size, iv, hmac, sha256, compression_flag, ciphertext.
|
||||
|
||||
**Pass 2 -- Compute offsets and write archive:**
|
||||
a. Compute TOC size: sum of (101 + name.len()) for each file.
|
||||
b. Set toc_offset = HEADER_SIZE (40).
|
||||
c. Compute data offsets:
|
||||
- First file: data_offset = toc_offset + toc_size
|
||||
- Each subsequent: previous data_offset + previous encrypted_size
|
||||
d. Determine flags byte: if ANY file has compression_flag == 1, set bit 0 (0x01). Bits 1-3 are 0 (no obfuscation in Phase 2). Bits 4-7 MUST be 0.
|
||||
e. Create Header: version=1, flags, file_count, toc_offset, toc_size, toc_iv=[0u8;16], reserved=[0u8;8].
|
||||
f. Open output file for writing.
|
||||
g. Write header using `format::write_header()`.
|
||||
h. Write TOC entries using `format::write_toc_entry()` for each file (with computed data_offset).
|
||||
i. Write data blocks: for each file, write ciphertext bytes.
|
||||
j. Print summary: "Packed {N} files into {output} ({total_bytes} bytes)".
|
||||
|
||||
Import KEY from `crate::key::KEY`.
|
||||
|
||||
2. Implement `inspect()` in `src/archive.rs`:
|
||||
|
||||
Signature: `pub fn inspect(archive: &Path) -> anyhow::Result<()>`
|
||||
|
||||
Algorithm:
|
||||
a. Open archive file for reading.
|
||||
b. Read header using `format::read_header()`. This validates magic, version, flags.
|
||||
c. Read TOC entries using `format::read_toc()`.
|
||||
d. Print header info:
|
||||
```
|
||||
Archive: {filename}
|
||||
Version: {version}
|
||||
Flags: 0x{flags:02X}
|
||||
Files: {file_count}
|
||||
TOC offset: {toc_offset}
|
||||
TOC size: {toc_size}
|
||||
```
|
||||
e. For each file entry, print:
|
||||
```
|
||||
[{i}] {name}
|
||||
Original: {original_size} bytes
|
||||
Compressed: {compressed_size} bytes
|
||||
Encrypted: {encrypted_size} bytes
|
||||
Offset: {data_offset}
|
||||
Compression: {yes/no}
|
||||
IV: {hex}
|
||||
HMAC: {hex}
|
||||
SHA-256: {hex}
|
||||
```
|
||||
f. Print total: "Total original size: {sum} bytes".
|
||||
|
||||
3. Implement `unpack()` in `src/archive.rs`:
|
||||
|
||||
Signature: `pub fn unpack(archive: &Path, output_dir: &Path) -> anyhow::Result<()>`
|
||||
|
||||
Algorithm (follows FORMAT.md Section 10 decode order):
|
||||
a. Open archive file for reading.
|
||||
b. Read header using `format::read_header()`. Validates magic, version, flags.
|
||||
c. Read TOC entries using `format::read_toc()`.
|
||||
d. Create output directory if it doesn't exist.
|
||||
e. Track error count for per-file failures.
|
||||
f. For each file entry:
|
||||
- Seek to data_offset. Read encrypted_size bytes (ciphertext).
|
||||
- **Verify HMAC FIRST**: `crypto::verify_hmac(&KEY, &entry.iv, &ciphertext, &entry.hmac)`.
|
||||
If HMAC fails: print error "HMAC verification failed for {name}, skipping", increment error count, continue to next file.
|
||||
- Decrypt: `decrypted = crypto::decrypt_data(&ciphertext, &KEY, &entry.iv)?`.
|
||||
- Decompress if compression_flag == 1: `decompressed = compression::decompress(&decrypted)?`.
|
||||
Else: `decompressed = decrypted`.
|
||||
- **Verify SHA-256**: Compare `crypto::sha256_hash(&decompressed)` with `entry.sha256`.
|
||||
If mismatch: print warning "SHA-256 mismatch for {name} (data may be corrupted)", increment error count. Still write the file.
|
||||
- Create parent directories if name contains `/`.
|
||||
- Write decompressed data to `output_dir/entry.name`.
|
||||
- Print "Extracted: {name} ({original_size} bytes)".
|
||||
g. Print summary: "Extracted {success_count}/{file_count} files".
|
||||
h. If error_count > 0: return Err with message "{error_count} file(s) had verification errors".
|
||||
|
||||
Per research open question #2: Abort on header/TOC errors. For per-file errors (HMAC/SHA-256), report and continue with non-zero exit code.
|
||||
|
||||
4. Wire up `src/main.rs`:
|
||||
Replace placeholder functions with actual calls:
|
||||
```rust
|
||||
match cli.command {
|
||||
Commands::Pack { files, output, no_compress } => {
|
||||
archive::pack(&files, &output, &no_compress)?;
|
||||
}
|
||||
Commands::Unpack { archive, output_dir } => {
|
||||
archive::unpack(&archive, &output_dir)?;
|
||||
}
|
||||
Commands::Inspect { archive } => {
|
||||
archive::inspect(&archive)?;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
IMPORTANT: Use `std::io::Seek` and `SeekFrom::Start(offset as u64)` for seeking to data_offset during unpack.
|
||||
IMPORTANT: Use `std::fs::create_dir_all()` for creating output directories.
|
||||
IMPORTANT: filename from TocEntry may contain path separators -- sanitize to prevent directory traversal (reject names starting with `/` or containing `..`).
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /home/nick/Projects/Rust/encrypted_archive && cargo build 2>&1 && echo "--- Build OK ---" && echo "Hello, World!" > /tmp/ea_test_hello.txt && printf '\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f\x10' > /tmp/ea_test_binary.bin && cargo run -- pack /tmp/ea_test_hello.txt /tmp/ea_test_binary.bin -o /tmp/ea_test_archive.bin 2>&1 && echo "--- Pack OK ---" && cargo run -- inspect /tmp/ea_test_archive.bin 2>&1 && echo "--- Inspect OK ---" && mkdir -p /tmp/ea_test_out && cargo run -- unpack /tmp/ea_test_archive.bin -o /tmp/ea_test_out 2>&1 && echo "--- Unpack OK ---" && diff /tmp/ea_test_hello.txt /tmp/ea_test_out/ea_test_hello.txt && diff /tmp/ea_test_binary.bin /tmp/ea_test_out/ea_test_binary.bin && echo "--- Round-trip OK: files identical ---" && file /tmp/ea_test_archive.bin 2>&1 && echo "--- file command check (should say 'data' not a known format) ---" && rm -rf /tmp/ea_test_*</automated>
|
||||
<manual>Verify inspect output shows correct file metadata, verify round-trip produces identical files</manual>
|
||||
<sampling_rate>run after this task commits, before declaring plan complete</sampling_rate>
|
||||
</verify>
|
||||
<done>
|
||||
- `encrypted_archive pack` accepts multiple input files and produces a single archive
|
||||
- `encrypted_archive inspect` displays file metadata (names, sizes, offsets, IVs, HMACs, SHA-256) without decryption
|
||||
- `encrypted_archive unpack` extracts all files, verifying HMAC before decryption and SHA-256 after decompression
|
||||
- Round-trip test: pack 2 files, unpack, diff shows files are byte-identical
|
||||
- Archive file is not recognized by `file` command (shows "data" not a known format)
|
||||
- HMAC verification happens before decryption (encrypt-then-MAC correctly implemented)
|
||||
- Files with compressed extensions (apk, zip, etc.) are stored without gzip compression
|
||||
- Error handling: HMAC failure skips file and continues, SHA-256 mismatch warns but still writes
|
||||
</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
- `cargo build` succeeds
|
||||
- Pack 2 test files (text + binary), unpack to different directory, diff shows byte-identical
|
||||
- `file archive.bin` does NOT show a recognized format (should show "data")
|
||||
- `inspect` shows correct file count, names, sizes, and hex-encoded IVs/HMACs/SHA-256
|
||||
- Compression auto-detection: `.apk` file should have compression_flag=0 in inspect output
|
||||
- Unpack with tampered archive (flip a byte in ciphertext) should report HMAC failure but continue
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
A fully functional `encrypted_archive` binary where `pack` creates archives matching FORMAT.md, `inspect` displays metadata, and `unpack` extracts with full HMAC and SHA-256 verification. Round-trip fidelity: packed files are byte-identical after unpacking.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/02-core-archiver/02-02-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user