zorin-authority-sdk-python

Python SDK Authority проверяет подтверждения ZAUTH/1 на сервере приложения. Это локальная проверка подписей и контекста операции; SDK не обращается к broker по HTTP и не инициирует USB-подтверждение телефона.

Публичный модуль zorin_authority экспортирует parse_assertion и verify_assertion.

Установка

Требуются Python 3.10+ и cryptography >=42:

git clone https://github.com/localzet/zorin-authority-sdk-python.git
cd zorin-authority-sdk-python
python3 -m venv .venv
.venv/bin/python -m pip install .

Подготовка серверной транзакции

Создайте challenge и сохраните ожидаемые origin, действие, ресурс, user/device binding и срок. Получите публичный ключ телефона из доверенной регистрации, а не из непроверенного входящего proof. Ключ broker также берётся из доверенной конфигурации.

После проверки challenge должен быть атомарно потреблён. В SDK нет базы сессий или replay cache; повторное предъявление ещё действующего assertion само по себе не запоминается.

Проверка разрешения ZAUTH

from zorin_authority import verify_assertion

payload = verify_assertion(
    assertion,
    trusted_broker_public_key_pem,
    aud="control-panel",
    origin="https://control.example.test",
    challenge=stored_challenge,
    action="server.restart",
    resource="vps:42",
    phone_public_key_der_hex=enrolled_phone_public_key_hex,
)

Входящий assertion имеет префикс z1 и три сегмента. Проверяются версия ZAUTH/1, сроки, точное совпадение ожидаемых полей, подпись broker и owner proof телефона, привязанный к этой транзакции. Результат — словарь payload.

payload не является командой на исполнение. Отдельно проверьте, что пользователь имеет право на ресурс; затем примените подтверждение в той же логике, которая предотвращает повторное действие.

Для воспроизводимых фикстур передайте now в секундах Unix. В обычном запросе используйте серверное время.

Разбор без проверки

parse_assertion(assertion) разбирает compact-форму и возвращает decoded payload без проверки подписи. Используйте его для диагностического разбора недоверенных данных, но не для user identity, выбора произвольного URL ключа или допуска операции.

До криптографической проверки ограничьте длину входа и проверьте структуру JSON. Значения timestamps приводятся через int; SDK не является строгим schema validator для произвольного Python-словаря.

Ошибки

Проверки контекста и времени выбрасывают ValueError. JSON/base64, несовместимые типы, отсутствующие поля и неверная криптографическая подпись могут приводить к соответствующим исключениям Python/cryptography. Перехватывайте их на границе обработки запроса, не продолжая с частично разобранным payload.

Не включайте полный assertion/proof или ключи в общий лог. SDK не выполняет enrollment, session issuance, hardware attestation и проверку ролей пользователя.

Сигнатуры и проверяемые поля

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