refactor: deprecate the useMtlsAlias symbol and options

panva · Sep 22, 2024 · d2b7cb0 · d2b7cb0
1 parent 60c9df4
commit d2b7cb0
Show file tree

Hide file tree

Showing 13 changed files with 128 additions and 224 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -190,7 +190,6 @@ Support from the community to continue maintaining and improving this module is
 - [RevocationRequestOptions](interfaces/RevocationRequestOptions.md)
 - [TokenEndpointRequestOptions](interfaces/TokenEndpointRequestOptions.md)
 - [TokenEndpointResponse](interfaces/TokenEndpointResponse.md)
-- [UseMTLSAliasOptions](interfaces/UseMTLSAliasOptions.md)
 - [UserInfoAddress](interfaces/UserInfoAddress.md)
 - [UserInfoRequestOptions](interfaces/UserInfoRequestOptions.md)
 - [UserInfoResponse](interfaces/UserInfoResponse.md)
@@ -222,4 +221,3 @@ Support from the community to continue maintaining and improving this module is
 - [skipAuthTimeCheck](variables/skipAuthTimeCheck.md)
 - [skipStateCheck](variables/skipStateCheck.md)
 - [skipSubjectCheck](variables/skipSubjectCheck.md)
-- [useMtlsAlias](variables/useMtlsAlias.md)
diff --git a/docs/interfaces/AuthenticatedRequestOptions.md b/docs/interfaces/AuthenticatedRequestOptions.md
@@ -8,14 +8,6 @@ Support from the community to continue maintaining and improving this module is
 
 ## Properties
 
-### \[useMtlsAlias\]?
-
-• `optional` **\[useMtlsAlias\]**: `boolean`
-
-See [useMtlsAlias](../variables/useMtlsAlias.md).
-
-***
-
 ### clientPrivateKey?
 
 • `optional` **clientPrivateKey**: [`CryptoKey`](https://developer.mozilla.org/docs/Web/API/CryptoKey) \| [`PrivateKey`](PrivateKey.md)

diff --git a/docs/interfaces/Client.md b/docs/interfaces/Client.md
@@ -124,6 +124,59 @@ requests. Default is `client_secret_basic`.
 Indicates the requirement for a client to use mutual TLS endpoint aliases defined by the AS
 where present. Default is `false`.
 
+When combined with [customFetch](../variables/customFetch.md) (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.
+
+#### Examples
+
+(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 }),
+})
+```
+
+(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)
+
 ***
 
 ### userinfo\_signed\_response\_alg?

diff --git a/docs/interfaces/ClientCredentialsGrantRequestOptions.md b/docs/interfaces/ClientCredentialsGrantRequestOptions.md
@@ -27,14 +27,6 @@ See [customFetch](../variables/customFetch.md).
 
 ***
 
-### \[useMtlsAlias\]?
-
-• `optional` **\[useMtlsAlias\]**: `boolean`
-
-See [useMtlsAlias](../variables/useMtlsAlias.md).
-
-***
-
 ### clientPrivateKey?
 
 • `optional` **clientPrivateKey**: [`CryptoKey`](https://developer.mozilla.org/docs/Web/API/CryptoKey) \| [`PrivateKey`](PrivateKey.md)

diff --git a/docs/interfaces/DeviceAuthorizationRequestOptions.md b/docs/interfaces/DeviceAuthorizationRequestOptions.md
@@ -27,14 +27,6 @@ See [customFetch](../variables/customFetch.md).
 
 ***
 
-### \[useMtlsAlias\]?
-
-• `optional` **\[useMtlsAlias\]**: `boolean`
-
-See [useMtlsAlias](../variables/useMtlsAlias.md).
-
-***
-
 ### clientPrivateKey?
 
 • `optional` **clientPrivateKey**: [`CryptoKey`](https://developer.mozilla.org/docs/Web/API/CryptoKey) \| [`PrivateKey`](PrivateKey.md)

diff --git a/docs/interfaces/IntrospectionRequestOptions.md b/docs/interfaces/IntrospectionRequestOptions.md
@@ -27,14 +27,6 @@ See [customFetch](../variables/customFetch.md).
 
 ***
 
-### \[useMtlsAlias\]?
-
-• `optional` **\[useMtlsAlias\]**: `boolean`
-
-See [useMtlsAlias](../variables/useMtlsAlias.md).
-
-***
-
 ### additionalParameters?
 
 • `optional` **additionalParameters**: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)\<`string`, `string`\> \| [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) \| `string`[][]

diff --git a/docs/interfaces/PushedAuthorizationRequestOptions.md b/docs/interfaces/PushedAuthorizationRequestOptions.md
@@ -27,14 +27,6 @@ See [customFetch](../variables/customFetch.md).
 
 ***
 
-### \[useMtlsAlias\]?
-
-• `optional` **\[useMtlsAlias\]**: `boolean`
-
-See [useMtlsAlias](../variables/useMtlsAlias.md).
-
-***
-
 ### clientPrivateKey?
 
 • `optional` **clientPrivateKey**: [`CryptoKey`](https://developer.mozilla.org/docs/Web/API/CryptoKey) \| [`PrivateKey`](PrivateKey.md)

diff --git a/docs/interfaces/RevocationRequestOptions.md b/docs/interfaces/RevocationRequestOptions.md
@@ -27,14 +27,6 @@ See [customFetch](../variables/customFetch.md).
 
 ***
 
-### \[useMtlsAlias\]?
-
-• `optional` **\[useMtlsAlias\]**: `boolean`
-
-See [useMtlsAlias](../variables/useMtlsAlias.md).
-
-***
-
 ### additionalParameters?
 
 • `optional` **additionalParameters**: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)\<`string`, `string`\> \| [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) \| `string`[][]

diff --git a/docs/interfaces/TokenEndpointRequestOptions.md b/docs/interfaces/TokenEndpointRequestOptions.md
@@ -27,14 +27,6 @@ See [customFetch](../variables/customFetch.md).
 
 ***
 
-### \[useMtlsAlias\]?
-
-• `optional` **\[useMtlsAlias\]**: `boolean`
-
-See [useMtlsAlias](../variables/useMtlsAlias.md).
-
-***
-
 ### additionalParameters?
 
 • `optional` **additionalParameters**: [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)\<`string`, `string`\> \| [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) \| `string`[][]

diff --git a/docs/interfaces/UseMTLSAliasOptions.md b/docs/interfaces/UseMTLSAliasOptions.md
diff --git a/docs/interfaces/UserInfoRequestOptions.md b/docs/interfaces/UserInfoRequestOptions.md
@@ -27,14 +27,6 @@ See [customFetch](../variables/customFetch.md).
 
 ***
 
-### \[useMtlsAlias\]?
-
-• `optional` **\[useMtlsAlias\]**: `boolean`
-
-See [useMtlsAlias](../variables/useMtlsAlias.md).
-
-***
-
 ### DPoP?
 
 • `optional` **DPoP**: [`DPoPOptions`](DPoPOptions.md)

diff --git a/docs/variables/useMtlsAlias.md b/docs/variables/useMtlsAlias.md