@civic/auth 0.8.2 → 0.9.0-beta.1

package/dist/vanillajs/auth/CivicAuth.js

@@ -8,7 +8,7 @@ import { AuthenticationEvents } from "./AuthenticationEvents.js";
 import { PopupError } from "../../services/types.js";
 import { getVersion } from "../../shared/index.js";
 import { handleOAuthRedirectPage } from "./handlers/OAuthCallbackHandler.js";
-import { generateOauthLogoutUrl, clearTokens, retrieveTokens, } from "../../shared/lib/util.js";
+import { generateOauthLogoutUrl, clearTokens, retrieveTokens, getBackendEndpoints, } from "../../shared/lib/util.js";
 import { LOGOUT_STATE } from "../../constants.js";
 import { getOauthEndpoints } from "../../lib/oauth.js";
 import { collectAndSendSDKAnalytics } from "../../lib/analytics.js";
@@ -17,6 +17,7 @@ import { processConfigWithDefaults } from "./config/ConfigProcessor.js";
 import { MessageHandler } from "./handlers/MessageHandler.js";
 import { PopupHandler } from "./handlers/PopupHandler.js";
 import { IframeAuthHandler } from "./handlers/IframeAuthHandler.js";
+import { IframeManager } from "../iframe/IframeManager.js";
 /**
  * CivicAuth client for handling OAuth authentication
  *
@@ -37,6 +38,9 @@ export class CivicAuth {
     authProcessTimeoutHandle;
     popupFailureTimeoutHandle;
     hasPopupFailed = false;
+    hasSignInStarted = false;
+    // Backend integration - custom login URL
+    loginUrl;
     // Handlers
     messageHandler;
     popupHandler;
@@ -49,6 +53,8 @@ export class CivicAuth {
         // Process config with defaults and validation
         this.config = processConfigWithDefaults(config);
         this.initialDisplayMode = this.config.displayMode;
+        // Set loginUrl from config if provided
+        this.loginUrl = this.config.loginUrl;
         // Configure logging
         configureLogging(this.config.logging);
         // Initialize logger - always use "vanillajs" as base namespace
@@ -68,7 +74,7 @@ export class CivicAuth {
         // Always initialize events - use provided events or create default instance
         this.events = config.events || new AuthenticationEvents();
         // Always initialize SessionManager
-        this.sessionManager = new SessionManager(this.storage, this.events);
+        this.sessionManager = new SessionManager(this.storage, this.events, this.config);
         // Initialize handlers
         this.initializeHandlers();
     }
@@ -82,6 +88,7 @@ export class CivicAuth {
      *
      * @example
      * ```typescript
+     * // Standard SPA authentication
      * const auth = await CivicAuth.create({
      *   clientId: "your-client-id",
      *   // redirectUrl is optional - defaults to current page (window.location.origin + window.location.pathname)
@@ -97,6 +104,12 @@ export class CivicAuth {
      *     success: "Authentication successful!"
      *   }
      * });
+     *
+     * // Backend integration authentication
+     * const authWithBackend = await CivicAuth.create({
+     *   clientId: "your-client-id",
+     *   loginUrl: "http://example.com/custom-backendurl" // Automatically uses BrowserCookieStorage
+     * });
      * ```
      */
     static async create(config) {
@@ -128,6 +141,8 @@ export class CivicAuth {
                     oauthServer: this.config.oauthServerBaseUrl,
                     scopes: this.config.scopes,
                     endpoints: this.endpoints,
+                    loginUrl: this.config.loginUrl || this.loginUrl, // Include loginUrl for backend flows
+                    backendEndpoints: this.config.backendEndpoints, // Pass backend endpoints config
                 };
                 this.logger.info("🔧 Initializing SessionManager", { authConfig });
                 await this.sessionManager.initializeWithAuthConfig(authConfig);
@@ -148,6 +163,43 @@ export class CivicAuth {
             else {
                 this.logger.info("🏠 Not a callback page, initialization complete");
             }
+            // Automatically preload iframe if enabled and user is not authenticated
+            // This runs after both callback processing and normal initialization
+            this.logger.info("🔍 Checking auto-preload conditions", {
+                preloadIframe: this.config.preloadIframe,
+                displayMode: this.config.displayMode,
+            });
+            if (this.config.preloadIframe && this.config.displayMode === "iframe") {
+                try {
+                    const isAuthenticated = await this.isAuthenticated();
+                    this.logger.info("🔍 Authentication check for preload", {
+                        isAuthenticated,
+                    });
+                    if (!isAuthenticated) {
+                        this.logger.info("🔄 Auto-preloading iframe for instant sign-in...");
+                        await this.preloadAuthentication();
+                        this.logger.info("✅ Iframe auto-preloaded successfully");
+                    }
+                    else {
+                        this.logger.debug("ℹ️ User already authenticated, skipping preload");
+                    }
+                }
+                catch (error) {
+                    // Don't fail initialization if preloading fails - graceful degradation
+                    this.logger.warn("⚠️ Auto-preloading failed (graceful degradation):", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            else {
+                this.logger.info("ℹ️ Auto-preload conditions not met", {
+                    preloadIframe: this.config.preloadIframe,
+                    displayMode: this.config.displayMode,
+                    reason: !this.config.preloadIframe
+                        ? "preloadIframe is disabled"
+                        : "displayMode is not iframe",
+                });
+            }
         }
         catch (error) {
             const errorMessage = error instanceof Error
@@ -177,17 +229,77 @@ export class CivicAuth {
         this.messageHandler = new MessageHandler({
             ...handlerConfig,
             onPopupFailure: this.handlePopupFailure.bind(this),
+            onBrowserCorsFailsSilently: async () => {
+                if (this.hasSignInStarted) {
+                    await this.handleBrowserCorsFailsSilently();
+                }
+            },
         });
         this.popupHandler = new PopupHandler(handlerConfig);
         this.iframeAuthHandler = new IframeAuthHandler({
             ...handlerConfig,
             messageHandler: this.messageHandler.handleMessage,
         });
+        // Set up automatic re-preloading when authentication is cancelled
+        this.setupAutoRepreload();
+    }
+    /**
+     * Set up automatic re-preloading when authentication is cancelled by user
+     * This maintains instant sign-in experience for subsequent attempts
+     */
+    setupAutoRepreload() {
+        this.events.on(AuthEvent.SIGN_IN_STARTED, () => {
+            this.hasSignInStarted = true;
+        });
+        this.events.on(AuthEvent.SIGN_IN_ERROR, (event) => {
+            // Only re-preload for iframe mode with user cancellation and preload enabled
+            if (this.config.displayMode === "iframe" &&
+                this.config.preloadIframe &&
+                event?.detail === "Authentication cancelled by user") {
+                this.logger.debug("🔄 Authentication cancelled, scheduling re-preload for instant subsequent sign-in");
+                // Small delay to ensure cleanup is complete
+                setTimeout(async () => {
+                    try {
+                        await this.preloadAuthentication();
+                        this.logger.debug("✅ Re-preloaded iframe after cancellation for instant sign-in");
+                    }
+                    catch (error) {
+                        // Don't fail silently, but don't crash either - just log the issue
+                        this.logger.warn("⚠️ Failed to re-preload iframe after cancellation:", {
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }, 200); // Small delay to ensure cleanup completion
+            }
+        });
     }
     /**
      * Builds the authentication URL with PKCE challenge
      */
     async buildAuthUrl() {
+        // If a login URL is set (for backend integration), use that instead
+        if (this.loginUrl) {
+            this.logger.info("🔗 Using login URL for backend integration", {
+                loginUrl: this.loginUrl,
+            });
+            // Generate state with display mode information for backend integration
+            const state = this.config.initialState ||
+                generateState({
+                    displayMode: this.config.displayMode || "iframe",
+                    iframeDisplayMode: this.config.iframeDisplayMode,
+                    framework: this.config.framework || "vanillajs",
+                    sdkVersion: getVersion(),
+                });
+            // Append state as query parameter to loginUrl
+            const url = new URL(this.loginUrl, window.location.origin);
+            url.searchParams.set("state", state);
+            this.logger.info("🔗 Built login URL with display mode state", {
+                loginUrl: url.toString(),
+                displayMode: this.config.displayMode,
+                iframeDisplayMode: this.config.iframeDisplayMode,
+            });
+            return url.toString();
+        }
         if (!this.endpoints) {
             throw new CivicAuthError("OAuth endpoints not initialized. Please wait for initialization to complete.", CivicAuthErrorCode.ENDPOINTS_NOT_INITIALIZED);
         }
@@ -196,6 +308,7 @@ export class CivicAuth {
         const state = this.config.initialState ||
             generateState({
                 displayMode: this.config.displayMode || "iframe",
+                iframeDisplayMode: this.config.iframeDisplayMode,
                 framework: this.config.framework || "vanillajs",
                 sdkVersion: getVersion(),
             });
@@ -210,6 +323,102 @@ export class CivicAuth {
             nonce: this.config.nonce,
         });
     }
+    /**
+     * Preloads the authentication iframe for instant sign-in
+     * This creates the iframe in the background but keeps it hidden until startAuthentication() is called
+     * @throws {CivicAuthError} If preloading fails or is not supported
+     * @private - This method is used internally for automatic preloading
+     */
+    async preloadAuthentication() {
+        this.logger.info("🎬 Preloading authentication for instant sign-in", {
+            displayMode: this.config.displayMode,
+            userAgent: navigator.userAgent,
+            currentUrl: window.location.href,
+        });
+        if (!this.endpoints) {
+            const error = new CivicAuthError("OAuth endpoints not initialized. Please wait for initialization to complete.", CivicAuthErrorCode.ENDPOINTS_NOT_INITIALIZED);
+            this.logger.error("❌ Endpoints not initialized for preload", {
+                error: error.message,
+            });
+            throw error;
+        }
+        // Only support preloading for iframe mode
+        if (this.config.displayMode !== "iframe") {
+            this.logger.warn("⚠️ Iframe preloading only supported for iframe display mode", {
+                displayMode: this.config.displayMode,
+            });
+            return;
+        }
+        if (!this.iframeAuthHandler) {
+            const error = new CivicAuthError("Iframe handler not initialized for preloading", CivicAuthErrorCode.INIT_FAILED);
+            this.logger.error("❌ Iframe handler not initialized", {
+                error: error.message,
+            });
+            throw error;
+        }
+        const fullAuthUrl = await this.buildAuthUrl();
+        this.logger.info("🔗 Built authentication URL for preload", {
+            url: fullAuthUrl,
+            displayMode: this.config.displayMode,
+        });
+        try {
+            await this.iframeAuthHandler.preloadIframe(fullAuthUrl);
+            const iframeElement = this.iframeAuthHandler.getIframeElement();
+            if (iframeElement) {
+                this.messageHandler?.updateIframeElement(iframeElement);
+            }
+            this.logger.info("✅ Authentication iframe preloaded successfully");
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Failed to preload iframe";
+            this.logger.error("❌ Failed to preload authentication iframe", {
+                error: errorMessage,
+            });
+            throw new CivicAuthError(errorMessage, CivicAuthErrorCode.IFRAME_PRELOAD_FAILED);
+        }
+    }
+    /**
+     * Check if authentication is preloaded and ready for instant sign-in
+     * @returns True if an iframe is preloaded and ready
+     */
+    isAuthenticationPreloaded() {
+        if (this.config.displayMode !== "iframe" || !this.iframeAuthHandler) {
+            return false;
+        }
+        return this.iframeAuthHandler.hasPreloadedIframe();
+    }
+    /**
+     * Enable or disable iframe preloading
+     * @param enabled Whether to enable iframe preloading
+     */
+    setPreloadEnabled(enabled) {
+        // Preloading only makes sense for iframe mode
+        if (this.config.displayMode !== "iframe") {
+            this.logger.debug("🎯 Iframe preloading not applicable for non-iframe mode", {
+                displayMode: this.config.displayMode,
+                enabled,
+            });
+            return;
+        }
+        if (this.iframeAuthHandler) {
+            this.iframeAuthHandler.setPreloadEnabled(enabled);
+            this.logger.info("🎯 Iframe preloading", { enabled });
+        }
+        else {
+            this.logger.warn("⚠️ Cannot set preload enabled: iframe handler not initialized");
+        }
+    }
+    /**
+     * Check if iframe preloading is enabled
+     * @returns True if iframe preloading is enabled
+     */
+    getPreloadEnabled() {
+        // Preloading only makes sense for iframe mode
+        if (this.config.displayMode !== "iframe") {
+            return false;
+        }
+        return this.iframeAuthHandler?.getPreloadEnabled() ?? false;
+    }
     /**
      * Starts the authentication process
      * @returns A promise that resolves with the authentication result
@@ -252,6 +461,30 @@ export class CivicAuth {
         });
         return this.authPromise;
     }
+    async handleBrowserCorsFailsSilently() {
+        this.logger.warn("🚨 Browser CORS fails silently - switching to redirect mode", {
+            displayMode: this.config.displayMode,
+            iframeAuthHandler: !!this.iframeAuthHandler,
+            messageHandler: !!this.messageHandler,
+        });
+        if (!this.iframeAuthHandler || !this.messageHandler) {
+            throw new Error("Iframe handler not initialized");
+        }
+        this.iframeAuthHandler.forceHideIframe();
+        const rebuiltUrl = await this.buildAuthUrl();
+        this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
+            detail: "Browser doesn't support popups and passkey with CORS in iframe - switching to redirect mode",
+            error: {
+                type: "browser_cors_fails_silently",
+                failedUrl: IframeManager.browserCorsFailsSilentlyUrl,
+                suggestion: "Browser doesn't support popups and passkey with CORS in iframe - switching to redirect mode",
+            },
+        });
+        // use a small delay to ensure the loader is shown
+        setTimeout(() => {
+            window.location.href = rebuiltUrl;
+        }, 100);
+    }
     /**
      * Handle authentication based on display mode
      */
@@ -278,6 +511,9 @@ export class CivicAuth {
                     if (!this.iframeAuthHandler || !this.messageHandler) {
                         throw new Error("Iframe handler not initialized");
                     }
+                    if (IframeManager.browserCorsFailsSilentlyUrl) {
+                        return this.handleBrowserCorsFailsSilently();
+                    }
                     const iframeElement = await this.iframeAuthHandler.handleIframeAuth(fullAuthUrl);
                     this.messageHandler.updateIframeElement(iframeElement);
                     break;
@@ -341,19 +577,15 @@ export class CivicAuth {
             });
             return;
         }
+        // Set up timeout for other modes
         if (this.config.authProcessTimeout && this.config.authProcessTimeout > 0) {
             this.logger.debug("⏰ Setting up authentication timeout", {
-                authProcessTimeout: this.config.authProcessTimeout,
+                timeout: this.config.authProcessTimeout,
                 displayMode: this.config.displayMode,
                 iframeDisplayMode: this.config.iframeDisplayMode,
             });
             this.authProcessTimeoutHandle = window.setTimeout(() => {
-                this.logger.error("⏰ Authentication timed out", {
-                    displayMode: this.config.displayMode,
-                    iframeDisplayMode: this.config.iframeDisplayMode,
-                    currentOrigin: window.location.origin,
-                    authProcessTimeout: this.config.authProcessTimeout,
-                });
+                this.logger.info("⏰ Authentication timeout reached");
                 this.events.emit(AuthEvent.SIGN_IN_ERROR, {
                     detail: "Authentication timed out",
                 });
@@ -599,6 +831,54 @@ export class CivicAuth {
     getTokenRefresherState() {
         return this.sessionManager.getTokenRefresherState() || null;
     }
+    /**
+     * Set a custom login URL for backend integration.
+     * This is useful when integrating with a backend that handles the OAuth flow.
+     * Alternatively, you can configure this directly in CivicAuth.create().
+     *
+     * @param loginUrl - The custom login URL to use (e.g., "http://localhost:3020/auth/login")
+     *
+     * @example
+     * ```typescript
+     * // Option 1: Configure in create()
+     * const authClient = await CivicAuth.create({
+     *   clientId: "YOUR_CLIENT_ID",
+     *   loginUrl: "http://example.com/custom-backendurl"
+     * });
+     *
+     * // Option 2: Set after creation
+     * civicAuth.setLoginUrl("http://localhost:3020/auth/login");
+     * await civicAuth.startAuthentication();
+     * ```
+     */
+    setLoginUrl(loginUrl) {
+        this.loginUrl = loginUrl;
+        // Update MessageHandler to expect messages from the custom origin
+        if (this.messageHandler) {
+            this.messageHandler.setCustomExpectedOrigin(loginUrl);
+        }
+        this.logger.info("🔗 Custom login URL set for backend integration", {
+            loginUrl: this.loginUrl,
+        });
+    }
+    /**
+     * Clear the login URL and return to standard OAuth flow
+     */
+    clearLoginUrl() {
+        this.loginUrl = undefined;
+        // Clear custom expected origin from MessageHandler
+        if (this.messageHandler) {
+            this.messageHandler.clearCustomExpectedOrigin();
+        }
+        this.logger.info("🔗 Login URL cleared, returning to standard OAuth flow");
+    }
+    /**
+     * Get the current login URL
+     * @returns The current login URL or undefined if not set
+     */
+    getLoginUrl() {
+        return this.loginUrl;
+    }
     /**
      * Update the iframe display mode
      * @param mode - The display mode to use for the iframe
@@ -631,7 +911,27 @@ export class CivicAuth {
             this.events.emit(AuthEvent.SIGN_OUT_STARTED, {
                 detail: "Logout process started",
             });
-            // Get current tokens before clearing them
+            // If a loginUrl is configured, redirect to the backend's logout endpoint.
+            // The backend will then handle redirecting to the OIDC provider.
+            if (this.loginUrl) {
+                this.logger.info("🚪 Redirecting to backend for logout in backend-integrated flow");
+                const backendUrl = new URL(this.loginUrl).origin;
+                const endpoints = getBackendEndpoints(this.config.backendEndpoints);
+                const backendLogoutUrl = `${backendUrl}${endpoints.logout}`;
+                // Clear local SDK session state before redirecting
+                await this.sessionManager.clearSession();
+                this.events.emit(AuthEvent.SIGN_OUT_COMPLETE, {
+                    detail: "Local session cleared, redirecting to backend for logout.",
+                });
+                // Perform top-level redirect to the backend logout endpoint
+                this.logger.info("🌐 Redirecting to backend logout endpoint", {
+                    url: backendLogoutUrl,
+                });
+                window.location.href = backendLogoutUrl;
+                return;
+            }
+            // --- Existing SPA redirect-based logout flow ---
+            this.logger.info("🚪 Using redirect-based logout for SPA flow");
             const tokens = await retrieveTokens(this.storage);
             if (!tokens?.id_token) {
                 this.logger.warn("⚠️ No ID token found, clearing local session only");