@nauth-toolkit/core 0.1.0

package/src/exceptions/nauth.exception.ts

@@ -0,0 +1,231 @@
+import { AuthErrorCode } from '../enums/error-codes.enum';
+
+/**
+ * Custom exception for nauth-toolkit
+ *
+ * **Framework-Agnostic Design:**
+ * This exception extends standard `Error`, not `HttpException`, making it
+ * usable in any context:
+ * - HTTP APIs (REST, NestJS)
+ * - WebSocket connections
+ * - GraphQL resolvers
+ * - gRPC services
+ * - Message queue workers
+ * - CLI tools
+ * - Standalone services
+ *
+ * **Consumer Responsibility:**
+ * The consumer application decides how to map these domain exceptions
+ * to their transport layer (HTTP status codes, WebSocket events, etc.)
+ *
+ * **Structured Error Data:**
+ * Provides error code, message, and optional metadata. Consumer can
+ * transform this into any response format needed.
+ *
+ * @example
+ * ```typescript
+ * // Throw domain exception
+ * throw new NAuthException(
+ *   AuthErrorCode.RATE_LIMIT_SMS,
+ *   'Too many verification SMS sent',
+ *   { retryAfter: 3600, maxAttempts: 3 }
+ * );
+ *
+ * // Consumer maps to HTTP (if using HTTP)
+ * catch (error) {
+ *   if (error instanceof NAuthException) {
+ *     const statusCode = this.mapErrorCodeToHttpStatus(error.code);
+ *     return res.status(statusCode).json({
+ *       code: error.code,
+ *       message: error.message,
+ *       details: error.details,
+ *       timestamp: new Date().toISOString()
+ *     });
+ *   }
+ * }
+ *
+ * // Or map to WebSocket
+ * catch (error) {
+ *   if (error instanceof NAuthException) {
+ *     socket.emit('error', {
+ *       code: error.code,
+ *       message: error.message,
+ *       details: error.details
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export class NAuthException extends Error {
+  /**
+   * Error code for programmatic handling
+   */
+  public readonly code: AuthErrorCode;
+
+  /**
+   * Additional error details/metadata
+   */
+  public readonly details?: Record<string, unknown>;
+
+  /**
+   * Timestamp when error was created
+   */
+  public readonly timestamp: string;
+
+  /**
+   * Create a new NAuthException
+   *
+   * @param code - Error code from AuthErrorCode enum
+   * @param message - Human-readable error message
+   * @param details - Optional metadata (retryAfter, validation errors, etc.)
+   *
+   * @example
+   * ```typescript
+   * throw new NAuthException(
+   *   AuthErrorCode.INVALID_CREDENTIALS,
+   *   'Invalid email or password'
+   * );
+   *
+   * throw new NAuthException(
+   *   AuthErrorCode.RATE_LIMIT_SMS,
+   *   'Too many SMS sent',
+   *   { retryAfter: 3600, currentCount: 4 }
+   * );
+   * ```
+   */
+  constructor(code: AuthErrorCode, message: string, details?: Record<string, unknown>) {
+    super(message);
+
+    this.code = code;
+    this.details = details;
+    this.timestamp = new Date().toISOString();
+    this.name = 'NAuthException';
+
+    // Ensure proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, NAuthException.prototype);
+
+    // Capture stack trace (excluding constructor call)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Get the error code
+   *
+   * @returns Error code
+   */
+  getCode(): AuthErrorCode {
+    return this.code;
+  }
+
+  /**
+   * Get error details/metadata
+   *
+   * @returns Error details or undefined
+   */
+  getDetails(): Record<string, unknown> | undefined {
+    return this.details;
+  }
+
+  /**
+   * Check if error is a specific code
+   *
+   * @param code - Error code to check
+   * @returns True if error matches code
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await sendSMS();
+   * } catch (error) {
+   *   if (error instanceof NAuthException && error.isCode(AuthErrorCode.RATE_LIMIT_SMS)) {
+   *     // Handle rate limit specifically
+   *   }
+   * }
+   * ```
+   */
+  isCode(code: AuthErrorCode): boolean {
+    return this.code === code;
+  }
+
+  /**
+   * Serialize error to plain object
+   *
+   * Useful for logging, HTTP responses, or any serialization needs.
+   *
+   * @returns Plain object representation
+   *
+   * @example
+   * ```typescript
+   * catch (error) {
+   *   if (error instanceof NAuthException) {
+   *     console.log(error.toJSON());
+   *     // { code: 'RATE_LIMIT_SMS', message: '...', details: {...}, timestamp: '...' }
+   *   }
+   * }
+   * ```
+   */
+  toJSON(): { code: string; message: string; details?: Record<string, unknown>; timestamp: string } {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      timestamp: this.timestamp,
+    };
+  }
+}
+
+/**
+ * Helper function to map error codes to suggested HTTP status codes
+ *
+ * **Optional** - Consumer can use this or define their own mapping.
+ * Provided as a convenience for HTTP-based applications.
+ *
+ * @param code - Error code
+ * @returns Suggested HTTP status code
+ *
+ * @example
+ * ```typescript
+ * // In NestJS exception filter
+ * catch (exception: NAuthException, host: ArgumentsHost) {
+ *   const statusCode = getHttpStatusForErrorCode(exception.code);
+ *   const response = host.switchToHttp().getResponse();
+ *   response.status(statusCode).json(exception.toJSON());
+ * }
+ * ```
+ */
+export function getHttpStatusForErrorCode(code: AuthErrorCode): number {
+  // Rate limits
+  if (code.startsWith('RATE_LIMIT_')) return 429;
+
+  // Authentication errors
+  if (code.startsWith('AUTH_')) {
+    if (code === AuthErrorCode.ACCOUNT_INACTIVE || code === AuthErrorCode.ACCOUNT_LOCKED) return 403;
+    return 401;
+  }
+
+  // Signup conflicts
+  if (
+    code === AuthErrorCode.EMAIL_EXISTS ||
+    code === AuthErrorCode.USERNAME_EXISTS ||
+    code === AuthErrorCode.PHONE_EXISTS
+  )
+    return 409;
+  if (code === AuthErrorCode.SIGNUP_DISABLED) return 403;
+
+  // Validation errors
+  if (code.startsWith('VALIDATION_') || code.startsWith('INVALID_')) return 400;
+
+  // Not found
+  if (code === AuthErrorCode.NOT_FOUND) return 404;
+
+  // Forbidden
+  if (code === AuthErrorCode.FORBIDDEN) return 403;
+
+  // Server errors
+  if (code === AuthErrorCode.INTERNAL_ERROR || code === AuthErrorCode.SERVICE_UNAVAILABLE) return 500;
+
+  // Default to 400
+  return 400;
+}

package/src/handlers/auth.handler.ts

@@ -0,0 +1,260 @@
+/**
+ * Authentication Handler
+ *
+ * Validates JWT tokens and attaches user to request.
+ *
+ * **Platform-Agnostic:**
+ * This handler operates purely on NAuthRequest interface.
+ * Context is managed by the adapter, not this handler.
+ */
+
+import { Repository } from 'typeorm';
+import {
+  NAuthConfig,
+  NAuthException,
+  AuthErrorCode,
+  resolveDeliveryForRequest,
+  BaseUser,
+  getAccessTokenCookieName,
+  NAuthLogger,
+  ContextStorage,
+  IClientInfo,
+} from '../index';
+import { JwtService, SessionService } from '../internal';
+import { NAuthRequest, NAuthResponse } from '../platform/interfaces';
+
+/**
+ * AuthHandler
+ *
+ * Validates JWT tokens and populates user context.
+ * Performs optional authentication by default (doesn't reject unauthenticated requests).
+ */
+export class AuthHandler {
+  constructor(
+    private jwtService: JwtService,
+    private sessionService: SessionService,
+    private userRepository: Repository<BaseUser>,
+    private config: NAuthConfig,
+    private logger?: NAuthLogger,
+  ) {}
+
+  /**
+   * Handle request - validate token and attach user
+   *
+   * 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> {
+    try {
+      // Skip if route is marked as public
+      if (req.attributes.nauthPublic) {
+        await next();
+        return;
+      }
+
+      const token = this.extractToken(req);
+
+      if (!token) {
+        // No token - continue without authentication (optional auth)
+        await next();
+        return;
+      }
+
+      const validation = await this.jwtService.validateAccessToken(token);
+
+      if (!validation.valid) {
+        this.logger?.debug?.('Invalid token:', validation.error);
+        await next();
+        return;
+      }
+
+      // Validate session
+      const sessionId = validation.payload!.sessionId;
+      const userId = validation.payload!.sub; // Extract userId from token sub claim
+      const session = await this.sessionService.findByIdLight(sessionId);
+
+      if (!session) {
+        this.logger?.debug?.('Session not found:', sessionId);
+        await next();
+        return;
+      }
+
+      const initialVersion = session.version;
+
+      if (session.isRevoked) {
+        this.logger?.warn?.('Session has been revoked:', sessionId);
+        await next();
+        return;
+      }
+
+      if (session.expiresAt < new Date()) {
+        this.logger?.debug?.('Session has expired:', sessionId);
+        await next();
+        return;
+      }
+
+      // Load user
+      const user = await this.userRepository.findOne({
+        select: this.getUserSelectFields(),
+        where: { sub: validation.payload!.sub },
+      });
+
+      if (!user) {
+        this.logger?.warn?.('User not found:', validation.payload!.sub);
+        await next();
+        return;
+      }
+
+      if (!user.isActive) {
+        this.logger?.warn?.('Account is not active:', user.sub);
+        await next();
+        return;
+      }
+
+      // Optimistic locking check - ensure session wasn't modified during request
+      const revalidated = await this.sessionService.findByIdLight(sessionId);
+      if (!revalidated || revalidated.version !== initialVersion || revalidated.isRevoked) {
+        this.logger?.error?.('Session was modified during request - possible security breach');
+        await next();
+        return;
+      }
+
+      // Attach to request attributes
+      req.attributes.user = user;
+      req.attributes.token = validation.payload;
+
+      // Store in ContextStorage for service access
+      ContextStorage.set('CURRENT_USER', user);
+      ContextStorage.set('JWT_PAYLOAD', validation.payload);
+      ContextStorage.set('CURRENT_SESSION', sessionId);
+
+      this.logger?.debug?.(`User ${user.sub} authenticated successfully`);
+
+      // Update CLIENT_INFO with sessionId and userId
+      this.updateClientInfoSessionId(sessionId);
+      this.updateClientInfoUserId(userId);
+
+      await next();
+    } catch (error) {
+      this.logger?.error?.(
+        'Error in auth handler:',
+        error instanceof Error ? error.message : String(error),
+        error instanceof Error ? error.stack : undefined,
+      );
+      await next();
+    }
+  }
+
+  /**
+   * Extract token from request based on delivery mode
+   */
+  private extractToken(req: NAuthRequest): string | null {
+    const method = this.config.tokenDelivery?.method || 'json';
+
+    // Get token from header
+    const authHeader = req.getHeader('authorization');
+    const headerToken = authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : null;
+
+    // Get token from cookie
+    const accessTokenCookieName = getAccessTokenCookieName(this.config);
+    const cookieToken = req.cookies[accessTokenCookieName];
+
+    // Check for route-level override
+    const routeMode = req.attributes.nauthTokenDelivery;
+
+    let effective: 'cookies' | 'json' = 'json';
+
+    if (routeMode) {
+      effective = routeMode;
+    } else if (method === 'hybrid') {
+      // Determine mode based on request characteristics
+      effective = resolveDeliveryForRequest(req.raw, this.config.tokenDelivery?.hybridPolicy);
+    } else {
+      effective = method === 'cookies' ? 'cookies' : 'json';
+    }
+
+    if (effective === 'cookies') {
+      // Cookie mode: Reject if Bearer header present
+      if (headerToken && !cookieToken) {
+        throw new NAuthException(
+          AuthErrorCode.BEARER_NOT_ALLOWED,
+          'Bearer tokens are not allowed in cookie-only path.',
+        );
+      }
+      return cookieToken || null;
+    }
+
+    // JSON mode: Reject if cookie present
+    if (cookieToken && !headerToken) {
+      throw new NAuthException(AuthErrorCode.COOKIES_NOT_ALLOWED, 'Cookie tokens are not allowed in JSON-only path.');
+    }
+    return headerToken || null;
+  }
+
+  /**
+   * Update CLIENT_INFO with session ID from token
+   */
+  private updateClientInfoSessionId(sessionId: string | number): void {
+    const clientInfo = ContextStorage.get<IClientInfo>('CLIENT_INFO');
+    if (clientInfo) {
+      const sessionIdNumber = typeof sessionId === 'number' ? sessionId : parseInt(String(sessionId), 10);
+
+      if (!isNaN(sessionIdNumber) && sessionIdNumber > 0) {
+        clientInfo.sessionId = sessionIdNumber;
+        ContextStorage.set('CLIENT_INFO', clientInfo);
+      }
+    }
+  }
+
+  /**
+   * Update CLIENT_INFO with user ID from token
+   */
+  private updateClientInfoUserId(userId: string | number): void {
+    const clientInfo = ContextStorage.get<IClientInfo>('CLIENT_INFO');
+    if (clientInfo) {
+      const userIdNumber = typeof userId === 'number' ? userId : parseInt(String(userId), 10);
+
+      if (!isNaN(userIdNumber) && userIdNumber > 0) {
+        clientInfo.userId = userIdNumber;
+        ContextStorage.set('CLIENT_INFO', clientInfo);
+      }
+    }
+  }
+
+  /**
+   * Get fields to select when loading user
+   */
+  private getUserSelectFields(): (keyof BaseUser)[] {
+    return [
+      'id',
+      'sub',
+      'username',
+      'firstName',
+      'lastName',
+      'email',
+      'phone',
+      'isEmailVerified',
+      'isPhoneVerified',
+      'isActive',
+      'mustChangePassword',
+      'isLocked',
+      'lockReason',
+      'lockedAt',
+      'lockedUntil',
+      'failedLoginAttempts',
+      'lastFailedLoginAt',
+      'lastLoginAt',
+      'lastLoginIp',
+      'hasSocialAuth',
+      'socialProviders',
+      'mfaEnabled',
+      'mfaMethods',
+      'preferredMfaMethod',
+      'mfaExempt',
+      'mfaExemptReason',
+      'mfaExemptGrantedAt',
+      'metadata',
+      'createdAt',
+      'updatedAt',
+    ] as (keyof BaseUser)[];
+  }
+}

package/src/handlers/client-info.handler.ts

@@ -0,0 +1,101 @@
+/**
+ * Client Info Handler
+ *
+ * Extracts client information (IP, user agent, device info) from NAuthRequest
+ * and stores in AsyncLocalStorage context.
+ *
+ * **Platform-Agnostic:**
+ * This handler operates purely on NAuthRequest interface.
+ * Context initialization is handled by the adapter, not this handler.
+ */
+
+import { ContextStorage, ClientInfoService, IClientInfo, NAuthLogger, getDeviceTokenCookieName } from '../index';
+import { GeoLocationService } from '../internal';
+import { NAuthRequest, NAuthResponse } from '../platform/interfaces';
+
+/**
+ * ClientInfoHandler
+ *
+ * First handler in the chain. Extracts client information and stores it
+ * in the context for downstream handlers and services.
+ */
+export class ClientInfoHandler {
+  constructor(
+    private clientInfoService: ClientInfoService,
+    private geoLocationService?: GeoLocationService,
+    private logger?: NAuthLogger,
+  ) {}
+
+  /**
+   * Handle request - extract and store client info
+   *
+   * Context initialization is handled by the adapter.
+   * This handler assumes context is already available.
+   */
+  public async handle(req: NAuthRequest, res: NAuthResponse, next: () => Promise<void> | void): Promise<void> {
+    try {
+      await this.extractAndStore(req, res);
+    } catch (error) {
+      this.logger?.error?.('Error extracting client info:', error);
+    }
+
+    await next();
+  }
+
+  /**
+   * Extract client information and store in context
+   */
+  private async extractAndStore(req: NAuthRequest, res: NAuthResponse): Promise<void> {
+    // Extract user agent
+    const userAgent = req.getHeader('user-agent') || 'unknown';
+
+    // Parse user agent for device/browser info
+    const parsedUA = this.clientInfoService.parseUserAgent(userAgent);
+
+    // Extract device token from cookie or header
+    // Use default cookie name (nauth_device_token) if config not available
+    const deviceTokenCookieName = getDeviceTokenCookieName();
+    const deviceToken = req.cookies[deviceTokenCookieName] || req.getHeader('x-device-token');
+
+    // Build client info object
+    const clientInfo: IClientInfo = {
+      ipAddress: req.ip,
+      userAgent,
+      deviceToken,
+      deviceName: (req.body.deviceName as string) || parsedUA.deviceName || undefined,
+      deviceType: ((req.body.deviceType as string) || parsedUA.deviceType || undefined) as IClientInfo['deviceType'],
+      platform: parsedUA.platform || undefined,
+      browser: parsedUA.browser || undefined,
+      sessionId: undefined, // Set later by AuthHandler
+      userId: undefined, // Set later by AuthHandler
+      ipCountry: undefined,
+      ipCity: undefined,
+      ipLatitude: undefined,
+      ipLongitude: undefined,
+    };
+
+    // Populate geolocation if service available
+    if (this.geoLocationService && clientInfo.ipAddress && clientInfo.ipAddress !== '0.0.0.0') {
+      try {
+        const geo = await this.geoLocationService.getIpGeolocation(clientInfo.ipAddress);
+        clientInfo.ipCountry = geo.country;
+        clientInfo.ipCity = geo.city;
+        clientInfo.ipLatitude = geo.latitude;
+        clientInfo.ipLongitude = geo.longitude;
+      } catch (error) {
+        // Log error instead of silently failing
+        this.logger?.error?.(
+          `Geolocation lookup failed for IP ${clientInfo.ipAddress}:`,
+          error instanceof Error ? error.message : 'Unknown error',
+        );
+      }
+    }
+
+    // Store in context
+    ContextStorage.set('CLIENT_INFO', clientInfo);
+    ContextStorage.set('HTTP_RESPONSE', res.raw);
+
+    // Also attach to request attributes for handler access
+    req.attributes.clientInfo = clientInfo;
+  }
+}