@civic/auth 0.6.1-beta.1 → 0.6.1-beta.2

package/dist/vanillajs/auth/CivicAuth.js

@@ -1,105 +1,55 @@
 import { AuthEvent } from "../types/index.js";
-import { LocalStorageAdapter } from "../../browser/storage.js";
-import { handleOAuthRedirectPage } from "./OAuthCallbackHandler.js";
 import { buildAuthUrl } from "../utils/auth-utils.js";
-import { createLogger, configureLogging, setCurrentLogger, } from "../utils/logger.js";
-import { SignalObserver } from "../iframe/SignalObserver.js";
+import { createMainLogger, configureLogging, setCurrentLogger, } from "../utils/logger.js";
 import { GenericPublicClientPKCEProducer } from "../../services/PKCE.js";
 import { generateState } from "../../lib/oauth.js";
 import { SessionManager } from "./SessionManager.js";
-import { IframeManager } from "../iframe/IframeManager.js";
-/**
- * Error codes for CivicAuth errors
- */
-export var CivicAuthErrorCode;
-(function (CivicAuthErrorCode) {
-    CivicAuthErrorCode["CONFIG_REQUIRED"] = "CONFIG_REQUIRED";
-    CivicAuthErrorCode["INIT_FAILED"] = "INIT_FAILED";
-    CivicAuthErrorCode["ENDPOINTS_NOT_INITIALIZED"] = "ENDPOINTS_NOT_INITIALIZED";
-    CivicAuthErrorCode["CONTAINER_NOT_FOUND"] = "CONTAINER_NOT_FOUND";
-    CivicAuthErrorCode["AUTH_PROCESS_TIMEOUT"] = "AUTH_PROCESS_TIMEOUT";
-    CivicAuthErrorCode["IFRAME_LOAD_ERROR"] = "IFRAME_LOAD_ERROR";
-    CivicAuthErrorCode["INVALID_MESSAGE"] = "INVALID_MESSAGE";
-})(CivicAuthErrorCode || (CivicAuthErrorCode = {}));
-/**
- * Constants for the auth client
- */
-const CONSTANTS = {
-    DEFAULT_IFRAME_ID: "civic-auth-iframe",
-    DEFAULT_AUTH_PROCESS_TIMEOUT: 60000, // 60 seconds
-    SUCCESS_SIGNAL_ID: "civic-auth-success-signal",
-    ERROR_SIGNAL_ID: "civic-auth-error-signal",
-};
-class CivicAuthError extends Error {
-    code;
-    constructor(message, code) {
-        super(message);
-        this.code = code;
-        this.name = "CivicAuthError";
-    }
-}
-/**
- * Process the configuration with defaults
- */
-function processConfigWithDefaults(config) {
-    const loggingConfig = {
-        enabled: true,
-        namespace: "iframe",
-        level: "debug",
-        ...config.logging,
-    };
-    return {
-        ...config,
-        displayMode: config.displayMode || "iframe",
-        authProcessTimeout: config.authProcessTimeout || CONSTANTS.DEFAULT_AUTH_PROCESS_TIMEOUT,
-        iframeId: config.iframeId || CONSTANTS.DEFAULT_IFRAME_ID,
-        logging: loggingConfig,
-        storageAdapter: config.storageAdapter || new LocalStorageAdapter(),
-    };
-}
+import { PopupError } from "../../services/types.js";
+import { handleOAuthRedirectPage } from "./handlers/OAuthCallbackHandler.js";
+import { generateOauthLogoutUrl, clearTokens, retrieveTokens, } from "../../shared/lib/util.js";
+import { CivicAuthError, CivicAuthErrorCode, CIVIC_AUTH_CONSTANTS, } from "./types/AuthTypes.js";
+import { processConfigWithDefaults } from "./config/ConfigProcessor.js";
+import { MessageHandler } from "./handlers/MessageHandler.js";
+import { PopupHandler } from "./handlers/PopupHandler.js";
+import { IframeAuthHandler } from "./handlers/IframeAuthHandler.js";
 /**
  * CivicAuth client for handling OAuth authentication
+ *
+ * This is a refactored version that uses a modular architecture for better maintainability.
  */
 export class CivicAuth {
-    /**
-     * Internal configuration with all optional properties resolved to required ones.
-     *
-     * We extend CivicAuthClientConfig rather than making these properties required
-     * in the public interface to maintain better DX (optional properties) while
-     * ensuring type safety internally after defaults are applied.
-     */
     config;
-    iframeElement;
-    observer;
-    authPromise;
-    authPromiseResolve;
-    authPromiseReject;
-    authProcessTimeoutHandle;
-    messageEventHandler;
     storage;
     endpoints;
     logger;
     sessionManager;
-    iframeManager;
+    initialDisplayMode;
+    // Authentication state
+    authPromise;
+    authPromiseResolve;
+    authPromiseReject;
+    authProcessTimeoutHandle;
+    popupFailureTimeoutHandle;
+    hasPopupFailed = false;
+    // Handlers
+    messageHandler;
+    popupHandler;
+    iframeAuthHandler;
     /**
-     * Private constructor for CivicAuth.
+     * Private constructor - initializes configuration and handlers.
      * Use {@link CivicAuth.create} to create a new instance.
-     * @param config - Configuration options for the auth client
-     * @throws {CivicAuthError} If required configuration is missing
-     * @private
      */
     constructor(config) {
-        // Process config with defaults
+        // Process config with defaults and validation
         this.config = processConfigWithDefaults(config);
-        // Configure logging based on config
+        this.initialDisplayMode = this.config.displayMode;
+        // Configure logging
         configureLogging(this.config.logging);
-        // Initialize logger based on config
+        // Initialize logger - always use "vanillajs" as base namespace
         if (this.config.logging?.enabled) {
-            const namespace = this.config.logging.namespace || "iframe";
-            this.logger = createLogger(namespace);
+            this.logger = createMainLogger("vanillajs"); // Always use "vanillajs"
         }
         else {
-            // Create a no-op logger when logging is disabled
             this.logger = {
                 debug: () => { },
                 info: () => { },
@@ -107,26 +57,14 @@ export class CivicAuth {
                 error: () => { },
             };
         }
-        // Set this logger as the current logger
         setCurrentLogger(this.logger);
-        // Use the storage adapter from processed config (guaranteed to be present)
         this.storage = this.config.storageAdapter;
         // Initialize SessionManager if events are provided
         if (config.events) {
             this.sessionManager = new SessionManager(this.storage, config.events);
         }
-        // Validate required configuration
-        const requiredConfigs = [
-            { key: "clientId", value: config.clientId },
-            { key: "targetContainerElement", value: config.targetContainerElement },
-            { key: "textSignals.success", value: config.textSignals?.success },
-        ];
-        for (const { key, value } of requiredConfigs) {
-            if (!value) {
-                throw new CivicAuthError(`CivicAuth: ${key} is required.`, CivicAuthErrorCode.CONFIG_REQUIRED);
-            }
-        }
-        this.messageEventHandler = this.handleIframeMessage.bind(this);
+        // Initialize handlers
+        this.initializeHandlers();
     }
     /**
      * Creates and initializes a new instance of CivicAuth.
@@ -140,9 +78,12 @@ export class CivicAuth {
      * ```typescript
      * const auth = await CivicAuth.create({
      *   clientId: "your-client-id",
-     *   redirectUrl: "https://your-app.com/callback",
-     *   oauthServerBaseUrl: "https://auth-server.com/",
-     *   scopes: ["openid", "profile"],
+     *   // redirectUrl is optional - defaults to current page (window.location.origin + window.location.pathname)
+     *   redirectUrl: "https://your-app.com/callback", // optional
+     *   // oauthServerBaseUrl is optional - defaults to "https://auth.civic.com/oauth/"
+     *   oauthServerBaseUrl: "https://auth-server.com/", // optional
+     *   // scopes is optional - defaults to ['openid', 'profile', 'email', 'offline_access']
+     *   scopes: ["openid", "profile"], // optional
      *   targetContainerElement: "auth-container",
      *   textSignals: {
      *     success: "Authentication successful!"
@@ -157,11 +98,16 @@ export class CivicAuth {
     }
     /**
      * Initializes the auth client and checks for callback handling
-     * @throws {CivicAuthError} If initialization fails
      */
     async init() {
+        this.logger.info("🚀 Initializing CivicAuth", {
+            currentUrl: window.location.href,
+            redirectUrl: this.config.redirectUrl,
+            oauthServerBaseUrl: this.config.oauthServerBaseUrl,
+            isCallbackUrl: window.location.href.startsWith(this.config.redirectUrl),
+        });
         try {
-            // Get OAuth endpoints from well-known configuration
+            // Get OAuth endpoints
             this.endpoints = {
                 auth: `${this.config.oauthServerBaseUrl}auth`,
                 token: `${this.config.oauthServerBaseUrl}token`,
@@ -169,7 +115,10 @@ export class CivicAuth {
                 userinfo: `${this.config.oauthServerBaseUrl}userinfo`,
                 endsession: `${this.config.oauthServerBaseUrl}endsession`,
             };
-            // Initialize SessionManager with auth config for token refresh
+            this.logger.info("🔗 OAuth endpoints configured", {
+                endpoints: this.endpoints,
+            });
+            // Initialize SessionManager with auth config
             if (this.sessionManager) {
                 const authConfig = {
                     clientId: this.config.clientId,
@@ -178,18 +127,32 @@ export class CivicAuth {
                     scopes: this.config.scopes,
                     endpoints: this.endpoints,
                 };
+                this.logger.info("🔧 Initializing SessionManager", { authConfig });
                 await this.sessionManager.initializeWithAuthConfig(authConfig);
             }
             // Check if we're on the callback page
-            if (window.location.href.startsWith(this.config.redirectUrl)) {
+            const isCallbackPage = window.location.href.startsWith(this.config.redirectUrl);
+            this.logger.info("🔍 Callback page check", {
+                isCallbackPage,
+                currentUrl: window.location.href,
+                redirectUrl: this.config.redirectUrl,
+            });
+            if (isCallbackPage) {
+                this.logger.info("📞 Processing callback page");
                 await this.handleCallback();
             }
+            else {
+                this.logger.info("🏠 Not a callback page, initialization complete");
+            }
         }
         catch (error) {
             const errorMessage = error instanceof Error
                 ? error.message
                 : "Failed to initialize authentication";
-            this.logger.error("Failed to initialize CivicAuth:", { error });
+            this.logger.error("❌ CivicAuth initialization failed", {
+                error: errorMessage,
+                stack: error instanceof Error ? error.stack : undefined,
+            });
             this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
                 detail: errorMessage,
             });
@@ -197,82 +160,33 @@ export class CivicAuth {
         }
     }
     /**
-     * Gets the container element for the auth iframe
-     * @returns The container element or null if not found
-     */
-    getContainerElement() {
-        if (typeof this.config.targetContainerElement === "string") {
-            const element = document.getElementById(this.config.targetContainerElement);
-            if (!element) {
-                this.logger.warn(`Container element with ID "${this.config.targetContainerElement}" not found`);
-            }
-            return element;
-        }
-        return this.config.targetContainerElement;
-    }
-    /**
-     * Determines the appropriate iframe display mode based on container characteristics
-     * @param container The HTML element that will contain the iframe
-     * @returns "modal" for full-screen overlay or "embedded" for in-container display
+     * Initialize all handlers with proper configuration
      */
-    determineIframeDisplayMode(container) {
-        // Use explicit config if provided
-        if (this.config.iframeDisplayMode) {
-            this.logger.debug(`Using configured iframe display mode: ${this.config.iframeDisplayMode}`);
-            return this.config.iframeDisplayMode;
-        }
-        // Analyze container characteristics to determine best display mode
-        const containerRect = container.getBoundingClientRect();
-        const containerStyles = window.getComputedStyle(container);
-        // Get container dimensions
-        const containerWidth = containerRect.width;
-        const containerHeight = containerRect.height;
-        // Check if container is positioned in a way that suggests it's meant for modal display
-        const isFullScreenContainer = containerStyles.position === "fixed" &&
-            (containerWidth >= window.innerWidth * 0.9 ||
-                containerHeight >= window.innerHeight * 0.9);
-        // Modal mode thresholds - if container is too small, use modal for better UX
-        const MIN_EMBEDDED_WIDTH = 320; // Same as modal content wrapper width
-        const MIN_EMBEDDED_HEIGHT = 400; // Reasonable minimum for embedded auth flow
-        // Determine mode based on container characteristics
-        if (isFullScreenContainer) {
-            this.logger.debug("Container appears to be full-screen positioned, using modal mode", { containerWidth, containerHeight, position: containerStyles.position });
-            return "modal";
-        }
-        if (containerWidth < MIN_EMBEDDED_WIDTH ||
-            containerHeight < MIN_EMBEDDED_HEIGHT) {
-            this.logger.debug(`Container too small for embedded mode (${containerWidth}x${containerHeight}), using modal mode`, {
-                containerWidth,
-                containerHeight,
-                MIN_EMBEDDED_WIDTH,
-                MIN_EMBEDDED_HEIGHT,
-            });
-            return "modal";
-        }
-        // Check if container has sufficient space and is properly positioned for embedding
-        const hasAdequateSpace = containerWidth >= MIN_EMBEDDED_WIDTH &&
-            containerHeight >= MIN_EMBEDDED_HEIGHT;
-        const isEmbeddablePosition = containerStyles.position === "relative" ||
-            containerStyles.position === "static" ||
-            containerStyles.position === "";
-        if (hasAdequateSpace && isEmbeddablePosition) {
-            this.logger.debug("Container has adequate space and positioning for embedded mode", { containerWidth, containerHeight, position: containerStyles.position });
-            return "embedded";
-        }
-        // Default to modal mode if container characteristics are unclear
-        this.logger.debug("Container characteristics unclear, defaulting to modal mode for better UX", { containerWidth, containerHeight, position: containerStyles.position });
-        return "modal";
+    initializeHandlers() {
+        const handlerConfig = {
+            config: this.config,
+            logger: this.logger,
+            onAuthSuccess: this.handleAuthSuccess.bind(this),
+            onAuthError: this.handleAuthError.bind(this),
+            cleanup: this.cleanup.bind(this),
+        };
+        this.messageHandler = new MessageHandler({
+            ...handlerConfig,
+            onPopupFailure: this.handlePopupFailure.bind(this),
+        });
+        this.popupHandler = new PopupHandler(handlerConfig);
+        this.iframeAuthHandler = new IframeAuthHandler({
+            ...handlerConfig,
+            messageHandler: this.messageHandler.handleMessage,
+        });
     }
     /**
      * Builds the authentication URL with PKCE challenge
-     * @returns The complete authentication URL
-     * @throws {CivicAuthError} If endpoints are not initialized
      */
     async buildAuthUrl() {
         if (!this.endpoints) {
             throw new CivicAuthError("OAuth endpoints not initialized. Please wait for initialization to complete.", CivicAuthErrorCode.ENDPOINTS_NOT_INITIALIZED);
         }
-        // Use storage directly since it's now AuthStorage
         const pkceProducer = new GenericPublicClientPKCEProducer(this.storage);
         const codeChallenge = await pkceProducer.getCodeChallenge();
         const state = this.config.initialState ||
@@ -287,293 +201,265 @@ export class CivicAuth {
             codeChallenge,
             state,
             prompt: this.config.prompt,
+            nonce: this.config.nonce,
         });
     }
-    handleIframeMessage(event) {
-        const expectedOrigin = new URL(this.config.oauthServerBaseUrl).origin;
-        this.logIncomingMessage(event, expectedOrigin);
-        if (!this.isValidMessageSource(event, expectedOrigin)) {
-            return;
-        }
-        this.handleValidMessage(event);
-    }
-    logIncomingMessage(event, expectedOrigin) {
-        this.logger.debug("Global window received message:", {
-            data: event.data,
-            origin: event.origin,
-            sourceProvided: !!event.source,
-            iframeContentWindow: this.iframeElement?.contentWindow,
-            expectedIframeOrigin: expectedOrigin,
-        });
-    }
-    isValidMessageSource(event, expectedOrigin) {
-        const isValidOrigin = event.origin === expectedOrigin;
-        const isValidSource = event.source === this.iframeElement?.contentWindow;
-        if (!isValidOrigin) {
-            this.logger.warn("Ignored message from unexpected origin.", {
-                receivedOrigin: event.origin,
-                expectedOrigin,
-                iframeSrc: this.iframeElement?.src,
-            });
-        }
-        if (!isValidSource) {
-            this.logger.warn("Ignored message from unexpected source.", {
-                isSourceProvided: !!event.source,
-                isIframeContentWindowAvailable: !!this.iframeElement?.contentWindow,
-                iframeSrc: this.iframeElement?.src,
-            });
-        }
-        return isValidOrigin && isValidSource;
-    }
-    handleValidMessage(event) {
-        this.logger.info("Message from configured iframe source and origin received", {
-            data: event.data,
-            iframeSrc: this.iframeElement?.src,
-        });
-        const message = event.data;
-        const messageType = message?.type;
-        switch (messageType) {
-            case "auth_success":
-                this.handleAuthSuccess(message);
-                break;
-            case "auth_error":
-                this.handleAuthError(message);
-                break;
-            default:
-                this.logger.debug("Message from iframe did not match expected types (auth_success, auth_error)", { data: event.data });
-        }
-    }
-    handleAuthSuccess(data) {
-        this.config.events?.emit(AuthEvent.SIGN_IN_COMPLETE, {
-            detail: "Success signal received via postMessage",
-            data,
-        });
-        this.authPromiseResolve?.(data?.data || {});
-        this.cleanup();
-    }
-    handleAuthError(data) {
-        this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
-            detail: "Error signal received via postMessage",
-            error: data,
-        });
-        this.authPromiseReject?.(new CivicAuthError(data?.detail || "Error signal received via postMessage", CivicAuthErrorCode.INVALID_MESSAGE));
-        this.cleanup();
-    }
-    setupSignalObserver(iframeDoc) {
-        const signalObserver = new SignalObserver({
-            textSignals: this.config.textSignals,
-            events: this.config.events,
-            logger: this.logger,
-        }, this.authPromiseResolve, this.authPromiseReject, () => this.cleanup());
-        signalObserver.setup(iframeDoc);
-    }
-    async handleNewTabAuth(fullAuthUrl, reject) {
-        const popupWindow = window.open(fullAuthUrl, "_blank");
-        if (!popupWindow) {
-            const error = new CivicAuthError("Failed to open popup window. Please check your browser's popup settings.", CivicAuthErrorCode.INIT_FAILED);
-            this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
-                detail: error.message,
-            });
-            reject(error);
-        }
-    }
-    async handleIframeAuth(fullAuthUrl, reject) {
-        const container = this.getContainerElement();
-        if (!container) {
-            const error = new CivicAuthError("Target container element not found.", CivicAuthErrorCode.CONTAINER_NOT_FOUND);
-            this.logger.error(error.message);
-            reject(error);
-            return;
-        }
-        this.logger.debug("Creating iframe with modal backdrop", {
-            url: fullAuthUrl,
-            containerId: container?.id,
-            iframeId: this.config.iframeId,
-            origin: window.location.origin,
-        });
-        // Determine the actual display mode for IframeManager
-        // For iframe displayMode, we need to decide between modal and embedded based on container
-        const iframeDisplayMode = this.determineIframeDisplayMode(container);
-        this.logger.debug(`🎯 CivicAuth: Creating IframeManager with display mode: ${iframeDisplayMode}`);
-        // Create IframeManager with appropriate display mode
-        this.iframeManager = new IframeManager({
-            container: container,
-            displayMode: iframeDisplayMode,
-            iframeId: this.config.iframeId,
-            onClose: () => {
-                this.logger.debug("Authentication close requested by user (backdrop click, close button, or Escape key)");
-                this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
-                    detail: "Authentication cancelled by user",
-                });
-                reject(new CivicAuthError("Authentication cancelled by user", CivicAuthErrorCode.AUTH_PROCESS_TIMEOUT));
-                this.cleanup();
-            },
-        });
-        // Create the iframe using IframeManager
-        this.iframeElement = this.iframeManager.createIframe(fullAuthUrl);
-        this.config.events?.emit(AuthEvent.SIGN_IN_STARTED, {
-            detail: "Iframe created with modal backdrop",
-        });
-        this.iframeElement.onload = () => {
-            this.logger.info("Iframe loaded", {
-                iframeSrc: this.iframeElement?.src,
-                currentOrigin: window.location.origin,
-                expectedAuthServerOrigin: new URL(this.config.oauthServerBaseUrl)
-                    .origin,
-            });
-            if (!this.iframeElement?.contentWindow) {
-                const errorMsg = "Iframe content window not available after load.";
-                this.logger.error(errorMsg, {
-                    iframeSrc: this.iframeElement?.src,
-                });
-                reject(new Error(errorMsg));
-                this.cleanup();
-                return;
-            }
-            // Set up postMessage listener for cross-origin communication
-            if (this.messageEventHandler) {
-                window.addEventListener("message", this.messageEventHandler);
-                this.logger.info("Added cross-origin message event listener for auth server communication", {
-                    parentOrigin: window.location.origin,
-                    authServerOrigin: new URL(this.config.oauthServerBaseUrl).origin,
-                });
-            }
-            else {
-                this.logger.error("messageEventHandler was not defined when trying to add listener.");
-            }
-            // Try to detect redirect to our domain
-            try {
-                const currentIframeHref = this.iframeElement.contentWindow.location.href;
-                if (currentIframeHref.startsWith(this.config.redirectUrl)) {
-                    this.logger.info("Iframe has navigated to redirectUrl (same-origin). Setting up DOM observer.");
-                    if (this.iframeElement.contentDocument &&
-                        this.iframeElement.contentDocument.body) {
-                        this.setupSignalObserver(this.iframeElement.contentDocument);
-                    }
-                }
-            }
-            catch (error) {
-                this.logger.error("Error checking iframe href", {
-                    error,
-                    iframeSrc: this.iframeElement?.src,
-                });
-                // This is expected when the iframe is on the auth server domain
-                this.logger.info("Iframe is on auth server domain - using postMessage for communication", {
-                    parentOrigin: window.location.origin,
-                    authServerOrigin: new URL(this.config.oauthServerBaseUrl).origin,
-                });
-            }
-        };
-        this.iframeElement.onerror = (event) => {
-            this.logger.error("Iframe load error", {
-                event,
-                iframeSrc: this.iframeElement?.src,
-                currentOrigin: window.location.origin,
-            });
-            this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
-                detail: "Iframe load error",
-                error: event,
-            });
-            reject(new Error("Iframe failed to load."));
-            this.cleanup();
-        };
-    }
     /**
      * Starts the authentication process
      * @returns A promise that resolves with the authentication result
      * @throws {CivicAuthError} If authentication fails or times out
      */
     async startAuthentication() {
+        this.logger.info("🎬 Starting authentication process", {
+            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", {
+                error: error.message,
+            });
             this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
                 detail: error.message,
             });
             throw error;
         }
         if (this.authPromise) {
-            this.logger.info("Authentication already in progress, returning existing promise");
+            this.logger.info("⏳ Authentication already in progress, returning existing promise");
             return this.authPromise;
         }
         const fullAuthUrl = await this.buildAuthUrl();
-        this.logger.info("Starting authentication process", {
-            constructedIframeUrl: fullAuthUrl,
+        this.logger.info("🔗 Built authentication URL", {
+            url: fullAuthUrl,
             displayMode: this.config.displayMode,
             authProcessTimeout: this.config.authProcessTimeout,
         });
         this.authPromise = new Promise((resolve, reject) => {
             this.authPromiseResolve = resolve;
             this.authPromiseReject = reject;
-            // Handle different display modes
+            this.handleAuthenticationByDisplayMode(fullAuthUrl);
+            this.setupAuthenticationTimeout();
+        });
+        return this.authPromise;
+    }
+    /**
+     * Handle authentication based on display mode
+     */
+    async handleAuthenticationByDisplayMode(fullAuthUrl) {
+        this.logger.info("🎯 Handling authentication with display mode", {
+            displayMode: this.config.displayMode,
+        });
+        try {
             switch (this.config.displayMode) {
                 case "redirect":
-                    // For redirect mode, just navigate to the auth URL
+                    this.logger.info("🌐 Using redirect mode");
                     window.location.href = fullAuthUrl;
                     break;
                 case "new_tab":
-                    this.handleNewTabAuth(fullAuthUrl, reject);
+                    this.logger.info("📱 Using new_tab mode");
+                    if (!this.popupHandler) {
+                        throw new Error("Popup handler not initialized");
+                    }
+                    await this.popupHandler.handleNewTabAuth(fullAuthUrl);
                     break;
                 case "iframe":
-                default:
-                    this.handleIframeAuth(fullAuthUrl, reject);
+                default: {
+                    this.logger.info("🖼️ Using iframe mode");
+                    if (!this.iframeAuthHandler || !this.messageHandler) {
+                        throw new Error("Iframe handler not initialized");
+                    }
+                    const iframeElement = await this.iframeAuthHandler.handleIframeAuth(fullAuthUrl);
+                    this.messageHandler.updateIframeElement(iframeElement);
                     break;
+                }
             }
-            // Set up timeout for all display modes
-            if (this.config.authProcessTimeout &&
-                this.config.authProcessTimeout > 0) {
-                this.logger.debug("Setting up authentication timeout", {
-                    authProcessTimeout: this.config.authProcessTimeout,
-                    displayMode: this.config.displayMode,
-                });
-                this.authProcessTimeoutHandle = window.setTimeout(() => {
-                    this.logger.warn("Authentication timed out", {
-                        displayMode: this.config.displayMode,
-                        currentOrigin: window.location.origin,
-                    });
-                    this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
-                        detail: "Authentication timed out",
-                    });
-                    reject(new Error("Authentication timed out."));
-                    this.cleanup();
-                }, this.config.authProcessTimeout);
+        }
+        catch (error) {
+            if (error instanceof PopupError) {
+                await this.handlePopupErrorWithFallback(fullAuthUrl, error);
+            }
+            else {
+                this.handleAuthError(error instanceof Error ? error : new Error(String(error)));
             }
+        }
+    }
+    /**
+     * Handle popup error with redirect fallback
+     */
+    async handlePopupErrorWithFallback(fullAuthUrl, error) {
+        this.logger.warn("🚫 Popup failed, falling back to redirect mode", {
+            originalDisplayMode: this.config.displayMode,
+            error: error.message,
         });
-        return this.authPromise;
+        this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
+            detail: "Popup blocked, falling back to redirect mode",
+        });
+        try {
+            this.logger.info("🔄 Attempting redirect fallback");
+            // Clean up current authentication attempt
+            this.cleanup();
+            // Always switch to redirect mode for Safari compatibility
+            this.config.displayMode = "redirect";
+            // Regenerate the auth URL with updated display mode in state
+            const fallbackAuthUrl = await this.buildAuthUrl();
+            this.logger.info("🌐 Redirecting to auth URL", { url: fallbackAuthUrl });
+            window.location.href = fallbackAuthUrl;
+            this.logger.info("✅ Redirect initiated successfully");
+        }
+        catch (redirectError) {
+            this.logger.error("❌ Redirect fallback failed", {
+                error: redirectError,
+                redirectUrl: fullAuthUrl,
+            });
+            const fallbackError = new CivicAuthError("Failed to open popup window and redirect fallback failed. Please check your browser's popup settings.", CivicAuthErrorCode.INIT_FAILED);
+            this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
+                detail: fallbackError.message,
+            });
+            this.handleAuthError(fallbackError);
+        }
     }
     /**
-     * Cleans up resources and event listeners
+     * Setup authentication timeout
      */
-    cleanup() {
-        this.logger.info("Cleaning up iframe authentication client");
-        if (this.observer) {
-            this.logger.debug("Disconnecting mutation observer");
-            this.observer.disconnect();
-            this.observer = undefined;
+    setupAuthenticationTimeout() {
+        if (this.config.authProcessTimeout && this.config.authProcessTimeout > 0) {
+            this.logger.debug("⏰ Setting up authentication timeout", {
+                authProcessTimeout: this.config.authProcessTimeout,
+                displayMode: this.config.displayMode,
+            });
+            this.authProcessTimeoutHandle = window.setTimeout(() => {
+                this.logger.error("⏰ Authentication timed out", {
+                    displayMode: this.config.displayMode,
+                    currentOrigin: window.location.origin,
+                    authProcessTimeout: this.config.authProcessTimeout,
+                });
+                this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
+                    detail: "Authentication timed out",
+                });
+                const error = new CivicAuthError("Authentication timed out", CivicAuthErrorCode.AUTH_PROCESS_TIMEOUT);
+                this.handleAuthError(error);
+            }, this.config.authProcessTimeout);
         }
-        if (this.messageEventHandler) {
-            window.removeEventListener("message", this.messageEventHandler);
-            this.logger.debug("Removed 'message' event listener from window.");
+    }
+    /**
+     * Handle successful authentication
+     */
+    handleAuthSuccess(result) {
+        this.logger.info("✅ Authentication successful");
+        this.authPromiseResolve?.(result);
+        this.cleanup();
+    }
+    /**
+     * Handle authentication error
+     */
+    handleAuthError(error) {
+        this.logger.error("❌ Authentication failed", { error: error.message });
+        this.authPromiseReject?.(error);
+        this.cleanup();
+    }
+    /**
+     * Handle popup failure - simplified like React implementation
+     */
+    handlePopupFailure(failedUrl) {
+        this.hasPopupFailed = true;
+        this.logger.warn("Popup failed, using redirect mode instead...", {
+            failedUrl,
+        });
+        // Clean up iframe if it exists
+        if (this.iframeAuthHandler) {
+            this.iframeAuthHandler.cleanupIframe();
         }
-        if (this.iframeManager) {
-            this.logger.debug("Cleaning up iframe manager");
-            this.iframeManager.cleanup();
-            this.iframeManager = undefined;
+        // Always redirect to the failed URL or build a new one
+        if (failedUrl) {
+            window.location.href = failedUrl;
         }
-        // Reset iframe element reference (actual removal handled by IframeManager)
-        if (this.iframeElement) {
-            this.iframeElement = undefined;
+        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);
+            });
         }
-        if (this.authProcessTimeoutHandle) {
-            this.logger.debug("Clearing authentication process timeout");
-            window.clearTimeout(this.authProcessTimeoutHandle);
-            this.authProcessTimeoutHandle = undefined;
+    }
+    /**
+     * Show popup failure message to user
+     */
+    showPopupFailureMessage(customMessage = "Authentication will continue in this window. Please wait...") {
+        const container = this.getContainerElement();
+        if (!container) {
+            this.logger.warn("Cannot show popup failure message - container not found");
+            return;
         }
-        this.logger.debug("Resetting promise state");
-        this.authPromise = undefined;
-        this.authPromiseResolve = undefined;
-        this.authPromiseReject = undefined;
+        const existingMessage = document.getElementById("civic-auth-popup-failure-message");
+        if (existingMessage && existingMessage.parentNode) {
+            existingMessage.parentNode.removeChild(existingMessage);
+        }
+        const messageOverlay = document.createElement("div");
+        messageOverlay.id = "civic-auth-popup-failure-message";
+        messageOverlay.style.cssText =
+            "position:absolute;top:0;left:0;right:0;background:rgba(255,249,196,.95);border:1px solid #f59e0b;border-radius:6px;padding:12px;margin:8px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;font-size:14px;color:#92400e;z-index:1000;box-shadow:0 2px 4px rgba(0,0,0,.1);";
+        messageOverlay.innerHTML =
+            '<div style="display:flex;align-items:center;gap:8px;">' +
+                '<span style="font-size:16px;">⚠️</span>' +
+                "<div>" +
+                "<strong>Popup blocked</strong><br>" +
+                '<span style="font-size:12px;">' +
+                customMessage +
+                "</span>" +
+                "</div>" +
+                "</div>";
+        if (getComputedStyle(container).position === "static") {
+            container.style.position = "relative";
+        }
+        container.appendChild(messageOverlay);
+        setTimeout(() => {
+            if (messageOverlay.parentNode) {
+                messageOverlay.parentNode.removeChild(messageOverlay);
+            }
+        }, 10000);
+        this.logger.info("Popup failure message displayed to user");
+    }
+    /**
+     * Setup popup failure timeout
+     */
+    setupPopupFailureTimeout() {
+        this.popupFailureTimeoutHandle = window.setTimeout(() => {
+            this.logger.info("⏰ Popup failure timeout reached");
+            this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
+                detail: "Authentication timeout - popup failure scenario",
+            });
+            const error = new CivicAuthError("Authentication timeout - popup failure scenario", CivicAuthErrorCode.AUTH_PROCESS_TIMEOUT);
+            this.handleAuthError(error);
+        }, 20000); // 20 seconds
     }
+    /**
+     * Gets the container element for the auth iframe
+     */
+    getContainerElement() {
+        if (typeof this.config.targetContainerElement === "string") {
+            const element = document.getElementById(this.config.targetContainerElement);
+            if (!element) {
+                this.logger.warn(`Container element with ID "${this.config.targetContainerElement}" not found`);
+            }
+            return element;
+        }
+        return this.config.targetContainerElement ?? null;
+    }
+    /**
+     * Handle OAuth callback
+     */
     async handleCallback() {
+        this.logger.info("🔄 Handling OAuth callback", {
+            currentUrl: window.location.href,
+            redirectUrl: this.config.redirectUrl,
+        });
         try {
             const callbackHandled = await handleOAuthRedirectPage({
                 clientId: this.config.clientId,
@@ -585,10 +471,12 @@ export class CivicAuth {
                 },
                 storageAdapter: this.storage,
             });
+            this.logger.info("📋 Callback processing result", { callbackHandled });
             if (callbackHandled) {
-                const successSignal = document.getElementById(CONSTANTS.SUCCESS_SIGNAL_ID);
-                const errorSignal = document.getElementById(CONSTANTS.ERROR_SIGNAL_ID);
+                const successSignal = document.getElementById(CIVIC_AUTH_CONSTANTS.SUCCESS_SIGNAL_ID);
+                const errorSignal = document.getElementById(CIVIC_AUTH_CONSTANTS.ERROR_SIGNAL_ID);
                 if (successSignal) {
+                    this.logger.info("✅ Success signal found");
                     let userInfo = null;
                     const userInfoAttr = successSignal.getAttribute("data-user-info");
                     if (userInfoAttr) {
@@ -596,7 +484,7 @@ export class CivicAuth {
                             userInfo = JSON.parse(userInfoAttr);
                         }
                         catch (error) {
-                            this.logger.error("Failed to parse user info:", { error });
+                            this.logger.error("❌ Failed to parse user info", { error });
                         }
                     }
                     this.config.events?.emit(AuthEvent.SIGN_IN_COMPLETE, {
@@ -605,6 +493,7 @@ export class CivicAuth {
                     });
                 }
                 else if (errorSignal) {
+                    this.logger.error("❌ Error signal found");
                     this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
                         detail: errorSignal.textContent || "Unknown error during callback",
                     });
@@ -612,6 +501,7 @@ export class CivicAuth {
             }
         }
         catch (error) {
+            this.logger.error("❌ Callback handling failed", { error });
             this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
                 detail: error instanceof Error
                     ? error.message
@@ -619,6 +509,32 @@ export class CivicAuth {
             });
         }
     }
+    /**
+     * Cleans up resources and event listeners
+     */
+    cleanup() {
+        this.logger.info("Cleaning up authentication client");
+        // Clean up handlers
+        this.iframeAuthHandler?.cleanupIframe();
+        // 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;
+        // Remove message event listener
+        if (this.messageHandler) {
+            window.removeEventListener("message", this.messageHandler.handleMessage);
+        }
+    }
     /**
      * Get the current session
      */
@@ -685,5 +601,66 @@ export class CivicAuth {
         this.sessionManager = undefined;
         this.logger.info("CivicAuth destroyed");
     }
+    /**
+     * Handle logout
+     */
+    async logout() {
+        if (!this.sessionManager) {
+            throw new Error("SessionManager not initialized. Provide events in config.");
+        }
+        try {
+            this.logger.info("🔄 Starting logout process");
+            this.config.events?.emit(AuthEvent.SIGN_OUT_STARTED, {
+                detail: "Logout process started",
+            });
+            // Get current tokens before clearing them
+            const tokens = await retrieveTokens(this.storage);
+            if (!tokens?.id_token) {
+                this.logger.warn("⚠️ No ID token found, clearing local session only");
+                await clearTokens(this.storage);
+                await this.sessionManager.clearSession();
+                this.config.events?.emit(AuthEvent.SIGN_OUT_COMPLETE, {
+                    detail: "Local session cleared",
+                });
+                return;
+            }
+            if (!this.endpoints) {
+                throw new Error("OAuth endpoints not initialized");
+            }
+            // Generate a state for logout
+            const state = generateState({
+                displayMode: this.config.displayMode || "iframe",
+            });
+            // Generate logout URL
+            const logoutUrl = await generateOauthLogoutUrl({
+                clientId: this.config.clientId,
+                redirectUrl: this.config.redirectUrl,
+                idToken: tokens.id_token,
+                state: state,
+                oauthServer: this.config.oauthServerBaseUrl,
+            });
+            this.logger.info("🔗 Generated logout URL", {
+                logoutUrl: logoutUrl.toString(),
+            });
+            // Clear local tokens and session
+            await clearTokens(this.storage);
+            await this.sessionManager.clearSession();
+            // Emit logout complete event before redirect
+            this.config.events?.emit(AuthEvent.SIGN_OUT_COMPLETE, {
+                detail: "Logout successful",
+            });
+            // Redirect to logout URL
+            this.logger.info("🌐 Redirecting to logout URL");
+            window.location.href = logoutUrl.toString();
+        }
+        catch (error) {
+            this.logger.error("❌ Logout failed", { error });
+            this.config.events?.emit(AuthEvent.SIGN_OUT_ERROR, {
+                detail: error instanceof Error ? error.message : String(error),
+            });
+            throw new CivicAuthError("Logout failed", CivicAuthErrorCode.LOGOUT_FAILED);
+        }
+    }
 }
+export { CivicAuthErrorCode } from "./types/AuthTypes.js";
 //# sourceMappingURL=CivicAuth.js.map