kit-jwt

用于Kit的JSON Web Token (JWT) 编码与解码

[TOC]

文件

文件	描述
`.editorconfig`	编辑器格式配置
`.gitignore`	构建产物和依赖的Git忽略规则
`.tool-versions`	asdf工具版本（Zig, Kit）
`LICENSE`	MIT许可证文件
`README.md`	本文件
`examples/basic.kit`	基本HS256使用示例
`kit.toml`	包含元数据、功能和依赖的包清单
`src/jwt.kit`	JWT编码、解码、验证和辅助API
`zig/jwt_rsa.zig`	基于OpenSSL的RSA签名与验证桥接
`zig/kit_ffi.zig`	用于RSA桥接的Kit Zig FFI值辅助函数
`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
原生库：用于RS256、RS384和RS512辅助函数的OpenSSL libcrypto
所需功能：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 "创建令牌失败："
      println e
    | Ok token ->
      println "JWT："
      println token

      if JWT.verify? token secret then
        println "令牌有效"
      else
        println "令牌无效"

      match JWT.decode token secret
        | Ok decoded ->
          println "头部："
          println decoded.header
          println "载荷："
          println decoded.payload
        | Err e ->
          println "解码失败："
          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。
优先使用短生命周期令牌，并根据应用威胁模型轮换密钥。
通过网络传输JWT时始终使用HTTPS。

许可证

此包根据MIT许可证发布——详见LICENSE。

kit-jwt v2026.7.12