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

# Requirements: Encrypted Archive

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

## v1.0 Requirements (Complete)

### 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**: Спецификация формата как документ (до начала реализации)
- [x] **FMT-06**: XOR-обфускация заголовков с фиксированным ключом
- [x] **FMT-07**: Зашифрованная таблица файлов (отдельный IV)
- [x] **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 чексумма для каждого файла (верификация после декомпрессии)
- [x] **INT-02**: Распакованные файлы byte-identical оригиналам (round-trip fidelity)

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

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

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

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

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

- [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 (Тестирование)

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

## v1.1 Requirements

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

- [x] **FMT-09**: Тип записи в TOC entry (файл/директория) — 1 байт
- [x] **FMT-10**: Unix permission bits (mode) в TOC entry — 2 байта (u16)
- [x] **FMT-11**: Относительные пути с `/` разделителем вместо filename-only
- [x] **FMT-12**: Обновлённая спецификация FORMAT.md с новыми полями

### Directory (Поддержка директорий)

- [x] **DIR-01**: `pack` рекурсивно обходит директории и добавляет все файлы
- [x] **DIR-02**: Относительные пути сохраняются при архивации (dir/subdir/file.txt)
- [x] **DIR-03**: Пустые директории сохраняются как записи типа "directory" в TOC
- [x] **DIR-04**: `unpack` создаёт полную иерархию директорий
- [x] **DIR-05**: `unpack` восстанавливает Unix mode bits для файлов и директорий

### Kotlin Decoder

- [ ] **KOT-05**: Парсинг нового TOC с типом записи и permissions
- [ ] **KOT-06**: Создание иерархии директорий при извлечении
- [ ] **KOT-07**: Установка permissions (File.setReadable/setWritable/setExecutable)

### Shell Decoder

- [ ] **SHL-04**: Парсинг нового TOC с типом записи и permissions
- [ ] **SHL-05**: mkdir -p для иерархии и пустых директорий
- [ ] **SHL-06**: chmod для восстановления permissions

### Testing

- [ ] **TST-04**: Round-trip с вложенными директориями (3+ уровня)
- [ ] **TST-05**: Round-trip с пустыми директориями
- [ ] **TST-06**: Проверка сохранения mode bits
- [ ] **TST-07**: Cross-validation: Rust archive → Kotlin/Shell decode с директориями

## Future 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 / лицензирование | Не цель проекта |
| Дедупликация файлов | Разные файлы, нет дублей |
| Симлинки и хардлинки | Только файлы и директории |
| uid/gid и timestamps | Только mode bits — достаточно для target use case |
| Обратная совместимость с v1.0 | Формат меняется, старые архивы не поддерживаются |

## 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 | Complete |
| FMT-07 | Phase 6 | Complete |
| FMT-08 | Phase 6 | Complete |
| 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 | Complete |
| CLI-01 | Phase 2 | Complete |
| CLI-02 | Phase 2 | Complete |
| CLI-03 | Phase 2 | Complete |
| KOT-01 | Phase 4 | Complete |
| KOT-02 | Phase 4 | Complete |
| KOT-03 | Phase 4 | Complete |
| KOT-04 | Phase 4 | Complete |
| 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 |
| FMT-09 | Phase 7 | Complete |
| FMT-10 | Phase 7 | Complete |
| FMT-11 | Phase 7 | Complete |
| FMT-12 | Phase 7 | Complete |
| DIR-01 | Phase 8 | Complete |
| DIR-02 | Phase 8 | Complete |
| DIR-03 | Phase 8 | Complete |
| DIR-04 | Phase 8 | Complete |
| DIR-05 | Phase 8 | Complete |
| KOT-05 | Phase 9 | Pending |
| KOT-06 | Phase 9 | Pending |
| KOT-07 | Phase 9 | Pending |
| SHL-04 | Phase 10 | Pending |
| SHL-05 | Phase 10 | Pending |
| SHL-06 | Phase 10 | Pending |
| TST-04 | Phase 11 | Pending |
| TST-05 | Phase 11 | Pending |
| TST-06 | Phase 11 | Pending |
| TST-07 | Phase 11 | Pending |

**Coverage:**
- v1.0 requirements: 30 total -- all Complete
- v1.1 requirements: 19 total -- all mapped to phases 7-11
- Mapped to phases: 19/19
- Unmapped: 0

---
*Requirements defined: 2026-02-24*
*Last updated: 2026-02-26 after Phase 8 completion (DIR-01 to DIR-05 complete)*