Пакет · jwt

JWT

Flytachi JWT — это современная библиотека с приоритетом безопасности для кодирования и декодирования JSON Web Tokens в PHP. Она опирается на строгую типизацию и объекты-значения, чтобы затруднить некорректное использование, поддерживает все популярные алгоритмы подписи и включает встроенный парсер JWKS, так что вы можете проверять токены от Google, Apple, Auth0 и других без дополнительных зависимостей.

Философия

Приоритет безопасности — подписи сравниваются с помощью hash_equals (постоянное время, устойчивость к атакам по времени), а алгоритм проверяющего ключа должен совпадать с заголовком токена, что закрывает классическую атаку путаницы алгоритмов.
Строгая типизация — ключи, заголовки и payload являются объектами-значениями (PrivateKey, PublicKey, JwtPayload), а не произвольными строками и массивами. Вы не сможете случайно передать общий секрет HMAC туда, где ожидается публичный ключ.
Никаких тяжёлых зависимостей — только ext-openssl и ext-json. Преобразование JWKS в PEM выполняется на чистом PHP через собственную реализацию ASN.1-кодирования.

Основные понятия

JwtPayload — claims токена (sub, exp, пользовательские поля). Объект-значение, который вы читаете через getClaim().
PrivateKey / PublicKey — материал ключа, привязанный к алгоритму. PrivateKey подписывает; PublicKey проверяет.
JWT — фасад с двумя статическими методами: encode() и decode().
JWK — парсер, который превращает JSON Web Key Set в карту объектов PublicKey, проиндексированных по kid.

Ключевые возможности

Все популярные алгоритмы — HMAC (HS256/384/512), RSA (RS256/384/512) и ECDSA (ES256/384/512).
Полная поддержка JWKS — разбор ключей RSA, EC и oct прямо из /.well-known/jwks.json провайдера.
Проверка временных claims — exp, nbf и iat проверяются автоматически, с настраиваемым допуском (leeway) для рассинхронизации часов.
Ротация ключей через kid — асимметричные токены несут идентификатор ключа (kid); decode() сам выбирает нужный ключ из набора.
Надёжные ошибки — каждый сбой выбрасывает единственное исключение JWTException, которое вы можете перехватить.

Хорошо подходит для

Аутентификации без состояния, токенов доступа к API, проверки сторонних ID-токенов (OIDC / OAuth2) и любых случаев, где нужно подписанное утверждение, фиксирующее подмену, которое можно проверить без общего хранилища сессий.

Требования

PHP ≥ 8.1
ext-openssl — подпись и проверка RSA/ECDSA, а также разбор ключей JWKS
ext-json — кодирование и декодирование сегментов токена

Работает на любой ОС, включая Windows — нет зависимостей от POSIX.

Установка

bash

composer require flytachi/jwt

Быстрый старт

Подпишите payload общим секретом, затем проверьте его обратно:

php

use Flytachi\Jwt\JWT;
use Flytachi\Jwt\Entity\JwtPayload;
use Flytachi\Jwt\Entity\PrivateKey;
use Flytachi\Jwt\Entity\PublicKey;

$token = JWT::encode(
  new JwtPayload(['sub' => 'user-42', 'exp' => time() + 3600]),
  new PrivateKey('my-secret', 'HS256')
);

$payload = JWT::decode($token, [new PublicKey('my-secret', 'HS256')]);
echo $payload->getClaim('sub'); // user-42

Пройдите его от начала до конца в разделе «Быстрый старт».

Исходный код и ссылки

GitHub — github.com/flytachi/php-jwt
Packagist — packagist.org/packages/flytachi/jwt

Продолжите с раздела «Установка и требования», «Быстрый старт» и «Модель работы».