Перенести документацию в docs и добавить социальный граф

docs/Keys/DERIVATION.md

@@ -0,0 +1,154 @@
+# Деривация секрета и ключей SHiNE (формулы)
+
+> **Статус: ИСТОЧНИК ИСТИНЫ (single source of truth) по конкретной деривации.**
+> Этот файл описывает, как из пароля получается секрет и как из секрета выводятся
+> все ключи (root, blockchain, device/Solana, homeserver) — формулами, байт-в-байт.
+> Если в коде меняется деривация (формула секрета, параметры Argon2id, соль, формула
+> ключа, разделитель `|`, набор/имена суффиксов, формат homeserver-ключа, связь
+> dev-ключ ↔ Solana-адрес) — **в том же изменении обязательно править этот документ**.
+> Роли и назначение ключей описаны отдельно в `Dev_Docs/Keys/README.md` (архитектура).
+> Здесь — только механика. Документ намеренно краткий.
+
+---
+
+## 1. Секрет (masterSecret)
+
+`masterSecret` — 32 байта. Два источника:
+
+**А. Из пароля пользователя (основной путь, UI).**
+
+```
+login    = trim(lowercase(login))
+salt     = SHA-256("shine-auth-v2|login=" + login + "|suffix=master.secret")[0..16)   // первые 16 байт
+material = utf8(login + "\n" + password)
+masterSecret(32) = Argon2id(material, salt, t=2, m=65536 KiB, p=1, dkLen=32)
+```
+
+- Параметры Argon2id фиксированы: `t=2`, `m=65536` (64 МиБ), `p=1`, `dkLen=32`.
+- Логин входит и в соль, и в начало `material` (склейка через `\n`).
+- Пустой пароль **запрещён**: легаси-fallback без Argon2 удалён, `deriveMasterSecretFromPassword` бросает ошибку на пустом пароле, а форма регистрации в UI блокирует пустой пароль (`register-view.js`).
+
+**Б. Случайный (прошивка ESP32, новый аккаунт без пароля).**
+
+```
+masterSecret(32) = 32 случайных байта (esp_random)   // хранится на устройстве как base58
+```
+
+Дальше деривация ключей одинакова независимо от источника секрета.
+
+---
+
+## 2. Производные ключи
+
+Все ключи выводятся из `masterSecret` по **одной формуле**, отличается только суффикс:
+
+```
+material    = base64_std(masterSecret) + "|" + <суффикс>
+seed(32)    = SHA-256(material)
+(pub, priv) = Ed25519_keypair_from_seed(seed)
+```
+
+- `base64_std` — стандартный base64 (не url-safe).
+- Разделитель — символ `|`.
+- Суффиксы значимы байт-в-байт (регистр и точки важны).
+
+| Ключ | Суффикс | Назначение (кратко) |
+|------|---------|---------------------|
+| root | `root.key` | Личность. Подписывает unsigned-часть PDA-записи (`RootKeyBlock`). |
+| blockchain | `bch.key` | Подписывает `LastBlockState` персонального блокчейна (`blockchain_public_key`). |
+| device / **Solana** | `client.key` | Ключ устройства = Solana-ключ. Fee payer и подпись Solana-транзакций; адрес кошелька = `base58(clientPub)`. См. §3. |
+| homeserver | `homeserver.key:<имя>` | Ключ homeserver-устройства, по одному на каждый homeserver (различитель — имя). См. §4. |
+
+Полные роли каждого ключа — в `Dev_Docs/Keys/README.md`.
+
+---
+
+## 3. Solana-ключ
+
+Отдельного «солана-ключа» нет. На Solana работают два ключа:
+
+- **`client.key` (device) — пополняемый кошелёк и fee payer.** Solana-адрес = `base58(clientPub)`.
+  Этим ключом оплачиваются и подписываются `create_user_pda` / `update_user_pda`.
+  Пополнять SOL нужно именно на этот адрес.
+- **`root.key` — авторитет записи**, подписывает unsigned-часть PDA через Ed25519-инструкцию, но **не** является fee payer.
+
+Соответствует формату PDA `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md` §2.1
+(«create/update оплачиваются с `client_key`», «root_key — не fee payer»).
+
+Кратко про роли на Solana: `root.key` — это **главный (master) ключ**: им управляют PDA-записью
+(`create/update`) и через это можно заменить все остальные ключи; `client.key` — это **пополняемый
+кошелёк и плательщик комиссий**. Полное описание ролей — `Dev_Docs/Keys/README.md`.
+
+---
+
+## 4. Ключи homeserver
+
+У пользователя может быть несколько homeserver-ов. Каждый имеет **своё имя** и **свой приватный ключ**,
+выведенный из секрета по той же формуле с именованным суффиксом:
+
+```
+suffix      = "homeserver.key:" + <имя homeserver>      // имя по умолчанию: "homeserver1"
+material    = base64_std(masterSecret) + "|" + suffix
+seed(32)    = SHA-256(material)
+(pub, priv) = Ed25519_keypair_from_seed(seed)
+```
+
+Пример для двух homeserver-ов:
+
+```
+homeserver.key:home-a   ->  ключ A
+homeserver.key:home-b   ->  ключ B
+```
+
+Публичный ключ homeserver-а публикуется в `SessionsBlock` пользовательской PDA как
+`session_pub_key` с `session_type = 100`, имя — в `session_name` (формат PDA §13).
+
+> Это переименование прежней схемы `subserver.key:<имя>` → `homeserver.key:<имя>`.
+> Термин «саб-сервер» по проекту заменяется на «homeserver».
+
+---
+
+## 5. Где это в коде
+
+### Деривация секрета и ключей (UI, каноническая)
+- `shine-UI/js/services/crypto-utils.js`
+  - секрет из пароля: `makeArgon2Salt`, `deriveMasterSecretArgon2id`, `deriveMasterSecretFromPassword` (~129–218);
+  - ключ из секрета: `deriveEd25519FromMasterSecret` (~220).
+- `shine-UI/js/services/auth-service.js` — набор root/bch/dev из `masterSecret` (~732–758).
+- `shine-UI/server-ui/js/server-ui-shared.js` — те же root/bch/dev для серверного UI (~147–160).
+
+### Solana-ключ / адрес кошелька (UI)
+- `shine-UI/js/pages/registration-payment-view.js` — `deriveUserWalletAddress`: адрес = `base58(clientPub)` (~113).
+- `shine-UI/js/pages/topup-view.js` — `clientWalletAddressFromBundle`: тот же канонический адрес из `preGeneratedKeyBundle.clientPair`.
+  Прежний расходящийся путь `deriveWalletFromPassword` (прямой Argon2 по `client.key`, мимо `masterSecret`) удалён.
+
+### Деривация ключей (прошивка ESP32)
+- `ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/main-device/shine_homeserver_main/shine_homeserver_main.ino`
+  - основной скетч ESP32-проекта `SHiNE`; `deriveKeysFromMasterSecret` (~782), `restoreDerivedKeysFromSecret` (~806), `deriveFreshSecretAndWallet` (~829);
+  - регистрация/подпись Solana: `registerHomeserverOnSolana` (~1182), `signMessageEd25519` (~1147).
+- `ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/main-device/shine_homeserver_ui/shine_homeserver_ui.ino`
+  - старый тестовый вариант; оставлен как legacy-скетч для сравнения и диагностики.
+
+### Формат PDA (куда попадают ключи)
+- `shine-solana/shine/doc/formats/shine-user-pda-format-v.1.0.md`
+  — `RootKeyBlock` §6, `ClientKeyBlock` §7, `blockchain_public_key` §9, `SessionsBlock`/`session_type=100` §13, оплата §2.1.
+
+### Сервер (тестовый seed)
+- `SHiNE-server/src/test/java/test/it/cases/SeedDataPopulationHelper.java` `deriveKeysFromPassword` (~246) —
+  выводит ключи как `Ed25519(SHA-256(base64(SHA-256(password)) + suffix))`, **без** Argon2 и **без** разделителя `|`.
+  Это **не баг**, а точное повторение легаси-пути UI `derivePasswordSeed` (для пустого пароля), у которого тоже нет `|`.
+  С современным путём `masterSecret`-bundle (Argon2 + `base64(secret)|suffix`) он **не совпадает** by design.
+  Если потребуется, чтобы seed совпадал с реальными клиентами на Argon2 — нужно отдельно портировать
+  Argon2id+masterSecret в Java (на сервере Argon2 сейчас нет). Простое добавление `|` было бы **неверным**:
+  сломало бы совпадение с легаси-путём и всё равно не дало бы совпадения с Argon2-путём.
+
+---
+
+## 6. Правило синхронизации (обязательно)
+
+1. Этот документ — источник истины по деривации секрета и ключей.
+2. Любое изменение кода, затрагивающее формулу секрета, параметры Argon2id, соль, формулу ключа,
+   разделитель `|`, набор/имена суффиксов, формат homeserver-ключа или связь dev-ключ ↔ Solana-адрес —
+   **обязательно** отражать здесь в том же изменении.
+3. Пункты, помеченные ⚠️, — это долг к устранению, а не норма.
+4. Нельзя сознательно оставлять код и этот документ в рассинхроне без отдельной явной договорённости.

docs/Keys/README.md

@@ -0,0 +1,177 @@
+# Ключи SHiNE
+
+Этот документ описывает роли ключей в SHiNE и их связь с Solana, персональным блокчейном, личными сообщениями, сессиями и будущими аппаратными устройствами.
+
+Документ является архитектурной справкой. Он не меняет текущие форматы API, DM-блоков или блокчейна сам по себе.
+
+## Коротко
+
+В SHiNE у пользователя есть несколько уровней ключей:
+
+- `root key` - главный (master) ключ пользователя: тот, кто им владеет, управляет пользовательской PDA в Solana и может заменить все остальные ключи. Это не пополняемый кошелёк (комиссии платит `client key`).
+- `blockchain key` - ключ записи в персональный SHiNE-блокчейн пользователя.
+- `client key` - общий ключ пользовательских устройств для повседневной работы, звонков, DM и мелких платежей.
+- `session key` - ключ конкретной сессии или конкретного устройства для авторизации на сервере.
+
+Главная идея: самые важные ключи можно держать на доверенном серверном или аппаратном устройстве, а обычные клиентские устройства получают только ключи, нужные для текущей работы.
+
+## `root key`
+
+`root key` - главный ключ пользователя.
+
+Назначение:
+
+- регистрация пользователя в Solana;
+- создание и обновление пользовательской PDA-записи;
+- вызов критически важных Solana-функций;
+- изменение главных настроек пользователя;
+- управление остальными ключами;
+- подтверждение операций, которые должны иметь максимальный уровень доверия.
+
+`root key` — это **главный (master) ключ** в следующем смысле: зная `root key`, можно управлять пользовательской PDA-записью в Solana (`create_user_pda` / `update_user_pda`) и тем самым **заменить все остальные ключи** пользователя (device, blockchain, homeserver). Поэтому компрометация `root key` равносильна компрометации всей личности пользователя.
+
+Важно не путать авторитет и кошелёк: `root key` — это авторитет над PDA-записью, а **SOL-комиссии за create/update платит `client key`** (он же fee payer и адрес для пополнения). Подробнее о том, какой ключ за что отвечает на Solana, — в `Dev_Docs/Keys/DERIVATION.md`, §3.
+
+## `blockchain key`
+
+`blockchain key` - ключ записи в персональный SHiNE-блокчейн пользователя.
+
+Назначение:
+
+- подпись записей в персональном блокчейне пользователя;
+- подтверждение действий, которые должны попасть в SHiNE-блокчейн;
+- разделение полномочий между главным Solana-ключом и ключом ежедневной записи.
+
+У пользователя может быть несколько персональных блокчейнов или веток. При смене `blockchain key` фактически создаётся новая ветка записи:
+
+- `username-001` - первая ветка;
+- `username-002` - вторая ветка;
+- `username-003` - третья ветка.
+
+Рабочая логика по умолчанию должна использовать последнюю актуальную ветку. Старые ветки остаются читаемыми и показывают историю смены ключей.
+
+## `client key`
+
+`client key` - общий ключ, который знают доверенные устройства пользователя.
+
+Назначение:
+
+- повседневные входящие и исходящие личные сообщения;
+- звонки и связанные с ними сообщения;
+- self-messages, то есть внутренние сообщения пользователя самому себе;
+- мелкие Solana-расходы на текущие операции;
+- derivation Arweave-кошелька;
+- оплата или подготовка добавления данных в Arweave-кошелек по отдельному протоколу.
+
+Arweave-кошелёк должен выводиться из `client key` по протоколу:
+
+- `Dev_Docs/Протоколы/SHINE_ARWEAVE_DERIVATION_V1.md`
+
+Если пользователь теряет только `client key`, в худшем случае ломается повседневная переписка и доступ конкретных устройств к ежедневным операциям. `root key` и `blockchain key` при правильной архитектуре остаются отдельно защищёнными.
+
+## `session key`
+
+`session key` - уникальный ключ конкретной сессии или устройства.
+
+Возможные форматы:
+
+- `Ed25519` - предпочтительный современный вариант;
+- `RSA` - legacy-вариант, полезный для устройств, где системное защищённое хранилище хорошо поддерживает RSA-ключи и не позволяет извлекать приватный ключ.
+
+Назначение:
+
+- авторизация сессии на сервере;
+- привязка устройства к пользователю;
+- подтверждение запросов от конкретной сессии;
+- доступ к зашифрованному `client key` после успешной авторизации.
+
+Одна и та же сессия может быть пригодна для подключения к нескольким серверам пользователя, если архитектура конкретного пользователя это допускает.
+
+У сессии должны быть:
+
+- имя сессии;
+- тип сессии;
+- публичная часть ключа;
+- ссылка на пользователя;
+- информация о сервере или серверах, которым эта сессия доверена.
+
+Имя сессии может создаваться автоматически из названия устройства и короткого случайного идентификатора, например `Android-a1b2c3`, `Ubuntu-f47a90`. Пользователь может переименовать сессию.
+
+## Типы сессий
+
+Базовые типы:
+
+- обычная пользовательская сессия;
+- серверная сессия;
+- аппаратная или доверенная сессия с доступом к расширенным ключам.
+
+Обычное устройство обычно имеет:
+
+- собственный `session key`;
+- зашифрованный `client key`, который открывается после авторизации;
+- доступ к DM, звонкам и обычным пользовательским операциям.
+
+Доверенное серверное или аппаратное устройство может иметь:
+
+- `root key`;
+- `blockchain key`;
+- `client key`;
+- собственный `session key`.
+
+Такая сессия может подписывать операции повышенной важности по запросам пользователя.
+
+## Внутренние self-messages
+
+Self-message - это сообщение пользователя самому себе.
+
+Такие сообщения нужны, чтобы обычное устройство могло попросить доверенное устройство выполнить действие:
+
+- подписать запись `blockchain key` и передать её в SHiNE-блокчейн;
+- подписать изменение настройки через `root key`;
+- обновить ключи;
+- сохранить внутреннюю команду или настройку;
+- отправить сообщение другому пользователю с сохранением копии себе;
+- сохранить сообщение только себе.
+
+Важно: self-message не является публичной командой сервера. Это пользовательская внутренняя команда, которую сервер или доверенное устройство обрабатывает в рамках прав конкретного пользователя.
+
+## Шифрование входящих сообщений
+
+Входящее сообщение может быть зашифровано:
+
+- `client key`;
+- `session key`;
+- отдельным ключом конкретного чата;
+- другим ключом, который уже известен клиенту.
+
+В сообщении не должно быть лишнего раскрытия того, каким именно ключом оно зашифровано. Клиент пробует расшифровать сообщение доступными ключами по порядку. Если расшифровка не удалась, сообщение остаётся непонятным для этого устройства.
+
+## Копии сообщений
+
+Для отправки сообщений нужны несколько режимов:
+
+- сообщение другому пользователю с исходящей копией себе;
+- сообщение другому пользователю без локальной исходящей копии;
+- сообщение только себе.
+
+Это должно позволить строить обычные DM, внутренние команды, личные заметки и зашифрованные пользовательские чаты поверх одной общей модели сообщений.
+
+## Связанные документы
+
+- `Dev_Docs/Keys/DERIVATION.md` - **источник истины по конкретной деривации** секрета и ключей (формулы Argon2id, `base64|suffix→SHA-256→Ed25519`, суффиксы `root.key`/`bch.key`/`client.key`/`homeserver.key:<имя>`, Solana-ключ, ссылки на код).
+- `Dev_Docs/Personal_Messages/Протокол_DM_v1.md` - текущая логическая документация личных сообщений.
+- `Dev_Docs/Personal_Messages/Формат_DM_v1.md` - точный байтовый формат личных сообщений.
+- `Dev_Docs/Blockchain/README.md` - точка входа по форматам SHiNE-блокчейна.
+- `Dev_Docs/Solana_Architecture/README.md` - архитектура Solana-программ, PDA-счетов, DAO и движения средств.
+- `Dev_Docs/Инициализация_Solana_регистрации/README.md` - деплой и первичная инициализация Solana-регистрации.
+- `Dev_Docs/Протоколы/SHINE_ARWEAVE_DERIVATION_V1.md` - derivation Arweave-кошелька из `client key`.
+
+## Что нужно уточнить перед реализацией
+
+- точный формат записи списка ключей в Solana PDA;
+- как именно обозначать активную ветку персонального блокчейна;
+- какие операции требуют `root key`, а какие достаточно подписывать `blockchain key`;
+- формат self-message-команд;
+- порядок перебора ключей при расшифровке входящих сообщений;
+- правила ротации `client key` и восстановления доступа после потери устройства;
+- какие типы серверных и аппаратных сессий нужны в первой реализации.