@wildo-ai/saas-backend-lib 1.0.1

package/src/security/authentications/services/auth-methods/webauthn.backend.service.ts

@@ -0,0 +1,393 @@
+import 'reflect-metadata';
+import { inject, injectable } from 'inversify';
+import {
+  generateRegistrationOptions,
+  verifyRegistrationResponse,
+  generateAuthenticationOptions,
+  verifyAuthenticationResponse,
+} from '@simplewebauthn/server';
+import type {
+  PublicKeyCredentialCreationOptionsJSON,
+  PublicKeyCredentialRequestOptionsJSON,
+  RegistrationResponseJSON,
+  AuthenticationResponseJSON,
+} from '@simplewebauthn/server';
+
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';
+import { RedisService } from '~wildo-backend-lib/databases/services/redis.service';
+import { AuthCredentialOpsBackendService } from '~wildo-backend-lib/security/authentications/services/utils/auth-credential-ops.backend.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import {
+  UserCredentials,
+  PasskeyCredentialEntry,
+  ErrorType,
+  ErrorCustomMessageReference,
+} from '@wildo-ai/saas-models';
+
+const CHALLENGE_TTL_SECONDS = 300; // 5 minutes
+const CHALLENGE_KEY_PREFIX_REG = 'webauthn_challenge:reg:';
+const CHALLENGE_KEY_PREFIX_AUTH = 'webauthn_challenge:auth:';
+
+/**
+ * WebAuthnBackendService
+ *
+ * Encapsulates all WebAuthn/FIDO2 ceremony logic using @simplewebauthn/server.
+ * Handles option generation, response verification, challenge management (Redis),
+ * and credential CRUD on user credential documents.
+ *
+ * This service does NOT:
+ * - Manage sessions (AuthSessionStore)
+ * - Issue tokens (AuthTokenIssuer)
+ * - Audit log (orchestrator/controller responsibility)
+ * - Know about the authentication flow (orchestrator's job)
+ */
+@injectable()
+export class WebAuthnBackendService {
+  private readonly logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly appConfigService: AppConfigurationService,
+    @inject(SAAS_SERVICE_TYPES.RedisService) private readonly redisService: RedisService,
+    @inject(SAAS_SERVICE_TYPES.AuthCredentialOpsService) private readonly credentialOps: AuthCredentialOpsBackendService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('WebAuthn');
+    this.logger.setDebugTypeLogging('WebAuthn', false);
+  }
+
+  // ─── Configuration ───────────────────────────────────────────
+
+  private get rpId(): string {
+    return this.appConfigService.config.auth.passkeyConfig.rpId;
+  }
+
+  private get rpName(): string {
+    return this.appConfigService.config.auth.passkeyConfig.rpName;
+  }
+
+  private get passkeyOps() {
+    return this.appConfigService.config.auth.passkeyOperational;
+  }
+
+  /**
+   * Derive the expected origin(s) from the app config's runtime endpoints.
+   * Returns all configured publicUrl values as valid origins.
+   */
+  private get expectedOrigins(): string[] {
+    const endPoints = this.appConfigService.config.runtime.endPoints;
+    const origins: string[] = [];
+    for (const [, urls] of Object.entries(endPoints)) {
+      if (urls?.publicUrl) {
+        origins.push(urls.publicUrl.replace(/\/$/, ''));
+      }
+    }
+    if (origins.length === 0) {
+      origins.push(`https://${this.rpId}`);
+    }
+    return origins;
+  }
+
+  // ─── Registration ────────────────────────────────────────────
+
+  /**
+   * Generate WebAuthn registration options for a user.
+   * The caller is responsible for ensuring the user is authenticated.
+   */
+  async generateRegistrationOptions(
+    ec: ExecutionContext<any>,
+    userId: string,
+    email: string,
+  ): Promise<PublicKeyCredentialCreationOptionsJSON> {
+    const { cred } = await this._resolveCredentialRecord(ec, userId);
+    const existingCredentials = (cred as UserCredentials).passkeyCredentials ?? [];
+
+    const maxPasskeys = this.appConfigService.config?.auth?.passkeyConfig?.maxPasskeysPerUser ?? 10;
+    if (existingCredentials.length >= maxPasskeys) {
+      throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+        context: { reason: `Maximum of ${maxPasskeys} passkeys reached` },
+      });
+    }
+
+    const ops = this.passkeyOps;
+    const options = await generateRegistrationOptions({
+      rpName: this.rpName,
+      rpID: this.rpId,
+      userName: email,
+      userDisplayName: email,
+      userID: new TextEncoder().encode(userId),
+      // Cast: @simplewebauthn narrows to 'direct'|'enterprise'|'none' but W3C
+      // AttestationConveyancePreference includes 'indirect' — valid at runtime.
+      attestationType: ops.attestation as 'direct' | 'enterprise' | 'none',
+      timeout: ops.timeoutSeconds * 1000,
+      authenticatorSelection: {
+        authenticatorAttachment: ops.authenticatorAttachment === 'any' ? undefined : ops.authenticatorAttachment,
+        residentKey: ops.requireResidentKey ? 'required' : 'preferred',
+        userVerification: ops.userVerification,
+      },
+      excludeCredentials: existingCredentials.map((c) => ({
+        id: c.credentialId,
+        transports: c.transports as AuthenticatorTransport[],
+      })),
+    });
+
+    await this._storeChallenge(CHALLENGE_KEY_PREFIX_REG + userId, options.challenge);
+    this.logDebug('Registration options generated', { userId, excludeCount: existingCredentials.length });
+
+    return options;
+  }
+
+  /**
+   * Verify a WebAuthn registration response and store the new credential.
+   * Returns the new credential entry on success.
+   */
+  async verifyRegistrationResponse(
+    ec: ExecutionContext<any>,
+    userId: string,
+    response: RegistrationResponseJSON,
+    credentialName?: string,
+  ): Promise<PasskeyCredentialEntry> {
+    const expectedChallenge = await this._getAndDeleteChallenge(CHALLENGE_KEY_PREFIX_REG + userId);
+    if (!expectedChallenge) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_CREDENTIALS_INVALID,
+        context: { reason: 'WebAuthn registration challenge expired or not found' },
+      });
+    }
+
+    const verification = await verifyRegistrationResponse({
+      response,
+      expectedChallenge,
+      expectedOrigin: this.expectedOrigins,
+      expectedRPID: this.rpId,
+      requireUserVerification: this.passkeyOps.userVerification === 'required',
+    });
+
+    if (!verification.verified || !verification.registrationInfo) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_CREDENTIALS_INVALID,
+        context: { reason: 'WebAuthn registration verification failed' },
+      });
+    }
+
+    const { credential, credentialDeviceType, credentialBackedUp } = verification.registrationInfo;
+
+    const newCredential: PasskeyCredentialEntry = {
+      credentialId: credential.id,
+      publicKey: Buffer.from(credential.publicKey).toString('base64url'),
+      counter: credential.counter,
+      transports: (credential.transports ?? []) as string[],
+      credentialDeviceType: credentialDeviceType ?? 'singleDevice',
+      credentialBackedUp: credentialBackedUp ?? false,
+      name: credentialName ?? 'Passkey',
+      aaguid: verification.registrationInfo.aaguid,
+      createdAt: new Date(),
+      lastUsedAt: undefined,
+    };
+
+    // Append to the credential record
+    const { cred } = await this._resolveCredentialRecord(ec, userId);
+    const existingCredentials = (cred as UserCredentials).passkeyCredentials ?? [];
+    const updatedCredentials = [...existingCredentials, newCredential];
+
+    await this.credentialOps.updateById(ec, cred._id, { passkeyCredentials: updatedCredentials } as Partial<UserCredentials>);
+
+    this.logDebug('Passkey registered', { userId, credentialId: newCredential.credentialId });
+    return newCredential;
+  }
+
+  // ─── Authentication ──────────────────────────────────────────
+
+  /**
+    * Generate WebAuthn authentication options for a user.
+   * Populates allowCredentials from the user's stored passkeys.
+   */
+  async generateAuthenticationOptions(
+    ec: ExecutionContext<any>,
+    userId: string,
+  ): Promise<PublicKeyCredentialRequestOptionsJSON> {
+    const { cred } = await this._resolveCredentialRecord(ec, userId);
+    const existingCredentials = (cred as UserCredentials).passkeyCredentials ?? [];
+
+    if (existingCredentials.length === 0) {
+      throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_CREDENTIALS_INVALID,
+        context: { reason: 'No passkey credentials registered for this user' },
+      });
+    }
+
+    const options = await generateAuthenticationOptions({
+      rpID: this.rpId,
+      userVerification: this.passkeyOps.userVerification,
+      timeout: this.passkeyOps.timeoutSeconds * 1000,
+      allowCredentials: existingCredentials.map((c) => ({
+        id: c.credentialId,
+        transports: c.transports as AuthenticatorTransport[],
+      })),
+    });
+
+    await this._storeChallenge(CHALLENGE_KEY_PREFIX_AUTH + userId, options.challenge);
+    this.logDebug('Authentication options generated', { userId, credentialCount: existingCredentials.length });
+
+    return options;
+  }
+
+  /**
+   * Verify a WebAuthn authentication response.
+   * Updates the credential counter and lastUsedAt on success.
+   */
+  async verifyAuthenticationResponse(
+    ec: ExecutionContext<any>,
+    userId: string,
+    response: AuthenticationResponseJSON,
+  ): Promise<{ verified: boolean; credentialId: string }> {
+    const expectedChallenge = await this._getAndDeleteChallenge(CHALLENGE_KEY_PREFIX_AUTH + userId);
+    if (!expectedChallenge) {
+      return { verified: false, credentialId: response.id };
+    }
+
+    const { cred } = await this._resolveCredentialRecord(ec, userId);
+    const existingCredentials = (cred as UserCredentials).passkeyCredentials ?? [];
+    const matchedCredential = existingCredentials.find((c) => c.credentialId === response.id);
+
+    if (!matchedCredential) {
+      this.logger.warn('WebAuthn authentication failed: credential not found', {
+        userId,
+        credentialId: response.id,
+      });
+      return { verified: false, credentialId: response.id };
+    }
+
+    const verification = await verifyAuthenticationResponse({
+      response,
+      expectedChallenge,
+      expectedOrigin: this.expectedOrigins,
+      expectedRPID: this.rpId,
+      requireUserVerification: this.passkeyOps.userVerification === 'required',
+      credential: {
+        id: matchedCredential.credentialId,
+        publicKey: Buffer.from(matchedCredential.publicKey, 'base64url'),
+        counter: matchedCredential.counter,
+        transports: matchedCredential.transports as AuthenticatorTransport[],
+      },
+    });
+
+    if (!verification.verified) {
+      return { verified: false, credentialId: response.id };
+    }
+
+    // Counter verification (clone detection)
+    const newCounter = verification.authenticationInfo.newCounter;
+    if (newCounter > 0 && newCounter <= matchedCredential.counter) {
+      this.logger.warn('WebAuthn counter did not increment — possible credential clone', {
+        userId,
+        credentialId: matchedCredential.credentialId,
+        storedCounter: matchedCredential.counter,
+        receivedCounter: newCounter,
+      });
+    }
+
+    // Update counter and lastUsedAt
+    const updatedCredentials = existingCredentials.map((c) =>
+      c.credentialId === matchedCredential.credentialId
+        ? { ...c, counter: newCounter, lastUsedAt: new Date() }
+        : c,
+    );
+
+    await this.credentialOps.updateById(ec, cred._id, { passkeyCredentials: updatedCredentials } as Partial<UserCredentials>);
+
+    this.logDebug('Passkey authentication verified', { userId, credentialId: matchedCredential.credentialId });
+    return { verified: true, credentialId: matchedCredential.credentialId };
+  }
+
+  // ─── Credential CRUD ─────────────────────────────────────────
+
+  /**
+   * List all passkey credentials for a user (safe fields only — no publicKey/counter).
+   */
+  async getCredentials(ec: ExecutionContext<any>, userId: string): Promise<PasskeyCredentialEntry[]> {
+    const { cred } = await this._resolveCredentialRecord(ec, userId);
+    return (cred as UserCredentials).passkeyCredentials ?? [];
+  }
+
+  /**
+   * Remove a passkey credential by its credential ID.
+   */
+  async removeCredential(ec: ExecutionContext<any>, userId: string, credentialId: string): Promise<void> {
+    const { cred } = await this._resolveCredentialRecord(ec, userId);
+    const existingCredentials = (cred as UserCredentials).passkeyCredentials ?? [];
+    const updatedCredentials = existingCredentials.filter((c) => c.credentialId !== credentialId);
+
+    if (updatedCredentials.length === existingCredentials.length) {
+      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+        context: { reason: 'Passkey credential not found', credentialId },
+      });
+    }
+
+    await this.credentialOps.updateById(ec, cred._id, { passkeyCredentials: updatedCredentials } as Partial<UserCredentials>);
+
+    this.logDebug('Passkey removed', { userId, credentialId });
+  }
+
+  /**
+   * Rename a passkey credential.
+   */
+  async renameCredential(ec: ExecutionContext<any>, userId: string, credentialId: string, newName: string): Promise<void> {
+    const { cred } = await this._resolveCredentialRecord(ec, userId);
+    const existingCredentials = (cred as UserCredentials).passkeyCredentials ?? [];
+    const found = existingCredentials.find((c) => c.credentialId === credentialId);
+
+    if (!found) {
+      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+        context: { reason: 'Passkey credential not found', credentialId },
+      });
+    }
+
+    const updatedCredentials = existingCredentials.map((c) =>
+      c.credentialId === credentialId ? { ...c, name: newName } : c,
+    );
+
+    await this.credentialOps.updateById(ec, cred._id, { passkeyCredentials: updatedCredentials } as Partial<UserCredentials>);
+
+    this.logDebug('Passkey renamed', { userId, credentialId, newName });
+  }
+
+  // ─── Challenge Management (Redis) ────────────────────────────
+
+  private async _storeChallenge(key: string, challenge: string): Promise<void> {
+    await this.redisService.set(key, challenge, { ttl: CHALLENGE_TTL_SECONDS });
+  }
+
+  private async _getAndDeleteChallenge(key: string): Promise<string | null> {
+    const fullKey = this.redisService.buildKey(key);
+    const GETDEL_SCRIPT = `local v = redis.call('GET', KEYS[1]); if v then redis.call('DEL', KEYS[1]); end; return v`;
+    const result = await this.redisService.eval(GETDEL_SCRIPT, [fullKey], []);
+    return result as string | null;
+  }
+
+  // ─── Internal Helpers ────────────────────────────────────────
+
+  /**
+   * Resolve the credential record for a user.
+   * Returns the credential document (throws if not found).
+   */
+  private async _resolveCredentialRecord(
+    ec: ExecutionContext<any>,
+    userId: string,
+  ): Promise<{
+    cred: UserCredentials;
+  }> {
+    const cred = await this.credentialOps.readByUserId(ec, userId);
+    if (!cred) {
+      throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+        context: { reason: 'User credentials not found', userId },
+      });
+    }
+    return { cred };
+  }
+}
+
+type AuthenticatorTransport = 'ble' | 'cable' | 'hybrid' | 'internal' | 'nfc' | 'smart-card' | 'usb';

package/src/security/authentications/services/auth-session-store.backend.service.ts

@@ -0,0 +1,211 @@
+import 'reflect-metadata';
+import { inject, injectable } from 'inversify';
+import * as crypto from 'crypto';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { RedisService } from '~wildo-backend-lib/databases/services/redis.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { AuthenticationSession, AuthenticationSessionSchema } from '@wildo-ai/saas-models';
+import { ErrorType, ErrorCustomMessageReference } from '@wildo-ai/saas-models';
+import { AUTH_REDIS_KEYS } from '~wildo-backend-lib/security/authentications/models/auth-constants.backend';
+
+/**
+ * IAuthSessionStore interface — abstraction over session storage.
+ * Implementations: RedisAuthSessionStore (production), InMemoryAuthSessionStore (testing).
+ */
+export interface IAuthSessionStore {
+  /** Get a session by ID. Returns null if not found or expired. */
+  get(sessionId: string): Promise<AuthenticationSession | null>;
+  /** Store a session with a TTL in seconds. */
+  set(sessionId: string, session: AuthenticationSession, ttlSeconds: number): Promise<void>;
+  /** Delete a session. */
+  delete(sessionId: string): Promise<void>;
+  /** Check if a session exists. */
+  exists(sessionId: string): Promise<boolean>;
+  /** Generate a cryptographically secure session ID. */
+  generateSessionId(): string;
+}
+
+/**
+ * Redis-backed authentication session store.
+ *
+ * Replaces the in-memory Map<string, AuthenticationSession> from the old AuthenticationBackendService.
+ * Sessions are stored as JSON in Redis with TTL-based expiry — no cleanup interval needed.
+ *
+ * TRAP 1 (from plan): If Redis is down, all authentication fails.
+ * This is intentional — fail-fast prevents a false sense of persistence from a silent in-memory fallback.
+ *
+ * TRAP 10 (from plan): Date serialization — AuthenticationSessionSchema.parse() on read
+ * handles z.coerce.date() conversion from ISO strings back to Date objects.
+ */
+@injectable()
+export class AuthSessionStoreBackendService implements IAuthSessionStore {
+  private readonly logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.RedisService) private readonly redisService: RedisService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('AuthSessionStore');
+    this.logger.setDebugTypeLogging('AuthSessionStore', false);
+  }
+
+  /**
+   * Generate a cryptographically secure session ID.
+   * Fix for Section 6.5: replaces Date.now()-Math.random() with crypto.randomBytes(32).
+   */
+  public generateSessionId(): string {
+    return crypto.randomBytes(32).toString('hex');
+  }
+
+  public async get(sessionId: string): Promise<AuthenticationSession | null> {
+    try {
+      const raw = await this.redisService.get<Record<string, unknown>>(this.key(sessionId));
+      if (!raw) {
+        return null;
+      }
+
+      // TRAP 10: JSON.parse() (inside RedisService.get) converts Date objects to ISO strings.
+      // AuthenticationSessionSchema uses z.date() which rejects strings.
+      // We must convert date fields back to Date objects before parsing.
+      const rehydrated = {
+        ...raw,
+        createdAt: raw.createdAt ? new Date(raw.createdAt as string) : undefined,
+        expiresAt: raw.expiresAt ? new Date(raw.expiresAt as string) : undefined,
+        lastActivity: raw.lastActivity ? new Date(raw.lastActivity as string) : undefined,
+        lockoutUntil: raw.lockoutUntil ? new Date(raw.lockoutUntil as string) : undefined,
+      };
+
+      const session = AuthenticationSessionSchema.parse(rehydrated);
+      return session;
+    } catch (error) {
+      this.logger.error('Failed to get auth session from Redis', {
+        sessionId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  }
+
+  public async set(sessionId: string, session: AuthenticationSession, ttlSeconds: number): Promise<void> {
+    try {
+      // Validate session before storing
+      const validated = AuthenticationSessionSchema.parse(session);
+      await this.redisService.set(this.key(sessionId), validated, { ttl: ttlSeconds });
+      this.logDebug(`Session stored: ${sessionId}`, { ttlSeconds });
+    } catch (error) {
+      this.logger.error('Failed to store auth session in Redis', {
+        sessionId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw this.errorBuilder.buildError(ErrorType.DATABASE, undefined, {
+        customMessageReference: ErrorCustomMessageReference.REDIS_CONNECTION_FAILED,
+        context: { operation: 'auth-session-set', sessionId },
+      });
+    }
+  }
+
+  public async delete(sessionId: string): Promise<void> {
+    try {
+      await this.redisService.del(this.key(sessionId));
+      this.logDebug(`Session deleted: ${sessionId}`);
+    } catch (error) {
+      this.logger.error('Failed to delete auth session from Redis', {
+        sessionId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      // Non-critical — session will expire via TTL anyway
+    }
+  }
+
+  public async exists(sessionId: string): Promise<boolean> {
+    try {
+      return await this.redisService.exists(this.key(sessionId));
+    } catch (error) {
+      this.logger.error('Failed to check auth session existence in Redis', {
+        sessionId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return false;
+    }
+  }
+
+  /**
+   * M1 fix: Atomic compare-and-swap update using a Lua script.
+   *
+   * Reads the current session, checks the version matches `expectedVersion`,
+   * and only writes the new session if versions match. This prevents TOCTOU
+   * race conditions in concurrent session state updates.
+   *
+   * @returns The updated session on success, or null if the version was stale
+   *          (indicating another writer modified the session concurrently).
+   */
+  public async atomicUpdate(
+    sessionId: string,
+    updatedSession: AuthenticationSession,
+    expectedVersion: number,
+    ttlSeconds: number,
+  ): Promise<AuthenticationSession | null> {
+    const validated = AuthenticationSessionSchema.parse(updatedSession);
+    const newJson = JSON.stringify(validated);
+
+    // Lua script: atomic check-version-then-set
+    // KEYS[1] = session key
+    // ARGV[1] = expected version (string)
+    // ARGV[2] = new session JSON
+    // ARGV[3] = TTL in seconds
+    // Returns: 1 if updated, 0 if version mismatch, -1 if key not found
+    const script = `
+      local data = redis.call('GET', KEYS[1])
+      if not data then return -1 end
+      local session = cjson.decode(data)
+      if tostring(session['version'] or 0) ~= ARGV[1] then return 0 end
+      redis.call('SETEX', KEYS[1], ARGV[3], ARGV[2])
+      return 1
+    `;
+
+    try {
+      // Use buildKey() to match the prefixed key that set()/get() produce
+      const fullKey = this.redisService.buildKey(this.key(sessionId));
+      const result = await this.redisService.eval(
+        script,
+        [fullKey],
+        [String(expectedVersion), newJson, String(ttlSeconds)],
+      );
+
+      if (result === 1) {
+        this.logDebug(`Session atomically updated: ${sessionId}`, { version: validated.version });
+        return validated;
+      }
+
+      if (result === 0) {
+        this.logDebug(`Session atomic update rejected (version stale): ${sessionId}`, {
+          expectedVersion,
+          newVersion: validated.version,
+        });
+        return null;
+      }
+
+      // result === -1: session not found
+      return null;
+    } catch (error) {
+      this.logger.error('Failed to atomically update auth session in Redis', {
+        sessionId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw this.errorBuilder.buildError(ErrorType.DATABASE, undefined, {
+        customMessageReference: ErrorCustomMessageReference.REDIS_CONNECTION_FAILED,
+        context: { operation: 'auth-session-atomic-update', sessionId },
+      });
+    }
+  }
+
+  /**
+   * Build the Redis key for a session.
+   * Uses the global scope (no organizationId) since auth sessions are app-level.
+   */
+  private key(sessionId: string): string {
+    return `${AUTH_REDIS_KEYS.SESSION}${sessionId}`;
+  }
+}