JWTInvalid, JWSInvalid, JWEInvalid

В библиотеке jose ошибка JWTInvalid относится к классу исключений, возникающих при обработке JSON Web Token (JWT), когда структура токена или его содержимое не соответствуют требованиям стандарта или ожиданиям библиотеки.

JWT в экосистеме JOSE представляет собой компактный способ передачи утверждений (claims) между двумя сторонами в виде трёх частей: header, payload, signature. Любое нарушение формата или невозможность корректной интерпретации этих частей приводит к выбросу JWTInvalid.

Основные причины возникновения JWTInvalid

1. Некорректная структура токена

JWT должен состоять из трёх частей, разделённых точками:

xxxxx.yyyyy.zzzzz

Если частей меньше или больше, либо присутствуют недопустимые символы, библиотека прекращает обработку.

2. Повреждение Base64URL кодировки

Каждая часть JWT кодируется в Base64URL. Если строка была изменена, обрезана или закодирована в обычный Base64 вместо Base64URL, декодирование становится невозможным.

3. Несоответствие алгоритма в заголовке

Header JWT содержит поле alg. Если указанный алгоритм не поддерживается или не совпадает с фактическим способом подписи, токен считается некорректным.

Пример проблемного заголовка:

{
  "alg": "HS512",
  "typ": "JWT"
}

Если проверка выполняется алгоритмом HS256, возникнет несоответствие.

4. Отсутствие обязательных полей

JWT может содержать обязательные зарегистрированные claims:

  • exp (expiration time)
  • iat (issued at)
  • nbf (not before)

Отсутствие критически важных полей в контексте проверки может приводить к JWTInvalid, особенно если библиотека ожидает строгую валидацию.

Поведение при выбросе JWTInvalid

Ошибка сигнализирует о том, что токен нельзя интерпретировать как валидный JWT ни на одном этапе: ни при декодировании, ни при валидации структуры.

JWSInvalid

JWSInvalid относится к более узкому уровню спецификации JOSE — JSON Web Signature (JWS). В отличие от JWT, который является контейнером, JWS отвечает исключительно за подпись данных.

Ошибка возникает, когда подпись JWS не может быть проверена или нарушена структура подписанного сообщения.

Основные причины JWSInvalid

1. Несовпадение подписи

Самая распространённая причина — несоответствие между подписанным payload и предоставленной подписью.

Это может произойти при:

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

2. Неверный алгоритм подписи

Если токен подписан, например, алгоритмом RS256, а проверка выполняется как HS256, результатом будет JWSInvalid.

3. Повреждённая структура JWS

Формат JWS:

header.payload.signature

Любое нарушение структуры приводит к невозможности проверки подписи.

4. Ошибка декодирования компонентов

Каждая часть JWS кодируется в Base64URL. Ошибки декодирования автоматически приводят к провалу проверки подписи.

Пример логики возникновения ошибки

При проверке:

  1. библиотека извлекает header и payload
  2. пересчитывает подпись
  3. сравнивает с переданной signature

Если хотя бы один шаг невозможен — выбрасывается JWSInvalid.

JWEInvalid

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

JWE более сложен по сравнению с JWS, так как включает не только подпись, но и полноценное шифрование содержимого.

Структура JWE

JWE состоит из пяти частей:

protectedHeader.encryptedKey.iv.ciphertext.tag

Нарушение любой из этих частей приводит к ошибке.

Основные причины JWEInvalid

1. Неверный ключ расшифровки

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

Это самая частая причина ошибки.

2. Несовместимость алгоритмов

JWE использует два типа алгоритмов:

  • alg — алгоритм управления ключом (например, RSA-OAEP)
  • enc — алгоритм шифрования содержимого (например, A256GCM)

Несовпадение ожидаемых и фактических алгоритмов приводит к JWEInvalid.

3. Повреждение ciphertext или tag

Шифротекст и аутентификационный тег критичны для целостности. Любое изменение:

  • одного байта ciphertext
  • или tag

делает дешифрование невозможным.

4. Нарушение структуры JWE

Если отсутствует хотя бы одна из пяти частей, токен считается некорректным.

5. Ошибка аутентификации (AEAD failure)

При использовании алгоритмов типа AES-GCM проверяется целостность данных. Если тег аутентификации не сходится, возникает JWEInvalid.

Сравнение JWTInvalid, JWSInvalid и JWEInvalid

JWTInvalid

  • уровень: логический контейнер JWT
  • проблема: общая некорректность токена
  • причины: структура, claims, формат

JWSInvalid

  • уровень: подпись данных
  • проблема: невозможность проверить подпись
  • причины: ключ, алгоритм, повреждение подписи

JWEInvalid

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

Типовые цепочки возникновения ошибок

В реальной работе с jose ошибки часто следуют каскадом:

  • повреждённый JWT → JWTInvalid
  • валидный JWT, но неправильная подпись → JWSInvalid
  • зашифрованный токен с неправильным ключом → JWEInvalid

Иногда один и тот же токен может проваливаться на разных этапах обработки, если используется комбинированный формат (например, JWE внутри JWT или наоборот).

Поведение библиотеки jose при валидации

При работе с функциями:

  • jwtVerify
  • jwtDecrypt
  • compactVerify
  • compactDecrypt

библиотека строго разделяет этапы:

  1. парсинг
  2. декодирование
  3. проверка подписи
  4. проверка шифрования
  5. проверка claims

Любое отклонение от спецификации JOSE прерывает выполнение и приводит к соответствующему типу исключения.

Практические причины появления ошибок в реальных системах

Чаще всего источником проблем являются:

  • потеря части токена при передаче через URL
  • неверная настройка CORS и заголовков Authorization
  • использование разных секретов в разных окружениях
  • ротация ключей без синхронизации сервисов
  • некорректная сериализация JSON перед подписью

Особенности диагностики

Ошибки JWTInvalid, JWSInvalid, JWEInvalid не содержат подробной информации о причине на уровне безопасности. Это сделано намеренно: библиотека не раскрывает детали, которые могут быть использованы для атак на криптографическую схему.

Диагностика обычно строится на:

  • проверке длины и структуры токена
  • сверке алгоритмов alg и enc
  • контроле ключей
  • тестировании этапов декодирования отдельно

Поведение при работе с различными форматами JOSE

JOSE допускает комбинирование:

  • JWT + JWS (подписанный токен)
  • JWT + JWE (зашифрованный токен)
  • JWS внутри JWE (подпись + шифрование)

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

Оглавление