oauth4webapi 2.4.5 → 2.6.0

package/README.md

@@ -43,7 +43,7 @@ import * as oauth2 from 'oauth4webapi'
 **`example`** Deno import
 
 ```js
-import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.4.5/mod.ts'
+import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.6.0/mod.ts'
 ```
 
 - Authorization Code Flow - OpenID Connect [source](examples/code.ts), or plain OAuth 2 [source](examples/oauth.ts)
@@ -53,7 +53,8 @@ import * as oauth2 from 'https://deno.land/x/oauth4webapi@v2.4.5/mod.ts'
 - Pushed Authorization Request (PAR) - [source](examples/par.ts) | [diff from code flow](examples/par.diff)
 - Client Credentials Grant - [source](examples/client_credentials.ts)
 - Device Authorization Grant - [source](examples/device_authorization_grant.ts)
-- FAPI 2.0 (Private Key JWT, PAR, DPoP) - [source](examples/fapi2.ts)
+- FAPI 1.0 Advanced (Private Key JWT, MTLS, JAR) - [source](examples/fapi1-advanced.ts)
+- FAPI 2.0 Security Profile (Private Key JWT, PAR, DPoP) - [source](examples/fapi2.ts)
 - FAPI 2.0 Message Signing (Private Key JWT, PAR, DPoP, JAR, JARM) - [source](examples/fapi2-message-signing.ts) | [diff](examples/fapi2-message-signing.diff)
 
 ## Supported Runtimes
@@ -74,6 +75,5 @@ The following features are currently out of scope:
 
 - CommonJS
 - Implicit, Hybrid, and Resource Owner Password Credentials Flows
-- Mutual-TLS Client Authentication and Certificate-Bound Access Tokens
 - JSON Web Encryption (JWE)
 - Automatic polyfills of any kind

package/build/index.d.ts

@@ -129,6 +129,166 @@ export type ClientAuthenticationMethod = 'client_secret_basic' | 'client_secret_
 export type JWSAlgorithm = 'PS256' | 'ES256' | 'RS256' | 'EdDSA' | 'ES384' | 'PS384' | 'RS384' | 'ES512' | 'PS512' | 'RS512';
 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.
+ *
+ * In theory any module that claims to be compatible with the Fetch API can be used but your mileage
+ * may vary. No workarounds to allow use of non-conform {@link Response}s will be considered.
+ *
+ * If you only need to update the {@link Request} properties you do not need to use a Fetch API
+ * module, just change what you need and pass it to globalThis.fetch just like this module would
+ * normally do.
+ *
+ * Its intended use cases are:
+ *
+ * - {@link Request}/{@link Response} tracing and logging
+ * - Custom caching strategies for responses of Authorization Server Metadata and JSON Web Key Set
+ *   (JWKS) endpoints
+ * - Changing the {@link Request} properties like headers, body, credentials, mode before it is passed
+ *   to fetch
+ *
+ * Known caveats:
+ *
+ * - Expect Type-related issues when passing the inputs through to fetch-like modules, they hardly
+ *   ever get their typings inline with actual fetch, you should `@ts-expect-error` them.
+ * - Returning self-constructed {@link Response} instances prohibits AS-signalled DPoP Nonce caching.
+ *
+ * @example
+ *
+ * Using [sindresorhus/ky](https://github.com/sindresorhus/ky) hooks feature for logging outgoing
+ * requests and their responses.
+ *
+ * ```js
+ * import ky from 'ky'
+ * import * as oauth from 'oauth4webapi'
+ *
+ * // example use
+ * await oauth.discoveryRequest(new URL('https://as.example.com'), {
+ *   [oauth.experimental_customFetch]: (...args) =>
+ *     ky(args[0], {
+ *       ...args[1],
+ *       hooks: {
+ *         beforeRequest: [
+ *           (request) => {
+ *             logRequest(request)
+ *           },
+ *         ],
+ *         beforeRetry: [
+ *           ({ request, error, retryCount }) => {
+ *             logRetry(request, error, retryCount)
+ *           },
+ *         ],
+ *         afterResponse: [
+ *           (request, _, response) => {
+ *             logResponse(request, response)
+ *           },
+ *         ],
+ *       },
+ *     }),
+ * })
+ * ```
+ *
+ * @example
+ *
+ * Using [nodejs/undici](https://github.com/nodejs/undici) for mocking.
+ *
+ * ```js
+ * import * as undici from 'undici'
+ * import * as oauth from 'oauth4webapi'
+ *
+ * const mockAgent = new undici.MockAgent()
+ * mockAgent.disableNetConnect()
+ * undici.setGlobalDispatcher(mockAgent)
+ *
+ * // continue as per undici documentation
+ * // https://github.com/nodejs/undici/blob/v6.2.1/docs/api/MockAgent.md#example---basic-mocked-request
+ *
+ * // example use
+ * await oauth.discoveryRequest(new URL('https://as.example.com'), {
+ *   [oauth.experimental_customFetch]: undici.fetch,
+ * })
+ * ```
+ *
+ * @group Experimental
+ */
+export declare const experimental_customFetch: unique symbol;
+/** @ignore */
+export declare const experimentalCustomFetch: 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 configured on an interface that extends {@link ExperimentalUseMTLSAliasOptions} this makes
+ * the client prioritize an endpoint URL present in
+ * {@link AuthorizationServer.mtls_endpoint_aliases `as.mtls_endpoint_aliases`}.
+ *
+ * @example
+ *
+ * (Node.js) Using [nodejs/undici](https://github.com/nodejs/undici) for Mutual-TLS Client
+ * Authentication and Certificate-Bound Access Tokens support.
+ *
+ * ```js
+ * import * as undici from 'undici'
+ * import * as oauth from 'oauth4webapi'
+ *
+ * const response = await oauth.pushedAuthorizationRequest(as, client, params, {
+ *   [oauth.experimental_useMtlsAlias]: true,
+ *   [oauth.experimental_customFetch]: (...args) => {
+ *     return undici.fetch(args[0], {
+ *       ...args[1],
+ *       dispatcher: new undici.Agent({
+ *         connect: {
+ *           key: clientKey,
+ *           cert: clientCertificate,
+ *         },
+ *       }),
+ *     })
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ *
+ * (Deno) Using Deno.createHttpClient API for Mutual-TLS Client Authentication and Certificate-Bound
+ * Access Tokens support. This is currently (Jan 2023) locked behind the --unstable command line
+ * flag.
+ *
+ * ```js
+ * import * as oauth from 'oauth4webapi'
+ *
+ * const agent = Deno.createHttpClient({
+ *   certChain: clientCertificate,
+ *   privateKey: clientKey,
+ * })
+ *
+ * const response = await oauth.pushedAuthorizationRequest(as, client, params, {
+ *   [oauth.experimental_useMtlsAlias]: true,
+ *   [oauth.experimental_customFetch]: (...args) => {
+ *     return fetch(args[0], {
+ *       ...args[1],
+ *       client: agent,
+ *     })
+ *   },
+ * })
+ * ```
+ *
+ * @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;
 /**
  * Authorization Server Metadata
  *
@@ -522,11 +682,17 @@ export interface HttpRequestOptions {
      * ```
      */
     signal?: (() => AbortSignal) | AbortSignal;
+    /** Headers to additionally send with the HTTP Request(s) triggered by this function's invocation. */
+    headers?: [string, string][] | Record<string, string> | Headers;
     /**
-     * A Headers instance to additionally send with the HTTP Request(s) triggered by this function's
-     * invocation.
+     * 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
      */
-    headers?: Headers;
+    [experimental_customFetch]?: typeof fetch;
 }
 export interface DiscoveryRequestOptions extends HttpRequestOptions {
     /** The issuer transformation algorithm to use. */
@@ -625,7 +791,18 @@ export interface DPoPRequestOptions {
     /** DPoP-related options. */
     DPoP?: DPoPOptions;
 }
-export interface AuthenticatedRequestOptions {
+export interface ExperimentalUseMTLSAliasOptions {
+    /**
+     * 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
+     */
+    [experimental_useMtlsAlias]?: boolean;
+}
+export interface AuthenticatedRequestOptions extends ExperimentalUseMTLSAliasOptions {
     /**
      * Private key to use for `private_key_jwt`
      * {@link ClientAuthenticationMethod client authentication}. Its algorithm must be compatible with
@@ -767,7 +944,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 {
+export interface UserInfoRequestOptions extends HttpRequestOptions, DPoPRequestOptions, ExperimentalUseMTLSAliasOptions {
 }
 /**
  * Performs a UserInfo Request at the
@@ -1184,6 +1361,32 @@ 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>;
+/**
+ * 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.
+ *
+ * @param as Authorization Server Metadata.
+ * @param client Client Metadata.
+ * @param parameters Authorization Response.
+ * @param expectedNonce Expected ID Token `nonce` claim value.
+ * @param expectedState Expected `state` parameter value. Default is {@link expectNoState}.
+ * @param maxAge ID Token {@link IDToken.auth_time `auth_time`} claim value will be checked to be
+ *   present and conform to the `maxAge` value. Use of this option is required if you sent a
+ *   `max_age` parameter in an authorization request. Default is
+ *   {@link Client.default_max_age `client.default_max_age`} and falls back to
+ *   {@link skipAuthTimeCheck}.
+ *
+ * @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, expectedNonce: string, expectedState?: string | typeof expectNoState, maxAge?: number | typeof skipAuthTimeCheck, options?: HttpRequestOptions): Promise<URLSearchParams | OAuth2Error>;
 /**
  * DANGER ZONE
  *

package/build/index.js

@@ -1,11 +1,27 @@
 let USER_AGENT;
 if (typeof navigator === 'undefined' || !navigator.userAgent?.startsWith?.('Mozilla/5.0 ')) {
     const NAME = 'oauth4webapi';
-    const VERSION = 'v2.4.5';
+    const VERSION = 'v2.6.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
+function looseInstanceOf(input, expected) {
+    if (input == null) {
+        return false;
+    }
+    try {
+        return (input instanceof expected ||
+            Object.getPrototypeOf(input)[Symbol.toStringTag] === expected.prototype[Symbol.toStringTag]);
+    }
+    catch {
+        return false;
+    }
+}
 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;
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 function buf(input) {
@@ -148,8 +164,8 @@ function isJsonObject(input) {
     return true;
 }
 function prepareHeaders(input) {
-    if (input !== undefined && !(input instanceof Headers)) {
-        throw new TypeError('"options.headers" must be an instance of Headers');
+    if (looseInstanceOf(input, Headers)) {
+        input = Object.fromEntries(input.entries());
     }
     const headers = new Headers(input);
     if (USER_AGENT && !headers.has('user-agent')) {
@@ -198,13 +214,12 @@ export async function discoveryRequest(issuerIdentifier, options) {
     }
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
-    const request = new Request(url.href, {
-        headers,
+    return (options?.[experimental_customFetch] || fetch)(url.href, {
+        headers: Object.fromEntries(headers.entries()),
         method: 'GET',
         redirect: 'manual',
         signal: options?.signal ? signal(options.signal) : null,
-    });
-    return fetch(request).then(processDpopNonce);
+    }).then(processDpopNonce);
 }
 function validateString(input) {
     return typeof input === 'string' && input.length !== 0;
@@ -213,7 +228,7 @@ export async function processDiscoveryResponse(expectedIssuerIdentifier, respons
     if (!(expectedIssuerIdentifier instanceof URL)) {
         throw new TypeError('"expectedIssuer" must be an instance of URL');
     }
-    if (!(response instanceof Response)) {
+    if (!looseInstanceOf(response, Response)) {
         throw new TypeError('"response" must be an instance of Response');
     }
     if (response.status !== 200) {
@@ -427,9 +442,11 @@ async function clientAuthentication(as, client, body, headers, clientPrivateKey)
             body.set('client_assertion', await privateKeyJwt(as, client, key, kid));
             break;
         }
+        case 'tls_client_auth':
+        case 'self_signed_tls_client_auth':
         case 'none': {
-            assertNoClientSecret('none', client.client_secret);
-            assertNoClientPrivateKey('none', clientPrivateKey);
+            assertNoClientSecret(client.token_endpoint_auth_method, client.client_secret);
+            assertNoClientPrivateKey(client.token_endpoint_auth_method, clientPrivateKey);
             body.set('client_id', client.client_id);
             break;
         }
@@ -531,13 +548,29 @@ async function publicJwk(key) {
     jwkCache.set(key, jwk);
     return jwk;
 }
+function validateEndpoint(value, endpoint, options) {
+    if (typeof value !== 'string') {
+        if (options?.[experimental_useMtlsAlias]) {
+            throw new TypeError(`"as.mtls_endpoint_aliases.${endpoint}" must be a string`);
+        }
+        else {
+            throw new TypeError(`"as.${endpoint}" must be a string`);
+        }
+    }
+    return new URL(value);
+}
+function resolveEndpoint(as, endpoint, options) {
+    if (options?.[experimental_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);
+}
 export async function pushedAuthorizationRequest(as, client, parameters, options) {
     assertAs(as);
     assertClient(client);
-    if (typeof as.pushed_authorization_request_endpoint !== 'string') {
-        throw new TypeError('"as.pushed_authorization_request_endpoint" must be a string');
-    }
-    const url = new URL(as.pushed_authorization_request_endpoint);
+    const url = resolveEndpoint(as, 'pushed_authorization_request_endpoint', options);
     const body = new URLSearchParams(parameters);
     body.set('client_id', client.client_id);
     const headers = prepareHeaders(options?.headers);
@@ -585,7 +618,7 @@ function wwwAuth(scheme, params) {
     };
 }
 export function parseWwwAuthenticateChallenges(response) {
-    if (!(response instanceof Response)) {
+    if (!looseInstanceOf(response, Response)) {
         throw new TypeError('"response" must be an instance of Response');
     }
     if (!response.headers.has('www-authenticate')) {
@@ -615,7 +648,7 @@ export function parseWwwAuthenticateChallenges(response) {
 export async function processPushedAuthorizationResponse(as, client, response) {
     assertAs(as);
     assertClient(client);
-    if (!(response instanceof Response)) {
+    if (!looseInstanceOf(response, Response)) {
         throw new TypeError('"response" must be an instance of Response');
     }
     if (response.status !== 201) {
@@ -659,22 +692,18 @@ 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}`);
     }
-    const request = new Request(url.href, {
+    return (options?.[experimental_customFetch] || fetch)(url.href, {
         body,
-        headers,
+        headers: Object.fromEntries(headers.entries()),
         method,
         redirect: 'manual',
         signal: options?.signal ? signal(options.signal) : null,
-    });
-    return fetch(request).then(processDpopNonce);
+    }).then(processDpopNonce);
 }
 export async function userInfoRequest(as, client, accessToken, options) {
     assertAs(as);
     assertClient(client);
-    if (typeof as.userinfo_endpoint !== 'string') {
-        throw new TypeError('"as.userinfo_endpoint" must be a string');
-    }
-    const url = new URL(as.userinfo_endpoint);
+    const url = resolveEndpoint(as, 'userinfo_endpoint', options);
     const headers = prepareHeaders(options?.headers);
     if (client.userinfo_signed_response_alg) {
         headers.set('accept', 'application/jwt');
@@ -778,7 +807,7 @@ function getContentType(response) {
 export async function processUserInfoResponse(as, client, expectedSubject, response) {
     assertAs(as);
     assertClient(client);
-    if (!(response instanceof Response)) {
+    if (!looseInstanceOf(response, Response)) {
         throw new TypeError('"response" must be an instance of Response');
     }
     if (response.status !== 200) {
@@ -826,20 +855,16 @@ 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');
-    const request = new Request(url.href, {
+    return (options?.[experimental_customFetch] || fetch)(url.href, {
         body,
-        headers,
+        headers: Object.fromEntries(headers.entries()),
         method,
         redirect: 'manual',
         signal: options?.signal ? signal(options.signal) : null,
-    });
-    return fetch(request).then(processDpopNonce);
+    }).then(processDpopNonce);
 }
 async function tokenEndpointRequest(as, client, grantType, parameters, options) {
-    if (typeof as.token_endpoint !== 'string') {
-        throw new TypeError('"as.token_endpoint" must be a string');
-    }
-    const url = new URL(as.token_endpoint);
+    const url = resolveEndpoint(as, 'token_endpoint', options);
     parameters.set('grant_type', grantType);
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
@@ -872,7 +897,7 @@ export function getValidatedIdTokenClaims(ref) {
 async function processGenericAccessTokenResponse(as, client, response, ignoreIdToken = false, ignoreRefreshToken = false) {
     assertAs(as);
     assertClient(client);
-    if (!(response instanceof Response)) {
+    if (!looseInstanceOf(response, Response)) {
         throw new TypeError('"response" must be an instance of Response');
     }
     if (response.status !== 200) {
@@ -994,17 +1019,20 @@ export async function authorizationCodeGrantRequest(as, client, callbackParamete
     parameters.set('code', code);
     return tokenEndpointRequest(as, client, 'authorization_code', parameters, options);
 }
-const claimNames = {
+const idTokenClaimNames = {
     aud: 'audience',
     exp: 'expiration time',
     iat: 'issued at',
     iss: 'issuer',
     sub: 'subject',
+    nonce: 'nonce',
+    s_hash: 'state hash',
+    c_hash: 'code hash',
 };
 function validatePresence(required, result) {
     for (const claim of required) {
         if (result.claims[claim] === undefined) {
-            throw new OPE(`JWT "${claim}" (${claimNames[claim]}) claim missing`);
+            throw new OPE(`JWT "${claim}" (${idTokenClaimNames[claim]}) claim missing`);
         }
     }
     return result;
@@ -1092,10 +1120,7 @@ export async function revocationRequest(as, client, token, options) {
     if (!validateString(token)) {
         throw new TypeError('"token" must be a non-empty string');
     }
-    if (typeof as.revocation_endpoint !== 'string') {
-        throw new TypeError('"as.revocation_endpoint" must be a string');
-    }
-    const url = new URL(as.revocation_endpoint);
+    const url = resolveEndpoint(as, 'revocation_endpoint', options);
     const body = new URLSearchParams(options?.additionalParameters);
     body.set('token', token);
     const headers = prepareHeaders(options?.headers);
@@ -1103,7 +1128,7 @@ export async function revocationRequest(as, client, token, options) {
     return authenticatedRequest(as, client, 'POST', url, body, headers, options);
 }
 export async function processRevocationResponse(response) {
-    if (!(response instanceof Response)) {
+    if (!looseInstanceOf(response, Response)) {
         throw new TypeError('"response" must be an instance of Response');
     }
     if (response.status !== 200) {
@@ -1126,10 +1151,7 @@ export async function introspectionRequest(as, client, token, options) {
     if (!validateString(token)) {
         throw new TypeError('"token" must be a non-empty string');
     }
-    if (typeof as.introspection_endpoint !== 'string') {
-        throw new TypeError('"as.introspection_endpoint" must be a string');
-    }
-    const url = new URL(as.introspection_endpoint);
+    const url = resolveEndpoint(as, 'introspection_endpoint', options);
     const body = new URLSearchParams(options?.additionalParameters);
     body.set('token', token);
     const headers = prepareHeaders(options?.headers);
@@ -1144,7 +1166,7 @@ export async function introspectionRequest(as, client, token, options) {
 export async function processIntrospectionResponse(as, client, response) {
     assertAs(as);
     assertClient(client);
-    if (!(response instanceof Response)) {
+    if (!looseInstanceOf(response, Response)) {
         throw new TypeError('"response" must be an instance of Response');
     }
     if (response.status !== 200) {
@@ -1186,23 +1208,19 @@ export async function processIntrospectionResponse(as, client, response) {
 }
 async function jwksRequest(as, options) {
     assertAs(as);
-    if (typeof as.jwks_uri !== 'string') {
-        throw new TypeError('"as.jwks_uri" must be a string');
-    }
-    const url = new URL(as.jwks_uri);
+    const url = resolveEndpoint(as, 'jwks_uri');
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
     headers.append('accept', 'application/jwk-set+json');
-    const request = new Request(url.href, {
-        headers,
+    return (options?.[experimental_customFetch] || fetch)(url.href, {
+        headers: Object.fromEntries(headers.entries()),
         method: 'GET',
         redirect: 'manual',
         signal: options?.signal ? signal(options.signal) : null,
-    });
-    return fetch(request).then(processDpopNonce);
+    }).then(processDpopNonce);
 }
 async function processJwksResponse(response) {
-    if (!(response instanceof Response)) {
+    if (!looseInstanceOf(response, Response)) {
         throw new TypeError('"response" must be an instance of Response');
     }
     if (response.status !== 200) {
@@ -1329,8 +1347,9 @@ async function validateJwt(jws, checkAlg, getKey, clockSkew, clockTolerance) {
         throw new OPE('unexpected JWT "crit" header parameter');
     }
     const signature = b64u(encodedSignature);
+    let key;
     if (getKey !== noSignatureCheck) {
-        const key = await getKey(header);
+        key = await getKey(header);
         const input = `${protectedHeader}.${payload}`;
         const verified = await crypto.subtle.verify(keyToSubtle(key), key, signature, buf(input));
         if (!verified) {
@@ -1379,7 +1398,7 @@ async function validateJwt(jws, checkAlg, getKey, clockSkew, clockTolerance) {
             throw new OPE('unexpected JWT "aud" (audience) claim type');
         }
     }
-    return { header, claims, signature };
+    return { header, claims, signature, key };
 }
 export async function validateJwtAuthResponse(as, client, parameters, expectedState, options) {
     assertAs(as);
@@ -1409,6 +1428,137 @@ export async function validateJwtAuthResponse(as, client, parameters, expectedSt
     }
     return validateAuthResponse(as, client, result, expectedState);
 }
+async function idTokenHash(alg, data, key) {
+    let algorithm;
+    switch (alg) {
+        case 'RS256':
+        case 'PS256':
+        case 'ES256':
+            algorithm = 'SHA-256';
+            break;
+        case 'RS384':
+        case 'PS384':
+        case 'ES384':
+            algorithm = 'SHA-384';
+            break;
+        case 'RS512':
+        case 'PS512':
+        case 'ES512':
+            algorithm = 'SHA-512';
+            break;
+        case 'EdDSA':
+            if (key.algorithm.name === 'Ed25519') {
+                algorithm = 'SHA-512';
+                break;
+            }
+            throw new UnsupportedOperationError();
+        default:
+            throw new UnsupportedOperationError();
+    }
+    const digest = await crypto.subtle.digest(algorithm, buf(data));
+    return b64u(digest.slice(0, digest.byteLength / 2));
+}
+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) {
+    assertAs(as);
+    assertClient(client);
+    if (!(parameters instanceof URLSearchParams)) {
+        throw new TypeError('"parameters" must be an instance of URLSearchParams');
+    }
+    parameters = new URLSearchParams(parameters);
+    const id_token = getURLSearchParameter(parameters, 'id_token');
+    parameters.delete('id_token');
+    switch (expectedState) {
+        case undefined:
+        case expectNoState:
+            break;
+        default:
+            if (!validateString(expectedState)) {
+                throw new TypeError('"expectedState" must be a non-empty string');
+            }
+    }
+    const result = validateAuthResponse({
+        ...as,
+        authorization_response_iss_parameter_supported: false,
+    }, client, parameters, expectedState);
+    if (isOAuth2Error(result)) {
+        return result;
+    }
+    if (!id_token) {
+        throw new OPE('"parameters" does not contain an ID Token');
+    }
+    const code = getURLSearchParameter(parameters, 'code');
+    if (!code) {
+        throw new OPE('"parameters" does not contain an Authorization Code');
+    }
+    if (typeof as.jwks_uri !== 'string') {
+        throw new TypeError('"as.jwks_uri" must be a string');
+    }
+    const requiredClaims = [
+        'aud',
+        'exp',
+        'iat',
+        'iss',
+        'sub',
+        'nonce',
+        'c_hash',
+    ];
+    if (typeof expectedState === 'string') {
+        requiredClaims.push('s_hash');
+    }
+    const { claims, header, key } = await validateJwt(id_token, checkSigningAlgorithm.bind(undefined, client.id_token_signed_response_alg, as.id_token_signing_alg_values_supported), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options), getClockSkew(client), getClockTolerance(client))
+        .then(validatePresence.bind(undefined, requiredClaims))
+        .then(validateIssuer.bind(undefined, as.issuer))
+        .then(validateAudience.bind(undefined, client.client_id));
+    const clockSkew = getClockSkew(client);
+    const now = epochTime() + clockSkew;
+    if (claims.iat < now - 3600) {
+        throw new OPE('unexpected JWT "iat" (issued at) claim value, it is too far in the past');
+    }
+    if (typeof claims.c_hash !== 'string' ||
+        (await idTokenHashMatches(code, claims.c_hash, header.alg, key)) !== true) {
+        throw new OPE('invalid ID Token "c_hash" (code hash) claim value');
+    }
+    if (claims.s_hash !== undefined && typeof expectedState !== 'string') {
+        throw new OPE('could not verify ID Token "s_hash" (state hash) claim value');
+    }
+    if (typeof expectedState === 'string' &&
+        (typeof claims.s_hash !== 'string' ||
+            (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');
+    }
+    maxAge ?? (maxAge = client.default_max_age ?? skipAuthTimeCheck);
+    if ((client.require_auth_time || maxAge !== skipAuthTimeCheck) &&
+        claims.auth_time === undefined) {
+        throw new OPE('ID Token "auth_time" (authentication time) claim missing');
+    }
+    if (maxAge !== skipAuthTimeCheck) {
+        if (typeof maxAge !== 'number' || maxAge < 0) {
+            throw new TypeError('"options.max_age" must be a non-negative number');
+        }
+        const now = epochTime() + getClockSkew(client);
+        const tolerance = getClockTolerance(client);
+        if (claims.auth_time + maxAge < now - tolerance) {
+            throw new OPE('too much time has elapsed since the last End-User authentication');
+        }
+    }
+    if (!validateString(expectedNonce)) {
+        throw new TypeError('"expectedNonce" must be a non-empty string');
+    }
+    if (claims.nonce !== expectedNonce) {
+        throw new OPE('unexpected ID Token "nonce" claim value');
+    }
+    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');
+    }
+    return result;
+}
 function checkSigningAlgorithm(client, issuer, header) {
     if (client !== undefined) {
         if (header.alg !== client) {
@@ -1525,10 +1675,7 @@ async function importJwk(alg, jwk) {
 export async function deviceAuthorizationRequest(as, client, parameters, options) {
     assertAs(as);
     assertClient(client);
-    if (typeof as.device_authorization_endpoint !== 'string') {
-        throw new TypeError('"as.device_authorization_endpoint" must be a string');
-    }
-    const url = new URL(as.device_authorization_endpoint);
+    const url = resolveEndpoint(as, 'device_authorization_endpoint', options);
     const body = new URLSearchParams(parameters);
     body.set('client_id', client.client_id);
     const headers = prepareHeaders(options?.headers);
@@ -1538,7 +1685,7 @@ export async function deviceAuthorizationRequest(as, client, parameters, options
 export async function processDeviceAuthorizationResponse(as, client, response) {
     assertAs(as);
     assertClient(client);
-    if (!(response instanceof Response)) {
+    if (!looseInstanceOf(response, Response)) {
         throw new TypeError('"response" must be an instance of Response');
     }
     if (response.status !== 200) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth4webapi",
-  "version": "2.4.5",
+  "version": "2.6.0",
   "description": "OAuth 2 / OpenID Connect for JavaScript Runtimes",
   "keywords": [
     "auth",
@@ -68,6 +68,7 @@
     "@types/node": "^20.10.8",
     "@types/oidc-provider": "^8.4.3",
     "@types/qunit": "^2.19.9",
+    "archiver": "^6.0.1",
     "ava": "^5.3.1",
     "chrome-launcher": "^1.1.0",
     "edge-runtime": "^2.5.7",
@@ -80,6 +81,7 @@
     "puppeteer-core": "^21.7.0",
     "qunit": "^2.20.0",
     "raw-body": "^2.5.2",
+    "selfsigned": "^2.4.1",
     "timekeeper": "^2.3.1",
     "tsx": "^4.7.0",
     "typedoc": "^0.25.7",