oauth4webapi 2.10.3 → 2.11.0

package/README.md

@@ -29,7 +29,7 @@ The following features are currently in scope and implemented in this software:
 
 `oauth4webapi` has no dependencies and it exports tree-shakeable ESM.
 
-## [Documentation](docs/README.md)
+## [API Reference](docs/README.md)
 
 `oauth4webapi` is distributed via [npmjs.com](https://www.npmjs.com/package/oauth4webapi), [deno.land/x](https://deno.land/x/oauth4webapi), [cdnjs.com](https://cdnjs.com/libraries/oauth4webapi), [jsdelivr.com](https://www.jsdelivr.com/package/npm/oauth4webapi), and [github.com](https://github.com/panva/oauth4webapi).
 
@@ -38,13 +38,13 @@ The following features are currently in scope and implemented in this software:
 **`example`** ESM import
 
 ```js
-import * as oauth2 from 'oauth4webapi'
+import * as oauth from 'oauth4webapi'
 ```
 
 **`example`** Deno import
 
 ```js
-import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.10.3/mod.ts'
+import * as oauth from 'https://deno.land/x/oauth4webapi@v2.11.0/mod.ts'
 ```
 
 - Authorization Code Flow (OAuth 2.0) - [source](examples/oauth.ts)

package/build/index.d.ts

@@ -135,11 +135,24 @@ export type ClientAuthenticationMethod = 'client_secret_basic' | 'client_secret_
  * ```
  */
 export type JWSAlgorithm = 'PS256' | 'ES256' | 'RS256' | 'EdDSA' | 'ES384' | 'PS384' | 'RS384' | 'ES512' | 'PS512' | 'RS512';
+export interface JWK {
+    readonly kty?: string;
+    readonly kid?: string;
+    readonly alg?: string;
+    readonly use?: string;
+    readonly key_ops?: string[];
+    readonly e?: string;
+    readonly n?: string;
+    readonly crv?: string;
+    readonly x?: string;
+    readonly y?: string;
+    readonly [parameter: string]: JsonValue | undefined;
+}
 export declare const clockSkew: unique symbol;
 export declare const clockTolerance: unique symbol;
 /**
- * When configured on an interface that extends {@link HttpRequestOptions}, that's every `options`
- * parameter for functions that trigger HTTP Requests, this replaces the use of global fetch. As a
+ * When configured on an interface that extends {@link HttpRequestOptions}, this applies to `options`
+ * parameter for functions that trigger HTTP requests, this replaces the use of global fetch. As a
  * fetch replacement the arguments and expected return are the same as fetch.
  *
  * In theory any module that claims to be compatible with the Fetch API can be used but your mileage
@@ -221,6 +234,63 @@ export declare const clockTolerance: unique symbol;
  * ```
  */
 export declare const customFetch: 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.
+ *
+ * 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 configured on an interface that extends {@link JWKSCacheOptions}, this applies to `options`
+ * parameter for functions that trigger HTTP requests for the
+ * {@link AuthorizationServer.jwks_uri `as.jwks_uri`}, 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 executing a function with {@link JWKSCacheOptions} in its `options` parameter 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 into the options interfaces that extend {@link JWKSCacheOptions};
+ * - Afterwards, update the key-value storage if the {@link ExportedJWKSCache.uat `uat`} property of
+ *   the object has changed.
+ *
+ * @example
+ *
+ * ```ts
+ * import * as oauth from 'oauth4webapi'
+ *
+ * // Prerequisites
+ * let as!: oauth.AuthorizationServer
+ * let request!: Request
+ * let expectedAudience!: string
+ *
+ * // Load JSON Web Key Set cache
+ * const jwksCache: oauth.JWKSCacheInput = (await getPreviouslyCachedJWKS()) || {}
+ * const { uat } = jwksCache
+ *
+ * // Use JSON Web Key Set cache
+ * const accessTokenClaims = await validateJwtAccessToken(as, request, expectedAudience, {
+ *   [oauth.experimental_jwksCache]: jwksCache,
+ * })
+ *
+ * if (uat !== jwksCache.uat) {
+ *   // Update JSON Web Key Set cache
+ *   await storeNewJWKScache(jwksCache)
+ * }
+ * ```
+ */
+export declare const experimental_jwksCache: unique symbol;
 /**
  * When combined with {@link customFetch} (to use a Fetch API implementation that supports client
  * certificates) this can be used to target FAPI 2.0 profiles that utilize Mutual-TLS for either
@@ -725,9 +795,15 @@ export declare class OperationProcessingError extends Error {
         cause?: unknown;
     });
 }
+export interface JWKSCacheOptions {
+    /**
+     * See {@link experimental_jwksCache}.
+     */
+    [experimental_jwksCache]?: JWKSCacheInput;
+}
 export interface HttpRequestOptions {
     /**
-     * An AbortSignal instance, or a factory returning one, to abort the HTTP Request(s) triggered by
+     * An AbortSignal instance, or a factory returning one, to abort the HTTP request(s) triggered by
      * this function's invocation.
      *
      * @example
@@ -740,7 +816,7 @@ export interface HttpRequestOptions {
      */
     signal?: (() => AbortSignal) | AbortSignal;
     /**
-     * Headers to additionally send with the HTTP Request(s) triggered by this function's invocation.
+     * Headers to additionally send with the HTTP request(s) triggered by this function's invocation.
      */
     headers?: [string, string][] | Record<string, string> | Headers;
     /**
@@ -1002,7 +1078,7 @@ export interface ProtectedResourceRequestOptions extends Omit<HttpRequestOptions
  * @see [RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://www.rfc-editor.org/rfc/rfc6750.html#section-2.1)
  * @see [RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)](https://www.rfc-editor.org/rfc/rfc9449.html#name-protected-resource-access)
  */
-export declare function protectedResourceRequest(accessToken: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | string, url: URL, headers?: Headers, body?: ReadableStream | Blob | ArrayBufferView | ArrayBuffer | FormData | URLSearchParams | string | null, options?: ProtectedResourceRequestOptions): Promise<Response>;
+export declare function protectedResourceRequest(accessToken: string, method: string, url: URL, headers?: Headers, body?: ReadableStream | Blob | ArrayBufferView | ArrayBuffer | FormData | URLSearchParams | string | null, options?: ProtectedResourceRequestOptions): Promise<Response>;
 export interface UserInfoRequestOptions extends HttpRequestOptions, DPoPRequestOptions, UseMTLSAliasOptions {
 }
 /**
@@ -1053,8 +1129,14 @@ export interface UserInfoResponse {
     readonly address?: UserInfoAddress;
     readonly [claim: string]: JsonValue | undefined;
 }
+export interface ExportedJWKSCache {
+    jwks: JWKS;
+    uat: number;
+}
+export type JWKSCacheInput = ExportedJWKSCache | Record<string, never>;
 /**
- * DANGER ZONE
+ * DANGER ZONE - This option has security implications that must be understood, assessed for
+ * applicability, and accepted before use.
  *
  * Use this as a value to {@link processUserInfoResponse} `expectedSubject` parameter to skip the
  * `sub` claim value check.
@@ -1433,6 +1515,11 @@ export interface IntrospectionResponse {
  * @see [draft-ietf-oauth-jwt-introspection-response-12 - JWT Response for OAuth Token Introspection](https://www.ietf.org/archive/id/draft-ietf-oauth-jwt-introspection-response-12.html#section-5)
  */
 export declare function processIntrospectionResponse(as: AuthorizationServer, client: Client, response: Response): Promise<IntrospectionResponse | OAuth2Error>;
+export interface JWKS {
+    readonly keys: JWK[];
+}
+export interface ValidateJwtAuthResponseOptions extends HttpRequestOptions, JWKSCacheOptions {
+}
 /**
  * Same as {@link validateAuthResponse} but for signed JARM responses.
  *
@@ -1449,7 +1536,9 @@ export declare function processIntrospectionResponse(as: AuthorizationServer, cl
  *
  * @see [JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)](https://openid.net/specs/openid-financial-api-jarm.html)
  */
-export declare function validateJwtAuthResponse(as: AuthorizationServer, client: Client, parameters: URLSearchParams | URL, expectedState?: string | typeof expectNoState | typeof skipStateCheck, options?: HttpRequestOptions): Promise<URLSearchParams | OAuth2Error>;
+export declare function validateJwtAuthResponse(as: AuthorizationServer, client: Client, parameters: URLSearchParams | URL, expectedState?: string | typeof expectNoState | typeof skipStateCheck, options?: ValidateJwtAuthResponseOptions): Promise<URLSearchParams | OAuth2Error>;
+export interface ValidateDetachedSignatureResponseOptions extends HttpRequestOptions, JWKSCacheOptions {
+}
 /**
  * Same as {@link validateAuthResponse} but for FAPI 1.0 Advanced Detached Signature authorization
  * responses.
@@ -1472,15 +1561,16 @@ export declare function validateJwtAuthResponse(as: AuthorizationServer, client:
  *
  * @see [Financial-grade API Security Profile 1.0 - Part 2: Advanced](https://openid.net/specs/openid-financial-api-part-2-1_0.html#id-token-as-detached-signature)
  */
-export declare function validateDetachedSignatureResponse(as: AuthorizationServer, client: Client, parameters: URLSearchParams | URL, expectedNonce: string, expectedState?: string | typeof expectNoState, maxAge?: number | typeof skipAuthTimeCheck, options?: HttpRequestOptions): Promise<URLSearchParams | OAuth2Error>;
+export declare function validateDetachedSignatureResponse(as: AuthorizationServer, client: Client, parameters: URLSearchParams | URL, expectedNonce: string, expectedState?: string | typeof expectNoState, maxAge?: number | typeof skipAuthTimeCheck, options?: ValidateDetachedSignatureResponseOptions): Promise<URLSearchParams | OAuth2Error>;
 /**
- * DANGER ZONE
+ * DANGER ZONE - This option has security implications that must be understood, assessed for
+ * applicability, and accepted before use.
  *
  * Use this as a value to {@link validateAuthResponse} `expectedState` parameter to skip the `state`
- * value check. This should only ever be done if you use a `state` parameter value that is integrity
- * protected and bound to the browsing session. One such mechanism to do so is described in an I-D
+ * value check when you'll be validating such `state` value yourself instead. This should only be
+ * done if you use a `state` parameter value that is integrity protected and bound to the browsing
+ * session. One such mechanism to do so is described in an I-D
  * [draft-bradley-oauth-jwt-encoded-state-09](https://datatracker.ietf.org/doc/html/draft-bradley-oauth-jwt-encoded-state-09).
- * It is expected you'll validate such `state` value yourself.
  */
 export declare const skipStateCheck: unique symbol;
 /**
@@ -1615,7 +1705,7 @@ export interface JWTAccessTokenClaims extends JWTPayload {
     readonly scope?: string;
     readonly [claim: string]: JsonValue | undefined;
 }
-export interface ValidateJWTAccessTokenOptions extends HttpRequestOptions {
+export interface ValidateJWTAccessTokenOptions extends HttpRequestOptions, JWKSCacheOptions {
     /**
      * Indicates whether DPoP use is required.
      */
@@ -1631,7 +1721,10 @@ export interface ValidateJWTAccessTokenOptions extends HttpRequestOptions {
 }
 /**
  * Validates use of JSON Web Token (JWT) OAuth 2.0 Access Tokens for a given {@link Request} as per
- * RFC 9068 and optionally also RFC 9449.
+ * RFC 6750, RFC 9068, and RFC 9449.
+ *
+ * The only supported means of sending access tokens is via the Authorization Request Header Field
+ * method.
  *
  * This does validate the presence and type of all required claims as well as the values of the
  * {@link JWTAccessTokenClaims.iss `iss`}, {@link JWTAccessTokenClaims.exp `exp`},
@@ -1655,6 +1748,7 @@ export interface ValidateJWTAccessTokenOptions extends HttpRequestOptions {
  *
  * @group JWT Access Tokens
  *
+ * @see [RFC 6750 - OAuth 2.0 Bearer Token Usage](https://www.rfc-editor.org/rfc/rfc6750.html)
  * @see [RFC 9068 - JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens](https://www.rfc-editor.org/rfc/rfc9068.html)
  * @see [RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)](https://www.rfc-editor.org/rfc/rfc9449.html)
  */

package/build/index.js

@@ -1,7 +1,7 @@
 let USER_AGENT;
 if (typeof navigator === 'undefined' || !navigator.userAgent?.startsWith?.('Mozilla/5.0 ')) {
     const NAME = 'oauth4webapi';
-    const VERSION = 'v2.10.3';
+    const VERSION = 'v2.11.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
 function looseInstanceOf(input, expected) {
@@ -19,6 +19,7 @@ function looseInstanceOf(input, expected) {
 export const clockSkew = Symbol();
 export const clockTolerance = Symbol();
 export const customFetch = Symbol();
+export const experimental_jwksCache = Symbol();
 export const useMtlsAlias = Symbol();
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
@@ -729,31 +730,60 @@ export async function userInfoRequest(as, client, accessToken, options) {
         [clockSkew]: getClockSkew(client),
     });
 }
-let jwksCache;
+let jwksMap;
+function setJwksCache(as, jwks, uat, cache) {
+    jwksMap || (jwksMap = new WeakMap());
+    jwksMap.set(as, {
+        jwks,
+        uat,
+        get age() {
+            return epochTime() - this.uat;
+        },
+    });
+    if (cache) {
+        Object.assign(cache, { jwks: structuredClone(jwks), uat });
+    }
+}
+function isFreshJwksCache(input) {
+    if (typeof input !== 'object' || input === null) {
+        return false;
+    }
+    if (!('uat' in input) || typeof input.uat !== 'number' || epochTime() - input.uat >= 300) {
+        return false;
+    }
+    if (!('jwks' in input) ||
+        !isJsonObject(input.jwks) ||
+        !Array.isArray(input.jwks.keys) ||
+        !Array.prototype.every.call(input.jwks.keys, isJsonObject)) {
+        return false;
+    }
+    return true;
+}
+function clearJwksCache(as, cache) {
+    jwksMap?.delete(as);
+    delete cache?.jwks;
+    delete cache?.uat;
+}
 async function getPublicSigKeyFromIssuerJwksUri(as, options, header) {
     const { alg, kid } = header;
     checkSupportedJwsAlg(alg);
+    if (!jwksMap?.has(as) && isFreshJwksCache(options?.[experimental_jwksCache])) {
+        setJwksCache(as, options?.[experimental_jwksCache].jwks, options?.[experimental_jwksCache].uat);
+    }
     let jwks;
     let age;
-    jwksCache || (jwksCache = new WeakMap());
-    if (jwksCache.has(as)) {
+    if (jwksMap?.has(as)) {
         ;
-        ({ jwks, age } = jwksCache.get(as));
+        ({ jwks, age } = jwksMap.get(as));
         if (age >= 300) {
-            jwksCache.delete(as);
+            clearJwksCache(as, options?.[experimental_jwksCache]);
             return getPublicSigKeyFromIssuerJwksUri(as, options, header);
         }
     }
     else {
         jwks = await jwksRequest(as, options).then(processJwksResponse);
         age = 0;
-        jwksCache.set(as, {
-            jwks,
-            iat: epochTime(),
-            get age() {
-                return epochTime() - this.iat;
-            },
-        });
+        setJwksCache(as, jwks, epochTime(), options?.[experimental_jwksCache]);
     }
     let kty;
     switch (alg.slice(0, 2)) {
@@ -798,7 +828,7 @@ async function getPublicSigKeyFromIssuerJwksUri(as, options, header) {
     const { 0: jwk, length } = candidates;
     if (!length) {
         if (age >= 60) {
-            jwksCache.delete(as);
+            clearJwksCache(as, options?.[experimental_jwksCache]);
             return getPublicSigKeyFromIssuerJwksUri(as, options, header);
         }
         throw new OPE('error when selecting a JWT verification key, no applicable keys found');
@@ -1073,7 +1103,7 @@ export async function processAuthorizationCodeOpenIDResponse(as, client, respons
     }
     if (maxAge !== skipAuthTimeCheck) {
         if (typeof maxAge !== 'number' || maxAge < 0) {
-            throw new TypeError('"options.max_age" must be a non-negative number');
+            throw new TypeError('"maxAge" must be a non-negative number');
         }
         const now = epochTime() + getClockSkew(client);
         const tolerance = getClockTolerance(client);
@@ -1564,7 +1594,7 @@ export async function validateDetachedSignatureResponse(as, client, parameters,
     }
     if (maxAge !== skipAuthTimeCheck) {
         if (typeof maxAge !== 'number' || maxAge < 0) {
-            throw new TypeError('"options.max_age" must be a non-negative number');
+            throw new TypeError('"maxAge" must be a non-negative number');
         }
         const now = epochTime() + getClockSkew(client);
         const tolerance = getClockTolerance(client);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth4webapi",
-  "version": "2.10.3",
+  "version": "2.11.0",
   "description": "OAuth 2 / OpenID Connect for JavaScript Runtimes",
   "keywords": [
     "access token",
@@ -67,29 +67,29 @@
   "devDependencies": {
     "@koa/cors": "^5.0.0",
     "@types/koa__cors": "^5.0.0",
-    "@types/node": "^20.11.16",
-    "@types/oidc-provider": "^8.4.3",
+    "@types/node": "^20.14.5",
+    "@types/oidc-provider": "^8.4.4",
     "@types/qunit": "^2.19.10",
-    "archiver": "^6.0.1",
-    "ava": "^5.3.1",
-    "chrome-launcher": "^1.1.0",
-    "edge-runtime": "^2.5.8",
-    "esbuild": "^0.20.0",
-    "jose": "^5.2.1",
-    "oidc-provider": "^8.4.5",
+    "archiver": "^7.0.1",
+    "ava": "^6.1.3",
+    "chrome-launcher": "^1.1.2",
+    "edge-runtime": "^2.5.10",
+    "esbuild": "^0.21.5",
+    "jose": "^5.4.0",
+    "oidc-provider": "^8.4.6",
     "patch-package": "^8.0.0",
-    "prettier": "^3.2.5",
+    "prettier": "^3.3.2",
     "prettier-plugin-jsdoc": "^1.3.0",
-    "puppeteer-core": "^22.0.0",
-    "qunit": "^2.20.0",
+    "puppeteer-core": "^22.11.1",
+    "qunit": "^2.21.0",
     "raw-body": "^2.5.2",
     "selfsigned": "^2.4.1",
     "timekeeper": "^2.3.1",
-    "tsx": "^4.7.0",
-    "typedoc": "^0.25.7",
+    "tsx": "^4.15.6",
+    "typedoc": "^0.25.13",
     "typedoc-plugin-markdown": "^3.17.1",
-    "typedoc-plugin-mdn-links": "^3.1.15",
-    "typescript": "^5.3.3",
-    "undici": "^5.28.3"
+    "typedoc-plugin-mdn-links": "^3.1.30",
+    "typescript": "~5.4.5",
+    "undici": "^6.19.2"
   }
 }