@imtbl/auth 2.12.5 → 2.12.6-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imtbl/auth",
-  "version": "2.12.5",
+  "version": "2.12.6-alpha.1",
   "description": "Authentication SDK for Immutable",
   "author": "Immutable",
   "bugs": "https://github.com/immutable/ts-immutable-sdk/issues",
@@ -25,18 +25,18 @@
     }
   },
   "dependencies": {
-    "@imtbl/generated-clients": "2.12.5",
-    "@imtbl/metrics": "2.12.5",
+    "@imtbl/generated-clients": "2.12.6-alpha.1",
+    "@imtbl/metrics": "2.12.6-alpha.1",
     "localforage": "^1.10.0",
     "oidc-client-ts": "3.4.1"
   },
   "devDependencies": {
-    "@swc/core": "^1.3.36",
+    "@swc/core": "^1.4.2",
     "@swc/jest": "^0.2.37",
     "@types/jest": "^29.5.12",
-    "@types/node": "^18.14.2",
+    "@types/node": "^22.10.7",
     "@jest/test-sequencer": "^29.7.0",
-    "jest": "^29.4.3",
+    "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.4.3",
     "ts-node": "^10.9.1",
     "tsup": "^8.3.0",

package/src/Auth.test.ts

@@ -268,6 +268,231 @@ describe('Auth', () => {
     });
   });
 
+  describe('refreshTokenAndUpdatePromise', () => {
+    it('emits TOKEN_REFRESHED event when signinSilent succeeds', async () => {
+      const mockOidcUser = {
+        id_token: 'new-id',
+        access_token: 'new-access',
+        refresh_token: 'new-refresh',
+        expired: false,
+        profile: { sub: 'user-123', email: 'test@example.com', nickname: 'tester' },
+      };
+
+      (decodeJwtPayload as jest.Mock).mockReturnValue({
+        username: undefined,
+        passport: undefined,
+      });
+
+      const auth = Object.create(Auth.prototype) as Auth;
+      const mockEventEmitter = { emit: jest.fn() };
+      const mockUserManager = {
+        signinSilent: jest.fn().mockResolvedValue(mockOidcUser),
+      };
+
+      (auth as any).eventEmitter = mockEventEmitter;
+      (auth as any).userManager = mockUserManager;
+      (auth as any).refreshingPromise = null;
+
+      const user = await (auth as any).refreshTokenAndUpdatePromise();
+
+      expect(user).toBeDefined();
+      expect(user.accessToken).toBe('new-access');
+      expect(mockEventEmitter.emit).toHaveBeenCalledWith(
+        AuthEvents.TOKEN_REFRESHED,
+        expect.objectContaining({
+          accessToken: 'new-access',
+          refreshToken: 'new-refresh',
+        }),
+      );
+    });
+
+    it('does not emit TOKEN_REFRESHED event when signinSilent returns null', async () => {
+      const auth = Object.create(Auth.prototype) as Auth;
+      const mockEventEmitter = { emit: jest.fn() };
+      const mockUserManager = {
+        signinSilent: jest.fn().mockResolvedValue(null),
+      };
+
+      (auth as any).eventEmitter = mockEventEmitter;
+      (auth as any).userManager = mockUserManager;
+      (auth as any).refreshingPromise = null;
+
+      const user = await (auth as any).refreshTokenAndUpdatePromise();
+
+      expect(user).toBeNull();
+      expect(mockEventEmitter.emit).not.toHaveBeenCalled();
+    });
+
+    it('emits USER_REMOVED event for invalid_grant error', async () => {
+      const auth = Object.create(Auth.prototype) as Auth;
+      const mockEventEmitter = { emit: jest.fn() };
+      const mockUserManager = {
+        signinSilent: jest.fn().mockRejectedValue(
+          Object.assign(new Error('invalid_grant'), {
+            error: 'invalid_grant',
+            error_description: 'Unknown or invalid refresh token',
+          }),
+        ),
+        removeUser: jest.fn().mockResolvedValue(undefined),
+      };
+
+      // Make the error an instance of ErrorResponse
+      const { ErrorResponse } = jest.requireActual('oidc-client-ts');
+      const errorResponse = new ErrorResponse({
+        error: 'invalid_grant',
+        error_description: 'Unknown or invalid refresh token',
+      });
+      mockUserManager.signinSilent.mockRejectedValue(errorResponse);
+
+      (auth as any).eventEmitter = mockEventEmitter;
+      (auth as any).userManager = mockUserManager;
+      (auth as any).refreshingPromise = null;
+
+      await expect((auth as any).refreshTokenAndUpdatePromise()).rejects.toThrow();
+
+      expect(mockEventEmitter.emit).toHaveBeenCalledWith(
+        AuthEvents.USER_REMOVED,
+        expect.objectContaining({
+          reason: 'refresh_failed',
+        }),
+      );
+      expect(mockUserManager.removeUser).toHaveBeenCalled();
+    });
+
+    it('emits USER_REMOVED event for login_required error', async () => {
+      const auth = Object.create(Auth.prototype) as Auth;
+      const mockEventEmitter = { emit: jest.fn() };
+      const mockUserManager = {
+        signinSilent: jest.fn(),
+        removeUser: jest.fn().mockResolvedValue(undefined),
+      };
+
+      const { ErrorResponse } = jest.requireActual('oidc-client-ts');
+      const errorResponse = new ErrorResponse({
+        error: 'login_required',
+        error_description: 'User must re-authenticate',
+      });
+      mockUserManager.signinSilent.mockRejectedValue(errorResponse);
+
+      (auth as any).eventEmitter = mockEventEmitter;
+      (auth as any).userManager = mockUserManager;
+      (auth as any).refreshingPromise = null;
+
+      await expect((auth as any).refreshTokenAndUpdatePromise()).rejects.toThrow();
+
+      expect(mockEventEmitter.emit).toHaveBeenCalledWith(
+        AuthEvents.USER_REMOVED,
+        expect.objectContaining({
+          reason: 'refresh_failed',
+        }),
+      );
+      expect(mockUserManager.removeUser).toHaveBeenCalled();
+    });
+
+    it('emits USER_REMOVED event for network errors', async () => {
+      const auth = Object.create(Auth.prototype) as Auth;
+      const mockEventEmitter = { emit: jest.fn() };
+      const mockUserManager = {
+        signinSilent: jest.fn().mockRejectedValue(new Error('Network error: Failed to fetch')),
+        removeUser: jest.fn().mockResolvedValue(undefined),
+      };
+
+      (auth as any).eventEmitter = mockEventEmitter;
+      (auth as any).userManager = mockUserManager;
+      (auth as any).refreshingPromise = null;
+
+      await expect((auth as any).refreshTokenAndUpdatePromise()).rejects.toThrow();
+
+      expect(mockEventEmitter.emit).toHaveBeenCalledWith(
+        AuthEvents.USER_REMOVED,
+        expect.objectContaining({
+          reason: 'refresh_failed',
+        }),
+      );
+      expect(mockUserManager.removeUser).toHaveBeenCalled();
+    });
+
+    it('emits USER_REMOVED event for server_error OAuth error', async () => {
+      const auth = Object.create(Auth.prototype) as Auth;
+      const mockEventEmitter = { emit: jest.fn() };
+      const mockUserManager = {
+        signinSilent: jest.fn(),
+        removeUser: jest.fn().mockResolvedValue(undefined),
+      };
+
+      const { ErrorResponse } = jest.requireActual('oidc-client-ts');
+      const errorResponse = new ErrorResponse({
+        error: 'server_error',
+        error_description: 'Internal server error',
+      });
+      mockUserManager.signinSilent.mockRejectedValue(errorResponse);
+
+      (auth as any).eventEmitter = mockEventEmitter;
+      (auth as any).userManager = mockUserManager;
+      (auth as any).refreshingPromise = null;
+
+      await expect((auth as any).refreshTokenAndUpdatePromise()).rejects.toThrow();
+
+      expect(mockEventEmitter.emit).toHaveBeenCalledWith(
+        AuthEvents.USER_REMOVED,
+        expect.objectContaining({
+          reason: 'refresh_failed',
+        }),
+      );
+      expect(mockUserManager.removeUser).toHaveBeenCalled();
+    });
+
+    it('emits USER_REMOVED event for unknown errors (safer default)', async () => {
+      const auth = Object.create(Auth.prototype) as Auth;
+      const mockEventEmitter = { emit: jest.fn() };
+      const mockUserManager = {
+        signinSilent: jest.fn().mockRejectedValue(new Error('Some unknown error')),
+        removeUser: jest.fn().mockResolvedValue(undefined),
+      };
+
+      (auth as any).eventEmitter = mockEventEmitter;
+      (auth as any).userManager = mockUserManager;
+      (auth as any).refreshingPromise = null;
+
+      await expect((auth as any).refreshTokenAndUpdatePromise()).rejects.toThrow();
+
+      // Unknown errors should remove user (safer default)
+      expect(mockEventEmitter.emit).toHaveBeenCalledWith(
+        AuthEvents.USER_REMOVED,
+        expect.objectContaining({
+          reason: 'refresh_failed',
+        }),
+      );
+      expect(mockUserManager.removeUser).toHaveBeenCalled();
+    });
+
+    it('does not emit USER_REMOVED event for ErrorTimeout', async () => {
+      const auth = Object.create(Auth.prototype) as Auth;
+      const mockEventEmitter = { emit: jest.fn() };
+      const mockUserManager = {
+        signinSilent: jest.fn(),
+        removeUser: jest.fn().mockResolvedValue(undefined),
+      };
+
+      // Mock ErrorTimeout
+      const { ErrorTimeout } = jest.requireActual('oidc-client-ts');
+      const timeoutError = new ErrorTimeout('Silent sign-in timed out');
+      mockUserManager.signinSilent.mockRejectedValue(timeoutError);
+
+      (auth as any).eventEmitter = mockEventEmitter;
+      (auth as any).userManager = mockUserManager;
+      (auth as any).refreshingPromise = null;
+
+      await expect((auth as any).refreshTokenAndUpdatePromise()).rejects.toThrow();
+
+      expect(mockEventEmitter.emit).not.toHaveBeenCalledWith(
+        AuthEvents.USER_REMOVED,
+        expect.anything(),
+      );
+      expect(mockUserManager.removeUser).not.toHaveBeenCalled();
+    });
+  });
+
   describe('loginWithPopup', () => {
     let mockUserManager: any;
     let originalCryptoRandomUUID: any;

package/src/Auth.ts

@@ -30,6 +30,7 @@ import {
   IdTokenPayload,
   isUserZkEvm,
   EvmChain,
+  ChainAddress,
 } from './types';
 import EmbeddedLoginPrompt from './login/embeddedLoginPrompt';
 import TypedEventEmitter from './utils/typedEventEmitter';
@@ -41,6 +42,7 @@ import logger from './utils/logger';
 import { isAccessTokenExpiredOrExpiring } from './utils/token';
 import LoginPopupOverlay from './overlay/loginPopupOverlay';
 import { LocalForageAsyncStorage } from './storage/LocalForageAsyncStorage';
+import { buildLogoutUrl } from './logout';
 
 const formUrlEncodedHeaders = {
   'Content-Type': 'application/x-www-form-urlencoded',
@@ -75,13 +77,12 @@ const extractTokenErrorMessage = (
   return `Token request failed with status ${status}`;
 };
 
-const logoutEndpoint = '/v2/logout';
-const crossSdkBridgeLogoutEndpoint = '/im-logged-out';
-const authorizeEndpoint = '/authorize';
+const toChainAddress = (ethAddress: string, userAdminAddress: string): ChainAddress => ({
+  ethAddress: ethAddress as `0x${string}`,
+  userAdminAddress: userAdminAddress as `0x${string}`,
+});
 
-const getLogoutEndpointPath = (crossSdkBridgeEnabled: boolean): string => (
-  crossSdkBridgeEnabled ? crossSdkBridgeLogoutEndpoint : logoutEndpoint
-);
+const authorizeEndpoint = '/authorize';
 
 const getAuthConfiguration = (config: IAuthConfiguration): UserManagerSettings => {
   const { authenticationDomain, oidcConfiguration } = config;
@@ -96,14 +97,12 @@ const getAuthConfiguration = (config: IAuthConfiguration): UserManagerSettings =
   }
   const userStore = new WebStorageStateStore({ store });
 
-  const endSessionEndpoint = new URL(
-    getLogoutEndpointPath(config.crossSdkBridgeEnabled),
-    authenticationDomain.replace(/^(?:https?:\/\/)?(.*)/, 'https://$1'),
-  );
-  endSessionEndpoint.searchParams.set('client_id', oidcConfiguration.clientId);
-  if (oidcConfiguration.logoutRedirectUri) {
-    endSessionEndpoint.searchParams.set('returnTo', oidcConfiguration.logoutRedirectUri);
-  }
+  const endSessionEndpoint = buildLogoutUrl({
+    clientId: oidcConfiguration.clientId,
+    authenticationDomain,
+    logoutRedirectUri: oidcConfiguration.logoutRedirectUri,
+    crossSdkBridgeEnabled: config.crossSdkBridgeEnabled,
+  });
 
   return {
     authority: authenticationDomain,
@@ -114,7 +113,7 @@ const getAuthConfiguration = (config: IAuthConfiguration): UserManagerSettings =
       authorization_endpoint: `${authenticationDomain}/authorize`,
       token_endpoint: `${authenticationDomain}/oauth/token`,
       userinfo_endpoint: `${authenticationDomain}/userinfo`,
-      end_session_endpoint: endSessionEndpoint.toString(),
+      end_session_endpoint: endSessionEndpoint,
       revocation_endpoint: `${authenticationDomain}/oauth/revoke`,
     },
     automaticSilentRenew: false,
@@ -573,20 +572,14 @@ export class Auth {
     };
 
     if (passport?.zkevm_eth_address && passport?.zkevm_user_admin_address) {
-      user.zkEvm = {
-        ethAddress: passport.zkevm_eth_address,
-        userAdminAddress: passport.zkevm_user_admin_address,
-      };
+      user.zkEvm = toChainAddress(passport.zkevm_eth_address, passport.zkevm_user_admin_address);
     }
 
     const chains = Object.values(EvmChain).filter((chain) => chain !== EvmChain.ZKEVM);
     for (const chain of chains) {
       const chainMetadata = passport?.[chain as Exclude<EvmChain, EvmChain.ZKEVM>];
       if (chainMetadata?.eth_address && chainMetadata?.user_admin_address) {
-        user[chain] = {
-          ethAddress: chainMetadata.eth_address,
-          userAdminAddress: chainMetadata.user_admin_address,
-        };
+        user[chain] = toChainAddress(chainMetadata.eth_address, chainMetadata.user_admin_address);
       }
     }
 
@@ -779,15 +772,21 @@ export class Auth {
         try {
           const newOidcUser = await this.userManager.signinSilent();
           if (newOidcUser) {
-            resolve(Auth.mapOidcUserToDomainModel(newOidcUser));
+            const user = Auth.mapOidcUserToDomainModel(newOidcUser);
+            // Emit TOKEN_REFRESHED event so consumers (e.g., auth-next-client) can sync
+            // the new tokens to their session. This is critical for refresh token
+            // rotation - without this, the server-side session may have stale tokens.
+            this.eventEmitter.emit(AuthEvents.TOKEN_REFRESHED, user);
+            resolve(user);
             return;
           }
           resolve(null);
         } catch (err) {
           let passportErrorType = PassportErrorType.AUTHENTICATION_ERROR;
           let errorMessage = 'Failed to refresh token';
+          // Default to REMOVING user - safer to log out on unknown errors
+          // Only keep user logged in for explicitly known transient errors
           let removeUser = true;
-
           if (err instanceof ErrorTimeout) {
             passportErrorType = PassportErrorType.SILENT_LOGIN_ERROR;
             errorMessage = `${errorMessage}: ${err.message}`;
@@ -802,6 +801,13 @@ export class Auth {
           }
 
           if (removeUser) {
+            // Emit USER_REMOVED event BEFORE removing user so consumers can react
+            // (e.g., auth-next-client can clear the NextAuth session)
+            this.eventEmitter.emit(AuthEvents.USER_REMOVED, {
+              reason: 'refresh_failed',
+              error: errorMessage,
+            });
+
             try {
               await this.userManager.removeUser();
             } catch (removeUserError) {

package/src/index.ts

@@ -19,9 +19,11 @@ export type {
   PassportMetadata,
   PassportChainMetadata,
   ChainAddress,
+  ZkEvmInfo,
   IdTokenPayload,
   PKCEData,
   AuthEventMap,
+  UserRemovedReason,
 } from './types';
 export {
   isUserZkEvm,
@@ -40,3 +42,28 @@ export {
 } from './errors';
 
 export { decodeJwtPayload } from './utils/jwt';
+
+// ============================================================================
+// Standalone Login Functions (stateless, for use with NextAuth or similar)
+// ============================================================================
+
+export {
+  loginWithPopup,
+  loginWithEmbedded,
+  loginWithRedirect,
+  handleLoginCallback,
+  type LoginConfig,
+  type TokenResponse,
+  type StandaloneLoginOptions,
+} from './login/standalone';
+
+// ============================================================================
+// Standalone Logout Functions (stateless, for use with NextAuth or similar)
+// ============================================================================
+
+export {
+  logoutWithRedirect,
+  logoutSilent,
+  buildLogoutUrl,
+  type LogoutConfig,
+} from './login/standalone';