网络安全认证鉴权后端【免费下载链接】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点击查看免费下载CompactSign 是 jose 库中用于构建和签名 Compact JWSJSON Web Signature字符串的核心类。它面向 Node.js、浏览器、Cloudflare Workers、Deno、Bun 等一切 Web 互操作运行时以极简的链式 API 完成「编码载荷 → 设置受保护头 → 计算签名」的全流程。阅读本文后你将掌握 CompactSign 的完整 API、Compact 序列化的三段式结构、全部受支持的签名算法与密钥要求以及如何结合 compactVerify 完成签名与验证的闭环并了解其底层实现与测试验证方式。一、CompactSign 是什么CompactSign 类用于构建并签名 Compact JWS 字符串该类以具名导出named export的方式从主模块入口jose以及子路径导出jose/jws/compact/sign两个入口暴露。主入口的导出位于 src/index.tsexport { CompactSign } from ./jws/compact/sign.js对应源码实现在 src/jws/compact/sign.ts其类型定义与使用说明见 docs/jws/compact/sign/classes/CompactSign.md 关联的类文档。最小可用示例原文档给出了一行可运行的完整示例签名一段托尔金名句并打印三段式 Compact JWS 字符串const jws await new jose.CompactSign( new TextEncoder().encode(It’s a dangerous business, Frodo, going out your door.), ) .setProtectedHeader({ alg: ES256 }) .sign(privateKey) console.log(jws)输出形如eyJhbGciOiJFUzI1NiJ9.base64url载荷.base64url签名的字符串。上述示例同样出现在源码 JSDoc 与测试夹具 test/jws/compact.sign.test.ts 中测试断言了使用 HS256 32 字节密钥时得到的精确 JWS 字符串test(CompactSign, async (t) { const jws await new CompactSign(t.context.payload) .setProtectedHeader({ alg: HS256 }) .sign(t.context.secret) t.is( jws, eyJhbGciOiJIUzI1NiJ9.SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IHlvdXIgZG9vci4.UKohvCM6JaKEJlDt7ApBPgcQMW4lmp-UGXfwPmCfUaA, ) })二、构造函数new CompactSign(payload)new CompactSign(payload): CompactSign参数类型说明payloadUint8Array待签名载荷的二进制表示构造函数唯一的入参是Uint8Array类型的载荷。源码中对此做了严格校验——非Uint8Array实例会直接抛出TypeErrorconstructor(payload: Uint8Array) { if (!(payload instanceof Uint8Array)) { throw new TypeError(payload must be an instance of Uint8Array) } this.#payload payload }因此在传入字符串之前必须先用new TextEncoder().encode(...)将其转换为字节序列。返回CompactSign实例便于继续链式调用setProtectedHeader()与sign()。三、setProtectedHeader()设置受保护头setProtectedHeader(protectedHeader): this参数类型说明protectedHeaderCompactJWSHeaderParametersJWS 受保护头Protected HeadersetProtectedHeader()在 CompactSign 对象上设置 JWS 受保护头返回this支持链式调用。源码中的实现通过assertNotSet保证该方法只能被调用一次重复调用会抛出TypeError(setProtectedHeader can only be called once)setProtectedHeader(protectedHeader: types.CompactJWSHeaderParameters): this { assertNotSet(this.#protectedHeader, setProtectedHeader) this.#protectedHeader protectedHeader return this }对应的测试 test/jws/compact.sign.test.ts 验证了这一行为。受保护头支持哪些成员类型定义CompactJWSHeaderParametersdocs/types/interfaces/CompactJWSHeaderParameters.md声明了 JWS 中已识别的头参数同时保留索引签名允许携带任意其他成员。核心成员包括成员类型含义algstringJWS alg算法头参数必填b64?booleanRFC 7797 扩展头参数修改 JWS 载荷表示与签名输入计算方式crit?string[]crit关键头参数cty?stringcty内容类型头参数jku?stringjkuJWK Set URL头参数jwk?去除私钥与对称密钥字段的JWKjwkJSON Web Key头参数仅允许公钥私钥、对称密钥参数如d、p、q、k一律禁止kid?stringkid密钥 ID头参数typ?stringtyp类型头参数x5c?string[]x5cX.509 证书链头参数x5t?stringx5tX.509 证书 SHA-1 指纹头参数x5u?stringx5uX.509 URL头参数alg是整个签名流程的枢纽sign()阶段会从受保护头中读取alg并据此选择底层 WebCrypto 算法。源码 src/lib/jws_sign.ts 中若alg缺失或不是合法字符串会抛出JWSInvalidfunction signatureAlgorithm(joseHeader: types.JWSHeaderParameters) { const alg joseHeader.alg if (typeof alg ! string || !alg) { throw new JWSInvalid(JWS alg (Algorithm) Header Parameter missing or invalid) } return jwsAlgorithm(alg) }四、sign()签名并输出 Compact JWS 字符串sign(key, options?): Promisestring参数类型说明keyKeyInput用于签名的私钥或共享密钥Secret详见算法密钥要求options?SignOptionsJWS 签名选项sign()是异步方法返回解析为 Compact JWS 字符串的Promise。签名完成后#payload、#protectedHeader和签名值被序列化为protectedHeader.payload.signature三段式 Compact 字符串。sign() 的源码级执行流程CompactSign.sign()的完整实现如下src/jws/compact/sign.tsasync sign(key: types.KeyInput, options?: types.SignOptions): Promisestring { return createCompactSignature(this.#payload, this.#protectedHeader, options?.crit, key, () { throw new TypeError(use the flattened module for creating JWS with b64: false) }) }真正的序列化与签名逻辑在 src/lib/jws_sign.ts 的createCompactSignature中完成export async function createCompactSignature( payload: Uint8Array, inputProtectedHeader: types.JWSHeaderParameters | undefined, inputCrit: { [propName: string]: boolean } | undefined, key: types.KeyInput, rejectUnencoded: () never, ): Promisestring { const [protectedHeader, protectedHeaderString] serializeProtectedHeader(inputProtectedHeader) if (!protectedHeader) { throw new JWSInvalid( either setProtectedHeader or setUnprotectedHeader must be called before #sign(), ) } const b64 validateSignatureHeader(protectedHeader, protectedHeader, inputCrit) if (!b64) rejectUnencoded() const entry signatureAlgorithm(protectedHeader) const encodedPayload b64u(payload) const signature await signSignature(protectedHeaderString, encode(encodedPayload), entry, key) return ${protectedHeaderString}.${encodedPayload}.${signature} }整个过程可以分为五个关键环节头部序列化与 base64url 编码受保护头对象经过规范化serializeJoseHeader后整体做 base64url 编码得到三段式的第一段。必须存在受保护头与 Flattened/General 序列化允许仅使用未受保护头不同Compact 序列化要求必须先调用setProtectedHeader()否则抛出JWSInvalid错误错误码为ERR_JWS_INVALID。测试 test/jws/compact.sign.test.ts 对此有明确断言。签名输入的计算签名输入为base64url(受保护头) . base64url(载荷)的字节拼接concat(encode(protectedHeader), encode(.), payload)见 src/lib/jws_sign.ts。算法解析从alg解析出对应的JWSAlgorithm描述jwsAlgorithm(alg)。密钥准备与 WebCrypto 签名prepareKey将KeyInput归一化为可用的CryptoKey或Uint8Array随后调用crypto.subtle.sign完成计算src/lib/signing.ts。Compact JWS 的三段式结构签名结果严格遵循 RFC 7515 的 Compact 序列化格式BASE64URL(UTF8(JWS Protected Header)) || . || BASE64URL(JWS Payload) || . || BASE64URL(JWS Signature)以测试中的 HS256 断言为例三段分别对应第一段eyJhbGciOiJIUzI1NiJ9受保护头{alg:HS256}的 base64url 编码第二段SXTigJlzIG...载荷字节的 base64url 编码不含填充符第三段UKohvCM6JaK...HMAC 签名值的 base64url 编码。b64 扩展与 Compact 序列化的边界sign()的第三个回调参数专门用于拒绝非 base64url 载荷由于 Compact 序列化没有承载未编码载荷的位置当受保护头声明b64: falseRFC 7797 的未编码载荷扩展时会立即抛出TypeError(use the flattened module for creating JWS with b64: false)提示改用 Flattened 模块。对应测试见 test/jws/compact.sign.test.ts。五、sign() 的密钥与算法要求key参数接受KeyInput类型docs/types/type-aliases/KeyInput.md即以下四种之一KeyInput CryptoKey | KeyObject | JWK | Uint8Array也就是说你可以直接传入 WebCrypto 的CryptoKey、Node.js 的KeyObject、JWK 对象或作为 HMAC 共享密钥的Uint8Array。所有 sign/verify/encrypt/decrypt 操作统一接受该类型。当前支持的 JWS 签名算法从 src/lib/jws_algorithms.ts 的算法注册表可以看到CompactSign 支持的alg与底层 WebCrypto 算法的对应关系alg密钥类型底层 WebCrypto 算法附加约束HS256/HS384/HS512oct共享密钥HMAC SHA-256/384/512密钥为Uint8Array或对称CryptoKeyRS256/RS384/RS512RSA私钥RSASSA-PKCS1-v1_5 SHA-2模长不低于 2048 位minRsaBits: 2048PS256/PS384/PS512RSA私钥RSA-PSS SHA-2saltLength 32/48/64模长不低于 2048 位ES256/ES384/ES512EC私钥ECDSA SHA-256/384/512曲线 P-256/P-384/P-521曲线与哈希一一对应EdDSA/Ed25519OKP私钥Ed25519两者指向同一实现ML-DSA-44/ML-DSA-65/ML-DSA-87AKP私钥ML-DSA-44/65/87后量子签名算法依赖运行时的 WebCrypto 支持当传入的alg未被实现或运行时不支持时jwsAlgorithm()会抛出JOSENotSupported错误src/lib/jws_algorithms.ts。RSA 密钥的模长检查checkModulusLength在 src/lib/signing.ts 中于签名前执行低于 2048 位会被拒绝。RFC 7520 官方向量验证仓库的 cookbook/jws.mjs 收录了多个与 CompactSign 直接对应的标准向量可作为算法正确性的交叉验证RFC 7520 §4.1RS256 RSA 私钥输出三段式 Compact 字符串RFC 7520 §4.2PS384RSA-PSSRFC 7520 §4.3ES512ECDSA P-521RFC 7520 §4.4HS256HMAC-SHA2RFC 8037 附录 A.4EdDSAEd25519ietf-cose-dilithiumML-DSA-44 / ML-DSA-65 / ML-DSA-87 后量子签名。每个向量的signing.protected字段给出了受保护头的推荐写法例如 RFC 7520 §4.1 使用{ alg: RS256, kid: bilbo.bagginshobbiton.example }。六、SignOptionscrit 关键头选项sign()的第二个可选参数options类型为SignOptionsdocs/types/interfaces/SignOptions.md目前仅有一个成员成员类型说明crit?object以「头参数名 → 布尔值」形式声明关键头参数值为true表示该头参数必须被完整性保护false表示无关紧要crit 的语义与安全警告crit选项的键代表已识别的crit头参数名。JWS 扩展头参数b64始终被内建识别并正确处理除此之外目前没有其他注册头参数获得这种内建处理。使用时有两点必须注意该选项仅校验头参数在提供时的语法正确性与可选的完整性保护它不会处理头参数也不会在头参数缺失时拒绝操作签名成功后你必须自行按照应用协议的验证步骤确认该头参数确实存在并按规范处理crit选项本身不承担语义验证。从源码看options?.crit会被透传到createCompactSignature的validateSignatureHeader再经validateCrit与validateCritDuplicates做校验src/lib/jws_sign.ts。测试 test/jws/compact.sign.test.ts 也验证了crit选项会在头部校验之前被读取。七、常见错误与边界行为速查综合 test/jws/compact.sign.test.ts 与源码抛错路径CompactSign 的典型失败场景如下场景抛出的错误触发条件载荷非Uint8ArrayTypeError构造时校验失败重复调用setProtectedHeaderTypeError(setProtectedHeader can only be called once)受保护头被二次设置未设置任何头就调用signJWSInvalidcodeERR_JWS_INVALIDCompact 序列化必须有受保护头受保护头缺少algJWSInvalid(JWS alg ... missing or invalid)alg缺失或非字符串声明b64: falseTypeError(use the flattened module for creating JWS with b64: false)Compact 不支持未编码载荷alg不受支持JOSENotSupported运行时/实现不支持该算法八、与 compactVerify 组成完整闭环签名之后通常需要验证。仓库在 docs/jws/compact/verify/functions/compactVerify.md 中提供了对应的compactVerify()函数const { payload, protectedHeader } await jose.compactVerify(jws, publicKey) console.log(protectedHeader) console.log(new TextDecoder().decode(payload))compactVerify(jws, key, options?)校验 Compact JWS 的签名与格式后解码载荷返回{ payload, protectedHeader }重载形式compactVerify(jws, getKey, options?)支持通过getKey函数动态解析验证密钥结果中额外携带已解析的密钥。一个完整的端到端流程是const jws await new jose.CompactSign( new TextEncoder().encode(It’s a dangerous business, Frodo, going out your door.), ) .setProtectedHeader({ alg: ES256, kid: bilbo.bagginshobbiton.example }) .sign(privateKey) const { payload, protectedHeader } await jose.compactVerify(jws, publicKey) console.log(protectedHeader) // { alg: ES256, kid: ... } console.log(new TextDecoder().decode(payload))九、相关参考路径类文档docs/jws/compact/sign/classes/CompactSign.md类实现src/jws/compact/sign.ts签名核心逻辑src/lib/jws_sign.tsWebCrypto 签名封装src/lib/signing.ts算法注册表src/lib/jws_algorithms.ts单元测试test/jws/compact.sign.test.ts标准签名向量cookbook/jws.mjs头参数类型docs/types/interfaces/CompactJWSHeaderParameters.md签名选项类型docs/types/interfaces/SignOptions.md密钥输入类型docs/types/type-aliases/KeyInput.md验证函数docs/jws/compact/verify/functions/compactVerify.md十、适用前提与限制CompactSign 面向所有提供 WebCryptocrypto.subtle的运行时包括 Node.js、浏览器、Cloudflare Workers、Deno、Bun 等具体可用的算法受运行时 WebCrypto 能力约束例如 ML-DSA 系列需要运行时原生支持。签名属于异步操作sign()返回Promise需要await。Compact 序列化要求受保护头必须存在且不支持b64: false这类需求应改用 Flattened 模块的FlattenedSign。载荷必须为二进制字节Uint8Array字符串载荷需先行TextEncoder编码。综上CompactSign 以最小化的链式 API 覆盖了 Compact JWS 的完整签名路径构造时编码载荷、setProtectedHeader声明算法与头信息、sign完成密钥准备与 WebCrypto 计算。结合本文的算法表、错误速查与 RFC 向量你可以在各种 Web 互操作运行时中稳定地生产、验证 Compact JWS。赞分享网络安全认证鉴权后端【免费下载链接】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 库 CompactSign 类详解构建与签名 Compact JWS 字符串的完整指南jose 库 CompactSign 类详解构建与签名 Compact JWS 字符串的完整指南 CompactSign 是 jose 模块中用于构建并签名网络安全认证鉴权后端jose 库 GeneralSign 类完全指南构建与签名 General JWS通用 JSON 序列化签名对象jose 库 GeneralSign 类完全指南构建与签名 General JWS通用 JSON 序列化签名对象 导读 GeneralSign 是 jos网络安全认证鉴权后端jose 库 compactVerify() 完全指南Compact JWS 签名验证与动态密钥解析jose 库 compactVerify 完全指南Compact JWS 签名验证与动态密钥解析 导读 compactVerify 是 jose https:网络安全认证鉴权后端上一篇如何利用霞鹜文楷优化跨语言排版体验从技术架构到实际应用下一篇Ruff 0.10.x 变更日志深度解析TYPE_CHECKING 行为变化、统一 noqa 语法与规则稳定化清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
jose CompactSign 完全指南：使用 Compact 序列化生成与签名 JWS
网络安全认证鉴权后端【免费下载链接】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点击查看免费下载CompactSign 是 jose 库中用于构建和签名 Compact JWSJSON Web Signature字符串的核心类。它面向 Node.js、浏览器、Cloudflare Workers、Deno、Bun 等一切 Web 互操作运行时以极简的链式 API 完成「编码载荷 → 设置受保护头 → 计算签名」的全流程。阅读本文后你将掌握 CompactSign 的完整 API、Compact 序列化的三段式结构、全部受支持的签名算法与密钥要求以及如何结合 compactVerify 完成签名与验证的闭环并了解其底层实现与测试验证方式。一、CompactSign 是什么CompactSign 类用于构建并签名 Compact JWS 字符串该类以具名导出named export的方式从主模块入口jose以及子路径导出jose/jws/compact/sign两个入口暴露。主入口的导出位于 src/index.tsexport { CompactSign } from ./jws/compact/sign.js对应源码实现在 src/jws/compact/sign.ts其类型定义与使用说明见 docs/jws/compact/sign/classes/CompactSign.md 关联的类文档。最小可用示例原文档给出了一行可运行的完整示例签名一段托尔金名句并打印三段式 Compact JWS 字符串const jws await new jose.CompactSign( new TextEncoder().encode(It’s a dangerous business, Frodo, going out your door.), ) .setProtectedHeader({ alg: ES256 }) .sign(privateKey) console.log(jws)输出形如eyJhbGciOiJFUzI1NiJ9.base64url载荷.base64url签名的字符串。上述示例同样出现在源码 JSDoc 与测试夹具 test/jws/compact.sign.test.ts 中测试断言了使用 HS256 32 字节密钥时得到的精确 JWS 字符串test(CompactSign, async (t) { const jws await new CompactSign(t.context.payload) .setProtectedHeader({ alg: HS256 }) .sign(t.context.secret) t.is( jws, eyJhbGciOiJIUzI1NiJ9.SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IHlvdXIgZG9vci4.UKohvCM6JaKEJlDt7ApBPgcQMW4lmp-UGXfwPmCfUaA, ) })二、构造函数new CompactSign(payload)new CompactSign(payload): CompactSign参数类型说明payloadUint8Array待签名载荷的二进制表示构造函数唯一的入参是Uint8Array类型的载荷。源码中对此做了严格校验——非Uint8Array实例会直接抛出TypeErrorconstructor(payload: Uint8Array) { if (!(payload instanceof Uint8Array)) { throw new TypeError(payload must be an instance of Uint8Array) } this.#payload payload }因此在传入字符串之前必须先用new TextEncoder().encode(...)将其转换为字节序列。返回CompactSign实例便于继续链式调用setProtectedHeader()与sign()。三、setProtectedHeader()设置受保护头setProtectedHeader(protectedHeader): this参数类型说明protectedHeaderCompactJWSHeaderParametersJWS 受保护头Protected HeadersetProtectedHeader()在 CompactSign 对象上设置 JWS 受保护头返回this支持链式调用。源码中的实现通过assertNotSet保证该方法只能被调用一次重复调用会抛出TypeError(setProtectedHeader can only be called once)setProtectedHeader(protectedHeader: types.CompactJWSHeaderParameters): this { assertNotSet(this.#protectedHeader, setProtectedHeader) this.#protectedHeader protectedHeader return this }对应的测试 test/jws/compact.sign.test.ts 验证了这一行为。受保护头支持哪些成员类型定义CompactJWSHeaderParametersdocs/types/interfaces/CompactJWSHeaderParameters.md声明了 JWS 中已识别的头参数同时保留索引签名允许携带任意其他成员。核心成员包括成员类型含义algstringJWS alg算法头参数必填b64?booleanRFC 7797 扩展头参数修改 JWS 载荷表示与签名输入计算方式crit?string[]crit关键头参数cty?stringcty内容类型头参数jku?stringjkuJWK Set URL头参数jwk?去除私钥与对称密钥字段的JWKjwkJSON Web Key头参数仅允许公钥私钥、对称密钥参数如d、p、q、k一律禁止kid?stringkid密钥 ID头参数typ?stringtyp类型头参数x5c?string[]x5cX.509 证书链头参数x5t?stringx5tX.509 证书 SHA-1 指纹头参数x5u?stringx5uX.509 URL头参数alg是整个签名流程的枢纽sign()阶段会从受保护头中读取alg并据此选择底层 WebCrypto 算法。源码 src/lib/jws_sign.ts 中若alg缺失或不是合法字符串会抛出JWSInvalidfunction signatureAlgorithm(joseHeader: types.JWSHeaderParameters) { const alg joseHeader.alg if (typeof alg ! string || !alg) { throw new JWSInvalid(JWS alg (Algorithm) Header Parameter missing or invalid) } return jwsAlgorithm(alg) }四、sign()签名并输出 Compact JWS 字符串sign(key, options?): Promisestring参数类型说明keyKeyInput用于签名的私钥或共享密钥Secret详见算法密钥要求options?SignOptionsJWS 签名选项sign()是异步方法返回解析为 Compact JWS 字符串的Promise。签名完成后#payload、#protectedHeader和签名值被序列化为protectedHeader.payload.signature三段式 Compact 字符串。sign() 的源码级执行流程CompactSign.sign()的完整实现如下src/jws/compact/sign.tsasync sign(key: types.KeyInput, options?: types.SignOptions): Promisestring { return createCompactSignature(this.#payload, this.#protectedHeader, options?.crit, key, () { throw new TypeError(use the flattened module for creating JWS with b64: false) }) }真正的序列化与签名逻辑在 src/lib/jws_sign.ts 的createCompactSignature中完成export async function createCompactSignature( payload: Uint8Array, inputProtectedHeader: types.JWSHeaderParameters | undefined, inputCrit: { [propName: string]: boolean } | undefined, key: types.KeyInput, rejectUnencoded: () never, ): Promisestring { const [protectedHeader, protectedHeaderString] serializeProtectedHeader(inputProtectedHeader) if (!protectedHeader) { throw new JWSInvalid( either setProtectedHeader or setUnprotectedHeader must be called before #sign(), ) } const b64 validateSignatureHeader(protectedHeader, protectedHeader, inputCrit) if (!b64) rejectUnencoded() const entry signatureAlgorithm(protectedHeader) const encodedPayload b64u(payload) const signature await signSignature(protectedHeaderString, encode(encodedPayload), entry, key) return ${protectedHeaderString}.${encodedPayload}.${signature} }整个过程可以分为五个关键环节头部序列化与 base64url 编码受保护头对象经过规范化serializeJoseHeader后整体做 base64url 编码得到三段式的第一段。必须存在受保护头与 Flattened/General 序列化允许仅使用未受保护头不同Compact 序列化要求必须先调用setProtectedHeader()否则抛出JWSInvalid错误错误码为ERR_JWS_INVALID。测试 test/jws/compact.sign.test.ts 对此有明确断言。签名输入的计算签名输入为base64url(受保护头) . base64url(载荷)的字节拼接concat(encode(protectedHeader), encode(.), payload)见 src/lib/jws_sign.ts。算法解析从alg解析出对应的JWSAlgorithm描述jwsAlgorithm(alg)。密钥准备与 WebCrypto 签名prepareKey将KeyInput归一化为可用的CryptoKey或Uint8Array随后调用crypto.subtle.sign完成计算src/lib/signing.ts。Compact JWS 的三段式结构签名结果严格遵循 RFC 7515 的 Compact 序列化格式BASE64URL(UTF8(JWS Protected Header)) || . || BASE64URL(JWS Payload) || . || BASE64URL(JWS Signature)以测试中的 HS256 断言为例三段分别对应第一段eyJhbGciOiJIUzI1NiJ9受保护头{alg:HS256}的 base64url 编码第二段SXTigJlzIG...载荷字节的 base64url 编码不含填充符第三段UKohvCM6JaK...HMAC 签名值的 base64url 编码。b64 扩展与 Compact 序列化的边界sign()的第三个回调参数专门用于拒绝非 base64url 载荷由于 Compact 序列化没有承载未编码载荷的位置当受保护头声明b64: falseRFC 7797 的未编码载荷扩展时会立即抛出TypeError(use the flattened module for creating JWS with b64: false)提示改用 Flattened 模块。对应测试见 test/jws/compact.sign.test.ts。五、sign() 的密钥与算法要求key参数接受KeyInput类型docs/types/type-aliases/KeyInput.md即以下四种之一KeyInput CryptoKey | KeyObject | JWK | Uint8Array也就是说你可以直接传入 WebCrypto 的CryptoKey、Node.js 的KeyObject、JWK 对象或作为 HMAC 共享密钥的Uint8Array。所有 sign/verify/encrypt/decrypt 操作统一接受该类型。当前支持的 JWS 签名算法从 src/lib/jws_algorithms.ts 的算法注册表可以看到CompactSign 支持的alg与底层 WebCrypto 算法的对应关系alg密钥类型底层 WebCrypto 算法附加约束HS256/HS384/HS512oct共享密钥HMAC SHA-256/384/512密钥为Uint8Array或对称CryptoKeyRS256/RS384/RS512RSA私钥RSASSA-PKCS1-v1_5 SHA-2模长不低于 2048 位minRsaBits: 2048PS256/PS384/PS512RSA私钥RSA-PSS SHA-2saltLength 32/48/64模长不低于 2048 位ES256/ES384/ES512EC私钥ECDSA SHA-256/384/512曲线 P-256/P-384/P-521曲线与哈希一一对应EdDSA/Ed25519OKP私钥Ed25519两者指向同一实现ML-DSA-44/ML-DSA-65/ML-DSA-87AKP私钥ML-DSA-44/65/87后量子签名算法依赖运行时的 WebCrypto 支持当传入的alg未被实现或运行时不支持时jwsAlgorithm()会抛出JOSENotSupported错误src/lib/jws_algorithms.ts。RSA 密钥的模长检查checkModulusLength在 src/lib/signing.ts 中于签名前执行低于 2048 位会被拒绝。RFC 7520 官方向量验证仓库的 cookbook/jws.mjs 收录了多个与 CompactSign 直接对应的标准向量可作为算法正确性的交叉验证RFC 7520 §4.1RS256 RSA 私钥输出三段式 Compact 字符串RFC 7520 §4.2PS384RSA-PSSRFC 7520 §4.3ES512ECDSA P-521RFC 7520 §4.4HS256HMAC-SHA2RFC 8037 附录 A.4EdDSAEd25519ietf-cose-dilithiumML-DSA-44 / ML-DSA-65 / ML-DSA-87 后量子签名。每个向量的signing.protected字段给出了受保护头的推荐写法例如 RFC 7520 §4.1 使用{ alg: RS256, kid: bilbo.bagginshobbiton.example }。六、SignOptionscrit 关键头选项sign()的第二个可选参数options类型为SignOptionsdocs/types/interfaces/SignOptions.md目前仅有一个成员成员类型说明crit?object以「头参数名 → 布尔值」形式声明关键头参数值为true表示该头参数必须被完整性保护false表示无关紧要crit 的语义与安全警告crit选项的键代表已识别的crit头参数名。JWS 扩展头参数b64始终被内建识别并正确处理除此之外目前没有其他注册头参数获得这种内建处理。使用时有两点必须注意该选项仅校验头参数在提供时的语法正确性与可选的完整性保护它不会处理头参数也不会在头参数缺失时拒绝操作签名成功后你必须自行按照应用协议的验证步骤确认该头参数确实存在并按规范处理crit选项本身不承担语义验证。从源码看options?.crit会被透传到createCompactSignature的validateSignatureHeader再经validateCrit与validateCritDuplicates做校验src/lib/jws_sign.ts。测试 test/jws/compact.sign.test.ts 也验证了crit选项会在头部校验之前被读取。七、常见错误与边界行为速查综合 test/jws/compact.sign.test.ts 与源码抛错路径CompactSign 的典型失败场景如下场景抛出的错误触发条件载荷非Uint8ArrayTypeError构造时校验失败重复调用setProtectedHeaderTypeError(setProtectedHeader can only be called once)受保护头被二次设置未设置任何头就调用signJWSInvalidcodeERR_JWS_INVALIDCompact 序列化必须有受保护头受保护头缺少algJWSInvalid(JWS alg ... missing or invalid)alg缺失或非字符串声明b64: falseTypeError(use the flattened module for creating JWS with b64: false)Compact 不支持未编码载荷alg不受支持JOSENotSupported运行时/实现不支持该算法八、与 compactVerify 组成完整闭环签名之后通常需要验证。仓库在 docs/jws/compact/verify/functions/compactVerify.md 中提供了对应的compactVerify()函数const { payload, protectedHeader } await jose.compactVerify(jws, publicKey) console.log(protectedHeader) console.log(new TextDecoder().decode(payload))compactVerify(jws, key, options?)校验 Compact JWS 的签名与格式后解码载荷返回{ payload, protectedHeader }重载形式compactVerify(jws, getKey, options?)支持通过getKey函数动态解析验证密钥结果中额外携带已解析的密钥。一个完整的端到端流程是const jws await new jose.CompactSign( new TextEncoder().encode(It’s a dangerous business, Frodo, going out your door.), ) .setProtectedHeader({ alg: ES256, kid: bilbo.bagginshobbiton.example }) .sign(privateKey) const { payload, protectedHeader } await jose.compactVerify(jws, publicKey) console.log(protectedHeader) // { alg: ES256, kid: ... } console.log(new TextDecoder().decode(payload))九、相关参考路径类文档docs/jws/compact/sign/classes/CompactSign.md类实现src/jws/compact/sign.ts签名核心逻辑src/lib/jws_sign.tsWebCrypto 签名封装src/lib/signing.ts算法注册表src/lib/jws_algorithms.ts单元测试test/jws/compact.sign.test.ts标准签名向量cookbook/jws.mjs头参数类型docs/types/interfaces/CompactJWSHeaderParameters.md签名选项类型docs/types/interfaces/SignOptions.md密钥输入类型docs/types/type-aliases/KeyInput.md验证函数docs/jws/compact/verify/functions/compactVerify.md十、适用前提与限制CompactSign 面向所有提供 WebCryptocrypto.subtle的运行时包括 Node.js、浏览器、Cloudflare Workers、Deno、Bun 等具体可用的算法受运行时 WebCrypto 能力约束例如 ML-DSA 系列需要运行时原生支持。签名属于异步操作sign()返回Promise需要await。Compact 序列化要求受保护头必须存在且不支持b64: false这类需求应改用 Flattened 模块的FlattenedSign。载荷必须为二进制字节Uint8Array字符串载荷需先行TextEncoder编码。综上CompactSign 以最小化的链式 API 覆盖了 Compact JWS 的完整签名路径构造时编码载荷、setProtectedHeader声明算法与头信息、sign完成密钥准备与 WebCrypto 计算。结合本文的算法表、错误速查与 RFC 向量你可以在各种 Web 互操作运行时中稳定地生产、验证 Compact JWS。赞分享网络安全认证鉴权后端【免费下载链接】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 库 CompactSign 类详解构建与签名 Compact JWS 字符串的完整指南jose 库 CompactSign 类详解构建与签名 Compact JWS 字符串的完整指南 CompactSign 是 jose 模块中用于构建并签名网络安全认证鉴权后端jose 库 GeneralSign 类完全指南构建与签名 General JWS通用 JSON 序列化签名对象jose 库 GeneralSign 类完全指南构建与签名 General JWS通用 JSON 序列化签名对象 导读 GeneralSign 是 jos网络安全认证鉴权后端jose 库 compactVerify() 完全指南Compact JWS 签名验证与动态密钥解析jose 库 compactVerify 完全指南Compact JWS 签名验证与动态密钥解析 导读 compactVerify 是 jose https:网络安全认证鉴权后端上一篇如何利用霞鹜文楷优化跨语言排版体验从技术架构到实际应用下一篇Ruff 0.10.x 变更日志深度解析TYPE_CHECKING 行为变化、统一 noqa 语法与规则稳定化清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
