From 0f09c124529bf84f027e57ce1f769319e7d42185 Mon Sep 17 00:00:00 2001 From: Filip Skokan Date: Mon, 19 Aug 2024 12:59:28 +0200 Subject: [PATCH] feat: graduate jwksCache to stable API --- .../jwks_remote.RemoteJWKSetOptions.md | 8 +++--- docs/modules/jwks_remote.md | 2 +- ..._jwksCache.md => jwks_remote.jwksCache.md} | 11 +++----- src/index.ts | 2 +- src/jwks/remote.ts | 26 +++++++++++-------- 5 files changed, 25 insertions(+), 24 deletions(-) rename docs/variables/{jwks_remote.experimental_jwksCache.md => jwks_remote.jwksCache.md} (83%) diff --git a/docs/interfaces/jwks_remote.RemoteJWKSetOptions.md b/docs/interfaces/jwks_remote.RemoteJWKSetOptions.md index 570ac7fe9b..d0c88c7819 100644 --- a/docs/interfaces/jwks_remote.RemoteJWKSetOptions.md +++ b/docs/interfaces/jwks_remote.RemoteJWKSetOptions.md @@ -12,7 +12,7 @@ Options for the remote JSON Web Key Set. ### Properties -- [[experimental\_jwksCache]](jwks_remote.RemoteJWKSetOptions.md#[experimental_jwkscache]) +- [[jwksCache]](jwks_remote.RemoteJWKSetOptions.md#[jwkscache]) - [agent](jwks_remote.RemoteJWKSetOptions.md#agent) - [cacheMaxAge](jwks_remote.RemoteJWKSetOptions.md#cachemaxage) - [cooldownDuration](jwks_remote.RemoteJWKSetOptions.md#cooldownduration) @@ -21,11 +21,11 @@ Options for the remote JSON Web Key Set. ## Properties -### [experimental\_jwksCache] +### [jwksCache] -• `Optional` **[experimental\_jwksCache]**: [`JWKSCacheInput`](../types/jwks_remote.JWKSCacheInput.md) +• `Optional` **[jwksCache]**: [`JWKSCacheInput`](../types/jwks_remote.JWKSCacheInput.md) -See [experimental_jwksCache](../variables/jwks_remote.experimental_jwksCache.md). +See [jwksCache](../variables/jwks_remote.jwksCache.md). ___ diff --git a/docs/modules/jwks_remote.md b/docs/modules/jwks_remote.md index fcb35dddf8..cc91333956 100644 --- a/docs/modules/jwks_remote.md +++ b/docs/modules/jwks_remote.md @@ -23,4 +23,4 @@ Support from the community to continue maintaining and improving this module is ### Variables -- [experimental\_jwksCache](../variables/jwks_remote.experimental_jwksCache.md) +- [jwksCache](../variables/jwks_remote.jwksCache.md) diff --git a/docs/variables/jwks_remote.experimental_jwksCache.md b/docs/variables/jwks_remote.jwksCache.md similarity index 83% rename from docs/variables/jwks_remote.experimental_jwksCache.md rename to docs/variables/jwks_remote.jwksCache.md index 2dfebde77c..d16dbdcfc5 100644 --- a/docs/variables/jwks_remote.experimental_jwksCache.md +++ b/docs/variables/jwks_remote.jwksCache.md @@ -1,4 +1,4 @@ -# Variable: experimental\_jwksCache +# Variable: jwksCache ## [💗 Help the project](https://github.com/sponsors/panva) @@ -6,10 +6,7 @@ Support from the community to continue maintaining and improving this module is --- -• `Const` **experimental\_jwksCache**: unique `symbol` - -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. +• `Const` **jwksCache**: unique `symbol` 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 @@ -33,7 +30,7 @@ The intended use pattern is: 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 [[experimental_jwksCache]](../interfaces/jwks_remote.RemoteJWKSetOptions.md); +- Pass it in as [[jwksCache]](../interfaces/jwks_remote.RemoteJWKSetOptions.md); - Afterwards, update the key-value storage if the [`uat`](../interfaces/jwks_remote.ExportedJWKSCache.md#uat) property of the object has changed. @@ -51,7 +48,7 @@ const jwksCache: jose.JWKSCacheInput = (await getPreviouslyCachedJWKS()) || {} const { uat } = jwksCache const JWKS = jose.createRemoteJWKSet(url, { - [jose.experimental_jwksCache]: jwksCache, + [jose.jwksCache]: jwksCache, }) // Use JSON Web Key Set cache diff --git a/src/index.ts b/src/index.ts index 343bf77d0c..cc9aedd817 100644 --- a/src/index.ts +++ b/src/index.ts @@ -35,7 +35,7 @@ export { calculateJwkThumbprint, calculateJwkThumbprintUri } from './jwk/thumbpr export { EmbeddedJWK } from './jwk/embedded.js' export { createLocalJWKSet } from './jwks/local.js' -export { createRemoteJWKSet, experimental_jwksCache } from './jwks/remote.js' +export { createRemoteJWKSet, jwksCache, experimental_jwksCache } from './jwks/remote.js' export type { RemoteJWKSetOptions, JWKSCacheInput, ExportedJWKSCache } from './jwks/remote.js' export { UnsecuredJWT } from './jwt/unsecured.js' diff --git a/src/jwks/remote.ts b/src/jwks/remote.ts index 91104ca7c2..5e9ae8350c 100644 --- a/src/jwks/remote.ts +++ b/src/jwks/remote.ts @@ -29,9 +29,6 @@ if (typeof navigator === 'undefined' || !navigator.userAgent?.startsWith?.('Mozi } /** - * 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. @@ -54,7 +51,7 @@ if (typeof navigator === 'undefined' || !navigator.userAgent?.startsWith?.('Mozi * 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]}; + * - Pass it in as {@link RemoteJWKSetOptions[jwksCache]}; * - Afterwards, update the key-value storage if the {@link ExportedJWKSCache.uat `uat`} property of * the object has changed. * @@ -72,7 +69,7 @@ if (typeof navigator === 'undefined' || !navigator.userAgent?.startsWith?.('Mozi * const { uat } = jwksCache * * const JWKS = jose.createRemoteJWKSet(url, { - * [jose.experimental_jwksCache]: jwksCache, + * [jose.jwksCache]: jwksCache, * }) * * // Use JSON Web Key Set cache @@ -84,7 +81,7 @@ if (typeof navigator === 'undefined' || !navigator.userAgent?.startsWith?.('Mozi * } * ``` */ -export const experimental_jwksCache: unique symbol = Symbol() +export const jwksCache: unique symbol = Symbol() /** Options for the remote JSON Web Key Set. */ export interface RemoteJWKSetOptions { @@ -123,8 +120,8 @@ export interface RemoteJWKSetOptions { */ headers?: Record - /** See {@link experimental_jwksCache}. */ - [experimental_jwksCache]?: JWKSCacheInput + /** See {@link jwksCache}. */ + [jwksCache]?: JWKSCacheInput } export interface ExportedJWKSCache { @@ -186,9 +183,9 @@ class RemoteJWKSet { 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)) { + if (options?.[jwksCache] !== undefined) { + this._cache = options?.[jwksCache] + if (isFreshJwksCache(options?.[jwksCache], this._cacheMaxAge)) { this._jwksTimestamp = this._cache.uat this._local = createLocalJWKSet(this._cache.jwks) } @@ -384,3 +381,10 @@ export function createRemoteJWKSet( // @ts-expect-error return remoteJWKSet } + +/** + * @ignore + * + * @deprecated Use {@link jwksCache}. + */ +export const experimental_jwksCache = jwksCache