13 KiB
HTTP API зашифрованных файлов личных сообщений
Текущий протокол DM v3 (2026-11): новые вложения отправляются напрямую в R2
shine-dmпослеPOST /api/dm-files/prepare; скачиваются поhttps://dm-files.<домен access-сервера отправителя>/<Base58(SHA-256(ciphertext))>. Большие файлы шифруются по 8 МиБ AES-256-GCM, список объектов находится в зашифрованном манифесте; 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-объекта — 8 МиБ + 16 байт. Подписанный 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.