feat(@whook/oauth2): add pkce support

packages/whook-oauth2/src/__snapshots__/index.test.ts.snap

@@ -126,6 +126,7 @@ exports[`OAuth2 server with the code flow should produce new tokens 2`] = `
       },
       "a_grant_code",
       "http://redirect.example.com/yolo",
+      undefined,
     ],
   ],
   "oAuth2CodeCreateCalls": [],
@@ -179,7 +180,10 @@ exports[`OAuth2 server with the code flow should redirect with a code 2`] = `
         "userId": "2",
       },
       "http://redirect.example.com/yolo?a_param=a_value",
-      {},
+      {
+        "codeChallenge": "",
+        "codeChallengeMethod": "plain",
+      },
     ],
   ],
   "oAuth2PasswordCheckCalls": [],

packages/whook-oauth2/src/index.test.ts

@@ -35,6 +35,8 @@ import {
   getOAuth2AuthorizeRedirectURIParameter,
   getOAuth2AuthorizeScopeParameter,
   getOAuth2AuthorizeStateParameter,
+  getOAuth2AuthorizeCodeChallengeParameter,
+  getOAuth2AuthorizeCodeChallengeMethodParameter,
   initPostOAuth2Acknowledge,
   postOAuth2AcknowledgeDefinition,
   initPostOAuth2Token,
@@ -127,6 +129,8 @@ describe('OAuth2 server', () => {
         getOAuth2AuthorizeRedirectURIParameter,
         getOAuth2AuthorizeScopeParameter,
         getOAuth2AuthorizeStateParameter,
+        getOAuth2AuthorizeCodeChallengeParameter,
+        getOAuth2AuthorizeCodeChallengeMethodParameter,
       ].reduce(
         (parametersHash, { name, parameter }) => ({
           ...parametersHash,

packages/whook-oauth2/src/index.ts

@@ -5,6 +5,8 @@ import initGetOAuth2Authorize, {
   redirectURIParameter as getOAuth2AuthorizeRedirectURIParameter,
   scopeParameter as getOAuth2AuthorizeScopeParameter,
   stateParameter as getOAuth2AuthorizeStateParameter,
+  codeChallengeParameter as getOAuth2AuthorizeCodeChallengeParameter,
+  codeChallengeMethodParameter as getOAuth2AuthorizeCodeChallengeMethodParameter,
 } from './routes/getOAuth2Authorize.js';
 import initPostOAuth2Acknowledge, {
   definition as postOAuth2AcknowledgeDefinition,
@@ -22,7 +24,6 @@ import initOAuth2Granters, {
   OAUTH2_ERRORS_DESCRIPTORS,
 } from './services/oAuth2Granters.js';
 import initOAuth2ClientCredentialsGranter from './services/oAuth2ClientCredentialsGranter.js';
-import initOAuth2CodeGranter from './services/oAuth2CodeGranter.js';
 import initOAuth2PasswordGranter from './services/oAuth2PasswordGranter.js';
 import initOAuth2RefreshTokenGranter from './services/oAuth2RefreshTokenGranter.js';
 import initOAuth2TokenGranter from './services/oAuth2TokenGranter.js';
@@ -55,6 +56,11 @@ import {
   type AuthCookiesData,
   type AuthHandlersConfig,
 } from './services/authCookies.js';
+import initOAuth2CodeGranter, {
+  base64UrlEncode,
+  hashCodeVerifier,
+  type CodeChallengeMethod,
+} from './services/oAuth2CodeGranter.js';
 
 declare module 'yerror' {
   interface YErrorRegistry extends OAuth2YErrorRegistry {
@@ -64,6 +70,7 @@ declare module 'yerror' {
 
 export type {
   OAuth2YErrorRegistry,
+  CodeChallengeMethod,
   OAuth2CodeService,
   OAuth2PasswordService,
   OAuth2AccessTokenService,
@@ -85,6 +92,10 @@ export {
   getOAuth2AuthorizeRedirectURIParameter,
   getOAuth2AuthorizeScopeParameter,
   getOAuth2AuthorizeStateParameter,
+  getOAuth2AuthorizeCodeChallengeParameter,
+  getOAuth2AuthorizeCodeChallengeMethodParameter,
+  base64UrlEncode,
+  hashCodeVerifier,
   initPostOAuth2Acknowledge,
   postOAuth2AcknowledgeDefinition,
   initPostOAuth2Token,

packages/whook-oauth2/src/routes/__snapshots__/getOAuth2Authorize.test.ts.snap

@@ -11,7 +11,10 @@ exports[`getOAuth2Authorize should redirect 2`] = `
         "redirectURI": "https://www.example.com",
         "scope": "user",
       },
-      {},
+      {
+        "codeChallenge": "",
+        "codeChallengeMethod": "plain",
+      },
     ],
   ],
   "logCalls": [],

packages/whook-oauth2/src/routes/getOAuth2Authorize.ts

@@ -13,13 +13,38 @@ import {
   type OAuth2GranterService,
 } from '../services/oAuth2Granters.js';
 import { type LogService } from 'common-services';
+import { CODE_CHALLENGE_METHODS } from '../services/oAuth2CodeGranter.js';
 
 /* Architecture Note #1: OAuth2 authorize
 This endpoint simply redirect the user to the authentication
  server page by first checking the application details are
  fine.
 */
 
+export const codeChallengeParameter = {
+  name: 'code_challenge',
+  parameter: {
+    in: 'query',
+    name: 'code_challenge',
+    required: false,
+    schema: {
+      type: 'string',
+    },
+  },
+} as const satisfies WhookAPIParameterDefinition;
+export const codeChallengeMethodParameter = {
+  name: 'code_challenge_method',
+  parameter: {
+    in: 'query',
+    name: 'code_challenge_method',
+    required: false,
+    schema: {
+      type: 'string',
+      enum: CODE_CHALLENGE_METHODS as unknown as string[],
+    },
+  },
+} as const satisfies WhookAPIParameterDefinition;
+
 export const responseTypeParameter = {
   name: 'responseType',
   parameter: {
@@ -94,6 +119,8 @@ export const definition = {
       refersTo(redirectURIParameter),
       refersTo(scopeParameter),
       refersTo(stateParameter),
+      refersTo(codeChallengeParameter),
+      refersTo(codeChallengeMethodParameter),
     ],
     responses: {
       '302': {
@@ -158,6 +185,8 @@ async function initGetOAuth2Authorize({
       redirect_uri: demandedRedirectURI = '',
       scope: demandedScope = '',
       state,
+      code_challenge: codeChallenge = '',
+      code_challenge_method: codeChallengeMethod = 'plain',
       ...authorizeParameters
     },
   }: {
@@ -167,6 +196,8 @@ async function initGetOAuth2Authorize({
       redirect_uri?: string;
       scope?: string;
       state: string;
+      code_challenge?: string;
+      code_challenge_method?: string;
     } & Record<string, unknown>;
   }) => {
     const url = new URL(OAUTH2.authenticateURL);
@@ -182,6 +213,16 @@ async function initGetOAuth2Authorize({
         throw new YError('E_UNKNOWN_AUTHORIZER_TYPE', [responseType]);
       }
 
+      if (responseType === 'code') {
+        if (!codeChallenge) {
+          if (OAUTH2.forcePKCE) {
+            throw new YError('E_PKCE_REQUIRED', [responseType]);
+          }
+        }
+      } else if (codeChallenge) {
+        throw new YError('E_PKCE_NOT_SUPPORTED', [responseType]);
+      }
+
       const { applicationId, redirectURI, scope } = await (
         granter.authorizer as NonNullable<OAuth2GranterService['authorizer']>
       ).authorize(
@@ -190,7 +231,15 @@ async function initGetOAuth2Authorize({
           redirectURI: demandedRedirectURI,
           scope: demandedScope,
         },
-        camelCaseObjectProperties(authorizeParameters),
+        camelCaseObjectProperties({
+          ...authorizeParameters,
+          ...(responseType === 'code'
+            ? {
+                codeChallenge,
+                codeChallengeMethod,
+              }
+            : {}),
+        }),
       );
 
       url.searchParams.set('type', responseType);

packages/whook-oauth2/src/routes/postOAuth2Token.ts

@@ -42,6 +42,10 @@ export const authorizationCodeTokenRequestBodySchema = {
         pattern: '^https?://',
         format: 'uri',
       },
+      code_verifier: {
+        type: 'string',
+        pattern: '^[\\d\\w\\-/\\._~]+$',
+      },
     },
   },
 } as const satisfies WhookAPISchemaDefinition;

packages/whook-oauth2/src/services/__snapshots__/oAuth2CodeGranter.test.ts.snap

@@ -33,6 +33,7 @@ exports[`OAuth2CodeGranter should work with a complete valid flow 2`] = `
       },
       "yolo",
       "https://www.example.com/oauth2/code",
+      "",
     ],
   ],
   "oAuth2CodeCreateCalls": [
@@ -42,7 +43,10 @@ exports[`OAuth2CodeGranter should work with a complete valid flow 2`] = `
         "scope": "user",
       },
       "https://www.example.com/oauth2/code",
-      {},
+      {
+        "codeChallenge": "",
+        "codeChallengeMethod": "plain",
+      },
     ],
   ],
 }

packages/whook-oauth2/src/services/oAuth2CodeGranter.test.ts

@@ -1,10 +1,13 @@
 import { describe, test, beforeEach, jest, expect } from '@jest/globals';
 import { type WhookAuthenticationData } from '@whook/authorization';
-import initOAuth2CodeGranter from './oAuth2CodeGranter.js';
 import {
   type CheckApplicationService,
   type OAuth2CodeService,
 } from './oAuth2Granters.js';
+import initOAuth2CodeGranter, {
+  base64UrlEncode,
+  hashCodeVerifier,
+} from './oAuth2CodeGranter.js';
 
 describe('OAuth2CodeGranter', () => {
   const oAuth2Code = {
@@ -44,11 +47,17 @@ describe('OAuth2CodeGranter', () => {
       [name: string]: unknown;
     });
 
-    const authorizerResult = await oAuth2CodeGranter.authorizer?.authorize({
-      clientId: 'abbacaca-abba-caca-abba-cacaabbacaca',
-      redirectURI: 'https://www.example.com/oauth2/code',
-      scope: 'user',
-    });
+    const authorizerResult = await oAuth2CodeGranter.authorizer?.authorize(
+      {
+        clientId: 'abbacaca-abba-caca-abba-cacaabbacaca',
+        redirectURI: 'https://www.example.com/oauth2/code',
+        scope: 'user',
+      },
+      {
+        codeChallenge: '',
+        codeChallengeMethod: 'plain',
+      },
+    );
     const acknowledgerResult =
       await oAuth2CodeGranter.acknowledger?.acknowledge(
         {
@@ -60,14 +69,18 @@ describe('OAuth2CodeGranter', () => {
           redirectURI: 'https://www.example.com/oauth2/code',
           scope: 'user',
         },
-        {},
+        {
+          codeChallenge: '',
+          codeChallengeMethod: 'plain',
+        },
       );
     const authenticatorResult =
       await oAuth2CodeGranter.authenticator?.authenticate(
         {
           clientId: 'abbacaca-abba-caca-abba-cacaabbacaca',
           redirectURI: 'https://www.example.com/oauth2/code',
           code: 'yolo',
+          codeVerifier: '',
         },
         {
           applicationId: 'abbacaca-abba-caca-abba-cacaabbacaca',
@@ -94,6 +107,8 @@ describe('OAuth2CodeGranter', () => {
         },
         "authorizerResult": {
           "applicationId": "abbacaca-abba-caca-abba-cacaabbacaca",
+          "codeChallenge": "",
+          "codeChallengeMethod": "plain",
           "redirectURI": "https://www.example.com",
           "scope": "user",
         },
@@ -107,3 +122,54 @@ describe('OAuth2CodeGranter', () => {
     }).toMatchSnapshot();
   });
 });
+
+describe('base64UrlEncode()', () => {
+  test('should work like here  https://tools.ietf.org/html/rfc7636#appendix-A', () => {
+    expect(
+      base64UrlEncode(
+        Buffer.from([
+          116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 187,
+          186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 132, 141,
+          121,
+        ]),
+      ),
+    ).toEqual('dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk');
+  });
+});
+
+describe('base64UrlEncode()', () => {
+  test('should work with plain method', () => {
+    expect(
+      hashCodeVerifier(
+        Buffer.from('dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'),
+        'plain',
+      ),
+    ).toEqual(Buffer.from('dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'));
+  });
+
+  test('should work with S256 like here https://tools.ietf.org/html/rfc7636#appendix-A', () => {
+    expect(
+      hashCodeVerifier(
+        Buffer.from('dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'),
+        'S256',
+      ),
+    ).toEqual(
+      Buffer.from([
+        19, 211, 30, 150, 26, 26, 216, 236, 47, 22, 177, 12, 76, 152, 46, 8,
+        118, 168, 120, 173, 109, 241, 68, 86, 110, 225, 137, 74, 203, 112, 249,
+        195,
+      ]),
+    );
+  });
+
+  test('should work base64 url encode like here https://tools.ietf.org/html/rfc7636#appendix-A', () => {
+    expect(
+      base64UrlEncode(
+        hashCodeVerifier(
+          Buffer.from('dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'),
+          'S256',
+        ),
+      ),
+    ).toEqual('E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM');
+  });
+});