android-encrypted-archiver/.planning/STATE.md

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: All 6 phases complete. Project milestone v1.0 finished.

Current Position

Phase: 6 of 6 (Obfuscation Hardening) Plan: 2 of 2 in current phase (COMPLETE) Status: All phases complete -- all decoders handle obfuscated archives Last activity: 2026-02-25 -- Kotlin and Shell decoder obfuscation support

Progress: [██████████] 100%

Performance Metrics

Velocity:

• Total plans completed: 10
• Average duration: 3.6 min
• Total execution time: 0.6 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	2/2	5 min	2.5 min
6. Obfuscation Hardening	2/2	6 min	3 min

Recent Trend:

• Last 5 plans: 4min, 3min, 2min, 3min, 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
• Phase 5: All 6 cross-validation tests passed on first run -- decode.sh was correct as written
• Phase 5: Used sh (not bash) to invoke decode.sh in tests for POSIX compatibility validation
• Phase 6: Always enable all 3 obfuscation features (no --no-obfuscate flag in v1)
• Phase 6: Decoy padding range 64-4096 bytes per file (FORMAT.md allows up to 65535)
• Phase 6: Shared read_archive_metadata() helper for unpack/inspect de-obfuscation
• Phase 6: Two-pass TOC serialization for correct data_offsets with encrypted TOC size
• Phase 6: XOR bootstrapping in Kotlin uses and 0xFF masking on BOTH operands for signed byte safety
• Phase 6: Shell decoder writes de-XORed header to temp file, reuses existing read_hex/read_le_u16/read_le_u32
• Phase 6: Shell decoder TOC_FILE/TOC_BASE_OFFSET abstraction for encrypted vs plaintext TOC
• Phase 6: Shell decoder HMAC constructs IV from parsed hex via hex_to_bin (not archive position)

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 06-02-PLAN.md (Kotlin and Shell decoder obfuscation support -- all phases complete) Resume file: None