oauth4webapi 2.11.0 → 2.12.0

package/README.md

@@ -21,10 +21,12 @@ The following features are currently in scope and implemented in this software:
 
 [<img width="96" height="50" align="right" src="https://user-images.githubusercontent.com/241506/166977513-7cd710a9-7f60-4944-aebe-a658e9f36375.png" alt="OpenID Certification">](#certification)
 
-[Filip Skokan](https://github.com/panva) has certified that [this software](https://github.com/panva/oauth4webapi) conforms to the Basic, FAPI 1.0 Advanced, FAPI 2.0 Security Profile, and FAPI 2.0 Message Signing Relying Party Conformance Profiles of the OpenID Connect™ protocol.
+[Filip Skokan](https://github.com/panva) has certified that [this software](https://github.com/panva/oauth4webapi) conforms to the Basic, FAPI 1.0, and FAPI 2.0 Relying Party Conformance Profiles of the OpenID Connect™ protocol.
 
 ## [💗 Help the project](https://github.com/sponsors/panva)
 
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
 ## Dependencies: 0
 
 `oauth4webapi` has no dependencies and it exports tree-shakeable ESM.
@@ -44,7 +46,7 @@ import * as oauth from 'oauth4webapi'
 **`example`** Deno import
 
 ```js
-import * as oauth from 'https://deno.land/x/oauth4webapi@v2.11.0/mod.ts'
+import * as oauth from 'https://deno.land/x/oauth4webapi@v2.12.0/mod.ts'
 ```
 
 - Authorization Code Flow (OAuth 2.0) - [source](examples/oauth.ts)

package/build/index.d.ts

@@ -148,7 +148,51 @@ export interface JWK {
     readonly y?: string;
     readonly [parameter: string]: JsonValue | undefined;
 }
+/**
+ * Use to adjust the assumed current time. Positive and negative finite values representing seconds
+ * are allowed. Default is `0` (Date.now() + 0 seconds is used).
+ *
+ * @example
+ *
+ * When the local clock is mistakenly 1 hour in the past
+ *
+ * ```ts
+ * const client: oauth.Client = {
+ *   client_id: 'abc4ba37-4ab8-49b5-99d4-9441ba35d428',
+ *   // ... other metadata
+ *   [oauth.clockSkew]: +(60 * 60),
+ * }
+ * ```
+ *
+ * @example
+ *
+ * When the local clock is mistakenly 1 hour in the future
+ *
+ * ```ts
+ * const client: oauth.Client = {
+ *   client_id: 'abc4ba37-4ab8-49b5-99d4-9441ba35d428',
+ *   // ... other metadata
+ *   [oauth.clockSkew]: -(60 * 60),
+ * }
+ * ```
+ */
 export declare const clockSkew: unique symbol;
+/**
+ * Use to set allowed clock tolerance when checking DateTime JWT Claims. Only positive finite values
+ * representing seconds are allowed. Default is `30` (30 seconds).
+ *
+ * @example
+ *
+ * Tolerate 30 seconds clock skew when validating JWT claims like exp or nbf.
+ *
+ * ```ts
+ * const client: oauth.Client = {
+ *   client_id: 'abc4ba37-4ab8-49b5-99d4-9441ba35d428',
+ *   // ... other metadata
+ *   [oauth.clockTolerance]: 30,
+ * }
+ * ```
+ */
 export declare const clockTolerance: unique symbol;
 /**
  * When configured on an interface that extends {@link HttpRequestOptions}, this applies to `options`
@@ -235,9 +279,6 @@ 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.
@@ -281,7 +322,7 @@ export declare const customFetch: unique symbol;
  *
  * // Use JSON Web Key Set cache
  * const accessTokenClaims = await validateJwtAccessToken(as, request, expectedAudience, {
- *   [oauth.experimental_jwksCache]: jwksCache,
+ *   [oauth.jwksCache]: jwksCache,
  * })
  *
  * if (uat !== jwksCache.uat) {
@@ -290,7 +331,7 @@ export declare const customFetch: unique symbol;
  * }
  * ```
  */
-export declare const experimental_jwksCache: unique symbol;
+export declare const 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
@@ -734,49 +775,11 @@ export interface Client {
      */
     default_max_age?: number;
     /**
-     * Use to adjust the client's assumed current time. Positive and negative finite values
-     * representing seconds are allowed. Default is `0` (Date.now() + 0 seconds is used).
-     *
-     * @example
-     *
-     * When the client's local clock is mistakenly 1 hour in the past
-     *
-     * ```ts
-     * const client: oauth.Client = {
-     *   client_id: 'abc4ba37-4ab8-49b5-99d4-9441ba35d428',
-     *   // ... other metadata
-     *   [oauth.clockSkew]: +(60 * 60),
-     * }
-     * ```
-     *
-     * @example
-     *
-     * When the client's local clock is mistakenly 1 hour in the future
-     *
-     * ```ts
-     * const client: oauth.Client = {
-     *   client_id: 'abc4ba37-4ab8-49b5-99d4-9441ba35d428',
-     *   // ... other metadata
-     *   [oauth.clockSkew]: -(60 * 60),
-     * }
-     * ```
+     * See {@link clockSkew}.
      */
     [clockSkew]?: number;
     /**
-     * Use to set allowed client's clock tolerance when checking DateTime JWT Claims. Only positive
-     * finite values representing seconds are allowed. Default is `30` (30 seconds).
-     *
-     * @example
-     *
-     * Tolerate 30 seconds clock skew when validating JWT claims like exp or nbf.
-     *
-     * ```ts
-     * const client: oauth.Client = {
-     *   client_id: 'abc4ba37-4ab8-49b5-99d4-9441ba35d428',
-     *   // ... other metadata
-     *   [oauth.clockTolerance]: 30,
-     * }
-     * ```
+     * See {@link clockTolerance}.
      */
     [clockTolerance]?: number;
     [metadata: string]: JsonValue | undefined;
@@ -797,9 +800,9 @@ export declare class OperationProcessingError extends Error {
 }
 export interface JWKSCacheOptions {
     /**
-     * See {@link experimental_jwksCache}.
+     * See {@link jwksCache}.
      */
-    [experimental_jwksCache]?: JWKSCacheInput;
+    [jwksCache]?: JWKSCacheInput;
 }
 export interface HttpRequestOptions {
     /**
@@ -822,7 +825,7 @@ export interface HttpRequestOptions {
     /**
      * See {@link customFetch}.
      */
-    [customFetch]?: typeof fetch;
+    [customFetch]?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 }
 export interface DiscoveryRequestOptions extends HttpRequestOptions {
     /**
@@ -1054,11 +1057,7 @@ export declare function parseWwwAuthenticateChallenges(response: Response): WWWA
 export declare function processPushedAuthorizationResponse(as: AuthorizationServer, client: Client, response: Response): Promise<PushedAuthorizationResponse | OAuth2Error>;
 export interface ProtectedResourceRequestOptions extends Omit<HttpRequestOptions, 'headers'>, DPoPRequestOptions {
     /**
-     * Use to adjust the client's assumed current time. Positive and negative finite values
-     * representing seconds are allowed. Default is `0` (Date.now() + 0 seconds is used).
-     *
-     * This option only affects the request if the {@link ProtectedResourceRequestOptions.DPoP DPoP}
-     * option is also used.
+     * See {@link clockSkew}.
      */
     [clockSkew]?: number;
 }
@@ -1711,11 +1710,11 @@ export interface ValidateJWTAccessTokenOptions extends HttpRequestOptions, JWKSC
      */
     requireDPoP?: boolean;
     /**
-     * Same functionality as in {@link Client}
+     * See {@link clockSkew}.
      */
     [clockSkew]?: number;
     /**
-     * Same functionality as in {@link Client}
+     * See {@link clockTolerance}.
      */
     [clockTolerance]?: number;
 }
@@ -1794,11 +1793,17 @@ export type IntrospectionConfirmationClaims = ConfirmationClaims;
  *
  * @deprecated Use {@link validateDetachedSignatureResponse}.
  */
-export declare const experimental_validateDetachedSignatureResponse: typeof validateDetachedSignatureResponse;
+export declare const experimental_validateDetachedSignatureResponse: (as: AuthorizationServer, client: Client, parameters: URLSearchParams | URL, expectedNonce: string, expectedState?: string | typeof expectNoState | undefined, maxAge?: number | typeof skipAuthTimeCheck | undefined, options?: ValidateDetachedSignatureResponseOptions | undefined) => Promise<URLSearchParams | OAuth2Error>;
 /**
  * @ignore
  *
  * @deprecated Use {@link validateJwtAccessToken}.
  */
-export declare const experimental_validateJwtAccessToken: typeof validateJwtAccessToken;
+export declare const experimental_validateJwtAccessToken: (as: AuthorizationServer, request: Request, expectedAudience: string, options?: ValidateJWTAccessTokenOptions | undefined) => Promise<JWTAccessTokenClaims>;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link jwksCache}.
+ */
+export declare const experimental_jwksCache: symbol;
 export {};

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.11.0';
+    const VERSION = 'v2.12.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
 function looseInstanceOf(input, expected) {
@@ -19,7 +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 jwksCache = Symbol();
 export const useMtlsAlias = Symbol();
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
@@ -767,8 +767,8 @@ function clearJwksCache(as, cache) {
 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);
+    if (!jwksMap?.has(as) && isFreshJwksCache(options?.[jwksCache])) {
+        setJwksCache(as, options?.[jwksCache].jwks, options?.[jwksCache].uat);
     }
     let jwks;
     let age;
@@ -776,14 +776,14 @@ async function getPublicSigKeyFromIssuerJwksUri(as, options, header) {
         ;
         ({ jwks, age } = jwksMap.get(as));
         if (age >= 300) {
-            clearJwksCache(as, options?.[experimental_jwksCache]);
+            clearJwksCache(as, options?.[jwksCache]);
             return getPublicSigKeyFromIssuerJwksUri(as, options, header);
         }
     }
     else {
         jwks = await jwksRequest(as, options).then(processJwksResponse);
         age = 0;
-        setJwksCache(as, jwks, epochTime(), options?.[experimental_jwksCache]);
+        setJwksCache(as, jwks, epochTime(), options?.[jwksCache]);
     }
     let kty;
     switch (alg.slice(0, 2)) {
@@ -828,7 +828,7 @@ async function getPublicSigKeyFromIssuerJwksUri(as, options, header) {
     const { 0: jwk, length } = candidates;
     if (!length) {
         if (age >= 60) {
-            clearJwksCache(as, options?.[experimental_jwksCache]);
+            clearJwksCache(as, options?.[jwksCache]);
             return getPublicSigKeyFromIssuerJwksUri(as, options, header);
         }
         throw new OPE('error when selecting a JWT verification key, no applicable keys found');
@@ -994,8 +994,9 @@ async function processGenericAccessTokenResponse(as, client, response, ignoreIdT
             if (Array.isArray(claims.aud) && claims.aud.length !== 1 && claims.azp !== client.client_id) {
                 throw new OPE('unexpected ID Token "azp" (authorized party) claim value');
             }
-            if (client.require_auth_time && typeof claims.auth_time !== 'number') {
-                throw new OPE('unexpected ID Token "auth_time" (authentication time) claim value');
+            if (claims.auth_time !== undefined &&
+                (!Number.isFinite(claims.auth_time) || Math.sign(claims.auth_time) !== 1)) {
+                throw new OPE('ID Token "auth_time" (authentication time) must be a positive number');
             }
             idTokenClaims.set(json, claims);
         }
@@ -1584,8 +1585,9 @@ export async function validateDetachedSignatureResponse(as, client, parameters,
             (await idTokenHashMatches(expectedState, claims.s_hash, header.alg, key)) !== true)) {
         throw new OPE('invalid ID Token "s_hash" (state hash) claim value');
     }
-    if (client.require_auth_time !== undefined && typeof claims.auth_time !== 'number') {
-        throw new OPE('unexpected ID Token "auth_time" (authentication time) claim value');
+    if (claims.auth_time !== undefined &&
+        (!Number.isFinite(claims.auth_time) || Math.sign(claims.auth_time) !== 1)) {
+        throw new OPE('ID Token "auth_time" (authentication time) must be a positive number');
     }
     maxAge ?? (maxAge = client.default_max_age ?? skipAuthTimeCheck);
     if ((client.require_auth_time || maxAge !== skipAuthTimeCheck) &&
@@ -1798,7 +1800,7 @@ export async function generateKeyPair(alg, options) {
     if (!validateString(alg)) {
         throw new TypeError('"alg" must be a non-empty string');
     }
-    const algorithm = algToSubtle(alg, alg === 'EdDSA' ? options?.crv ?? 'Ed25519' : undefined);
+    const algorithm = algToSubtle(alg, alg === 'EdDSA' ? (options?.crv ?? 'Ed25519') : undefined);
     if (alg.startsWith('PS') || alg.startsWith('RS')) {
         Object.assign(algorithm, {
             modulusLength: options?.modulusLength ?? 2048,
@@ -1961,5 +1963,6 @@ export const experimentalCustomFetch = customFetch;
 export const experimental_customFetch = customFetch;
 export const experimentalUseMtlsAlias = useMtlsAlias;
 export const experimental_useMtlsAlias = useMtlsAlias;
-export const experimental_validateDetachedSignatureResponse = validateDetachedSignatureResponse;
-export const experimental_validateJwtAccessToken = validateJwtAccessToken;
+export const experimental_validateDetachedSignatureResponse = (...args) => validateDetachedSignatureResponse(...args);
+export const experimental_validateJwtAccessToken = (...args) => validateJwtAccessToken(...args);
+export const experimental_jwksCache = jwksCache;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth4webapi",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "OAuth 2 / OpenID Connect for JavaScript Runtimes",
   "keywords": [
     "access token",
@@ -67,29 +67,28 @@
   "devDependencies": {
     "@koa/cors": "^5.0.0",
     "@types/koa__cors": "^5.0.0",
-    "@types/node": "^20.14.5",
-    "@types/oidc-provider": "^8.4.4",
+    "@types/node": "^20.14.15",
     "@types/qunit": "^2.19.10",
     "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",
+    "edge-runtime": "^3.0.1",
+    "esbuild": "^0.23.1",
+    "jose": "^5.6.3",
+    "oidc-provider": "^8.5.1",
     "patch-package": "^8.0.0",
-    "prettier": "^3.3.2",
+    "prettier": "^3.3.3",
     "prettier-plugin-jsdoc": "^1.3.0",
-    "puppeteer-core": "^22.11.1",
-    "qunit": "^2.21.0",
-    "raw-body": "^2.5.2",
+    "puppeteer-core": "^23.1.0",
+    "qunit": "^2.21.1",
+    "raw-body": "^3.0.0",
     "selfsigned": "^2.4.1",
     "timekeeper": "^2.3.1",
-    "tsx": "^4.15.6",
-    "typedoc": "^0.25.13",
-    "typedoc-plugin-markdown": "^3.17.1",
-    "typedoc-plugin-mdn-links": "^3.1.30",
-    "typescript": "~5.4.5",
-    "undici": "^6.19.2"
+    "tsx": "^4.16.5",
+    "typedoc": "^0.26.6",
+    "typedoc-plugin-markdown": "^4.2.5",
+    "typedoc-plugin-mdn-links": "^3.2.9",
+    "typescript": "~5.5.4",
+    "undici": "^6.19.7"
   }
 }