From 1b86bca19a26e89b93071f6220af3a76fa75c87221b8a8c326f34b8c028be3da Mon Sep 17 00:00:00 2001 From: AidarKC Date: Mon, 16 Nov 2026 10:47:43 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9E=D0=B1=D0=BD=D0=BE=D0=B2=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=20=D1=85=D1=80=D0=B0=D0=BD=D0=B5=D0=BD=D0=B8=D0=B5=20?= =?UTF-8?q?=D0=B2=D0=BB=D0=BE=D0=B6=D0=B5=D0=BD=D0=B8=D0=B9=20R2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../java/shine/db/DatabaseInitializer.java | 10 +- .../main/resources/postgres/migration_v42.sql | 27 +++ .../java/server/files/R2DmPrepareServlet.java | 1 + .../java/server/files/R2PrepareServlet.java | 1 + .../server/files/R2UploadAuditRecorder.java | 41 +++++ VERSION.properties | 4 +- docs/API/18_DM_File_Storage_API.md | 6 +- docs/API/21_Public_File_Storage_API.md | 167 ++++-------------- docs/Blockchain/15_TEXT_Attachments.md | 139 +++------------ docs/Personal_Messages/Файлы_DM_v3_R2.md | 4 + scripts/tests/test-r2-file-preparation.mjs | 4 +- scripts/tests/test-r2-upload-audit-schema.mjs | 18 ++ shine-UI/js/i18n/locales/en.json | 5 +- shine-UI/js/i18n/locales/ru.json | 5 +- shine-UI/js/services/attachment-format.js | 99 +++++++++-- .../public-attachment-inline-media.test.mjs | 64 ++++++- shine-UI/tests/tg-midnight-theme.test.mjs | 2 +- 17 files changed, 321 insertions(+), 276 deletions(-) create mode 100644 SHiNE-server/shine-server-db/src/main/resources/postgres/migration_v42.sql create mode 100644 SHiNE-server/src/main/java/server/files/R2UploadAuditRecorder.java create mode 100644 scripts/tests/test-r2-upload-audit-schema.mjs diff --git a/SHiNE-server/shine-server-db/src/main/java/shine/db/DatabaseInitializer.java b/SHiNE-server/shine-server-db/src/main/java/shine/db/DatabaseInitializer.java index 11de4c68..d4906707 100644 --- a/SHiNE-server/shine-server-db/src/main/java/shine/db/DatabaseInitializer.java +++ b/SHiNE-server/shine-server-db/src/main/java/shine/db/DatabaseInitializer.java @@ -32,6 +32,7 @@ public final class DatabaseInitializer { public static final int SCHEMA_VERSION_39 = 39; public static final int SCHEMA_VERSION_40 = 40; public static final int SCHEMA_VERSION_41 = 41; + public static final int SCHEMA_VERSION_42 = 42; public static final String POSTGRES_SCHEMA_RESOURCE = "postgres/schema_v1.sql"; public static final String POSTGRES_MIGRATION_V31_RESOURCE = "postgres/migration_v31.sql"; public static final String POSTGRES_MIGRATION_V32_RESOURCE = "postgres/migration_v32.sql"; @@ -44,6 +45,7 @@ public final class DatabaseInitializer { public static final String POSTGRES_MIGRATION_V39_RESOURCE = "postgres/migration_v39.sql"; public static final String POSTGRES_MIGRATION_V40_RESOURCE = "postgres/migration_v40.sql"; public static final String POSTGRES_MIGRATION_V41_RESOURCE = "postgres/migration_v41.sql"; + public static final String POSTGRES_MIGRATION_V42_RESOURCE = "postgres/migration_v42.sql"; private DatabaseInitializer() {} @@ -179,9 +181,13 @@ public final class DatabaseInitializer { runSqlScript(conn, POSTGRES_MIGRATION_V41_RESOURCE); currentVersion = readCurrentSchemaVersion(conn); } - if (currentVersion != SCHEMA_VERSION_41) { + if (currentVersion == SCHEMA_VERSION_41) { + runSqlScript(conn, POSTGRES_MIGRATION_V42_RESOURCE); + currentVersion = readCurrentSchemaVersion(conn); + } + if (currentVersion != SCHEMA_VERSION_42) { throw new SQLException( - "Unsupported SHiNE DB v2 schema version: expected 41, found " + currentVersion); + "Unsupported SHiNE DB v2 schema version: expected 42, found " + currentVersion); } normalizeBlockchainStateKeysToBase64(conn); } diff --git a/SHiNE-server/shine-server-db/src/main/resources/postgres/migration_v42.sql b/SHiNE-server/shine-server-db/src/main/resources/postgres/migration_v42.sql new file mode 100644 index 00000000..33fe5386 --- /dev/null +++ b/SHiNE-server/shine-server-db/src/main/resources/postgres/migration_v42.sql @@ -0,0 +1,27 @@ +-- SHiNE v42: журнал выдачи разрешений R2 (не подтверждение успешного PUT). +-- В DM записываются только зашифрованные объекты (включая манифест), без имени и MIME. +BEGIN; +CREATE TABLE IF NOT EXISTS public_file_uploads ( + id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, + user_login TEXT NOT NULL, + file_hash TEXT NOT NULL, + file_size_bytes BIGINT NOT NULL CHECK (file_size_bytes > 0), + disposition TEXT NOT NULL CHECK (disposition IN ('upload_url_issued', 'already_exists')), + requested_at TIMESTAMPTZ NOT NULL DEFAULT now() +); +CREATE INDEX IF NOT EXISTS public_file_uploads_user_time_idx ON public_file_uploads (user_login, requested_at DESC); +CREATE INDEX IF NOT EXISTS public_file_uploads_hash_idx ON public_file_uploads (file_hash); + +CREATE TABLE IF NOT EXISTS dm_file_uploads ( + id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY, + user_login TEXT NOT NULL, + file_hash TEXT NOT NULL, + file_size_bytes BIGINT NOT NULL CHECK (file_size_bytes > 0), + disposition TEXT NOT NULL CHECK (disposition IN ('upload_url_issued', 'already_exists')), + requested_at TIMESTAMPTZ NOT NULL DEFAULT now() +); +CREATE INDEX IF NOT EXISTS dm_file_uploads_user_time_idx ON dm_file_uploads (user_login, requested_at DESC); +CREATE INDEX IF NOT EXISTS dm_file_uploads_hash_idx ON dm_file_uploads (file_hash); + +UPDATE db_schema_version SET schema_version = 42, updated_at_ms = (EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::BIGINT WHERE id = 1; +COMMIT; diff --git a/SHiNE-server/src/main/java/server/files/R2DmPrepareServlet.java b/SHiNE-server/src/main/java/server/files/R2DmPrepareServlet.java index a3bd429a..ed0f0349 100644 --- a/SHiNE-server/src/main/java/server/files/R2DmPrepareServlet.java +++ b/SHiNE-server/src/main/java/server/files/R2DmPrepareServlet.java @@ -93,6 +93,7 @@ public final class R2DmPrepareServlet extends HttpServlet { } } } + R2UploadAuditRecorder.record(req, true, fileId, size, result.path("exists").asBoolean(false)); respond(resp, 200, result); } catch (Exception error) { getServletContext().log("R2 DM prepare failed", error); diff --git a/SHiNE-server/src/main/java/server/files/R2PrepareServlet.java b/SHiNE-server/src/main/java/server/files/R2PrepareServlet.java index e29ea714..0b9397b1 100644 --- a/SHiNE-server/src/main/java/server/files/R2PrepareServlet.java +++ b/SHiNE-server/src/main/java/server/files/R2PrepareServlet.java @@ -85,6 +85,7 @@ public final class R2PrepareServlet extends HttpServlet { } } } + R2UploadAuditRecorder.record(req, false, root, size, out.path("exists").asBoolean(false)); respond(resp, 200, out); } catch (Exception e) { getServletContext().log("R2 prepare failure", e); diff --git a/SHiNE-server/src/main/java/server/files/R2UploadAuditRecorder.java b/SHiNE-server/src/main/java/server/files/R2UploadAuditRecorder.java new file mode 100644 index 00000000..0241b635 --- /dev/null +++ b/SHiNE-server/src/main/java/server/files/R2UploadAuditRecorder.java @@ -0,0 +1,41 @@ +package server.files; + +import jakarta.servlet.http.HttpServletRequest; +import shine.db.DbController; +import shine.db.dao.ActiveSessionsDAO; +import shine.db.entities.ActiveSessionEntry; + +import java.sql.Connection; +import java.sql.PreparedStatement; +import java.sql.SQLException; + +/** + * Учёт выдачи разрешений R2. ВАЖНО: запись не удостоверяет завершённый PUT. + * Не сохраняет исходные имена и MIME личных файлов. + */ +final class R2UploadAuditRecorder { + private R2UploadAuditRecorder() {} + + static void record(HttpServletRequest request, boolean dm, String fileHash, long size, boolean exists) + throws SQLException { + // Заголовок используется только ПОСЛЕ проверки Ed25519-подписи в вызывающем servlet. + String sessionId = request.getHeader("X-Shine-Session-Id"); + if (sessionId == null || sessionId.isBlank()) throw new SQLException("Upload session ID missing"); + String table = dm ? "dm_file_uploads" : "public_file_uploads"; + try (Connection connection = DbController.getInstance().getConnection()) { + ActiveSessionEntry session = ActiveSessionsDAO.getInstance().getBySessionId(connection, sessionId.trim()); + if (session == null || session.getLogin() == null || session.getLogin().isBlank()) { + throw new SQLException("Upload session missing for audit"); + } + String sql = "INSERT INTO " + table + + " (user_login, file_hash, file_size_bytes, disposition) VALUES (?, ?, ?, ?)"; + try (PreparedStatement statement = connection.prepareStatement(sql)) { + statement.setString(1, session.getLogin()); + statement.setString(2, fileHash); + statement.setLong(3, size); + statement.setString(4, exists ? "already_exists" : "upload_url_issued"); + statement.executeUpdate(); + } + } + } +} diff --git a/VERSION.properties b/VERSION.properties index 7fefe937..f05d4da2 100644 --- a/VERSION.properties +++ b/VERSION.properties @@ -1,2 +1,2 @@ -client.version=1.20.49 -server.version=1.16.25 +client.version=1.20.50 +server.version=1.16.26 diff --git a/docs/API/18_DM_File_Storage_API.md b/docs/API/18_DM_File_Storage_API.md index d1f41cc2..e24fa86c 100644 --- a/docs/API/18_DM_File_Storage_API.md +++ b/docs/API/18_DM_File_Storage_API.md @@ -1,5 +1,9 @@ # HTTP API зашифрованных файлов личных сообщений +> **Текущий протокол DM v3 (2026-11):** новые вложения отправляются напрямую в R2 `shine-dm` после `POST /api/dm-files/prepare`; скачиваются по `https://dm-files.shineup.me/`. Большие файлы шифруются по 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/размер в `` внутри plaintext DM; 7. обычный механизм E2EE DM шифрует эту техническую вставку отдельно для отправителя и получателя. diff --git a/docs/API/21_Public_File_Storage_API.md b/docs/API/21_Public_File_Storage_API.md index 60ebeed3..006f3bde 100644 --- a/docs/API/21_Public_File_Storage_API.md +++ b/docs/API/21_Public_File_Storage_API.md @@ -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`, без расширения). +- Предпросмотр публичных изображений и видео использует прямой 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` — lowercase hex, ровно 64 символа. +При использовании Arweave дополнительно передаётся `;ar=TXID` — существующая загрузка Arweave/Turbo не меняется. Источник выбирается по `ar` (если есть), иначе R2 по `pr`. Не добавлять `storage=r2` в постоянные записи. Общее описание — `docs/Blockchain/15_TEXT_Attachments.md`. -На диске сервер хранит один глобальный объект: +Новые аватары: ``. SHA-256 hex остаётся лишь в исторических файловых маршрутах, **новые аватары SHA-256 не создают**. Старые аватары v1 не мигрируются автоматически (v41 сбрасывает старые ссылки каналов). -```text -/ +## Выдача разрешения на загрузку + +`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/` +## Исторический локальный 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: -X-Shine-Time-Ms: -X-Shine-Content-Length: -X-Shine-Signature: -``` - -Подписываемая строка 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/` и `HEAD /files/`. -Проверка 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: "" -``` - -Поддерживаются формы `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 -> -``` - -означает public file на текущем сервере доступа автора. - -```text -;ar=> -``` - -означает Arweave. - -Адрес сервера доступа в блок не записывается. При чтении клиент определяет текущий access server автора через его PDA и строит: - -```text -https:///files/ -``` - -## 6. Preview - -В UI видео со storage=server получает прямую ссылку `/files/` (без полного `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/` 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/`; 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/`. Папки `avatars/` нет; загрузка идёт через `/api/files/prepare`, не через `/api/avatars/prepare`. После оптимизации изображения вычисляется PR от именно передаваемых байтов. ``; `ar` остаётся нативным Arweave TX ID в Base64URL. Старые `` не поддерживаются. - -Для потенциального **будущего** 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`. diff --git a/docs/Blockchain/15_TEXT_Attachments.md b/docs/Blockchain/15_TEXT_Attachments.md index a0f54c7c..3a84c374 100644 --- a/docs/Blockchain/15_TEXT_Attachments.md +++ b/docs/Blockchain/15_TEXT_Attachments.md @@ -1,132 +1,35 @@ -# Вложения в TEXT-сообщениях (`S:att v=1`) +# Вложения в TEXT-сообщениях (`S:att;v=1`) -Документ фиксирует текущий формат вложений в текстовых блоках SHiNE. +Технический префикс в UTF-8 `text` для `TEXT_POST`, `TEXT_REPLY`, `TEXT_EDIT_POST`, `TEXT_EDIT_REPLY`. Бинарный формат TEXT не меняется. До 10 вложений в начале сообщения, затем обычный текст; порядок сохраняется. -## Область применения - -Формат применяется к UTF-8 полю `text` в TEXT-блоках: - -- `TEXT_POST` -- `TEXT_REPLY` -- `TEXT_EDIT_POST` -- `TEXT_EDIT_REPLY` - -Бинарный формат `TextBody` не меняется. Вложения являются техническим префиксом внутри обычного текста. - -## Общий вид - -Arweave-вложение: +## Канонический формат (2026-11) ```text - + + +Текст публикации ``` -Public file на сервере доступа автора: +- `v` — версия (1). +- `nm` — имя файла в `encodeURIComponent`. +- `sz` — размер подготовленных байтов в десятичном виде. +- `pr` — **BitTorrent v2 Pieces Root (32 байта), Base58**, не SHA-256 целого файла; текущий стандарт новых вложений. +- `mm` — необязательный MIME, в формате `type/subtype`; неизвестный — `application/octet-stream`. +- `ar` — необязательный Arweave Transaction ID, нативный формат Arweave. +- `sha256` — исторический lowercase hex SHA-256 для старых тегов/объектов; новые записи его не создают. -```text - -``` +`ar` присутствует → получить файл через Arweave gateway. Нет `ar`, есть `pr` → `https://files.shineup.me/`. Исторический `sha256` без `pr`/`ar` → прежний `/files/` access-сервера автора. `storage=r2` и абсолютные URL в тег не записываются. -Несколько вложений идут подряд в самом начале текста: +Идентификаторы новых аватаров — тоже **Base58(PR)**, но формат аватара отдельный: ``. Формат v1/SHA-256 аватаров больше не создаётся; миграция v41 не конвертирует старые значения. -```text - - -Текст сообщения -``` +## Отображение и безопасность -После последнего attach-блока идёт обычный пользовательский текст. Пользовательский текст может быть пустым, если есть хотя бы одно валидное вложение. +Клиент берёт тип по `mm` (при его наличии), иначе пытается использовать расширение `nm`. Для HTTP-открытия URL без расширения R2 также хранит `Content-Type` в метаданных объекта. Изображения загружаются `loading="lazy"`; публичные видео не получают `src`, пока не приблизились к экрану (`IntersectionObserver` с fallback). Встроенное отображение использует исходный файл, дополнительных preview-объектов нет. -Клиент SHiNE ограничивает одно сообщение максимум 10 вложениями и сохраняет порядок attach-блоков. +HTML, SVG, XHTML, JavaScript, XML по расширению или MIME выводятся карточками с подтверждением перед переходом из UI. Пользователь может отменить открытие; прямые ссылки R2/Arweave обходят это предупреждение. Это не изменение доступа, криптографии или правила хранения и **не даёт защиты от вредоносного содержимого на уровне HTTP**. -## Поля +Публичные вложения сохраняются на R2 либо в Arweave без автоматического удаления; DM-вложения используют отдельный протокол, см. `docs/Personal_Messages/Файлы_DM_v3_R2.md`. Редактирование текста сохраняет технические attach-блоки и не переносит объекты между хранилищами. -Обязательные поля: +## Совместимость -- `v=1` - версия формата attach-блока; -- `nm` - имя файла, закодированное через `encodeURIComponent`; -- `sz` - размер файла в байтах; -- один из идентификаторов файла: `pr` — pieces root BitTorrent v2 (base64url, 43 символа) для новых вложений; `sha256` — hex SHA-256 (64 символа) для совместимости со старыми. - -Опциональные поля: - -- `ar` - короткий Arweave Transaction ID, 43 символа, без gateway URL; -- `mm` - MIME типа `image/jpeg` или `video/mp4`; если отсутствует, UI использует расширение `nm`. - -Источник определяется следующим образом: - -- `ar` присутствует -> Arweave; -- `ar` отсутствует, но есть `pr` -> публичный Cloudflare R2 (`https://files.shineup.me/`); -- `ar` и `pr` отсутствуют, есть `sha256` -> старое файловое хранилище сервера доступа автора. - -Адрес сервера автора, URL файла и login автора в attach-блок не записываются: автор уже известен из подписанного блока. Старые файлы разрешаются через сервер доступа, новые R2 — по `pr`. - -## Preview - -Отдельные preview-файлы в текущем протоколе **не поддерживаются и пока не нужны**. - -Клиент не должен создавать или использовать поля `preAr`, `preSha256`, `previewAr`, `previewSha256`. Для изображения или видео используется исходный файл вложения. - -Если такие поля встречаются в экспериментальных старых данных, текущая реализация может их игнорировать; они не являются частью канонического `S:att v=1`. - -## Хранение файла - -Сам файл всегда находится вне блокчейна. - -### Arweave - -Если присутствует `ar`, файл читается через настроенный Arweave gateway по указанному `txId`. - -### Cloudflare R2 (новые публичные файлы) - -Если `ar` отсутствует и указан `pr`, клиент использует прямой адрес `https://files.shineup.me/`. Браузер запрашивает исходное медиа напрямую; сервер Java в отдаче файла не участвует. При видео браузер может запрашивать только метаданные и нужные фрагменты через HTTP Range. - -### Сервер доступа (старые вложения с SHA-256) - -Если `ar` и `pr` отсутствуют, клиент: - -1. определяет текущий сервер доступа автора сообщения; -2. запрашивает файл по стандартному пути `/files/`; -3. использует прежний формат ссылок для совместимости с существующими сообщениями. - -URL или домен конкретного сервера в блокчейн не записывается. Поэтому смена сервера доступа не требует изменения старых сообщений. - -## Создание вложения в UI - -UI предлагает два способа хранения публичных вложений: `Cloudflare R2` (через пункт сервера доступа) и `Arweave`. Отдельные preview-файлы не создаются. - -После загрузки в R2 формируется `S:att v=1` с `pr` и `mm`, без `ar`. Для Arweave используется механизм Arweave/Turbo; дополнительно записывается `ar`. - -Журнал загрузок Arweave хранится только в `sessionStorage` текущего браузера и не является частью блокчейна. - -## Отображение - -Клиент при чтении сообщения: - -1. читает валидные attach-блоки только из начала текста; -2. скрывает технические attach-строки; -3. определяет источник по наличию `ar`; -4. получает Arweave-файл по `txId`, R2-файл по `pr` либо старый server-файл по `/files/`; -5. определяет тип вложения по `mm` (если указан), иначе по расширению `nm`; -6. изображение отображает из исходного файла; -7. видео отображает из исходного файла и открывает HTML5-плеер; -8. обычный файл показывает как карточку с именем, размером и скачиванием; -9. при перелистывании останавливает воспроизводящееся видео; -10. битый attach-блок игнорирует, не ломая остальное сообщение. - -## Редактирование - -При редактировании сообщения UI сохраняет существующие attach-блоки и меняет только пользовательский текст. Удаление сообщения выполняется через edit-блок с пустым текстом, как описано в `11_TEXT_Blocks.md`. - -## Совместимость и ограничения - -- полный URL в поле `ar` не используется; -- для старых `sha256`-вложений MIME не записывался, тип UI определяется по расширению `nm`; -- старые текстовые префиксы `` и `` могут продолжать читаться как совместимые формы; -- отдельные preview-поля не входят в текущий протокол; -- `width`, `height`, `duration` и `thumbnail` не записываются отдельными полями; новые вложения могут содержать `mm` (MIME). - - -## MVP R2 (2026-11): новые публичные вложения - -Для **новых** публичных вложений использовать ``; при загрузке в Arweave добавляется `;ar=TXID`. `pr` — 32-байтный BitTorrent v2 pieces root в base64url без padding (43 символа), а не SHA-256 файла. `mm` необязателен; отсутствие означает `application/octet-stream`. Новое публичное вложение без `ar` скачивается с `https://files.shineup.me/`. `storage=r2` отсутствует. Новые аватары **не изменяются**: SHA-256 и старый API `/files/` остаются. Существующий формат чтения `sha256` оставлен для ранее созданных данных и уже загруженных транзакций Arweave. Публичные изображения и видео показываются внутри сообщения из исходного файла (`` / `