Актуализировать документацию и навигацию для агентов

This commit is contained in:
AidarKC
2026-11-05 22:50:31 +03:00
parent 3c6021a290
commit 4f8c2a72e9
31 changed files with 315 additions and 927 deletions
+3 -3
View File
@@ -7,7 +7,7 @@
- `GetUser` — временная серверная проверка существования пользователя и чтение его базовых данных;
- `SearchUsers` — dev/test поиск логинов по префиксу, при необходимости с фильтром только по server PDA.
Регистрация выполняется только через Solana.
Регистрация платного аккаунта выполняется через Solana; для бесплатного namespace также зарегистрирован отдельный flow с email-кодом и сертификатом Arweave (см. раздел «Регистрация V2» ниже).
## Статус документа
@@ -170,12 +170,12 @@
- `GetUser` — проверка существования пользователя на сервере.
- `SearchUsers` — временный поиск пользователей по префиксу.
- Регистрация выполняется только через Solana.
- Регистрация платного аккаунта выполняется через Solana; для бесплатного namespace также зарегистрирован отдельный flow с email-кодом и сертификатом Arweave (см. раздел «Регистрация 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`.
Все бесплатные сертификаты подписаны ANS-104 и внутренней подписью Ed25519; успешный Turbo ACK не означает подтверждённую высоту Arweave. Клиент никогда не отправляет пароль или приватные ключи на сервер.
+18 -2
View File
@@ -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-состояние его блокчейна |
| `SearchUsers` | `01_User_Registration_API.md` | поиск логинов и публичных имён пользователей |
| `SearchChannels` | `06_Channels_Read_API.md` | поиск публичных каналов по названию, slug и логину владельца |
@@ -20,6 +26,13 @@
| `CreateAuthSession` | `02_Authentication_API.md` | создание новой авторизованной сессии |
| `SessionChallenge` | `02_Authentication_API.md` | challenge для входа в существующую сессию |
| `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` | чтение текущего режима входа через доверенное устройство |
| `UpsertTrustedDeviceLoginSettings` | `03_Session_Management_API.md` | включение/обновление pairing-настроек доверенной сессией |
| `StartTrustedDeviceLogin` | `03_Session_Management_API.md` | создание pairing-заявки для нового устройства |
@@ -56,6 +69,9 @@
| `GetMessageThread` | `06_Channels_Read_API.md` | тред сообщения |
| `GetMessageLikes` | `06_Channels_Read_API.md` | списки пользователей, поставивших лайк сообщению |
| `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` | счетчики разделов каналов |
| `SetChannelReadState` | `06_Channels_Read_API.md` | подписанный watermark чтения канала |
| `ListGroupChats200` | `06_Channels_Read_API.md` | список групповых чатов типа `200` |
@@ -93,7 +109,7 @@
- `ServerHello` пока принимает заявленный `serverLogin` на доверии и не является криптографической аутентификацией.
- 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`.
- Классы `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`.
@@ -106,7 +122,7 @@
- `ConfirmFreeRegistration` — подтверждение тестовым кодом и Turbo ACK;
- `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
+16
View File
@@ -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` из корня репозитория.
+37
View File
@@ -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,6 +4,8 @@
**Базовая версия:** `SHiNE-bundle-2026.10.23-12.36.02.zip` (SHA-256 `e2871bb11610437c354507dc9a723d64f14b0be4161af5f82d19f1466af648a6`)
**Исходная ветка/коммит:** не определены, потому что загруженный архив не содержит `.git`.
> **Статус документа:** исторический журнал этапов. Более поздние изменения кода здесь не всегда отражены. Сейчас сервер генерирует шестизначный код и отправляет его через Resend. Текущее поведение подтверждения описано в [RESEND_EMAIL_VERIFICATION.md](../../registration-v2/RESEND_EMAIL_VERIFICATION.md), а зарегистрированные WS-операции — в [индексе API](../../API/09_Operations_Index.md).
## Прогресс всех этапов (мастер-план V2, всего 14: 0–13)
| Этап | Название | Статус |
@@ -70,7 +72,7 @@
## 23 октября 2026: накопительный код этапов 8–10
- Этап 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 проверяют статус. Платные могут исполнять старый процесс.
- Реальные тесты сквозного сервера/DB/сети по-прежнему не проведены. Патч только для test/dev review; **НЕ деплоить на production**.
- Отчёт: `PATCH_STAGES_8_9_10.md`.
@@ -79,7 +81,7 @@
## 23 октября 2026: накопительный патч с этапами 9 и 11–13
- **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.
- **13:** добавлены контрактные тесты и smoke-runbook; полноценный E2E отложен до доступных Rust/Gradle/PostgreSQL/Turbo сетей.
- **Не готово:** `cargo`, full Gradle, PostgreSQL migration v33/v34, реальные WS, Turbo ACK, Solana localnet, браузер и межсерверный импорт. Все этапы **PARTIAL**, никакого production.
@@ -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 обновлены.
- Внутренняя Java-машина заявок сохраняет один подписанный ANS-104 DataItem на challenge, повторное подтверждение до TTL использует те же байты.
- Почтовый код `1111` учебный, факт владения email НЕ подтверждает.
- На момент этого патча подтверждение email было демонстрационным; текущий механизм отправки письма описан отдельно.
- Код ответа `TURBO_ACCEPTED` отличается от `ARWEAVE_CONFIRMED`.
- Введены базовые ограничения частоты запросов (30 на соединение и 1200 глобально за минуту); не заменяют IP/rate limiting на reverse proxy.
- Debug-логи регистрации редактированы, чтобы не записывать email/публичные ключи и содержимое challenge.
@@ -15,7 +15,7 @@
## Этап 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: итоговый экран входа и маршрутизация бесплатного пользователя не проверены.
@@ -1,6 +1,6 @@
# 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 **не выполнялся**.
**Этап 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 и отбрасывает искажения.
## Обязательные проверки, которые реально прошли
@@ -11,8 +11,8 @@
- **Проверить в реальной сети:** Arweave gateway / GraphQL фильтрация / root-range доступность и работу с несколькими серверами. Нет фактического Turbo upload и PostgreSQL integration; нельзя считать этап завершённым.
## 9 — WS API (подготовка, публичное API не изменено)
- Внутренний `FreeRegistrationWorkflow`: реестр namespace, precheck, 15-минутный временный challenge, `1111`, однократно сформированные raw bytes, тот же DataItem при повторе, status lookup.
- См. `WS_REGISTRATION_V2_PROPOSED_NOT_ENABLED.md`. По правилу `AGENTS.md` точные имена/поля/ErrorCodes требуют отдельного подтверждения. `JsonHandlerRegistry`, сериализация новых публичных запросов и действующая документация `docs/API/` **не изменены**; обычным WS-клиентом пройти free регистрацию пока нельзя.
- Внутренний `FreeRegistrationWorkflow`: реестр namespace, precheck, временный challenge и демонстрационное подтверждение email, однократно сформированные raw bytes, тот же DataItem при повторе, status lookup.
- См. `WS_REGISTRATION_V2_API.md`. По правилу `AGENTS.md` точные имена/поля/ErrorCodes требуют отдельного подтверждения. `JsonHandlerRegistry`, сериализация новых публичных запросов и действующая документация `docs/API/` **не изменены**; обычным WS-клиентом пройти free регистрацию пока нельзя.
## 10 — единая авторизация и запреты free (частично)
- `RegistrationIdentityDAO.ResolvedIdentity` хранит источник, статус, namespace, root/blockchain/client keys, сервер доступа, `hasSolanaPda` (для FREE_CERT он false).
+9
View File
@@ -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`
Если старый текст противоречит текущим документам, проверяйте действующий код и обновляйте актуальную спецификацию, а не применяйте старый план как инструкцию.
@@ -16,7 +16,7 @@
- Обновлять или удалять namespace пока нельзя. Старую классификацию `shine_login_guard` и `promo_seller` исключаем из **новой** регистрации. Автоматическая миграция legacy пользователей не требуется; в других программах удалять лишнее без необходимости не нужно.
- Economy-PDA остаётся аккаунтом только для чтения во всех новых Solana-транзакциях регистрации и создания namespace, поскольку его история используется как источник транзакций для синхронизации. Цена регистрации берётся из namespace, а параметры лимитов — из economy.
- Бесплатный сертификат: бинарные версия, полный логин, root/client/blockchain **публичные** ключи, внутренняя Ed25519-подпись регистратора от этих полей, затем SHA-256 нормализованного email. Внешняя подпись ANS-104 DataItem — тем же ключом, но **это другая подпись от другого сообщения**. Email не включён во внутреннюю подпись. Приватные ключи пользователя нигде не публикуются и серверу не передаются.
- Пока email-подтверждение демонстрационное, фиксированный код `1111`; в интерфейсе явно указать «тестовый код, реального подтверждения владения почтой нет». Хеш email в Arweave публичен и может подбираться: это принятое ограничение тестовой схемы.
- Пока email-подтверждение демонстрационное, демонстрационный код; в интерфейсе явно указать «тестовый код, реального подтверждения владения почтой нет». Хеш email в Arweave публичен и может подбираться: это принятое ограничение тестовой схемы.
- Временный ключ регистратора (секрет) читается из конфигурации сервера/переменных окружения вне git. Не писать секрет в репозиторий, открытые настройки UI, журнал или лог. В перспективе интерфейс подписания отделяется на аппаратный регистратор.
- Система не реализует в этом патче защиту от компрометации ключа регистратора и отдельный аппаратный журнал. Однако обязательны проверки обычных подписей/полномочий и запрет перезаписи уже зарегистрированного логина.
- Бесплатным пользователям запрещены смена root/client/blockchain ключей, смена access-server и форки, меняющие ключи. Обычные операции публикации и работы с контентом остаются.
@@ -126,7 +126,7 @@
- Реализовать бинарный codec сертификата, строгий парсер, проверку ключа, двух подписей и namespace; внутренний Ed25519 подписывает только версию, полное имя и три публичных ключа. Внешняя ANS-104 подпись — весь DataItem с hash-email.
- Кодирующий модуль должен выдавать **точные сырые байты ANS-104 DataItem** плюс ID (а не просто JSON с полями). Публиковать через текущий Turbo uploader с отдельным тегом типа `free_registration`, не маскируя запись под обычный блок.
- Регистратор проверяет перед подписанием текущие локально синхронизированные логины, хеш email, поддерживаемый namespace и подходящий ключ; повторная выдача для уже зарегистрированного имени отклоняется. Это обычная корректность регистрации, а не разработка новой защиты от кражи ключа.
- Код `1111` — только временный сценарий тестирования; UI должен прямо сообщать, что письмо не отправляется.
- Демонстрационный код — только временный сценарий тестирования; UI должен прямо сообщать, что письмо не отправляется.
**Тесты:** корректный DataItem проходит внешний/внутренний verify, изменение даже одного бита отбрасывается, секрет не попадает в логи/JSON, email не входит во внутреннюю подпись, отсутствие сертификата не заменяется «доверяем JSON».
@@ -173,7 +173,7 @@
- На первом шаге предложить «Регистрация через Solana» и «Бесплатная регистрация»; показывать только namespace соответствующего типа, загруженные из синхронизированного on-chain реестра.
- Поля логин (часть до `@`), namespace (dropdown), итоговое полное имя, цена в SOL, минимальная/максимальная длина, занятость; убрать premium/promo UI.
- Платный сценарий: генерация ключей от **полного логина**, существующая страница оплаты, новая Solana-транзакция, сохранение ключей и авторизация.
- Бесплатный: локальная генерация тех же трёх ключей → email → тестовый код `1111` → запрос серверу на сертификат+Turbo → локальное принятие → автоматический вход; при сетевой ошибке не перегенерировать ключи и не терять черновик.
- Бесплатный: локальная генерация тех же трёх ключей → email → демонстрационный код → запрос серверу на сертификат+Turbo → локальное принятие → автоматический вход; при сетевой ошибке не перегенерировать ключи и не терять черновик.
- В аккаунте free отображать статус, отсутствие Solana PDA, закреплённый сервер, блокировку ключей и CTA «Зарегистрировать в Solana». Показать реальные lamports/SOL из namespace.
- Upgrade использует существующие локальные приватные ключи; отправляет сертификат (внутреннюю подпись) и оплачивает тот же логин. После подтверждения меняет только статус и разрешения, не создаёт новые ключи и новый блокчейн.
- Удалить все остатки promo code UI, старой проверки premium и guard; обновить FAQ, ошибки, экран входа по полному имени.
@@ -220,7 +220,7 @@
- `ArweaveBlockSyncService` сейчас фильтрует записи по `block.height` и импортирует обычные блоки; сертификаты идут другой веткой и локальной немедленной обработкой.
- Текущая Solana-логика create привязывает `created_at_ms` к текущему времени; это обязательно учесть для старых бесплатных блокчейнов на этапе upgrade.
- На разных серверах нельзя считать «в какой последовательности я скачал DataItem» окончательным глобальным порядком. Даже если коллизии выдачи исключены организационно, безопасный импорт обязан проверять подписанта, и не должен заменять уже установленную идентичность произвольной повторной записью.
- Заявление «один email на всю SHiNE» при фиксированном коде `1111` означает уникальность **указанной строки email**, но не подтверждает владение почтовым ящиком. При задержке межсерверной синхронизации невозможно гарантировать идеальную моментальную глобальную блокировку без общего авторитетного регистратора; нынешняя схема предусматривает один регистратор.
- Заявление «один email на всю SHiNE» в первоначальном плане означает уникальность **указанной строки email**, но не подтверждает владение почтовым ящиком. При задержке межсерверной синхронизации невозможно гарантировать идеальную моментальную глобальную блокировку без общего авторитетного регистратора; нынешняя схема предусматривает один регистратор.
- Экономический PDA в read-only accounts сохраняет **поиск через history/signatures**. Одно лишь чтение не обязано порождать account-change notification; периодический poll/snapshot уже существует, и остаётся.
- Проверка upgrade authority требует корректной работы с account `ProgramData`, а не сравнения с исполняемым Program ID и не обычного owner поля PDA.
@@ -12,7 +12,7 @@
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 и сохраняемые связи/каналы.
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, отсутствие дубликатов.
7. У Bob создать сообщения и канал, затем Solana upgrade; сравнить login, три ключа, хеш цепи, число блоков, каналы, used bytes, DM, доступ до/после. Если хоть один отличается — release blocked.
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` — виды блокчейнов и логические линии внутри цепочки.
- `10_TECH_Blocks.md` — системные блоки (`type=0`).
- `11_TEXT_Blocks.md` — текстовые блоки (`type=1`).
+14 -7
View File
@@ -2,13 +2,20 @@
Актуальная версия пользовательского 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 и обратный импорт между серверами.
- [`sync-between-servers.md`](sync-between-servers.md) — межсерверная синхронизация и full-resync без файловой копии blockchain.
- [`CHANGELOG.md`](CHANGELOG.md) — история изменений протокола.
| Что нужно понять | Документ |
| --- | --- |
| Frame v1, ANS-104, подписи, хэши, теги | [Общий формат блока](01_Common_Block_Format.md) |
| Виды блоков и логические линии | [Индекс типов](00_Blockchain_Formats_and_Block_Types.md), [линии](02_Blockchain_Kinds_and_Lines.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 ещё не пройден.
- Регистрационные 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).
+20
View File
@@ -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 -10
View File
@@ -4,15 +4,9 @@
- Основной актуальный документ по личным сообщениям:
- `README.md`
- Его считать единственным источником истины по текущей реализованной логике DM.
- Его считать оглавлением действующей документации DM. Точные правила и форматы находятся в перечисленных там профильных документах.
## Черновик будущих вложений
## Сопровождение
- Файл `Черновик_будущих_DM_вложений.md` не является актуальной спецификацией.
- В нём описан только ранний черновик того, как когда-то планировались:
- формат вложений в DM;
- внешние и внутренние поля вложения;
- предполагаемая механика загрузки файлов.
- Эта схема не была реализована в таком виде и может существенно измениться в будущем.
- Любые решения по текущему коду, протоколу и UI нельзя принимать по этому черновику.
- Если есть расхождение между `README.md` и черновиком вложений, верным всегда считается `README.md`.
- При изменении DM обновлять затронутые документы из `README.md` в том же наборе изменений.
- Черновики и устаревшие версии не использовать как действующую спецификацию.
+2 -4
View File
@@ -12,13 +12,11 @@
- `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/Personal_Messages/Спецификация_DM_v0.5_устаревшая.md`
Документы с версиями `v1` и `v2` описывают разные уровни: `v1` — контейнер и доставка сообщения, `v2` — формат больших файлов внутри зашифрованного содержимого DM. Реализация `v2` находится в `shine-UI/js/services/dm-file-service.js` и `dm-tech-blocks.js`.
Правило сопровождения:
- код DM и оба документа `Протокол_DM_v1.md` + `Формат_DM_v1.md` всегда должны обновляться синхронно;
- код DM и затронутые документы из списка выше должны обновляться синхронно; если байтовый контейнер не менялся, это нужно прямо указать в описании изменения;
- если меняется поведение DM в коде, в том же наборе изменений обновляется и эта документация.
- локальная таблица пользователей для DM считается кэшем, а источником истины остаётся Solana PDA; если серверная логика DM меняет правила lazy-import пользователей из PDA, это тоже обязательно фиксируется в документации.
+23
View File
@@ -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).
+12 -11
View File
@@ -1,23 +1,24 @@
# Архитектура Solana-программ SHiNE
Документ описывает рабочую архитектуру Solana-части SHiNE: три Anchor-программы, DAO, ключи управления, PDA-счета и движение денег.
Документ описывает архитектуру трёх Solana-программ SHiNE, DAO, ключи управления, PDA-счета и движение денег. Текущие `shine_users` и `shine_payments` имеют собственный обработчик инструкций на Rust; не следует считать все три программы Anchor-программами.
Это архитектурная справка. Она не меняет код, формат PDA-записи пользователя, серверный API или формат блокчейна SHiNE.
Статус: актуализировано по коду `shine-solana/shine/programs/*` на 2026-05-25.
Статус: обзорная справка. Состав инструкций `shine_users`, program ID и seed сверен с кодом; экономические сценарии и фактическое состояние развёрнутых программ требуют отдельной проверки в сети.
Связанные документы:
- `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/FUNDS_FLOW.md` — короткая справка по денежным потокам внутри Solana-модуля.
- `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.2.md` — текущий формат `user_pda` для `shine_users`; версия v1.0 сохранена как историческая.
- `shine-solana/shine/doc/formats/shine-namespace-pda-format-v1.md` — формат namespace PDA.
- `shine-solana/shine/doc/FUNDS_FLOW.md` — справка по денежным потокам внутри Solana-модуля.
## Кратко
В Solana-модуле сейчас три основные программы:
1. `shine_login_guard` — в текущем временном режиме проверяет базовую валидность логина и пропускает on-chain любые валидные логины длиной от 5 символов.
2. `shine_users` — создает и обновляет пользовательскую PDA-запись, проверяет подписи и берет оплату за регистрацию/увеличение лимита.
2. `shine_users` — создаёт namespace и пользовательские PDA, проверяет подписи и обрабатывает оплату регистрации/увеличения лимита. В коде есть платный путь через Solana и upgrade бесплатного сертификата.
3. `shine_payments` — принимает входящий поток средств в `inflow_vault`, ведет очереди тикетов, позволяет DAO выдавать лимиты менеджерам и выполняет выплаты.
DAO в текущем виде не является отдельной Anchor-программой SHiNE внутри `programs/`. Это управляющая модель поверх кошельков, governance-скриптов и authority-адресов. Для проектирования ее удобно считать отдельным управляющим блоком: DAO голосует, назначает управляющие ключи, управляет казной и вызывает защищенные методы второй и третьей программ.
@@ -36,13 +37,13 @@ DAO в текущем виде не является отдельной Anchor-
| Блок | Папка/имя | Текущие функции из кода | Основной смысл |
| --- | --- | --- | --- |
| 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-настройки, лимиты менеджеров. |
| DAO | governance/authority | Вызовы через governance и управляющие ключи | Управление правами, казной, настройками и будущими обновлениями программ. |
## Актуальные program id
Актуальные адреса заданы одновременно в `Anchor.toml`, `declare_id!` программ и `programs/common/src/deploy_config.rs`:
Program ID в этом checkout заданы в `Anchor.toml` и `declare_id!` программ. Дополнительные константы и адреса в UI/сервере проверяйте по инструкции инициализации:
| Программа | Program ID |
| --- | --- |
@@ -54,8 +55,7 @@ DAO в текущем виде не является отдельной Anchor-
1. `shine-solana/shine/Anchor.toml`
2. `declare_id!` в `programs/*/src/lib.rs`
3. `programs/common/src/deploy_config.rs`
4. UI/серверные константы, перечисленные в `docs/Инициализация_Solana_регистрации/README.md`
3. константы и настройки UI/сервера, перечисленные в `docs/Инициализация_Solana_регистрации/README.md`
## Ключи и authority
@@ -81,14 +81,15 @@ DAO в текущем виде не является отдельной Anchor-
- DAO может добавлять и отзывать управляющие ключи по голосованию.
- 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 и счета:
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` — общие параметры экономики регистрации и лимита.
2. `shine_payments`
@@ -20,9 +20,9 @@
6. `manager_wallet` — кошелек менеджера, которому DAO выдает лимиты на создание тикетов.
7. `user root_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`:
- `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`.
`shine_payments`:
+2 -2
View File
@@ -1,11 +1,11 @@
# Дизайн SHiNE
Статус: направление выбрано, спецификация 0.2 от 22.09.2026. Основа — Ночной SHiNE; дневная тема — тёплая палитра; компактная шапка канала; полноэкранный ответ. У лайков только общий счётчик, оглавление в меню.
Статус: исторический дизайн-макет и спецификация 0.2 от 22.09.2026; соответствие текущему `shine-UI/` не проверено. Основа — Ночной SHiNE; дневная тема — тёплая палитра; компактная шапка канала; полноэкранный ответ. У лайков только общий счётчик, оглавление в меню.
- [Общий дизайн-документ](DESIGN.md) — актуальная спецификация выбранного стиля, обе темы, общие компоненты, сценарии и критерии приёмки.
- [Открыть исходную 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, **патч не готов**. Сохранение единой личности — центральное требование всей работы.
+14
View File
@@ -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) сохранены отдельно. При реализации и сопровождении используйте действующие документы из таблицы и сверяйте их с кодом.
@@ -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":{...}}`.
@@ -10,13 +10,13 @@
| `CheckRegistrationLogin` | `fullLogin` | `loginAvailable,namespaceType,minLocalLength,registrationFeeLamports` | после логина/пароля, до генерации ключей |
| `CheckRegistrationEmail` | `email` | `emailAvailable` | отдельный экран email |
| `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 |
`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 *не резервирует* их; перед подписью и перед импортом делается повторная проверка.
**Ограничения приватности:** публичный 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
Статус: бинарный протокол для отдельного 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 приводит к отказу.
Нормализация 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 внешний контейнер