android-encrypted-archiver/.planning/REQUIREMENTS.md

# Requirements: Encrypted Archive

**Defined:** 2026-02-24
**Core Value:** Архив невозможно распаковать без знания формата — стандартные утилиты не распознают содержимое

## v1 Requirements

### Format (Бинарный формат)

- [x] **FMT-01**: Кастомный бинарный формат с нестандартными magic bytes (не распознаётся binwalk/file/7z)
- [x] **FMT-02**: Поле версии формата (1 байт) для forward compatibility
- [x] **FMT-03**: Таблица файлов с метаданными: имя файла, original size, compressed size, encrypted size, offset, IV, HMAC
- [x] **FMT-04**: Little-endian для всех multi-byte полей
- [x] **FMT-05**: Спецификация формата как документ (до начала реализации)
- [ ] **FMT-06**: XOR-обфускация заголовков с фиксированным ключом
- [ ] **FMT-07**: Зашифрованная таблица файлов (отдельный IV)
- [ ] **FMT-08**: Decoy padding (случайные данные между блоками)

### Encryption (Шифрование)

- [x] **ENC-01**: AES-256-CBC шифрование каждого файла отдельно
- [x] **ENC-02**: HMAC-SHA256 аутентификация (encrypt-then-MAC) для каждого файла
- [x] **ENC-03**: Случайный 16-байтный IV для каждого файла, хранится в cleartext
- [x] **ENC-04**: Зашитый 32-байтный ключ (hardcoded во всех декодерах)
- [x] **ENC-05**: PKCS7 padding для AES-CBC

### Compression (Сжатие)

- [x] **CMP-01**: Gzip (DEFLATE) сжатие каждого файла перед шифрованием
- [x] **CMP-02**: Per-file флаг: сжатие или raw (пропуск для уже сжатых файлов типа APK)

### Integrity (Целостность)

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

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

- [x] **CLI-01**: Rust CLI утилита для создания архивов (Linux/macOS)
- [ ] **CLI-02**: Упаковка нескольких файлов (тексты + APK) в один архив
- [ ] **CLI-03**: Подкоманды: pack, unpack (для тестирования), inspect (для отладки)

### Kotlin Decoder (Kotlin декодер)

- [ ] **KOT-01**: Kotlin-код деархивации на Android 13 без native-библиотек
- [ ] **KOT-02**: Использование javax.crypto (AES/CBC/PKCS5Padding) и java.util.zip.GZIPInputStream
- [ ] **KOT-03**: Верификация HMAC перед дешифровкой
- [ ] **KOT-04**: Верификация SHA-256 чексуммы после декомпрессии

### 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 именами (кириллица)

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

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

## v2 Requirements

### Расширенная обфускация
- **OBF-01**: Shuffled blocks (хранение блоков в случайном порядке с scramble map)
- **OBF-02**: Fake headers (имитация JPEG/PNG для ввода в заблуждение анализаторов)

### UX
- **UX-01**: Progress reporting для больших архивов
- **UX-02**: Dry-run / validation mode (проверка без извлечения)
- **UX-03**: Configurable compression level

### Security
- **SEC-01**: Per-file derived keys (HKDF от master key + file index)
- **SEC-02**: Обфускация ключа в Kotlin APK (byte array + split hex в shell)

## Out of Scope

| Feature | Reason |
|---------|--------|
| GUI-интерфейс | CLI достаточен для разработчика |
| Windows-поддержка | Только Linux/macOS, WSL для Windows |
| Парольная защита (PBKDF2/Argon2) | Зашитый ключ, UX на магнитоле |
| Streaming/pipe | Файлы помещаются в память целиком |
| Вложенные архивы | Плоский список файлов |
| Асимметричное шифрование | Избыточно для hardcoded key модели |
| Self-extracting архивы | Shell-скрипт — отдельный файл |
| DRM / лицензирование | Не цель проекта |
| File permissions в архиве | Android управляет своими permissions |
| Дедупликация файлов | Разные файлы, нет дублей |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| FMT-01 | Phase 2 | Complete |
| FMT-02 | Phase 2 | Complete |
| FMT-03 | Phase 2 | Complete |
| FMT-04 | Phase 2 | Complete |
| FMT-05 | Phase 1 | Complete |
| FMT-06 | Phase 6 | Pending |
| FMT-07 | Phase 6 | Pending |
| FMT-08 | Phase 6 | Pending |
| ENC-01 | Phase 2 | Complete |
| ENC-02 | Phase 2 | Complete |
| ENC-03 | Phase 2 | Complete |
| ENC-04 | Phase 2 | Complete |
| ENC-05 | Phase 2 | Complete |
| CMP-01 | Phase 2 | Complete |
| CMP-02 | Phase 2 | Complete |
| INT-01 | Phase 2 | Complete |
| INT-02 | Phase 3 | Pending |
| CLI-01 | Phase 2 | Complete |
| CLI-02 | Phase 2 | Pending |
| CLI-03 | Phase 2 | Pending |
| KOT-01 | Phase 4 | Pending |
| KOT-02 | Phase 4 | Pending |
| KOT-03 | Phase 4 | Pending |
| KOT-04 | Phase 4 | Pending |
| 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-03 | Phase 3 | Pending |

**Coverage:**
- v1 requirements: 30 total
- Mapped to phases: 30
- Unmapped: 0

---
*Requirements defined: 2026-02-24*
*Last updated: 2026-02-24 after roadmap creation*