@nauth-toolkit/core 0.1.0 → 0.1.5

package/src/exceptions/nauth.exception.ts

@@ -1,231 +0,0 @@
-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

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

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