108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
---
|
|
phase: 02-core-archiver
|
|
plan: 02
|
|
subsystem: archive, cli
|
|
tags: [aes-256-cbc, hmac-sha256, gzip, binary-format, pack, unpack, inspect, encrypt-then-mac]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 02-core-archiver
|
|
plan: 01
|
|
provides: "Crypto pipeline (encrypt/decrypt/HMAC/SHA-256), format types (Header/TocEntry serialization), compression (gzip/heuristic), CLI skeleton, hardcoded key"
|
|
provides:
|
|
- "pack() function: two-pass archive writer producing FORMAT.md-compliant archives"
|
|
- "unpack() function: HMAC-first verification, AES-256-CBC decryption, optional gzip decompression, SHA-256 integrity check"
|
|
- "inspect() function: metadata display (sizes, offsets, IVs, HMACs, SHA-256) without decryption"
|
|
- "CLI dispatch wiring all three commands to archive module"
|
|
- "Directory traversal protection in unpack"
|
|
affects: [03-round-trip-verification, 04-kotlin-decoder, 05-shell-decoder, 06-obfuscation]
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added: []
|
|
patterns: [two-pass archive writing (process then compute offsets), HMAC-before-decrypt verification order, filename-only entry names from full paths]
|
|
|
|
key-files:
|
|
created: []
|
|
modified:
|
|
- src/archive.rs
|
|
- src/main.rs
|
|
|
|
key-decisions:
|
|
- "Use filename-only (not full path) as archive entry name to keep entries portable"
|
|
- "Directory traversal protection: reject names starting with / or containing .."
|
|
- "HMAC failure skips file and continues; SHA-256 mismatch warns but still writes file"
|
|
- "Flags byte bit 0 set only when at least one file is actually compressed"
|
|
|
|
patterns-established:
|
|
- "Two-pass archive writing: Pass 1 processes files in memory, Pass 2 computes offsets and writes sequentially"
|
|
- "HMAC verified before decryption attempt (encrypt-then-MAC per FORMAT.md Section 10)"
|
|
- "Per-file error handling: HMAC/SHA-256 failures increment error count, non-zero exit on any errors"
|
|
- "Inline TOC size computation: sum of (101 + name.len()) per file"
|
|
|
|
requirements-completed: [CLI-02, CLI-03]
|
|
|
|
# Metrics
|
|
duration: 2min
|
|
completed: 2026-02-24
|
|
---
|
|
|
|
# Phase 2 Plan 2: Archive Commands Summary
|
|
|
|
**Pack/unpack/inspect commands with AES-256-CBC encryption, HMAC-SHA-256 verification, gzip compression, and FORMAT.md-compliant binary output**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 2 min
|
|
- **Started:** 2026-02-24T21:01:22Z
|
|
- **Completed:** 2026-02-24T21:03:40Z
|
|
- **Tasks:** 1
|
|
- **Files modified:** 2
|
|
|
|
## Accomplishments
|
|
- Fully functional `encrypted_archive` binary with pack, unpack, and inspect commands
|
|
- Round-trip verified: packed files are byte-identical after unpacking (text + binary)
|
|
- HMAC tamper detection verified: flipping a ciphertext byte triggers rejection with non-zero exit
|
|
- Compression auto-detection verified: .apk files stored without gzip (compression_flag=0, flags=0x00)
|
|
- Archive starts with magic bytes 0x00 0xEA 0x72 0x63 (not recognized as any standard format)
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task 1: Implement pack, inspect, unpack commands and wire CLI** - `be50707` (feat)
|
|
|
|
## Files Created/Modified
|
|
- `src/archive.rs` - Pack, unpack, and inspect orchestration (237 lines): two-pass pack writer, HMAC-first unpack, metadata inspect
|
|
- `src/main.rs` - CLI dispatch wiring Commands enum to archive::pack/unpack/inspect
|
|
|
|
## Decisions Made
|
|
- **Filename-only entries:** Archive stores only the filename (not the full path) for portability across systems
|
|
- **Directory traversal protection:** Reject filenames starting with `/` or containing `..` during unpack (Rule 2 - security)
|
|
- **Error continuation:** HMAC failure skips the file; SHA-256 mismatch warns but still writes (per FORMAT.md Section 10 guidance)
|
|
- **Flags byte logic:** Header flags bit 0 is set only when at least one file in the archive has compression_flag=1
|
|
|
|
## Deviations from Plan
|
|
|
|
None - plan executed exactly as written.
|
|
|
|
## Issues Encountered
|
|
None.
|
|
|
|
## User Setup Required
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
- Phase 2 (Core Archiver) is complete: all modules wired and functional
|
|
- Ready for Phase 3 (Round-trip verification / integration tests)
|
|
- Two dead-code warnings remain for `format::entry_size` and `format::compute_toc_size` helper functions (usable by future code)
|
|
- All obfuscation features deferred to Phase 6 as per ROADMAP
|
|
|
|
## Self-Check: PASSED
|
|
|
|
All 2 modified files verified present. Task commit (be50707) verified in git log.
|
|
|
|
---
|
|
*Phase: 02-core-archiver*
|
|
*Completed: 2026-02-24*
|