网络安全认证鉴权后端【免费下载链接】joseJWA, JWS, JWE, JWT, JWK, JWKS for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes项目地址https://gitcode.com/gh_mirrors/jo/jose点击查看免费下载本篇技术指南围绕 jose 仓库中 ProduceJWT 接口 展开深入讲解该接口定义的七个 JWT 标准 Claim 设置方法iss、sub、aud、jti、nbf、exp、iat、链式调用设计以及时间输入的三态解析规则。读者读完将掌握 SignJWT、EncryptJWT、UnsecuredJWT 三类 JWT 生产类共用的 Claims 构建能力并能结合源码理解时间跨度字符串的底层解析实现与参数校验逻辑。ProduceJWT 是什么ProduceJWT是 jose 中定义在 src/types.d.ts 的 TypeScript 接口其文档自述为 Generic interface for JWT producing classesJWT 生产类的通用接口。它把向 JWT Claims Set 写入标准声明这一行为抽象成统一契约凡是实现了该接口的类都可以用同一套链式 API 来填充 JWT 载荷。在 jose 中以下三个类都继承自JWTClaimsBuildersrc/lib/jwt_claims_set.ts因此全部满足ProduceJWT契约SignJWTsrc/jwt/sign.ts用于构建并签名 Compact JWS 格式的 JWTEncryptJWTsrc/jwt/encrypt.ts用于构建并加密 Compact JWE 格式的 JWTUnsecuredJWTsrc/jwt/unsecured.ts用于处理{ alg: none }的未签名、未加密 JWT。从源码可以确认SignJWT_base、EncryptJWT_base、UnsecuredJWT_base三者的类型都被声明为new (payload?: types.JWTPayload) types.ProduceJWT这正是接口作为生产端统一类型的体现。七个方法完整的标准 Claim 写入能力ProduceJWT共声明 7 个方法全部返回this从而支持无中断的链式调用。它们覆盖了 RFC 7519 中 JWT Claims Set 的全部标准注册声明方法对应 Claim参数类型说明setIssuer(issuer)issIssuer签发者string必须为字符串setSubject(subject)subSubject主体string必须为字符串setAudience(audience)audAudience受众string \| string[]字符串或字符串数组setJti(jwtId)jtiJWT IDstring用于防止重放的唯一标识setNotBefore(input)nbfNot Before生效时间number \| string \| Date三态时间输入见下文setExpirationTime(input)expExpiration Time过期时间number \| string \| Date三态时间输入见下文setIssuedAt(input?)iatIssued At签发时间number \| string \| Date可选不传参数则使用当前时间戳字符串类 Claim 的强校验对于iss、sub、jti三个字符串型 Claim实现层在 src/lib/jwt_claims_set.ts 做了严格类型检查非字符串输入会抛出TypeError如iss claim must be a stringaud则必须是字符串或全部由字符串组成的数组否则抛出aud claim must be a string or an array of strings。测试用例 test/jwt/sign.test.ts 验证了这些边界行为例如setIssuer(0)、setSubject(null)、setJti({})、setAudience([audience, 0])都会被拒绝。时间类 Claim 的三态输入setExpirationTime、setNotBefore与setIssuedAt接受三种输入语义完全一致number直接作为 Unix 时间戳使用以秒为单位Date内部通过Math.floor(date.getTime() / 1000)源码中的epoch函数见 src/lib/jwt_claims_set.ts转换为 Unix 时间戳string解析为相对于当前 Unix 时间戳的时间跨度即当前时间 时间跨度。其中时间字符串的解析由secs()函数src/lib/jwt_claims_set.ts完成。它使用正则/^(\|\-)? ?(\d|\d\.\d) ?(seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|years?|yrs?|y)(?: (ago|from now))?$/i并按单位换算系数src/lib/jwt_claims_set.ts计算秒数单位系数秒合法的拼写变体秒1sec、secs、second、seconds、s分钟60minute、minutes、min、mins、m小时3600hour、hours、hr、hrs、h天86400day、days、d周604800week、weeks、w年31557600365.25 天year、years、yr、yrs、y注意两个细节月份不被支持没有month/mo单位一年被定义为 365.25 天即 31557600 秒这与 RFC 7519 对 NumericDate 的定义保持一致。时间跨度还支持方向语义前置-如-1 hour或后置ago如1 hour ago表示从当前时间减去该跨度后置from now如1 hour from now仅用于增强可读性语义等同于直接加法最终都作用于当前 Unix 时间戳同时使用-与ago会被拒绝正则中matched[4] matched[1]判定非法测试 test/unit/secs.test.ts 覆盖了1 fortnight、 1 second、- 1 second ago等非法格式均抛出TypeError: Invalid time period format。setIssuedAt略有特殊参数可选不传参数时直接取epoch(new Date())即以调用时刻的当前时间戳作为iat。其余两个方法必须传参。链式调用与最终序列化ProduceJWT的所有方法返回this这是 jose 生产端 API 的核心体验。一个典型的完整用法如下源自 SignJWT 文档示例const secret new TextEncoder().encode( cc7e0d44fd473002f1c42167459001140ec6389b7353f8088f4d9a95f2f596f2, ) const alg HS256 const jwt await new jose.SignJWT({ urn:example:claim: true }) .setProtectedHeader({ alg }) .setIssuedAt() .setIssuer(urn:example:issuer) .setAudience(urn:example:audience) .setExpirationTime(2h) .sign(secret) console.log(jwt)对应的加密版本EncryptJWT 文档示例结构完全一致仅把setProtectedHeader({ alg })换成同时包含alg与enc的头部并把终端方法sign()换成encrypt()const secret jose.base64url.decode(zH4NRP1HMALxxCFnRZABFA7GOJtzU_gIj02alfL1lvI) const jwt await new jose.EncryptJWT({ urn:example:claim: true }) .setProtectedHeader({ alg: dir, enc: A128CBC-HS256 }) .setIssuedAt() .setIssuer(urn:example:issuer) .setAudience(urn:example:audience) .setExpirationTime(2h) .encrypt(secret) console.log(jwt)未加密场景UnsecuredJWT 文档示例则直接调用同步的encode()const unsecuredJwt new jose.UnsecuredJWT({ urn:example:claim: true }) .setIssuedAt() .setIssuer(urn:example:issuer) .setAudience(urn:example:audience) .setExpirationTime(2h) .encode()内部实现WeakMap 隔离载荷ProduceJWT的方法在底层由JWTClaimsBuilder实现src/lib/jwt_claims_set.ts。值得注意的实现细节是构造器通过structuredClone(payload)深拷贝初始载荷并将结果保存在一个WeakMapobject, JWTPayloadproducerPayloads中按生产者实例隔离数据。当setIssuedAt()未传参时写入的当前时间戳、setExpirationTime(2h)换算出的绝对时间戳最终都进入该 WeakMap 对应的载荷对象。终端方法如SignJWT.sign会调用jwtData(this)src/lib/jwt_claims_set.ts取出载荷并序列化。序列化前还会校验iat、nbf、exp三个时间 Claim 必须是有限数值非有限数值如Infinity会抛出TypeError。时间 Claim 的最终形态绝对时间戳需要特别强调的是字符串时间跨度在写入时就被换算成绝对的 Unix 时间戳而不是把2h原样写进载荷。以setExpirationTime(2h)为例numericDate()src/lib/jwt_claims_set.ts执行epoch(new Date()) secs(2h)得到的exp是一个确定秒数。因此最终 JWT 的 payload 中所有时间 Claim 都是 RFC 7519 定义的 NumericDateUnix 时间戳秒数这也与 JWTPayload 接口 中nbf?: number、exp?: number、iat?: number的类型声明相互印证。与消费端的呼应验证选项对齐ProduceJWT设置的标准 Claim与消费端 JWTClaimVerificationOptions 中的校验选项一一对应生产端setIssuer↔ 消费端issuer选项期望签发者设置后强制要求issClaim 存在生产端setAudience↔ 消费端audience选项期望受众设置后强制要求audClaim 存在生产端setSubject↔ 消费端subject选项期望主体生产端setExpirationTime↔ 消费端exp校验exp now - clockTolerance时抛出 JWTExpired生产端setNotBefore↔ 消费端nbf校验nbf now clockTolerance时校验失败生产端setIssuedAt↔ 消费端maxTokenAge选项设置后强制要求iatClaim 存在并检查 Token 年龄。并且验证侧同样复用了secs()来解析clockTolerance、maxTokenAge等字符串形式的选项src/lib/jwt_claims_set.ts保证生产用 2h验证用 10 minutes这类字符串语义在整条链路上完全一致。这种生产端与消费端的对称设计是 jose 在处理 JWT 时间语义上的一致性保证。使用建议优先使用字符串时间跨度表达相对时间如2h、-1 day、30 minutes from now可读性强且自动换算为绝对时间戳需要精确控制时再直接传number时间戳。setIssuedAt()建议无参调用自动以当前时间为基准配合消费端maxTokenAge可实现Token 签发后 N 秒内有效的滑动窗口策略。同一 Claim 只设置一次JWTClaimsBuilder的赋值是覆盖式写入重复链式调用后值以最后一次为准且SignJWT.setProtectedHeader等头部方法在重复调用时会通过assertNotSet抛错src/jwt/sign.ts因此应避免在链式表达式中重复设置同一属性。结合泛型载荷使用构造器接受的payload为 JWTPayload其中[propName: string]: unknown允许携带任意自定义 Claim标准 Claim 则由上述七方法写入二者互不冲突。延伸阅读SignJWT 类文档签名 JWT 的完整用法与密钥示例PKCS#8、JWKEncryptJWT 类文档加密 JWT 的完整用法与replicateIssuerAsHeader等复制方法UnsecuredJWT 类文档alg: none场景的编码与解码JWTPayload 接口标准 Claim 的完整类型定义JWTClaimVerificationOptions 接口消费端与ProduceJWT一一对应的校验选项secs 单元测试时间跨度解析的完整边界用例JWTClaimsBuilder 实现ProduceJWT契约的底层实现赞分享网络安全认证鉴权后端【免费下载链接】joseJWA, JWS, JWE, JWT, JWK, JWKS for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes项目地址https://gitcode.com/gh_mirrors/jo/jose点击查看免费下载相关推荐LiveCodeBench leaderboard提交指南如何让你的模型快速登上代码能力排行榜LiveCodeBench leaderboard提交指南如何让你的模型快速登上代码能力排行榜 LiveCodeBench是一个全面且无污染的代码大语言模型评网络安全认证鉴权后端解密加密 JWT 的结果契约jose 库 JWTDecryptResult 接口全解析解密加密 JWT 的结果契约jose 库 JWTDecryptResult 接口全解析 jose 是一个为 Node.js、浏览器、Cloudflare Wo网络安全认证鉴权后端jose 中的 decodeJwt免验签解析 JWT Claims Set 的完整指南jose 中的 decodeJwt免验签解析 JWT Claims Set 的完整指南 decodeJwt 是 jose 库中用于解析 JSON Web To网络安全认证鉴权后端上一篇MPV PlayKit开源视频播放器增强方案的终极指南下一篇3小时掌握YOLO人脸检测从零开始的终极实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考