# HTTP API зашифрованных файлов личных сообщений > **Текущий протокол DM v3 (2026-11):** новые вложения отправляются напрямую в R2 `shine-dm` после `POST /api/dm-files/prepare`; скачиваются по `https://dm-files.<домен access-сервера отправителя>/`. Большие файлы шифруются по 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-тип или ключ расшифрования. Клиент: 1. генерирует случайный AES-256-GCM key и 96-bit IV; 2. шифрует файл в браузере; 3. считает `SHA-256(ciphertext)`; 4. переводит 32-byte hash в Base58 — это `fileId` и имя файла на диске сервера; 5. для нового v3 загружает ciphertext напрямую в R2 (ниже описан legacy v1/v2); 6. помещает ID ciphertext, key, IV, исходное имя/MIME/размер в `` (новый v3 без URL) внутри plaintext DM; 7. обычный механизм E2EE DM шифрует эту техническую вставку отдельно для отправителя и получателя. Следствие: сервер файлов не знает AES-key и не может расшифровать вложение. ## 2. Конфигурация сервера ```properties 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` обязан быть равен: ```text Base58(SHA-256(ciphertext)) ``` ### Заголовки авторизации ```text Content-Type: application/octet-stream X-Shine-Session-Id: X-Shine-Time-Ms: X-Shine-Content-Length: X-Shine-Signature: ``` Подписываемая UTF-8 строка: ```text DM_FILE_UPLOAD_V1:{sessionId}:{fileId}:{encryptedSize}:{timeMs} ``` Подпись проверяется публичным `session_key` из активной сессии. Допустимое отклонение времени — 60 секунд. Сервер потоково пишет временный файл, одновременно считает SHA-256, проверяет фактический размер и только после успешной проверки атомарно перемещает объект под именем `{fileId}`. Повторная корректно подписанная загрузка уже существующего immutable объекта идемпотентна. Перед ответом `alreadyExists=true` сервер повторно вычисляет `SHA-256` уже сохранённого объекта и сверяет его с `fileId`; одного совпадения имени файла на диске недостаточно. Если объект повреждён или подменён, сервер удаляет некорректную копию и принимает корректный `PUT` заново. Успешный ответ: ```json { "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-сервера отправителя>/`; GET публичный, но объект содержит только AES-GCM ciphertext. R2 объект содержит `Content-Type: application/octet-stream`; исходный MIME хранится внутри зашифрованного ``. Доступ к 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 в технической вставке ``: передаются `id` (Base58 SHA-256 ciphertext), ключи/IV и необходимые метаданные, а также новое поле `at` — время завершения загрузки в миллисекундах Unix. Имя файлового домена вычисляется по отправителю: `dm-files.`. Клиент узнаёт адрес через общий `GET /api/files/user-server?login=` на своём 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.<домен>/` для проверки конфликтов при PUT. Отдельный R2 public URL в конфигурации не нужен. Публичный адрес файла должен поддерживать CORS GET/HEAD, а корзина R2 — прямой браузерный доступ. Для **новых R2 DM v3** после 14 дней от `at` клиент не делает скачивание и показывает сообщение об истечении срока. Для ранних v3 без `at` используется время сообщения. Это UX-гарантия клиента, а не физическое удаление: Cloudflare R2 lifecycle необходимо настроить отдельно. Старые локальные DM v1/v2 не помечаются истёкшими, поскольку для них не настроен R2 lifecycle.