LWT — API

Статический API

LWT::encode($data, string $signatureKey = null, string $tokenEncryption = null, string $encryptionKey = null): string
LWT::decode(string $token, string $signatureKey = null, string $tokenEncryption = null, string $encryptionKey = null)

Ключ подписи и алгоритм обязательны по поведению; пустые значения отклоняются. Внутри статическое типизированное поле алгоритма получает аргумент до проверки пустоты, поэтому null может привести к TypeError, а не к прикладному исключению. Передавайте аргументы явно.

encode() возвращает compact-токен; decode() возвращает JSON-декодированные данные, без проверки application claims. Временной допуск, допустимый issuer/audience и replay policy аргументами не задаются.

Заголовок

Поле	Содержимое
typ	LWTv3
cty	JWS без payload encryption, LZX при заданном ключе шифрования
alg	Переданная строка алгоритма подписи
kid	Публичное статическое LWT::$CLAIM_KID, если задано и не отфильтровано как пустое
enc	AES-256-CBC+RSA для зашифрованного режима

При decode проверяются typ, cty и alg. Это не полноценная политика JOSE critical headers и не resolver ключей по kid.

Payload

Без encryption payload — base64url от JSON. При encryption в base64url помещается бинарная структура:

uint32_be(4 + encrypted_key_length)
| RSA-encrypted AES key
| IV
| AES-256-CBC ciphertext in OpenSSL default encoded form

Использование openssl_encrypt() с options 0 означает, что ciphertext внутри этого envelope уже представлен в base64-форме. Не трактуйте его как стандартный raw JWE ciphertext. RSA padding выбирается из доступных констант с приоритетом OAEP; отдельного аргумента для фиксации профиля padding у API нет.

Подпись

Подписывается исходная строка headerSegment.payloadSegment. HMAC использует бинарный результат hash_hmac(). Для обычного симметричного ключа берутся переданные байты; специальная ветка PEM не должна использоваться как замена секрету HMAC.

RSA/ECDSA обращаются к OpenSSL напрямую; EdDSA использует sodium. Для ECDSA не выполняется преобразование DER в фиксированную пару R/S. Строгая проверка размера RSA и соответствия EC curve алгоритму, имеющаяся в JWT::JwaSignature, здесь отсутствует.

Base64url и ошибки

base64UrlEncode() и base64UrlDecode() доступны публично. Decode дополняет padding и вызывает base64_decode() без strict mode; это не тот же строгий канонический decoder, что в библиотеке JWT.

Ошибки в key/envelope/JSON/signature обозначаются разными встроенными исключениями PHP и OpenSSL/sodium. Не передавайте их сообщения клиенту как подробный ответ endpoint. Ограничивайте длину токена до разбора, проверяйте application claims после успешного decode и не используйте decode как доказательство пригодности токена для конкретного действия.