Add authenticateWithCodeAndVerifier method for strict PKCE enforcement (#1297)

Author: nicknisi

src/user-management/interfaces/authenticate-with-code-and-verifier-options.interface.ts

@@ -0,0 +1,19 @@
+import {
+  AuthenticateWithOptionsBase,
+  SerializedAuthenticateWithPKCEBase,
+} from './authenticate-with-options-base.interface';
+
+export interface AuthenticateWithCodeAndVerifierOptions
+  extends AuthenticateWithOptionsBase {
+  codeVerifier: string;
+  code: string;
+  invitationToken?: string;
+}
+
+export interface SerializedAuthenticateWithCodeAndVerifierOptions
+  extends SerializedAuthenticateWithPKCEBase {
+  grant_type: 'authorization_code';
+  code_verifier: string;
+  code: string;
+  invitation_token?: string;
+}

src/user-management/interfaces/authenticate-with-options-base.interface.ts

@@ -16,3 +16,9 @@ export interface SerializedAuthenticateWithOptionsBase {
   ip_address?: string;
   user_agent?: string;
 }
+
+export interface SerializedAuthenticateWithPKCEBase {
+  client_id: string;
+  ip_address?: string;
+  user_agent?: string;
+}

src/user-management/interfaces/index.ts

@@ -1,4 +1,5 @@
 export * from './authenticate-with-code-options.interface';
+export * from './authenticate-with-code-and-verifier-options.interface';
 export * from './authenticate-with-email-verification-options.interface';
 export * from './authenticate-with-magic-auth-options.interface';
 export * from './authenticate-with-options-base.interface';

src/user-management/serializers/authenticate-with-code-and-verifier-options.serializer.ts

@@ -0,0 +1,16 @@
+import {
+  AuthenticateWithCodeAndVerifierOptions,
+  SerializedAuthenticateWithCodeAndVerifierOptions,
+} from '../interfaces';
+
+export const serializeAuthenticateWithCodeAndVerifierOptions = (
+  options: AuthenticateWithCodeAndVerifierOptions,
+): SerializedAuthenticateWithCodeAndVerifierOptions => ({
+  grant_type: 'authorization_code',
+  client_id: options.clientId,
+  code: options.code,
+  code_verifier: options.codeVerifier,
+  invitation_token: options.invitationToken,
+  ip_address: options.ipAddress,
+  user_agent: options.userAgent,
+});

src/user-management/serializers/index.ts

@@ -1,4 +1,5 @@
 export * from './authenticate-with-code-options.serializer';
+export * from './authenticate-with-code-and-verifier-options.serializer';
 export * from './authenticate-with-magic-auth-options.serializer';
 export * from './authenticate-with-password-options.serializer';
 export * from './authenticate-with-refresh-token.options.serializer';

src/user-management/user-management.spec.ts

@@ -465,6 +465,105 @@ describe('UserManagement', () => {
     });
   });
 
+  describe('authenticateWithCodeAndVerifier', () => {
+    it('sends a token authentication request with required code_verifier', async () => {
+      fetchOnce({ user: userFixture });
+      const resp = await workos.userManagement.authenticateWithCodeAndVerifier({
+        clientId: 'proj_whatever',
+        code: 'auth_code_123',
+        codeVerifier: 'required_code_verifier',
+      });
+
+      expect(fetchURL()).toContain('/user_management/authenticate');
+      expect(fetchBody()).toEqual({
+        client_id: 'proj_whatever',
+        code: 'auth_code_123',
+        code_verifier: 'required_code_verifier',
+        grant_type: 'authorization_code',
+      });
+
+      expect(resp).toMatchObject({
+        user: {
+          email: '[email protected]',
+        },
+      });
+    });
+
+    it('sends a token authentication request with invitation token', async () => {
+      fetchOnce({ user: userFixture });
+      const resp = await workos.userManagement.authenticateWithCodeAndVerifier({
+        clientId: 'proj_whatever',
+        code: 'auth_code_123',
+        codeVerifier: 'required_code_verifier',
+        invitationToken: 'invitation_123',
+      });
+
+      expect(fetchURL()).toContain('/user_management/authenticate');
+      expect(fetchBody()).toEqual({
+        client_id: 'proj_whatever',
+        code: 'auth_code_123',
+        code_verifier: 'required_code_verifier',
+        invitation_token: 'invitation_123',
+        grant_type: 'authorization_code',
+      });
+
+      expect(resp).toMatchObject({
+        user: {
+          email: '[email protected]',
+        },
+      });
+    });
+
+    describe('when sealSession = true', () => {
+      beforeEach(() => {
+        fetchOnce({
+          user: userFixture,
+          access_token:
+            'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJzdWIiOiAiMTIzNDU2Nzg5MCIsCiAgIm5hbWUiOiAiSm9obiBEb2UiLAogICJpYXQiOiAxNTE2MjM5MDIyLAogICJzaWQiOiAic2Vzc2lvbl8xMjMiLAogICJvcmdfaWQiOiAib3JnXzEyMyIsCiAgInJvbGUiOiAibWVtYmVyIiwKICAicGVybWlzc2lvbnMiOiBbInBvc3RzOmNyZWF0ZSIsICJwb3N0czpkZWxldGUiXQp9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
+        });
+      });
+
+      describe('when the cookie password is undefined', () => {
+        it('throws an error', async () => {
+          await expect(
+            workos.userManagement.authenticateWithCodeAndVerifier({
+              clientId: 'proj_whatever',
+              code: 'auth_code_123',
+              codeVerifier: 'required_code_verifier',
+              session: { sealSession: true },
+            }),
+          ).rejects.toThrow('Cookie password is required');
+        });
+      });
+
+      describe('when successfully authenticated', () => {
+        it('returns the sealed session data', async () => {
+          const cookiePassword = 'alongcookiesecretmadefortestingsessions';
+
+          const response =
+            await workos.userManagement.authenticateWithCodeAndVerifier({
+              clientId: 'proj_whatever',
+              code: 'auth_code_123',
+              codeVerifier: 'required_code_verifier',
+              session: { sealSession: true, cookiePassword },
+            });
+
+          expect(response).toEqual({
+            sealedSession: expect.any(String),
+            accessToken: expect.any(String),
+            authenticationMethod: undefined,
+            impersonator: undefined,
+            organizationId: undefined,
+            refreshToken: undefined,
+            user: expect.objectContaining({
+              email: '[email protected]',
+            }),
+          });
+        });
+      });
+    });
+  });
+
   describe('authenticateWithRefreshToken', () => {
     it('sends a refresh_token authentication request', async () => {
       fetchOnce({

src/user-management/user-management.ts

@@ -8,6 +8,7 @@ import { deserializeChallenge } from '../mfa/serializers';
 import { WorkOS } from '../workos';
 import {
   AuthenticateWithCodeOptions,
+  AuthenticateWithCodeAndVerifierOptions,
   AuthenticateWithMagicAuthOptions,
   AuthenticateWithPasswordOptions,
   AuthenticateWithRefreshTokenOptions,
@@ -32,6 +33,7 @@ import {
   SendPasswordResetEmailOptions,
   SendVerificationEmailOptions,
   SerializedAuthenticateWithCodeOptions,
+  SerializedAuthenticateWithCodeAndVerifierOptions,
   SerializedAuthenticateWithMagicAuthOptions,
   SerializedAuthenticateWithPasswordOptions,
   SerializedAuthenticateWithRefreshTokenOptions,
@@ -112,6 +114,7 @@ import {
   deserializePasswordReset,
   deserializeUser,
   serializeAuthenticateWithCodeOptions,
+  serializeAuthenticateWithCodeAndVerifierOptions,
   serializeAuthenticateWithMagicAuthOptions,
   serializeAuthenticateWithPasswordOptions,
   serializeAuthenticateWithRefreshTokenOptions,
@@ -315,6 +318,25 @@ export class UserManagement {
     });
   }
 
+  async authenticateWithCodeAndVerifier(
+    payload: AuthenticateWithCodeAndVerifierOptions,
+  ): Promise<AuthenticationResponse> {
+    const { session, ...remainingPayload } = payload;
+
+    const { data } = await this.workos.post<
+      AuthenticationResponseResponse,
+      SerializedAuthenticateWithCodeAndVerifierOptions
+    >(
+      '/user_management/authenticate',
+      serializeAuthenticateWithCodeAndVerifierOptions(remainingPayload),
+    );
+
+    return this.prepareAuthenticationResponse({
+      authenticationResponse: deserializeAuthenticationResponse(data),
+      session,
+    });
+  }
+
   async authenticateWithRefreshToken(
     payload: AuthenticateWithRefreshTokenOptions,
   ): Promise<AuthenticationResponse> {