zorin-authority-sdk-ts

TypeScript SDK связывает веб-приложение с локальным Authority broker. Он создаёт запросы подтверждения операций, получает подтверждения операций и проверяет подписи ZAUTH/1. Получение ответа от устройства и проверка этого ответа — отдельные операции.

Установка и среда

Пакет @zorin/authority экспортирует ESM-модуль и TypeScript-типы. Браузерные операции используют Fetch и Web Crypto. Подключение телефона обслуживает локальный broker.

git clone https://github.com/localzet/zorin-authority-sdk-ts.git
cd zorin-authority-sdk-ts
npm install
npm run build
npm pack

Для сборки исходников версии 0.1.0 подходит TypeScript 5.8.3. При использовании 5.9.3 возникают ошибки совместимости BufferSource и ArrayBufferLike в криптографических вызовах.

Полученный tarball устанавливается в приложение через npm install /path/to/package.tgz. Имя импорта — @zorin/authority.

Подтверждение операции

import { authorize } from '@zorin/authority';

const request = await authorize({
  projectId: 'control-panel',
  origin: window.location.origin,
  challenge: challengeFromServer,
  action: 'server.restart',
  resource: 'vps:42',
  message: 'Перезапустить сервер?',
});

if (request.status === 'approved' && request.assertion) {
  await submitAssertionToServer(request.assertion);
}

challengeFromServer выдаёт сервер приложения для конкретной операции. submitAssertionToServer — обработчик приложения: он отправляет assertion серверу, который сверяет ожидаемые параметры и зарегистрированные ключи, проверяет полномочия пользователя и атомарно погашает challenge.

По умолчанию broker доступен по http://127.0.0.1:47475. authorize() создаёт запрос через POST /v1/authorize, затем опрашивает GET /v1/requests/{id} каждые 700 мс с секретом запроса в заголовке Authorization. Возвращается первый результат со статусом, отличным от pending. Denied, expired и error — тоже результаты, поэтому проверка status обязательна.

Срок запроса по умолчанию — 90 секунд, срок ожидания SDK — 70 секунд. timeoutMs ограничивает цикл ожидания, но не отменяет отдельный зависший Fetch.

Проверка ответа

verifyAssertion(assertion, brokerPublicKeyPem, expected) проверяет обе подписи и привязку к операции. Expected содержит aud, origin, challenge, action, resource и phonePublicKeyDERHex. Ключ broker — PEM, ключ телефона — SPKI DER в hex из доверенной регистрации.

import { verifyAssertion } from '@zorin/authority';

const payload = await verifyAssertion(assertion, trustedBrokerPublicKeyPem, {
  aud: 'control-panel',
  origin: 'https://control.example.test',
  challenge: storedChallenge,
  action: 'server.restart',
  resource: 'vps:42',
  phonePublicKeyDERHex: enrolledPhonePublicKeyHex,
});

Значения expected задаёт приложение из сохранённой транзакции. Нельзя брать ожидаемый ключ телефона из входящего owner proof: это докажет владение произвольным ключом вместо зарегистрированного устройства.

Подпись broker покрывает исходный сегмент payload. Вложенная подпись телефона покрывает owner proof с transaction scope. Проверяются срок assertion, срок owner proof, идентификаторы host/phone и точное совпадение ожидаемых параметров. Результат — проверенный payload.

Браузерная проверка помогает интерфейсу, но сервер обязан самостоятельно проверить доказательство перед выдачей сессии или изменением данных. Приложение проверяет права аккаунта и атомарно потребляет challenge: SDK не имеет replay cache и не предотвращает повтор действующего assertion.

Разбор и ошибки

parseAssertion() декодирует JSON без проверки подписи и времени. Его результат остаётся недоверенным. Не используйте его для допуска операции или выбора произвольного удалённого источника ключей.

Ошибка HTTP, отказ криптографической проверки и превышение времени ожидания отклоняют Promise. Denied/expired/error от broker возвращаются как AuthorityRequest, поэтому обрабатываются через status.

В опубликованной версии 0.1.0 USB-доступ не экспортируется браузерным SDK: подтверждение выполняет локальный broker. Браузер должен иметь доступ к его loopback-адресу с учётом ограничений Fetch и локальной сети.

Исходный код · MIT