@nauth-toolkit/core 0.1.0

package/src/interfaces/entities.interface.ts

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

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

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

@@ -0,0 +1,154 @@
+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'>>;