Files
SHiNE-server/docs/registration-v2/WS_REGISTRATION_V2_API.md
T

3.8 KiB

Регистрация V2: WebSocket API

Статус: шесть операций зарегистрированы в JsonHandlerRegistry. Доступность полного сценария зависит от конфигурации регистратора, Resend, Turbo и синхронизации; регистрацию на конкретном контуре нужно проверять отдельно.

Общий транспорт: {"op":"...","requestId":"...","payload":{...}} и {"op":"...","requestId":"...","status":200,"ok":true,"payload":{...}}.

op Поля payload запроса Поля результата (payload) Когда нужен
GetNamespaces {} namespaces:[{name,type,minLocalLength,registrationFeeLamports,defaultServerLogin}] первый экран
CheckRegistrationLogin fullLogin loginAvailable,namespaceType,minLocalLength,registrationFeeLamports после логина/пароля, до генерации ключей
CheckRegistrationEmail email emailAvailable отдельный экран email
StartFreeRegistration fullLogin,rootPublicKeyB64,blockchainPublicKeyB64,clientPublicKeyB64,email challengeId,expiresAtMs создание временной заявки
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-кода. Код генерируется случайно и отправляется через Resend. См. RESEND_EMAIL_VERIFICATION.md.

Ограничения надёжности: challenge и единожды подписанные bytes пока живут в памяти сервера до 1 часа (FreeRegistrationWorkflow.TTL_MS). Если сервер перезапущен после Turbo ACK, пользователь проверяет GetRegistrationStatus, но повтор той же challenge невозможен. Для нескольких инстансов нужна общая очередь заявок/подписанных артефактов с защитой от повторного выпуска.