言签：JWT

言签（yanxu-jwt）1.0.0 是纯言序的 JSON Web Token 库。它固定使用 HS256，不根据不可信头部选择算法；签名基于标准库 HMAC-SHA-256 与恒时比较，并支持文字或二进制密钥、本地 kid密钥集轮换和严格标准声明策略。

版本与安装

yanbao add 言签 \
  --git https://github.com/yanxulang/yanxu-jwt.git \
  --rev v1.0.0 \
  --version '^1.0'

[依赖]
言签 = { git = "https://github.com/yanxulang/yanxu-jwt.git", 修订 = "v1.0.0", 版 = "^1.0" }

提交生成的 言序.lock。生产密钥不应出现在清单、锁文件、源码或日志中。

核心能力：签发带标识的标准令牌

引「包:言签」为 言签；

# 仅为文档示例；生产密钥必须由密码学安全随机源生成。
定 当前密钥：文 为 「abcdef0123456789abcdef0123456789」；

定 令牌：文 为 言签.签发标准带标识（
    {「role」：「editor」}，
    当前密钥，
    「2026-07」，
    {
        「当前秒」：1700000000，
        「有效秒」：900，
        「iss」：「auth.example」，
        「aud」：【「web」，「mobile」】，
        「sub」：「user-42」，
        「jti」：「session-42」
    }
）；

签发标准…自动构造 iat、nbf和exp，并合并可选的 iss、aud、sub与jti。第一个附加声明参数不得覆盖这些标准声明，避免业务载荷绕过签发策略。

若密钥来自 KMS、二进制配置或安全随机源，应保留为字节串并使用带字节密钥后缀的签发与验证入口；只有明确是 UTF-8 文本的密钥才使用文字密钥入口。

验证与安全轮换

定 密钥集：典 为 {
    「2026-01」：旧密钥，
    「2026-07」：当前密钥
}；

定 声明：典 为 言签.验证密钥集（令牌，密钥集，{
    「当前秒」：1700000100，
    「时差秒」：30，
    「签发者」：「auth.example」，
    「受众」：「web」，
    「主题」：「user-42」，
    「密钥标识」：「2026-07」，
    「需要过期」：真，
    「需要签发时间」：真，
    「需要生效时间」：真，
    「需要编号」：真，
    「最大寿命秒」：900，
    「必需声明」：【「role」】
}）；

言 声明【「role」】；

密钥集必须来自受信任本地配置，并包含 1–64 项。未知或缺失 kid立即失败，不会回退到任意密钥。安全轮换顺序是：

1. 先把新密钥加入所有验证方；
2. 再让签发方改用新的 kid；
3. 等待旧令牌最大寿命加允许时差；
4. 最后从验证方移除旧密钥。

验证成功才返回声明。测试和回放应显式传当前秒；生产可使用读取系统时间的便捷验证入口，但仍应配置固定签发者、受众、主题、必需时间声明和最大寿命。

公共接口

URL Base64 使用无填充规范形式；解码会拒绝 =填充、非法字符、错误长度和非规范尾位。紧凑令牌固定为三段，头部和载荷必须是 JSON 对象。

错误、权限与安全边界

试 则
    定 声明 为 言签.验证密钥集（令牌，密钥集，策略）；
救 所误 则
    定 详情：典 为 言签.错误详情（所误）；
    言 详情【「代码」】；
终

错误使用稳定 YANQIAN_*代码。服务可以把代码统一映射为 401 或 403，并只在脱敏的服务端日志中保留必要诊断；不要回显详细解析差异、完整令牌或密钥。

言签无第三方依赖，不申请文件、网络、监听、环境、进程或原生扩展权限。Python 互操作测试只用于发布验证，不是运行时依赖。

解析未验证与已知限制

解析未验证只检查紧凑格式、URL Base64、UTF-8 与 JSON 对象，返回的头部、声明和分段仍完全受攻击者控制。它只适合诊断或互操作测试，绝不能参与认证、授权、数据库过滤或远程密钥选择。

此外：

• 1.0 只支持 HS256，不提供 RSA、ECDSA、EdDSA、none或算法协商。
• 不读取远程 JWK，也拒绝依赖 jku、jwk、x5u或x5c的密钥选择。
• 密钥存储、分发、撤销、会话状态和重放防护由应用负责。
• aud可为文字或非空文字列；其他身份声明要求非空文字，时间声明拒绝小数、负数和溢出。
• 生产中应使用短寿命令牌，并把验证后的声明与服务端授权和撤销状态结合。

项目链接

• GitHub 仓库
• 言签 1.0.0 Release