oauth4webapi 2.16.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.
 

package/build/index.d.ts

@@ -444,63 +444,9 @@ export declare const jweDecrypt: 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.
- *
- * ```ts
- * import * as undici from 'undici'
- * import * as oauth from 'oauth4webapi'
- *
- * // Prerequisites
- * let as!: oauth.AuthorizationServer
- * let client!: oauth.Client
- * 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.useMtlsAlias]: true,
- *   [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
- * 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.useMtlsAlias]: true,
- *   [oauth.customFetch]: (...args) => 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;
 /**
@@ -882,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}.
      */
@@ -1006,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}.
@@ -1048,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;
 }
@@ -1976,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.16.0';
+    const VERSION = 'v2.17.0';
     USER_AGENT = `${NAME}/${VERSION}`;
 }
 function looseInstanceOf(input, expected) {
@@ -575,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);
@@ -726,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');
@@ -917,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');
@@ -1228,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);
@@ -1259,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);
@@ -1799,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);
@@ -1875,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);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oauth4webapi",
-  "version": "2.16.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",