Files
SHiNE-server/docs/API/18_DM_File_Storage_API.md
T

13 KiB
Raw Blame History

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-тип или ключ расшифрования.

Клиент:

  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/размер в <S:file...> (новый v3 без URL) внутри plaintext DM;
  7. обычный механизм 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.