jose 5.4.1 → 5.5.0

package/dist/browser/index.js

@@ -17,7 +17,7 @@ export { EncryptJWT } from './jwt/encrypt.js';
 export { calculateJwkThumbprint, calculateJwkThumbprintUri } from './jwk/thumbprint.js';
 export { EmbeddedJWK } from './jwk/embedded.js';
 export { createLocalJWKSet } from './jwks/local.js';
-export { createRemoteJWKSet } from './jwks/remote.js';
+export { createRemoteJWKSet, experimental_jwksCache } from './jwks/remote.js';
 export { UnsecuredJWT } from './jwt/unsecured.js';
 export { exportPKCS8, exportSPKI, exportJWK } from './key/export.js';
 export { importSPKI, importPKCS8, importX509, importJWK } from './key/import.js';

package/dist/browser/jwks/remote.js

@@ -1,6 +1,7 @@
 import fetchJwks from '../runtime/fetch_jwks.js';
 import { JWKSNoMatchingKey } from '../util/errors.js';
 import { createLocalJWKSet } from './local.js';
+import isObject from '../lib/is_object.js';
 function isCloudflareWorkers() {
     return (typeof WebSocketPair !== 'undefined' ||
         (typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers') ||
@@ -9,9 +10,25 @@ function isCloudflareWorkers() {
 let USER_AGENT;
 if (typeof navigator === 'undefined' || !navigator.userAgent?.startsWith?.('Mozilla/5.0 ')) {
     const NAME = 'jose';
-    const VERSION = 'v5.4.1';
+    const VERSION = 'v5.5.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
+export const experimental_jwksCache = Symbol();
+function isFreshJwksCache(input, cacheMaxAge) {
+    if (typeof input !== 'object' || input === null) {
+        return false;
+    }
+    if (!('uat' in input) || typeof input.uat !== 'number' || Date.now() - input.uat >= cacheMaxAge) {
+        return false;
+    }
+    if (!('jwks' in input) ||
+        !isObject(input.jwks) ||
+        !Array.isArray(input.jwks.keys) ||
+        !Array.prototype.every.call(input.jwks.keys, isObject)) {
+        return false;
+    }
+    return true;
+}
 class RemoteJWKSet {
     constructor(url, options) {
         if (!(url instanceof URL)) {
@@ -24,6 +41,13 @@ class RemoteJWKSet {
         this._cooldownDuration =
             typeof options?.cooldownDuration === 'number' ? options?.cooldownDuration : 30000;
         this._cacheMaxAge = typeof options?.cacheMaxAge === 'number' ? options?.cacheMaxAge : 600000;
+        if (options?.[experimental_jwksCache] !== undefined) {
+            this._cache = options?.[experimental_jwksCache];
+            if (isFreshJwksCache(options?.[experimental_jwksCache], this._cacheMaxAge)) {
+                this._jwksTimestamp = this._cache.uat;
+                this._local = createLocalJWKSet(this._cache.jwks);
+            }
+        }
     }
     coolingDown() {
         return typeof this._jwksTimestamp === 'number'
@@ -64,6 +88,10 @@ class RemoteJWKSet {
         this._pendingFetch || (this._pendingFetch = fetchJwks(this._url, this._timeoutDuration, this._options)
             .then((json) => {
             this._local = createLocalJWKSet(json);
+            if (this._cache) {
+                this._cache.uat = Date.now();
+                this._cache.jwks = json;
+            }
             this._jwksTimestamp = Date.now();
             this._pendingFetch = undefined;
         })

package/dist/node/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cryptoRuntime = exports.base64url = exports.generateSecret = exports.generateKeyPair = exports.errors = exports.decodeJwt = exports.decodeProtectedHeader = exports.importJWK = exports.importX509 = exports.importPKCS8 = exports.importSPKI = exports.exportJWK = exports.exportSPKI = exports.exportPKCS8 = exports.UnsecuredJWT = exports.createRemoteJWKSet = exports.createLocalJWKSet = exports.EmbeddedJWK = exports.calculateJwkThumbprintUri = exports.calculateJwkThumbprint = exports.EncryptJWT = exports.SignJWT = exports.GeneralSign = exports.FlattenedSign = exports.CompactSign = exports.FlattenedEncrypt = exports.CompactEncrypt = exports.jwtDecrypt = exports.jwtVerify = exports.generalVerify = exports.flattenedVerify = exports.compactVerify = exports.GeneralEncrypt = exports.generalDecrypt = exports.flattenedDecrypt = exports.compactDecrypt = void 0;
+exports.cryptoRuntime = exports.base64url = exports.generateSecret = exports.generateKeyPair = exports.errors = exports.decodeJwt = exports.decodeProtectedHeader = exports.importJWK = exports.importX509 = exports.importPKCS8 = exports.importSPKI = exports.exportJWK = exports.exportSPKI = exports.exportPKCS8 = exports.UnsecuredJWT = exports.experimental_jwksCache = exports.createRemoteJWKSet = exports.createLocalJWKSet = exports.EmbeddedJWK = exports.calculateJwkThumbprintUri = exports.calculateJwkThumbprint = exports.EncryptJWT = exports.SignJWT = exports.GeneralSign = exports.FlattenedSign = exports.CompactSign = exports.FlattenedEncrypt = exports.CompactEncrypt = exports.jwtDecrypt = exports.jwtVerify = exports.generalVerify = exports.flattenedVerify = exports.compactVerify = exports.GeneralEncrypt = exports.generalDecrypt = exports.flattenedDecrypt = exports.compactDecrypt = void 0;
 var decrypt_js_1 = require("./jwe/compact/decrypt.js");
 Object.defineProperty(exports, "compactDecrypt", { enumerable: true, get: function () { return decrypt_js_1.compactDecrypt; } });
 var decrypt_js_2 = require("./jwe/flattened/decrypt.js");
@@ -42,6 +42,7 @@ var local_js_1 = require("./jwks/local.js");
 Object.defineProperty(exports, "createLocalJWKSet", { enumerable: true, get: function () { return local_js_1.createLocalJWKSet; } });
 var remote_js_1 = require("./jwks/remote.js");
 Object.defineProperty(exports, "createRemoteJWKSet", { enumerable: true, get: function () { return remote_js_1.createRemoteJWKSet; } });
+Object.defineProperty(exports, "experimental_jwksCache", { enumerable: true, get: function () { return remote_js_1.experimental_jwksCache; } });
 var unsecured_js_1 = require("./jwt/unsecured.js");
 Object.defineProperty(exports, "UnsecuredJWT", { enumerable: true, get: function () { return unsecured_js_1.UnsecuredJWT; } });
 var export_js_1 = require("./key/export.js");

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

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createRemoteJWKSet = void 0;
+exports.createRemoteJWKSet = exports.experimental_jwksCache = void 0;
 const fetch_jwks_js_1 = require("../runtime/fetch_jwks.js");
 const errors_js_1 = require("../util/errors.js");
 const local_js_1 = require("./local.js");
+const is_object_js_1 = require("../lib/is_object.js");
 function isCloudflareWorkers() {
     return (typeof WebSocketPair !== 'undefined' ||
         (typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers') ||
@@ -12,9 +13,25 @@ function isCloudflareWorkers() {
 let USER_AGENT;
 if (typeof navigator === 'undefined' || !navigator.userAgent?.startsWith?.('Mozilla/5.0 ')) {
     const NAME = 'jose';
-    const VERSION = 'v5.4.1';
+    const VERSION = 'v5.5.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
+exports.experimental_jwksCache = Symbol();
+function isFreshJwksCache(input, cacheMaxAge) {
+    if (typeof input !== 'object' || input === null) {
+        return false;
+    }
+    if (!('uat' in input) || typeof input.uat !== 'number' || Date.now() - input.uat >= cacheMaxAge) {
+        return false;
+    }
+    if (!('jwks' in input) ||
+        !(0, is_object_js_1.default)(input.jwks) ||
+        !Array.isArray(input.jwks.keys) ||
+        !Array.prototype.every.call(input.jwks.keys, is_object_js_1.default)) {
+        return false;
+    }
+    return true;
+}
 class RemoteJWKSet {
     _url;
     _timeoutDuration;
@@ -24,6 +41,7 @@ class RemoteJWKSet {
     _pendingFetch;
     _options;
     _local;
+    _cache;
     constructor(url, options) {
         if (!(url instanceof URL)) {
             throw new TypeError('url must be an instance of URL');
@@ -35,6 +53,13 @@ class RemoteJWKSet {
         this._cooldownDuration =
             typeof options?.cooldownDuration === 'number' ? options?.cooldownDuration : 30000;
         this._cacheMaxAge = typeof options?.cacheMaxAge === 'number' ? options?.cacheMaxAge : 600000;
+        if (options?.[exports.experimental_jwksCache] !== undefined) {
+            this._cache = options?.[exports.experimental_jwksCache];
+            if (isFreshJwksCache(options?.[exports.experimental_jwksCache], this._cacheMaxAge)) {
+                this._jwksTimestamp = this._cache.uat;
+                this._local = (0, local_js_1.createLocalJWKSet)(this._cache.jwks);
+            }
+        }
     }
     coolingDown() {
         return typeof this._jwksTimestamp === 'number'
@@ -75,6 +100,10 @@ class RemoteJWKSet {
         this._pendingFetch ||= (0, fetch_jwks_js_1.default)(this._url, this._timeoutDuration, this._options)
             .then((json) => {
             this._local = (0, local_js_1.createLocalJWKSet)(json);
+            if (this._cache) {
+                this._cache.uat = Date.now();
+                this._cache.jwks = json;
+            }
             this._jwksTimestamp = Date.now();
             this._pendingFetch = undefined;
         })

package/dist/node/esm/index.js

@@ -17,7 +17,7 @@ export { EncryptJWT } from './jwt/encrypt.js';
 export { calculateJwkThumbprint, calculateJwkThumbprintUri } from './jwk/thumbprint.js';
 export { EmbeddedJWK } from './jwk/embedded.js';
 export { createLocalJWKSet } from './jwks/local.js';
-export { createRemoteJWKSet } from './jwks/remote.js';
+export { createRemoteJWKSet, experimental_jwksCache } from './jwks/remote.js';
 export { UnsecuredJWT } from './jwt/unsecured.js';
 export { exportPKCS8, exportSPKI, exportJWK } from './key/export.js';
 export { importSPKI, importPKCS8, importX509, importJWK } from './key/import.js';

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

@@ -1,6 +1,7 @@
 import fetchJwks from '../runtime/fetch_jwks.js';
 import { JWKSNoMatchingKey } from '../util/errors.js';
 import { createLocalJWKSet } from './local.js';
+import isObject from '../lib/is_object.js';
 function isCloudflareWorkers() {
     return (typeof WebSocketPair !== 'undefined' ||
         (typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers') ||
@@ -9,9 +10,25 @@ function isCloudflareWorkers() {
 let USER_AGENT;
 if (typeof navigator === 'undefined' || !navigator.userAgent?.startsWith?.('Mozilla/5.0 ')) {
     const NAME = 'jose';
-    const VERSION = 'v5.4.1';
+    const VERSION = 'v5.5.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
+export const experimental_jwksCache = Symbol();
+function isFreshJwksCache(input, cacheMaxAge) {
+    if (typeof input !== 'object' || input === null) {
+        return false;
+    }
+    if (!('uat' in input) || typeof input.uat !== 'number' || Date.now() - input.uat >= cacheMaxAge) {
+        return false;
+    }
+    if (!('jwks' in input) ||
+        !isObject(input.jwks) ||
+        !Array.isArray(input.jwks.keys) ||
+        !Array.prototype.every.call(input.jwks.keys, isObject)) {
+        return false;
+    }
+    return true;
+}
 class RemoteJWKSet {
     _url;
     _timeoutDuration;
@@ -21,6 +38,7 @@ class RemoteJWKSet {
     _pendingFetch;
     _options;
     _local;
+    _cache;
     constructor(url, options) {
         if (!(url instanceof URL)) {
             throw new TypeError('url must be an instance of URL');
@@ -32,6 +50,13 @@ class RemoteJWKSet {
         this._cooldownDuration =
             typeof options?.cooldownDuration === 'number' ? options?.cooldownDuration : 30000;
         this._cacheMaxAge = typeof options?.cacheMaxAge === 'number' ? options?.cacheMaxAge : 600000;
+        if (options?.[experimental_jwksCache] !== undefined) {
+            this._cache = options?.[experimental_jwksCache];
+            if (isFreshJwksCache(options?.[experimental_jwksCache], this._cacheMaxAge)) {
+                this._jwksTimestamp = this._cache.uat;
+                this._local = createLocalJWKSet(this._cache.jwks);
+            }
+        }
     }
     coolingDown() {
         return typeof this._jwksTimestamp === 'number'
@@ -72,6 +97,10 @@ class RemoteJWKSet {
         this._pendingFetch ||= fetchJwks(this._url, this._timeoutDuration, this._options)
             .then((json) => {
             this._local = createLocalJWKSet(json);
+            if (this._cache) {
+                this._cache.uat = Date.now();
+                this._cache.jwks = json;
+            }
             this._jwksTimestamp = Date.now();
             this._pendingFetch = undefined;
         })

package/dist/types/index.d.ts

@@ -28,8 +28,8 @@ export { EncryptJWT } from './jwt/encrypt';
 export { calculateJwkThumbprint, calculateJwkThumbprintUri } from './jwk/thumbprint';
 export { EmbeddedJWK } from './jwk/embedded';
 export { createLocalJWKSet } from './jwks/local';
-export { createRemoteJWKSet } from './jwks/remote';
-export type { RemoteJWKSetOptions } from './jwks/remote';
+export { createRemoteJWKSet, experimental_jwksCache } from './jwks/remote';
+export type { RemoteJWKSetOptions, JWKSCacheInput, ExportedJWKSCache } from './jwks/remote';
 export { UnsecuredJWT } from './jwt/unsecured';
 export type { UnsecuredResult } from './jwt/unsecured';
 export { exportPKCS8, exportSPKI, exportJWK } from './key/export';

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

@@ -1,4 +1,58 @@
 import type { KeyLike, JWSHeaderParameters, FlattenedJWSInput, JSONWebKeySet } from '../types';
+/**
+ * This is an experimental feature, it is not subject to semantic versioning rules. Non-backward
+ * compatible changes or removal may occur in any future release.
+ *
+ * DANGER ZONE - This option has security implications that must be understood, assessed for
+ * applicability, and accepted before use. It is critical that the JSON Web Key Set cache only be
+ * writable by your own code.
+ *
+ * This option is intended for cloud computing runtimes that cannot keep an in memory cache between
+ * their code's invocations. Use in runtimes where an in memory cache between requests is available
+ * is not desirable.
+ *
+ * When passed to {@link jwks/remote.createRemoteJWKSet createRemoteJWKSet} this allows the passed in
+ * object to:
+ *
+ * - Serve as an initial value for the JSON Web Key Set that the module would otherwise need to
+ *   trigger an HTTP request for
+ * - Have the JSON Web Key Set the function optionally ended up triggering an HTTP request for
+ *   assigned to it as properties
+ *
+ * The intended use pattern is:
+ *
+ * - Before verifying with {@link jwks/remote.createRemoteJWKSet createRemoteJWKSet} you pull the
+ *   previously cached object from a low-latency key-value store offered by the cloud computing
+ *   runtime it is executed on;
+ * - Default to an empty object `{}` instead when there's no previously cached value;
+ * - Pass it in as {@link RemoteJWKSetOptions[experimental_jwksCache]};
+ * - Afterwards, update the key-value storage if the {@link ExportedJWKSCache.uat `uat`} property of
+ *   the object has changed.
+ *
+ * import * as jose from 'jose'
+ *
+ * // Prerequisites
+ * let url!: URL
+ * let jwt!: string
+ *
+ * // Load JSON Web Key Set cache
+ * const jwksCache: jose.JWKSCacheInput = (await getPreviouslyCachedJWKS()) || {}
+ * const { uat } = jwksCache
+ *
+ * const JWKS = jose.createRemoteJWKSet(url, {
+ *   [jose.experimental_jwksCache]: jwksCache,
+ * })
+ *
+ * // Use JSON Web Key Set cache
+ * await jose.jwtVerify(jwt, JWKS)
+ *
+ * if (uat !== jwksCache.uat) {
+ *   // Update JSON Web Key Set cache
+ *   await storeNewJWKScache(jwksCache)
+ * }
+ * ```
+ */
+export declare const experimental_jwksCache: unique symbol;
 /** Options for the remote JSON Web Key Set. */
 export interface RemoteJWKSetOptions {
     /**
@@ -31,7 +85,14 @@ export interface RemoteJWKSetOptions {
      * configuration would cause an unnecessary CORS preflight request.
      */
     headers?: Record<string, string>;
+    /** See {@link experimental_jwksCache}. */
+    [experimental_jwksCache]?: JWKSCacheInput;
+}
+export interface ExportedJWKSCache {
+    jwks: JSONWebKeySet;
+    uat: number;
 }
+export type JWKSCacheInput = ExportedJWKSCache | Record<string, never>;
 /**
  * Returns a function that resolves a JWS JOSE Header to a public key object downloaded from a
  * remote endpoint returning a JSON Web Key Set, that is, for example, an OAuth 2.0 or OIDC

package/package.json

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