13 KiB
HTTP API зашифрованных файлов личных сообщений
Текущий протокол DM v3 (2026-11): новые вложения отправляются напрямую в R2
shine-dmпослеPOST /api/dm-files/prepare; скачиваются поhttps://dm-files.<домен access-сервера отправителя>/<Base58(SHA-256(ciphertext))>. Новые файлы шифруются по 64 МиБ AES-256-GCM (старые v3 по 8 МиБ читаются), список объектов находится в зашифрованном манифесте; BitTorrent v2 используется только в старых DM v2. Ниже разделыPUT /dm-files/{fileId}иGET /dm-files/{fileId}описывают legacy локальный сервер для v1/v2, а не новый R2. Полный текущий контракт см.docs/Personal_Messages/Файлы_DM_v3_R2.md.
Статистика v42: сервер при успешной выдаче presigned URL или обнаружении уже существующего шифротекста добавляет запись в
dm_file_uploads(user_login,file_hash,file_size_bytes,requested_at,disposition). Каждая зашифрованная часть/манифест — отдельный объект, имена и MIME исходного файла не сохраняются. Запись не доказывает успешный PUT. Шифрование, DM-протокол и клиент не изменяются.
1. Назначение
Ранее файлы DM хранились только на access-сервере отправителя. Новые DM v3 хранятся в Cloudflare R2 shine-dm, а legacy /dm-files продолжает обслуживать старые файлы v1/v2.
HTTP API не получает исходное имя файла, MIME-тип или ключ расшифрования.
Клиент:
- генерирует случайный AES-256-GCM key и 96-bit IV;
- шифрует файл в браузере;
- считает
SHA-256(ciphertext); - переводит 32-byte hash в Base58 — это
fileIdи имя файла на диске сервера; - для нового v3 загружает ciphertext напрямую в R2 (ниже описан legacy v1/v2);
- помещает ID ciphertext, key, IV, исходное имя/MIME/размер в
<S:file...>(новый v3 без URL) внутри plaintext DM; - обычный механизм E2EE DM шифрует эту техническую вставку отдельно для отправителя и получателя.
Следствие: сервер файлов не знает AES-key и не может расшифровать вложение.
2. Конфигурация сервера
dm.files.enabled=true
dm.files.storageDir=data/dm-files
dm.files.maxBytes=52428816
dm.files.maxBytes ограничивает размер одного ciphertext-объекта. Для legacy DM file v1 это фактически ограничивало целый файл. В DM file v2 файл состоит из 1-MiB ciphertext-объектов, поэтому общий размер логического файла этим параметром не ограничивается.
3. PUT /dm-files/{fileId}
Загружает immutable ciphertext.
fileId обязан быть равен:
Base58(SHA-256(ciphertext))
Заголовки авторизации
Content-Type: application/octet-stream
X-Shine-Session-Id: <active session id>
X-Shine-Time-Ms: <unix time ms>
X-Shine-Content-Length: <ciphertext bytes>
X-Shine-Signature: <Ed25519 signature, Base64>
Подписываемая UTF-8 строка:
DM_FILE_UPLOAD_V1:{sessionId}:{fileId}:{encryptedSize}:{timeMs}
Подпись проверяется публичным session_key из активной сессии. Допустимое отклонение времени — 60 секунд.
Сервер потоково пишет временный файл, одновременно считает SHA-256, проверяет фактический размер и только после успешной проверки атомарно перемещает объект под именем {fileId}.
Повторная корректно подписанная загрузка уже существующего immutable объекта идемпотентна. Перед ответом alreadyExists=true сервер повторно вычисляет SHA-256 уже сохранённого объекта и сверяет его с fileId; одного совпадения имени файла на диске недостаточно. Если объект повреждён или подменён, сервер удаляет некорректную копию и принимает корректный PUT заново.
Успешный ответ:
{
"ok": true,
"fileId": "...",
"size": 12345,
"alreadyExists": false
}
Основные ошибки: BAD_FILE_ID, MISSING_UPLOAD_AUTH, UPLOAD_AUTH_EXPIRED, BAD_UPLOAD_SIGNATURE, FILE_TOO_LARGE, LENGTH_MISMATCH, HASH_MISMATCH.
4. GET /dm-files/{fileId}
Возвращает только сохранённый ciphertext как application/octet-stream.
GET не требует пользовательской сессии: fileId является непредсказуемым 256-bit content address, а без AES-key содержимое остаётся зашифрованным. AES-key передаётся только внутри E2EE DM.
Ответ разрешает cross-origin чтение (Access-Control-Allow-Origin: *), потому что получатель может быть подключён к другому access-серверу и должен скачать ciphertext непосредственно с сервера отправителя.
Перед расшифрованием официальный UI повторно проверяет Base58(SHA-256(downloadedCiphertext)) == fileId.
5. HEAD и OPTIONS
HEAD /dm-files/{fileId}возвращает метаданные ciphertext без тела только после повторной проверкиBase58(SHA-256(ciphertext)) == fileId; официальный UI использует этот запрос передPUT, чтобы не отправлять уже существующие байты повторно;OPTIONS /dm-files/*обслуживает CORS preflight для браузерного PUT.
6. Reverse proxy
Caddy/Nginx должен проксировать /dm-files/* в тот же Jetty, что обслуживает /ws. Route должен находиться до SPA fallback.
7. Ограничения legacy v1
- legacy-файл перед загрузкой целиком читается в память браузера и ограничен 50 MiB;
- новые отправки официального UI используют v2 и этого ограничения не имеют;
- удаления/TTL/garbage collection пока нет;
- если ciphertext уже загружен, а отправка E2EE DM затем не удалась, объект может остаться orphan-файлом;
- resumable/chunked upload не входит в v1.
8. DM file v2: большие файлы
Начиная с UI v2 один логический файл не загружается одним HTTP-объектом. Клиент режет plaintext на 1 MiB части и каждый AES-GCM ciphertext-кусок загружает отдельным обычным PUT /dm-files/{fileId}.
Поэтому dm.files.maxBytes — это лимит одного immutable HTTP-объекта, а не всего пользовательского файла. При стандартном chunkSize=1 MiB общий размер файла этим параметром не ограничивается.
Манифест также хранится через тот же immutable API:
- encrypted manifest page — до 256 chunk descriptors;
- encrypted root manifest — ссылки на страницы + BitTorrent v2 root metadata.
Никаких новых доверенных серверных операций для v2 не требуется: сервер по-прежнему только проверяет подпись PUT, длину и Base58(SHA-256(ciphertext)).
9. Новый R2 API: POST /api/dm-files/prepare (DM v3)
Новые зашифрованные вложения загружаются браузером прямо в R2. Клиент посылает JSON { "fileId": "Base58_SHA256(ciphertext)", "size": 12345 } и подписанные заголовки X-Shine-Session-Id, X-Shine-Time-Ms, X-Shine-Signature. Строка Ed25519-подписи: DM_R2_PREPARE_V1:{sessionId}:{fileId}:{size}:{timeMs}. Сервер подтверждает существование объекта или выдаёт uploadUrl и requiredHeaders с условием If-None-Match: *.
Максимальный размер одного ciphertext-объекта для R2 DM v3 — 64 МиБ + 16 байт (67 108 880 байт). Новые вложения используют куски по 64 МиБ, а старые v3 с 8 МиБ продолжают читаться по chunkSize из зашифрованного манифеста. Максимальный размер исходного вложения остаётся 500 МиБ. Legacy dm.files.maxBytes не меняется. Подписанный PUT действителен 30 минут. Загрузка не идёт через Java. Новый URL скачивания: https://dm-files.<домен access-сервера отправителя>/<fileId>; GET публичный, но объект содержит только AES-GCM ciphertext. R2 объект содержит Content-Type: application/octet-stream; исходный MIME хранится внутри зашифрованного <S:file;v=3...>.
Доступ к R2 требует настроек r2.dmBucket=shine-dm и серверных R2_ENDPOINT, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY. Рекомендуется lifecycle rule 14 дней. Кэш CDN допускается и может продлить доступность ciphertext после удаления из R2. Сервер не гарантирует соответствие загруженных байтов hash: читающий клиент проверяет Base58(SHA-256(ciphertext)). Полный формат DM v3 описан в docs/Personal_Messages/Файлы_DM_v3_R2.md.
10. Федеративное R2-хранилище (16.11.2026)
У каждого access-сервера свои две корзины R2. Новый DM v3 не сохраняет полный URL в
технической вставке <S:file>: передаются id (Base58 SHA-256 ciphertext),
ключи/IV и необходимые метаданные, а также новое поле at — время завершения
загрузки в миллисекундах Unix. Имя файлового домена вычисляется по отправителю:
dm-files.<DNS-имя access-сервера>. Клиент узнаёт адрес через общий GET /api/files/user-server?login=<senderLogin> на своём access-сервере (из
синхронизированной PostgreSQL-проекции Solana). В RAM кэшируется соответствие
логин → сервер; при ошибке файла допускается один повторный поиск в час на
пользователя. Для DM v3 с ранее сохранённым url этот URL по-прежнему читается.
Формат бинарного E2EE-контейнера не меняется.
Сервер-владелец R2 получает DNS-адрес из собственной server-PDA в синхронизированной
PostgreSQL по server.SHiNE.login. POST /api/dm-files/prepare автоматически возвращает
fileUrl в формате https://dm-files.<домен>/<id> для проверки конфликтов при PUT.
Отдельный R2 public URL в конфигурации не нужен. Публичный адрес файла
должен поддерживать CORS GET/HEAD, а корзина R2 — прямой браузерный доступ.
Для новых R2 DM v3 после 14 дней от at клиент не делает скачивание и
показывает сообщение об истечении срока. Для ранних v3 без at используется
время сообщения. Это UX-гарантия клиента, а не физическое удаление: Cloudflare
R2 lifecycle необходимо настроить отдельно. Старые локальные DM v1/v2 не
помечаются истёкшими, поскольку для них не настроен R2 lifecycle.