refactor!: client authentication is now an explicit argument to authe…

…nticated functions
panva · Sep 28, 2024 · ddeb149 · ddeb149
1 parent fee815e
commit ddeb149
Show file tree

Hide file tree

Showing 71 changed files with 818 additions and 818 deletions.
diff --git a/conformance/runner.ts b/conformance/runner.ts
@@ -163,7 +163,6 @@ export const flow = (options?: MacroOptions) => {
       const decoder = new TextDecoder()
       const client: oauth.Client = {
         client_id: configuration.client.client_id,
-        client_secret: configuration.client.client_secret,
         async [oauth.jweDecrypt](jwe) {
           const { plaintext } = await compactDecrypt(
             jwe,
@@ -177,38 +176,34 @@ export const flow = (options?: MacroOptions) => {
         use_mtls_endpoint_aliases: configuration.client.use_mtls_endpoint_aliases,
       }
 
+      let clientAuth: oauth.ClientAuthenticationImplementation
       switch (variant.client_auth_type) {
         case 'mtls':
-          client.token_endpoint_auth_method = 'self_signed_tls_client_auth'
+          clientAuth = oauth.SelfSignedTlsClientAuth()
           break
         case 'none':
+          clientAuth = oauth.None()
+          break
         case 'private_key_jwt':
+          const [jwk] = configuration.client.jwks.keys
+          clientAuth = oauth.PrivateKeyJwt({
+            kid: jwk.kid,
+            key: await importPrivateKey(JWS_ALGORITHM, jwk),
+          })
+          break
         case 'client_secret_basic':
+          clientAuth = oauth.ClientSecretBasic(configuration.client.client_secret!)
+          break
         case 'client_secret_post':
-          client.token_endpoint_auth_method = variant.client_auth_type
+          clientAuth = oauth.ClientSecretPost(configuration.client.client_secret!)
           break
         default:
-          client.token_endpoint_auth_method = 'client_secret_basic'
+          clientAuth = oauth.ClientSecretPost(configuration.client.client_secret!)
           break
       }
 
       if (instance.name.includes('client-secret-basic')) {
-        client.token_endpoint_auth_method = 'client_secret_basic'
-      }
-
-      let clientPrivateKey!: oauth.PrivateKey
-
-      switch (client.token_endpoint_auth_method) {
-        case 'none':
-          delete client.client_secret
-          break
-        case 'private_key_jwt':
-          delete client.client_secret
-          const [jwk] = configuration.client.jwks.keys
-          clientPrivateKey = {
-            kid: jwk.kid,
-            key: await importPrivateKey(JWS_ALGORITHM, jwk),
-          }
+        clientAuth = oauth.ClientSecretBasic(configuration.client.client_secret!)
       }
 
       const mtlsFetch = (...args: Parameters<typeof fetch>) => {
@@ -320,10 +315,9 @@ export const flow = (options?: MacroOptions) => {
       if (usesPar(plan)) {
         t.log('PAR request with', Object.fromEntries(authorizationUrl.searchParams.entries()))
         const request = () =>
-          oauth.pushedAuthorizationRequest(as, client, authorizationUrl.searchParams, {
+          oauth.pushedAuthorizationRequest(as, client, clientAuth, authorizationUrl.searchParams, {
             ...clientAuthOptions('par'),
             DPoP,
-            clientPrivateKey,
           })
         let par = await request()
 
@@ -383,12 +377,12 @@ export const flow = (options?: MacroOptions) => {
           oauth.authorizationCodeGrantRequest(
             as,
             client,
+            clientAuth,
             params,
             configuration.client.redirect_uri,
             code_verifier,
             {
               ...clientAuthOptions('token'),
-              clientPrivateKey,
               DPoP,
             },
           )

diff --git a/docs/README.md b/docs/README.md
@@ -38,6 +38,15 @@ Support from the community to continue maintaining and improving this module is
 - [discoveryRequest](functions/discoveryRequest.md)
 - [processDiscoveryResponse](functions/processDiscoveryResponse.md)
 
+## Client Authentication Methods
+
+- [ClientSecretBasic](functions/ClientSecretBasic.md)
+- [ClientSecretPost](functions/ClientSecretPost.md)
+- [None](functions/None.md)
+- [PrivateKeyJwt](functions/PrivateKeyJwt.md)
+- [SelfSignedTlsClientAuth](functions/SelfSignedTlsClientAuth.md)
+- [TlsClientAuth](functions/TlsClientAuth.md)
+
 ## Client Credentials Grant
 
 - [clientCredentialsGrantRequest](functions/clientCredentialsGrantRequest.md)
@@ -157,7 +166,6 @@ Support from the community to continue maintaining and improving this module is
 
 ## Interfaces
 
-- [AuthenticatedRequestOptions](interfaces/AuthenticatedRequestOptions.md)
 - [AuthorizationDetails](interfaces/AuthorizationDetails.md)
 - [AuthorizationServer](interfaces/AuthorizationServer.md)
 - [Client](interfaces/Client.md)
@@ -200,7 +208,7 @@ Support from the community to continue maintaining and improving this module is
 
 ## Type Aliases
 
-- [ClientAuthenticationMethod](type-aliases/ClientAuthenticationMethod.md)
+- [ClientAuthenticationImplementation](type-aliases/ClientAuthenticationImplementation.md)
 - [JsonArray](type-aliases/JsonArray.md)
 - [JsonObject](type-aliases/JsonObject.md)
 - [JsonPrimitive](type-aliases/JsonPrimitive.md)

diff --git a/docs/functions/ClientSecretBasic.md b/docs/functions/ClientSecretBasic.md
@@ -0,0 +1,28 @@
+# Function: ClientSecretBasic()
+
+[💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+***
+
+▸ **ClientSecretBasic**(`clientSecret`): [`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md)
+
+**`client_secret_basic`** uses the HTTP `Basic` authentication scheme to send `client_id` and
+`client_secret` in an `Authorization` HTTP Header.
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `clientSecret` | `string` |  |
+
+## Returns
+
+[`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md)
+
+## See
+
+ - [OAuth Token Endpoint Authentication Methods](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-endpoint-auth-method)
+ - [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-2.3)
+ - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
diff --git a/docs/functions/ClientSecretPost.md b/docs/functions/ClientSecretPost.md
@@ -0,0 +1,28 @@
+# Function: ClientSecretPost()
+
+[💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+***
+
+▸ **ClientSecretPost**(`clientSecret`): [`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md)
+
+**`client_secret_post`** uses the HTTP request body to send `client_id` and `client_secret` as
+`application/x-www-form-urlencoded` body parameters
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `clientSecret` | `string` |  |
+
+## Returns
+
+[`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md)
+
+## See
+
+ - [OAuth Token Endpoint Authentication Methods](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-endpoint-auth-method)
+ - [RFC 6749 - The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749.html#section-2.3)
+ - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
diff --git a/docs/functions/None.md b/docs/functions/None.md
@@ -0,0 +1,21 @@
+# Function: None()
+
+[💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+***
+
+▸ **None**(): [`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md)
+
+**`none`** (public client) uses the HTTP request body to send only `client_id` as
+`application/x-www-form-urlencoded` body parameter.
+
+## Returns
+
+[`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md)
+
+## See
+
+ - [OAuth Token Endpoint Authentication Methods](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-endpoint-auth-method)
+ - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
diff --git a/docs/functions/PrivateKeyJwt.md b/docs/functions/PrivateKeyJwt.md
@@ -0,0 +1,27 @@
+# Function: PrivateKeyJwt()
+
+[💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+***
+
+▸ **PrivateKeyJwt**(`clientPrivateKey`): [`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md)
+
+**`private_key_jwt`** uses the HTTP request body to send `client_id`, `client_assertion_type`,
+and `client_assertion` as `application/x-www-form-urlencoded` body parameters.
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `clientPrivateKey` | [`CryptoKey`](https://developer.mozilla.org/docs/Web/API/CryptoKey) \| [`PrivateKey`](../interfaces/PrivateKey.md) |  |
+
+## Returns
+
+[`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md)
+
+## See
+
+ - [OAuth Token Endpoint Authentication Methods](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-endpoint-auth-method)
+ - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication)
diff --git a/docs/functions/SelfSignedTlsClientAuth.md b/docs/functions/SelfSignedTlsClientAuth.md
@@ -0,0 +1,22 @@
+# Function: SelfSignedTlsClientAuth()
+
+[💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+***
+
+▸ **SelfSignedTlsClientAuth**(): [`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md)
+
+**`self_signed_tls_client_auth`** uses the HTTP request body to send only `client_id` as
+`application/x-www-form-urlencoded` body parameter and the mTLS key and certificate is configured
+through [customFetch](../variables/customFetch.md).
+
+## Returns
+
+[`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md)
+
+## See
+
+ - [OAuth Token Endpoint Authentication Methods](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-endpoint-auth-method)
+ - [RFC 8705 - OAuth 2.0 Mutual-TLS Client Authentication (Self-Signed Certificate Mutual-TLS Method)](https://www.rfc-editor.org/rfc/rfc8705.html#name-self-signed-certificate-mut)
diff --git a/docs/functions/TlsClientAuth.md b/docs/functions/TlsClientAuth.md
@@ -0,0 +1,22 @@
+# Function: TlsClientAuth()
+
+[💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+***
+
+▸ **TlsClientAuth**(): [`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md)
+
+**`tls_client_auth`** uses the HTTP request body to send only `client_id` as
+`application/x-www-form-urlencoded` body parameter and the mTLS key and certificate is configured
+through [customFetch](../variables/customFetch.md).
+
+## Returns
+
+[`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md)
+
+## See
+
+ - [OAuth Token Endpoint Authentication Methods](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-endpoint-auth-method)
+ - [RFC 8705 - OAuth 2.0 Mutual-TLS Client Authentication (PKI Mutual-TLS Method)](https://www.rfc-editor.org/rfc/rfc8705.html#name-pki-mutual-tls-method)
diff --git a/docs/functions/authorizationCodeGrantRequest.md b/docs/functions/authorizationCodeGrantRequest.md
@@ -6,7 +6,7 @@ Support from the community to continue maintaining and improving this module is
 
 ***
 
-▸ **authorizationCodeGrantRequest**(`as`, `client`, `callbackParameters`, `redirectUri`, `codeVerifier`, `options`?): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`Response`](https://developer.mozilla.org/docs/Web/API/Response)\>
+▸ **authorizationCodeGrantRequest**(`as`, `client`, `clientAuthentication`, `callbackParameters`, `redirectUri`, `codeVerifier`, `options`?): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`Response`](https://developer.mozilla.org/docs/Web/API/Response)\>
 
 Performs an Authorization Code grant request at the
 [`as.token_endpoint`](../interfaces/AuthorizationServer.md#token_endpoint).
@@ -17,6 +17,7 @@ Performs an Authorization Code grant request at the
 | ------ | ------ | ------ |
 | `as` | [`AuthorizationServer`](../interfaces/AuthorizationServer.md) | Authorization Server Metadata. |
 | `client` | [`Client`](../interfaces/Client.md) | Client Metadata. |
+| `clientAuthentication` | [`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md) | Client Authentication Method. |
 | `callbackParameters` | [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) | Parameters obtained from the callback to redirect_uri, this is returned from [validateAuthResponse](validateAuthResponse.md), or [validateJwtAuthResponse](validateJwtAuthResponse.md). |
 | `redirectUri` | `string` | `redirect_uri` value used in the authorization request. |
 | `codeVerifier` | `string` | PKCE `code_verifier` to send to the token endpoint. |

diff --git a/docs/functions/clientCredentialsGrantRequest.md b/docs/functions/clientCredentialsGrantRequest.md
@@ -6,7 +6,7 @@ Support from the community to continue maintaining and improving this module is
 
 ***
 
-▸ **clientCredentialsGrantRequest**(`as`, `client`, `parameters`, `options`?): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`Response`](https://developer.mozilla.org/docs/Web/API/Response)\>
+▸ **clientCredentialsGrantRequest**(`as`, `client`, `clientAuthentication`, `parameters`, `options`?): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`Response`](https://developer.mozilla.org/docs/Web/API/Response)\>
 
 Performs a Client Credentials Grant request at the
 [`as.token_endpoint`](../interfaces/AuthorizationServer.md#token_endpoint).
@@ -17,6 +17,7 @@ Performs a Client Credentials Grant request at the
 | ------ | ------ | ------ |
 | `as` | [`AuthorizationServer`](../interfaces/AuthorizationServer.md) | Authorization Server Metadata. |
 | `client` | [`Client`](../interfaces/Client.md) | Client Metadata. |
+| `clientAuthentication` | [`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md) | Client Authentication Method. |
 | `parameters` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)\<`string`, `string`\> \| [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) \| `string`[][] | - |
 | `options`? | [`ClientCredentialsGrantRequestOptions`](../interfaces/ClientCredentialsGrantRequestOptions.md) | - |
 

diff --git a/docs/functions/deviceAuthorizationRequest.md b/docs/functions/deviceAuthorizationRequest.md
@@ -6,7 +6,7 @@ Support from the community to continue maintaining and improving this module is
 
 ***
 
-▸ **deviceAuthorizationRequest**(`as`, `client`, `parameters`, `options`?): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`Response`](https://developer.mozilla.org/docs/Web/API/Response)\>
+▸ **deviceAuthorizationRequest**(`as`, `client`, `clientAuthentication`, `parameters`, `options`?): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`Response`](https://developer.mozilla.org/docs/Web/API/Response)\>
 
 Performs a Device Authorization Request at the
 [`as.device_authorization_endpoint`](../interfaces/AuthorizationServer.md#device_authorization_endpoint).
@@ -17,6 +17,7 @@ Performs a Device Authorization Request at the
 | ------ | ------ | ------ |
 | `as` | [`AuthorizationServer`](../interfaces/AuthorizationServer.md) | Authorization Server Metadata. |
 | `client` | [`Client`](../interfaces/Client.md) | Client Metadata. |
+| `clientAuthentication` | [`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md) | Client Authentication Method. |
 | `parameters` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)\<`string`, `string`\> \| [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) \| `string`[][] | Device Authorization Request parameters. |
 | `options`? | [`DeviceAuthorizationRequestOptions`](../interfaces/DeviceAuthorizationRequestOptions.md) | - |
 

diff --git a/docs/functions/deviceCodeGrantRequest.md b/docs/functions/deviceCodeGrantRequest.md
@@ -6,7 +6,7 @@ Support from the community to continue maintaining and improving this module is
 
 ***
 
-▸ **deviceCodeGrantRequest**(`as`, `client`, `deviceCode`, `options`?): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`Response`](https://developer.mozilla.org/docs/Web/API/Response)\>
+▸ **deviceCodeGrantRequest**(`as`, `client`, `clientAuthentication`, `deviceCode`, `options`?): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`Response`](https://developer.mozilla.org/docs/Web/API/Response)\>
 
 Performs a Device Authorization Grant request at the
 [`as.token_endpoint`](../interfaces/AuthorizationServer.md#token_endpoint).
@@ -17,6 +17,7 @@ Performs a Device Authorization Grant request at the
 | ------ | ------ | ------ |
 | `as` | [`AuthorizationServer`](../interfaces/AuthorizationServer.md) | Authorization Server Metadata. |
 | `client` | [`Client`](../interfaces/Client.md) | Client Metadata. |
+| `clientAuthentication` | [`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md) | Client Authentication Method. |
 | `deviceCode` | `string` | Device Code. |
 | `options`? | [`TokenEndpointRequestOptions`](../interfaces/TokenEndpointRequestOptions.md) | - |
 

diff --git a/docs/functions/genericTokenEndpointRequest.md b/docs/functions/genericTokenEndpointRequest.md
@@ -6,7 +6,7 @@ Support from the community to continue maintaining and improving this module is
 
 ***
 
-▸ **genericTokenEndpointRequest**(`as`, `client`, `grantType`, `parameters`, `options`?): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`Response`](https://developer.mozilla.org/docs/Web/API/Response)\>
+▸ **genericTokenEndpointRequest**(`as`, `client`, `clientAuthentication`, `grantType`, `parameters`, `options`?): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`Response`](https://developer.mozilla.org/docs/Web/API/Response)\>
 
 Performs any Grant request at the [`as.token_endpoint`](../interfaces/AuthorizationServer.md#token_endpoint).
 The purpose is to be able to execute grant requests such as Token Exchange Grant Type, JWT Bearer
@@ -18,6 +18,7 @@ Token Grant Type, or SAML 2.0 Bearer Assertion Grant Type.
 | ------ | ------ | ------ |
 | `as` | [`AuthorizationServer`](../interfaces/AuthorizationServer.md) | Authorization Server Metadata. |
 | `client` | [`Client`](../interfaces/Client.md) | Client Metadata. |
+| `clientAuthentication` | [`ClientAuthenticationImplementation`](../type-aliases/ClientAuthenticationImplementation.md) | Client Authentication Method. |
 | `grantType` | `string` | Grant Type. |
 | `parameters` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)\<`string`, `string`\> \| [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) \| `string`[][] | - |
 | `options`? | [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys)\<[`TokenEndpointRequestOptions`](../interfaces/TokenEndpointRequestOptions.md), `"additionalParameters"`\> | - |