Обновлён server UI и приватные ключи переведены в base58

2026-06-02 15:52:22 +04:00
parent 67f882b9bc
commit a06b76b800
14 changed files with 2277 additions and 5 deletions
@@ -0,0 +1,82 @@
+# AGENTS.md — shine-server-UI
+
+## Назначение
+
+`shine-server-UI/` — автономная веб-панель администратора для управления серверным аккаунтом SHiNE
+в Solana (регистрация и обновление `user_pda` с флагом `is_server=true`).
+
+Это не часть основного клиентского SPA (`shine-UI/`). Страницы — самостоятельные HTML-файлы,
+открываемые напрямую в браузере. Никакого бэкенда нет.
+
+## Структура файлов
+
+```
+shine-server-UI/
+  index.html               — главная страница с навигацией
+  create-server-pda.html   — регистрация нового серверного аккаунта
+  update-server-pda.html   — обновление адреса/sync_servers существующей PDA
+  styles.css               — тёмная тема
+  js/
+    server-pda-core.js     — вся логика: парсинг PDA, Borsh, криптография, Solana
+```
+
+## Как пользоваться
+
+### Регистрация сервера (`create-server-pda.html`)
+
+Открыть страницу в браузере (требуется HTTPS для WebCrypto — локально либо через сервер).
+
+Ввести:
+- **Логин сервера** — уникальный логин в Solana (только a-z, 0-9, _ ; без точки ; макс. 20 символов).
+- **Адрес сервера** — полный WebSocket/HTTP URL, например `https://shineup.me/ws`.
+- **sync_servers** — логины SHiNE-аккаунтов серверов-партнёров (по одному на строку).
+
+**Способ ввода ключей (переключатель):**
+
+- **«Из пароля»** — ввести пароль. Ключи автоматически выводятся из логина + пароля
+  по той же схеме, что SHiNE-клиент (Argon2id + Ed25519). Занимает 2–5 сек.
+  На страницах сервера публичные и приватные ключи показываются в base58, приватный ключ
+  хранится как 32-байтовый seed в base58.
+- **«JSON ключей»** — вставить keyBundle JSON с тремя парами (rootPair, devicePair, blockchainPair).
+
+На **device-ключе** должно быть достаточно SOL для оплаты транзакции регистрации.
+
+### Обновление настроек сервера (`update-server-pda.html`)
+
+1. Ввести логин и нажать **«Загрузить PDA»** — страница прочитает существующую PDA из Solana и
+   покажет текущие данные.
+2. Изменить адрес сервера или список sync_servers.
+3. Выбрать способ ввода ключей:
+   - **«Из пароля»** — ввести пароль (логин берётся из поля выше);
+   - **«JSON ключей»** — вставить keyBundle (достаточно rootPair + devicePair).
+   Blockchain-ключ для обновления не нужен — существующая подпись из PDA переиспользуется.
+   При ручном вводе допустим base58 seed; если blockchain seed не указан, обновление
+   использует уже сохранённую подпись последнего блока.
+4. Нажать **«Обновить PDA»**.
+
+## Ключевой файл логики
+
+`js/server-pda-core.js` — автономный ES-модуль (без зависимостей на shine-UI).
+
+Экспортирует:
+- `readServerPdaData({ login, solanaEndpoint })` — читает и парсит PDA из Solana;
+- `registerServerOnSolana({ login, keyBundle, serverAddress, syncServers, ... })`;
+- `updateServerOnSolana({ login, keyBundle, serverAddress, syncServers, ... })`;
+- `parsePdaData(rawBytes)` — парсит бинарный формат PDA (matches Rust `deserialize_record_from_pda`).
+
+## Связанные документы
+
+- Формат PDA: `shine-solana/shine/doc/SHiNE-user-format-v.1.0.md`
+- Деплой Solana-программ: `Dev_Docs/Инициализация_Solana_регистрации/README.md`
+- Синхронизация между серверами: `Dev_Docs/Blockchain/sync-between-servers.md`
+- Настройки сервера: `SHiNE-server/AGENTS.md`
+
+## Правила при доработке
+
+- Формат Borsh-аргументов в `server-pda-core.js` должен строго соответствовать
+  `UserMutableFields` в `shine-solana/shine/programs/shine_users/src/users.rs`.
+- Бинарный формат PDA в `buildUnsignedRecordBytesServer` должен совпадать с
+  `serialize_unsigned_record` в Rust.
+- При любом изменении формата Solana-программы (`users.rs`) — обновлять `server-pda-core.js`
+  и документ формата PDA в том же коммите.
+- Язык кода и комментариев: русский.