SHA256
332 lines
20 KiB
Markdown
332 lines
20 KiB
Markdown
# Key Rotation API
|
||
|
||
> Протокольная семантика fork и target-ссылок: `docs/Blockchain/18_KEY_ROTATION_AND_FORK_TARGETS.md`.
|
||
> Физические fork имеют номера только `001..999`; из `*-999` следующая ротация blockchain key запрещена.
|
||
|
||
Этот раздел описывает публичные JSON/WebSocket операции мастера смены ключей пользователя.
|
||
|
||
Публично доступны:
|
||
|
||
- `KeyRotationStart`
|
||
- `KeyRotationStatus`
|
||
- `KeyRotationAddBlock`
|
||
- `KeyRotationFinishChain`
|
||
- `KeyRotationRotatePda`
|
||
- `KeyRotationContinue`
|
||
- `KeyRotationAbort`
|
||
|
||
После `PDA_ROTATED` отдельный фоновый worker автоматически переводит ротацию в `REBUILDING_SERVER`, делает новую candidate-chain единственной рабочей цепочкой PostgreSQL и затем переводит процесс в `WALLET_MIGRATION`.
|
||
|
||
## Общие правила
|
||
|
||
- операции доступны только авторизованному LOCAL-пользователю своего access server;
|
||
- login берётся из авторизованной сессии и не передаётся в payload;
|
||
- приватные ключи и пароли серверу не передаются никогда;
|
||
- в БД сохраняются только старые/новые публичные ключи;
|
||
- первая серверная запись появляется сразу в состоянии `COPYING_CHAIN`; состояния `PREPARING` в БД нет;
|
||
- во время `KeyRotationStart` сервер захватывает тот же per-blockchain lock, что использует обычный `AddBlock`, и фиксирует непротиворечивый source tip.
|
||
|
||
## `KeyRotationStart`
|
||
|
||
Создаёт новую серверную сессию ротации.
|
||
|
||
### Request
|
||
|
||
```json
|
||
{
|
||
"op": "KeyRotationStart",
|
||
"requestId": "kr-1",
|
||
"payload": {
|
||
"newRootKey": "<Base58 или Base64 публичного ключа 32B>",
|
||
"newBlockchainKey": "<Base58 или Base64 публичного ключа 32B>",
|
||
"newClientKey": "<Base58 или Base64 публичного ключа 32B>",
|
||
"forkFromBlock": 120,
|
||
"forkFromHash": "<64 hex>",
|
||
"reasonCode": 1,
|
||
"comment": "Плановая смена пароля"
|
||
}
|
||
}
|
||
```
|
||
|
||
`reasonCode`:
|
||
|
||
1. обычная ротация;
|
||
2. возможная компрометация;
|
||
3. подтверждённая компрометация / rollback;
|
||
4. recovery.
|
||
|
||
Сервер самостоятельно берёт из текущего PDA:
|
||
|
||
- `oldRootKey`;
|
||
- `oldBlockchainKey`;
|
||
- `oldClientKey`;
|
||
- текущий `sourceBlockchainName`.
|
||
|
||
Также сервер самостоятельно фиксирует текущий tip цепочки. Клиент не может подменить эти значения в запросе.
|
||
|
||
`forkFromBlock/forkFromHash` обязаны указывать на реально существующий блок текущей активной цепочки.
|
||
|
||
Новые root/blockchain/client keys должны быть валидными 32-байтовыми публичными ключами, отличаться от соответствующих старых ключей и друг от друга.
|
||
|
||
После успеха создаётся `key_rotation_sessions` со статусом `COPYING_CHAIN`. В сегментированной модели `progressTotal = 1`: публикуется только один новый `TECH_FORK` с номером `forkFromBlock + 1`; старый префикс `0..forkFromBlock` не перепубликуется.
|
||
|
||
### Success response
|
||
|
||
Ответ использует тот же payload состояния, что и `KeyRotationStatus`.
|
||
|
||
## `KeyRotationStatus`
|
||
|
||
Возвращает текущее состояние ротации авторизованного пользователя.
|
||
|
||
### Request
|
||
|
||
```json
|
||
{
|
||
"op": "KeyRotationStatus",
|
||
"requestId": "kr-status-1",
|
||
"payload": {}
|
||
}
|
||
```
|
||
|
||
Если активной ротации нет:
|
||
|
||
```json
|
||
{
|
||
"op": "KeyRotationStatus",
|
||
"requestId": "kr-status-1",
|
||
"status": 200,
|
||
"ok": true,
|
||
"payload": {
|
||
"rotationStatus": "NONE"
|
||
}
|
||
}
|
||
```
|
||
|
||
Если ротация есть, payload содержит:
|
||
|
||
- `rotationSessionId`;
|
||
- `rotationStatus`;
|
||
- `sourceBlockchainName` / `candidateBlockchainName`;
|
||
- старые и новые публичные root/blockchain/client keys;
|
||
- `forkFromBlock` / `forkFromHash`;
|
||
- `sourceTipBlock` / `sourceTipHash`;
|
||
- `reasonCode` / `comment`;
|
||
- `progressCurrent` / `progressTotal`;
|
||
- `pdaRotationSignature` (когда появится на последующем этапе);
|
||
- `walletMigrationStatus`;
|
||
- `messageMigrationStatus`;
|
||
- `lastError` / `retryCount`;
|
||
- `createdAtMs` / `updatedAtMs`.
|
||
|
||
Любая авторизованная сессия пользователя может читать этот статус. Состояние ротации принадлежит аккаунту, а не конкретному WebSocket-сеансу.
|
||
|
||
|
||
## `KeyRotationAddBlock`
|
||
|
||
Принимает единственный ANS-104 `TECH_FORK` будущего сегмента на этапе `COPYING_CHAIN`. Candidate-блок хранится отдельно от обычной таблицы `blocks`, поэтому до переключения fork он **не создаёт лайки, ответы, каналы, связи и другие materialized effects**.
|
||
|
||
### Request
|
||
|
||
```json
|
||
{
|
||
"op": "KeyRotationAddBlock",
|
||
"requestId": "kr-block-1",
|
||
"payload": {
|
||
"blockNumber": "<forkFromBlock+1>",
|
||
"prevBlockHash": "<forkFromHash>",
|
||
"blockBytesB64": "<полный ANS-104 TECH_FORK DataItem в Base64>"
|
||
}
|
||
}
|
||
```
|
||
|
||
Правила:
|
||
|
||
- операция доступна только при `rotationStatus=COPYING_CHAIN`;
|
||
- принимается только один `TECH_FORK` с номером `forkFromBlock + 1`; старые блоки `0..forkFromBlock` повторно не загружаются;
|
||
- каждый DataItem обязан быть подписан `newBlockchainKey`;
|
||
- последний блок обязан быть `TECH_FORK`, а его parent key, fork point, старый tip, reason/comment и число отброшенных блоков должны совпадать с `KeyRotationStart`;
|
||
- повтор уже принятого идентичного блока безопасен и возвращает success; другой DataItem/hash на том же номере возвращает conflict;
|
||
- candidate-блоки попадают в отдельную очередь Arweave/Turbo publisher-а и имеют приоритет перед обычными блоками;
|
||
- `progressCurrent` увеличивается **только после фактической успешной публикации** DataItem в Arweave/Turbo. Поэтому `KeyRotationStatus` показывает реальный прогресс публикации, а не только приём сервером.
|
||
|
||
### Основные ошибки
|
||
|
||
- `KEY_ROTATION_NOT_COPYING` — ротация не находится в `COPYING_CHAIN`;
|
||
- `KEY_ROTATION_BLOCK_OUT_OF_ORDER` — передан номер, отличный от `forkFromBlock + 1`;
|
||
- `KEY_ROTATION_BLOCK_CONFLICT` — на этом номере уже сохранён другой candidate-блок;
|
||
- `KEY_ROTATION_BAD_SIGNATURE` — DataItem подписан не новым blockchain key;
|
||
- `KEY_ROTATION_TECH_FORK_REQUIRED` — вместо финального `TECH_FORK` передан другой блок;
|
||
- ошибки `KEY_ROTATION_TECH_FORK_*` — поля `TECH_FORK` не соответствуют зафиксированной rotation session.
|
||
|
||
## Основные ошибки `KeyRotationStart`
|
||
|
||
- `AUTH_REQUIRED` — нет авторизованной сессии;
|
||
- `KEY_ROTATION_ALREADY_ACTIVE` — для login уже выполняется ротация;
|
||
- `KEY_ROTATION_BAD_FIELDS` — некорректные public keys/hash;
|
||
- `KEY_ROTATION_BAD_NEW_KEYS` — ключи не изменились либо новые ключи совпадают друг с другом;
|
||
- `KEY_ROTATION_BAD_REASON` — reason вне диапазона `1..4`;
|
||
- `KEY_ROTATION_COMMENT_TOO_LONG` — комментарий больше 1024 UTF-8 байт;
|
||
- `KEY_ROTATION_BAD_FORK_POINT` — неверная точка fork;
|
||
- `KEY_ROTATION_FORK_BLOCK_NOT_FOUND` — выбранный блок отсутствует;
|
||
- `KEY_ROTATION_FORK_HASH_MISMATCH` — переданный hash не совпадает с сервером;
|
||
- `KEY_ROTATION_SESSION_STALE` — авторизованная сессия содержит уже неактуальный blockchainName.
|
||
|
||
|
||
## `KeyRotationFinishChain`
|
||
|
||
Финализирует публикацию candidate `TECH_FORK`. Операция **не меняет PDA** и не переключает активную цепочку пользователя: она только доказывает, что новый сегмент уже имеет опубликованную точку входа в Arweave/Turbo.
|
||
|
||
### Request
|
||
|
||
```json
|
||
{
|
||
"op": "KeyRotationFinishChain",
|
||
"requestId": "kr-finish-chain-1",
|
||
"payload": {}
|
||
}
|
||
```
|
||
|
||
Перед переходом в `CHAIN_READY` сервер повторно проверяет:
|
||
|
||
- существует ровно один candidate-блок, соответствующий `progressTotal = 1`;
|
||
- каждый candidate-блок уже подтверждён Arweave/Turbo publisher-ом;
|
||
- `blockHash` и `DataItem id` совпадают с сохранёнными значениями;
|
||
- каждый DataItem подписан `newBlockchainKey`;
|
||
- единственный candidate-блок является корректным `TECH_FORK`, его `prevHash` равен hash выбранного fork point, а body повторяет зафиксированные parent key, fork point, parent tip, reason/comment и число отброшенных блоков.
|
||
|
||
Только после успешной финальной проверки выполняется:
|
||
|
||
`COPYING_CHAIN -> CHAIN_READY`.
|
||
|
||
Повторный `KeyRotationFinishChain`, когда ротация уже находится в `CHAIN_READY`, идемпотентно возвращает success. Это позволяет безопасно вызывать операцию из нескольких сессий или повторить её после потери ответа.
|
||
|
||
### Основные ошибки
|
||
|
||
- `KEY_ROTATION_NOT_ACTIVE` — активная ротация отсутствует;
|
||
- `KEY_ROTATION_NOT_COPYING` — текущий этап уже не позволяет завершать candidate-chain;
|
||
- `KEY_ROTATION_CHAIN_INCOMPLETE` — сервер получил не все candidate-блоки;
|
||
- `KEY_ROTATION_CHAIN_NOT_PUBLISHED` — не все DataItem подтверждены Arweave/Turbo publisher-ом;
|
||
- `KEY_ROTATION_BAD_SIGNATURE` — сохранённый `TECH_FORK` не подтверждается новым blockchain key;
|
||
- `KEY_ROTATION_TECH_FORK_*` — финальный `TECH_FORK` больше не соответствует rotation session;
|
||
- `KEY_ROTATION_FINISH_CHAIN_RACE` — состояние ротации было одновременно изменено другой операцией.
|
||
|
||
|
||
## `KeyRotationRotatePda`
|
||
|
||
Фиксирует, что клиент уже локально подписал и отправил в Solana транзакцию полной ротации PDA.
|
||
|
||
Сервер **не получает приватные ключи и не подписывает транзакцию**. Клиент передаёт только публичную Solana transaction signature.
|
||
|
||
### Request
|
||
|
||
```json
|
||
{
|
||
"op": "KeyRotationRotatePda",
|
||
"requestId": "kr-rotate-pda-1",
|
||
"payload": {
|
||
"pdaRotationSignature": "<Base58 Solana transaction signature>"
|
||
}
|
||
}
|
||
```
|
||
|
||
Операция разрешена только после `CHAIN_READY`. Сервер атомарно сохраняет signature и переводит:
|
||
|
||
`CHAIN_READY -> ROTATING_PDA`.
|
||
|
||
После этого отмена ротации уже запрещена: отправленная Solana-транзакция может подтвердиться позже, даже если клиент потерял соединение.
|
||
|
||
Подтверждением успешной ротации служит **не сам факт наличия signature**, а фактический current PDA, увиденный Solana sync. Sync требует одновременного совпадения:
|
||
|
||
- `rootKey == newRootKey`;
|
||
- `blockchainKey == newBlockchainKey`;
|
||
- `clientKey == newClientKey`;
|
||
- `blockchainName == candidateBlockchainName`.
|
||
|
||
Только после этого сервер атомарно переводит:
|
||
|
||
`ROTATING_PDA -> PDA_ROTATED`.
|
||
|
||
Если Solana sync успел увидеть новое PDA раньше вызова `KeyRotationRotatePda`, он умеет подтвердить ожидаемые ключи прямо из `CHAIN_READY`. Поэтому потеря клиентского запроса после уже подтверждённой Solana-транзакции не оставляет ротацию зависшей. Если API-вызов всё же приходит, handler идемпотентно возвращает текущее подтверждённое состояние.
|
||
|
||
Повтор с той же signature идемпотентен: при `PDA_ROTATED`, `REBUILDING_SERVER`, `WALLET_MIGRATION`, `MESSAGE_MIGRATION` и `FINALIZING` возвращается актуальное состояние без ошибки 409. Это закрывает гонку Solana sync с уведомлением UI. Если signature ранее сохранена, конфликтующая signature возвращает conflict.
|
||
|
||
### Основные ошибки
|
||
|
||
- `KEY_ROTATION_NOT_ACTIVE` — активной ротации нет;
|
||
- `KEY_ROTATION_NOT_CHAIN_READY` — candidate-chain ещё не подтверждена;
|
||
- `KEY_ROTATION_BAD_SOLANA_SIGNATURE` — signature отсутствует или не Base58;
|
||
- `KEY_ROTATION_PDA_SIGNATURE_CONFLICT` — для этой ротации уже сохранена другая signature;
|
||
- `KEY_ROTATION_ROTATE_PDA_FAILED` — внутренняя ошибка фиксации этапа.
|
||
|
||
|
||
## Автоматический rebuild после `PDA_ROTATED`
|
||
|
||
После подтверждения нового current PDA сервер сам выполняет:
|
||
|
||
`PDA_ROTATED -> REBUILDING_SERVER -> WALLET_MIGRATION`.
|
||
|
||
Во время rebuild:
|
||
|
||
- проверяется, что current PDA действительно указывает на `candidateBlockchainName/newBlockchainKey`;
|
||
- старая активная цепочка удаляется из рабочих PostgreSQL-таблиц;
|
||
- candidate-блоки повторно проходят обычный `AddBlock` validation/projection path;
|
||
- никакого rebind `to_bch_name` не выполняется: внешняя цель уже идентифицируется как `login + blockNumber + blockHash`;
|
||
- входящие `message_stats` не удаляются; для активных LIKE удаляемого пользователя точечно пересчитываются только затронутые like-счётчики; REPLY в Stage 2 отдельно не перерабатывается;
|
||
- после `COMPLETE` временные строки candidate-chain удаляются из PostgreSQL.
|
||
|
||
Если rebuild прерывается, `REBUILDING_SERVER` остаётся активным, ошибка записывается в `lastError/retryCount`, а worker безопасно повторяет rebuild.
|
||
|
||
## `KeyRotationContinue`
|
||
|
||
Продолжает post-PDA этапы после фактической клиентской работы. Сервер не хранит приватные ключи и сам не переводит средства и не расшифровывает DM.
|
||
|
||
### `WALLET_MIGRATION`
|
||
|
||
Клиент сначала выполняет перенос SOL локально или пользователь явно пропускает перенос, затем вызывает:
|
||
|
||
```json
|
||
{
|
||
"op": "KeyRotationContinue",
|
||
"requestId": "kr-continue-wallet",
|
||
"payload": {
|
||
"walletMigrationStatus": "COMPLETE"
|
||
}
|
||
}
|
||
```
|
||
|
||
Допустимые значения: `COMPLETE`, `SKIPPED`. После фиксации сервер переводит ротацию в `MESSAGE_MIGRATION`. Автоматически переносится только SOL; другие активы пользователь переносит вручную.
|
||
|
||
### `MESSAGE_MIGRATION`
|
||
|
||
Момент перехода в `MESSAGE_MIGRATION` становится cutoff текущей DM-миграции (`updatedAtMs` состояния). Клиент выбирает старые локальные копии через `GetDirectMessages` с `reencryptedBeforeMs=cutoff`, перешифровывает их старым/новым client key и сохраняет через `ReencryptDirectMessage`, выставляя `reencryptedAtMs=cutoff`.
|
||
|
||
После обхода клиент вызывает `KeyRotationContinue` с пустым payload. Сервер сам считает строки владельца с `message_type IN (1,2)`, `created_at_ms <= cutoff` и `reencrypted_at_ms < cutoff`. Если они ещё есть, возвращается `KEY_ROTATION_DM_PENDING`. Если нет — `message_migration_status=COMPLETE`, затем `FINALIZING -> COMPLETE`.
|
||
|
||
Эта схема позволяет безопасно продолжить после перезапуска: уже обновлённые сообщения больше не попадают в выборку. Новые сообщения, сохранённые после начала `MESSAGE_MIGRATION`, в текущую миграцию не включаются.
|
||
|
||
## `KeyRotationAbort`
|
||
|
||
Прерывает ротацию только пока Solana-ротация PDA ещё не могла быть отправлена:
|
||
|
||
- разрешено из `COPYING_CHAIN`;
|
||
- разрешено из `CHAIN_READY`;
|
||
- начиная с `ROTATING_PDA` отмена запрещена, процесс можно только довести вперёд.
|
||
|
||
Request:
|
||
|
||
```json
|
||
{
|
||
"op": "KeyRotationAbort",
|
||
"requestId": "kr-abort-1",
|
||
"payload": {}
|
||
}
|
||
```
|
||
|
||
При `ABORTED` временные candidate-строки удаляются из PostgreSQL. Уже опубликованные Arweave DataItem остаются неизменяемым сиротским историческим следом и не становятся активной цепочкой, поскольку PDA не переключён.
|
||
|
||
## Пользовательский flow key rotation (06.10.2026)
|
||
|
||
`KeyRotationStart` после успешного создания ротации в той же транзакции удаляет все остальные активные сессии пользователя, оставляя текущую. После commit активные WebSocket-подключения этих сессий получают `SessionRevoked` и закрываются.
|
||
|
||
Для пользователя подготовка `TECH_FORK` и последующая смена PDA выглядят как одна последовательность: если старый и новый наборы ключей ещё находятся в RAM, после `CHAIN_READY` клиент автоматически запускает Solana-ротацию без повторного ввода паролей. Серверные состояния остаются отдельными checkpoint'ами для безопасного восстановления.
|