@wildo-ai/saas-backend-lib 1.0.1

package/src/security/authentications/services/authentication-orchestrator.backend.service.ts

@@ -0,0 +1,3156 @@
+import 'reflect-metadata';
+import { inject, injectable } from 'inversify';
+import * as crypto from 'crypto';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import type { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import {
+  AuthIdentificationRequest,
+  AvailableMethod,
+  CoreConsumableTokenTypes,
+  ConsumableToken_ConsumptionMode,
+  ErrorCustomMessageReference,
+  ErrorType,
+  isWildoBackendError,
+  PasswordAuthRequest,
+  User,
+  UserStatus,
+} from '@wildo-ai/saas-models';
+import { CoreResourceType } from '@wildo-ai/saas-models';
+import {
+  AuthUtils,
+  AuthIdentificationResponseSchema,
+  AuthMethod,
+  AuthFactorLevel,
+  AuthenticationResponseSchema,
+  AuthIdentificationResponse,
+  AuthenticationRequest,
+  AuthenticationResponse,
+  AuthenticationSession,
+  AuthenticationSessionSchema,
+  AuthenticationSessionState,
+  AuthNextStep,
+  AuthScopeType,
+} from '@wildo-ai/saas-models';
+import { AuthSessionPurpose, MfaEnrollmentState } from '@wildo-ai/saas-models';
+import type { EmailOTPAuthRequest, TOTPAuthRequest, PasskeyAuthRequest, SMSOTPAuthRequest, UserCredentials, MagicLinkSendRequest, MagicLinkVerifyRequest, UserTypeAuthPolicy, UserTypesConfig } from '@wildo-ai/saas-models';
+import { RegistrationMode, EmailVerificationMode } from '@wildo-ai/saas-models';
+import { DurationUnit } from '@wildo-ai/zod-decorators';
+import { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';
+import { AuditLogsBackendService } from '~wildo-backend-lib/compliance/audit-trails/services/audit-logs.backend.service';
+import { createOrgOnRegistration } from '~wildo-backend-lib/organizations/services/org-creation-on-registration.backend.utils';
+import { grantUserTypesOnOrgJoin } from '~wildo-backend-lib/organizations/services/user-org-type-grant.backend.utils';
+
+// New decomposed services
+import { AuthSessionStoreBackendService } from '~wildo-backend-lib/security/authentications/services/auth-session-store.backend.service';
+import { AuthCredentialVerifierBackendService } from '~wildo-backend-lib/security/authentications/services/auth-credential-verifier.backend.service';
+import { AuthTokenIssuerBackendService, type AuthTokens } from '~wildo-backend-lib/security/authentications/services/auth-token-issuer.backend.service';
+import { WebAuthnBackendService } from '~wildo-backend-lib/security/authentications/services/auth-methods/webauthn.backend.service';
+import type { OtpOperational, MagicLinkOperational, TotpOperational } from '~wildo-backend-lib/config/models/app-config.backend.schemas';
+import type { LockoutPolicyConfig } from '@wildo-ai/saas-models';
+import { ConsumableTokenBackendService } from '~wildo-backend-lib/security/consumable-tokens/services/consumable-token.backend.service';
+import { RedisService } from '~wildo-backend-lib/databases/services/redis.service';
+import { RateLimitBackendService } from '~wildo-backend-lib/errors/services/rate-limit.backend.service';
+import { DomainToOrgLookupBackendService } from '~wildo-backend-lib/security/authentications/services/admin-config/domain-to-org-lookup.backend.service';
+import type { DomainOrgLookupResult } from '~wildo-backend-lib/security/authentications/services/admin-config/domain-to-org-lookup.backend.service';
+import { AuthOrganizationConfigurationService } from '~wildo-backend-lib/security/authentications/services/admin-config/auth-organization-configuration.service';
+import { AUTH_REDIS_KEYS } from '~wildo-backend-lib/security/authentications/models/auth-constants.backend';
+import { OAuth2ConnectionResolverBackendService } from '~wildo-backend-lib/security/authentications/services/auth-methods/oauth2-connection-resolver.backend.service';
+import { AuthUserLookupBackendService } from '~wildo-backend-lib/security/authentications/services/utils/auth-user-lookup.backend.service';
+import { AuthCredentialOpsBackendService } from '~wildo-backend-lib/security/authentications/services/utils/auth-credential-ops.backend.service';
+
+/**
+ * AuthenticationOrchestratorBackendService
+ *
+ * Orchestrates the authentication flow: identify → authenticate → tokens.
+ *
+ * Decomposed from the original AuthenticationBackendService (1900 lines → ~400 lines).
+ * Session storage, credential verification, and token issuance are delegated to
+ * focused sub-services (AuthSessionStore, AuthCredentialVerifier, AuthTokenIssuer).
+ *
+ * Public API preserved:
+ * - identify(request) → AuthIdentificationResponse
+ * - authenticate(request) → AuthenticationResponse
+ * - authenticatePassword(request) → AuthenticationResponse
+ * - getAuthenticationSessionState(sessionId) → AuthenticationSession | null
+ *
+ * TRAP 2: The controller calls exactly these methods. Signatures accept EC as the first parameter.
+ * TRAP 9: Dependency arrows flow one way: Orchestrator → Services → Infrastructure.
+ * TRAP 13: Audit logging stays here (not in sub-services).
+ */
+@injectable()
+export class AuthenticationOrchestratorBackendService {
+  /** L11: Default session duration in minutes (absolute TTL). Overridden by userTypes[t].auth.sessionDurationMinutes. */
+  private static readonly DEFAULT_SESSION_DURATION_MINUTES = 30;
+  /** Idle timeout in minutes — session is deleted if lastActivity exceeds this. Must be < SESSION_DURATION_MINUTES. */
+  private static readonly AUTH_SESSION_IDLE_TIMEOUT_MINUTES = 5;
+  /** Default number of MFA methods required (for future MFA support). */
+  private static readonly DEFAULT_MFA_METHODS_REQUIRED = 1;
+
+  private readonly logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly appConfigService: AppConfigurationService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService) private readonly servicesRegistryHandler: ServicesRegistryHandlerBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuditLogsService) private readonly auditLogsService: AuditLogsBackendService,
+    // New decomposed services
+    @inject(SAAS_SERVICE_TYPES.AuthSessionStore) private readonly sessionStore: AuthSessionStoreBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthCredentialVerifier) private readonly credentialVerifier: AuthCredentialVerifierBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthTokenIssuer) private readonly tokenIssuer: AuthTokenIssuerBackendService,
+    // MFA services (Step 10-11)
+    @inject(SAAS_SERVICE_TYPES.ConsumableTokenService) private readonly consumableTokenService: ConsumableTokenBackendService,
+    @inject(SAAS_SERVICE_TYPES.RedisService) private readonly redisService: RedisService,
+    @inject(SAAS_SERVICE_TYPES.RateLimitBackendService) private readonly rateLimitService: RateLimitBackendService,
+    // Domain-to-org lookup service (Step 14 — enterprise SSO domain routing)
+    @inject(SAAS_SERVICE_TYPES.DomainToOrgLookupService) private readonly domainToOrgLookup: DomainToOrgLookupBackendService,
+    // Organization configuration (M12 — org-level auth policy enforcement)
+    @inject(SAAS_SERVICE_TYPES.AuthOrganizationConfigurationService) private readonly orgConfigService: AuthOrganizationConfigurationService,
+    // WebAuthn/Passkey ceremony service (Phase G1)
+    @inject(SAAS_SERVICE_TYPES.WebAuthnService) private readonly webAuthnService: WebAuthnBackendService,
+    // G3: OAuth2 connection resolver — for filtering providers by org restrictions
+    @inject(SAAS_SERVICE_TYPES.OAuth2ConnectionResolverService) private readonly oauth2Resolver: OAuth2ConnectionResolverBackendService,
+    // AUTH-14: User lookup + effective auth policy resolution with org overrides
+    @inject(SAAS_SERVICE_TYPES.AuthUserLookupService) private readonly userLookup: AuthUserLookupBackendService,
+    // Centralized credential read/update operations via service registry
+    @inject(SAAS_SERVICE_TYPES.AuthCredentialOpsService) private readonly credentialOps: AuthCredentialOpsBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('AuthenticationOrchestrator');
+    this.logger.setDebugTypeLogging('AuthenticationOrchestrator', false);
+  }
+
+  /**
+   * Global lockout policy for email-scoped rate limiting (pre-authentication, user type unknown).
+   * Computed as the most-restrictive lockout across all configured user types:
+   * lowest maxLoginAttempts, longest lockoutDuration, progressive if any type uses it.
+   */
+  private get lockoutPolicy(): LockoutPolicyConfig {
+    const userTypes = this.appConfigService.config.userTypes;
+    const policies = Object.values(userTypes).map(ut => ut.auth.lockoutPolicy);
+    if (policies.length === 0) {
+      return { maxLoginAttempts: 5, lockoutDurationMinutes: 30, progressiveLockout: false, maxProgressiveLockoutHours: 24 };
+    }
+    return {
+      maxLoginAttempts: Math.min(...policies.map(p => p.maxLoginAttempts)),
+      lockoutDurationMinutes: Math.max(...policies.map(p => p.lockoutDurationMinutes)),
+      progressiveLockout: policies.some(p => p.progressiveLockout),
+      maxProgressiveLockoutHours: Math.max(...policies.map(p => p.maxProgressiveLockoutHours)),
+    };
+  }
+
+  private get otpConfig(): OtpOperational {
+    return this.appConfigService.config.auth.otpOperational;
+  }
+
+  private get magicLinkConfig(): MagicLinkOperational {
+    return this.appConfigService.config.auth.magicLinkOperational;
+  }
+
+  private get totpConfig(): TotpOperational {
+    return this.appConfigService.config.auth.totpOperational;
+  }
+
+  // ===============================
+  // PER-USER-TYPE AUTH CONFIG RESOLUTION (W3.1)
+  // ===============================
+
+  /**
+   * Resolve the effective auth policy for a given user type.
+   * If the user type exists in config.userTypes, returns its auth policy.
+   * Falls back to FALLBACK_AUTH_POLICY when no user type is configured.
+   */
+  private _resolveAuthPolicy(activeUserType?: string | null): UserTypeAuthPolicy {
+    if (activeUserType) {
+      const policy = this.appConfigService.getUserTypeAuthPolicy(activeUserType);
+      if (policy) return policy;
+    }
+    return AuthenticationOrchestratorBackendService.FALLBACK_AUTH_POLICY;
+  }
+
+  /**
+   * W6.8: Safe default auth policy when no user type is resolved.
+   * All values are restrictive-safe. Applications MUST configure userTypes for full control.
+   */
+  private static readonly FALLBACK_AUTH_POLICY: UserTypeAuthPolicy = {
+    authMethodsEnabled: { [AuthMethod.PASSWORD]: true },
+    mfaPolicy: {
+      requireMFA: false,
+      requireStrongMFA: false,
+      enrollmentGracePeriodDays: 0,
+      passkeyExemptFromMFA: true,
+    },
+    registration: {
+      mode: RegistrationMode.OPEN,
+      allowedMethods: [AuthMethod.PASSWORD],
+      requirePasswordOnRegister: true,
+      emailVerification: EmailVerificationMode.REQUIRED_BEFORE_ACCESS,
+      blockForSSODomains: false,
+    },
+    passwordPolicy: {
+      minLength: 8,
+      maxLength: 128,
+      requireUppercase: true,
+      requireLowercase: true,
+      requireNumbers: true,
+      requireSpecialChars: false,
+      expiryDays: 0,
+    },
+    sessionDurationMinutes: AuthenticationOrchestratorBackendService.DEFAULT_SESSION_DURATION_MINUTES,
+    lockoutPolicy: {
+      maxLoginAttempts: 5,
+      lockoutDurationMinutes: 30,
+      progressiveLockout: false,
+      maxProgressiveLockoutHours: 24,
+    },
+    autoLinkByEmail: true,
+    methodManagement: {
+      allowUserMethodRemoval: true,
+      requireReauthForMethodChanges: false,
+    },
+  };
+
+  /**
+   * AUTH-14: Resolve auth policy with org override merging for a known user.
+   * Use this instead of _resolveAuthPolicy when userId is available.
+   * Falls back to raw user-type policy if org resolution fails.
+   */
+  private async _resolveAuthPolicyWithOrgOverrides(
+    ec: ExecutionContext<any>,
+    activeUserType: string | null | undefined,
+    userId: string,
+  ): Promise<UserTypeAuthPolicy> {
+    if (!activeUserType) return AuthenticationOrchestratorBackendService.FALLBACK_AUTH_POLICY;
+    const effective = await this.userLookup.resolveEffectiveAuthPolicy(ec, userId, activeUserType);
+    return effective ?? AuthenticationOrchestratorBackendService.FALLBACK_AUTH_POLICY;
+  }
+
+  /**
+   * W6.8: Check if an auth method is enabled in ANY configured user type.
+   * Used for pre-identification guards (sendMagicLink, sendSMSOTP) where
+   * the user type is not yet known.
+   */
+  private _isMethodEnabledGlobally(method: AuthMethod): boolean {
+    const userTypes: UserTypesConfig = this.appConfigService.config.userTypes ?? {};
+    for (const [, typeDef] of Object.entries(userTypes)) {
+      if (typeDef?.auth?.authMethodsEnabled?.[method]) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Resolve auth policy from a session's activeUserType. Convenience wrapper.
+   */
+  private _resolveAuthPolicyFromSession(session: AuthenticationSession): UserTypeAuthPolicy {
+    return this._resolveAuthPolicy(session.activeUserType);
+  }
+
+  private _assertFrontendServiceAuthAllowed(frontendServiceName: string | undefined, userType: string | null | undefined): void {
+    if (!frontendServiceName || !userType) {
+      return;
+    }
+
+    const userManagement = this.appConfigService.getFrontendServiceUserManagementEntry(frontendServiceName, userType);
+    if (!userManagement?.auth) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHORIZATION,
+        context: {
+          message: `Authentication is disabled for frontend service "${frontendServiceName}" and user type "${userType}"`,
+          frontendServiceName,
+          activeUserType: userType,
+        },
+      });
+    }
+  }
+
+  // ===============================
+  // SESSION HELPERS (delegate to AuthSessionStore)
+  // ===============================
+
+  private _getSessionTtlSeconds(activeUserType?: string | null): number {
+    const policy = this._resolveAuthPolicy(activeUserType);
+    return policy.sessionDurationMinutes * 60;
+  }
+
+
+  /**
+   * Create a new authentication session in the store.
+   */
+  /** W4: Registration sessions get longer TTL (24h) to match email verification token expiry. */
+  private static readonly REGISTRATION_SESSION_TTL_SECONDS = 24 * 60 * 60;
+
+  private async createSession(
+    sessionId: string,
+    initialState: AuthenticationSessionState = AuthenticationSessionState.CREATED,
+    options: {
+      deviceInfo?: { userAgent?: string; ipAddress?: string };
+      activeUserType?: string;
+      purpose?: AuthSessionPurpose;
+      email?: string;
+      userId?: string;
+      pendingOrgType?: string;
+    } = {},
+  ): Promise<AuthenticationSession> {
+    const authPolicy = this._resolveAuthPolicy(options.activeUserType);
+    const isRegistrationFlow = options.purpose === AuthSessionPurpose.REGISTRATION || options.purpose === AuthSessionPurpose.INVITATION;
+    const ttlSeconds = isRegistrationFlow
+      ? AuthenticationOrchestratorBackendService.REGISTRATION_SESSION_TTL_SECONDS
+      : authPolicy.sessionDurationMinutes * 60;
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + ttlSeconds * 1000);
+
+    const session: AuthenticationSession = {
+      sessionId,
+      state: initialState,
+      activeUserType: options.activeUserType,
+      purpose: options.purpose ?? AuthSessionPurpose.LOGIN,
+      email: options.email,
+      userId: options.userId,
+      createdAt: now,
+      expiresAt,
+      lastActivity: now,
+      completedFactors: [],
+      availableFirstFactorMethods: [],
+      availableSecondFactorMethods: [],
+      availableEnrollmentMethods: [],
+      enrolledSecondFactorMethods: [],
+      usableSecondFactorMethods: [],
+      requiresMFA: false,
+      requireStrongMFA: false,
+      mfaMethodsRequired: AuthenticationOrchestratorBackendService.DEFAULT_MFA_METHODS_REQUIRED,
+      attempts: 0,
+      maxAttempts: authPolicy.lockoutPolicy.maxLoginAttempts,
+      requestedIntegrations: [],
+      deviceInfo: options.deviceInfo,
+      pendingOrgType: options.pendingOrgType,
+      version: 0,
+    };
+
+    await this.sessionStore.set(sessionId, session, ttlSeconds);
+    this.logDebug(`Created new authentication session: ${sessionId}`, { purpose: session.purpose });
+
+    return session;
+  }
+
+  /**
+   * Get and validate a session. Returns null if not found, expired, or idle-timed-out.
+   */
+  private async getSession(sessionId: string): Promise<AuthenticationSession | null> {
+    const session = await this.sessionStore.get(sessionId);
+
+    if (!session) {
+      return null;
+    }
+
+    // Check expiry (Redis TTL handles this too, but defensive check)
+    if (session.expiresAt < new Date()) {
+      await this.sessionStore.delete(sessionId);
+      this.logDebug(`Session expired and removed: ${sessionId}`);
+      return null;
+    }
+
+    // M15 fix: Idle timeout — delete session if lastActivity is stale
+    if (session.lastActivity) {
+      const idleLimitMs = AuthenticationOrchestratorBackendService.AUTH_SESSION_IDLE_TIMEOUT_MINUTES * 60 * 1000;
+      const idleDuration = Date.now() - session.lastActivity.getTime();
+      if (idleDuration > idleLimitMs) {
+        await this.sessionStore.delete(sessionId);
+        this.logDebug(`Session idle-timed-out and removed: ${sessionId}`, {
+          idleMinutes: Math.round(idleDuration / 60000),
+          limitMinutes: AuthenticationOrchestratorBackendService.AUTH_SESSION_IDLE_TIMEOUT_MINUTES,
+        });
+        return null;
+      }
+    }
+
+    return session;
+  }
+
+  /** Maximum retries for atomic session updates before falling back to non-atomic write. */
+  private static readonly ATOMIC_UPDATE_MAX_RETRIES = 3;
+
+  /**
+   * Update a session in the store using atomic compare-and-swap (M1 fix).
+   *
+   * Uses the session `version` field for optimistic concurrency control.
+   * On version mismatch (concurrent writer), re-reads and retries up to MAX_RETRIES.
+   * Falls back to a non-atomic write only if all retries are exhausted.
+   */
+  private async updateSession(
+    sessionId: string,
+    updates: Partial<AuthenticationSession>,
+  ): Promise<AuthenticationSession | null> {
+    for (let attempt = 0; attempt <= AuthenticationOrchestratorBackendService.ATOMIC_UPDATE_MAX_RETRIES; attempt++) {
+      const session = await this.getSession(sessionId);
+      if (!session) {
+        return null;
+      }
+
+      const expectedVersion = session.version ?? 0;
+      const updatedSession = AuthenticationSessionSchema.parse({
+        ...session,
+        ...updates,
+        lastActivity: new Date(),
+        version: expectedVersion + 1,
+      });
+
+      // Try atomic update via Lua compare-and-swap
+      const result = await this.sessionStore.atomicUpdate(
+        sessionId,
+        updatedSession,
+        expectedVersion,
+        this._getSessionTtlSeconds(updatedSession.activeUserType),
+      );
+
+      if (result) {
+        this.logDebug(`Updated authentication session: ${sessionId}`, {
+          state: updatedSession.state,
+          version: updatedSession.version,
+        });
+        return result;
+      }
+
+      // Version mismatch — another writer beat us. Retry with fresh read.
+      this.logDebug(`Session update version conflict (attempt ${attempt + 1}): ${sessionId}`);
+    }
+
+    // All retries exhausted — return null to signal failure rather than falling back
+    // to a non-atomic write that could silently overwrite a concurrent writer's update.
+    this.logger.warn?.('Session atomic update retries exhausted, returning failure', { sessionId });
+    return null;
+  }
+
+  /**
+   * Remove a session from the store.
+   */
+  private async removeSession(sessionId: string): Promise<void> {
+    await this.sessionStore.delete(sessionId);
+    this.logDebug(`Removed authentication session: ${sessionId}`);
+  }
+
+  /**
+   * Increment session attempts and check for lockout.
+   * W3.1: Uses per-user-type lockout policy from session's activeUserType.
+   */
+  private async incrementSessionAttempts(
+    ec: ExecutionContext<any>,
+    sessionId: string,
+  ): Promise<{ session: AuthenticationSession | null; locked: boolean }> {
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      return { session: null, locked: false };
+    }
+
+    const sessionPolicy = this._resolveAuthPolicyFromSession(session);
+    const sessionLockout = sessionPolicy.lockoutPolicy;
+    const attempts = session.attempts + 1;
+    const locked = attempts >= session.maxAttempts;
+
+    let effectiveLockoutMinutes = sessionLockout.lockoutDurationMinutes;
+
+    // W2.3: Progressive lockout — double duration for each consecutive lockout, capped at maxProgressiveLockoutHours
+    if (locked && sessionLockout.progressiveLockout && session.userId) {
+      try {
+        const { previousCount } = await this.credentialOps.incrementLockout(ec, session.userId!);
+        const maxMinutes = (sessionLockout.maxProgressiveLockoutHours ?? 24) * 60;
+        effectiveLockoutMinutes = Math.min(
+          sessionLockout.lockoutDurationMinutes * Math.pow(2, previousCount),
+          maxMinutes,
+        );
+      } catch {
+        // Fallback to base duration if credential lookup fails
+      }
+    }
+
+    const updates: Partial<AuthenticationSession> = {
+      attempts,
+      state: locked ? AuthenticationSessionState.LOCKED : session.state,
+      lockoutUntil: locked
+        ? new Date(Date.now() + effectiveLockoutMinutes * 60 * 1000)
+        : undefined,
+    };
+
+    const updatedSession = await this.updateSession(sessionId, updates);
+
+    if (locked && updatedSession?.userId) {
+      const deviceInfo = updatedSession.deviceInfo;
+      await this.auditLogsService.logUserAccountLocked({
+        userId: updatedSession.userId,
+        email: updatedSession.email || 'unknown',
+        authMethod: AuthMethod.PASSWORD,
+        lockoutDuration: effectiveLockoutMinutes,
+        ipAddress: deviceInfo?.ipAddress || 'unknown',
+        userAgent: deviceInfo?.userAgent || 'unknown',
+        sessionId,
+      });
+    }
+
+    return { session: updatedSession, locked };
+  }
+
+  // ===============================
+  // GLOBAL LOCKOUT (C1 fix — per-email, Redis-based)
+  // ===============================
+
+  /**
+   * Get the current global attempt count for an email address.
+   */
+  private async _getGlobalAttempts(email: string): Promise<number> {
+    const key = `${AUTH_REDIS_KEYS.GLOBAL_LOCKOUT}${email.toLowerCase()}`;
+    return this.redisService.getRateLimitCount(key);
+  }
+
+  /**
+   * Increment the global attempt counter for an email.
+   * Returns the new count and whether the account is locked.
+   * The key auto-expires after the lockout duration.
+   */
+  private async _incrementGlobalAttempts(email: string): Promise<{ count: number; locked: boolean }> {
+    const key = `${AUTH_REDIS_KEYS.GLOBAL_LOCKOUT}${email.toLowerCase()}`;
+    const count = await this.redisService.incrementRateLimit(key, this.lockoutPolicy.lockoutDurationMinutes * 60);
+    return { count, locked: count >= this.lockoutPolicy.maxLoginAttempts };
+  }
+
+  /**
+   * Reset the global attempt counter on successful authentication.
+   */
+  private async _resetGlobalAttempts(email: string): Promise<void> {
+    const key = `${AUTH_REDIS_KEYS.GLOBAL_LOCKOUT}${email.toLowerCase()}`;
+    await this.redisService.del(`rate_limit:${key}`);
+  }
+
+  /**
+   * Check if an email is globally locked out. If so, throw an error.
+   */
+  private async _checkGlobalLockout(email: string): Promise<void> {
+    const attempts = await this._getGlobalAttempts(email);
+    if (attempts >= this.lockoutPolicy.maxLoginAttempts) {
+      this.logDebug('Global lockout active', { email, attempts, max: this.lockoutPolicy.maxLoginAttempts });
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_ACCOUNT_LOCKED,
+        context: {
+          message: 'Account temporarily locked due to too many failed attempts. Please try again later.',
+          lockoutDurationMinutes: this.lockoutPolicy.lockoutDurationMinutes,
+        },
+      });
+    }
+  }
+
+  // ===============================
+  // INTERNAL HELPERS
+  // ===============================
+
+  /**
+   * Resolve user for authentication by email.
+   */
+  private async _resolveUserForAuthentication(
+    ec: ExecutionContext<any>,
+    _session: AuthenticationSession,
+    email: string,
+    sessionId: string,
+  ): Promise<User> {
+    this.logDebug(`Resolving user for authentication: sessionId=${sessionId}, email=${email}`);
+
+    const user = await this.userLookup.findAnyUserByEmail(ec, email);
+
+    if (!user) {
+      const { locked } = await this.incrementSessionAttempts(ec, sessionId);
+      const authResponse = this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.FIRST, { retryAllowed: !locked });
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_NOT_FOUND,
+        context: { email, authResponse },
+      });
+    }
+
+    this._enforceUserStatus(user, sessionId);
+    return user;
+  }
+
+  private _enforceUserStatus(user: User, sessionId: string): void {
+    if (user.status === UserStatus.ACTIVE) return;
+
+    throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+      customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_ACCOUNT_LOCKED,
+      context: { userStatus: user.status, sessionId },
+    });
+  }
+
+  /**
+   * Update session after successful method authentication.
+   * Sets the correct session state based on whether this is a first or second factor completion.
+   */
+  private async _updateSessionAfterSuccessfulAuth(
+    ec: ExecutionContext<any>,
+    sessionId: string,
+    userId: string,
+    authMethod: AuthMethod,
+  ): Promise<void> {
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_SESSION_INVALID,
+        context: { sessionId, operation: 'update' },
+      });
+    }
+
+    const currentFactors = session.completedFactors || [];
+    const newCompletedFactors = currentFactors.includes(authMethod)
+      ? currentFactors
+      : [...currentFactors, authMethod];
+
+    // Determine correct session state: second-factor methods get COMPLETED (not FIRST_FACTOR_COMPLETED)
+    const isSecondFactor = AuthUtils.canBeSecondFactor(authMethod) && currentFactors.length > 0;
+
+    // Backend enforcement: reject second-factor methods not in usableSecondFactorMethods.
+    // Prevents API-level bypass of requireStrongMFA (e.g. submitting EMAIL_OTP directly).
+    if (isSecondFactor && session.usableSecondFactorMethods && session.usableSecondFactorMethods.length > 0) {
+      if (!session.usableSecondFactorMethods.includes(authMethod)) {
+        throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_METHOD_NOT_SUPPORTED,
+          context: { method: authMethod, reason: 'METHOD_NOT_IN_USABLE_LIST' },
+        });
+      }
+    }
+
+    const newState = isSecondFactor
+      ? AuthenticationSessionState.COMPLETED
+      : AuthenticationSessionState.FIRST_FACTOR_COMPLETED;
+
+    // AUTH-14: Use org-override-aware policy when userId is known
+    const sessionPolicy = userId
+      ? await this._resolveAuthPolicyWithOrgOverrides(ec, session.activeUserType, userId)
+      : this._resolveAuthPolicyFromSession(session);
+
+    const sessionUpdate: Partial<AuthenticationSession> = {
+      state: newState,
+      completedFactors: newCompletedFactors,
+      attempts: 0, // Reset attempts on successful authentication
+      userId: userId,
+    };
+
+    // After first-factor success, determine if MFA is required for this session.
+    // W3.1: Resolve per-user-type auth policy from session's activeUserType.
+    if (!isSecondFactor) {
+      const mfaCheck = await this._shouldRequireMFA(ec, userId, session.organizationId, authMethod, sessionPolicy);
+      if (mfaCheck.required) {
+        const hasEnrolledStrongFactor = mfaCheck.enrolledMethods.some(m => m !== AuthMethod.EMAIL_OTP);
+
+        if (!hasEnrolledStrongFactor) {
+          // W4.5: MFA required but no strong factor enrolled — route to enrollment
+          const secondFactorMethods = AuthUtils.getSecondFactorMethods();
+          const availableEnrollment = secondFactorMethods.filter(
+            m => sessionPolicy.authMethodsEnabled?.[m],
+          );
+
+          sessionUpdate.state = AuthenticationSessionState.MFA_ENROLLMENT_REQUIRED;
+          sessionUpdate.requiresMFA = true;
+          sessionUpdate.requireStrongMFA = sessionPolicy.mfaPolicy?.requireStrongMFA ?? false;
+          sessionUpdate.nextStep = AuthNextStep.MFA_ENROLLMENT;
+          sessionUpdate.availableEnrollmentMethods = availableEnrollment;
+        } else {
+          const mfaResolution = await this._resolveUsableMfaMethods(mfaCheck.enrolledMethods, sessionPolicy);
+
+          sessionUpdate.requiresMFA = true;
+          sessionUpdate.requireStrongMFA = mfaResolution.requireStrongMFA;
+          sessionUpdate.availableSecondFactorMethods = mfaResolution.availableMethods;
+          sessionUpdate.enrolledSecondFactorMethods = mfaCheck.enrolledMethods;
+          sessionUpdate.usableSecondFactorMethods = mfaResolution.usableMethods;
+        }
+      }
+    }
+
+    await this.updateSession(sessionId, sessionUpdate);
+
+    // W2.3: Reset progressive lockout counter on successful auth
+    if (sessionPolicy.lockoutPolicy.progressiveLockout && userId) {
+      try {
+        await this.credentialOps.resetLockout(ec, userId);
+      } catch {
+        // Non-critical: lockout counter reset failure should not block auth
+      }
+    }
+  }
+
+  // ===============================
+  // AUTHENTICATION FLOW METHODS
+  // ===============================
+
+  public async identify(
+    ec: ExecutionContext<any>,
+    identificationRequest: AuthIdentificationRequest,
+    activeUserType?: string,
+    frontendServiceName?: string,
+  ): Promise<AuthIdentificationResponse> {
+    const { email, deviceInfo } = identificationRequest;
+
+    this.logDebug(`User identification request: email=${email}`);
+
+    // H1 fix: Rate limit identify() — 10 req/min per IP, 10 req/min per email
+    if (deviceInfo?.ipAddress) {
+      await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.IDENTIFY_IP}${deviceInfo.ipAddress}`, 10, 60);
+    }
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.IDENTIFY_EMAIL}${email.toLowerCase()}`, 10, 60);
+
+    // C1 fix: Check global lockout before creating a session
+    await this._checkGlobalLockout(email);
+
+    const user = await this.userLookup.findAnyUserByEmail(ec, email);
+
+    this.logDebug(`User lookup result: userExists=${!!user}, email=${email}`);
+
+    // AUTH-10 FIX: When the user exists in DB, trust their stored userTypes over
+    // the client-provided X-Frontend-Service-Name-derived hint. The header is only used as a
+    // hint when the user is unknown (pre-registration UI).
+    const dbUserTypes = user ? (user as User & { userTypes?: string[] }).userTypes : undefined;
+    const resolvedUserType = (dbUserTypes?.length ? dbUserTypes[0] : undefined) ?? activeUserType;
+
+    // ─── Step 14: Domain-based SSO routing ───
+    // Extract email domain and check if an org claims it for SSO
+    const emailDomain = email.split('@')[1]?.toLowerCase();
+    let domainOrgLookup: DomainOrgLookupResult | null = null;
+
+    if (emailDomain) {
+      try {
+        domainOrgLookup = await this.domainToOrgLookup.findOrgByDomain(ec, emailDomain);
+      } catch {
+        this.logDebug('Domain-to-org lookup failed (non-fatal)', { emailDomain });
+      }
+    }
+
+    // Generate cryptographically secure session ID (Section 6.5 fix)
+    const sessionId = this.sessionStore.generateSessionId();
+
+    // AUTH-14: Use org-override-aware policy when user is known, raw policy for unknown users
+    this._assertFrontendServiceAuthAllowed(frontendServiceName, resolvedUserType);
+
+    const authPolicy = (user && resolvedUserType)
+      ? await this._resolveAuthPolicyWithOrgOverrides(ec, resolvedUserType, user._id)
+      : this._resolveAuthPolicy(resolvedUserType);
+    const firstFactorMethods = await this._getAvailableFirstFactorMethods(ec, domainOrgLookup, authPolicy);
+
+    // G1: Filter PASSKEY from firstFactorMethods if the user has no registered passkeys.
+    // Also enrich the PASSKEY method config with the registered passkey count for UI hints.
+    if (user) {
+      try {
+        const userId = user._id;
+        const cred = await this.credentialVerifier.resolveCredentials(ec, userId);
+        const passkeyCount = (cred as UserCredentials)?.passkeyCredentials?.length ?? 0;
+
+        if (passkeyCount === 0) {
+          // Remove PASSKEY from available first factor methods since user has none registered
+          const passkeyIdx = firstFactorMethods.findIndex(m => m.method === AuthMethod.PASSKEY);
+          if (passkeyIdx >= 0) {
+            firstFactorMethods.splice(passkeyIdx, 1);
+          }
+        } else {
+          // Enrich PASSKEY config with credential count for UI hinting
+          const passkeyMethod = firstFactorMethods.find(m => m.method === AuthMethod.PASSKEY);
+          if (passkeyMethod) {
+            passkeyMethod.config = {
+              ...passkeyMethod.config,
+              registeredPasskeyCount: passkeyCount,
+            };
+          }
+        }
+      } catch {
+        // If credential lookup fails, just leave PASSKEY as-is from app config
+      }
+    }
+
+    // If org requires SSO and disallows password fallback, filter out password
+    if (domainOrgLookup?.enforcement?.requireSSO && !domainOrgLookup.enforcement.allowPasswordFallback) {
+      const ssoOnlyMethods = firstFactorMethods.filter(
+        m => m.method === AuthMethod.ORG_OPENID_CONNECT || m.method === AuthMethod.ORG_SAML,
+      );
+      if (ssoOnlyMethods.length > 0) {
+        firstFactorMethods.length = 0;
+        firstFactorMethods.push(...ssoOnlyMethods);
+      }
+    }
+
+    // Create session (W3.5: activeUserType stored on session, W3.1: per-user-type TTL + lockout)
+    // AUTH-10: Store the DB-resolved user type, not the raw header value
+    const session = await this.createSession(sessionId, AuthenticationSessionState.IDENTIFIED, {
+      deviceInfo,
+      activeUserType: resolvedUserType,
+    });
+
+    await this.updateSession(sessionId, {
+      email: email.toLowerCase(),
+      userExists: !!user,
+      userId: user?._id,
+      availableFirstFactorMethods: firstFactorMethods,
+      organizationId: domainOrgLookup?.scopeId,
+      scopeType: domainOrgLookup?.scopeType,
+    });
+
+    // Build organization branding if domain matched an org
+    const organizationBranding = domainOrgLookup
+      ? { organizationName: domainOrgLookup.matchedProvider?.displayName }
+      : undefined;
+
+    // H2 fix: Always return userExists: true to prevent email enumeration.
+    // If no user was found, still advertise PASSWORD as available method so the
+    // response shape is identical regardless of email existence.
+    if (!user && firstFactorMethods.length === 0) {
+      const passwordMethod = await this._buildAvailableMethodObject(undefined, AuthMethod.PASSWORD, undefined, authPolicy);
+      if (passwordMethod) {
+        firstFactorMethods.push(passwordMethod);
+      }
+    }
+
+    // #13g Step 3: Flag ssoMigrationRequired when user's domain matches enforced SSO
+    // but they haven't linked yet — signals the frontend to show migration messaging.
+    let ssoMigrationRequired = false;
+    if (user && domainOrgLookup?.enforcement?.requireSSO && domainOrgLookup.matchedProvider) {
+      try {
+        const matchedConnectionId = (domainOrgLookup.matchedProvider._id as string) || (domainOrgLookup.matchedProvider.connectionId as string);
+        if (matchedConnectionId) {
+          const existingLink = await this.servicesRegistryHandler.read<{ _id: string }>(CoreResourceType.USER_IDENTITY_LINKS, ec, {
+            userId: (user as User)._id,
+            connectionId: matchedConnectionId,
+          });
+          if (!existingLink) {
+            ssoMigrationRequired = true;
+          }
+        }
+      } catch {
+        this.logger.warn('SSO migration check failed (non-fatal)', { email });
+      }
+    }
+
+    const payload = {
+      sessionId,
+      email: email.toLowerCase(),
+      userExists: true, // H2 fix: always true to prevent enumeration
+      firstFactorMethods,
+      defaultFirstFactorMethod: firstFactorMethods.length > 0 ? firstFactorMethods[0].method : undefined,
+      secondFactorMethods: [],
+      requiresMFA: false,
+      mfaMethodsRequired: AuthenticationOrchestratorBackendService.DEFAULT_MFA_METHODS_REQUIRED,
+      organizationBranding,
+      availableIntegrations: [],
+      ssoMigrationRequired,
+    };
+    return AuthIdentificationResponseSchema.parse(payload);
+  }
+
+  // ===============================
+  // AVAILABLE METHODS LOGIC
+  // ===============================
+
+  private async _getAvailableFirstFactorMethods(ec: ExecutionContext<any>, domainOrgLookup?: DomainOrgLookupResult | null, authPolicy?: UserTypeAuthPolicy): Promise<AvailableMethod[]> {
+    const policy = authPolicy ?? AuthenticationOrchestratorBackendService.FALLBACK_AUTH_POLICY;
+    const methods: AvailableMethod[] = [];
+    for (const method of AuthUtils.getFirstFactorMethods()) {
+      const availableMethod = await this._buildAvailableMethodObject(ec, method, domainOrgLookup, policy);
+      if (availableMethod) {
+        methods.push(availableMethod);
+      }
+    }
+    return methods;
+  }
+
+  private async _getAvailableSecondFactorMethods(authPolicy?: UserTypeAuthPolicy): Promise<AvailableMethod[]> {
+    const policy = authPolicy ?? AuthenticationOrchestratorBackendService.FALLBACK_AUTH_POLICY;
+    const methods: AvailableMethod[] = [];
+    for (const method of AuthUtils.getSecondFactorMethods()) {
+      const availableMethod = await this._buildAvailableMethodObject(undefined, method, undefined, policy);
+      if (availableMethod) {
+        methods.push(availableMethod);
+      }
+    }
+
+    const acceptable = policy.mfaPolicy?.acceptableMFAMethods ?? [];
+    if (acceptable.length > 0) {
+      return methods.filter(m => acceptable.includes(m.method));
+    }
+    return methods;
+  }
+
+  /**
+   * Intersects available methods with enrolled methods, applying requireStrongMFA filtering.
+   * Returns { availableMethods, usableMethods, requireStrongMFA } for session population.
+   */
+  private async _resolveUsableMfaMethods(enrolledMethods: AuthMethod[], authPolicy?: UserTypeAuthPolicy): Promise<{
+    availableMethods: AvailableMethod[];
+    usableMethods: AuthMethod[];
+    requireStrongMFA: boolean;
+  }> {
+    const policy = authPolicy ?? AuthenticationOrchestratorBackendService.FALLBACK_AUTH_POLICY;
+    const availableMethods = await this._getAvailableSecondFactorMethods(policy);
+    const enrolledSet = new Set<AuthMethod>(enrolledMethods);
+    const requireStrongMFA = !!policy.mfaPolicy?.requireStrongMFA;
+    let usableMethods: AuthMethod[] = availableMethods
+      .filter(m => enrolledSet.has(m.method))
+      .map(m => m.method);
+    if (requireStrongMFA) {
+      usableMethods = usableMethods.filter(m => m !== AuthMethod.EMAIL_OTP);
+    }
+    return { availableMethods, usableMethods, requireStrongMFA };
+  }
+
+  // ===============================
+  // PASSWORD AUTHENTICATION
+  // ===============================
+
+  public async authenticatePassword(ec: ExecutionContext<any>, passwordAuthRequest: PasswordAuthRequest): Promise<AuthenticationResponse> {
+    const { sessionId, password } = passwordAuthRequest;
+    this.logDebug('Password authentication started', { sessionId, hasPassword: !!password });
+
+    // Get and validate session
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      this.logDebug('Session not found', { sessionId });
+      const authResponse = this._buildIdentificationErrorResponse(sessionId, passwordAuthRequest.factorLevel, false, session);
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_SESSION_INVALID,
+        context: { sessionId, authResponse },
+      });
+    }
+
+    // Check session-level lockout
+    if (session.state === AuthenticationSessionState.LOCKED) {
+      const authResponse = this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.FIRST, {
+        retryAllowed: false,
+        lockoutUntil: session.lockoutUntil,
+      });
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_ACCOUNT_LOCKED,
+        context: { sessionId, authResponse },
+      });
+    }
+
+    // M2 fix: State machine guard — only allow password auth from valid states
+    const validPasswordStates = new Set([
+      AuthenticationSessionState.IDENTIFIED,
+      AuthenticationSessionState.FIRST_FACTOR_IN_PROGRESS,
+    ]);
+    if (!validPasswordStates.has(session.state)) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_SESSION_INVALID,
+        context: { message: 'Invalid session state for password authentication' },
+      });
+    }
+
+    const { email } = session;
+
+    // H1 fix: Rate limit authenticatePassword() — 5 req/min per email+IP
+    const ipAddress = session.deviceInfo?.ipAddress;
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.PASSWORD_EMAIL}${email.toLowerCase()}`, 5, 60);
+    if (ipAddress) {
+      await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.PASSWORD_IP}${ipAddress}`, 10, 60);
+    }
+
+    // C1 fix: Check global lockout (per-email, survives session recreation)
+    await this._checkGlobalLockout(email);
+
+    // M14 fix: If user's scope requires SSO, check grace login allowance before proceeding.
+    if (session.organizationId) {
+      await this._checkSSOGraceLoginAllowed(ec, (session.scopeType as AuthScopeType) || AuthScopeType.ORGANIZATION, session.organizationId, session.userId || '');
+    }
+
+    // Update session state
+    await this.updateSession(sessionId, {
+      state: AuthenticationSessionState.FIRST_FACTOR_IN_PROGRESS,
+      currentFactor: AuthFactorLevel.FIRST,
+    });
+
+    // Resolve user
+    const user = await this._resolveUserForAuthentication(ec, session, email, sessionId);
+    const userId = (user as User)._id;
+
+    // Resolve credentials via AuthCredentialVerifier
+    const cred = await this.credentialVerifier.resolveCredentials(ec, userId);
+
+    if (!cred) {
+      const { locked } = await this.incrementSessionAttempts(ec, sessionId);
+      const authResponse = this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.FIRST, {
+        authMethod: AuthMethod.PASSWORD,
+        retryAllowed: !locked,
+      });
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_CREDENTIALS_NOT_FOUND,
+        context: { email, authResponse },
+      });
+    }
+
+    // Verify password via AuthCredentialVerifier
+    this.logDebug('Verifying password', { sessionId });
+    const ok = await this.credentialVerifier.verifyPassword(cred.passwordHash, password);
+    this.logDebug('Password verification result', { sessionId, passwordMatch: ok });
+
+    if (!ok) {
+      this.logDebug('Password verification failed', { sessionId });
+      const { locked } = await this.incrementSessionAttempts(ec, sessionId);
+
+      // C1 fix: Also increment global counter (survives session recreation)
+      const { locked: globalLocked } = await this._incrementGlobalAttempts(email);
+      const effectivelyLocked = locked || globalLocked;
+
+      // Audit log authentication failure (TRAP 13: audit stays in orchestrator)
+      const deviceInfo = session.deviceInfo;
+      await this.auditLogsService.logUserLoginFailed({
+        email,
+        authMethod: AuthMethod.PASSWORD,
+        failureReason: 'Invalid credentials',
+        ipAddress: deviceInfo?.ipAddress || 'unknown',
+        userAgent: deviceInfo?.userAgent || 'unknown',
+        attemptsRemaining: session.maxAttempts - session.attempts - 1,
+        sessionId,
+      });
+
+      const authResponse = this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.FIRST, {
+        authMethod: AuthMethod.PASSWORD,
+        retryAllowed: !effectivelyLocked,
+      });
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: effectivelyLocked
+          ? ErrorCustomMessageReference.AUTHENTICATION_ACCOUNT_LOCKED
+          : ErrorCustomMessageReference.AUTHENTICATION_USER_CREDENTIALS_INVALID,
+        context: { email, authResponse },
+      });
+    }
+
+    // Password verified — update session
+    this.logDebug('Password authentication successful', { sessionId, userId });
+
+    // C1 fix: Reset global lockout counter on successful authentication
+    await this._resetGlobalAttempts(email);
+
+    // M14 fix: Increment SSO grace login counter after successful password auth.
+    if (session.organizationId) {
+      await this._incrementSSOGraceLogin(ec, (session.scopeType as AuthScopeType) || AuthScopeType.ORGANIZATION, session.organizationId, userId);
+    }
+
+    await this._updateSessionAfterSuccessfulAuth(ec, sessionId, userId, AuthMethod.PASSWORD);
+
+    const updatedSession = await this.getSession(sessionId);
+    return this._buildAuthenticationSuccessMethod(
+      sessionId,
+      AuthFactorLevel.FIRST,
+      AuthMethod.PASSWORD,
+      '', // No access token yet — tokens issued after completion check in authenticate()
+      {
+        completedFactors: updatedSession?.completedFactors || [],
+        requiresMFA: updatedSession?.requiresMFA || false,
+        availableMFAMethods: updatedSession?.availableSecondFactorMethods || [],
+        mfaMethodsRequired: updatedSession?.mfaMethodsRequired,
+        enrolledSecondFactorMethods: updatedSession?.enrolledSecondFactorMethods || [],
+        usableSecondFactorMethods: updatedSession?.usableSecondFactorMethods || [],
+        nextStep: updatedSession?.nextStep,
+        availableEnrollmentMethods: updatedSession?.availableEnrollmentMethods || [],
+      },
+    );
+  }
+
+  // ===============================
+  // NATIVE SDK FIRST-FACTOR (S0.9)
+  // ===============================
+
+  /**
+   * Handle a native SDK token exchange as a completed first factor.
+   * Creates a session, checks MFA requirement, and either issues tokens or returns MFA-required.
+   * User status is enforced before any token issuance.
+   */
+  public async handleNativeSDKFirstFactor(
+    ec: ExecutionContext<any>,
+    userId: string,
+    email: string,
+    deviceInfo?: { ipAddress?: string; userAgent?: string },
+    activeUserType?: string,
+    frontendServiceName?: string,
+  ): Promise<{ mfaRequired: false; tokens: AuthTokens } | { mfaRequired: true; sessionId: string; enrolledMethods: AuthMethod[] }> {
+    const user = await this.userLookup.findUserById(ec, userId);
+    if (!user || user.status !== UserStatus.ACTIVE) {
+      this._enforceUserStatus(user || { status: UserStatus.DELETED } as User, `native-sdk:${userId}`);
+    }
+
+    // AUTH-10 FIX: Trust DB user type over header. The user already exists (provisioned above).
+    const nativeDbUserTypes = (user as User & { userTypes?: string[] })?.userTypes ?? [];
+    const nativeResolvedUserType = nativeDbUserTypes[0] ?? activeUserType;
+
+    // W3.1b: Validate header-claimed type matches DB if both are present
+    if (activeUserType && nativeDbUserTypes.length > 0 && !nativeDbUserTypes.includes(activeUserType)) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_TYPE_MISMATCH,
+        context: { message: 'Your account is not registered for this application.', activeUserType },
+      });
+    }
+
+    this._assertFrontendServiceAuthAllowed(frontendServiceName, nativeResolvedUserType);
+
+    // AUTH-14: Use org-override-aware policy for native SDK flows
+    const nativeSdkPolicy = await this._resolveAuthPolicyWithOrgOverrides(ec, nativeResolvedUserType, userId);
+    const mfaCheck = await this._shouldRequireMFA(ec, userId, undefined, AuthMethod.EXTERNAL_OAUTH2, nativeSdkPolicy);
+
+    if (mfaCheck.required) {
+      const hasEnrolledStrongFactor = mfaCheck.enrolledMethods.some(m => m !== AuthMethod.EMAIL_OTP);
+
+      if (hasEnrolledStrongFactor) {
+        const sessionId = this.sessionStore.generateSessionId();
+        await this.createSession(sessionId, AuthenticationSessionState.FIRST_FACTOR_COMPLETED, { deviceInfo, activeUserType: nativeResolvedUserType });
+        const mfaResolution = await this._resolveUsableMfaMethods(mfaCheck.enrolledMethods, nativeSdkPolicy);
+
+        await this.updateSession(sessionId, {
+          userId,
+          email,
+          completedFactors: [AuthMethod.EXTERNAL_OAUTH2],
+          requiresMFA: true,
+          requireStrongMFA: mfaResolution.requireStrongMFA,
+          availableSecondFactorMethods: mfaResolution.availableMethods,
+          enrolledSecondFactorMethods: mfaCheck.enrolledMethods,
+          usableSecondFactorMethods: mfaResolution.usableMethods,
+        });
+        return { mfaRequired: true, sessionId, enrolledMethods: mfaCheck.enrolledMethods };
+      }
+
+      // W4.5: MFA required but no strong factor enrolled — block token issuance, require enrollment
+      const sessionId = this.sessionStore.generateSessionId();
+      const secondFactorMethods = AuthUtils.getSecondFactorMethods();
+      const availableEnrollment = secondFactorMethods.filter(
+        m => nativeSdkPolicy.authMethodsEnabled?.[m],
+      );
+
+      await this.createSession(sessionId, AuthenticationSessionState.MFA_ENROLLMENT_REQUIRED, { deviceInfo, activeUserType: nativeResolvedUserType });
+      await this.updateSession(sessionId, {
+        userId,
+        email,
+        completedFactors: [AuthMethod.EXTERNAL_OAUTH2],
+        requiresMFA: true,
+        requireStrongMFA: nativeSdkPolicy.mfaPolicy?.requireStrongMFA ?? false,
+        nextStep: AuthNextStep.MFA_ENROLLMENT,
+        availableEnrollmentMethods: availableEnrollment,
+      });
+      return { mfaRequired: true, sessionId, enrolledMethods: [] };
+    }
+
+    const tokens = await this.tokenIssuer.issueTokensForUser(userId, undefined, {
+      lastAuthenticatedAt: Math.floor(Date.now() / 1000),
+    });
+    return { mfaRequired: false, tokens };
+  }
+
+  // ===============================
+  // W4: REGISTRATION PIPELINE
+  // ===============================
+
+  /**
+   * W4.1: Create a registration session after user account creation.
+   * Called by `registerUser()` instead of returning a generic success message.
+   * The session tracks the registration pipeline state (email verify → MFA enrollment → complete).
+   */
+  public async createRegistrationSession(
+    userId: string,
+    email: string,
+    options: {
+      activeUserType?: string;
+      purpose?: AuthSessionPurpose;
+      deviceInfo?: { userAgent?: string; ipAddress?: string };
+      pendingOrgType?: string;
+    } = {},
+  ): Promise<AuthenticationSession> {
+    const sessionId = this.sessionStore.generateSessionId();
+    const session = await this.createSession(sessionId, AuthenticationSessionState.REGISTERED, {
+      activeUserType: options.activeUserType,
+      purpose: options.purpose ?? AuthSessionPurpose.REGISTRATION,
+      email,
+      userId,
+      deviceInfo: options.deviceInfo,
+      pendingOrgType: options.pendingOrgType,
+    });
+    return session;
+  }
+
+  /**
+   * W4.1: Process email verification through the registration pipeline.
+   * Instead of issuing tokens directly, transitions the session through:
+   * EMAIL_VERIFIED → check MFA → MFA_ENROLLMENT_REQUIRED / MFA_ENROLLMENT_GRACE / COMPLETED.
+   *
+   * Returns the updated session with `nextStep` indicating what the frontend should do.
+   */
+  public async processEmailVerification(
+    ec: ExecutionContext<any>,
+    userId: string,
+    email: string,
+    activeUserType?: string,
+    deviceInfo?: { userAgent?: string; ipAddress?: string },
+    purpose?: AuthSessionPurpose,
+  ): Promise<AuthenticationSession> {
+    const authPolicy = activeUserType
+      ? await this._resolveAuthPolicyWithOrgOverrides(ec, activeUserType, userId)
+      : AuthenticationOrchestratorBackendService.FALLBACK_AUTH_POLICY;
+
+    const sessionId = this.sessionStore.generateSessionId();
+    const session = await this.createSession(sessionId, AuthenticationSessionState.EMAIL_VERIFIED, {
+      activeUserType,
+      purpose: purpose ?? AuthSessionPurpose.REGISTRATION,
+      email,
+      userId,
+      deviceInfo,
+    });
+
+    return this._advanceRegistrationPipeline(ec, session, authPolicy, userId);
+  }
+
+  /**
+   * W4: Advance a registration session through the pipeline after a state transition.
+   * Checks MFA requirements, grace period, and onboarding to determine next state.
+   */
+  private async _advanceRegistrationPipeline(
+    ec: ExecutionContext<any>,
+    session: AuthenticationSession,
+    authPolicy: UserTypeAuthPolicy,
+    userId: string,
+  ): Promise<AuthenticationSession> {
+    if (session.state !== AuthenticationSessionState.EMAIL_VERIFIED) {
+      return session;
+    }
+
+    const mfaResult = await this._shouldRequireMFA(ec, userId, undefined, undefined, authPolicy);
+
+    const cred = await this.credentialOps.readByUserId(ec, userId);
+
+    if (mfaResult.required) {
+      const hasEnrolledStrongFactor = mfaResult.enrolledMethods.some(m => m !== AuthMethod.EMAIL_OTP);
+
+      if (hasEnrolledStrongFactor) {
+        if (cred && cred.mfaEnrollmentState !== MfaEnrollmentState.ENROLLED) {
+          await this.credentialOps.updateById(ec, cred._id, { mfaEnrollmentState: MfaEnrollmentState.ENROLLED } as Partial<UserCredentials>);
+        }
+        return this._completeRegistrationSession(session);
+      }
+
+      const gracePeriodDays = authPolicy.mfaPolicy?.enrollmentGracePeriodDays ?? 0;
+      if (gracePeriodDays > 0) {
+        const graceExpiresAt = new Date();
+        graceExpiresAt.setDate(graceExpiresAt.getDate() + gracePeriodDays);
+
+        if (cred) {
+          await this.credentialOps.updateById(ec, cred._id, {
+            mfaEnrollmentState: MfaEnrollmentState.GRACE,
+            firstMfaPromptAt: cred.firstMfaPromptAt ?? new Date(),
+          } as Partial<UserCredentials>);
+        }
+
+        const updated = await this.updateSession(session.sessionId, {
+          state: AuthenticationSessionState.MFA_ENROLLMENT_GRACE,
+          nextStep: AuthNextStep.COMPLETE,
+          mfaGraceExpiresAt: graceExpiresAt.toISOString(),
+          requiresMFA: true,
+        });
+        return updated ?? session;
+      }
+
+      if (cred) {
+        await this.credentialOps.updateById(ec, cred._id, { mfaEnrollmentState: MfaEnrollmentState.PENDING } as Partial<UserCredentials>);
+      }
+
+      const secondFactorMethods = AuthUtils.getSecondFactorMethods();
+      const availableEnrollment = secondFactorMethods.filter(
+        m => authPolicy.authMethodsEnabled?.[m],
+      );
+
+      const updated = await this.updateSession(session.sessionId, {
+        state: AuthenticationSessionState.MFA_ENROLLMENT_REQUIRED,
+        nextStep: AuthNextStep.MFA_ENROLLMENT,
+        requiresMFA: true,
+        requireStrongMFA: authPolicy.mfaPolicy?.requireStrongMFA ?? false,
+        availableEnrollmentMethods: availableEnrollment,
+      });
+      return updated ?? session;
+    }
+
+    if (cred && cred.mfaEnrollmentState !== MfaEnrollmentState.NOT_REQUIRED && cred.mfaEnrollmentState !== MfaEnrollmentState.ENROLLED) {
+      await this.credentialOps.updateById(ec, cred._id, { mfaEnrollmentState: MfaEnrollmentState.NOT_REQUIRED } as Partial<UserCredentials>);
+    }
+    return this._completeRegistrationSession(session);
+  }
+
+  /**
+   * W4: Complete a registration session — transition to COMPLETED or ONBOARDING_PENDING state.
+   * W5.7: When pendingOrgType is set, route to ONBOARDING_PENDING instead of COMPLETED.
+   */
+  private async _completeRegistrationSession(session: AuthenticationSession): Promise<AuthenticationSession> {
+    if (session.pendingOrgType) {
+      const updated = await this.updateSession(session.sessionId, {
+        state: AuthenticationSessionState.ONBOARDING_PENDING,
+        nextStep: AuthNextStep.ONBOARDING,
+      });
+      return updated ?? session;
+    }
+
+    const updated = await this.updateSession(session.sessionId, {
+      state: AuthenticationSessionState.COMPLETED,
+      nextStep: AuthNextStep.COMPLETE,
+    });
+    return updated ?? session;
+  }
+
+  /**
+   * W4.3: Complete MFA enrollment during registration pipeline.
+   * Called after the user successfully enrolls an MFA method during registration.
+   * Transitions from MFA_ENROLLMENT_REQUIRED → COMPLETED and issues tokens.
+   */
+  public async completeRegistrationMfaEnrollment(
+    ec: ExecutionContext<any>,
+    sessionId: string,
+  ): Promise<AuthenticationSession> {
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_SESSION_EXPIRED,
+        context: { message: 'Registration session not found or expired' },
+      });
+    }
+
+    if (session.state !== AuthenticationSessionState.MFA_ENROLLMENT_REQUIRED &&
+        session.state !== AuthenticationSessionState.SECOND_FACTOR_IN_PROGRESS) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: `Cannot complete MFA enrollment from state: ${session.state}` },
+      });
+    }
+
+    // W4.9 SEC FIX: Verify that a strong MFA method was actually enrolled before completing
+    if (!session.userId) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: 'Session missing userId — cannot complete MFA enrollment' },
+      });
+    }
+
+    const cred = await this.credentialOps.readByUserId(ec, session.userId);
+    const enrolledMethods = AuthUtils.getEnrolledSecondFactorMethods(cred);
+    const hasStrongFactor = enrolledMethods.some(m => m !== AuthMethod.EMAIL_OTP);
+
+    if (!hasStrongFactor) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: 'No MFA method has been enrolled yet. Complete MFA setup before continuing.' },
+      });
+    }
+
+    if (cred && cred.mfaEnrollmentState !== MfaEnrollmentState.ENROLLED) {
+      await this.credentialOps.updateById(ec, cred._id, { mfaEnrollmentState: MfaEnrollmentState.ENROLLED } as Partial<UserCredentials>);
+    }
+
+    return this._completeRegistrationSession(session);
+  }
+
+  /**
+   * W5.7: Complete org onboarding — create the deferred organization and transition to COMPLETED.
+   * Called by the guidance/onboarding flow after collecting the org name from the user.
+   */
+  public async completeOrgOnboarding(
+    ec: ExecutionContext<any>,
+    sessionId: string,
+    organizationName: string,
+  ): Promise<AuthenticationSession> {
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_SESSION_EXPIRED,
+        context: { message: 'Session not found or expired' },
+      });
+    }
+
+    if (session.state !== AuthenticationSessionState.ONBOARDING_PENDING) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: `Cannot complete org onboarding from state: ${session.state}` },
+      });
+    }
+
+    if (!session.pendingOrgType || !session.userId || !session.email) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: 'Session missing pendingOrgType, userId, or email' },
+      });
+    }
+
+    const trimmedName = organizationName.trim();
+    if (!trimmedName) {
+      throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+        context: { message: 'Organization name is required' },
+      });
+    }
+
+    const orgTypeDef = (this.appConfigService.config as any)?.organizationTypes?.[session.pendingOrgType];
+    const policy = orgTypeDef?.creationPolicy;
+
+    const orgResult = await createOrgOnRegistration(ec, {
+      userId: session.userId,
+      userEmail: session.email,
+      activeUserType: session.activeUserType ?? '',
+      organizationName: trimmedName,
+      organizationTypes: {
+        [session.pendingOrgType]: {
+          creationPolicy: {
+            createOnUserTypeRegistration: [session.activeUserType ?? ''],
+            orgNameSource: 'ask' as const,
+            defaultOwnerRole: policy?.defaultOwnerRole,
+          },
+        },
+      },
+      servicesRegistryHandler: this.servicesRegistryHandler,
+    });
+
+    if (orgResult.created && orgResult.organizationId) {
+      const organizationTypes = (this.appConfigService.config as any)?.organizationTypes;
+      await grantUserTypesOnOrgJoin(ec, {
+        userId: session.userId,
+        organizationId: orgResult.organizationId,
+        organizationTypes,
+        servicesRegistryHandler: this.servicesRegistryHandler,
+      });
+    }
+
+    const updated = await this.updateSession(session.sessionId, {
+      state: AuthenticationSessionState.COMPLETED,
+      nextStep: AuthNextStep.COMPLETE,
+      pendingOrgType: undefined,
+      organizationId: orgResult.organizationId,
+    });
+    return updated ?? session;
+  }
+
+  // ===============================
+  // MAIN AUTHENTICATE DISPATCH
+  // ===============================
+
+  public async authenticate(ec: ExecutionContext<any>, request: AuthenticationRequest): Promise<AuthenticationResponse> {
+    this.logDebug('Main authenticate method called', {
+      sessionId: request.sessionId,
+      method: request.method,
+      factorLevel: request.factorLevel,
+    });
+
+    let authResponse: AuthenticationResponse;
+
+    // Step 1: Dispatch to the method-specific handler.
+    // Capture discriminant before switch to preserve type information for error fallback.
+    const method = request.method;
+    switch (method) {
+      case AuthMethod.PASSWORD: {
+        const session = await this.getSession(request.sessionId);
+        if (!session) {
+          return this.__buildAuthenticationErrorMethod(request.sessionId, request.factorLevel, { retryAllowed: false });
+        }
+
+        const email = session.email;
+        if (!email) {
+          return this.__buildAuthenticationErrorMethod(request.sessionId, request.factorLevel, { retryAllowed: true });
+        }
+
+        try {
+          authResponse = await this.authenticatePassword(ec, request as PasswordAuthRequest);
+        } catch (error) {
+          throw error;
+        }
+        break;
+      }
+
+      case AuthMethod.EMAIL_OTP: {
+        authResponse = await this.authenticateEmailOTP(ec, request as EmailOTPAuthRequest);
+        break;
+      }
+
+      case AuthMethod.TOTP: {
+        authResponse = await this.authenticateTOTP(ec, request as TOTPAuthRequest);
+        break;
+      }
+
+      case AuthMethod.PASSKEY: {
+        authResponse = await this.authenticatePasskey(ec, request as PasskeyAuthRequest);
+        break;
+      }
+
+      case AuthMethod.SMS_OTP: {
+        authResponse = await this.authenticateSMSOTP(ec, request as SMSOTPAuthRequest);
+        break;
+      }
+
+      default:
+        // Unimplemented methods return a clean error.
+        // sessionId and factorLevel exist on BaseAuthRequestSchema — shared by all union variants.
+        return this.__buildAuthenticationErrorMethod(
+          request.sessionId,
+          request.factorLevel ?? AuthFactorLevel.FIRST,
+          { retryAllowed: true },
+        );
+    }
+
+    this.logDebug('Authentication method result', {
+      sessionId: request.sessionId,
+      method: request.method,
+      success: authResponse.success,
+    });
+
+    // Step 2: If method succeeded, check if overall authentication is complete.
+    if (authResponse.success) {
+      const session = await this.getSession(request.sessionId);
+      if (!session) {
+        return this.__buildAuthenticationErrorMethod(request.sessionId, request.factorLevel, { retryAllowed: false });
+      }
+
+      const isComplete = this._isAuthenticationComplete(session, request.factorLevel, request.method);
+
+      if (isComplete) {
+        this.logDebug('Authentication complete, issuing tokens', { sessionId: request.sessionId });
+
+        // S0.7 Layer 1: Re-check user status before token issuance (catches race conditions and all auth paths)
+        if (session.userId) {
+          const currentUser = await this.userLookup.findUserById(ec, session.userId);
+          if (!currentUser || currentUser.status !== UserStatus.ACTIVE) {
+            await this.updateSession(request.sessionId, { state: AuthenticationSessionState.FAILED });
+            this._enforceUserStatus(currentUser || { status: UserStatus.DELETED } as User, request.sessionId);
+          }
+
+          // W3.1b: Validate user-type membership — user's userTypes[] must include the session's activeUserType
+          if (session.activeUserType && currentUser) {
+            const userTypes = (currentUser as User & { userTypes?: string[] }).userTypes ?? [];
+            if (!userTypes.includes(session.activeUserType)) {
+              await this.updateSession(request.sessionId, { state: AuthenticationSessionState.FAILED });
+              throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_TYPE_MISMATCH,
+                context: { message: 'Your account is not registered for this application.', activeUserType: session.activeUserType },
+              });
+            }
+          }
+        }
+
+        // W2.2 + W3.1 + AUTH-14: Password expiry check with org overrides
+        const sessionAuthPolicy = session.userId
+          ? await this._resolveAuthPolicyWithOrgOverrides(ec, session.activeUserType, session.userId)
+          : this._resolveAuthPolicyFromSession(session);
+        const expiryDays = sessionAuthPolicy.passwordPolicy?.expiryDays ?? 0;
+        if (expiryDays > 0 && session.userId) {
+          const expired = await this.credentialOps.isPasswordExpired(ec, session.userId, expiryDays);
+          if (expired) {
+            await this.updateSession(request.sessionId, { state: AuthenticationSessionState.PASSWORD_EXPIRED });
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+              customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_PASSWORD_EXPIRED,
+              context: { sessionId: request.sessionId, reason: 'PASSWORD_EXPIRED' },
+            });
+          }
+        }
+
+        const tokens = await this.tokenIssuer.issueTokens(session, {
+          includeRefreshToken: true,
+          lastAuthenticatedAt: Math.floor(Date.now() / 1000),
+        });
+
+        // Update session to completed
+        await this.updateSession(request.sessionId, { state: AuthenticationSessionState.COMPLETED });
+
+        // Get final session for audit log
+        const finalSession = await this.getSession(request.sessionId);
+        const completedFactors = finalSession?.completedFactors || session.completedFactors || [];
+
+        // Audit log successful authentication (TRAP 13)
+        const deviceInfo = finalSession?.deviceInfo;
+        if (finalSession?.userId) {
+          await this.auditLogsService.logUserLogin({
+            userId: finalSession.userId,
+            email: finalSession.email || 'unknown',
+            authMethod: request.method,
+            ipAddress: deviceInfo?.ipAddress || 'unknown',
+            userAgent: deviceInfo?.userAgent || 'unknown',
+            sessionId: request.sessionId,
+            organizationId: finalSession.organizationId,
+          });
+        }
+
+        // Clean up session after successful authentication
+        await this.removeSession(request.sessionId);
+
+        return this._buildAuthenticationSuccessMethod(
+          request.sessionId,
+          request.factorLevel,
+          request.method,
+          tokens.accessToken,
+          {
+            refreshToken: tokens.refreshToken,
+            completedFactors,
+          },
+        );
+      } else {
+        // Method succeeded but overall auth is not complete (e.g., MFA required)
+        return authResponse;
+      }
+    }
+
+    return authResponse;
+  }
+
+  // ===============================
+  // PUBLIC API: SESSION STATE
+  // ===============================
+
+  /**
+   * Get the current state of an authentication session.
+   *
+   * TRAP 2 (async change): This method is now async because Redis lookups are Promise-based.
+   * The controller must add `await` to this call — this is the one allowed controller modification.
+   */
+  public async getAuthenticationSessionState(ec: ExecutionContext<any>, sessionId: string): Promise<AuthenticationSession | null> {
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      return null;
+    }
+    // Return a copy to avoid external modifications
+    return { ...session };
+  }
+
+  // ===============================
+  // EMAIL OTP AUTHENTICATION (Step 10)
+  // ===============================
+
+  /**
+   * Send an Email OTP to the user's email address.
+   *
+   * Called from the auth controller (POST /auth/mfa/email-otp/send).
+   * Generates a 6-digit OTP, stores it as a consumable token, and returns
+   * the session state. The actual email sending is done by the controller.
+   *
+   * Rate limiting: Redis INCR with TTL. Values from config.auth.otpOperational.
+   */
+  public async sendEmailOTP(ec: ExecutionContext<any>, sessionId: string): Promise<{ otpToken: string; email: string; expiryMinutes: number }> {
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_SESSION_INVALID,
+        context: { sessionId },
+      });
+    }
+
+    // Must have completed first factor before MFA
+    if (session.state !== AuthenticationSessionState.FIRST_FACTOR_COMPLETED &&
+        session.state !== AuthenticationSessionState.MFA_REQUIRED) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: 'First factor authentication must be completed before requesting Email OTP' },
+      });
+    }
+
+    const email = session.email;
+    if (!email) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: 'No email associated with this session' },
+      });
+    }
+
+    const userId = session.userId;
+    if (!userId) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: 'No user associated with this session' },
+      });
+    }
+
+    // Rate limiting — Redis INCR with 60s window. Values from config.auth.otpOperational.
+    const rateLimitKey = `${AUTH_REDIS_KEYS.EMAIL_OTP}${userId}:email_otp`;
+    const currentCount = await this.redisService.incrementRateLimit(rateLimitKey, 60);
+    if (currentCount > this.otpConfig.emailOtp.rateLimitPerMinute) {
+      throw this.errorBuilder.buildError(ErrorType.RATE_LIMIT, undefined, {
+        context: {
+          message: 'Too many OTP requests. Please wait before requesting another code.',
+          retryAfterSeconds: 60,
+        },
+      });
+    }
+
+    // Revoke any existing EMAIL_OTP tokens for this user to ensure only one valid OTP at a time
+    await this.consumableTokenService.revokeTokensByRelatedId(userId, CoreConsumableTokenTypes.EMAIL_OTP);
+
+    // Generate OTP — cryptographically random N-digit code
+    const otpLength = this.otpConfig.emailOtp.otpLength;
+    const otpCode = this._generateOTP(otpLength);
+
+    // Store as consumable token (SINGLE_USE, configurable TTL)
+    const expiryMinutes = this.otpConfig.emailOtp.expiryMinutes;
+    await this.consumableTokenService.createToken({
+      tokenType: CoreConsumableTokenTypes.EMAIL_OTP,
+      consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
+      expiresIn: { value: expiryMinutes, unit: DurationUnit.MINUTES },
+      userId: userId,
+      resourceIdentifier: CoreResourceType.USERS,
+      relatedId: userId,
+      metadata: {
+        otpCode,
+        sessionId,
+        email,
+      },
+    });
+
+    // Update session to MFA_REQUIRED state
+    await this.updateSession(sessionId, {
+      state: AuthenticationSessionState.MFA_REQUIRED,
+      currentFactor: AuthFactorLevel.SECOND,
+    });
+
+    this.logDebug('Email OTP generated and stored', { sessionId, userId });
+
+    return { otpToken: otpCode, email, expiryMinutes };
+  }
+
+  /**
+   * Verify an Email OTP code submitted by the user.
+   *
+   * Called from authenticate() dispatch when method=EMAIL_OTP,
+   * or directly from the auth controller (POST /auth/mfa/email-otp/verify).
+   */
+  public async authenticateEmailOTP(ec: ExecutionContext<any>, request: EmailOTPAuthRequest): Promise<AuthenticationResponse> {
+    const { sessionId, token } = request;
+
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      return this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.SECOND, { retryAllowed: false });
+    }
+
+    // Must be in MFA_REQUIRED, SECOND_FACTOR_IN_PROGRESS, or FIRST_FACTOR_COMPLETED state.
+    // FIRST_FACTOR_COMPLETED is accepted because the MFA flow may not have explicitly
+    // transitioned to MFA_REQUIRED yet (consistent with TOTP which has no "send" step).
+    if (session.state !== AuthenticationSessionState.MFA_REQUIRED &&
+        session.state !== AuthenticationSessionState.SECOND_FACTOR_IN_PROGRESS &&
+        session.state !== AuthenticationSessionState.FIRST_FACTOR_COMPLETED) {
+      return this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.SECOND, {
+        retryAllowed: true,
+      });
+    }
+
+    if (!token) {
+      return this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.SECOND, {
+        retryAllowed: true,
+        authMethod: AuthMethod.EMAIL_OTP,
+      });
+    }
+
+    // Update session to in-progress
+    await this.updateSession(sessionId, {
+      state: AuthenticationSessionState.SECOND_FACTOR_IN_PROGRESS,
+      currentFactor: AuthFactorLevel.SECOND,
+    });
+
+    const userId = session.userId;
+    if (!userId) {
+      return this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.SECOND, { retryAllowed: false });
+    }
+
+    // Find matching consumable token by looking up EMAIL_OTP tokens for this user.
+    // We verify the OTP code matches the stored metadata.
+    const isValid = await this._verifyEmailOTP(userId, sessionId, token);
+
+    if (!isValid) {
+      const { locked } = await this.incrementSessionAttempts(ec, sessionId);
+
+      // Audit log MFA failure
+      const deviceInfo = session.deviceInfo;
+      await this.auditLogsService.logUserLoginFailed({
+        email: session.email || 'unknown',
+        authMethod: AuthMethod.EMAIL_OTP,
+        failureReason: 'Invalid OTP code',
+        ipAddress: deviceInfo?.ipAddress || 'unknown',
+        userAgent: deviceInfo?.userAgent || 'unknown',
+        attemptsRemaining: session.maxAttempts - session.attempts - 1,
+        sessionId,
+      });
+
+      return this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.SECOND, {
+        authMethod: AuthMethod.EMAIL_OTP,
+        retryAllowed: !locked,
+      });
+    }
+
+    // OTP verified — update session
+    await this._updateSessionAfterSuccessfulAuth(ec, sessionId, userId, AuthMethod.EMAIL_OTP);
+
+    const updatedSession = await this.getSession(sessionId);
+    return this._buildAuthenticationSuccessMethod(
+      sessionId,
+      AuthFactorLevel.SECOND,
+      AuthMethod.EMAIL_OTP,
+      '', // Tokens issued by authenticate() after completion check
+      { completedFactors: updatedSession?.completedFactors || [] },
+    );
+  }
+
+  /**
+   * Verify the OTP code against stored consumable tokens for this user and session.
+   * Attempts to consume the token atomically to prevent replay.
+   */
+  private async _verifyEmailOTP(userId: string, sessionId: string, code: string): Promise<boolean> {
+    try {
+      // Find unconsumed EMAIL_OTP tokens for this user
+      const tokens = await this.consumableTokenService.findTokensByRelatedId(
+        userId,
+        CoreConsumableTokenTypes.EMAIL_OTP,
+      );
+
+      for (const tokenDoc of tokens) {
+        const metadata = tokenDoc.metadata as Record<string, unknown> | undefined;
+        if (!metadata?.otpCode || !metadata?.sessionId) continue;
+
+        // L1 fix: constant-time comparison to prevent timing side-channel on OTP
+        const storedCode = String(metadata.otpCode);
+        const storedSession = String(metadata.sessionId);
+        if (storedCode.length !== code.length || storedSession.length !== sessionId.length) continue;
+
+        const codeMatch = crypto.timingSafeEqual(Buffer.from(storedCode), Buffer.from(code));
+        const sessionMatch = crypto.timingSafeEqual(Buffer.from(storedSession), Buffer.from(sessionId));
+
+        if (codeMatch && sessionMatch) {
+          // Consume the token atomically
+          try {
+            await this.consumableTokenService.consumeToken(tokenDoc.token);
+            return true;
+          } catch {
+            // Token already consumed or expired — try next
+            continue;
+          }
+        }
+      }
+
+      return false;
+    } catch (error) {
+      if (isWildoBackendError(error)) {
+        throw error;
+      }
+      this.logger.error('Failed to verify Email OTP', {
+        userId,
+        sessionId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return false;
+    }
+  }
+
+  // ===============================
+  // TOTP AUTHENTICATION (Step 11)
+  // ===============================
+
+  /**
+   * Verify a TOTP code submitted by the user.
+   *
+   * Called from authenticate() dispatch when method=TOTP.
+   * Reads the user's verified TOTP secret from their credential record,
+   * validates the code using the otpauth library.
+   */
+  public async authenticateTOTP(ec: ExecutionContext<any>, request: TOTPAuthRequest): Promise<AuthenticationResponse> {
+    const { sessionId, token } = request;
+
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      return this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.SECOND, { retryAllowed: false });
+    }
+
+    // Must be in MFA_REQUIRED or SECOND_FACTOR_IN_PROGRESS state
+    if (session.state !== AuthenticationSessionState.MFA_REQUIRED &&
+        session.state !== AuthenticationSessionState.SECOND_FACTOR_IN_PROGRESS &&
+        session.state !== AuthenticationSessionState.FIRST_FACTOR_COMPLETED) {
+      return this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.SECOND, {
+        retryAllowed: true,
+      });
+    }
+
+    // Update session to in-progress
+    await this.updateSession(sessionId, {
+      state: AuthenticationSessionState.SECOND_FACTOR_IN_PROGRESS,
+      currentFactor: AuthFactorLevel.SECOND,
+    });
+
+    const userId = session.userId;
+    if (!userId) {
+      return this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.SECOND, { retryAllowed: false });
+    }
+
+    const cred = await this.credentialOps.readByUserId(ec, userId);
+
+    if (!cred || !cred.totpVerified || !cred.secretBase32) {
+      return this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.SECOND, {
+        authMethod: AuthMethod.TOTP,
+        retryAllowed: true,
+      });
+    }
+
+    const { TOTP } = await import('otpauth');
+    const { algorithm, digits, period, window } = this.totpConfig;
+    const totp = new TOTP({
+      secret: cred.secretBase32,
+      algorithm,
+      digits,
+      period,
+    });
+
+    const delta = totp.validate({ token, window });
+    let isValidTOTP = delta !== null;
+
+    // M7 fix: TOTP anti-replay — reject codes at or before the last used time step (RFC 6238 §5.2)
+    // Store the absolute time step counter (current period + delta) instead of relative delta,
+    // so comparisons remain valid across time period boundaries.
+    if (isValidTOTP) {
+      const currentTimeStep = Math.floor(Date.now() / (period * 1000));
+      const absoluteStep = currentTimeStep + delta!;
+      const replayKey = `${AUTH_REDIS_KEYS.TOTP_USED}${userId}`;
+      const lastUsedStep = await this.redisService.get<string>(replayKey);
+      if (lastUsedStep !== null && absoluteStep <= parseInt(lastUsedStep as string, 10)) {
+        isValidTOTP = false;
+      } else {
+        await this.redisService.set(replayKey, String(absoluteStep), { ttl: 90 });
+      }
+    }
+
+    // If TOTP code fails, try backup codes
+    let usedBackupCode = false;
+    if (!isValidTOTP && cred.backupCodesHashed?.length > 0) {
+      const inputHash = crypto.createHash('sha256').update(token).digest('hex');
+      const inputBuf = Buffer.from(inputHash, 'hex');
+
+      // L2 fix: constant-time comparison iterating ALL hashes to prevent timing leak
+      let matchIndex = -1;
+      for (let i = 0; i < cred.backupCodesHashed.length; i++) {
+        const storedBuf = Buffer.from(cred.backupCodesHashed[i], 'hex');
+        if (inputBuf.length === storedBuf.length && crypto.timingSafeEqual(inputBuf, storedBuf)) {
+          matchIndex = i;
+          // Don't break — always compare all to prevent timing leak
+        }
+      }
+
+      if (matchIndex >= 0) {
+        const updatedCodes = [...cred.backupCodesHashed];
+        updatedCodes.splice(matchIndex, 1);
+        await this.credentialOps.updateBackupCodes(ec, cred._id, updatedCodes);
+        usedBackupCode = true;
+      }
+    }
+
+    if (!isValidTOTP && !usedBackupCode) {
+      const { locked } = await this.incrementSessionAttempts(ec, sessionId);
+
+      // Audit log MFA failure
+      const deviceInfo = session.deviceInfo;
+      await this.auditLogsService.logUserLoginFailed({
+        email: session.email || 'unknown',
+        authMethod: AuthMethod.TOTP,
+        failureReason: 'Invalid TOTP code',
+        ipAddress: deviceInfo?.ipAddress || 'unknown',
+        userAgent: deviceInfo?.userAgent || 'unknown',
+        attemptsRemaining: session.maxAttempts - session.attempts - 1,
+        sessionId,
+      });
+
+      return this.__buildAuthenticationErrorMethod(sessionId, AuthFactorLevel.SECOND, {
+        authMethod: AuthMethod.TOTP,
+        retryAllowed: !locked,
+      });
+    }
+
+    // TOTP verified — update session
+    await this._updateSessionAfterSuccessfulAuth(ec, sessionId, userId, AuthMethod.TOTP);
+
+    const updatedSession = await this.getSession(sessionId);
+    return this._buildAuthenticationSuccessMethod(
+      sessionId,
+      AuthFactorLevel.SECOND,
+      AuthMethod.TOTP,
+      '', // Tokens issued by authenticate() after completion check
+      {
+        completedFactors: updatedSession?.completedFactors || [],
+        challengeData: usedBackupCode ? { usedBackupCode: true } : undefined,
+      },
+    );
+  }
+
+  // ===============================
+  // PASSKEY AUTHENTICATION (Phase G1)
+  // ===============================
+
+  /**
+   * Verify a WebAuthn/Passkey authentication response.
+   *
+   * Called from authenticate() dispatch when method=PASSKEY.
+   * Supports both first factor (passwordless) and second factor (MFA) usage.
+   * Delegates to WebAuthnBackendService for cryptographic verification.
+   */
+  public async authenticatePasskey(ec: ExecutionContext<any>, request: PasskeyAuthRequest): Promise<AuthenticationResponse> {
+    const { sessionId, factorLevel, response } = request;
+
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      return this.__buildAuthenticationErrorMethod(sessionId, factorLevel, { retryAllowed: false });
+    }
+
+    // State machine guard — valid states depend on factor level
+    const validStates = factorLevel === AuthFactorLevel.FIRST
+      ? new Set([AuthenticationSessionState.IDENTIFIED, AuthenticationSessionState.FIRST_FACTOR_IN_PROGRESS])
+      : new Set([AuthenticationSessionState.MFA_REQUIRED, AuthenticationSessionState.SECOND_FACTOR_IN_PROGRESS, AuthenticationSessionState.FIRST_FACTOR_COMPLETED]);
+
+    if (!validStates.has(session.state)) {
+      return this.__buildAuthenticationErrorMethod(sessionId, factorLevel, {
+        authMethod: AuthMethod.PASSKEY,
+        retryAllowed: true,
+      });
+    }
+
+    const userId = session.userId;
+    if (!userId) {
+      return this.__buildAuthenticationErrorMethod(sessionId, factorLevel, { retryAllowed: false });
+    }
+
+    // Update session to in-progress
+    await this.updateSession(sessionId, {
+      state: factorLevel === AuthFactorLevel.FIRST
+        ? AuthenticationSessionState.FIRST_FACTOR_IN_PROGRESS
+        : AuthenticationSessionState.SECOND_FACTOR_IN_PROGRESS,
+      currentFactor: factorLevel,
+    });
+
+    // Delegate to WebAuthn service for cryptographic verification
+    let verified = false;
+    let credentialId = response.id;
+    try {
+      const result = await this.webAuthnService.verifyAuthenticationResponse(ec, userId, response as any);
+      verified = result.verified;
+      credentialId = result.credentialId;
+    } catch (error) {
+      this.logger.warn('WebAuthn verification threw an error', {
+        userId,
+        sessionId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      verified = false;
+    }
+
+    if (!verified) {
+      const { locked } = await this.incrementSessionAttempts(ec, sessionId);
+
+      // Audit log passkey auth failure
+      const deviceInfo = session.deviceInfo;
+      await this.auditLogsService.logUserPasskeyAuthFailure({
+        email: session.email || 'unknown',
+        failureReason: 'WebAuthn verification failed',
+        ipAddress: deviceInfo?.ipAddress || 'unknown',
+        userAgent: deviceInfo?.userAgent || 'unknown',
+        sessionId,
+      });
+
+      return this.__buildAuthenticationErrorMethod(sessionId, factorLevel, {
+        authMethod: AuthMethod.PASSKEY,
+        retryAllowed: !locked,
+      });
+    }
+
+    // Passkey verified — audit log success
+    const deviceInfo = session.deviceInfo;
+    await this.auditLogsService.logUserPasskeyAuthSuccess({
+      userId: userId,
+      email: session.email || 'unknown',
+      credentialId,
+      ipAddress: deviceInfo?.ipAddress || 'unknown',
+      userAgent: deviceInfo?.userAgent || 'unknown',
+      sessionId,
+    });
+
+    // C1 fix: Reset global lockout counter on successful authentication
+    if (session.email) {
+      await this._resetGlobalAttempts(session.email);
+    }
+
+    // Update session state
+    await this._updateSessionAfterSuccessfulAuth(ec, sessionId, userId, AuthMethod.PASSKEY);
+
+    const updatedSession = await this.getSession(sessionId);
+    return this._buildAuthenticationSuccessMethod(
+      sessionId,
+      factorLevel,
+      AuthMethod.PASSKEY,
+      '', // Tokens issued by authenticate() after completion check
+      {
+        completedFactors: updatedSession?.completedFactors || [],
+        requiresMFA: updatedSession?.requiresMFA || false,
+        availableMFAMethods: updatedSession?.availableSecondFactorMethods || [],
+        mfaMethodsRequired: updatedSession?.mfaMethodsRequired,
+      },
+    );
+  }
+
+  // ===============================
+  // MFA HELPERS
+  // ===============================
+
+  /**
+   * Determine if MFA is required for this user/session after first-factor success.
+   *
+   * M12+M13 fix: Now checks org-level auth policy in addition to app-level.
+   * Effective policy = max(app_policy, org_policy) — org can only tighten, never weaken.
+   *
+   * Returns true if:
+   * - The effective policy requires MFA for all users, OR
+    * - The effective policy requires MFA for admins, OR
+   * - The org's minimumAuthLevel is 'mfa' or 'sso', OR
+   * - The user has enrolled a verified TOTP secret (user opted in to MFA)
+   */
+  private async _shouldRequireMFA(ec: ExecutionContext<any>, userId: string, organizationId?: string, firstFactorMethod?: AuthMethod, authPolicy?: UserTypeAuthPolicy): Promise<{ required: boolean; enrolledMethods: AuthMethod[] }> {
+    const policy = authPolicy ?? AuthenticationOrchestratorBackendService.FALLBACK_AUTH_POLICY;
+    const mfaPolicy = policy.mfaPolicy;
+    const NOT_REQUIRED = { required: false, enrolledMethods: [] as AuthMethod[] };
+
+    // G1 + W2.5: Passkey exemption — passkeys are multi-factor by nature (possession + biometric/PIN).
+    if (firstFactorMethod === AuthMethod.PASSKEY) {
+      const passkeyExemptFromMFA = mfaPolicy?.passkeyExemptFromMFA ?? true;
+      if (passkeyExemptFromMFA) {
+        return NOT_REQUIRED;
+      }
+    }
+
+    const policyRequiresMFA = !!mfaPolicy?.requireMFA;
+
+    try {
+      const cred = await this.credentialOps.readByUserId(ec, userId);
+
+      const enrolledMethods = AuthUtils.getEnrolledSecondFactorMethods(cred);
+
+      if (policyRequiresMFA) {
+        const hasStrongSecondFactor = enrolledMethods.some(
+          (m) => m !== AuthMethod.EMAIL_OTP,
+        );
+
+        if (hasStrongSecondFactor) {
+          if (cred && cred.mfaEnrollmentState !== MfaEnrollmentState.ENROLLED) {
+            await this.credentialOps.updateById(ec, cred._id, { mfaEnrollmentState: MfaEnrollmentState.ENROLLED } as Partial<UserCredentials>);
+          }
+          return { required: true, enrolledMethods };
+        }
+
+        const graceDays = mfaPolicy?.enrollmentGracePeriodDays ?? 0;
+        if (graceDays > 0 && cred) {
+          if (!cred.firstMfaPromptAt) {
+            await this.credentialOps.updateById(ec, cred._id, { firstMfaPromptAt: new Date(), mfaEnrollmentState: MfaEnrollmentState.GRACE } as Partial<UserCredentials>);
+          } else if (cred.mfaEnrollmentState !== MfaEnrollmentState.GRACE) {
+            await this.credentialOps.updateById(ec, cred._id, { mfaEnrollmentState: MfaEnrollmentState.GRACE } as Partial<UserCredentials>);
+          }
+
+          const graceStart = cred.firstMfaPromptAt ?? new Date();
+          const graceEnd = new Date(graceStart.getTime() + graceDays * 86_400_000);
+          if (new Date() < graceEnd) {
+            return NOT_REQUIRED;
+          }
+
+          await this.credentialOps.updateById(ec, cred._id, { mfaEnrollmentState: MfaEnrollmentState.PENDING } as Partial<UserCredentials>);
+        }
+
+        return { required: true, enrolledMethods };
+      }
+
+      if (cred?.totpVerified) {
+        return { required: true, enrolledMethods };
+      }
+    } catch {
+      if (policyRequiresMFA) {
+        return { required: true, enrolledMethods: [] };
+      }
+    }
+
+    return NOT_REQUIRED;
+  }
+
+  // ===============================
+  // AUTH POLICY MERGE (M13)
+  // ===============================
+
+  // W2.10: _mergeAuthPolicies removed — runtime AuthPolicyBase deprecated.
+  // All MFA requirements now come solely from config (mfaPolicy).
+
+  // ===============================
+  // SSO GRACE LOGIN TRACKING (M14)
+  // ===============================
+
+  /** Redis key prefix for SSO grace login counters — scope-aware format: sso_grace_logins:{scopeType}:{scopeId}:{userId} */
+
+  /**
+   * M14: Check if password login is allowed under SSO grace policy.
+   * If the scope requires SSO and grace logins are exhausted, throws AUTHENTICATION error.
+   */
+  private async _checkSSOGraceLoginAllowed(ec: ExecutionContext<any>, scopeType: AuthScopeType, scopeId: string, userId: string): Promise<void> {
+    try {
+      const ssoConfig = await this.orgConfigService.loadSSOConfig(ec, scopeType, scopeId);
+      if (!ssoConfig) return;
+
+      const { enforcement } = ssoConfig;
+      if (!enforcement.requireSSO) return;
+      if (!enforcement.allowPasswordFallback) {
+        throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_SSO_REQUIRED,
+          context: { message: 'SSO is required. Password login is not allowed.' },
+        });
+      }
+
+      const maxGrace = enforcement.graceLoginAttempts;
+      if (maxGrace <= 0) {
+        throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_SSO_REQUIRED,
+          context: { message: 'SSO is required. Password login grace period exhausted.' },
+        });
+      }
+
+      if (!userId) return;
+
+      const identifier = `${AUTH_REDIS_KEYS.SSO_GRACE_LOGINS}${scopeType}:${scopeId}:${userId}`;
+      const currentCount = await this.redisService.getRateLimitCount(identifier);
+
+      if (currentCount >= maxGrace) {
+        throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_SSO_REQUIRED,
+          context: {
+            message: 'Password login grace period exhausted. Please use SSO.',
+            graceLoginsUsed: currentCount,
+            graceLoginsMax: maxGrace,
+          },
+        });
+      }
+    } catch (error) {
+      if (isWildoBackendError(error)) throw error;
+      this.logDebug('SSO grace login check failed (non-fatal)', {
+        scopeType,
+        scopeId,
+        userId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /** 1 year in seconds — effectively permanent for grace counter, but avoids orphaned keys */
+  private static readonly SSO_GRACE_TTL_SECONDS = 365 * 24 * 60 * 60;
+
+  /**
+   * M14: Atomically increment SSO grace login counter after successful password auth.
+   * Uses Redis INCR (via incrementRateLimit) for atomic increment — no TOCTOU race.
+   * TTL is 1 year (effectively permanent but avoids orphaned keys if scope config changes).
+   */
+  private async _incrementSSOGraceLogin(ec: ExecutionContext<any>, scopeType: AuthScopeType, scopeId: string, userId: string): Promise<void> {
+    try {
+      const ssoConfig = await this.orgConfigService.loadSSOConfig(ec, scopeType, scopeId);
+      if (!ssoConfig?.enforcement.requireSSO) return;
+
+      const identifier = `${AUTH_REDIS_KEYS.SSO_GRACE_LOGINS}${scopeType}:${scopeId}:${userId}`;
+      const newCount = await this.redisService.incrementRateLimit(
+        identifier,
+        AuthenticationOrchestratorBackendService.SSO_GRACE_TTL_SECONDS,
+      );
+
+      this.logDebug('SSO grace login counter incremented', {
+        scopeType,
+        scopeId,
+        userId,
+        graceLoginsUsed: newCount,
+        graceLoginsMax: ssoConfig.enforcement.graceLoginAttempts,
+      });
+    } catch {
+      // Non-fatal — don't block auth if counter update fails
+    }
+  }
+
+  // ===============================
+  // MAGIC LINK (Phase G2)
+  // ===============================
+
+  /**
+   * Send a magic link email to the user.
+   * Anti-enumeration: always returns success regardless of whether the user exists.
+   * Rate limited per email.
+   */
+  public async sendMagicLink(ec: ExecutionContext<any>, request: MagicLinkSendRequest, deviceInfo?: { ipAddress?: string; userAgent?: string }): Promise<{ success: true; token?: string; email?: string; userId?: string; expiresInMinutes?: number }> {
+    if (!this._isMethodEnabledGlobally(AuthMethod.MAGIC_LINK)) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: 'Magic link authentication is not enabled' },
+      });
+    }
+
+    const { email } = request;
+
+    // Rate limiting — dual window (per minute + per hour)
+    await this.rateLimitService.checkRateLimit(
+      `${AUTH_REDIS_KEYS.MAGIC_LINK_MIN}${email}:min`,
+      this.magicLinkConfig.rateLimitPerMinute,
+      60
+    );
+    await this.rateLimitService.checkRateLimit(
+      `${AUTH_REDIS_KEYS.MAGIC_LINK_MIN}${email}:hour`,
+      this.magicLinkConfig.rateLimitPerHour,
+      3600
+    );
+
+    // Look up the user (same pattern as identify())
+    let user: User | null = null;
+    try {
+      user = await this.userLookup.findUserByEmail(ec, email);
+    } catch {
+      // Suppress — anti-enumeration (also covers non-active users)
+    }
+
+    // Audit the send (even if user doesn't exist or is inactive)
+    await this.auditLogsService.logMagicLinkSent({
+      email,
+      ipAddress: deviceInfo?.ipAddress || 'unknown',
+      userAgent: deviceInfo?.userAgent || 'unknown',
+    });
+
+    // If user doesn't exist or is not active, return success silently (anti-enumeration)
+    if (!user) {
+      return { success: true };
+    }
+
+    const userId = user._id;
+
+    // Revoke any existing MAGIC_LINK tokens for this user
+    await this.consumableTokenService.revokeTokensByRelatedId(userId, CoreConsumableTokenTypes.MAGIC_LINK);
+
+    // Store as consumable token (createToken auto-generates a crypto-random token value)
+    const createdToken = await this.consumableTokenService.createToken({
+      tokenType: CoreConsumableTokenTypes.MAGIC_LINK,
+      consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
+      expiresIn: { value: this.magicLinkConfig.tokenExpiryMinutes, unit: DurationUnit.MINUTES },
+      userId: userId,
+      resourceIdentifier: CoreResourceType.USERS,
+      relatedId: userId,
+      metadata: { email },
+    });
+
+    this.logDebug('Magic link token created', { email, userId });
+
+    return { success: true, token: createdToken.token, email, userId, expiresInMinutes: this.magicLinkConfig.tokenExpiryMinutes };
+  }
+
+  /**
+   * Verify a magic link token.
+   * Returns an auth response with tokens on success.
+   */
+  public async verifyMagicLink(ec: ExecutionContext<any>, request: MagicLinkVerifyRequest, deviceInfo?: { ipAddress?: string; userAgent?: string }, activeUserType?: string): Promise<AuthenticationResponse> {
+    if (!this._isMethodEnabledGlobally(AuthMethod.MAGIC_LINK)) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: 'Magic link authentication is not enabled' },
+      });
+    }
+
+    const { token } = request;
+
+    // Validate the token (checks expiry, revocation, consumption)
+    let validatedToken: Awaited<ReturnType<typeof this.consumableTokenService.validateToken>> | null = null;
+    try {
+      validatedToken = await this.consumableTokenService.validateToken(token, [CoreConsumableTokenTypes.MAGIC_LINK]);
+    } catch {
+      // Token invalid, expired, or already consumed
+    }
+
+    if (!validatedToken) {
+      await this.auditLogsService.logMagicLinkFailed({
+        failureReason: 'Invalid or expired magic link token',
+        ipAddress: deviceInfo?.ipAddress || 'unknown',
+        userAgent: deviceInfo?.userAgent || 'unknown',
+      });
+
+      return {
+        success: false,
+        sessionId: '',
+        userExists: false,
+        factorLevel: AuthFactorLevel.FIRST,
+        authMethod: AuthMethod.MAGIC_LINK,
+        error: 'Invalid or expired magic link',
+        errorCode: 'MAGIC_LINK_INVALID',
+        retryAllowed: false,
+        integrationTokens: [],
+        requiresMFA: false,
+      } as AuthenticationResponse;
+    }
+
+    // Consume the token atomically — wrap in try/catch for concurrent double-click race
+    try {
+      await this.consumableTokenService.consumeToken(token);
+    } catch {
+      // Token already consumed by concurrent request — return same error as invalid token
+      await this.auditLogsService.logMagicLinkFailed({
+        failureReason: 'Magic link token already consumed (concurrent request)',
+        ipAddress: deviceInfo?.ipAddress || 'unknown',
+        userAgent: deviceInfo?.userAgent || 'unknown',
+      });
+      return {
+        success: false,
+        sessionId: '',
+        userExists: false,
+        factorLevel: AuthFactorLevel.FIRST,
+        authMethod: AuthMethod.MAGIC_LINK,
+        error: 'Invalid or expired magic link',
+        errorCode: 'MAGIC_LINK_INVALID',
+        retryAllowed: false,
+        integrationTokens: [],
+        requiresMFA: false,
+      } as AuthenticationResponse;
+    }
+
+    const userId = validatedToken.relatedId;
+    if (!userId) {
+      await this.auditLogsService.logMagicLinkFailed({
+        failureReason: 'Magic link token has no associated user',
+        ipAddress: deviceInfo?.ipAddress || 'unknown',
+        userAgent: deviceInfo?.userAgent || 'unknown',
+      });
+      return {
+        success: false,
+        sessionId: '',
+        userExists: false,
+        factorLevel: AuthFactorLevel.FIRST,
+        authMethod: AuthMethod.MAGIC_LINK,
+        error: 'Invalid magic link token',
+        errorCode: 'MAGIC_LINK_INVALID',
+        retryAllowed: false,
+        integrationTokens: [],
+        requiresMFA: false,
+      } as AuthenticationResponse;
+    }
+    const tokenMetadata = validatedToken.metadata as Record<string, unknown> | undefined;
+    const email = tokenMetadata?.email as string;
+
+    // Defense-in-depth: constant-time compare request email vs token email.
+    // Prevents URL-tampering attacks where an attacker changes the email in the
+    // magic link URL while keeping a stolen/intercepted token value.
+    if (!email) {
+      this.logger.warn('Magic link token metadata missing email — token integrity issue', {
+        userId,
+        tokenType: CoreConsumableTokenTypes.MAGIC_LINK,
+      });
+      await this.auditLogsService.logMagicLinkFailed({
+        failureReason: 'Token metadata missing email (data integrity issue)',
+        ipAddress: deviceInfo?.ipAddress || 'unknown',
+        userAgent: deviceInfo?.userAgent || 'unknown',
+      });
+      return {
+        success: false,
+        sessionId: '',
+        userExists: false,
+        factorLevel: AuthFactorLevel.FIRST,
+        authMethod: AuthMethod.MAGIC_LINK,
+        error: 'Invalid or expired magic link',
+        errorCode: 'MAGIC_LINK_INVALID',
+        retryAllowed: false,
+        integrationTokens: [],
+        requiresMFA: false,
+      } as AuthenticationResponse;
+    }
+
+    const tokenEmailBuf = Buffer.from(email.toLowerCase());
+    const requestEmailBuf = Buffer.from(request.email.toLowerCase());
+    if (tokenEmailBuf.length !== requestEmailBuf.length || !crypto.timingSafeEqual(tokenEmailBuf, requestEmailBuf)) {
+      this.logger.warn('Magic link email mismatch — possible URL tampering or token theft', {
+        userId,
+        requestEmail: request.email,
+      });
+      await this.auditLogsService.logMagicLinkFailed({
+        failureReason: 'Email mismatch between request and token',
+        ipAddress: deviceInfo?.ipAddress || 'unknown',
+        userAgent: deviceInfo?.userAgent || 'unknown',
+      });
+      return {
+        success: false,
+        sessionId: '',
+        userExists: false,
+        factorLevel: AuthFactorLevel.FIRST,
+        authMethod: AuthMethod.MAGIC_LINK,
+        error: 'Invalid or expired magic link',
+        errorCode: 'MAGIC_LINK_INVALID',
+        retryAllowed: false,
+        integrationTokens: [],
+        requiresMFA: false,
+      } as AuthenticationResponse;
+    }
+
+    // Load the user
+    let user: User | null = null;
+    try {
+      user = await this.userLookup.findUserById(ec, userId);
+    } catch {
+      // Suppress
+    }
+
+    if (!user) {
+      return {
+        success: false,
+        sessionId: '',
+        userExists: false,
+        factorLevel: AuthFactorLevel.FIRST,
+        authMethod: AuthMethod.MAGIC_LINK,
+        error: 'User not found',
+        errorCode: 'USER_NOT_FOUND',
+        retryAllowed: false,
+        integrationTokens: [],
+        requiresMFA: false,
+      } as AuthenticationResponse;
+    }
+
+    // Verify user is active — reject suspended/locked/pending users
+    const userStatus = (user as Record<string, unknown>).status as string | undefined;
+    if (userStatus && userStatus !== UserStatus.ACTIVE) {
+      await this.auditLogsService.logMagicLinkFailed({
+        failureReason: `Account is not active (status: ${userStatus})`,
+        ipAddress: deviceInfo?.ipAddress || 'unknown',
+        userAgent: deviceInfo?.userAgent || 'unknown',
+      });
+      return {
+        success: false,
+        sessionId: '',
+        userExists: true,
+        factorLevel: AuthFactorLevel.FIRST,
+        authMethod: AuthMethod.MAGIC_LINK,
+        error: 'Account is not active',
+        errorCode: 'ACCOUNT_INACTIVE',
+        retryAllowed: false,
+        integrationTokens: [],
+        requiresMFA: false,
+      } as AuthenticationResponse;
+    }
+
+    // Resolve scope via domain lookup (mirrors identify() pattern)
+    let resolvedOrganizationId: string | undefined;
+    if (email) {
+      const emailDomain = email.split('@')[1]?.toLowerCase();
+      if (emailDomain) {
+        try {
+          const domainOrgLookup = await this.domainToOrgLookup.findOrgByDomain(ec, emailDomain);
+          resolvedOrganizationId = domainOrgLookup?.scopeId;
+        } catch {
+          this.logDebug('Domain-to-org lookup failed during magic link verify (non-fatal)', { emailDomain });
+        }
+      }
+    }
+
+    // Create a session for this auth flow
+    const sessionId = this.sessionStore.generateSessionId();
+    await this.createSession(sessionId, AuthenticationSessionState.FIRST_FACTOR_COMPLETED, {
+      deviceInfo,
+      activeUserType,
+    });
+
+    // Update session with user info (including organizationId for downstream MFA/SSO checks)
+    await this.updateSession(sessionId, {
+      email,
+      userExists: true,
+      userId: userId,
+      completedFactors: [AuthMethod.MAGIC_LINK],
+      currentFactor: AuthFactorLevel.FIRST,
+      organizationId: resolvedOrganizationId,
+    });
+
+    // Audit success
+    await this.auditLogsService.logMagicLinkVerified({
+      userId: userId,
+      email,
+      sessionId,
+      ipAddress: deviceInfo?.ipAddress || 'unknown',
+      userAgent: deviceInfo?.userAgent || 'unknown',
+    });
+
+    // Reset global lockout counter — magic link proves email ownership (high assurance)
+    if (email) {
+      await this._resetGlobalAttempts(email);
+    }
+
+    // AUTH-14: Use org-override-aware policy for magic link flows
+    const magicLinkPolicy = await this._resolveAuthPolicyWithOrgOverrides(ec, activeUserType, userId);
+    const mfaCheck = await this._shouldRequireMFA(ec, userId, resolvedOrganizationId, AuthMethod.MAGIC_LINK, magicLinkPolicy);
+
+    if (mfaCheck.required) {
+      const mfaResolution = await this._resolveUsableMfaMethods(mfaCheck.enrolledMethods, magicLinkPolicy);
+
+      await this.updateSession(sessionId, {
+        state: AuthenticationSessionState.MFA_REQUIRED,
+        requiresMFA: true,
+        requireStrongMFA: mfaResolution.requireStrongMFA,
+        availableSecondFactorMethods: mfaResolution.availableMethods,
+        enrolledSecondFactorMethods: mfaCheck.enrolledMethods,
+        usableSecondFactorMethods: mfaResolution.usableMethods,
+      });
+
+      return {
+        success: false,
+        sessionId,
+        userExists: true,
+        factorLevel: AuthFactorLevel.FIRST,
+        authMethod: AuthMethod.MAGIC_LINK,
+        requiresMFA: true,
+        availableMFAMethods: mfaResolution.availableMethods,
+        mfaMethodsRequired: AuthenticationOrchestratorBackendService.DEFAULT_MFA_METHODS_REQUIRED,
+        enrolledSecondFactorMethods: mfaCheck.enrolledMethods,
+        usableSecondFactorMethods: mfaResolution.usableMethods,
+        completedFactors: [AuthMethod.MAGIC_LINK],
+        retryAllowed: true,
+        integrationTokens: [],
+      } as AuthenticationResponse;
+    }
+
+    // Complete authentication — issue tokens
+    await this.updateSession(sessionId, {
+      state: AuthenticationSessionState.COMPLETED,
+    });
+
+    const updatedSession = await this.getSession(sessionId);
+    if (!updatedSession) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: 'Session lost after magic link verification' },
+      });
+    }
+
+    const tokens = await this.tokenIssuer.issueTokens(updatedSession, {
+      includeRefreshToken: true,
+      lastAuthenticatedAt: Math.floor(Date.now() / 1000),
+    });
+
+    // Audit login
+    await this.auditLogsService.logUserLogin({
+      userId: userId,
+      ipAddress: deviceInfo?.ipAddress || 'unknown',
+      userAgent: deviceInfo?.userAgent || 'unknown',
+      authMethod: AuthMethod.MAGIC_LINK,
+      email,
+      sessionId,
+    });
+
+    // Clean up session
+    await this.removeSession(sessionId);
+
+    return this._buildAuthenticationSuccessMethod(
+      sessionId,
+      AuthFactorLevel.FIRST,
+      AuthMethod.MAGIC_LINK,
+      tokens.accessToken,
+      {
+        refreshToken: tokens.refreshToken,
+        completedFactors: [AuthMethod.MAGIC_LINK],
+      },
+    );
+  }
+
+  // ===============================
+  // SMS OTP (Phase G2)
+  // ===============================
+
+  /**
+   * Send an SMS OTP code to the user's verified phone number.
+   * Can be used as first factor or second factor depending on config.
+   * Rate limited with dual-window (burst + hourly).
+   */
+  public async sendSMSOTP(ec: ExecutionContext<any>, sessionId: string, phoneNumber?: string): Promise<{ sent: true; otpCode: string; targetPhone: string }> {
+    if (!this._isMethodEnabledGlobally(AuthMethod.SMS_OTP)) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: 'SMS OTP authentication is not enabled' },
+      });
+    }
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_SESSION_INVALID,
+        context: { sessionId },
+      });
+    }
+
+    // Validate session state — allow states valid for first-factor or second-factor OTP send
+    const validSendStates = [
+      AuthenticationSessionState.IDENTIFIED,
+      AuthenticationSessionState.FIRST_FACTOR_IN_PROGRESS,
+      AuthenticationSessionState.FIRST_FACTOR_COMPLETED,
+      AuthenticationSessionState.MFA_REQUIRED,
+    ];
+    if (!validSendStates.includes(session.state as AuthenticationSessionState)) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: 'Session is not in a valid state for SMS OTP send' },
+      });
+    }
+
+    // Determine the phone number to send to
+    let targetPhone = phoneNumber;
+
+    if (!targetPhone) {
+      const userId = session.userId;
+      if (userId) {
+        try {
+          targetPhone = await this.credentialOps.getVerifiedPhone(ec, userId);
+        } catch {
+          // Suppress
+        }
+      }
+    }
+
+    if (!targetPhone) {
+      throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+        context: { message: 'No verified phone number available for SMS OTP' },
+      });
+    }
+
+    // Dual-window rate limiting
+    await this.rateLimitService.checkRateLimit(
+      `${AUTH_REDIS_KEYS.SMS_OTP_BURST}${targetPhone}:burst`,
+      this.otpConfig.smsOtp.rateLimitBurst,
+      60
+    );
+    await this.rateLimitService.checkRateLimit(
+      `${AUTH_REDIS_KEYS.SMS_OTP_BURST}${targetPhone}:hourly`,
+      this.otpConfig.smsOtp.rateLimitHourly,
+      3600
+    );
+
+    const userId = session.userId;
+    if (userId) {
+      // Revoke existing SMS_OTP tokens
+      await this.consumableTokenService.revokeTokensByRelatedId(userId, CoreConsumableTokenTypes.SMS_OTP);
+    }
+
+    // Generate OTP code
+    const otpCode = this._generateOTP(this.otpConfig.smsOtp.otpLength);
+
+    // Store as consumable token
+    await this.consumableTokenService.createToken({
+      tokenType: CoreConsumableTokenTypes.SMS_OTP,
+      consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
+      expiresIn: { value: this.otpConfig.smsOtp.expiryMinutes, unit: DurationUnit.MINUTES },
+      userId: userId,
+      resourceIdentifier: CoreResourceType.USERS,
+      relatedId: userId || targetPhone,
+      metadata: {
+        otpCode,
+        sessionId,
+        phoneNumber: targetPhone,
+      },
+    });
+
+    // Audit
+    await this.auditLogsService.logSMSOTPSent({
+      phoneNumber: targetPhone,
+      factorLevel: session.currentFactor || AuthFactorLevel.FIRST,
+      sessionId,
+      ipAddress: session.deviceInfo?.ipAddress || 'unknown',
+      userAgent: session.deviceInfo?.userAgent || 'unknown',
+    });
+
+    // Update session state to reflect pending OTP verification
+    const isSecondFactor = session.state === AuthenticationSessionState.FIRST_FACTOR_COMPLETED
+      || session.state === AuthenticationSessionState.MFA_REQUIRED;
+    await this.updateSession(sessionId, {
+      state: isSecondFactor
+        ? AuthenticationSessionState.MFA_REQUIRED
+        : AuthenticationSessionState.FIRST_FACTOR_IN_PROGRESS,
+      currentFactor: isSecondFactor ? AuthFactorLevel.SECOND : AuthFactorLevel.FIRST,
+    });
+
+    this.logDebug('SMS OTP generated', { sessionId, phoneNumber: targetPhone });
+
+    return { sent: true, otpCode, targetPhone };
+  }
+
+  /**
+   * Verify an SMS OTP code. Supports both first and second factor.
+   * Called from authenticate() dispatch — does NOT issue tokens (authenticate() handles completion).
+   * Uses constant-time comparison for the OTP code.
+   */
+  public async authenticateSMSOTP(ec: ExecutionContext<any>, request: SMSOTPAuthRequest): Promise<AuthenticationResponse> {
+    if (!this._isMethodEnabledGlobally(AuthMethod.SMS_OTP)) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: 'SMS OTP authentication is not enabled' },
+      });
+    }
+
+    const { sessionId, token, factorLevel } = request;
+
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      return this.__buildAuthenticationErrorMethod(sessionId, factorLevel, { retryAllowed: false });
+    }
+
+    // Allow-list: SMS OTP can be first or second factor, so accept states valid for either.
+    // Reject unexpected states (COMPLETED, LOCKED, CREATED) to prevent replay or abuse.
+    const validSMSOTPStates = [
+      AuthenticationSessionState.IDENTIFIED,
+      AuthenticationSessionState.FIRST_FACTOR_IN_PROGRESS,
+      AuthenticationSessionState.FIRST_FACTOR_COMPLETED,
+      AuthenticationSessionState.MFA_REQUIRED,
+      AuthenticationSessionState.SECOND_FACTOR_IN_PROGRESS,
+    ];
+    if (!validSMSOTPStates.includes(session.state as AuthenticationSessionState)) {
+      return this.__buildAuthenticationErrorMethod(sessionId, factorLevel, {
+        retryAllowed: false,
+        authMethod: AuthMethod.SMS_OTP,
+      });
+    }
+
+    if (!token) {
+      return this.__buildAuthenticationErrorMethod(sessionId, factorLevel, {
+        retryAllowed: true,
+        authMethod: AuthMethod.SMS_OTP,
+      });
+    }
+
+    // Update session to in-progress
+    const inProgressState = factorLevel === AuthFactorLevel.SECOND
+      ? AuthenticationSessionState.SECOND_FACTOR_IN_PROGRESS
+      : AuthenticationSessionState.FIRST_FACTOR_IN_PROGRESS;
+    await this.updateSession(sessionId, {
+      state: inProgressState,
+      currentFactor: factorLevel,
+    });
+
+    const userId = session.userId;
+    if (!userId) {
+      return this.__buildAuthenticationErrorMethod(sessionId, factorLevel, { retryAllowed: false });
+    }
+
+    // Find matching SMS_OTP token and verify with constant-time comparison
+    const isValid = await this._verifySMSOTP(userId, sessionId, token);
+
+    if (!isValid) {
+      const { locked } = await this.incrementSessionAttempts(ec, sessionId);
+
+      await this.auditLogsService.logSMSOTPFailed({
+        phoneNumber: request.phoneNumber,
+        factorLevel,
+        failureReason: locked ? 'Account locked after too many attempts' : 'Invalid OTP code',
+        sessionId,
+        ipAddress: session.deviceInfo?.ipAddress || 'unknown',
+        userAgent: session.deviceInfo?.userAgent || 'unknown',
+      });
+
+      return this.__buildAuthenticationErrorMethod(sessionId, factorLevel, {
+        retryAllowed: !locked,
+        authMethod: AuthMethod.SMS_OTP,
+      });
+    }
+
+    // Audit success
+    await this.auditLogsService.logSMSOTPVerified({
+      userId: userId,
+      phoneNumber: request.phoneNumber || 'unknown',
+      factorLevel,
+      sessionId,
+      ipAddress: session.deviceInfo?.ipAddress || 'unknown',
+      userAgent: session.deviceInfo?.userAgent || 'unknown',
+    });
+
+    // Update session (mirrors authenticateEmailOTP pattern)
+    await this._updateSessionAfterSuccessfulAuth(ec, sessionId, userId, AuthMethod.SMS_OTP);
+
+    const updatedSession = await this.getSession(sessionId);
+    return this._buildAuthenticationSuccessMethod(
+      sessionId,
+      factorLevel,
+      AuthMethod.SMS_OTP,
+      '', // Tokens issued by authenticate() after completion check
+      { completedFactors: updatedSession?.completedFactors || [] },
+    );
+  }
+
+  /**
+   * Verify an SMS OTP code using constant-time comparison.
+   * Mirrors the _verifyEmailOTP pattern.
+   */
+  private async _verifySMSOTP(userId: string, sessionId: string, submittedCode: string): Promise<boolean> {
+    try {
+      const tokens = await this.consumableTokenService.findTokensByRelatedId(
+        userId,
+        CoreConsumableTokenTypes.SMS_OTP,
+      );
+
+      for (const tokenDoc of tokens) {
+        const metadata = tokenDoc.metadata as Record<string, unknown> | undefined;
+        if (!metadata?.otpCode || !metadata?.sessionId) continue;
+
+        const storedCode = String(metadata.otpCode);
+        const storedSession = String(metadata.sessionId);
+        if (storedCode.length !== submittedCode.length || storedSession.length !== sessionId.length) continue;
+
+        const codeMatch = crypto.timingSafeEqual(Buffer.from(storedCode), Buffer.from(submittedCode));
+        const sessionMatch = crypto.timingSafeEqual(Buffer.from(storedSession), Buffer.from(sessionId));
+
+        if (codeMatch && sessionMatch) {
+          try {
+            await this.consumableTokenService.consumeToken(tokenDoc.token);
+            return true;
+          } catch {
+            continue;
+          }
+        }
+      }
+
+      return false;
+    } catch (error) {
+      if (isWildoBackendError(error)) {
+        throw error;
+      }
+      this.logger.error('Failed to verify SMS OTP', {
+        userId,
+        sessionId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return false;
+    }
+  }
+
+  /**
+   * Generate a cryptographically random N-digit numeric OTP.
+   */
+  private _generateOTP(length: number): string {
+    const max = Math.pow(10, length);
+    const min = Math.pow(10, length - 1);
+    // Use crypto.randomInt for unbiased random number generation
+    const { randomInt } = crypto;
+    return String(randomInt(min, max));
+  }
+
+  // ===============================
+  // COMPLETION LOGIC
+  // ===============================
+
+  private _isAuthenticationComplete(
+    session: AuthenticationSession,
+    currentFactorLevel: AuthFactorLevel,
+    authMethod: AuthMethod,
+  ): boolean {
+    const completedFactors = session.completedFactors || [];
+
+    const hasFirstFactor = completedFactors.some((factor) => AuthUtils.canBeFirstFactor(factor));
+    const hasSecondFactor = completedFactors.some((factor) => AuthUtils.canBeSecondFactor(factor));
+
+    switch (currentFactorLevel) {
+      case AuthFactorLevel.FIRST:
+        // If MFA is required for this session (set during first-factor success based on
+        // app MFA policy + user's enrolled second-factor methods), first factor alone is not enough.
+        if (session.requiresMFA) {
+          return false;
+        }
+        return session.state === AuthenticationSessionState.FIRST_FACTOR_COMPLETED && hasFirstFactor;
+      case AuthFactorLevel.SECOND:
+        return hasFirstFactor && hasSecondFactor && completedFactors.length >= 2;
+      default:
+        return false;
+    }
+  }
+
+  // ===============================
+  // RESPONSE BUILDERS
+  // ===============================
+
+  private _buildIdentificationErrorResponse(
+    sessionId: string,
+    factorLevel: AuthFactorLevel,
+    retryAllowed: boolean = true,
+    session?: AuthenticationSession | null,
+  ): AuthenticationResponse {
+    return AuthenticationResponseSchema.parse({
+      success: false,
+      sessionId,
+      userExists: session?.userExists ?? false,
+      factorLevel,
+      retryAllowed,
+      remainingAttempts: session ? session.maxAttempts - session.attempts : undefined,
+      lockoutUntil: session?.lockoutUntil,
+      requiresMFA: false,
+      integrationTokens: [],
+    });
+  }
+
+  private _buildAuthenticationSuccessMethod(
+    sessionId: string,
+    factorLevel: AuthFactorLevel,
+    authMethod: AuthMethod,
+    accessToken: string,
+    options: {
+      refreshToken?: string;
+      expiresIn?: number;
+      user?: any;
+      integrationTokens?: Array<{
+        integrationId: string;
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn?: number;
+        scopes: string[];
+      }>;
+      requiresMFA?: boolean;
+      availableMFAMethods?: AvailableMethod[];
+      mfaMethodsRequired?: number;
+      enrolledSecondFactorMethods?: AuthMethod[];
+      usableSecondFactorMethods?: AuthMethod[];
+      completedFactors?: AuthMethod[];
+      challengeData?: Record<string, any>;
+      redirectUrl?: string;
+      nextStep?: string;
+      availableEnrollmentMethods?: AuthMethod[];
+    } = {},
+  ): AuthenticationResponse {
+    return AuthenticationResponseSchema.parse({
+      success: !options.requiresMFA,
+      sessionId,
+      userExists: true,
+      factorLevel,
+      authMethod,
+      accessToken,
+      refreshToken: options.refreshToken,
+      expiresIn: options.expiresIn,
+      user: options.user,
+      integrationTokens: options.integrationTokens || [],
+      requiresMFA: options.requiresMFA || false,
+      availableMFAMethods: options.availableMFAMethods,
+      mfaMethodsRequired: options.mfaMethodsRequired,
+      enrolledSecondFactorMethods: options.enrolledSecondFactorMethods || [],
+      usableSecondFactorMethods: options.usableSecondFactorMethods || [],
+      completedFactors: options.completedFactors || [authMethod],
+      retryAllowed: true,
+      challengeData: options.challengeData,
+      redirectUrl: options.redirectUrl,
+      nextStep: options.nextStep,
+      availableEnrollmentMethods: options.availableEnrollmentMethods || [],
+    });
+  }
+
+  private __buildAuthenticationErrorMethod(
+    sessionId: string,
+    factorLevel: AuthFactorLevel,
+    options: {
+      authMethod?: AuthMethod;
+      retryAllowed?: boolean;
+      remainingAttempts?: number;
+      lockoutUntil?: Date;
+      requiresMFA?: boolean;
+      availableMFAMethods?: AvailableMethod[];
+      mfaMethodsRequired?: number;
+      completedFactors?: AuthMethod[];
+      challengeData?: Record<string, any>;
+      redirectUrl?: string;
+    } = {},
+  ): AuthenticationResponse {
+    // Note: we don't call getSession here synchronously because this is used in sync error builders.
+    // The session data is passed through options when available.
+    return AuthenticationResponseSchema.parse({
+      success: false,
+      sessionId,
+      userExists: false,
+      factorLevel,
+      authMethod: options.authMethod,
+      retryAllowed: options.retryAllowed ?? true,
+      remainingAttempts: options.remainingAttempts,
+      lockoutUntil: options.lockoutUntil,
+      requiresMFA: options.requiresMFA ?? false,
+      availableMFAMethods: options.availableMFAMethods,
+      mfaMethodsRequired: options.mfaMethodsRequired,
+      completedFactors: options.completedFactors || [],
+      integrationTokens: [],
+      challengeData: options.challengeData,
+      redirectUrl: options.redirectUrl,
+    });
+  }
+
+  private async _buildAvailableMethodObject(
+    ec: ExecutionContext<any> | undefined,
+    method: AuthMethod,
+    domainOrgLookup?: DomainOrgLookupResult | null,
+    authPolicy?: UserTypeAuthPolicy,
+  ): Promise<AvailableMethod | null> {
+    const globalAuth = this.appConfigService.config.auth;
+    const policy = authPolicy ?? AuthenticationOrchestratorBackendService.FALLBACK_AUTH_POLICY;
+
+    const isEnabled = policy.authMethodsEnabled[method];
+    if (!isEnabled) {
+      return null;
+    }
+
+    const factorType = AuthUtils.getFactorType(method);
+    const category = AuthUtils.getMethodCategory(method);
+    const canBeFirstFactor = AuthUtils.canBeFirstFactor(method);
+    const canBeSecondFactor = AuthUtils.canBeSecondFactor(method);
+    const organizationRestricted = AuthUtils.isOrganizationRestricted(method);
+    const supportsIntegrations = AuthUtils.supportsIntegrationAccess(method);
+
+    let required = false;
+    if (canBeSecondFactor && policy.mfaPolicy.requireMFA) {
+      required = true;
+    }
+    let oauth2ProviderRefs: string[] = [];
+    let ssoIds: string[] = [];
+    let availableIntegrations: string[] = [];
+    let config: Record<string, any> | undefined;
+
+    switch (method) {
+      case AuthMethod.EXTERNAL_OAUTH2: {
+        let oauth2Providers = Object.keys(globalAuth.ssoProviders || {});
+        if (domainOrgLookup && ec) {
+          oauth2Providers = await this.oauth2Resolver.filterProviders(
+            ec,
+            domainOrgLookup.scopeType,
+            domainOrgLookup.scopeId,
+            oauth2Providers,
+          );
+        }
+        if (oauth2Providers.length === 0) return null;
+        availableIntegrations = oauth2Providers;
+        oauth2ProviderRefs = oauth2Providers;
+        break;
+      }
+      case AuthMethod.MAGIC_LINK:
+      case AuthMethod.SMS_OTP:
+        break;
+      case AuthMethod.PASSKEY:
+        config = globalAuth.passkeyConfig
+          ? { rpName: globalAuth.passkeyConfig.rpName, rpId: globalAuth.passkeyConfig.rpId }
+          : undefined;
+        break;
+      case AuthMethod.ORG_OPENID_CONNECT: {
+        if (!domainOrgLookup || domainOrgLookup.matchedProviderType !== 'oidc') {
+          return null;
+        }
+        const providerInfo = this.domainToOrgLookup.getSSOProviderInfo(domainOrgLookup);
+        if (!providerInfo) return null;
+        ssoIds = [providerInfo.connectionId];
+        config = {
+          displayName: providerInfo.displayName,
+          providerRef: providerInfo.providerRef,
+          connectionId: providerInfo.connectionId,
+          scopeType: domainOrgLookup.scopeType,
+          scopeId: domainOrgLookup.scopeId,
+          organizationId: domainOrgLookup.organizationId,
+        };
+        if (domainOrgLookup.enforcement?.requireSSO) {
+          required = true;
+        }
+        break;
+      }
+      case AuthMethod.ORG_SAML: {
+        if (!domainOrgLookup || domainOrgLookup.matchedProviderType !== 'saml') {
+          return null;
+        }
+        const samlProviderInfo = this.domainToOrgLookup.getSSOProviderInfo(domainOrgLookup);
+        if (!samlProviderInfo) return null;
+        ssoIds = [samlProviderInfo.connectionId];
+        config = {
+          displayName: samlProviderInfo.displayName,
+          providerRef: samlProviderInfo.providerRef,
+          connectionId: samlProviderInfo.connectionId,
+          loginUrl: `/auth/saml/login/${samlProviderInfo.connectionId}`,
+          scopeType: domainOrgLookup.scopeType,
+          scopeId: domainOrgLookup.scopeId,
+          organizationId: domainOrgLookup.organizationId,
+        };
+        if (domainOrgLookup.enforcement?.requireSSO) {
+          required = true;
+        }
+        break;
+      }
+      default:
+        break;
+    }
+
+    return {
+      method,
+      factorType,
+      category,
+      canBeFirstFactor,
+      canBeSecondFactor,
+      required,
+      oauth2ProviderRefs,
+      ssoIds,
+      organizationRestricted,
+      supportsIntegrations,
+      availableIntegrations,
+      config,
+    };
+  }
+}