feat: add a server metadata helper for checking PKCE support

panva · Oct 17, 2024 · ca34a91 · ca34a91
1 parent a704534
commit ca34a91
Show file tree

Hide file tree

Showing 11 changed files with 79 additions and 42 deletions.
diff --git a/README.md b/README.md
@@ -107,10 +107,7 @@ let parameters: Record<string, string> = {
   code_challenge_method: 'S256',
 }
 
-if (
-  config.serverMetadata().code_challenge_methods_supported?.includes('S256') !==
-  true
-) {
+if (!config.serverMetadata().supportsPKCE()) {
   /**
    * We cannot be sure the server supports PKCE so we're going to use state too.
    * Use of PKCE is backwards compatible even if the AS doesn't support it which

diff --git a/conformance/runner.ts b/conformance/runner.ts
@@ -295,14 +295,16 @@ export const flow = (options?: MacroOptions) => {
         ? lib.getDPoPHandle(client, await lib.randomDPoPKeyPair(ALG))
         : undefined
 
-      let code_challenge: string | undefined
-      let code_verifier: string | undefined
-      let code_challenge_method: string | undefined
-
-      if (response_type.includes('code')) {
-        code_verifier = lib.randomPKCECodeVerifier()
-        code_challenge = await lib.calculatePKCECodeChallenge(code_verifier)
-        code_challenge_method = 'S256'
+      const code_verifier = lib.randomPKCECodeVerifier()
+      const code_challenge = await lib.calculatePKCECodeChallenge(code_verifier)
+      const code_challenge_method = 'S256'
+
+      if (
+        !client.serverMetadata().supportsPKCE() &&
+        !response_type.includes('id_token')
+      ) {
+        options ||= {}
+        options.useState = true
       }
 
       const scope = getScope(variant)

diff --git a/docs/README.md b/docs/README.md
@@ -115,6 +115,7 @@ Support from the community to continue maintaining and improving this module is
 - [ModifyAssertionOptions](interfaces/ModifyAssertionOptions.md)
 - [MTLSEndpointAliases](interfaces/MTLSEndpointAliases.md)
 - [PrivateKey](interfaces/PrivateKey.md)
+- [ServerMetadataHelpers](interfaces/ServerMetadataHelpers.md)
 - [TokenEndpointResponse](interfaces/TokenEndpointResponse.md)
 - [TokenEndpointResponseHelpers](interfaces/TokenEndpointResponseHelpers.md)
 - [UserInfoAddress](interfaces/UserInfoAddress.md)

diff --git a/docs/interfaces/ConfigurationMethods.md b/docs/interfaces/ConfigurationMethods.md
@@ -12,10 +12,10 @@ Public methods available on a [Configuration](../classes/Configuration.md) insta
 
 ### serverMetadata()
 
-▸ **serverMetadata**(): [`Readonly`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype)\<[`ServerMetadata`](ServerMetadata.md)\>
+▸ **serverMetadata**(): [`Readonly`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype)\<[`ServerMetadata`](ServerMetadata.md)\> & [`ServerMetadataHelpers`](ServerMetadataHelpers.md)
 
 Used to retrieve the Authorization Server Metadata
 
 #### Returns
 
-[`Readonly`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype)\<[`ServerMetadata`](ServerMetadata.md)\>
+[`Readonly`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype)\<[`ServerMetadata`](ServerMetadata.md)\> & [`ServerMetadataHelpers`](ServerMetadataHelpers.md)
diff --git a/docs/interfaces/ServerMetadataHelpers.md b/docs/interfaces/ServerMetadataHelpers.md
@@ -0,0 +1,26 @@
+# Interface: ServerMetadataHelpers
+
+[💗 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).
+
+***
+
+## Methods
+
+### supportsPKCE()
+
+▸ **supportsPKCE**(`method`?): `boolean`
+
+Determines whether the Authorization Server supports a given Code Challenge
+Method
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `method`? | `string` | Code Challenge Method. Default is `S256` |
+
+#### Returns
+
+`boolean`
diff --git a/examples/jar.ts b/examples/jar.ts
@@ -43,11 +43,7 @@ let state!: string
    * of PKCE is backwards compatible even if the AS doesn't support it which is
    * why we're using it regardless.
    */
-  if (
-    config
-      .serverMetadata()
-      .code_challenge_methods_supported?.includes('S256') !== true
-  ) {
+  if (!config.serverMetadata().supportsPKCE()) {
     state = client.randomState()
     parameters.state = state
   }

diff --git a/examples/jarm.ts b/examples/jarm.ts
@@ -44,11 +44,7 @@ let state!: string
    * of PKCE is backwards compatible even if the AS doesn't support it which is
    * why we're using it regardless.
    */
-  if (
-    config
-      .serverMetadata()
-      .code_challenge_methods_supported?.includes('S256') !== true
-  ) {
+  if (!config.serverMetadata().supportsPKCE()) {
     state = client.randomState()
     parameters.state = state
   }

diff --git a/examples/oauth.ts b/examples/oauth.ts
@@ -42,11 +42,7 @@ let state!: string
    * of PKCE is backwards compatible even if the AS doesn't support it which is
    * why we're using it regardless.
    */
-  if (
-    config
-      .serverMetadata()
-      .code_challenge_methods_supported?.includes('S256') !== true
-  ) {
+  if (!config.serverMetadata().supportsPKCE()) {
     state = client.randomState()
     parameters.state = state
   }

diff --git a/examples/oidc.ts b/examples/oidc.ts
@@ -42,11 +42,7 @@ let nonce!: string
    * of PKCE is backwards compatible even if the AS doesn't support it which is
    * why we're using it regardless.
    */
-  if (
-    config
-      .serverMetadata()
-      .code_challenge_methods_supported?.includes('S256') !== true
-  ) {
+  if (!config.serverMetadata().supportsPKCE()) {
     nonce = client.randomNonce()
     parameters.nonce = nonce
   }

diff --git a/examples/par.ts b/examples/par.ts
@@ -42,11 +42,7 @@ let state!: string
    * of PKCE is backwards compatible even if the AS doesn't support it which is
    * why we're using it regardless.
    */
-  if (
-    config
-      .serverMetadata()
-      .code_challenge_methods_supported?.includes('S256') !== true
-  ) {
+  if (!config.serverMetadata().supportsPKCE()) {
     state = client.randomState()
     parameters.state = state
   }

diff --git a/src/index.ts b/src/index.ts
@@ -1449,6 +1449,35 @@ async function decrypt(
   )
 }
 
+export interface ServerMetadataHelpers {
+  /**
+   * Determines whether the Authorization Server supports a given Code Challenge
+   * Method
+   *
+   * @param method Code Challenge Method. Default is `S256`
+   */
+  supportsPKCE(method?: string): boolean
+}
+
+function getServerHelpers(metadata: Readonly<ServerMetadata>) {
+  return {
+    supportsPKCE: {
+      __proto__: null,
+      value(method = 'S256') {
+        return (
+          metadata.code_challenge_methods_supported?.includes(method) !== true
+        )
+      },
+    },
+  }
+}
+
+function addServerHelpers(
+  metadata: Readonly<ServerMetadata>,
+): asserts metadata is typeof metadata & ServerMetadataHelpers {
+  Object.defineProperties(metadata, getServerHelpers(metadata))
+}
+
 // private
 const kEntraId: unique symbol = Symbol()
 
@@ -1471,7 +1500,7 @@ export interface ConfigurationMethods {
   /**
    * Used to retrieve the Authorization Server Metadata
    */
-  serverMetadata(): Readonly<ServerMetadata>
+  serverMetadata(): Readonly<ServerMetadata> & ServerMetadataHelpers
 }
 
 /**
@@ -1651,8 +1680,10 @@ export class Configuration
   /**
    * @ignore
    */
-  serverMetadata(): Readonly<ServerMetadata> {
-    return structuredClone(int(this).as)
+  serverMetadata(): Readonly<ServerMetadata> & ServerMetadataHelpers {
+    const metadata = structuredClone(int(this).as)
+    addServerHelpers(metadata)
+    return metadata
   }
 
   /**