oauth4webapi 2.8.0 → 2.9.0

package/README.md

@@ -44,7 +44,7 @@ import * as oauth2 from 'oauth4webapi'
 **`example`** Deno import
 
 ```js
-import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.8.0/mod.ts'
+import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.9.0/mod.ts'
 ```
 
 - Authorization Code Flow - OpenID Connect [source](examples/code.ts), or plain OAuth 2 [source](examples/oauth.ts)

package/build/index.d.ts

@@ -1,12 +1,20 @@
-/** JSON Object */
+/**
+ * JSON Object
+ */
 export type JsonObject = {
     [Key in string]?: JsonValue;
 };
-/** JSON Array */
+/**
+ * JSON Array
+ */
 export type JsonArray = JsonValue[];
-/** JSON Primitives */
+/**
+ * JSON Primitives
+ */
 export type JsonPrimitive = string | number | boolean | null;
-/** JSON Values */
+/**
+ * JSON Values
+ */
 export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 /**
  * Interface to pass an asymmetric private key and, optionally, its associated JWK Key ID to be
@@ -130,9 +138,6 @@ export type JWSAlgorithm = 'PS256' | 'ES256' | 'RS256' | 'EdDSA' | 'ES384' | 'PS
 export declare const clockSkew: unique symbol;
 export declare const clockTolerance: 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.
- *
  * 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
  * fetch replacement the arguments and expected return are the same as fetch.
@@ -169,7 +174,7 @@ export declare const clockTolerance: unique symbol;
  *
  * // example use
  * await oauth.discoveryRequest(new URL('https://as.example.com'), {
- *   [oauth.experimental_customFetch]: (...args) =>
+ *   [oauth.customFetch]: (...args) =>
  *     ky(args[0], {
  *       ...args[1],
  *       hooks: {
@@ -210,26 +215,19 @@ export declare const clockTolerance: unique symbol;
  *
  * // example use
  * await oauth.discoveryRequest(new URL('https://as.example.com'), {
- *   [oauth.experimental_customFetch]: undici.fetch,
+ *   [oauth.customFetch]: undici.fetch,
  * })
  * ```
- *
- * @group Experimental
  */
-export declare const experimental_customFetch: unique symbol;
-/** @ignore */
-export declare const experimentalCustomFetch: 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.
- *
- * When combined with {@link experimental_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 client authentication or sender constraining. FAPI 1.0 Advanced profiles
- * that use PAR and JARM can also be targetted.
+ * 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
+ * client authentication or sender constraining. FAPI 1.0 Advanced profiles that use PAR and JARM
+ * can also be targetted.
  *
- * When configured on an interface that extends {@link ExperimentalUseMTLSAliasOptions} this makes
- * the client prioritize an endpoint URL present in
+ * When configured on an interface that extends {@link UseMTLSAliasOptions} this makes the client
+ * prioritize an endpoint URL present in
  * {@link AuthorizationServer.mtls_endpoint_aliases `as.mtls_endpoint_aliases`}.
  *
  * @example
@@ -242,8 +240,8 @@ export declare const experimentalCustomFetch: symbol;
  * import * as oauth from 'oauth4webapi'
  *
  * const response = await oauth.pushedAuthorizationRequest(as, client, params, {
- *   [oauth.experimental_useMtlsAlias]: true,
- *   [oauth.experimental_customFetch]: (...args) => {
+ *   [oauth.useMtlsAlias]: true,
+ *   [oauth.customFetch]: (...args) => {
  *     return undici.fetch(args[0], {
  *       ...args[1],
  *       dispatcher: new undici.Agent({
@@ -272,8 +270,8 @@ export declare const experimentalCustomFetch: symbol;
  * })
  *
  * const response = await oauth.pushedAuthorizationRequest(as, client, params, {
- *   [oauth.experimental_useMtlsAlias]: true,
- *   [oauth.experimental_customFetch]: (...args) => {
+ *   [oauth.useMtlsAlias]: true,
+ *   [oauth.customFetch]: (...args) => {
  *     return fetch(args[0], {
  *       ...args[1],
  *       client: agent,
@@ -282,30 +280,38 @@ export declare const experimentalCustomFetch: symbol;
  * })
  * ```
  *
- * @group Experimental
- *
  * @see [RFC 8705 - OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html)
  */
-export declare const experimental_useMtlsAlias: unique symbol;
-/** @ignore */
-export declare const experimentalUseMtlsAlias: symbol;
+export declare const useMtlsAlias: unique symbol;
 /**
  * Authorization Server Metadata
  *
  * @see [IANA OAuth Authorization Server Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata)
  */
 export interface AuthorizationServer {
-    /** Authorization server's Issuer Identifier URL. */
+    /**
+     * Authorization server's Issuer Identifier URL.
+     */
     readonly issuer: string;
-    /** URL of the authorization server's authorization endpoint. */
+    /**
+     * URL of the authorization server's authorization endpoint.
+     */
     readonly authorization_endpoint?: string;
-    /** URL of the authorization server's token endpoint. */
+    /**
+     * URL of the authorization server's token endpoint.
+     */
     readonly token_endpoint?: string;
-    /** URL of the authorization server's JWK Set document. */
+    /**
+     * URL of the authorization server's JWK Set document.
+     */
     readonly jwks_uri?: string;
-    /** URL of the authorization server's Dynamic Client Registration Endpoint. */
+    /**
+     * URL of the authorization server's Dynamic Client Registration Endpoint.
+     */
     readonly registration_endpoint?: string;
-    /** JSON array containing a list of the `scope` values that this authorization server supports. */
+    /**
+     * JSON array containing a list of the `scope` values that this authorization server supports.
+     */
     readonly scopes_supported?: string[];
     /**
      * JSON array containing a list of the `response_type` values that this authorization server
@@ -322,7 +328,9 @@ export interface AuthorizationServer {
      * supports.
      */
     readonly grant_types_supported?: string[];
-    /** JSON array containing a list of client authentication methods supported by this token endpoint. */
+    /**
+     * JSON array containing a list of client authentication methods supported by this token endpoint.
+     */
     readonly token_endpoint_auth_methods_supported?: string[];
     /**
      * JSON array containing a list of the JWS signing algorithms supported by the token endpoint for
@@ -350,7 +358,9 @@ export interface AuthorizationServer {
      * the authorization server's terms of service.
      */
     readonly op_tos_uri?: string;
-    /** URL of the authorization server's revocation endpoint. */
+    /**
+     * URL of the authorization server's revocation endpoint.
+     */
     readonly revocation_endpoint?: string;
     /**
      * JSON array containing a list of client authentication methods supported by this revocation
@@ -362,7 +372,9 @@ export interface AuthorizationServer {
      * for the signature on the JWT used to authenticate the client at the revocation endpoint.
      */
     readonly revocation_endpoint_auth_signing_alg_values_supported?: string[];
-    /** URL of the authorization server's introspection endpoint. */
+    /**
+     * URL of the authorization server's introspection endpoint.
+     */
     readonly introspection_endpoint?: string;
     /**
      * JSON array containing a list of client authentication methods supported by this introspection
@@ -375,20 +387,30 @@ export interface AuthorizationServer {
      * endpoint.
      */
     readonly introspection_endpoint_auth_signing_alg_values_supported?: string[];
-    /** PKCE code challenge methods supported by this authorization server. */
+    /**
+     * PKCE code challenge methods supported by this authorization server.
+     */
     readonly code_challenge_methods_supported?: string[];
-    /** Signed JWT containing metadata values about the authorization server as claims. */
+    /**
+     * Signed JWT containing metadata values about the authorization server as claims.
+     */
     readonly signed_metadata?: string;
-    /** URL of the authorization server's device authorization endpoint. */
+    /**
+     * URL of the authorization server's device authorization endpoint.
+     */
     readonly device_authorization_endpoint?: string;
-    /** Indicates authorization server support for mutual-TLS client certificate-bound access tokens. */
+    /**
+     * Indicates authorization server support for mutual-TLS client certificate-bound access tokens.
+     */
     readonly tls_client_certificate_bound_access_tokens?: boolean;
     /**
      * JSON object containing alternative authorization server endpoints, which a client intending to
      * do mutual TLS will use in preference to the conventional endpoints.
      */
     readonly mtls_endpoint_aliases?: MTLSEndpointAliases;
-    /** URL of the authorization server's UserInfo Endpoint. */
+    /**
+     * URL of the authorization server's UserInfo Endpoint.
+     */
     readonly userinfo_endpoint?: string;
     /**
      * JSON array containing a list of the Authentication Context Class References that this
@@ -415,11 +437,17 @@ export interface AuthorizationServer {
      * the ID Token.
      */
     readonly id_token_encryption_enc_values_supported?: string[];
-    /** JSON array containing a list of the JWS `alg` values supported by the UserInfo Endpoint. */
+    /**
+     * JSON array containing a list of the JWS `alg` values supported by the UserInfo Endpoint.
+     */
     readonly userinfo_signing_alg_values_supported?: string[];
-    /** JSON array containing a list of the JWE `alg` values supported by the UserInfo Endpoint. */
+    /**
+     * JSON array containing a list of the JWE `alg` values supported by the UserInfo Endpoint.
+     */
     readonly userinfo_encryption_alg_values_supported?: string[];
-    /** JSON array containing a list of the JWE `enc` values supported by the UserInfo Endpoint. */
+    /**
+     * JSON array containing a list of the JWE `enc` values supported by the UserInfo Endpoint.
+     */
     readonly userinfo_encryption_enc_values_supported?: string[];
     /**
      * JSON array containing a list of the JWS `alg` values supported by the authorization server for
@@ -441,7 +469,9 @@ export interface AuthorizationServer {
      * supports.
      */
     readonly display_values_supported?: string[];
-    /** JSON array containing a list of the Claim Types that the authorization server supports. */
+    /**
+     * JSON array containing a list of the Claim Types that the authorization server supports.
+     */
     readonly claim_types_supported?: string[];
     /**
      * JSON array containing a list of the Claim Names of the Claims that the authorization server MAY
@@ -478,9 +508,13 @@ export interface AuthorizationServer {
      * through either `request` or `request_uri` parameter.
      */
     readonly require_signed_request_object?: boolean;
-    /** URL of the authorization server's pushed authorization request endpoint. */
+    /**
+     * URL of the authorization server's pushed authorization request endpoint.
+     */
     readonly pushed_authorization_request_endpoint?: string;
-    /** Indicates whether the authorization server accepts authorization requests only via PAR. */
+    /**
+     * Indicates whether the authorization server accepts authorization requests only via PAR.
+     */
     readonly require_pushed_authorization_requests?: boolean;
     /**
      * JSON array containing a list of algorithms supported by the authorization server for
@@ -517,23 +551,31 @@ export interface AuthorizationServer {
      * introspection response encryption (`enc` value).
      */
     readonly authorization_encryption_enc_values_supported?: string[];
-    /** CIBA Backchannel Authentication Endpoint. */
+    /**
+     * CIBA Backchannel Authentication Endpoint.
+     */
     readonly backchannel_authentication_endpoint?: string;
     /**
      * JSON array containing a list of the JWS signing algorithms supported for validation of signed
      * CIBA authentication requests.
      */
     readonly backchannel_authentication_request_signing_alg_values_supported?: string[];
-    /** Supported CIBA authentication result delivery modes. */
+    /**
+     * Supported CIBA authentication result delivery modes.
+     */
     readonly backchannel_token_delivery_modes_supported?: string[];
-    /** Indicates whether the authorization server supports the use of the CIBA `user_code` parameter. */
+    /**
+     * Indicates whether the authorization server supports the use of the CIBA `user_code` parameter.
+     */
     readonly backchannel_user_code_parameter_supported?: boolean;
     /**
      * URL of an authorization server iframe that supports cross-origin communications for session
      * state information with the RP Client, using the HTML5 postMessage API.
      */
     readonly check_session_iframe?: string;
-    /** JSON array containing a list of the JWS algorithms supported for DPoP proof JWTs. */
+    /**
+     * JSON array containing a list of the JWS algorithms supported for DPoP proof JWTs.
+     */
     readonly dpop_signing_alg_values_supported?: string[];
     /**
      * URL at the authorization server to which an RP can perform a redirect to request that the
@@ -546,14 +588,18 @@ export interface AuthorizationServer {
      * `frontchannel_logout_uri` is used.
      */
     readonly frontchannel_logout_session_supported?: boolean;
-    /** Boolean value specifying whether the authorization server supports HTTP-based logout. */
+    /**
+     * Boolean value specifying whether the authorization server supports HTTP-based logout.
+     */
     readonly frontchannel_logout_supported?: boolean;
     /**
      * Boolean value specifying whether the authorization server can pass a `sid` (session ID) Claim
      * in the Logout Token to identify the RP session with the OP.
      */
     readonly backchannel_logout_session_supported?: boolean;
-    /** Boolean value specifying whether the authorization server supports back-channel logout. */
+    /**
+     * Boolean value specifying whether the authorization server supports back-channel logout.
+     */
     readonly backchannel_logout_supported?: boolean;
     readonly [metadata: string]: JsonValue | undefined;
 }
@@ -566,9 +612,13 @@ export interface MTLSEndpointAliases extends Pick<AuthorizationServer, 'token_en
  * @see [IANA OAuth Client Registration Metadata registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#client-metadata)
  */
 export interface Client {
-    /** Client identifier. */
+    /**
+     * Client identifier.
+     */
     client_id: string;
-    /** Client secret. */
+    /**
+     * Client secret.
+     */
     client_secret?: string;
     /**
      * Client {@link ClientAuthenticationMethod authentication method} for the client's authenticated
@@ -608,7 +658,9 @@ export interface Client {
      * and fall back to `RS256` when the authorization server metadata is not set.
      */
     introspection_signed_response_alg?: string;
-    /** Default Maximum Authentication Age. */
+    /**
+     * Default Maximum Authentication Age.
+     */
     default_max_age?: number;
     /**
      * Use to adjust the client's assumed current time. Positive and negative finite values
@@ -658,11 +710,15 @@ export interface Client {
     [clockTolerance]?: number;
     [metadata: string]: JsonValue | undefined;
 }
-/** @group Errors */
+/**
+ * @group Errors
+ */
 export declare class UnsupportedOperationError extends Error {
     constructor(message?: string);
 }
-/** @group Errors */
+/**
+ * @group Errors
+ */
 export declare class OperationProcessingError extends Error {
     constructor(message: string, options?: {
         cause?: unknown;
@@ -682,20 +738,19 @@ 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;
     /**
-     * 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.
-     *
-     * See {@link experimental_customFetch} for its documentation.
-     *
-     * @group Experimental
+     * See {@link customFetch}.
      */
-    [experimental_customFetch]?: typeof fetch;
+    [customFetch]?: typeof fetch;
 }
 export interface DiscoveryRequestOptions extends HttpRequestOptions {
-    /** The issuer transformation algorithm to use. */
+    /**
+     * The issuer transformation algorithm to use.
+     */
     algorithm?: 'oidc' | 'oauth2';
 }
 /**
@@ -737,9 +792,9 @@ export declare function processDiscoveryResponse(expectedIssuerIdentifier: URL,
  * @group Utilities
  * @group Authorization Code Grant
  * @group Authorization Code Grant w/ OpenID Connect (OIDC)
- * @group Proof Key for Code Exchange by OAuth Public Clients (PKCE)
+ * @group Proof Key for Code Exchange (PKCE)
  *
- * @see [RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
+ * @see [RFC 7636 - Proof Key for Code Exchange (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
  */
 export declare function generateRandomCodeVerifier(): string;
 /**
@@ -766,9 +821,9 @@ export declare function generateRandomNonce(): string;
  *
  * @group Authorization Code Grant
  * @group Authorization Code Grant w/ OpenID Connect (OIDC)
- * @group Proof Key for Code Exchange by OAuth Public Clients (PKCE)
+ * @group Proof Key for Code Exchange (PKCE)
  *
- * @see [RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
+ * @see [RFC 7636 - Proof Key for Code Exchange (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
  */
 export declare function calculatePKCECodeChallenge(codeVerifier: string): Promise<string>;
 export interface DPoPOptions extends CryptoKeyPair {
@@ -778,7 +833,9 @@ export interface DPoPOptions extends CryptoKeyPair {
      * Its algorithm must be compatible with a supported {@link JWSAlgorithm JWS `alg` Algorithm}.
      */
     privateKey: CryptoKey;
-    /** The public key corresponding to {@link DPoPOptions.privateKey}. */
+    /**
+     * The public key corresponding to {@link DPoPOptions.privateKey}.
+     */
     publicKey: CryptoKey;
     /**
      * Server-Provided Nonce to use in the request. This option serves as an override in case the
@@ -788,21 +845,18 @@ export interface DPoPOptions extends CryptoKeyPair {
     nonce?: string;
 }
 export interface DPoPRequestOptions {
-    /** DPoP-related options. */
+    /**
+     * DPoP-related options.
+     */
     DPoP?: DPoPOptions;
 }
-export interface ExperimentalUseMTLSAliasOptions {
+export interface UseMTLSAliasOptions {
     /**
-     * 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.
-     *
-     * See {@link experimental_useMtlsAlias} for its documentation.
-     *
-     * @group Experimental
+     * See {@link useMtlsAlias}.
      */
-    [experimental_useMtlsAlias]?: boolean;
+    [useMtlsAlias]?: boolean;
 }
-export interface AuthenticatedRequestOptions extends ExperimentalUseMTLSAliasOptions {
+export interface AuthenticatedRequestOptions extends UseMTLSAliasOptions {
     /**
      * Private key to use for `private_key_jwt`
      * {@link ClientAuthenticationMethod client authentication}. Its algorithm must be compatible with
@@ -874,11 +928,15 @@ export interface WWWAuthenticateChallengeParameters {
     readonly error_uri?: string;
     readonly algs?: string;
     readonly scope?: string;
-    /** NOTE: because the parameter names are case insensitive they are always returned lowercased */
+    /**
+     * NOTE: because the parameter names are case insensitive they are always returned lowercased
+     */
     readonly [parameter: Lowercase<string>]: string | undefined;
 }
 export interface WWWAuthenticateChallenge {
-    /** NOTE: because the value is case insensitive it is always returned lowercased */
+    /**
+     * NOTE: because the value is case insensitive it is always returned lowercased
+     */
     readonly scheme: Lowercase<string>;
     readonly parameters: WWWAuthenticateChallengeParameters;
 }
@@ -944,7 +1002,7 @@ export interface ProtectedResourceRequestOptions extends Omit<HttpRequestOptions
  * @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 interface UserInfoRequestOptions extends HttpRequestOptions, DPoPRequestOptions, ExperimentalUseMTLSAliasOptions {
+export interface UserInfoRequestOptions extends HttpRequestOptions, DPoPRequestOptions, UseMTLSAliasOptions {
 }
 /**
  * Performs a UserInfo Request at the
@@ -1025,7 +1083,9 @@ export declare const skipSubjectCheck: unique symbol;
  */
 export declare function processUserInfoResponse(as: AuthorizationServer, client: Client, expectedSubject: string | typeof skipSubjectCheck, response: Response): Promise<UserInfoResponse>;
 export interface TokenEndpointRequestOptions extends HttpRequestOptions, AuthenticatedRequestOptions, DPoPRequestOptions {
-    /** Any additional parameters to send. This cannot override existing parameter values. */
+    /**
+     * Any additional parameters to send. This cannot override existing parameter values.
+     */
     additionalParameters?: URLSearchParams | Record<string, string> | string[][];
 }
 /**
@@ -1097,7 +1157,7 @@ export declare function processRefreshTokenResponse(as: AuthorizationServer, cli
  *
  * @see [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1)
  * @see [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
- * @see [RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
+ * @see [RFC 7636 - Proof Key for Code Exchange (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html#section-4)
  * @see [RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP)](https://www.rfc-editor.org/rfc/rfc9449.html#name-dpop-access-token-request)
  */
 export declare function authorizationCodeGrantRequest(as: AuthorizationServer, client: Client, callbackParameters: URLSearchParams, redirectUri: string, codeVerifier: string, options?: TokenEndpointRequestOptions): Promise<Response>;
@@ -1129,7 +1189,9 @@ export interface TokenEndpointResponse {
     readonly id_token?: string;
     readonly refresh_token?: string;
     readonly scope?: string;
-    /** NOTE: because the value is case insensitive it is always returned lowercased */
+    /**
+     * NOTE: because the value is case insensitive it is always returned lowercased
+     */
     readonly token_type: 'bearer' | 'dpop' | Lowercase<string>;
     readonly [parameter: string]: JsonValue | undefined;
 }
@@ -1139,7 +1201,9 @@ export interface OpenIDTokenEndpointResponse {
     readonly id_token: string;
     readonly refresh_token?: string;
     readonly scope?: string;
-    /** NOTE: because the value is case insensitive it is always returned lowercased */
+    /**
+     * NOTE: because the value is case insensitive it is always returned lowercased
+     */
     readonly token_type: 'bearer' | 'dpop' | Lowercase<string>;
     readonly [parameter: string]: JsonValue | undefined;
 }
@@ -1149,7 +1213,9 @@ export interface OAuth2TokenEndpointResponse {
     readonly id_token?: undefined;
     readonly refresh_token?: string;
     readonly scope?: string;
-    /** NOTE: because the value is case insensitive it is always returned lowercased */
+    /**
+     * NOTE: because the value is case insensitive it is always returned lowercased
+     */
     readonly token_type: 'bearer' | 'dpop' | Lowercase<string>;
     readonly [parameter: string]: JsonValue | undefined;
 }
@@ -1157,7 +1223,9 @@ export interface ClientCredentialsGrantResponse {
     readonly access_token: string;
     readonly expires_in?: number;
     readonly scope?: string;
-    /** NOTE: because the value is case insensitive it is always returned lowercased */
+    /**
+     * NOTE: because the value is case insensitive it is always returned lowercased
+     */
     readonly token_type: 'bearer' | 'dpop' | Lowercase<string>;
     readonly [parameter: string]: JsonValue | undefined;
 }
@@ -1246,7 +1314,9 @@ export declare function clientCredentialsGrantRequest(as: AuthorizationServer, c
  */
 export declare function processClientCredentialsResponse(as: AuthorizationServer, client: Client, response: Response): Promise<ClientCredentialsGrantResponse | OAuth2Error>;
 export interface RevocationRequestOptions extends HttpRequestOptions, AuthenticatedRequestOptions {
-    /** Any additional parameters to send. This cannot override existing parameter values. */
+    /**
+     * Any additional parameters to send. This cannot override existing parameter values.
+     */
     additionalParameters?: URLSearchParams | Record<string, string> | string[][];
 }
 /**
@@ -1278,7 +1348,9 @@ export declare function revocationRequest(as: AuthorizationServer, client: Clien
  */
 export declare function processRevocationResponse(response: Response): Promise<undefined | OAuth2Error>;
 export interface IntrospectionRequestOptions extends HttpRequestOptions, AuthenticatedRequestOptions {
-    /** Any additional parameters to send. This cannot override existing parameter values. */
+    /**
+     * Any additional parameters to send. This cannot override existing parameter values.
+     */
     additionalParameters?: URLSearchParams | Record<string, string> | string[][];
     /**
      * Request a JWT Response from the
@@ -1311,8 +1383,6 @@ export interface ConfirmationClaims {
     readonly jkt?: string;
     readonly [claim: string]: JsonValue | undefined;
 }
-/** @ignore */
-export type IntrospectionConfirmationClaims = ConfirmationClaims;
 export interface IntrospectionResponse {
     readonly active: boolean;
     readonly client_id?: string;
@@ -1366,9 +1436,6 @@ export declare function processIntrospectionResponse(as: AuthorizationServer, cl
  */
 export declare function validateJwtAuthResponse(as: AuthorizationServer, client: Client, parameters: URLSearchParams | URL, expectedState?: string | typeof expectNoState | typeof skipStateCheck, options?: HttpRequestOptions): Promise<URLSearchParams | OAuth2Error>;
 /**
- * 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.
- *
  * Same as {@link validateAuthResponse} but for FAPI 1.0 Advanced Detached Signature authorization
  * responses.
  *
@@ -1387,11 +1454,10 @@ export declare function validateJwtAuthResponse(as: AuthorizationServer, client:
  * @returns Validated Authorization Response parameters or Authorization Error Response.
  *
  * @group FAPI 1.0 Advanced
- * @group Experimental
  *
  * @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 experimental_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?: HttpRequestOptions): Promise<URLSearchParams | OAuth2Error>;
 /**
  * DANGER ZONE
  *
@@ -1501,11 +1567,17 @@ export declare function deviceCodeGrantRequest(as: AuthorizationServer, client:
  */
 export declare function processDeviceCodeResponse(as: AuthorizationServer, client: Client, response: Response): Promise<TokenEndpointResponse | OAuth2Error>;
 export interface GenerateKeyPairOptions {
-    /** Indicates whether or not the private key may be exported. Default is `false`. */
+    /**
+     * Indicates whether or not the private key may be exported. Default is `false`.
+     */
     extractable?: boolean;
-    /** (RSA algorithms only) The length, in bits, of the RSA modulus. Default is `2048`. */
+    /**
+     * (RSA algorithms only) The length, in bits, of the RSA modulus. Default is `2048`.
+     */
     modulusLength?: number;
-    /** (EdDSA algorithms only) The EdDSA sub-type. Default is `Ed25519`. */
+    /**
+     * (EdDSA algorithms only) The EdDSA sub-type. Default is `Ed25519`.
+     */
     crv?: 'Ed25519' | 'Ed448';
 }
 /**
@@ -1527,17 +1599,20 @@ export interface JWTAccessTokenClaims extends JWTPayload {
     readonly [claim: string]: JsonValue | undefined;
 }
 export interface ValidateJWTAccessTokenOptions extends HttpRequestOptions {
-    /** Indicates whether DPoP use is required. */
+    /**
+     * Indicates whether DPoP use is required.
+     */
     requireDPoP?: boolean;
-    /** Same functionality as in {@link Client} */
+    /**
+     * Same functionality as in {@link Client}
+     */
     [clockSkew]?: number;
-    /** Same functionality as in {@link Client} */
+    /**
+     * Same functionality as in {@link Client}
+     */
     [clockTolerance]?: number;
 }
 /**
- * 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.
- *
  * 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.
  *
@@ -1562,10 +1637,57 @@ export interface ValidateJWTAccessTokenOptions extends HttpRequestOptions {
  * @param options
  *
  * @group JWT Access Tokens
- * @group Experimental
  *
  * @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)
  */
-export declare function experimental_validateJwtAccessToken(as: AuthorizationServer, request: Request, expectedAudience: string, options?: ValidateJWTAccessTokenOptions): Promise<JWTAccessTokenClaims>;
+export declare function validateJwtAccessToken(as: AuthorizationServer, request: Request, expectedAudience: string, options?: ValidateJWTAccessTokenOptions): Promise<JWTAccessTokenClaims>;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link customFetch}.
+ */
+export declare const experimentalCustomFetch: symbol;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link customFetch}.
+ */
+export declare const experimental_customFetch: symbol;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link useMtlsAlias}.
+ */
+export declare const experimentalUseMtlsAlias: symbol;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link useMtlsAlias}.
+ */
+export declare const experimental_useMtlsAlias: symbol;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link UseMTLSAliasOptions}.
+ */
+export type ExperimentalUseMTLSAliasOptions = UseMTLSAliasOptions;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link ConfirmationClaims}.
+ */
+export type IntrospectionConfirmationClaims = ConfirmationClaims;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link validateDetachedSignatureResponse}.
+ */
+export declare const experimental_validateDetachedSignatureResponse: typeof validateDetachedSignatureResponse;
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link validateJwtAccessToken}.
+ */
+export declare const experimental_validateJwtAccessToken: typeof validateJwtAccessToken;
 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.8.0';
+    const VERSION = 'v2.9.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
 function looseInstanceOf(input, expected) {
@@ -18,10 +18,8 @@ function looseInstanceOf(input, expected) {
 }
 export const clockSkew = Symbol();
 export const clockTolerance = Symbol();
-export const experimental_customFetch = Symbol();
-export const experimentalCustomFetch = experimental_customFetch;
-export const experimental_useMtlsAlias = Symbol();
-export const experimentalUseMtlsAlias = experimental_useMtlsAlias;
+export const customFetch = Symbol();
+export const useMtlsAlias = Symbol();
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 function buf(input) {
@@ -214,7 +212,7 @@ export async function discoveryRequest(issuerIdentifier, options) {
     }
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
-    return (options?.[experimental_customFetch] || fetch)(url.href, {
+    return (options?.[customFetch] || fetch)(url.href, {
         headers: Object.fromEntries(headers.entries()),
         method: 'GET',
         redirect: 'manual',
@@ -554,7 +552,7 @@ async function publicJwk(key) {
 }
 function validateEndpoint(value, endpoint, options) {
     if (typeof value !== 'string') {
-        if (options?.[experimental_useMtlsAlias]) {
+        if (options?.[useMtlsAlias]) {
             throw new TypeError(`"as.mtls_endpoint_aliases.${endpoint}" must be a string`);
         }
         else {
@@ -564,9 +562,7 @@ function validateEndpoint(value, endpoint, options) {
     return new URL(value);
 }
 function resolveEndpoint(as, endpoint, options) {
-    if (options?.[experimental_useMtlsAlias] &&
-        as.mtls_endpoint_aliases &&
-        endpoint in as.mtls_endpoint_aliases) {
+    if (options?.[useMtlsAlias] && as.mtls_endpoint_aliases && endpoint in as.mtls_endpoint_aliases) {
         return validateEndpoint(as.mtls_endpoint_aliases[endpoint], endpoint, options);
     }
     return validateEndpoint(as[endpoint], endpoint);
@@ -696,7 +692,7 @@ export async function protectedResourceRequest(accessToken, method, url, headers
         await dpopProofJwt(headers, options.DPoP, url, 'GET', getClockSkew({ [clockSkew]: options?.[clockSkew] }), accessToken);
         headers.set('authorization', `DPoP ${accessToken}`);
     }
-    return (options?.[experimental_customFetch] || fetch)(url.href, {
+    return (options?.[customFetch] || fetch)(url.href, {
         body,
         headers: Object.fromEntries(headers.entries()),
         method,
@@ -859,7 +855,7 @@ export async function processUserInfoResponse(as, client, expectedSubject, respo
 async function authenticatedRequest(as, client, method, url, body, headers, options) {
     await clientAuthentication(as, client, body, headers, options?.clientPrivateKey);
     headers.set('content-type', 'application/x-www-form-urlencoded;charset=UTF-8');
-    return (options?.[experimental_customFetch] || fetch)(url.href, {
+    return (options?.[customFetch] || fetch)(url.href, {
         body,
         headers: Object.fromEntries(headers.entries()),
         method,
@@ -1222,7 +1218,7 @@ async function jwksRequest(as, options) {
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
     headers.append('accept', 'application/jwk-set+json');
-    return (options?.[experimental_customFetch] || fetch)(url.href, {
+    return (options?.[customFetch] || fetch)(url.href, {
         headers: Object.fromEntries(headers.entries()),
         method: 'GET',
         redirect: 'manual',
@@ -1472,7 +1468,7 @@ async function idTokenHashMatches(data, actual, alg, key) {
     const expected = await idTokenHash(alg, data, key);
     return actual === expected;
 }
-export async function experimental_validateDetachedSignatureResponse(as, client, parameters, expectedNonce, expectedState, maxAge, options) {
+export async function validateDetachedSignatureResponse(as, client, parameters, expectedNonce, expectedState, maxAge, options) {
     assertAs(as);
     assertClient(client);
     if (parameters instanceof URL) {
@@ -1785,6 +1781,7 @@ async function validateDPoP(as, request, accessTokenClaims, options) {
     if (typeof accessTokenClaims.cnf?.jkt !== 'string') {
         throw new OPE('operation indicated DPoP use but the JWT Access Token has no jkt confirmation claim');
     }
+    const clockSkew = getClockSkew(options);
     const proof = await validateJwt(request.headers.get('dpop'), checkSigningAlgorithm.bind(undefined, undefined, as?.dpop_signing_alg_values_supported || SUPPORTED_JWS_ALGS), async ({ jwk, alg }) => {
         if (!jwk) {
             throw new OPE('DPoP Proof is missing the jwk header parameter');
@@ -1794,9 +1791,14 @@ async function validateDPoP(as, request, accessTokenClaims, options) {
             throw new OPE('DPoP Proof jwk header parameter must contain a public key');
         }
         return key;
-    }, getClockSkew(options), getClockTolerance(options))
+    }, clockSkew, getClockTolerance(options))
         .then(checkJwtType.bind(undefined, 'dpop+jwt'))
         .then(validatePresence.bind(undefined, ['iat', 'jti', 'ath', 'htm', 'htu']));
+    const now = epochTime() + clockSkew;
+    const diff = Math.abs(now - proof.claims.iat);
+    if (diff > 300) {
+        throw new OPE('DPoP Proof iat is not recent enough');
+    }
     if (proof.claims.htm !== request.method) {
         throw new OPE('DPoP Proof htm mismatch');
     }
@@ -1845,7 +1847,7 @@ async function validateDPoP(as, request, accessTokenClaims, options) {
         }
     }
 }
-export async function experimental_validateJwtAccessToken(as, request, expectedAudience, options) {
+export async function validateJwtAccessToken(as, request, expectedAudience, options) {
     assertAs(as);
     if (!looseInstanceOf(request, Request)) {
         throw new TypeError('"request" must be an instance of Request');
@@ -1913,3 +1915,9 @@ export async function experimental_validateJwtAccessToken(as, request, expectedA
     }
     return claims;
 }
+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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth4webapi",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "OAuth 2 / OpenID Connect for JavaScript Runtimes",
   "keywords": [
     "access token",
@@ -67,20 +67,20 @@
   "devDependencies": {
     "@koa/cors": "^5.0.0",
     "@types/koa__cors": "^5.0.0",
-    "@types/node": "^20.11.5",
+    "@types/node": "^20.11.15",
     "@types/oidc-provider": "^8.4.3",
     "@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.19.11",
+    "esbuild": "^0.20.0",
     "jose": "^5.2.0",
     "oidc-provider": "^8.4.5",
     "patch-package": "^8.0.0",
     "prettier": "^3.2.4",
     "prettier-plugin-jsdoc": "^1.3.0",
-    "puppeteer-core": "^21.7.0",
+    "puppeteer-core": "^21.10.0",
     "qunit": "^2.20.0",
     "raw-body": "^2.5.2",
     "selfsigned": "^2.4.1",
@@ -88,7 +88,7 @@
     "tsx": "^4.7.0",
     "typedoc": "^0.25.7",
     "typedoc-plugin-markdown": "^3.17.1",
-    "typedoc-plugin-mdn-links": "^3.1.13",
+    "typedoc-plugin-mdn-links": "^3.1.14",
     "typescript": "^5.3.3",
     "undici": "^5.28.2"
   }