Иерархия ошибок в Jose

В библиотеке JOSE (JSON Object Signing and Encryption) обработка ошибок является одной из ключевых частей архитектуры, поскольку работа с токенами и криптографическими операциями требует строгой диагностики причин сбоев. Иерархия ошибок в JOSE построена таким образом, чтобы разработчик мог точно определить, на каком этапе произошла проблема: при декодировании структуры токена, проверке подписи, валидации алгоритма или при обработке ключей.

Базовым элементом всей системы ошибок выступает класс JOSENotSupported и его производные, но корневым классом, от которого фактически наследуются все специализированные ошибки, является JOSEError. Он инкапсулирует общую семантику ошибок криптографического уровня и служит единым типом для перехвата всех исключений, связанных с обработкой JOSE-структур.

JOSEError — это фундаментальная ошибка, которая не привязана к конкретному этапу обработки. Она используется как абстрактный контейнер для всех проблем, возникающих в библиотеке. В реальной практике напрямую она возникает редко, поскольку большинство случаев уточняются через более конкретные подклассы.

Ключевая роль этого уровня — унификация обработки:

• позволяет централизованно ловить любые ошибки JOSE через instanceof JOSEError
• упрощает построение middleware-обработчиков
• служит маркером того, что ошибка относится к криптографической области

Ошибки формата и структуры

Одной из самых частых категорий являются ошибки, связанные с некорректной структурой токена или JWS/JWE объекта.

JOSEParseError

Возникает при невозможности разобрать входную строку как корректный JWT или JWE. Это может происходить в случаях:

• нарушена структура из трёх или пяти сегментов JWT
• отсутствует обязательный разделитель
• данные не являются Base64URL

Данный тип ошибки относится к ранней стадии обработки, до выполнения криптографических операций.

JOSENotCompact (в некоторых реализациях)

Используется, когда входной объект не соответствует compact serialization формату. Например, попытка передать JSON-сериализованный JWS в функцию, ожидающую compact JWT.

Ошибки криптографических операций

Эта группа является центральной в JOSE, поскольку именно здесь происходит проверка подлинности данных.

JWSInvalidSignature

Одна из наиболее критичных ошибок. Возникает, когда подпись JWT не соответствует ожидаемому значению при проверке с использованием публичного ключа.

Причины возникновения:

• изменение payload после подписания
• использование неправильного ключа
• несоответствие алгоритма подписи
• повреждение токена при передаче

Эта ошибка всегда означает, что доверие к токену не может быть установлено.

JWSSignatureVerificationFailed

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

JWEDecryptionFailed

Возникает при невозможности расшифровать JWE (JSON Web Encryption). Это одна из наиболее сложных ошибок, поскольку она может скрывать широкий спектр причин:

• неверный приватный ключ
• повреждение зашифрованного payload
• несоответствие алгоритмов шифрования и дешифрования
• использование устаревших параметров ключа

Ошибки алгоритмов

JOSE строго контролирует допустимость криптографических алгоритмов. Любое несоответствие приводит к ошибкам уровня безопасности.

JOSENotSupported

Используется, когда:

• алгоритм подписи не поддерживается библиотекой
• указан запрещённый алгоритм (например, none, если он отключён)
• комбинация алгоритмов не соответствует политике безопасности

Этот класс часто является базой для более конкретных ошибок, связанных с алгоритмами.

JOSEAlgNotAllowed

Возникает при попытке использовать алгоритм, явно запрещённый конфигурацией приложения. Например, система может разрешать только RS256, но входящий токен использует HS256.

Ошибки ключей и криптографической инфраструктуры

Работа с ключами — одна из наиболее чувствительных областей, и JOSE выделяет отдельные ошибки для диагностики проблем с ними.

JWKInvalid

Возникает при некорректном формате JSON Web Key (JWK):

• отсутствуют обязательные поля (kty, use, alg)
• ключ повреждён
• несовместимый тип ключа

JWKMissingKey

Используется, когда необходимый ключ не найден в наборе JWK Set. Часто встречается при работе с динамическими ключевыми источниками (например, JWKS endpoint).

JWKSMultipleMatchingKeys

Возникает, когда для одного token header находится несколько подходящих ключей. Это создаёт неоднозначность при выборе ключа и считается критической ошибкой конфигурации.

Ошибки валидации токена

После успешного декодирования и проверки криптографической целостности выполняется этап валидации claims. Здесь также существует отдельная группа ошибок.

JWTExpired

Возникает, когда поле exp (expiration time) указывает на прошедшее время. Это одна из самых частых ошибок в production-системах.

JWTNotBeforeError

Возникает при нарушении поля nbf (not before). Токен ещё не должен быть активен.

JWTClaimValidationFailed

Обобщённая ошибка для случаев, когда один или несколько claims не соответствуют ожиданиям:

• неправильный iss (issuer)
• несоответствие aud (audience)
• отсутствующие обязательные claims

Ошибки сериализации и декодирования

На нижнем уровне находятся ошибки, связанные с кодированием данных.

JWEInvalid

Используется при невозможности корректно разобрать структуру JWE-сообщения. Может включать проблемы с:

• сегментами encrypted key
• initialization vector
• authentication tag

JOSENotBase64URLEncoded

Возникает, когда часть JWT не соответствует стандарту Base64URL. Это часто указывает на повреждение токена или попытку передать некорректные данные.

Иерархическая структура и логика наследования

Иерархия ошибок в JOSE построена по принципу постепенного уточнения:

• JOSEError

  • ошибки парсинга
  • ошибки алгоритмов
  • ошибки ключей
  • ошибки подписи и шифрования
  • ошибки валидации claims

Такое дерево позволяет:

• отделять транспортные ошибки от криптографических
• различать фатальные и валидационные сбои
• выстраивать многоуровневую обработку исключений

Практически важной особенностью является то, что большинство ошибок можно перехватывать на разных уровнях абстракции. Например, обработчик может ловить как общий JOSEError, так и конкретный JWTExpired, в зависимости от требуемой логики.

Практическая роль и поведение в приложениях

В реальных системах иерархия ошибок используется не только для отладки, но и для построения политик безопасности:

• при JWTExpired выполняется инициирование refresh flow
• при JWSInvalidSignature запрос полностью отклоняется
• при JWKMissingKey может запускаться обновление JWKS cache
• при JOSENotSupported фиксируется ошибка конфигурации системы

Таким образом, ошибки JOSE являются не просто диагностическим механизмом, а полноценной частью управления жизненным циклом токенов и безопасностью приложения.