@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/security/authentications/services/authentication-orchestrator.backend.service.js

@@ -19,8 +19,9 @@ import { LoggerService } from '../../../monitoring/logger/services/logger.servic
 import { ErrorBuilderBackendService } from '../../../errors/services/error-builder.backend.service.js';
 import { resolveActiveMemberOrgIds } from '../../../security/authentications/services/resolve-active-member-orgs.backend.utils.js';
 import { CoreConsumableTokenTypes, ConsumableToken_ConsumptionMode, ErrorCustomMessageReference, ErrorType, isWildoBackendError, UserStatus, } from '@wildo-ai/saas-models';
-import { CoreResourceType, getEnabledMethods } from '@wildo-ai/saas-models';
-import { AuthUtils, AuthIdentificationResponseSchema, AuthMethod, AuthFactorLevel, BrandAssetComposition, BrandAssetTheme, AuthenticationResponseSchema, AuthenticationSessionSchema, AuthenticationSessionState, AuthNextStep, OrganizationNameSource, SsoProtocol, } from '@wildo-ai/saas-models';
+import { CoreResourceType, getEnabledMethods, resolveTenantBrandPresentation } from '@wildo-ai/saas-models';
+import { RepositoriesRegistryHandlerBackendService } from '../../../base-classes/services/repositories/repositories-registry-handler.backend.service.js';
+import { AuthUtils, AuthIdentificationResponseSchema, AuthMethod, AuthFactorLevel, BrandAssetComposition, BrandAssetTheme, AuthenticationResponseSchema, AuthenticationSessionSchema, AuthenticationSessionState, AuthNextStep, AuthScopeType, OrganizationNameSource, SsoProtocol, } from '@wildo-ai/saas-models';
 import { AuthSessionPurpose, MfaEnrollmentState, AccountLockoutReason } from '@wildo-ai/saas-models';
 import { RegistrationAcquisitionChannel, RegistrationMode, EmailVerificationMode, evaluateUserTypeAcquisition, } from '@wildo-ai/saas-models';
 import { DurationUnit } from '@wildo-ai/zod-decorators';
@@ -47,7 +48,7 @@ import { OAuth2ConnectionResolverBackendService } from '../../../security/authen
 import { AuthUserLookupBackendService } from '../../../security/authentications/services/utils/auth-user-lookup.backend.service.js';
 import { AuthCredentialOpsBackendService } from '../../../security/authentications/services/utils/auth-credential-ops.backend.service.js';
 import { AuthControllerUtils } from '../../../security/authentications/services/utils/auth-controller.utils.js';
-import { requiresEnterpriseSsoOnly, restrictFirstFactorMethodsForEnterpriseSso, } from '../../../security/authentications/utils/enterprise-sso-enforcement.backend.utils.js';
+import { requiresEnterpriseSsoOnly, isBreakGlassAccount, restrictFirstFactorMethodsForEnterpriseSso, } from '../../../security/authentications/utils/enterprise-sso-enforcement.backend.utils.js';
 import { isEnabledSocialOAuth2LoginProvider } from '../../../security/authentications/utils/social-oauth2-purpose.backend.utils.js';
 /**
  * AuthenticationOrchestratorBackendService
@@ -74,6 +75,7 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
     appConfigService;
     errorBuilder;
     servicesRegistryHandler;
+    repositoriesRegistry;
     auditLogsService;
     sessionStore;
     credentialVerifier;
@@ -117,11 +119,12 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
      * the fleet (the always-on DB store still records every lock unconditionally).
      */
     _accountLockedAuditDedup = new Map();
-    constructor(logger, appConfigService, errorBuilder, servicesRegistryHandler, auditLogsService, sessionStore, credentialVerifier, tokenIssuer, consumableTokenService, redisService, rateLimitService, domainToOrgLookup, orgConfigService, webAuthnService, oauth2Resolver, userLookup, credentialOps, systemAccessService, mongoDBService, resourcePersistenceUnitOfWork, authMfaService) {
+    constructor(logger, appConfigService, errorBuilder, servicesRegistryHandler, repositoriesRegistry, auditLogsService, sessionStore, credentialVerifier, tokenIssuer, consumableTokenService, redisService, rateLimitService, domainToOrgLookup, orgConfigService, webAuthnService, oauth2Resolver, userLookup, credentialOps, systemAccessService, mongoDBService, resourcePersistenceUnitOfWork, authMfaService) {
         this.logger = logger;
         this.appConfigService = appConfigService;
         this.errorBuilder = errorBuilder;
         this.servicesRegistryHandler = servicesRegistryHandler;
+        this.repositoriesRegistry = repositoriesRegistry;
         this.auditLogsService = auditLogsService;
         this.sessionStore = sessionStore;
         this.credentialVerifier = credentialVerifier;
@@ -679,35 +682,26 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
             ? await this._resolveAuthPolicyWithOrgOverrides(ec, resolvedUserType, user._id)
             : this._resolveAuthPolicy(resolvedUserType);
         const firstFactorMethods = await this._getAvailableFirstFactorMethods(ec, domainOrgLookup, authPolicy);
-        // G1: Filter PASSKEY from firstFactorMethods if the user has no registered passkeys.
-        // Also enrich the PASSKEY method config with the registered passkey count for UI hints.
-        if (user) {
-            try {
-                const userId = user._id;
-                const cred = await this.credentialVerifier.resolveCredentials(ec, userId);
-                const passkeyCount = cred?.passkeyCredentials?.length ?? 0;
-                if (passkeyCount === 0) {
-                    // Remove PASSKEY from available first factor methods since user has none registered
-                    const passkeyIdx = firstFactorMethods.findIndex(m => m.method === AuthMethod.PASSKEY);
-                    if (passkeyIdx >= 0) {
-                        firstFactorMethods.splice(passkeyIdx, 1);
-                    }
-                }
-                else {
-                    // Enrich PASSKEY config with credential count for UI hinting
-                    const passkeyMethod = firstFactorMethods.find(m => m.method === AuthMethod.PASSKEY);
-                    if (passkeyMethod) {
-                        passkeyMethod.config = {
-                            ...passkeyMethod.config,
-                            registeredPasskeyCount: passkeyCount,
-                        };
-                    }
-                }
-            }
-            catch {
-                // If credential lookup fails, just leave PASSKEY as-is from app config
-            }
-        }
+        /*
+         * ─── The offered method set depends on POLICY ONLY ────────────────────────────────────────
+         *
+         * This is a PRE-AUTHENTICATION response to an email hint, and the whole point of the `userExists:
+         * true` fix below is that it must be identical whether or not the address names an account. Two
+         * per-account narrowings used to run here and defeated that, each in the same one-sided way:
+         *
+         *   - PASSKEY was removed when an EXISTING user had none registered — so an absent PASSKEY
+         *     proved the account exists, because the branch is skipped entirely for an unknown address;
+         *   - the surviving PASSKEY entry was enriched with `registeredPasskeyCount`, disclosing how
+         *     many authenticators a named person has before anyone proved they are that person.
+         *
+         * Neither had a single consumer anywhere in the repository — no frontend read the count, and no
+         * caller depended on the narrowing — so both were paying an enumeration oracle for nothing.
+         *
+         * PASSKEY is now offered whenever the policy enables it. A caller with no credential learns that
+         * from their own authenticator: `navigator.credentials.get()` reports no discoverable credential
+         * client-side, which is where that answer belongs. It is also what conditional UI (passkey
+         * autofill) already does — the browser knows, and the server does not have to say.
+         */
         // If org requires SSO and disallows password fallback, fail closed to
         // enterprise methods only. If none can be materialized, keep the list empty
         // instead of advertising social/password and failing after an IdP round-trip.
@@ -730,23 +724,46 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
             scopeId: domainOrgLookup?.scopeId,
             scopeType: domainOrgLookup?.scopeType,
         });
-        // Build organization branding if domain matched an org. The org has no
-        // per-org logo at identification time (we've only matched a domain, not
-        // loaded an org profile), so the app-level brand is the default: resolve
-        // the header lockup (falling back to the symbol) from config brandAssets.
-        // `resolveBrandLogoUrl` returns undefined when no brand asset was
-        // generated yet.
+        /*
+         * Build organization branding if the domain matched an org — the TENANT's own branding first,
+         * the application's brand assets second (#410).
+         *
+         * The comment here used to say the org "has no per-org logo at identification time (we've only
+         * matched a domain, not loaded an org profile)". That was true of what the code did and false
+         * as a constraint: the domain lookup resolves `scopeId`, which IS the organization id, so the
+         * profile was always one read away. A tenant could upload a logo, see it on its settings screen,
+         * and never see it on its own sign-in page.
+         *
+         * Discloses nothing new. `organizationName` — the tenant's display name — is already returned at
+         * this step, to anyone, keyed only on the domain and never on whether the user exists (the H2
+         * anti-enumeration invariant below). A login screen's branding is meant to be seen by the person
+         * about to sign in; that is what it is for.
+         *
+         * Best-effort by construction: this is a PRE-AUTHENTICATION path, so a profile read that fails
+         * must degrade to the application brand rather than refuse an identification.
+         */
+        const organizationBrandingRecord = domainOrgLookup?.scopeId
+            ? await this.readOrganizationBrandingForIdentification(ec, domainOrgLookup.scopeId)
+            : undefined;
         const organizationBranding = domainOrgLookup
             ? {
                 organizationName: domainOrgLookup.matchedProvider?.displayName,
-                logoUrl: this.appConfigService.resolveBrandLogoUrl({
-                    composition: BrandAssetComposition.LOCKUP,
-                    theme: BrandAssetTheme.DEFAULT,
-                })
-                    ?? this.appConfigService.resolveBrandLogoUrl({
-                        composition: BrandAssetComposition.SYMBOL,
+                ...resolveTenantBrandPresentation(organizationBrandingRecord, {
+                    // `resolveBrandLogoUrl` returns undefined when no brand asset was generated yet.
+                    logoUrl: this.appConfigService.resolveBrandLogoUrl({
+                        composition: BrandAssetComposition.LOCKUP,
                         theme: BrandAssetTheme.DEFAULT,
-                    }),
+                    })
+                        ?? this.appConfigService.resolveBrandLogoUrl({
+                            composition: BrandAssetComposition.SYMBOL,
+                            theme: BrandAssetTheme.DEFAULT,
+                        }),
+                    // No application-level primary colour exists to fall back to: the only configured
+                    // `primaryColor` in the engine is an EMAIL brand token, which is a different palette for
+                    // a different medium. So this DTO field is populated from the tenant or not at all —
+                    // honestly absent rather than filled with a value from somewhere it does not belong.
+                    primaryColor: undefined,
+                }),
             }
             : undefined;
         // H2 fix: Always return userExists: true to prevent email enumeration.
@@ -758,26 +775,21 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
                 firstFactorMethods.push(passwordMethod);
             }
         }
-        // #13g Step 3: Flag ssoMigrationRequired when user's domain matches enforced SSO
-        // but they haven't linked yet — signals the frontend to show migration messaging.
-        let ssoMigrationRequired = false;
-        if (user && domainOrgLookup?.enforcement?.requireSSO && domainOrgLookup.matchedProvider) {
-            try {
-                const matchedConnectionId = domainOrgLookup.matchedProvider._id;
-                if (matchedConnectionId) {
-                    const existingLink = await this.servicesRegistryHandler.read(CoreResourceType.USER_IDENTITY_LINKS, ec, {
-                        userId: user._id,
-                        connectionId: matchedConnectionId,
-                    });
-                    if (!existingLink) {
-                        ssoMigrationRequired = true;
-                    }
-                }
-            }
-            catch {
-                this.logger.warn('SSO migration check failed (non-fatal)', { email });
-            }
-        }
+        /*
+         * ─── `ssoMigrationRequired` is GONE, and its removal is the same fix as the block above ───────
+         *
+         * It was computed here as "this user's domain enforces SSO and they have not linked an identity
+         * yet", which required BOTH an existing user and an identity-link read. `true` therefore proved
+         * the address names an account — the third one-sided existence oracle in this response, sitting
+         * two statements above the `userExists: true` line that exists to prevent exactly that.
+         *
+         * It could have been made enumeration-safe by deriving it from the DOMAIN alone, and that was
+         * rejected: domain-derived, the flag is true for people who HAVE linked, so its name would
+         * become a lie and the messaging a future reader wires from it would fire on the wrong half of
+         * the tenant. The honest answer is that it has no consumer — no frontend, no test, nothing in
+         * either dogfood application read it — so there is nothing to preserve. A flag that only a
+         * post-authentication surface can answer honestly belongs on a post-authentication surface.
+         */
         const payload = {
             sessionId,
             email: email.toLowerCase(),
@@ -789,7 +801,6 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
             mfaMethodsRequired: AuthenticationOrchestratorBackendService_1.DEFAULT_MFA_METHODS_REQUIRED,
             organizationBranding,
             availableIntegrations: [],
-            ssoMigrationRequired,
         };
         return AuthIdentificationResponseSchema.parse(payload);
     }
@@ -989,10 +1000,23 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
         if (ipAddress) {
             await this.rateLimitService.checkRateLimit(`${AUTH_REDIS_KEYS.PASSWORD_IP}${ipAddress}`, 10, 60);
         }
-        // M14 fix: If user's scope requires SSO, check grace login allowance before proceeding.
-        if (session.scopeType && session.scopeId) {
-            await this._checkSSOGraceLoginAllowed(ec, session.scopeType, session.scopeId, session.userId || '');
-        }
+        /*
+         * ─── The SSO enforcement gate MOVED, and it moved for two reasons ────────────────────────────
+         *
+         * It used to run HERE, before the user was resolved and before the password was verified, and
+         * it answers with a distinguishable `AUTHENTICATION_SSO_REQUIRED` that reaches the client
+         * verbatim. So any per-account decision it took — and break-glass (#423) is one — was
+         * observable to a caller who had proved nothing. It now runs after verification, immediately
+         * beside `_incrementSSOGraceLogin`, which is the counter it gates.
+         *
+         * The second reason is the one that would matter even without break-glass: a caller who typed
+         * the wrong password at an SSO-enforced tenant used to be told the tenant enforces SSO, before
+         * anything about them was established. Now a wrong password fails as a wrong password.
+         *
+         * What this costs: an exhausted-grace account burns one password verification before being
+         * refused. That is one bcrypt comparison against a caller who supplied a credential, on a path
+         * already rate-limited per email and per IP two statements above.
+         */
         // Resolve user
         const user = await this._resolveUserForAuthentication(ec, session, email, sessionId);
         const userId = user._id;
@@ -1157,8 +1181,16 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
         this.logDebug('Password authentication successful', { sessionId, userId });
         // C1 fix: Reset global lockout counter on successful authentication
         await this._resetGlobalAttempts(email);
-        // M14 fix: Increment SSO grace login counter after successful password auth.
+        /*
+         * SSO enforcement, evaluated on a caller who has now PROVED the credential — see the note at
+         * the top of this method for why it is here rather than in front of the verification.
+         *
+         * The check may refuse (the tenant requires SSO and this account is neither exempt nor within
+         * its grace allowance), so it runs BEFORE the increment: a refused sign-in must not consume a
+         * grace attempt it was never granted.
+         */
         if (session.scopeType && session.scopeId) {
+            await this._checkSSOGraceLoginAllowed(ec, session.scopeType, session.scopeId, userId, user.email, { sessionId, ipAddress: ipAddress ?? '', userAgent: session.deviceInfo?.userAgent ?? '' });
             await this._incrementSSOGraceLogin(ec, session.scopeType, session.scopeId, userId);
         }
         await this._updateSessionAfterSuccessfulAuth(ec, sessionId, userId, AuthMethod.PASSWORD);
@@ -2031,10 +2063,12 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
         // Delegate to WebAuthn service for cryptographic verification
         let verified = false;
         let credentialId = response.id;
+        let cloneSuspicion;
         try {
             const result = await this.webAuthnService.verifyAuthenticationResponse(ec, userId, response);
             verified = result.verified;
             credentialId = result.credentialId;
+            cloneSuspicion = result.cloneSuspicion;
         }
         catch (error) {
             this.logger.warn('WebAuthn verification threw an error', {
@@ -2050,11 +2084,35 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
             const deviceInfo = session.deviceInfo;
             await this.auditLogsService.logUserPasskeyAuthFailure({
                 email: session.email || 'unknown',
-                failureReason: 'WebAuthn verification failed',
+                // Named, not generic. Every refusal used to record the same string, so the one cause worth
+                // alerting on was byte-identical to a wrong credential or an expired challenge.
+                failureReason: cloneSuspicion ? 'passkey_signature_counter_regression' : 'WebAuthn verification failed',
                 ipAddress: deviceInfo?.ipAddress || 'unknown',
                 userAgent: deviceInfo?.userAgent || 'unknown',
                 sessionId,
             });
+            /*
+             * A verified assertion whose counter did not advance gets its OWN CRITICAL row, in addition
+             * to the ordinary failure above — the failure event is what the lockout and rate-limit story
+             * reads and must keep its shape, while this one is what a SOC alerts on.
+             *
+             * Reachable only after signature verification (the service refuses to evaluate the counter
+             * before it), so this row cannot be forged by someone who merely knows a credential id.
+             */
+            if (cloneSuspicion) {
+                await this.auditLogsService.logUserPasskeyCloneSuspected({
+                    userId,
+                    credentialId: cloneSuspicion.credentialId,
+                    storedCounter: cloneSuspicion.storedCounter,
+                    receivedCounter: cloneSuspicion.receivedCounter,
+                    credentialDeviceType: cloneSuspicion.credentialDeviceType,
+                    credentialBackedUp: cloneSuspicion.credentialBackedUp,
+                    ...(cloneSuspicion.aaguid ? { aaguid: cloneSuspicion.aaguid } : {}),
+                    ceremony: cloneSuspicion.ceremony,
+                    ipAddress: deviceInfo?.ipAddress || 'unknown',
+                    userAgent: deviceInfo?.userAgent || 'unknown',
+                });
+            }
             return this.__buildAuthenticationErrorMethod(sessionId, factorLevel, {
                 authMethod: AuthMethod.PASSKEY,
                 retryAllowed: !locked,
@@ -2168,11 +2226,61 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
     // SSO GRACE LOGIN TRACKING (M14)
     // ===============================
     /** Redis key prefix for SSO grace login counters — scope-aware format: sso_grace_logins:{scopeType}:{scopeId}:{userId} */
+    /**
+     * Read the tenant's branding for the sign-in screen (#410).
+     *
+     * NEVER throws. This runs on the pre-authentication identification path, so every failure mode —
+     * no profile row, a profile with no branding block, a store that is momentarily unavailable —
+     * resolves to `undefined` and the caller falls back to the application's brand. Letting a
+     * cosmetic read refuse an identification would turn a missing logo into an outage.
+     *
+     * `ORGANIZATION_PROFILES` had no backend reader at all before this; the audit note on
+     * `OrganizationBrandingSchema` records why, and why that reasoning was wrong.
+     *
+     * **Reads the REPOSITORY, not the service, and that is the difference between working and inert.**
+     * `ORGANIZATION_PROFILES`'s default READ variant requires `ORG_MEMBER`, and an identification
+     * request carries no roles at all — it is what happens BEFORE anyone is authenticated. Going
+     * through `servicesRegistryHandler.read` would therefore be refused by the operation pipeline,
+     * the refusal would be swallowed by the catch below, and the tenant's logo would silently never
+     * appear while every test stayed green. This is a SYSTEM read on the system's own behalf, to
+     * decorate a login screen; the repository is where a system read belongs. Same shape as the
+     * notifications dispatcher reading a recipient's preferences.
+     */
+    async readOrganizationBrandingForIdentification(ec, organizationId) {
+        try {
+            const repository = this.repositoriesRegistry.getRepository(CoreResourceType.ORGANIZATION_PROFILES);
+            const profile = await repository?.read(ec, { organizationId });
+            return profile?.branding ?? undefined;
+        }
+        catch {
+            this.logger.warn('Organization branding lookup failed (non-fatal, falling back to application brand)', { organizationId });
+            return undefined;
+        }
+    }
     /**
      * M14: Check if password login is allowed under SSO grace policy.
      * If the scope requires SSO and grace logins are exhausted, throws AUTHENTICATION error.
+     *
+     * ## Runs AFTER the credential is verified
+     *
+     * See the note at the `authenticatePassword` call site. Two consequences for anyone editing this:
+     * `email` is the address of a user whose password has been checked — never a caller-supplied
+     * claim — and every refusal here is one a caller could only reach by knowing that password.
+     *
+     * ## The break-glass exemption (#423)
+     *
+     * A named account in `emergencyAccess.breakGlassAccounts` is exempt from this refusal, including
+     * grace exhaustion, and from nothing else: same password, same lockout counters, same rate limits.
+     * Every use emits `EMERGENCY_ACCESS_USED` at CRITICAL, which is the control that makes a standing
+     * bypass acceptable at all — Microsoft Entra's emergency-access guidance asks for an alert on
+     * every sign-in of such an account and a post-mortem after each one, and the alert is the half a
+     * framework can provide.
+     *
+     * The emit is best-effort and never blocks the sign-in. That is deliberate and it is the same
+     * trade every audit emission on this path makes: refusing a break-glass sign-in because the audit
+     * store is unavailable would take the door away during exactly the outage it exists for.
      */
-    async _checkSSOGraceLoginAllowed(ec, scopeType, scopeId, userId) {
+    async _checkSSOGraceLoginAllowed(ec, scopeType, scopeId, userId, email, provenance) {
         try {
             const ssoConfig = await this.orgConfigService.loadSSOConfig(ec, scopeType, scopeId);
             if (!ssoConfig) {
@@ -2183,6 +2291,41 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
             const { enforcement } = ssoConfig;
             if (!enforcement.requireSSO)
                 return;
+            /*
+             * Checked before every refusal below, and before the grace counter — a break-glass account is
+             * exempt from the whole policy, not merely from running out of attempts. Placed after the
+             * `requireSSO` early return so an ordinary tenant emits nothing.
+             */
+            if (isBreakGlassAccount(ssoConfig.emergencyAccess, email)) {
+                /*
+                 * Recorded under whichever scope the policy belongs to.
+                 *
+                 * `emergencyAccess` lives on the POLYMORPHIC SSO config, so an APPLICATION-scope policy
+                 * names break-glass accounts for the application itself. This branch REFUSED that case for
+                 * one release, because `EMERGENCY_ACCESS_USED` required an `organizationId` and admitting
+                 * an unrecordable bypass is the one outcome the mechanism exists to prevent. The event now
+                 * carries either scope and refuses anything but exactly one, so the refusal is gone and the
+                 * use is audited either way.
+                 */
+                void this.auditLogsService?.logEmergencyAccessUsed({
+                    userId,
+                    email: email,
+                    scopeType,
+                    ...(scopeType === AuthScopeType.ORGANIZATION
+                        ? { organizationId: scopeId }
+                        : { applicationId: scopeId }),
+                    ipAddress: provenance?.ipAddress ?? '',
+                    userAgent: provenance?.userAgent ?? '',
+                    sessionId: provenance?.sessionId ?? '',
+                })?.catch((error) => {
+                    this.logger.warn('Emergency-access audit emit failed (sign-in allowed)', {
+                        scopeType,
+                        scopeId,
+                        ...projectCaughtErrorLogFields(error),
+                    });
+                });
+                return;
+            }
             if (!enforcement.allowPasswordFallback) {
                 throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
                     customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_SSO_REQUIRED,
@@ -2528,15 +2671,50 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
         catch {
             // Suppress
         }
+        /*
+         * Both remaining failure arms answer with the SAME generic response every other arm of this
+         * method already uses, and the reason each one refused is recorded in the audit trail instead.
+         *
+         * ## Why this changed
+         *
+         * They used to be distinguishable — `USER_NOT_FOUND` with `userExists: false`, and
+         * `ACCOUNT_INACTIVE` with `userExists: true` — which told a caller holding a valid token whether
+         * the account exists and whether it is usable. That contradicted the two nearest surfaces in the
+         * same flow family, and the contradiction was the defect rather than the disclosure's size:
+         *
+         *  - the magic-link SEND leg refuses silently for a non-ACTIVE user, so no fresh link can even
+         *    be obtained for one;
+         *  - `AuthPasswordResetBackendService.completePasswordReset` — the true peer, a one-off token
+         *    that reaches an account-state check — throws a single `AUTHENTICATION_INVALID_TOKEN` for
+         *    every arm, including "no such user";
+         *  - the password-reset REQUEST leg returns a generic success for a non-ACTIVE user, with the
+         *    reason written down in its own code as anti-enumeration.
+         *
+         * So three siblings had one posture and this method had another. The window it opened is narrow —
+         * a link minted while the account was ACTIVE and clicked after it was suspended — but a narrow
+         * window is a reason to close it cheaply, not a reason to keep it.
+         *
+         * ## What is NOT lost
+         *
+         * Nothing operational. `logMagicLinkFailed` already carries the exact status, and it did before
+         * this change; the distinction moves from the client to the audit trail, which is where a
+         * suspended-account signal belongs. No client branches on either code — the frontend's
+         * `userExists` consumers read the IDENTIFY response, not this one.
+         */
         if (!user) {
+            await this.auditLogsService.logMagicLinkFailed({
+                failureReason: 'Magic link token resolves to no user row',
+                ipAddress: deviceInfo?.ipAddress || 'unknown',
+                userAgent: deviceInfo?.userAgent || 'unknown',
+            });
             return {
                 success: false,
                 sessionId: '',
                 userExists: false,
                 factorLevel: AuthFactorLevel.FIRST,
                 authMethod: AuthMethod.MAGIC_LINK,
-                error: 'User not found',
-                errorCode: 'USER_NOT_FOUND',
+                error: 'Invalid or expired magic link',
+                errorCode: 'MAGIC_LINK_INVALID',
                 retryAllowed: false,
                 integrationTokens: [],
                 requiresMFA: false,
@@ -2553,11 +2731,11 @@ let AuthenticationOrchestratorBackendService = class AuthenticationOrchestratorB
             return {
                 success: false,
                 sessionId: '',
-                userExists: true,
+                userExists: false,
                 factorLevel: AuthFactorLevel.FIRST,
                 authMethod: AuthMethod.MAGIC_LINK,
-                error: 'Account is not active',
-                errorCode: 'ACCOUNT_INACTIVE',
+                error: 'Invalid or expired magic link',
+                errorCode: 'MAGIC_LINK_INVALID',
                 retryAllowed: false,
                 integrationTokens: [],
                 requiresMFA: false,
@@ -3244,26 +3422,28 @@ AuthenticationOrchestratorBackendService = AuthenticationOrchestratorBackendServ
     __param(1, inject(SAAS_SERVICE_TYPES.AppConfigService)),
     __param(2, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
     __param(3, inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService)),
-    __param(4, inject(SAAS_SERVICE_TYPES.AuditLogsService)),
-    __param(5, inject(SAAS_SERVICE_TYPES.AuthSessionStore)),
-    __param(6, inject(SAAS_SERVICE_TYPES.AuthCredentialVerifier)),
-    __param(7, inject(SAAS_SERVICE_TYPES.AuthTokenIssuer)),
-    __param(8, inject(SAAS_SERVICE_TYPES.ConsumableTokenService)),
-    __param(9, inject(SAAS_SERVICE_TYPES.RedisService)),
-    __param(10, inject(SAAS_SERVICE_TYPES.RateLimitBackendService)),
-    __param(11, inject(SAAS_SERVICE_TYPES.DomainToOrgLookupService)),
-    __param(12, inject(SAAS_SERVICE_TYPES.AuthOrganizationConfigurationService)),
-    __param(13, inject(SAAS_SERVICE_TYPES.WebAuthnService)),
-    __param(14, inject(SAAS_SERVICE_TYPES.OAuth2ConnectionResolverService)),
-    __param(15, inject(SAAS_SERVICE_TYPES.AuthUserLookupService)),
-    __param(16, inject(SAAS_SERVICE_TYPES.AuthCredentialOpsService)),
-    __param(17, inject(SAAS_SERVICE_TYPES.SystemAccessService)),
-    __param(18, inject(SAAS_SERVICE_TYPES.MongoDBService)),
-    __param(19, inject(SAAS_SERVICE_TYPES.ResourcePersistenceUnitOfWorkService)),
-    __param(20, inject(SAAS_SERVICE_TYPES.AuthMfaService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService)),
+    __param(5, inject(SAAS_SERVICE_TYPES.AuditLogsService)),
+    __param(6, inject(SAAS_SERVICE_TYPES.AuthSessionStore)),
+    __param(7, inject(SAAS_SERVICE_TYPES.AuthCredentialVerifier)),
+    __param(8, inject(SAAS_SERVICE_TYPES.AuthTokenIssuer)),
+    __param(9, inject(SAAS_SERVICE_TYPES.ConsumableTokenService)),
+    __param(10, inject(SAAS_SERVICE_TYPES.RedisService)),
+    __param(11, inject(SAAS_SERVICE_TYPES.RateLimitBackendService)),
+    __param(12, inject(SAAS_SERVICE_TYPES.DomainToOrgLookupService)),
+    __param(13, inject(SAAS_SERVICE_TYPES.AuthOrganizationConfigurationService)),
+    __param(14, inject(SAAS_SERVICE_TYPES.WebAuthnService)),
+    __param(15, inject(SAAS_SERVICE_TYPES.OAuth2ConnectionResolverService)),
+    __param(16, inject(SAAS_SERVICE_TYPES.AuthUserLookupService)),
+    __param(17, inject(SAAS_SERVICE_TYPES.AuthCredentialOpsService)),
+    __param(18, inject(SAAS_SERVICE_TYPES.SystemAccessService)),
+    __param(19, inject(SAAS_SERVICE_TYPES.MongoDBService)),
+    __param(20, inject(SAAS_SERVICE_TYPES.ResourcePersistenceUnitOfWorkService)),
+    __param(21, inject(SAAS_SERVICE_TYPES.AuthMfaService)),
     __metadata("design:paramtypes", [LoggerService,
         AppConfigurationService,
-        ErrorBuilderBackendService, Function, AuditLogsBackendService,
+        ErrorBuilderBackendService, Function, RepositoriesRegistryHandlerBackendService,
+        AuditLogsBackendService,
         AuthSessionStoreBackendService,
         AuthCredentialVerifierBackendService,
         AuthTokenIssuerBackendService,