网络安全认证鉴权后端【免费下载链接】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点击查看免费下载CryptoKey是 jose 库在 TypeScript 类型系统中对 Web Crypto API 密钥对象的标准抽象它贯穿签名、验签、加密、解密等全部核心操作。本文将以 docs/types/type-aliases/CryptoKey.md 为主线结合 src/types.d.ts 的源码实现讲解该类型别名的推导逻辑、结构化属性、获取途径以及在 KeyInput 密钥输入体系中的地位帮助读者在 Node.js、浏览器、Cloudflare Workers、Deno、Bun 等 Web 互操作运行时中正确理解和使用密钥对象。一、类型别名的定义从全局 Web Crypto API 推导jose 对CryptoKey的定义并非硬编码的结构体而是通过 TypeScript 条件类型从宿主运行时的全局声明中动态推导export type CryptoKey typeof globalThis extends { crypto: { subtle: { generateKey(...args: any[]): Promiseinfer R } } } ? ExtractR, { type: string } : CryptoKeyStructuralFallback这段源码位于 src/types.d.ts 的CryptoKey定义处其设计逻辑可以拆解为两层条件判断typeof globalThis extends { crypto: { subtle: ... } }用于探测宿主运行时或当前的 TS 环境是否在全局对象上暴露了crypto.subtle且带有generateKey方法签名。由于globalThis是一个typeof查询类型这一判断完全由编译时的环境决定。取值推导若条件成立则使用ExtractR, { type: string }从generateKey的返回类型R中提取出带type: string属性的成员即标准 Web Crypto API 的CryptoKey类型若不成立则回退到内部后备类型CryptoKeyStructuralFallback。原文档对CryptoKey的定位说明指出它是密钥/机密在所有受支持运行时中的一种表示a representation of a key/secret available in all supported runtimes。也就是说在 jose 中CryptoKey并不仅仅指浏览器 Web Crypto 的密钥对象而是将 Web 标准中CryptoKey的形态统一映射到所有 Web 互操作运行时Node.js、Browser、Cloudflare Workers、Deno、Bun 等之上的类型抽象。二、后备类型 CryptoKeyStructuralFallback 的结构与作用当宿主运行时没有在typeof globalThis上暴露crypto全局时例如该全局在环境类型声明中缺失或是以const/let方式声明而无法被typeof感知jose 的类型系统会启用内部后备类型 CryptoKeyStructuralFallback。其结构如下属性类型说明algorithmobject含name: string密钥所使用算法的名称extractableboolean密钥是否允许被导出typestring密钥类型public/private/secretusagesstring[]允许的密钥用途集合该接口在文档中被标记为internal因为它仅在编译期环境无法感知 Web Crypto 全局的边界场景下充当占位类型。关键设计点在于它保持了与宿主环境真实CryptoKey声明的结构兼容性structurally compatible因此任何符合该结构的对象依然可以在 jose API 与原生SubtleCryptoAPI 之间自由流转不会因类型回退而阻断实际调用。这一点体现了 jose 类型系统结构类型structural typing的取向只要密钥对象具备algorithm、extractable、type、usages这四个字段无论它来自哪个运行时、哪个声明来源都能被类型系统接受为合法的CryptoKey。三、如何获取 CryptoKey导入、生成与原生 Web Crypto原文档明确指出除了 jose 自身的密钥导入函数之外还可以使用原生SubtleCrypto.importKeyAPI 从已有密钥材料中获得CryptoKey。在实际项目中获取CryptoKey主要有以下三条路径1. 使用 jose 密钥导入函数jose 在jose/key/import子路径下提供了一组导入函数全部返回CryptoKey对称密钥除外见下文说明importJWK从 JSON Web KeyJWK导入适用于 EC、RSA、OKP、AKP 等非对称密钥。导入时要求 JWK 自带alg参数或显式传入算法标识符作为第二个参数例如const ecPublicKey await jose.importJWK( { crv: P-256, kty: EC, x: ySK38C1jBdLwDsNWKzzBHqKYEE5Cgv-qjWvorUXk9fw, y: _LeQBw07cf5t57Iavn4j-BqJsAD1dpoz8gokd3sBsOo, }, ES256, ) const rsaPublicKey await jose.importJWK( { kty: RSA, e: AQAB, n: 12oBZRhCiZFJLcPg59LkZZ9mdhSMTKAQZYq32k_ti5SBB6jerkh-WzOMAO664r_qyLkqHUSp3u5SbXtseZEpN3XPWGKSxjsy-1JyEFTdLSYe6f9gfrmxkUF_7DTpq0gn6rntP05g2-wFW50YO7mosfdslfrTJYWHFhJALabAeYirYD7-9kqq9ebfFMF4sRRELbv9oi36As6Q9B3Qb5_C1rAzqfao_PCsf9EPsTZsVVVkA5qoIAr47lo1ipfiBPxUCCNSdvkmDTYgvvRm6ZoMjFbvOtgyts55fXKdMWv7I9HMD5HwE9uW839PWA514qhbcIsXEYSFMPMV6fnlsiZvQQ, }, PS256, )importSPKI/importPKCS8从 PEM 编码的公钥SPKI或私钥PKCS8导入返回CryptoKey。这两者对应的底层实现在 src/key/import.ts 中先通过asn1.ts解析 DER 结构再交由 Web Crypto 的importKey完成导入。importX509从 X.509 证书导入公钥CryptoKey。值得注意的例外对称 JWKkty: oct导入后返回的是Uint8Array而非CryptoKey。这与 importJWK 文档中的说明一致也是 src/types.d.ts 中ImportedJWK条件类型所体现的行为kty: oct分支产出Uint8Array。这一设计使得 jose 在 HMAC、AES 等对称算法场景下直接以字节序列表示密钥同时仍然能够满足SubtleCrypto.importKey的raw格式要求。2. 使用密钥生成函数jose 还提供了便捷的密钥生成入口直接返回CryptoKey或密钥对generateSecret生成对称密钥。传入算法标识符如HS256、A128GCM等返回Uint8Array | CryptoKey——对称密钥在支持的环境下同样以Uint8Array呈现。generateKeyPair生成非对称密钥对EC、RSA、OKP 等返回{ publicKey: CryptoKey; privateKey: CryptoKey }。3. 使用原生 SubtleCrypto.importKey在 Node.js 20 与所有主流浏览器、以及 Deno、Bun、Cloudflare Workers 等 Web 互操作运行时中globalThis.crypto.subtle.importKey均可用。你完全可以从已有的 PEM、原始字节等密钥材料中自行导入CryptoKey再将其直接交给 jose 的签名、验签、加密、解密函数使用const raw new TextEncoder().encode(my-256-bit-secret-0000000000000000) const key await crypto.subtle.importKey(raw, raw, { name: HMAC }, false, [sign, verify])四、CryptoKey 在 KeyInput 密钥输入体系中的地位jose 的所有签名、验签、加密、解密操作都接受统一的密钥输入类型 KeyInputexport type KeyInput CryptoKey | KeyObject | JWK | Uint8Array可见CryptoKey是这一联合类型中的第一成员代表面向所有运行时的密钥形态而 KeyObject 仅代表 Node.js 运行时的密钥形态可通过createPublicKey、createPrivateKey、createSecretKey获得。二者在源码中通过统一的密钥形态检测被识别见 src/lib/is_key_like.tsexport const isCryptoKey (key: unknown): key is types.CryptoKey { if (key?.[Symbol.toStringTag] CryptoKey) return true try { return key instanceof CryptoKey } catch { return false } } export const isKeyLike (key: unknown): key is types.CryptoKey | types.KeyObject isCryptoKey(key) || isKeyObject(key)这段实现值得注意检测优先使用Symbol.toStringTag CryptoKey判定再尝试instanceof CryptoKey并在该全局不可用时通过try/catch安全回退。这正与类型别名中全局缺失则启用结构回退的设计相互呼应——运行时层面同样允许在无 Web Crypto 全局的环境下正常工作。五、源码层面的密钥校验checkCryptoKey 与 checkUsage类型系统之外jose 在运行时还会对传入的CryptoKey做严格的结构与用途校验相关逻辑集中在 src/lib/crypto_key.tscheckUsage(key, usage)检查密钥的usages数组是否包含指定用途如sign、verify、encrypt、decrypt、wrapKey、unwrapKey不满足时抛出TypeError提示其 usages 必须包含 xxx。checkModulusLength(alg, key)对 RSA 算法强制要求密钥modulusLength不小于 2048 位。checkCryptoKey(key, expected, usage?)通用校验入口逐项比对algorithm.name、algorithm.hash、algorithm.namedCurve、algorithm.length与期望值最后调用checkUsage。这种类型定义 运行时断言的双层设计确保即使通过类型系统传递进来的CryptoKey也会在算法不匹配、密钥长度不足、用途不符等场景下被及时拒绝避免产生不可预期的加密结果。对应的测试如 test/jwk/jwk2key.test.ts则覆盖了 JWK 导入边界情况非对象输入抛出TypeError、未识别的kty抛出ERR_JOSE_NOT_SUPPORTED等。六、使用注意事项extractable与key_ops的传递通过 importJWK 导入时JWK 中的ext与key_ops参数会参与CryptoKey的导入过程分别映射为extractable与usages。导入函数的KeyImportOptions.extractable选项可显式覆盖默认值私钥默认false其余默认true。结构回退不等于能力缺失CryptoKeyStructuralFallback仅是编译期的类型占位。在运行时若宿主确实没有 Web Crypto 实现例如极旧的 Node.js 版本jose 的对应功能调用会抛出JOSENotSupported等错误类型回退不会改变运行时能力边界。对称密钥的特殊返回类型凡是输入kty: oct的 JWK 或对称密钥生成返回值是Uint8Array在编写 TypeScript 时可通过ImportedJWK的泛型推导获得精确返回类型无需手动断言。七、小结CryptoKey类型别名是 jose 将 Web Crypto 标准密钥形态统一到所有 Web 互操作运行时的类型枢纽它通过条件类型从globalThis动态推导在环境无法感知 Web Crypto 全局时回退到结构兼容的后备类型它与 KeyObject、JWK、Uint8Array共同构成 KeyInput 密钥输入体系在运行时则由 src/lib/crypto_key.ts 与 src/lib/is_key_like.ts 提供检测与校验支撑。理解这一类型的设计有助于在跨运行时项目中正确导入、生成、传递并校验密钥充分发挥 Web Crypto 标准的互操作能力。赞分享网络安全认证鉴权后端【免费下载链接】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 的 CryptoKeyStructuralFallback跨运行时 Web Crypto 密钥类型的结构化兼容方案jose 的 CryptoKeyStructuralFallback跨运行时 Web Crypto 密钥类型的结构化兼容方案 导读 本文围绕 jose 开源库网络安全认证鉴权后端深入解析 jose 的 ImportedJWK 类型别名JWK 导入结果的条件类型推导与运行时行为深入解析 jose 的 ImportedJWK 类型别名JWK 导入结果的条件类型推导与运行时行为 本篇文章围绕 jose 仓库中 docs/key/impo网络安全认证鉴权后端TypeScript 对象类型Object Types完全指南interface、type 别名与匿名类型的实战运用TypeScript 对象类型Object Types完全指南interface、type 别名与匿名类型的实战运用 本篇技术指南以《The Concis文档教程上一篇Valetudo终极指南如何让扫地机器人彻底摆脱云端控制下一篇Bootstrap Icons图标字体故障排除常见问题解决创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 jose 中的 CryptoKey 类型别名：Web Crypto 密钥对象在跨运行时环境下的类型设计与用法
网络安全认证鉴权后端【免费下载链接】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点击查看免费下载CryptoKey是 jose 库在 TypeScript 类型系统中对 Web Crypto API 密钥对象的标准抽象它贯穿签名、验签、加密、解密等全部核心操作。本文将以 docs/types/type-aliases/CryptoKey.md 为主线结合 src/types.d.ts 的源码实现讲解该类型别名的推导逻辑、结构化属性、获取途径以及在 KeyInput 密钥输入体系中的地位帮助读者在 Node.js、浏览器、Cloudflare Workers、Deno、Bun 等 Web 互操作运行时中正确理解和使用密钥对象。一、类型别名的定义从全局 Web Crypto API 推导jose 对CryptoKey的定义并非硬编码的结构体而是通过 TypeScript 条件类型从宿主运行时的全局声明中动态推导export type CryptoKey typeof globalThis extends { crypto: { subtle: { generateKey(...args: any[]): Promiseinfer R } } } ? ExtractR, { type: string } : CryptoKeyStructuralFallback这段源码位于 src/types.d.ts 的CryptoKey定义处其设计逻辑可以拆解为两层条件判断typeof globalThis extends { crypto: { subtle: ... } }用于探测宿主运行时或当前的 TS 环境是否在全局对象上暴露了crypto.subtle且带有generateKey方法签名。由于globalThis是一个typeof查询类型这一判断完全由编译时的环境决定。取值推导若条件成立则使用ExtractR, { type: string }从generateKey的返回类型R中提取出带type: string属性的成员即标准 Web Crypto API 的CryptoKey类型若不成立则回退到内部后备类型CryptoKeyStructuralFallback。原文档对CryptoKey的定位说明指出它是密钥/机密在所有受支持运行时中的一种表示a representation of a key/secret available in all supported runtimes。也就是说在 jose 中CryptoKey并不仅仅指浏览器 Web Crypto 的密钥对象而是将 Web 标准中CryptoKey的形态统一映射到所有 Web 互操作运行时Node.js、Browser、Cloudflare Workers、Deno、Bun 等之上的类型抽象。二、后备类型 CryptoKeyStructuralFallback 的结构与作用当宿主运行时没有在typeof globalThis上暴露crypto全局时例如该全局在环境类型声明中缺失或是以const/let方式声明而无法被typeof感知jose 的类型系统会启用内部后备类型 CryptoKeyStructuralFallback。其结构如下属性类型说明algorithmobject含name: string密钥所使用算法的名称extractableboolean密钥是否允许被导出typestring密钥类型public/private/secretusagesstring[]允许的密钥用途集合该接口在文档中被标记为internal因为它仅在编译期环境无法感知 Web Crypto 全局的边界场景下充当占位类型。关键设计点在于它保持了与宿主环境真实CryptoKey声明的结构兼容性structurally compatible因此任何符合该结构的对象依然可以在 jose API 与原生SubtleCryptoAPI 之间自由流转不会因类型回退而阻断实际调用。这一点体现了 jose 类型系统结构类型structural typing的取向只要密钥对象具备algorithm、extractable、type、usages这四个字段无论它来自哪个运行时、哪个声明来源都能被类型系统接受为合法的CryptoKey。三、如何获取 CryptoKey导入、生成与原生 Web Crypto原文档明确指出除了 jose 自身的密钥导入函数之外还可以使用原生SubtleCrypto.importKeyAPI 从已有密钥材料中获得CryptoKey。在实际项目中获取CryptoKey主要有以下三条路径1. 使用 jose 密钥导入函数jose 在jose/key/import子路径下提供了一组导入函数全部返回CryptoKey对称密钥除外见下文说明importJWK从 JSON Web KeyJWK导入适用于 EC、RSA、OKP、AKP 等非对称密钥。导入时要求 JWK 自带alg参数或显式传入算法标识符作为第二个参数例如const ecPublicKey await jose.importJWK( { crv: P-256, kty: EC, x: ySK38C1jBdLwDsNWKzzBHqKYEE5Cgv-qjWvorUXk9fw, y: _LeQBw07cf5t57Iavn4j-BqJsAD1dpoz8gokd3sBsOo, }, ES256, ) const rsaPublicKey await jose.importJWK( { kty: RSA, e: AQAB, n: 12oBZRhCiZFJLcPg59LkZZ9mdhSMTKAQZYq32k_ti5SBB6jerkh-WzOMAO664r_qyLkqHUSp3u5SbXtseZEpN3XPWGKSxjsy-1JyEFTdLSYe6f9gfrmxkUF_7DTpq0gn6rntP05g2-wFW50YO7mosfdslfrTJYWHFhJALabAeYirYD7-9kqq9ebfFMF4sRRELbv9oi36As6Q9B3Qb5_C1rAzqfao_PCsf9EPsTZsVVVkA5qoIAr47lo1ipfiBPxUCCNSdvkmDTYgvvRm6ZoMjFbvOtgyts55fXKdMWv7I9HMD5HwE9uW839PWA514qhbcIsXEYSFMPMV6fnlsiZvQQ, }, PS256, )importSPKI/importPKCS8从 PEM 编码的公钥SPKI或私钥PKCS8导入返回CryptoKey。这两者对应的底层实现在 src/key/import.ts 中先通过asn1.ts解析 DER 结构再交由 Web Crypto 的importKey完成导入。importX509从 X.509 证书导入公钥CryptoKey。值得注意的例外对称 JWKkty: oct导入后返回的是Uint8Array而非CryptoKey。这与 importJWK 文档中的说明一致也是 src/types.d.ts 中ImportedJWK条件类型所体现的行为kty: oct分支产出Uint8Array。这一设计使得 jose 在 HMAC、AES 等对称算法场景下直接以字节序列表示密钥同时仍然能够满足SubtleCrypto.importKey的raw格式要求。2. 使用密钥生成函数jose 还提供了便捷的密钥生成入口直接返回CryptoKey或密钥对generateSecret生成对称密钥。传入算法标识符如HS256、A128GCM等返回Uint8Array | CryptoKey——对称密钥在支持的环境下同样以Uint8Array呈现。generateKeyPair生成非对称密钥对EC、RSA、OKP 等返回{ publicKey: CryptoKey; privateKey: CryptoKey }。3. 使用原生 SubtleCrypto.importKey在 Node.js 20 与所有主流浏览器、以及 Deno、Bun、Cloudflare Workers 等 Web 互操作运行时中globalThis.crypto.subtle.importKey均可用。你完全可以从已有的 PEM、原始字节等密钥材料中自行导入CryptoKey再将其直接交给 jose 的签名、验签、加密、解密函数使用const raw new TextEncoder().encode(my-256-bit-secret-0000000000000000) const key await crypto.subtle.importKey(raw, raw, { name: HMAC }, false, [sign, verify])四、CryptoKey 在 KeyInput 密钥输入体系中的地位jose 的所有签名、验签、加密、解密操作都接受统一的密钥输入类型 KeyInputexport type KeyInput CryptoKey | KeyObject | JWK | Uint8Array可见CryptoKey是这一联合类型中的第一成员代表面向所有运行时的密钥形态而 KeyObject 仅代表 Node.js 运行时的密钥形态可通过createPublicKey、createPrivateKey、createSecretKey获得。二者在源码中通过统一的密钥形态检测被识别见 src/lib/is_key_like.tsexport const isCryptoKey (key: unknown): key is types.CryptoKey { if (key?.[Symbol.toStringTag] CryptoKey) return true try { return key instanceof CryptoKey } catch { return false } } export const isKeyLike (key: unknown): key is types.CryptoKey | types.KeyObject isCryptoKey(key) || isKeyObject(key)这段实现值得注意检测优先使用Symbol.toStringTag CryptoKey判定再尝试instanceof CryptoKey并在该全局不可用时通过try/catch安全回退。这正与类型别名中全局缺失则启用结构回退的设计相互呼应——运行时层面同样允许在无 Web Crypto 全局的环境下正常工作。五、源码层面的密钥校验checkCryptoKey 与 checkUsage类型系统之外jose 在运行时还会对传入的CryptoKey做严格的结构与用途校验相关逻辑集中在 src/lib/crypto_key.tscheckUsage(key, usage)检查密钥的usages数组是否包含指定用途如sign、verify、encrypt、decrypt、wrapKey、unwrapKey不满足时抛出TypeError提示其 usages 必须包含 xxx。checkModulusLength(alg, key)对 RSA 算法强制要求密钥modulusLength不小于 2048 位。checkCryptoKey(key, expected, usage?)通用校验入口逐项比对algorithm.name、algorithm.hash、algorithm.namedCurve、algorithm.length与期望值最后调用checkUsage。这种类型定义 运行时断言的双层设计确保即使通过类型系统传递进来的CryptoKey也会在算法不匹配、密钥长度不足、用途不符等场景下被及时拒绝避免产生不可预期的加密结果。对应的测试如 test/jwk/jwk2key.test.ts则覆盖了 JWK 导入边界情况非对象输入抛出TypeError、未识别的kty抛出ERR_JOSE_NOT_SUPPORTED等。六、使用注意事项extractable与key_ops的传递通过 importJWK 导入时JWK 中的ext与key_ops参数会参与CryptoKey的导入过程分别映射为extractable与usages。导入函数的KeyImportOptions.extractable选项可显式覆盖默认值私钥默认false其余默认true。结构回退不等于能力缺失CryptoKeyStructuralFallback仅是编译期的类型占位。在运行时若宿主确实没有 Web Crypto 实现例如极旧的 Node.js 版本jose 的对应功能调用会抛出JOSENotSupported等错误类型回退不会改变运行时能力边界。对称密钥的特殊返回类型凡是输入kty: oct的 JWK 或对称密钥生成返回值是Uint8Array在编写 TypeScript 时可通过ImportedJWK的泛型推导获得精确返回类型无需手动断言。七、小结CryptoKey类型别名是 jose 将 Web Crypto 标准密钥形态统一到所有 Web 互操作运行时的类型枢纽它通过条件类型从globalThis动态推导在环境无法感知 Web Crypto 全局时回退到结构兼容的后备类型它与 KeyObject、JWK、Uint8Array共同构成 KeyInput 密钥输入体系在运行时则由 src/lib/crypto_key.ts 与 src/lib/is_key_like.ts 提供检测与校验支撑。理解这一类型的设计有助于在跨运行时项目中正确导入、生成、传递并校验密钥充分发挥 Web Crypto 标准的互操作能力。赞分享网络安全认证鉴权后端【免费下载链接】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 的 CryptoKeyStructuralFallback跨运行时 Web Crypto 密钥类型的结构化兼容方案jose 的 CryptoKeyStructuralFallback跨运行时 Web Crypto 密钥类型的结构化兼容方案 导读 本文围绕 jose 开源库网络安全认证鉴权后端深入解析 jose 的 ImportedJWK 类型别名JWK 导入结果的条件类型推导与运行时行为深入解析 jose 的 ImportedJWK 类型别名JWK 导入结果的条件类型推导与运行时行为 本篇文章围绕 jose 仓库中 docs/key/impo网络安全认证鉴权后端TypeScript 对象类型Object Types完全指南interface、type 别名与匿名类型的实战运用TypeScript 对象类型Object Types完全指南interface、type 别名与匿名类型的实战运用 本篇技术指南以《The Concis文档教程上一篇Valetudo终极指南如何让扫地机器人彻底摆脱云端控制下一篇Bootstrap Icons图标字体故障排除常见问题解决创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考