zorin-authority-sdk-php

PHP SDK Authority проверяет подписанное подтверждение действия или входа, созданное с участием телефона. В пакете один публичный класс — Zorin\Authority\Verifier. Он проверяет данные локально через OpenSSL, не отправляет запросы broker и не показывает запрос подтверждения на устройстве.

Есть два контура: ZAUTH/1 для разрешения конкретной операции через broker и ZWEB/1 для подтверждения web-аутентификации. Оба требуют заранее доверенного публичного ключа телефона.

Установка

Нужны PHP 8.1+ и OpenSSL:

composer config repositories.zorin-authority vcs https://github.com/localzet/zorin-authority-sdk-php
composer require zorin/authority:dev-main

Пакет называется zorin/authority, а namespace — Zorin\Authority.

Откуда берётся доверие

Сервер приложения создаёт challenge для конкретного пользователя, origin и операции и сохраняет его до проверки. Ключ broker берётся из доверенной конфигурации, ключ телефона — из заранее выполненной регистрации устройства.

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

После успешной проверки сервер должен атомарно пометить challenge/request как использованный. SDK не имеет базы использованных challenge и сам повторное предъявление ещё действующего подтверждения не запрещает.

Разрешение действия ZAUTH

use Zorin\Authority\Verifier;

$payload = Verifier::verify($assertion, $trustedBrokerPublicKeyPem, [
    'aud' => 'control-panel',
    'origin' => 'https://control.example.test',
    'challenge' => $storedChallenge,
    'action' => 'server.restart',
    'resource' => 'vps:42',
    'phone_public_key_der_hex' => $enrolledPhonePublicKeyHex,
]);

Переменные в примере принадлежат серверному контексту приложения: $assertion получен от клиента, остальные ожидаемые значения — из доверенной конфигурации и сохранённой транзакции.

verify() требует три сегмента с префиксом z1, payload версии ZAUTH/1 и действующий период exp/iat. Затем сверяет aud/origin/challenge/action/resource, подпись broker и подпись owner proof телефона. Phone proof должен быть связан с этой транзакцией, а его срок действия — покрывать срок assertion.

Результат — массив payload. Получение массива не перезапускает VPS и не заменяет обычную проверку права пользователя на vps:42: разрешение устройства и полномочия аккаунта должны проверяться вместе.

Подтверждение входа ZWEB

$verified = Verifier::verifyWebAuthentication($authentication, [
    'project_id' => 'control-panel',
    'origin' => 'https://control.example.test',
    'challenge' => $storedChallenge,
    'request_id' => $storedRequestId,
    'phone_public_key_der_hex' => $enrolledPhonePublicKeyHex,
    'require_biometric' => true,
]);

$authentication — декодированный JSON-массив результата browser/USB SDK. Здесь нет broker assertion: проверяется ZWEB object и его phone owner proof.

При require_biometric = true допускается только связанный с подписанным действием профиль web.authenticate.biometric. Одного неподписанного текста assurance недостаточно: действие proof также должно совпасть с требуемым.

Если приложение не требует биометрию, оно может принять соответствующий базовый профиль. Этот выбор должен определяться серверной политикой операции, а не переключателем клиента.

Время, ошибки и повторное использование

Оба метода принимают необязательный $now в Unix seconds для воспроизводимого теста. В обычной обработке оставьте null, чтобы использовалось системное время. Будущее issued/iat допускается не более чем на 30 секунд; истёкший срок отклоняется.

Ошибка проверки приводит к исключению. Неполный expected вызывает InvalidArgumentException, часть отказов — RuntimeException, некорректный JSON/типы могут дать другие встроенные ошибки. На HTTP-границе преобразуйте их в единообразный отказ, не возвращая клиенту подробности ключей и криптографических операций.

До вызова ограничьте размер входного сообщения и проверьте его форму. SDK проверяет подписанный proof, но не выполняет enrollment, user lookup, session creation, challenge storage или атомарное предотвращение replay.

Поля expected, форматы и методы

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