# ADR-0008. Защита персональных данных

- Статус: принято, реализовано на этапе 2
- Дата: 2026-09-30, уточнение — 2026-10-02

## Контекст

Мерчант — оператор ПДн участников, платформа — обработчик по поручению. С 01.07.2025 запись и хранение
ПДн граждан РФ в зарубежных базах запрещены, с 01.09.2025 согласие оформляется отдельным документом,
за утечки введены крупные и оборотные штрафы.

## Решение

- Все первичные базы и резервные копии — только в российских ЦОД. Зарубежные сервисы (APNs, FCM,
  зарубежный мониторинг) не становятся местом первичной записи ПДн.
- Телефон и email шифруются на уровне приложения отдельным ключом ПДн (не `APP_KEY`), в шифротексте
  хранится идентификатор ключа для ротации. Поиск — по слепому индексу HMAC-SHA256 с отдельным ключом.
- Кассам и интерфейсам по умолчанию отдаются маскированные значения (`+7 *** ***-12-34`).
- В логах, событиях outbox, вебхуках и журнале аудита (ADR-0010) нет телефонов, email и токенов.
- Песочница для интеграторов (ADR-0012) принимает только тестовые телефоны и e-mail и шифрует данные своими ключами.
- Согласия хранятся с версией текста, каналом, временем и доказательством (код подтверждения, отметка).
- Обезличивание участника сохраняет целостность леджера: проводки остаются, ПДн удаляются.

## Реализация (этап 2)

- **Шифрование:** `Modules\Kernel\Security\PiiCipher`, XChaCha20-Poly1305 (libsodium). Шифротекст —
  `id_ключа:base64url(nonce|ciphertext)`. Ассоциированные данные — `тенант|таблица|id_записи|поле`: шифротекст
  нельзя перенести в другой тенант, запись или колонку. Ключи — `PII_ENCRYPTION_KEYS`
  (`k2:…,k1:…`, текущий первым), старые ключи только расшифровывают.
- **Слепой индекс:** `Modules\Kernel\Security\BlindIndex`, HMAC-SHA256 от `тенант\0поле\0значение`.
  Один и тот же телефон у разных мерчантов имеет несвязанные индексы: утечка таблицы не показывает общих
  клиентов. Ключ — `PII_BLIND_INDEX_KEY`; его смена требует пересчёта индексов.
- **Что хранится:** телефон и email — шифротекст, индекс и маска; имя и дата рождения — открыто (нужны для
  сегментации и поздравлений), но не пишутся в логи; номера карт — только индекс и последние 4 цифры;
  коды подтверждения и одноразовые коды для кассы — только HMAC.
- **Согласия:** документы и события append-only; согласие на обработку ПДн обязательно при регистрации.
- **Ключи генерирует** `php artisan pii:generate-keys` (не перезаписывает существующие). В проде ключи хранятся
  в менеджере секретов облака, не в образе.

## Последствия

- Поиск по частичному телефону или по имени через SQL невозможен: интерфейсы ищут по полному номеру,
  карте, внешнему ID или по имени (оно не шифруется).
- Потеря ключа ПДн делает телефоны и email нечитаемыми — резервное хранение ключей обязательно.

## Дополнение (этап 6a)

- E-mail сотрудников хранится так же, как контакты участников: шифртекст с контекстом `platform|users|<id>|email`,
  слепой индекс области `platform` и маска (ADR-0013). Наружу модуль `identity` отдаёт только маску; адрес
  расшифровывается внутри модуля — для писем самому сотруднику и для проверки, что пароль не построен из адреса.
- Ключи счётчиков попыток входа — HMAC введённого e-mail (`BlindIndex`), не адрес и не его простой хеш.
- Ошибки БД не несут значений запроса: соединения маскируют параметры в тексте `QueryException`
  (`mask_bindings_in_exception_messages`), а редактор логов скрывает строку `DETAIL` и значения, которые PostgreSQL
  повторяет в тексте ошибки, хеши паролей и превращает исключение в контексте записи в текст без аргументов стека.
- Текст исключения упавшей задачи очереди (`failed_jobs.exception`) очищается тем же редактором (этап 6b-3): отказ
  почтового сервера повторяет адрес получателя, ошибка БД — строку. Полезная нагрузка задач с ПДн зашифрована
  (`ShouldBeEncrypted`).

## Дополнение (этап 6f-6b-3a)

- Офлайн-пакет чеков (`receipt_batches.receipts`) хранит телефоны и карты участников, пока пакет не обработан; после
  обработки (и когда задание пакета сдалось или пакет никто не обработал за сутки — `receipts:finish-batches`)
  идентификаторы участников из него удаляются, у пакетов, обработанных раньше, — миграцией; результаты называют чеки
  по номерам.
- Веб-касса хранит на устройстве чеки, проданные без связи, с телефоном или картой участника — не дольше 72 часов и
  только до их приёма сервером (ADR-0016); показывает их маской, а чек, который сервер не принял, хранит только с маской.
  Оболочка устройства, которое не заработает никогда (отозвано, 180 дней без использования), отвечает
  `Clear-Site-Data: "storage"`, и браузер стирает хранилище кассы.
- Отпечаток запроса у ключа идемпотентности (`idempotency_keys.fingerprint`) — HMAC на ключе приложения: простой хэш
  тела с телефоном можно было бы подобрать перебором телефонов. После ротации ключа приложения отпечатки на прежних
  ключах (`APP_PREVIOUS_KEYS`) принимаются, пока их строки хранятся.
