From 387836ca14f6b1197948d4691cc650e2eb1adf4f Mon Sep 17 00:00:00 2001 From: NikitolProject Date: Wed, 25 Feb 2026 00:42:05 +0300 Subject: [PATCH] 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 --- .planning/REQUIREMENTS.md | 14 +- .planning/ROADMAP.md | 6 +- .planning/STATE.md | 29 ++-- .../03-02-SUMMARY.md | 124 ++++++++++++++++++ 4 files changed, 150 insertions(+), 23 deletions(-) create mode 100644 .planning/phases/03-round-trip-verification/03-02-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index ec6efeb..1b97c8d 100644 --- 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* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 3596f61..e3d062e 100644 --- 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 | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index f05351b..03978dd 100644 --- 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 diff --git a/.planning/phases/03-round-trip-verification/03-02-SUMMARY.md b/.planning/phases/03-round-trip-verification/03-02-SUMMARY.md new file mode 100644 index 0000000..1783134 --- /dev/null +++ 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*