@nauth-toolkit/core 0.1.0

package/src/handlers/csrf.handler.ts

@@ -0,0 +1,156 @@
+/**
+ * CSRF Handler
+ *
+ * Generates and validates CSRF tokens for cookie-based authentication.
+ *
+ * **Platform-Agnostic:**
+ * This handler operates purely on NAuthRequest interface.
+ * Context is managed by the adapter, not this handler.
+ *
+ * **Lazy Validation:**
+ * CSRF errors are stored in request attributes instead of thrown immediately.
+ * This allows public routes and requireAuth() to decide how to handle them.
+ */
+
+import { NAuthConfig, NAuthException, AuthErrorCode, NAuthLogger } from '../index';
+import { CsrfService } from '../services/csrf.service';
+import { NAuthRequest, NAuthResponse } from '../platform/interfaces';
+
+/** HTTP methods that don't require CSRF validation */
+const SAFE_METHODS = ['GET', 'HEAD', 'OPTIONS'];
+
+/**
+ * CsrfHandler
+ *
+ * Handles CSRF token generation and validation for cookie-based authentication.
+ */
+export class CsrfHandler {
+  constructor(
+    private readonly csrfService: CsrfService,
+    private readonly config: NAuthConfig,
+    private readonly logger?: NAuthLogger,
+  ) {}
+
+  /**
+   * Handle request - generate or validate CSRF token
+   *
+   * Note: Context is managed by adapter. This handler assumes context is available.
+   */
+  public async handle(req: NAuthRequest, res: NAuthResponse, next: () => Promise<void> | void): Promise<void> {
+    // Skip if token delivery is not cookies or hybrid
+    const method = this.config.tokenDelivery?.method || 'json';
+    if (method !== 'cookies' && method !== 'hybrid') {
+      await next();
+      return;
+    }
+
+    // Safe methods: Generate token if missing
+    if (SAFE_METHODS.includes(req.method)) {
+      await this.generateTokenIfMissing(req, res);
+      await next();
+      return;
+    }
+
+    // Skip public routes (CSRF not required)
+    if (req.attributes.nauthPublic) {
+      await next();
+      return;
+    }
+
+    // Skip excluded paths
+    const excludedPaths = this.config.security?.csrf?.excludedPaths || [];
+    if (excludedPaths.some((p: string) => req.path.startsWith(p))) {
+      await next();
+      return;
+    }
+
+    // Validate CSRF token for unsafe methods (POST, PUT, DELETE, etc.)
+    await this.validateToken(req);
+
+    await next();
+  }
+
+  /**
+   * Generate CSRF token if not present in cookies
+   */
+  private async generateTokenIfMissing(req: NAuthRequest, res: NAuthResponse): Promise<void> {
+    const cookieName = this.csrfService.getCookieName();
+    const existingToken = req.cookies[cookieName];
+
+    if (existingToken) {
+      // Token exists, clear any previous error state
+      delete req.attributes.nauthCsrfError;
+      return;
+    }
+
+    // Generate new token
+    const token = this.csrfService.generateToken();
+
+    // Build cookie options
+    const cookieOptions = {
+      httpOnly: true, // Prevents XSS access to token
+      secure: this.config.tokenDelivery?.cookieOptions?.secure ?? true,
+      sameSite: (this.config.tokenDelivery?.cookieOptions?.sameSite || 'strict') as 'strict' | 'lax' | 'none',
+      domain: this.config.tokenDelivery?.cookieOptions?.domain,
+      path: '/',
+      ...this.csrfService.getCookieOptions(),
+    };
+
+    // Set cookie
+    res.setCookie(cookieName, token, cookieOptions);
+
+    // Also expose token in response header (since cookie is httpOnly)
+    res.header(this.csrfService.getHeaderName(), token);
+
+    this.logger?.debug?.('CSRF token generated and set');
+  }
+
+  /**
+   * Validate CSRF token from request
+   *
+   * Uses lazy validation - stores error in attributes instead of throwing.
+   * requireAuth() helper will throw if error exists.
+   */
+  private async validateToken(req: NAuthRequest): Promise<void> {
+    const headerName = this.csrfService.getHeaderName();
+    const cookieName = this.csrfService.getCookieName();
+
+    // Get token from header or body
+    let tokenFromRequest = req.getHeader(headerName);
+    if (!tokenFromRequest && req.body) {
+      // Check common body fields
+      const body = req.body as Record<string, unknown>;
+      tokenFromRequest = (body[headerName] || body['_csrf'] || body['csrfToken']) as string | undefined;
+    }
+
+    // Get token from cookie
+    const cookieToken = req.cookies[cookieName];
+
+    // Validate - store errors lazily
+    if (!tokenFromRequest) {
+      req.attributes.nauthCsrfError = new NAuthException(
+        AuthErrorCode.CSRF_TOKEN_MISSING,
+        `CSRF token required. Include ${headerName} header or _csrf/csrfToken in body with the value from ${cookieName} cookie.`,
+      );
+      return;
+    }
+
+    if (!cookieToken) {
+      req.attributes.nauthCsrfError = new NAuthException(
+        AuthErrorCode.CSRF_TOKEN_MISSING,
+        'CSRF cookie missing. Make a GET request first to obtain a token.',
+      );
+      return;
+    }
+
+    // Validate token matches
+    const isValid = this.csrfService.validateToken(String(tokenFromRequest), cookieToken);
+
+    if (!isValid) {
+      req.attributes.nauthCsrfError = new NAuthException(AuthErrorCode.CSRF_TOKEN_INVALID, 'CSRF token mismatch.');
+      return;
+    }
+
+    this.logger?.debug?.('CSRF token validated successfully');
+  }
+}

package/src/handlers/token-delivery.handler.ts

@@ -0,0 +1,118 @@
+/**
+ * Token Delivery Handler
+ *
+ * Handles response interception to deliver tokens via Cookies or JSON.
+ */
+
+import {
+  NAuthConfig,
+  resolveDeliveryForRequest,
+  getAccessTokenCookieName,
+  getRefreshTokenCookieName,
+  NAuthLogger,
+} from '../index';
+import { NAuthRequest, NAuthResponse, NAuthCookieOptions } from '../platform/interfaces';
+
+export class TokenDeliveryHandler {
+  constructor(
+    private config: NAuthConfig,
+    private logger?: NAuthLogger,
+  ) {}
+
+  /**
+   * Process the response body.
+   * If it contains tokens, handle delivery and return sanitized body.
+   * If not, return original body.
+   */
+  public async handleResponse(req: NAuthRequest, res: NAuthResponse, body: any): Promise<any> {
+    // Check if this is an auth response
+    if (body && typeof body === 'object' && body.accessToken && body.refreshToken) {
+      const deliveryMode = this.resolveDeliveryMode(req);
+
+      if (deliveryMode === 'cookies') {
+        this.setTokenCookies(res, body);
+
+        // Remove tokens and expiration fields from body
+        // Expiration is managed by cookie maxAge, so these fields are not needed
+        const sanitizedBody = { ...body };
+        delete sanitizedBody.accessToken;
+        delete sanitizedBody.refreshToken;
+        delete sanitizedBody.accessTokenExpiresAt;
+        delete sanitizedBody.refreshTokenExpiresAt;
+
+        this.logger?.debug?.('Tokens delivered via cookies');
+        return sanitizedBody;
+      } else {
+        this.logger?.debug?.('Tokens delivered via JSON');
+        return body;
+      }
+    }
+
+    return body;
+  }
+
+  private resolveDeliveryMode(req: NAuthRequest): 'json' | 'cookies' {
+    const method = this.config.tokenDelivery?.method || 'json';
+
+    // Route override
+    if (req.attributes['nauthTokenDelivery']) {
+      return req.attributes['nauthTokenDelivery'];
+    }
+
+    // Hybrid mode
+    if (method === 'hybrid') {
+      return resolveDeliveryForRequest(req.raw, this.config.tokenDelivery?.hybridPolicy);
+    }
+
+    return method === 'cookies' ? 'cookies' : 'json';
+  }
+
+  private setTokenCookies(res: NAuthResponse, body: any): void {
+    const accessTokenCookieName = getAccessTokenCookieName(this.config);
+    const refreshTokenCookieName = getRefreshTokenCookieName(this.config);
+
+    const cookieOptions: NAuthCookieOptions = {
+      httpOnly: true,
+      secure: this.config.tokenDelivery?.cookieOptions?.secure ?? true,
+      sameSite: (this.config.tokenDelivery?.cookieOptions?.sameSite || 'strict') as 'strict' | 'lax' | 'none',
+      domain: this.config.tokenDelivery?.cookieOptions?.domain,
+      path: '/',
+    };
+
+    const accessMaxAge = this.parseExpiry(this.config.jwt.accessToken.expiresIn) * 1000;
+    const refreshMaxAge = this.parseExpiry(this.config.jwt.refreshToken.expiresIn) * 1000;
+
+    res.setCookie(accessTokenCookieName, body.accessToken, {
+      ...cookieOptions,
+      maxAge: accessMaxAge,
+    });
+
+    res.setCookie(refreshTokenCookieName, body.refreshToken, {
+      ...cookieOptions,
+      maxAge: refreshMaxAge,
+    });
+  }
+
+  private parseExpiry(expiry: string | number): number {
+    if (typeof expiry === 'number') return expiry;
+
+    const match = expiry.match(/^(\d+)([smhd])$/);
+    if (!match) return 900; // Default 15m
+
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+
+    switch (unit) {
+      case 's':
+        return value;
+      case 'm':
+        return value * 60;
+      case 'h':
+        return value * 3600;
+      case 'd':
+        return value * 86400;
+      default:
+        return 900;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,118 @@
+// ============================================================================
+// Public Services API
+// ============================================================================
+// These are the services that consumer applications should use directly.
+// For internal services needed by framework adapters, see ./internal.ts
+
+/**
+ * Main authentication service
+ * Handles signup, login, logout, password management, and user operations
+ */
+export * from './services/auth.service';
+
+/**
+ * Multi-Factor Authentication service
+ * Manages MFA setup, verification, and device management
+ */
+export * from './services/mfa.service';
+
+/**
+ * Social authentication service
+ * Complete API for OAuth authentication, social account linking, and management
+ */
+export * from './services/social-auth.service';
+
+/**
+ * Email verification service
+ * Handles email verification codes and verification workflows
+ */
+export * from './services/email-verification.service';
+
+/**
+ * Phone verification service
+ * Handles SMS verification codes and phone verification workflows
+ */
+export * from './services/phone-verification.service';
+
+/**
+ * Client information service
+ * Provides access to request context (IP, user agent, device token, session ID)
+ */
+export * from './services/client-info.service';
+
+/**
+ * Authentication audit service
+ * Logs and queries authentication events for security monitoring
+ *
+ * Note: Only query methods are available in the public API.
+ * Event recording is handled internally by the framework.
+ */
+export { AuthAuditService } from './services/auth-audit.service';
+
+/**
+ * CSRF Protection Service
+ */
+export { CsrfService } from './services/csrf.service';
+
+// ============================================================================
+// Internal Services - NOT EXPORTED
+// ============================================================================
+// Internal services are NOT exported from this file. They are only available
+// via '@nauth-toolkit/core/internal' for framework adapter development.
+//
+// Consumer applications should use the public services above (AuthService,
+// MFAService, etc.) which provide high-level APIs and automatically manage
+// internal services like password hashing, JWT tokens, and sessions.
+
+// ============================================================================
+// DTOs, Exceptions, Interfaces, Entities, Storage, and Utilities
+// ============================================================================
+// DTOs (Core only - feature DTOs moved to feature packages)
+export * from './dto';
+
+// Exceptions & Error Handling
+export { NAuthException, getHttpStatusForErrorCode } from './exceptions/nauth.exception';
+export { AuthErrorCode } from './enums/error-codes.enum';
+export { AuthAuditEventType } from './enums/auth-audit-event-type.enum';
+export { MFAMethod, MFADeviceMethod, MFAVerificationMethod, MFADeviceMethods } from './enums/mfa-method.enum';
+
+// Interfaces (All interfaces stay in core for contracts)
+export * from './interfaces';
+// Re-export ClientInfo interface with alias to avoid naming conflicts with decorators
+export type { ClientInfo as IClientInfo } from './interfaces/client-info.interface';
+
+// Zod Schemas (Runtime validation)
+export { authConfigSchema, type NAuthConfig as NAuthConfigFromSchema } from './schemas/auth-config.schema';
+// Keep interface export for backward compatibility
+export type { NAuthConfig } from './interfaces/config.interface';
+
+// Base Entity Classes (Database-agnostic entities)
+export * from './entities';
+
+// Storage
+export * from './storage';
+
+// Templates (Shared base templates)
+export * from './templates';
+
+// Utilities
+export * from './utils';
+
+// Validators
+export * from './validators/template.validator';
+
+// ============================================================================
+// Platform Agnostic Components (New Architecture)
+// ============================================================================
+
+// Bootstrap
+export * from './bootstrap';
+
+// Platform Interfaces
+export * from './platform/interfaces';
+
+// Adapters
+export * from './adapters';
+
+// Storage Factories
+export * from './adapters/storage.factory';

package/src/interfaces/client-info.interface.ts

@@ -0,0 +1,85 @@
+/**
+ * Client information extracted from HTTP request
+ *
+ * This interface represents metadata about the client making the request,
+ * automatically extracted by nauth-toolkit interceptors.
+ */
+export interface ClientInfo {
+  /**
+   * Client IP address (extracted from X-Forwarded-For, CF-Connecting-IP, etc.)
+   * Automatically handles proxies and load balancers
+   */
+  ipAddress: string;
+
+  /**
+   * User agent string from the request
+   */
+  userAgent: string;
+
+  /**
+   * Device token for trusted device feature
+   *
+   * Extracted from:
+   * - Cookie: `nauth_device_token` (web - httpOnly cookie)
+   * - Header: `X-Device-Token` (mobile - from secure storage)
+   *
+   * This token is server-generated and stored securely by clients.
+   * Used to identify trusted devices for MFA bypass.
+   */
+  deviceToken?: string;
+
+  /**
+   * Optional device name (if provided by client)
+   */
+  deviceName?: string;
+
+  /**
+   * Optional device type (if provided by client)
+   */
+  deviceType?: 'mobile' | 'desktop' | 'tablet';
+
+  /**
+   * Optional IP country (from geolocation, if available)
+   */
+  ipCountry?: string;
+
+  /**
+   * Optional IP city (from geolocation, if available)
+   */
+  ipCity?: string;
+
+  /**
+   * Optional IP latitude (from geolocation, if available)
+   * Used for impossible travel detection
+   */
+  ipLatitude?: number;
+
+  /**
+   * Optional IP longitude (from geolocation, if available)
+   * Used for impossible travel detection
+   */
+  ipLongitude?: number;
+
+  /**
+   * Platform extracted from user agent (e.g., "iOS", "Android", "Windows", "macOS")
+   */
+  platform?: string;
+
+  /**
+   * Browser extracted from user agent (e.g., "Chrome", "Safari", "Firefox")
+   */
+  browser?: string;
+
+  /**
+   * Current session ID (if available from authenticated request)
+   * Extracted from JWT token payload after authentication
+   */
+  sessionId?: number;
+
+  /**
+   * Current user ID (if available from authenticated request)
+   * Extracted from JWT token payload (sub claim) after authentication
+   * Used to identify who performed an action (e.g., for audit trails)
+   */
+  userId?: number;
+}