@civic/auth 0.9.6-beta.1 → 0.10.0-beta.0

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, getBackendEndpoints, } from "../../shared/lib/util.js";
+import { generateOauthLogoutUrl, clearTokens, retrieveTokens, getBackendEndpoints, resolveEndpointUrl, } from "../../shared/lib/util.js";
 import { LOGOUT_STATE } from "../../constants.js";
 import { getOauthEndpoints } from "../../lib/oauth.js";
 import { collectAndSendSDKAnalytics } from "../../lib/analytics.js";
@@ -74,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.config);
+        this.sessionManager = new SessionManager(this.storage, this.events, this.config, this.config.initialUser);
         // Initialize handlers
         this.initializeHandlers();
     }
@@ -172,13 +172,33 @@ 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,
+            // Check if we're in embedded mode - we need to show the iframe
+            // Note: After config processing, "embedded" displayMode becomes "iframe" + iframeDisplayMode: "embedded"
+            const isEmbeddedMode = this.config.displayMode === "iframe" &&
+                this.config.iframeDisplayMode === "embedded";
+            this.logger.info("🔍 Checking display mode conditions", {
                 displayMode: this.config.displayMode,
+                iframeDisplayMode: this.config.iframeDisplayMode,
+                isEmbeddedMode,
+                preloadIframe: this.config.preloadIframe,
             });
-            if (this.config.preloadIframe && this.config.displayMode === "iframe") {
+            if (isEmbeddedMode) {
+                // For embedded mode, we need to start authentication to show the iframe
+                try {
+                    this.logger.info("🖼️ Starting authentication for embedded mode to show iframe...");
+                    await this.startAuthentication();
+                    this.logger.info("✅ Embedded iframe authentication started successfully");
+                }
+                catch (error) {
+                    // Don't fail initialization if embedded authentication fails - graceful degradation
+                    this.logger.warn("⚠️ Embedded authentication failed (graceful degradation):", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            else if (this.config.preloadIframe &&
+                this.config.displayMode === "iframe") {
+                // Regular iframe preloading logic for modal mode
                 try {
                     const isAuthenticated = await this.isAuthenticated();
                     this.logger.info("🔍 Authentication check for preload", {
@@ -204,9 +224,12 @@ export class CivicAuth {
                 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",
+                    isEmbeddedMode,
+                    reason: isEmbeddedMode
+                        ? "embedded mode uses startAuthentication instead"
+                        : !this.config.preloadIframe
+                            ? "preloadIframe is disabled"
+                            : "displayMode is not iframe",
                 });
             }
         }
@@ -298,6 +321,7 @@ export class CivicAuth {
                     iframeDisplayMode: this.config.iframeDisplayMode,
                     framework: this.config.framework || "vanillajs",
                     sdkVersion: getVersion(),
+                    loginSuccessUrl: this.config.loginSuccessUrl,
                 });
             // Append state as query parameter to loginUrl
             const url = new URL(this.loginUrl, window.location.origin);
@@ -324,6 +348,7 @@ export class CivicAuth {
                 iframeDisplayMode: this.config.iframeDisplayMode,
                 framework: this.config.framework || "vanillajs",
                 sdkVersion: getVersion(),
+                loginSuccessUrl: this.config.loginSuccessUrl,
             });
         return buildAuthUrl({
             endpoints: this.endpoints,
@@ -474,6 +499,82 @@ export class CivicAuth {
         });
         return this.authPromise;
     }
+    /**
+     * Reloads embedded authentication interface
+     *
+     * This method is specifically designed for embedded mode scenarios where the iframe
+     * needs to be recreated after navigation or DOM changes. It performs a complete
+     * re-initialization by calling the full init() method.
+     *
+     * @returns Promise that resolves when the embedded iframe is created
+     * @throws {CivicAuthError} If not in embedded mode or if iframe creation fails
+     *
+     * @example
+     * ```typescript
+     * // After navigation in a SPA
+     * await civicAuth.reloadEmbedded();
+     * ```
+     */
+    async reloadEmbedded() {
+        this.logger.info("🔄 Reloading embedded authentication interface", {
+            displayMode: this.config.displayMode,
+            iframeDisplayMode: this.config.iframeDisplayMode,
+            authPromise: !!this.authPromise,
+        });
+        this.config.displayMode = "iframe";
+        this.config.iframeDisplayMode = "embedded";
+        // Check if container element exists
+        const container = this.getContainerElement();
+        this.logger.info("🎯 Container element check", {
+            containerFound: !!container,
+            containerId: container?.id,
+            containerClass: container?.className,
+        });
+        if (!container) {
+            const error = new CivicAuthError("Container element for embedded iframe not found. Ensure an element with id 'civic-login-container' exists or provide targetContainerElement in config.", CivicAuthErrorCode.CONTAINER_NOT_FOUND);
+            this.logger.error(error.message);
+            throw error;
+        }
+        // Clear any existing auth promise to ensure fresh start
+        if (this.authPromise) {
+            this.logger.info("🧹 Clearing existing auth promise for fresh start");
+            this.authPromise = undefined;
+            this.authPromiseResolve = undefined;
+            this.authPromiseReject = undefined;
+        }
+        // Clean up any existing handlers before re-initialization
+        if (this.messageHandler || this.popupHandler || this.iframeAuthHandler) {
+            this.logger.info("🧹 Cleaning up existing handlers before re-initialization");
+            this.cleanup();
+        }
+        this.logger.info("🔄 Re-initializing handlers and starting embedded auth");
+        try {
+            // Don't call init() - that would re-process config based on current page
+            // Instead, do minimal re-initialization with original config
+            // Ensure OAuth endpoints are available (they should be from original init)
+            if (!this.endpoints) {
+                this.logger.info("🔗 Getting OAuth endpoints");
+                this.endpoints = await getOauthEndpoints(this.config.oauthServerBaseUrl);
+            }
+            // Re-initialize all handlers (creates new instances)
+            this.logger.info("🔄 Re-initializing handlers");
+            this.initializeHandlers();
+            // Start authentication to create the embedded iframe
+            this.logger.info("🎬 Starting embedded authentication");
+            await this.startAuthentication();
+            this.logger.info("✅ Embedded iframe reloaded successfully");
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error
+                ? error.message
+                : "Failed to reload embedded iframe";
+            this.logger.error("❌ Failed to reload embedded iframe", {
+                error: errorMessage,
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            throw error;
+        }
+    }
     async handleBrowserCorsFailsSilently() {
         this.logger.warn("🚨 Browser CORS fails silently - switching to redirect mode", {
             displayMode: this.config.displayMode,
@@ -510,7 +611,7 @@ export class CivicAuth {
             switch (this.config.displayMode) {
                 case "redirect":
                     this.logger.info("🌐 Using redirect mode");
-                    window.location.href = fullAuthUrl;
+                    this.events.locationChange(fullAuthUrl, "Redirecting to auth URL", "login");
                     break;
                 case "new_tab":
                     this.logger.info("📱 Using new_tab mode");
@@ -614,7 +715,19 @@ export class CivicAuth {
     handleAuthSuccess(result) {
         this.logger.info("✅ Authentication successful");
         this.authPromiseResolve?.(result);
-        this.cleanup();
+        // For embedded mode, preserve the iframe completely - don't cleanup
+        // The iframe should stay visible showing the successful authentication state
+        const isEmbeddedMode = this.config.displayMode === "iframe" &&
+            this.config.iframeDisplayMode === "embedded";
+        if (isEmbeddedMode) {
+            this.logger.info("🔧 Embedded mode - preserving iframe, skipping cleanup");
+            // Only clean up timeouts and reset promises, but keep iframe visible
+            this.cleanupTimeoutsAndState();
+        }
+        else {
+            // For modal/redirect modes, do full cleanup as before
+            this.cleanup();
+        }
     }
     /**
      * Handle authentication error
@@ -622,7 +735,19 @@ export class CivicAuth {
     handleAuthError(error) {
         this.logger.error("❌ Authentication failed", { error: error.message });
         this.authPromiseReject?.(error);
-        this.cleanup();
+        // For embedded mode, preserve the iframe to show error state
+        // For other modes, do full cleanup as before
+        const isEmbeddedMode = this.config.displayMode === "iframe" &&
+            this.config.iframeDisplayMode === "embedded";
+        if (isEmbeddedMode) {
+            this.logger.info("🔧 Embedded mode - preserving iframe to show error state");
+            // Only clean up timeouts and reset promises, but keep iframe visible
+            this.cleanupTimeoutsAndState();
+        }
+        else {
+            // For modal/redirect modes, do full cleanup as before
+            this.cleanup();
+        }
     }
     /**
      * Handle popup failure - simplified like React implementation
@@ -638,21 +763,22 @@ export class CivicAuth {
         }
         // Always redirect to the failed URL or build a new one
         if (failedUrl) {
-            window.location.href = failedUrl;
+            // this.config.displayMode = "redirect";
+            // Use centralized location change handler
+            this.events.locationChange(failedUrl, "Popup blocked, falling back to redirect mode", "login");
+            return;
         }
-        else {
-            this.buildAuthUrl()
-                .then((authUrl) => {
-                window.location.href = authUrl;
-            })
-                .catch((error) => {
-                this.logger.error("Failed to build auth URL for redirect fallback", {
-                    error,
-                });
-                const fallbackError = new CivicAuthError("Failed to redirect for authentication", CivicAuthErrorCode.INIT_FAILED);
-                this.handleAuthError(fallbackError);
+        this.buildAuthUrl()
+            .then((authUrl) => {
+            this.events.locationChange(authUrl, "Redirecting to auth URL", "login");
+        })
+            .catch((error) => {
+            this.logger.error("Failed to build auth URL for redirect fallback", {
+                error,
             });
-        }
+            const fallbackError = new CivicAuthError("Failed to redirect for authentication", CivicAuthErrorCode.INIT_FAILED);
+            this.handleAuthError(fallbackError);
+        });
     }
     /**
      * Show popup failure message to user
@@ -716,7 +842,16 @@ export class CivicAuth {
             }
             return element;
         }
-        return this.config.targetContainerElement ?? null;
+        if (this.config.targetContainerElement) {
+            return this.config.targetContainerElement;
+        }
+        // Fallback: Look for element with id "civic-login-container"
+        const fallbackContainer = document.getElementById("civic-login-container");
+        if (fallbackContainer) {
+            this.logger.debug('Using fallback container with id "civic-login-container"');
+            return fallbackContainer;
+        }
+        return null;
     }
     /**
      * Handle OAuth callback
@@ -810,6 +945,27 @@ export class CivicAuth {
             window.removeEventListener("message", this.messageHandler.handleMessage);
         }
     }
+    /**
+     * Clean up only timeouts and state without touching iframe (for embedded mode)
+     */
+    cleanupTimeoutsAndState() {
+        this.logger.info("Cleaning up timeouts and state (preserving iframe for embedded mode)");
+        // Clean up timeouts
+        if (this.authProcessTimeoutHandle) {
+            window.clearTimeout(this.authProcessTimeoutHandle);
+            this.authProcessTimeoutHandle = undefined;
+        }
+        if (this.popupFailureTimeoutHandle) {
+            window.clearTimeout(this.popupFailureTimeoutHandle);
+            this.popupFailureTimeoutHandle = undefined;
+        }
+        // Reset state
+        this.hasPopupFailed = false;
+        this.authPromise = undefined;
+        this.authPromiseResolve = undefined;
+        this.authPromiseReject = undefined;
+        // Keep message handler and iframe for embedded mode
+    }
     /**
      * Get the current session
      */
@@ -917,6 +1073,37 @@ export class CivicAuth {
     getIframeDisplayMode() {
         return this.config.iframeDisplayMode;
     }
+    /**
+     * Reset authentication state when page is restored from back-forward cache (bfcache)
+     * This clears any pending authentication promises that may have been interrupted
+     * by the browser caching the page, allowing fresh authentication attempts
+     */
+    resetOnBfcache() {
+        this.logger.info("🔄 Resetting authentication state due to bfcache restore");
+        // Clear pending authentication promise and related state
+        if (this.authPromise) {
+            this.logger.debug("Clearing stale authentication promise from bfcache");
+            this.authPromise = undefined;
+            this.authPromiseResolve = undefined;
+            this.authPromiseReject = undefined;
+        }
+        // Clear timeouts that may no longer be valid
+        if (this.authProcessTimeoutHandle) {
+            window.clearTimeout(this.authProcessTimeoutHandle);
+            this.authProcessTimeoutHandle = undefined;
+        }
+        if (this.popupFailureTimeoutHandle) {
+            window.clearTimeout(this.popupFailureTimeoutHandle);
+            this.popupFailureTimeoutHandle = undefined;
+        }
+        // Reset auth flags
+        this.hasPopupFailed = false;
+        this.hasSignInStarted = false;
+        // Reset iframe handler state if needed
+        if (this.iframeAuthHandler) {
+            this.iframeAuthHandler.cleanupIframe();
+        }
+    }
     /**
      * Destroy the auth client and clean up all resources
      */
@@ -940,17 +1127,33 @@ export class CivicAuth {
                 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}`;
+                const backendLogoutUrl = resolveEndpointUrl(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.",
                 });
+                // Generate state for backend integration to enable iframe mode detection
+                const state = generateState({
+                    displayMode: this.config.displayMode || "iframe",
+                    framework: this.config.framework || "vanillajs",
+                    sdkVersion: getVersion(),
+                });
                 // Perform top-level redirect to the backend logout endpoint
-                this.logger.info("🌐 Redirecting to backend logout endpoint", {
-                    url: backendLogoutUrl,
+                // Include logoutRedirectUrl and state as query parameters
+                const logoutUrl = new URL(backendLogoutUrl);
+                if (this.config.logoutRedirectUrl) {
+                    logoutUrl.searchParams.set("logoutRedirectUrl", this.config.logoutRedirectUrl);
+                }
+                // Include state for iframe mode detection on server
+                logoutUrl.searchParams.set("state", state);
+                this.logger.info("🌐 Loading backend logout endpoint in iframe", {
+                    url: logoutUrl.toString(),
+                    logoutRedirectUrl: this.config.logoutRedirectUrl,
+                    displayMode: this.config.displayMode,
                 });
-                window.location.href = backendLogoutUrl;
+                // Use iframe for SPA logout to avoid full page reload
+                this.loadLogoutInIframe(logoutUrl);
                 return;
             }
             // --- Existing SPA redirect-based logout flow ---
@@ -1002,30 +1205,7 @@ export class CivicAuth {
                 detail: "Logout successful",
             });
             // Use hidden iframe instead of redirect to avoid full page reload in SPA mode
-            this.logger.info("🌐 Loading logout URL in hidden iframe");
-            const logoutIframe = document.createElement("iframe");
-            logoutIframe.style.display = "none";
-            // Clean up iframe when logout completes (or errors)
-            const cleanupIframe = () => {
-                this.logger.info("🧹 Cleaning up logout iframe");
-                if (!logoutIframe.parentNode) {
-                    this.logger.warn("🧹 Logout iframe not found, skipping iframe cleanup");
-                    return;
-                }
-                logoutIframe.parentNode.removeChild(logoutIframe);
-                if (this.config.logoutRedirectUrl) {
-                    window.location.href = this.config.logoutRedirectUrl;
-                }
-            };
-            logoutIframe.onload = () => {
-                cleanupIframe();
-            };
-            logoutIframe.onerror = (error) => {
-                this.logger.error("❌ Logout iframe failed to load", { error });
-                cleanupIframe();
-            };
-            logoutIframe.src = logoutUrl.toString();
-            document.body.appendChild(logoutIframe);
+            this.loadLogoutInIframe(logoutUrl);
         }
         catch (error) {
             this.logger.error("❌ Logout failed", { error });
@@ -1035,6 +1215,41 @@ export class CivicAuth {
             throw new CivicAuthError("Logout failed", CivicAuthErrorCode.LOGOUT_FAILED);
         }
     }
+    /**
+     * Load logout URL in a hidden iframe to avoid full page reload
+     * @param logoutUrl The URL to load in the iframe
+     */
+    loadLogoutInIframe(logoutUrl) {
+        this.logger.info("🌐 Loading logout URL in hidden iframe");
+        const logoutIframe = document.createElement("iframe");
+        logoutIframe.style.display = "none";
+        // Clean up iframe when logout completes (or errors)
+        const cleanupIframe = () => {
+            this.logger.info("🧹 Cleaning up logout iframe");
+            if (!logoutIframe.parentNode) {
+                this.logger.warn("🧹 Logout iframe not found, skipping iframe cleanup");
+                return;
+            }
+            logoutIframe.parentNode.removeChild(logoutIframe);
+            if (this.config.logoutRedirectUrl) {
+                this.logger.info("🌐 Redirecting to logoutRedirectUrl after logout iframe cleanup", {
+                    logoutRedirectUrl: this.config.logoutRedirectUrl,
+                });
+                // Use direct redirect for logout to ensure frontend state is cleared
+                // This bypasses any URL_CHANGE event listeners that might interfere
+                window.location.href = this.config.logoutRedirectUrl;
+            }
+        };
+        logoutIframe.onload = () => {
+            cleanupIframe();
+        };
+        logoutIframe.onerror = (error) => {
+            this.logger.error("❌ Logout iframe failed to load", { error });
+            cleanupIframe();
+        };
+        logoutIframe.src = logoutUrl.toString();
+        document.body.appendChild(logoutIframe);
+    }
     /**
      * Handle logout state cleanup
      * This mirrors the logic from useSignIn.ts to properly clean up after logout