SHA256
Обновить хранение вложений R2
This commit is contained in:
@@ -1,5 +1,9 @@
|
||||
# HTTP API зашифрованных файлов личных сообщений
|
||||
|
||||
> **Текущий протокол DM v3 (2026-11):** новые вложения отправляются напрямую в R2 `shine-dm` после `POST /api/dm-files/prepare`; скачиваются по `https://dm-files.shineup.me/<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.
|
||||
@@ -11,7 +15,7 @@ HTTP API не получает исходное имя файла, MIME-тип
|
||||
2. шифрует файл в браузере;
|
||||
3. считает `SHA-256(ciphertext)`;
|
||||
4. переводит 32-byte hash в Base58 — это `fileId` и имя файла на диске сервера;
|
||||
5. загружает ciphertext на свой access-сервер;
|
||||
5. для нового v3 загружает ciphertext напрямую в R2 (ниже описан legacy v1/v2);
|
||||
6. помещает URL, key, IV, исходное имя/MIME/размер в `<S:file...>` внутри plaintext DM;
|
||||
7. обычный механизм E2EE DM шифрует эту техническую вставку отдельно для отправителя и получателя.
|
||||
|
||||
|
||||
@@ -1,155 +1,52 @@
|
||||
# HTTP API публичных файлов каналов
|
||||
# Публичные вложения SHiNE: Cloudflare R2 и legacy API
|
||||
|
||||
## 1. Назначение
|
||||
## Действующий формат (15.11.2026)
|
||||
|
||||
Публичное вложение может храниться не в Arweave, а на текущем сервере доступа автора.
|
||||
Файловый слой намеренно максимально простой: он хранит только байты, адресованные их SHA-256.
|
||||
Новые публичные файлы и аватары используют **BitTorrent v2 Pieces Root**, закодированный **Base58** (32 байта; строка обычно 43–44 символа). Идентификатор не зависит от имени и MIME. Клиент вычисляет корень по подготовленным байтам. Содержимое файла **не проходит через Java**.
|
||||
|
||||
Канонический URL:
|
||||
- R2 bucket: `shine-files`.
|
||||
- Публичный GET: `https://files.shineup.me/<PR>` (ключ объекта = `PR`, без расширения).
|
||||
- Предпросмотр публичных изображений и видео использует прямой URL. Картинки `loading="lazy"`; публичные видео получают `src` только у видимой области через `IntersectionObserver` и запрашивают метаданные после входа в область. В старом браузере используется обычная загрузка metadata.
|
||||
- Отдельных preview-файлов нет. Скачивание/просмотр медиаконтента выполняет сам браузер (в том числе HTTP Range, если доступен).
|
||||
- Тип определяется по `mm`, затем по расширению `nm`; HTTP `Content-Type` объекта задаётся при PUT. Неизвестные файлы — `application/octet-stream`.
|
||||
- HTML, SVG и похожие активные типы отображаются как обычные файловые карточки. Перед открытием **из публичного интерфейса** показывается предупреждение с возможностью отмены. Это не серверная санитаризация и не гарантия безопасности прямого URL.
|
||||
|
||||
Формат публичного вложения (версия тега остаётся 1):
|
||||
|
||||
```text
|
||||
/files/<sha256>
|
||||
<S:att;v=1;nm=photo.jpg;sz=123456;pr=BASE58_ROOT;mm=image/jpeg>
|
||||
```
|
||||
|
||||
`sha256` — lowercase hex, ровно 64 символа.
|
||||
При использовании Arweave дополнительно передаётся `;ar=TXID` — существующая загрузка Arweave/Turbo не меняется. Источник выбирается по `ar` (если есть), иначе R2 по `pr`. Не добавлять `storage=r2` в постоянные записи. Общее описание — `docs/Blockchain/15_TEXT_Attachments.md`.
|
||||
|
||||
На диске сервер хранит один глобальный объект:
|
||||
Новые аватары: `<S:ava;v=2;sz=N;pr=BASE58_ROOT[;ar=TXID]>`. SHA-256 hex остаётся лишь в исторических файловых маршрутах, **новые аватары SHA-256 не создают**. Старые аватары v1 не мигрируются автоматически (v41 сбрасывает старые ссылки каналов).
|
||||
|
||||
```text
|
||||
<public.files.storageDir>/<sha256>
|
||||
## Выдача разрешения на загрузку
|
||||
|
||||
`POST /api/files/prepare` (JSON):
|
||||
|
||||
```json
|
||||
{"pr":"BASE58_ROOT","size":123456,"mm":"image/jpeg"}
|
||||
```
|
||||
|
||||
Имя пользователя, исходное имя файла, расширение, MIME и ссылка на сообщение в файловом хранилище не нужны. Одинаковые байты, загруженные разными пользователями, дедуплицируются в один объект.
|
||||
Сессионная Ed25519-подпись обязательна. Заголовки:
|
||||
|
||||
## 2. Конфигурация Java-сервера
|
||||
- `X-Shine-Session-Id`
|
||||
- `X-Shine-Time-Ms`
|
||||
- `X-Shine-Signature`
|
||||
|
||||
```properties
|
||||
public.files.enabled=true
|
||||
public.files.storageDir=data/public-files
|
||||
public.files.maxBytes=536870912
|
||||
```
|
||||
Подписываемая строка `PUBLIC_R2_PREPARE_V1:{sessionId}:{pr}:{size}:{mm}:{timeMs}`.
|
||||
|
||||
Для production рекомендуется задать `public.files.storageDir` абсолютным путём, который одновременно доступен Java для записи и Caddy для чтения.
|
||||
Сервер проверяет авторизацию, Base58 32-байтного PR, размер (≤500 МиБ), MIME, выполняет S3 `HeadObject`. Если объект уже существует с тем же размером — возвращает `exists:true`; если нет — `uploadUrl`, `requiredHeaders`, `fileUrl`. Браузер делает один **Presigned PUT** прямо в S3 Endpoint R2 с обязательными подписанными заголовками, включая `If-None-Match: *` для защиты от перезаписи. Действие не использует R2 credential в браузере.
|
||||
|
||||
Например:
|
||||
Java **не проверяет реальный Pieces Root содержимого** и не гарантирует строгий объём через один заявленный клиентом `size`; нет Multipart, квот или автоматической проверки фактического PUT после выдачи URL. Неверный PR у первоначального объекта может нарушать дедупликацию — это известный компромисс MVP.
|
||||
|
||||
```text
|
||||
/home/player/shine-public-files
|
||||
```
|
||||
Конфигурация сервера: `R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `r2.publicBucket=shine-files`. CORS корзины должен разрешать origin PWA и PUT с подписанными заголовками. Ключи — только на сервере.
|
||||
|
||||
## 3. PUT `/files/<sha256>`
|
||||
## Исторический локальный API SHA-256
|
||||
|
||||
Загружает immutable public file. PUT требует активную пользовательскую сессию.
|
||||
Старый `PublicFileServlet` обслуживает `/files/<64 lowercase hex SHA-256>` на локальном диске (`public.files.storageDir`). Для старых файлов может продолжать работать GET/HEAD/PUT с проверкой SHA-256 и HTTP Range. Новые `pr`-файлы туда **не загружаются**. Детали legacy передавать только при поддержке исторических данных, не использовать этот API в новых тегах.
|
||||
|
||||
Заголовки:
|
||||
## Учёт разрешений R2 (PostgreSQL v42)
|
||||
|
||||
```text
|
||||
Content-Type: application/octet-stream
|
||||
X-Shine-Session-Id: <active session id>
|
||||
X-Shine-Time-Ms: <unix time ms>
|
||||
X-Shine-Content-Length: <file bytes>
|
||||
X-Shine-Signature: <Ed25519 signature, Base64>
|
||||
```
|
||||
|
||||
Подписываемая строка UTF-8:
|
||||
|
||||
```text
|
||||
PUBLIC_FILE_UPLOAD_V1:{sessionId}:{sha256}:{size}:{timeMs}
|
||||
```
|
||||
|
||||
Сервер потоково принимает байты, заново считает SHA-256 и принимает объект только если:
|
||||
|
||||
```text
|
||||
SHA256(received bytes) == sha256 из URL
|
||||
```
|
||||
|
||||
Если корректный объект уже существует и размер совпадает, PUT идемпотентно отвечает `alreadyExists=true`.
|
||||
|
||||
## 4. GET и HEAD (включая HTTP Range)
|
||||
|
||||
Java servlet обслуживает `GET /files/<sha256>` и `HEAD /files/<sha256>`.
|
||||
Проверка SHA-256 **при чтении не выполняется**: хеш проверяется при исходном PUT,
|
||||
файл immutable, а скачивание не должно требовать предварительного прочтения всех байтов.
|
||||
Проверка корректности при повторном PUT уже имеющегося объекта сохранена.
|
||||
|
||||
Полный GET, как и прежде, возвращает `200 OK` и `Content-Length` всего файла.
|
||||
HEAD всегда возвращает метаданные **полного объекта** без тела и без обхода
|
||||
всего файла по байтам (Range в HEAD игнорируется).
|
||||
|
||||
Для `GET` с одним диапазоном:
|
||||
|
||||
```http
|
||||
Range: bytes=0-262143
|
||||
```
|
||||
|
||||
Ответ:
|
||||
|
||||
```http
|
||||
HTTP/1.1 206 Partial Content
|
||||
Accept-Ranges: bytes
|
||||
Content-Range: bytes 0-262143/<общий размер>
|
||||
Content-Length: 262144
|
||||
ETag: "<sha256>"
|
||||
```
|
||||
|
||||
Поддерживаются формы `bytes=START-END`, `bytes=START-` и `bytes=-SUFFIX`.
|
||||
Для составных или неудовлетворяемых диапазонов сервер возвращает `416` +
|
||||
`Content-Range: bytes */<общий размер>`. `If-Range` поддерживает точный
|
||||
совпадающий ETag; при несовпадении возвращается полный `200`.
|
||||
|
||||
Остальные заголовки:
|
||||
|
||||
```http
|
||||
Cache-Control: public, max-age=31536000, immutable
|
||||
Cross-Origin-Resource-Policy: cross-origin
|
||||
Access-Control-Allow-Origin: *
|
||||
```
|
||||
|
||||
Тип для MP4, WebM, Ogg и AVI Java определяет по первым байтам файла.
|
||||
Неизвестные типы остаются `application/octet-stream`. Протокол `S:att`
|
||||
не меняется, имя файла/тип на сервере не сохраняются.
|
||||
|
||||
При прямой выдаче Caddy (`file_server`) Range обеспечивает Caddy, а не Java.
|
||||
Следует проверить `Content-Type` (у файлов с именем SHA-256 нет расширения),
|
||||
а также корректность ответа `206` через публичный домен, особенно с CDN.
|
||||
Если нужен корректный MIME по сигнатуре, используйте HTTP reverse_proxy к Java
|
||||
из инструкции `deploy/PUBLIC_FILES_CADDY_CLOUDFLARE.md`.
|
||||
|
||||
## 5. Связь с `S:att`
|
||||
|
||||
```text
|
||||
<S:att;v=1;nm=photo.jpg;sz=12345;sha256=<64 hex>>
|
||||
```
|
||||
|
||||
означает public file на текущем сервере доступа автора.
|
||||
|
||||
```text
|
||||
<S:att;v=1;nm=photo.jpg;sz=12345;sha256=<64 hex>;ar=<txId>>
|
||||
```
|
||||
|
||||
означает Arweave.
|
||||
|
||||
Адрес сервера доступа в блок не записывается. При чтении клиент определяет текущий access server автора через его PDA и строит:
|
||||
|
||||
```text
|
||||
https://<current-access-server>/files/<sha256>
|
||||
```
|
||||
|
||||
## 6. Preview
|
||||
|
||||
В UI видео со storage=server получает прямую ссылку `/files/<sha256>` (без полного `fetch` в Blob): браузер сам запрашивает диапазоны, читает длительность и загружает стартовый кадр. Размер берётся из `sz` вложения. Для Arweave частичная загрузка зависит от gateway.
|
||||
|
||||
Отдельных preview-файлов сейчас нет. `preAr`, `preSha256`, `previewAr`, `previewSha256` не являются частью текущего протокола.
|
||||
|
||||
|
||||
## R2 direct upload (MVP, 2026-11)
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## Единый формат публичных идентификаторов
|
||||
Аватарки и публичные вложения имеют одинаковый `PR = Base58(BitTorrent v2 Pieces Root)` и сохраняются в **корень** R2 bucket `shine-files`, URL `https://files.shineup.me/<PR>`. Папки `avatars/` нет; загрузка идёт через `/api/files/prepare`, не через `/api/avatars/prepare`. После оптимизации изображения вычисляется PR от именно передаваемых байтов. `<S:ava;v=2;sz=N;pr=BASE58[;ar=TXID]>`; `ar` остаётся нативным Arweave TX ID в Base64URL. Старые `<S:ava;v=1;...sha256=...>` не поддерживаются.
|
||||
|
||||
Для потенциального **будущего** SHA-256 типа идентификатора публичного файла используем `Base58(SHA-256(bytes))`, а не hex. Это отдельный алгоритм, его нельзя смешивать с PR. На данный момент новые публичные вложения/аватарки не используют SHA-256 как идентификатор.
|
||||
В `public_file_uploads` пишется событие после успешной авторизации и решения S3: логин, PR, заявленный размер, `requested_at`, `disposition` (`upload_url_issued` или `already_exists`). **Это журнал выдачи разрешения/повторного использования, а не доказательство завершённого PUT.** Повторные попытки фиксируются отдельными строками. Лимитов и блокировок по журналу пока нет. Параллельная таблица DM описана в `docs/API/18_DM_File_Storage_API.md`.
|
||||
|
||||
Reference in New Issue
Block a user