docs: add project research

.planning/research/SUMMARY.md

@@ -0,0 +1,76 @@
+# Research Summary
+
+**Project:** encrypted_archive
+**Researched:** 2026-02-24
+
+## Stack Decision
+
+| Layer | Choice | Rationale |
+|-------|--------|-----------|
+| Language (archiver) | Rust | Memory safety, crypto ecosystem, cross-compilation |
+| Encryption | AES-256-CBC + HMAC-SHA256 | Only cipher reliably available in busybox openssl + javax.crypto + RustCrypto |
+| Compression | gzip (DEFLATE) via `flate2` | Native everywhere: Rust, Android GZIPInputStream, busybox gunzip |
+| CLI | `clap` v4 | De facto Rust standard |
+| Binary format | Manual byte I/O | Full control for obfuscation; no recognizable patterns |
+| Kotlin decoder | javax.crypto + java.util.zip | Zero external dependencies, Android SDK built-in |
+| Shell decoder | dd + xxd + openssl + gunzip | Standard busybox applets |
+
+**Critical constraint:** busybox shell is the weakest link. Every technology choice is validated against "can busybox do this?"
+
+## Table Stakes Features
+
+1. Multi-file packing/unpacking (texts + APKs)
+2. AES-256-CBC encryption with HMAC-SHA256 (encrypt-then-MAC)
+3. Gzip compression before encryption
+4. Custom magic bytes (not recognizable by binwalk/file/7z)
+5. Hardcoded 32-byte key in all decoders
+6. Per-file IV (random 16 bytes, stored in cleartext)
+7. Round-trip fidelity (byte-identical decompression)
+8. Kotlin decoder (primary, Android 13)
+9. Shell decoder (fallback, busybox)
+10. File metadata (name, sizes, offsets)
+11. Data integrity (SHA-256 checksums per file)
+
+## Architecture
+
+Three independent implementations unified by a shared format specification:
+
+```
+FORMAT SPEC (shared document)
+    |
+    +-- Rust Archiver (CLI, Linux/macOS)
+    +-- Kotlin Decoder (Android 13, primary)
+    +-- Shell Decoder (busybox, fallback)
+```
+
+**Rust archiver pipeline:** collect → compress → encrypt → format → obfuscate
+
+**Key patterns:**
+- Per-file independence (each file compressed/encrypted separately)
+- Encrypt-then-MAC (HMAC over IV || ciphertext)
+- Little-endian everywhere
+- Format version field for forward compatibility
+
+## Top Pitfalls to Prevent
+
+1. **busybox openssl cipher availability** — test on actual device before format design
+2. **OpenSSL key derivation mismatch** — use `-K HEX -iv HEX -nosalt` for raw keys
+3. **Cross-platform crypto incompatibility** — golden test vectors mandatory
+4. **Over-engineering obfuscation** — AES encryption IS obfuscation for casual users
+5. **APKs don't compress** — per-file compression flag needed
+
+## Recommended Build Order
+
+1. **Format spec + busybox feasibility proof** — validate constraints first
+2. **Rust archiver** — core pipeline (compress → encrypt → format)
+3. **Rust test decoder** — catch format bugs in same language
+4. **Kotlin decoder** — primary extraction path
+5. **Shell decoder** — busybox fallback
+6. **Obfuscation hardening + integration testing** — binwalk/file/strings testing
+
+## Open Questions
+
+- Does target busybox have `openssl enc -aes-256-cbc` with `-K`/`-iv` flags?
+- Is `xxd` available in target busybox? (fallback: `od`)
+- Is `gunzip` available in target busybox?
+- Should HMAC use same key as AES or derived subkey?