@civic/auth 0.6.1-beta.4 → 0.7.0-beta.1

package/dist/vanillajs/auth/handlers/MessageHandler.js

@@ -0,0 +1,367 @@
+import { AuthEvent } from "../../types/index.js";
+import { CivicAuthError, CivicAuthErrorCode } from "../types/AuthTypes.js";
+import { createLogger as createLoggerFn } from "../../utils/logger.js";
+/**
+ * MessageHandler - Handles postMessage communication and authentication flow logic
+ * Processes messages from iframe, validates origins, and manages auth state transitions
+ */
+export class MessageHandler {
+    config;
+    logger = createLoggerFn("message-handler");
+    iframeElement;
+    onAuthSuccess;
+    onAuthError;
+    onPopupFailure;
+    cleanup;
+    constructor(handlerConfig) {
+        this.config = handlerConfig.config;
+        this.iframeElement = handlerConfig.iframeElement;
+        this.onAuthSuccess = handlerConfig.onAuthSuccess;
+        this.onAuthError = handlerConfig.onAuthError;
+        this.onPopupFailure = handlerConfig.onPopupFailure;
+        this.cleanup = handlerConfig.cleanup;
+    }
+    /**
+     * Updates the iframe element reference used for message validation.
+     *
+     * This method allows updating the iframe element after the MessageHandler
+     * has been instantiated, which is useful when the iframe is created
+     * dynamically after the handler setup.
+     *
+     * @param iframeElement - The new iframe element to associate with this handler
+     */
+    updateIframeElement(iframeElement) {
+        this.iframeElement = iframeElement;
+    }
+    /**
+     * Main message handler for processing postMessage events.
+     *
+     * Validates message origin and source, then routes valid messages to
+     * appropriate handlers. This is the entry point for all iframe communication.
+     *
+     * @param event - The MessageEvent received from the iframe or other sources
+     */
+    handleMessage = (event) => {
+        const expectedOrigin = new URL(this.config.oauthServerBaseUrl).origin;
+        this.logIncomingMessage(event, expectedOrigin);
+        if (!this.isValidMessageSource(event, expectedOrigin)) {
+            return;
+        }
+        this.handleValidMessage(event);
+    };
+    /**
+     * Logs incoming message details for debugging purposes.
+     *
+     * Provides comprehensive logging of message properties including origin,
+     * source validation, and iframe state for troubleshooting communication issues.
+     *
+     * @param event - The MessageEvent to log
+     * @param expectedOrigin - The expected origin for comparison
+     */
+    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,
+        });
+    }
+    /**
+     * Validates that a message comes from the expected origin and source.
+     *
+     * Performs security checks to ensure messages are only processed from
+     * the configured OAuth server origin and the designated iframe element.
+     *
+     * @param event - The MessageEvent to validate
+     * @param expectedOrigin - The expected origin URL for the message
+     * @returns True if the message source and origin are valid, false otherwise
+     */
+    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;
+    }
+    /**
+     * Processes messages that have passed origin and source validation.
+     *
+     * Routes validated messages to specific handlers based on message type,
+     * including civicloginApp messages, iframe resizer messages, and standard auth messages.
+     *
+     * @param event - The validated MessageEvent to process
+     */
+    handleValidMessage(event) {
+        this.logger.info("Message from configured iframe source and origin received", {
+            data: event.data,
+            iframeSrc: this.iframeElement?.src,
+        });
+        const message = event.data;
+        this.logger.debug("Processing iframe message", {
+            messageType: typeof message,
+            hasType: message && typeof message === "object" && "type" in message,
+            hasSource: message && typeof message === "object" && "source" in message,
+            messageKeys: message && typeof message === "object" ? Object.keys(message) : [],
+            rawData: message,
+        });
+        // Handle civicloginApp messages
+        if (this.isCivicLoginAppMessage(message)) {
+            this.handleCivicLoginAppMessage(message);
+            return;
+        }
+        // Handle iframe resizer messages
+        if (this.isIframeResizerMessage(message)) {
+            this.handleIframeResizerMessage(message);
+            return;
+        }
+        // Handle standard auth messages
+        this.handleStandardAuthMessage(message);
+    }
+    /**
+     * Type guard to identify civicloginApp messages.
+     *
+     * Checks if a message object has the structure and source property
+     * that identifies it as coming from the civicloginApp.
+     *
+     * @param message - The message object to check
+     * @returns True if the message is a LoginAppMessage, false otherwise
+     */
+    isCivicLoginAppMessage(message) {
+        return (message !== null &&
+            typeof message === "object" &&
+            "source" in message &&
+            message.source === "civicloginApp");
+    }
+    /**
+     * Handles messages originating from the civicloginApp.
+     *
+     * Processes various civicloginApp message types including authentication errors,
+     * popup failures, design updates, and other app-specific communications.
+     * Validates client ID matches before processing.
+     *
+     * @param message - The validated civicloginApp message to process
+     */
+    handleCivicLoginAppMessage(message) {
+        this.logger.info("Received civicloginApp message", {
+            type: message.type,
+            clientId: message.clientId,
+            data: message.data,
+        });
+        // Validate clientId matches our config
+        if (message.clientId !== this.config.clientId) {
+            this.logger.warn("civicloginApp message clientId mismatch", {
+                received: message.clientId,
+                expected: this.config.clientId,
+            });
+            return;
+        }
+        switch (message.type) {
+            case "auth_error":
+            case "auth_error_try_again":
+                this.handleCivicLoginAppError(message);
+                break;
+            case "generatePopupFailed":
+                this.handlePopupFailure(message);
+                break;
+            case "design":
+                this.logger.debug("civicloginApp design message", {
+                    data: message.data,
+                });
+                break;
+            default:
+                this.handleUnknownCivicLoginAppMessage(message);
+                break;
+        }
+    }
+    /**
+     * Handles authentication error messages from civicloginApp.
+     *
+     * Processes auth_error and auth_error_try_again messages, creates
+     * appropriate error objects, emits error events, and triggers cleanup.
+     *
+     * @param message - The civicloginApp error message to process
+     */
+    handleCivicLoginAppError(message) {
+        this.logger.error("civicloginApp authentication error", {
+            type: message.type,
+            data: message.data,
+        });
+        const error = new CivicAuthError(`Login app error: ${message.type}`, CivicAuthErrorCode.INVALID_MESSAGE);
+        this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
+            detail: error.message,
+            error: message.data,
+        });
+        this.onAuthError(error);
+        this.cleanup();
+    }
+    /**
+     * Handles popup generation failure messages from civicloginApp.
+     *
+     * Processes generatePopupFailed messages, extracts the failed URL,
+     * emits appropriate events, and triggers the popup failure callback
+     * to enable fallback authentication methods.
+     *
+     * @param message - The civicloginApp popup failure message to process
+     */
+    handlePopupFailure(message) {
+        this.logger.warn("civicloginApp popup generation failed", {
+            data: message.data,
+        });
+        const failedUrl = message.data
+            ?.url;
+        if (failedUrl) {
+            this.logger.info("Popup failed for URL, considering fallback options", {
+                failedUrl,
+                displayMode: this.config.displayMode,
+            });
+            this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
+                detail: "Popup blocked by browser - switching to redirect mode",
+                error: {
+                    type: "popup_blocked",
+                    failedUrl,
+                    suggestion: "The browser blocked a popup window. Redirecting to complete authentication in a new page.",
+                },
+            });
+        }
+        this.onPopupFailure(failedUrl);
+    }
+    /**
+     * Handles unknown or unrecognized civicloginApp message types.
+     *
+     * Provides fallback handling for unexpected message types, with special
+     * logic to detect potential success messages that don't match standard types.
+     *
+     * @param message - The unrecognized civicloginApp message to process
+     */
+    handleUnknownCivicLoginAppMessage(message) {
+        this.logger.debug("Unhandled civicloginApp message type", {
+            type: message.type,
+            data: message.data,
+        });
+        // Check if this might be a success message with a different type
+        if (message.type && message.type.toLowerCase().includes("success")) {
+            this.logger.info("Potential success message from civicloginApp", {
+                type: message.type,
+                data: message.data,
+            });
+            this.handleAuthSuccess({
+                type: "auth_success",
+                detail: `civicloginApp success: ${message.type}`,
+                data: message.data,
+            });
+        }
+    }
+    /**
+     * Type guard to identify iframe resizer messages.
+     *
+     * Checks if a message is related to iframe resizing functionality,
+     * including both civic-specific resize messages and iFrameResizerChild messages.
+     *
+     * @param message - The message object to check
+     * @returns True if the message is an iframe resizer message, false otherwise
+     */
+    isIframeResizerMessage(message) {
+        return ((message !== null &&
+            typeof message === "object" &&
+            "type" in message &&
+            (message.type === "civic-iframe-resize" ||
+                message.type ===
+                    "civic-iframe-ready")) ||
+            (typeof message === "string" && message.includes("iFrameResizerChild")));
+    }
+    /**
+     * Handles iframe resizer messages for dynamic iframe sizing.
+     *
+     * Processes messages related to iframe resizing, including height adjustments
+     * and ready state notifications from the iframe resizer library.
+     *
+     * @param message - The iframe resizer message to process
+     */
+    handleIframeResizerMessage(message) {
+        if (typeof message === "string") {
+            this.logger.debug("Received iframe resizer child message", { message });
+        }
+        else if (message && typeof message === "object" && message !== null) {
+            const messageObj = message;
+            this.logger.debug("Received iframe resizer message", {
+                type: messageObj.type,
+                height: messageObj.height,
+            });
+        }
+    }
+    /**
+     * Handles standard authentication messages.
+     *
+     * Processes auth_success and auth_error messages that follow the standard
+     * authentication message format, routing them to appropriate success or error handlers.
+     *
+     * @param message - The standard auth message to process
+     */
+    handleStandardAuthMessage(message) {
+        const messageObj = message && typeof message === "object" && message !== null
+            ? message
+            : null;
+        const messageType = messageObj?.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, civicloginApp, iframe-resizer)", {
+                    data: message,
+                    messageType: typeof message,
+                    hasType: messageObj?.type ?? "none",
+                });
+        }
+    }
+    /**
+     * Handles successful authentication completion.
+     *
+     * Processes authentication success messages, emits success events,
+     * triggers the success callback with authentication results, and performs cleanup.
+     *
+     * @param data - The authentication success message containing result data
+     */
+    handleAuthSuccess(data) {
+        this.config.events?.emit(AuthEvent.SIGN_IN_COMPLETE, {
+            detail: "Success signal received via postMessage",
+            data,
+        });
+        this.onAuthSuccess(data?.data || {});
+        this.cleanup();
+    }
+    /**
+     * Handles authentication errors.
+     *
+     * Processes authentication error messages, creates appropriate error objects,
+     * emits error events, triggers the error callback, and performs cleanup.
+     *
+     * @param data - The authentication error message containing error details
+     */
+    handleAuthError(data) {
+        this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {
+            detail: "Error signal received via postMessage",
+            error: data,
+        });
+        const error = new CivicAuthError(data?.detail || "Error signal received via postMessage", CivicAuthErrorCode.INVALID_MESSAGE);
+        this.onAuthError(error);
+        this.cleanup();
+    }
+}
+//# sourceMappingURL=MessageHandler.js.map

package/dist/vanillajs/auth/handlers/MessageHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageHandler.js","sourceRoot":"","sources":["../../../../src/vanillajs/auth/handlers/MessageHandler.ts"],"names":[],"mappings":"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","sourcesContent":["import { AuthEvent } from \"../../types/index.js\";\nimport type { AuthResult } from \"../../types/index.js\";\nimport type {\n  IframeMessage,\n  AuthMessage,\n  LoginAppMessage,\n  ProcessedCivicAuthConfig,\n} from \"../types/AuthTypes.js\";\nimport { CivicAuthError, CivicAuthErrorCode } from \"../types/AuthTypes.js\";\nimport type { createLogger } from \"../../utils/logger.js\";\nimport { createLogger as createLoggerFn } from \"../../utils/logger.js\";\n\nexport interface MessageHandlerConfig {\n  config: ProcessedCivicAuthConfig;\n  logger: ReturnType<typeof createLogger>;\n  iframeElement?: HTMLIFrameElement;\n  onAuthSuccess: (result: AuthResult) => void;\n  onAuthError: (error: Error) => void;\n  onPopupFailure: (failedUrl?: string) => void;\n  cleanup: () => void;\n}\n\n/**\n * MessageHandler - Handles postMessage communication and authentication flow logic\n * Processes messages from iframe, validates origins, and manages auth state transitions\n */\nexport class MessageHandler {\n  private config: ProcessedCivicAuthConfig;\n  private logger = createLoggerFn(\"message-handler\");\n  private iframeElement?: HTMLIFrameElement;\n  private onAuthSuccess: (result: AuthResult) => void;\n  private onAuthError: (error: Error) => void;\n  private onPopupFailure: (failedUrl?: string) => void;\n  private cleanup: () => void;\n\n  constructor(handlerConfig: MessageHandlerConfig) {\n    this.config = handlerConfig.config;\n    this.iframeElement = handlerConfig.iframeElement;\n    this.onAuthSuccess = handlerConfig.onAuthSuccess;\n    this.onAuthError = handlerConfig.onAuthError;\n    this.onPopupFailure = handlerConfig.onPopupFailure;\n    this.cleanup = handlerConfig.cleanup;\n  }\n\n  /**\n   * Updates the iframe element reference used for message validation.\n   *\n   * This method allows updating the iframe element after the MessageHandler\n   * has been instantiated, which is useful when the iframe is created\n   * dynamically after the handler setup.\n   *\n   * @param iframeElement - The new iframe element to associate with this handler\n   */\n  public updateIframeElement(iframeElement: HTMLIFrameElement): void {\n    this.iframeElement = iframeElement;\n  }\n\n  /**\n   * Main message handler for processing postMessage events.\n   *\n   * Validates message origin and source, then routes valid messages to\n   * appropriate handlers. This is the entry point for all iframe communication.\n   *\n   * @param event - The MessageEvent received from the iframe or other sources\n   */\n  public handleMessage = (event: MessageEvent): void => {\n    const expectedOrigin = new URL(this.config.oauthServerBaseUrl).origin;\n    this.logIncomingMessage(event, expectedOrigin);\n\n    if (!this.isValidMessageSource(event, expectedOrigin)) {\n      return;\n    }\n\n    this.handleValidMessage(event);\n  };\n\n  /**\n   * Logs incoming message details for debugging purposes.\n   *\n   * Provides comprehensive logging of message properties including origin,\n   * source validation, and iframe state for troubleshooting communication issues.\n   *\n   * @param event - The MessageEvent to log\n   * @param expectedOrigin - The expected origin for comparison\n   */\n  private logIncomingMessage(\n    event: MessageEvent,\n    expectedOrigin: string,\n  ): void {\n    this.logger.debug(\"Global window received message:\", {\n      data: event.data,\n      origin: event.origin,\n      sourceProvided: !!event.source,\n      iframeContentWindow: this.iframeElement?.contentWindow,\n      expectedIframeOrigin: expectedOrigin,\n    });\n  }\n\n  /**\n   * Validates that a message comes from the expected origin and source.\n   *\n   * Performs security checks to ensure messages are only processed from\n   * the configured OAuth server origin and the designated iframe element.\n   *\n   * @param event - The MessageEvent to validate\n   * @param expectedOrigin - The expected origin URL for the message\n   * @returns True if the message source and origin are valid, false otherwise\n   */\n  private isValidMessageSource(\n    event: MessageEvent,\n    expectedOrigin: string,\n  ): boolean {\n    const isValidOrigin = event.origin === expectedOrigin;\n    const isValidSource = event.source === this.iframeElement?.contentWindow;\n\n    if (!isValidOrigin) {\n      this.logger.warn(\"Ignored message from unexpected origin.\", {\n        receivedOrigin: event.origin,\n        expectedOrigin,\n        iframeSrc: this.iframeElement?.src,\n      });\n    }\n\n    if (!isValidSource) {\n      this.logger.warn(\"Ignored message from unexpected source.\", {\n        isSourceProvided: !!event.source,\n        isIframeContentWindowAvailable: !!this.iframeElement?.contentWindow,\n        iframeSrc: this.iframeElement?.src,\n      });\n    }\n\n    return isValidOrigin && isValidSource;\n  }\n\n  /**\n   * Processes messages that have passed origin and source validation.\n   *\n   * Routes validated messages to specific handlers based on message type,\n   * including civicloginApp messages, iframe resizer messages, and standard auth messages.\n   *\n   * @param event - The validated MessageEvent to process\n   */\n  private handleValidMessage(event: MessageEvent): void {\n    this.logger.info(\n      \"Message from configured iframe source and origin received\",\n      {\n        data: event.data,\n        iframeSrc: this.iframeElement?.src,\n      },\n    );\n\n    const message = event.data as IframeMessage;\n\n    this.logger.debug(\"Processing iframe message\", {\n      messageType: typeof message,\n      hasType: message && typeof message === \"object\" && \"type\" in message,\n      hasSource: message && typeof message === \"object\" && \"source\" in message,\n      messageKeys:\n        message && typeof message === \"object\" ? Object.keys(message) : [],\n      rawData: message,\n    });\n\n    // Handle civicloginApp messages\n    if (this.isCivicLoginAppMessage(message)) {\n      this.handleCivicLoginAppMessage(message);\n      return;\n    }\n\n    // Handle iframe resizer messages\n    if (this.isIframeResizerMessage(message)) {\n      this.handleIframeResizerMessage(message);\n      return;\n    }\n\n    // Handle standard auth messages\n    this.handleStandardAuthMessage(message);\n  }\n\n  /**\n   * Type guard to identify civicloginApp messages.\n   *\n   * Checks if a message object has the structure and source property\n   * that identifies it as coming from the civicloginApp.\n   *\n   * @param message - The message object to check\n   * @returns True if the message is a LoginAppMessage, false otherwise\n   */\n  private isCivicLoginAppMessage(message: unknown): message is LoginAppMessage {\n    return (\n      message !== null &&\n      typeof message === \"object\" &&\n      \"source\" in message &&\n      (message as Record<string, unknown>).source === \"civicloginApp\"\n    );\n  }\n\n  /**\n   * Handles messages originating from the civicloginApp.\n   *\n   * Processes various civicloginApp message types including authentication errors,\n   * popup failures, design updates, and other app-specific communications.\n   * Validates client ID matches before processing.\n   *\n   * @param message - The validated civicloginApp message to process\n   */\n  private handleCivicLoginAppMessage(message: LoginAppMessage): void {\n    this.logger.info(\"Received civicloginApp message\", {\n      type: message.type,\n      clientId: message.clientId,\n      data: message.data,\n    });\n\n    // Validate clientId matches our config\n    if (message.clientId !== this.config.clientId) {\n      this.logger.warn(\"civicloginApp message clientId mismatch\", {\n        received: message.clientId,\n        expected: this.config.clientId,\n      });\n      return;\n    }\n\n    switch (message.type) {\n      case \"auth_error\":\n      case \"auth_error_try_again\":\n        this.handleCivicLoginAppError(message);\n        break;\n      case \"generatePopupFailed\":\n        this.handlePopupFailure(message);\n        break;\n      case \"design\":\n        this.logger.debug(\"civicloginApp design message\", {\n          data: message.data,\n        });\n        break;\n      default:\n        this.handleUnknownCivicLoginAppMessage(message);\n        break;\n    }\n  }\n\n  /**\n   * Handles authentication error messages from civicloginApp.\n   *\n   * Processes auth_error and auth_error_try_again messages, creates\n   * appropriate error objects, emits error events, and triggers cleanup.\n   *\n   * @param message - The civicloginApp error message to process\n   */\n  private handleCivicLoginAppError(message: LoginAppMessage): void {\n    this.logger.error(\"civicloginApp authentication error\", {\n      type: message.type,\n      data: message.data,\n    });\n\n    const error = new CivicAuthError(\n      `Login app error: ${message.type}`,\n      CivicAuthErrorCode.INVALID_MESSAGE,\n    );\n\n    this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {\n      detail: error.message,\n      error: message.data,\n    });\n\n    this.onAuthError(error);\n    this.cleanup();\n  }\n\n  /**\n   * Handles popup generation failure messages from civicloginApp.\n   *\n   * Processes generatePopupFailed messages, extracts the failed URL,\n   * emits appropriate events, and triggers the popup failure callback\n   * to enable fallback authentication methods.\n   *\n   * @param message - The civicloginApp popup failure message to process\n   */\n  private handlePopupFailure(message: LoginAppMessage): void {\n    this.logger.warn(\"civicloginApp popup generation failed\", {\n      data: message.data,\n    });\n\n    const failedUrl = (message.data as Record<string, unknown> | undefined)\n      ?.url as string | undefined;\n    if (failedUrl) {\n      this.logger.info(\"Popup failed for URL, considering fallback options\", {\n        failedUrl,\n        displayMode: this.config.displayMode,\n      });\n\n      this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {\n        detail: \"Popup blocked by browser - switching to redirect mode\",\n        error: {\n          type: \"popup_blocked\",\n          failedUrl,\n          suggestion:\n            \"The browser blocked a popup window. Redirecting to complete authentication in a new page.\",\n        },\n      });\n    }\n\n    this.onPopupFailure(failedUrl);\n  }\n\n  /**\n   * Handles unknown or unrecognized civicloginApp message types.\n   *\n   * Provides fallback handling for unexpected message types, with special\n   * logic to detect potential success messages that don't match standard types.\n   *\n   * @param message - The unrecognized civicloginApp message to process\n   */\n  private handleUnknownCivicLoginAppMessage(message: LoginAppMessage): void {\n    this.logger.debug(\"Unhandled civicloginApp message type\", {\n      type: message.type,\n      data: message.data,\n    });\n\n    // Check if this might be a success message with a different type\n    if (message.type && message.type.toLowerCase().includes(\"success\")) {\n      this.logger.info(\"Potential success message from civicloginApp\", {\n        type: message.type,\n        data: message.data,\n      });\n\n      this.handleAuthSuccess({\n        type: \"auth_success\",\n        detail: `civicloginApp success: ${message.type}`,\n        data: message.data,\n      });\n    }\n  }\n\n  /**\n   * Type guard to identify iframe resizer messages.\n   *\n   * Checks if a message is related to iframe resizing functionality,\n   * including both civic-specific resize messages and iFrameResizerChild messages.\n   *\n   * @param message - The message object to check\n   * @returns True if the message is an iframe resizer message, false otherwise\n   */\n  private isIframeResizerMessage(message: unknown): boolean {\n    return (\n      (message !== null &&\n        typeof message === \"object\" &&\n        \"type\" in message &&\n        ((message as Record<string, unknown>).type === \"civic-iframe-resize\" ||\n          (message as Record<string, unknown>).type ===\n            \"civic-iframe-ready\")) ||\n      (typeof message === \"string\" && message.includes(\"iFrameResizerChild\"))\n    );\n  }\n\n  /**\n   * Handles iframe resizer messages for dynamic iframe sizing.\n   *\n   * Processes messages related to iframe resizing, including height adjustments\n   * and ready state notifications from the iframe resizer library.\n   *\n   * @param message - The iframe resizer message to process\n   */\n  private handleIframeResizerMessage(message: unknown): void {\n    if (typeof message === \"string\") {\n      this.logger.debug(\"Received iframe resizer child message\", { message });\n    } else if (message && typeof message === \"object\" && message !== null) {\n      const messageObj = message as Record<string, unknown>;\n      this.logger.debug(\"Received iframe resizer message\", {\n        type: messageObj.type,\n        height: messageObj.height,\n      });\n    }\n  }\n\n  /**\n   * Handles standard authentication messages.\n   *\n   * Processes auth_success and auth_error messages that follow the standard\n   * authentication message format, routing them to appropriate success or error handlers.\n   *\n   * @param message - The standard auth message to process\n   */\n  private handleStandardAuthMessage(message: unknown): void {\n    const messageObj =\n      message && typeof message === \"object\" && message !== null\n        ? (message as Record<string, unknown>)\n        : null;\n    const messageType = messageObj?.type;\n\n    switch (messageType) {\n      case \"auth_success\":\n        this.handleAuthSuccess(message as AuthMessage);\n        break;\n      case \"auth_error\":\n        this.handleAuthError(message as AuthMessage);\n        break;\n      default:\n        this.logger.debug(\n          \"Message from iframe did not match expected types (auth_success, auth_error, civicloginApp, iframe-resizer)\",\n          {\n            data: message,\n            messageType: typeof message,\n            hasType: messageObj?.type ?? \"none\",\n          },\n        );\n    }\n  }\n\n  /**\n   * Handles successful authentication completion.\n   *\n   * Processes authentication success messages, emits success events,\n   * triggers the success callback with authentication results, and performs cleanup.\n   *\n   * @param data - The authentication success message containing result data\n   */\n  private handleAuthSuccess(data: AuthMessage): void {\n    this.config.events?.emit(AuthEvent.SIGN_IN_COMPLETE, {\n      detail: \"Success signal received via postMessage\",\n      data,\n    });\n    this.onAuthSuccess((data?.data as AuthResult) || {});\n    this.cleanup();\n  }\n\n  /**\n   * Handles authentication errors.\n   *\n   * Processes authentication error messages, creates appropriate error objects,\n   * emits error events, triggers the error callback, and performs cleanup.\n   *\n   * @param data - The authentication error message containing error details\n   */\n  private handleAuthError(data: AuthMessage): void {\n    this.config.events?.emit(AuthEvent.SIGN_IN_ERROR, {\n      detail: \"Error signal received via postMessage\",\n      error: data,\n    });\n\n    const error = new CivicAuthError(\n      data?.detail || \"Error signal received via postMessage\",\n      CivicAuthErrorCode.INVALID_MESSAGE,\n    );\n\n    this.onAuthError(error);\n    this.cleanup();\n  }\n}\n"]}

package/dist/vanillajs/auth/{OAuthCallbackHandler.d.ts → handlers/OAuthCallbackHandler.d.ts}

@@ -18,24 +18,19 @@
  * - Shared token storage utilities for consistent state management
  *
  * @example
- * ```typescript
- * // In an OAuth callback page
- * import { handleOAuthRedirectPage, LocalStorageAdapter } from '@civic/auth/vanillajs';
- *
- * const handled = await handleOAuthRedirectPage({
+ * ```javascript
+ * // Basic usage
+ * const config = {
  *   clientId: 'your-client-id',
- *   redirectUrl: 'https://your-app.com/callback',
- *   oauthServer: 'https://auth.civic.com/oauth/',
- *   textSignals: {
- *     success: 'Authentication successful!',
- *     error: 'Authentication failed!'
- *   },
- *   storageAdapter: new LocalStorageAdapter()
- * });
+ *   redirectUrl: 'https://yourapp.com/callback',
+ *   oauthServer: 'https://auth.civic.com/oauth',
+ *   scopes: ['openid', 'profile', 'email']
+ * };
+ * const result = await handleOAuthRedirectPage(config);
  * ```
  */
-import { getCurrentLogger } from "../utils/logger.js";
-import type { AuthStorage, OIDCTokenResponseBody } from "../../types.js";
+import type { getCurrentLogger } from "../../utils/logger.js";
+import type { AuthStorage, OIDCTokenResponseBody } from "../../../types.js";
 /**
  * Store tokens using the shared utilities from /shared/lib
  * This ensures consistency with the React implementation and also handles user session storage
@@ -71,19 +66,15 @@ export interface HandleOAuthRedirectConfig {
  * @returns Promise<boolean> - Returns true if callback was handled, false otherwise
  *
  * @example
- * ```typescript
- * import { handleOAuthRedirectPage, LocalStorageAdapter } from '@civic/auth/vanillajs';
- *
- * const handled = await handleOAuthRedirectPage({
+ * ```javascript
+ * // Using storeTokens with default iframe mode
+ * const config = {
  *   clientId: 'your-client-id',
- *   redirectUrl: 'https://your-app.com/callback',
- *   oauthServer: 'https://auth.civic.com/oauth/',
- *   textSignals: {
- *     success: 'Authentication successful!',
- *     error: 'Authentication failed!'
- *   },
- *   storageAdapter: new LocalStorageAdapter()
- * });
+ *   redirectUrl: 'https://yourapp.com/callback',
+ *   oauthServer: 'https://auth.civic.com/oauth',
+ *   scopes: ['openid', 'profile', 'email']
+ * };
+ * await storeTokens(params, config);
  * ```
  */
 export declare function handleOAuthRedirectPage(config: HandleOAuthRedirectConfig): Promise<boolean>;

package/dist/vanillajs/auth/handlers/OAuthCallbackHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthCallbackHandler.d.ts","sourceRoot":"","sources":["../../../../src/vanillajs/auth/handlers/OAuthCallbackHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAWH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE5E;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,qBAAqB,EAC7B,cAAc,EAAE,WAAW,EAC3B,cAAc;;;;;CAAiC,GAC9C,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyBxB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,cAAc,EAAE,WAAW,CAAC;IAC5B,MAAM,CAAC,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,OAAO,CAAC,CA2PlB"}