docs: create roadmap (6 phases)

2026-02-24 22:55:12 +03:00
parent 5181148131
commit e0627c8653
3 changed files with 217 additions and 33 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -93,42 +93,42 @@

 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| FMT-01 | TBD | Pending |
-| FMT-02 | TBD | Pending |
-| FMT-03 | TBD | Pending |
-| FMT-04 | TBD | Pending |
-| FMT-05 | TBD | Pending |
-| FMT-06 | TBD | Pending |
-| FMT-07 | TBD | Pending |
-| FMT-08 | TBD | Pending |
-| ENC-01 | TBD | Pending |
-| ENC-02 | TBD | Pending |
-| ENC-03 | TBD | Pending |
-| ENC-04 | TBD | Pending |
-| ENC-05 | TBD | Pending |
-| CMP-01 | TBD | Pending |
-| CMP-02 | TBD | Pending |
-| INT-01 | TBD | Pending |
-| INT-02 | TBD | Pending |
-| CLI-01 | TBD | Pending |
-| CLI-02 | TBD | Pending |
-| CLI-03 | TBD | Pending |
-| KOT-01 | TBD | Pending |
-| KOT-02 | TBD | Pending |
-| KOT-03 | TBD | Pending |
-| KOT-04 | TBD | Pending |
-| SHL-01 | TBD | Pending |
-| SHL-02 | TBD | Pending |
-| SHL-03 | TBD | Pending |
-| TST-01 | TBD | Pending |
-| TST-02 | TBD | Pending |
-| TST-03 | TBD | Pending |
+| FMT-01 | Phase 2 | Pending |
+| FMT-02 | Phase 2 | Pending |
+| FMT-03 | Phase 2 | Pending |
+| FMT-04 | Phase 2 | Pending |
+| FMT-05 | Phase 1 | Pending |
+| FMT-06 | Phase 6 | Pending |
+| FMT-07 | Phase 6 | Pending |
+| FMT-08 | Phase 6 | Pending |
+| ENC-01 | Phase 2 | Pending |
+| ENC-02 | Phase 2 | Pending |
+| ENC-03 | Phase 2 | Pending |
+| ENC-04 | Phase 2 | Pending |
+| ENC-05 | Phase 2 | Pending |
+| CMP-01 | Phase 2 | Pending |
+| CMP-02 | Phase 2 | Pending |
+| INT-01 | Phase 2 | Pending |
+| INT-02 | Phase 3 | Pending |
+| CLI-01 | Phase 2 | Pending |
+| CLI-02 | Phase 2 | Pending |
+| CLI-03 | Phase 2 | Pending |
+| KOT-01 | Phase 4 | Pending |
+| KOT-02 | Phase 4 | Pending |
+| KOT-03 | Phase 4 | Pending |
+| KOT-04 | Phase 4 | Pending |
+| SHL-01 | Phase 5 | Pending |
+| SHL-02 | Phase 5 | Pending |
+| SHL-03 | Phase 5 | Pending |
+| TST-01 | Phase 3 | Pending |
+| TST-02 | Phase 3 | Pending |
+| TST-03 | Phase 3 | Pending |

 **Coverage:**
 - v1 requirements: 30 total
- Mapped to phases: 0
- Unmapped: 30
+- Mapped to phases: 30
+- Unmapped: 0

 ---
 *Requirements defined: 2026-02-24*
-*Last updated: 2026-02-24 after initial definition*
+*Last updated: 2026-02-24 after roadmap creation*
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -0,0 +1,122 @@
+# Roadmap: Encrypted Archive
+
+## Overview
+
+Build a custom encrypted archive format that standard tools cannot recognize or extract. The format spec comes first (it governs all three implementations), then the Rust archiver with full crypto pipeline, then round-trip verification to catch format bugs early, then Kotlin decoder (primary extraction on Android), then shell decoder (busybox fallback), and finally obfuscation hardening to defeat binwalk/file/strings analysis.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: Format Specification** - Document the complete binary format before writing any code
+- [ ] **Phase 2: Core Archiver** - Rust CLI that compresses, encrypts, and packs files into the custom format
+- [ ] **Phase 3: Round-Trip Verification** - Rust unpack command + golden test vectors + unit tests proving byte-identical round-trips
+- [ ] **Phase 4: Kotlin Decoder** - Android 13 decoder using javax.crypto and java.util.zip (primary extraction path)
+- [ ] **Phase 5: Shell Decoder** - Busybox shell script decoder using dd/xxd/openssl/gunzip (fallback extraction)
+- [ ] **Phase 6: Obfuscation Hardening** - XOR-obfuscated headers, encrypted file table, decoy padding to defeat casual analysis
+
+## Phase Details
+
+### Phase 1: Format Specification
+**Goal**: A complete, unambiguous binary format document that all three implementations can build against
+**Depends on**: Nothing (first phase)
+**Requirements**: FMT-05
+**Success Criteria** (what must be TRUE):
+  1. Format spec document exists with byte-level field definitions (offsets, sizes, types) for header, file table, and data blocks
+  2. Spec defines magic bytes, version field, encryption parameters (AES-256-CBC, IV storage, HMAC placement), and compression flags
+  3. Spec includes a worked example: a concrete archive with 2 files showing exact byte layout
+  4. Spec addresses all obfuscation features (XOR headers, encrypted TOC, decoy padding) even though implementation is Phase 6
+**Plans**: TBD
+
+Plans:
+- [ ] 01-01: TBD
+
+### Phase 2: Core Archiver
+**Goal**: A working Rust CLI that takes input files and produces a valid encrypted archive
+**Depends on**: Phase 1
+**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, CLI-02, CLI-03
+**Success Criteria** (what must be TRUE):
+  1. Running `encrypted_archive pack file1.txt file2.apk -o archive.bin` produces a single binary file
+  2. The output file is not recognized by `file`, `binwalk`, or `7z` (custom magic bytes, no standard signatures)
+  3. Each file in the archive is independently compressed (gzip) and encrypted (AES-256-CBC) with a unique random IV
+  4. HMAC-SHA256 is computed over IV+ciphertext for each file (encrypt-then-MAC)
+  5. Running `encrypted_archive inspect archive.bin` shows file count, names, and sizes without decrypting content
+**Plans**: TBD
+
+Plans:
+- [ ] 02-01: TBD
+- [ ] 02-02: TBD
+
+### Phase 3: Round-Trip Verification
+**Goal**: Proven byte-identical round-trips through the Rust unpack command, backed by golden test vectors
+**Depends on**: Phase 2
+**Requirements**: INT-02, TST-01, TST-02, TST-03
+**Success Criteria** (what must be TRUE):
+  1. Running `encrypted_archive unpack archive.bin -o output_dir/` extracts all files byte-identical to originals (verified by SHA-256 comparison)
+  2. Golden test vectors exist: a known plaintext + known key + known IV produces an expected ciphertext (checked in CI)
+  3. Unit tests cover each pipeline stage independently: compression, encryption, HMAC, format serialization/deserialization
+  4. Round-trip succeeds for edge cases: empty file, large APK (>10MB), file with non-ASCII name (Cyrillic)
+**Plans**: TBD
+
+Plans:
+- [ ] 03-01: TBD
+- [ ] 03-02: TBD
+
+### Phase 4: Kotlin Decoder
+**Goal**: Android 13 Kotlin code that extracts files from the custom archive using only Android SDK built-ins
+**Depends on**: Phase 3
+**Requirements**: KOT-01, KOT-02, KOT-03, KOT-04
+**Success Criteria** (what must be TRUE):
+  1. Kotlin decoder extracts all files from an archive created by the Rust archiver, producing byte-identical output
+  2. Decoder uses only javax.crypto (AES/CBC/PKCS5Padding) and java.util.zip.GZIPInputStream -- no native libraries or third-party dependencies
+  3. Decoder verifies HMAC-SHA256 before attempting decryption (fails fast on tampered data)
+  4. Decoder verifies SHA-256 checksum after decompression (catches decompression corruption)
+**Plans**: TBD
+
+Plans:
+- [ ] 04-01: TBD
+
+### Phase 5: Shell Decoder
+**Goal**: A busybox-compatible shell script that extracts files from the custom archive as a fallback when Kotlin is unavailable
+**Depends on**: Phase 3
+**Requirements**: SHL-01, SHL-02, SHL-03
+**Success Criteria** (what must be TRUE):
+  1. Shell script extracts all files from an archive created by the Rust archiver, producing byte-identical output
+  2. Script uses only standard busybox commands: dd, xxd, openssl (with -K/-iv/-nosalt for raw key mode), gunzip
+  3. Script correctly handles files with non-ASCII names (Cyrillic characters)
+**Plans**: TBD
+
+Plans:
+- [ ] 05-01: TBD
+
+### Phase 6: Obfuscation Hardening
+**Goal**: Archive format resists casual analysis -- binwalk, file, strings, and hex editors reveal nothing useful
+**Depends on**: Phase 4, Phase 5
+**Requirements**: FMT-06, FMT-07, FMT-08
+**Success Criteria** (what must be TRUE):
+  1. File table (names, sizes, offsets) is encrypted with its own IV -- hex dump of archive reveals no plaintext metadata
+  2. All headers are XOR-obfuscated with a fixed key -- no recognizable structure patterns in first 256 bytes
+  3. Random decoy padding exists between data blocks -- file boundaries are not detectable by size analysis
+  4. All three decoders (Rust, Kotlin, Shell) still produce byte-identical output after obfuscation is applied
+**Plans**: TBD
+
+Plans:
+- [ ] 06-01: TBD
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Format Specification | 0/1 | Not started | - |
+| 2. Core Archiver | 0/2 | Not started | - |
+| 3. Round-Trip Verification | 0/2 | Not started | - |
+| 4. Kotlin Decoder | 0/1 | Not started | - |
+| 5. Shell Decoder | 0/1 | Not started | - |
+| 6. Obfuscation Hardening | 0/1 | Not started | - |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -0,0 +1,62 @@
+# 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 1: Format Specification
+
+## Current Position
+
+Phase: 1 of 6 (Format Specification)
+Plan: 0 of 1 in current phase
+Status: Ready to plan
+Last activity: 2026-02-24 -- Roadmap created
+
+Progress: [░░░░░░░░░░] 0%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 0
+- Average duration: -
+- Total execution time: 0 hours
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| - | - | - | - |
+
+**Recent Trend:**
+- Last 5 plans: -
+- Trend: -
+
+*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
+
+### Pending Todos
+
+None yet.
+
+### Blockers/Concerns
+
+- Open question: Does target busybox have `openssl enc -aes-256-cbc` with `-K`/`-iv` flags? (affects Phase 5)
+- Open question: Is `xxd` available in target busybox? Fallback: `od` (affects Phase 5)
+- Open question: Should HMAC use same key as AES or derived subkey? (must resolve in Phase 1 spec)
+
+## Session Continuity
+
+Last session: 2026-02-24
+Stopped at: Roadmap created, ready to plan Phase 1
+Resume file: None