@civic/auth 0.13.0 → 0.13.1-beta.0

package/dist/server/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/server/config.ts"],"names":[],"mappings":"","sourcesContent":["import type { Endpoints } from \"@/types.ts\";\n\n/**\n * Configuration for backend authentication endpoints\n * Allows customization of API endpoints when using backend integration (loginUrl)\n */\nexport interface BackendEndpoints {\n  /** Endpoint for token refresh (default: \"/auth/refresh\") */\n  refresh?: string;\n  /** Endpoint for logout (default: \"/auth/logout\") */\n  logout?: string;\n  /** Endpoint for user info and session validation (default: \"/auth/user\") */\n  user?: string;\n  /** Endpoint for clearing session/cookies server-side (default: \"/auth/clearsession\") */\n  clearSession?: string;\n}\n\nexport type AuthConfig = {\n  clientSecret?: string; // Optional client secret for confidential clients\n  pkce?: boolean; // Optional PKCE flag, defaults to true if not specified\n  redirectUrl: string;\n  oauthServer?: string;\n  oauthServerBaseUrl?: string;\n  challengeUrl?: string;\n  refreshUrl?: string;\n  endpointOverrides?: Partial<Endpoints> | undefined;\n  postLogoutRedirectUrl?: string;\n  /**\n   * Custom backend endpoints configuration for backend integration\n   * Only used when loginUrl is provided. Allows overriding default endpoints.\n   */\n  backendEndpoints?: BackendEndpoints;\n  /**\n   * Optional URL to redirect frontend clients back to after successful authentication.\n   * When provided, the backend will automatically redirect SPA clients to this URL\n   * instead of traditional server-side redirects. Useful for backend + frontend integration.\n   * Example: \"http://localhost:5173\" or \"https://your-spa.com\"\n   */\n  loginSuccessUrl?: string;\n  /**\n   * Optional CORS configuration for authentication endpoints\n   */\n  cors?: {\n    origin?: string | string[] | boolean;\n    credentials?: boolean;\n    optionsSuccessStatus?: number;\n    allowedHeaders?: string[];\n    exposedHeaders?: string[];\n  };\n  /**\n   * Optional logger configuration for authentication middleware\n   */\n  logger?: {\n    enabled?: boolean; // Defaults to true if not specified\n  };\n  /**\n   * Optional flag to disable iframe detection in handleCallback.\n   * When true, callbacks will always attempt to redirect instead of returning HTML content for iframes.\n   * Useful for testing environments like Cypress where iframe detection may interfere with expected redirects.\n   */\n  disableIframeDetection?: boolean;\n  /**\n   * Optional flag to disable automatic token refresh functionality.\n   * When true, the SDK will not attempt to refresh expired tokens automatically.\n   * This affects both server-side session validation and client-side auto-refresh.\n   * Useful for applications that want to handle token lifecycle manually.\n   */\n  disableRefresh?: boolean;\n} & (\n  | {\n      /** OAuth client ID - required for standard OAuth flow */\n      clientId: string;\n      /** Custom login URL for backend integration - optional */\n      loginUrl?: string;\n    }\n  | {\n      /** OAuth client ID - optional when using backend integration */\n      clientId?: string;\n      /** Custom login URL for backend integration - required when clientId is not provided */\n      loginUrl: string;\n    }\n);\n"]}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/server/config.ts"],"names":[],"mappings":"","sourcesContent":["import type { Endpoints } from \"@/types.ts\";\n\n/**\n * Controls how deep links (original URLs) are handled after authentication.\n *\n * - `\"fullUrl\"`: Redirect to the original URL the user tried to access.\n *   `loginSuccessUrl` is used as fallback only when no deep link exists.\n * - `\"queryParamsOnly\"`: Redirect to `loginSuccessUrl`, but merge query params from original URL.\n * - `\"disabled\"`: No deep link preservation. Always use `loginSuccessUrl`.\n *\n * @default \"fullUrl\"\n */\nexport type DeepLinkHandling = \"fullUrl\" | \"queryParamsOnly\" | \"disabled\";\n\n/**\n * Configuration for backend authentication endpoints\n * Allows customization of API endpoints when using backend integration (loginUrl)\n */\nexport interface BackendEndpoints {\n  /** Endpoint for token refresh (default: \"/auth/refresh\") */\n  refresh?: string;\n  /** Endpoint for logout (default: \"/auth/logout\") */\n  logout?: string;\n  /** Endpoint for user info and session validation (default: \"/auth/user\") */\n  user?: string;\n  /** Endpoint for clearing session/cookies server-side (default: \"/auth/clearsession\") */\n  clearSession?: string;\n}\n\nexport type AuthConfig = {\n  clientSecret?: string; // Optional client secret for confidential clients\n  pkce?: boolean; // Optional PKCE flag, defaults to true if not specified\n  redirectUrl: string;\n  oauthServer?: string;\n  oauthServerBaseUrl?: string;\n  challengeUrl?: string;\n  refreshUrl?: string;\n  endpointOverrides?: Partial<Endpoints> | undefined;\n  postLogoutRedirectUrl?: string;\n  /**\n   * Custom backend endpoints configuration for backend integration\n   * Only used when loginUrl is provided. Allows overriding default endpoints.\n   */\n  backendEndpoints?: BackendEndpoints;\n  /**\n   * Optional URL to redirect frontend clients back to after successful authentication.\n   * When provided, the backend will automatically redirect SPA clients to this URL\n   * instead of traditional server-side redirects. Useful for backend + frontend integration.\n   * Example: \"http://localhost:5173\" or \"https://your-spa.com\"\n   */\n  loginSuccessUrl?: string;\n  /**\n   * Optional CORS configuration for authentication endpoints\n   */\n  cors?: {\n    origin?: string | string[] | boolean;\n    credentials?: boolean;\n    optionsSuccessStatus?: number;\n    allowedHeaders?: string[];\n    exposedHeaders?: string[];\n  };\n  /**\n   * Optional logger configuration for authentication middleware\n   */\n  logger?: {\n    enabled?: boolean; // Defaults to true if not specified\n  };\n  /**\n   * Optional flag to disable iframe detection in handleCallback.\n   * When true, callbacks will always attempt to redirect instead of returning HTML content for iframes.\n   * Useful for testing environments like Cypress where iframe detection may interfere with expected redirects.\n   */\n  disableIframeDetection?: boolean;\n  /**\n   * Optional flag to disable automatic token refresh functionality.\n   * When true, the SDK will not attempt to refresh expired tokens automatically.\n   * This affects both server-side session validation and client-side auto-refresh.\n   * Useful for applications that want to handle token lifecycle manually.\n   */\n  disableRefresh?: boolean;\n  /**\n   * Optional base path for URL handling.\n   * When set, this will be prepended to relative URLs in handleCallback responses.\n   * Commonly used with NextJS basePath configuration.\n   */\n  basePath?: string;\n  /**\n   * Controls how deep links (original URLs) are handled after authentication.\n   * @see DeepLinkHandling\n   * @default \"fullUrl\"\n   */\n  deepLinkHandling?: DeepLinkHandling;\n} & (\n  | {\n      /** OAuth client ID - required for standard OAuth flow */\n      clientId: string;\n      /** Custom login URL for backend integration - optional */\n      loginUrl?: string;\n    }\n  | {\n      /** OAuth client ID - optional when using backend integration */\n      clientId?: string;\n      /** Custom login URL for backend integration - required when clientId is not provided */\n      loginUrl: string;\n    }\n);\n"]}

package/dist/server/session.d.ts

@@ -91,6 +91,63 @@ export declare class CivicAuth {
      * Clear all authentication tokens from storage
      */
     clearTokens(): Promise<void>;
+    /**
+     * Handles deep linking by computing the return URL and setting it as a cookie.
+     * This method encapsulates the deep-linking logic for use by middleware in any framework.
+     *
+     * The method automatically detects whether the user is at the login URL or a protected route
+     * and applies the appropriate logic:
+     *
+     * **At login URL:**
+     * - Auth redirect (marker present): Preserve existing deep link cookie
+     * - Fresh navigation with query params: Set cookie with query params
+     * - Fresh navigation without params: Clear stale cookie
+     *
+     * **At protected route:**
+     * - Always set the cookie to capture the deep link destination
+     *
+     * @param requestUrl - The full URL of the request being made (the page the user tried to access)
+     * @param originUrl - The origin URL of the application (e.g., "https://myapp.com")
+     * @returns The computed deep link destination, or null if deep linking is disabled or the URL is invalid
+     *
+     * @example
+     * ```typescript
+     * // In middleware for any framework
+     * if (!session.authenticated) {
+     *   await civicAuth.handleDeepLinking(requestUrl, originUrl);
+     * }
+     * ```
+     */
+    handleDeepLinking(requestUrl: string, originUrl: string): Promise<string | null>;
+    /**
+     * Internal: Handles deep linking when at a protected route.
+     * Sets the cookie to capture the user's intended destination and the auth redirect marker.
+     */
+    private handleDeepLinkingAtProtectedRoute;
+    /**
+     * Internal: Handles deep linking when at the login URL.
+     * Checks the auth redirect marker and handles appropriately.
+     */
+    private handleDeepLinkingAtLoginUrl;
+    /**
+     * Sets the auth redirect marker cookie. This marker helps distinguish auth redirects
+     * from fresh navigations to the login page, preventing the deep link cookie from being
+     * incorrectly overwritten.
+     *
+     * **Note:** This method is automatically called by `handleDeepLinking` when the user is
+     * at a protected route. You typically do NOT need to call this method manually unless
+     * you have a specific use case where you're not using `handleDeepLinking`.
+     *
+     * @example
+     * ```typescript
+     * // In most cases, just call handleDeepLinking - it sets the marker automatically:
+     * if (!isAuthenticated) {
+     *   await req.civicAuth.handleDeepLinking(requestUrl, originUrl);
+     *   return res.redirect('/login');
+     * }
+     * ```
+     */
+    setAuthRedirectMarker(): Promise<void>;
     /**
      * Framework-agnostic URL detection and resolution helpers
      * These methods handle proxy environments and can be used by any framework

package/dist/server/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/server/session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/server/session.ts"],"names":[],"mappings":"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"}

package/dist/server/session.js

@@ -9,10 +9,10 @@ import { refreshTokens } from "../server/refresh.js";
 import { getVersion } from "../shared/index.js";
 import { ServerAuthenticationResolver } from "../server/ServerAuthenticationResolver.js";
 import { DEFAULT_AUTH_SERVER, JWT_PAYLOAD_KNOWN_CLAIM_KEYS, } from "../constants.js";
-import { displayModeFromState, loginSuccessUrlFromState } from "../lib/oauth.js";
+import { displayModeFromState, injectLoginSuccessUrlIntoState, loginSuccessUrlFromState, } from "../lib/oauth.js";
 import { decodeJwt } from "jose";
-import { generateOauthLogoutUrl, getBackendEndpoints, resolveEndpointUrl, sanitizeReturnUrl, } from "../shared/lib/util.js";
-import { CodeVerifier } from "../shared/lib/types.js";
+import { computeDeepLinkDestination, generateOauthLogoutUrl, getBackendEndpoints, prependBasePath, resolveEndpointUrl, sanitizeReturnUrl, } from "../shared/lib/util.js";
+import { AUTH_REDIRECT_MARKER_MAX_AGE, AuthFlowCookie, CodeVerifier, } from "../shared/lib/types.js";
 import { loggers } from "../lib/logger.js";
 // Function to omit keys from an object
 const omitKeys = (keys, obj) => {
@@ -141,10 +141,29 @@ export class CivicAuth {
      * @returns The login URL
      */
     async buildLoginUrl(options) {
+        const logger = loggers.server;
+        let finalState = options?.state;
+        // If deep linking is enabled, read the return URL cookie and inject into state
+        if (this.authConfig.deepLinkHandling !== "disabled") {
+            try {
+                const returnUrl = await this.storage.get(AuthFlowCookie.RETURN_URL);
+                if (returnUrl) {
+                    logger.debug("[buildLoginUrl] Found RETURN_URL cookie, injecting into state", { returnUrl });
+                    // Inject the return URL into state, preserving any existing state
+                    finalState = injectLoginSuccessUrlIntoState(finalState ?? null, returnUrl);
+                }
+            }
+            catch (error) {
+                logger.warn("[buildLoginUrl] Failed to read RETURN_URL cookie", {
+                    error,
+                });
+                // Continue without the cookie - don't block login
+            }
+        }
         return buildLoginUrl({
             ...this.authConfig,
             scopes: options?.scopes,
-            state: options?.state,
+            state: finalState,
             nonce: options?.nonce,
             framework: "server",
             sdkVersion: getVersion(),
@@ -220,6 +239,162 @@ export class CivicAuth {
     async clearTokens() {
         return clearTokensUtil(this.storage);
     }
+    /**
+     * Handles deep linking by computing the return URL and setting it as a cookie.
+     * This method encapsulates the deep-linking logic for use by middleware in any framework.
+     *
+     * The method automatically detects whether the user is at the login URL or a protected route
+     * and applies the appropriate logic:
+     *
+     * **At login URL:**
+     * - Auth redirect (marker present): Preserve existing deep link cookie
+     * - Fresh navigation with query params: Set cookie with query params
+     * - Fresh navigation without params: Clear stale cookie
+     *
+     * **At protected route:**
+     * - Always set the cookie to capture the deep link destination
+     *
+     * @param requestUrl - The full URL of the request being made (the page the user tried to access)
+     * @param originUrl - The origin URL of the application (e.g., "https://myapp.com")
+     * @returns The computed deep link destination, or null if deep linking is disabled or the URL is invalid
+     *
+     * @example
+     * ```typescript
+     * // In middleware for any framework
+     * if (!session.authenticated) {
+     *   await civicAuth.handleDeepLinking(requestUrl, originUrl);
+     * }
+     * ```
+     */
+    async handleDeepLinking(requestUrl, originUrl) {
+        const logger = loggers.server;
+        const deepLinkHandling = this.authConfig.deepLinkHandling ?? "queryParamsOnly";
+        if (deepLinkHandling === "disabled") {
+            return null;
+        }
+        // Parse the request URL to extract path, search, and hash
+        let parsedUrl;
+        try {
+            parsedUrl = new URL(requestUrl, originUrl);
+        }
+        catch (error) {
+            logger.warn("[handleDeepLinking] Failed to parse request URL:", {
+                requestUrl,
+                originUrl,
+                error,
+            });
+            return null;
+        }
+        // Determine if we're at the login URL
+        const loginUrl = this.authConfig.loginUrl || "/";
+        const loginPathWithoutBasePath = loginUrl.startsWith("/")
+            ? loginUrl
+            : new URL(loginUrl, originUrl).pathname;
+        const isAtLoginUrl = parsedUrl.pathname === loginPathWithoutBasePath;
+        logger.debug("[handleDeepLinking]:", {
+            pathname: parsedUrl.pathname,
+            isAtLoginUrl,
+            loginUrl: loginPathWithoutBasePath,
+        });
+        if (isAtLoginUrl) {
+            // At login URL - use the updateDeepLinkCookie logic
+            return this.handleDeepLinkingAtLoginUrl(parsedUrl, originUrl);
+        }
+        // At protected route - set the deep link cookie
+        return this.handleDeepLinkingAtProtectedRoute(parsedUrl, originUrl);
+    }
+    /**
+     * Internal: Handles deep linking when at a protected route.
+     * Sets the cookie to capture the user's intended destination and the auth redirect marker.
+     */
+    async handleDeepLinkingAtProtectedRoute(parsedUrl, originUrl) {
+        const logger = loggers.server;
+        const deepLinkHandling = this.authConfig.deepLinkHandling ?? "queryParamsOnly";
+        const returnTo = computeDeepLinkDestination(parsedUrl.pathname, parsedUrl.search, parsedUrl.hash, originUrl, deepLinkHandling, this.authConfig.loginSuccessUrl);
+        if (!returnTo) {
+            logger.debug("[handleDeepLinking] No deep link destination computed (disabled or invalid URL)");
+            return null;
+        }
+        // Set the cookie with the computed return URL
+        await this.storage.set(AuthFlowCookie.RETURN_URL, returnTo, {});
+        logger.debug("[handleDeepLinking] Set RETURN_URL cookie", { returnTo });
+        // Also set the auth redirect marker since we're at a protected route
+        // and the user will be redirected to login
+        await this.storage.set(AuthFlowCookie.AUTH_REDIRECT_MARKER, "1", {
+            maxAge: AUTH_REDIRECT_MARKER_MAX_AGE,
+        });
+        logger.debug("[handleDeepLinking] Set auth redirect marker");
+        return returnTo;
+    }
+    /**
+     * Internal: Handles deep linking when at the login URL.
+     * Checks the auth redirect marker and handles appropriately.
+     */
+    async handleDeepLinkingAtLoginUrl(parsedUrl, originUrl) {
+        const logger = loggers.server;
+        const deepLinkHandling = this.authConfig.deepLinkHandling ?? "queryParamsOnly";
+        const hasQueryParams = parsedUrl.searchParams.size > 0;
+        // Check and clean up the auth redirect marker cookie
+        const isAuthRedirect = await this.storage.get(AuthFlowCookie.AUTH_REDIRECT_MARKER);
+        await this.storage.delete(AuthFlowCookie.AUTH_REDIRECT_MARKER);
+        // Get existing cookie to determine if we need to clear stale data
+        const existingCookie = await this.storage.get(AuthFlowCookie.RETURN_URL);
+        logger.debug("[handleDeepLinking] At login URL:", {
+            hasQueryParams,
+            isAuthRedirect: !!isAuthRedirect,
+            existingCookie,
+        });
+        if (isAuthRedirect) {
+            // This is a redirect from auth middleware - don't overwrite the cookie
+            logger.debug("[handleDeepLinking] Auth redirect detected - preserving existing cookie");
+            return existingCookie;
+        }
+        // Fresh navigation
+        if (hasQueryParams) {
+            // User visited with query params - capture them
+            const returnTo = computeDeepLinkDestination(parsedUrl.pathname, parsedUrl.search, parsedUrl.hash, originUrl, deepLinkHandling, this.authConfig.loginSuccessUrl);
+            if (returnTo) {
+                logger.debug(`[handleDeepLinking] Fresh visit with params - setting cookie to "${returnTo}"`);
+                await this.storage.set(AuthFlowCookie.RETURN_URL, returnTo, {});
+                return returnTo;
+            }
+        }
+        // Fresh navigation without params - clear any stale cookie
+        if (existingCookie) {
+            logger.debug("[handleDeepLinking] Fresh visit without params - clearing stale cookie");
+            await this.storage.delete(AuthFlowCookie.RETURN_URL);
+        }
+        return null;
+    }
+    /**
+     * Sets the auth redirect marker cookie. This marker helps distinguish auth redirects
+     * from fresh navigations to the login page, preventing the deep link cookie from being
+     * incorrectly overwritten.
+     *
+     * **Note:** This method is automatically called by `handleDeepLinking` when the user is
+     * at a protected route. You typically do NOT need to call this method manually unless
+     * you have a specific use case where you're not using `handleDeepLinking`.
+     *
+     * @example
+     * ```typescript
+     * // In most cases, just call handleDeepLinking - it sets the marker automatically:
+     * if (!isAuthenticated) {
+     *   await req.civicAuth.handleDeepLinking(requestUrl, originUrl);
+     *   return res.redirect('/login');
+     * }
+     * ```
+     */
+    async setAuthRedirectMarker() {
+        const logger = loggers.server;
+        const deepLinkHandling = this.authConfig.deepLinkHandling ?? "queryParamsOnly";
+        if (deepLinkHandling === "disabled") {
+            return;
+        }
+        await this.storage.set(AuthFlowCookie.AUTH_REDIRECT_MARKER, "1", {
+            maxAge: AUTH_REDIRECT_MARKER_MAX_AGE,
+        });
+        logger.debug("[setAuthRedirectMarker] Set auth redirect marker cookie");
+    }
     /**
      * Framework-agnostic URL detection and resolution helpers
      * These methods handle proxy environments and can be used by any framework
@@ -373,7 +548,11 @@ export class CivicAuth {
                 newSearchParams.delete("loginSuccessUrl");
                 // Use preserved deep link if available and valid, otherwise fall back to loginSuccessUrl or "/"
                 // Note: Do NOT fall back to currentUrl.pathname as that's the callback URL, which would cause a loop
-                const redirectUrl = loginSuccessUrl || this.authConfig.loginSuccessUrl || "/";
+                let redirectUrl = loginSuccessUrl || this.authConfig.loginSuccessUrl || "/";
+                // Apply basePath if configured
+                if (this.authConfig.basePath) {
+                    redirectUrl = prependBasePath(redirectUrl, this.authConfig.basePath);
+                }
                 return {
                     content: {
                         success: true,
@@ -405,9 +584,13 @@ export class CivicAuth {
                         // "User already authenticated, skipping iframe workaround",
                         const user = await this.getUser();
                         const loginSuccessUrlFromStateValue = loginSuccessUrlFromState(state);
-                        const frontendUrl = options?.frontendUrl ||
+                        let frontendUrl = options?.frontendUrl ||
                             loginSuccessUrlFromStateValue ||
                             this.authConfig.loginSuccessUrl;
+                        // Apply basePath to frontendUrl if configured
+                        if (frontendUrl && this.authConfig.basePath) {
+                            frontendUrl = prependBasePath(frontendUrl, this.authConfig.basePath);
+                        }
                         // Check if this is an iframe context - if so, generate iframe completion HTML
                         const stateDisplayMode = displayModeFromState(state, undefined);
                         const isConfiguredForIframe = stateDisplayMode === "iframe";
@@ -440,9 +623,13 @@ export class CivicAuth {
                 if (isConfiguredForIframe && !this.authConfig.disableIframeDetection) {
                     // Generate HTML that will trigger same-domain callback
                     const loginSuccessUrlFromStateValue = loginSuccessUrlFromState(state);
-                    const frontendUrl = options?.frontendUrl ||
+                    let frontendUrl = options?.frontendUrl ||
                         loginSuccessUrlFromStateValue ||
                         this.authConfig.loginSuccessUrl;
+                    // Apply basePath to frontendUrl if configured
+                    if (frontendUrl && this.authConfig.basePath) {
+                        frontendUrl = prependBasePath(frontendUrl, this.authConfig.basePath);
+                    }
                     const callbackUrl = req.url || "";
                     const sameDomainHtml = this.generateSameDomainCallbackHtml(callbackUrl, frontendUrl);
                     return { content: sameDomainHtml };
@@ -458,9 +645,13 @@ export class CivicAuth {
         // Extract loginSuccessUrl from state if present
         const loginSuccessUrlFromStateValue = loginSuccessUrlFromState(state);
         // Priority: options.frontendUrl > loginSuccessUrl from state > config loginSuccessUrl
-        const frontendUrl = options?.frontendUrl ||
+        let frontendUrl = options?.frontendUrl ||
             loginSuccessUrlFromStateValue ||
             this.authConfig.loginSuccessUrl;
+        // Apply basePath to frontendUrl if configured
+        if (frontendUrl && this.authConfig.basePath) {
+            frontendUrl = prependBasePath(frontendUrl, this.authConfig.basePath);
+        }
         // Priority 1: Check state for display mode configuration
         const stateDisplayMode = displayModeFromState(state, undefined);
         const isConfiguredForIframe = stateDisplayMode === "iframe";
@@ -525,7 +716,12 @@ export class CivicAuth {
         }
         // Absolute fallback: redirect to loginSuccessUrl or "/"
         // Never return JSON for browser navigation - that would display raw JSON to the user
-        return { redirectTo: this.authConfig.loginSuccessUrl || "/" };
+        const fallbackUrl = this.authConfig.loginSuccessUrl || "/";
+        return {
+            redirectTo: this.authConfig.basePath
+                ? prependBasePath(fallbackUrl, this.authConfig.basePath)
+                : fallbackUrl,
+        };
     }
     /**
      * Generate HTML content for iframe completion that sends postMessage to parent