fix(pkce): improve validation and type safety

- Add empty codeVerifier validation to prevent silent bypass of PKCE flow
- Add PKCE field coupling types (codeChallenge + codeChallengeMethod must be set together)
- Standardize error types to TypeError for argument validation
- Add tests for empty/whitespace codeVerifier edge cases

Author: nicknisi

src/sso/interfaces/authorization-url-options.interface.ts

@@ -1,12 +1,13 @@
-interface SSOAuthorizationURLBase {
+/**
+ * PKCE fields must be provided together or not at all.
+ * Use workos.pkce.generate() to create a valid pair.
+ */
+type PKCEFields =
+  | { codeChallenge?: never; codeChallengeMethod?: never }
+  | { codeChallenge: string; codeChallengeMethod: 'S256' };
+
+interface SSOAuthorizationURLBaseFields {
   clientId: string;
-  /**
-   * PKCE code challenge for public clients.
-   * Generate using workos.pkce.generate() and pass the codeChallenge here.
-   */
-  codeChallenge?: string;
-  /** PKCE code challenge method. Use 'S256' (recommended). */
-  codeChallengeMethod?: 'S256';
   domainHint?: string;
   loginHint?: string;
   providerQueryParams?: Record<string, string | boolean | number>;
@@ -31,23 +32,26 @@ export interface SSOPKCEAuthorizationURLResult {
   codeVerifier: string;
 }
 
-interface SSOWithConnection extends SSOAuthorizationURLBase {
-  connection: string;
-  organization?: never;
-  provider?: never;
-}
+type SSOWithConnection = SSOAuthorizationURLBaseFields &
+  PKCEFields & {
+    connection: string;
+    organization?: never;
+    provider?: never;
+  };
 
-interface SSOWithOrganization extends SSOAuthorizationURLBase {
-  organization: string;
-  connection?: never;
-  provider?: never;
-}
+type SSOWithOrganization = SSOAuthorizationURLBaseFields &
+  PKCEFields & {
+    organization: string;
+    connection?: never;
+    provider?: never;
+  };
 
-interface SSOWithProvider extends SSOAuthorizationURLBase {
-  provider: string;
-  connection?: never;
-  organization?: never;
-}
+type SSOWithProvider = SSOAuthorizationURLBaseFields &
+  PKCEFields & {
+    provider: string;
+    connection?: never;
+    organization?: never;
+  };
 
 export type SSOAuthorizationURLOptions =
   | SSOWithConnection

src/sso/sso.spec.ts

@@ -620,6 +620,32 @@ describe('SSO', () => {
                 'or an API key configured on the WorkOS instance (for confidential clients).',
             );
           });
+
+          it('throws error when codeVerifier is an empty string', async () => {
+            await expect(
+              publicWorkos.sso.getProfileAndToken({
+                code: 'authorization_code',
+                clientId: 'proj_123',
+                codeVerifier: '',
+              }),
+            ).rejects.toThrow(
+              'codeVerifier cannot be an empty string. ' +
+                'Generate a valid PKCE pair using workos.pkce.generate().',
+            );
+          });
+
+          it('throws error when codeVerifier is whitespace only', async () => {
+            await expect(
+              publicWorkos.sso.getProfileAndToken({
+                code: 'authorization_code',
+                clientId: 'proj_123',
+                codeVerifier: '   ',
+              }),
+            ).rejects.toThrow(
+              'codeVerifier cannot be an empty string. ' +
+                'Generate a valid PKCE pair using workos.pkce.generate().',
+            );
+          });
         });
       });
     });

src/sso/sso.ts

@@ -68,7 +68,7 @@ export class SSO {
     } = options;
 
     if (!provider && !connection && !organization) {
-      throw new Error(
+      throw new TypeError(
         `Incomplete arguments. Need to specify either a 'connection', 'organization', or 'provider'.`,
       );
     }
@@ -193,11 +193,19 @@ export class SSO {
   }: GetProfileAndTokenOptions): Promise<
     ProfileAndToken<CustomAttributesType>
   > {
+    // Validate codeVerifier is not an empty string (common mistake)
+    if (codeVerifier !== undefined && codeVerifier.trim() === '') {
+      throw new TypeError(
+        'codeVerifier cannot be an empty string. ' +
+          'Generate a valid PKCE pair using workos.pkce.generate().',
+      );
+    }
+
     const usePublicClientFlow = !!codeVerifier;
     const hasApiKey = !!this.workos.key;
 
     if (!usePublicClientFlow && !hasApiKey) {
-      throw new Error(
+      throw new TypeError(
         'getProfileAndToken requires either a codeVerifier (for public clients) ' +
           'or an API key configured on the WorkOS instance (for confidential clients).',
       );

src/user-management/interfaces/authorization-url-options.interface.ts

@@ -1,12 +1,13 @@
-export interface UserManagementAuthorizationURLOptions {
+/**
+ * PKCE fields must be provided together or not at all.
+ * Use workos.pkce.generate() to create a valid pair.
+ */
+type PKCEFields =
+  | { codeChallenge?: never; codeChallengeMethod?: never }
+  | { codeChallenge: string; codeChallengeMethod: 'S256' };
+
+interface UserManagementAuthorizationURLBaseOptions {
   clientId: string;
-  /**
-   * PKCE code challenge for public clients.
-   * Generate using workos.pkce.generate() and pass the codeChallenge here.
-   */
-  codeChallenge?: string;
-  /** PKCE code challenge method. Use 'S256' (recommended). */
-  codeChallengeMethod?: 'S256';
   connectionId?: string;
   organizationId?: string;
   domainHint?: string;
@@ -20,6 +21,9 @@ export interface UserManagementAuthorizationURLOptions {
   screenHint?: 'sign-up' | 'sign-in';
 }
 
+export type UserManagementAuthorizationURLOptions =
+  UserManagementAuthorizationURLBaseOptions & PKCEFields;
+
 /**
  * Result of getAuthorizationUrlWithPKCE() containing the URL,
  * state, and PKCE code verifier.

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

@@ -382,6 +382,32 @@ describe('UserManagement', () => {
             'or an API key configured on the WorkOS instance (for confidential clients).',
         );
       });
+
+      it('throws error when codeVerifier is an empty string', async () => {
+        await expect(
+          publicWorkos.userManagement.authenticateWithCode({
+            clientId: 'proj_whatever',
+            code: 'some_code',
+            codeVerifier: '',
+          }),
+        ).rejects.toThrow(
+          'codeVerifier cannot be an empty string. ' +
+            'Generate a valid PKCE pair using workos.pkce.generate().',
+        );
+      });
+
+      it('throws error when codeVerifier is whitespace only', async () => {
+        await expect(
+          publicWorkos.userManagement.authenticateWithCode({
+            clientId: 'proj_whatever',
+            code: 'some_code',
+            codeVerifier: '   ',
+          }),
+        ).rejects.toThrow(
+          'codeVerifier cannot be an empty string. ' +
+            'Generate a valid PKCE pair using workos.pkce.generate().',
+        );
+      });
     });
 
     it('deserializes authentication_method', async () => {

src/user-management/user-management.ts

@@ -306,11 +306,19 @@ export class UserManagement {
   ): Promise<AuthenticationResponse> {
     const { session, codeVerifier, ...remainingPayload } = payload;
 
+    // Validate codeVerifier is not an empty string (common mistake)
+    if (codeVerifier !== undefined && codeVerifier.trim() === '') {
+      throw new TypeError(
+        'codeVerifier cannot be an empty string. ' +
+          'Generate a valid PKCE pair using workos.pkce.generate().',
+      );
+    }
+
     const usePublicClientFlow = !!codeVerifier;
     const hasApiKey = !!this.workos.key;
 
     if (!usePublicClientFlow && !hasApiKey) {
-      throw new Error(
+      throw new TypeError(
         'authenticateWithCode requires either a codeVerifier (for public clients) ' +
           'or an API key configured on the WorkOS instance (for confidential clients).',
       );