jose 中 Compact JWE 解密结果类型 CompactDecryptResult 全面解析

网络安全认证鉴权后端【免费下载链接】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点击查看免费下载CompactDecryptResult是 jose 库中compactDecrypt()函数对紧凑序列化Compact SerializationJWE 解密成功后返回的结果对象类型它承载解密后的明文与受完整性保护的 JOSE 头。本文以 CompactDecryptResult.md 为骨架结合src/jwe/compact/decrypt.ts、src/lib/jwe_decrypt.ts等源码与测试深入讲解该类型的每个字段、其产生过程、使用方式与底层解密流程帮助你在 Node.js、浏览器、Deno、Bun、Cloudflare Workers 等运行时中正确消费解密结果。一、CompactDecryptResult 是什么CompactDecryptResult是一个 TypeScript 接口定义在 src/types.d.ts/** Compact JWE decryption result */ export interface CompactDecryptResult { /** Plaintext. */ plaintext: Uint8Array /** JWE Protected Header. */ protectedHeader: CompactJWEHeaderParameters }它是compactDecrypt()的返回值类型PromiseCompactDecryptResult同时也是 jose 公共 API 的一部分——从主入口jose与子路径jose/jwe/compact/decrypt均以命名导出的方式暴露见 src/index.ts 与 src/jwe/compact/decrypt.ts。与 Flattened扁平和 General通用序列化的解密结果不同Compact JWE 只使用受完整性保护的 Header即protected段因此结果中没有sharedUnprotectedHeader、unprotectedHeader、additionalAuthenticatedData等可选字段字段结构最简洁只有plaintext和protectedHeader两个成员。二、接口字段详解plaintext解密后的明文类型Uint8Array语义通过内容加密密钥CEK对密文执行认证解密后得到的原始字节流。plaintext是Uint8Array而非字符串这是 jose 全库一致的设计原则加密前的输入也必须传Uint8Array。拿到结果后通常需要借助TextDecoder将其还原为文本例如 compactDecrypt 函数文档 中的示例const { plaintext, protectedHeader } await jose.compactDecrypt(jwe, privateKey) console.log(protectedHeader) console.log(new TextDecoder().decode(plaintext))若明文本身就是二进制数据如密钥、图片字节、自定义序列化格式直接使用plaintext即可无需经过字符串转换。protectedHeaderJWE Protected Header类型CompactJWEHeaderParameters语义JWE 中受完整性保护的 Header 参数对象。在 Compact 序列化中它是唯一的 Header 载体alg与enc等关键参数全部从此解析。CompactJWEHeaderParameters的完整定义见 CompactJWEHeaderParameters.md其结构要点如下参数类型必需说明algstring✅JWE algAlgorithm密钥管理算法头参数encstring✅JWE encEncryption Algorithm内容加密算法头参数critstring[]可选JWE critCritical关键头参数ctystring可选ctyContent Type内容类型头参数jkustring可选jkuJWK Set URLJWK 集合地址头参数jwkOmitJWK, d \| p \| q \| k \| dp \| dq \| qi \| priv \| oth可选jwkJSON Web Key头参数仅允许公钥私钥与对称密钥参数被排除kidstring可选kidKey ID密钥标识头参数typstring可选typType类型头参数x5cstring[]可选x5cX.509 Certificate Chain证书链头参数x5tstring可选x5tX.509 Certificate SHA-1 Thumbprint证书指纹头参数x5ustring可选x5uX.509 URL证书地址头参数zipstring可选JWE zipCompression Algorithm压缩算法头参数唯一支持值DEFDEFLATE且要求运行时具备CompressionStream/DecompressionStreamAPI此外该接口带索引签名[propName: string]: unknown意味着任何其他未识别的 JWE Header 成员也可以出现在对象上类型层面不会阻止你读取自定义头参数。三、compactDecrypt 如何产出这个结果compactDecrypt()有三个重载见 src/jwe/compact/decrypt.ts返回结果随调用方式略有差异直接传密钥compactDecrypt(jwe, key, options?)→PromiseCompactDecryptResult结果只有plaintext与protectedHeader传密钥解析函数compactDecryptKeyType(jwe, getKey, options?)→PromiseCompactDecryptResult ResolvedKeyKeyType结果在基础字段之上额外携带key字段即最终解析出的实际解密密钥转发场景compactDecrypt(jwe, key, options?)接受密钥或解析函数二选一返回CompactDecryptResult PartialResolvedKey——key仅在传入解析函数时出现。实现层的关键代码在 src/jwe/compact/decrypt.tsconst decrypted await decryptCompact(jwe, prepareDecrypt(options), key) const result { plaintext: decrypted[0], protectedHeader: decrypted[1]! } if (typeof key function) { return { ...result, key: decrypted[2] } } return result可见protectedHeader来自decryptCompact内部解析出的parsedProtCompact 序列化下必然存在因此使用非空断言!plaintext则是decryptRecipientCore完成认证解密与可选解压后的最终字节流。四、处理解密密文的实战姿势plaintext是二进制字节常见的消费方式有三种// 1. 还原为 UTF-8 文本 const text new TextDecoder().decode(result.plaintext) // 2. 还原为 JSON const payload JSON.parse(new TextDecoder().decode(result.plaintext)) // 3. 直接作为二进制处理图片、文件、密钥材料等 const bytes result.plaintext // Uint8Array在 JWE 加密JWTJWE 序列化的 JWT的场景中解密结果中的明文就是 JWT Claims Set 的 JSON 字节可结合jwtDecrypt或手动JSON.parse继续消费。测试 test/jwe/compact.decrypt.test.ts 展示了典型的加密→解密→比对闭环const jwe await new CompactEncrypt(plaintext) .setProtectedHeader({ alg: dir, enc: A128GCM }) .setInitializationVector(new Uint8Array(12)) .encrypt(secret) const result await compactDecrypt(new TextEncoder().encode(jwe), (protectedHeader, token) { // 解析函数中可以读取 protectedHeader 与 token 成员动态决定用哪把密钥 return secret }) // 结果与原始明文逐字节相等 t.deepEqual(result.plaintext, plaintext) t.is(result.key, secret) // 使用解析函数时返回额外携带的 key五、结果中的 protectedHeader 值得关注的点解密成功后protectedHeader.alg与protectedHeader.enc就是实际生效的密钥管理与内容加密算法它们决定了整个解密路径alg对应密钥管理算法dir、RSA-OAEP、RSA-OAEP-256、A128KW、ECDH-ES、ECDH-ESA128KW、PBES2-HS256A128KW等enc对应内容加密算法A128GCM、A192GCM、A256GCM、A128CBC-HS256、A192CBC-HS384、A256CBC-HS512等。在 cookbook/jwe.mjs 中可以找到各算法组合的官方 RFC 7520 互操作向量例如第 5.2 节RSA-OAEPA256GCM、第 5.6 节dirA128GCM、第 5.9 节带zip: DEF压缩等均包含可以直接验证的 Compact JWE 样例字符串。若protectedHeader.zip DEF说明明文在加密前经过了 DEFLATE 压缩解密时 jose 会自动解压见 src/lib/jwe_decrypt.ts此时plaintext是解压后的最终明文你无需手动处理。六、解密结果的底层产生流程从CompactDecryptResult的两个字段出发可以顺藤摸瓜看到 jose 完整的解密链路核心实现在 src/lib/jwe_decrypt.ts格式校验与切分decryptCompact将 Compact JWE 按.切分为 5 段protected、encrypted_key、iv、ciphertext、tag段数不为 5 时抛出JWEInvalidInvalid Compact JWEHeader 解析对protected段做 base64url 解码与 JSON 解析得到parsedProt即结果中的protectedHeader来源算法校验decryptRecipientCore检查alg、enc是否存在并通过crit、keyManagementAlgorithms、contentEncryptionAlgorithms等选项做白名单拦截命中限制时抛JOSEAlgNotAllowed见 src/lib/jwe_decrypt.ts密钥管理与 CEK 恢复decryptKeyManagement按alg恢复内容加密密钥 CEK。值得注意的安全细节当密钥管理失败时jose 依据 RFC 7516 第 11.5 节替换为随机生成的 CEK 继续执行避免区分格式、填充、长度错误而引入时序攻击见 src/lib/jwe_decrypt.ts内容认证解密decrypt()见 src/lib/content_encryption.ts按enc分发到 AES-GCMgcmDecrypt校验 128 位 tag 与 IV 长度或 AES-CBC HMACcbcDecrypt先常数时间比对 tag 再解密不匹配抛JWEDecryptionFailed可选解压zip DEF时使用DecompressionStream解压受maxDecompressedLength限制默认 250 KB设为0拒绝一切压缩 JWE设为Infinity关闭限制组装结果{ plaintext, protectedHeader }返回若传入解析函数则追加key。由此可以推断protectedHeader的alg/enc值直接决定第 45 步走哪条密码学路径而plaintext是经过完整认证GCM tag 或 HMAC验证后的可信输出——任何篡改都会在解密阶段失败并抛出JWEDecryptionFailed或JWEInvalid不会进入结果对象。七、与 Flattened / General 解密结果的对比字段CompactDecryptResultFlattenedDecryptResult / GeneralDecryptResultplaintext✅ 必有✅ 必有protectedHeader✅ 必有CompactJWEHeaderParameters⭕ 可选sharedUnprotectedHeader❌ 不存在⭕ 可选unprotectedHeader❌ 不存在⭕ 可选additionalAuthenticatedData❌ 不存在⭕ 可选对比定义见 src/types.d.ts。Compact 序列化只有 5 段、单一收件人、无 AAD 与非保护头因此结果接口刻意保持最小化这也是该类型在 TypeScript 层面承诺的字段一定存在、消费时无需做可选判断的原因。如果你需要处理多收件人、共享非保护头或 AAD则应使用flattenedDecrypt/generalDecrypt对应的结果类型。八、相关文档与进一步阅读compactDecrypt 函数文档三个重载签名、参数与返回值细节CompactJWEHeaderParameters.mdprotectedHeader字段的完整类型定义DecryptOptions.md解密选项keyManagementAlgorithms、contentEncryptionAlgorithms、crit、maxPBES2Count、maxDecompressedLength与 PBES2 默认限制默认p2c上限 10000KeyInput.mdkey参数可接受的密钥输入形式CryptoKey、KeyObject、Uint8Array、JWKtest/jwe/compact.decrypt.test.ts格式校验、成员解码顺序、解析函数与结果字段的单元测试cookbook/jwe.mjsRFC 7520 全量互操作向量可直接用于验证解密结果。总结CompactDecryptResult以最精简的两个字段——plaintext: Uint8Array与protectedHeader: CompactJWEHeaderParameters——完整封装了 Compact JWE 解密的产出前者是经过认证解密必要时解压后的可信明文后者是驱动整个解密路径的关键 Header 参数集合。理解它的字段语义、产生过程与底层校验链能让你在 jose 中安全、正确地消费各类 Compact JWE 解密结果无论是普通加密消息、压缩内容还是基于动态密钥解析函数的高并发场景。赞分享网络安全认证鉴权后端【免费下载链接】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点击查看免费下载相关推荐Faker 日本媒体模块实战使用 Faker::JapaneseMedia::Doraemon 生成哆啦A梦主题假数据Faker 日本媒体模块实战使用 Faker::JapaneseMedia::Doraemon 生成哆啦A梦主题假数据 本指南围绕 Faker 项目日本媒体网络安全认证鉴权后端KubeSphere 中的 Go JOSEgo-jose v2JWE / JWS / JWT 加密签名库深度解析KubeSphere 中的 Go JOSEgo jose v2JWE / JWS / JWT 加密签名库深度解析 本文以 KubeSphere 仓库中 v后端云原生容器编排微服务Haystack Embedders 组件完全指南从 OpenAI 到 Sentence Transformers 的文本、文档与稀疏向量嵌入Haystack Embedders 组件完全指南从 OpenAI 到 Sentence Transformers 的文本、文档与稀疏向量嵌入 本文是 Hay网络安全认证鉴权后端上一篇Qwen3-14B-AWQ2025年大模型效率革命的轻量化标杆下一篇create-react-native-app模板全解析3步打造个性化React Native项目创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考