@nauth-toolkit/core 0.1.0 → 0.1.5

package/src/handlers/csrf.handler.ts

@@ -1,156 +0,0 @@
-/**
- * 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

@@ -1,118 +0,0 @@
-/**
- * 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

@@ -1,118 +0,0 @@
-// ============================================================================
-// 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

@@ -1,85 +0,0 @@
-/**
- * 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;
-}