@wildo-ai/saas-backend-lib 1.0.1

package/src/security/authentications/controllers/authentication-controller.backend.service.ts

@@ -0,0 +1,2712 @@
+import 'reflect-metadata';
+import { injectable, inject } from 'inversify';
+import express, { Request, Response, NextFunction } from 'express';
+import { AbstractControllerBackendService } from '~wildo-backend-lib/base-classes/services/controllers/abstract-controller.backend.service';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { ErrorHandlerService } from '~wildo-backend-lib/errors/services/error-handler.backend.service';
+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 { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { AuthenticationOrchestratorBackendService } from '~wildo-backend-lib/security/authentications/services/authentication-orchestrator.backend.service';
+import { AuthTokenIssuerBackendService } from '~wildo-backend-lib/security/authentications/services/auth-token-issuer.backend.service';
+import { OAuth2AuthenticationBackendService } from '~wildo-backend-lib/security/authentications/services/auth-methods/oauth2-authentication.backend.service';
+import { OAuth2ConnectionResolverBackendService } from '~wildo-backend-lib/security/authentications/services/auth-methods/oauth2-connection-resolver.backend.service';
+import { ConsumableTokenBackendService } from '~wildo-backend-lib/security/consumable-tokens/services/consumable-token.backend.service';
+import { JwtBackendService } from '~wildo-backend-lib/security/jwt/services/jwt.backend.service';
+import { WebAuthnBackendService } from '~wildo-backend-lib/security/authentications/services/auth-methods/webauthn.backend.service';
+import { DomainToOrgLookupBackendService } from '~wildo-backend-lib/security/authentications/services/admin-config/domain-to-org-lookup.backend.service';
+import { SAMLAuthenticationBackendService } from '~wildo-backend-lib/security/authentications/services/auth-methods/saml-authentication.backend.service';
+import { SAMLMetadataBackendService } from '~wildo-backend-lib/security/authentications/services/auth-methods/saml-metadata.backend.service';
+import { EmailBackendService } from '~wildo-backend-lib/notifications/email/services/email.backend.service';
+import { SMSBackendService } from '~wildo-backend-lib/notifications/sms/services/sms.backend.service';
+import { AuthExecutionContextFactoryBackendService } from '~wildo-backend-lib/security/authentications/services/auth-execution-context-factory.backend.service';
+import type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import { AUTH_REDIS_KEYS, AUTH_OPERATION, AuthSource } from '~wildo-backend-lib/security/authentications/models/auth-constants.backend';
+import { AuthControllerUtils } from '~wildo-backend-lib/security/authentications/services/utils/auth-controller.utils';
+import { AuthResponseHelperBackendService } from '~wildo-backend-lib/security/authentications/services/utils/auth-response-helper.backend.service';
+import { AuthJwtGuardBackendService } from '~wildo-backend-lib/security/jwt/services/auth-jwt-guard.backend.service';
+import { AuthPasswordResetBackendService } from '~wildo-backend-lib/security/authentications/services/auth-methods/auth-password-reset.backend.service';
+import { AuthRegistrationBackendService } from '~wildo-backend-lib/security/authentications/services/auth-methods/auth-registration.backend.service';
+import { AuthMfaBackendService } from '~wildo-backend-lib/security/authentications/services/auth-methods/auth-mfa.backend.service';
+import { AuthPhoneVerificationBackendService } from '~wildo-backend-lib/security/authentications/services/auth-methods/auth-phone-verification.backend.service';
+import { AuthMethodManagementBackendService } from '~wildo-backend-lib/security/authentications/services/auth-methods/auth-method-management.backend.service';
+import { AnonymousSessionBackendService } from '~wildo-backend-lib/security/authentications/services/anonymous-session.backend.service';
+import { AuthUserLookupBackendService } from '~wildo-backend-lib/security/authentications/services/utils/auth-user-lookup.backend.service';
+import { RateLimitBackendService } from '~wildo-backend-lib/errors/services/rate-limit.backend.service';
+import { z } from 'zod';
+import {
+  AuthIdentificationRequestSchema,
+  AuthenticationRequestSchema,
+  AuthLoginFormDtoSchema,
+  PasswordResetRequestDtoSchema,
+  PasswordResetCompleteDtoSchema,
+  UserRegisterApiDtoSchema,
+  UserInvitationApiDtoSchema,
+  UserInvitationRejectApiDtoSchema,
+  EmailVerifyDtoSchema,
+  NativeTokenExchangeRequestSchema,
+  AuthMethod,
+  AuthFactorLevel,
+  AuthenticationSessionState,
+  CoreConsumableTokenTypes,
+  ConsumableToken_ConsumptionMode,
+  ConsumableTokenTypesSchema,
+  CoreResourceType,
+  CoreResourceOperation,
+  CoreAuditableEventType,
+  ResourceOperationVariantType,
+  ResourceOperationRiskLevel,
+  ResourcePrimaryScope,
+  CORE_APP_ROLES,
+  UserStatus,
+  SsoConnectionType,
+  EmailTemplateType,
+  SystemEmailTemplateRef,
+  ErrorType,
+  ErrorCustomMessageReference,
+  isWildoBackendError,
+  MANUAL_CONTROLLER_ROUTES_URLS,
+  ManualControllerRouteKey,
+  AuthRedirectErrorCode,
+  AuthScopeType,
+  SessionType,
+  WildoHeaderKeys,
+} from '@wildo-ai/saas-models';
+import { DurationUnit } from '@wildo-ai/zod-decorators';
+import type { AuthIdentificationResponse, AuthenticationRequest, AuthenticationResponse, User } from '@wildo-ai/saas-models';
+import { MagicLinkSendRequestSchema, MagicLinkVerifyRequestSchema, PhoneVerifySendRequestSchema, PhoneVerifyConfirmRequestSchema } from '@wildo-ai/saas-models';
+import { AvailableLanguage, AuthResponseMessageRef, BackendSmsMessageRef } from '@wildo-ai/presets-components-models';
+
+
+// Password auth body extends the shared login form DTO with session/method/factor fields
+// that are added programmatically by the frontend service layer.
+const PasswordAuthBodySchema = AuthLoginFormDtoSchema.extend({
+  sessionId: z.string(),
+  method: z.literal(AuthMethod.PASSWORD),
+  factorLevel: z.literal(AuthFactorLevel.FIRST),
+});
+
+const RefreshTokenBodySchema = z.object({
+  refreshToken: z.string().min(1),
+});
+
+const TokenExchangeBodySchema = z.object({
+  code: z.string().min(1),
+});
+
+const LogoutBodySchema = z.object({
+  refreshToken: z.string().min(1),
+});
+
+const CreateOneOffTokenRequestSchema = z.object({
+  userId: z.string().min(1),
+  tokenType: ConsumableTokenTypesSchema,
+  consumeAt: z.enum(['EXCHANGE', 'TARGET_OPERATION']),
+  consumptionMode: z.enum(ConsumableToken_ConsumptionMode).optional().default(ConsumableToken_ConsumptionMode.SINGLE_USE),
+  maxUses: z.number().int().min(1).optional(),
+  expiresIn: z.object({
+    value: z.number().int().min(1),
+    unit: z.enum(['minutes', 'hours', 'days']),
+  }).optional().default({ value: 24, unit: 'hours' }),
+  resourceIdentifier: z.string().optional(),
+  relatedId: z.string().optional(),
+  metadata: z.record(z.string(), z.any()).optional(),
+  targeting: z.object({
+    initiatorIds: z.record(z.string(), z.string()).optional(),
+  }).optional(),
+});
+
+const OneOffSessionExchangeBodySchema = z.object({
+  token: z.string().min(1),
+});
+
+@injectable()
+export class AuthenticationControllerBackendService extends AbstractControllerBackendService {
+  private readonly authService: AuthenticationOrchestratorBackendService;
+  private readonly tokenIssuer: AuthTokenIssuerBackendService;
+  private readonly oauth2Service: OAuth2AuthenticationBackendService;
+  private readonly oauth2Resolver: OAuth2ConnectionResolverBackendService;
+  private readonly consumableTokenService: ConsumableTokenBackendService;
+  private readonly jwtService: JwtBackendService;
+  private readonly emailService: EmailBackendService;
+  private readonly appConfigService: AppConfigurationService;
+  private readonly auditLogsService: AuditLogsBackendService;
+  private readonly rateLimitService: RateLimitBackendService;
+  private readonly webAuthnService: WebAuthnBackendService;
+  private readonly smsService: SMSBackendService;
+  private readonly domainToOrgLookup: DomainToOrgLookupBackendService;
+  private readonly samlAuthService: SAMLAuthenticationBackendService;
+  private readonly samlMetadataService: SAMLMetadataBackendService;
+  private readonly authResponseHelper: AuthResponseHelperBackendService;
+  private readonly authJwtGuard: AuthJwtGuardBackendService;
+  private readonly passwordResetService: AuthPasswordResetBackendService;
+  private readonly registrationService: AuthRegistrationBackendService;
+  private readonly mfaService: AuthMfaBackendService;
+  private readonly phoneVerificationService: AuthPhoneVerificationBackendService;
+  private readonly methodManagementService: AuthMethodManagementBackendService;
+  private readonly anonymousSessionService: AnonymousSessionBackendService;
+  private readonly userLookup: AuthUserLookupBackendService;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.ErrorHandlerService) errorHandler: ErrorHandlerService,
+    @inject(SAAS_SERVICE_TYPES.AuthenticationOrchestratorService) authService: AuthenticationOrchestratorBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthTokenIssuer) tokenIssuer: AuthTokenIssuerBackendService,
+    @inject(SAAS_SERVICE_TYPES.OAuth2AuthenticationService) oauth2Service: OAuth2AuthenticationBackendService,
+    @inject(SAAS_SERVICE_TYPES.OAuth2ConnectionResolverService) oauth2Resolver: OAuth2ConnectionResolverBackendService,
+    @inject(SAAS_SERVICE_TYPES.ConsumableTokenService) consumableTokenService: ConsumableTokenBackendService,
+    @inject(SAAS_SERVICE_TYPES.JwtBackendService) jwtService: JwtBackendService,
+    @inject(SAAS_SERVICE_TYPES.EmailService) emailService: EmailBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthExecutionContextFactory) private readonly authEcFactory: AuthExecutionContextFactoryBackendService,
+    @inject(SAAS_SERVICE_TYPES.AppConfigService) appConfigService: AppConfigurationService,
+    @inject(SAAS_SERVICE_TYPES.AuditLogsService) auditLogsService: AuditLogsBackendService,
+    @inject(SAAS_SERVICE_TYPES.RateLimitBackendService) rateLimitService: RateLimitBackendService,
+    @inject(SAAS_SERVICE_TYPES.WebAuthnService) webAuthnService: WebAuthnBackendService,
+    @inject(SAAS_SERVICE_TYPES.SMSService) smsService: SMSBackendService,
+    @inject(SAAS_SERVICE_TYPES.DomainToOrgLookupService) domainToOrgLookup: DomainToOrgLookupBackendService,
+    @inject(SAAS_SERVICE_TYPES.SAMLAuthenticationService) samlAuthService: SAMLAuthenticationBackendService,
+    @inject(SAAS_SERVICE_TYPES.SAMLMetadataService) samlMetadataService: SAMLMetadataBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthResponseHelperService) authResponseHelper: AuthResponseHelperBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthJwtGuardService) authJwtGuard: AuthJwtGuardBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthPasswordResetService) passwordResetService: AuthPasswordResetBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthRegistrationService) registrationService: AuthRegistrationBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthMfaService) mfaService: AuthMfaBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthPhoneVerificationService) phoneVerificationService: AuthPhoneVerificationBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthMethodManagementService) methodManagementService: AuthMethodManagementBackendService,
+    @inject(SAAS_SERVICE_TYPES.AnonymousSessionService) anonymousSessionService: AnonymousSessionBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthUserLookupService) userLookup: AuthUserLookupBackendService,
+  ) {
+    super(logger, errorBuilder, errorHandler, 'AuthenticationController');
+    this.authService = authService;
+    this.tokenIssuer = tokenIssuer;
+    this.oauth2Service = oauth2Service;
+    this.oauth2Resolver = oauth2Resolver;
+    this.consumableTokenService = consumableTokenService;
+    this.jwtService = jwtService;
+    this.emailService = emailService;
+    this.appConfigService = appConfigService;
+    this.auditLogsService = auditLogsService;
+    this.rateLimitService = rateLimitService;
+    this.webAuthnService = webAuthnService;
+    this.smsService = smsService;
+    this.domainToOrgLookup = domainToOrgLookup;
+    this.samlAuthService = samlAuthService;
+    this.samlMetadataService = samlMetadataService;
+    this.authResponseHelper = authResponseHelper;
+    this.authJwtGuard = authJwtGuard;
+    this.passwordResetService = passwordResetService;
+    this.registrationService = registrationService;
+    this.mfaService = mfaService;
+    this.phoneVerificationService = phoneVerificationService;
+    this.methodManagementService = methodManagementService;
+    this.anonymousSessionService = anonymousSessionService;
+    this.userLookup = userLookup;
+  }
+
+  protected setupRoutes(): void {
+    // ─── Existing Authentication Routes ───
+
+    // User/Customer identification
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_IDENTIFY], this.asyncHandler(this.identify.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_IDENTIFY], 'Identify user/customer and get available methods');
+
+    // Authentication methods
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_AUTHENTICATE_PASSWORD], this.asyncHandler(this.authenticatePassword.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_AUTHENTICATE_PASSWORD], 'Authenticate with password');
+
+    // Generic authentication endpoint for all methods
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_AUTHENTICATE], this.asyncHandler(this.authenticate.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_AUTHENTICATE], 'Universal authentication endpoint (all methods)');
+
+    // Token refresh (TRAP 11: NOT behind JWT auth — user's access token may be expired)
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_TOKEN_REFRESH], this.asyncHandler(this.refreshToken.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_TOKEN_REFRESH], 'Refresh access token using refresh token');
+
+    // Session management
+    this.router.get(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SESSION_STATE], this.asyncHandler(this.getSessionState.bind(this)));
+    this.logRouteRegistration('GET', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SESSION_STATE], 'Get authentication session state');
+
+    // ─── OAuth2 Routes (Step 5) ───
+    // [Capacitor] [OAuth2] [SAML]
+    // These routes serve both web and Capacitor clients:
+    // - oauth2Authorize: returns authorizationUrl — web uses window.location.href, Capacitor uses Browser.open()
+    // - oauth2Callback: IdP redirects here (server-to-server) — unaffected by Capacitor
+    // - tokenExchange: frontend/Capacitor app exchanges one-time code for JWT — works identically
+    // When Capacitor introduces native Apple/Google SDKs, a new POST /auth/native-token/exchange
+    // route will be needed to accept native SDK tokens (Apple identityToken, Google idToken)
+    // and issue JWT tokens. The existing oauth2Callback route is NOT used for native SDK flows.
+
+    // OAuth2 authorize — returns authorization URL for frontend to redirect
+    this.router.get(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_OAUTH2_AUTHORIZE], this.asyncHandler(this.oauth2Authorize.bind(this)));
+    this.logRouteRegistration('GET', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_OAUTH2_AUTHORIZE], 'OAuth2 authorize — get IdP authorization URL');
+
+    // OAuth2 callback — accepts GET and POST only (L7 fix: was router.all(), narrowed to reduce attack surface)
+    // GET: standard OAuth2 authorization code flow
+    // POST: Apple uses response_mode=form_post (TRAP 5)
+    const oauth2CallbackHandler = this.asyncHandler(this.oauth2Callback.bind(this));
+    const oauth2CallbackUrl = MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_OAUTH2_CALLBACK];
+    this.router.get(oauth2CallbackUrl, oauth2CallbackHandler);
+    this.router.post(oauth2CallbackUrl, oauth2CallbackHandler);
+    this.logRouteRegistration('GET+POST', oauth2CallbackUrl, 'OAuth2 callback — handle IdP redirect (GET+POST for Apple form_post)');
+
+    // Token exchange — frontend exchanges one-time code for JWT tokens (Decision 7)
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_TOKEN_EXCHANGE], this.asyncHandler(this.tokenExchange.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_TOKEN_EXCHANGE], 'Exchange one-time code for JWT tokens');
+
+    // Logout — revoke refresh token
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_LOGOUT], this.asyncHandler(this.logout.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_LOGOUT], 'Logout — revoke refresh token');
+
+    // ─── Password Reset Routes (Step 7) ───
+
+    // Request password reset — sends email with reset link
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSWORD_RESET_REQUEST], this.asyncHandler(this.passwordResetRequest.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSWORD_RESET_REQUEST], 'Request password reset — send email with reset link');
+
+    // Complete password reset — validate token and update password
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSWORD_RESET_COMPLETE], this.asyncHandler(this.passwordResetComplete.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSWORD_RESET_COMPLETE], 'Complete password reset — validate token and set new password');
+
+    // ─── Registration Routes (Step 8) ───
+
+    // Register — create account with email verification
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_REGISTER], this.asyncHandler(this.register.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_REGISTER], 'Register — create user account with email verification');
+
+    // Accept invitation — public token-driven invitation completion
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_ACCEPT_INVITATION], this.asyncHandler(this.acceptInvitation.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_ACCEPT_INVITATION], 'Accept invitation — create/link account and continue auth flow');
+
+    // Reject invitation — public token-driven invitation decline
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_REJECT_INVITATION], this.asyncHandler(this.rejectInvitation.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_REJECT_INVITATION], 'Reject invitation — mark invitee decline explicitly');
+
+    // Verify email — confirm email and auto-login
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_VERIFY_EMAIL], this.asyncHandler(this.verifyEmail.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_VERIFY_EMAIL], 'Verify email — confirm email address and issue tokens');
+
+    // Resend verification email (F5)
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_RESEND_VERIFICATION], this.asyncHandler(this.resendVerificationEmail.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_RESEND_VERIFICATION], 'Resend verification email — re-send email verification link');
+
+    // W5.7: Complete org onboarding (deferred org creation)
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_COMPLETE_ORG_ONBOARDING], this.asyncHandler(this.completeOrgOnboarding.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_COMPLETE_ORG_ONBOARDING], 'Complete org onboarding — create deferred organization');
+
+    // ─── MFA: Email OTP Routes (Step 10) ───
+
+    // Send email OTP — generates OTP and sends via email
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MFA_EMAIL_OTP_SEND], this.asyncHandler(this.mfaEmailOTPSend.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MFA_EMAIL_OTP_SEND], 'Send email OTP for MFA second factor');
+
+    // Verify email OTP — validates the submitted OTP code
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MFA_EMAIL_OTP_VERIFY], this.asyncHandler(this.mfaEmailOTPVerify.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MFA_EMAIL_OTP_VERIFY], 'Verify email OTP for MFA second factor');
+
+    // ─── MFA: TOTP Routes (Step 11) ───
+
+    // TOTP setup — generate secret + QR URI for enrollment
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MFA_TOTP_SETUP], this.asyncHandler(this.mfaTOTPSetup.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MFA_TOTP_SETUP], 'Setup TOTP — generate secret and QR code URI');
+
+    // TOTP verify setup — confirm enrollment with a code from the authenticator app
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MFA_TOTP_VERIFY_SETUP], this.asyncHandler(this.mfaTOTPVerifySetup.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MFA_TOTP_VERIFY_SETUP], 'Verify TOTP setup — confirm enrollment with code');
+
+    // TOTP verify — validate TOTP code during login MFA
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MFA_TOTP_VERIFY], this.asyncHandler(this.mfaTOTPVerify.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MFA_TOTP_VERIFY], 'Verify TOTP code for MFA second factor');
+
+    // ─── Enterprise SSO Routes (Step 15) ───
+    // Enterprise OIDC authorize — initiate SSO flow for an org's OIDC connection
+    // Callback reuses the same /auth/oauth2/callback/:providerRef route — state token carries enterprise context
+    this.router.get(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_ENTERPRISE_SSO_AUTHORIZE], this.asyncHandler(this.enterpriseSSOAuthorize.bind(this)));
+    this.logRouteRegistration('GET', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_ENTERPRISE_SSO_AUTHORIZE], 'Enterprise SSO authorize — get IdP authorization URL for org OIDC connection');
+
+    // App-enterprise OIDC authorize — initiate SSO flow for an APPLICATION-scoped connection
+    this.router.get(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_APP_ENTERPRISE_AUTHORIZE], this.asyncHandler(this.appEnterpriseSSOAuthorize.bind(this)));
+    this.logRouteRegistration('GET', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_APP_ENTERPRISE_AUTHORIZE], 'App-enterprise SSO authorize — get IdP authorization URL for app OIDC connection');
+
+    // ─── SAML Routes (AUTH-2) ───
+    this.router.get(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SAML_LOGIN], this.asyncHandler(this.handleSAMLLogin.bind(this)));
+    this.logRouteRegistration('GET', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SAML_LOGIN], 'SAML login — initiate SP-initiated SSO');
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SAML_ACS],
+      express.urlencoded({ extended: false, limit: '2mb' }),
+      this.asyncHandler(this.handleSAMLACS.bind(this)),
+    );
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SAML_ACS], 'SAML ACS — process IdP response (SC-30: 2mb urlencoded)');
+
+    this.router.get(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SAML_METADATA], this.asyncHandler(this.handleSAMLMetadata.bind(this)));
+    this.logRouteRegistration('GET', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SAML_METADATA], 'SAML SP metadata — public XML endpoint');
+
+    this.router.get(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SAML_SLO], this.asyncHandler(this.handleSAMLSLO_GET.bind(this)));
+    this.logRouteRegistration('GET', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SAML_SLO], 'SAML SLO — IdP-initiated via HTTP-Redirect or SP-initiated LogoutResponse');
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SAML_SLO],
+      express.urlencoded({ extended: false, limit: '2mb' }),
+      this.asyncHandler(this.handleSAMLSLO_POST.bind(this)),
+    );
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SAML_SLO], 'SAML SLO — IdP-initiated via HTTP-POST');
+
+    // ─── WebAuthn/Passkey Routes (Phase G1) ───
+    // Registration (JWT-authenticated)
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_REGISTER_OPTIONS], this.asyncHandler(this.handlePasskeyRegisterOptions.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_REGISTER_OPTIONS], 'Passkey register options — generate registration challenge');
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_REGISTER_VERIFY], this.asyncHandler(this.handlePasskeyRegisterVerify.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_REGISTER_VERIFY], 'Passkey register verify — verify and store credential');
+
+    // Authentication (unauthenticated — part of login flow)
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_AUTH_OPTIONS], this.asyncHandler(this.handlePasskeyAuthOptions.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_AUTH_OPTIONS], 'Passkey auth options — generate authentication challenge');
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_AUTH_VERIFY], this.asyncHandler(this.handlePasskeyAuthVerify.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_AUTH_VERIFY], 'Passkey auth verify — verify assertion and complete login');
+
+    // Management (JWT-authenticated)
+    this.router.get(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_LIST], this.asyncHandler(this.handlePasskeyList.bind(this)));
+    this.logRouteRegistration('GET', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_LIST], 'Passkey list — list registered passkeys');
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_REMOVE], this.asyncHandler(this.handlePasskeyRemove.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_REMOVE], 'Passkey remove — remove a passkey');
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_RENAME], this.asyncHandler(this.handlePasskeyRename.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PASSKEY_RENAME], 'Passkey rename — rename a passkey');
+
+    // ─── Magic Link Routes (Phase G2) ───
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MAGIC_LINK_SEND], this.asyncHandler(this.magicLinkSend.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MAGIC_LINK_SEND], 'Magic link send — send passwordless login link via email');
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MAGIC_LINK_VERIFY], this.asyncHandler(this.magicLinkVerify.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_MAGIC_LINK_VERIFY], 'Magic link verify — verify token and issue auth tokens');
+
+    // ─── SMS OTP Routes (Phase G2) ───
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SMS_OTP_SEND], this.asyncHandler(this.smsOTPSend.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_SMS_OTP_SEND], 'SMS OTP send — send OTP code via SMS');
+
+    // Note: SMS OTP verify goes through the generic /auth/authenticate endpoint via SMS_OTP method
+
+    // ─── Phone Verification Routes (Phase G2) ───
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PHONE_VERIFY_SEND], this.asyncHandler(this.phoneVerifySend.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PHONE_VERIFY_SEND], 'Phone verify send — send verification code via SMS');
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PHONE_VERIFY_CONFIRM], this.asyncHandler(this.phoneVerifyConfirm.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_PHONE_VERIFY_CONFIRM], 'Phone verify confirm — confirm phone ownership with code');
+
+    // ─── Native SDK Token Exchange (F2) ───
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_NATIVE_TOKEN_EXCHANGE], this.asyncHandler(this.nativeTokenExchange.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_NATIVE_TOKEN_EXCHANGE], 'Exchange native SDK identity token for Wildo JWT');
+
+    // ─── One-Off Session Routes (W7.3b) ───
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_ONE_OFF_SESSION_CREATE], this.asyncHandler(this.createOneOffToken.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_ONE_OFF_SESSION_CREATE], 'Create one-off session token (app-scoped)');
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_ONE_OFF_SESSION_CREATE_ORG], this.asyncHandler(this.createOneOffToken.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_ONE_OFF_SESSION_CREATE_ORG], 'Create one-off session token (org+app-scoped)');
+
+    this.router.post(MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_ONE_OFF_SESSION_EXCHANGE], this.asyncHandler(this.exchangeOneOffToken.bind(this)));
+    this.logRouteRegistration('POST', MANUAL_CONTROLLER_ROUTES_URLS[ManualControllerRouteKey.AUTH_ONE_OFF_SESSION_EXCHANGE], 'Exchange one-off token for JWT session');
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Existing Authentication Route Handlers
+  // ═══════════════════════════════════════════════════════════════
+
+  private async identify(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const body = AuthIdentificationRequestSchema.parse(req.body || {});
+
+    // Capture device information from request headers (consistent IP extraction)
+    const deviceInfo = {
+      userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+      ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+    };
+
+    const identificationRequest = {
+      ...body,
+      deviceInfo
+    };
+
+    // W3.5 + W3.11: Resolve activeUserType hint from X-Frontend-Service-Name header.
+    // AUTH-10: This is only a hint for pre-identification flows (unknown users).
+    // For known users, the orchestrator overrides with the DB-stored userTypes[0].
+    // AUTH-10: Cross-validate Origin against claimed frontend service identity (defense-in-depth).
+    const frontendServiceName = req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] as string | undefined;
+    this._validateFrontendAppOrigin(req, frontendServiceName);
+    const activeUserType = frontendServiceName
+      ? this.appConfigService.resolveUserTypeFromFrontendServiceName(frontendServiceName) ?? undefined
+      : undefined;
+
+    const result: AuthIdentificationResponse = await this.authService.identify(
+      ec,
+      identificationRequest,
+      activeUserType,
+      frontendServiceName,
+    );
+    this.jsonSuccess(res, result);
+  }
+
+  private async authenticatePassword(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const body = PasswordAuthBodySchema.parse(req.body || {});
+    const passwordRequest = {
+      sessionId: body.sessionId,
+      method: body.method,
+      factorLevel: body.factorLevel,
+      password: body.password,
+      email: body.email, // Email should be available from session, but included for compatibility
+      rememberMe: false,
+      requestedIntegrations: []
+    };
+    const result: AuthenticationResponse = await this.authService.authenticatePassword(ec, passwordRequest);
+    await this.handleAnonymousTransposition(req, result);
+    this.jsonSuccess(res, result);
+  }
+
+  // Generic authenticate endpoint for future extensibility (SSO/MFA/etc.)
+  private async authenticate(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const request = AuthenticationRequestSchema.parse(req.body || {}) as AuthenticationRequest;
+    const result: AuthenticationResponse = await this.authService.authenticate(ec, request);
+    await this.handleAnonymousTransposition(req, result);
+    this.jsonSuccess(res, result);
+  }
+
+  /**
+   * Refresh access token using a valid refresh token.
+   * POST /auth/token/refresh
+   * Body: { refreshToken: string }
+   * Response: { accessToken, refreshToken?, expiresIn }
+   *
+   * TRAP 11: This endpoint is NOT behind JWT auth middleware.
+   * The user's access token is expired — that's why they're calling refresh.
+   */
+  private async refreshToken(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const body = RefreshTokenBodySchema.parse(req.body || {});
+    const tokens = await this.tokenIssuer.refreshAccessToken(body.refreshToken);
+
+    // H5: Audit token refresh
+    try {
+      const decoded = await this.jwtService.verify(tokens.accessToken);
+      if (typeof decoded === 'object' && decoded !== null) {
+        const payload = decoded as Record<string, unknown>;
+        const refreshUserId = typeof payload.userId === 'string' ? payload.userId : undefined;
+        const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : 'unknown';
+        if (refreshUserId) {
+          this.auditLogsService.logUserTokenRefreshed({
+            userId: refreshUserId,
+            sessionId,
+            ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+            userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+          }).catch(() => {});
+        }
+      }
+    } catch { /* token decode failure — don't block the response */ }
+
+    this.jsonSuccess(res, tokens);
+  }
+
+  // Get current authentication session state
+  private async getSessionState(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const sessionId = req.params.sessionId as string | undefined;
+
+    if (!sessionId) {
+      return this.jsonError(res, 'Session ID is required');
+    }
+
+    const sessionState = await this.authService.getAuthenticationSessionState(ec, sessionId);
+
+    if (!sessionState) {
+      return this.jsonError(res, 'Session not found or expired');
+    }
+
+    // H2 fix: Strip sensitive fields from public endpoint to prevent enumeration.
+    // Removed: email, userExists, userId (H2), remainingAttempts, lockedUntil (review fix #5).
+    // Frontend uses error responses (customMessageReference, authResponse) for retry/lockout UI.
+    const publicSessionState = {
+      sessionId: sessionState.sessionId,
+      state: sessionState.state,
+      completedFactors: sessionState.completedFactors,
+      currentFactor: sessionState.currentFactor,
+      availableFirstFactorMethods: sessionState.availableFirstFactorMethods,
+      availableSecondFactorMethods: sessionState.availableSecondFactorMethods,
+      enrolledSecondFactorMethods: sessionState.enrolledSecondFactorMethods,
+      usableSecondFactorMethods: sessionState.usableSecondFactorMethods,
+      requiresMFA: sessionState.requiresMFA,
+      requireStrongMFA: sessionState.requireStrongMFA,
+      mfaMethodsRequired: sessionState.mfaMethodsRequired,
+      expiresAt: sessionState.expiresAt,
+    };
+
+    this.jsonSuccess(res, publicSessionState);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // OAuth2 Route Handlers (Step 5)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * GET /auth/oauth2/authorize/:providerRef
+   *
+   * Initiates an OAuth2 authorization flow for a social SSO provider.
+   * Returns the IdP authorization URL for the frontend to redirect to.
+   *
+   * Enterprise-ready: In Step 14/15, a query param (?org=...&connection=...)
+   * will trigger resolveEnterpriseConnection() instead.
+   */
+  private async oauth2Authorize(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const providerRef = req.params.providerRef as string | undefined;
+
+    if (!providerRef) {
+      throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: { message: 'providerRef parameter is required' },
+      });
+    }
+
+    // G3 + P3: Determine scope context from email hint before resolving credentials.
+    // Used for both provider restriction checks (G3) and social credential overrides (P3).
+    const emailHint = req.query.email as string | undefined;
+    let scopeContext: { scopeType: AuthScopeType; scopeId: string } | undefined;
+
+    if (emailHint) {
+      const emailDomain = emailHint.split('@')[1]?.toLowerCase();
+      if (emailDomain) {
+        const orgLookup = await this.domainToOrgLookup.findOrgByDomain(ec, emailDomain);
+        if (orgLookup) {
+          scopeContext = { scopeType: orgLookup.scopeType, scopeId: orgLookup.scopeId };
+
+          // G3: Check org-level provider restrictions (UX optimization — hard enforcement in callback G3-M5)
+          const { allowed, reason } = await this.oauth2Resolver.isProviderAllowed(
+            ec, orgLookup.scopeType, orgLookup.scopeId, providerRef,
+          );
+          if (!allowed) {
+            await this.auditLogsService.logOAuth2ProviderBlocked({
+              email: emailHint,
+              providerRef,
+              organizationId: orgLookup.scopeId,
+              reason: reason || 'Organization policy',
+              ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+              userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+            });
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+              customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_INVALID_TOKEN,
+              context: { message: reason || 'This login provider is not allowed for your organization.' },
+            });
+          }
+        }
+      }
+    }
+
+    // Resolve connection config from catalog + app config + secrets + scope overrides (P3)
+    const connection = await this.oauth2Resolver.resolveSocialConnection(
+      providerRef,
+      scopeContext ? { ec, ...scopeContext } : undefined,
+    );
+
+    // Validate the frontend originator early — fail now with a clear error instead of
+    // silently storing undefined in the state token and getting a confusing error on callback.
+    // resolveFrontendAppPublicUrl throws if the header is missing or the frontend service is unknown.
+    const frontendUrl = this.resolveFrontendAppPublicUrl(req);
+    const frontendServiceName = req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] as string;
+    const returnUrl = typeof req.query.returnUrl === 'string' ? req.query.returnUrl : undefined;
+    void frontendUrl; // validated and discarded — the URL is resolved again on callback from the state token
+    if (returnUrl) {
+      this.validateFrontendReturnUrl(returnUrl, frontendUrl);
+    }
+
+    // Build the authorization URL with PKCE + state token (includes frontendServiceName + scope in state)
+    const { authorizationUrl } = await this.oauth2Service.buildAuthorizationUrl(connection, {
+      frontendServiceName,
+      scopeType: scopeContext?.scopeType,
+      scopeId: scopeContext?.scopeId,
+      returnUrl,
+    });
+
+    this.logDebug('OAuth2 authorize URL generated', {
+      providerRef,
+      connectionType: connection.connectionType,
+    });
+
+    this.jsonSuccess(res, { authorizationUrl });
+  }
+
+  /**
+   * GET /auth/enterprise/authorize/:orgId/:connectionId
+   *
+   * Initiates an enterprise SSO OIDC flow for an organization's connection.
+   * Uses the same OAuth2 engine — only the resolver path is different.
+   * The callback reuses /auth/oauth2/callback/:providerRef — the state token
+   * carries connectionType='enterprise', organizationId, and connectionId.
+   *
+   * Step 15: Enterprise SSO authorize route.
+   */
+  private async enterpriseSSOAuthorize(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const orgId = req.params.orgId as string | undefined;
+    const connectionId = req.params.connectionId as string | undefined;
+
+    if (!orgId || !connectionId) {
+      throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: { message: 'orgId and connectionId parameters are required' },
+      });
+    }
+
+    // Resolve enterprise connection from org config
+    const connection = await this.oauth2Resolver.resolveEnterpriseConnection(ec, AuthScopeType.ORGANIZATION, orgId, connectionId);
+
+    // Validate the frontend originator
+    const frontendUrl = this.resolveFrontendAppPublicUrl(req);
+    const frontendServiceName = req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] as string;
+    const returnUrl = typeof req.query.returnUrl === 'string' ? req.query.returnUrl : undefined;
+    void frontendUrl;
+    if (returnUrl) {
+      this.validateFrontendReturnUrl(returnUrl, frontendUrl);
+    }
+
+    // Build the authorization URL using the same OAuth2 engine
+    const { authorizationUrl } = await this.oauth2Service.buildAuthorizationUrl(connection, {
+      frontendServiceName,
+      returnUrl,
+    });
+
+    this.logDebug('Enterprise SSO authorize URL generated', {
+      orgId,
+      connectionId,
+      connectionType: connection.connectionType,
+      providerRef: connection.providerRef,
+    });
+
+    this.jsonSuccess(res, { authorizationUrl });
+  }
+
+  /**
+   * GET /auth/app-enterprise/authorize/:connectionId
+   *
+   * Application-scoped enterprise SSO authorize route.
+   * Same flow as org-scoped enterpriseSSOAuthorize but resolves from APPLICATION scope.
+   */
+  private async appEnterpriseSSOAuthorize(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const connectionId = req.params.connectionId as string | undefined;
+
+    if (!connectionId) {
+      throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: { message: 'connectionId parameter is required' },
+      });
+    }
+
+    const appId = req.headers[WildoHeaderKeys.APPLICATION_ID] as string | undefined;
+    if (!appId) {
+      throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+        context: { message: 'Application ID header is required for app-enterprise SSO' },
+      });
+    }
+
+    const connection = await this.oauth2Resolver.resolveEnterpriseConnection(ec, AuthScopeType.APPLICATION, appId, connectionId);
+
+    // Validate the frontend originator early so OAuth state always carries
+    // a usable frontendServiceName for callback redirection.
+    const frontendUrl = this.resolveFrontendAppPublicUrl(req);
+    const frontendServiceName = req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] as string;
+    const returnUrl = typeof req.query.returnUrl === 'string' ? req.query.returnUrl : undefined;
+    void frontendUrl;
+    if (returnUrl) {
+      this.validateFrontendReturnUrl(returnUrl, frontendUrl);
+    }
+    const { authorizationUrl } = await this.oauth2Service.buildAuthorizationUrl(connection, {
+      frontendServiceName,
+      returnUrl,
+    });
+
+    this.logDebug('App-enterprise SSO authorize URL generated', {
+      appId,
+      connectionId,
+      connectionType: connection.connectionType,
+      providerRef: connection.providerRef,
+    });
+
+    this.jsonSuccess(res, { authorizationUrl });
+  }
+
+  /**
+   * GET /auth/saml/login/:connectionId
+   *
+   * Initiate SP-initiated SAML SSO. Generates an AuthnRequest,
+   * creates a state token, and redirects the browser to the IdP SSO URL.
+   *
+   * Rate limit: SC-38 — 10 req/min per IP.
+   */
+  private async handleSAMLLogin(req: Request, res: Response): Promise<void> {
+    const clientIp = AuthControllerUtils.getClientIpFromRequest(req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.SAML_LOGIN_IP}${clientIp}`, 10, 60);
+
+    const ec = await this._getPreAuthExecutionContext();
+    const connectionId = req.params.connectionId as string;
+    const returnUrl = (req.query.returnUrl as string) || '/';
+
+    try {
+      const { redirectUrl } = await this.samlAuthService.initiateLogin(ec, connectionId, returnUrl);
+      res.redirect(302, redirectUrl);
+    } catch (error) {
+      if (isWildoBackendError(error)) {
+        this.logger.warn('SAML login initiation failed', { connectionId });
+      } else {
+        this.logger.error('SAML login initiation failed with unexpected error', {
+          connectionId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+      const frontendUrl = this._resolveSAMLRedirectUrl();
+      return this.redirectToFrontendWithError(res, AuthRedirectErrorCode.SAML_LOGIN_FAILED, 'Authentication failed. Please try again.', frontendUrl);
+    }
+  }
+
+  /**
+   * POST /auth/saml/acs
+   *
+   * Assertion Consumer Service — processes the SAML Response from the IdP.
+   * Route-specific body parser: `express.urlencoded({ extended: false, limit: '2mb' })` (SC-30).
+   *
+   * Rate limit: SC-39 — 20 req/min per IP (higher because IdPs may retry).
+   * E16: POST-only (enforced by route registration).
+   * E19: RelayState size check — accept up to 1024 bytes, warn if >80.
+   */
+  private async handleSAMLACS(req: Request, res: Response): Promise<void> {
+    const clientIp = AuthControllerUtils.getClientIpFromRequest(req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.SAML_ACS_IP}${clientIp}`, 20, 60);
+
+    const samlResponse: string | undefined = req.body?.SAMLResponse;
+    const relayState: string | undefined = req.body?.RelayState;
+
+    if (!samlResponse) {
+      const frontendUrl = this._resolveSAMLRedirectUrl();
+      return this.redirectToFrontendWithError(res, AuthRedirectErrorCode.SAML_AUTH_FAILED, 'Authentication failed.', frontendUrl);
+    }
+
+    if (relayState && relayState.length > 1024) {
+      this.logger.warn('SAML RelayState exceeds 1024 bytes, rejecting', { length: relayState.length });
+      const frontendUrl = this._resolveSAMLRedirectUrl();
+      return this.redirectToFrontendWithError(res, AuthRedirectErrorCode.SAML_AUTH_FAILED, 'Authentication failed.', frontendUrl);
+    }
+    if (relayState && relayState.length > 80) {
+      this.logger.warn('SAML RelayState exceeds 80-byte spec limit (accepted)', { length: relayState.length });
+    }
+
+    const ec = await this._getPreAuthExecutionContext();
+
+    try {
+      const clientContext = {
+        ipAddress: clientIp,
+        userAgent: (req.headers[WildoHeaderKeys.USER_AGENT] as string) || 'unknown',
+      };
+      const result = await this.samlAuthService.handleACS(ec, samlResponse, relayState, clientContext);
+      res.redirect(302, result.redirectUrl);
+    } catch (error) {
+      if (isWildoBackendError(error)) {
+        this.logger.warn('SAML ACS processing failed', {
+          errorRef: (error as any).customMessageReference || 'unknown',
+        });
+      } else {
+        this.logger.error('SAML ACS failed with unexpected error', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+      const frontendUrl = this._resolveSAMLRedirectUrl();
+      return this.redirectToFrontendWithError(res, AuthRedirectErrorCode.SAML_AUTH_FAILED, 'Authentication failed. Please try again.', frontendUrl);
+    }
+  }
+
+  /**
+   * GET /auth/saml/metadata/:scopeType/:scopeId
+   *
+   * Public endpoint — returns SP metadata XML for IdP admins to configure their IdP.
+   * No auth middleware required (D16).
+   * Content-Type: application/samlmetadata+xml
+   */
+  private async handleSAMLMetadata(req: Request, res: Response): Promise<void> {
+    const scopeType = req.params.scopeType as string;
+    const scopeId = req.params.scopeId as string;
+
+    const metadataXml = this.samlMetadataService.generateSPMetadata(scopeType, scopeId);
+    res.set(WildoHeaderKeys.CONTENT_TYPE, 'application/samlmetadata+xml');
+    res.status(200).send(metadataXml);
+  }
+
+  /**
+   * GET /auth/saml/slo
+   *
+   * Handles two distinct cases via query params:
+   * - `SAMLRequest` present → IdP-initiated SLO (HTTP-Redirect binding)
+   * - `SAMLResponse` present → IdP's response to our SP-initiated SLO
+   *
+   * Rate limit: SC-40 — 10 req/min per IP.
+   */
+  private async handleSAMLSLO_GET(req: Request, res: Response): Promise<void> {
+    const clientIp = AuthControllerUtils.getClientIpFromRequest(req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.SAML_SLO_IP}${clientIp}`, 10, 60);
+
+    const samlRequest: string | undefined = req.query.SAMLRequest as string | undefined;
+    const samlResponse: string | undefined = req.query.SAMLResponse as string | undefined;
+    const relayState: string | undefined = req.query.RelayState as string | undefined;
+
+    const ec = await this._getPreAuthExecutionContext();
+
+    if (samlRequest) {
+      try {
+        const result = await this.samlAuthService.handleIdPInitiatedSLO(ec, 'redirect', samlRequest, relayState);
+        res.redirect(302, result.logoutResponseUrl);
+      } catch (error) {
+        this.logger.warn('SAML SLO (IdP-initiated GET) failed', {
+          errorRef: isWildoBackendError(error) ? (error as any).customMessageReference : 'unknown',
+          error: error instanceof Error ? error.message : String(error),
+        });
+        const frontendUrl = this._resolveSAMLRedirectUrl();
+        return this.redirectToFrontendWithError(res, AuthRedirectErrorCode.SAML_SLO_FAILED, 'Logout failed.', frontendUrl);
+      }
+    } else if (samlResponse) {
+      try {
+        await this.samlAuthService.handleSLOResponse(ec, 'redirect', samlResponse);
+      } catch (error) {
+        this.logger.warn('SAML SLO LogoutResponse processing failed (GET)', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+      const frontendUrl = this._resolveSAMLRedirectUrl() || '/';
+      res.redirect(302, `${frontendUrl}/auth/login?slo=success`);
+    } else {
+      res.status(400).json({ error: 'Missing SAMLRequest or SAMLResponse parameter' });
+    }
+  }
+
+  /**
+   * POST /auth/saml/slo
+   *
+   * IdP-initiated SLO via HTTP-POST binding.
+   * Route-specific body parser: `express.urlencoded({ extended: false, limit: '2mb' })`.
+   *
+   * Rate limit: SC-40 — 10 req/min per IP.
+   */
+  private async handleSAMLSLO_POST(req: Request, res: Response): Promise<void> {
+    const clientIp = AuthControllerUtils.getClientIpFromRequest(req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.SAML_SLO_IP}${clientIp}`, 10, 60);
+
+    const samlRequest: string | undefined = req.body?.SAMLRequest;
+    const samlResponse: string | undefined = req.body?.SAMLResponse;
+    const relayState: string | undefined = req.body?.RelayState;
+
+    const ec = await this._getPreAuthExecutionContext();
+
+    if (samlRequest) {
+      try {
+        const result = await this.samlAuthService.handleIdPInitiatedSLO(ec, 'post', samlRequest, relayState);
+        res.redirect(302, result.logoutResponseUrl);
+      } catch (error) {
+        this.logger.warn('SAML SLO (IdP-initiated POST) failed', {
+          errorRef: isWildoBackendError(error) ? (error as any).customMessageReference : 'unknown',
+          error: error instanceof Error ? error.message : String(error),
+        });
+        const frontendUrl = this._resolveSAMLRedirectUrl();
+        return this.redirectToFrontendWithError(res, AuthRedirectErrorCode.SAML_SLO_FAILED, 'Logout failed.', frontendUrl);
+      }
+    } else if (samlResponse) {
+      try {
+        await this.samlAuthService.handleSLOResponse(ec, 'post', samlResponse);
+      } catch (error) {
+        this.logger.warn('SAML SLO LogoutResponse processing failed (POST)', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+      const frontendUrl = this._resolveSAMLRedirectUrl() || '/';
+      res.redirect(302, `${frontendUrl}/auth/login?slo=success`);
+    } else {
+      res.status(400).json({ error: 'Missing SAMLRequest or SAMLResponse parameter' });
+    }
+  }
+
+  /**
+   * Resolve a frontend URL for SAML redirects.
+   * Uses the user-type → frontend-service reverse lookup from `frontendServices.usersManagement`.
+   * When `userType` is provided (post-identification), resolves the frontend service that serves that user type.
+   * Falls back to the config's default frontend service (first with any `isDefault` entry).
+   */
+  private _resolveSAMLRedirectUrl(userType?: string): string | undefined {
+    try {
+      const frontendServiceName = userType
+        ? this.appConfigService.resolveFrontendServiceNameFromUserType(userType)
+        : this.appConfigService.resolveDefaultFrontendServiceName();
+      if (!frontendServiceName) return undefined;
+      return this.resolveFrontendAppPublicUrlFromFrontendServiceName(frontendServiceName);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * GET+POST /auth/oauth2/callback/:providerRef
+   *
+   * Handles the IdP redirect after user authentication.
+   * Accepts both GET and POST — TRAP 5: Apple uses response_mode=form_post.
+   *
+   * Flow:
+   * 1. Extract code/state from query (GET) or body (POST)
+   * 2. handleCallback() — validate state, exchange code, extract profile
+   * 3. provisionOrLinkUser() — find/create user, create identity link
+   * 4. Issue JWT tokens via AuthTokenIssuer.issueTokensForUser() (TRAP 12)
+   * 5. Create AUTH_CODE_EXCHANGE consumable token containing JWT tokens
+   * 6. Redirect to frontend /auth/callback?code={consumableTokenCode}
+   *
+   * [Capacitor] [OAuth2] [SAML]
+   * The final redirect URL ({frontendUrl}/auth/callback?code=xxx) must be reachable by
+   * the client. On web, it's a normal navigation. On Capacitor, this URL must be configured
+   * as a Universal Link (iOS) / App Link (Android) so the OS routes it to the native app.
+   * The frontendUrl in app config may need a platform-aware variant (e.g., a custom URL scheme
+   * fallback: com.wildo.app://auth/callback?code=xxx) if Universal Links are not configured.
+   *
+   * TRAP 13: Audit logging for OAuth2 logins happens HERE (not in the engine).
+   */
+  private async oauth2Callback(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    // M10 fix: Check for IdP error parameters FIRST, before extracting code/state.
+    // If the IdP sends both error and code/state (some IdPs do this), we must handle
+    // the error rather than consuming the state token and attempting a code exchange
+    // that will fail with an opaque error.
+    const idpError = (req.query.error as string) || req.body?.error;
+    if (idpError) {
+      const errorDescription = (req.query.error_description as string) || req.body?.error_description || 'Authentication denied by identity provider';
+
+      // Try to peek at the state token (without consuming it) to resolve the frontendUrl
+      // for a user-friendly redirect instead of a raw JSON 400 response.
+      // The state token expires naturally — not consuming it is safe.
+      let errorRedirectUrl: string | undefined;
+      let errorReturnUrl: string | undefined;
+      const stateValue = (req.query.state as string) || req.body?.state;
+      if (stateValue) {
+        try {
+          const stateToken = await this.consumableTokenService.validateToken(stateValue);
+          const stateMetadata = stateToken.metadata as Record<string, unknown> | undefined;
+          const frontendServiceName = stateMetadata?.frontendServiceName as string | undefined;
+          errorReturnUrl = typeof stateMetadata?.returnUrl === 'string'
+            ? stateMetadata.returnUrl
+            : undefined;
+          if (frontendServiceName) {
+            errorRedirectUrl = this.resolveFrontendAppPublicUrlFromFrontendServiceName(frontendServiceName);
+          }
+        } catch {
+          // State token invalid/expired — fall through to JSON fallback
+        }
+      }
+
+      return this.redirectToFrontendWithError(res, idpError, errorDescription, errorRedirectUrl, errorReturnUrl);
+    }
+
+    // 1. Extract code and state from query (GET) or body (POST)
+    const code = (req.query.code as string) || req.body?.code;
+    const state = (req.query.state as string) || req.body?.state;
+
+    if (!code || !state) {
+      return this.redirectToFrontendWithError(res, AuthRedirectErrorCode.MISSING_PARAMS, 'Missing code or state parameter');
+    }
+
+    // Hoisted so the catch block can use it for error redirects
+    let frontendUrl: string | undefined;
+    let callbackReturnUrl: string | undefined;
+
+    try {
+      // 2. Handle callback — validate state, exchange code, extract profile
+      const callbackParams = {
+        code,
+        state,
+        body: req.method === 'POST' ? req.body : undefined, // Apple form_post: body contains `user` JSON
+      };
+      const { normalizedProfile, connection, stateMetadata } = await this.oauth2Service.handleCallback(callbackParams);
+
+      // Resolve the frontend URL from the state token's frontendServiceName field.
+      // This is the frontend that initiated the OAuth2 flow — redirects must go back there.
+      frontendUrl = stateMetadata.frontendServiceName
+        ? this.resolveFrontendAppPublicUrlFromFrontendServiceName(stateMetadata.frontendServiceName)
+        : undefined;
+      callbackReturnUrl = stateMetadata.returnUrl;
+
+      // 3. Provision or link user
+      const { userId, isNewUser } = await this.oauth2Service.provisionOrLinkUser(normalizedProfile, connection);
+
+      const frontendServiceName = stateMetadata.frontendServiceName;
+      if (frontendServiceName) {
+        const authenticatedUser = await this.userLookup.findUserById(ec, userId);
+        const authenticatedUserType = authenticatedUser?.userTypes?.[0];
+        const userManagement = authenticatedUserType
+          ? this.appConfigService.getFrontendServiceUserManagementEntry(frontendServiceName, authenticatedUserType)
+          : null;
+
+        if (!authenticatedUserType || !userManagement?.auth) {
+          throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+            customMessageReference: ErrorCustomMessageReference.AUTHORIZATION,
+            context: {
+              message:
+                `Authentication is disabled for frontend service "${frontendServiceName}"` +
+                (authenticatedUserType ? ` and user type "${authenticatedUserType}"` : ''),
+              frontendServiceName,
+              activeUserType: authenticatedUserType,
+            },
+          });
+        }
+      }
+
+      const tokens = await this.tokenIssuer.issueTokensForUser(userId, undefined, {
+        lastAuthenticatedAt: Math.floor(Date.now() / 1000),
+      });
+
+      // 5. Create AUTH_CODE_EXCHANGE consumable token with JWT tokens as metadata
+      const exchangeToken = await this.consumableTokenService.createToken({
+        tokenType: CoreConsumableTokenTypes.AUTH_CODE_EXCHANGE,
+        consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
+        expiresIn: { value: 5, unit: DurationUnit.MINUTES },
+        userId: userId,
+        resourceIdentifier: CoreResourceType.USERS,
+        metadata: {
+          accessToken: tokens.accessToken,
+          refreshToken: tokens.refreshToken,
+          expiresIn: tokens.expiresIn,
+          providerRef: connection.providerRef,
+          isNewUser: isNewUser,
+        },
+      });
+
+      // TRAP 13: Audit log OAuth2 login (audit stays in the route handler, not engine)
+      const deviceInfo = {
+        ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+        userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+      };
+
+      await this.auditLogsService.logUserSSOLogin({
+        userId: userId,
+        email: normalizedProfile.email,
+        providerRef: connection.providerRef,
+        connectionType: connection.connectionType as SsoConnectionType,
+      authSource: AuthSource.OIDC,
+      organizationId: connection.organization?.organizationId,
+        ipAddress: deviceInfo.ipAddress,
+        userAgent: deviceInfo.userAgent,
+        sessionId: `oauth2:${connection.providerRef}:${userId}`,
+      });
+
+      this.logDebug('OAuth2 callback processed successfully', {
+        providerRef: connection.providerRef,
+        userId,
+        isNewUser,
+      });
+
+      // 6. Redirect to frontend with the one-time exchange code (Decision 7)
+      this.redirectToFrontendWithCode(res, exchangeToken.token, frontendUrl, stateMetadata.returnUrl);
+
+    } catch (error) {
+      // Redirect to frontend with error instead of returning JSON.
+      // frontendUrl may be set if handleCallback succeeded but a later step failed.
+      // If handleCallback itself failed, frontendUrl is undefined → JSON fallback.
+      const message = error instanceof Error ? error.message : 'OAuth2 authentication failed';
+      this.logDebug('OAuth2 callback failed', { error: message });
+      return this.redirectToFrontendWithError(
+        res,
+        AuthRedirectErrorCode.OAUTH_FAILED,
+        message,
+        frontendUrl,
+        callbackReturnUrl,
+      );
+    }
+  }
+
+  /**
+   * POST /auth/token/exchange
+   * Body: { code: string }
+   * Response: { accessToken, refreshToken, expiresIn }
+   *
+   * The frontend calls this after receiving the one-time code from the OAuth2 callback redirect.
+   * Validates and consumes the AUTH_CODE_EXCHANGE consumable token, returns the JWT tokens.
+   *
+   * Decision 7: Tokens never appear in URL — only a one-time code.
+   */
+  private async tokenExchange(req: Request, res: Response): Promise<void> {
+    const { code } = TokenExchangeBodySchema.parse(req.body || {});
+
+    // Consume the token atomically (prevents race conditions vs separate validate+consume)
+    let consumedToken;
+    try {
+      consumedToken = await this.consumableTokenService.consumeToken(code);
+    } catch {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_INVALID_TOKEN,
+        context: { message: 'Invalid or expired exchange code' },
+      });
+    }
+
+    // Defense-in-depth: verify the token type is AUTH_CODE_EXCHANGE (same pattern as Step 4 OAUTH2_STATE check)
+    if (consumedToken.tokenType !== CoreConsumableTokenTypes.AUTH_CODE_EXCHANGE) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_INVALID_TOKEN,
+        context: { message: 'Invalid token type for code exchange' },
+      });
+    }
+
+    const metadata = consumedToken.metadata as Record<string, unknown>;
+
+    if (consumedToken.userId) {
+      await this.handleAnonymousTranspositionForTokenExchange(req, consumedToken.userId);
+    }
+
+    this.jsonSuccess(res, {
+      accessToken: metadata.accessToken,
+      refreshToken: metadata.refreshToken,
+      expiresIn: metadata.expiresIn,
+    });
+  }
+
+  /**
+   * POST /auth/logout
+   * Body: { refreshToken: string }
+   * Response: 204 No Content
+   *
+   * Revokes the refresh token. Accessible both with and without a valid JWT
+   * (user's access token may be expired when they logout).
+   */
+  private async logout(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const { refreshToken } = LogoutBodySchema.parse(req.body || {});
+
+    // Try to decode the refresh token to get identity for audit (best-effort, don't fail logout if decode fails)
+    let logoutUserId: string | undefined;
+    try {
+      const decoded = await this.jwtService.verifyRefreshToken(refreshToken);
+      if (typeof decoded === 'object' && decoded !== null) {
+        const payload = decoded as Record<string, unknown>;
+        logoutUserId = typeof payload.userId === 'string' ? payload.userId : undefined;
+      }
+    } catch { /* token may be expired — that's fine */ }
+
+    // Revoke the refresh token by adding its JTI to the Redis blacklist.
+    // The token issuer's refreshAccessToken() checks this blacklist before issuing new tokens.
+    await this.tokenIssuer.revokeRefreshToken(refreshToken);
+
+    // H5: Audit logout
+    this.auditLogsService.logUserLogout({
+      userId: logoutUserId || 'unknown',
+      ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+      userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+    }).catch(() => {}); // fire-and-forget
+
+    this.logDebug('Logout completed — refresh token revoked');
+
+    res.status(204).send();
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Password Reset Route Handlers (Step 7)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * POST /auth/password-reset/request → AuthPasswordResetService.requestPasswordReset
+   */
+  private async passwordResetRequest(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const { email } = PasswordResetRequestDtoSchema.parse(req.body || {});
+
+    const ipAddress = AuthControllerUtils.getClientIpFromRequest(req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.RESET_EMAIL}${email.toLowerCase()}`, 3, 3600);
+    if (ipAddress !== 'unknown') {
+      await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.RESET_IP}${ipAddress}`, 5, 3600);
+    }
+
+    const frontendUrl = this.resolveFrontendAppPublicUrl(req);
+    const result = await this.passwordResetService.requestPasswordReset(ec, {
+      email, frontendUrl, ipAddress, userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+    });
+    this.jsonSuccess(res, result);
+  }
+
+  /**
+   * POST /auth/password-reset/complete → AuthPasswordResetService.completePasswordReset
+   */
+  private async passwordResetComplete(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const { token, newPassword } = PasswordResetCompleteDtoSchema.parse(req.body || {});
+
+    const result = await this.passwordResetService.completePasswordReset(ec, {
+      token, newPassword,
+      ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+      userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+    });
+    this.jsonSuccess(res, result);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Registration Route Handlers (Step 8) → AuthRegistrationService
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * POST /auth/register → AuthRegistrationService.registerUser
+   */
+  private async register(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const { email, firstName, lastName, password, organizationName } = UserRegisterApiDtoSchema.parse(req.body || {});
+    const ipAddress = AuthControllerUtils.getClientIpFromRequest(req);
+
+    if (ipAddress !== 'unknown') await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.REGISTER_IP}${ipAddress}`, 3, 60);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.REGISTER_EMAIL}${email.toLowerCase()}`, 3, 3600);
+
+    const frontendUrl = this.resolveFrontendAppPublicUrl(req);
+
+    // W3.4 + AUTH-10: Resolve activeUserType for registration context.
+    // For registration, the header is the authoritative source since the user doesn't exist yet.
+    // The registration service validates the resolved type allows registration (mode != disabled).
+    // AUTH-10: Cross-validate Origin against the claimed frontend service to prevent user-type spoofing.
+    const frontendServiceNameReg = req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] as string | undefined;
+    this._validateFrontendAppOrigin(req, frontendServiceNameReg);
+    const activeUserTypeReg = frontendServiceNameReg
+      ? this.appConfigService.resolveUserTypeFromFrontendServiceName(frontendServiceNameReg) ?? undefined
+      : undefined;
+
+    const result = await this.registrationService.registerUser(ec,
+      { email, firstName, lastName, password, organizationName },
+      { frontendUrl, ipAddress, userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown', frontendServiceName: frontendServiceNameReg, activeUserType: activeUserTypeReg },
+    );
+    this.jsonSuccess(res, result);
+  }
+
+  /**
+   * POST /auth/invitation/accept → AuthRegistrationService.acceptInvitation
+   */
+  private async acceptInvitation(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const { invitationToken, firstName, lastName, password } = UserInvitationApiDtoSchema.parse(req.body || {});
+    const ipAddress = AuthControllerUtils.getClientIpFromRequest(req);
+
+    if (ipAddress !== 'unknown') {
+      await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.INVITATION_ACCEPT_IP}${ipAddress}`, 10, 60);
+    }
+
+    const result = await this.registrationService.acceptInvitation(ec, {
+      invitationToken,
+      firstName,
+      lastName,
+      password,
+      ipAddress,
+      userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+    });
+
+    if (result.accessToken && result.userId) {
+      await this.handleAnonymousTranspositionForTokenExchange(req, result.userId);
+    }
+
+    this.jsonSuccess(res, result);
+  }
+
+  /**
+   * POST /auth/invitation/reject → AuthRegistrationService.rejectInvitation
+   */
+  private async rejectInvitation(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const { invitationToken, rejectionReason } = UserInvitationRejectApiDtoSchema.parse(req.body || {});
+    const ipAddress = AuthControllerUtils.getClientIpFromRequest(req);
+
+    if (ipAddress !== 'unknown') {
+      await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.INVITATION_REJECT_IP}${ipAddress}`, 10, 60);
+    }
+
+    const result = await this.registrationService.rejectInvitation(ec, {
+      invitationToken,
+      rejectionReason,
+    });
+
+    this.jsonSuccess(res, result);
+  }
+
+  /**
+   * POST /auth/verify-email → AuthRegistrationService.verifyEmail
+   */
+  private async verifyEmail(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const { token, email } = EmailVerifyDtoSchema.parse(req.body || {});
+
+    const result = await this.registrationService.verifyEmail(ec, {
+      token, email,
+      ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+      userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+    });
+
+    if (result.accessToken && result.userId) {
+      await this.handleAnonymousTranspositionForTokenExchange(req, result.userId);
+    }
+
+    this.jsonSuccess(res, result);
+  }
+
+  /**
+   * POST /auth/resend-verification → AuthRegistrationService.resendVerificationEmail
+   */
+  private async resendVerificationEmail(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const { email } = z.object({
+      email: z.string().email(),
+    }).parse(req.body || {});
+
+    const ipAddress = AuthControllerUtils.getClientIpFromRequest(req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.RESEND_VERIF_EMAIL}${email.toLowerCase()}`, 3, 600);
+    if (ipAddress !== 'unknown') await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.RESEND_VERIF_IP}${ipAddress}`, 5, 600);
+
+    const frontendUrl = this.resolveFrontendAppPublicUrl(req);
+    const result = await this.registrationService.resendVerificationEmail(ec, {
+      email, frontendUrl, ipAddress,
+      userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+    });
+    this.jsonSuccess(res, result);
+  }
+
+  /**
+   * POST /auth/onboarding/complete-org → AuthRegistrationService.completeOrgOnboarding
+   */
+  private async completeOrgOnboarding(req: Request, res: Response): Promise<void> {
+    const clientIp = AuthControllerUtils.getClientIpFromRequest(req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.ORG_ONBOARDING_IP}${clientIp}`, 10, 60);
+
+    const ec = await this._getPreAuthExecutionContext();
+    const { sessionId, organizationName } = z.object({
+      sessionId: z.string(),
+      organizationName: z.string().min(1).max(200)
+        .regex(/^[^<>"'`;{}()\\]+$/, 'Organization name contains disallowed characters'),
+    }).parse(req.body || {});
+
+    const result = await this.registrationService.completeOrgOnboarding(ec, {
+      sessionId,
+      organizationName: organizationName.trim(),
+    });
+    this.jsonSuccess(res, result);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // MFA: Email OTP Route Handlers (Step 10)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * POST /auth/mfa/email-otp/send
+   * Body: { sessionId: string }
+   * Response: { message: string }
+   *
+   * Generates a 6-digit OTP, stores as consumable token, sends email to user.
+   * Must be called after first factor completion (session state = FIRST_FACTOR_COMPLETED).
+   */
+  private async mfaEmailOTPSend(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const body = z.object({ sessionId: z.string().min(1) }).parse(req.body || {});
+
+    this.logDebug('MFA Email OTP send requested', { sessionId: body.sessionId });
+
+    // Orchestrator handles validation, rate limiting, OTP generation, and token storage.
+    // It returns the OTP code and the user's email — we send the email here.
+    const { otpToken, email, expiryMinutes } = await this.authService.sendEmailOTP(ec, body.sessionId);
+
+    // Send the OTP email
+    try {
+      const appIdentity = this.appConfigService.config.appIdentity;
+      await this.emailService.send({
+        templateRef: SystemEmailTemplateRef.EMAIL_OTP,
+        locale: AvailableLanguage.EN,
+        type: EmailTemplateType.TRANSACTIONAL,
+        to: email,
+        context: {
+          currentObject: { email },
+          objectContext: {
+            primaryScopeContext: {
+              appName: appIdentity.appName,
+              applicationId: this.appConfigService.applicationId,
+            },
+          },
+          userContext: { userId: '', email }, // userId not available in pre-auth flow; email is the key identifier
+          additionalContext: { otpCode: otpToken, expiresInMinutes: expiryMinutes },
+        },
+      });
+      this.logDebug('MFA Email OTP sent', { email });
+    } catch (emailError) {
+      this.logger.error('Failed to send MFA email OTP', {
+        error: emailError instanceof Error ? emailError.message : String(emailError),
+      });
+      // Still return success — the OTP was generated and stored.
+      // User can retry sending if email delivery fails.
+    }
+
+    // H5: Audit MFA email OTP sent
+    this.auditLogsService.logUserMFAEmailOTPSent({
+      email,
+      sessionId: body.sessionId,
+      ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+      userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+    }).catch(() => {});
+
+    this.jsonSuccess(res, this.authResponseHelper.getAuthResponse(AuthResponseMessageRef.MFA_EMAIL_OTP_SENT));
+  }
+
+  /**
+   * POST /auth/mfa/email-otp/verify
+   * Body: { sessionId: string, code: string }
+   * Response: AuthenticationResponse (from orchestrator)
+   *
+   * Verifies the submitted OTP code against stored consumable tokens.
+   * On success, returns authentication result (may complete auth or require more factors).
+   */
+  private async mfaEmailOTPVerify(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const body = z.object({
+      sessionId: z.string().min(1),
+      code: z.string().regex(/^\d{4,8}$/, { error: 'Invalid OTP code' }),
+    }).parse(req.body || {});
+
+    this.logDebug('MFA Email OTP verify requested', { sessionId: body.sessionId });
+
+    // Build an EmailOTPAuthRequest and route through the main authenticate method
+    // so that completion logic (token issuance) is handled uniformly.
+    const authRequest = {
+      sessionId: body.sessionId,
+      method: AuthMethod.EMAIL_OTP as const,
+      factorLevel: AuthFactorLevel.SECOND as const,
+      token: body.code,
+      rememberMe: false,
+      requestedIntegrations: [],
+    };
+
+    const result = await this.authService.authenticate(ec, authRequest);
+    this.jsonSuccess(res, result);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // MFA: TOTP Route Handlers (Step 11)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * POST /auth/mfa/totp/setup
+   * Headers: Authorization: Bearer <accessToken>
+   * Response: { secret: string, qrCodeUri: string, backupCodes: string[] }
+   *
+   * Uses `extractFromSessionOrJwt` — the caller may be fully authenticated (JWT)
+   * or partially authenticated (MFA_REQUIRED / MFA_ENROLLMENT_REQUIRED session).
+   * In the partial-auth path, identity is not yet fully proven, so we intentionally
+   * use a pre-auth EC (no userId attribution). Security relies on the JWT guard /
+   * session state validation in `extractFromSessionOrJwt`, not on the EC's role.
+   */
+  private async mfaTOTPSetup(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const { userId, email } = await this.authJwtGuard.extractFromSessionOrJwt(ec, req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.TOTP_SETUP}${userId}`, 5, 3600);
+
+    const result = await this.mfaService.setupTOTP(ec, {
+      userId,
+      email,
+      ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+      userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+    });
+
+    this.jsonSuccess(res, result);
+  }
+
+  /**
+   * POST /auth/mfa/totp/verify-setup
+   * Headers: Authorization: Bearer <accessToken>
+   * Body: { code: string }
+   * Response: { verified: boolean }
+   *
+   * Uses `extractFromSessionOrJwt` — caller may be partially authenticated
+   * (mid-MFA enrollment). Pre-auth EC used intentionally: identity is not
+   * fully proven until MFA setup completes. See mfaTOTPSetup JSDoc.
+   */
+  private async mfaTOTPVerifySetup(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const { userId } = await this.authJwtGuard.extractFromSessionOrJwt(ec, req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.TOTP_SETUP}${userId}`, 5, 3600);
+    const body = z.object({
+      code: z.string().regex(/^\d{6}$/, { error: 'Invalid TOTP code — must be 6 digits' }),
+    }).parse(req.body || {});
+
+    const result = await this.mfaService.verifyTOTPSetup(ec, {
+      userId,
+      code: body.code,
+      ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+      userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+    });
+
+    this.jsonSuccess(res, result);
+  }
+
+  /**
+   * POST /auth/mfa/totp/verify
+   * Body: { sessionId: string, code: string }
+   * Response: AuthenticationResponse (from orchestrator)
+   *
+   * Verifies a TOTP code during login MFA flow.
+   * Routes through the main authenticate method for uniform completion logic.
+   */
+  private async mfaTOTPVerify(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const body = z.object({
+      sessionId: z.string().min(1),
+      code: z.string().min(1, { error: 'TOTP code is required' }),
+    }).parse(req.body || {});
+
+    this.logDebug('MFA TOTP verify requested', { sessionId: body.sessionId });
+
+    const authRequest = {
+      sessionId: body.sessionId,
+      method: AuthMethod.TOTP as const,
+      factorLevel: AuthFactorLevel.SECOND as const,
+      token: body.code,
+      rememberMe: false,
+      requestedIntegrations: [],
+    };
+
+    const result = await this.authService.authenticate(ec, authRequest);
+    this.jsonSuccess(res, result);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // WebAuthn/Passkey Route Handlers (Phase G1)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * POST /auth/passkey/register/options
+   * Headers: Authorization: Bearer <accessToken>
+   * Response: PublicKeyCredentialCreationOptionsJSON
+   *
+   * Uses `extractFromSessionOrJwt` — caller may be partially authenticated
+   * (mid-MFA enrollment, registering a passkey as their MFA method).
+   * Pre-auth EC used intentionally: identity not fully proven until
+   * MFA enrollment completes. See mfaTOTPSetup JSDoc.
+   */
+  private async handlePasskeyRegisterOptions(req: Request, res: Response): Promise<void> {
+    try {
+      const ec = await this._getPreAuthExecutionContext();
+      const { userId, email } = await this.authJwtGuard.extractFromSessionOrJwt(ec, req);
+      await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.PASSKEY_REGISTER}${userId}`, 10, 3600);
+      const options = await this.webAuthnService.generateRegistrationOptions(ec, userId, email);
+      this.jsonSuccess(res, options);
+    } catch (error) {
+      if (isWildoBackendError(error)) throw error;
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+        context: { operation: AUTH_OPERATION.PASSKEY_REGISTER_OPTIONS },
+      });
+    }
+  }
+
+  /**
+   * POST /auth/passkey/register/verify
+   * Headers: Authorization: Bearer <accessToken>
+   * Body: { response: RegistrationResponseJSON, name?: string }
+   * Response: { registered: boolean, credential: { credentialId, name, createdAt } }
+   *
+   * Uses `extractFromSessionOrJwt` — caller may be partially authenticated
+   * (mid-MFA enrollment). Pre-auth EC used intentionally: identity not fully
+   * proven until MFA enrollment completes. See mfaTOTPSetup JSDoc.
+   */
+  private async handlePasskeyRegisterVerify(req: Request, res: Response): Promise<void> {
+    try {
+      const ec = await this._getPreAuthExecutionContext();
+      const { userId, email } = await this.authJwtGuard.extractFromSessionOrJwt(ec, req);
+      await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.PASSKEY_REGISTER}${userId}`, 10, 3600);
+      const PasskeyRegisterVerifyBodySchema = z.object({
+        response: z.object({
+          id: z.string(),
+          rawId: z.string(),
+          response: z.object({
+            attestationObject: z.string(),
+            clientDataJSON: z.string(),
+          }),
+          authenticatorAttachment: z.enum(['cross-platform', 'platform'] as const).optional(),
+          clientExtensionResults: z.record(z.string(), z.any()).default({}),
+          type: z.literal('public-key'),
+        }),
+        name: z.string().max(100).optional(),
+      });
+      const { response, name } = PasskeyRegisterVerifyBodySchema.parse(req.body || {});
+      const credential = await this.webAuthnService.verifyRegistrationResponse(ec, userId, response, name);
+
+      await this.auditLogsService.logUserPasskeyRegistered({
+        userId: userId,
+        email,
+        credentialId: credential.credentialId,
+        credentialName: credential.name,
+        credentialDeviceType: credential.credentialDeviceType,
+        ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+        userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+      });
+
+      this.jsonSuccess(res, {
+        registered: true,
+        credential: {
+          credentialId: credential.credentialId,
+          name: credential.name,
+          createdAt: credential.createdAt,
+        },
+      });
+    } catch (error) {
+      if (isWildoBackendError(error)) throw error;
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+        context: { operation: AUTH_OPERATION.PASSKEY_REGISTER_VERIFY },
+      });
+    }
+  }
+
+  /**
+   * POST /auth/passkey/authenticate/options
+   * Body: { sessionId: string }
+   * Response: PublicKeyCredentialRequestOptionsJSON
+   *
+   * Unauthenticated. Part of login flow. Generates authentication options for the session's user.
+   */
+  private async handlePasskeyAuthOptions(req: Request, res: Response): Promise<void> {
+    try {
+      const ec = await this._getPreAuthExecutionContext();
+      const { sessionId } = req.body;
+      if (!sessionId) {
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+          context: { reason: 'sessionId is required' },
+        });
+      }
+
+      const session = await this.authService.getAuthenticationSessionState(ec, sessionId);
+      if (!session) {
+        throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_SESSION_INVALID,
+          context: { sessionId },
+        });
+      }
+
+      const validStatesForPasskeyAuth = new Set([
+        AuthenticationSessionState.IDENTIFIED,
+        AuthenticationSessionState.FIRST_FACTOR_IN_PROGRESS,
+        AuthenticationSessionState.FIRST_FACTOR_COMPLETED,
+        AuthenticationSessionState.MFA_REQUIRED,
+      ]);
+      if (!validStatesForPasskeyAuth.has(session.state as AuthenticationSessionState)) {
+        throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+          context: { reason: 'Invalid session state for passkey authentication' },
+        });
+      }
+
+      const userId = session.userId;
+      if (!userId) {
+        throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+          context: { reason: 'No user associated with session' },
+        });
+      }
+
+      const options = await this.webAuthnService.generateAuthenticationOptions(ec, userId);
+      this.jsonSuccess(res, options);
+    } catch (error) {
+      if (isWildoBackendError(error)) throw error;
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+        context: { operation: AUTH_OPERATION.PASSKEY_AUTH_OPTIONS },
+      });
+    }
+  }
+
+  /**
+   * POST /auth/passkey/authenticate/verify
+   * Body: { sessionId: string, response: AuthenticationResponseJSON, factorLevel?: AuthFactorLevel }
+   * Response: AuthenticationResponse (from orchestrator)
+   *
+   * Unauthenticated. Routes through authService.authenticate() for uniform completion logic.
+   */
+  private async handlePasskeyAuthVerify(req: Request, res: Response): Promise<void> {
+    try {
+      const ec = await this._getPreAuthExecutionContext();
+      const PasskeyAuthVerifyBodySchema = z.object({
+        sessionId: z.string().min(1),
+        response: z.object({
+          id: z.string(),
+          rawId: z.string(),
+          response: z.object({
+            authenticatorData: z.string(),
+            clientDataJSON: z.string(),
+            signature: z.string(),
+            userHandle: z.string().optional(),
+          }),
+          authenticatorAttachment: z.enum(['cross-platform', 'platform'] as const).optional(),
+          clientExtensionResults: z.record(z.string(), z.any()).default({}),
+          type: z.literal('public-key'),
+        }),
+        factorLevel: z.string().optional(),
+      });
+      const { sessionId, response, factorLevel } = PasskeyAuthVerifyBodySchema.parse(req.body || {});
+
+      const authResponse = await this.authService.authenticate(ec, {
+        sessionId,
+        method: AuthMethod.PASSKEY,
+        factorLevel: (factorLevel as AuthFactorLevel) || AuthFactorLevel.FIRST,
+        response,
+        rememberMe: false,
+        requestedIntegrations: [],
+      });
+      await this.handleAnonymousTransposition(req, authResponse);
+      this.jsonSuccess(res, authResponse);
+    } catch (error) {
+      if (isWildoBackendError(error)) throw error;
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+        context: { operation: AUTH_OPERATION.PASSKEY_AUTH_VERIFY },
+      });
+    }
+  }
+
+  /**
+   * GET /auth/passkey/list
+   * Headers: Authorization: Bearer <accessToken>
+   * Response: { credentials: PasskeyCredentialEntry[] } (safe fields only)
+   *
+   * JWT-authenticated. Lists registered passkeys for the authenticated user.
+   */
+  private async handlePasskeyList(req: Request, res: Response): Promise<void> {
+    try {
+      const preAuthEc = await this._getPreAuthExecutionContext();
+      const { userId } = await this.authJwtGuard.extractAuthenticatedUser(preAuthEc, req);
+      const ec = await this._getAuthenticatedExecutionContext(userId);
+      const credentials = await this.webAuthnService.getCredentials(ec, userId);
+
+      const safeCredentials = credentials.map((c) => ({
+        credentialId: c.credentialId,
+        name: c.name,
+        createdAt: c.createdAt,
+        lastUsedAt: c.lastUsedAt,
+        credentialDeviceType: c.credentialDeviceType,
+        credentialBackedUp: c.credentialBackedUp,
+      }));
+      this.jsonSuccess(res, { credentials: safeCredentials });
+    } catch (error) {
+      if (isWildoBackendError(error)) throw error;
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+        context: { operation: AUTH_OPERATION.PASSKEY_LIST },
+      });
+    }
+  }
+
+  /**
+   * POST /auth/passkey/remove
+   * Headers: Authorization: Bearer <accessToken>
+   * Body: { credentialId: string }
+   * Response: { removed: boolean }
+   *
+   * JWT-authenticated. Removes a passkey from the authenticated user.
+   */
+  private async handlePasskeyRemove(req: Request, res: Response): Promise<void> {
+    try {
+      const preAuthEc = await this._getPreAuthExecutionContext();
+      const { userId, email } = await this.authJwtGuard.extractAuthenticatedUser(preAuthEc, req);
+      const ec = await this._getAuthenticatedExecutionContext(userId);
+      const { credentialId } = req.body;
+      if (!credentialId) {
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+          context: { reason: 'credentialId is required' },
+        });
+      }
+      await this.methodManagementService.enforceUserMethodRemovalAllowed(ec, userId);
+
+      const credentials = await this.webAuthnService.getCredentials(ec, userId);
+      const target = credentials.find((c) => c.credentialId === credentialId);
+
+      // D9 safety check: count password + passkeys + identity links
+      const authMethodCounts = await this.methodManagementService.countAuthMethods(ec, userId);
+      if (authMethodCounts.total <= 1) {
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+          context: { reason: 'Cannot remove your only authentication method' },
+        });
+      }
+
+      await this.webAuthnService.removeCredential(ec, userId, credentialId);
+
+      await this.auditLogsService.logUserPasskeyRemoved({
+        userId: userId,
+        email,
+        credentialId,
+        credentialName: target?.name || 'Unknown',
+        ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+        userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+      });
+
+      this.jsonSuccess(res, { removed: true });
+    } catch (error) {
+      if (isWildoBackendError(error)) throw error;
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+        context: { operation: AUTH_OPERATION.PASSKEY_REMOVE },
+      });
+    }
+  }
+
+  /**
+   * POST /auth/passkey/rename
+   * Headers: Authorization: Bearer <accessToken>
+   * Body: { credentialId: string, name: string }
+   * Response: { renamed: boolean }
+   *
+   * JWT-authenticated. Renames a passkey for the authenticated user.
+   */
+  private async handlePasskeyRename(req: Request, res: Response): Promise<void> {
+    try {
+      const preAuthEc = await this._getPreAuthExecutionContext();
+      const { userId } = await this.authJwtGuard.extractAuthenticatedUser(preAuthEc, req);
+      const ec = await this._getAuthenticatedExecutionContext(userId);
+      const { credentialId, name } = req.body;
+      if (!credentialId || !name) {
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+          context: { reason: 'credentialId and name are required' },
+        });
+      }
+      await this.webAuthnService.renameCredential(ec, userId, credentialId, name);
+      this.jsonSuccess(res, { renamed: true });
+    } catch (error) {
+      if (isWildoBackendError(error)) throw error;
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+        context: { operation: AUTH_OPERATION.PASSKEY_RENAME },
+      });
+    }
+  }
+
+
+  /**
+   * Pre-auth EC for operations where the caller is not yet authenticated.
+   * Uses PUBLIC_EXECUTION with APP_PUBLIC (minimal privilege, no initiator).
+   * Primary intent: user identification/lookup across auth handlers.
+   *
+   * Also used as the bootstrap EC for JWT/session extraction calls
+   * (`extractAuthenticatedUser`, `extractFromSessionOrJwt`) since identity
+   * is unknown at that point.
+   */
+  private async _getPreAuthExecutionContext() {
+    return this.authEcFactory.createForPreAuthOperation(this.authEcFactory.getUsersReadOperationPath());
+  }
+
+  /**
+   * Authenticated EC for operations where the caller's identity has been
+   * confirmed via JWT. Carries userId attribution for audit trail and
+   * uses APP_USER role.
+   *
+   * Endpoints that call `extractAuthenticatedUser` (requiring a valid JWT)
+   * should use this for all downstream service calls after extraction.
+   */
+  private async _getAuthenticatedExecutionContext(userId: string) {
+    return this.authEcFactory.createForAuthenticatedAuthOperation(userId, this.authEcFactory.getUsersReadOperationPath());
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Private: Frontend Redirect Helpers
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Redirect to the frontend callback page with the one-time exchange code.
+   * URL: {frontendUrl}/auth/callback?code={exchangeCode}
+   *
+   * @param frontendUrl - The resolved frontend publicUrl from the OAuth2 state token.
+   *   If undefined (state token didn't carry frontendServiceName — legacy flows), throws.
+   */
+  private redirectToFrontendWithCode(
+    res: Response,
+    exchangeCode: string,
+    frontendUrl?: string,
+    returnUrl?: string,
+  ): void {
+    if (!frontendUrl) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+        context: { message: 'Cannot redirect: frontendServiceName was not stored in OAuth2 state token. The originating frontend is unknown.' },
+      });
+    }
+    const searchParams = new URLSearchParams({
+      code: exchangeCode,
+    });
+    if (returnUrl) {
+      searchParams.set('redirect', returnUrl);
+    }
+    const redirectUrl = `${frontendUrl}/auth/callback?${searchParams.toString()}`;
+    res.redirect(302, redirectUrl);
+  }
+
+  /**
+   * Redirect to the frontend login page with an error.
+   * URL: {frontendUrl}/login?error={error}&reason={description}
+   *
+   * TRAP 6: Error redirect goes to login page (not generic error page)
+   * so the user can retry.
+   *
+   * If frontendUrl is undefined (state token didn't carry frontendServiceName, or error
+   * occurred before state could be read), falls back to a plain JSON error
+   * since we can't redirect to an unknown frontend.
+   */
+  private redirectToFrontendWithError(
+    res: Response,
+    error: string,
+    description: string,
+    frontendUrl?: string,
+    returnUrl?: string,
+  ): void {
+    if (!frontendUrl) {
+      res.status(400).json({ error, error_description: description });
+      return;
+    }
+    const searchParams = new URLSearchParams({
+      error,
+      reason: description,
+    });
+    if (returnUrl) {
+      searchParams.set('redirect', returnUrl);
+    }
+    const redirectUrl = `${frontendUrl}/login?${searchParams.toString()}`;
+    res.redirect(302, redirectUrl);
+  }
+
+  private validateFrontendReturnUrl(returnUrl: string, frontendUrl: string): void {
+    if (returnUrl.startsWith('/') && !returnUrl.startsWith('//')) {
+      return;
+    }
+
+    const allowedOrigins = new Set<string>();
+    try {
+      allowedOrigins.add(new URL(frontendUrl).origin);
+    } catch {
+      // frontendUrl comes from validated config, but keep the helper defensive.
+    }
+
+    for (const frontendServiceName of Object.keys(this.appConfigService.config.frontendServices ?? {})) {
+      const publicUrl = AuthControllerUtils.lookupFrontendPublicUrl(
+        this.appConfigService.config,
+        frontendServiceName,
+      );
+      if (!publicUrl) {
+        continue;
+      }
+      allowedOrigins.add(new URL(publicUrl).origin);
+    }
+
+    try {
+      const parsed = new URL(returnUrl);
+      if (allowedOrigins.has(parsed.origin)) {
+        return;
+      }
+    } catch {
+      // Invalid absolute URL — reject below.
+    }
+
+    throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+      customMessageReference: ErrorCustomMessageReference.VALIDATION,
+      context: {
+        message: 'Invalid returnUrl: must be a relative path or an allowed frontend origin',
+        returnUrl,
+      },
+    });
+  }
+
+  /**
+   * Resolve the public URL of the frontend app that initiated this request.
+   *
+   * Reads the X-Frontend-Service-Name header (a configured frontend service identity),
+   * then looks up the
+   * corresponding publicUrl from the configured runtime endpoints.
+   *
+   * Fail-fast: throws if the header is missing, the frontend service is unknown,
+   * or no publicUrl is configured for that frontend service.
+   */
+  private resolveFrontendAppPublicUrl(req: Request): string {
+    const frontendServiceName = req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] as string | undefined;
+
+    if (!frontendServiceName) {
+      throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+        context: {
+          message: 'X-Frontend-Service-Name header is required. The frontend must identify itself.',
+          header: WildoHeaderKeys.FRONTEND_SERVICE_NAME,
+        },
+      });
+    }
+
+    return this._lookupFrontendPublicUrl(frontendServiceName);
+  }
+
+  /**
+   * Resolve the frontend service identity from a raw string (e.g., from state token metadata).
+   * Returns the publicUrl for that frontend service. Throws if invalid or not configured.
+   */
+  private resolveFrontendAppPublicUrlFromFrontendServiceName(frontendServiceName: string): string {
+    return this._lookupFrontendPublicUrl(frontendServiceName);
+  }
+
+  /**
+   * Core lookup: delegates to AuthControllerUtils.lookupFrontendPublicUrl (returns null on failure),
+   * then throws if null. Preserves the original fail-fast behavior in the controller.
+   */
+  private _lookupFrontendPublicUrl(frontendServiceName: string): string {
+    const url = AuthControllerUtils.lookupFrontendPublicUrl(this.appConfigService.config, frontendServiceName);
+    if (!url) {
+      throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+        context: {
+          message: `Cannot resolve publicUrl for frontend service "${frontendServiceName}".`,
+          frontendServiceName,
+        },
+      });
+    }
+    return url;
+  }
+
+  /**
+   * AUTH-10: Cross-validate X-Frontend-Service-Name header against the browser Origin header.
+   *
+   * The Origin header is browser-enforced (forbidden header per Fetch spec) and cannot
+   * be spoofed by client-side JavaScript. If the Origin doesn't match the configured
+   * publicUrl for the claimed frontend service, the request is rejected.
+   *
+   * Non-browser clients (curl, Postman, mobile SDKs) do not send the Origin header,
+   * so this validation is skipped for them. This is acceptable because:
+   * - Rate limiting gates all registration/identify endpoints
+   * - Registration policy enforcement (mode, password policy) applies regardless
+   * - The DB override in the orchestrator protects known users independently
+   * If non-browser registration restriction is needed, use invitation tokens or API keys.
+   */
+  private _validateFrontendAppOrigin(req: Request, claimedFrontendServiceName: string | undefined): void {
+    if (!claimedFrontendServiceName) return;
+
+    const configuredUrl = AuthControllerUtils.lookupFrontendPublicUrl(this.appConfigService.config, claimedFrontendServiceName);
+    if (!configuredUrl) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHORIZATION,
+        context: {
+          message:
+            `Unknown or unbound frontend service identity "${claimedFrontendServiceName}". ` +
+            `Declare it in frontendServices and materialize runtime.endPoints.${claimedFrontendServiceName}.publicUrl before using it at runtime.`,
+          frontendServiceName: claimedFrontendServiceName,
+        },
+      });
+    }
+
+    // Origin absent → non-browser client or same-origin; skip (see JSDoc for rationale)
+    const origin = req.headers[WildoHeaderKeys.ORIGIN] as string | undefined;
+    if (!origin) return;
+
+    try {
+      const configuredOrigin = new URL(configuredUrl).origin;
+      if (origin !== configuredOrigin) {
+        this.logDebug('Origin mismatch — X-Frontend-Service-Name header does not match request Origin', {
+          claimedFrontendServiceName,
+          requestOrigin: origin,
+          configuredOrigin,
+        });
+        throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+          customMessageReference: ErrorCustomMessageReference.AUTHORIZATION,
+          context: { message: 'Request origin does not match the claimed frontend service identity.' },
+        });
+      }
+    } catch (e) {
+      if (isWildoBackendError(e)) throw e;
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Magic Link Route Handlers (Phase G2)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * POST /auth/magic-link/send
+   * Body: { email: string }
+   * Response: { message: string }
+   *
+   * Generates a magic link token and sends an email containing the link.
+   * Always returns success to prevent email enumeration.
+   */
+  private async magicLinkSend(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const body = MagicLinkSendRequestSchema.parse(req.body || {});
+    const ipAddress = AuthControllerUtils.getClientIpFromRequest(req);
+    const userAgent = req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown';
+
+    this.logDebug('Magic link send requested', { email: body.email });
+
+    // IP-based rate limit to prevent email flooding from a single source
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.MAGIC_LINK_SEND_IP}${ipAddress}`, 10, 3600);
+
+    const result = await this.authService.sendMagicLink(ec, body, { ipAddress, userAgent });
+
+    if (result.token && result.email) {
+      try {
+        const frontendUrl = this.resolveFrontendAppPublicUrl(req);
+        const magicLinkUrl = `${frontendUrl}/auth/magic-link/verify?token=${encodeURIComponent(result.token)}&email=${encodeURIComponent(result.email)}`;
+
+        const appIdentity = this.appConfigService.config.appIdentity;
+        await this.emailService.send({
+          templateRef: SystemEmailTemplateRef.MAGIC_LINK,
+          locale: AvailableLanguage.EN,
+          type: EmailTemplateType.TRANSACTIONAL,
+          to: result.email,
+          context: {
+            currentObject: { email: result.email },
+            objectContext: {
+              primaryScopeContext: {
+                appName: appIdentity.appName,
+                applicationId: this.appConfigService.applicationId,
+              },
+            },
+            userContext: { userId: result.userId || 'unknown', email: result.email },
+            additionalContext: { magicLinkUrl, tokenValue: result.token, expiresInMinutes: result.expiresInMinutes },
+          },
+        });
+      } catch (error) {
+        this.logger.error('Failed to send magic link email', {
+          email: result.email,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        // Don't reveal email delivery failure (anti-enumeration)
+      }
+    }
+
+    this.jsonSuccess(res, this.authResponseHelper.getAuthResponse(AuthResponseMessageRef.MAGIC_LINK_SENT));
+  }
+
+  /**
+   * POST /auth/magic-link/verify
+   * Body: { token: string, email: string }
+   * Response: AuthenticationResponse
+   *
+   * Validates a magic link token and returns auth tokens on success.
+   * Email is included for defense-in-depth constant-time comparison against token metadata.
+   * This is a standalone auth endpoint (not dispatched through authenticate()).
+   */
+  private async magicLinkVerify(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const body = MagicLinkVerifyRequestSchema.parse(req.body || {});
+    const ipAddress = AuthControllerUtils.getClientIpFromRequest(req);
+    const userAgent = req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown';
+
+    // IP-based rate limit for resource protection
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.MAGIC_LINK_VERIFY_IP}${ipAddress}`, 20, 60);
+
+    this.logDebug('Magic link verify requested');
+
+    const authResponse = await this.authService.verifyMagicLink(ec, body, { ipAddress, userAgent });
+
+    await this.handleAnonymousTransposition(req, authResponse);
+    this.jsonSuccess(res, authResponse);
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // SMS OTP Route Handlers (Phase G2)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * POST /auth/sms-otp/send
+   * Body: { sessionId: string, phoneNumber?: string }
+   * Response: { message: string }
+   *
+   * Generates an OTP code and sends it via SMS.
+   * Requires an active auth session. Can be used for first or second factor.
+   */
+  private async smsOTPSend(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const body = z.object({
+      sessionId: z.string().min(1),
+      phoneNumber: z.string().regex(/^\+?[1-9]\d{1,14}$/, { error: 'Invalid phone number' }).optional(),
+    }).parse(req.body || {});
+
+    this.logDebug('SMS OTP send requested', { sessionId: body.sessionId });
+
+    // IP-based rate limit to prevent SMS pump fraud from a single source
+    const ipAddress = AuthControllerUtils.getClientIpFromRequest(req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.SMS_OTP_SEND_IP}${ipAddress}`, 5, 3600);
+
+    const result = await this.authService.sendSMSOTP(ec, body.sessionId, body.phoneNumber);
+
+    const appIdentity = this.appConfigService.config.appIdentity;
+    const smsResult = await this.smsService.send(
+      result.targetPhone,
+      this.authResponseHelper.getSmsLabel(BackendSmsMessageRef.OTP_VERIFICATION_CODE, { appName: appIdentity.appName, code: result.otpCode }),
+    );
+    if (!smsResult.success) {
+      this.logger.error('SMS OTP delivery failed', {
+        sessionId: body.sessionId,
+        error: smsResult.error,
+      });
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: this.authResponseHelper.getSmsLabel(BackendSmsMessageRef.VERIFICATION_SEND_FAILED) },
+      });
+    }
+
+    this.jsonSuccess(res, { message: this.authResponseHelper.getSmsLabel(BackendSmsMessageRef.VERIFICATION_SENT) });
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Phone Verification Route Handlers (Phase G2)
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * POST /auth/phone/verify/send
+   * Body: { phoneNumber: string, sessionId?: string }
+   * Response: { message: string }
+   *
+   * Sends a verification code to prove phone number ownership.
+   * Used during account setup, not authentication.
+   */
+  private async phoneVerifySend(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const body = PhoneVerifySendRequestSchema.parse(req.body || {});
+    const ipAddress = AuthControllerUtils.getClientIpFromRequest(req);
+
+    await this.authJwtGuard.extractFromSessionOrJwt(ec, req);
+
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.PHONE_VERIFY_SEND}${body.phoneNumber}`, 3, 300);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.PHONE_VERIFY_SEND_IP}${ipAddress}`, 5, 3600);
+
+    const { otpCode } = await this.phoneVerificationService.createVerificationCode(ec, {
+      phoneNumber: body.phoneNumber,
+      ipAddress,
+    });
+
+    const appIdentity = this.appConfigService.config.appIdentity;
+    const smsResult = await this.smsService.send(
+      body.phoneNumber,
+      this.authResponseHelper.getSmsLabel(BackendSmsMessageRef.PHONE_VERIFICATION_CODE, { appName: appIdentity.appName, code: otpCode, expiry: '10' }),
+    );
+    if (!smsResult.success) {
+      this.logger.error('Phone verification SMS delivery failed', { phoneNumber: body.phoneNumber, error: smsResult.error });
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        context: { message: this.authResponseHelper.getSmsLabel(BackendSmsMessageRef.VERIFICATION_SEND_FAILED) },
+      });
+    }
+
+    this.jsonSuccess(res, { message: this.authResponseHelper.getSmsLabel(BackendSmsMessageRef.PHONE_VERIFICATION_SENT) });
+  }
+
+  /**
+   * POST /auth/phone/verify/confirm
+   * Body: { phoneNumber: string, code: string }
+   * Response: { verified: boolean }
+   *
+   * Confirms phone ownership by validating the submitted code.
+   * On success, marks the phone as verified on the user's credentials.
+   */
+  private async phoneVerifyConfirm(req: Request, res: Response): Promise<void> {
+    const ec = await this._getPreAuthExecutionContext();
+    const body = PhoneVerifyConfirmRequestSchema.parse(req.body || {});
+
+    const { userId } = await this.authJwtGuard.extractFromSessionOrJwt(ec, req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.PHONE_VERIFY_CONFIRM}${body.phoneNumber}`, 5, 300);
+
+    const result = await this.phoneVerificationService.confirmVerification(ec, {
+      phoneNumber: body.phoneNumber,
+      code: body.code,
+      userId,
+      ipAddress: AuthControllerUtils.getClientIpFromRequest(req),
+      userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+    });
+
+    this.jsonSuccess(res, result);
+  }
+
+  /**
+   * POST /auth/native-token/exchange
+   * Body: { provider: 'apple' | 'google', identityToken: string, userType?: 'user' }
+   * Response: { accessToken, refreshToken?, expiresIn?, isNewUser }
+   *
+   * Exchanges a native Apple/Google SDK identity token for a Wildo JWT.
+   * The identity token is verified against the IdP's JWKS before provisioning.
+   */
+  private async nativeTokenExchange(req: Request, res: Response): Promise<void> {
+    const ipAddress = AuthControllerUtils.getClientIpFromRequest(req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.NATIVE_EXCHANGE_IP}${ipAddress}`, 10, 60);
+
+    const body = NativeTokenExchangeRequestSchema.parse(req.body || {});
+    const { provider, identityToken, nonce } = body;
+
+    const appConfig = this.appConfigService.config;
+    const providerConfig = appConfig.externalProvidersConfigurations?.[provider]?.sso_oauth2 as
+      Record<string, unknown> | undefined;
+    const nativeClientIds = (providerConfig?.nativeClientIds as string[] | undefined) || [];
+
+    if (nativeClientIds.length === 0) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+        context: { message: `Native SDK token exchange not configured for provider '${provider}'. Set nativeClientIds in externalProvidersConfigurations.` },
+      });
+    }
+
+    try {
+      const ec = await this._getPreAuthExecutionContext();
+      const { provisionResult, normalizedProfile } = await this.oauth2Service.exchangeNativeToken(
+        provider,
+        identityToken,
+        nativeClientIds,
+        nonce,
+      );
+
+      const deviceInfo = {
+        ipAddress,
+        userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+      };
+
+      // Resolve activeUserType hint from X-Frontend-Service-Name header.
+      // The orchestrator overrides with the DB-stored userTypes[0] for the provisioned user.
+      // Cross-validate Origin against the claimed frontend service (defense-in-depth).
+      const nativeFrontendServiceName = req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] as string | undefined;
+      this._validateFrontendAppOrigin(req, nativeFrontendServiceName);
+      const nativeActiveUserType = nativeFrontendServiceName
+        ? this.appConfigService.resolveUserTypeFromFrontendServiceName(nativeFrontendServiceName) ?? undefined
+        : undefined;
+
+      const result = await this.authService.handleNativeSDKFirstFactor(
+        ec,
+        provisionResult.userId,
+        normalizedProfile.email,
+        deviceInfo,
+        nativeActiveUserType,
+        nativeFrontendServiceName,
+      );
+
+      await this.auditLogsService.logUserSSOLogin({
+        userId: provisionResult.userId,
+        email: normalizedProfile.email,
+        providerRef: provider,
+        connectionType: SsoConnectionType.SOCIAL,
+        authSource: AuthSource.OIDC,
+        ipAddress: deviceInfo.ipAddress,
+        userAgent: deviceInfo.userAgent,
+        sessionId: result.mfaRequired ? result.sessionId : `native-sdk:${provider}:${provisionResult.userId}`,
+      });
+
+      if (result.mfaRequired === true) {
+        this.jsonSuccess(res, {
+          mfaRequired: true,
+          sessionId: result.sessionId,
+          enrolledMethods: result.enrolledMethods,
+          isNewUser: provisionResult.isNewUser,
+        });
+      } else {
+        await this.handleAnonymousTranspositionForTokenExchange(req, provisionResult.userId);
+        this.jsonSuccess(res, {
+          accessToken: result.tokens.accessToken,
+          refreshToken: result.tokens.refreshToken,
+          expiresIn: result.tokens.expiresIn,
+          isNewUser: provisionResult.isNewUser,
+        });
+      }
+    } catch (error) {
+      if (isWildoBackendError(error)) throw error;
+
+      this.logger.warn('Native token exchange failed', {
+        provider,
+        error: error instanceof Error ? error.message : String(error),
+        ipAddress,
+      });
+
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_INVALID_TOKEN,
+        context: { message: 'Invalid or expired identity token' },
+      });
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // W7.3b: One-Off Session Token Handlers
+  // ═══════════════════════════════════════════════════════════════
+
+  private async createOneOffToken(req: Request, res: Response): Promise<void> {
+    const preAuthEc = await this._getPreAuthExecutionContext();
+    const ipAddress = AuthControllerUtils.getClientIpFromRequest(req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.ONE_OFF_CREATE_IP}${ipAddress}`, 30, 60);
+
+    const caller = await this.authJwtGuard.extractAuthenticatedUser(preAuthEc, req);
+    const ec = await this._getAuthenticatedExecutionContext(caller.userId);
+    const body = CreateOneOffTokenRequestSchema.parse(req.body || {});
+
+    const callerUser = await this.userLookup.findUserById(ec, caller.userId);
+    const callerRoles = callerUser?.appRoles || [];
+    const isAdmin = callerRoles.includes(CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN);
+    if (!isAdmin) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+        context: { message: 'Only super-admin users can create one-off session tokens.' },
+      });
+    }
+
+    if (caller.userId === body.userId) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+        context: { message: 'Cannot create one-off token targeting self.' },
+      });
+    }
+
+    const targetUser = await this.userLookup.findUserById(ec, body.userId);
+    if (!targetUser) {
+      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_NOT_FOUND,
+        context: { userId: body.userId },
+      });
+    }
+    if (targetUser.status !== UserStatus.ACTIVE) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_NOT_ACTIVE,
+        context: { userId: body.userId },
+      });
+    }
+
+    const userType = targetUser.userTypes?.[0];
+    if (!userType) {
+      throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_TYPE_MISMATCH,
+        context: { userId: body.userId, message: 'Target user has no assigned user type.' },
+      });
+    }
+
+    const appConfig = this.appConfigService.config;
+    const userTypeConfig = appConfig?.userTypes?.[userType];
+    if (!userTypeConfig?.auth?.oneOffSessionAllowed) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.FEATURE_NOT_AVAILABLE,
+        context: { message: `One-off sessions not allowed for user type "${userType}".` },
+      });
+    }
+
+    const expiresIn = body.expiresIn;
+    const durationMs =
+      expiresIn.unit === 'minutes' ? expiresIn.value * 60 * 1000
+      : expiresIn.unit === 'hours' ? expiresIn.value * 3600 * 1000
+      : expiresIn.value * 86400 * 1000;
+
+    const organizationId = req.params.organizationId as string | undefined;
+    const applicationId = req.params.applicationId as string | undefined;
+
+    const tokenResult = await this.consumableTokenService.createToken({
+      tokenType: body.tokenType as string,
+      consumptionMode: body.consumptionMode,
+      expiresIn: { value: durationMs, unit: DurationUnit.MILLISECONDS },
+      organizationId,
+      userId: body.userId,
+      resourceIdentifier: body.resourceIdentifier,
+      relatedId: body.relatedId,
+      metadata: { ...body.metadata, ...(applicationId ? { applicationId } : {}) },
+      roles: (targetUser.appRoles || []).map(role => ({
+        roles: [role],
+        relatedPrimaryScope: ResourcePrimaryScope.APPLICATION,
+      })),
+      maxUses: body.maxUses,
+      createsOneOffSession: true,
+      consumeAt: body.consumeAt,
+      targeting: body.targeting,
+    });
+
+    try {
+      await this.auditLogsService.logGenericEvent({
+        userId: caller.userId,
+        organizationId,
+        riskLevel: ResourceOperationRiskLevel.MEDIUM,
+        eventType: CoreAuditableEventType.ONE_OFF_TOKEN_CREATED,
+        eventData: {
+          tokenId: tokenResult._id,
+          tokenType: body.tokenType,
+          targetUserId: body.userId,
+          consumeAt: body.consumeAt,
+          callerUserId: caller.userId,
+          ipAddress,
+          userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+        },
+      });
+    } catch (error) {
+      this.logger.warn('Audit log failed for one-off token creation', { error, tokenId: tokenResult._id });
+    }
+
+    this.jsonSuccess(res, {
+      tokenValue: tokenResult.token,
+      tokenId: tokenResult._id,
+      expiresAt: tokenResult.expiresAt,
+    });
+  }
+
+  private async exchangeOneOffToken(req: Request, res: Response): Promise<void> {
+    const ipAddress = AuthControllerUtils.getClientIpFromRequest(req);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.ONE_OFF_EXCHANGE_IP}${ipAddress}`, 10, 60);
+    await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.ONE_OFF_EXCHANGE_HOUR_IP}${ipAddress}`, 100, 3600);
+
+    const body = OneOffSessionExchangeBodySchema.parse(req.body || {});
+
+    const consumableToken = await this.consumableTokenService.validateToken(body.token);
+
+    if (!consumableToken.createsOneOffSession) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_TYPE_MISMATCH,
+        context: { message: 'Token is not a one-off session token.' },
+      });
+    }
+
+    if (!consumableToken.userId) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_CONTEXT_MISMATCH,
+        context: { message: 'Token has no target user.' },
+      });
+    }
+
+    const ec = await this._getPreAuthExecutionContext();
+
+    const targetUser = await this.userLookup.findUserById(ec, consumableToken.userId);
+    if (!targetUser || targetUser.status !== UserStatus.ACTIVE) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_NOT_ACTIVE,
+        context: { userId: consumableToken.userId },
+      });
+    }
+
+    const userType = targetUser.userTypes?.[0];
+    if (!userType) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_TYPE_MISMATCH,
+        context: { userId: consumableToken.userId },
+      });
+    }
+
+    const appConfig = this.appConfigService.config;
+    const userTypeConfig = appConfig?.userTypes?.[userType];
+    if (!userTypeConfig?.auth?.oneOffSessionAllowed) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.FEATURE_NOT_AVAILABLE,
+        context: { message: `One-off sessions no longer allowed for user type "${userType}".` },
+      });
+    }
+
+    let consumableTokenValue: string | undefined;
+    if (consumableToken.consumeAt === 'EXCHANGE') {
+      await this.consumableTokenService.consumeToken(body.token);
+    } else {
+      consumableTokenValue = body.token;
+    }
+
+    const tokens = await this.tokenIssuer.issueTokensForUser(
+      consumableToken.userId,
+      undefined,
+      { sessionType: SessionType.ONE_OFF, activeUserType: userType },
+      {
+        skipSessionTracking: true,
+        refreshTokenExpiresAt: consumableToken.expiresAt,
+      },
+    );
+
+    try {
+      await this.auditLogsService.logGenericEvent({
+        userId: consumableToken.userId,
+        organizationId: consumableToken.organizationId,
+        riskLevel: ResourceOperationRiskLevel.MEDIUM,
+        eventType: CoreAuditableEventType.ONE_OFF_TOKEN_EXCHANGED,
+        eventData: {
+          tokenId: consumableToken._id,
+          tokenType: consumableToken.tokenType,
+          consumeAt: consumableToken.consumeAt,
+          consumed: consumableToken.consumeAt === 'EXCHANGE',
+          ipAddress,
+          userAgent: req.headers[WildoHeaderKeys.USER_AGENT] || 'unknown',
+        },
+      });
+    } catch (error) {
+      this.logger.warn('Audit log failed for one-off token exchange', { error, tokenId: consumableToken._id });
+    }
+
+    this.jsonSuccess(res, {
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken,
+      sessionType: SessionType.ONE_OFF,
+      ...(consumableTokenValue ? {
+        consumableTokenValue,
+        tokenExpiresAt: consumableToken.expiresAt.toISOString(),
+      } : {}),
+      context: {
+        tokenId: consumableToken._id,
+        tokenType: consumableToken.tokenType,
+        targeting: consumableToken.targeting,
+        organizationId: consumableToken.organizationId,
+        applicationId: (consumableToken.metadata as Record<string, unknown> | undefined)?.applicationId as string | undefined,
+        userId: consumableToken.userId,
+      },
+    });
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // W7.3a: Anonymous Session Transposition on Login/Register
+  // ═══════════════════════════════════════════════════════════════
+
+  /**
+   * Called after a successful authentication. If the request carries an
+   * anonymous session token, verifies it and transposes ownership of
+   * anonymous resources to the newly authenticated user.
+   *
+   * Errors are swallowed to avoid blocking the auth response.
+   */
+  private async handleAnonymousTransposition(req: Request, authResult: AuthenticationResponse): Promise<void> {
+    if (!authResult.success || !authResult.user?._id) return;
+
+    const anonymousToken = req.headers[WildoHeaderKeys.ANONYMOUS_SESSION] as string | undefined;
+    if (!anonymousToken) return;
+
+    try {
+      const { anonymousUserId } = this.anonymousSessionService.verifySessionToken(anonymousToken);
+      const userType = this.resolveUserTypeFromRequest(req)
+        ?? authResult.user.userTypes?.[0]
+        ?? 'default';
+
+      const result = await this.anonymousSessionService.transposeOwnership(
+        anonymousUserId,
+        authResult.user._id,
+        userType,
+      );
+
+      this.logDebug('Anonymous session transposition completed', {
+        anonymousUserId,
+        userId: authResult.user._id,
+        userType,
+        status: result.status,
+        transposedTypes: result.transposedTypes,
+        failedCount: result.failedTypes.length,
+      });
+    } catch (error) {
+      this.logger.warn('Anonymous session transposition failed (non-blocking)', {
+        userId: authResult.user._id,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Simplified transposition for OAuth2 token exchange, where we have a userId
+   * but no AuthenticationResponse. Uses header-resolved userType.
+   */
+  private async handleAnonymousTranspositionForTokenExchange(req: Request, userId: string): Promise<void> {
+    const anonymousToken = req.headers[WildoHeaderKeys.ANONYMOUS_SESSION] as string | undefined;
+    if (!anonymousToken) return;
+
+    try {
+      const { anonymousUserId } = this.anonymousSessionService.verifySessionToken(anonymousToken);
+      const userType = this.resolveUserTypeFromRequest(req) ?? 'default';
+
+      const result = await this.anonymousSessionService.transposeOwnership(anonymousUserId, userId, userType);
+
+      this.logDebug('Anonymous session transposition completed (token exchange)', {
+        anonymousUserId, userId, userType, status: result.status,
+        transposedTypes: result.transposedTypes, failedCount: result.failedTypes.length,
+      });
+    } catch (error) {
+      this.logger.warn('Anonymous session transposition failed in token exchange (non-blocking)', {
+        userId, error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  private resolveUserTypeFromRequest(req: Request): string | undefined {
+    const frontendServiceName = req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] as string | undefined;
+    if (!frontendServiceName) return undefined;
+    return this.appConfigService.resolveUserTypeFromFrontendServiceName(frontendServiceName) ?? undefined;
+  }
+}