@nauth-toolkit/client-angular 0.1.56 → 0.1.58

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

@@ -0,0 +1,1390 @@
+import { NAuthErrorCode, NAuthClientError, NAuthClient } from '@nauth-toolkit/client';
+export * from '@nauth-toolkit/client';
+import * as i0 from '@angular/core';
+import { InjectionToken, Injectable, Inject, NgModule, inject, PLATFORM_ID } from '@angular/core';
+import { firstValueFrom, BehaviorSubject, Subject, catchError, from, switchMap, throwError, filter as filter$1, take } from 'rxjs';
+import { filter } from 'rxjs/operators';
+import * as i1 from '@angular/common/http';
+import { HttpErrorResponse, HTTP_INTERCEPTORS, HttpClientModule, HttpClient } from '@angular/common/http';
+import * as i3 from '@angular/router';
+import { Router } from '@angular/router';
+import { isPlatformBrowser } from '@angular/common';
+
+/**
+ * Injection token for providing NAuthClientConfig in Angular apps.
+ */
+const NAUTH_CLIENT_CONFIG = new InjectionToken('NAUTH_CLIENT_CONFIG');
+
+/**
+ * HTTP adapter for Angular using HttpClient.
+ *
+ * This adapter:
+ * - Uses Angular's HttpClient for all requests
+ * - Works with Angular's HTTP interceptors (including authInterceptor)
+ * - Auto-provided via Angular DI (providedIn: 'root')
+ * - Converts HttpClient responses to HttpResponse format
+ * - Converts HttpErrorResponse to NAuthClientError
+ *
+ * Users don't need to configure this manually - it's automatically
+ * injected when using AuthService in Angular apps.
+ *
+ * @example
+ * ```typescript
+ * // Automatic usage (no manual setup needed)
+ * // AuthService automatically injects AngularHttpAdapter
+ * constructor(private auth: AuthService) {}
+ * ```
+ */
+class AngularHttpAdapter {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Safely parse a JSON response body.
+     *
+     * Angular's fetch backend (`withFetch()`) will throw a raw `SyntaxError` if
+     * `responseType: 'json'` is used and the backend returns HTML (common for
+     * proxies, 502 pages, SSR fallbacks, or misrouted requests).
+     *
+     * To avoid crashing consumer apps, we always request as text and then parse
+     * JSON only when the response actually looks like JSON.
+     *
+     * @param bodyText - Raw response body as text
+     * @param contentType - Content-Type header value (if available)
+     * @returns Parsed JSON value (unknown)
+     * @throws {SyntaxError} When body is non-empty but not valid JSON
+     */
+    parseJsonBody(bodyText, contentType) {
+        const trimmed = bodyText.trim();
+        if (!trimmed)
+            return null;
+        // If it's clearly HTML, never attempt JSON.parse (some proxies mislabel Content-Type).
+        if (trimmed.startsWith('<')) {
+            return bodyText;
+        }
+        const looksLikeJson = trimmed.startsWith('{') || trimmed.startsWith('[');
+        const isJsonContentType = typeof contentType === 'string' && contentType.toLowerCase().includes('application/json');
+        if (!looksLikeJson && !isJsonContentType) {
+            // Return raw text when it doesn't look like JSON (e.g., HTML error pages).
+            return bodyText;
+        }
+        return JSON.parse(trimmed);
+    }
+    /**
+     * Execute HTTP request using Angular's HttpClient.
+     *
+     * @param config - Request configuration
+     * @returns Response with parsed data
+     * @throws NAuthClientError if request fails
+     */
+    async request(config) {
+        try {
+            // Use Angular's HttpClient - goes through ALL interceptors.
+            // IMPORTANT: Use responseType 'text' to avoid raw JSON.parse crashes when
+            // the backend returns HTML (seen in some proxy/SSR/misroute setups).
+            const res = await firstValueFrom(this.http.request(config.method, config.url, {
+                body: config.body,
+                headers: config.headers,
+                withCredentials: config.credentials === 'include',
+                observe: 'response',
+                responseType: 'text',
+            }));
+            const contentType = res.headers?.get('content-type');
+            const parsed = this.parseJsonBody(res.body ?? '', contentType);
+            return {
+                data: parsed,
+                status: res.status,
+                headers: {}, // Reserved for future header passthrough if needed
+            };
+        }
+        catch (error) {
+            if (error instanceof HttpErrorResponse) {
+                // Convert Angular's HttpErrorResponse to NAuthClientError.
+                // When using responseType 'text', `error.error` is typically a string.
+                const contentType = error.headers?.get('content-type') ?? null;
+                const rawBody = typeof error.error === 'string' ? error.error : '';
+                const parsedError = this.parseJsonBody(rawBody, contentType);
+                const errorData = typeof parsedError === 'object' && parsedError !== null ? parsedError : {};
+                const code = typeof errorData['code'] === 'string' ? errorData['code'] : NAuthErrorCode.INTERNAL_ERROR;
+                const message = typeof errorData['message'] === 'string'
+                    ? errorData['message']
+                    : typeof parsedError === 'string' && parsedError.trim()
+                        ? parsedError
+                        : error.message || `Request failed with status ${error.status}`;
+                const timestamp = typeof errorData['timestamp'] === 'string' ? errorData['timestamp'] : undefined;
+                const details = typeof errorData['details'] === 'object' ? errorData['details'] : undefined;
+                throw new NAuthClientError(code, message, {
+                    statusCode: error.status,
+                    timestamp,
+                    details,
+                    isNetworkError: error.status === 0, // Network error (no response from server)
+                });
+            }
+            // Re-throw non-HTTP errors as an SDK error so consumers don't see raw parser crashes.
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            throw new NAuthClientError(NAuthErrorCode.INTERNAL_ERROR, message, {
+                statusCode: 0,
+                isNetworkError: true,
+            });
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: AngularHttpAdapter, deps: [{ token: i1.HttpClient }], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: AngularHttpAdapter });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: AngularHttpAdapter, decorators: [{
+            type: Injectable
+        }], ctorParameters: () => [{ type: i1.HttpClient }] });
+
+/**
+ * Angular wrapper around NAuthClient that provides promise-based auth methods and reactive state.
+ *
+ * This service provides:
+ * - Reactive state (currentUser$, isAuthenticated$, challenge$)
+ * - All core auth methods as Promises (login, signup, logout, refresh)
+ * - Profile management (getProfile, updateProfile, changePassword)
+ * - Challenge flow methods (respondToChallenge, resendCode)
+ * - MFA management (getMfaStatus, setupMfaDevice, etc.)
+ * - Social authentication and account linking
+ * - Device trust management
+ * - Audit history
+ *
+ * @example
+ * ```typescript
+ * constructor(private auth: AuthService) {}
+ *
+ * // Reactive state
+ * this.auth.currentUser$.subscribe(user => ...);
+ * this.auth.isAuthenticated$.subscribe(isAuth => ...);
+ *
+ * // Auth operations with async/await
+ * const response = await this.auth.login(email, password);
+ *
+ * // Profile management
+ * await this.auth.changePassword(oldPassword, newPassword);
+ * const user = await this.auth.updateProfile({ firstName: 'John' });
+ *
+ * // MFA operations
+ * const status = await this.auth.getMfaStatus();
+ * ```
+ */
+class AuthService {
+    client;
+    config;
+    currentUserSubject = new BehaviorSubject(null);
+    isAuthenticatedSubject = new BehaviorSubject(false);
+    challengeSubject = new BehaviorSubject(null);
+    authEventsSubject = new Subject();
+    initialized = false;
+    /**
+     * @param config - Injected client configuration (required)
+     * @param httpAdapter - Angular HTTP adapter for making requests (required)
+     */
+    constructor(config, httpAdapter) {
+        this.config = config;
+        // Use provided httpAdapter (from config or injected)
+        const adapter = config.httpAdapter ?? httpAdapter;
+        if (!adapter) {
+            throw new Error('HttpAdapter not found. Either provide httpAdapter in NAUTH_CLIENT_CONFIG or ensure HttpClient is available.');
+        }
+        this.client = new NAuthClient({
+            ...config,
+            httpAdapter: adapter,
+            onAuthStateChange: (user) => {
+                this.currentUserSubject.next(user);
+                this.isAuthenticatedSubject.next(Boolean(user));
+                config.onAuthStateChange?.(user);
+            },
+        });
+        // Forward all client events to Observable stream
+        this.client.on('*', (event) => {
+            this.authEventsSubject.next(event);
+        });
+        // Auto-initialize on construction (hydrate from storage)
+        this.initialize();
+    }
+    // ============================================================================
+    // Reactive State Observables
+    // ============================================================================
+    /**
+     * Current user observable.
+     */
+    get currentUser$() {
+        return this.currentUserSubject.asObservable();
+    }
+    /**
+     * Authenticated state observable.
+     */
+    get isAuthenticated$() {
+        return this.isAuthenticatedSubject.asObservable();
+    }
+    /**
+     * Current challenge observable (for reactive challenge navigation).
+     */
+    get challenge$() {
+        return this.challengeSubject.asObservable();
+    }
+    /**
+     * Authentication events stream.
+     * Emits all auth lifecycle events for custom logic, analytics, or UI updates.
+     */
+    get authEvents$() {
+        return this.authEventsSubject.asObservable();
+    }
+    /**
+     * Successful authentication events stream.
+     * Emits when user successfully authenticates (login, signup, social auth).
+     */
+    get authSuccess$() {
+        return this.authEventsSubject.pipe(filter((e) => e.type === 'auth:success'));
+    }
+    /**
+     * Authentication error events stream.
+     * Emits when authentication fails (login error, OAuth error, etc.).
+     */
+    get authError$() {
+        return this.authEventsSubject.pipe(filter((e) => e.type === 'auth:error' || e.type === 'oauth:error'));
+    }
+    // ============================================================================
+    // Sync State Accessors (for guards, templates)
+    // ============================================================================
+    /**
+     * Check if authenticated (sync, uses cached state).
+     */
+    isAuthenticated() {
+        return this.client.isAuthenticatedSync();
+    }
+    /**
+     * Get current user (sync, uses cached state).
+     */
+    getCurrentUser() {
+        return this.client.getCurrentUser();
+    }
+    /**
+     * Get current challenge (sync).
+     */
+    getCurrentChallenge() {
+        return this.challengeSubject.value;
+    }
+    // ============================================================================
+    // Core Auth Methods
+    // ============================================================================
+    /**
+     * Login with identifier and password.
+     *
+     * @param identifier - User email or username
+     * @param password - User password
+     * @returns Promise with auth response or challenge
+     *
+     * @example
+     * ```typescript
+     * const response = await this.auth.login('user@example.com', 'password');
+     * if (response.challengeName) {
+     *   // Handle challenge
+     * } else {
+     *   // Login successful
+     * }
+     * ```
+     */
+    async login(identifier, password) {
+        const res = await this.client.login(identifier, password);
+        return this.updateChallengeState(res);
+    }
+    /**
+     * Signup with credentials.
+     *
+     * @param payload - Signup request payload
+     * @returns Promise with auth response or challenge
+     *
+     * @example
+     * ```typescript
+     * const response = await this.auth.signup({
+     *   email: 'new@example.com',
+     *   password: 'SecurePass123!',
+     *   firstName: 'John',
+     * });
+     * ```
+     */
+    async signup(payload) {
+        const res = await this.client.signup(payload);
+        return this.updateChallengeState(res);
+    }
+    /**
+     * Logout current session.
+     *
+     * @param forgetDevice - If true, removes device trust
+     *
+     * @example
+     * ```typescript
+     * await this.auth.logout();
+     * ```
+     */
+    async logout(forgetDevice) {
+        await this.client.logout(forgetDevice);
+        this.challengeSubject.next(null);
+        // Explicitly update auth state after logout
+        this.currentUserSubject.next(null);
+        this.isAuthenticatedSubject.next(false);
+        // Clear CSRF token cookie if in cookies mode
+        // Note: Backend should clear httpOnly cookies, but we clear non-httpOnly ones
+        if (this.config.tokenDelivery === 'cookies' && typeof document !== 'undefined') {
+            const csrfCookieName = this.config.csrf?.cookieName ?? 'nauth_csrf_token';
+            // Extract domain from baseUrl if possible
+            try {
+                const url = new URL(this.config.baseUrl);
+                document.cookie = `${csrfCookieName}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/; domain=${url.hostname}`;
+                // Also try without domain (for localhost)
+                document.cookie = `${csrfCookieName}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/`;
+            }
+            catch {
+                // Fallback if baseUrl parsing fails
+                document.cookie = `${csrfCookieName}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/`;
+            }
+        }
+    }
+    /**
+     * Logout all sessions.
+     *
+     * Revokes all active sessions for the current user across all devices.
+     * Optionally revokes all trusted devices if forgetDevices is true.
+     *
+     * @param forgetDevices - If true, also revokes all trusted devices (default: false)
+     * @returns Promise with number of sessions revoked
+     *
+     * @example
+     * ```typescript
+     * const result = await this.auth.logoutAll();
+     * console.log(`Revoked ${result.revokedCount} sessions`);
+     * ```
+     */
+    async logoutAll(forgetDevices) {
+        const res = await this.client.logoutAll(forgetDevices);
+        this.challengeSubject.next(null);
+        // Explicitly update auth state after logout
+        this.currentUserSubject.next(null);
+        this.isAuthenticatedSubject.next(false);
+        return res;
+    }
+    /**
+     * Refresh tokens.
+     *
+     * @returns Promise with new tokens
+     *
+     * @example
+     * ```typescript
+     * const tokens = await this.auth.refresh();
+     * ```
+     */
+    async refresh() {
+        return this.client.refreshTokens();
+    }
+    // ============================================================================
+    // Account Recovery (Forgot Password)
+    // ============================================================================
+    /**
+     * Request a password reset code (forgot password).
+     *
+     * @param identifier - User email, username, or phone
+     * @returns Promise with password reset response
+     *
+     * @example
+     * ```typescript
+     * await this.auth.forgotPassword('user@example.com');
+     * ```
+     */
+    async forgotPassword(identifier) {
+        return this.client.forgotPassword(identifier);
+    }
+    /**
+     * Confirm a password reset code and set a new password.
+     *
+     * @param identifier - User email, username, or phone
+     * @param code - One-time reset code
+     * @param newPassword - New password
+     * @returns Promise with confirmation response
+     *
+     * @example
+     * ```typescript
+     * await this.auth.confirmForgotPassword('user@example.com', '123456', 'NewPass123!');
+     * ```
+     */
+    async confirmForgotPassword(identifier, code, newPassword) {
+        return this.client.confirmForgotPassword(identifier, code, newPassword);
+    }
+    /**
+     * Change user password (requires current password).
+     *
+     * @param oldPassword - Current password
+     * @param newPassword - New password (must meet requirements)
+     * @returns Promise that resolves when password is changed
+     *
+     * @example
+     * ```typescript
+     * await this.auth.changePassword('oldPassword123', 'newSecurePassword456!');
+     * ```
+     */
+    async changePassword(oldPassword, newPassword) {
+        return this.client.changePassword(oldPassword, newPassword);
+    }
+    /**
+     * Request password change (must change on next login).
+     *
+     * @returns Promise that resolves when request is sent
+     *
+     * @example
+     * ```typescript
+     * await this.auth.requestPasswordChange();
+     * ```
+     */
+    async requestPasswordChange() {
+        return this.client.requestPasswordChange();
+    }
+    // ============================================================================
+    // Profile Management
+    // ============================================================================
+    /**
+     * Get current user profile.
+     *
+     * @returns Promise of current user profile
+     *
+     * @example
+     * ```typescript
+     * const user = await this.auth.getProfile();
+     * console.log('User profile:', user);
+     * ```
+     */
+    async getProfile() {
+        const user = await this.client.getProfile();
+        // Update local state when profile is fetched
+        this.currentUserSubject.next(user);
+        return user;
+    }
+    /**
+     * Update user profile.
+     *
+     * @param updates - Profile fields to update
+     * @returns Promise of updated user profile
+     *
+     * @example
+     * ```typescript
+     * const user = await this.auth.updateProfile({ firstName: 'John', lastName: 'Doe' });
+     * console.log('Profile updated:', user);
+     * ```
+     */
+    async updateProfile(updates) {
+        const user = await this.client.updateProfile(updates);
+        // Update local state when profile is updated
+        this.currentUserSubject.next(user);
+        return user;
+    }
+    // ============================================================================
+    // Challenge Flow Methods (Essential for any auth flow)
+    // ============================================================================
+    /**
+     * Respond to a challenge (VERIFY_EMAIL, VERIFY_PHONE, MFA_REQUIRED, etc.).
+     *
+     * @param response - Challenge response data
+     * @returns Promise with auth response or next challenge
+     *
+     * @example
+     * ```typescript
+     * const result = await this.auth.respondToChallenge({
+     *   session: challengeSession,
+     *   type: 'VERIFY_EMAIL',
+     *   code: '123456',
+     * });
+     * ```
+     */
+    async respondToChallenge(response) {
+        const res = await this.client.respondToChallenge(response);
+        return this.updateChallengeState(res);
+    }
+    /**
+     * Resend challenge code.
+     *
+     * @param session - Challenge session token
+     * @returns Promise with destination information
+     *
+     * @example
+     * ```typescript
+     * const result = await this.auth.resendCode(session);
+     * console.log('Code sent to:', result.destination);
+     * ```
+     */
+    async resendCode(session) {
+        return this.client.resendCode(session);
+    }
+    /**
+     * Get MFA setup data (for MFA_SETUP_REQUIRED challenge).
+     *
+     * Returns method-specific setup information:
+     * - TOTP: { secret, qrCode, manualEntryKey }
+     * - SMS: { maskedPhone }
+     * - Email: { maskedEmail }
+     * - Passkey: WebAuthn registration options
+     *
+     * @param session - Challenge session token
+     * @param method - MFA method to set up
+     * @returns Promise of setup data response
+     *
+     * @example
+     * ```typescript
+     * const setupData = await this.auth.getSetupData(session, 'totp');
+     * console.log('QR Code:', setupData.setupData.qrCode);
+     * ```
+     */
+    async getSetupData(session, method) {
+        return this.client.getSetupData(session, method);
+    }
+    /**
+     * Get MFA challenge data (for MFA_REQUIRED challenge - e.g., passkey options).
+     *
+     * @param session - Challenge session token
+     * @param method - Challenge method
+     * @returns Promise of challenge data response
+     *
+     * @example
+     * ```typescript
+     * const challengeData = await this.auth.getChallengeData(session, 'passkey');
+     * ```
+     */
+    async getChallengeData(session, method) {
+        return this.client.getChallengeData(session, method);
+    }
+    /**
+     * Clear stored challenge (when navigating away from challenge flow).
+     *
+     * @returns Promise that resolves when challenge is cleared
+     *
+     * @example
+     * ```typescript
+     * await this.auth.clearChallenge();
+     * ```
+     */
+    async clearChallenge() {
+        await this.client.clearStoredChallenge();
+        this.challengeSubject.next(null);
+    }
+    // ============================================================================
+    // Social Authentication
+    // ============================================================================
+    /**
+     * Initiate social OAuth login flow.
+     * Redirects the browser to backend `/auth/social/:provider/redirect`.
+     *
+     * @param provider - Social provider ('google', 'apple', 'facebook')
+     * @param options - Optional redirect options
+     * @returns Promise that resolves when redirect starts
+     *
+     * @example
+     * ```typescript
+     * await this.auth.loginWithSocial('google', { returnTo: '/auth/callback' });
+     * ```
+     */
+    async loginWithSocial(provider, options) {
+        return this.client.loginWithSocial(provider, options);
+    }
+    /**
+     * Exchange an exchangeToken (from redirect callback URL) into an AuthResponse.
+     *
+     * Used for `tokenDelivery: 'json'` or hybrid flows where the backend redirects back
+     * with `exchangeToken` instead of setting cookies.
+     *
+     * @param exchangeToken - One-time exchange token from the callback URL
+     * @returns Promise of AuthResponse
+     *
+     * @example
+     * ```typescript
+     * const response = await this.auth.exchangeSocialRedirect(exchangeToken);
+     * ```
+     */
+    async exchangeSocialRedirect(exchangeToken) {
+        const res = await this.client.exchangeSocialRedirect(exchangeToken);
+        return this.updateChallengeState(res);
+    }
+    /**
+     * Verify native social token (mobile).
+     *
+     * @param request - Social verification request with provider and token
+     * @returns Promise of AuthResponse
+     *
+     * @example
+     * ```typescript
+     * const result = await this.auth.verifyNativeSocial({
+     *   provider: 'google',
+     *   idToken: nativeIdToken,
+     * });
+     * ```
+     */
+    async verifyNativeSocial(request) {
+        const res = await this.client.verifyNativeSocial(request);
+        return this.updateChallengeState(res);
+    }
+    /**
+     * Get linked social accounts.
+     *
+     * @returns Promise of linked accounts response
+     *
+     * @example
+     * ```typescript
+     * const accounts = await this.auth.getLinkedAccounts();
+     * console.log('Linked providers:', accounts.providers);
+     * ```
+     */
+    async getLinkedAccounts() {
+        return this.client.getLinkedAccounts();
+    }
+    /**
+     * Link social account.
+     *
+     * @param provider - Social provider to link
+     * @param code - OAuth authorization code
+     * @param state - OAuth state parameter
+     * @returns Promise with success message
+     *
+     * @example
+     * ```typescript
+     * await this.auth.linkSocialAccount('google', code, state);
+     * ```
+     */
+    async linkSocialAccount(provider, code, state) {
+        return this.client.linkSocialAccount(provider, code, state);
+    }
+    /**
+     * Unlink social account.
+     *
+     * @param provider - Social provider to unlink
+     * @returns Promise with success message
+     *
+     * @example
+     * ```typescript
+     * await this.auth.unlinkSocialAccount('google');
+     * ```
+     */
+    async unlinkSocialAccount(provider) {
+        return this.client.unlinkSocialAccount(provider);
+    }
+    // ============================================================================
+    // MFA Management
+    // ============================================================================
+    /**
+     * Get MFA status for the current user.
+     *
+     * @returns Promise of MFA status
+     *
+     * @example
+     * ```typescript
+     * const status = await this.auth.getMfaStatus();
+     * console.log('MFA enabled:', status.enabled);
+     * ```
+     */
+    async getMfaStatus() {
+        return this.client.getMfaStatus();
+    }
+    /**
+     * Get MFA devices for the current user.
+     *
+     * @returns Promise of MFA devices array
+     *
+     * @example
+     * ```typescript
+     * const devices = await this.auth.getMfaDevices();
+     * ```
+     */
+    async getMfaDevices() {
+        return this.client.getMfaDevices();
+    }
+    /**
+     * Setup MFA device (authenticated user).
+     *
+     * @param method - MFA method to set up
+     * @returns Promise of setup data
+     *
+     * @example
+     * ```typescript
+     * const setupData = await this.auth.setupMfaDevice('totp');
+     * ```
+     */
+    async setupMfaDevice(method) {
+        return this.client.setupMfaDevice(method);
+    }
+    /**
+     * Verify MFA setup (authenticated user).
+     *
+     * @param method - MFA method
+     * @param setupData - Setup data from setupMfaDevice
+     * @param deviceName - Optional device name
+     * @returns Promise with device ID
+     *
+     * @example
+     * ```typescript
+     * const result = await this.auth.verifyMfaSetup('totp', { code: '123456' }, 'My Phone');
+     * ```
+     */
+    async verifyMfaSetup(method, setupData, deviceName) {
+        return this.client.verifyMfaSetup(method, setupData, deviceName);
+    }
+    /**
+     * Remove MFA device.
+     *
+     * @param method - MFA method to remove
+     * @returns Promise with success message
+     *
+     * @example
+     * ```typescript
+     * await this.auth.removeMfaDevice('sms');
+     * ```
+     */
+    async removeMfaDevice(method) {
+        return this.client.removeMfaDevice(method);
+    }
+    /**
+     * Set preferred MFA method.
+     *
+     * @param method - Device method to set as preferred ('totp', 'sms', 'email', or 'passkey')
+     * @returns Promise with success message
+     *
+     * @example
+     * ```typescript
+     * await this.auth.setPreferredMfaMethod('totp');
+     * ```
+     */
+    async setPreferredMfaMethod(method) {
+        return this.client.setPreferredMfaMethod(method);
+    }
+    /**
+     * Generate backup codes.
+     *
+     * @returns Promise of backup codes array
+     *
+     * @example
+     * ```typescript
+     * const codes = await this.auth.generateBackupCodes();
+     * console.log('Backup codes:', codes);
+     * ```
+     */
+    async generateBackupCodes() {
+        return this.client.generateBackupCodes();
+    }
+    /**
+     * Set MFA exemption (admin/test scenarios).
+     *
+     * @param exempt - Whether to exempt user from MFA
+     * @param reason - Optional reason for exemption
+     * @returns Promise that resolves when exemption is set
+     *
+     * @example
+     * ```typescript
+     * await this.auth.setMfaExemption(true, 'Test account');
+     * ```
+     */
+    async setMfaExemption(exempt, reason) {
+        return this.client.setMfaExemption(exempt, reason);
+    }
+    // ============================================================================
+    // Device Trust
+    // ============================================================================
+    /**
+     * Trust current device.
+     *
+     * @returns Promise with device token
+     *
+     * @example
+     * ```typescript
+     * const result = await this.auth.trustDevice();
+     * console.log('Device trusted:', result.deviceToken);
+     * ```
+     */
+    async trustDevice() {
+        return this.client.trustDevice();
+    }
+    /**
+     * Check if the current device is trusted.
+     *
+     * @returns Promise with trusted status
+     *
+     * @example
+     * ```typescript
+     * const result = await this.auth.isTrustedDevice();
+     * if (result.trusted) {
+     *   console.log('This device is trusted');
+     * }
+     * ```
+     */
+    async isTrustedDevice() {
+        return this.client.isTrustedDevice();
+    }
+    // ============================================================================
+    // Audit History
+    // ============================================================================
+    /**
+     * Get paginated audit history for the current user.
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Promise of audit history response
+     *
+     * @example
+     * ```typescript
+     * const history = await this.auth.getAuditHistory({
+     *   page: 1,
+     *   limit: 20,
+     *   eventType: 'LOGIN_SUCCESS'
+     * });
+     * console.log('Audit history:', history);
+     * ```
+     */
+    async getAuditHistory(params) {
+        return this.client.getAuditHistory(params);
+    }
+    // ============================================================================
+    // Escape Hatch
+    // ============================================================================
+    /**
+     * Expose underlying NAuthClient for advanced scenarios.
+     *
+     * @deprecated All core functionality is now exposed directly on AuthService as Promises.
+     * Use the direct methods on AuthService instead (e.g., `auth.changePassword()` instead of `auth.getClient().changePassword()`).
+     * This method is kept for backward compatibility only and may be removed in a future version.
+     *
+     * @returns The underlying NAuthClient instance
+     *
+     * @example
+     * ```typescript
+     * // Deprecated - use direct methods instead
+     * const status = await this.auth.getClient().getMfaStatus();
+     *
+     * // Preferred - use direct methods
+     * const status = await this.auth.getMfaStatus();
+     * ```
+     */
+    getClient() {
+        return this.client;
+    }
+    // ============================================================================
+    // Internal Methods
+    // ============================================================================
+    /**
+     * Initialize by hydrating state from storage.
+     * Called automatically on construction.
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        await this.client.initialize();
+        // Hydrate challenge state
+        const storedChallenge = await this.client.getStoredChallenge();
+        if (storedChallenge) {
+            this.challengeSubject.next(storedChallenge);
+        }
+        // Update subjects from client state
+        const user = this.client.getCurrentUser();
+        if (user) {
+            this.currentUserSubject.next(user);
+            this.isAuthenticatedSubject.next(true);
+        }
+    }
+    /**
+     * Update challenge state after auth response.
+     */
+    updateChallengeState(response) {
+        if (response.challengeName) {
+            this.challengeSubject.next(response);
+        }
+        else {
+            this.challengeSubject.next(null);
+        }
+        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 }], 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: [{
+            type: Injectable
+        }], ctorParameters: () => [{ type: undefined, decorators: [{
+                    type: Inject,
+                    args: [NAUTH_CLIENT_CONFIG]
+                }] }, { type: AngularHttpAdapter }] });
+
+/**
+ * Refresh state management.
+ */
+let isRefreshing$1 = false;
+const refreshTokenSubject$1 = new BehaviorSubject(null);
+const retriedRequests$1 = new WeakSet();
+/**
+ * Get CSRF token from cookie.
+ */
+function getCsrfToken$1(cookieName) {
+    if (typeof document === 'undefined')
+        return null;
+    const match = document.cookie.match(new RegExp(`(^| )${cookieName}=([^;]+)`));
+    return match ? decodeURIComponent(match[2]) : null;
+}
+/**
+ * Class-based HTTP interceptor for NgModule apps (Angular < 17).
+ *
+ * For standalone components (Angular 17+), use the functional `authInterceptor` instead.
+ *
+ * @example
+ * ```typescript
+ * // app.module.ts
+ * import { HTTP_INTERCEPTORS } from '@angular/common/http';
+ * import { AuthInterceptorClass } from '@nauth-toolkit/client-angular';
+ *
+ * @NgModule({
+ *   providers: [
+ *     { provide: HTTP_INTERCEPTORS, useClass: AuthInterceptorClass, multi: true }
+ *   ]
+ * })
+ * ```
+ */
+class AuthInterceptorClass {
+    config;
+    http;
+    authService;
+    router;
+    constructor(config, http, authService, router) {
+        this.config = config;
+        this.http = http;
+        this.authService = authService;
+        this.router = router;
+    }
+    intercept(req, next) {
+        const tokenDelivery = this.config.tokenDelivery;
+        const baseUrl = this.config.baseUrl;
+        // ============================================================================
+        // COOKIES MODE: withCredentials + CSRF token
+        // ============================================================================
+        if (tokenDelivery === 'cookies') {
+            let clonedReq = req.clone({ withCredentials: true });
+            // Add CSRF token header if it's a mutating request
+            if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method)) {
+                const csrfToken = getCsrfToken$1(this.config.csrf?.cookieName || 'XSRF-TOKEN');
+                if (csrfToken) {
+                    clonedReq = clonedReq.clone({
+                        setHeaders: { [this.config.csrf?.headerName || 'X-XSRF-TOKEN']: csrfToken },
+                    });
+                }
+            }
+            return next.handle(clonedReq).pipe(catchError((error) => {
+                if (error.status === 401 && !retriedRequests$1.has(req)) {
+                    retriedRequests$1.add(req);
+                    if (!isRefreshing$1) {
+                        isRefreshing$1 = true;
+                        refreshTokenSubject$1.next(null);
+                        return from(this.http
+                            .post(`${baseUrl}/refresh`, {}, { withCredentials: true })
+                            .toPromise()).pipe(switchMap(() => {
+                            isRefreshing$1 = false;
+                            refreshTokenSubject$1.next('refreshed');
+                            return next.handle(clonedReq);
+                        }), catchError((refreshError) => {
+                            isRefreshing$1 = false;
+                            this.authService.logout();
+                            this.router.navigate([this.config.redirects?.sessionExpired || '/login']);
+                            return throwError(() => refreshError);
+                        }));
+                    }
+                    else {
+                        return refreshTokenSubject$1.pipe(filter$1((token) => token !== null), take(1), switchMap(() => next.handle(clonedReq)));
+                    }
+                }
+                return throwError(() => error);
+            }));
+        }
+        // ============================================================================
+        // JSON MODE: Delegate to SDK for token handling
+        // ============================================================================
+        return next.handle(req);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: AuthInterceptorClass, deps: [{ token: NAUTH_CLIENT_CONFIG }, { token: i1.HttpClient }, { token: AuthService }, { token: i3.Router }], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: AuthInterceptorClass });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: AuthInterceptorClass, decorators: [{
+            type: Injectable
+        }], ctorParameters: () => [{ type: undefined, decorators: [{
+                    type: Inject,
+                    args: [NAUTH_CLIENT_CONFIG]
+                }] }, { type: i1.HttpClient }, { type: AuthService }, { type: i3.Router }] });
+
+/**
+ * NgModule for nauth-toolkit Angular integration.
+ *
+ * Use this for NgModule-based apps (Angular 17+ with NgModule or legacy apps).
+ *
+ * @example
+ * ```typescript
+ * // app.module.ts
+ * import { NAuthModule } from '@nauth-toolkit/client-angular';
+ *
+ * @NgModule({
+ *   imports: [
+ *     NAuthModule.forRoot({
+ *       baseUrl: 'http://localhost:3000/auth',
+ *       tokenDelivery: 'cookies',
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+class NAuthModule {
+    static forRoot(config) {
+        return {
+            ngModule: NAuthModule,
+            providers: [
+                {
+                    provide: NAUTH_CLIENT_CONFIG,
+                    useValue: config,
+                },
+                AngularHttpAdapter,
+                {
+                    provide: AuthService,
+                    useFactory: (httpAdapter) => {
+                        return new AuthService(config, httpAdapter);
+                    },
+                    deps: [AngularHttpAdapter],
+                },
+                {
+                    provide: HTTP_INTERCEPTORS,
+                    useClass: AuthInterceptorClass,
+                    multi: true,
+                },
+            ],
+        };
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: NAuthModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
+    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "17.3.12", ngImport: i0, type: NAuthModule, imports: [HttpClientModule], exports: [HttpClientModule] });
+    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: NAuthModule, imports: [HttpClientModule, HttpClientModule] });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: NAuthModule, decorators: [{
+            type: NgModule,
+            args: [{
+                    imports: [HttpClientModule],
+                    exports: [HttpClientModule],
+                }]
+        }] });
+
+/**
+ * Refresh state management.
+ * BehaviorSubject pattern is the industry-standard for token refresh.
+ */
+let isRefreshing = false;
+const refreshTokenSubject = new BehaviorSubject(null);
+/**
+ * Track retried requests to prevent infinite loops.
+ */
+const retriedRequests = new WeakSet();
+/**
+ * Get CSRF token from cookie.
+ */
+function getCsrfToken(cookieName) {
+    if (typeof document === 'undefined')
+        return null;
+    const match = document.cookie.match(new RegExp(`(^| )${cookieName}=([^;]+)`));
+    return match ? decodeURIComponent(match[2]) : null;
+}
+/**
+ * Angular HTTP interceptor for nauth-toolkit.
+ *
+ * Handles:
+ * - Cookies mode: withCredentials + CSRF tokens + refresh via POST
+ * - JSON mode: refresh via SDK, retry with new token
+ */
+const authInterceptor = (req, next) => {
+    const config = inject(NAUTH_CLIENT_CONFIG);
+    const http = inject(HttpClient);
+    const authService = inject(AuthService);
+    const platformId = inject(PLATFORM_ID);
+    const router = inject(Router);
+    const isBrowser = isPlatformBrowser(platformId);
+    if (!isBrowser) {
+        return next(req);
+    }
+    const tokenDelivery = config.tokenDelivery;
+    const baseUrl = config.baseUrl;
+    const endpoints = config.endpoints ?? {};
+    const refreshPath = endpoints.refresh ?? '/refresh';
+    const loginPath = endpoints.login ?? '/login';
+    const signupPath = endpoints.signup ?? '/signup';
+    const socialExchangePath = endpoints.socialExchange ?? '/social/exchange';
+    const refreshUrl = `${baseUrl}${refreshPath}`;
+    const isAuthApiRequest = req.url.includes(baseUrl);
+    const isRefreshEndpoint = req.url.includes(refreshPath);
+    const isPublicEndpoint = req.url.includes(loginPath) || req.url.includes(signupPath) || req.url.includes(socialExchangePath);
+    // Build request with credentials (cookies mode only)
+    let authReq = req;
+    if (tokenDelivery === 'cookies') {
+        authReq = authReq.clone({ withCredentials: true });
+        if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method)) {
+            const csrfCookieName = config.csrf?.cookieName ?? 'nauth_csrf_token';
+            const csrfHeaderName = config.csrf?.headerName ?? 'x-csrf-token';
+            const csrfToken = getCsrfToken(csrfCookieName);
+            if (csrfToken) {
+                authReq = authReq.clone({ setHeaders: { [csrfHeaderName]: csrfToken } });
+            }
+        }
+    }
+    return next(authReq).pipe(catchError((error) => {
+        const shouldHandle = error instanceof HttpErrorResponse &&
+            error.status === 401 &&
+            isAuthApiRequest &&
+            !isRefreshEndpoint &&
+            !isPublicEndpoint &&
+            !retriedRequests.has(req);
+        if (!shouldHandle) {
+            return throwError(() => error);
+        }
+        if (config.debug) {
+            console.warn('[nauth-interceptor] 401 detected:', req.url);
+        }
+        if (!isRefreshing) {
+            isRefreshing = true;
+            refreshTokenSubject.next(null);
+            if (config.debug) {
+                console.warn('[nauth-interceptor] Starting refresh...');
+            }
+            // Refresh based on mode
+            const refresh$ = tokenDelivery === 'cookies'
+                ? http.post(refreshUrl, {}, { withCredentials: true })
+                : from(authService.refresh());
+            return refresh$.pipe(switchMap((response) => {
+                if (config.debug) {
+                    console.warn('[nauth-interceptor] Refresh successful');
+                }
+                isRefreshing = false;
+                // Get new token (JSON mode) or signal success (cookies mode)
+                const newToken = 'accessToken' in response ? response.accessToken : 'success';
+                refreshTokenSubject.next(newToken ?? 'success');
+                // Build retry request
+                const retryReq = buildRetryRequest(authReq, tokenDelivery, newToken);
+                retriedRequests.add(retryReq);
+                if (config.debug) {
+                    console.warn('[nauth-interceptor] Retrying:', req.url);
+                }
+                return next(retryReq);
+            }), catchError((err) => {
+                if (config.debug) {
+                    console.error('[nauth-interceptor] Refresh failed:', err);
+                }
+                isRefreshing = false;
+                refreshTokenSubject.next(null);
+                // Handle session expiration - redirect to configured URL
+                if (config.redirects?.sessionExpired) {
+                    router.navigateByUrl(config.redirects.sessionExpired).catch((navError) => {
+                        if (config.debug) {
+                            console.error('[nauth-interceptor] Navigation failed:', navError);
+                        }
+                    });
+                }
+                return throwError(() => err);
+            }));
+        }
+        else {
+            // Wait for ongoing refresh
+            if (config.debug) {
+                console.warn('[nauth-interceptor] Waiting for refresh...');
+            }
+            return refreshTokenSubject.pipe(filter$1((token) => token !== null), take(1), switchMap((token) => {
+                if (config.debug) {
+                    console.warn('[nauth-interceptor] Refresh done, retrying:', req.url);
+                }
+                const retryReq = buildRetryRequest(authReq, tokenDelivery, token);
+                retriedRequests.add(retryReq);
+                return next(retryReq);
+            }));
+        }
+    }));
+};
+/**
+ * Build retry request with appropriate auth.
+ */
+function buildRetryRequest(originalReq, tokenDelivery, newToken) {
+    if (tokenDelivery === 'json' && newToken && newToken !== 'success') {
+        return originalReq.clone({
+            setHeaders: { Authorization: `Bearer ${newToken}` },
+        });
+    }
+    return originalReq.clone();
+}
+/**
+ * Class-based interceptor for NgModule compatibility.
+ */
+class AuthInterceptor {
+    intercept(req, next) {
+        return authInterceptor(req, next);
+    }
+}
+
+/**
+ * Functional route guard for authentication (Angular 17+).
+ *
+ * Protects routes by checking if user is authenticated.
+ * Redirects to login page if not authenticated.
+ *
+ * @param redirectTo - Path to redirect to if not authenticated (default: '/login')
+ * @returns CanActivateFn guard function
+ *
+ * @example
+ * ```typescript
+ * // In route configuration
+ * const routes: Routes = [
+ *   {
+ *     path: 'home',
+ *     component: HomeComponent,
+ *     canActivate: [authGuard()]
+ *   },
+ *   {
+ *     path: 'admin',
+ *     component: AdminComponent,
+ *     canActivate: [authGuard('/admin/login')]
+ *   }
+ * ];
+ * ```
+ */
+function authGuard(redirectTo = '/login') {
+    return () => {
+        const auth = inject(AuthService);
+        const router = inject(Router);
+        if (auth.isAuthenticated()) {
+            return true;
+        }
+        return router.createUrlTree([redirectTo]);
+    };
+}
+/**
+ * Class-based authentication guard for NgModule compatibility.
+ *
+ * @example
+ * ```typescript
+ * // In route configuration (NgModule)
+ * const routes: Routes = [
+ *   {
+ *     path: 'home',
+ *     component: HomeComponent,
+ *     canActivate: [AuthGuard]
+ *   }
+ * ];
+ *
+ * // In module providers
+ * @NgModule({
+ *   providers: [AuthGuard]
+ * })
+ * ```
+ */
+class AuthGuard {
+    auth;
+    router;
+    /**
+     * @param auth - Authentication service
+     * @param router - Angular router
+     */
+    constructor(auth, router) {
+        this.auth = auth;
+        this.router = router;
+    }
+    /**
+     * Check if route can be activated.
+     *
+     * @returns True if authenticated, otherwise redirects to login
+     */
+    canActivate() {
+        if (this.auth.isAuthenticated()) {
+            return true;
+        }
+        return this.router.createUrlTree(['/login']);
+    }
+}
+
+/**
+ * Social redirect callback route guard.
+ *
+ * This guard supports the redirect-first social flow where the backend redirects
+ * back to the frontend with:
+ * - `appState` (always optional)
+ * - `exchangeToken` (present for json/hybrid flows, and for cookie flows that return a challenge)
+ * - `error` / `error_description` (provider errors)
+ *
+ * Behavior:
+ * - If `exchangeToken` exists: exchanges it via backend and redirects to success or challenge routes.
+ * - If no `exchangeToken`: treat as cookie-success path and redirect to success route.
+ * - If `error` exists: redirects to oauthError route.
+ *
+ * @example
+ * ```typescript
+ * import { socialRedirectCallbackGuard } from '@nauth-toolkit/client/angular';
+ *
+ * export const routes: Routes = [
+ *   { path: 'auth/callback', canActivate: [socialRedirectCallbackGuard], component: CallbackComponent },
+ * ];
+ * ```
+ */
+const socialRedirectCallbackGuard = async () => {
+    const auth = inject(AuthService);
+    const config = inject(NAUTH_CLIENT_CONFIG);
+    const platformId = inject(PLATFORM_ID);
+    const isBrowser = isPlatformBrowser(platformId);
+    if (!isBrowser) {
+        return false;
+    }
+    const params = new URLSearchParams(window.location.search);
+    const error = params.get('error');
+    const exchangeToken = params.get('exchangeToken');
+    // Provider error: redirect to oauthError
+    if (error) {
+        const errorUrl = config.redirects?.oauthError || '/login';
+        window.location.replace(errorUrl);
+        return false;
+    }
+    // No exchangeToken: cookie success path; redirect to success.
+    //
+    // Note: we do not "activate" the callback route to avoid consumers needing to render a page.
+    if (!exchangeToken) {
+        // ============================================================================
+        // Cookies mode: hydrate user state before redirecting
+        // ============================================================================
+        // WHY: In cookie delivery, the OAuth callback completes via browser redirects, so the frontend
+        // does not receive a JSON AuthResponse to populate the SDK's cached `currentUser`.
+        //
+        // Without this, sync guards (`authGuard`) can immediately redirect to /login because
+        // `currentUser` is still null even though cookies were set successfully.
+        try {
+            await auth.getProfile();
+        }
+        catch {
+            const errorUrl = config.redirects?.oauthError || '/login';
+            window.location.replace(errorUrl);
+            return false;
+        }
+        const successUrl = config.redirects?.success || '/';
+        window.location.replace(successUrl);
+        return false;
+    }
+    // Exchange token and route accordingly
+    const response = await auth.exchangeSocialRedirect(exchangeToken);
+    if (response.challengeName) {
+        const challengeBase = config.redirects?.challengeBase || '/auth/challenge';
+        const challengeRoute = response.challengeName.toLowerCase().replace(/_/g, '-');
+        window.location.replace(`${challengeBase}/${challengeRoute}`);
+        return false;
+    }
+    const successUrl = config.redirects?.success || '/';
+    window.location.replace(successUrl);
+    return false;
+};
+
+/**
+ * Public API Surface of @nauth-toolkit/client-angular (NgModule)
+ *
+ * This is the default entry point for NgModule-based Angular apps.
+ * For standalone components, use: @nauth-toolkit/client-angular/standalone
+ */
+// Re-export core client types and utilities
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { AngularHttpAdapter, AuthGuard, AuthInterceptor, AuthInterceptorClass, AuthService, NAUTH_CLIENT_CONFIG, NAuthModule, authGuard, authInterceptor, socialRedirectCallbackGuard };
+//# sourceMappingURL=nauth-toolkit-client-angular.mjs.map