企业官网建设流程全解析

• 网络安全
• 认证鉴权
• 后端

导读

在基于 jose 库进行 JWS 签名验证时，无论是使用本地 JSON Web Key Set（createLocalJWKSet）还是远程 JWKS（createRemoteJWKSet），密钥解析器都要求"恰好一个密钥匹配"——当多个密钥同时命中选择条件时，就会抛出JWKSMultipleMatchingKeys错误。本文以 JWKSMultipleMatchingKeys 官方文档 为核心，结合 src/util/errors.ts 与 src/jwks/local.ts 的源码实现，系统讲解该错误的身份识别、稳定错误码、独有的异步迭代能力，以及如何用它优雅地实现"逐个密钥尝试验证"的生产级回退策略。

一、什么是 JWKSMultipleMatchingKeys

JWKSMultipleMatchingKeys是 jose 错误体系中的一员，由JOSEError派生而来，官方定义非常明确："当从 JWKS 中匹配到多个密钥时抛出的错误子类"。

它与JWKSNoMatchingKey恰好构成一对"镜像"错误：前者表示候选密钥多于一个，后者表示候选密钥为零。二者的触发逻辑都集中在 src/jwks/local.ts 的密钥选择器中：

const candidates = snapshot.keys.filter((jwk) => isUsableJWK(jwk, entry, alg!, kid)) const { 0: jwk, length } = candidates if (!length) { throw new JWKSNoMatchingKey() } if (length !== 1) { const error = new JWKSMultipleMatchingKeys() error[Symbol.asyncIterator] = async function* () { /* ... */ } throw error } return importWithAlgCache(cached, jwk, entry)

从源码结构可以清晰看到选择流程的三种结局：候选数为 0 抛JWKSNoMatchingKey；候选数为 1 正常导入密钥返回；候选数大于 1 抛JWKSMultipleMatchingKeys。匹配依据（见 isUsableJWK 实现）包括 JWS Header 中的alg（算法）、kid（密钥 ID），以及 JWK 上的use（用途）、key_ops（密钥操作）、kty/crv（密钥类型与曲线）等字段。

[!NOTE] 该错误与整个 JWKS 解析器一样，仅服务于签名验证场景（解析公钥），不能用于公钥加密场景，这一点在 createRemoteJWKSet 文档 中有明确说明。

二、错误如何导出与如何识别

所有 JOSE 模块错误统一以errors命名空间导出，可以从主入口'jose'或子路径'jose/errors'引入，相关说明见 util/errors README。在 src/index.ts 中可以看到errors命名空间的导出方式：

import * as errors from './util/errors.js' export { errors }

JWKSMultipleMatchingKeys提供了两种可靠的识别方式：

方式一：使用稳定的错误码code

if (err.code === 'ERR_JWKS_MULTIPLE_MATCHING_KEYS') { // ... }

方式二：使用instanceof

if (err instanceof jose.errors.JWKSMultipleMatchingKeys) { // ... }

code是一个字符串属性，固定值为'ERR_JWKS_MULTIPLE_MATCHING_KEYS'，定义见 src/util/errors.ts。该错误码同时也是JOSEErrorCode联合类型的成员（见 src/util/errors.ts），配合AnyJOSEError判别联合，可以在switch (err.code)中实现类型收窄：

function handle(err: jose.errors.AnyJOSEError) { switch (err.code) { case 'ERR_JWKS_MULTIPLE_MATCHING_KEYS': // 此处 err 已被收窄为 JWKSMultipleMatchingKeys，可直接 for await 遍历 break // ... } }

关于code属性，还值得注意的是：jose 的错误类同时定义了静态static code与实例code，二者取值一致；默认的JOSEError基类 code 为'ERR_JOSE_GENERIC'。测试 test/jwks/remote.test.ts 中对错误码与默认消息做了断言验证：

let error: errors.JWKSMultipleMatchingKeys = await t.throwsAsync(jwtVerify(jwt, JWKS), { code: 'ERR_JWKS_MULTIPLE_MATCHING_KEYS', message: 'multiple matching keys found in the JSON Web Key Set', })

这意味着即使不查看源码，仅凭err.code与err.message也能稳定识别该错误——默认消息为'multiple matching keys found in the JSON Web Key Set'（见 src/util/errors.ts）。

三、核心特性：[asyncIterator] —— 错误本身就是一个可迭代的密钥集合

JWKSMultipleMatchingKeys区别于 jose 其它错误类的最独特之处，是其暴露的[Symbol.asyncIterator]属性，官方文档定义如下：

• 类型：() => AsyncIterableIterator<CryptoKey>
• 语义：遍历在 JWS JOSE Header 匹配过程中命中的全部公钥，从而可以依次用每个密钥尝试签名验证。
• 关键行为差异：由本模块抛出的实例总是能遍历匹配到的密钥；而由其它代码手动new出来的实例则遍历不到任何内容。

这一点在源码中体现得非常直接。类定义中[Symbol.asyncIterator]默认是一个空异步生成器（src/util/errors.ts）：

[Symbol.asyncIterator]: () => AsyncIterableIterator<types.CryptoKey> = async function* () {}

而当 createLocalJWKSet 检测到多个候选密钥时，会用真实的候选集合覆写这个迭代器，并借助importWithAlgCache将每个 JWK 异步转换为CryptoKey后逐个 yield：

if (length !== 1) { const error = new JWKSMultipleMatchingKeys() error[Symbol.asyncIterator] = async function* () { for (const jwk of candidates) { try { yield await importWithAlgCache(cached, jwk, entry) } catch {} } } throw error }

importWithAlgCache（见 src/jwks/local.ts）内部还会校验key.type === 'public'，确保 JWKS 成员必须是公钥。测试 test/jwks/remote.test.ts 验证了远程 JWKS 场景下可迭代两次匹配密钥，且两次迭代返回的密钥对象来自同一缓存（WeakSet 命中），这印证了"命中密钥会被缓存的转换结果反复复用"这一实现细节。

四、为什么会有多个密钥命中

密钥选择器会综合 JWS Header 与 JWK 字段做过滤，命中条件本身就有可能在 JWKS 中匹配到多条记录，典型情形包括：

1. 未携带kid时算法同类型多条匹配：JWT 只声明alg，而 JWKS 中恰好有多个同类型（同kty/crv）的密钥记录。远程 JWKS 场景的测试用例即如此构造（见 test/jwks/remote.test.ts）：JWT 只设置{ alg: 'RS256' }而不带kid，而 JWKS 中该算法对应多个 RSA 公钥。
2. JWK 记录未声明alg：isUsableJWK的逻辑是jwkAlg === undefined ? kty !== 'AKP' : alg === jwkAlg（src/jwks/local.ts），即未声明alg的 JWK 只要kty匹配即可入选，可能同时命中多把不同用途的钥匙。
3. JWK 缺少use/key_ops限定：use === undefined || use === 'sig'的判定（src/jwks/local.ts）意味着未声明用途的密钥同样可能扩大候选集。

值得注意的是，选择器内部（见 src/jwks/local.ts）对key_ops的合法性有严格校验：必须是去重后的字符串数组且包含'verify'，非法key_ops会被直接排除；若 JWKS 结构本身不合法（不是合法的 JSON Web Key Set 格式），则会在更早阶段抛出JWKSInvalid（src/jwks/local.ts），并不属于本文讨论的错误。

五、实战：把"多密钥命中"变成"逐钥验证"的生产级处理

官方文档给出的核心建议是：当多个密钥匹配时，主动"opt-in"遍历匹配到的公钥，逐个尝试签名验证。这也是[Symbol.asyncIterator]存在的根本目的。以下示例来自 createLocalJWKSet 文档，同样适用于 createRemoteJWKSet 文档 的场景：

const options = { issuer: 'urn:example:issuer', audience: 'urn:example:audience', } const { payload, protectedHeader } = await jose .jwtVerify(jwt, JWKS, options) .catch(async (error) => { if (error instanceof jose.errors.JWKSMultipleMatchingKeys) { for await (const publicKey of error) { try { return await jose.jwtVerify(jwt, publicKey, options) } catch (innerError) { if (innerError instanceof jose.errors.JWSSignatureVerificationFailed) { continue } throw innerError } } throw new jose.errors.JWSSignatureVerificationFailed() } throw error }) console.log(protectedHeader) console.log(payload)

这个模式的关键设计值得拆解：

• 只有签名验证失败才继续尝试：捕获JWSSignatureVerificationFailed后continue换下一把钥匙；其它错误（如 JWT 过期、claims 校验失败）直接上抛，避免掩盖真正的业务错误。
• 全部尝试失败后明确失败：循环结束后抛出新的JWSSignatureVerificationFailed，语义清晰。
• for await...of直接作用于错误对象：这是[Symbol.asyncIterator]提供的便利，error本身就是可迭代对象，无需从错误上取任何附加属性。
• 非多匹配错误原样抛出：catch块最后throw error，保证JWKSNoMatchingKey、JWKSTimeout等其它错误不受影响。

createRemoteJWKSet与createLocalJWKSet返回的解析函数可被 jwtVerify、compactVerify、flattenedVerify、generalVerify 等验证函数直接接受，因此上述回退策略对所有基于 JWKS 的验证入口普遍适用。

六、与 JWKS 家族错误的关系与边界

把JWKSMultipleMatchingKeys放进整个错误家族中看，能更清楚地把握它的职责边界。全部 15 个稳定错误码见 src/util/errors.ts，与 JWKS 相关的有四个：

其中远程 JWKS 的请求超时由AbortSignal.timeout(timeoutDuration)触发（见 src/jwks/remote.ts），默认超时 5000ms（timeoutDuration默认值），其余参数如cooldownDuration（默认 30000ms）、cacheMaxAge（默认 600000ms）的定义可查 RemoteJWKSetOptions。

一个值得注意的边界：远程 JWKS 的"自动重载"机制。从 src/jwks/remote.ts 可以看到，只有当抛出的是JWKSNoMatchingKey（而非JWKSMultipleMatchingKeys）时，解析器才会在冷却窗口之外自动重新拉取 JWKS 并重试一次。也就是说，多密钥命中不会被远程解析器"自动消解"，必须由调用方通过本文第五节的方式显式处理——这正是该错误需要暴露可迭代公钥的深层原因。

七、小结

JWKSMultipleMatchingKeys是 jose 处理 JWKS 密钥解析二义性的关键错误类型，其价值可以概括为三点：

1. 稳定的可识别性：ERR_JWKS_MULTIPLE_MATCHING_KEYS错误码 +instanceof双通道识别，默认消息为'multiple matching keys found in the JSON Web Key Set'。
2. 错误即数据：通过[Symbol.asyncIterator]将"错误对象"升级为"可迭代的匹配公钥集合"，让错误处理天然承载回退验证所需的数据。
3. 清晰的触发与边界：由 src/jwks/local.ts 在选择器检测到多个候选密钥时抛出；与JWKSNoMatchingKey互补，且不受远程解析器自动重载逻辑的自动消解。

在实际的 OIDC/jwks_uri接入中，多密钥并存是常态（密钥轮换期尤其如此），掌握"捕获JWKSMultipleMatchingKeys→for await遍历 → 逐个验证"这套模式，是写出健壮 JWT 验签代码的重要一环。

• 网络安全
• 认证鉴权
• 后端