@imtbl/auth 2.12.5 → 2.12.6-alpha.1

package/src/logout/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Internal logout utilities shared between Auth class and standalone functions.
+ * NOT exported from package index - only used internally.
+ */
+
+const LOGOUT_ENDPOINT = '/v2/logout';
+const CROSS_SDK_BRIDGE_LOGOUT_ENDPOINT = '/im-logged-out';
+const DEFAULT_AUTH_DOMAIN = 'https://auth.immutable.com';
+
+/**
+ * Internal config for building logout URLs.
+ * Includes crossSdkBridgeEnabled for Auth class (Passport SDK).
+ * NOT exported publicly from the package.
+ */
+export interface InternalLogoutConfig {
+  /** The client ID for the application */
+  clientId: string;
+  /** The authentication domain (defaults to https://auth.immutable.com) */
+  authenticationDomain?: string;
+  /** The URI to redirect to after logout */
+  logoutRedirectUri?: string;
+  /** Whether cross-SDK bridge is enabled (internal to Auth class) */
+  crossSdkBridgeEnabled?: boolean;
+}
+
+/**
+ * Normalize authentication domain to ensure https:// prefix.
+ */
+function normalizeAuthDomain(domain: string): string {
+  return domain.replace(/^(?:https?:\/\/)?(.*)/, 'https://$1');
+}
+
+/**
+ * Build logout URL for federated logout.
+ * Used by both Auth class (with crossSdkBridgeEnabled) and standalone functions.
+ *
+ * @param config - Configuration for building the logout URL
+ * @returns The complete logout URL string
+ */
+export function buildLogoutUrl(config: InternalLogoutConfig): string {
+  const authDomain = normalizeAuthDomain(config.authenticationDomain || DEFAULT_AUTH_DOMAIN);
+  const endpoint = config.crossSdkBridgeEnabled
+    ? CROSS_SDK_BRIDGE_LOGOUT_ENDPOINT
+    : LOGOUT_ENDPOINT;
+
+  const url = new URL(endpoint, authDomain);
+  url.searchParams.set('client_id', config.clientId);
+  if (config.logoutRedirectUri) {
+    url.searchParams.set('returnTo', config.logoutRedirectUri);
+  }
+  return url.toString();
+}

package/src/types.ts

@@ -26,10 +26,12 @@ export enum EvmChain {
 }
 
 export type ChainAddress = {
-  ethAddress: string;
-  userAdminAddress: string;
+  ethAddress: `0x${string}`;
+  userAdminAddress: `0x${string}`;
 };
 
+export type ZkEvmInfo = ChainAddress;
+
 export type User = {
   idToken?: string;
   accessToken: string;
@@ -163,12 +165,44 @@ export type LoginOptions = {
 export enum AuthEvents {
   LOGGED_OUT = 'loggedOut',
   LOGGED_IN = 'loggedIn',
+  /**
+   * Emitted when tokens are refreshed via signinSilent().
+   * This is critical for refresh token rotation - when client-side refresh happens,
+   * the new tokens must be synced to server-side session to prevent race conditions.
+   */
+  TOKEN_REFRESHED = 'tokenRefreshed',
+  /**
+   * Emitted when the user is removed from local storage due to a permanent auth error.
+   * Only emitted for errors where the refresh token is truly invalid:
+   * - invalid_grant: refresh token expired, revoked, or already used
+   * - login_required: user must re-authenticate
+   * - consent_required / interaction_required: user must interact with auth server
+   *
+   * NOT emitted for transient errors (network, timeout, server errors) - user stays logged in.
+   * Consumers should sync this state by clearing their session (e.g., NextAuth signOut).
+   */
+  USER_REMOVED = 'userRemoved',
 }
 
+/**
+ * Error reason for USER_REMOVED event.
+ * Note: Network/timeout errors do NOT emit USER_REMOVED (user stays logged in),
+ * so 'network_error' is not a valid reason.
+ */
+export type UserRemovedReason =
+  // OAuth permanent errors (invalid_grant, login_required, etc.)
+  | 'refresh_token_invalid'
+  // Unknown non-OAuth errors
+  | 'refresh_failed'
+  // Fallback for truly unknown error types
+  | 'unknown';
+
 /**
  * Event map for typed event emitter
  */
 export interface AuthEventMap extends Record<string, any> {
   [AuthEvents.LOGGED_OUT]: [];
   [AuthEvents.LOGGED_IN]: [User];
+  [AuthEvents.TOKEN_REFRESHED]: [User];
+  [AuthEvents.USER_REMOVED]: [{ reason: UserRemovedReason; error?: string }];
 }