3.9 KiB
Project State
Project Reference
See: .planning/PROJECT.md (updated 2026-02-24)
Core value: Archive impossible to unpack without knowing the format -- standard tools (7z, tar, unzip, binwalk) cannot recognize or extract contents Current focus: Phase 5 in progress (Shell Decoder)
Current Position
Phase: 5 of 6 (Shell Decoder) Plan: 1 of 2 in current phase Status: Plan 1 complete, Plan 2 (cross-validation tests) remaining Last activity: 2026-02-25 -- Busybox-compatible shell decoder script (shell/decode.sh)
Progress: [███████░░░] 70%
Performance Metrics
Velocity:
- Total plans completed: 7
- Average duration: 4.1 min
- Total execution time: 0.5 hours
By Phase:
| Phase | Plans | Total | Avg/Plan |
|---|---|---|---|
| 1. Format Specification | 1 | 7 min | 7 min |
| 2. Core Archiver | 2/2 | 6 min | 3 min |
| 3. Round-Trip Verification | 2/2 | 8 min | 4 min |
| 4. Kotlin Decoder | 1/1 | 4 min | 4 min |
| 5. Shell Decoder | 1/2 | 3 min | 3 min |
Recent Trend:
- Last 5 plans: 2min, 3min, 5min, 4min, 3min
- Trend: stable
Updated after each plan completion
Accumulated Context
Decisions
Decisions are logged in PROJECT.md Key Decisions table. Recent decisions affecting current work:
- Roadmap: Format spec must precede all implementation (all three decoders build against same spec)
- Roadmap: Obfuscation (XOR headers, encrypted TOC, decoy padding) deferred to Phase 6 after all decoders work without it
- Phase 1: IV stored only in TOC, not duplicated in data blocks (simplifies shell dd extraction)
- Phase 1: Same 32-byte key for AES-256-CBC and HMAC-SHA-256 in v1 (v2 will use HKDF)
- Phase 1: Magic bytes 0x00 0xEA 0x72 0x63 (leading null signals binary)
- Phase 1: HMAC scope = IV (16 bytes) || ciphertext (encrypted_size bytes)
- Phase 2: Used rand::Fill::fill() for IV generation (correct rand 0.9 API)
- Phase 2: Manual binary serialization with to_le_bytes/from_le_bytes (no serde/bincode)
- Phase 2: Filename-only entry names (not full paths) for archive portability
- Phase 2: HMAC failure skips file and continues; SHA-256 mismatch warns but writes
- Phase 2: Flags bit 0 set only when at least one file is actually compressed
- Phase 3: Library crate with pub mod re-exports for all 6 modules
- Phase 3: Unit tests embedded in modules via #[cfg(test)] (not separate files)
- Phase 3: hex-literal v1.1 for compile-time SHA-256 known-value assertions
- Phase 3: Corrected HMAC golden vector (openssl pipe+xxd produced wrong value; verified with file input and Python)
- Phase 3: cargo_bin! macro for non-deprecated assert_cmd binary resolution
- Phase 3: 11MB deterministic pseudo-random data for large file test (wrapping_mul Knuth hash)
- Phase 4: Single-file Kotlin decoder (ArchiveDecoder.kt) for simplicity and Android embeddability
- Phase 4: RandomAccessFile for seeking to data blocks instead of reading entire archive into memory
- Phase 4: HMAC failure skips file, SHA-256 mismatch warns but writes (matching Rust behavior)
- Phase 4: Kotlin signed byte handling with .toByte() for literals > 0x7F, contentEquals() for ByteArray comparison
- Phase 5: POSIX sh (not bash) for maximum busybox compatibility
- Phase 5: xxd/od auto-detection at startup for hex conversion
- Phase 5: Graceful HMAC degradation when openssl lacks -mac support
- Phase 5: Extract ciphertext to temp file before decryption (avoids pipe buffering issues)
- Phase 5: LC_ALL=C for predictable byte handling across locales
Pending Todos
None yet.
Blockers/Concerns
- RESOLVED: openssl enc with -K/-iv flags implemented in shell decoder; script fails gracefully if openssl missing
- RESOLVED: xxd/od auto-detection implemented in shell decoder (xxd primary, od fallback)
- RESOLVED: HMAC uses same key as AES in v1 (decided in Phase 1 spec, v2 will use HKDF)
Session Continuity
Last session: 2026-02-25 Stopped at: Completed 05-01-PLAN.md (Shell decoder script; Phase 5 Plan 1 of 2) Resume file: None