oauth4webapi 2.15.0 → 2.17.0

package/README.md

@@ -1,4 +1,4 @@
-# OAuth 2 / OpenID Connect for JavaScript Runtimes
+# Low-Level OAuth 2 / OpenID Connect Client API for JavaScript Runtimes
 
 This software provides a collection of routines that can be used to build client modules for OAuth 2.1, OAuth 2.0 with the latest Security Best Current Practices (BCP), and FAPI 2.0, as well as OpenID Connect where applicable. The primary goal of this software is to promote secure and up-to-date best practices while using only the capabilities common to both browser and non-browser JavaScript runtimes.
 
@@ -60,8 +60,9 @@ import * as oauth from 'oauth4webapi'
   - Device Authorization Grant - [source](examples/device_authorization_grant.ts)
   - Refresh Token Grant - [source](examples/refresh_token.ts) | [diff](examples/refresh_token.diff)
 - FAPI
-  - FAPI 1.0 Advanced (Private Key JWT, MTLS, JAR) - [source](examples/fapi1-advanced.ts) | [diff](examples/fapi1-advanced.diff)
-  - FAPI 2.0 Security Profile (Private Key JWT, PAR, DPoP) - [source](examples/fapi2.ts) | [diff](examples/fapi2.diff)
+  - FAPI 1.0 Advanced - [source](examples/fapi1-advanced.ts) | [diff](examples/fapi1-advanced.diff)
+  - FAPI 2.0 Security Profile - [source](examples/fapi2.ts) | [diff](examples/fapi2.diff)
+  - FAPI 2.0 Message Signing - [source](examples/fapi2-message-signing.ts) | [diff](examples/fapi2-message-signing.diff)
 
 
 ## Supported Runtimes

package/build/index.d.ts

@@ -16,6 +16,17 @@ export type JsonPrimitive = string | number | boolean | null;
  * JSON Values
  */
 export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+export interface ModifyAssertionFunction {
+    (
+    /**
+     * JWS Header to modify right before it is signed.
+     */
+    header: Record<string, JsonValue | undefined>, 
+    /**
+     * JWT Claims Set to modify right before it is signed.
+     */
+    payload: Record<string, JsonValue | undefined>): void;
+}
 /**
  * Interface to pass an asymmetric private key and, optionally, its associated JWK Key ID to be
  * added as a `kid` JOSE Header Parameter.
@@ -32,6 +43,12 @@ export interface PrivateKey {
      * ID) will be added to the JOSE Header.
      */
     kid?: string;
+    /**
+     * Use to modify the JWT signed by this key right before it is signed.
+     *
+     * @see {@link modifyAssertion}
+     */
+    [modifyAssertion]?: ModifyAssertionFunction;
 }
 /**
  * Supported Client Authentication Methods.
@@ -278,6 +295,100 @@ export declare const clockTolerance: unique symbol;
  * ```
  */
 export declare const customFetch: unique symbol;
+/**
+ * Use to mutate JWT header and payload before they are signed. Its intended use is working around
+ * non-conform server behaviours, such as modifying JWT "aud" (audience) claims, or otherwise
+ * changing fixed claims used by this library.
+ *
+ * @example
+ *
+ * Changing Private Key JWT client assertion audience issued from an array to a string
+ *
+ * ```ts
+ * import * as oauth from 'oauth4webapi'
+ *
+ * // Prerequisites
+ * let as!: oauth.AuthorizationServer
+ * let client!: oauth.Client
+ * let parameters!: URLSearchParams
+ * let clientPrivateKey!: CryptoKey
+ *
+ * const response = await oauth.pushedAuthorizationRequest(as, client, parameters, {
+ *   clientPrivateKey: {
+ *     key: clientPrivateKey,
+ *     [oauth.modifyAssertion](header, payload) {
+ *       payload.aud = as.issuer
+ *     },
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ *
+ * Changing Request Object issued by {@link issueRequestObject} to have an expiration of 5 minutes
+ *
+ * ```ts
+ * import * as oauth from 'oauth4webapi'
+ *
+ * // Prerequisites
+ * let as!: oauth.AuthorizationServer
+ * let client!: oauth.Client
+ * let parameters!: URLSearchParams
+ * let jarPrivateKey!: CryptoKey
+ *
+ * const request = await oauth.issueRequestObject(as, client, parameters, {
+ *   key: jarPrivateKey,
+ *   [oauth.modifyAssertion](header, payload) {
+ *     payload.exp = <number>payload.iat + 300
+ *   },
+ * })
+ * ```
+ */
+export declare const modifyAssertion: unique symbol;
+/**
+ * Use to add support for decrypting JWEs the client encounters, namely
+ *
+ * - Encrypted ID Tokens returned by the Token Endpoint
+ * - Encrypted ID Tokens returned as part of FAPI 1.0 Advanced Detached Signature authorization
+ *   responses
+ * - Encrypted JWT UserInfo responses
+ * - Encrypted JWT Introspection responses
+ * - Encrypted JARM Responses
+ *
+ * @example
+ *
+ * Decrypting JARM responses
+ *
+ * ```ts
+ * import * as oauth from 'oauth4webapi'
+ * import * as jose from 'jose'
+ *
+ * // Prerequisites
+ * let as!: oauth.AuthorizationServer
+ * let key!: CryptoKey
+ * let alg!: string
+ * let enc!: string
+ *
+ * const decoder = new TextDecoder()
+ *
+ * const client: oauth.Client = {
+ *   client_id: 'urn:example:client_id',
+ *   async [oauth.jweDecrypt](jwe) {
+ *     const { plaintext } = await compactDecrypt(jwe, key, {
+ *       keyManagementAlgorithms: [alg],
+ *       contentEncryptionAlgorithms: [enc],
+ *     }).catch((cause) => {
+ *       throw new oauth.OperationProcessingError('decryption failed', { cause })
+ *     })
+ *
+ *     return decoder.decode(plaintext)
+ *   },
+ * }
+ *
+ * const params = await oauth.validateJwtAuthResponse(as, client, currentUrl)
+ * ```
+ */
+export declare const jweDecrypt: unique symbol;
 /**
  * DANGER ZONE - This option has security implications that must be understood, assessed for
  * applicability, and accepted before use. It is critical that the JSON Web Key Set cache only be
@@ -333,66 +444,9 @@ export declare const customFetch: 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
- * 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 UseMTLSAliasOptions} 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.useMtlsAlias]: true,
- *   [oauth.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.useMtlsAlias]: true,
- *   [oauth.customFetch]: (...args) => {
- *     return fetch(args[0], {
- *       ...args[1],
- *       client: agent,
- *     })
- *   },
- * })
- * ```
+ * @ignore
  *
- * @see [RFC 8705 - OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html)
+ * @deprecated Use {@link Client.use_mtls_endpoint_aliases `client.use_mtls_endpoint_aliases`}.
  */
 export declare const useMtlsAlias: unique symbol;
 /**
@@ -774,6 +828,64 @@ export interface Client {
      * Default Maximum Authentication Age.
      */
     default_max_age?: number;
+    /**
+     * Indicates the requirement for a client to use mutual TLS endpoint aliases defined by the AS
+     * where present. Default is `false`.
+     *
+     * 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.
+     *
+     * @example
+     *
+     * (Node.js) Using [nodejs/undici](https://github.com/nodejs/undici) for Mutual-TLS Client
+     * Authentication and Certificate-Bound Access Tokens support.
+     *
+     * ```ts
+     * import * as undici from 'undici'
+     * import * as oauth from 'oauth4webapi'
+     *
+     * // Prerequisites
+     * let as!: oauth.AuthorizationServer
+     * let client!: oauth.Client & { use_mtls_endpoint_aliases: true }
+     * let params!: URLSearchParams
+     * let key!: string // PEM-encoded key
+     * let cert!: string // PEM-encoded certificate
+     *
+     * const agent = new undici.Agent({ connect: { key, cert } })
+     *
+     * const response = await oauth.pushedAuthorizationRequest(as, client, params, {
+     *   [oauth.customFetch]: (...args) =>
+     *     undici.fetch(args[0], { ...args[1], dispatcher: agent }),
+     * })
+     * ```
+     *
+     * @example
+     *
+     * (Deno) Using Deno.createHttpClient API for Mutual-TLS Client Authentication and
+     * Certificate-Bound Access Tokens support.
+     *
+     * ```ts
+     * import * as oauth from 'oauth4webapi'
+     *
+     * // Prerequisites
+     * let as!: oauth.AuthorizationServer
+     * let client!: oauth.Client & { use_mtls_endpoint_aliases: true }
+     * let params!: URLSearchParams
+     * let key!: string // PEM-encoded key
+     * let cert!: string // PEM-encoded certificate
+     *
+     * const agent = Deno.createHttpClient({ key, cert })
+     *
+     * const response = await oauth.pushedAuthorizationRequest(as, client, params, {
+     *   [oauth.customFetch]: (...args) => fetch(args[0], { ...args[1], client: agent }),
+     * })
+     * ```
+     *
+     * @see [RFC 8705 - OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://www.rfc-editor.org/rfc/rfc8705.html)
+     */
+    use_mtls_endpoint_aliases?: boolean;
     /**
      * See {@link clockSkew}.
      */
@@ -782,6 +894,10 @@ export interface Client {
      * See {@link clockTolerance}.
      */
     [clockTolerance]?: number;
+    /**
+     * See {@link jweDecrypt}.
+     */
+    [jweDecrypt]?: JweDecryptFunction;
     [metadata: string]: JsonValue | undefined;
 }
 /**
@@ -894,7 +1010,7 @@ export declare function generateRandomState(): string;
  */
 export declare function generateRandomNonce(): string;
 /**
- * Calculates the PKCE `code_verifier` value to send with an authorization request using the S256
+ * Calculates the PKCE `code_challenge` value to send with an authorization request using the S256
  * PKCE Code Challenge Method transformation.
  *
  * @param codeVerifier `code_verifier` value generated e.g. from {@link generateRandomCodeVerifier}.
@@ -923,6 +1039,12 @@ export interface DPoPOptions extends CryptoKeyPair {
      * will be used automatically.
      */
     nonce?: string;
+    /**
+     * Use to modify the DPoP Proof JWT right before it is signed.
+     *
+     * @see {@link modifyAssertion}
+     */
+    [modifyAssertion]?: ModifyAssertionFunction;
 }
 export interface DPoPRequestOptions {
     /**
@@ -930,9 +1052,16 @@ export interface DPoPRequestOptions {
      */
     DPoP?: DPoPOptions;
 }
+/**
+ * @ignore
+ *
+ * @deprecated Use {@link Client.use_mtls_endpoint_aliases `client.use_mtls_endpoint_aliases`}.
+ */
 export interface UseMTLSAliasOptions {
     /**
-     * See {@link useMtlsAlias}.
+     * @ignore
+     *
+     * @deprecated Use {@link Client.use_mtls_endpoint_aliases `client.use_mtls_endpoint_aliases`}.
      */
     [useMtlsAlias]?: boolean;
 }
@@ -1611,6 +1740,9 @@ export declare function processIntrospectionResponse(as: AuthorizationServer, cl
 export interface JWKS {
     readonly keys: JWK[];
 }
+export interface JweDecryptFunction {
+    (jwe: string): Promise<string>;
+}
 /**
  * Same as {@link validateAuthResponse} but for signed JARM responses.
  *
@@ -1855,19 +1987,19 @@ export declare const experimental_customFetch: symbol;
 /**
  * @ignore
  *
- * @deprecated Use {@link useMtlsAlias}.
+ * @deprecated Use {@link Client.use_mtls_endpoint_aliases `client.use_mtls_endpoint_aliases`}.
  */
 export declare const experimentalUseMtlsAlias: symbol;
 /**
  * @ignore
  *
- * @deprecated Use {@link useMtlsAlias}.
+ * @deprecated Use {@link Client.use_mtls_endpoint_aliases `client.use_mtls_endpoint_aliases`}.
  */
 export declare const experimental_useMtlsAlias: symbol;
 /**
  * @ignore
  *
- * @deprecated Use {@link UseMTLSAliasOptions}.
+ * @deprecated Use {@link Client.use_mtls_endpoint_aliases `client.use_mtls_endpoint_aliases`}.
  */
 export type ExperimentalUseMTLSAliasOptions = UseMTLSAliasOptions;
 /**

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.15.0';
+    const VERSION = 'v2.17.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
 function looseInstanceOf(input, expected) {
@@ -19,6 +19,8 @@ function looseInstanceOf(input, expected) {
 export const clockSkew = Symbol();
 export const clockTolerance = Symbol();
 export const customFetch = Symbol();
+export const modifyAssertion = Symbol();
+export const jweDecrypt = Symbol();
 export const jwksCache = Symbol();
 export const useMtlsAlias = Symbol();
 const encoder = new TextEncoder();
@@ -279,7 +281,11 @@ function getKeyAndKid(input) {
     if (input.kid !== undefined && !validateString(input.kid)) {
         throw new TypeError('"kid" must be a non-empty string');
     }
-    return { key: input.key, kid: input.kid };
+    return {
+        key: input.key,
+        kid: input.kid,
+        modifyAssertion: input[modifyAssertion],
+    };
 }
 function formUrlEncode(token) {
     return encodeURIComponent(token).replace(/%20/g, '+');
@@ -366,11 +372,11 @@ function clientAssertion(as, client) {
         sub: client.client_id,
     };
 }
-async function privateKeyJwt(as, client, key, kid) {
-    return jwt({
-        alg: keyToJws(key),
-        kid,
-    }, clientAssertion(as, client), key);
+async function privateKeyJwt(as, client, key, kid, modifyAssertion) {
+    const header = { alg: keyToJws(key), kid };
+    const payload = clientAssertion(as, client);
+    modifyAssertion?.(header, payload);
+    return jwt(header, payload, key);
 }
 function assertAs(as) {
     if (typeof as !== 'object' || as === null) {
@@ -428,13 +434,13 @@ async function clientAuthentication(as, client, body, headers, clientPrivateKey)
             if (clientPrivateKey === undefined) {
                 throw new TypeError('"options.clientPrivateKey" must be provided when "client.token_endpoint_auth_method" is "private_key_jwt"');
             }
-            const { key, kid } = getKeyAndKid(clientPrivateKey);
+            const { key, kid, modifyAssertion } = getKeyAndKid(clientPrivateKey);
             if (!isPrivateKey(key)) {
                 throw new TypeError('"options.clientPrivateKey.key" must be a private CryptoKey');
             }
             body.set('client_id', client.client_id);
             body.set('client_assertion_type', 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer');
-            body.set('client_assertion', await privateKeyJwt(as, client, key, kid));
+            body.set('client_assertion', await privateKeyJwt(as, client, key, kid, modifyAssertion));
             break;
         }
         case 'tls_client_auth':
@@ -449,11 +455,11 @@ async function clientAuthentication(as, client, body, headers, clientPrivateKey)
             throw new UnsupportedOperationError('unsupported client token_endpoint_auth_method');
     }
 }
-async function jwt(header, claimsSet, key) {
+async function jwt(header, payload, key) {
     if (!key.usages.includes('sign')) {
         throw new TypeError('CryptoKey instances used for signing assertions must include "sign" in their "usages"');
     }
-    const input = `${b64u(buf(JSON.stringify(header)))}.${b64u(buf(JSON.stringify(claimsSet)))}`;
+    const input = `${b64u(buf(JSON.stringify(header)))}.${b64u(buf(JSON.stringify(payload)))}`;
     const signature = b64u(await crypto.subtle.sign(keyToSubtle(key), key, buf(input)));
     return `${input}.${signature}`;
 }
@@ -461,7 +467,7 @@ export async function issueRequestObject(as, client, parameters, privateKey) {
     assertAs(as);
     assertClient(client);
     parameters = new URLSearchParams(parameters);
-    const { key, kid } = getKeyAndKid(privateKey);
+    const { key, kid, modifyAssertion } = getKeyAndKid(privateKey);
     if (!isPrivateKey(key)) {
         throw new TypeError('"privateKey.key" must be a private CryptoKey');
     }
@@ -519,11 +525,13 @@ export async function issueRequestObject(as, client, parameters, privateKey) {
             }
         }
     }
-    return jwt({
+    const header = {
         alg: keyToJws(key),
         typ: 'oauth-authz-req+jwt',
         kid,
-    }, claims, key);
+    };
+    modifyAssertion?.(header, claims);
+    return jwt(header, claims, key);
 }
 async function dpopProofJwt(headers, options, url, htm, clockSkew, accessToken) {
     const { privateKey, publicKey, nonce = dpopNonces.get(url.origin) } = options;
@@ -540,19 +548,21 @@ async function dpopProofJwt(headers, options, url, htm, clockSkew, accessToken)
         throw new TypeError('"DPoP.publicKey.extractable" must be true');
     }
     const now = epochTime() + clockSkew;
-    const proof = await jwt({
+    const header = {
         alg: keyToJws(privateKey),
         typ: 'dpop+jwt',
         jwk: await publicJwk(publicKey),
-    }, {
+    };
+    const payload = {
         iat: now,
         jti: randomBytes(),
         htm,
         nonce,
         htu: `${url.origin}${url.pathname}`,
         ath: accessToken ? b64u(await crypto.subtle.digest('SHA-256', buf(accessToken))) : undefined,
-    }, privateKey);
-    headers.set('dpop', proof);
+    };
+    options[modifyAssertion]?.(header, payload);
+    headers.set('dpop', await jwt(header, payload, privateKey));
 }
 let jwkCache;
 async function getSetPublicJwkCache(key) {
@@ -565,25 +575,31 @@ async function publicJwk(key) {
     jwkCache || (jwkCache = new WeakMap());
     return jwkCache.get(key) || getSetPublicJwkCache(key);
 }
-function validateEndpoint(value, endpoint, options) {
+function validateEndpoint(value, endpoint, useMtlsAlias) {
     if (typeof value !== 'string') {
-        if (options?.[useMtlsAlias]) {
+        if (useMtlsAlias) {
             throw new TypeError(`"as.mtls_endpoint_aliases.${endpoint}" must be a string`);
         }
         throw new TypeError(`"as.${endpoint}" must be a string`);
     }
     return new URL(value);
 }
-function resolveEndpoint(as, endpoint, options) {
-    if (options?.[useMtlsAlias] && as.mtls_endpoint_aliases && endpoint in as.mtls_endpoint_aliases) {
-        return validateEndpoint(as.mtls_endpoint_aliases[endpoint], endpoint, options);
+function resolveEndpoint(as, endpoint, useMtlsAlias = false) {
+    if (useMtlsAlias && as.mtls_endpoint_aliases && endpoint in as.mtls_endpoint_aliases) {
+        return validateEndpoint(as.mtls_endpoint_aliases[endpoint], endpoint, useMtlsAlias);
     }
-    return validateEndpoint(as[endpoint], endpoint);
+    return validateEndpoint(as[endpoint], endpoint, useMtlsAlias);
+}
+function alias(client, options) {
+    if (client.use_mtls_endpoint_aliases || options?.[useMtlsAlias]) {
+        return true;
+    }
+    return false;
 }
 export async function pushedAuthorizationRequest(as, client, parameters, options) {
     assertAs(as);
     assertClient(client);
-    const url = resolveEndpoint(as, 'pushed_authorization_request_endpoint', options);
+    const url = resolveEndpoint(as, 'pushed_authorization_request_endpoint', alias(client, options));
     const body = new URLSearchParams(parameters);
     body.set('client_id', client.client_id);
     const headers = prepareHeaders(options?.headers);
@@ -716,7 +732,7 @@ export async function protectedResourceRequest(accessToken, method, url, headers
 export async function userInfoRequest(as, client, accessToken, options) {
     assertAs(as);
     assertClient(client);
-    const url = resolveEndpoint(as, 'userinfo_endpoint', options);
+    const url = resolveEndpoint(as, 'userinfo_endpoint', alias(client, options));
     const headers = prepareHeaders(options?.headers);
     if (client.userinfo_signed_response_alg) {
         headers.set('accept', 'application/jwt');
@@ -858,8 +874,7 @@ export async function processUserInfoResponse(as, client, expectedSubject, respo
     let json;
     if (getContentType(response) === 'application/jwt') {
         assertReadableResponse(response);
-        const jwt = await response.text();
-        const { claims } = await validateJwt(jwt, checkSigningAlgorithm.bind(undefined, client.userinfo_signed_response_alg, as.userinfo_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client))
+        const { claims, jwt } = await validateJwt(await response.text(), checkSigningAlgorithm.bind(undefined, client.userinfo_signed_response_alg, as.userinfo_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client), client[jweDecrypt])
             .then(validateOptionalAudience.bind(undefined, client.client_id))
             .then(validateOptionalIssuer.bind(undefined, as.issuer));
         jwtResponseBodies.set(response, jwt);
@@ -908,7 +923,7 @@ async function authenticatedRequest(as, client, method, url, body, headers, opti
     }).then(processDpopNonce);
 }
 async function tokenEndpointRequest(as, client, grantType, parameters, options) {
-    const url = resolveEndpoint(as, 'token_endpoint', options);
+    const url = resolveEndpoint(as, 'token_endpoint', alias(client, options));
     parameters.set('grant_type', grantType);
     const headers = prepareHeaders(options?.headers);
     headers.set('accept', 'application/json');
@@ -937,14 +952,14 @@ export function getValidatedIdTokenClaims(ref) {
     if (!claims) {
         throw new TypeError('"ref" was already garbage collected or did not resolve from the proper sources');
     }
-    return claims;
+    return claims[0];
 }
 export async function validateIdTokenSignature(as, ref, options) {
     assertAs(as);
-    if (!getValidatedIdTokenClaims(ref)) {
+    if (!idTokenClaims.has(ref)) {
         throw new OPE('"ref" does not contain an ID Token to verify the signature of');
     }
-    const { 0: protectedHeader, 1: payload, 2: encodedSignature } = ref.id_token.split('.');
+    const { 0: protectedHeader, 1: payload, 2: encodedSignature, } = idTokenClaims.get(ref)[1].split('.');
     const header = JSON.parse(buf(b64u(protectedHeader)));
     if (header.alg.startsWith('HS')) {
         throw new UnsupportedOperationError();
@@ -1024,7 +1039,7 @@ async function processGenericAccessTokenResponse(as, client, response, ignoreIdT
             throw new OPE('"response" body "id_token" property must be a non-empty string');
         }
         if (json.id_token) {
-            const { claims } = await validateJwt(json.id_token, checkSigningAlgorithm.bind(undefined, client.id_token_signed_response_alg, as.id_token_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client))
+            const { claims, jwt } = await validateJwt(json.id_token, checkSigningAlgorithm.bind(undefined, client.id_token_signed_response_alg, as.id_token_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client), client[jweDecrypt])
                 .then(validatePresence.bind(undefined, ['aud', 'exp', 'iat', 'iss', 'sub']))
                 .then(validateIssuer.bind(undefined, as.issuer))
                 .then(validateAudience.bind(undefined, client.client_id));
@@ -1040,7 +1055,7 @@ async function processGenericAccessTokenResponse(as, client, response, ignoreIdT
                 (!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);
+            idTokenClaims.set(json, [claims, jwt]);
         }
     }
     return json;
@@ -1219,7 +1234,7 @@ export async function revocationRequest(as, client, token, options) {
     if (!validateString(token)) {
         throw new TypeError('"token" must be a non-empty string');
     }
-    const url = resolveEndpoint(as, 'revocation_endpoint', options);
+    const url = resolveEndpoint(as, 'revocation_endpoint', alias(client, options));
     const body = new URLSearchParams(options?.additionalParameters);
     body.set('token', token);
     const headers = prepareHeaders(options?.headers);
@@ -1250,7 +1265,7 @@ export async function introspectionRequest(as, client, token, options) {
     if (!validateString(token)) {
         throw new TypeError('"token" must be a non-empty string');
     }
-    const url = resolveEndpoint(as, 'introspection_endpoint', options);
+    const url = resolveEndpoint(as, 'introspection_endpoint', alias(client, options));
     const body = new URLSearchParams(options?.additionalParameters);
     body.set('token', token);
     const headers = prepareHeaders(options?.headers);
@@ -1278,8 +1293,7 @@ export async function processIntrospectionResponse(as, client, response) {
     let json;
     if (getContentType(response) === 'application/token-introspection+jwt') {
         assertReadableResponse(response);
-        const jwt = await response.text();
-        const { claims } = await validateJwt(jwt, checkSigningAlgorithm.bind(undefined, client.introspection_signed_response_alg, as.introspection_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client))
+        const { claims, jwt } = await validateJwt(await response.text(), checkSigningAlgorithm.bind(undefined, client.introspection_signed_response_alg, as.introspection_signing_alg_values_supported), noSignatureCheck, getClockSkew(client), getClockTolerance(client), client[jweDecrypt])
             .then(checkJwtType.bind(undefined, 'token-introspection+jwt'))
             .then(validatePresence.bind(undefined, ['aud', 'iat', 'iss']))
             .then(validateIssuer.bind(undefined, as.issuer))
@@ -1432,10 +1446,16 @@ async function validateJwsSignature(protectedHeader, payload, key, signature) {
         throw new OPE('JWT signature verification failed');
     }
 }
-async function validateJwt(jws, checkAlg, getKey, clockSkew, clockTolerance) {
-    const { 0: protectedHeader, 1: payload, 2: encodedSignature, length } = jws.split('.');
+async function validateJwt(jws, checkAlg, getKey, clockSkew, clockTolerance, decryptJwt) {
+    let { 0: protectedHeader, 1: payload, 2: encodedSignature, length } = jws.split('.');
     if (length === 5) {
-        throw new UnsupportedOperationError('JWE structure JWTs are not supported');
+        if (decryptJwt !== undefined) {
+            jws = await decryptJwt(jws);
+            ({ 0: protectedHeader, 1: payload, 2: encodedSignature, length } = jws.split('.'));
+        }
+        else {
+            throw new UnsupportedOperationError('JWE structure JWTs are not supported');
+        }
     }
     if (length !== 3) {
         throw new OPE('Invalid JWT');
@@ -1502,7 +1522,7 @@ async function validateJwt(jws, checkAlg, getKey, clockSkew, clockTolerance) {
             throw new OPE('unexpected JWT "aud" (audience) claim type');
         }
     }
-    return { header, claims, signature, key };
+    return { header, claims, signature, key, jwt: jws };
 }
 export async function validateJwtAuthResponse(as, client, parameters, expectedState, options) {
     assertAs(as);
@@ -1517,7 +1537,7 @@ export async function validateJwtAuthResponse(as, client, parameters, expectedSt
     if (!response) {
         throw new OPE('"parameters" does not contain a JARM response');
     }
-    const { claims } = await validateJwt(response, checkSigningAlgorithm.bind(undefined, client.authorization_signed_response_alg, as.authorization_signing_alg_values_supported), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options), getClockSkew(client), getClockTolerance(client))
+    const { claims } = await validateJwt(response, checkSigningAlgorithm.bind(undefined, client.authorization_signed_response_alg, as.authorization_signing_alg_values_supported), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options), getClockSkew(client), getClockTolerance(client), client[jweDecrypt])
         .then(validatePresence.bind(undefined, ['aud', 'exp', 'iss']))
         .then(validateIssuer.bind(undefined, as.issuer))
         .then(validateAudience.bind(undefined, client.client_id));
@@ -1613,7 +1633,7 @@ export async function validateDetachedSignatureResponse(as, client, parameters,
     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))
+    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), client[jweDecrypt])
         .then(validatePresence.bind(undefined, requiredClaims))
         .then(validateIssuer.bind(undefined, as.issuer))
         .then(validateAudience.bind(undefined, client.client_id));
@@ -1785,7 +1805,7 @@ async function importJwk(alg, jwk) {
 export async function deviceAuthorizationRequest(as, client, parameters, options) {
     assertAs(as);
     assertClient(client);
-    const url = resolveEndpoint(as, 'device_authorization_endpoint', options);
+    const url = resolveEndpoint(as, 'device_authorization_endpoint', alias(client, options));
     const body = new URLSearchParams(parameters);
     body.set('client_id', client.client_id);
     const headers = prepareHeaders(options?.headers);
@@ -1861,7 +1881,10 @@ export async function generateKeyPair(alg, options) {
             publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
         });
     }
-    return (crypto.subtle.generateKey(algorithm, options?.extractable ?? false, ['sign', 'verify']));
+    return crypto.subtle.generateKey(algorithm, options?.extractable ?? false, [
+        'sign',
+        'verify',
+    ]);
 }
 function normalizeHtu(htu) {
     const url = new URL(htu);
@@ -1890,7 +1913,7 @@ async function validateDPoP(as, request, accessToken, accessTokenClaims, options
             throw new OPE('DPoP Proof jwk header parameter must contain a public key');
         }
         return key;
-    }, clockSkew, getClockTolerance(options))
+    }, clockSkew, getClockTolerance(options), undefined)
         .then(checkJwtType.bind(undefined, 'dpop+jwt'))
         .then(validatePresence.bind(undefined, ['iat', 'jti', 'ath', 'htm', 'htu']));
     const now = epochTime() + clockSkew;
@@ -1981,7 +2004,7 @@ export async function validateJwtAccessToken(as, request, expectedAudience, opti
     if (options?.requireDPoP || scheme === 'dpop' || request.headers.has('dpop')) {
         requiredClaims.push('cnf');
     }
-    const { claims } = await validateJwt(accessToken, checkSigningAlgorithm.bind(undefined, undefined, SUPPORTED_JWS_ALGS), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options), getClockSkew(options), getClockTolerance(options))
+    const { claims } = await validateJwt(accessToken, checkSigningAlgorithm.bind(undefined, undefined, SUPPORTED_JWS_ALGS), getPublicSigKeyFromIssuerJwksUri.bind(undefined, as, options), getClockSkew(options), getClockTolerance(options), undefined)
         .then(checkJwtType.bind(undefined, 'at+jwt'))
         .then(validatePresence.bind(undefined, requiredClaims))
         .then(validateIssuer.bind(undefined, as.issuer))

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oauth4webapi",
-  "version": "2.15.0",
-  "description": "OAuth 2 / OpenID Connect for JavaScript Runtimes",
+  "version": "2.17.0",
+  "description": "Low-Level OAuth 2 / OpenID Connect Client API for JavaScript Runtimes",
   "keywords": [
     "access token",
     "auth",