JWT — API
JWT::encode()
Заголовок раздела «JWT::encode()»JWT::encode($claims, ?string $signatureKey = null, ?string $tokenEncryption = null): stringНесмотря на имя $tokenEncryption, аргумент выбирает алгоритм подписи, а не шифрование payload. Ключ и алгоритм обязательны по поведению; null приводит к отказу. Результат — компактная строка из трёх base64url-сегментов.
Claims сериализуются в JSON-объект. Содержимое не шифруется. Автоматической установки issuer, audience, subject и срока действия нет.
JWT::decode()
Заголовок раздела «JWT::decode()»JWT::decode(string $token, ?string $signatureKey = null, ?string $tokenEncryption = null)Возвращает массив claims после проверки подписи и поддерживаемых временных полей. Ключ и алгоритм берутся из аргументов, не из токена. Сравнение header algorithm с доверенно выбранным алгоритмом должно пройти точно.
| Условие | Поведение |
|---|---|
| Не три сегмента | UnexpectedValueException. |
Неканонический base64url, padding =, недопустимые символы | Отказ декодирования. |
Нет нужных typ/alg или они не совпадают | Отказ проверки header. |
Есть ненулевой crit/b64 | Отказ как неподдерживаемого header. |
| Подпись неверна | Отказ до чтения/возврата claims. |
| Payload не соответствует JSON-объекту | Отказ. |
exp, nbf, iat имеют неподходящий тип | UnexpectedValueException. |
exp <= time() либо nbf > time() | UnexpectedValueException. |
iss/aud не подходят приложению | Автоматической проверки нет. |
| Нет срока действия, токен отозван приложением | Самостоятельного отказа по этим причинам нет. |
В заголовке проверяется наличие crit/b64 через isset(): JSON null не трактуется как заданное поддерживаемое расширение. API не реализует обработку критических JOSE-расширений.
JWT::$CLAIM_KID
Заголовок раздела «JWT::$CLAIM_KID»Публичное статическое поле позволяет добавить kid в генерируемый header. Resolver ключей, JWKS download, cache или выбор ключа по этому полю не выполняются. После временной настройки восстановите прежнее значение в долгоживущем процессе, чтобы не перенести kid в следующий несвязанный выпуск токена.
Base64url helpers
Заголовок раздела «Base64url helpers»JWT::base64UrlEncode($data): string кодирует байты без padding. Пустая строка не является поддерживаемым входом этого helper.
JWT::base64UrlDecode(string $data): string принимает непустую каноническую строку base64url. После декодирования выполняет обратное кодирование и сравнение с исходной строкой; альтернативные формы с лишними битами или padding отклоняются.
Это низкоуровневые кодировки. Декодирование отдельного сегмента ничего не говорит о доверии к токену.
JwaSignature
Заголовок раздела «JwaSignature»Вспомогательный класс содержит validateKey($pem, $algorithm, $signing), fromDer($signature, $algorithm) и toDer($signature, $algorithm) для проверки RSA/EC-ключей и преобразования ECDSA-подписей. fromDer() разбирает DER integer-пару, проверяя длины и отсутствие лишних данных; toDer() требует точную ширину JOSE-подписи соответствующего алгоритма.
Для обычного выпуска/проверки используйте JWT, который вызывает эти проверки. Прямой вызов конвертера не проверяет содержимое JWT и его application policy.