Files
SHiNE-server/docs/API/19_Key_Rotation_API.md
AidarKC 79598fffa6 Доделать смену ключей в новой версии
Добавлена доработка сценариев ротации ключей, закрытия сессий и повторного шифрования DM.

Версия пока не проверена полностью, но ожидается рабочей.
2026-10-06 18:42:55 +03:00

20 KiB
Raw Permalink Blame History

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

{
  "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

{
  "op": "KeyRotationStatus",
  "requestId": "kr-status-1",
  "payload": {}
}

Если активной ротации нет:

{
  "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

{
  "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

{
  "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

{
  "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 идемпотентен. Другая signature для уже начатого ROTATING_PDA возвращает 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 локально или пользователь явно пропускает перенос, затем вызывает:

{
  "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:

{
  "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'ами для безопасного восстановления.