refactor: enforce discriminated union for SSO authorization options

Apply strict typing to SSO authorization URL options, requiring exactly one of connection, organization, or provider to be specified at compile time. This prevents invalid parameter combinations that would previously fail at runtime.

Breaking change for TypeScript users: The SSOAuthorizationURLOptions type now uses a discriminated union pattern.

Author: nicknisi

src/client/sso.spec.ts

@@ -102,6 +102,7 @@ describe('Public SSO Methods', () => {
 
     it('throws error when no provider, connection, or organization specified', () => {
       expect(() => {
+        // @ts-expect-error Testing runtime validation with invalid input
         getAuthorizationUrl({
           clientId: 'client_123',
           redirectUri: 'https://app.com/callback',

src/client/sso.ts

@@ -1,17 +1,10 @@
 import { toQueryString } from './utils';
+import type { SSOAuthorizationURLOptions as BaseSSOAuthorizationURLOptions } from '../sso/interfaces';
 
-export interface SSOAuthorizationURLOptions {
-  clientId: string;
-  connection?: string;
-  organization?: string;
-  domainHint?: string;
-  loginHint?: string;
-  provider?: string;
-  providerQueryParams?: Record<string, string | boolean | number>;
-  providerScopes?: string[];
-  redirectUri: string;
-  state?: string;
-}
+// Extend the base options to include baseURL for internal use
+export type SSOAuthorizationURLOptions = BaseSSOAuthorizationURLOptions & {
+  baseURL?: string;
+};
 
 /**
  * Generates the authorization URL for SSO authentication.
@@ -22,7 +15,7 @@ export interface SSOAuthorizationURLOptions {
  * @throws Error if required arguments are missing
  */
 export function getAuthorizationUrl(
-  options: SSOAuthorizationURLOptions & { baseURL?: string },
+  options: SSOAuthorizationURLOptions,
 ): string {
   const {
     connection,

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

@@ -1,12 +1,32 @@
-export interface SSOAuthorizationURLOptions {
+interface SSOAuthorizationURLBase {
   clientId: string;
-  connection?: string;
-  organization?: string;
   domainHint?: string;
   loginHint?: string;
-  provider?: string;
   providerQueryParams?: Record<string, string | boolean | number>;
   providerScopes?: string[];
   redirectUri: string;
   state?: string;
 }
+
+interface SSOWithConnection extends SSOAuthorizationURLBase {
+  connection: string;
+  organization?: never;
+  provider?: never;
+}
+
+interface SSOWithOrganization extends SSOAuthorizationURLBase {
+  organization: string;
+  connection?: never;
+  provider?: never;
+}
+
+interface SSOWithProvider extends SSOAuthorizationURLBase {
+  provider: string;
+  connection?: never;
+  organization?: never;
+}
+
+export type SSOAuthorizationURLOptions =
+  | SSOWithConnection
+  | SSOWithOrganization
+  | SSOWithProvider;

src/sso/sso.spec.ts

@@ -70,6 +70,7 @@ describe('SSO', () => {
           const workos = new WorkOS('sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU');
 
           const urlFn = () =>
+            // @ts-expect-error Testing runtime validation with invalid input
             workos.sso.getAuthorizationUrl({
               clientId: 'proj_123',
               redirectUri: 'example.com/sso/workos/callback',

src/user-management/session.spec.ts

@@ -281,6 +281,53 @@ describe('Session', () => {
 
         expect(resp.authenticated).toBe(true);
       });
+
+      it('rotates refresh tokens when refreshing session', async () => {
+        const originalRefreshToken = 'original_refresh_token_123';
+        const newRefreshToken = 'new_refresh_token_456';
+        const accessToken =
+          'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ewogICJzdWIiOiAiMTIzNDU2Nzg5MCIsCiAgIm5hbWUiOiAiSm9obiBEb2UiLAogICJpYXQiOiAxNTE2MjM5MDIyLAogICJzaWQiOiAic2Vzc2lvbl8xMjMiLAogICJvcmdfaWQiOiAib3JnXzEyMyIsCiAgInJvbGUiOiAibWVtYmVyIiwKICAicGVybWlzc2lvbnMiOiBbInBvc3RzOmNyZWF0ZSIsICJwb3N0czpkZWxldGUiXQp9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
+
+        // Mock the API to return a new refresh token
+        fetchOnce({
+          user: userFixture,
+          accessToken,
+          refreshToken: newRefreshToken, // Different from original
+        });
+
+        const cookiePassword = 'alongcookiesecretmadefortestingsessions';
+
+        // Create initial session with original refresh token
+        const sessionData = await sealData(
+          {
+            accessToken,
+            refreshToken: originalRefreshToken,
+            user: {
+              object: 'user',
+              id: 'user_01H5JQDV7R7ATEYZDEG0W5PRYS',
+              email: '[email protected]',
+            },
+          },
+          { password: cookiePassword },
+        );
+
+        const session = workos.userManagement.loadSealedSession({
+          sessionData,
+          cookiePassword,
+        });
+
+        const response = await session.refresh();
+
+        expect(response.authenticated).toBe(true);
+
+        if (!response.authenticated) {
+          throw new Error('Expected successful response');
+        }
+
+        // Verify we got a new sealed session (which proves the refresh token was rotated)
+        expect(response.sealedSession).toBeDefined();
+        expect(response.sealedSession).not.toBe(sessionData);
+      });
     });
   });