@nauth-toolkit/core 0.1.0 → 0.1.5

package/src/interfaces/entities.interface.ts

@@ -1,226 +0,0 @@
-/**
- * Entity Interface Contracts
- *
- * These interfaces define the shape of entities without importing concrete implementations.
- * Database packages must implement these interfaces to ensure type safety across the modular architecture.
- *
- * This allows core to maintain strict typing while entities live in separate packages.
- */
-
-/**
- * User Entity Interface
- *
- * Core user authentication record
- */
-export interface IUser {
-  id: number;
-  sub: string;
-  email: string;
-  username: string | null;
-  phone: string | null;
-  firstName: string | null;
-  lastName: string | null;
-  passwordHash: string | null;
-  passwordChangedAt: Date | null;
-  passwordHistory: string[] | null;
-  isEmailVerified: boolean;
-  isPhoneVerified: boolean;
-  isActive: boolean;
-  mustChangePassword: boolean;
-  isLocked: boolean;
-  lockReason: string | null;
-  lockedAt: Date | null;
-  lockedUntil: Date | null;
-  failedLoginAttempts: number;
-  lastFailedLoginAt: Date | null;
-  lastLoginAt: Date | null;
-  lastLoginIp: string | null;
-  hasSocialAuth: boolean;
-  socialProviders: string[] | null;
-  mfaEnabled: boolean;
-  mfaMethods: string[] | null;
-  preferredMfaMethod: string | null;
-  mfaExempt?: boolean;
-  mfaExemptReason?: string | null;
-  mfaExemptGrantedAt?: Date | null;
-  mfaExemptGrantedBy?: string | null;
-  backupCodes: string[] | null;
-  metadata: Record<string, unknown> | null;
-  createdAt: Date;
-  updatedAt: Date;
-  deletedAt: Date | null;
-}
-
-/**
- * Session Entity Interface
- *
- * JWT session tracking
- */
-export interface ISession {
-  id: number;
-  userId: number;
-  accessTokenHash: string;
-  refreshTokenHash: string;
-  tokenFamily: string;
-  deviceId: string | null;
-  deviceName: string | null;
-  deviceType: string | null;
-  deviceFingerprint: string | null;
-  ipAddress: string | null;
-  ipCountry: string | null;
-  ipCity: string | null;
-  ipIsp: string | null;
-  userAgent: string | null;
-  platform: string | null;
-  browser: string | null;
-  authMethod: string | null;
-  isRemembered: boolean;
-  isTrustedDevice: boolean;
-  expiresAt: Date;
-  lastActivityAt: Date | null;
-  isRevoked: boolean;
-  revokedAt: Date | null;
-  revokeReason: string | null;
-  version: number;
-  metadata: Record<string, unknown> | null;
-  createdAt: Date;
-}
-
-/**
- * Login Attempt Entity Interface
- *
- * Failed login tracking
- */
-export interface ILoginAttempt {
-  id: number;
-  email: string | null;
-  userId: number | null;
-  ipAddress: string | null;
-  userAgent: string | null;
-  success: boolean;
-  failureReason: string | null;
-  mfaRequired: boolean;
-  metadata: Record<string, unknown> | null;
-  createdAt: Date;
-}
-
-/**
- * Verification Token Entity Interface
- *
- * Email/phone/password reset tokens
- */
-export interface IVerificationToken {
-  id: number;
-  userId: number;
-  challengeSessionId?: number | null;
-  type: 'email' | 'phone' | 'password_reset';
-  token: string;
-  code: string | null;
-  expiresAt: Date;
-  attempts: number;
-  usedAt: Date | null;
-  ipAddress: string | null;
-  userAgent: string | null;
-  createdAt: Date;
-  // Helper methods (if entity implements them)
-  isExpired?: () => boolean;
-  maxAttemptsExceeded?: (max: number) => boolean;
-}
-
-/**
- * Social Account Entity Interface
- *
- * OAuth provider linkage
- */
-export interface ISocialAccount {
-  id: number;
-  userId: number;
-  provider: string;
-  providerId: string;
-  providerEmail: string | null;
-  linkedAt: Date;
-  lastUsedAt: Date | null;
-  metadata: Record<string, unknown> | null;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-/**
- * Challenge Session Entity Interface
- *
- * Temporary sessions for challenge-response flows
- */
-export interface IChallengeSession {
-  id: number;
-  userId: number;
-  user?: IUser; // Optional relation
-  sessionToken: string;
-  challengeName: string;
-  challengeParameters: Record<string, unknown> | null;
-  metadata?: Record<string, unknown> | null;
-  attempts: number;
-  maxAttempts: number;
-  expiresAt: Date;
-  isCompleted?: boolean;
-  completedAt?: Date | null;
-  ipAddress: string | null;
-  userAgent: string | null;
-  createdAt: Date;
-}
-
-/**
- * MFA Device Entity Interface
- *
- * Multi-factor authentication device registrations
- */
-import { MFADeviceMethod } from '../enums/mfa-method.enum';
-
-export interface IMFADevice {
-  id: number;
-  userId: number;
-  type: MFADeviceMethod;
-  name: string;
-  secret: string | null;
-  credentialId: string | null;
-  publicKey: string | null;
-  counter: number | null;
-  transports: string[] | null;
-  phoneNumber?: string | null; // For SMS MFA
-  email?: string | null; // For Email MFA
-  isPrimary?: boolean; // Primary device flag
-  isActive: boolean;
-  lastUsedAt: Date | null;
-  createdAt: Date;
-}
-
-/**
- * Authentication Audit Entity Interface
- *
- * Audit trail record for authentication and security events
- */
-export interface IAuthAudit {
-  id: number;
-  userId: number;
-  eventType: string;
-  eventStatus: 'SUCCESS' | 'FAILURE' | 'INFO' | 'SUSPICIOUS';
-  riskFactor?: number | null;
-  riskFactors?: string[] | null; // Stored as string[] in DB, but should use RiskFactor enum values
-  adaptiveMfaTriggered?: boolean | null;
-  ipAddress?: string | null;
-  ipCountry?: string | null;
-  ipCity?: string | null;
-  userAgent?: string | null;
-  platform?: string | null;
-  browser?: string | null;
-  deviceId?: string | null;
-  deviceName?: string | null;
-  deviceType?: string | null;
-  sessionId?: number | null;
-  challengeSessionId?: number | null;
-  authMethod?: string | null;
-  performedBy?: string | null;
-  reason?: string | null;
-  description?: string | null;
-  metadata?: Record<string, unknown> | null;
-  createdAt: Date;
-}

package/src/interfaces/index.ts

@@ -1,15 +0,0 @@
-export * from './config.interface';
-export * from './entities.interface';
-export * from './logger.interface';
-export * from './mfa-provider.interface';
-export * from './oauth.interface';
-export * from './provider.interface';
-// NOTE: SMS provider configurations moved to their respective packages
-// Import from @nauth-toolkit/sms-aws-sns, @nauth-toolkit/sms-twilio, etc.
-// export * from './sms-config.interface'; // Deprecated - kept for backward compatibility notes only
-export * from './social-auth-provider.interface';
-export * from './storage-adapter.interface';
-export * from './template.interface';
-export * from './token-verifier.interface';
-// Note: ClientInfo interface is exported directly from core/index.ts as IClientInfo
-// to avoid naming conflict with ClientInfo decorator

package/src/interfaces/logger.interface.ts

@@ -1,283 +0,0 @@
-/**
- * Logging Provider Interface
- *
- * Allows users to plug in their own logging solution (Winston, Pino, etc.)
- * while nauth-toolkit automatically redacts PII (Personally Identifiable Information).
- *
- * Key features:
- * - Standard log levels (debug, log, warn, error)
- * - Automatic PII redaction (emails, passwords, tokens, IPs)
- * - Structured logging support
- * - Contextual logging with metadata
- *
- * @example
- * ```typescript
- * // Use default NestJS logger
- * AuthModule.forRoot({
- *   logger: new NestJsLoggerAdapter(),
- * })
- *
- * // Use Winston
- * AuthModule.forRoot({
- *   logger: new WinstonLoggerAdapter(winstonInstance),
- * })
- *
- * // Use Pino
- * AuthModule.forRoot({
- *   logger: new PinoLoggerAdapter(pinoInstance),
- * })
- * ```
- */
-
-/**
- * Log Level
- *
- * Standard logging levels in order of severity
- */
-export enum LogLevel {
-  DEBUG = 'debug',
-  LOG = 'log',
-  INFO = 'info',
-  WARN = 'warn',
-  ERROR = 'error',
-}
-
-/**
- * Log Metadata
- *
- * Additional context for log entries.
- * All values are automatically redacted if they contain PII.
- */
-export interface LogMetadata {
-  /**
-   * User ID (non-PII, safe to log)
-   */
-  userId?: string;
-
-  /**
-   * Session ID (non-PII, safe to log)
-   */
-  sessionId?: string;
-
-  /**
-   * Request ID for tracing
-   */
-  requestId?: string;
-
-  /**
-   * Event type (e.g., 'login', 'signup', 'password_change')
-   */
-  event?: string;
-
-  /**
-   * IP address (will be redacted to first 3 octets)
-   */
-  ipAddress?: string;
-
-  /**
-   * Device information (non-PII)
-   */
-  deviceType?: string;
-
-  /**
-   * Error details
-   */
-  error?: Error | string;
-
-  /**
-   * Duration in milliseconds (for performance tracking)
-   */
-  duration?: number;
-
-  /**
-   * Additional custom metadata
-   */
-  [key: string]: unknown;
-}
-
-/**
- * Logger Provider Interface
- *
- * Contract that all logging providers must implement.
- * nauth-toolkit will call these methods and automatically redact PII.
- *
- * @example
- * ```typescript
- * class CustomLogger implements LoggerProvider {
- *   debug(message: string, metadata?: LogMetadata): void {
- *     myLogger.debug(message, metadata);
- *   }
- *
- *   log(message: string, metadata?: LogMetadata): void {
- *     myLogger.info(message, metadata);
- *   }
- *
- *   warn(message: string, metadata?: LogMetadata): void {
- *     myLogger.warn(message, metadata);
- *   }
- *
- *   error(message: string, metadata?: LogMetadata): void {
- *     myLogger.error(message, metadata);
- *   }
- * }
- * ```
- */
-export interface LoggerProvider {
-  /**
-   * Log debug message (lowest priority)
-   *
-   * Used for detailed debugging information.
-   *
-   * @param message - Log message
-   * @param metadata - Additional context (PII will be redacted)
-   */
-  debug(message: string, metadata?: LogMetadata): void;
-
-  /**
-   * Log informational message
-   *
-   * Used for general informational messages about system operation.
-   *
-   * @param message - Log message
-   * @param metadata - Additional context (PII will be redacted)
-   */
-  log(message: string, metadata?: LogMetadata): void;
-
-  /**
-   * Log warning message
-   *
-   * Used for potentially harmful situations.
-   *
-   * @param message - Log message
-   * @param metadata - Additional context (PII will be redacted)
-   */
-  warn(message: string, metadata?: LogMetadata): void;
-
-  /**
-   * Log error message (highest priority)
-   *
-   * Used for error events that might still allow the application to continue.
-   *
-   * @param message - Log message
-   * @param metadata - Additional context (PII will be redacted)
-   */
-  error(message: string, metadata?: LogMetadata): void;
-}
-
-/**
- * PII Redaction Options
- *
- * Configure what PII should be redacted from logs
- */
-export interface PiiRedactionOptions {
-  /**
-   * Redact email addresses
-   * @default true
-   *
-   * Example: `user@example.com` → `u***@***.com`
-   */
-  redactEmails?: boolean;
-
-  /**
-   * Redact full IP addresses (keep first 3 octets)
-   * @default true
-   *
-   * Example: `192.168.1.100` → `192.168.1.***`
-   */
-  redactIpAddresses?: boolean;
-
-  /**
-   * Redact tokens and secrets
-   * @default true
-   *
-   * Example: `eyJhbGciOiJIUzI1...` → `eyJ***...***`
-   */
-  redactTokens?: boolean;
-
-  /**
-   * Redact passwords and password hashes
-   * @default true
-   *
-   * Never log passwords! Always redacted.
-   */
-  redactPasswords?: boolean;
-
-  /**
-   * Redact phone numbers
-   * @default true
-   *
-   * Example: `+1234567890` → `+123***7890`
-   */
-  redactPhoneNumbers?: boolean;
-
-  /**
-   * Redact names (firstName, lastName)
-   * @default true
-   *
-   * Example: `John Doe` → `J*** D***`
-   */
-  redactNames?: boolean;
-
-  /**
-   * Custom fields to redact
-   *
-   * Field names that should be fully redacted if present in metadata.
-   *
-   * @default ['ssn', 'creditCard', 'bankAccount']
-   */
-  customRedactionFields?: string[];
-}
-
-/**
- * Logger Configuration
- *
- * Configuration for the logging system
- */
-export interface LoggerConfig {
-  /**
-   * Logger provider instance
-   *
-   * @default NestJsLoggerAdapter (built-in)
-   */
-  provider?: LoggerProvider;
-
-  /**
-   * Minimum log level to output
-   *
-   * @default LogLevel.LOG
-   */
-  level?: LogLevel;
-
-  /**
-   * Enable PII redaction
-   *
-   * @default true (always enabled in production)
-   */
-  enablePiiRedaction?: boolean;
-
-  /**
-   * PII redaction options
-   */
-  piiRedactionOptions?: PiiRedactionOptions;
-
-  /**
-   * Log authentication events
-   *
-   * @default true
-   */
-  logAuthEvents?: boolean;
-
-  /**
-   * Log security events (lockouts, suspicious activity)
-   *
-   * @default true
-   */
-  logSecurityEvents?: boolean;
-
-  /**
-   * Log performance metrics
-   *
-   * @default false
-   */
-  logPerformance?: boolean;
-}

package/src/interfaces/mfa-provider.interface.ts

@@ -1,154 +0,0 @@
-import { IUser } from './entities.interface';
-
-/**
- * MFA Provider Service Interface
- *
- * Defines the contract that all MFA provider services must implement.
- * Each MFA method (TOTP, SMS, Passkey) is a separate provider that extends
- * the base class and implements this interface.
- *
- * Provider-specific types (e.g., SetupTOTPResponseDTO) are defined in each
- * provider package, not in core, to maintain proper separation of concerns.
- *
- * @example
- * ```typescript
- * @Injectable()
- * export class TOTPMFAProviderService extends BaseMFAProviderService implements IMFAProviderService {
- *   readonly methodName = 'totp';
- *
- *   async setup(user: IUser): Promise<unknown> {
- *     // TOTP-specific setup logic
- *   }
- *
- *   async verify(user: IUser, code: string, deviceId?: number): Promise<boolean> {
- *     // TOTP verification logic
- *   }
- * }
- * ```
- */
-export interface IMFAProviderService {
-  /**
-   * Unique method name for this MFA provider
-   * Examples: 'totp', 'sms', 'passkey'
-   */
-  readonly methodName: string;
-
-  /**
-   * Check if this MFA method is allowed by configuration
-   *
-   * @returns True if method is allowed
-   */
-  isMethodAllowed(): boolean;
-
-  /**
-   * Setup MFA device for user
-   *
-   * Initiates the setup process for this MFA method.
-   * Provider-specific setup data is returned.
-   *
-   * @param user - User setting up MFA
-   * @returns Provider-specific setup data (e.g., QR code for TOTP, options for Passkey)
-   * @throws {NAuthException} If method is not allowed or setup fails
-   *
-   * @example
-   * ```typescript
-   * // TOTP provider returns { secret, qrCode, manualEntryKey }
-   * const setupData = await totpProvider.setup(user);
-   *
-   * // Passkey provider returns WebAuthn registration options
-   * const options = await passkeyProvider.setup(user);
-   * ```
-   */
-  setup(user: IUser, setupData?: unknown): Promise<unknown>;
-
-  /**
-   * Verify and complete MFA setup
-   *
-   * Validates the verification code/credential and creates the MFA device.
-   *
-   * @param user - User completing setup
-   * @param verificationData - Provider-specific verification data (code, credential, etc.)
-   * @param deviceName - Optional device name
-   * @returns Created MFA device ID
-   * @throws {NAuthException} If verification fails
-   *
-   * @example
-   * ```typescript
-   * // TOTP: verificationData = { secret, code }
-   * const deviceId = await totpProvider.verifySetup(user, { secret: '...', code: '123456' });
-   *
-   * // SMS: verificationData = { phoneNumber, code }
-   * const deviceId = await smsProvider.verifySetup(user, { phoneNumber: '+1234567890', code: '123456' });
-   *
-   * // Passkey: verificationData = { credential, challenge }
-   * const deviceId = await passkeyProvider.verifySetup(user, { credential: {...}, challenge: '...' });
-   * ```
-   */
-  verifySetup(user: IUser, verificationData: unknown, deviceName?: string): Promise<number>;
-
-  /**
-   * Verify MFA code/credential during authentication
-   *
-   * Validates the MFA code or credential for an existing device.
-   *
-   * @param user - User being authenticated
-   * @param code - MFA code or credential (provider-specific)
-   * @param deviceId - Optional device ID to verify against (if not provided, finds active device)
-   * @returns True if verification succeeds
-   * @throws {NAuthException} If device not found or verification fails
-   *
-   * @example
-   * ```typescript
-   * // TOTP: code = '123456'
-   * const isValid = await totpProvider.verify(user, '123456');
-   *
-   * // SMS: code = '123456'
-   * const isValid = await smsProvider.verify(user, '123456');
-   *
-   * // Passkey: code = { credential: {...}, challenge: '...' }
-   * const isValid = await passkeyProvider.verify(user, { credential: {...}, challenge: '...' });
-   * ```
-   */
-  verify(user: IUser, code: unknown, deviceId?: number): Promise<boolean>;
-
-  /**
-   * Send verification code/challenge for authentication
-   *
-   * Used during login to send SMS code or generate passkey challenge.
-   * Not applicable for TOTP (user generates code locally).
-   *
-   * @param user - User requesting verification
-   * @returns Provider-specific challenge data (e.g., masked phone for SMS, WebAuthn options for Passkey)
-   * @throws {NAuthException} If no device registered or send fails
-   *
-   * @example
-   * ```typescript
-   * // SMS: returns masked phone number
-   * const maskedPhone = await smsProvider.sendChallenge(user); // '***-***-1234'
-   *
-   * // Passkey: returns WebAuthn authentication options
-   * const options = await passkeyProvider.sendChallenge(user); // { challenge: '...', ... }
-   * ```
-   */
-  sendChallenge?(user: IUser): Promise<unknown>; // Optional - only providers like SMS need it
-
-  /**
-   * Generate backup codes for user
-   *
-   * Creates single-use recovery codes that can be used when MFA devices are unavailable.
-   * Provided by BaseMFAProviderService for all providers.
-   *
-   * @param user - User to generate codes for
-   * @returns Generated backup codes (plain text - shown only once)
-   *
-   * @example
-   * ```typescript
-   * const codes = await provider.generateBackupCodes?.(user);
-   * // Returns: ['ABC12345', 'DEF67890', ...]
-   * ```
-   */
-  generateBackupCodes?(user: IUser): Promise<string[]>; // Optional - provided by BaseMFAProviderService
-}
-
-// Helper type to check if a provider implements sendChallenge
-export type MFAProviderWithChallenge = IMFAProviderService & Required<Pick<IMFAProviderService, 'sendChallenge'>>;