# Публичные вложения SHiNE: Cloudflare R2 и legacy API ## Действующий формат (15.11.2026) Новые публичные файлы и аватары используют **BitTorrent v2 Pieces Root**, закодированный **Base58** (32 байта; строка обычно 43–44 символа). Идентификатор не зависит от имени и MIME. Клиент вычисляет корень по подготовленным байтам. Содержимое файла **не проходит через Java**. - R2 bucket: `shine-files`. - Публичный GET: `https://files.<домен access-сервера автора>/` (ключ объекта = `PR`, без расширения). - Предпросмотр публичных изображений и видео использует прямой URL. Картинки `loading="lazy"`; публичные видео получают `src` только у видимой области через `IntersectionObserver` и запрашивают метаданные после входа в область. В старом браузере используется обычная загрузка metadata. - Отдельных preview-файлов нет. Скачивание/просмотр медиаконтента выполняет сам браузер (в том числе HTTP Range, если доступен). - Тип определяется по `mm`, затем по расширению `nm`; HTTP `Content-Type` объекта задаётся при PUT. Неизвестные файлы — `application/octet-stream`. - HTML, SVG и похожие активные типы отображаются как обычные файловые карточки. Перед открытием **из публичного интерфейса** показывается предупреждение с возможностью отмены. Это не серверная санитаризация и не гарантия безопасности прямого URL. Формат публичного вложения (версия тега остаётся 1): ```text ``` При использовании Arweave дополнительно передаётся `;ar=TXID` — существующая загрузка Arweave/Turbo не меняется. Источник выбирается по `ar` (если есть), иначе R2 по `pr`. Не добавлять `storage=r2` в постоянные записи. Общее описание — `docs/Blockchain/15_TEXT_Attachments.md`. Новые аватары: ``. SHA-256 hex остаётся лишь в исторических файловых маршрутах, **новые аватары SHA-256 не создают**. Старые аватары v1 не мигрируются автоматически (v41 сбрасывает старые ссылки каналов). ## Выдача разрешения на загрузку `POST /api/files/prepare` (JSON): ```json {"pr":"BASE58_ROOT","size":123456,"mm":"image/jpeg"} ``` Сессионная Ed25519-подпись обязательна. Заголовки: - `X-Shine-Session-Id` - `X-Shine-Time-Ms` - `X-Shine-Signature` Подписываемая строка `PUBLIC_R2_PREPARE_V1:{sessionId}:{pr}:{size}:{mm}:{timeMs}`. Сервер проверяет авторизацию, 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. Конфигурация сервера: `R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `r2.publicBucket=shine-files`. CORS корзины должен разрешать origin PWA и PUT с подписанными заголовками. Ключи — только на сервере. ## Исторический локальный API SHA-256 Старый `PublicFileServlet` обслуживает `/files/<64 lowercase hex SHA-256>` на локальном диске (`public.files.storageDir`). Для старых файлов может продолжать работать GET/HEAD/PUT с проверкой SHA-256 и HTTP Range. Новые `pr`-файлы туда **не загружаются**. Детали legacy передавать только при поддержке исторических данных, не использовать этот API в новых тегах. ## Учёт разрешений R2 (PostgreSQL v42) В `public_file_uploads` пишется событие после успешной авторизации и решения S3: логин, PR, заявленный размер, `requested_at`, `disposition` (`upload_url_issued` или `already_exists`). **Это журнал выдачи разрешения/повторного использования, а не доказательство завершённого PUT.** Повторные попытки фиксируются отдельными строками. Лимитов и блокировок по журналу пока нет. Параллельная таблица DM описана в `docs/API/18_DM_File_Storage_API.md`.