docs(03-02): complete golden vectors and round-trip tests plan

- SUMMARY.md: 7 golden vectors + 6 round-trip integration tests - STATE.md: Phase 3 complete (50% overall), 5 plans done - ROADMAP.md: Phase 3 marked complete - REQUIREMENTS.md: INT-02, TST-01, TST-02 marked complete Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-25 00:42:05 +03:00
parent 91ee354db6
commit 387836ca14
4 changed files with 150 additions and 23 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -32,7 +32,7 @@
 ### Integrity (Целостность)

 - [x] **INT-01**: SHA-256 чексумма для каждого файла (верификация после декомпрессии)
- [ ] **INT-02**: Распакованные файлы byte-identical оригиналам (round-trip fidelity)
+- [x] **INT-02**: Распакованные файлы byte-identical оригиналам (round-trip fidelity)

 ### CLI Archiver (Архиватор)

@@ -55,8 +55,8 @@

 ### Testing (Тестирование)

- [ ] **TST-01**: Round-trip тесты: архивация Rust → деархивация Rust
- [ ] **TST-02**: Golden test vectors: известный plaintext/key/IV → ожидаемый ciphertext
+- [x] **TST-01**: Round-trip тесты: архивация Rust → деархивация Rust
+- [x] **TST-02**: Golden test vectors: известный plaintext/key/IV → ожидаемый ciphertext
 - [x] **TST-03**: Базовые unit-тесты для каждого модуля pipeline

 ## v2 Requirements
@@ -109,7 +109,7 @@
 | CMP-01 | Phase 2 | Complete |
 | CMP-02 | Phase 2 | Complete |
 | INT-01 | Phase 2 | Complete |
-| INT-02 | Phase 3 | Pending |
+| INT-02 | Phase 3 | Complete |
 | CLI-01 | Phase 2 | Complete |
 | CLI-02 | Phase 2 | Complete |
 | CLI-03 | Phase 2 | Complete |
@@ -120,8 +120,8 @@
 | 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-01 | Phase 3 | Complete |
+| TST-02 | Phase 3 | Complete |
 | TST-03 | Phase 3 | Complete |

 **Coverage:**
@@ -131,4 +131,4 @@

 ---
 *Requirements defined: 2026-02-24*
-*Last updated: 2026-02-24 after roadmap creation*
+*Last updated: 2026-02-24 after Phase 3 completion*
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -14,7 +14,7 @@ Decimal phases appear between their surrounding integers in numeric order.

 - [x] **Phase 1: Format Specification** - Document the complete binary format before writing any code (completed 2026-02-24)
 - [x] **Phase 2: Core Archiver** - Rust CLI that compresses, encrypts, and packs files into the custom format (completed 2026-02-24)
- [ ] **Phase 3: Round-Trip Verification** - Rust unpack command + golden test vectors + unit tests proving byte-identical round-trips
+- [x] **Phase 3: Round-Trip Verification** - Rust unpack command + golden test vectors + unit tests proving byte-identical round-trips (completed 2026-02-24)
 - [ ] **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
@@ -64,7 +64,7 @@ Plans:

 Plans:
 - [x] 03-01-PLAN.md -- Library crate structure, dev-dependencies, and unit tests for crypto/compression/format modules
- [ ] 03-02-PLAN.md -- Golden test vectors with fixed IV/key and CLI round-trip integration tests
+- [x] 03-02-PLAN.md -- Golden test vectors with fixed IV/key and CLI round-trip integration tests

 ### Phase 4: Kotlin Decoder
 **Goal**: Android 13 Kotlin code that extracts files from the custom archive using only Android SDK built-ins
@@ -116,7 +116,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6
 |-------|----------------|--------|-----------|
 | 1. Format Specification | 1/1 | Complete    | 2026-02-24 |
 | 2. Core Archiver | 2/2 | Complete    | 2026-02-24 |
-| 3. Round-Trip Verification | 1/2 | In progress | - |
+| 3. Round-Trip Verification | 2/2 | Complete    | 2026-02-24 |
 | 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
@@ -5,23 +5,23 @@
 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 3: Round-Trip Verification
+**Current focus:** Phase 3 complete, ready for Phase 4

 ## Current Position

-Phase: 3 of 6 (Round-Trip Verification)
-Plan: 1 of 2 in current phase
-Status: Plan 03-01 complete, ready for Plan 03-02
-Last activity: 2026-02-24 -- Library crate + 19 unit tests for crypto/compression/format
+Phase: 3 of 6 (Round-Trip Verification) -- COMPLETE
+Plan: 2 of 2 in current phase (all done)
+Status: Phase 3 complete, ready for Phase 4
+Last activity: 2026-02-24 -- Golden vectors + round-trip integration tests (32 total tests passing)

-Progress: [████░░░░░░] 43%
+Progress: [█████░░░░░] 50%

 ## Performance Metrics

 **Velocity:**
- Total plans completed: 4
- Average duration: 4 min
- Total execution time: 0.3 hours
+- Total plans completed: 5
+- Average duration: 4.6 min
+- Total execution time: 0.4 hours

 **By Phase:**

@@ -29,11 +29,11 @@ Progress: [████░░░░░░] 43%
 |-------|-------|-------|----------|
 | 1. Format Specification | 1 | 7 min | 7 min |
 | 2. Core Archiver | 2/2 | 6 min | 3 min |
-| 3. Round-Trip Verification | 1/2 | 3 min | 3 min |
+| 3. Round-Trip Verification | 2/2 | 8 min | 4 min |

 **Recent Trend:**
- Last 5 plans: 7min, 4min, 2min, 3min
- Trend: stable/improving
+- Last 5 plans: 7min, 4min, 2min, 3min, 5min
+- Trend: stable

 *Updated after each plan completion*

@@ -58,6 +58,9 @@ Recent decisions affecting current work:
 - 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)

 ### Pending Todos

@@ -72,5 +75,5 @@ None yet.
 ## Session Continuity

 Last session: 2026-02-24
-Stopped at: Completed 03-01-PLAN.md (Library crate + unit tests)
+Stopped at: Completed 03-02-PLAN.md (Golden vectors + round-trip tests; Phase 3 complete)
 Resume file: None
--- a/.planning/phases/03-round-trip-verification/03-02-SUMMARY.md
+++ b/.planning/phases/03-round-trip-verification/03-02-SUMMARY.md
@@ -0,0 +1,124 @@
+---
+phase: 03-round-trip-verification
+plan: 02
+subsystem: testing
+tags: [golden-vectors, integration-tests, round-trip, aes-256-cbc, hmac-sha256, sha256, assert_cmd, tempfile]
+
+# Dependency graph
+requires:
+  - phase: 03-round-trip-verification
+    plan: 01
+    provides: "Library crate (src/lib.rs) with pub mod re-exports, dev-dependencies (assert_cmd, tempfile, hex-literal)"
+  - phase: 02-core-archiver
+    provides: "crypto.rs, compression.rs, format.rs, archive.rs with pack/unpack CLI"
+provides:
+  - "7 golden test vectors for AES-256-CBC, HMAC-SHA256, and SHA-256 (deterministic, cross-verified)"
+  - "6 CLI round-trip integration tests covering all Phase 3 edge cases"
+  - "32 total tests (19 unit + 7 golden + 6 integration) all passing"
+affects: [phase-4-cli-polish, phase-5-shell-decoder, verification]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [golden-vector-testing-with-fixed-iv, cli-integration-via-assert_cmd-cargo_bin-macro, tempdir-isolation-for-parallel-tests]
+
+key-files:
+  created: [tests/golden.rs, tests/round_trip.rs]
+  modified: []
+
+key-decisions:
+  - "Corrected HMAC golden vector: research openssl pipe+xxd gave wrong value; verified with openssl file input and Python hmac module"
+  - "Used cargo_bin! macro instead of deprecated Command::cargo_bin() for forward compatibility"
+  - "Large file test uses 11MB deterministic pseudo-random data with --no-compress to avoid gzip non-determinism"
+
+patterns-established:
+  - "Golden vector pattern: fixed IV + known KEY for deterministic crypto test output"
+  - "CLI integration pattern: tempdir + cargo_bin! + pack/unpack + assert_eq on raw bytes"
+  - "Edge case coverage: empty file (PKCS7), Cyrillic UTF-8 names, >10MB files, APK no-compress"
+
+requirements-completed: [INT-02, TST-01, TST-02]
+
+# Metrics
+duration: 5min
+completed: 2026-02-24
+---
+
+# Phase 3 Plan 02: Golden Vectors and Round-Trip Tests Summary
+
+**7 golden crypto test vectors (AES-256-CBC, HMAC-SHA256, SHA-256) and 6 CLI round-trip integration tests covering empty files, Cyrillic filenames, and 11MB binaries**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-02-24T21:34:17Z
+- **Completed:** 2026-02-24T21:39:45Z
+- **Tasks:** 2
+- **Files created:** 2
+
+## Accomplishments
+- Created 7 golden test vectors with fixed IVs for deterministic crypto verification (TST-02)
+- Created 6 CLI round-trip integration tests proving byte-identical pack->unpack (INT-02, TST-01)
+- All 32 tests pass (19 unit + 7 golden + 6 integration) with zero warnings
+- Cross-verified golden values with openssl (file input) and Python hmac module
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create golden test vectors with fixed IV/key** - `329bed6` (test)
+2. **Task 2: Create CLI round-trip integration tests** - `91ee354` (test)
+
+## Files Created/Modified
+- `tests/golden.rs` - 7 golden vector tests: AES-256-CBC encrypt/decrypt/empty, HMAC-SHA256 compute/verify, SHA-256 x2
+- `tests/round_trip.rs` - 6 CLI integration tests: single file, multiple files, empty, Cyrillic, 11MB large, APK no-compress
+
+## Decisions Made
+- Corrected HMAC golden vector from research: openssl pipe with xxd -r -p produced incorrect binary, verified correct value (`efa09db0...`) using openssl with file input and Python hmac.new()
+- Used `cargo_bin!` macro (non-deprecated) instead of `Command::cargo_bin()` to avoid deprecation warnings
+- Large file test generates 11MB of deterministic pseudo-random data (`i.wrapping_mul(2654435761) as u8`) to ensure reproducibility
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Corrected HMAC-SHA256 golden vector value**
+- **Found during:** Task 1 (golden test vectors)
+- **Issue:** Research openssl cross-verification produced wrong HMAC value (`0c85780b...`) due to pipe+xxd binary corruption; correct value is `efa09db0...`
+- **Fix:** Computed correct value independently with Python hmac module and openssl file-based input, updated golden vector
+- **Files modified:** tests/golden.rs
+- **Verification:** All 7 golden tests pass; value matches Rust hmac crate, Python hmac, and openssl (file)
+- **Committed in:** 329bed6 (Task 1 commit)
+
+**2. [Rule 1 - Bug] Replaced deprecated assert_cmd API**
+- **Found during:** Task 2 (round-trip tests)
+- **Issue:** `Command::cargo_bin()` deprecated in assert_cmd 2.1 with warning about custom cargo build-dir incompatibility
+- **Fix:** Used `cargo_bin!("encrypted_archive")` macro which resolves at compile time via `CARGO_BIN_EXE_` env var
+- **Files modified:** tests/round_trip.rs
+- **Verification:** Zero deprecation warnings, all 6 round-trip tests pass
+- **Committed in:** 91ee354 (Task 2 commit)
+
+---
+
+**Total deviations:** 2 auto-fixed (2 bugs)
+**Impact on plan:** Both fixes necessary for correctness and clean builds. No scope change.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Phase 3 fully complete: 32 tests (19 unit + 7 golden + 6 integration) all pass
+- All Phase 3 success criteria met: byte-identical round-trips, golden vectors, unit tests, edge cases (empty, >10MB, Cyrillic)
+- Ready for Phase 4 (CLI polish) or Phase 5 (shell decoder)
+
+## Self-Check: PASSED
+
+- All 2 key files exist on disk: tests/golden.rs, tests/round_trip.rs
+- Both task commits verified: 329bed6, 91ee354
+- cargo test: 32 passed (19 unit + 7 golden + 6 integration), 0 failed
+
+---
+*Phase: 03-round-trip-verification*
+*Completed: 2026-02-24*