@nauth-toolkit/core 0.1.0 → 0.1.3

package/src/services/phone-verification.service.ts

@@ -1,751 +0,0 @@
-import { Repository, IsNull } from 'typeorm';
-import { IUser, IVerificationToken } from '../interfaces/entities.interface';
-import { BaseVerificationToken, BaseUser } from '../entities';
-import { SMSProvider } from '../interfaces/provider.interface';
-import { StorageAdapter } from '../interfaces/storage-adapter.interface';
-import { NAuthConfig } from '../interfaces/config.interface';
-import { ClientInfoService } from './client-info.service';
-import { InternalAuthAuditService as AuthAuditService } from './auth-audit.service';
-import { AuthAuditEventType } from '../enums/auth-audit-event-type.enum';
-import { NAuthException } from '../exceptions/nauth.exception';
-import { AuthErrorCode } from '../enums/error-codes.enum';
-import { NAuthLogger } from '../utils/nauth-logger';
-import {
-  SendVerificationSMSDTO,
-  SendVerificationSMSResponseDTO,
-  VerifyPhoneWithCodeDTO,
-  VerifyPhoneResponseDTO,
-  ResendVerificationSMSDTO,
-  ResendVerificationSMSResponseDTO,
-} from '../dto/verify-phone.dto';
-import { VerifyPhoneWithCodeBySubDTO } from '../dto/verify-phone-by-sub.dto';
-import * as crypto from 'crypto';
-
-/**
- * Phone Verification Service (Core)
- *
- * Database-agnostic phone verification workflow with provider-driven SMS delivery.
- *
- * WHY: Keeps core business logic independent of database and SMS vendors. Databases are
- * injected via repository tokens and SMS via an `SMSProvider` adapter so consumers
- * can plug in Postgres, MySQL, or any SMS provider without code changes.
- *
- * @example
- * ```typescript
- * // Send OTP
- * const tokenId = await phoneVerificationService.sendVerificationSMS('user-sub');
- *
- * // Verify by sub
- * await phoneVerificationService.verifyPhoneWithCodeBySub('user-sub', '123456');
- *
- * // Resend
- * await phoneVerificationService.resendVerificationSMS('user-sub');
- * ```
- */
-export class PhoneVerificationService {
-  constructor(
-    private readonly verificationTokenRepo: Repository<BaseVerificationToken>,
-    private readonly userRepo: Repository<BaseUser>,
-    private readonly smsProvider: SMSProvider,
-    private readonly storageAdapter: StorageAdapter,
-    private readonly config: NAuthConfig,
-    private readonly clientInfoService: ClientInfoService,
-    private readonly logger: NAuthLogger,
-    private readonly auditService?: AuthAuditService, // Optional - audit trail service (enabled via config.auditLogs.enabled)
-  ) {}
-
-  /**
-   * Send verification SMS to user identified by `sub`.
-   * Applies rate limits and resend delay, stores hashed token + OTP, and sends via SMS provider.
-   *
-   * @param dto - Request DTO containing sub and skipAlreadyVerifiedCheck
-   * @returns Response DTO with verification token ID
-   * @throws {NAuthException} RATE_LIMIT_SMS | NOT_FOUND | PHONE_REQUIRED | ALREADY_VERIFIED | RATE_LIMIT_RESEND
-   */
-  async sendVerificationSMS(dto: SendVerificationSMSDTO): Promise<SendVerificationSMSResponseDTO> {
-    const { sub, skipAlreadyVerifiedCheck = true, challengeSessionId } = dto;
-    const rateLimitKey = `phone-verification:${sub}`;
-
-    // Get rate limit configuration from config (moved to signup.phoneVerification)
-    const rateLimitMax = this.config.signup?.phoneVerification?.rateLimitMax || 3;
-    const rateLimitWindow = this.config.signup?.phoneVerification?.rateLimitWindow || 3600; // 1 hour in seconds
-
-    // Check if key exists and has valid TTL (not expired)
-    const ttlBefore = await this.storageAdapter.ttl(rateLimitKey);
-    // Window is expired if: key doesn't exist (-1), expired (<0), or TTL is longer than configured window (config changed)
-    const isWindowExpired = ttlBefore === -1 || ttlBefore < 0 || ttlBefore > rateLimitWindow;
-
-    // If TTL is longer than configured window (config changed), delete the old key to reset it
-    // This ensures the new window uses the current rateLimitWindow instead of preserving old expiry
-    if (ttlBefore > rateLimitWindow) {
-      await this.storageAdapter.del(rateLimitKey);
-    }
-
-    // Increment counter (will reset to 1 if key expired or doesn't exist)
-    // Pass TTL so new records are created with correct expiry immediately
-    const currentCount = await this.storageAdapter.incr(rateLimitKey, isWindowExpired ? rateLimitWindow : undefined);
-
-    // If we created a new window, log it
-    if (isWindowExpired && currentCount === 1) {
-      this.logger?.debug?.(
-        `Rate limit window reset for phone verification: sub=${sub}, window=${rateLimitWindow}s, max=${rateLimitMax}`,
-      );
-    }
-
-    // Get actual TTL after setting expiry (for error message)
-    const actualTtl = await this.storageAdapter.ttl(rateLimitKey);
-
-    this.logger?.debug?.(
-      `Phone verification rate limit check: sub=${sub}, count=${currentCount}/${rateLimitMax}, ttl=${actualTtl}s`,
-    );
-
-    if (currentCount > rateLimitMax) {
-      this.logger?.warn?.(
-        `SMS rate limit exceeded: sub=${sub}, count=${currentCount}, max=${rateLimitMax}, retryAfter=${actualTtl}s`,
-      );
-      throw new NAuthException(
-        AuthErrorCode.RATE_LIMIT_SMS,
-        `Too many verification SMS sent. Please try again in ${actualTtl > 0 ? actualTtl : rateLimitWindow} seconds`,
-        {
-          retryAfter: actualTtl > 0 ? actualTtl : rateLimitWindow,
-          currentCount,
-          maxAttempts: rateLimitMax,
-        },
-      );
-    }
-
-    // Load user by external identifier
-    const user = (await this.userRepo.findOne({ where: { sub } })) as IUser | null;
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
-    }
-    if (!user.phone) {
-      throw new NAuthException(AuthErrorCode.PHONE_REQUIRED, 'No phone number associated with this account');
-    }
-    // Only check "already verified" if not skipping (skip for MFA contexts where codes are needed even if phone is verified)
-    if (!skipAlreadyVerifiedCheck && user.isPhoneVerified) {
-      throw new NAuthException(AuthErrorCode.ALREADY_VERIFIED, 'Phone already verified');
-    }
-
-    // Enforce resend delay to prevent abuse
-    const resendDelay = this.config.signup?.phoneVerification?.resendDelay ?? 60;
-    const lastToken = (await this.verificationTokenRepo.findOne({
-      where: { userId: user.id, type: 'phone' },
-      order: { createdAt: 'DESC' },
-    })) as IVerificationToken | null;
-    if (lastToken) {
-      const secondsSinceLastSend = (Date.now() - lastToken.createdAt.getTime()) / 1000;
-      if (secondsSinceLastSend < resendDelay) {
-        const waitSeconds = Math.ceil(resendDelay - secondsSinceLastSend);
-        throw new NAuthException(
-          AuthErrorCode.RATE_LIMIT_RESEND,
-          `Please wait ${waitSeconds} seconds before requesting another code`,
-          {
-            retryAfter: waitSeconds,
-            resendDelay,
-          },
-        );
-      }
-    }
-
-    // Invalidate existing unused tokens for this user
-    await this.verificationTokenRepo.update(
-      { userId: user.id, type: 'phone', usedAt: IsNull() },
-      { usedAt: new Date() },
-    );
-
-    // Generate OTP and hashed token
-    const code = this.generateCode();
-    const token = this.generateToken();
-    const tokenHash = this.hashToken(token);
-
-    // Capture client info for auditability
-    const clientInfo = this.clientInfoService.get();
-    const { ipAddress, userAgent } = clientInfo;
-
-    const verificationToken = this.verificationTokenRepo.create({
-      userId: user.id,
-      challengeSessionId: challengeSessionId ?? null, // Link to challenge session if provided
-      type: 'phone',
-      token: tokenHash,
-      code,
-      expiresAt: new Date(Date.now() + (this.config.signup?.phoneVerification?.expiresIn || 300) * 1000),
-      attempts: 0,
-      ipAddress,
-      userAgent,
-    });
-
-    const saved = (await this.verificationTokenRepo.save(verificationToken)) as unknown as IVerificationToken;
-
-    this.logger?.log?.(
-      `SMS token created: sub=${sub}, tokenId=${saved.id}, code=${code}, codeType=${typeof code}, userId=${user.id}, usedAt=${saved.usedAt || 'null'}`,
-    );
-
-    await this.smsProvider.sendOTP(user.phone, code);
-    this.logger?.log?.(
-      `SMS verification code sent: sub=${sub}, tokenId=${saved.id}, phone=${this.maskPhone(user.phone)}`,
-    );
-
-    // ============================================================================
-    // Audit: Record phone verification request
-    // ============================================================================
-    try {
-      await this.auditService?.recordEvent({
-        userId: user.id,
-        eventType: AuthAuditEventType.PHONE_VERIFICATION_REQUESTED,
-        eventStatus: 'INFO',
-        metadata: {
-          // Client info automatically included from context
-          verificationTokenId: saved.id,
-          phone: this.maskPhone(user.phone),
-        },
-      });
-    } catch (auditError) {
-      // Non-blocking: Log but continue
-      const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-      this.logger?.error?.(`Failed to record PHONE_VERIFICATION_REQUESTED audit event: ${errorMessage}`, {
-        error: auditError,
-        userId: user.id,
-      });
-    }
-
-    return { tokenId: saved.id };
-  }
-
-  /**
-   * Verify phone by phone number and code.
-   * Handles duplicate phone numbers by selecting the token whose user matches the phone provided.
-   *
-   * @param dto - Request DTO containing phone and code
-   * @returns Response DTO with success message
-   * @throws {NAuthException} VERIFICATION_CODE_INVALID | VERIFICATION_CODE_EXPIRED | VERIFICATION_TOO_MANY_ATTEMPTS
-   */
-  async verifyPhoneWithCode(dto: VerifyPhoneWithCodeDTO): Promise<VerifyPhoneResponseDTO> {
-    const { phone, code, challengeSessionId } = dto;
-    // Find all unused tokens matching the code and type
-    // If challengeSessionId is provided, ensure token belongs to specific session
-    const whereClause = {
-      type: 'phone' as const,
-      code,
-      usedAt: IsNull(),
-      ...(challengeSessionId !== undefined && { challengeSessionId }), // Include if provided
-    };
-
-    const candidateTokens = (await this.verificationTokenRepo.find({
-      where: whereClause,
-      order: { createdAt: 'DESC' },
-    })) as unknown as IVerificationToken[];
-
-    // Resolve the token whose user has the given phone
-    let matched: { token: IVerificationToken; user: IUser } | null = null;
-    for (const token of candidateTokens) {
-      const user = (await this.userRepo.findOne({ where: { id: token.userId } })) as IUser | null;
-      if (user && user.phone === phone) {
-        matched = { token, user };
-        break;
-      }
-    }
-
-    if (!matched) {
-      throw new NAuthException(AuthErrorCode.VERIFICATION_CODE_INVALID, 'Invalid or expired verification code');
-    }
-
-    const { token, user } = matched;
-
-    // Get verification attempt rate limit configuration from config
-    const maxAttemptsPerUser = this.config.signup?.phoneVerification?.maxAttemptsPerUser ?? 10;
-    const maxAttemptsPerIP = this.config.signup?.phoneVerification?.maxAttemptsPerIP ?? 20;
-    const attemptWindow = this.config.signup?.phoneVerification?.attemptWindow ?? 3600; // 1 hour
-
-    // Rate limit verification attempts per user (not just per token)
-    const userRateLimitKey = `verify-attempts:user:${user.id}`;
-    const userAttempts = await this.storageAdapter.incr(userRateLimitKey);
-
-    if (userAttempts === 1) {
-      await this.storageAdapter.expire(userRateLimitKey, attemptWindow);
-    }
-
-    if (userAttempts > maxAttemptsPerUser) {
-      throw new NAuthException(
-        AuthErrorCode.VERIFICATION_TOO_MANY_ATTEMPTS,
-        'Too many verification attempts. Please try again later.',
-      );
-    }
-
-    // Also rate limit by IP
-    const clientInfo = this.clientInfoService.get();
-    if (clientInfo.ipAddress) {
-      const ipRateLimitKey = `verify-attempts:ip:${clientInfo.ipAddress}`;
-      const ipAttempts = await this.storageAdapter.incr(ipRateLimitKey);
-
-      if (ipAttempts === 1) {
-        await this.storageAdapter.expire(ipRateLimitKey, attemptWindow);
-      }
-
-      if (ipAttempts > maxAttemptsPerIP) {
-        throw new NAuthException(
-          AuthErrorCode.VERIFICATION_TOO_MANY_ATTEMPTS,
-          'Too many verification attempts from this IP. Please try again later.',
-        );
-      }
-    }
-
-    // Expiry check (use entity method if provided)
-    const isExpired =
-      typeof token.isExpired === 'function' ? !!token.isExpired() : token.expiresAt.getTime() <= Date.now();
-    if (isExpired) {
-      throw new NAuthException(AuthErrorCode.VERIFICATION_CODE_EXPIRED, 'Verification code has expired');
-    }
-
-    // Attempts check (use entity method if provided)
-    const maxAttempts = this.config.signup?.phoneVerification?.maxAttempts ?? 3;
-    const tooManyAttempts =
-      typeof token.maxAttemptsExceeded === 'function'
-        ? !!token.maxAttemptsExceeded(maxAttempts)
-        : token.attempts >= maxAttempts;
-    if (tooManyAttempts) {
-      throw new NAuthException(
-        AuthErrorCode.VERIFICATION_TOO_MANY_ATTEMPTS,
-        'Too many failed attempts. Request a new code.',
-        {
-          maxAttempts,
-          currentAttempts: token.attempts,
-        },
-      );
-    }
-
-    // Increment attempts even on success to prevent reuse by race
-    token.attempts += 1;
-    if (token.code !== code) {
-      await this.verificationTokenRepo.save(token);
-      this.logger?.debug?.(
-        `Phone verification failed: phone=${this.maskPhone(phone)}, attempts=${token.attempts}/${maxAttempts}`,
-      );
-
-      // ============================================================================
-      // Audit: Record phone verification failure
-      // ============================================================================
-      try {
-        await this.auditService?.recordEvent({
-          userId: user.id,
-          eventType: AuthAuditEventType.PHONE_VERIFICATION_FAILED,
-          eventStatus: 'FAILURE',
-          reason: 'invalid_code',
-          // Client info automatically included from context
-          description: 'Invalid verification code provided',
-          metadata: {
-            verificationTokenId: token.id,
-            attempts: token.attempts,
-            phone: this.maskPhone(phone),
-          },
-        });
-      } catch (auditError) {
-        // Non-blocking: Log but continue
-        const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-        this.logger?.error?.(`Failed to record PHONE_VERIFICATION_FAILED audit event: ${errorMessage}`, {
-          error: auditError,
-          userId: user.id,
-        });
-      }
-
-      throw new NAuthException(AuthErrorCode.VERIFICATION_CODE_INVALID, 'Invalid verification code', {
-        attemptsRemaining: Math.max(0, maxAttempts - token.attempts),
-      });
-    }
-
-    // Mark token used
-    token.usedAt = new Date();
-    await this.verificationTokenRepo.save(token);
-
-    // Update user flags
-    await this.userRepo.update(user.id, {
-      isPhoneVerified: true,
-      isActive: true,
-    });
-
-    this.logger?.log?.(`Phone verification successful: userId=${user.id}, phone=${this.maskPhone(phone)}`);
-
-    // ============================================================================
-    // Audit: Record phone verification success
-    // ============================================================================
-    try {
-      // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
-      // Note: ClientInfoService is used transparently by AuditService
-      await this.auditService?.recordEvent({
-        userId: user.id,
-        eventType: AuthAuditEventType.PHONE_VERIFIED,
-        eventStatus: 'SUCCESS',
-        metadata: {
-          // Client info automatically included from context
-          verificationTokenId: token.id,
-          verificationMethod: 'code',
-          phone: this.maskPhone(phone),
-        },
-      });
-    } catch (auditError) {
-      // Non-blocking: Log but continue
-      const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-      this.logger?.error?.(`Failed to record PHONE_VERIFIED audit event: ${errorMessage}`, {
-        error: auditError,
-        userId: user.id,
-      });
-    }
-
-    return { message: 'Phone verified successfully. Please log in to continue.' };
-  }
-
-  /**
-   * Verify phone by user sub and code.
-   *
-   * @param dto - Request DTO containing sub and code
-   * @returns Response DTO with success message
-   */
-  async verifyPhoneWithCodeBySub(dto: VerifyPhoneWithCodeBySubDTO): Promise<VerifyPhoneResponseDTO> {
-    const { sub, code, challengeSessionId } = dto;
-    // Load user to get current phone verification status
-    // This ensures we have the latest state from the database
-    const user = (await this.userRepo.findOne({ where: { sub } })) as IUser | null;
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
-    }
-    if (!user.phone) {
-      throw new NAuthException(AuthErrorCode.PHONE_REQUIRED, 'No phone number associated with this account');
-    }
-
-    // Store initial verification status to avoid unnecessary updates
-    const wasPhoneVerified = Boolean(user.isPhoneVerified);
-
-    // ============================================================================
-    // Security: Rate limit configuration
-    // IP-based rate limiting applies only to INVALID attempts to prevent brute force
-    // Valid codes should not be blocked by IP rate limits
-    // ============================================================================
-    const maxAttemptsPerIP = this.config.signup?.phoneVerification?.maxAttemptsPerIP ?? 20;
-    const attemptWindow = this.config.signup?.phoneVerification?.attemptWindow ?? 3600; // 1 hour
-    const clientInfo = this.clientInfoService.get();
-
-    // Find verification token
-    // Query for unused tokens matching the code (order by newest first)
-    // Ensure code is a string (database stores as varchar/string)
-    // TypeORM may receive code as number from JSON, so convert to string for query
-    const codeString = String(code);
-    this.logger?.log?.(
-      `Looking for verification token: sub=${sub}, code=${codeString}, codeType=${typeof code}, userId=${user.id}`,
-    );
-    // If challengeSessionId is provided, ensure token belongs to specific session
-    const whereClause = {
-      userId: user.id,
-      type: 'phone' as const,
-      code: codeString,
-      usedAt: IsNull(),
-      ...(challengeSessionId !== undefined && { challengeSessionId }), // Include if provided
-    };
-
-    const verificationToken = (await this.verificationTokenRepo.findOne({
-      where: whereClause,
-      order: { createdAt: 'DESC' },
-    })) as IVerificationToken | null;
-
-    // ============================================================================
-    // Security: Increment IP rate limit for invalid attempts only
-    // This prevents brute force attacks while allowing valid codes through
-    // ============================================================================
-    const incrementIPRateLimit = async (): Promise<void> => {
-      if (clientInfo.ipAddress) {
-        const ipRateLimitKey = `verify-attempts:ip:${clientInfo.ipAddress}`;
-        const ipAttempts = await this.storageAdapter.incr(ipRateLimitKey);
-
-        if (ipAttempts === 1) {
-          await this.storageAdapter.expire(ipRateLimitKey, attemptWindow);
-        }
-
-        if (ipAttempts > maxAttemptsPerIP) {
-          throw new NAuthException(
-            AuthErrorCode.VERIFICATION_TOO_MANY_ATTEMPTS,
-            'Too many verification attempts from this IP. Please try again later.',
-          );
-        }
-      }
-    };
-
-    if (!verificationToken) {
-      this.logger?.warn?.(
-        `Phone verification token not found: sub=${sub}, code=${codeString}, originalCodeType=${typeof code}, userId=${user.id}`,
-      );
-      // Invalid attempt - increment IP rate limit
-      await incrementIPRateLimit();
-      throw new NAuthException(AuthErrorCode.VERIFICATION_CODE_INVALID, 'Invalid or expired verification code');
-    }
-
-    const isExpired =
-      typeof verificationToken.isExpired === 'function'
-        ? !!verificationToken.isExpired()
-        : verificationToken.expiresAt.getTime() <= Date.now();
-    if (isExpired) {
-      // Expired token - increment IP rate limit
-      await incrementIPRateLimit();
-      throw new NAuthException(AuthErrorCode.VERIFICATION_CODE_EXPIRED, 'Verification code has expired');
-    }
-
-    const maxAttempts = this.config.signup?.phoneVerification?.maxAttempts ?? 3;
-    const tooManyAttempts =
-      typeof verificationToken.maxAttemptsExceeded === 'function'
-        ? !!verificationToken.maxAttemptsExceeded(maxAttempts)
-        : verificationToken.attempts >= maxAttempts;
-    if (tooManyAttempts) {
-      // Token exceeded max attempts - increment IP rate limit
-      await incrementIPRateLimit();
-      throw new NAuthException(
-        AuthErrorCode.VERIFICATION_TOO_MANY_ATTEMPTS,
-        'Too many failed attempts. Request a new code.',
-        {
-          maxAttempts,
-          currentAttempts: verificationToken.attempts,
-        },
-      );
-    }
-
-    // ============================================================================
-    // Security: Rate limit verification attempts per user (for invalid attempts only)
-    // This prevents users from exhausting their own tokens through repeated attempts
-    // Valid codes should not be blocked by user rate limits
-    // ============================================================================
-    const maxAttemptsPerUser = this.config.signup?.phoneVerification?.maxAttemptsPerUser ?? 10;
-
-    // Helper to increment user rate limit (only for invalid attempts)
-    const incrementUserRateLimit = async (): Promise<void> => {
-      const userRateLimitKey = `verify-attempts:user:${user.id}`;
-      const userAttempts = await this.storageAdapter.incr(userRateLimitKey);
-
-      if (userAttempts === 1) {
-        await this.storageAdapter.expire(userRateLimitKey, attemptWindow);
-      }
-
-      if (userAttempts > maxAttemptsPerUser) {
-        throw new NAuthException(
-          AuthErrorCode.VERIFICATION_TOO_MANY_ATTEMPTS,
-          'Too many verification attempts. Please try again later.',
-        );
-      }
-    };
-
-    verificationToken.attempts += 1;
-    // Compare normalized codes (trim whitespace for comparison)
-    const storedCode = String(verificationToken.code).trim();
-    const providedCode = String(code).trim();
-    if (storedCode !== providedCode) {
-      // Invalid code - increment both IP and user rate limits
-      await incrementIPRateLimit();
-      await incrementUserRateLimit();
-
-      await this.verificationTokenRepo.save(verificationToken);
-      this.logger?.debug?.(
-        `Phone verification failed: sub=${sub}, attempts=${verificationToken.attempts}/${maxAttempts}`,
-      );
-
-      // ============================================================================
-      // Audit: Record phone verification failure (by sub)
-      // ============================================================================
-      try {
-        await this.auditService?.recordEvent({
-          userId: user.id,
-          eventType: AuthAuditEventType.PHONE_VERIFICATION_FAILED,
-          eventStatus: 'FAILURE',
-          reason: 'invalid_code',
-          // Client info automatically included from context
-          description: 'Invalid verification code provided',
-          metadata: {
-            verificationTokenId: verificationToken.id,
-            attempts: verificationToken.attempts,
-            phone: this.maskPhone(user.phone || ''),
-          },
-        });
-      } catch (auditError) {
-        // Non-blocking: Log but continue
-        const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-        this.logger?.error?.(`Failed to record PHONE_VERIFICATION_FAILED audit event (by sub): ${errorMessage}`, {
-          error: auditError,
-          userId: user.id,
-        });
-      }
-
-      throw new NAuthException(AuthErrorCode.VERIFICATION_CODE_INVALID, 'Invalid verification code', {
-        attemptsRemaining: Math.max(0, maxAttempts - verificationToken.attempts),
-      });
-    }
-
-    // ============================================================================
-    // Code is valid - proceed without rate limit checks
-    // Valid codes should always be allowed through
-    // ============================================================================
-
-    verificationToken.usedAt = new Date();
-    await this.verificationTokenRepo.save(verificationToken);
-
-    // ============================================================================
-    // Only update user if phone is not already verified to avoid unnecessary DB write
-    // This prevents updating updatedAt timestamp when phone is already verified
-    // We use the verification status from when user was loaded at the start
-    // ============================================================================
-    if (!wasPhoneVerified) {
-      // Use update() with explicit WHERE clause to ensure the change is persisted
-      // This bypasses entity tracking issues and ensures the update is committed
-      await this.userRepo.update(
-        { sub },
-        {
-          isPhoneVerified: true,
-          isActive: true,
-        },
-      );
-      this.logger?.log?.(`Phone verification successful: sub=${sub}, userId=${user.id} - phone marked as verified`);
-    } else {
-      // Phone already verified - just mark token as used, no user update needed
-      this.logger?.log?.(`Phone verification code validated: sub=${sub}, userId=${user.id} - phone already verified`);
-    }
-
-    // ============================================================================
-    // Audit: Record phone verification success (by sub)
-    // ============================================================================
-    try {
-      // Client info (ipAddress, userAgent) automatically extracted from ClientInfoService
-      // Note: ClientInfoService is used transparently by AuditService
-      await this.auditService?.recordEvent({
-        userId: user.id,
-        eventType: AuthAuditEventType.PHONE_VERIFIED,
-        eventStatus: 'SUCCESS',
-        metadata: {
-          // Client info automatically included from context
-          verificationTokenId: verificationToken.id,
-          verificationMethod: 'code',
-          phone: this.maskPhone(user.phone || ''),
-        },
-      });
-    } catch (auditError) {
-      // Non-blocking: Log but continue
-      const errorMessage = auditError instanceof Error ? auditError.message : 'Unknown error';
-      this.logger?.error?.(`Failed to record PHONE_VERIFIED audit event (by sub): ${errorMessage}`, {
-        error: auditError,
-        userId: user.id,
-      });
-    }
-
-    return { message: 'Phone verified successfully. Please log in to continue.' };
-  }
-
-  /**
-   * Resend verification SMS
-   * Supports both sub and phone-based resend
-   *
-   * @param dto - Request DTO containing sub or phone
-   * @returns Response DTO with verification token ID
-   */
-  async resendVerificationSMS(dto: ResendVerificationSMSDTO): Promise<ResendVerificationSMSResponseDTO> {
-    // Validate that either sub or phone is provided
-    if (!dto.sub && !dto.phone) {
-      throw new NAuthException(AuthErrorCode.VALIDATION_FAILED, 'Either sub or phone must be provided');
-    }
-
-    if (dto.sub) {
-      return this.resendVerificationSMSBySub(dto.sub);
-    }
-
-    return this.resendVerificationSMSForPhone(dto.phone!);
-  }
-
-  /**
-   * Resend verification SMS by user sub (private helper)
-   *
-   * @param sub - External user identifier
-   * @returns New verification token id
-   */
-  private async resendVerificationSMSBySub(sub: string): Promise<ResendVerificationSMSResponseDTO> {
-    const user = (await this.userRepo.findOne({ where: { sub } })) as IUser | null;
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
-    }
-
-    const resendDelay = this.config.signup?.phoneVerification?.resendDelay ?? 60;
-    const lastToken = (await this.verificationTokenRepo.findOne({
-      where: { userId: user.id, type: 'phone' },
-      order: { createdAt: 'DESC' },
-    })) as IVerificationToken | null;
-    if (lastToken) {
-      const secondsSinceLastSend = (Date.now() - lastToken.createdAt.getTime()) / 1000;
-      if (secondsSinceLastSend < resendDelay) {
-        const waitSeconds = Math.ceil(resendDelay - secondsSinceLastSend);
-        this.logger?.debug?.(`Resend rate limit: sub=${sub}, wait=${waitSeconds}s, delay=${resendDelay}s`);
-        throw new NAuthException(
-          AuthErrorCode.RATE_LIMIT_RESEND,
-          `Please wait ${waitSeconds} seconds before requesting another code`,
-          {
-            retryAfter: waitSeconds,
-            resendDelay,
-          },
-        );
-      }
-    }
-
-    this.logger?.debug?.(`Resending SMS verification code: sub=${sub}`);
-    // Preserve challengeSessionId from the last token to ensure verification succeeds
-    const sendDto = Object.assign(new SendVerificationSMSDTO(), {
-      sub,
-      challengeSessionId: lastToken?.challengeSessionId ?? undefined,
-    });
-    const result = await this.sendVerificationSMS(sendDto);
-    return { tokenId: result.tokenId };
-  }
-
-  /**
-   * Resend verification SMS by phone number (private helper)
-   *
-   * @param phone - Phone number
-   * @returns New verification token id
-   */
-  private async resendVerificationSMSForPhone(phone: string): Promise<ResendVerificationSMSResponseDTO> {
-    const user = (await this.userRepo.findOne({ where: { phone } })) as IUser | null;
-    if (!user) {
-      throw new NAuthException(AuthErrorCode.NOT_FOUND, 'User not found');
-    }
-    if (user.isPhoneVerified) {
-      throw new NAuthException(AuthErrorCode.ALREADY_VERIFIED, 'Phone number is already verified');
-    }
-    return this.resendVerificationSMSBySub(user.sub);
-  }
-
-  // ============================================================================
-  // Helpers
-  // ============================================================================
-
-  /**
-   * Generate N-digit OTP code (default 6)
-   */
-  private generateCode(): string {
-    const codeLength = this.config.signup?.phoneVerification?.codeLength || 6;
-    const min = Math.pow(10, codeLength - 1);
-    const max = Math.pow(10, codeLength) - 1;
-    return Math.floor(min + Math.random() * (max - min + 1)).toString();
-  }
-
-  /**
-   * Generate secure random token
-   */
-  private generateToken(): string {
-    return crypto.randomBytes(32).toString('hex');
-  }
-
-  /**
-   * Hash token with SHA-256
-   */
-  private hashToken(token: string): string {
-    return crypto.createHash('sha256').update(token).digest('hex');
-  }
-
-  /**
-   * Mask phone number for logging (preserves last 4 digits)
-   * @private
-   */
-  private maskPhone(phone: string): string {
-    if (!phone || phone.length < 4) return '***';
-    return `***${phone.slice(-4)}`;
-  }
-}