@nauth-toolkit/client-angular 0.1.91 → 0.1.93

package/fesm2022/nauth-toolkit-client-angular.mjs

@@ -1,7 +1,7 @@
 import { NAuthErrorCode, NAuthClientError, NAuthClient } from '@nauth-toolkit/client';
 export * from '@nauth-toolkit/client';
 import * as i0 from '@angular/core';
-import { InjectionToken, Injectable, Inject, Optional, inject, NgModule, PLATFORM_ID } from '@angular/core';
+import { InjectionToken, Injectable, PLATFORM_ID, Inject, Optional, inject, APP_INITIALIZER, NgModule, makeEnvironmentProviders } from '@angular/core';
 import { firstValueFrom, BehaviorSubject, Subject, from, switchMap, of, map, catchError, throwError, finalize, shareReplay } from 'rxjs';
 import { filter } from 'rxjs/operators';
 import * as i1 from '@angular/common/http';
@@ -136,6 +136,374 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
             type: Injectable
         }], ctorParameters: () => [{ type: i1.HttpClient }] });
 
+/**
+ * Injection token for reCAPTCHA configuration
+ */
+const RECAPTCHA_CONFIG = new InjectionToken('RECAPTCHA_CONFIG', {
+    providedIn: 'root',
+    factory: () => undefined,
+});
+/**
+ * Google reCAPTCHA service for Angular applications.
+ *
+ * Provides lazy loading of reCAPTCHA script and platform-aware token generation.
+ * Automatically detects platform (web, Capacitor WebView, Capacitor native, SSR)
+ * and skips reCAPTCHA in environments where it's not supported or needed.
+ *
+ * Features:
+ * - Lazy script loading (only loads when needed)
+ * - v2 (checkbox) and v3 (invisible) support
+ * - Platform detection (web, Capacitor, SSR)
+ * - Automatic skip for Capacitor native mode
+ * - Automatic skip for SSR
+ *
+ * @example v3 Automatic Mode
+ * ```typescript
+ * constructor(private recaptcha: RecaptchaService) {}
+ *
+ * async login() {
+ *   const token = await this.recaptcha.execute('login');
+ *   await this.auth.login(email, password, token);
+ * }
+ * ```
+ *
+ * @example v2 Manual Mode
+ * ```typescript
+ * ngOnInit() {
+ *   this.recaptcha.render('recaptcha-container', (token) => {
+ *     this.recaptchaToken = token;
+ *   });
+ * }
+ * ```
+ */
+class RecaptchaService {
+    platformId;
+    config;
+    scriptLoaded = false;
+    scriptLoading = null;
+    platform;
+    widgetId = null;
+    constructor(platformId, config) {
+        this.platformId = platformId;
+        this.config = config;
+        this.platform = this.detectPlatform();
+        // Auto-preload script for v3/Enterprise so it's ready before first login/signup
+        // No-op when disabled, shouldSkip, or v2 (v2 renders on-demand)
+        if (this.config?.enabled && (this.config.version === 'v3' || this.config.version === 'enterprise')) {
+            if (!this.shouldSkip()) {
+                this.loadScript().catch(() => {
+                    // Silently fail - execute() will handle errors when called
+                });
+            }
+        }
+    }
+    // ============================================================================
+    // Platform Detection
+    // ============================================================================
+    /**
+     * Detect the current platform environment.
+     *
+     * Detection priority:
+     * 1. SSR (not in browser) → 'ssr'
+     * 2. Capacitor native (no web view) → 'capacitor-native'
+     * 3. Capacitor WebView → 'capacitor-webview'
+     * 4. Web browser → 'web'
+     *
+     * @returns Detected platform type
+     *
+     * @example
+     * ```typescript
+     * const platform = this.detectPlatform();
+     * if (platform === 'capacitor-native') {
+     *   // Skip reCAPTCHA, use device attestation
+     * }
+     * ```
+     */
+    detectPlatform() {
+        // SSR detection
+        if (!isPlatformBrowser(this.platformId)) {
+            return 'ssr';
+        }
+        // Capacitor detection (window.Capacitor exists)
+        const windowRef = window;
+        if (windowRef.Capacitor) {
+            // Capacitor native (iOS/Android app)
+            if (typeof windowRef.Capacitor.isNativePlatform === 'function' && windowRef.Capacitor.isNativePlatform()) {
+                return 'capacitor-native';
+            }
+            // Capacitor WebView
+            return 'capacitor-webview';
+        }
+        return 'web';
+    }
+    /**
+     * Get the current platform.
+     *
+     * @returns Current platform type
+     */
+    getPlatform() {
+        return this.platform;
+    }
+    /**
+     * Check if reCAPTCHA should be skipped for current platform.
+     *
+     * Skips for:
+     * - SSR (no window object)
+     * - Capacitor native (use device attestation instead)
+     *
+     * @returns True if should skip reCAPTCHA
+     */
+    shouldSkip() {
+        return this.platform === 'ssr' || this.platform === 'capacitor-native';
+    }
+    // ============================================================================
+    // Script Loading
+    // ============================================================================
+    /**
+     * Load Google reCAPTCHA script if not already loaded.
+     *
+     * Script URL format:
+     * - v2: https://www.google.com/recaptcha/api.js
+     * - v3: https://www.google.com/recaptcha/api.js?render={siteKey}
+     * - Enterprise: https://www.google.com/recaptcha/enterprise.js?render={siteKey}
+     *
+     * @returns Promise that resolves when script is loaded
+     *
+     * @throws Error if config is missing or script fails to load
+     */
+    async loadScript() {
+        // Skip in SSR or Capacitor native
+        if (this.shouldSkip()) {
+            return;
+        }
+        // Skip if disabled
+        if (!this.config?.enabled) {
+            return;
+        }
+        // Already loaded
+        if (this.scriptLoaded) {
+            return;
+        }
+        // Already loading (return existing promise)
+        if (this.scriptLoading) {
+            return this.scriptLoading;
+        }
+        // Validate config
+        if (!this.config.siteKey) {
+            throw new Error('[RecaptchaService] Site key is required');
+        }
+        // Start loading
+        this.scriptLoading = this.injectScript();
+        try {
+            await this.scriptLoading;
+            this.scriptLoaded = true;
+        }
+        finally {
+            this.scriptLoading = null;
+        }
+    }
+    /**
+     * Inject the reCAPTCHA script into the DOM.
+     *
+     * @returns Promise that resolves when script loads
+     */
+    injectScript() {
+        return new Promise((resolve, reject) => {
+            const script = document.createElement('script');
+            script.async = true;
+            script.defer = true;
+            // Set script URL based on version
+            if (this.config.version === 'enterprise') {
+                script.src = `https://www.google.com/recaptcha/enterprise.js?render=${this.config.siteKey}`;
+            }
+            else if (this.config.version === 'v3') {
+                script.src = `https://www.google.com/recaptcha/api.js?render=${this.config.siteKey}`;
+            }
+            else {
+                // v2 - load without render parameter
+                let url = 'https://www.google.com/recaptcha/api.js';
+                if (this.config.language) {
+                    url += `?hl=${this.config.language}`;
+                }
+                script.src = url;
+            }
+            script.onload = () => resolve();
+            script.onerror = () => reject(new Error('[RecaptchaService] Failed to load reCAPTCHA script'));
+            document.head.appendChild(script);
+        });
+    }
+    // ============================================================================
+    // v3/Enterprise Methods (Invisible Challenge)
+    // ============================================================================
+    /**
+     * Execute reCAPTCHA v3/Enterprise challenge (invisible).
+     *
+     * Automatically loads script if needed and generates a token.
+     * Skips automatically for SSR and Capacitor native.
+     *
+     * @param action - Action name for v3 analytics (e.g., 'login', 'signup')
+     * @returns Promise resolving to reCAPTCHA token, or undefined if skipped
+     *
+     * @throws Error if version is v2, config missing, or execution fails
+     *
+     * @example
+     * ```typescript
+     * const token = await this.recaptcha.execute('login');
+     * if (token) {
+     *   await this.auth.login(email, password, token);
+     * }
+     * ```
+     */
+    async execute(action) {
+        // Skip for platforms that don't support reCAPTCHA
+        if (this.shouldSkip()) {
+            return undefined;
+        }
+        // Skip if disabled
+        if (!this.config?.enabled) {
+            return undefined;
+        }
+        // v2 requires manual render
+        if (this.config.version === 'v2') {
+            throw new Error('[RecaptchaService] execute() is only for v3/Enterprise. Use render() for v2.');
+        }
+        // Load script if needed
+        await this.loadScript();
+        // Get grecaptcha object
+        const grecaptcha = window.grecaptcha;
+        if (!grecaptcha) {
+            throw new Error('[RecaptchaService] grecaptcha is not loaded');
+        }
+        // Execute reCAPTCHA
+        const actionName = action || this.config.action || 'submit';
+        try {
+            if (this.config.version === 'enterprise' && grecaptcha.enterprise?.execute) {
+                return await grecaptcha.enterprise.execute(this.config.siteKey, { action: actionName });
+            }
+            else if (grecaptcha.execute) {
+                return await grecaptcha.execute(this.config.siteKey, { action: actionName });
+            }
+            else {
+                throw new Error('[RecaptchaService] grecaptcha.execute is not available');
+            }
+        }
+        catch (error) {
+            throw new Error(`[RecaptchaService] Failed to execute reCAPTCHA: ${error instanceof Error ? error.message : 'unknown error'}`);
+        }
+    }
+    // ============================================================================
+    // v2 Methods (Visible Checkbox)
+    // ============================================================================
+    /**
+     * Render reCAPTCHA v2 checkbox widget.
+     *
+     * @param containerId - DOM element ID or element to render in
+     * @param callback - Callback when user completes challenge
+     * @returns Promise resolving to widget ID
+     *
+     * @throws Error if version is not v2, config missing, or render fails
+     *
+     * @example
+     * ```typescript
+     * ngAfterViewInit() {
+     *   this.recaptcha.render('recaptcha-container', (token) => {
+     *     this.recaptchaToken = token;
+     *     this.loginForm.patchValue({ recaptchaToken: token });
+     *   });
+     * }
+     * ```
+     */
+    async render(containerId, callback) {
+        // Skip for platforms that don't support reCAPTCHA
+        if (this.shouldSkip()) {
+            throw new Error('[RecaptchaService] reCAPTCHA v2 is not supported in SSR or Capacitor native');
+        }
+        // Skip if disabled
+        if (!this.config?.enabled) {
+            throw new Error('[RecaptchaService] reCAPTCHA is not enabled');
+        }
+        // Only for v2
+        if (this.config.version !== 'v2') {
+            throw new Error('[RecaptchaService] render() is only for v2. Use execute() for v3/Enterprise.');
+        }
+        // Load script if needed
+        await this.loadScript();
+        // Get grecaptcha object
+        const grecaptcha = window.grecaptcha;
+        if (!grecaptcha?.render) {
+            throw new Error('[RecaptchaService] grecaptcha.render is not available');
+        }
+        // Render widget
+        try {
+            this.widgetId = grecaptcha.render(containerId, {
+                sitekey: this.config.siteKey,
+                callback: callback,
+            });
+            return this.widgetId;
+        }
+        catch (error) {
+            throw new Error(`[RecaptchaService] Failed to render reCAPTCHA: ${error instanceof Error ? error.message : 'unknown error'}`);
+        }
+    }
+    /**
+     * Get response token from v2 widget.
+     *
+     * @param widgetId - Widget ID (optional, uses last rendered widget if not provided)
+     * @returns reCAPTCHA token or null if not completed
+     *
+     * @example
+     * ```typescript
+     * const token = this.recaptcha.getResponse();
+     * if (token) {
+     *   await this.auth.login(email, password, token);
+     * }
+     * ```
+     */
+    getResponse(widgetId) {
+        const grecaptcha = window.grecaptcha;
+        if (!grecaptcha?.getResponse) {
+            return null;
+        }
+        const id = widgetId !== undefined ? widgetId : this.widgetId ?? undefined;
+        return grecaptcha.getResponse(id) || null;
+    }
+    /**
+     * Reset v2 widget (clear response).
+     *
+     * @param widgetId - Widget ID (optional, uses last rendered widget if not provided)
+     *
+     * @example
+     * ```typescript
+     * // After failed login
+     * this.recaptcha.reset();
+     * ```
+     */
+    reset(widgetId) {
+        const grecaptcha = window.grecaptcha;
+        if (!grecaptcha?.reset) {
+            return;
+        }
+        const id = widgetId !== undefined ? widgetId : this.widgetId ?? undefined;
+        grecaptcha.reset(id);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: RecaptchaService, deps: [{ token: PLATFORM_ID }, { token: RECAPTCHA_CONFIG, optional: true }], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: RecaptchaService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: RecaptchaService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }], ctorParameters: () => [{ type: undefined, decorators: [{
+                    type: Inject,
+                    args: [PLATFORM_ID]
+                }] }, { type: undefined, decorators: [{
+                    type: Optional
+                }, {
+                    type: Inject,
+                    args: [RECAPTCHA_CONFIG]
+                }] }] });
+
 /**
  * Angular wrapper around NAuthClient that provides promise-based auth methods and reactive state.
  *
@@ -170,6 +538,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
  */
 class AuthService {
     router;
+    recaptchaService;
     client;
     config;
     currentUserSubject = new BehaviorSubject(null);
@@ -181,9 +550,11 @@ class AuthService {
      * @param config - Injected client configuration (required)
      * @param httpAdapter - Angular HTTP adapter for making requests (required)
      * @param router - Angular Router (optional, automatically used for navigation if available)
+     * @param recaptchaService - RecaptchaService (optional, for automatic token generation)
      */
-    constructor(config, httpAdapter, router) {
+    constructor(config, httpAdapter, router, recaptchaService) {
         this.router = router;
+        this.recaptchaService = recaptchaService;
         this.config = config;
         // Use provided httpAdapter (from config or injected)
         const adapter = config.httpAdapter ?? httpAdapter;
@@ -334,31 +705,39 @@ class AuthService {
     /**
      * Login with identifier and password.
      *
+     * Automatically generates reCAPTCHA token if configured (v3 only).
+     * For v2 manual mode, pass the token explicitly.
+     *
      * @param identifier - User email or username
      * @param password - User password
+     * @param recaptchaToken - Optional reCAPTCHA token (for v2 manual mode or when auto-generation is disabled)
      * @returns Promise with auth response or challenge
      *
-     * @example
+     * @example Basic Login
      * ```typescript
      * const response = await this.auth.login('user@example.com', 'password');
-     * if (response.challengeName) {
-     *   // Handle challenge
-     * } else {
-     *   // Login successful
-     * }
+     * ```
+     *
+     * @example With Manual reCAPTCHA (v2)
+     * ```typescript
+     * const response = await this.auth.login('user@example.com', 'password', recaptchaToken);
      * ```
      */
-    async login(identifier, password) {
-        const res = await this.client.login(identifier, password);
+    async login(identifier, password, recaptchaToken) {
+        const token = await this.getRecaptchaToken(recaptchaToken, 'login');
+        const res = await this.client.login(identifier, password, token);
         return this.updateChallengeState(res);
     }
     /**
      * Signup with credentials.
      *
+     * Automatically generates reCAPTCHA token if configured (v3 only).
+     * For v2 manual mode, include token in payload.
+     *
      * @param payload - Signup request payload
      * @returns Promise with auth response or challenge
      *
-     * @example
+     * @example Basic Signup
      * ```typescript
      * const response = await this.auth.signup({
      *   email: 'new@example.com',
@@ -366,8 +745,25 @@ class AuthService {
      *   firstName: 'John',
      * });
      * ```
+     *
+     * @example With Manual reCAPTCHA (v2)
+     * ```typescript
+     * const response = await this.auth.signup({
+     *   email: 'new@example.com',
+     *   password: 'SecurePass123!',
+     *   recaptchaToken: token,
+     * });
+     * ```
      */
     async signup(payload) {
+        // Auto-generate reCAPTCHA token for v3 if configured and not already provided
+        const payloadWithRecaptcha = payload;
+        if (!payloadWithRecaptcha.recaptchaToken) {
+            const token = await this.getRecaptchaToken(undefined, 'signup');
+            if (token) {
+                payload = { ...payload, recaptchaToken: token };
+            }
+        }
         const res = await this.client.signup(payload);
         return this.updateChallengeState(res);
     }
@@ -1029,7 +1425,58 @@ class AuthService {
         }
         return response;
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: AuthService, deps: [{ token: NAUTH_CLIENT_CONFIG }, { token: AngularHttpAdapter }, { token: i2.Router, optional: true }], target: i0.ɵɵFactoryTarget.Injectable });
+    // ============================================================================
+    // reCAPTCHA Helper
+    // ============================================================================
+    /**
+     * Get reCAPTCHA token - auto-generate for v3 or use provided token.
+     *
+     * Handles platform detection:
+     * - Web browser: Generate token if enabled and v3
+     * - Capacitor native: Skip (use device attestation instead)
+     * - SSR: Skip
+     * - Manual mode (v2 or manualChallenge=true): Requires explicit token
+     *
+     * @param providedToken - Explicitly provided token (v2 manual mode)
+     * @param action - Action name for v3 analytics
+     * @returns reCAPTCHA token or undefined
+     *
+     * @private
+     */
+    async getRecaptchaToken(providedToken, action) {
+        // If token explicitly provided, use it (v2 manual mode)
+        if (providedToken) {
+            return providedToken;
+        }
+        // No reCAPTCHA service available
+        if (!this.recaptchaService) {
+            return undefined;
+        }
+        // Check if reCAPTCHA is configured
+        const recaptchaConfig = this.config.recaptcha;
+        if (!recaptchaConfig?.enabled) {
+            return undefined;
+        }
+        // Skip for platforms that don't support reCAPTCHA (SSR, Capacitor native)
+        if (this.recaptchaService.shouldSkip()) {
+            return undefined;
+        }
+        // v2 or manual mode - user must provide token explicitly
+        if (recaptchaConfig.version === 'v2' || recaptchaConfig.manualChallenge) {
+            return undefined;
+        }
+        // Auto-generate token for v3/Enterprise
+        try {
+            return await this.recaptchaService.execute(action);
+        }
+        catch (error) {
+            // Log error but don't block authentication
+            // Server will enforce if required
+            console.warn('[AuthService] Failed to generate reCAPTCHA token:', error);
+            return undefined;
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: AuthService, deps: [{ token: NAUTH_CLIENT_CONFIG }, { token: AngularHttpAdapter }, { token: i2.Router, optional: true }, { token: RecaptchaService, optional: true }], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: AuthService });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: AuthService, decorators: [{
@@ -1039,6 +1486,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
                     args: [NAUTH_CLIENT_CONFIG]
                 }] }, { type: AngularHttpAdapter }, { type: i2.Router, decorators: [{
                     type: Optional
+                }] }, { type: RecaptchaService, decorators: [{
+                    type: Optional
                 }] }] });
 
 /**
@@ -1458,7 +1907,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
  *
  * Use this for NgModule-based apps (Angular 17+ with NgModule or legacy apps).
  *
- * @example
+ * @example Basic Setup
  * ```typescript
  * // app.module.ts
  * import { NAuthModule } from '@nauth-toolkit/client-angular';
@@ -1473,35 +1922,67 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
  * })
  * export class AppModule {}
  * ```
+ *
+ * @example With reCAPTCHA Enterprise
+ * ```typescript
+ * NAuthModule.forRoot({
+ *   baseUrl: 'http://localhost:3000/auth',
+ *   tokenDelivery: 'cookies',
+ *   recaptcha: {
+ *     enabled: true,
+ *     version: 'enterprise',
+ *     siteKey: environment.recaptchaSiteKey,
+ *     action: 'login',
+ *   },
+ * })
+ * ```
  */
 class NAuthModule {
     static forRoot(config) {
-        return {
-            ngModule: NAuthModule,
-            providers: [
-                {
-                    provide: NAUTH_CLIENT_CONFIG,
-                    useValue: config,
-                },
-                AngularHttpAdapter,
-                {
-                    provide: AuthService,
-                    useFactory: (httpAdapter) => {
-                        // Try to inject Router optionally - if not available, pass undefined
-                        // Router will be undefined if not provided (e.g., in apps without routing)
-                        const router = inject(Router, { optional: true });
-                        return new AuthService(config, httpAdapter, router ?? undefined);
-                    },
-                    deps: [AngularHttpAdapter],
+        const providers = [
+            {
+                provide: NAUTH_CLIENT_CONFIG,
+                useValue: config,
+            },
+            AngularHttpAdapter,
+            {
+                provide: AuthService,
+                useFactory: (httpAdapter, recaptchaService) => {
+                    // Try to inject Router optionally - if not available, pass undefined
+                    // Router will be undefined if not provided (e.g., in apps without routing)
+                    const router = inject(Router, { optional: true });
+                    return new AuthService(config, httpAdapter, router ?? undefined, recaptchaService);
                 },
-                {
-                    provide: HTTP_INTERCEPTORS,
-                    useClass: AuthInterceptorClass,
-                    multi: true,
+                deps: [AngularHttpAdapter, [new Optional(), RecaptchaService]],
+            },
+            {
+                provide: HTTP_INTERCEPTORS,
+                useClass: AuthInterceptorClass,
+                multi: true,
+            },
+            // Provide AuthGuard so it has access to NAUTH_CLIENT_CONFIG
+            AuthGuard,
+        ];
+        // Add reCAPTCHA providers if configured
+        if (config.recaptcha?.enabled) {
+            providers.push({
+                provide: RECAPTCHA_CONFIG,
+                // Cast because interface extends but they're compatible
+                useValue: config.recaptcha,
+            }, RecaptchaService, {
+                provide: APP_INITIALIZER,
+                useFactory: () => {
+                    // Force RecaptchaService instantiation at app startup so script preloads
+                    inject(RecaptchaService);
+                    // No-op - constructor already handles preload
+                    return () => { };
                 },
-                // Provide AuthGuard so it has access to NAUTH_CLIENT_CONFIG
-                AuthGuard,
-            ],
+                multi: true,
+            });
+        }
+        return {
+            ngModule: NAuthModule,
+            providers,
         };
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: NAuthModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
@@ -1557,6 +2038,7 @@ class AuthInterceptor {
  * - If `exchangeToken` exists: exchanges it via backend (SDK handles navigation automatically).
  * - If no `exchangeToken`: treat as cookie-success path (SDK handles navigation automatically).
  * - If `error` exists: redirects to oauthError route.
+ * - If auto-redirect is disabled (redirectUrls set to null): returns true to activate the route.
  *
  * @example
  * ```typescript
@@ -1587,14 +2069,16 @@ const socialRedirectCallbackGuard = async () => {
     if (appState) {
         await auth.getClient().storeOauthState(appState);
     }
-    // Provider error: redirect to oauthError
+    // Provider error: redirect to oauthError (or activate route if auto-redirect disabled)
     if (error) {
         await router.navigateToError('oauth');
-        return false;
+        // Return true to activate route if oauthError redirect is disabled
+        return router.isErrorRedirectDisabled('oauth');
     }
     // No exchangeToken: cookie success path; hydrate then navigate to success.
     //
-    // Note: we do not "activate" the callback route to avoid consumers needing to render a page.
+    // Note: When auto-redirect is enabled, we do not "activate" the callback route to avoid
+    // consumers needing to render a page. When disabled, we activate the route.
     if (!exchangeToken) {
         // ============================================================================
         // Cookies mode: hydrate user state before redirecting
@@ -1636,34 +2120,88 @@ const socialRedirectCallbackGuard = async () => {
                 appState: appState ?? undefined,
             });
         }
-        catch (err) {
+        catch (error) {
             // Only treat auth failures (401/403) as OAuth errors
             // Network errors or other issues might be temporary - still try success route
-            const isAuthError = err instanceof NAuthClientError &&
-                (err.statusCode === 401 ||
-                    err.statusCode === 403 ||
-                    err.code === NAuthErrorCode.AUTH_TOKEN_INVALID ||
-                    err.code === NAuthErrorCode.AUTH_SESSION_EXPIRED ||
-                    err.code === NAuthErrorCode.AUTH_SESSION_NOT_FOUND);
-            if (isAuthError) {
-                // Cookies weren't set properly - OAuth failed
-                await router.navigateToError('oauth');
-            }
-            else {
-                // For network errors or other issues, proceed to success route
-                // The auth guard will handle authentication state on the next route
-                await router.navigateToSuccess(appState ? { appState } : undefined);
+            // Type guard: check if error is NAuthClientError
+            if (error instanceof NAuthClientError) {
+                const isAuthError = error.statusCode === 401 ||
+                    error.statusCode === 403 ||
+                    error.code === NAuthErrorCode.AUTH_TOKEN_INVALID ||
+                    error.code === NAuthErrorCode.AUTH_SESSION_EXPIRED ||
+                    error.code === NAuthErrorCode.AUTH_SESSION_NOT_FOUND;
+                if (isAuthError) {
+                    // Cookies weren't set properly - OAuth failed
+                    await router.navigateToError('oauth');
+                    return router.isErrorRedirectDisabled('oauth');
+                }
             }
+            // For network errors or other non-auth issues, proceed to success route
+            // The auth guard will handle authentication state on the next route
+            await router.navigateToSuccess(appState ? { appState } : undefined);
         }
-        return false;
+        // Return true if success redirect is disabled, allowing the callback component to render
+        return router.isSuccessRedirectDisabled({ source: 'social', appState: appState ?? undefined });
     }
     // Exchange token - SDK handles navigation automatically
     // Note: appState will be passed via query params when navigateToSuccess is called
     // by the challenge router after successful exchange
     await auth.exchangeSocialRedirect(exchangeToken);
-    return false;
+    // Return true if success redirect is disabled, allowing the callback component to render
+    // We use 'social' as source since this is the social OAuth callback flow
+    return router.isSuccessRedirectDisabled({ source: 'social', appState: appState ?? undefined });
 };
 
+/**
+ * Provides reCAPTCHA configuration and automatic script preloading.
+ *
+ * Sets up `RECAPTCHA_CONFIG` and forces `RecaptchaService` instantiation at app
+ * startup so the reCAPTCHA script preloads before the user clicks login/signup.
+ *
+ * @param config - reCAPTCHA configuration (enabled, version, siteKey, action)
+ * @returns Environment providers for reCAPTCHA
+ *
+ * @example
+ * ```typescript
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideRecaptcha({
+ *       enabled: true,
+ *       version: 'enterprise',
+ *       siteKey: environment.recaptchaSiteKey,
+ *       action: 'login',
+ *     }),
+ *     // ... other providers
+ *   ],
+ * };
+ * ```
+ */
+function provideRecaptcha(config) {
+    return makeEnvironmentProviders([
+        {
+            provide: RECAPTCHA_CONFIG,
+            useValue: config,
+        },
+        RecaptchaService,
+        {
+            provide: APP_INITIALIZER,
+            useFactory: () => {
+                const recaptcha = inject(RecaptchaService);
+                // Return initialization function that ensures script starts loading
+                return () => {
+                    // Trigger script load (fire-and-forget, don't block app startup)
+                    if (config.enabled && (config.version === 'v3' || config.version === 'enterprise')) {
+                        recaptcha.loadScript().catch(() => {
+                            // Silent fail - execute() will retry when called
+                        });
+                    }
+                };
+            },
+            multi: true,
+        },
+    ]);
+}
+
 /**
  * Public API Surface of @nauth-toolkit/client-angular (NgModule)
  *
@@ -1676,5 +2214,5 @@ const socialRedirectCallbackGuard = async () => {
  * Generated bundle index. Do not edit.
  */
 
-export { AngularHttpAdapter, AuthGuard, AuthInterceptor, AuthInterceptorClass, AuthService, NAUTH_CLIENT_CONFIG, NAuthModule, authGuard, authInterceptor, socialRedirectCallbackGuard };
+export { AngularHttpAdapter, AuthGuard, AuthInterceptor, AuthInterceptorClass, AuthService, NAUTH_CLIENT_CONFIG, NAuthModule, RECAPTCHA_CONFIG, RecaptchaService, authGuard, authInterceptor, provideRecaptcha, socialRedirectCallbackGuard };
 //# sourceMappingURL=nauth-toolkit-client-angular.mjs.map