Entrixy — E2EE архитектура

Zero-knowledge архитектура: сервер не имеет ключей расшифровки ни для чего, кроме технических идентификаторов. Все содержательные поля (телефоны, URL, координаты, webhook-секреты, Wi-Fi BSSID, приветствия) шифруются на устройстве владельца и лежат на сервере как непрозрачный blob. Ключ для расшифровки выдаётся гостю внутри ссылки-приглашения (в URL-fragment, который браузер не отправляет серверу).

1. Цели и границы

Конфиденциальность содержимого. Сервер не знает адрес шлагбаума, номер телефона, url webhook'а, геокоординат, BSSID Wi-Fi, текст приветствия.
Проверяемость целостности. Любая попытка сервера подменить blob ломает расшифровку (AES-GCM). Клиент честно видит «повреждённые данные».
Forward-compatibility по ключам. Гость получает доступ только к тем объектам, которые конкретно ему разрешены. Даже компрометация одного гостевого ключа не раскрывает другие.
Граница zero-knowledge. Сервер видит: факт существования ключа, таймстемпы активности, идентификаторы объектов (для роутинга). Это приемлемо для MVP. Скрытие метаданных (onion) не входит в scope.

2. Крипто-примитив

Алгоритм: AES-256-GCM. Доступен из коробки в JVM (через javax.crypto), поддержан Android Keystore. Даёт одновременно конфиденциальность и аутентификацию.

Формат ciphertext

v1:<base64url(nonce || ciphertext || tag)>

v1: — префикс версии, на будущее для ротации формата.
nonce — 12 байт, рандом на каждую шифровку.
ciphertext+tag — всё что отдаёт Cipher.doFinal. Tag 128-bit встроен.
base64url без padding — безопасно в URL и JSON.

Источник энтропии

SecureRandom() (системный). На Android это /dev/urandom + Linux prng.

3. Иерархия ключей

K_master — мастер-ключ владельца

32 случайных байта, генерируется на первом запуске.
Хранится в EncryptedSharedPreferences — `"master_key"`. Никогда не покидает устройство в открытом виде.
Используется только для обёртки `K_obj` при локальном хранении.

K_obj — ключ объекта

32 случайных байта, генерируется при создании каждого объекта.
Локально хранится как `encrypt_k_master(K_obj)` под ключом `"obj_key_{id}"`.
Им шифруется JSON всех чувствительных полей объекта (data_cipher на сервере).
Ротация = новый K_obj_new → пере-зашифровать data_cipher + все бандлы, где он был.

K_guest — ключ гостевого бандла

32 случайных байта, генерируется при создании гостевого ключа.
Им шифруется bundle — маленький JSON {obj_id: K_obj} для объектов, разрешённых гостю.
На сервер уходит только bundle_cipher. Сам K_guest сервер не видит.
K_guest попадает гостю через URL-fragment: gate.simfolder.com/go/<user_key>#k=<base64url(K_guest)>. Fragment не отправляется серверу при HTTP-запросе — это базовая браузерная гарантия.

Ротация K_guest невозможна без выдачи новой ссылки. Это и есть «отзыв доступа»: сервер удаляет строку ключа, гость теряет возможность получить актуальный bundle_cipher.

4. Что где лежит

На устройстве владельца (EncryptedSharedPreferences)

Ключ	Значение
`master_key`	32 байта plain (SharedPreferences уже сам шифрует).
`obj_key_{id}`	K_obj объекта, обёрнутый K_master.
`obj_plain_{id}`	(опционально) кэш расшифрованного JSON, чтобы быстро рисовать UI.

На сервере

Таблица / поле	Содержимое
`numbers.data_cipher`	Зашифрованный K_obj-ом JSON: `{phone, url, secret, geo_lat, geo_lon, share_lat, share_lon, snapshot, welcome, label}`.
`numbers.id / type`	Plain — нужно для роутинга и отображения типа иконки.
`keys.bundle_cipher`	Зашифрованный K_guest-ом JSON: `{obj_ids: [1,2,3], obj_keys: {1: K_obj1, 2: K_obj2, ...}, welcome_cipher: ..., ...}`.
`keys.user_key / mode / force_when_busy`	Plain — для роутинга и быстрого access-чека.

Приветствие гостю шифруется отдельно внутри бандла — чтобы сервер не видел и его тоже.

5. Формат ссылки-приглашения

https://entrixy.com/go/<user_key>#k=<K_guest_base64url>&v=1

user_key — существующий server-side идентификатор. Без него сервер не отдаст bundle.
Fragment (#...) не попадает в server-log. Это гарантия браузера.
Лендинг gate.simfolder.com/go/* — чистый JS, читает location.hash, пихает в intent Entrixy приложения (intent://...) чтобы K_guest попал прямо в клиент без round-trip через сервер.
Если APK не установлен — лендинг показывает кнопку «Скачать» и хранит hash в sessionStorage до следующего открытия.

6. Основные flow

Создание объекта

Владелец жмёт «Добавить». Генерируется K_obj.
Поля упаковываются в JSON, шифруются K_obj → data_cipher.
POST /api/number_add с data_cipher + type. Сервер возвращает id.
Локально сохраняется obj_key_{id} = encrypt_k_master(K_obj).

Обновление объекта

Локально собираем новый JSON → шифруем существующим K_obj → POST /api/number_update. K_obj не меняется.

Создание гостевого ключа

Владелец выбрал [obj1, obj2, obj3]. Генерируется K_guest.
Собирается bundle JSON: {obj_ids: [...], obj_keys: {1: K_obj1, ...}, welcome_cipher: ...}.
Шифруется K_guest → bundle_cipher.
POST /api/key_create с bundle_cipher, obj_ids (plain — для access-матрицы).
Сервер возвращает user_key.
Владельцу показывается QR gate.simfolder.com/go/{user_key}#k={base64url(K_guest)}.

Приём ключа гостем

Гость тапает QR или ссылку. Лендинг читает location.hash, передаёт в APK через intent.
Клиент запрашивает GET /api/key_info?user_key=X → получает bundle_cipher, список obj_ids.
Расшифровывает bundle K_guest-ом → получает {obj_keys, welcome}.
K_guest и расшифрованные obj_keys сохраняются в EncryptedSharedPreferences клиента-гостя.
Далее при каждом вызове: GET зашифрованный data_cipher объекта → расшифровка локальным obj_key_{id}.

Отзыв гостевого ключа

Владелец нажимает «Удалить» → POST /api/key_delete → сервер удаляет строку keys. Гость при следующем key_info получает 404 — доступ потерян.

Ротация объекта

Владелец жмёт «Перегенерировать ключ» в настройках объекта. Генерируется K_obj_new, все bundle_cipher с этим объектом пере-шифровываются (клиент их сам не знает — нужен отдельный бандл-rebuild на клиенте-владельце, который достаёт bundle_cipher каждого своего ключа, расшифровывает, вставляет K_obj_new, перешифровывает). На сервер идут новые blob-ы пачкой.

7. Backup / Restore

Потеря K_master = потеря доступа ко всем объектам и ключам. Обязателен экспорт.

Владелец задаёт парольную фразу (минимум 8 символов).
KDF: Argon2id (64 MB memory, 3 iterations, 1 thread) → derived 32-byte key.
Derived key шифрует K_master → получается master_backup_blob.
Blob отображается как QR и сохраняется в «Скачанные». Этот QR можно распечатать и положить в сейф.
Восстановление на новом устройстве: сканируется QR + вводится фраза → восстанавливается K_master → клиент пре-скачивает все obj_keys с сервера (они же лежат там в bundle для ключей владельца-себя) и ре-шифрует локально.

Без парольной фразы QR-бэкап — это просто голый K_master. Фраза обязательна.

8. Фазы внедрения

Фаза 2 — серверная миграция схемы (готово)

Все sensitive-поля вынесены в numbers.data_cipher и user_keys.bundle_cipher. Старые plain-колонки (phone, label, radius, time_*, geo_*, wifi_*, share_*, has_avatar, security_level, user_keys.label, hosts.label, pending_actions.phone, hosts.last_ip) удалены из БД (Фаза 7). webhook_url/webhook_secret остаются plain ТОЛЬКО для webhook_mode='server' — без них сервер не сможет стрелять HTTP. Для webhook_mode='phone' они шифруются в data_cipher.

9. Риски и митигации

Риск	Митигация
Потеря K_master	Обязательный backup-flow (Фаза 5). Warning-баннер пока backup не сделан.
Компрометация устройства владельца	Неизбежна — PIN/биометрия для запуска приложения. EncryptedSharedPreferences + Android Keystore.
Ротация ключа объекта — rebuild всех bundle	Клиент владельца хранит свою копию всех bundle_cipher локально (или тянет с сервера), пересобирает, шлёт пачкой. Операция редкая.
Сервер подменит bundle	AES-GCM tag не сойдётся → «повреждённый ключ». Клиент показывает ошибку.
Утечка K_guest через скрин QR	Никак — QR содержит K_guest. Владельцу рекомендуется показывать QR только доверенному гостю (как и раньше с паролем).
URL-fragment в истории браузера	Лендинг на gate сразу после считывания hash делает `history.replaceState(..., '#')` — fragment стирается.

Entrixy — End-to-End Encryption