Method setup

apps/api/src/api/auth/services/mfa.service.ts:58–97

* Begin enrollment. Requires the user's current password as step-up * auth so a stolen session cannot silently enrol a new device. The * generated secret is encrypted at rest in Valkey; the route forwards * the otpauth URI + plaintext recovery codes to the SPA for display. * * Calling

(userId: string, password: string)

   * Calling `setup` twice replaces the prior staged secret.
   */
  async setup(userId: string, password: string): Promise<IMfaSetupResult> {
    const user = await this.assertPasswordValid(userId, password);

    if (user.mfaEnabledAt !== null) {
      throw ApiErrors.conflict(
        "MFA is already enabled. Disable it before enrolling a new device."
      );
    }

    const secret = new Secret({ size: 32 });
    const totp = buildTotp(secret.base32, user.email);
    const recoveryCodes = generateRecoveryCodes();
    const recoveryCodeHashes = await Promise.all(
      recoveryCodes.map((code) => passwordService.hash(code))
    );
    const cachePayload: IMfaSetupCachePayload = {
      secretEncrypted: encryptString(secret.base32),
      recoveryCodeHashes,
    };

    await cacheService.set(MFA_CACHE_KEYS.setup(userId), cachePayload, {
      ttlSeconds: MFA_SETUP_TTL_SECONDS,
    });

    void auditLogService.record({
      userId,
      action: AUDIT_ACTIONS.AUTH_MFA_SETUP_INITIATED,
    });

    logger.info("MFA setup initiated", {
      event: "auth.mfa.setup_initiated",
      userId,
    });

    return {
      otpauthUri: totp.toString(),
      secretBase32: secret.base32,
      recoveryCodes,
    };
  }

  /**
   * Complete enrollment. Validates the first TOTP code against the