kit-jwt

Кодирование и декодирование JSON Web Token (JWT) для Kit

[TOC]

Файлы

Файл	Описание
`.editorconfig`	Конфигурация форматирования редактора
`.gitignore`	Правила игнорирования Git для артефактов сборки и зависимостей
`.tool-versions`	Версии инструментов asdf (Zig, Kit)
`LICENSE`	Файл лицензии MIT
`README.md`	Этот файл
`examples/basic.kit`	Пример базового использования HS256
`kit.toml`	Манифест пакета с метаданными, возможностями и зависимостями
`src/jwt.kit`	API кодирования, декодирования, верификации и вспомогательные функции JWT
`zig/jwt_rsa.zig`	Мост для подписи и верификации RSA на базе OpenSSL
`zig/kit_ffi.zig`	Вспомогательные функции FFI Kit Zig, используемые мостом RSA
`tests/hs256.test.kit`	Активные тесты поведения HS256
`tests/types.test.kit`	Тесты ошибок, типов, алгоритмов и формы утверждений
`tests/rs256.kit.disabled`	Опциональные тесты поведения RS256
`tests/rs384.kit.disabled`	Опциональные тесты поведения RS384
`tests/rs512.kit.disabled`	Опциональные тесты поведения RS512

Зависимости

Зависимость пакета Kit: crypto
Стандартный модуль Kit: Encoding.Base64
Нативная библиотека: OpenSSL libcrypto для вспомогательных функций RS256, RS384 и RS512
Требуемая возможность: ffi

Пакет объявлен как ffi-zig, поскольку подпись и верификация RSA используют zig/jwt_rsa.zig. HS256 использует crypto.hmac-sha256.

Установка

kit add gitlab.com/kit-lang/packages/kit-jwt.git

Использование

import Kit.Jwt as JWT

main = fn =>
  secret = "my-super-secret-key-at-least-32-chars"
  claims = "{\"sub\":\"user123\",\"name\":\"John Doe\",\"admin\":true,\"iat\":1700000000}"

  match JWT.encode claims secret
    | Err e ->
      println "Failed to create token:"
      println e
    | Ok token ->
      println "JWT:"
      println token

      if JWT.verify? token secret then
        println "Token is valid"
      else
        println "Token is invalid"

      match JWT.decode token secret
        | Ok decoded ->
          println "Header:"
          println decoded.header
          println "Payload:"
          println decoded.payload
        | Err e ->
          println "Decode failed:"
          println e

main

Поддерживаемые вспомогательные функции подписи и верификации:

Алгоритм	Вспомогательные функции
HS256	`encode`, `encode-with-header`, `decode`, `verify?`
RS256	`encode-rs256`, `decode-rs256`, `verify-rs256?`, `get-claims-rs256`
RS384	`encode-rs384`, `decode-rs384`, `verify-rs384?`, `get-claims-rs384`
RS512	`encode-rs512`, `decode-rs512`, `verify-rs512?`, `get-claims-rs512`

Вспомогательные функции небезопасного просмотра также доступны для отладки токенов без верификации подписей:

decode-unsafe
get-claims-unsafe
get-header-unsafe

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

Разработка

Запуск примеров

Запустите базовый пример с помощью интерпретатора:

kit run examples/basic.kit --allow=ffi

Скомпилируйте пример в нативный двоичный файл:

kit build examples/basic.kit --allow=ffi && ./basic

Запуск тестов

Запустите активный набор тестов:

kit test --allow=ffi

Запустите активный набор тестов с покрытием:

kit test --coverage --allow=ffi

Запустите опциональные файлы тестов RSA напрямую:

kit test tests/rs256.kit.disabled --allow=ffi
kit test tests/rs384.kit.disabled --allow=ffi
kit test tests/rs512.kit.disabled --allow=ffi

Запуск kit dev

Запустите стандартный рабочий процесс разработки (форматирование, проверка, тестирование):

kit dev

Это выполнит:

Проверка форматирования исходных файлов Kit и примеров
Проверка типов исходников и примеров
Запуск активных тестов с покрытием

Запуск проверок паритета

Запустите проверки паритета интерпретатора/компилятора для примеров:

kit parity --failures-only

Проверки паритета удостоверяются, что примеры выполняются через интерпретатор, успешно компилируются, успешно выполняются и выдают совпадающий вывод.

Генерация документации

Сгенерируйте документацию API из комментариев кода:

kit doc src/jwt.kit

Примечание: Исходники Kit с комментариями документирования (##) генерируют HTML-документацию.

Очистка артефактов сборки

Удалите сгенерированные файлы, кеши и артефакты сборки:

kit task clean

Примечание: Определено в kit.toml.

Локальная установка

Чтобы установить этот пакет локально для разработки:

kit install

Это устанавливает пакет в ~/.kit/packages/@kit/jwt/, делая его доступным для импорта как Kit.Jwt в других проектах.

Замечания по безопасности

Используйте стойкие случайные секреты HS256. Рекомендуется минимум 256 бит.
Никогда не сохраняйте в репозитории приватные ключи или секреты JWT для продакшена.
После декодирования проверяйте утверждения приложения, такие как exp, nbf, iat, iss и aud.
Предпочитайте короткоживущие токены и регулярно меняйте ключи в соответствии с моделью угроз вашего приложения.
Используйте HTTPS при передаче JWT по сети.

Лицензия

Этот пакет выпущен под лицензией MIT — см. LICENSE для подробностей.

kit-jwt v2026.7.12