@nauth-toolkit/client-angular 0.1.53 → 0.1.55

package/README.md

@@ -1,182 +1,9 @@
 # @nauth-toolkit/client-angular
 
-Angular adapter for nauth-toolkit client SDK. Provides Angular-specific components, services, guards, and interceptors for seamless authentication integration.
+Angular adapter for nauth-toolkit client SDK
 
-## Features
+## Preview Release Notice
 
-- **AuthService** - Injectable wrapper around NAuthClient with RxJS Observables
-- **authInterceptor** - HTTP interceptor for auth headers, CSRF, and token refresh
-- **authGuard** - Route guard for protected routes
-- **socialRedirectCallbackGuard** - OAuth callback handler
-- **NAuthModule** - NgModule for non-standalone apps (Angular < 17)
-- **AngularHttpAdapter** - Uses Angular's HttpClient for all requests
-
-## Installation
-
-```bash
-npm install @nauth-toolkit/client-angular @nauth-toolkit/client
-```
-
-Or with Yarn:
-
-```bash
-yarn add @nauth-toolkit/client-angular @nauth-toolkit/client
-```
-
-## Quick Start
-
-### Standalone Components (Angular 17+)
-
-```typescript
-// app.config.ts
-import { ApplicationConfig, inject } from '@angular/core';
-import { Router, provideRouter } from '@angular/router';
-import { provideHttpClient, withInterceptors } from '@angular/common/http';
-import { NAUTH_CLIENT_CONFIG, authInterceptor } from '@nauth-toolkit/client-angular';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideRouter(routes),
-    {
-      provide: NAUTH_CLIENT_CONFIG,
-      useFactory: () => {
-        const router = inject(Router);
-        return {
-          baseUrl: 'https://api.example.com/auth',
-          tokenDelivery: 'cookies',
-          onSessionExpired: () => router.navigate(['/login']),
-        };
-      },
-    },
-    provideHttpClient(withInterceptors([authInterceptor])),
-  ],
-};
-```
-
-### NgModule (Angular < 17)
-
-```typescript
-// app.module.ts
-import { NgModule } from '@angular/core';
-import { BrowserModule } from '@angular/platform-browser';
-import { Router } from '@angular/router';
-import { HttpClientModule, HTTP_INTERCEPTORS } from '@angular/common/http';
-import { NAuthModule, AuthInterceptor, NAUTH_CLIENT_CONFIG } from '@nauth-toolkit/client-angular';
-
-@NgModule({
-  imports: [BrowserModule, HttpClientModule, NAuthModule],
-  providers: [
-    {
-      provide: NAUTH_CLIENT_CONFIG,
-      useFactory: (router: Router) => ({
-        baseUrl: 'https://api.example.com/auth',
-        tokenDelivery: 'cookies',
-        onSessionExpired: () => router.navigate(['/login']),
-      }),
-      deps: [Router],
-    },
-    { provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true },
-  ],
-  bootstrap: [AppComponent],
-})
-export class AppModule {}
-```
-
-## Usage
-
-### Authentication
-
-```typescript
-import { Component } from '@angular/core';
-import { Router } from '@angular/router';
-import { AuthService } from '@nauth-toolkit/client-angular';
-
-@Component({
-  selector: 'app-login',
-  template: `
-    <form (ngSubmit)="login()">
-      <input [(ngModel)]="email" placeholder="Email" />
-      <input [(ngModel)]="password" type="password" />
-      <button type="submit">Login</button>
-    </form>
-  `,
-})
-export class LoginComponent {
-  email = '';
-  password = '';
-
-  constructor(
-    private auth: AuthService,
-    private router: Router,
-  ) {}
-
-  async login() {
-    const response = await this.auth.login(this.email, this.password);
-    if (response.challengeName) {
-      this.router.navigate(['/verify', response.challengeName.toLowerCase()]);
-    } else {
-      this.router.navigate(['/dashboard']);
-    }
-  }
-}
-```
-
-### Route Protection
-
-```typescript
-// app.routes.ts
-import { Routes } from '@angular/router';
-import { authGuard } from '@nauth-toolkit/client-angular';
-
-export const routes: Routes = [
-  { path: 'login', component: LoginComponent },
-  {
-    path: 'dashboard',
-    component: DashboardComponent,
-    canActivate: [authGuard()],
-  },
-];
-```
-
-### Reactive State
-
-```typescript
-import { Component } from '@angular/core';
-import { AuthService } from '@nauth-toolkit/client-angular';
-import { AsyncPipe } from '@angular/common';
-
-@Component({
-  selector: 'app-profile',
-  template: `
-    @if (currentUser$ | async; as user) {
-      <h1>Welcome, {{ user.email }}</h1>
-    }
-  `,
-  imports: [AsyncPipe],
-})
-export class ProfileComponent {
-  currentUser$ = this.auth.currentUser$;
-
-  constructor(private auth: AuthService) {}
-}
-```
-
-## Compatibility
-
-- **Angular**: 14.0.0+
-- **RxJS**: 7.x or 8.x
-- **Node.js**: 22.0.0+
-
-## Documentation
-
-Full documentation available at [https://nauth-toolkit.com/docs](https://nauth-toolkit.com/docs)
-
-- [Angular Integration Guide](https://nauth-toolkit.com/docs/frontend-sdk/angular/overview)
-- [API Reference](https://nauth-toolkit.com/docs/frontend-sdk/api/overview)
-- [Challenge Handling](https://nauth-toolkit.com/docs/frontend-sdk/guides/challenge-handling)
-- [MFA Setup](https://nauth-toolkit.com/docs/frontend-sdk/guides/mfa-setup)
-
-## License
-
-UNLICENSED
+**This is a preview release for internal testing. Do not use in production yet.**
 
+This package is part of nauth-toolkit and is currently in early access/preview. Features and APIs may change between releases. For production use, please wait for the stable v1.0 release.

package/ng-package.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "./dist",
+  "lib": {
+    "entryFile": "src/public-api.ts",
+    "flatModuleFile": "nauth-toolkit-client-angular"
+  },
+  "allowedNonPeerDependencies": [
+    "@nauth-toolkit/client"
+  ]
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauth-toolkit/client-angular",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "description": "Angular adapter for nauth-toolkit client SDK",
   "keywords": [
     "nauth",
@@ -22,27 +22,31 @@
     "tag": "latest"
   },
   "peerDependencies": {
-    "@angular/common": ">=14.0.0",
-    "@angular/core": ">=14.0.0",
-    "@nauth-toolkit/client": "^0.1.53",
+    "@angular/common": ">=17.0.0",
+    "@angular/core": ">=17.0.0",
+    "@nauth-toolkit/client": "^0.1.55",
     "rxjs": "^7.0.0 || ^8.0.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"
   },
-  "engines": {
-    "node": ">=22.0.0"
+  "devDependencies": {
+    "@angular/common": "^17.3.12",
+    "@angular/compiler": "^17.3.12",
+    "@angular/compiler-cli": "^17.3.12",
+    "@angular/core": "^17.3.12",
+    "@angular/platform-browser": "^17.3.12",
+    "@angular/platform-browser-dynamic": "^17.3.12",
+    "@angular/router": "^17.3.12",
+    "ng-packagr": "^17.0.0",
+    "rxjs": "~7.8.0",
+    "typescript": "~5.3.3"
   },
-  "module": "fesm2022/nauth-toolkit-client-angular.mjs",
-  "typings": "types/nauth-toolkit-client-angular.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./types/nauth-toolkit-client-angular.d.ts",
-      "default": "./fesm2022/nauth-toolkit-client-angular.mjs"
-    }
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json",
+    "clean": "rm -rf dist"
   },
-  "sideEffects": false
-}
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/src/lib/auth.guard.ts

@@ -0,0 +1,86 @@
+import { inject } from '@angular/core';
+import { CanActivateFn, Router, UrlTree } from '@angular/router';
+import { AuthService } from '../ngmodule/auth.service';
+
+/**
+ * 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')]
+ *   }
+ * ];
+ * ```
+ */
+export function authGuard(redirectTo = '/login'): CanActivateFn {
+  return (): boolean | UrlTree => {
+    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]
+ * })
+ * ```
+ */
+export class AuthGuard {
+  /**
+   * @param auth - Authentication service
+   * @param router - Angular router
+   */
+  constructor(
+    private auth: AuthService,
+    private router: Router,
+  ) {}
+
+  /**
+   * Check if route can be activated.
+   *
+   * @returns True if authenticated, otherwise redirects to login
+   */
+  canActivate(): boolean | UrlTree {
+    if (this.auth.isAuthenticated()) {
+      return true;
+    }
+
+    return this.router.createUrlTree(['/login']);
+  }
+}

package/src/lib/auth.interceptor.ts

@@ -0,0 +1,194 @@
+import { inject, PLATFORM_ID } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import { HttpHandlerFn, HttpInterceptorFn, HttpRequest, HttpClient, HttpErrorResponse } from '@angular/common/http';
+import { Router } from '@angular/router';
+import { catchError, switchMap, throwError, filter, take, BehaviorSubject, from } from 'rxjs';
+import { NAUTH_CLIENT_CONFIG } from '../ngmodule/tokens';
+import { AuthService } from '../ngmodule/auth.service';
+
+/**
+ * Refresh state management.
+ * BehaviorSubject pattern is the industry-standard for token refresh.
+ */
+let isRefreshing = false;
+const refreshTokenSubject = new BehaviorSubject<string | null>(null);
+
+/**
+ * Track retried requests to prevent infinite loops.
+ */
+const retriedRequests = new WeakSet<HttpRequest<unknown>>();
+
+/**
+ * Get CSRF token from cookie.
+ */
+function getCsrfToken(cookieName: string): string | null {
+  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
+ */
+export const authInterceptor: HttpInterceptorFn = (req: HttpRequest<unknown>, next: HttpHandlerFn) => {
+  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: unknown) => {
+      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<{ accessToken?: string }>(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((token): token is string => 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: HttpRequest<unknown>,
+  tokenDelivery: string,
+  newToken?: string,
+): HttpRequest<unknown> {
+  if (tokenDelivery === 'json' && newToken && newToken !== 'success') {
+    return originalReq.clone({
+      setHeaders: { Authorization: `Bearer ${newToken}` },
+    });
+  }
+  return originalReq.clone();
+}
+
+/**
+ * Class-based interceptor for NgModule compatibility.
+ */
+export class AuthInterceptor {
+  intercept(req: HttpRequest<unknown>, next: HttpHandlerFn) {
+    return authInterceptor(req, next);
+  }
+}

package/src/lib/social-redirect-callback.guard.ts

@@ -0,0 +1,87 @@
+import { inject, PLATFORM_ID } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import { type CanActivateFn } from '@angular/router';
+import { AuthService } from '../ngmodule/auth.service';
+import { NAUTH_CLIENT_CONFIG } from '../ngmodule/tokens';
+
+/**
+ * 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 },
+ * ];
+ * ```
+ */
+export const socialRedirectCallbackGuard: CanActivateFn = async (): Promise<boolean> => {
+  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;
+};