diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 6608d4c..de5595d 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -49,9 +49,9 @@ ### Shell Decoder (Shell декодер) -- [ ] **SHL-01**: Shell-скрипт деархивации через busybox (dd, xxd, openssl, gunzip) -- [ ] **SHL-02**: openssl enc -aes-256-cbc с -K/-iv/-nosalt для raw key mode -- [ ] **SHL-03**: Поддержка файлов с не-ASCII именами (кириллица) +- [x] **SHL-01**: Shell-скрипт деархивации через busybox (dd, xxd, openssl, gunzip) +- [x] **SHL-02**: openssl enc -aes-256-cbc с -K/-iv/-nosalt для raw key mode +- [x] **SHL-03**: Поддержка файлов с не-ASCII именами (кириллица) ### Testing (Тестирование) @@ -117,9 +117,9 @@ | KOT-02 | Phase 4 | Complete | | KOT-03 | Phase 4 | Complete | | KOT-04 | Phase 4 | Complete | -| SHL-01 | Phase 5 | Pending | -| SHL-02 | Phase 5 | Pending | -| SHL-03 | Phase 5 | Pending | +| SHL-01 | Phase 5 | Complete | +| SHL-02 | Phase 5 | Complete | +| SHL-03 | Phase 5 | Complete | | TST-01 | Phase 3 | Complete | | TST-02 | Phase 3 | Complete | | TST-03 | Phase 3 | Complete | diff --git a/.planning/STATE.md b/.planning/STATE.md index d494b75..eb91f55 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -5,22 +5,22 @@ 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 4 complete, ready for Phase 5 +**Current focus:** Phase 5 in progress (Shell Decoder) ## Current Position -Phase: 4 of 6 (Kotlin Decoder) -- COMPLETE -Plan: 1 of 1 in current phase (all done) -Status: Phase 4 complete, ready for Phase 5 -Last activity: 2026-02-25 -- Kotlin archive decoder with full decode pipeline and cross-validation test script +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: [██████░░░░] 60% +Progress: [███████░░░] 70% ## Performance Metrics **Velocity:** -- Total plans completed: 6 -- Average duration: 4.5 min +- Total plans completed: 7 +- Average duration: 4.1 min - Total execution time: 0.5 hours **By Phase:** @@ -31,9 +31,10 @@ Progress: [██████░░░░] 60% | 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: 4min, 2min, 3min, 5min, 4min +- Last 5 plans: 2min, 3min, 5min, 4min, 3min - Trend: stable *Updated after each plan completion* @@ -66,6 +67,11 @@ Recent decisions affecting current work: - 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 @@ -73,12 +79,12 @@ 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; spec includes od fallback functions) +- 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 04-01-PLAN.md (Kotlin decoder + cross-validation tests; Phase 4 complete) +Stopped at: Completed 05-01-PLAN.md (Shell decoder script; Phase 5 Plan 1 of 2) Resume file: None diff --git a/.planning/phases/05-shell-decoder/05-01-SUMMARY.md b/.planning/phases/05-shell-decoder/05-01-SUMMARY.md new file mode 100644 index 0000000..b4ffbb0 --- /dev/null +++ b/.planning/phases/05-shell-decoder/05-01-SUMMARY.md @@ -0,0 +1,98 @@ +--- +phase: 05-shell-decoder +plan: 01 +subsystem: shell-decoder +tags: [posix-sh, busybox, openssl, aes-256-cbc, dd, xxd, od, hmac, sha256] + +# Dependency graph +requires: + - phase: 01-format-specification + provides: "FORMAT.md binary format spec with shell decoder reference (Section 13)" + - phase: 02-core-archiver + provides: "Rust archiver for creating test archives" +provides: + - "shell/decode.sh -- busybox-compatible POSIX shell decoder script" + - "Full decode pipeline: header -> TOC -> HMAC verify -> decrypt -> decompress -> SHA-256 verify -> write" +affects: [06-obfuscation] + +# Tech tracking +tech-stack: + added: [sh, dd, openssl-enc, xxd, od, gunzip, sha256sum] + patterns: [posix-shell-binary-parsing, xxd-od-fallback, hmac-graceful-degradation] + +key-files: + created: + - shell/decode.sh + +key-decisions: + - "POSIX sh (not bash) for maximum busybox compatibility" + - "xxd/od auto-detection at startup for hex conversion" + - "Graceful HMAC degradation when openssl lacks -mac support" + - "Extract ciphertext to temp file before decryption (avoids pipe issues)" + - "LC_ALL=C for predictable byte handling" + +patterns-established: + - "dd-based binary parsing with hex byte-swap for little-endian integers" + - "Temp file cleanup via trap on EXIT" + - "HMAC computed from raw archive bytes (IV from TOC offset + ciphertext), not from hex variables" + +requirements-completed: [SHL-01, SHL-02, SHL-03] + +# Metrics +duration: 3min +completed: 2026-02-25 +--- + +# Phase 5 Plan 1: Shell Decoder Summary + +**Busybox-compatible POSIX shell decoder with full decode pipeline (dd+xxd/od for parsing, openssl enc for AES-256-CBC decryption, HMAC verification with graceful degradation, SHA-256 integrity checks)** + +## Performance + +- **Duration:** 3 min +- **Started:** 2026-02-24T22:37:48Z +- **Completed:** 2026-02-24T22:40:29Z +- **Tasks:** 1 +- **Files created:** 1 + +## Accomplishments +- Created self-contained POSIX shell decoder script (250 lines) implementing full FORMAT.md Section 10 decode pipeline +- Verified byte-identical extraction against Rust archiver output (ASCII and Cyrillic filenames) +- Implemented xxd/od auto-detection fallback for hex conversion on minimal busybox systems +- HMAC graceful degradation: detects openssl HMAC support at startup, skips with warning if unavailable + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Create shell/decode.sh with full decode pipeline** - `6df2639` (feat) + +## Files Created/Modified +- `shell/decode.sh` - Busybox-compatible POSIX shell script implementing complete archive decode pipeline + +## Decisions Made +- Used POSIX sh (not bash) with no bash-specific syntax for maximum compatibility +- Auto-detect xxd vs od at startup; define read_hex using whichever is available +- Graceful HMAC degradation: test openssl HMAC capability at startup, set SKIP_HMAC flag +- Extract ciphertext to temp file before decryption (avoids pipe buffering issues with openssl enc) +- Set LC_ALL=C at script top for predictable byte handling across locales +- Used printf-based substring extraction instead of bash ${var:offset:len} for POSIX compliance + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered +None. + +## User Setup Required +None - no external service configuration required. + +## Next Phase Readiness +- Shell decoder complete, ready for cross-validation testing in Plan 2 +- Script verified against Rust archiver with both ASCII and Cyrillic filenames +- Phase 6 (obfuscation) can extend the script with XOR header deobfuscation and TOC decryption + +--- +*Phase: 05-shell-decoder* +*Completed: 2026-02-25*