SHA256
Актуализировать документацию и навигацию для агентов
This commit is contained in:
@@ -1,145 +1,27 @@
|
|||||||
# AGENTS
|
# Инструкции для агентов SHiNE
|
||||||
|
|
||||||
## Язык проекта
|
Этот файл относится к репозиторию SHiNE. По умолчанию писать документацию, пользовательские пояснения и сообщения коммитов на русском языке.
|
||||||
- По умолчанию использовать русский язык во всех пользовательских текстах и технических пояснениях.
|
|
||||||
- Пояснения к коммитам, PR и merge-запросам писать на русском языке.
|
|
||||||
- Комментарии в коде, встроенные справки, документацию и инструкции писать по возможности на русском языке.
|
|
||||||
|
|
||||||
## Примечание
|
## Сначала определить область работы
|
||||||
- Если внешний инструмент/интеграция требует английский формат, допускается английский, но рядом желательно дать краткое пояснение на русском.
|
|
||||||
|
|
||||||
## Структура проекта (кратко)
|
| Область | Код | Правила и документация |
|
||||||
- Серверный код SHiNE находится в папке `SHiNE-server/`.
|
| --- | --- | --- |
|
||||||
- Код клиентского UI SHiNE находится в папке `shine-UI/`.
|
| Сервер, WebSocket/API, PostgreSQL | `SHiNE-server/` | `SHiNE-server/AGENTS.md`, `docs/API/` |
|
||||||
- Веб-панель администратора сервера (управление Solana PDA сервера) находится в `shine-UI/`:
|
| Блокчейн, Arweave | `SHiNE-server/shine-server-blockchain/` | `docs/Blockchain/README.md` |
|
||||||
- точка входа `shine-UI/server-ui.html`;
|
| Личные сообщения | сервер и `shine-UI/` | `docs/Personal_Messages/README.md`, локальный `AGENTS.md` |
|
||||||
- остальные файлы серверного UI — в `shine-UI/server-ui/`.
|
| Браузерный UI | `shine-UI/` | `shine-UI/AGENTS.md`, `docs/UI-Design/README.md` |
|
||||||
- Локальный Telegram-бот агента-кодера живёт рядом с репозиторием продукта, обычно в `../SHiNE-agent-bot-coder/`, и не входит в публичный код основного приложения.
|
| Solana/Anchor | `shine-solana/shine/` | локальный `AGENTS.md`, `docs/Solana_Architecture/README.md` |
|
||||||
- Solana/Anchor-модуль находится в папке `shine-solana/shine/` и ведётся отдельно от основного server/UI деплоя.
|
| ESP32 | `ESP32/` | `ESP32/AGENTS.md`, инструкции конкретного устройства |
|
||||||
|
| Деплой и резервные копии | `deploy/` | `deploy/AGENTS.md`, `deploy/backup/AGENTS.md` |
|
||||||
|
| Тестовый издатель | `tools/test-publisher/` | локальный `AGENTS.md` |
|
||||||
|
|
||||||
## Сервис агента-кодера
|
Общий каталог — `docs/README.md`; карта компонентов и потоков данных — `docs/ARCHITECTURE.md`. Правила сопровождения документов — `docs/CONTRIBUTING_DOCS.md`; после правки документации запускать `python3 scripts/check_docs.py`. Планы в `TODO/` не считать описанием действующего поведения или разрешением на реализацию.
|
||||||
- Локальный Telegram-бот-сервис агента-кодера находится вне этого git-репозитория, обычно в `../SHiNE-agent-bot-coder/`.
|
|
||||||
- Сервис принимает сообщения из Telegram, ведёт историю диалога, ставит задачи в очередь и вызывает Codex CLI для обработки запросов по проекту.
|
|
||||||
- Рабочая папка Codex для сервиса должна указывать на этот продуктовый репозиторий: `CODEX_WORKDIR=/home/ai/work/SHiNE/SHiNE-server-sha256/SHiNE-product`.
|
|
||||||
- Автоматически читаемые инструкции для Codex внутри сервиса держать в `../SHiNE-agent-bot-coder/AGENTS.md`.
|
|
||||||
- Подробные служебные правила Telegram-обработчика, его очередь, история, systemd-запуск и особенности ответов описывать в `../SHiNE-agent-bot-coder/AGENT.md`.
|
|
||||||
- Если в сообщениях пользователя встречается «агент MD» или похожая формулировка про файл инструкций Codex, считать, что имеется в виду автоматически читаемый `AGENTS.md`.
|
|
||||||
|
|
||||||
## ESP32 UI homeserver
|
## Постоянные правила
|
||||||
- Для UI-скетча устройства `ESP32-S3-Touch-AMOLED-2.16` документ-спецификация и Arduino-скетч должны всегда оставаться синхронными.
|
|
||||||
- Актуальный документ по экранной логике, состояниям, кнопкам, полям, статусам и ограничениям UI считать источником истины для скетча.
|
|
||||||
- При изменении документа обязательно в том же наборе изменений приводить в соответствие скетч.
|
|
||||||
- При изменении скетча обязательно в том же наборе изменений обновлять документ, если поменялись экраны, тексты, переходы, статусы, кнопки, поля или поведение.
|
|
||||||
- Для нового ESP32 UI-прототипа homeserver использовать русский язык как основной и отдельно следить, чтобы текст реально отображался на устройстве, а не только логически присутствовал в коде.
|
|
||||||
|
|
||||||
## Solana-модуль
|
- Прежде чем править подсистему, прочитать её локальный `AGENTS.md` и действующую документацию через `docs/README.md`. Архивные отчёты и старые планы не использовать как текущий контракт. При расхождении документа с кодом проверить реализацию и исправить документ либо явно отметить неопределённость.
|
||||||
- В проекте есть отдельный Solana/Anchor-модуль в папке `shine-solana/shine/`.
|
- Изменение поведения, формата, API, конфигурации или пользовательского сценария сопровождать обновлением соответствующего документа в том же наборе изменений. Не выдавать план, черновик или тестовое состояние за действующую функцию.
|
||||||
- Модуль логически связан с SHiNE, но не должен автоматически подключаться к сборке или деплою основного сервера без отдельного решения.
|
- Формат блокчейна и контракт серверного API изменять только после отдельного явного согласия пользователя; документировать изменения в `docs/Blockchain/` и `docs/API/`. Для добавления блока использовать `AddBlock` с актуальной вершиной цепочки.
|
||||||
- В Solana-модуле действуют локальные инструкции `shine-solana/shine/AGENTS.md`; при изменениях внутри модуля сначала читать их.
|
- Любые изменения и деплой production (`shineup.me`, `server2.shineup.me`) — только после отдельного явного согласия пользователя. Перед деплоем прочитать `deploy/AGENTS.md` и проверить резервную копию. Для деплоя использовать скрипты `deploy/scripts/`.
|
||||||
- В git добавлять исходники, lock-файлы, настройки проекта и документацию Solana-модуля, но не добавлять локальные ключи, `.git`, `.idea`, `.gradle`, `target`, `node_modules`, `test-ledger`, логи, временные run-отчёты и `.env`-конфиги.
|
- Секреты, приватные ключи, локальные конфиги, сборочные артефакты и логи не добавлять в git.
|
||||||
- Для Solana deploy/push использовать правила из локального `shine-solana/shine/AGENTS.md`; не смешивать deploy Solana-модуля со скриптами основного server/UI deploy из `deploy/scripts/`.
|
- Коммиты, версии и merge выполнять по `COMMIT_AND_VERSION_RULES.md`. Не делать коммит или push без необходимости для задачи.
|
||||||
- Для регистрации пользователей в Solana (программа `shine_users`) единая актуальная инструкция по деплою/инициализации, адресам программ, и куда их прописывать в UI/сервере находится в:
|
|
||||||
- `docs/Инициализация_Solana_регистрации/README.md`
|
|
||||||
- Этот файл считать основной справкой (single source of truth) по деплою и первичной инициализации Solana-регистрации в текущем проекте.
|
|
||||||
- Актуальная архитектурная справка по устройству Solana-программ, PDA-счетам, ролям DAO и движению средств находится в:
|
|
||||||
- `docs/Solana_Architecture/README.md`
|
|
||||||
- Документы формата пользовательской PDA-записи `shine_users`:
|
|
||||||
- текущий: `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.2.md`;
|
|
||||||
- legacy: `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md`.
|
|
||||||
- Актуальная документация по серверному модулю синхронизации Solana users находится в:
|
|
||||||
- `docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md`
|
|
||||||
- При любом изменении логики серверной синхронизации `shine_users`, её таблиц PostgreSQL, checkpoint-механизма, startup/lifecycle или deploy-настроек обязательно обновлять:
|
|
||||||
- `docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md`
|
|
||||||
- `deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md`
|
|
||||||
|
|
||||||
## Документация блокчейна
|
|
||||||
- Актуальная документация по форматам блокчейна находится в `docs/Blockchain/README.md`.
|
|
||||||
- Это точка входа (оглавление), рядом расположены детальные файлы по форматам, типам каналов и командным сообщениям.
|
|
||||||
- При любом изменении кода, связанного с блокчейном (формат блока, типы каналов, правила чтения/записи, команды), обязательно обновлять соответствующие документы в `docs/Blockchain/`.
|
|
||||||
- Дополнительно обязательно вести `docs/Blockchain/CHANGELOG.md`: дописывать изменения построчно с указанием даты/времени и хэша коммита, после которого внесено изменение.
|
|
||||||
- Перед любым изменением формата блокчейна обязательно заранее предупреждать пользователя, что формат будет изменён.
|
|
||||||
- Изменять формат блокчейна можно только после явного подтверждения пользователя (без подтверждения формат не менять).
|
|
||||||
- Добавление любых данных в блокчейн выполнять только через операцию `AddBlock`.
|
|
||||||
- Перед каждым `AddBlock` обязательно проверять/актуализировать текущее состояние вершины блокчейна (`last global number/hash`) и использовать его при формировании блока.
|
|
||||||
|
|
||||||
## Документация личных сообщений (DM)
|
|
||||||
- Актуальная документация по логике личных сообщений находится в `docs/Personal_Messages/Протокол_DM_v1.md`.
|
|
||||||
- Точный байтовый формат DM находится в `docs/Personal_Messages/Формат_DM_v1.md`.
|
|
||||||
- При любом изменении кода, связанного с личными сообщениями (формат подписанного DM-блока, типы DM-сообщений, правила доставки/ACK/read-receipt, роутинг по сессиям, UI-логика чатов), обязательно обновлять оба документа:
|
|
||||||
- `docs/Personal_Messages/Протокол_DM_v1.md`
|
|
||||||
- `docs/Personal_Messages/Формат_DM_v1.md`
|
|
||||||
- Логика личных сообщений в коде должна всегда соответствовать этим документам.
|
|
||||||
- Документ по личным сообщениям обязан поддерживаться в актуальном состоянии.
|
|
||||||
|
|
||||||
## Документация API сервера
|
|
||||||
- Актуальная документация по публичному JSON/WebSocket API сервера находится в `docs/API/`.
|
|
||||||
- При любом изменении серверного API/эндпоинтов/операций `op` обязательно обновлять соответствующие документы в `docs/API/`.
|
|
||||||
- Перед изменением самого серверного API обязательно явно предупредить пользователя, какие операции, поля запросов/ответов или коды ошибок будут изменены, и запросить отдельное подтверждение.
|
|
||||||
- Без явного подтверждения пользователя формат серверного API не менять; допускается только приведение документации в соответствие уже существующему коду.
|
|
||||||
- Если добавляется новая операция `op`, нужно обновить общий список операций в `docs/API/09_Operations_Index.md` или создать его, если файла ещё нет.
|
|
||||||
|
|
||||||
## Документация Figma
|
|
||||||
- Актуальная документация по переносу экранов SHiNE в Figma и обратному переносу из Figma в код находится в `docs/Figma/`.
|
|
||||||
- Точка входа: `docs/Figma/README.md`.
|
|
||||||
- Подробный рабочий регламент: `docs/Figma/TRANSFER_UI_SCREENS.md`.
|
|
||||||
- Для экранов регистрации, входа и других чувствительных UI-flow по умолчанию переносить экраны в Figma по одному, а не пачкой, если пользователь отдельно не подтвердил иной способ.
|
|
||||||
|
|
||||||
## Версионирование
|
|
||||||
- Все правила по коммитам, merge в `main`, `git push` и обновлению `VERSION.properties` находятся в `COMMIT_AND_VERSION_RULES.md`.
|
|
||||||
- Этот файл считать единым источником истины по правилам версионирования и коммитов для данного репозитория.
|
|
||||||
|
|
||||||
## Deploy
|
|
||||||
- Все документы, инструкции, backup-правила и скрипты деплоя хранить в папке `deploy/`.
|
|
||||||
- Подробные правила для агента по деплою находятся в `deploy/AGENTS.md`; перед любым deploy читать этот файл.
|
|
||||||
- Production-серверы SHiNE: `shineup.me` и `server2.shineup.me`.
|
|
||||||
- Тестовые/devnet серверы SHiNE: `t1.shineup.me`, `t2.shineup.me`, `t3.shineup.me`, `t4.shineup.me`.
|
|
||||||
- В deploy-документах и скриптах использовать домены, а не IP.
|
|
||||||
- По возможности все справки, комментарии и примечания в конфигах/документах писать на русском языке.
|
|
||||||
- Любые изменения и любой деплой на production (`shineup.me` и `server2.shineup.me`) выполнять только после отдельного явного подтверждения пользователя.
|
|
||||||
- Перед production deploy обязательно проверить/обновить бэкап в `deploy/backup/archive/`.
|
|
||||||
- Если пользователь пишет просто `задеплой` без уточнения production/test, уточнить целевой контур; не выбирать production автоматически.
|
|
||||||
- Deploy выполнять shell-скриптами из `deploy/scripts/`; Gradle deploy-задачи не использовать.
|
|
||||||
- Для локального запуска использовать `./gradlew startLocal` (или `startLocalWithBuild`).
|
|
||||||
- Сначала предлагать локальную проверку, а деплой на сервер выполнять по запросу пользователя.
|
|
||||||
- Для временной бесплатной загрузки аватаров в Arweave секретный JWK нельзя хранить в git и нельзя прописывать в репозиторный `application.properties`.
|
|
||||||
- Для продовой настройки тестового Arweave-кошелька JWK-файл нужно хранить только на сервере, например: `/home/player/SHiNE/secrets/test-free-avatar-wallet.json`.
|
|
||||||
- Для этой временной фичи на проде должны быть заданы параметры `test.freeAvatar.walletJwkPath` и `test.freeAvatar.walletAddress` через серверный override-конфиг/секреты на хосте.
|
|
||||||
- После изменения продовых значений `test.freeAvatar.*` нужно заново выполнить серверный деплой или перезапуск сервера, чтобы настройки были перечитаны приложением.
|
|
||||||
- При таких изменениях в git допускается коммитить только документацию и код чтения настроек, но не сам JWK, не содержимое секрета и не реальные приватные ключи.
|
|
||||||
|
|
||||||
## Логи звонков (установка соединения)
|
|
||||||
- Специальный поток диагностики установки звонков идёт через `CallDeliveryReport` (клиент → сервер).
|
|
||||||
- На проде специальный файл для звонков:
|
|
||||||
- `/home/player/SHiNE/shine-server/logs/call-delivery-events.log`
|
|
||||||
- Общий серверный лог (и ротации) на проде:
|
|
||||||
- `/home/player/SHiNE/shine-server/logs/app.log`
|
|
||||||
- `/home/player/SHiNE/shine-server/logs/app.YYYY-MM-DD.log`
|
|
||||||
- Для анализа причин недозвона в первую очередь фильтровать записи по ключам:
|
|
||||||
- `CallDeliveryReport`
|
|
||||||
- `call_connected`
|
|
||||||
- `outgoing_failed`
|
|
||||||
- `incoming_failed`
|
|
||||||
- `call_busy`
|
|
||||||
- `call_declined`
|
|
||||||
- `unknown_error`
|
|
||||||
- В этих записях искать поля `reason`, `failureStage`, `pcConnectionState`, `pcIceConnectionState`, `routeLabel`, `configuredTurnHosts*`, `reachableTurnHosts*`.
|
|
||||||
|
|
||||||
## Будущие фичи / TODO
|
|
||||||
- Папка для задач, сознательно отложенных на будущее: `TODO/`.
|
|
||||||
- Точка входа по планам: `TODO/README.md`.
|
|
||||||
- Внутри планы разделены по горизонтам: `near/`, `medium/`, `far/` и тематическим подпапкам.
|
|
||||||
- Если пользователь спрашивает, какие есть планы или что можно продолжить, сначала читать `TODO/README.md`, затем при необходимости конкретные файлы из подпапок.
|
|
||||||
- Файлы из этой папки не считать активными задачами и не начинать реализацию без явной просьбы пользователя.
|
|
||||||
- Старую папку `docs/Future_Features/` считать выведенной из использования и больше не использовать для новых записей.
|
|
||||||
- Если часть кода временно отключена или закомментирована, либо удалена как временная заглушка, в TODO-файле подробно описывать:
|
|
||||||
- какие файлы и участки отключены;
|
|
||||||
- что осталось в коде как заготовка;
|
|
||||||
- какие документы нужно обновить при возврате;
|
|
||||||
- с какого сценария продолжать разработку;
|
|
||||||
- из какого коммита брать последнюю полную реализацию.
|
|
||||||
|
|
||||||
## Коммуникация по новым задачам
|
|
||||||
- При получении нового задания кратко подтвердить понимание задачи, если это помогает синхронизироваться.
|
|
||||||
- До начала реализации задавать уточняющие вопросы только когда без ответа есть риск сделать не то или затронуть опасную область.
|
|
||||||
- Если задача понятна и не требует отдельного подтверждения по другим правилам проекта, переходить к реализации сразу.
|
|
||||||
- Если есть уместные идеи/улучшения — кратко предложить их; если полезных идей нет, ничего дополнительно не предлагать.
|
|
||||||
|
|||||||
@@ -1,7 +1,29 @@
|
|||||||
# SHiNE
|
# SHiNE
|
||||||
|
|
||||||
## План запуска DAO
|
SHiNE — проект децентрализованного общения: браузерный клиент, сервер, пользовательские блокчейны, личные сообщения и интеграция с Solana и Arweave. Репозиторий содержит также экспериментальные компоненты для ESP32 и браузерное расширение кошелька.
|
||||||
|
|
||||||
План запуска DAO зафиксирован в [DAO_запуск/README.md](DAO_запуск/README.md).
|
> **Статус:** активная разработка и подготовка к публичному запуску. Исходный код доступен для изучения; самостоятельный запуск возможен, но инструкции по установке ещё дорабатываются. Не все описанные в планах возможности реализованы.
|
||||||
|
|
||||||
Это рабочий список задач по `этап1` и `этап2`. Дальше ведём его как основной чек-лист запуска DAO и отмечаем в нём выполненные пункты по мере готовности.
|
## Как устроен проект
|
||||||
|
|
||||||
|
| Компонент | Назначение |
|
||||||
|
| --- | --- |
|
||||||
|
| [`shine-UI/`](shine-UI/) | Браузерный клиент и панель администратора сервера |
|
||||||
|
| [`SHiNE-server/`](SHiNE-server/) | WebSocket/HTTP сервер, PostgreSQL, блокчейн, доставка сообщений |
|
||||||
|
| [`shine-solana/shine/`](shine-solana/shine/) | Anchor-программы и инструменты Solana |
|
||||||
|
| [`SHiNE-browser-plugin-wallet/`](SHiNE-browser-plugin-wallet/) | Браузерное расширение кошелька |
|
||||||
|
| [`ESP32/`](ESP32/) | Прошивки и прототипы устройств |
|
||||||
|
| [`deploy/`](deploy/) | Скрипты и инструкции по развёртыванию |
|
||||||
|
|
||||||
|
Архитектура и границы компонентов описаны в [общей схеме](docs/ARCHITECTURE.md). Пользовательские блоки проектируются для публикации в Arweave; подробности и текущие ограничения тестового контура приведены в [документации блокчейна](docs/Blockchain/README.md).
|
||||||
|
|
||||||
|
## Самостоятельный запуск
|
||||||
|
|
||||||
|
Основной сервер собирается Gradle из корня репозитория. Для локального запуска предусмотрены `./gradlew startLocal` и `./gradlew startLocalWithBuild`; состав и требования этих задач зависят от локальной конфигурации. Начните с [инструкций по развёртыванию](deploy/README.md) и [примера настроек](application.properties.example). Клиент находится в `shine-UI/`. Публичное пошаговое руководство по установке всего комплекса ещё готовится.
|
||||||
|
|
||||||
|
## Документация
|
||||||
|
|
||||||
|
- [Каталог документации](docs/README.md) — действующие спецификации, инструкции и планы.
|
||||||
|
- [Общая архитектура](docs/ARCHITECTURE.md) — компоненты и потоки данных.
|
||||||
|
- [API](docs/API/09_Operations_Index.md), [формат блокчейна](docs/Blockchain/README.md), [личные сообщения](docs/Personal_Messages/README.md), [Solana](docs/Solana_Architecture/README.md).
|
||||||
|
- [Правила обновления документации](docs/CONTRIBUTING_DOCS.md).
|
||||||
|
|||||||
@@ -15,6 +15,17 @@ SHiNE-server — серверная часть мессенджера SHiNE: Web
|
|||||||
- `shine-server-config/` — конфигурация сервера
|
- `shine-server-config/` — конфигурация сервера
|
||||||
- `shine-server-log/` — логирование
|
- `shine-server-log/` — логирование
|
||||||
- `shine-server-geo/` — геолокация IP
|
- `shine-server-geo/` — геолокация IP
|
||||||
|
- `shine-server-solana-users-sync/` — синхронизация PDA Solana в серверные данные
|
||||||
|
- `shine-server-archive/` — публикация/импорт Arweave и workflow бесплатной регистрации
|
||||||
|
|
||||||
|
## Документация при изменении кода
|
||||||
|
|
||||||
|
- Новая или изменённая WS-операция: обновить профильный документ `../docs/API/` и `../docs/API/09_Operations_Index.md`; список зарегистрированных операций сверять с `JsonHandlerRegistry.java`.
|
||||||
|
- Формат блока, правила проверки или публикации: обновить `../docs/Blockchain/` и журнал изменений этого раздела.
|
||||||
|
- Доставка или формат DM: обновить затронутые документы из `../docs/Personal_Messages/README.md`.
|
||||||
|
- Синхронизация Solana users: обновить `../docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md` и `../deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md`.
|
||||||
|
- Регистрация с email, namespace или Arweave-сертификатами: обновить действующие документы в `../docs/registration-v2/`, а исторические планы явно оставлять помеченными как история.
|
||||||
|
- Изменение локального запуска или конфигурации: обновить корневой `../README.md`, `../docs/ARCHITECTURE.md` либо `../deploy/README.md` по затронутой теме.
|
||||||
|
|
||||||
## Настройка сервера в Solana (Solana PDA)
|
## Настройка сервера в Solana (Solana PDA)
|
||||||
|
|
||||||
|
|||||||
+2
-2
@@ -1,2 +1,2 @@
|
|||||||
client.version=1.20.18
|
client.version=1.20.19
|
||||||
server.version=1.16.15
|
server.version=1.16.16
|
||||||
|
|||||||
@@ -7,7 +7,7 @@
|
|||||||
- `GetUser` — временная серверная проверка существования пользователя и чтение его базовых данных;
|
- `GetUser` — временная серверная проверка существования пользователя и чтение его базовых данных;
|
||||||
- `SearchUsers` — dev/test поиск логинов по префиксу, при необходимости с фильтром только по server PDA.
|
- `SearchUsers` — dev/test поиск логинов по префиксу, при необходимости с фильтром только по server PDA.
|
||||||
|
|
||||||
Регистрация выполняется только через Solana.
|
Регистрация платного аккаунта выполняется через Solana; для бесплатного namespace также зарегистрирован отдельный flow с email-кодом и сертификатом Arweave (см. раздел «Регистрация V2» ниже).
|
||||||
|
|
||||||
## Статус документа
|
## Статус документа
|
||||||
|
|
||||||
@@ -170,12 +170,12 @@
|
|||||||
|
|
||||||
- `GetUser` — проверка существования пользователя на сервере.
|
- `GetUser` — проверка существования пользователя на сервере.
|
||||||
- `SearchUsers` — временный поиск пользователей по префиксу.
|
- `SearchUsers` — временный поиск пользователей по префиксу.
|
||||||
- Регистрация выполняется только через Solana.
|
- Регистрация платного аккаунта выполняется через Solana; для бесплатного namespace также зарегистрирован отдельный flow с email-кодом и сертификатом Arweave (см. раздел «Регистрация V2» ниже).
|
||||||
|
|
||||||
|
|
||||||
## Регистрация V2: полные логины и независимые проверки
|
## Регистрация V2: полные логины и независимые проверки
|
||||||
|
|
||||||
Публичные WS-операции нового протокола перечислены в `docs/registration-v2/WS_REGISTRATION_V2_PROPOSED_NOT_ENABLED.md`.
|
Публичные WS-операции нового протокола перечислены в [контракте регистрации v2](../registration-v2/WS_REGISTRATION_V2_API.md).
|
||||||
Сначала `GetNamespaces` → `CheckRegistrationLogin` с полным `login@namespace`; затем **только для бесплатной регистрации** отдельное `CheckRegistrationEmail`. После проверки запускается `StartFreeRegistration`, затем `ConfirmFreeRegistration` с шестизначным одноразовым кодом из письма (1 час, 5 попыток). Состояние читается через `GetRegistrationStatus`.
|
Сначала `GetNamespaces` → `CheckRegistrationLogin` с полным `login@namespace`; затем **только для бесплатной регистрации** отдельное `CheckRegistrationEmail`. После проверки запускается `StartFreeRegistration`, затем `ConfirmFreeRegistration` с шестизначным одноразовым кодом из письма (1 час, 5 попыток). Состояние читается через `GetRegistrationStatus`.
|
||||||
|
|
||||||
Все бесплатные сертификаты подписаны ANS-104 и внутренней подписью Ed25519; успешный Turbo ACK не означает подтверждённую высоту Arweave. Клиент никогда не отправляет пароль или приватные ключи на сервер.
|
Все бесплатные сертификаты подписаны ANS-104 и внутренней подписью Ed25519; успешный Turbo ACK не означает подтверждённую высоту Arweave. Клиент никогда не отправляет пароль или приватные ключи на сервер.
|
||||||
|
|||||||
@@ -12,6 +12,12 @@
|
|||||||
|
|
||||||
| Операция | Раздел документации | Кратко |
|
| Операция | Раздел документации | Кратко |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
|
| `GetNamespaces` | `01_User_Registration_API.md` | список namespace для регистрации |
|
||||||
|
| `CheckRegistrationLogin` | `01_User_Registration_API.md` | проверка полного логина |
|
||||||
|
| `CheckRegistrationEmail` | `01_User_Registration_API.md` | проверка доступности email |
|
||||||
|
| `StartFreeRegistration` | `01_User_Registration_API.md` | начало бесплатной регистрации с email-кодом |
|
||||||
|
| `ConfirmFreeRegistration` | `01_User_Registration_API.md` | подтверждение кода и выпуск сертификата |
|
||||||
|
| `GetRegistrationStatus` | `01_User_Registration_API.md` | статус регистрации |
|
||||||
| `GetUser` | `01_User_Registration_API.md` | чтение/проверка пользователя + server-состояние его блокчейна |
|
| `GetUser` | `01_User_Registration_API.md` | чтение/проверка пользователя + server-состояние его блокчейна |
|
||||||
| `SearchUsers` | `01_User_Registration_API.md` | поиск логинов и публичных имён пользователей |
|
| `SearchUsers` | `01_User_Registration_API.md` | поиск логинов и публичных имён пользователей |
|
||||||
| `SearchChannels` | `06_Channels_Read_API.md` | поиск публичных каналов по названию, slug и логину владельца |
|
| `SearchChannels` | `06_Channels_Read_API.md` | поиск публичных каналов по названию, slug и логину владельца |
|
||||||
@@ -20,6 +26,13 @@
|
|||||||
| `CreateAuthSession` | `02_Authentication_API.md` | создание новой авторизованной сессии |
|
| `CreateAuthSession` | `02_Authentication_API.md` | создание новой авторизованной сессии |
|
||||||
| `SessionChallenge` | `02_Authentication_API.md` | challenge для входа в существующую сессию |
|
| `SessionChallenge` | `02_Authentication_API.md` | challenge для входа в существующую сессию |
|
||||||
| `SessionLogin` | `02_Authentication_API.md` | вход в существующую сессию |
|
| `SessionLogin` | `02_Authentication_API.md` | вход в существующую сессию |
|
||||||
|
| `UpsertEspPairingSettings` | `03_Session_Management_API.md` | альтернативное имя настройки pairing; тот же обработчик, что `UpsertTrustedDeviceLoginSettings` |
|
||||||
|
| `StartEspPairing` | `03_Session_Management_API.md` | альтернативное имя начала pairing |
|
||||||
|
| `ListEspPairingRequests` | `03_Session_Management_API.md` | альтернативное имя списка заявок |
|
||||||
|
| `ApproveEspPairing` | `03_Session_Management_API.md` | альтернативное имя подтверждения |
|
||||||
|
| `RejectEspPairing` | `03_Session_Management_API.md` | альтернативное имя отклонения |
|
||||||
|
| `CancelEspPairing` | `03_Session_Management_API.md` | альтернативное имя отмены |
|
||||||
|
| `GetEspPairingStatus` | `03_Session_Management_API.md` | альтернативное имя чтения статуса |
|
||||||
| `GetTrustedDeviceLoginSettings` | `03_Session_Management_API.md` | чтение текущего режима входа через доверенное устройство |
|
| `GetTrustedDeviceLoginSettings` | `03_Session_Management_API.md` | чтение текущего режима входа через доверенное устройство |
|
||||||
| `UpsertTrustedDeviceLoginSettings` | `03_Session_Management_API.md` | включение/обновление pairing-настроек доверенной сессией |
|
| `UpsertTrustedDeviceLoginSettings` | `03_Session_Management_API.md` | включение/обновление pairing-настроек доверенной сессией |
|
||||||
| `StartTrustedDeviceLogin` | `03_Session_Management_API.md` | создание pairing-заявки для нового устройства |
|
| `StartTrustedDeviceLogin` | `03_Session_Management_API.md` | создание pairing-заявки для нового устройства |
|
||||||
@@ -56,6 +69,9 @@
|
|||||||
| `GetMessageThread` | `06_Channels_Read_API.md` | тред сообщения |
|
| `GetMessageThread` | `06_Channels_Read_API.md` | тред сообщения |
|
||||||
| `GetMessageLikes` | `06_Channels_Read_API.md` | списки пользователей, поставивших лайк сообщению |
|
| `GetMessageLikes` | `06_Channels_Read_API.md` | списки пользователей, поставивших лайк сообщению |
|
||||||
| `GetPersonalDiary` | `06_Channels_Read_API.md` | виртуальный канал `Личный дневник` из STATUS_ACTION |
|
| `GetPersonalDiary` | `06_Channels_Read_API.md` | виртуальный канал `Личный дневник` из STATUS_ACTION |
|
||||||
|
| `ListUserProfileChannels` | `06_Channels_Read_API.md` | публичные каналы профиля |
|
||||||
|
| `ListUserProfileRelations` | `11_Connections_API.md` | связи пользователя в профиле |
|
||||||
|
| `GetUserCounters` | `17_User_Counters_API.md` | счётчики пользователя |
|
||||||
| `GetChannelsCounters` | `06_Channels_Read_API.md` | счетчики разделов каналов |
|
| `GetChannelsCounters` | `06_Channels_Read_API.md` | счетчики разделов каналов |
|
||||||
| `SetChannelReadState` | `06_Channels_Read_API.md` | подписанный watermark чтения канала |
|
| `SetChannelReadState` | `06_Channels_Read_API.md` | подписанный watermark чтения канала |
|
||||||
| `ListGroupChats200` | `06_Channels_Read_API.md` | список групповых чатов типа `200` |
|
| `ListGroupChats200` | `06_Channels_Read_API.md` | список групповых чатов типа `200` |
|
||||||
@@ -93,7 +109,7 @@
|
|||||||
- `ServerHello` пока принимает заявленный `serverLogin` на доверии и не является криптографической аутентификацией.
|
- `ServerHello` пока принимает заявленный `serverLogin` на доверии и не является криптографической аутентификацией.
|
||||||
- HTTP endpoints зашифрованных DM-файлов (`PUT/GET/HEAD/OPTIONS /dm-files/{fileId}`) не являются WebSocket `op` и описаны отдельно в `18_DM_File_Storage_API.md`.
|
- HTTP endpoints зашифрованных DM-файлов (`PUT/GET/HEAD/OPTIONS /dm-files/{fileId}`) не являются WebSocket `op` и описаны отдельно в `18_DM_File_Storage_API.md`.
|
||||||
- HTTP endpoints публичных content-addressed файлов (`PUT/GET/HEAD/OPTIONS /files/{sha256}`) также не являются WebSocket `op` и описаны отдельно в `21_Public_File_Storage_API.md`.
|
- HTTP endpoints публичных content-addressed файлов (`PUT/GET/HEAD/OPTIONS /files/{sha256}`) также не являются WebSocket `op` и описаны отдельно в `21_Public_File_Storage_API.md`.
|
||||||
- Классы `Net_MarkChannelMessagesSeen_*` существуют в коде, но операция `MarkChannelMessagesSeen` не зарегистрирована в `JsonHandlerRegistry`, поэтому в публичный список API не входит.
|
- Закомментированный `ListSubscribedChannels` не зарегистрирован и не входит в публичный API. Классы `Net_MarkChannelMessagesSeen_*` существуют в коде, но операция `MarkChannelMessagesSeen` не зарегистрирована в `JsonHandlerRegistry`, поэтому в публичный список API не входит.
|
||||||
- HTTP debug endpoints из `src/main/java/server/debug/` не входят в этот индекс WebSocket `op`; они описаны отдельно в `13_HTTP_Debug_API.md`.
|
- HTTP debug endpoints из `src/main/java/server/debug/` не входят в этот индекс WebSocket `op`; они описаны отдельно в `13_HTTP_Debug_API.md`.
|
||||||
|
|
||||||
|
|
||||||
@@ -106,7 +122,7 @@
|
|||||||
- `ConfirmFreeRegistration` — подтверждение тестовым кодом и Turbo ACK;
|
- `ConfirmFreeRegistration` — подтверждение тестовым кодом и Turbo ACK;
|
||||||
- `GetRegistrationStatus` — статус и публичные поля сертификата для upgrade.
|
- `GetRegistrationStatus` — статус и публичные поля сертификата для upgrade.
|
||||||
|
|
||||||
Точный JSON и ограничения: `docs/registration-v2/WS_REGISTRATION_V2_PROPOSED_NOT_ENABLED.md` (имя сохранено для обратных ссылок; внутри утверждённая версия).
|
Точный JSON и ограничения: [контракт регистрации v2](../registration-v2/WS_REGISTRATION_V2_API.md).
|
||||||
|
|
||||||
### `GetRegistrationStatus` после DB v35
|
### `GetRegistrationStatus` после DB v35
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,16 @@
|
|||||||
|
# API сервера SHiNE
|
||||||
|
|
||||||
|
Сервер принимает JSON-операции по WebSocket. Точный общий конверт описан в [общем формате](00_Common_API_Format.md); зарегистрированные имена `op` — в [индексе операций](09_Operations_Index.md). Источник списка в коде: `SHiNE-server/shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/JsonHandlerRegistry.java`.
|
||||||
|
|
||||||
|
| Раздел | Документы |
|
||||||
|
| --- | --- |
|
||||||
|
| Регистрация и вход | [регистрация](01_User_Registration_API.md), [аутентификация](02_Authentication_API.md), [сессии и pairing](03_Session_Management_API.md) |
|
||||||
|
| Блокчейн и ключи | [AddBlock](04_Add_Block_to_Blockchain_API.md), [ротация ключей](19_Key_Rotation_API.md), [собственная цепочка](20_Get_My_Blockchain_API.md) |
|
||||||
|
| Каналы и профиль | [чтение каналов](06_Channels_Read_API.md), [связи](11_Connections_API.md), [счётчики](17_User_Counters_API.md) |
|
||||||
|
| Личные сообщения | [DM, push и звонки](12_Direct_Messages_Push_Calls_API.md), [HTTP-файлы DM](18_DM_File_Storage_API.md) |
|
||||||
|
| Настройки и система | [технические операции](05_Technical_Requests_API.md), [параметры](10_User_Params_API.md), [настройки](13_User_Settings_API.md), [уведомления](15_Notifications_API.md) |
|
||||||
|
| Отдельные HTTP endpoint | [публичные файлы](21_Public_File_Storage_API.md), [debug](13_HTTP_Debug_API.md) |
|
||||||
|
|
||||||
|
Зарегистрированное имя `op` означает наличие обработчика, но не гарантирует доступность функции на каждом сервере: часть возможностей зависит от конфигурации, сети и состояния миграций. Сведения о текущей регистрации по email — в [профильном документе](../registration-v2/RESEND_EMAIL_VERIFICATION.md). Старые планы регистрации описывают прежние этапы.
|
||||||
|
|
||||||
|
При изменении `JsonHandlerRegistry` обновите профильный документ и индекс. После изменения документации запустите `python3 scripts/check_docs.py` из корня репозитория.
|
||||||
@@ -0,0 +1,37 @@
|
|||||||
|
# Архитектура SHiNE
|
||||||
|
|
||||||
|
Этот документ даёт общую карту продукта. Точные форматы, операции и инструкции находятся по ссылкам ниже. Состояние отдельных функций может отличаться между тестовым и production контурами; для изменения протокола сверяйтесь с кодом и профильной спецификацией.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
UI[Браузерный UI] -->|HTTP / WebSocket| Server[Сервер SHiNE]
|
||||||
|
Wallet[Расширение кошелька] -->|Сессия и подписи| Server
|
||||||
|
ESP[ESP32 прототипы] -.->|Сценарии устройства| Server
|
||||||
|
Server --> DB[(PostgreSQL)]
|
||||||
|
Server <-->|Публикация и импорт блоков| Arweave[(Arweave)]
|
||||||
|
UI -->|PDA и транзакции| Solana[(Solana)]
|
||||||
|
Server -->|Чтение PDA / синхронизация| Solana
|
||||||
|
```
|
||||||
|
|
||||||
|
## Компоненты и границы
|
||||||
|
|
||||||
|
| Компонент | За что отвечает | Где смотреть детали |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `shine-UI/` | Браузерные экраны, локальное состояние, взаимодействие с сервером | `shine-UI/AGENTS.md`, `docs/UI-Design/README.md` |
|
||||||
|
| `SHiNE-server/` | HTTP/WS запросы, валидация, доставка сообщений и звонков, хранение | `SHiNE-server/AGENTS.md`, `docs/API/09_Operations_Index.md` |
|
||||||
|
| PostgreSQL | Локальные данные сервера и пользовательские блоки | `SHiNE-server/shine-server-db/`, `docs/Blockchain/README.md` |
|
||||||
|
| Arweave | Внешняя публикация и импорт подписанных пользовательских блоков | `docs/Blockchain/17_ANS104_Arweave_Transport.md` |
|
||||||
|
| Solana | Пользовательские PDA, регистрация и платёжные программы | `docs/Solana_Architecture/README.md`, `docs/Инициализация_Solana_регистрации/README.md` |
|
||||||
|
| `SHiNE-browser-plugin-wallet/` | Вход через сессию кошелька в браузере | `SHiNE-browser-plugin-wallet/README.md` |
|
||||||
|
| `ESP32/` | Прототипы устройств и прошивки | `ESP32/AGENTS.md` |
|
||||||
|
|
||||||
|
## Основные потоки
|
||||||
|
|
||||||
|
1. **Регистрация и подключение.** Клиент взаимодействует с Solana PDA и сервером; серверный адрес публикуется в PDA серверного аккаунта. Детали регистрации и её текущий статус: `docs/Инициализация_Solana_регистрации/README.md`, `docs/registration-v2/README.md`.
|
||||||
|
2. **Пользовательские блоки.** Клиент создаёт подписанный ANS-104 DataItem с SHiNE Frame v1. Сервер проверяет его при `AddBlock`, хранит локально в PostgreSQL и, в зависимости от режима публикации, передаёт в Arweave. Другие серверы могут импортировать опубликованные блоки. Точный формат и ограничения: `docs/Blockchain/README.md`.
|
||||||
|
3. **Личные сообщения.** Клиент формирует зашифрованное сообщение; сервер обслуживает доставку и локальное хранение, не получая ключ содержимого. Точные правила, формат и доставка: `docs/Personal_Messages/README.md`.
|
||||||
|
4. **Деплой.** Сборка основного сервера управляется корневым Gradle-проектом; эксплуатационные сценарии и отдельный Solana-модуль документированы раздельно: `deploy/README.md`, `shine-solana/shine/AGENTS.md`.
|
||||||
|
|
||||||
|
## Ограничения этой карты
|
||||||
|
|
||||||
|
Схема показывает связи компонентов, но не обещает доступность каждой функции на каждом контуре. Документы с названиями `TODO`, `Черновик`, `PROPOSED` и исторические отчёты не описывают действующий контракт. Если карта расходится с профильной спецификацией или кодом, расхождение нужно проверить и исправить по [правилам сопровождения](CONTRIBUTING_DOCS.md).
|
||||||
+4
-2
@@ -4,6 +4,8 @@
|
|||||||
**Базовая версия:** `SHiNE-bundle-2026.10.23-12.36.02.zip` (SHA-256 `e2871bb11610437c354507dc9a723d64f14b0be4161af5f82d19f1466af648a6`)
|
**Базовая версия:** `SHiNE-bundle-2026.10.23-12.36.02.zip` (SHA-256 `e2871bb11610437c354507dc9a723d64f14b0be4161af5f82d19f1466af648a6`)
|
||||||
**Исходная ветка/коммит:** не определены, потому что загруженный архив не содержит `.git`.
|
**Исходная ветка/коммит:** не определены, потому что загруженный архив не содержит `.git`.
|
||||||
|
|
||||||
|
> **Статус документа:** исторический журнал этапов. Более поздние изменения кода здесь не всегда отражены. Сейчас сервер генерирует шестизначный код и отправляет его через Resend. Текущее поведение подтверждения описано в [RESEND_EMAIL_VERIFICATION.md](../../registration-v2/RESEND_EMAIL_VERIFICATION.md), а зарегистрированные WS-операции — в [индексе API](../../API/09_Operations_Index.md).
|
||||||
|
|
||||||
## Прогресс всех этапов (мастер-план V2, всего 14: 0–13)
|
## Прогресс всех этапов (мастер-план V2, всего 14: 0–13)
|
||||||
|
|
||||||
| Этап | Название | Статус |
|
| Этап | Название | Статус |
|
||||||
@@ -70,7 +72,7 @@
|
|||||||
## 23 октября 2026: накопительный код этапов 8–10
|
## 23 октября 2026: накопительный код этапов 8–10
|
||||||
|
|
||||||
- Этап 8: новый `VerifiedFreeRegistrationImporter`, `FreeRegistrationPublisher`, GraphQL discovery отдельного `t=reg` и PostgreSQL миграция v34 для checkpoint; ACK Turbo и независимое Arweave подтверждение — разные события.
|
- Этап 8: новый `VerifiedFreeRegistrationImporter`, `FreeRegistrationPublisher`, GraphQL discovery отдельного `t=reg` и PostgreSQL миграция v34 для checkpoint; ACK Turbo и независимое Arweave подтверждение — разные события.
|
||||||
- Этап 9: Java `FreeRegistrationWorkflow` есть, но **новые публичные WS `op` не регистрировались** до отдельного согласования по `AGENTS.md`. Проект договора — `WS_REGISTRATION_V2_PROPOSED_NOT_ENABLED.md`.
|
- Этап 9: Java `FreeRegistrationWorkflow` есть, но **новые публичные WS `op` не регистрировались** до отдельного согласования по `AGENTS.md`. Проект договора — `WS_REGISTRATION_V2_API.md`.
|
||||||
- Этап 10: `RegistrationIdentityDAO` и проверка отсутствия PDA у бесплатного пользователя; семь серверных обработчиков KeyRotation проверяют статус. Платные могут исполнять старый процесс.
|
- Этап 10: `RegistrationIdentityDAO` и проверка отсутствия PDA у бесплатного пользователя; семь серверных обработчиков KeyRotation проверяют статус. Платные могут исполнять старый процесс.
|
||||||
- Реальные тесты сквозного сервера/DB/сети по-прежнему не проведены. Патч только для test/dev review; **НЕ деплоить на production**.
|
- Реальные тесты сквозного сервера/DB/сети по-прежнему не проведены. Патч только для test/dev review; **НЕ деплоить на production**.
|
||||||
- Отчёт: `PATCH_STAGES_8_9_10.md`.
|
- Отчёт: `PATCH_STAGES_8_9_10.md`.
|
||||||
@@ -79,7 +81,7 @@
|
|||||||
## 23 октября 2026: накопительный патч с этапами 9 и 11–13
|
## 23 октября 2026: накопительный патч с этапами 9 и 11–13
|
||||||
|
|
||||||
- **9:** шесть WS API с независимыми проверками имени и email. Утверждение владельца получено. JSON DTO, Registry и SPI в net-protocol, сервис в archive, startup в WsServer; ограничитель запросов по WebSocket и глобальный счётчик. Не проверено реальной Java Gradle-сборкой.
|
- **9:** шесть WS API с независимыми проверками имени и email. Утверждение владельца получено. JSON DTO, Registry и SPI в net-protocol, сервис в archive, startup в WsServer; ограничитель запросов по WebSocket и глобальный счётчик. Не проверено реальной Java Gradle-сборкой.
|
||||||
- **11:** переписана UI-регистрация под выбор paid/free namespace, Argon2id от полного логина, отдельный email, тест `1111`, Turbo ACK и текущую сессию. Существующая оплата Solana сохранена. Node-тесты проверяют кодеки/контракт, но не браузерное прохождение сценария.
|
- **11:** переписана UI-регистрация под выбор paid/free namespace, Argon2id от полного логина, отдельный email, демонстрационное подтверждение email, Turbo ACK и текущую сессию. Существующая оплата Solana сохранена. Node-тесты проверяют кодеки/контракт, но не браузерное прохождение сценария.
|
||||||
- **12:** добавлен экран upgrade по неизменным ключам и внутренней подписи сертификата; status из сервера, fee из namespace-PDA. Не проверена отправка реальной транзакции localnet/devnet.
|
- **12:** добавлен экран upgrade по неизменным ключам и внутренней подписи сертификата; status из сервера, fee из namespace-PDA. Не проверена отправка реальной транзакции localnet/devnet.
|
||||||
- **13:** добавлены контрактные тесты и smoke-runbook; полноценный E2E отложен до доступных Rust/Gradle/PostgreSQL/Turbo сетей.
|
- **13:** добавлены контрактные тесты и smoke-runbook; полноценный E2E отложен до доступных Rust/Gradle/PostgreSQL/Turbo сетей.
|
||||||
- **Не готово:** `cargo`, full Gradle, PostgreSQL migration v33/v34, реальные WS, Turbo ACK, Solana localnet, браузер и межсерверный импорт. Все этапы **PARTIAL**, никакого production.
|
- **Не готово:** `cargo`, full Gradle, PostgreSQL migration v33/v34, реальные WS, Turbo ACK, Solana localnet, браузер и межсерверный импорт. Все этапы **PARTIAL**, никакого production.
|
||||||
+2
-2
@@ -7,7 +7,7 @@
|
|||||||
Владелец согласовал шесть новых WS `op`: `GetNamespaces`, `CheckRegistrationLogin`, `CheckRegistrationEmail`, `StartFreeRegistration`, `ConfirmFreeRegistration`, `GetRegistrationStatus`. Проверка имени и email — две независимые операции и два экрана UI. Код интегрирован через Bridge SPI (`shine-server-net-protocol` ↔ `shine-server-archive`), поднимается в `WsServer` без циклической зависимости Gradle. Реестр API и docs/API обновлены.
|
Владелец согласовал шесть новых WS `op`: `GetNamespaces`, `CheckRegistrationLogin`, `CheckRegistrationEmail`, `StartFreeRegistration`, `ConfirmFreeRegistration`, `GetRegistrationStatus`. Проверка имени и email — две независимые операции и два экрана UI. Код интегрирован через Bridge SPI (`shine-server-net-protocol` ↔ `shine-server-archive`), поднимается в `WsServer` без циклической зависимости Gradle. Реестр API и docs/API обновлены.
|
||||||
|
|
||||||
- Внутренняя Java-машина заявок сохраняет один подписанный ANS-104 DataItem на challenge, повторное подтверждение до TTL использует те же байты.
|
- Внутренняя Java-машина заявок сохраняет один подписанный ANS-104 DataItem на challenge, повторное подтверждение до TTL использует те же байты.
|
||||||
- Почтовый код `1111` учебный, факт владения email НЕ подтверждает.
|
- На момент этого патча подтверждение email было демонстрационным; текущий механизм отправки письма описан отдельно.
|
||||||
- Код ответа `TURBO_ACCEPTED` отличается от `ARWEAVE_CONFIRMED`.
|
- Код ответа `TURBO_ACCEPTED` отличается от `ARWEAVE_CONFIRMED`.
|
||||||
- Введены базовые ограничения частоты запросов (30 на соединение и 1200 глобально за минуту); не заменяют IP/rate limiting на reverse proxy.
|
- Введены базовые ограничения частоты запросов (30 на соединение и 1200 глобально за минуту); не заменяют IP/rate limiting на reverse proxy.
|
||||||
- Debug-логи регистрации редактированы, чтобы не записывать email/публичные ключи и содержимое challenge.
|
- Debug-логи регистрации редактированы, чтобы не записывать email/публичные ключи и содержимое challenge.
|
||||||
@@ -15,7 +15,7 @@
|
|||||||
|
|
||||||
## Этап 11 — регистрационные экраны (PARTIAL)
|
## Этап 11 — регистрационные экраны (PARTIAL)
|
||||||
|
|
||||||
`register-view`: переключатель «Solana / бесплатно», on-chain список namespace через сервер, `login@namespace`, пароль, отдельный запрос доступности имени, исходный KDF Argon2id на полном имени и пароле, сохранение черновика в рамках текущего сеанса. Для платного переход в старую (адаптированную) страницу оплаты. Для бесплатного новая `registration-email-view`: запрос доступности email → временная заявка → код `1111` → Turbo → попытка штатного авто-входа. Ключи генерируются только локально; API передаёт только три публичных ключа в Base64.
|
`register-view`: переключатель «Solana / бесплатно», on-chain список namespace через сервер, `login@namespace`, пароль, отдельный запрос доступности имени, исходный KDF Argon2id на полном имени и пароле, сохранение черновика в рамках текущего сеанса. Для платного переход в старую (адаптированную) страницу оплаты. Для бесплатного новая `registration-email-view`: запрос доступности email → временная заявка → подтверждение email → Turbo → попытка штатного авто-входа. Ключи генерируются только локально; API передаёт только три публичных ключа в Base64.
|
||||||
|
|
||||||
Требуется реальный браузерный E2E: итоговый экран входа и маршрутизация бесплатного пользователя не проверены.
|
Требуется реальный браузерный E2E: итоговый экран входа и маршрутизация бесплатного пользователя не проверены.
|
||||||
|
|
||||||
+2
-2
@@ -1,6 +1,6 @@
|
|||||||
# SHiNE — накопительный патч этапов 0–7 (новые изменения 4–7)
|
# SHiNE — накопительный патч этапов 0–7 (новые изменения 4–7)
|
||||||
|
|
||||||
**Основа:** в точности каталог исходников ZIP `SHiNE-registration-stages0-3-combined-2026.10.23.zip`. Без Git/commit, никаких deploy/запросов к production не производилось. Нумерация — 14 этапов из `MASTER_PLAN_V2_2026-10-23.md`.
|
**Основа:** в точности каталог исходников ZIP `SHiNE-registration-stages0-3-combined-2026.10.23.zip`. Без Git/commit, никаких deploy/запросов к production не производилось. Нумерация — 14 этапов из первоначального плана этапов.
|
||||||
|
|
||||||
## Внесённые изменения
|
## Внесённые изменения
|
||||||
|
|
||||||
@@ -10,7 +10,7 @@
|
|||||||
|
|
||||||
**Этап 6 / Solana Users Sync (код):** `IX_CREATE_NAMESPACE=7` распознаётся в history, бинарный namespace декодируется отдельно, адрес проверяется через `SHA256(namespace=...)`, `SHA256(user_login=...)` для новых пользователей; snapshot и history умеют получать namespace + user, атомарно upsert в PostgreSQL вместе с checkpoint, повторный on-chain snapshot не удаляет free-пользователей; `PostgresStorageRepository.migrate()` больше не перезаписывает функции v33 устаревшими Solana-only. Кодек и PDA проверены на известном векторе Java. Полный RPC/DB history replay **не выполнялся**.
|
**Этап 6 / Solana Users Sync (код):** `IX_CREATE_NAMESPACE=7` распознаётся в history, бинарный namespace декодируется отдельно, адрес проверяется через `SHA256(namespace=...)`, `SHA256(user_login=...)` для новых пользователей; snapshot и history умеют получать namespace + user, атомарно upsert в PostgreSQL вместе с checkpoint, повторный on-chain snapshot не удаляет free-пользователей; `PostgresStorageRepository.migrate()` больше не перезаписывает функции v33 устаревшими Solana-only. Кодек и PDA проверены на известном векторе Java. Полный RPC/DB history replay **не выполнялся**.
|
||||||
|
|
||||||
**Этап 7 / Java registrar (код):** интерфейс `RegistrarSigner`, локальный seed signer с конфигурацией вне Git, бинарный codec, формирование внутреннего Ed25519+внешнего ANS-104 с точными тегами и верификацией, `FreeRegistrationIssuer` проверяет доверенное namespace-PDA из синхронизированного реестра, занятость login/email и тестовый код `1111`. **Пока только выпускает raw signed bytes, не передаёт Turbo и не активирует пользователя** — это этап 8. Отдельный тест `FreeRegistrationCertificateV1Check` сверяет существующий JSON-фиксированный DataItem и отбрасывает искажения.
|
**Этап 7 / Java registrar (код):** интерфейс `RegistrarSigner`, локальный seed signer с конфигурацией вне Git, бинарный codec, формирование внутреннего Ed25519+внешнего ANS-104 с точными тегами и верификацией, `FreeRegistrationIssuer` проверяет доверенное namespace-PDA из синхронизированного реестра, занятость login/email и демонстрационный механизм подтверждения email. **Пока только выпускает raw signed bytes, не передаёт Turbo и не активирует пользователя** — это этап 8. Отдельный тест `FreeRegistrationCertificateV1Check` сверяет существующий JSON-фиксированный DataItem и отбрасывает искажения.
|
||||||
|
|
||||||
## Обязательные проверки, которые реально прошли
|
## Обязательные проверки, которые реально прошли
|
||||||
|
|
||||||
+2
-2
@@ -11,8 +11,8 @@
|
|||||||
- **Проверить в реальной сети:** Arweave gateway / GraphQL фильтрация / root-range доступность и работу с несколькими серверами. Нет фактического Turbo upload и PostgreSQL integration; нельзя считать этап завершённым.
|
- **Проверить в реальной сети:** Arweave gateway / GraphQL фильтрация / root-range доступность и работу с несколькими серверами. Нет фактического Turbo upload и PostgreSQL integration; нельзя считать этап завершённым.
|
||||||
|
|
||||||
## 9 — WS API (подготовка, публичное API не изменено)
|
## 9 — WS API (подготовка, публичное API не изменено)
|
||||||
- Внутренний `FreeRegistrationWorkflow`: реестр namespace, precheck, 15-минутный временный challenge, `1111`, однократно сформированные raw bytes, тот же DataItem при повторе, status lookup.
|
- Внутренний `FreeRegistrationWorkflow`: реестр namespace, precheck, временный challenge и демонстрационное подтверждение email, однократно сформированные raw bytes, тот же DataItem при повторе, status lookup.
|
||||||
- См. `WS_REGISTRATION_V2_PROPOSED_NOT_ENABLED.md`. По правилу `AGENTS.md` точные имена/поля/ErrorCodes требуют отдельного подтверждения. `JsonHandlerRegistry`, сериализация новых публичных запросов и действующая документация `docs/API/` **не изменены**; обычным WS-клиентом пройти free регистрацию пока нельзя.
|
- См. `WS_REGISTRATION_V2_API.md`. По правилу `AGENTS.md` точные имена/поля/ErrorCodes требуют отдельного подтверждения. `JsonHandlerRegistry`, сериализация новых публичных запросов и действующая документация `docs/API/` **не изменены**; обычным WS-клиентом пройти free регистрацию пока нельзя.
|
||||||
|
|
||||||
## 10 — единая авторизация и запреты free (частично)
|
## 10 — единая авторизация и запреты free (частично)
|
||||||
- `RegistrationIdentityDAO.ResolvedIdentity` хранит источник, статус, namespace, root/blockchain/client keys, сервер доступа, `hasSolanaPda` (для FREE_CERT он false).
|
- `RegistrationIdentityDAO.ResolvedIdentity` хранит источник, статус, namespace, root/blockchain/client keys, сервер доступа, `hasSolanaPda` (для FREE_CERT он false).
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
# Архив разработки регистрации v2
|
||||||
|
|
||||||
|
Здесь сохранены первоначальная дорожная карта, журнал этапов, промежуточные отчёты и проверки. Они описывают состояние проекта на даты соответствующих этапов и **не являются инструкциями для текущей реализации**. Действующие документы собраны в [регистрации v2](../../registration-v2/README.md).
|
||||||
|
|
||||||
|
- [Первоначальная дорожная карта](ROADMAP_ORIGINAL_2026-10-23.md)
|
||||||
|
- [Журнал этапов](IMPLEMENTATION_STATUS.md)
|
||||||
|
- Промежуточные отчёты `PATCH_STAGES_*.md`, `SOURCE_BASELINE.md` и `VALIDATION_STAGE_13.md`
|
||||||
|
|
||||||
|
Если старый текст противоречит текущим документам, проверяйте действующий код и обновляйте актуальную спецификацию, а не применяйте старый план как инструкцию.
|
||||||
+4
-4
@@ -16,7 +16,7 @@
|
|||||||
- Обновлять или удалять namespace пока нельзя. Старую классификацию `shine_login_guard` и `promo_seller` исключаем из **новой** регистрации. Автоматическая миграция legacy пользователей не требуется; в других программах удалять лишнее без необходимости не нужно.
|
- Обновлять или удалять namespace пока нельзя. Старую классификацию `shine_login_guard` и `promo_seller` исключаем из **новой** регистрации. Автоматическая миграция legacy пользователей не требуется; в других программах удалять лишнее без необходимости не нужно.
|
||||||
- Economy-PDA остаётся аккаунтом только для чтения во всех новых Solana-транзакциях регистрации и создания namespace, поскольку его история используется как источник транзакций для синхронизации. Цена регистрации берётся из namespace, а параметры лимитов — из economy.
|
- Economy-PDA остаётся аккаунтом только для чтения во всех новых Solana-транзакциях регистрации и создания namespace, поскольку его история используется как источник транзакций для синхронизации. Цена регистрации берётся из namespace, а параметры лимитов — из economy.
|
||||||
- Бесплатный сертификат: бинарные версия, полный логин, root/client/blockchain **публичные** ключи, внутренняя Ed25519-подпись регистратора от этих полей, затем SHA-256 нормализованного email. Внешняя подпись ANS-104 DataItem — тем же ключом, но **это другая подпись от другого сообщения**. Email не включён во внутреннюю подпись. Приватные ключи пользователя нигде не публикуются и серверу не передаются.
|
- Бесплатный сертификат: бинарные версия, полный логин, root/client/blockchain **публичные** ключи, внутренняя Ed25519-подпись регистратора от этих полей, затем SHA-256 нормализованного email. Внешняя подпись ANS-104 DataItem — тем же ключом, но **это другая подпись от другого сообщения**. Email не включён во внутреннюю подпись. Приватные ключи пользователя нигде не публикуются и серверу не передаются.
|
||||||
- Пока email-подтверждение демонстрационное, фиксированный код `1111`; в интерфейсе явно указать «тестовый код, реального подтверждения владения почтой нет». Хеш email в Arweave публичен и может подбираться: это принятое ограничение тестовой схемы.
|
- Пока email-подтверждение демонстрационное, демонстрационный код; в интерфейсе явно указать «тестовый код, реального подтверждения владения почтой нет». Хеш email в Arweave публичен и может подбираться: это принятое ограничение тестовой схемы.
|
||||||
- Временный ключ регистратора (секрет) читается из конфигурации сервера/переменных окружения вне git. Не писать секрет в репозиторий, открытые настройки UI, журнал или лог. В перспективе интерфейс подписания отделяется на аппаратный регистратор.
|
- Временный ключ регистратора (секрет) читается из конфигурации сервера/переменных окружения вне git. Не писать секрет в репозиторий, открытые настройки UI, журнал или лог. В перспективе интерфейс подписания отделяется на аппаратный регистратор.
|
||||||
- Система не реализует в этом патче защиту от компрометации ключа регистратора и отдельный аппаратный журнал. Однако обязательны проверки обычных подписей/полномочий и запрет перезаписи уже зарегистрированного логина.
|
- Система не реализует в этом патче защиту от компрометации ключа регистратора и отдельный аппаратный журнал. Однако обязательны проверки обычных подписей/полномочий и запрет перезаписи уже зарегистрированного логина.
|
||||||
- Бесплатным пользователям запрещены смена root/client/blockchain ключей, смена access-server и форки, меняющие ключи. Обычные операции публикации и работы с контентом остаются.
|
- Бесплатным пользователям запрещены смена root/client/blockchain ключей, смена access-server и форки, меняющие ключи. Обычные операции публикации и работы с контентом остаются.
|
||||||
@@ -126,7 +126,7 @@
|
|||||||
- Реализовать бинарный codec сертификата, строгий парсер, проверку ключа, двух подписей и namespace; внутренний Ed25519 подписывает только версию, полное имя и три публичных ключа. Внешняя ANS-104 подпись — весь DataItem с hash-email.
|
- Реализовать бинарный codec сертификата, строгий парсер, проверку ключа, двух подписей и namespace; внутренний Ed25519 подписывает только версию, полное имя и три публичных ключа. Внешняя ANS-104 подпись — весь DataItem с hash-email.
|
||||||
- Кодирующий модуль должен выдавать **точные сырые байты ANS-104 DataItem** плюс ID (а не просто JSON с полями). Публиковать через текущий Turbo uploader с отдельным тегом типа `free_registration`, не маскируя запись под обычный блок.
|
- Кодирующий модуль должен выдавать **точные сырые байты ANS-104 DataItem** плюс ID (а не просто JSON с полями). Публиковать через текущий Turbo uploader с отдельным тегом типа `free_registration`, не маскируя запись под обычный блок.
|
||||||
- Регистратор проверяет перед подписанием текущие локально синхронизированные логины, хеш email, поддерживаемый namespace и подходящий ключ; повторная выдача для уже зарегистрированного имени отклоняется. Это обычная корректность регистрации, а не разработка новой защиты от кражи ключа.
|
- Регистратор проверяет перед подписанием текущие локально синхронизированные логины, хеш email, поддерживаемый namespace и подходящий ключ; повторная выдача для уже зарегистрированного имени отклоняется. Это обычная корректность регистрации, а не разработка новой защиты от кражи ключа.
|
||||||
- Код `1111` — только временный сценарий тестирования; UI должен прямо сообщать, что письмо не отправляется.
|
- Демонстрационный код — только временный сценарий тестирования; UI должен прямо сообщать, что письмо не отправляется.
|
||||||
|
|
||||||
**Тесты:** корректный DataItem проходит внешний/внутренний verify, изменение даже одного бита отбрасывается, секрет не попадает в логи/JSON, email не входит во внутреннюю подпись, отсутствие сертификата не заменяется «доверяем JSON».
|
**Тесты:** корректный DataItem проходит внешний/внутренний verify, изменение даже одного бита отбрасывается, секрет не попадает в логи/JSON, email не входит во внутреннюю подпись, отсутствие сертификата не заменяется «доверяем JSON».
|
||||||
|
|
||||||
@@ -173,7 +173,7 @@
|
|||||||
- На первом шаге предложить «Регистрация через Solana» и «Бесплатная регистрация»; показывать только namespace соответствующего типа, загруженные из синхронизированного on-chain реестра.
|
- На первом шаге предложить «Регистрация через Solana» и «Бесплатная регистрация»; показывать только namespace соответствующего типа, загруженные из синхронизированного on-chain реестра.
|
||||||
- Поля логин (часть до `@`), namespace (dropdown), итоговое полное имя, цена в SOL, минимальная/максимальная длина, занятость; убрать premium/promo UI.
|
- Поля логин (часть до `@`), namespace (dropdown), итоговое полное имя, цена в SOL, минимальная/максимальная длина, занятость; убрать premium/promo UI.
|
||||||
- Платный сценарий: генерация ключей от **полного логина**, существующая страница оплаты, новая Solana-транзакция, сохранение ключей и авторизация.
|
- Платный сценарий: генерация ключей от **полного логина**, существующая страница оплаты, новая Solana-транзакция, сохранение ключей и авторизация.
|
||||||
- Бесплатный: локальная генерация тех же трёх ключей → email → тестовый код `1111` → запрос серверу на сертификат+Turbo → локальное принятие → автоматический вход; при сетевой ошибке не перегенерировать ключи и не терять черновик.
|
- Бесплатный: локальная генерация тех же трёх ключей → email → демонстрационный код → запрос серверу на сертификат+Turbo → локальное принятие → автоматический вход; при сетевой ошибке не перегенерировать ключи и не терять черновик.
|
||||||
- В аккаунте free отображать статус, отсутствие Solana PDA, закреплённый сервер, блокировку ключей и CTA «Зарегистрировать в Solana». Показать реальные lamports/SOL из namespace.
|
- В аккаунте free отображать статус, отсутствие Solana PDA, закреплённый сервер, блокировку ключей и CTA «Зарегистрировать в Solana». Показать реальные lamports/SOL из namespace.
|
||||||
- Upgrade использует существующие локальные приватные ключи; отправляет сертификат (внутреннюю подпись) и оплачивает тот же логин. После подтверждения меняет только статус и разрешения, не создаёт новые ключи и новый блокчейн.
|
- Upgrade использует существующие локальные приватные ключи; отправляет сертификат (внутреннюю подпись) и оплачивает тот же логин. После подтверждения меняет только статус и разрешения, не создаёт новые ключи и новый блокчейн.
|
||||||
- Удалить все остатки promo code UI, старой проверки premium и guard; обновить FAQ, ошибки, экран входа по полному имени.
|
- Удалить все остатки promo code UI, старой проверки premium и guard; обновить FAQ, ошибки, экран входа по полному имени.
|
||||||
@@ -220,7 +220,7 @@
|
|||||||
- `ArweaveBlockSyncService` сейчас фильтрует записи по `block.height` и импортирует обычные блоки; сертификаты идут другой веткой и локальной немедленной обработкой.
|
- `ArweaveBlockSyncService` сейчас фильтрует записи по `block.height` и импортирует обычные блоки; сертификаты идут другой веткой и локальной немедленной обработкой.
|
||||||
- Текущая Solana-логика create привязывает `created_at_ms` к текущему времени; это обязательно учесть для старых бесплатных блокчейнов на этапе upgrade.
|
- Текущая Solana-логика create привязывает `created_at_ms` к текущему времени; это обязательно учесть для старых бесплатных блокчейнов на этапе upgrade.
|
||||||
- На разных серверах нельзя считать «в какой последовательности я скачал DataItem» окончательным глобальным порядком. Даже если коллизии выдачи исключены организационно, безопасный импорт обязан проверять подписанта, и не должен заменять уже установленную идентичность произвольной повторной записью.
|
- На разных серверах нельзя считать «в какой последовательности я скачал DataItem» окончательным глобальным порядком. Даже если коллизии выдачи исключены организационно, безопасный импорт обязан проверять подписанта, и не должен заменять уже установленную идентичность произвольной повторной записью.
|
||||||
- Заявление «один email на всю SHiNE» при фиксированном коде `1111` означает уникальность **указанной строки email**, но не подтверждает владение почтовым ящиком. При задержке межсерверной синхронизации невозможно гарантировать идеальную моментальную глобальную блокировку без общего авторитетного регистратора; нынешняя схема предусматривает один регистратор.
|
- Заявление «один email на всю SHiNE» в первоначальном плане означает уникальность **указанной строки email**, но не подтверждает владение почтовым ящиком. При задержке межсерверной синхронизации невозможно гарантировать идеальную моментальную глобальную блокировку без общего авторитетного регистратора; нынешняя схема предусматривает один регистратор.
|
||||||
- Экономический PDA в read-only accounts сохраняет **поиск через history/signatures**. Одно лишь чтение не обязано порождать account-change notification; периодический poll/snapshot уже существует, и остаётся.
|
- Экономический PDA в read-only accounts сохраняет **поиск через history/signatures**. Одно лишь чтение не обязано порождать account-change notification; периодический poll/snapshot уже существует, и остаётся.
|
||||||
- Проверка upgrade authority требует корректной работы с account `ProgramData`, а не сравнения с исполняемым Program ID и не обычного owner поля PDA.
|
- Проверка upgrade authority требует корректной работы с account `ProgramData`, а не сравнения с исполняемым Program ID и не обычного owner поля PDA.
|
||||||
|
|
||||||
+1
-1
@@ -12,7 +12,7 @@
|
|||||||
2. Solana `cargo test`, `anchor test`, local validator: IX7 type1/type2, чужая ProgramData/authority, 32B PDA seed, Ed25519 root/blockchain/registrar и точные суммы.
|
2. Solana `cargo test`, `anchor test`, local validator: IX7 type1/type2, чужая ProgramData/authority, 32B PDA seed, Ed25519 root/blockchain/registrar и точные суммы.
|
||||||
3. PostgreSQL: чистая БД с v33/v34 и обновление existing до v34; проверить FK, snapshot и сохраняемые связи/каналы.
|
3. PostgreSQL: чистая БД с v33/v34 и обновление existing до v34; проверить FK, snapshot и сохраняемые связи/каналы.
|
||||||
4. Настроить вне Git registrar 32B seed, Turbo credits, отдельный test namespace type2; API на dev WS.
|
4. Настроить вне Git registrar 32B seed, Turbo credits, отдельный test namespace type2; API на dev WS.
|
||||||
5. В браузере: `alice@shine` paid → профиль, блоки, каналы; `bob@free` → логин → email → `1111` → Turbo → мгновенная сессия.
|
5. В браузере: `alice@shine` paid → профиль, блоки, каналы; `bob@free` → логин → email → код из письма → Turbo → мгновенная сессия.
|
||||||
6. Два сервера: второй находит ту же запись из Arweave, правильный owner, inner signature, отсутствие дубликатов.
|
6. Два сервера: второй находит ту же запись из Arweave, правильный owner, inner signature, отсутствие дубликатов.
|
||||||
7. У Bob создать сообщения и канал, затем Solana upgrade; сравнить login, три ключа, хеш цепи, число блоков, каналы, used bytes, DM, доступ до/после. Если хоть один отличается — release blocked.
|
7. У Bob создать сообщения и канал, затем Solana upgrade; сравнить login, три ключа, хеш цепи, число блоков, каналы, used bytes, DM, доступ до/после. Если хоть один отличается — release blocked.
|
||||||
8. Отрицательные тесты: неверные подписи, повтор email/login, потеря WS ответа, Turbo timeout и restart, попытки free key rotation/access-server.
|
8. Отрицательные тесты: неверные подписи, повтор email/login, потеря WS ответа, Turbo timeout и restart, попытки free key rotation/access-server.
|
||||||
@@ -4,7 +4,7 @@
|
|||||||
|
|
||||||
## Структура раздела
|
## Структура раздела
|
||||||
|
|
||||||
- `01_Common_Block_Format.md` — общий бинарный формат блока (Frame v0), правила подписи и проверки.
|
- `01_Common_Block_Format.md` — текущий Frame v1 внутри подписанного ANS-104 DataItem, правила подписи и проверки.
|
||||||
- `02_Blockchain_Kinds_and_Lines.md` — виды блокчейнов и логические линии внутри цепочки.
|
- `02_Blockchain_Kinds_and_Lines.md` — виды блокчейнов и логические линии внутри цепочки.
|
||||||
- `10_TECH_Blocks.md` — системные блоки (`type=0`).
|
- `10_TECH_Blocks.md` — системные блоки (`type=0`).
|
||||||
- `11_TEXT_Blocks.md` — текстовые блоки (`type=1`).
|
- `11_TEXT_Blocks.md` — текстовые блоки (`type=1`).
|
||||||
|
|||||||
@@ -2,13 +2,20 @@
|
|||||||
|
|
||||||
Актуальная версия пользовательского blockchain использует **SHiNE Frame v1 внутри подписанного ANS-104 DataItem**. Старый Frame v0 и файловое хранение `.bch` не поддерживаются.
|
Актуальная версия пользовательского blockchain использует **SHiNE Frame v1 внутри подписанного ANS-104 DataItem**. Старый Frame v0 и файловое хранение `.bch` не поддерживаются.
|
||||||
|
|
||||||
## Основные документы
|
## Карта раздела
|
||||||
|
|
||||||
- [`01_Common_Block_Format.md`](01_Common_Block_Format.md) — точный Frame v1, ANS-104, подпись, хэши и теги.
|
| Что нужно понять | Документ |
|
||||||
- [`17_TEXT_Channel_Delete.md`](17_TEXT_Channel_Delete.md) — soft-delete канала через `TEXT_CHANNEL_DELETE=92` и правила автоматического оживления.
|
| --- | --- |
|
||||||
- [`17_ANS104_Arweave_Transport.md`](17_ANS104_Arweave_Transport.md) — публикация блоков в Arweave и обратный импорт между серверами.
|
| Frame v1, ANS-104, подписи, хэши, теги | [Общий формат блока](01_Common_Block_Format.md) |
|
||||||
- [`sync-between-servers.md`](sync-between-servers.md) — межсерверная синхронизация и full-resync без файловой копии blockchain.
|
| Виды блоков и логические линии | [Индекс типов](00_Blockchain_Formats_and_Block_Types.md), [линии](02_Blockchain_Kinds_and_Lines.md) |
|
||||||
- [`CHANGELOG.md`](CHANGELOG.md) — история изменений протокола.
|
| TECH, TEXT, реакции, связи, профиль, статусы | [TECH](10_TECH_Blocks.md), [TEXT](11_TEXT_Blocks.md), [REACTION](12_REACTION_Blocks.md), [CONNECTION](13_CONNECTION_Blocks.md), [USER_PROFILE](14_USER_PROFILE_Blocks.md), [STATUS_ACTION](15_STATUS_ACTION_Blocks.md) |
|
||||||
|
| Каналы, метаданные и удаление | [Создание канала](01_Channel_Types_and_CreateChannel.md), [команды](02_Channel_Commands.md), [метаданные](16_TEXT_Channel_Meta.md), [soft-delete](17_TEXT_Channel_Delete.md) |
|
||||||
|
| Вложения в TEXT | [Формат вложений](15_TEXT_Attachments.md) |
|
||||||
|
| Публикация и импорт | [Arweave транспорт](17_ANS104_Arweave_Transport.md), [синхронизация серверов](sync-between-servers.md) |
|
||||||
|
| Ротация и fork | [Ротация ключей](18_KEY_ROTATION_AND_FORK_TARGETS.md), [логические цели](19_STAGE2_LOGICAL_TARGETS_AND_FORK_STORAGE.md) |
|
||||||
|
| История изменений | [CHANGELOG.md](CHANGELOG.md) |
|
||||||
|
|
||||||
|
Файлы с `TODO`, `CODEX_APPLY` и старые отчёты относятся к планам или истории выполнения; для текущего формата начинайте с таблицы выше.
|
||||||
|
|
||||||
## Короткая схема
|
## Короткая схема
|
||||||
|
|
||||||
@@ -46,6 +53,6 @@ Other servers
|
|||||||
|
|
||||||
Новая платформа регистрации `t=reg` использует ANS-104 Ed25519 и независимый payload, **не являющийся пользовательским AddBlock**. Формат определён в [регистрационном протоколе](../Протоколы/SHINE_FREE_REGISTRATION_CERTIFICATE_V1.md). Обычный формат пользовательских блоков не меняется. Новая регистрация отправляет `t=reg` через Turbo и отдельный импортёр, код включён только в тестовом патче; фактический Turbo/GraphQL E2E ещё не пройден.
|
Новая платформа регистрации `t=reg` использует ANS-104 Ed25519 и независимый payload, **не являющийся пользовательским AddBlock**. Формат определён в [регистрационном протоколе](../Протоколы/SHINE_FREE_REGISTRATION_CERTIFICATE_V1.md). Обычный формат пользовательских блоков не меняется. Новая регистрация отправляет `t=reg` через Turbo и отдельный импортёр, код включён только в тестовом патче; фактический Turbo/GraphQL E2E ещё не пройден.
|
||||||
|
|
||||||
- Регистрационные Arweave ANS-104 DataItem `t=reg` (вне пользовательских блокчейнов): `../Протоколы/SHINE_FREE_REGISTRATION_CERTIFICATE_V1.md`, `../registration-v2/PATCH_STAGES_8_9_10.md`.
|
- Регистрационные Arweave ANS-104 DataItem `t=reg` (вне пользовательских блокчейнов): [формат сертификата](../Протоколы/SHINE_FREE_REGISTRATION_CERTIFICATE_V1.md), [регистрация v2](../registration-v2/README.md).
|
||||||
|
|
||||||
- [Единая идентичность логина без учёта регистра](CASE_INSENSITIVE_LOGIN.md) — правила логинов, PDA и социальных ссылок (2026-10-28).
|
- [Единая идентичность логина без учёта регистра](CASE_INSENSITIVE_LOGIN.md) — правила логинов, PDA и социальных ссылок (2026-10-28).
|
||||||
|
|||||||
@@ -0,0 +1,20 @@
|
|||||||
|
# Как поддерживать документацию
|
||||||
|
|
||||||
|
## При каждом изменении
|
||||||
|
|
||||||
|
1. Определите затронутые компоненты по [карте архитектуры](ARCHITECTURE.md) и прочитайте их локальные `AGENTS.md`.
|
||||||
|
2. Если меняются наблюдаемое поведение, операция API, формат данных, конфигурация или способ запуска, обновите профильную документацию в том же наборе изменений. Для DM проверьте также документы о доставке, технических вставках и файлах; для Solana — формат PDA и инструкции инициализации.
|
||||||
|
3. Если изменился состав компонентов или поток данных, обновите `ARCHITECTURE.md`; если появился новый раздел, обновите этот каталог. Публичный README меняйте при изменении возможностей, статуса или способа запуска.
|
||||||
|
4. Запустите `python3 scripts/check_docs.py` из корня репозитория: он проверяет локальные ссылки в документах и соответствие индекса зарегистрированным WS-операциям. Затем проверьте точность команд/путей вручную. Сравните утверждения с конкретными файлами кода или конфигурации. Непроверенное обозначьте как «требует сверки», планы — как «планируется».
|
||||||
|
5. В описании изменения укажите, какие документы обновлены и что проверено. Если документацию менять не требуется, кратко объясните почему.
|
||||||
|
|
||||||
|
Особые связки: изменение формата блоков требует обновления профильного файла в `Blockchain/` и `Blockchain/CHANGELOG.md`; изменение серверных операций — профильного файла в `API/` и индекса операций; изменение синхронизации Solana users — `Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md` и `../deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md`; изменение экранов ESP32 — спецификации устройства и скетча. В журнале блокчейна не требуйте хэш ещё не созданного коммита: фиксируйте дату и суть изменения, а ссылку на коммит добавляйте после его появления, если она нужна.
|
||||||
|
|
||||||
|
## Источники и статусы
|
||||||
|
|
||||||
|
- **Реализовано** — подтверждено кодом; укажите модуль и, если полезно, проверенный сценарий.
|
||||||
|
- **Тестовый контур** — работает только с тестовыми значениями, ключами или namespace; не обещайте production-поведение.
|
||||||
|
- **Планируется** — проектное решение, ещё не являющееся контрактом.
|
||||||
|
- **История/архив** — полезно для контекста, но не для новых интеграций.
|
||||||
|
|
||||||
|
Когда документы противоречат друг другу, сначала проверяйте код и тесты, затем правьте обе стороны противоречия. Точные форматы держите в профильной спецификации; обзорные файлы должны ссылаться на неё, а не копировать таблицы байтов или адреса. Для решений, меняющих протокол или требующих согласия на деплой, действуют ограничения из корневого и локальных `AGENTS.md`.
|
||||||
@@ -4,15 +4,9 @@
|
|||||||
|
|
||||||
- Основной актуальный документ по личным сообщениям:
|
- Основной актуальный документ по личным сообщениям:
|
||||||
- `README.md`
|
- `README.md`
|
||||||
- Его считать единственным источником истины по текущей реализованной логике DM.
|
- Его считать оглавлением действующей документации DM. Точные правила и форматы находятся в перечисленных там профильных документах.
|
||||||
|
|
||||||
## Черновик будущих вложений
|
## Сопровождение
|
||||||
|
|
||||||
- Файл `Черновик_будущих_DM_вложений.md` не является актуальной спецификацией.
|
- При изменении DM обновлять затронутые документы из `README.md` в том же наборе изменений.
|
||||||
- В нём описан только ранний черновик того, как когда-то планировались:
|
- Черновики и устаревшие версии не использовать как действующую спецификацию.
|
||||||
- формат вложений в DM;
|
|
||||||
- внешние и внутренние поля вложения;
|
|
||||||
- предполагаемая механика загрузки файлов.
|
|
||||||
- Эта схема не была реализована в таком виде и может существенно измениться в будущем.
|
|
||||||
- Любые решения по текущему коду, протоколу и UI нельзя принимать по этому черновику.
|
|
||||||
- Если есть расхождение между `README.md` и черновиком вложений, верным всегда считается `README.md`.
|
|
||||||
|
|||||||
@@ -12,13 +12,11 @@
|
|||||||
- `docs/Personal_Messages/Файлы_DM_v2.md` — большие chunked-вложения, голосовые и BitTorrent v2 SHA-256/Merkle metadata
|
- `docs/Personal_Messages/Файлы_DM_v2.md` — большие chunked-вложения, голосовые и BitTorrent v2 SHA-256/Merkle metadata
|
||||||
- `docs/API/18_DM_File_Storage_API.md` — HTTP-хранилище зашифрованных файлов DM на access-сервере отправителя
|
- `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`.
|
||||||
|
|
||||||
- `docs/Personal_Messages/Спецификация_DM_v0.5_устаревшая.md`
|
|
||||||
|
|
||||||
Правило сопровождения:
|
Правило сопровождения:
|
||||||
|
|
||||||
- код DM и оба документа `Протокол_DM_v1.md` + `Формат_DM_v1.md` всегда должны обновляться синхронно;
|
- код DM и затронутые документы из списка выше должны обновляться синхронно; если байтовый контейнер не менялся, это нужно прямо указать в описании изменения;
|
||||||
- если меняется поведение DM в коде, в том же наборе изменений обновляется и эта документация.
|
- если меняется поведение DM в коде, в том же наборе изменений обновляется и эта документация.
|
||||||
- локальная таблица пользователей для DM считается кэшем, а источником истины остаётся Solana PDA; если серверная логика DM меняет правила lazy-import пользователей из PDA, это тоже обязательно фиксируется в документации.
|
- локальная таблица пользователей для DM считается кэшем, а источником истины остаётся Solana PDA; если серверная логика DM меняет правила lazy-import пользователей из PDA, это тоже обязательно фиксируется в документации.
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,23 @@
|
|||||||
|
# Документация SHiNE
|
||||||
|
|
||||||
|
Начните с [общей архитектуры](ARCHITECTURE.md). Этот каталог разделяет действующие спецификации, эксплуатационные инструкции и материалы разработки. Слово «актуальный» в старом документе само по себе не подтверждает соответствие коду: при изменении контракта сверяйте реализацию.
|
||||||
|
|
||||||
|
| Тема | Точка входа | Назначение |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| Серверный API | [API сервера](API/README.md) | Операции и форматы запросов |
|
||||||
|
| Пользовательский блокчейн | [Blockchain](Blockchain/README.md) | Frame, ANS-104, типы блоков, Arweave |
|
||||||
|
| Личные сообщения | [Personal Messages](Personal_Messages/README.md) | Протокол, бинарный формат, доставка и файлы |
|
||||||
|
| Solana | [архитектура программ](Solana_Architecture/README.md) | PDA, роли, программы и денежные потоки |
|
||||||
|
| Регистрация Solana | [инициализация](Инициализация_Solana_регистрации/README.md) | Адреса и порядок настройки |
|
||||||
|
| Регистрация v2 | [карта регистрации](registration-v2/README.md) | Действующие операции, email и сертификат |
|
||||||
|
| Ключи | [Keys](Keys/README.md) | Назначение и получение ключей |
|
||||||
|
| UI | [UI Design](UI-Design/README.md) | Дизайн и состояние реализации |
|
||||||
|
| Деплой | [deploy/README.md](../deploy/README.md) | Контуры, конфигурация и скрипты |
|
||||||
|
|
||||||
|
## Как искать
|
||||||
|
|
||||||
|
Для изменения кода начните с точки входа в таблице, затем откройте профильный документ и соответствующий код. Точные форматы находятся в профильных спецификациях; общая [архитектура](ARCHITECTURE.md) показывает связи между ними.
|
||||||
|
|
||||||
|
[Архив](Archive/registration-v2/README.md), `Черновики/`, `закомментировано/`, старые аудиты и материалы с пометками `legacy` или `v0` сохраняют историю и идеи. Они не задают текущий контракт. Вложенные каталоги с кодом также содержат локальные README и `AGENTS.md`; карта входа для агентов находится в [корневом AGENTS.md](../AGENTS.md).
|
||||||
|
|
||||||
|
Как поддерживать этот каталог и профильные документы: [CONTRIBUTING_DOCS.md](CONTRIBUTING_DOCS.md).
|
||||||
@@ -1,23 +1,24 @@
|
|||||||
# Архитектура Solana-программ SHiNE
|
# Архитектура Solana-программ SHiNE
|
||||||
|
|
||||||
Документ описывает рабочую архитектуру Solana-части SHiNE: три Anchor-программы, DAO, ключи управления, PDA-счета и движение денег.
|
Документ описывает архитектуру трёх Solana-программ SHiNE, DAO, ключи управления, PDA-счета и движение денег. Текущие `shine_users` и `shine_payments` имеют собственный обработчик инструкций на Rust; не следует считать все три программы Anchor-программами.
|
||||||
|
|
||||||
Это архитектурная справка. Она не меняет код, формат PDA-записи пользователя, серверный API или формат блокчейна SHiNE.
|
Это архитектурная справка. Она не меняет код, формат PDA-записи пользователя, серверный API или формат блокчейна SHiNE.
|
||||||
|
|
||||||
Статус: актуализировано по коду `shine-solana/shine/programs/*` на 2026-05-25.
|
Статус: обзорная справка. Состав инструкций `shine_users`, program ID и seed сверен с кодом; экономические сценарии и фактическое состояние развёрнутых программ требуют отдельной проверки в сети.
|
||||||
|
|
||||||
Связанные документы:
|
Связанные документы:
|
||||||
|
|
||||||
- `docs/Инициализация_Solana_регистрации/README.md` — single source of truth по деплою и первичной инициализации регистрации пользователей.
|
- `docs/Инициализация_Solana_регистрации/README.md` — single source of truth по деплою и первичной инициализации регистрации пользователей.
|
||||||
- `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md` — точный формат `user_pda` для `shine_users`.
|
- `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.2.md` — текущий формат `user_pda` для `shine_users`; версия v1.0 сохранена как историческая.
|
||||||
- `shine-solana/shine/doc/FUNDS_FLOW.md` — короткая справка по денежным потокам внутри Solana-модуля.
|
- `shine-solana/shine/doc/formats/shine-namespace-pda-format-v1.md` — формат namespace PDA.
|
||||||
|
- `shine-solana/shine/doc/FUNDS_FLOW.md` — справка по денежным потокам внутри Solana-модуля.
|
||||||
|
|
||||||
## Кратко
|
## Кратко
|
||||||
|
|
||||||
В Solana-модуле сейчас три основные программы:
|
В Solana-модуле сейчас три основные программы:
|
||||||
|
|
||||||
1. `shine_login_guard` — в текущем временном режиме проверяет базовую валидность логина и пропускает on-chain любые валидные логины длиной от 5 символов.
|
1. `shine_login_guard` — в текущем временном режиме проверяет базовую валидность логина и пропускает on-chain любые валидные логины длиной от 5 символов.
|
||||||
2. `shine_users` — создает и обновляет пользовательскую PDA-запись, проверяет подписи и берет оплату за регистрацию/увеличение лимита.
|
2. `shine_users` — создаёт namespace и пользовательские PDA, проверяет подписи и обрабатывает оплату регистрации/увеличения лимита. В коде есть платный путь через Solana и upgrade бесплатного сертификата.
|
||||||
3. `shine_payments` — принимает входящий поток средств в `inflow_vault`, ведет очереди тикетов, позволяет DAO выдавать лимиты менеджерам и выполняет выплаты.
|
3. `shine_payments` — принимает входящий поток средств в `inflow_vault`, ведет очереди тикетов, позволяет DAO выдавать лимиты менеджерам и выполняет выплаты.
|
||||||
|
|
||||||
DAO в текущем виде не является отдельной Anchor-программой SHiNE внутри `programs/`. Это управляющая модель поверх кошельков, governance-скриптов и authority-адресов. Для проектирования ее удобно считать отдельным управляющим блоком: DAO голосует, назначает управляющие ключи, управляет казной и вызывает защищенные методы второй и третьей программ.
|
DAO в текущем виде не является отдельной Anchor-программой SHiNE внутри `programs/`. Это управляющая модель поверх кошельков, governance-скриптов и authority-адресов. Для проектирования ее удобно считать отдельным управляющим блоком: DAO голосует, назначает управляющие ключи, управляет казной и вызывает защищенные методы второй и третьей программ.
|
||||||
@@ -36,13 +37,13 @@ DAO в текущем виде не является отдельной Anchor-
|
|||||||
| Блок | Папка/имя | Текущие функции из кода | Основной смысл |
|
| Блок | Папка/имя | Текущие функции из кода | Основной смысл |
|
||||||
| --- | --- | --- | --- |
|
| --- | --- | --- | --- |
|
||||||
| 1 | `shine_login_guard` | `classify_login` | Временная on-chain проверка логина перед регистрацией. |
|
| 1 | `shine_login_guard` | `classify_login` | Временная on-chain проверка логина перед регистрацией. |
|
||||||
| 2 | `shine_users` | `init_users_economy_config`, `update_users_economy_config`, `create_user_pda`, `update_user_pda` | Регистрация пользователя, обновление записи, экономика лимита. |
|
| 2 | `shine_users` | `init_users_economy_config`, `update_users_economy_config`, `create_namespace`, `create_user_pda`, `update_user_pda`, `close_legacy_user_pda` | Namespace, регистрация, обновление записи и экономика лимита. |
|
||||||
| 3 | `shine_payments` | `init`, `update_coef_limit`, `grant_manager_limits`, `buy_ticket`, `buy_ticket_usd`, `buy_ticket_sol`, `manager_add_ticket`, `step_payout`, `change_ticket_recipient` | Vault, билеты, очереди, выплаты, DAO-настройки, лимиты менеджеров. |
|
| 3 | `shine_payments` | `init`, `update_coef_limit`, `grant_manager_limits`, `buy_ticket`, `buy_ticket_usd`, `buy_ticket_sol`, `manager_add_ticket`, `step_payout`, `change_ticket_recipient` | Vault, билеты, очереди, выплаты, DAO-настройки, лимиты менеджеров. |
|
||||||
| DAO | governance/authority | Вызовы через governance и управляющие ключи | Управление правами, казной, настройками и будущими обновлениями программ. |
|
| DAO | governance/authority | Вызовы через governance и управляющие ключи | Управление правами, казной, настройками и будущими обновлениями программ. |
|
||||||
|
|
||||||
## Актуальные program id
|
## Актуальные program id
|
||||||
|
|
||||||
Актуальные адреса заданы одновременно в `Anchor.toml`, `declare_id!` программ и `programs/common/src/deploy_config.rs`:
|
Program ID в этом checkout заданы в `Anchor.toml` и `declare_id!` программ. Дополнительные константы и адреса в UI/сервере проверяйте по инструкции инициализации:
|
||||||
|
|
||||||
| Программа | Program ID |
|
| Программа | Program ID |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
@@ -54,8 +55,7 @@ DAO в текущем виде не является отдельной Anchor-
|
|||||||
|
|
||||||
1. `shine-solana/shine/Anchor.toml`
|
1. `shine-solana/shine/Anchor.toml`
|
||||||
2. `declare_id!` в `programs/*/src/lib.rs`
|
2. `declare_id!` в `programs/*/src/lib.rs`
|
||||||
3. `programs/common/src/deploy_config.rs`
|
3. константы и настройки UI/сервера, перечисленные в `docs/Инициализация_Solana_регистрации/README.md`
|
||||||
4. UI/серверные константы, перечисленные в `docs/Инициализация_Solana_регистрации/README.md`
|
|
||||||
|
|
||||||
## Ключи и authority
|
## Ключи и authority
|
||||||
|
|
||||||
@@ -81,14 +81,15 @@ DAO в текущем виде не является отдельной Anchor-
|
|||||||
- DAO может добавлять и отзывать управляющие ключи по голосованию.
|
- DAO может добавлять и отзывать управляющие ключи по голосованию.
|
||||||
- DAO-казна получает деньги от покупки тикетов и DAO-часть выплат из `inflow_vault`.
|
- DAO-казна получает деньги от покупки тикетов и DAO-часть выплат из `inflow_vault`.
|
||||||
|
|
||||||
Адреса program id сейчас берутся из `programs/common/src/deploy_config.rs`. Для production/devnet можно подбирать vanity-адреса с понятным началом вроде `SHi...`, но это отдельная операция генерации ключей и деплоя.
|
Для отдельных программ зависимости от ID других программ задаются в их исходниках и настройках; например ID `shine_payments` указан в `programs/shine_users/src/settings.rs`. Перед сменой адреса нужно искать все ссылки в коде и конфигурации.
|
||||||
|
|
||||||
## Счета и PDA
|
## Счета и PDA
|
||||||
|
|
||||||
Постоянные PDA и счета:
|
Постоянные PDA и счета:
|
||||||
|
|
||||||
1. `shine_users`
|
1. `shine_users`
|
||||||
- `user_pda` — пользовательская запись по seed `login=<login>`, создается для каждого логина.
|
- `user_pda` — пользовательская запись по хэшу от `user_login=<login>`; точный seed определён в `programs/shine_users/src/settings.rs` и `user_pda_seed()`.
|
||||||
|
- `namespace_pda` — запись namespace по хэшу от `namespace=<name>`.
|
||||||
- `users_economy_config_pda` — общие параметры экономики регистрации и лимита.
|
- `users_economy_config_pda` — общие параметры экономики регистрации и лимита.
|
||||||
|
|
||||||
2. `shine_payments`
|
2. `shine_payments`
|
||||||
|
|||||||
@@ -20,9 +20,9 @@
|
|||||||
6. `manager_wallet` — кошелек менеджера, которому DAO выдает лимиты на создание тикетов.
|
6. `manager_wallet` — кошелек менеджера, которому DAO выдает лимиты на создание тикетов.
|
||||||
7. `user root_key` — корневой ключ пользователя для подписи пользовательской записи.
|
7. `user root_key` — корневой ключ пользователя для подписи пользовательской записи.
|
||||||
8. `user client_key` — ключ устройства пользователя.
|
8. `user client_key` — ключ устройства пользователя.
|
||||||
9. `server_key` — ключ сервера пользователя, если пользователь является сервером.
|
9. Серверный профиль пользователя публикует endpoint в `user_pda`; отдельной постоянной роли `server_key` в формате PDA 1.2 нет.
|
||||||
|
|
||||||
Текущие адреса из `programs/common/src/deploy_config.rs`:
|
Program ID сверяйте с `Anchor.toml` и `declare_id!` в исходниках программ; значения ниже приведены для ориентира. Для конфигурации деплоя используйте [инструкцию инициализации](../../Инициализация_Solana_регистрации/README.md):
|
||||||
|
|
||||||
| Роль | Адрес |
|
| Роль | Адрес |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
@@ -36,7 +36,8 @@
|
|||||||
|
|
||||||
`shine_users`:
|
`shine_users`:
|
||||||
|
|
||||||
- `user_pda` — создается для каждого логина, seed `login=` + normalized login.
|
- `user_pda` — создаётся для каждого логина, seed вычисляется как SHA-256 строки `user_login=` + нормализованный логин.
|
||||||
|
- `namespace_pda` — запись namespace, seed вычисляется как SHA-256 строки `namespace=` + имя namespace.
|
||||||
- `users_economy_config_pda` — один PDA с экономикой регистрации, seed `shine_users_economy_config`.
|
- `users_economy_config_pda` — один PDA с экономикой регистрации, seed `shine_users_economy_config`.
|
||||||
|
|
||||||
`shine_payments`:
|
`shine_payments`:
|
||||||
|
|||||||
@@ -1,11 +1,11 @@
|
|||||||
# Дизайн SHiNE
|
# Дизайн SHiNE
|
||||||
|
|
||||||
Статус: направление выбрано, спецификация 0.2 от 22.09.2026. Основа — Ночной SHiNE; дневная тема — тёплая палитра; компактная шапка канала; полноэкранный ответ. У лайков только общий счётчик, оглавление в меню.
|
Статус: исторический дизайн-макет и спецификация 0.2 от 22.09.2026; соответствие текущему `shine-UI/` не проверено. Основа — Ночной SHiNE; дневная тема — тёплая палитра; компактная шапка канала; полноэкранный ответ. У лайков только общий счётчик, оглавление в меню.
|
||||||
|
|
||||||
- [Общий дизайн-документ](DESIGN.md) — актуальная спецификация выбранного стиля, обе темы, общие компоненты, сценарии и критерии приёмки.
|
- [Общий дизайн-документ](DESIGN.md) — актуальная спецификация выбранного стиля, обе темы, общие компоненты, сценарии и критерии приёмки.
|
||||||
- [Открыть исходную HTML-галерею](channels-v1/index.html) — четыре варианта, четыре экрана в каждом; история выбора.
|
- [Открыть исходную HTML-галерею](channels-v1/index.html) — четыре варианта, четыре экрана в каждом; история выбора.
|
||||||
|
|
||||||
Галерея сохранена без изменений и ещё не отражает итоговое сочетание решений. Для последующего переноса источником истины служит `DESIGN.md`, а не детали одного старого варианта. Код приложения не менялся.
|
Галерея сохранена без изменений и ещё не отражает итоговое сочетание решений. Для последующего переноса источником истины служит `DESIGN.md`, а не детали одного старого варианта. Эта галерея не является описанием текущего кода приложения.
|
||||||
|
|
||||||
## Как посмотреть
|
## Как посмотреть
|
||||||
|
|
||||||
|
|||||||
@@ -1,720 +0,0 @@
|
|||||||
# SHiNE — МАСТЕР-ПЛАН РЕАЛИЗАЦИИ РЕГИСТРАЦИИ V2
|
|
||||||
|
|
||||||
**Дата:** 23 октября 2026 года
|
|
||||||
**Тип:** автономное техническое задание и инструкция для нового чата / Codex
|
|
||||||
**Базовый архив:** `SHiNE-bundle-2026.10.22-12.53.20(1).zip`
|
|
||||||
**Связанный предыдущий план:** `SHiNE_registration_roadmap_2026-10-23.md`
|
|
||||||
**Статус:** проектирование; изменения в исходный код этим документом НЕ внесены.
|
|
||||||
**Принцип:** один этап = один контролируемый патч. Не реализовывать весь документ за одну генерацию.
|
|
||||||
|
|
||||||
> **ВАЖНО ДЛЯ СЛЕДУЮЩЕГО ИСПОЛНИТЕЛЯ.** Не воспринимай этот документ как свидетельство, что код уже изменён. Сперва открой архив / рабочий репозиторий, прочитай локальные AGENTS.md, проверь текущую ветку и выполни только тот этап, который явно поручен. Все пути ниже сверены с архивом от 22.10.2026; в другой версии они могут отличаться. Если обнаружишь техническую неточность плана, исправь её обоснованно, сохранив согласованные продуктовые правила. Не менять API и формат существующего пользовательского блокчейна без предусмотренного проектом согласования.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## КАК ПЕРЕДАТЬ В НОВЫЙ ЧАТ (важнее всего)
|
|
||||||
|
|
||||||
Передать **оба вложения**:
|
|
||||||
1. Полный исходный архив проекта `SHiNE-bundle-2026.10.22-12.53.20(1).zip` либо актуальную версию репозитория.
|
|
||||||
2. **Этот файл мастер-плана V2**, а также последний журнал завершённых этапов, если работа уже начата.
|
|
||||||
|
|
||||||
В новом чате дать инструкцию:
|
|
||||||
|
|
||||||
> «Это проект SHiNE. Прочитай `SHiNE_registration_implementation_masterplan_v2_2026-10-23.md`, затем AGENTS.md в корне и в изменяемых модулях. Сначала сверь план с реальным исходным кодом. Выполни **только этап № N**, включая тесты, актуализацию обязательной документации и отчёт по шаблону из конца плана. Не придумывай другую схему регистрации. Не трогай production, не меняй публичный API/формат старого блокчейна без отдельного разрешения. После выполнения остановись».
|
|
||||||
|
|
||||||
Если кодовая база изменилась после архива, **источником истины для расположения кода является актуальный репозиторий**, а этот документ — источник согласованных требований и порядка действий.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# А. ПРОДУКТОВОЕ ТЗ: ЧТО ДОЛЖНО ПОЛУЧИТЬСЯ
|
|
||||||
|
|
||||||
## А1. Три допустимых состояния одного аккаунта
|
|
||||||
|
|
||||||
| Состояние | Кто удостоверяет имя | Пользовательский PDA Solana | Сервер доступа | Смена ключей |
|
|
||||||
|---|---|---|---|---|
|
|
||||||
| `PAID_DIRECT` | `shine_users` | есть | определяется своим PDA | разрешена по правилам PDA |
|
|
||||||
| `FREE_CERT` | сертификат регистратора в Arweave | нет | общий сервер из namespace-PDA | запрещена |
|
|
||||||
| `PAID_UPGRADED` | `shine_users` + ранее выданный сертификат | есть | определяется своим PDA | разрешена по правилам PDA |
|
|
||||||
|
|
||||||
`FREE_CERT → PAID_UPGRADED` **не создаёт нового пользователя**: полное имя `login@namespace`, root/client/blockchain публичные и приватные ключи, старые публикации, каналы и история блокчейна остаются прежними. Приватные ключи доступны только пользователю и не попадают на сервер.
|
|
||||||
|
|
||||||
**Уточнение по времени:** дата создания Solana PDA при upgrade может быть новой датой on-chain регистрации; дата первоначальной бесплатной регистрации и история Arweave остаются отдельно. Нельзя выдавать новую on-chain дату за дату создания исходного аккаунта или обнулять историю/расход лимитов.
|
|
||||||
|
|
||||||
## А2. Полные логины и пространства имён
|
|
||||||
|
|
||||||
- Каждый пользователь имеет имя `login@namespace` (пример: `alice@shine`, `bob@free`).
|
|
||||||
- Namespace — реально существующий аккаунт PDA программы `shine_users`, а не hardcoded список в UI.
|
|
||||||
- Тип `1`: прямая платная регистрация в Solana.
|
|
||||||
- Тип `2`: первоначальная бесплатная регистрация с сертификатом регистратора; позднее возможна платная регистрация PDA.
|
|
||||||
- Оба namespace имеют стоимость создания пользовательского PDA. Цена в типе `2` списывается **в момент перехода на Solana**.
|
|
||||||
- У каждого namespace есть нижняя граница длины части `login`; общая максимальная длина `login@namespace` на этом этапе — 30 байт при ASCII-алфавите.
|
|
||||||
- Не продавать отдельные короткие логины, не вводить premium-классы.
|
|
||||||
- Пространства создаются действующей **upgrade authority Solana-программы `shine_users`**, а не отдельной константой DAO. В будущем upgrade authority сможет принадлежать DAO.
|
|
||||||
- Пока разрешено **создавать**, но не редактировать или удалять namespace.
|
|
||||||
|
|
||||||
## А3. Ключи и пароль
|
|
||||||
|
|
||||||
- Клиент получает root key, blockchain key, client key из своего существующего механизма восстановления по **полному нормализованному логину и паролю**; не придумывать новый KDF.
|
|
||||||
- При регистрации бесплатного пользователя сервер видит **только три публичных ключа**.
|
|
||||||
- Приватный ключ **регистратора** — совершенно другой ключ. Пока находится в защищённой конфигурации сервера (вне Git); в будущем замещается аппаратным регистратором.
|
|
||||||
- Публичный ключ регистратора записывается в PDA бесплатного namespace.
|
|
||||||
- Нельзя связывать бесплатную регистрацию с хранением пароля или приватных ключей пользователя на сервере.
|
|
||||||
|
|
||||||
## А4. Сертификат и две подписи
|
|
||||||
|
|
||||||
Последовательность данных внутри подписанного ANS-104 DataItem:
|
|
||||||
|
|
||||||
1. Версия сертификата.
|
|
||||||
2. Полный `login@namespace`.
|
|
||||||
3. Три публичных ключа (порядок однозначно зафиксировать в протоколе; предлагается `root`, `blockchain`, `client`).
|
|
||||||
4. **Внутренняя Ed25519-подпись регистратора** только от полей идентичности — версии, полного имени и трёх публичных ключей (плюс протокольный domain separator).
|
|
||||||
5. SHA-256 от нормализованного email — **после внутренней подписи**, не входит в её сообщение.
|
|
||||||
6. Весь ANS-104 DataItem, включая поле хеша email и теги, подписывается **внешней подписью ANS-104 тем же ключом регистратора**.
|
|
||||||
|
|
||||||
Внутренняя подпись нужна для последующей проверки в Solana, внешняя — для удостоверения полного DataItem при его импорте. Это **две разные подписи от разных последовательностей байтов**.
|
|
||||||
|
|
||||||
Теги DataItem следует отделять от обычных пользовательских блоков, например существующим `App=test5592` плюс отдельный тег типа `t=reg`; точный набор тегов утвердить в документе протокола, не смешивать с `t=prof|conn|tech`.
|
|
||||||
|
|
||||||
## А5. Email
|
|
||||||
|
|
||||||
- При free-регистрации пользователь вводит email.
|
|
||||||
- Пока **проверка учебная**, реальная почта не отправляется; правильный код `1111` и это явно сказано в UI.
|
|
||||||
- В Arweave публикуется **только `SHA256(normalized_email)`**; исходный email не публикуется и не передаётся в Solana.
|
|
||||||
- Один нормализованный email-хеш должен соответствовать максимум одной бесплатной регистрации в известном реестре SHiNE.
|
|
||||||
- Пользователь понимает принятое ограничение: простой SHA-256 допускает проверку догадок об email; это не обещание полной анонимности.
|
|
||||||
- Пока единственный доверенный регистратор; не реализовывать сложную распределённую выдачу/резервирование и защиту от кражи ключа.
|
|
||||||
- Важная честная оговорка: `1111` доказывает только ввод фиксированного кода, **не подтверждает владение email**. Глобальная уникальность зависит от полноты синхронизации и единственного регистратора; не объявлять это криптографически абсолютной гарантией.
|
|
||||||
|
|
||||||
## А6. Источники идентичности и приоритет
|
|
||||||
|
|
||||||
- Для платных пользователей источником полномочий служит настоящий Solana PDA.
|
|
||||||
- Для бесплатных — проверенный сертификат Arweave, связанный с PDA бесплатного namespace.
|
|
||||||
- После upgrade статус меняется **у существующей логической личности**; Arweave-сертификат сохраняется как историческое основание исходной выдачи имени.
|
|
||||||
- При импорте сертификата всегда проверяется полномочие подписавшего ключа; сам факт хранения в Arweave не делает запись доверенной.
|
|
||||||
- Если запись уже принята, произвольная другая запись того же логина **не должна её заменять**. Дополнительную модель кражи ключа пока не строить.
|
|
||||||
|
|
||||||
## А7. Сервер доступа и ограничения free
|
|
||||||
|
|
||||||
- До Solana upgrade сервер доступа всех аккаунтов бесплатного namespace задаёт его namespace-PDA.
|
|
||||||
- Для платного пользователя сервер доступа берётся из собственного PDA v1.2.
|
|
||||||
- `FREE_CERT` не может менять root, blockchain и client keys; не может менять сервер доступа; не может запускать fork/key rotation, если это меняет ключи.
|
|
||||||
- Ограничение действует не только в UI, но и в серверных проверках; обязательно найти альтернативные пути соответствующих операций.
|
|
||||||
- Публикации, каналы, связи, личные сообщения и чтение истории должны работать обычным образом.
|
|
||||||
- После upgrade смена ключей/сервера работает по существующим правилам Solana.
|
|
||||||
|
|
||||||
## А8. Экономика и управление
|
|
||||||
|
|
||||||
- `init_users_economy_config` остаётся доступной любому подписанту; она инициализирует детерминированные исходные параметры только один раз.
|
|
||||||
- `update_users_economy_config` вместо постоянной `DAO_AUTHORITY` проверяет **действующую upgrade authority через ProgramData**.
|
|
||||||
- Стоимость **регистрации** — из соответствующего namespace-PDA; стоимость покупки дополнительных лимитов и иные параметры остаются в economy-PDA.
|
|
||||||
- При `create_namespace` и каждой новой регистрации economy-PDA присутствует в account metas как read-only для текущего механизма history/poll синхронизации.
|
|
||||||
- Чтение economy-PDA не обязано генерировать WebSocket account-change notification; для истории продолжает работать `getSignaturesForAddress`/периодический poll.
|
|
||||||
- Удалить использование promo_seller и shine_login_guard из **новой пользовательской регистрации**, связанные инструкционные ветки `shine_users`, клиентские поля промокодов и premium-проверки. Отдельные legacy-программы без необходимости не удалять.
|
|
||||||
|
|
||||||
## А9. Мгновенный вход после Turbo
|
|
||||||
|
|
||||||
`код 1111 → выпуск подписанного DataItem → успешный ACK Turbo → импорт тех же raw signed bytes локально → пользователь получает доступ`.
|
|
||||||
|
|
||||||
- **Не ждать** высоты блока Arweave для первого входа.
|
|
||||||
- Другие серверы обнаружат запись позже через Arweave, и это нормально.
|
|
||||||
- Локально различать `TURBO_ACCEPTED` и `ARWEAVE_CONFIRMED`; не путать приём Turbo с окончательным подтверждением сети.
|
|
||||||
- При сетевой ошибке или неизвестном результате публикации не терять пользовательские ключи, не создавать бессмысленно новый сертификат и новый DataItem при каждом повторе.
|
|
||||||
|
|
||||||
## А10. Не входит в этот релиз
|
|
||||||
|
|
||||||
Нет реального SMTP, восстановления ключей через email, изменения/удаления namespace, аппаратного регистратора, мультиподписей регистраторов, обработки компрометации его ключа, управления DAO, продажи премиальных имён, автоматической миграции старых Solana PDA/логинов, масштабного редизайна остальных экранов.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Б. КАРТА РЕАЛЬНОГО ИСХОДНОГО КОДА (архив 22.10.2026)
|
|
||||||
|
|
||||||
Эти файлы **существуют** в проверенном архиве. Для новых классов ниже будет явно сказано «создать».
|
|
||||||
|
|
||||||
| Компонент | Существующие точки входа | Что там сейчас / зачем менять |
|
|
||||||
|---|---|---|
|
|
||||||
| Solana | `shine-solana/shine/programs/shine_users/src/lib.rs` | instruction dispatcher, `create_user_pda`, `update_user_pda`, Ed25519 precompile, экономика, promo и guard |
|
|
||||||
| Настройки Solana | `shine-solana/shine/programs/shine_users/src/settings.rs` | `USER_PDA_SEED_PREFIX="user_login="`, старые константы `DAO_AUTHORITY`, guard, promo |
|
|
||||||
| Документ Solana | `shine-solana/shine/doc/programs/shine_users.md` | контракт, аккаунты, инструкции |
|
|
||||||
| Документ PDA v1.2 | `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.2.md` | существующий формат полноценного PDA; сохранять |
|
|
||||||
| Solana UI codec | `shine-UI/js/services/shine-user-pda-service.js` | seed, сериализация, транзакции регистрации, promo |
|
|
||||||
| Solana UI facade | `shine-UI/js/services/solana-register-service.js` | guard/premium precheck, доступность имени, вызов общего сервиса |
|
|
||||||
| Адреса программ | `shine-UI/js/solana-programs.js` | реальные program id считывать из актуального окружения |
|
|
||||||
| Получение ключей | `shine-UI/js/services/auth-service.js` | `derivePasswordKeyBundle(login,password)`; полный login входит в Argon2id/KDF |
|
|
||||||
| Регистрация UI | `shine-UI/js/pages/register-view.js`, `registration-payment-view.js`, `registration-draft-keys-view.js` | старая платная форма, лимиты длины и promo UI |
|
|
||||||
| Логин / настройки | `shine-UI/js/pages/login-view.js`, `login-password-view.js`, `settings-view.js`, `key-rotation-view.js` | вход и функции ключей |
|
|
||||||
| UI router/state | `shine-UI/js/router.js`, `shine-UI/js/state.js` | новые страницы и черновики регистрации |
|
|
||||||
| Solana sync | `SHiNE-server/shine-server-solana-users-sync/src/main/java/sync/service/SolanaUsersSyncService.java` | историю отслеживает по economy-PDA; snapshot и checkpoint |
|
|
||||||
| Solana parser | `.../sync/codec/ShineUsersCodec.java` | декодирование инструкций и записей |
|
|
||||||
| Solana PDA utility | `.../sync/util/SolanaPdaUtil.java` | вычисляет findProgramAddress на Java |
|
|
||||||
| Solana sync DB | `.../sync/storage/postgres/PostgresStorageRepository.java` | upsert/account snapshot; нужны namespaces и новые статусы |
|
|
||||||
| База | `SHiNE-server/shine-server-db/src/main/resources/postgres/schema_v1.sql` и `migration_v31.sql`, `migration_v32.sql` | baseline и текущие миграции; следующая — новая по порядку, НЕ переписывать прошлые |
|
|
||||||
| DB login facade | `SHiNE-server/shine-server-db/src/main/java/shine/db/sql/CurrentUsersSql.java` | сейчас возвращает пользователей только из `solana_user_pda_current` |
|
|
||||||
| DB DAO | `.../shine/db/dao/CurrentUsersDAO.java`, `SolanaUserPdaCurrentDAO.java`, `UserAccessServersCurrentDAO.java` | проверки пользователей, ключей, сервера |
|
|
||||||
| Авторизация | `SHiNE-server/shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/handlers/auth/` | `SolanaUserPdaImportService`, `Net_ResolveLoginForAuth_Handler`, `Net_CreateAuthSession__Handler` и связанные классы |
|
|
||||||
| Ротация | `.../handlers/keyRotation/`, `KeyRotationSessionsDAO.java` | запреты для `FREE_CERT` |
|
|
||||||
| Config | `SHiNE-server/shine-server-config/src/main/java/utils/config/AppConfig.java` | встраивание параметров регистратора без Git-секрета |
|
|
||||||
| ANS-104 | `SHiNE-server/shine-server-blockchain/src/main/java/blockchain/Ans104DataItem.java` | сериализация, deep-hash, Ed25519 signature verify |
|
|
||||||
| Turbo | `SHiNE-server/shine-server-archive/src/main/java/server/archive/TurboDataItemUploader.java` | принимает **уже подписанный** DataItem, проверяет и отправляет |
|
|
||||||
| Arweave import | `SHiNE-server/shine-server-archive/src/main/java/server/archive/ArweaveBlockSyncService.java` | GraphQL discovery, блоки, фильтр `block.height`; нужен отдельный путь регистрации |
|
|
||||||
| API dispatch | `SHiNE-server/shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/JsonHandlerRegistry.java` | подключение новых WS операций |
|
|
||||||
| Документация API | `docs/API/01_User_Registration_API.md`, `docs/API/09_Operations_Index.md` | новые операции и ошибки: согласовать изменения |
|
|
||||||
| Документация sync | `docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md`, `deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md` | алгоритм и эксплуатация sync |
|
|
||||||
| Деплой | `deploy/AGENTS.md`, `deploy/TEST_SERVERS.md`, `docs/Инициализация_Solana_регистрации/README.md` | тестовый контур и порядок инициализации |
|
|
||||||
|
|
||||||
**Подтверждённые особенности кода:**
|
|
||||||
- В `shine_users` opcode 1 = init economy, 2 = update economy, 3 = create user, 4 = update user, 5 = upsert promo seller, 6 = close legacy. Новым инструкциям назначать непересекающиеся id, зафиксировать их в документации.
|
|
||||||
- Текущее `create_user_pda` подтверждает root и blockchain через Ed25519 instructions sysvar (разбор относительно текущей инструкции). Дополнительная подпись регистратора потребует тщательно задать расположение этих инструкций.
|
|
||||||
- Пользовательский PDA v1.2 содержит root, client, forks blockchain key, access servers, а не простую запись «три ключа + имя».
|
|
||||||
- `solana_user_pda_current` сейчас является центральной таблицей и целью внешних ключей; **нельзя** подделывать наличие on-chain PDA для free.
|
|
||||||
- В `CurrentUsersSql.usersSubquery` список сейчас берётся только из `solana_user_pda_current`.
|
|
||||||
- `TurboDataItemUploader.upload` не подписывает DataItem за клиента: raw signed DataItem нужно сформировать до вызова.
|
|
||||||
- В `ArweaveBlockSyncService` текущая основная выборка пропускает GraphQL-записи без `block.height`; free-registration требует отдельной ветки и немедленного локального пути.
|
|
||||||
- В `register-view.js` есть временная логика нормализации `<=20` и пропуск `_` для guard. Для новой системы `_` не удалять из идентичности: `a_b` и `ab` не должны внезапно стать одним именем.
|
|
||||||
|
|
||||||
**Читать перед началом:** корневой `AGENTS.md`, `COMMIT_AND_VERSION_RULES.md` и локальные `shine-solana/shine/AGENTS.md`, `SHiNE-server/AGENTS.md`, `shine-UI/AGENTS.md` при работе с соответствующими модулями. Особенно: проект требует отдельного согласования перед **изменением публичного WebSocket API** или **формата существующего блокчейна**. Утверждённая архитектура не отменяет эти рабочие правила.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# В. ПРОТОКОЛ V1: ПРЕДЛАГАЕМАЯ ТОЧНАЯ КОНКРЕТИЗАЦИЯ
|
|
||||||
|
|
||||||
**Статус подраздела В:** проект формата для принятия на этапе 1. Дальше его нельзя «чуть изменить в одном месте»; изменение только одновременно в Rust, JS, Java, документах, фикстурах. Здесь изложены технические детали уже согласованного поведения, не новые продуктовые возможности.
|
|
||||||
|
|
||||||
## В1. Канонический login
|
|
||||||
|
|
||||||
- `localPart` и `namespace` — ASCII lowercase, разрешённые символы утвердить по совместимости с кодом; практичный набор: `[a-z0-9_]`, без пробелов, без второго `@`.
|
|
||||||
- Полное имя: `${localPart}@${namespace}`.
|
|
||||||
- `normalizedFullLogin` — байты UTF-8 ровно этой lowercase-строки, без пробелов по краям. Для проверки нового аккаунта отклонять неоднозначные формы, не преобразовывать «почти такие же» имена молча.
|
|
||||||
- Общее ограничение полного имени: 30 **UTF-8 байт** на этой версии; минимальная длина localPart — из namespace PDA, считать байты (ASCII = символы).
|
|
||||||
- Никогда не отбрасывать `_`, не обрезать строку, не менять namespace после создания.
|
|
||||||
|
|
||||||
## В2. Seed пользовательского PDA
|
|
||||||
|
|
||||||
```text
|
|
||||||
preimage = UTF8("user_login=" + normalizedFullLogin)
|
|
||||||
seed32 = SHA256(preimage) // именно 32 СЫРЫХ БАЙТА
|
|
||||||
userPda = findProgramAddress([seed32], shineUsersProgramId)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Не** base58-строку хеша, не hex-строку, не два старых seed. На адрес дополнительно влияет programId и bump стандартного findProgramAddress. Для подписания `create_program_address` программа использует `[seed32, bump]`.
|
|
||||||
|
|
||||||
## В3. Seed namespace PDA
|
|
||||||
|
|
||||||
```text
|
|
||||||
preimage = UTF8("namespace=" + normalizedNamespace)
|
|
||||||
seed32 = SHA256(preimage)
|
|
||||||
namespacePda = findProgramAddress([seed32], shineUsersProgramId)
|
|
||||||
```
|
|
||||||
|
|
||||||
Префикс `namespace=` здесь предложен как **окончательная константа v1 после утверждения на этапе 1**; его нельзя менять после первых созданных PDA.
|
|
||||||
|
|
||||||
## В4. Бинарный namespace-PDA
|
|
||||||
|
|
||||||
```text
|
|
||||||
major u8 // 1
|
|
||||||
minor u8 // 0
|
|
||||||
namespace_type u8 // 1 paid-direct / 2 free-cert
|
|
||||||
min_localpart_len u8
|
|
||||||
namespace_len u8 // N
|
|
||||||
namespace u8[N] // lowercase ASCII
|
|
||||||
registration_fee u64 LE // lamports; и для будущего upgrade free
|
|
||||||
if namespace_type == 2:
|
|
||||||
registrar_pubkey u8[32] // Ed25519
|
|
||||||
server_login_len u8 // M
|
|
||||||
server_login u8[M] // полный login@namespace зарегистрированного сервера
|
|
||||||
```
|
|
||||||
|
|
||||||
Сериализатор и парсер должны отвергать неизвестные версии/типы, неправильную длину данных, некорректный namespace и подставленный PDA. Если Solana-аккаунт создаётся с дополнительной областью из-за выравнивания/rent, определить однозначную политику padding и её проверку. Для type 1 поля регистратора/сервера отсутствуют, а не заполнены «нулевой фикцией».
|
|
||||||
|
|
||||||
## В5. Внутренняя подпись бесплатного сертификата
|
|
||||||
|
|
||||||
Пример детерминированного массива байтов (предлагается как v1):
|
|
||||||
|
|
||||||
```text
|
|
||||||
identity_fields =
|
|
||||||
major:u8 (=1) || minor:u8 (=0) ||
|
|
||||||
full_login_len:u8 || full_login_utf8 ||
|
|
||||||
root_pubkey:32 || blockchain_pubkey:32 || client_pubkey:32
|
|
||||||
|
|
||||||
inner_message = UTF8("SHiNE_FREE_REG_V1\u0000") || identity_fields
|
|
||||||
inner_signature64 = Ed25519.sign(registrar_private_key, inner_message)
|
|
||||||
```
|
|
||||||
|
|
||||||
- Domain separator убирает риск приравнивания подписи к подписи чужого протокола.
|
|
||||||
- Контракт должен проверить **байты** `inner_message`, а не локальный JSON/строковую интерпретацию.
|
|
||||||
- Внешняя ANS-104 подпись использует стандартный `deepHash(...)` и **не заменяет** внутреннюю подпись.
|
|
||||||
- Тот же публичный ключ регистратора должен быть в namespace PDA и в owner внешнего DataItem.
|
|
||||||
|
|
||||||
## В6. Payload DataItem
|
|
||||||
|
|
||||||
```text
|
|
||||||
payload = identity_fields || inner_signature64:64 || normalized_email_sha256:32
|
|
||||||
```
|
|
||||||
|
|
||||||
Плюс теги, отделяющие регистрационный DataItem от пользовательского блока. Email внутри `inner_message` отсутствует **осознанно**, по решению владельца проекта.
|
|
||||||
|
|
||||||
**Не включать:** пароль, masterSecret, root/blockchain/client private keys, приватный ключ регистратора, исходный email.
|
|
||||||
|
|
||||||
## В7. Нормализация email
|
|
||||||
|
|
||||||
- `trim` пробелы с краёв.
|
|
||||||
- Unicode NFC, lowercase без зависимости от локали.
|
|
||||||
- Не удалять `+tag` и точки: разные почтовые сервисы трактуют их неодинаково.
|
|
||||||
- `email_hash = SHA256(UTF8(normalizedEmail))`.
|
|
||||||
- Хеш проверяется по индексу, а не принимается на веру со слов клиента: пока сервер получает email по защищённому каналу, нормализует сам.
|
|
||||||
|
|
||||||
## В8. On-chain Ed25519-инструкции и экономическая транзакция
|
|
||||||
|
|
||||||
Упорядочить инструкции в Solana-транзакции так, чтобы контракт надёжно проверял (а) подпись root над хешем записи пользователя, (б) подпись blockchain над тем же хешем и (в) для type 2 подпись регистратора над `inner_message`. Количество/индексы Ed25519 IX и номера инструкций должны быть зафиксированы в документах **и тестах на отрицательные случаи**. Не делать проверку «подпись где-то есть в транзакции» без проверки конкретного сообщения, ключа и содержания.
|
|
||||||
|
|
||||||
Регистрационную комиссию переводить в существующий `shine_payments` inflow-vault с сохранением текущего расчёта дополнительного лимита. Считывать цену регистрации из namespace, не из economy. Economy PDA участвует read-only и используется для параметров лимитов и истории транзакций.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Г. ВЫПОЛНЕНИЕ: 14 ПОСЛЕДОВАТЕЛЬНЫХ ЭТАПОВ
|
|
||||||
|
|
||||||
Каждый этап начинается с аудита указанных файлов, завершается **сборкой, целевыми тестами, документацией и отчётом**. Завершение одного этапа не равно завершению всего проекта.
|
|
||||||
|
|
||||||
## ЭТАП 0. Подготовить ветку, матрицу зависимостей и базовый тестовый стенд
|
|
||||||
|
|
||||||
**Зачем:** зафиксировать исходное состояние и не выполнять изменения вслепую.
|
|
||||||
|
|
||||||
**Файлы/места:** корень, все `AGENTS.md`, `COMMIT_AND_VERSION_RULES.md`, `deploy/TEST_SERVERS.md`, `shine-solana/shine/`, `SHiNE-server/`, `shine-UI/`.
|
|
||||||
|
|
||||||
**Действия:**
|
|
||||||
1. Распаковать/клонировать исходник. Зафиксировать commit/архив, рабочую ветку, версии tools, Rust/Anchor/Solana, Java/Gradle, Node, PostgreSQL.
|
|
||||||
2. Прочитать инструкции по модулям. Разрешения на production **не подразумеваются**.
|
|
||||||
3. Установить базовые команды сборки/тестов по реальным файлам проекта; выполнить smoke baseline и записать результаты (включая уже существующие ошибки).
|
|
||||||
4. Найти все вызовы `find_user_pda`, `user_login=`, `getProgramAccounts`, константы 20/8, `shine_login_guard`, `promo_seller`, `registration_fee_lamports`, `solana_user_pda_current`, `resolveLogin`.
|
|
||||||
5. Выписать все SQL FK на `solana_user_pda_current`, PostgreSQL triggers/views и клиентов `CurrentUsersSql`; отдельным списком — операции, зависящие от real Solana PDA.
|
|
||||||
6. Создать в ветке `docs/registration-v2/IMPLEMENTATION_STATUS.md` (или отдельный рабочий журнал), заполнять после каждого этапа.
|
|
||||||
|
|
||||||
**Готово, когда:** известны реальные точки редактирования, baseline сборки и правила релиза; основной код пока неизменён.
|
|
||||||
|
|
||||||
## ЭТАП 1. Зафиксировать протоколы и тест-векторы Rust/Java/JS
|
|
||||||
|
|
||||||
**Зависимость:** этап 0.
|
|
||||||
|
|
||||||
**Создать/изменить:**
|
|
||||||
- `shine-solana/shine/doc/formats/shine-namespace-pda-format-v1.md` (новый).
|
|
||||||
- `docs/Протоколы/SHINE_FREE_REGISTRATION_CERTIFICATE_V1.md` (новый).
|
|
||||||
- `shine-solana/shine/doc/programs/shine_users.md` (разделы новых IX и seed).
|
|
||||||
- Общие тестовые фикстуры по одному логину/ключам/email; место выбрать так, чтобы тесты трёх языков могли читать их.
|
|
||||||
|
|
||||||
**Задачи:**
|
|
||||||
1. Застолбить все поля форматов, версии, число байт, encoding `u64 LE`, `full login`, запрет неоднозначных имён.
|
|
||||||
2. Застолбить доменные префиксы seed и внутренней подписи.
|
|
||||||
3. Зафиксировать структуру подписанного `inner_message` и `ANS-104 payload`, уникальные теги для регистраций.
|
|
||||||
4. Фиксировать максимумы, ошибка/результат на некорректном типе, парсинге, padding, цене, серверном логине.
|
|
||||||
5. Подготовить тест-векторы: `alice@shine`, `bob@free`, `_` в имени, минимальная длина, 30-й байт, 31-й байт; один детерминированный email.
|
|
||||||
6. Записать ожидаемые хеши и PDA **для конкретного program ID теста**. Проверка в Rust/Java/JS обязана давать побайтово одинаковые значения.
|
|
||||||
7. Зафиксировать как обрабатывается созданная ранее история free пользователя: ключи/блоки неизменны; создание Solana PDA может иметь новую timestamp без сброса логической регистрации.
|
|
||||||
|
|
||||||
**Тесты:** round-trip кодирования; одинаковые хеши; подмена одного ключа ломает внутреннюю подпись; подмена email ломает внешнюю ANS-104 подпись.
|
|
||||||
|
|
||||||
**Готово, когда:** ни исполнитель Solana, ни исполнитель UI не должен выбирать форматы заново.
|
|
||||||
|
|
||||||
## ЭТАП 2. Solana: Namespace PDA и полномочия upgrade authority
|
|
||||||
|
|
||||||
**Зависимость:** этап 1.
|
|
||||||
|
|
||||||
**Изменить:**
|
|
||||||
- `shine-solana/shine/programs/shine_users/src/lib.rs`;
|
|
||||||
- `.../settings.rs`;
|
|
||||||
- `shine-solana/shine/tests/shine.ts` и документацию программы.
|
|
||||||
|
|
||||||
**Задачи:**
|
|
||||||
1. Добавить типы `NamespaceState`/`CreateNamespaceArgs`, строгий parser/serializer.
|
|
||||||
2. Добавить **новый opcode** `IX_CREATE_NAMESPACE` без конфликта с текущими 1–6.
|
|
||||||
3. Проверять правильный PDA из SHA-256 seed `namespace=...`, owner, rent, размер, неповторяемость имени.
|
|
||||||
4. Проверять владельца `ProgramData`: это ProgramData **конкретной** программы, принадлежащий BPF upgradeable loader, с текущей `upgrade_authority_address`; signer должен совпадать. Если программа immutable — отказ.
|
|
||||||
5. В `update_users_economy_config` применить ту же проверку ProgramData. Инициализацию economy не менять.
|
|
||||||
6. В `create_namespace` принять economy-PDA как read-only account meta; проверить его ожидаемый адрес. Цена хранится в namespace.
|
|
||||||
7. Сделать CLI/скрипт подготовки создания двух test namespaces и независимый декодер.
|
|
||||||
|
|
||||||
**Тесты:** админ создаёт; посторонний не создаёт; чужой/поддельный ProgramData не помогает; тот же namespace повторно отвергается; неверный type/version/данные отвергаются; economy init всё ещё открыт, economy update закрыт.
|
|
||||||
|
|
||||||
**Готово, когда:** два test namespace создаются и читаются в localnet/devnet; **пока не изменять production**.
|
|
||||||
|
|
||||||
## ЭТАП 3. Solana: создание PDA пользователем напрямую и по сертификату
|
|
||||||
|
|
||||||
**Зависимость:** этап 2.
|
|
||||||
|
|
||||||
**Изменить:** `shine_users/src/lib.rs`, `settings.rs`, `shine/tests/shine.ts`, документы формата PDA v1.2 и программы.
|
|
||||||
|
|
||||||
**Задачи:**
|
|
||||||
1. Во всех местах create/update/close (где нужно) заменить вычисление пользовательского PDA на SHA-256 от **полного** имени, включая `@namespace`.
|
|
||||||
2. Проверять `(localPart, namespace)`, тип, min local length, max full length 30 байт, правильный namespace-PDA.
|
|
||||||
3. Оставить бинарный payload существующего PDA пользователя **версии 1.2**, если нет объективной необходимости его менять.
|
|
||||||
4. Для type 1: проверка доступности имени, root/blockchain подтверждение, создание PDA, комиссия по namespace + лимит из economy.
|
|
||||||
5. Для type 2: дополнительно требовать внутреннюю подпись регистрирующего ключа над тем же полным именем и **теми же** root/blockchain/client public keys. Ключ проверки брать из on-chain namespace.
|
|
||||||
6. Передать economy-PDA в account list read-only при любой регистрации; сохранить `shine_payments` inflow-vault.
|
|
||||||
7. Обновить Ed25519 instruction index: корректно отличать root, blockchain, registrar; отрицательные тесты на путаницу индексов.
|
|
||||||
8. Удалить из новой регистрации guard CPI, premium-classification, promo seller args/promo IX и связанные комиссии. Старые отдельные Solana-программы не трогать без причины.
|
|
||||||
9. Для upgrade не допускать повторного Solana PDA, не требовать создания заново пользовательского Arweave блокчейна.
|
|
||||||
10. Продумать состояние лимитов: бесплатный пользователь мог уже писать и тратить стартовый ресурс — не объявлять оплаченный лимит или баланс «с нуля» без согласования с реальным текущим учётом блоков. Не давать дополнительных стартовых бонусов за сам факт upgrade без явного правила.
|
|
||||||
|
|
||||||
**Тесты:** прямой paid create; free→paid create; цена для разных namespaces; заблокирован type2 без сертификата; неверный регистратор; изменённый client/root/blockchain; чужой namespace; 30 vs 31 байт; повторное создание; корректность PDA; существующий paid update без регрессии.
|
|
||||||
|
|
||||||
**Готово, когда:** новая Solana-программа умеет создавать обе категории PDA и корректно обновлять существующую v1.2 запись. UI можно внедрять позже.
|
|
||||||
|
|
||||||
## ЭТАП 4. Клиентский Solana codec, поиск PDA и bootstrap namespace
|
|
||||||
|
|
||||||
**Зависимость:** этап 3.
|
|
||||||
|
|
||||||
**Изменить:**
|
|
||||||
- `shine-UI/js/services/shine-user-pda-service.js`;
|
|
||||||
- `shine-UI/js/services/solana-register-service.js`;
|
|
||||||
- `shine-UI/js/solana-programs.js` при необходимости;
|
|
||||||
- `shine-UI/server-ui/` (если инструменты управления серверным аккаунтом используют прежний seed).
|
|
||||||
|
|
||||||
**Задачи:**
|
|
||||||
1. Добавить JS encode/decode NamespaceState, `deriveNamespacePda()` и `deriveUserPda(fullLogin)`.
|
|
||||||
2. Удалить `getProgramAccounts`/поиск по старой строке-логину или адаптировать под хеш seed и новый формат. Не предполагать, что seed можно восстановить из PDA без данных.
|
|
||||||
3. Переделать сериализацию `create_user_pda`, account metas (namespace, economy), fee display, IX order.
|
|
||||||
4. Для type2 сформировать и подключить Ed25519 ix с **готовой** внутренней подписью сертификата; приватный ключ регистратора в браузер не попадает.
|
|
||||||
5. Убрать UI service API `promoCode` и premium guard precheck там, где они обслуживают регистрацию.
|
|
||||||
6. Обновить код **создания серверного аккаунта**, который тоже является user PDA и тоже требует полный `login@namespace`.
|
|
||||||
7. Создать независимые JS unit tests на PDA, namespace decode, transaction serialization, equality signature message.
|
|
||||||
|
|
||||||
**Готово, когда:** тестовый JS может создать correct paid/free Solana transaction по контракту без рабочего пользовательского экрана.
|
|
||||||
|
|
||||||
## ЭТАП 5. PostgreSQL: единый логический пользователь вместо фиктивного free PDA
|
|
||||||
|
|
||||||
**Зависимость:** этап 1; желательно готов этап 3 для схемы Solana полей.
|
|
||||||
|
|
||||||
**Изменить:** schema/migrations `SHiNE-server/shine-server-db/src/main/resources/postgres/`; `CurrentUsersSql`, `CurrentUsersDAO`, `SolanaUserPdaCurrentDAO`, `UserAccessServersCurrentDAO`, зависимые views/triggers/DAO, отдельные entities.
|
|
||||||
|
|
||||||
**Главный риск:** **текущие FK, stats и queries считают `solana_user_pda_current` полным списком пользователей.** Нельзя просто положить сертификаты в новую таблицу и надеяться, что всё заработает.
|
|
||||||
|
|
||||||
**Предпочтительное решение:** создать каноническую таблицу **логических пользователей**, например `user_identity_current` (название финализировать по реальному SQL), с уникальным `normalized_login` и ключами; оставить `solana_user_pda_current` таблицей **только настоящих** PDA, связанной с логической личностью. Хранить `namespace`, `registration_source`, `registration_status`, `registered_at_ms`, `free_data_item_id`, `solana_pda_address (nullable)` и текущие ключи. В свободном состоянии `solana_pda_address = NULL`, не выдумывать адрес «как будто on-chain аккаунт есть».
|
|
||||||
|
|
||||||
**Задачи:**
|
|
||||||
1. На основе полного поиска SQL составить список всех FK/views/triggers/запросов и миграционный граф.
|
|
||||||
2. Создать новую **следующую** миграцию после существующей v32 (номер брать из актуального исходника, если новее). Не переписывать исторические миграции.
|
|
||||||
3. Добавить таблицу синхронизированных namespaces, таблицу сертификатов (полный signed payload/ID/hash email/внутренняя подпись/публикационный статус) и индексы уникальности.
|
|
||||||
4. Сформировать общий индекс `user_identity_current`, связать paid/free; изменить зависимости SQL на него там, где нужна любая идентичность, а не именно реальный PDA.
|
|
||||||
5. Обновить `CurrentUsersSql.usersSubquery()` и соответствующие DAO на общее представление пользователя. В частях, где необходим фактический PDA (rotation, Solana-specific reads), делать явную проверку `has_solana_pda`.
|
|
||||||
6. Учитывать сервер доступа: `FREE_CERT` → namespace.defaultServerLogin; `PAID_DIRECT`/`PAID_UPGRADED` → account access servers из PDA.
|
|
||||||
7. Добавить атомарную операцию **upgrade существующего логического аккаунта** без дублирования `login`, ссылок, каналов и связей.
|
|
||||||
8. Для уже существующих реальных PDA подготовить idempotent backfill в канонический индекс; старая база не должна разрушаться.
|
|
||||||
9. Добавить интеграционные тесты на restart/re-run migration; FK, статистику, связи, access routing, уникальность.
|
|
||||||
|
|
||||||
**Готово, когда:** тот же логин может существовать как `FREE_CERT` без PDA и затем приобрести настоящий PDA без новой строки логического пользователя. На чистой и обновляемой тестовой базе старые DAO продолжают работать.
|
|
||||||
|
|
||||||
## ЭТАП 6. Java синхронизация Solana: namespaces + новые PDA + события
|
|
||||||
|
|
||||||
**Зависимость:** этапы 3 и 5.
|
|
||||||
|
|
||||||
**Изменить:**
|
|
||||||
- `SHiNE-server/shine-server-solana-users-sync/src/main/java/sync/service/SolanaUsersSyncService.java`;
|
|
||||||
- `.../sync/codec/ShineUsersCodec.java`;
|
|
||||||
- `.../sync/storage/postgres/PostgresStorageRepository.java`;
|
|
||||||
- `.../sync/util/SolanaPdaUtil.java`;
|
|
||||||
- `docs/Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md`;
|
|
||||||
- `deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md`.
|
|
||||||
|
|
||||||
**Задачи:**
|
|
||||||
1. Кодеки namespace PDA, новой инструкции и нового расчёта seed.
|
|
||||||
2. History parse: `IX_CREATE_NAMESPACE`, новый `IX_CREATE_USER_PDA` и существующие update. Сохранять `economy PDA` как индекс RPC истории.
|
|
||||||
3. Snapshot bootstrap должен находить **все актуальные namespace** и **все реальные пользовательские PDA**, а не зависеть только от уже обработанных событий.
|
|
||||||
4. На каждое подтверждённое создание/обновление делать идемпотентный upsert в реестр, не изменять кэш бесплатного сертификата без проверок.
|
|
||||||
5. Если пришёл paid upgrade для существующего free логина — обновить ту же логическую личность, а не удалить/recreate.
|
|
||||||
6. Реализовать корректный checkpoint/retry при RPC timeout, ошибках декодера, дубликатах signature, задержках сети.
|
|
||||||
7. Сохранять доступ к деталям economy после init/update для прежней модели лимитов.
|
|
||||||
8. Проверить, что сервер умеет различать `free cert есть`, `Solana PDA ещё нет` и `Solana PDA уже появился`.
|
|
||||||
|
|
||||||
**Готово, когда:** из clean snapshot и из history replay получается одна и та же PostgreSQL-сущность для пользователей и namespaces; upgrade не плодит дубли.
|
|
||||||
|
|
||||||
## ЭТАП 7. Сервер: доверенный регистратор (временная программная заглушка)
|
|
||||||
|
|
||||||
**Зависимость:** этапы 1, 5 и импорт namespace из 6.
|
|
||||||
|
|
||||||
**Изменить/создать:** `SHiNE-server/shine-server-config/src/main/java/utils/config/AppConfig.java`; новый сервис/интерфейс registrar в подходящем Java модуле; unit tests; новый конфигурационный README.
|
|
||||||
|
|
||||||
**Задачи:**
|
|
||||||
1. Настройки: включено ли бесплатное регистрирование, какие namespace обслуживает сервер, публичный ключ и **путь/secret reference** к приватному ключу регистратора; не хранить ключ в Git или логе.
|
|
||||||
2. При старте сверять локальный public key с public key **соответствующего** on-chain namespace; при несоответствии блокировать новые выдачи, не ломая работу старых пользователей.
|
|
||||||
3. Выделить интерфейс `RegistrarSigner.sign(byte[])` и software-реализацию. В будущем можно заменить на hardware signer.
|
|
||||||
4. Подготовить детерминированный `identity_fields` и `inner_message`; получить внутреннюю Ed25519-подпись.
|
|
||||||
5. Собрать `payload` и внешнюю ANS-104 подпись тем же keypair; задать отличающиеся от user block теги.
|
|
||||||
6. Проверять формат имени, min/max длины, неповторяемость известных login/email, тестовый код `1111` и соответствие namespace type2.
|
|
||||||
7. Не принимать приватные ключи пользователя даже «временно», не хранить пароли.
|
|
||||||
8. Не вводить сейчас аппаратное устройство и сложный распределённый mutex/компрометацию ключа; достаточно корректного последовательного выполнения обычной выдачи на одном регистраторе.
|
|
||||||
|
|
||||||
**Тесты:** повторяемые фикстуры; правильная внутренняя + внешняя подпись; неверный namespace; отсутствие ключа; несоответствие pubkey; неправильный email code; секреты не появляются в диагностике.
|
|
||||||
|
|
||||||
**Готово, когда:** Java локально выдаёт raw signed ANS-104 bytes с обеими проверяемыми подписями без Turbo и UI.
|
|
||||||
|
|
||||||
## ЭТАП 8. Arweave: отдельный импорт сертификатов и немедленное принятие после Turbo
|
|
||||||
|
|
||||||
**Зависимость:** этапы 5, 6 и 7.
|
|
||||||
|
|
||||||
**Изменить:** `SHiNE-server/shine-server-archive/src/main/java/server/archive/ArweaveBlockSyncService.java`, `TurboDataItemUploader.java` **переиспользовать**, `Ans104DataItem.java` **переиспользовать**; новая ветка/сервис регистрации и DAO. Не менять формат существующих обычных блоков.
|
|
||||||
|
|
||||||
**Задачи:**
|
|
||||||
1. Создать **отдельный importer** для `t=reg` DataItem, а не подделывать пользовательский блок.
|
|
||||||
2. Парсер payload; проверка внешней ANS104 подписи, owner = on-chain registrar pubkey, внутренней Ed25519 подписи, имени, namespace, структурных границ.
|
|
||||||
3. Проверить уникальность ID DataItem; не дать повторному discovery создать двойника или переписать существующий login.
|
|
||||||
4. После успешного Turbo upload сразу прогонять **точно те же raw signed bytes** через этот importer в локальную БД.
|
|
||||||
5. Обновить GraphQL discovery / типовые фильтры, чтобы независимый сервер мог получить `t=reg` и восстановить сертификаты позже. Не ограничиваться существующим фильтром только блоков/высот без учёта регистраций.
|
|
||||||
6. Хранить `TURBO_ACCEPTED`, последующее подтверждение Arweave, отметки retries, ID и ошибку при необходимости.
|
|
||||||
7. Idempotent import: immediate → GraphQL повторный импорт должен дать «уже учтено» и сохранить те же ключи/identity.
|
|
||||||
8. При Turbo timeout/неопределённости не выдавать ложный окончательный успех; предусмотреть проверку известного DataItem ID и повторную отправку идентичных байтов.
|
|
||||||
9. Сервер B импортирует записи, созданные сервером A, при достижении Arweave и наличии namespace registry.
|
|
||||||
|
|
||||||
**Готово, когда:** подтверждение Turbo даёт первый вход на принимающем сервере без ожидания GraphQL; второй сервер узнаёт пользователя после sync; дубли harmless.
|
|
||||||
|
|
||||||
## ЭТАП 9. Сервер: WS/API операции бесплатной регистрации
|
|
||||||
|
|
||||||
**Зависимость:** этапы 7 и 8.
|
|
||||||
|
|
||||||
**До изменения API:** прочитать `AGENTS.md`, `docs/API/*` и **получить отдельное согласование пользователя на конкретные новые операции/поля** — это правило репозитория, даже когда общая функциональность одобрена.
|
|
||||||
|
|
||||||
**Изменить:** `JsonHandlerRegistry.java`, новые handler/DTO классы в `shine-server-net-protocol`, `docs/API/01_User_Registration_API.md`, `docs/API/09_Operations_Index.md`.
|
|
||||||
|
|
||||||
**Предложение минимального протокола (ИМЕНА ОПЕРАЦИЙ — ПРОЕКТ, не существующий код):**
|
|
||||||
|
|
||||||
| Операция | Ввод | Результат |
|
|
||||||
|---|---|---|
|
|
||||||
| `GetNamespaces` | — | список существующих namespace + type/fee/min/server |
|
|
||||||
| `CheckRegistrationAvailability` | fullLogin, email (для free) | доступен ли login/email; не считать результат резервированием |
|
|
||||||
| `StartFreeRegistration` | fullLogin, 3 public keys, email | продолжение проверки кода, id временного процесса при необходимости |
|
|
||||||
| `ConfirmFreeRegistration` | id/данные процесса, code=`1111` | Turbo dataItemId, статус, подтверждённый fullLogin |
|
|
||||||
| `GetRegistrationStatus` | login или ID операции | `FREE_CERT`, `PAID_DIRECT`, `PAID_UPGRADED`, `PENDING`, ошибка |
|
|
||||||
|
|
||||||
**Задачи:**
|
|
||||||
1. Выбрать окончательные `op` имена по текущему стилю API, чтобы не ломать существующий клиент.
|
|
||||||
2. Согласовать поля/ответы/ошибки, зафиксировать в `docs/API/` **до редактирования реализации**.
|
|
||||||
3. Интегрировать `RegistrarSigner`, Turbo uploader, импортёр и logical identity DAO.
|
|
||||||
4. Не помещать приватные пользовательские ключи в requests/responses. Не отдавать приватный registrar key.
|
|
||||||
5. Любую выдачу завершать только после валидного signed DataItem и успешного локального импорта.
|
|
||||||
6. Возвращать явный статус `Turbo accepted, chain confirmation pending` без обещания финального подтверждения.
|
|
||||||
7. Сделать обработку ошибочного/отменённого запроса, потерянного ответа и retry.
|
|
||||||
8. Добавить unit/integration tests handler и документированные errors.
|
|
||||||
|
|
||||||
**Готово, когда:** WS-клиент может пройти free-регистрацию и получить подтверждённую локальную идентичность без UI.
|
|
||||||
|
|
||||||
## ЭТАП 10. Сервер: единая авторизация и реальные ограничения `FREE_CERT`
|
|
||||||
|
|
||||||
**Зависимость:** этапы 5, 8, 9.
|
|
||||||
|
|
||||||
**Изменить:** `.../handlers/auth/{SolanaUserPdaImportService,Net_ResolveLoginForAuth_Handler,Net_CreateAuthSession__Handler}` и соседние обработчики, `CurrentUsersDAO`, `UserAccessServersCurrentDAO`, `.../handlers/keyRotation/`, соответствующие docs/API.
|
|
||||||
|
|
||||||
**Задачи:**
|
|
||||||
1. Определить единый объект `ResolvedIdentity`: fullLogin, root/client/blockchain public keys, source, status, namespace, accessServer, hasSolanaPda.
|
|
||||||
2. Разрешить login как через PDA, так и через сертификат; обе ветки выдают общую структуру авторизации, но не одинаковые права.
|
|
||||||
3. Проверять пароль локально через получение ключей, а серверу предоставлять существующие криптографические proofs; сервер не получает пароль или приватные ключи.
|
|
||||||
4. До upgrade routing `FREE_CERT` берёт сервер из namespace. После upgrade — из пользовательского PDA.
|
|
||||||
5. Закрыть все варианты server-side смены ключей, access server и fork rotation для free (искать как прямые обработчики, так и фоновые сервисы/обходные API).
|
|
||||||
6. Убедиться, что бесплатные могут создавать подписанные блоки, читать/писать в каналах и работать с direct messages как обычные пользователи.
|
|
||||||
7. Не использовать «наличие строки в solana_user_pda_current» как единственный признак существования человека в общих обработчиках.
|
|
||||||
8. При upgrade переключать источник полномочий без потери session, graph, messages, user profile, saved files.
|
|
||||||
|
|
||||||
**Готово, когда:** free/paid login и работа с контентом функционируют; попытки обойти ограничения free отвергаются именно сервером.
|
|
||||||
|
|
||||||
## ЭТАП 11. UI: выбор типа регистрации, формы и мгновенный вход
|
|
||||||
|
|
||||||
**Зависимость:** этапы 4, 9 и 10.
|
|
||||||
|
|
||||||
**Изменить:** `shine-UI/js/pages/{register-view,registration-payment-view,registration-draft-keys-view,login-view,settings-view,key-rotation-view}.js`, `js/state.js`, `js/router.js`, `js/services/solana-register-service.js`. При необходимости создать `registration-method-view.js`, `registration-email-view.js` и собственный контролируемый onboarding step.
|
|
||||||
|
|
||||||
**Задачи:**
|
|
||||||
1. Первый экран: «Через Solana» или «Бесплатно»; UI не диктует namespace из захардкоженных названий.
|
|
||||||
2. Drop-down подгружает on-chain namespace list, показывает fee/min/type и разрешает выбирать соответствующие способу регистрации.
|
|
||||||
3. Пользователь вводит localPart и видит `localPart@namespace`; длина проверяется включая суффикс. Старые 20/8 и premium/promo form logic отключить в новой ветке.
|
|
||||||
4. Локальная генерация keyBundle из **полного имени и пароля**, одинаковая для free/direct paid/последующего входа.
|
|
||||||
5. Бесплатный flow: public keys + email → экран с текстом «Тест: код 1111; письмо не отправляется» → server-confirm → Turbo ACK → локальный sign-in.
|
|
||||||
6. Любая ошибка Turbo/сети **не должна заставлять генерировать новые ключи** или терять корректно введённый логин/пароль до понятного завершения процесса; обеспечить осознанную очистку чувствительного UI state.
|
|
||||||
7. Платный flow использует новую транзакцию, цену namespace и текущую существующую оплату.
|
|
||||||
8. У free отображается статус, фиксированный access server, ограничения ключей и будущая кнопка перехода в Solana.
|
|
||||||
9. Сохранить текущую архитектуру UI из `shine-UI/AGENTS.md`: App/Router единственный mount owner, shared components, никакого нового UI-framework.
|
|
||||||
10. Обновить FAQ, подсказки и ошибки; не обещать, что Arweave окончательно подтвердил запись при одном Turbo ACK.
|
|
||||||
|
|
||||||
**Готово, когда:** новый человек может пройти paid или free регистрацию и войти с обычного экрана без ручных CLI/WS команд.
|
|
||||||
|
|
||||||
## ЭТАП 12. Upgrade UI и end-to-end free → Solana без смены личности
|
|
||||||
|
|
||||||
**Зависимость:** этапы 3, 4, 6, 10, 11.
|
|
||||||
|
|
||||||
**Изменить:** `shine-UI/js/services/shine-user-pda-service.js`, `shine-UI/js/pages/settings-view.js` (или отдельная `registration-upgrade-view.js`), серверный статус identity при Solana sync.
|
|
||||||
|
|
||||||
**Задачи:**
|
|
||||||
1. Кнопка «Зарегистрировать аккаунт в Solana» видна только `FREE_CERT`.
|
|
||||||
2. Показать **сумму из namespace type2**, получаемую из Solana, а не старую цену economy.
|
|
||||||
3. Прочитать сохранённый подписанный сертификат; предъявить **внутреннюю** подпись и идентификационные поля.
|
|
||||||
4. Использовать существующие три ключа пользователя. Root + blockchain подписывают актуальную запись PDA по правилам Solana; registrar private key не участвует в upgrade.
|
|
||||||
5. Сформировать новую Solana транзакцию; оплатить PDA и комиссию; дождаться корректного on-chain результата.
|
|
||||||
6. Синхронизация связывает PDA с **тем же normalized full login**; меняет регистрацию на `PAID_UPGRADED` без новой logical-user строки.
|
|
||||||
7. Не сбрасывать старые Arweave блоки, used bytes, channel ownership, connections, profile, DM адресацию, session state.
|
|
||||||
8. В интерфейсе после синхронизации показывать «Зарегистрирован в Solana», разрешать обычную key rotation/access-server operations.
|
|
||||||
9. Если Solana транзакция упала или UI перезагрузился — пользователь остаётся бесплатным, сертификат и история сохранены, повторная попытка безопасна.
|
|
||||||
|
|
||||||
**Готово, когда:** пользователь Bob создал публикации/канал будучи free, оплатил Solana и затем видит все старые данные теми же ключами и именем.
|
|
||||||
|
|
||||||
## ЭТАП 13. Сквозные тесты, тестовый релиз и выпускная проверка
|
|
||||||
|
|
||||||
**Зависимость:** этапы 0–12.
|
|
||||||
|
|
||||||
**Стенд:** localnet/devnet Solana; отдельная тестовая PostgreSQL; тестовый сервер SHiNE; Turbo (помнить, что публикация может быть реальной и долговечной); второй независимый тестовый сервер.
|
|
||||||
|
|
||||||
**Сценарии приёмки:**
|
|
||||||
1. `create_namespace(@shine, type1)` и `create_namespace(@free, type2)` выполняет upgrade authority; посторонний отклонён.
|
|
||||||
2. Economy init разрешён любому, update только upgrade authority.
|
|
||||||
3. Серверный аккаунт регистрируется полноценным full login и имеет доступный server profile; free namespace ссылается на реально разрешаемый сервер.
|
|
||||||
4. `alice@shine` direct paid: PDA создан, сумма правильная, вход/профиль/публикации работают.
|
|
||||||
5. `bob@free`: три пары ключей генерируются локально, код 1111 принят, внутри и снаружи подпись правильная, email hash опубликован без email.
|
|
||||||
6. Turbo ACK → быстрый локальный импорт → вход Bob **без ожидания Arweave height**.
|
|
||||||
7. Независимый сервер импортирует Bob через Arweave и распознаёт тот же namespace/identity.
|
|
||||||
8. Повторный login/email отклоняется, повторный импорт того же DataItem идемпотентен.
|
|
||||||
9. Подменённый inner signature/root/client/blockchain/namespace/owner не проходит.
|
|
||||||
10. Bob не может менять ключи/access server до оплаты, включая прямой серверный вызов.
|
|
||||||
11. Bob создаёт профиль, публикацию, канал, связь и сообщение до Solana PDA.
|
|
||||||
12. Bob делает платный upgrade с сертификатом. Проверяются адрес PDA, fee, неизменность имени/3 ключей/блоков и отсутствие дублирующего пользователя.
|
|
||||||
13. После upgrade доступны штатные операции PDA/update/key rotation/access-server (по существующим ограничениям).
|
|
||||||
14. Перезапуск каждого сервера, новая БД + snapshot, обработка GraphQL повторно, задержка Turbo и Solana RPC не портят данные.
|
|
||||||
15. Две цены namespace ведут к двум разным корректным платежам.
|
|
||||||
16. Старые экраны, каналы, ссылки, DM, websocket auth, поиск, статистика и публикации не деградируют.
|
|
||||||
17. Проверить все места `getProgramAccounts`/PDA derivation; old seed не используется для **новых** регистраций.
|
|
||||||
18. Фактические сборки и тесты Rust/JS/Java, списки skip/fail, ручной smoke browser.
|
|
||||||
19. Обновлены документы Solana, DB, sync, API и runbooks. Разрешения на изменение API/формата соблюдены.
|
|
||||||
20. Все runtime secrets вне Git/logs/browser и test fixtures. Секрет регистратора не возвращается ни одним API.
|
|
||||||
|
|
||||||
**Только после этого:** отдельная подготовка к production, backup и план переключения. Сам факт прохождения devnet **не является разрешением** деплоя на боевой контур.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Д. ОСОБЫЕ ЗАВИСИМОСТИ И СЛОЖНЫЕ УЧАСТКИ
|
|
||||||
|
|
||||||
## Д1. Первоначальное развёртывание — устраняем «курица или яйцо»
|
|
||||||
|
|
||||||
Один бесплатный namespace содержит **полный login сервера доступа**, а сервер сам является user PDA. Поэтому при развёртывании чистого проекта придерживаться порядка:
|
|
||||||
|
|
||||||
1. Deploy тестовой `shine_users`, затем economy init.
|
|
||||||
2. Upgrade authority создаёт платный namespace, например `@shine`.
|
|
||||||
3. Создать **платный серверный аккаунт** с полным именем вроде `server@shine`, оформить ServerProfileBlock и адрес сервера.
|
|
||||||
4. Настроить в тестовом сервере публичный/временный приватный registrar key.
|
|
||||||
5. Upgrade authority создаёт `@free` type2, указывая public registrar key и **уже зарегистрированный** `server@shine`.
|
|
||||||
6. Синхронизировать namespaces/server account во всех тестовых серверах; только после этого открывать бесплатную регистрацию.
|
|
||||||
|
|
||||||
Иначе free-пользователи получат несуществующий access-server login и не смогут подключаться.
|
|
||||||
|
|
||||||
## Д2. Данные после перехода free → paid
|
|
||||||
|
|
||||||
Создание Solana PDA — это **изменение статуса идентичности**, не новое начало пользовательского блокчейна. В E2E сравнивать до/после как минимум: fullLogin, 3 ключа, hash последнего блока, количество/ID публикаций, каналов, связей, значение used bytes, доступность DM. Не менять `blockchain_name` произвольно.
|
|
||||||
|
|
||||||
## Д3. Консистентность подписей
|
|
||||||
|
|
||||||
`inner signature` подтверждает только идентичность (имя + 3 публичных ключа), а **не email**. Solana проверяет `inner_message`, а не внешний DataItem и не email hash. Сервер, импортирующий Arweave, проверяет **обе** подписи и наличие email hash. Изменение email hash без нового ANS-104 DataItem изменит внешнюю подпись/ID, но не внутреннюю; это ожидаемое разделение функций.
|
|
||||||
|
|
||||||
## Д4. Синхронизация Solana против Arweave
|
|
||||||
|
|
||||||
Источник on-chain регистрации — Solana PDA. Источник бесплатной регистрации — подписанный Arweave DataItem. Локальная PostgreSQL — **индекс и рабочая проекция**, не третий независимый источник правды. При рестарте восстанавливать один и тот же логический набор. До Arweave confirmation локальная видимость законна после Turbo ACK, но межсерверная не обязана быть мгновенной.
|
|
||||||
|
|
||||||
## Д5. Нельзя оставлять обход для free-ограничений
|
|
||||||
|
|
||||||
Не ограничиваться disabled-кнопками. Free identity должна быть read-only по части **ротируемых прав** во всех server-side обработчиках. Для платного пользователя управление изменениями выполняется через существующий Solana PDA; нужно проверять, что после upgrade не осталось fallback на старый free certificate как источник прав смены ключей.
|
|
||||||
|
|
||||||
## Д6. Legacy программы и история
|
|
||||||
|
|
||||||
В этой версии нет миграции старых коротких Solana логинов. Не удалять старые PDA «для чистоты», не пересоздавать production. Удаление `promo_seller` из новой логики не означает обязательного удаления существующих PDA в блокчейне или программы `shine_login_guard`; это отдельное решение.
|
|
||||||
|
|
||||||
## Д7. Правила, которые не стоит молча менять
|
|
||||||
|
|
||||||
- Цена едина для всех имён одного namespace, нет premium tiers.
|
|
||||||
- Подпись регистратора не включает email.
|
|
||||||
- Один физический источник подписи пока программный.
|
|
||||||
- Код подтверждения строго `1111` и явно маркирован тестовым.
|
|
||||||
- Namespace creation через upgrade authority, economy-init остаётся открытым.
|
|
||||||
- Нет исправления угрозы украденного registrar key.
|
|
||||||
- Не меняются три ключа, логин, пользовательская цепочка при upgrade.
|
|
||||||
- До upgrade сервер доступа определяется только namespace.
|
|
||||||
|
|
||||||
Если рабочий код требует продукта, меняющего эти правила, **остановиться только по конкретному архитектурному противоречию**, не изобретать новый продукт. Мелкие инженерные вопросы решать в соответствии с протоколом и фиксировать в документации.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Е. ПОШАГОВАЯ МАТРИЦА РЕЗУЛЬТАТОВ
|
|
||||||
|
|
||||||
| № | Выходной артефакт | Не начинать без | Минимальный тест готовности |
|
|
||||||
|---:|---|---|---|
|
|
||||||
| 0 | Исходный аудит и status file | Архив/репо | baseline и карта SQL зависимостей |
|
|
||||||
| 1 | Протокол + fixtures | 0 | одинаковые байты Rust/Java/JS |
|
|
||||||
| 2 | create namespace + authority | 1 | 2 namespace, чужой signer отклонён |
|
|
||||||
| 3 | Solana register 2 types | 2 | on-chain create paid/free-upgrade |
|
|
||||||
| 4 | JS codecs, tx builder | 3 | сериализация, реальные Solana tests |
|
|
||||||
| 5 | Unified PostgreSQL identity | 1, 3 | free identity без fake PDA |
|
|
||||||
| 6 | Sync Solana | 3, 5 | snapshot/history = одинаковая БД |
|
|
||||||
| 7 | Registrar signer stub | 1, 5, 6 | 2 подписи валидны |
|
|
||||||
| 8 | Arweave registration importer | 5–7 | локально сразу, второй сервер потом |
|
|
||||||
| 9 | WS free registration API | 7–8 + API approval | успешный WS flow |
|
|
||||||
| 10 | Auth/free permissions | 5, 8, 9 | login works, rotation blocked |
|
|
||||||
| 11 | UI registration | 4, 9, 10 | free и paid через браузер |
|
|
||||||
| 12 | UI upgrade | 3, 4, 6, 10, 11 | free→paid без новых данных |
|
|
||||||
| 13 | E2E / devnet / release checks | 0–12 | full regression suite |
|
|
||||||
|
|
||||||
**Условие завершения:** одно слово «готово» ничего не означает без доказанных тестов и списка изменённых файлов.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# Ж. СТАНДАРТНЫЙ ОТЧЁТ ПОСЛЕ КАЖДОГО ЭТАПА
|
|
||||||
|
|
||||||
В конце каждого этапа исполнитель обязан заполнить текст ниже и сохранить в `docs/registration-v2/IMPLEMENTATION_STATUS.md` (или приложить файл, если исходный репозиторий на этом этапе недоступен):
|
|
||||||
|
|
||||||
```text
|
|
||||||
SHiNE Registration V2 — журнал выполнения
|
|
||||||
Дата и время:
|
|
||||||
Базовая ветка / коммит / архив:
|
|
||||||
Этап №:
|
|
||||||
Статус: COMPLETED / PARTIAL / BLOCKED / NOT STARTED
|
|
||||||
|
|
||||||
1. Что было поручено:
|
|
||||||
2. Что реально изменено (полный список файлов):
|
|
||||||
3. Новые форматы / op codes / DB migrations / конфиги:
|
|
||||||
4. Команды сборки и тестов + результаты:
|
|
||||||
5. Ручная проверка и её фактический результат:
|
|
||||||
6. Что НЕ сделано или не проверено:
|
|
||||||
7. Совместимость с уже завершёнными этапами:
|
|
||||||
8. Обновлённые документы:
|
|
||||||
9. Коммит(ы) / diff / ссылка на патч:
|
|
||||||
10. Риски / открытые технические проблемы:
|
|
||||||
11. Следующий конкретный этап №:
|
|
||||||
12. Где следующий исполнитель должен начать чтение:
|
|
||||||
13. Нужны ли дополнительные разрешения по AGENTS.md:
|
|
||||||
|
|
||||||
Запрещено:
|
|
||||||
- считать partial этап завершённым;
|
|
||||||
- утверждать, что тесты прошли, если они не запускались;
|
|
||||||
- раскрывать секреты и реальные приватные ключи;
|
|
||||||
- деплоить production без согласования;
|
|
||||||
- менять формат пользовательских блоков незаметно;
|
|
||||||
- брать новую архитектуру «из головы» вместо этого документа.
|
|
||||||
```
|
|
||||||
|
|
||||||
**Контроль перед началом новой сессии:** открыть этот журнал, прочитать решения из раздела А, проверить статус этапов, продолжать с первого незавершённого этапа. Если исходник изменился, сначала обновить карту файлов и тестовые ожидания.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# З. КОНЕЧНАЯ ПРИЁМКА ПРОЕКТА
|
|
||||||
|
|
||||||
Работа завершена только если одновременно верно следующее:
|
|
||||||
|
|
||||||
- `[ ]` У каждого аккаунта формат полного логина `login@namespace`.
|
|
||||||
- `[ ]` Namespace-PDA обоих типов читаются любым сервером/клиентом.
|
|
||||||
- `[ ]` Namespace создаёт только действующая upgrade authority.
|
|
||||||
- `[ ]` Update economy контролируется upgrade authority; init economy остался публичным.
|
|
||||||
- `[ ]` PDA seed использует SHA-256, 32 сырых байта и полное имя.
|
|
||||||
- `[ ]` У paid direct есть полноценный PDA; цена берётся из namespace.
|
|
||||||
- `[ ]` Бесплатный DataItem содержит публичные ключи, две подписи и хеш email, но не секреты.
|
|
||||||
- `[ ]` Сертификат проходит внутреннюю Solana проверку и внешнюю ANS-104 проверку.
|
|
||||||
- `[ ]` Free user появляется локально после Turbo ACK без ожидания Arweave height.
|
|
||||||
- `[ ]` Другие серверы догоняют через Arweave sync, не создавая дублей.
|
|
||||||
- `[ ]` Free user реально входит и пользуется каналами/публикациями/связями/сообщениями.
|
|
||||||
- `[ ]` У free нельзя сменить ключи или access server через UI и через сервер.
|
|
||||||
- `[ ]` Free user платит за создание PDA, предъявляет сертификат и получает status paid.
|
|
||||||
- `[ ]` После upgrade сохраняются логин, три ключа, блокчейн, история, каналы, связи.
|
|
||||||
- `[ ]` Нет `shine_login_guard`/`promo_seller` в новом registration flow.
|
|
||||||
- `[ ]` Тестовые ошибочные подписи, суммы, seed, дубли и retry обрабатываются корректно.
|
|
||||||
- `[ ]` PostgreSQL migration/restart и Solana snapshot/history восстанавливают одинаковую картину.
|
|
||||||
- `[ ]` Документация соответствует Rust/Java/JS и текущему коду API.
|
|
||||||
- `[ ]` Тестовый стенд пройден; production не тронут без отдельного разрешения.
|
|
||||||
|
|
||||||
**Финальное правило:** если новая регистрация работает, но пользователь теряет прежние данные при upgrade, **патч не готов**. Сохранение единой личности — центральное требование всей работы.
|
|
||||||
@@ -0,0 +1,14 @@
|
|||||||
|
# Регистрация v2
|
||||||
|
|
||||||
|
Точка входа для работы с текущей реализацией регистрации. Сервер генерирует случайный шестизначный код подтверждения и отправляет письмо через Resend. Успешный ответ отправки письма сам по себе не завершает регистрацию: дальше нужны подтверждение кода, публикация сертификата и проверенный импорт.
|
||||||
|
|
||||||
|
| Тема | Действующий документ | Код |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| WS-операции | [индекс API](../API/09_Operations_Index.md), [контракт регистрации](WS_REGISTRATION_V2_API.md) | `JsonHandlerRegistry.java`, `Net_Registration_Handler.java` |
|
||||||
|
| Email и подтверждение | [настройка и проверка Resend](RESEND_EMAIL_VERIFICATION.md) | `FreeRegistrationWorkflow.java`, `RegistrationEmailCode.java` |
|
||||||
|
| Конфигурация регистратора | [параметры](REGISTRAR_CONFIGURATION.md) | `FreeRegistrationApiBootstrap.java` |
|
||||||
|
| Сертификат Arweave | [бинарный формат](../Протоколы/SHINE_FREE_REGISTRATION_CERTIFICATE_V1.md) | `FreeRegistrationCertificateV1.java` |
|
||||||
|
| Solana PDA | [namespace](../../shine-solana/shine/doc/formats/shine-namespace-pda-format-v1.md), [пользователь](../../shine-solana/shine/doc/formats/shine-user-pda-format-v.1.2.md) | `programs/shine_users/src/lib.rs` |
|
||||||
|
| UI регистрации | [три шага](REGISTRATION_UI_3_STEPS_2026-11-04.md) | `shine-UI/js/` |
|
||||||
|
|
||||||
|
[Отчёты и первоначальные планы](../Archive/registration-v2/README.md) сохранены отдельно. При реализации и сопровождении используйте действующие документы из таблицы и сверяйте их с кодом.
|
||||||
+5
-5
@@ -1,6 +1,6 @@
|
|||||||
# Регистрация V2: утверждённый API (23.10.2026)
|
# Регистрация V2: WebSocket API
|
||||||
|
|
||||||
**Статус:** код шести новых операций зарегистрирован в `JsonHandlerRegistry` по явному согласованию владельца. Не означает успешную проверку devnet или разрешение на production.
|
**Статус:** шесть операций зарегистрированы в `JsonHandlerRegistry`. Доступность полного сценария зависит от конфигурации регистратора, Resend, Turbo и синхронизации; регистрацию на конкретном контуре нужно проверять отдельно.
|
||||||
|
|
||||||
Общий транспорт: `{"op":"...","requestId":"...","payload":{...}}` и `{"op":"...","requestId":"...","status":200,"ok":true,"payload":{...}}`.
|
Общий транспорт: `{"op":"...","requestId":"...","payload":{...}}` и `{"op":"...","requestId":"...","status":200,"ok":true,"payload":{...}}`.
|
||||||
|
|
||||||
@@ -10,13 +10,13 @@
|
|||||||
| `CheckRegistrationLogin` | `fullLogin` | `loginAvailable,namespaceType,minLocalLength,registrationFeeLamports` | после логина/пароля, до генерации ключей |
|
| `CheckRegistrationLogin` | `fullLogin` | `loginAvailable,namespaceType,minLocalLength,registrationFeeLamports` | после логина/пароля, до генерации ключей |
|
||||||
| `CheckRegistrationEmail` | `email` | `emailAvailable` | отдельный экран email |
|
| `CheckRegistrationEmail` | `email` | `emailAvailable` | отдельный экран email |
|
||||||
| `StartFreeRegistration` | `fullLogin,rootPublicKeyB64,blockchainPublicKeyB64,clientPublicKeyB64,email` | `challengeId,expiresAtMs` | создание временной заявки |
|
| `StartFreeRegistration` | `fullLogin,rootPublicKeyB64,blockchainPublicKeyB64,clientPublicKeyB64,email` | `challengeId,expiresAtMs` | создание временной заявки |
|
||||||
| `ConfirmFreeRegistration` | `challengeId,code` (учебное `1111`) | `fullLogin,dataItemId,publicationStatus,chainConfirmed:false` | выпуск+Turbo ACK+локальный импорт |
|
| `ConfirmFreeRegistration` | `challengeId,code` (случайный шестизначный код из письма) | `fullLogin,dataItemId,publicationStatus,chainConfirmed:false` | выпуск+Turbo ACK+локальный импорт |
|
||||||
| `GetRegistrationStatus` | `fullLogin` | `registrationStatus,dataItemId,publicationStatus`; для FREE_CERT дополнительно `innerSignature64B64,rootPublicKey,blockchainPublicKey,clientPublicKey,defaultServerLogin` | retry/upgrade |
|
| `GetRegistrationStatus` | `fullLogin` | `registrationStatus,dataItemId,publicationStatus`; для FREE_CERT дополнительно `innerSignature64B64,rootPublicKey,blockchainPublicKey,clientPublicKey,defaultServerLogin` | retry/upgrade |
|
||||||
|
|
||||||
`registrationFeeLamports` — строка десятичного целого u64. Публичные ключи запроса — Base64 от ровно 32 байт (не PKCS#8). `innerSignature64B64` — Base64 внутренней подписи Ed25519, публичная информация сертификата; PRIVATE-ключ регистратора никогда не отдаётся.
|
`registrationFeeLamports` — строка десятичного целого u64. Публичные ключи запроса — Base64 от ровно 32 байт (не PKCS#8). `innerSignature64B64` — Base64 внутренней подписи Ed25519, публичная информация сертификата; PRIVATE-ключ регистратора никогда не отдаётся.
|
||||||
|
|
||||||
**Ошибки:** `REGISTRATION_UNAVAILABLE` 503, `INVALID_REGISTRATION_INPUT` 400, `REGISTRATION_CONFLICT` 409, `RATE_LIMITED` 429, прочие 500 требуют анализа логов без раскрытия секретов. Проверка логина и email *не резервирует* их; перед подписью и перед импортом делается повторная проверка.
|
**Ошибки:** `REGISTRATION_UNAVAILABLE` 503, `INVALID_REGISTRATION_INPUT` 400, `REGISTRATION_CONFLICT` 409, `RATE_LIMITED` 429, прочие 500 требуют анализа логов без раскрытия секретов. Проверка логина и email *не резервирует* их; перед подписью и перед импортом делается повторная проверка.
|
||||||
|
|
||||||
**Ограничения приватности:** публичный boolean `emailAvailable` допускает подбор адресов. Действует глобальный/per-WebSocket счётчик запросов; пересоздание WebSocket может обходить персональную квоту, перед production нужен rate limit на edge по IP/ASN и CAPTCHA, плюс переход с тестового кода на реальное подтверждение email. Учебный код `1111` не означает подтверждения владения адресом.
|
**Ограничения приватности:** публичный boolean `emailAvailable` допускает подбор адресов. Действует глобальный/per-WebSocket счётчик запросов; пересоздание WebSocket может обходить персональную квоту, перед production нужен rate limit на edge по IP/ASN и CAPTCHA, а также контроль доставки и хранения email-кода. Код генерируется случайно и отправляется через Resend. См. `RESEND_EMAIL_VERIFICATION.md`.
|
||||||
|
|
||||||
**Ограничения надёжности:** challenge и единожды подписанные bytes пока живут в памяти сервера не более 15 минут. Если сервер перезапущен после Turbo ACK, пользователь проверяет `GetRegistrationStatus`, но повтор той же challenge невозможен. Для production нужна долговечная очередь заявок/подписанных артефактов с защитой от повторного выпуска.
|
**Ограничения надёжности:** challenge и единожды подписанные bytes пока живут в памяти сервера до 1 часа (`FreeRegistrationWorkflow.TTL_MS`). Если сервер перезапущен после Turbo ACK, пользователь проверяет `GetRegistrationStatus`, но повтор той же challenge невозможен. Для нескольких инстансов нужна общая очередь заявок/подписанных артефактов с защитой от повторного выпуска.
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
# SHiNE — сертификат бесплатной регистрации V1
|
# SHiNE — сертификат бесплатной регистрации V1
|
||||||
|
|
||||||
Статус: бинарный протокол для отдельного ANS-104 DataItem `t=reg`; регистрация и импорт Java появятся в последующих этапах. В текущем патче готова Solana-проверка **внутренней** подписи при upgrade, а не выпуск сертификатов сервером.
|
Статус: формат отдельного ANS-104 DataItem `t=reg`. В коде есть выпуск сертификата, публикация через Turbo, локальный импорт и проверка внутренней подписи при upgrade. Это описание формата; готовность сквозного сценария на конкретном контуре проверяется отдельно.
|
||||||
|
|
||||||
## Байты и нормализация
|
## Байты и нормализация
|
||||||
|
|
||||||
@@ -16,7 +16,7 @@ payload = identity_fields || inner_signature64 || email_sha256:32
|
|||||||
|
|
||||||
Порядок ключей фиксирован: **root → blockchain → client**. Регистратор не имеет доступа к приватным ключам пользователя. Адрес public key регистратора хранится в namespace-PDA типа 2. Подделка любого байта identity приводит к отказу.
|
Порядок ключей фиксирован: **root → blockchain → client**. Регистратор не имеет доступа к приватным ключам пользователя. Адрес public key регистратора хранится в namespace-PDA типа 2. Подделка любого байта identity приводит к отказу.
|
||||||
|
|
||||||
Нормализация email: удалить пробелы только по краям (`trim`), Unicode NFC, lowercase независимо от locale; **не** удалять `+tag` и точки. `email_sha256=SHA256(UTF8(normalized_email))` публикуется после внутренней подписи, **не входит в `inner_message`**. Это обычный SHA-256, допускающий словарный подбор email; не обеспечивает полной анонимности. В тестовом UI код `1111` и явно сказано, что письма нет и владение email не подтверждается.
|
Нормализация email: удалить пробелы только по краям (`trim`), Unicode NFC, lowercase независимо от locale; **не** удалять `+tag` и точки. `email_sha256=SHA256(UTF8(normalized_email))` публикуется после внутренней подписи, **не входит в `inner_message`**. Это обычный SHA-256, допускающий словарный подбор email; не обеспечивает полной анонимности. Текущая проверка email использует случайный шестизначный код и письмо через Resend; детали и тестовый обход описаны в [инструкции по email](../registration-v2/RESEND_EMAIL_VERIFICATION.md).
|
||||||
|
|
||||||
## ANS-104 внешний контейнер
|
## ANS-104 внешний контейнер
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,55 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""Проверка локальных ссылок документации и индекса публичных WS-операций."""
|
||||||
|
from pathlib import Path
|
||||||
|
import re
|
||||||
|
import sys
|
||||||
|
from urllib.parse import unquote
|
||||||
|
|
||||||
|
ROOT = Path(__file__).resolve().parents[1]
|
||||||
|
DOCS = ROOT / 'docs'
|
||||||
|
REGISTRY = ROOT / 'SHiNE-server/shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/JsonHandlerRegistry.java'
|
||||||
|
INDEX = DOCS / 'API/09_Operations_Index.md'
|
||||||
|
LINK = re.compile(r'\[[^\]]+\]\(([^)]+)\)')
|
||||||
|
OP = re.compile(r'Map\.entry\("([A-Za-z0-9_]+)"')
|
||||||
|
INDEX_OP = re.compile(r'^\| `([A-Za-z0-9_]+)` \|', re.MULTILINE)
|
||||||
|
|
||||||
|
|
||||||
|
def check_links():
|
||||||
|
errors = []
|
||||||
|
files = [ROOT / 'README.md', ROOT / 'AGENTS.md', ROOT / 'deploy/README.md', *DOCS.rglob('*.md')]
|
||||||
|
for page in files:
|
||||||
|
for raw in LINK.findall(page.read_text(encoding='utf-8')):
|
||||||
|
target = unquote(raw.strip('<>').split('#', 1)[0].split('?', 1)[0])
|
||||||
|
if not target or '://' in target or target.startswith(('mailto:', '/')):
|
||||||
|
continue
|
||||||
|
if not (page.parent / target).exists():
|
||||||
|
errors.append(f'{page.relative_to(ROOT)}: отсутствует {target}')
|
||||||
|
return errors
|
||||||
|
|
||||||
|
|
||||||
|
def check_operations():
|
||||||
|
source = REGISTRY.read_text(encoding='utf-8')
|
||||||
|
source = '\n'.join(line for line in source.splitlines() if not line.lstrip().startswith('//'))
|
||||||
|
handlers_part, request_part = source.split('private static final Map<String, Class<? extends Net_Request>> REQUEST_TYPES', 1)
|
||||||
|
handlers = set(OP.findall(handlers_part))
|
||||||
|
requests = set(OP.findall(request_part))
|
||||||
|
documented = set(INDEX_OP.findall(INDEX.read_text(encoding='utf-8')))
|
||||||
|
return ([f'Нет request type для WS-операции: {op}' for op in sorted(handlers - requests)]
|
||||||
|
+ [f'Нет handler для request type: {op}' for op in sorted(requests - handlers)]
|
||||||
|
+ [f'Нет в индексе API: {op}' for op in sorted(handlers - documented)]
|
||||||
|
+ [f'Нет в реестре WS: {op}' for op in sorted(documented - handlers)])
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
errors = check_links() + check_operations()
|
||||||
|
for error in errors:
|
||||||
|
print(error, file=sys.stderr)
|
||||||
|
if errors:
|
||||||
|
print(f'Ошибок документации: {len(errors)}', file=sys.stderr)
|
||||||
|
return 1
|
||||||
|
print('Ссылки документации и индекс WS-операций согласованы с файлами проекта.')
|
||||||
|
return 0
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == '__main__':
|
||||||
|
raise SystemExit(main())
|
||||||
Reference in New Issue
Block a user