Перевести вложения DM на R2 и обновить файловый API

This commit is contained in:
AidarKC
2026-11-15 14:33:52 +03:00
parent 3ecec25fce
commit 70540ff041
23 changed files with 770 additions and 202 deletions
+10 -1
View File
@@ -2,7 +2,7 @@
## 1. Назначение
Файлы личных сообщений хранятся только на access-сервере отправителя и только в зашифрованном виде.
Ранее файлы DM хранились только на access-сервере отправителя. **Новые DM v3** хранятся в Cloudflare R2 `shine-dm`, а legacy `/dm-files` продолжает обслуживать старые файлы v1/v2.
HTTP API не получает исходное имя файла, MIME-тип или ключ расшифрования.
Клиент:
@@ -111,3 +111,12 @@ Caddy/Nginx должен проксировать `/dm-files/*` в тот же J
- 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.shineup.me/<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`.
+1 -1
View File
@@ -144,6 +144,6 @@ https://<current-access-server>/files/<sha256>
## R2 direct upload (MVP, 2026-11)
New public attachments use BitTorrent v2 `pr` (base64url 43 characters), `mm` (optional MIME) and `v=1`. Avatars retain the original SHA-256 `/files/<sha256>` API. The client signs `PUBLIC_R2_PREPARE_V1:{sessionId}:{pr}:{size}:{mm}:{timeMs}` with its Ed25519 session key, submits JSON `{pr,size,mm}` to `POST /api/files/prepare` and provides `X-Shine-Session-Id`, `X-Shine-Time-Ms` and `X-Shine-Signature`. The endpoint returns `exists`, `fileUrl`, and for missing objects `uploadUrl` and `requiredHeaders`. The browser uploads the original Blob directly to the S3 endpoint, not the Java server. A signature does not certify the hash of uploaded content. The public GET URL is `https://files.shineup.me/<pr>`.
New public attachments use BitTorrent v2 `pr` (canonical Base58 encoding of the 32-byte Pieces Root, normally 43–44 characters, variable length 32–44), `mm` (optional MIME) and `v=1`. Avatars retain the original SHA-256 `/files/<sha256>` API. The client signs `PUBLIC_R2_PREPARE_V1:{sessionId}:{pr}:{size}:{mm}:{timeMs}` with its Ed25519 session key, submits JSON `{pr,size,mm}` to `POST /api/files/prepare` and provides `X-Shine-Session-Id`, `X-Shine-Time-Ms` and `X-Shine-Signature`. The endpoint returns `exists`, `fileUrl`, and for missing objects `uploadUrl` and `requiredHeaders`. The browser uploads the original Blob directly to the S3 endpoint, not the Java server. A signature does not certify the hash of uploaded content. The public GET URL is `https://files.shineup.me/<pr>`; the R2 object key is exactly the same Base58 `pr` (no extension). Old Base64URL PR identifiers are not read or migrated. Arweave TX IDs and DM file identifiers keep their existing encodings. Client and Java server must be updated together.
Configuration: `R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `r2.publicBucket=shine-files` (or `r2.endpoint`, `r2.accessKeyId`, `r2.secretAccessKey` in trusted server config). Never publish keys. Configure browser CORS to permit signed PUT headers including `If-None-Match`. Max size: 500 MiB. Single PUT only, no multipart in this MVP.
+6 -5
View File
@@ -9,10 +9,11 @@
- `docs/Personal_Messages/Доставка_и_синхронизация_DM.md` — доставка на
единственный access-сервер, retry-воркер и UI-статусы
- `docs/Personal_Messages/Технические_вставки_DM_v1.md` — формат специальных `<S:...>` вставок внутри plaintext DM после расшифровки
- `docs/Personal_Messages/Файлы_DM_v2.md` — большие chunked-вложения, голосовые и BitTorrent v2 SHA-256/Merkle metadata
- `docs/Personal_Messages/Файлы_DM_v2.md` — старый формат chunked-вложений с BitTorrent v2 (только чтение);
- `docs/Personal_Messages/Файлы_DM_v3_R2.md` — **новые** chunked-вложения и голосовые в Cloudflare R2, AES-GCM, SHA-256/Base58
- `docs/API/18_DM_File_Storage_API.md` — HTTP-хранилище зашифрованных файлов DM на access-сервере отправителя
Документы с версиями `v1` и `v2` описывают разные уровни: `v1` — контейнер и доставка сообщения, `v2` — формат больших файлов внутри зашифрованного содержимого DM. Реализация `v2` находится в `shine-UI/js/services/dm-file-service.js` и `dm-tech-blocks.js`.
Документы с версиями `v1`, `v2` и `v3` описывают разные уровни: `v1` — контейнер и доставка сообщения, `v2` — старый формат больших файлов, `v3` — новые файлы в R2 без BitTorrent. Клиентская реализация находится в `shine-UI/js/services/dm-file-service.js` и `dm-tech-blocks.js`.
Правило сопровождения:
@@ -22,12 +23,12 @@
## Зашифрованные файлы DM
Официальный UI v1 умеет отправлять файл как внешний зашифрованный объект:
Официальный UI v3 отправляет файл как зашифрованные объекты R2 (чтение старого v1/v2 поддерживается):
- файл шифруется в браузере `AES-256-GCM`;
- ciphertext хранится только на access-сервере отправителя под именем `Base58(SHA-256(ciphertext))`;
- новый ciphertext хранится в корзине `shine-dm` по адресу `https://dm-files.shineup.me/<Base58(SHA-256(ciphertext))>`;
- AES-key, IV, исходное имя, MIME, размер и URL находятся в `<S:file...>` внутри plaintext DM, а значит сами защищены существующим E2EE DM;
- получатель скачивает ciphertext с сервера отправителя, проверяет SHA-256, расшифровывает локально и только затем отдаёт Blob браузеру для сохранения под исходным именем;
- получатель скачивает новый ciphertext напрямую из R2, проверяет SHA-256, расшифровывает локально и только затем отдаёт Blob браузеру для сохранения под исходным именем;
- сервер файлов ключ расшифрования не получает.
Формат бинарного контейнера `SHiNE_DM` при этом не меняется.
@@ -195,3 +195,14 @@ fromLogin|toLogin|timeMs|nonce
В одном plaintext DM разрешено несколько последовательных `<S:file...>` блоков. Официальный UI собирает их в один список вложений и скрывает fallback-текст.
Подробный формат chunk encryption, manifest pages и BitTorrent v2 hashing: `Файлы_DM_v2.md`.
## 11. Новый `file` v3 — R2 без BitTorrent
Новые вложения и голосовые сообщения отправляются только в `v=3`, при этом продолжается чтение v1 и v2:
```text
<S:file;v=3;id=BASE58_SHA256_ROOT_CIPHERTEXT;url=ENCODED_HTTPS_DM_FILES_URL;key=BASE64URL_AES_KEY;ivp=BASE64URL_4BYTE_PREFIX;name=ENCODED_NAME;mime=ENCODED_MIME;size=10485760;encsize=104859XX;chunk=8388608;chunks=2;kind=file;dur=0>
```
Здесь **нет** `th` или `pr`; `id` обозначает SHA-256 **зашифрованного корневого манифеста** в Base58. Все части и манифест шифруются AES-256-GCM, хранятся по `Base58(SHA-256(ciphertext))`. Встроенный MIME по-прежнему называется `mime` в DM-протоколе (сокращение `mm` касается публичного `S:att`). Бинарный E2EE-контейнер не меняется. Подробности: `Файлы_DM_v3_R2.md`.
@@ -0,0 +1,94 @@
# DM file v3: Cloudflare R2, AES-GCM, SHA-256 / Base58
## Назначение
Все **новые** файлы и голосовые сообщения DM официального PWA загружаются непосредственно в R2 `shine-dm`.
Содержимое файлов Java-сервером не проксируется, а сервер выдаёт временные S3 PUT URL после проверки Ed25519-сессии.
Скачивание публичное по `https://dm-files.shineup.me/<id>`: там хранится **только ciphertext**.
Ключ AES, префикс IV, имя, MIME и размер помещаются внутрь уже E2EE-зашифрованного сообщения.
В v3 **нет BitTorrent, Merkle/`pieces root` и infohash**. Они сохранились только для чтения ранее отправленных DM v2.
## Как создаётся файл
- Клиент делит исходный файл на куски по **8 МиБ**; это границы шифрования, а не торрентные pieces.
- На всё вложение генерируется новый случайный AES-256-GCM key и новый 4-байтный IV prefix.
- Для каждой части используется отдельный 12-байтный IV: `prefix[4] || uint64_be(index)`; AAD содержит домен `chunk`, index и IV prefix. IV страниц манифеста и корня зарезервированы отдельно, как в v2.
- Каждая часть шифруется независимо и получает идентификатор **`Base58(SHA-256(ciphertext))`**.
- Клиент загружает части параллельно не более чем по одной (последовательно) через подписанные URL (без Multipart).
- Список частей помещается **в один зашифрованный корневой манифест**, который также получает собственный SHA-256/Base58 ID и загружается в R2.
- Итоговая `<S:file;v=3...>`-вставка с ключом и ссылкой на root manifest передаётся только внутри обычного E2EE DM.
Максимальный размер оригинального файла в этом MVP — **500 МиБ**. Обычная загрузка одного ciphertext-объекта — до `8 МиБ + 16` байт. Дополнительная проверка хеша исходного plaintext не требуется: каждый объект проверяется по SHA-256 ciphertext, а расшифрование AES-GCM аутентифицирует содержимое каждого куска и его порядковый номер.
## Манифест после расшифрования
```json
{
"v": 3,
"scheme": "SHINE-DM-R2-AES-256-GCM",
"chunkSize": 8388608,
"fileSize": 10485760,
"chunkCount": 2,
"chunks": [
{"i": 0, "id": "<Base58 SHA256 ciphertext>", "ps": 8388608, "es": 8388624},
{"i": 1, "id": "<Base58 SHA256 ciphertext>", "ps": 2097152, "es": 2097168}
]
}
```
`ps` — размер plaintext, `es = ps + 16` — размер ciphertext с GCM tag. Манифест и любой отдельный chunk в R2 имеют `Content-Type: application/octet-stream`; MIME исходного файла хранится **только в E2EE технической вставке**.
## Загрузка через R2
`POST /api/dm-files/prepare` с JSON `{ "fileId": "Base58_SHA256_CIPHERTEXT", "size": 8388624 }`.
Заголовки:
- `X-Shine-Session-Id`
- `X-Shine-Time-Ms`
- `X-Shine-Signature` — Base64 Ed25519 подписи активным session key.
Подписываемая UTF-8 строка:
```
DM_R2_PREPARE_V1:{sessionId}:{fileId}:{size}:{timeMs}
```
Сервер проверяет действующую сессию и размер, выполняет S3 `HeadObject` в `shine-dm`, затем возвращает:
- `exists: true` — объект уже существует и совпадает по размеру;
- либо `exists: false`, `uploadUrl` и `requiredHeaders` для одноразового по назначению (но действующего в течение срока) S3 PUT. PUT требует `If-None-Match: *` для исключения перезаписи.
Срок действия ссылки: 30 минут. Сервер не проверяет SHA-256 загруженного ciphertext, поэтому клиент при чтении **обязан** проверить Base58(SHA-256(downloadedCiphertext)) перед расшифрованием. SHA-256 объекта не равен S3 ETag.
## Скачивание
1. Скачать ciphertext root manifest по адресу, записанному в E2EE-сообщении.
2. Проверить `Base58(SHA-256(ciphertext)) == id`.
3. Расшифровать AES-GCM и проверить структуру манифеста.
4. Получить каждую зашифрованную часть напрямую с `dm-files.shineup.me/<id>`.
5. Проверить SHA-256 каждой части, расшифровать AES-GCM, проверить порядок и длину.
6. Последовательно записать исходные данные в браузерный поток сохранения или Blob fallback.
## Настройка Cloudflare
- R2 Bucket: `shine-dm`, публичный custom domain `dm-files.shineup.me` (в R2 только шифротекст).
- Object Lifecycle: удалить объекты через 14 дней (Cloudflare выполняет удаление асинхронно).
- CDN-кэширование разрешено: файлы могут оставаться доступными из кэша после удаления из R2, гарантий точного срока недоступности нет.
- CORS: с origin сайта SHiNE разрешить `GET`, `HEAD`, `PUT`; `AllowedHeaders: ["*"]`; `ExposeHeaders: ["Content-Length", "ETag"]`.
- Секреты S3 (`R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`) задаются **на Java-сервере**, никак не в браузере.
- `r2.dmBucket=shine-dm` в конфигурации Java.
- Обеспечить reverse proxy **только нового** `POST /api/dm-files/prepare` к Java-серверу (до SPA fallback), помимо уже действующего `/dm-files/*` для старых DM.
- Токен R2 должен иметь Object Read & Write для обоих buckets `shine-files` и `shine-dm`.
## Совместимость
DM v1 и DM v2 читаются прежними обработчиками (с локальных старых URL), но новые вложения генерируются **только v3**. В v2 используется BitTorrent v2, в v3 — нет. Старым клиентам v3 необходимо обновление: это новая версия технической вставки. Бинарный формат E2EE-контейнера DM и его криптопротокол не меняются.
## Границы MVP и ограничения
- Нет Multipart Upload в S3, нет возобновления одного незавершённого PUT.
- Java-сервер не доказывает соответствие присланных байтов объявленному SHA-256; повреждённые объекты обнаруживаются получателем. Подмена первого объекта до дедупликации требует отдельной доверенной проверки в будущем.
- Заявленный размер и URL не защищают от всех злоупотреблений: для публичного запуска дополнительно нужны лимиты и мониторинг R2-расходов.
- Удаление из R2 не удаляет уже скачанные копии, CDN-кэш и копии у получателей.