jose 4.11.4 → 4.12.0

package/README.md

@@ -38,7 +38,7 @@ const jose = require('jose')
 
 **`example`** Deno import
 ```js
-import * as jose from 'https://deno.land/x/jose@v4.11.4/index.ts'
+import * as jose from 'https://deno.land/x/jose@v4.12.0/index.ts'
 ```
 
 - JSON Web Tokens (JWT)

package/dist/browser/jwks/local.js

@@ -38,7 +38,7 @@ export class LocalJWKSet {
         this._jwks = clone(jwks);
     }
     async getKey(protectedHeader, token) {
-        const { alg, kid } = { ...protectedHeader, ...token.header };
+        const { alg, kid } = { ...protectedHeader, ...token === null || token === void 0 ? void 0 : token.header };
         const kty = getKtyFromAlg(alg);
         const candidates = this._jwks.keys.filter((jwk) => {
             let candidate = kty === jwk.kty;
@@ -80,18 +80,33 @@ export class LocalJWKSet {
             throw new JWKSNoMatchingKey();
         }
         else if (length !== 1) {
-            throw new JWKSMultipleMatchingKeys();
+            const error = new JWKSMultipleMatchingKeys();
+            const { _cached } = this;
+            error[Symbol.asyncIterator] = async function* () {
+                for (const jwk of candidates) {
+                    try {
+                        yield await importWithAlgCache(_cached, jwk, alg);
+                    }
+                    catch (_a) {
+                        continue;
+                    }
+                }
+            };
+            throw error;
         }
-        const cached = this._cached.get(jwk) || this._cached.set(jwk, {}).get(jwk);
-        if (cached[alg] === undefined) {
-            const keyObject = await importJWK({ ...jwk, ext: true }, alg);
-            if (keyObject instanceof Uint8Array || keyObject.type !== 'public') {
-                throw new JWKSInvalid('JSON Web Key Set members must be public keys');
-            }
-            cached[alg] = keyObject;
+        return importWithAlgCache(this._cached, jwk, alg);
+    }
+}
+async function importWithAlgCache(cache, jwk, alg) {
+    const cached = cache.get(jwk) || cache.set(jwk, {}).get(jwk);
+    if (cached[alg] === undefined) {
+        const keyObject = await importJWK({ ...jwk, ext: true }, alg);
+        if (keyObject.type !== 'public') {
+            throw new JWKSInvalid('JSON Web Key Set members must be public keys');
         }
-        return cached[alg];
+        cached[alg] = keyObject;
     }
+    return cached[alg];
 }
 export function createLocalJWKSet(jwks) {
     return LocalJWKSet.prototype.getKey.bind(new LocalJWKSet(jwks));

package/dist/browser/util/errors.js

@@ -125,6 +125,7 @@ export class JWKSMultipleMatchingKeys extends JOSEError {
         return 'ERR_JWKS_MULTIPLE_MATCHING_KEYS';
     }
 }
+Symbol.asyncIterator;
 export class JWKSTimeout extends JOSEError {
     constructor() {
         super(...arguments);

package/dist/node/cjs/jwks/local.js

@@ -42,7 +42,7 @@ class LocalJWKSet {
         this._jwks = clone(jwks);
     }
     async getKey(protectedHeader, token) {
-        const { alg, kid } = { ...protectedHeader, ...token.header };
+        const { alg, kid } = { ...protectedHeader, ...token === null || token === void 0 ? void 0 : token.header };
         const kty = getKtyFromAlg(alg);
         const candidates = this._jwks.keys.filter((jwk) => {
             let candidate = kty === jwk.kty;
@@ -84,20 +84,35 @@ class LocalJWKSet {
             throw new errors_js_1.JWKSNoMatchingKey();
         }
         else if (length !== 1) {
-            throw new errors_js_1.JWKSMultipleMatchingKeys();
-        }
-        const cached = this._cached.get(jwk) || this._cached.set(jwk, {}).get(jwk);
-        if (cached[alg] === undefined) {
-            const keyObject = await (0, import_js_1.importJWK)({ ...jwk, ext: true }, alg);
-            if (keyObject instanceof Uint8Array || keyObject.type !== 'public') {
-                throw new errors_js_1.JWKSInvalid('JSON Web Key Set members must be public keys');
-            }
-            cached[alg] = keyObject;
+            const error = new errors_js_1.JWKSMultipleMatchingKeys();
+            const { _cached } = this;
+            error[Symbol.asyncIterator] = async function* () {
+                for (const jwk of candidates) {
+                    try {
+                        yield await importWithAlgCache(_cached, jwk, alg);
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+            };
+            throw error;
         }
-        return cached[alg];
+        return importWithAlgCache(this._cached, jwk, alg);
     }
 }
 exports.LocalJWKSet = LocalJWKSet;
+async function importWithAlgCache(cache, jwk, alg) {
+    const cached = cache.get(jwk) || cache.set(jwk, {}).get(jwk);
+    if (cached[alg] === undefined) {
+        const keyObject = await (0, import_js_1.importJWK)({ ...jwk, ext: true }, alg);
+        if (keyObject.type !== 'public') {
+            throw new errors_js_1.JWKSInvalid('JSON Web Key Set members must be public keys');
+        }
+        cached[alg] = keyObject;
+    }
+    return cached[alg];
+}
 function createLocalJWKSet(jwks) {
     return LocalJWKSet.prototype.getKey.bind(new LocalJWKSet(jwks));
 }

package/dist/node/cjs/util/errors.js

@@ -141,6 +141,7 @@ class JWKSMultipleMatchingKeys extends JOSEError {
     }
 }
 exports.JWKSMultipleMatchingKeys = JWKSMultipleMatchingKeys;
+Symbol.asyncIterator;
 class JWKSTimeout extends JOSEError {
     constructor() {
         super(...arguments);

package/dist/node/esm/jwks/local.js

@@ -38,7 +38,7 @@ export class LocalJWKSet {
         this._jwks = clone(jwks);
     }
     async getKey(protectedHeader, token) {
-        const { alg, kid } = { ...protectedHeader, ...token.header };
+        const { alg, kid } = { ...protectedHeader, ...token === null || token === void 0 ? void 0 : token.header };
         const kty = getKtyFromAlg(alg);
         const candidates = this._jwks.keys.filter((jwk) => {
             let candidate = kty === jwk.kty;
@@ -80,18 +80,33 @@ export class LocalJWKSet {
             throw new JWKSNoMatchingKey();
         }
         else if (length !== 1) {
-            throw new JWKSMultipleMatchingKeys();
+            const error = new JWKSMultipleMatchingKeys();
+            const { _cached } = this;
+            error[Symbol.asyncIterator] = async function* () {
+                for (const jwk of candidates) {
+                    try {
+                        yield await importWithAlgCache(_cached, jwk, alg);
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+            };
+            throw error;
         }
-        const cached = this._cached.get(jwk) || this._cached.set(jwk, {}).get(jwk);
-        if (cached[alg] === undefined) {
-            const keyObject = await importJWK({ ...jwk, ext: true }, alg);
-            if (keyObject instanceof Uint8Array || keyObject.type !== 'public') {
-                throw new JWKSInvalid('JSON Web Key Set members must be public keys');
-            }
-            cached[alg] = keyObject;
+        return importWithAlgCache(this._cached, jwk, alg);
+    }
+}
+async function importWithAlgCache(cache, jwk, alg) {
+    const cached = cache.get(jwk) || cache.set(jwk, {}).get(jwk);
+    if (cached[alg] === undefined) {
+        const keyObject = await importJWK({ ...jwk, ext: true }, alg);
+        if (keyObject.type !== 'public') {
+            throw new JWKSInvalid('JSON Web Key Set members must be public keys');
         }
-        return cached[alg];
+        cached[alg] = keyObject;
     }
+    return cached[alg];
 }
 export function createLocalJWKSet(jwks) {
     return LocalJWKSet.prototype.getKey.bind(new LocalJWKSet(jwks));

package/dist/node/esm/util/errors.js

@@ -125,6 +125,7 @@ export class JWKSMultipleMatchingKeys extends JOSEError {
         return 'ERR_JWKS_MULTIPLE_MATCHING_KEYS';
     }
 }
+Symbol.asyncIterator;
 export class JWKSTimeout extends JOSEError {
     constructor() {
         super(...arguments);

package/dist/types/jwks/local.d.ts

@@ -1,4 +1,4 @@
-import type { KeyLike, JWSHeaderParameters, JSONWebKeySet, FlattenedJWSInput, GetKeyFunction } from '../types';
+import type { KeyLike, JWSHeaderParameters, JSONWebKeySet, FlattenedJWSInput } from '../types';
 /** @private */
 export declare function isJWKSLike(jwks: unknown): jwks is JSONWebKeySet;
 /** @private */
@@ -6,13 +6,20 @@ export declare class LocalJWKSet {
     protected _jwks?: JSONWebKeySet;
     private _cached;
     constructor(jwks: unknown);
-    getKey(protectedHeader: JWSHeaderParameters, token: FlattenedJWSInput): Promise<KeyLike>;
+    getKey(protectedHeader?: JWSHeaderParameters, token?: FlattenedJWSInput): Promise<KeyLike>;
 }
 /**
  * Returns a function that resolves to a key object from a locally stored, or otherwise available,
  * JSON Web Key Set.
  *
- * Only a single public key must match the selection process.
+ * It uses the "alg" (JWS Algorithm) Header Parameter to determine the right JWK "kty" (Key Type),
+ * then proceeds to match the JWK "kid" (Key ID) with one found in the JWS Header Parameters (if
+ * there is one) while also respecting the JWK "use" (Public Key Use) and JWK "key_ops" (Key
+ * Operations) Parameters (if they are present on the JWK).
+ *
+ * Only a single public key must match the selection process. As shown in the example below when
+ * multiple keys get matched it is possible to opt-in to iterate over the matched keys and attempt
+ * verification in an iterative manner.
  *
  * @example Usage
  *
@@ -43,6 +50,36 @@ export declare class LocalJWKSet {
  * console.log(payload)
  * ```
  *
+ * @example Opting-in to multiple JWKS matches using `createLocalJWKSet`
+ *
+ * ```js
+ * const options = {
+ *   issuer: 'urn:example:issuer',
+ *   audience: 'urn:example:audience',
+ * }
+ * const { payload, protectedHeader } = await jose
+ *   .jwtVerify(jwt, JWKS, options)
+ *   .catch(async (error) => {
+ *     if (error?.code === 'ERR_JWKS_MULTIPLE_MATCHING_KEYS') {
+ *       for await (const publicKey of error) {
+ *         try {
+ *           return await jose.jwtVerify(jwt, publicKey, options)
+ *         } catch (innerError) {
+ *           if (innerError?.code === 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED') {
+ *             continue
+ *           }
+ *           throw innerError
+ *         }
+ *       }
+ *       throw new jose.errors.JWSSignatureVerificationFailed()
+ *     }
+ *
+ *     throw error
+ *   })
+ * console.log(protectedHeader)
+ * console.log(payload)
+ * ```
+ *
  * @param jwks JSON Web Key Set formatted object.
  */
-export declare function createLocalJWKSet(jwks: JSONWebKeySet): GetKeyFunction<JWSHeaderParameters, FlattenedJWSInput>;
+export declare function createLocalJWKSet(jwks: JSONWebKeySet): (protectedHeader?: JWSHeaderParameters | undefined, token?: FlattenedJWSInput | undefined) => Promise<KeyLike>;

package/dist/types/jwks/remote.d.ts

@@ -1,4 +1,4 @@
-import type { JWSHeaderParameters, FlattenedJWSInput, GetKeyFunction } from '../types';
+import type { KeyLike, JWSHeaderParameters, FlattenedJWSInput } from '../types';
 /** Options for the remote JSON Web Key Set. */
 export interface RemoteJWKSetOptions {
     /**
@@ -30,10 +30,18 @@ export interface RemoteJWKSetOptions {
 }
 /**
  * Returns a function that resolves to a key object downloaded from a remote endpoint returning a
- * JSON Web Key Set, that is, for example, an OAuth 2.0 or OIDC jwks_uri. Only a single public key
- * must match the selection process. The JSON Web Key Set is fetched when no key matches the
- * selection process but only as frequently as the `cooldownDuration` option allows, to prevent
- * abuse.
+ * JSON Web Key Set, that is, for example, an OAuth 2.0 or OIDC jwks_uri. The JSON Web Key Set is
+ * fetched when no key matches the selection process but only as frequently as the
+ * `cooldownDuration` option allows to prevent abuse.
+ *
+ * It uses the "alg" (JWS Algorithm) Header Parameter to determine the right JWK "kty" (Key Type),
+ * then proceeds to match the JWK "kid" (Key ID) with one found in the JWS Header Parameters (if
+ * there is one) while also respecting the JWK "use" (Public Key Use) and JWK "key_ops" (Key
+ * Operations) Parameters (if they are present on the JWK).
+ *
+ * Only a single public key must match the selection process. As shown in the example below when
+ * multiple keys get matched it is possible to opt-in to iterate over the matched keys and attempt
+ * verification in an iterative manner.
  *
  * @example Usage
  *
@@ -48,7 +56,37 @@ export interface RemoteJWKSetOptions {
  * console.log(payload)
  * ```
  *
+ * @example Opting-in to multiple JWKS matches using `createRemoteJWKSet`
+ *
+ * ```js
+ * const options = {
+ *   issuer: 'urn:example:issuer',
+ *   audience: 'urn:example:audience',
+ * }
+ * const { payload, protectedHeader } = await jose
+ *   .jwtVerify(jwt, JWKS, options)
+ *   .catch(async (error) => {
+ *     if (error?.code === 'ERR_JWKS_MULTIPLE_MATCHING_KEYS') {
+ *       for await (const publicKey of error) {
+ *         try {
+ *           return await jose.jwtVerify(jwt, publicKey, options)
+ *         } catch (innerError) {
+ *           if (innerError?.code === 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED') {
+ *             continue
+ *           }
+ *           throw innerError
+ *         }
+ *       }
+ *       throw new jose.errors.JWSSignatureVerificationFailed()
+ *     }
+ *
+ *     throw error
+ *   })
+ * console.log(protectedHeader)
+ * console.log(payload)
+ * ```
+ *
  * @param url URL to fetch the JSON Web Key Set from.
  * @param options Options for the remote JSON Web Key Set.
  */
-export declare function createRemoteJWKSet(url: URL, options?: RemoteJWKSetOptions): GetKeyFunction<JWSHeaderParameters, FlattenedJWSInput>;
+export declare function createRemoteJWKSet(url: URL, options?: RemoteJWKSetOptions): (protectedHeader?: JWSHeaderParameters | undefined, token?: FlattenedJWSInput | undefined) => Promise<KeyLike>;

package/dist/types/jwt/sign.d.ts

@@ -53,7 +53,7 @@ import { ProduceJWT } from './produce';
  * 59lLWBCsocvvbd1cvDMNlRywAAyhsCb1SuX4nEAK9mrSBdfmoF2Nm3eilfsOds0f
  * K5mX069IKG82CMqh3Mzptd7e7lyb9lsoGO0BAtjho3cWtha/UZ70vfaMzGuZ6JmQ
  * ak6k+8+UFd93M4z0Qo74OhXB
- * -----END PRIVATE KEY----`
+ * -----END PRIVATE KEY-----`
  * const privateKey = await jose.importPKCS8(pkcs8, alg)
  *
  * const jwt = await new jose.SignJWT({ 'urn:example:claim': true })

package/dist/types/util/errors.d.ts

@@ -1,3 +1,4 @@
+import type { KeyLike } from '../types';
 /** A generic Error subclass that all other specific JOSE Error subclasses inherit from. */
 export declare class JOSEError extends Error {
     /** A unique error code for the particular error subclass. */
@@ -78,6 +79,8 @@ export declare class JWKSNoMatchingKey extends JOSEError {
 }
 /** An error subclass thrown when multiple keys match from a JWKS. */
 export declare class JWKSMultipleMatchingKeys extends JOSEError {
+    /** @ignore */
+    [Symbol.asyncIterator]: () => AsyncIterableIterator<KeyLike>;
     static get code(): 'ERR_JWKS_MULTIPLE_MATCHING_KEYS';
     code: string;
     message: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jose",
-  "version": "4.11.4",
+  "version": "4.12.0",
   "description": "'JSON Web Almost Everything' - JWA, JWS, JWE, JWT, JWK, JWKS for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes",
   "keywords": [
     "browser",