---
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*