@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/security/authentications/controllers/authentication-controller.backend.service.js

@@ -0,0 +1,2371 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import 'reflect-metadata';
+import { injectable, inject } from 'inversify';
+import express from 'express';
+import { AbstractControllerBackendService } from '../../../base-classes/services/controllers/abstract-controller.backend.service.js';
+import { LoggerService } from '../../../monitoring/logger/services/logger.service.js';
+import { ErrorBuilderBackendService } from '../../../errors/services/error-builder.backend.service.js';
+import { ErrorHandlerService } from '../../../errors/services/error-handler.backend.service.js';
+import { AppConfigurationService } from '../../../config/services/app-configuration.backend.service.js';
+import { AuditLogsBackendService } from '../../../compliance/audit-trails/services/audit-logs.backend.service.js';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+import { AuthenticationOrchestratorBackendService } from '../../../security/authentications/services/authentication-orchestrator.backend.service.js';
+import { AuthTokenIssuerBackendService } from '../../../security/authentications/services/auth-token-issuer.backend.service.js';
+import { OAuth2AuthenticationBackendService } from '../../../security/authentications/services/auth-methods/oauth2-authentication.backend.service.js';
+import { OAuth2ConnectionResolverBackendService } from '../../../security/authentications/services/auth-methods/oauth2-connection-resolver.backend.service.js';
+import { ConsumableTokenBackendService } from '../../../security/consumable-tokens/services/consumable-token.backend.service.js';
+import { JwtBackendService } from '../../../security/jwt/services/jwt.backend.service.js';
+import { WebAuthnBackendService } from '../../../security/authentications/services/auth-methods/webauthn.backend.service.js';
+import { DomainToOrgLookupBackendService } from '../../../security/authentications/services/admin-config/domain-to-org-lookup.backend.service.js';
+import { SAMLAuthenticationBackendService } from '../../../security/authentications/services/auth-methods/saml-authentication.backend.service.js';
+import { SAMLMetadataBackendService } from '../../../security/authentications/services/auth-methods/saml-metadata.backend.service.js';
+import { EmailBackendService } from '../../../notifications/email/services/email.backend.service.js';
+import { SMSBackendService } from '../../../notifications/sms/services/sms.backend.service.js';
+import { AuthExecutionContextFactoryBackendService } from '../../../security/authentications/services/auth-execution-context-factory.backend.service.js';
+import { AUTH_REDIS_KEYS, AUTH_OPERATION, AuthSource } from '../../../security/authentications/models/auth-constants.backend.js';
+import { AuthControllerUtils } from '../../../security/authentications/services/utils/auth-controller.utils.js';
+import { AuthResponseHelperBackendService } from '../../../security/authentications/services/utils/auth-response-helper.backend.service.js';
+import { AuthJwtGuardBackendService } from '../../../security/jwt/services/auth-jwt-guard.backend.service.js';
+import { AuthPasswordResetBackendService } from '../../../security/authentications/services/auth-methods/auth-password-reset.backend.service.js';
+import { AuthRegistrationBackendService } from '../../../security/authentications/services/auth-methods/auth-registration.backend.service.js';
+import { AuthMfaBackendService } from '../../../security/authentications/services/auth-methods/auth-mfa.backend.service.js';
+import { AuthPhoneVerificationBackendService } from '../../../security/authentications/services/auth-methods/auth-phone-verification.backend.service.js';
+import { AuthMethodManagementBackendService } from '../../../security/authentications/services/auth-methods/auth-method-management.backend.service.js';
+import { AnonymousSessionBackendService } from '../../../security/authentications/services/anonymous-session.backend.service.js';
+import { AuthUserLookupBackendService } from '../../../security/authentications/services/utils/auth-user-lookup.backend.service.js';
+import { RateLimitBackendService } from '../../../errors/services/rate-limit.backend.service.js';
+import { z } from 'zod';
+import { AuthIdentificationRequestSchema, AuthenticationRequestSchema, AuthLoginFormDtoSchema, PasswordResetRequestDtoSchema, PasswordResetCompleteDtoSchema, UserRegisterApiDtoSchema, UserInvitationApiDtoSchema, UserInvitationRejectApiDtoSchema, EmailVerifyDtoSchema, NativeTokenExchangeRequestSchema, AuthMethod, AuthFactorLevel, AuthenticationSessionState, CoreConsumableTokenTypes, ConsumableToken_ConsumptionMode, ConsumableTokenTypesSchema, CoreResourceType, CoreAuditableEventType, 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 { 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),
+});
+let AuthenticationControllerBackendService = class AuthenticationControllerBackendService extends AbstractControllerBackendService {
+    authEcFactory;
+    authService;
+    tokenIssuer;
+    oauth2Service;
+    oauth2Resolver;
+    consumableTokenService;
+    jwtService;
+    emailService;
+    appConfigService;
+    auditLogsService;
+    rateLimitService;
+    webAuthnService;
+    smsService;
+    domainToOrgLookup;
+    samlAuthService;
+    samlMetadataService;
+    authResponseHelper;
+    authJwtGuard;
+    passwordResetService;
+    registrationService;
+    mfaService;
+    phoneVerificationService;
+    methodManagementService;
+    anonymousSessionService;
+    userLookup;
+    constructor(logger, errorBuilder, errorHandler, authService, tokenIssuer, oauth2Service, oauth2Resolver, consumableTokenService, jwtService, emailService, authEcFactory, appConfigService, auditLogsService, rateLimitService, webAuthnService, smsService, domainToOrgLookup, samlAuthService, samlMetadataService, authResponseHelper, authJwtGuard, passwordResetService, registrationService, mfaService, phoneVerificationService, methodManagementService, anonymousSessionService, userLookup) {
+        super(logger, errorBuilder, errorHandler, 'AuthenticationController');
+        this.authEcFactory = authEcFactory;
+        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;
+    }
+    setupRoutes() {
+        // ─── 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
+    // ═══════════════════════════════════════════════════════════════
+    async identify(req, res) {
+        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];
+        this._validateFrontendAppOrigin(req, frontendServiceName);
+        const activeUserType = frontendServiceName
+            ? this.appConfigService.resolveUserTypeFromFrontendServiceName(frontendServiceName) ?? undefined
+            : undefined;
+        const result = await this.authService.identify(ec, identificationRequest, activeUserType, frontendServiceName);
+        this.jsonSuccess(res, result);
+    }
+    async authenticatePassword(req, res) {
+        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 = await this.authService.authenticatePassword(ec, passwordRequest);
+        await this.handleAnonymousTransposition(req, result);
+        this.jsonSuccess(res, result);
+    }
+    // Generic authenticate endpoint for future extensibility (SSO/MFA/etc.)
+    async authenticate(req, res) {
+        const ec = await this._getPreAuthExecutionContext();
+        const request = AuthenticationRequestSchema.parse(req.body || {});
+        const result = 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.
+     */
+    async refreshToken(req, res) {
+        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;
+                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
+    async getSessionState(req, res) {
+        const ec = await this._getPreAuthExecutionContext();
+        const sessionId = req.params.sessionId;
+        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.
+     */
+    async oauth2Authorize(req, res) {
+        const ec = await this._getPreAuthExecutionContext();
+        const providerRef = req.params.providerRef;
+        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;
+        let scopeContext;
+        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];
+        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.
+     */
+    async enterpriseSSOAuthorize(req, res) {
+        const ec = await this._getPreAuthExecutionContext();
+        const orgId = req.params.orgId;
+        const connectionId = req.params.connectionId;
+        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];
+        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.
+     */
+    async appEnterpriseSSOAuthorize(req, res) {
+        const ec = await this._getPreAuthExecutionContext();
+        const connectionId = req.params.connectionId;
+        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];
+        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];
+        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.
+     */
+    async handleSAMLLogin(req, res) {
+        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;
+        const returnUrl = req.query.returnUrl || '/';
+        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.
+     */
+    async handleSAMLACS(req, res) {
+        const clientIp = AuthControllerUtils.getClientIpFromRequest(req);
+        await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.SAML_ACS_IP}${clientIp}`, 20, 60);
+        const samlResponse = req.body?.SAMLResponse;
+        const relayState = 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] || '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.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
+     */
+    async handleSAMLMetadata(req, res) {
+        const scopeType = req.params.scopeType;
+        const scopeId = req.params.scopeId;
+        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.
+     */
+    async handleSAMLSLO_GET(req, res) {
+        const clientIp = AuthControllerUtils.getClientIpFromRequest(req);
+        await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.SAML_SLO_IP}${clientIp}`, 10, 60);
+        const samlRequest = req.query.SAMLRequest;
+        const samlResponse = req.query.SAMLResponse;
+        const relayState = req.query.RelayState;
+        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.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.
+     */
+    async handleSAMLSLO_POST(req, res) {
+        const clientIp = AuthControllerUtils.getClientIpFromRequest(req);
+        await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.SAML_SLO_IP}${clientIp}`, 10, 60);
+        const samlRequest = req.body?.SAMLRequest;
+        const samlResponse = req.body?.SAMLResponse;
+        const relayState = 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.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).
+     */
+    _resolveSAMLRedirectUrl(userType) {
+        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).
+     */
+    async oauth2Callback(req, res) {
+        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 || req.body?.error;
+        if (idpError) {
+            const errorDescription = req.query.error_description || 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;
+            let errorReturnUrl;
+            const stateValue = req.query.state || req.body?.state;
+            if (stateValue) {
+                try {
+                    const stateToken = await this.consumableTokenService.validateToken(stateValue);
+                    const stateMetadata = stateToken.metadata;
+                    const frontendServiceName = stateMetadata?.frontendServiceName;
+                    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 || req.body?.code;
+        const state = req.query.state || 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;
+        let callbackReturnUrl;
+        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,
+                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.
+     */
+    async tokenExchange(req, res) {
+        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;
+        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).
+     */
+    async logout(req, res) {
+        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;
+        try {
+            const decoded = await this.jwtService.verifyRefreshToken(refreshToken);
+            if (typeof decoded === 'object' && decoded !== null) {
+                const payload = decoded;
+                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
+     */
+    async passwordResetRequest(req, res) {
+        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
+     */
+    async passwordResetComplete(req, res) {
+        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
+     */
+    async register(req, res) {
+        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];
+        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
+     */
+    async acceptInvitation(req, res) {
+        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
+     */
+    async rejectInvitation(req, res) {
+        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
+     */
+    async verifyEmail(req, res) {
+        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
+     */
+    async resendVerificationEmail(req, res) {
+        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
+     */
+    async completeOrgOnboarding(req, res) {
+        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).
+     */
+    async mfaEmailOTPSend(req, res) {
+        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).
+     */
+    async mfaEmailOTPVerify(req, res) {
+        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,
+            factorLevel: AuthFactorLevel.SECOND,
+            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.
+     */
+    async mfaTOTPSetup(req, res) {
+        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.
+     */
+    async mfaTOTPVerifySetup(req, res) {
+        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.
+     */
+    async mfaTOTPVerify(req, res) {
+        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,
+            factorLevel: AuthFactorLevel.SECOND,
+            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.
+     */
+    async handlePasskeyRegisterOptions(req, res) {
+        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.
+     */
+    async handlePasskeyRegisterVerify(req, res) {
+        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']).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.
+     */
+    async handlePasskeyAuthOptions(req, res) {
+        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)) {
+                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.
+     */
+    async handlePasskeyAuthVerify(req, res) {
+        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']).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 || 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.
+     */
+    async handlePasskeyList(req, res) {
+        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.
+     */
+    async handlePasskeyRemove(req, res) {
+        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.
+     */
+    async handlePasskeyRename(req, res) {
+        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.
+     */
+    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.
+     */
+    async _getAuthenticatedExecutionContext(userId) {
+        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.
+     */
+    redirectToFrontendWithCode(res, exchangeCode, frontendUrl, returnUrl) {
+        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.
+     */
+    redirectToFrontendWithError(res, error, description, frontendUrl, returnUrl) {
+        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);
+    }
+    validateFrontendReturnUrl(returnUrl, frontendUrl) {
+        if (returnUrl.startsWith('/') && !returnUrl.startsWith('//')) {
+            return;
+        }
+        const allowedOrigins = new Set();
+        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.
+     */
+    resolveFrontendAppPublicUrl(req) {
+        const frontendServiceName = req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME];
+        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.
+     */
+    resolveFrontendAppPublicUrlFromFrontendServiceName(frontendServiceName) {
+        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.
+     */
+    _lookupFrontendPublicUrl(frontendServiceName) {
+        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.
+     */
+    _validateFrontendAppOrigin(req, claimedFrontendServiceName) {
+        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];
+        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.
+     */
+    async magicLinkSend(req, res) {
+        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()).
+     */
+    async magicLinkVerify(req, res) {
+        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.
+     */
+    async smsOTPSend(req, res) {
+        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.
+     */
+    async phoneVerifySend(req, res) {
+        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.
+     */
+    async phoneVerifyConfirm(req, res) {
+        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.
+     */
+    async nativeTokenExchange(req, res) {
+        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;
+        const nativeClientIds = providerConfig?.nativeClientIds || [];
+        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];
+            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
+    // ═══════════════════════════════════════════════════════════════
+    async createOneOffToken(req, res) {
+        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;
+        const applicationId = req.params.applicationId;
+        const tokenResult = await this.consumableTokenService.createToken({
+            tokenType: body.tokenType,
+            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,
+        });
+    }
+    async exchangeOneOffToken(req, res) {
+        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;
+        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?.applicationId,
+                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.
+     */
+    async handleAnonymousTransposition(req, authResult) {
+        if (!authResult.success || !authResult.user?._id)
+            return;
+        const anonymousToken = req.headers[WildoHeaderKeys.ANONYMOUS_SESSION];
+        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.
+     */
+    async handleAnonymousTranspositionForTokenExchange(req, userId) {
+        const anonymousToken = req.headers[WildoHeaderKeys.ANONYMOUS_SESSION];
+        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),
+            });
+        }
+    }
+    resolveUserTypeFromRequest(req) {
+        const frontendServiceName = req.headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME];
+        if (!frontendServiceName)
+            return undefined;
+        return this.appConfigService.resolveUserTypeFromFrontendServiceName(frontendServiceName) ?? undefined;
+    }
+};
+AuthenticationControllerBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ErrorHandlerService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.AuthenticationOrchestratorService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.AuthTokenIssuer)),
+    __param(5, inject(SAAS_SERVICE_TYPES.OAuth2AuthenticationService)),
+    __param(6, inject(SAAS_SERVICE_TYPES.OAuth2ConnectionResolverService)),
+    __param(7, inject(SAAS_SERVICE_TYPES.ConsumableTokenService)),
+    __param(8, inject(SAAS_SERVICE_TYPES.JwtBackendService)),
+    __param(9, inject(SAAS_SERVICE_TYPES.EmailService)),
+    __param(10, inject(SAAS_SERVICE_TYPES.AuthExecutionContextFactory)),
+    __param(11, inject(SAAS_SERVICE_TYPES.AppConfigService)),
+    __param(12, inject(SAAS_SERVICE_TYPES.AuditLogsService)),
+    __param(13, inject(SAAS_SERVICE_TYPES.RateLimitBackendService)),
+    __param(14, inject(SAAS_SERVICE_TYPES.WebAuthnService)),
+    __param(15, inject(SAAS_SERVICE_TYPES.SMSService)),
+    __param(16, inject(SAAS_SERVICE_TYPES.DomainToOrgLookupService)),
+    __param(17, inject(SAAS_SERVICE_TYPES.SAMLAuthenticationService)),
+    __param(18, inject(SAAS_SERVICE_TYPES.SAMLMetadataService)),
+    __param(19, inject(SAAS_SERVICE_TYPES.AuthResponseHelperService)),
+    __param(20, inject(SAAS_SERVICE_TYPES.AuthJwtGuardService)),
+    __param(21, inject(SAAS_SERVICE_TYPES.AuthPasswordResetService)),
+    __param(22, inject(SAAS_SERVICE_TYPES.AuthRegistrationService)),
+    __param(23, inject(SAAS_SERVICE_TYPES.AuthMfaService)),
+    __param(24, inject(SAAS_SERVICE_TYPES.AuthPhoneVerificationService)),
+    __param(25, inject(SAAS_SERVICE_TYPES.AuthMethodManagementService)),
+    __param(26, inject(SAAS_SERVICE_TYPES.AnonymousSessionService)),
+    __param(27, inject(SAAS_SERVICE_TYPES.AuthUserLookupService)),
+    __metadata("design:paramtypes", [LoggerService,
+        ErrorBuilderBackendService,
+        ErrorHandlerService,
+        AuthenticationOrchestratorBackendService,
+        AuthTokenIssuerBackendService,
+        OAuth2AuthenticationBackendService,
+        OAuth2ConnectionResolverBackendService,
+        ConsumableTokenBackendService,
+        JwtBackendService,
+        EmailBackendService,
+        AuthExecutionContextFactoryBackendService,
+        AppConfigurationService,
+        AuditLogsBackendService,
+        RateLimitBackendService,
+        WebAuthnBackendService,
+        SMSBackendService,
+        DomainToOrgLookupBackendService,
+        SAMLAuthenticationBackendService,
+        SAMLMetadataBackendService,
+        AuthResponseHelperBackendService,
+        AuthJwtGuardBackendService,
+        AuthPasswordResetBackendService,
+        AuthRegistrationBackendService,
+        AuthMfaBackendService,
+        AuthPhoneVerificationBackendService,
+        AuthMethodManagementBackendService,
+        AnonymousSessionBackendService,
+        AuthUserLookupBackendService])
+], AuthenticationControllerBackendService);
+export { AuthenticationControllerBackendService };
+//# sourceMappingURL=authentication-controller.backend.service.js.map