zorin-authority-sdk-ts — API

Экспортируемые функции

Функция	Результат
authorize(input, options?)	Promise<AuthorityRequest>; создание запроса и ожидание решения
parseAssertion(assertion)	AssertionPayload; разбор без проверки подписи
verifyAssertion(assertion, brokerPublicKeyPem, expected, now?)	Promise<AssertionPayload>; проверка broker и телефона

В опубликованной версии 0.1.0 это все функции корневого модуля. Криптографические вспомогательные функции внутренние.

AuthorizeInput и options

Обязательные поля input: projectId, origin, challenge, action, resource. Необязательные: message (по умолчанию пустая строка), ttlSeconds (90). Options содержит baseUrl (http://127.0.0.1:47475) и timeoutMs (70000).

POST /v1/authorize отправляет поля project_id, origin, challenge, action, resource, message, ttl_seconds. Ответ содержит request_id и request_secret. Последующие GET /v1/requests/{id} используют заголовок Authorization со схемой Zorin и этим секретом. Не сохраняйте секрет в URL или общедоступных логах.

AuthorityRequest

Поля: id, project_id, origin, challenge, action, resource, message, status, created_at, expires_at; error и assertion необязательны. Статусы: pending, approved, denied, expired, error.

Функция authorize возвращает первый результат со статусом, отличным от pending после опросов с интервалом 700 мс. Она не вызывает verifyAssertion автоматически. Превышение timeoutMs проверяется между запросами, без отмены зависшего Fetch.

VerifyExpected

Поля aud, origin, challenge, action и resource сравниваются с payload точно. phonePublicKeyDERHex сравнивается с ключом owner proof без учёта регистра hex. Параметр now — секунды Unix; по умолчанию текущее серверное/браузерное время среды выполнения.

ZAUTH/1 требует exp > now и iat <= now + 30. Owner proof версии ZOWNER/1 должен иметь действие authority.authorize, совпадающие fingerprints, срок не короче exp assertion и соответствующий request scope.

Scope — zauth: и SHA-256 от UTF-8 канонической строки с NUL-разделителями, связывающей aud, origin, challenge, action, resource и jti. Подписи ECDSA/SHA-256 проверяются ключами P-256 через Web Crypto; DER-подписи преобразуются в P1363.

AssertionPayload и OwnerProof

Payload содержит v, iss, aud, origin, challenge, action, resource, iat, exp, jti, assurance, host_fp, phone_fp и owner_proof. Наличие поля в TypeScript-типе не является runtime-валидацией JSON. В частности, issuer и assurance не входят в отдельную прикладную политику допуска этого verifier.

OwnerProof содержит version, action, resource, host_fingerprint, phone_fingerprint, phone_public_key_der_hex, nonce, issued_unix, expires_unix и signature_der_hex. Его подпись покрывает строку ZTRUST/2|OWNER_PROOF с действием и ресурсом в hex.

Однократность challenge/jti, права аккаунта и выбор доверенных ключей реализует приложение.