fix(auth): 2단계 인증을 켠 사이트의 로그인 흐름 구현

2단계 인증은 7.0.6 에서 서버측이 갖춰졌지만 인증번호를 입력할 화면이 어느 버전에도
없었다. 그래서 그 설정을 켠 사이트는 관리자를 포함한 전원이 로그인할 수 없었다.

원인은 `POST /api/auth/login` 이 조건에 따라 **다른 형태의 200** 을 돌려준다는 것이다.
평소에는 `{token, user}` 지만 2단계 인증이 켜져 있으면 `{two_factor_required,
challenge_id, ...}` 를 돌려준다. 프론트는 앞의 형태만 선언하고 `response.data.user.language`
를 바로 읽었으므로 그 자리에서 TypeError 가 났고, 영문 원문이 로그인 화면에 그대로 노출됐다.
서버는 정상 응답했으므로 서버 로그에는 아무 흔적도 남지 않는다.

이어서 `setToken(undefined)` 가 `localStorage` 에 문자열 `"undefined"` 를 남겼다.
이 값은 truthy 라 이후 모든 요청이 `Bearer undefined` 로 나가 401 이 되고, 사용자에게는
「세션이 만료되었습니다」로 보인다. 관리자 로그인은 한발 더 나가 `null->isAdmin` 으로
500 이 되어, 설정을 되돌릴 수단까지 함께 사라졌다.

## 구현

- 로그인 응답을 판별 유니온(`LoginResult`)으로 표현하고, 형태를 판별한 뒤에 읽는다.
 `ApiClient.setToken` 은 비어 있지 않은 문자열만 저장한다.
- 사용자·관리자 로그인 화면에 인증번호 입력 단계를 추가했다. 같은 카드 안에서 넘어가며
 「인증번호 다시 받기」와 「처음부터」를 제공한다. 관리자 판정은 코드 확인에 성공한 뒤에
 수행하고, 거부할 때는 그 직전에 발급된 토큰을 회수한다.
- 재발송(`login/two-factor/resend`)은 기존 challenge 를 취소하고 새로 발행한다. 유효한
 코드를 여러 개 살려 두면 대입 시도의 표적이 넓어진다.
- 인증번호를 보내지 못하면 401 이 아니라 503 으로 답한다. 자격 증명은 올바른데 401 로
 뭉개면 사용자는 비밀번호를 의심하며 같은 시도를 반복하고, 운영자는 메일 설정이 깨진
 사실을 알 방법이 없다.
- 공개 본인인증 경로(`identity/verify`·`cancel`)가 로그인 목적의 challenge 를 소진하지
 못하도록 403 게이트를 세웠다. 소진되면 그 challenge 로 영영 로그인할 수 없다.
- 로그인 시도 제한 429 응답이 다국어 문구를 싣도록 했다(종전에는 프레임워크 기본 영문).
- 다국어 파라미터에서 파이프 표현식이 평가되지 않아 「유효시간 까지」처럼 값이 빠지던
 문제를 함께 고쳤다. 같은 결함이 문의 목록 화면에도 있었다.

## 이번 점검에서 함께 고친 것

- 계정 잠금(423)·발송 실패(503) 응답이 사용자·관리자 컨트롤러에 동일하게 복제돼 있었고
 그 주석 자신은 "단일 지점에서 만든다" 고 적혀 있었다. 페이로드에 필드가 하나 추가되면
 한쪽만 따라가 같은 실패를 두 화면이 다르게 안내하게 된다 — 트레이트로 통합했다.
- 테스트가 개발자 자신의 사이트 설정을 읽고 있었다. 2단계 인증을 켜 둔 환경에서는 로그인
 성공을 전제한 테스트가 503 으로 깨지는데 실패 메시지가 원인을 가리키지도 않는다.
 같은 결함군을 위해 이미 존재하던 단일 지점에 그 축을 추가했다.

## 버전

코어 7.0.11 · sirsoft-basic 1.1.4 · sirsoft-admin_basic 1.0.9 ·
번들 일본어팩 3종 · 템플릿 엔진 engine-v1.65.0.

app/Http/Controllers/Api/Admin/AuthController.php

@@ -3,9 +3,13 @@
 namespace App\Http\Controllers\Api\Admin;
 
 use App\Exceptions\Auth\AccountLockedException;
+use App\Exceptions\Auth\TwoFactorDeliveryFailedException;
 use App\Http\Controllers\Api\Base\AdminBaseController;
+use App\Http\Controllers\Concerns\BuildsAuthFailureResponses;
 use App\Http\Requests\Auth\AuthenticatedRequest;
 use App\Http\Requests\Auth\LoginRequest;
+use App\Http\Requests\Auth\TwoFactorChallengeRequest;
+use App\Http\Requests\Auth\TwoFactorResendRequest;
 use App\Http\Resources\UserResource;
 use App\Services\AuthService;
 use Illuminate\Http\JsonResponse;
@@ -13,10 +17,21 @@ use Illuminate\Validation\ValidationException;
 
 class AuthController extends AdminBaseController
 {
+    use BuildsAuthFailureResponses;
+
     public function __construct(
         private AuthService $authService
     ) {
-        parent::__construct();
+        // 부모 생성자 호출하지 않음 - 인증 미들웨어를 수동으로 설정
+        // parent::__construct();
+
+        // 2단계 인증 확인·재발송은 아직 토큰이 없는 상태에서 호출된다 — 주체는 challenge 가
+        // 식별하며, 관리자 여부는 코드 확인에 성공한 뒤 서비스가 돌려준 사용자로 판정한다.
+        $this->middleware(['auth:sanctum', 'admin'])->except([
+            'login',
+            'verifyTwoFactor',
+            'resendTwoFactor',
+        ]);
     }
 
     /**
@@ -33,10 +48,21 @@ class AuthController extends AdminBaseController
                 $request->validated()['password']
             );
 
+            // 2단계 인증이 켜져 있으면 아직 토큰도 사용자도 없다 — 관리자 판정은 코드 확인
+            // 뒤로 미룬다. 이 분기가 없으면 $data['user'] 가 없어 500 이 되고, 관리자까지
+            // 로그인할 수 없어 설정을 되돌릴 수단이 사라진다.
+            if ($data['two_factor_required'] ?? false) {
+                return $this->success('auth.two_factor_required', $data);
+            }
+
             $user = $data['user'];
 
             // 관리자 권한 확인
             if (! $user->isAdmin()) {
+                // 이 시점에는 이미 토큰과 web 세션이 발급되어 있다 — 거절하면서 남겨 두면
+                // 관리자가 아닌 사용자가 응답만 403 을 받을 뿐 세션은 그대로 유효해진다.
+                $this->authService->revokeIssuedSession($user, $data['token']);
+
                 return $this->forbidden('auth.admin_required');
             }
 
@@ -45,22 +71,92 @@ class AuthController extends AdminBaseController
 
             return $this->success('auth.admin_login_success', $data);
         } catch (AccountLockedException $e) {
-            // 영구 잠금(무한대 설정)은 해제 시각·잔여 시간이 없다 — null 그대로 노출.
-            return $this->error(
-                $e->isPermanent() ? 'auth.account_locked_permanently' : 'auth.account_locked',
-                423,
-                [
-                    'locked_until' => $e->lockedUntil?->toIso8601String(),
-                    'retry_after_seconds' => $e->remainingMinutes === null ? null : $e->remainingMinutes * 60,
-                    'permanent' => $e->isPermanent(),
-                ],
-                ['minutes' => $e->remainingMinutes]
-            );
+            return $this->lockedResponse($e);
+        } catch (TwoFactorDeliveryFailedException $e) {
+            return $this->deliveryFailedResponse();
         } catch (ValidationException $e) {
             return $this->unauthorized('auth.login_failed');
         }
     }
 
+    /**
+     * 관리자의 2단계 인증 코드를 확인하고 로그인을 완료합니다.
+     *
+     * 비밀번호 확인 단계(`login`)는 토큰 대신 challenge 를 돌려주며, 이 엔드포인트가
+     * 코드 확인에 성공해야 비로소 토큰이 발급됩니다.
+     *
+     * @param  TwoFactorChallengeRequest  $request  challenge 확인 요청
+     * @return JsonResponse 로그인 결과와 관리자 정보, 토큰을 포함한 JSON 응답
+     */
+    public function verifyTwoFactor(TwoFactorChallengeRequest $request): JsonResponse
+    {
+        $validated = $request->validated();
+
+        try {
+            $data = $this->authService->completeTwoFactor(
+                $validated['challenge_id'],
+                ['code' => $validated['code']]
+            );
+
+            $user = $data['user'];
+
+            if (! $user->isAdmin()) {
+                // completeTwoFactor() 는 코드 확인에 성공한 시점에 토큰을 발급한다.
+                // 관리자 판정으로 거절하면서 그 발급분을 회수하지 않으면 관리자가 아닌
+                // 사용자가 유효한 세션을 손에 쥔 채 응답만 403 을 받는다.
+                $this->authService->revokeIssuedSession($user, $data['token']);
+
+                return $this->forbidden('auth.admin_required');
+            }
+
+            $data['user'] = new UserResource($user);
+
+            return $this->success('auth.admin_login_success', $data);
+        } catch (AccountLockedException $e) {
+            // 세션을 여는 지점이므로 `login` 과 같은 423 계약을 따른다.
+            return $this->lockedResponse($e);
+        } catch (TwoFactorDeliveryFailedException $e) {
+            return $this->deliveryFailedResponse();
+        } catch (ValidationException $e) {
+            return $this->unauthorized('auth.two_factor_failed');
+        }
+    }
+
+    /**
+     * 관리자의 2단계 인증 코드를 재발송합니다.
+     *
+     * 기존 challenge 는 취소되고 새 challenge 가 발행되므로, 앞서 받은 인증번호는
+     * 더 이상 통하지 않습니다.
+     *
+     * @param  TwoFactorResendRequest  $request  challenge 재발송 요청
+     * @return JsonResponse 새 challenge 정보를 포함한 JSON 응답
+     */
+    public function resendTwoFactor(TwoFactorResendRequest $request): JsonResponse
+    {
+        try {
+            $resolvedUser = null;
+
+            $data = $this->authService->resendTwoFactorChallenge(
+                $request->validated()['challenge_id'],
+                $resolvedUser
+            );
+
+            // 이 단계는 토큰을 발급하지 않으므로 회수할 것이 없다 — 다만 완료할 수 없는
+            // 상대에게 새 인증번호를 계속 보내지는 않는다.
+            if ($resolvedUser === null || ! $resolvedUser->isAdmin()) {
+                return $this->forbidden('auth.admin_required');
+            }
+
+            return $this->success('auth.two_factor_required', $data);
+        } catch (AccountLockedException $e) {
+            return $this->lockedResponse($e);
+        } catch (TwoFactorDeliveryFailedException $e) {
+            return $this->deliveryFailedResponse();
+        } catch (ValidationException $e) {
+            return $this->validationError($e->errors(), 'auth.two_factor_invalid_challenge');
+        }
+    }
+
     /**
      * 관리자를 로그아웃시킵니다.
      *
@@ -113,16 +209,7 @@ class AuthController extends AdminBaseController
         } catch (AccountLockedException $e) {
             // 재발급도 세션을 여는 지점이다 — 사용자 경로와 같은 423 계약을 따른다.
             // 이 catch 가 없으면 잠긴 계정의 재발급 시도가 500 으로 새어 나간다.
-            return $this->error(
-                $e->isPermanent() ? 'auth.account_locked_permanently' : 'auth.account_locked',
-                423,
-                [
-                    'locked_until' => $e->lockedUntil?->toIso8601String(),
-                    'retry_after_seconds' => $e->remainingMinutes === null ? null : $e->remainingMinutes * 60,
-                    'permanent' => $e->isPermanent(),
-                ],
-                ['minutes' => $e->remainingMinutes]
-            );
+            return $this->lockedResponse($e);
         } catch (ValidationException $e) {
             return $this->unauthorized('auth.unauthenticated');
         }

app/Http/Controllers/Api/Auth/AuthController.php

@@ -3,13 +3,16 @@
 namespace App\Http\Controllers\Api\Auth;
 
 use App\Exceptions\Auth\AccountLockedException;
+use App\Exceptions\Auth\TwoFactorDeliveryFailedException;
 use App\Http\Controllers\Api\Base\AuthBaseController;
+use App\Http\Controllers\Concerns\BuildsAuthFailureResponses;
 use App\Http\Requests\Auth\AuthenticatedRequest;
 use App\Http\Requests\Auth\ForgotPasswordRequest;
 use App\Http\Requests\Auth\LoginRequest;
 use App\Http\Requests\Auth\RegisterRequest;
 use App\Http\Requests\Auth\ResetPasswordRequest;
 use App\Http\Requests\Auth\TwoFactorChallengeRequest;
+use App\Http\Requests\Auth\TwoFactorResendRequest;
 use App\Http\Requests\Auth\ValidateResetTokenRequest;
 use App\Http\Resources\UserResource;
 use App\Services\AuthService;
@@ -18,6 +21,8 @@ use Illuminate\Validation\ValidationException;
 
 class AuthController extends AuthBaseController
 {
+    use BuildsAuthFailureResponses;
+
     public function __construct(
         private AuthService $authService
     ) {
@@ -27,8 +32,9 @@ class AuthController extends AuthBaseController
         // 공개 인증 엔드포인트를 제외한 나머지에만 인증 미들웨어 적용
         $this->middleware('auth:sanctum')->except([
             'login',
-            // 2단계 인증 확인은 아직 토큰이 없는 상태에서 호출된다 — 주체는 challenge 가 식별한다
+            // 2단계 인증 확인·재발송은 아직 토큰이 없는 상태에서 호출된다 — 주체는 challenge 가 식별한다
             'verifyTwoFactor',
+            'resendTwoFactor',
             'register',
             'forgotPassword',
             'resetPassword',
@@ -61,6 +67,8 @@ class AuthController extends AuthBaseController
             return $this->success('auth.login_success', $data);
         } catch (AccountLockedException $e) {
             return $this->lockedResponse($e);
+        } catch (TwoFactorDeliveryFailedException $e) {
+            return $this->deliveryFailedResponse();
         } catch (ValidationException $e) {
             return $this->unauthorized('auth.login_failed');
         }
@@ -92,32 +100,37 @@ class AuthController extends AuthBaseController
             // 세션을 여는 지점이므로 `login` 과 같은 423 계약을 따른다 — 화면은 두 경로를
             // 구분하지 않으므로 한쪽만 다른 모양이면 잠금 안내가 깨진다.
             return $this->lockedResponse($e);
+        } catch (TwoFactorDeliveryFailedException $e) {
+            return $this->deliveryFailedResponse();
         } catch (ValidationException $e) {
             return $this->unauthorized('auth.two_factor_failed');
         }
     }
 
     /**
-     * 계정 잠금 응답(423)을 구성합니다.
+     * 2단계 인증 코드를 재발송합니다.
      *
-     * 세션을 발급하는 모든 엔드포인트가 같은 페이로드를 돌려주도록 단일 지점에서 만든다.
+     * 기존 challenge 는 취소되고 새 challenge 가 발행되므로, 앞서 받은 인증번호는
+     * 더 이상 통하지 않습니다.
      *
-     * @param  AccountLockedException  $e  잠금 예외
-     * @return JsonResponse 423 응답
+     * @param  TwoFactorResendRequest  $request  challenge 재발송 요청
+     * @return JsonResponse 새 challenge 정보를 포함한 JSON 응답
      */
-    private function lockedResponse(AccountLockedException $e): JsonResponse
+    public function resendTwoFactor(TwoFactorResendRequest $request): JsonResponse
     {
-        // 영구 잠금(무한대 설정)은 해제 시각·잔여 시간이 없다 — null 그대로 노출.
-        return $this->error(
-            $e->isPermanent() ? 'auth.account_locked_permanently' : 'auth.account_locked',
-            423,
-            [
-                'locked_until' => $e->lockedUntil?->toIso8601String(),
-                'retry_after_seconds' => $e->remainingMinutes === null ? null : $e->remainingMinutes * 60,
-                'permanent' => $e->isPermanent(),
-            ],
-            ['minutes' => $e->remainingMinutes]
-        );
+        try {
+            $data = $this->authService->resendTwoFactorChallenge(
+                $request->validated()['challenge_id']
+            );
+
+            return $this->success('auth.two_factor_required', $data);
+        } catch (AccountLockedException $e) {
+            return $this->lockedResponse($e);
+        } catch (TwoFactorDeliveryFailedException $e) {
+            return $this->deliveryFailedResponse();
+        } catch (ValidationException $e) {
+            return $this->validationError($e->errors(), 'auth.two_factor_invalid_challenge');
+        }
     }
 
     /**

app/Http/Controllers/Api/Identity/IdentityVerificationController.php

@@ -3,6 +3,7 @@
 namespace App\Http\Controllers\Api\Identity;
 
 use App\Enums\IdentityOriginType;
+use App\Enums\IdentityVerificationPurpose;
 use App\Extension\IdentityVerification\IdentityVerificationManager;
 use App\Http\Controllers\Api\Base\PublicBaseController;
 use App\Http\Requests\Identity\CancelChallengeRequest;
@@ -96,6 +97,15 @@ class IdentityVerificationController extends PublicBaseController
      */
     public function verify(VerifyChallengeRequest $request, IdentityVerificationLog $challenge): JsonResponse
     {
+        // 로그인 challenge 는 이 공개 경로로 다루지 않는다. 여기서 검증·취소되면
+        // 바로 뒤의 `auth/login/two-factor` 가 INVALID_STATE 로 거절해, 그 challenge 로는
+        // 영영 로그인할 수 없게 된다(자기 DoS). 로그인 전용 엔드포인트만 사용한다.
+        if ($challenge->purpose === IdentityVerificationPurpose::Login->value) {
+            return $this->error('identity.errors.purpose_not_allowed', 403, [
+                'failure_code' => 'PURPOSE_NOT_ALLOWED',
+            ]);
+        }
+
         $result = $this->service->verify(
             challengeId: $challenge->id,
             input: $request->validated(),
@@ -142,6 +152,15 @@ class IdentityVerificationController extends PublicBaseController
      */
     public function cancel(CancelChallengeRequest $request, IdentityVerificationLog $challenge): JsonResponse
     {
+        // 로그인 challenge 는 이 공개 경로로 다루지 않는다. 여기서 검증·취소되면
+        // 바로 뒤의 `auth/login/two-factor` 가 INVALID_STATE 로 거절해, 그 challenge 로는
+        // 영영 로그인할 수 없게 된다(자기 DoS). 로그인 전용 엔드포인트만 사용한다.
+        if ($challenge->purpose === IdentityVerificationPurpose::Login->value) {
+            return $this->error('identity.errors.purpose_not_allowed', 403, [
+                'failure_code' => 'PURPOSE_NOT_ALLOWED',
+            ]);
+        }
+
         $ok = $this->service->cancel($challenge->id);
 
         if (! $ok) {

app/Http/Controllers/Concerns/BuildsAuthFailureResponses.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace App\Http\Controllers\Concerns;
+
+use App\Exceptions\Auth\AccountLockedException;
+use Illuminate\Http\JsonResponse;
+
+/**
+ * 세션을 발급하는 엔드포인트가 공유하는 실패 응답을 구성하는 트레이트.
+ *
+ * 사용자 로그인과 관리자 로그인은 서로 다른 베이스 컨트롤러를 상속하지만, 계정 잠금과
+ * 인증번호 발송 실패는 **같은 사건**이므로 같은 형태로 응답해야 합니다. 두 컨트롤러가
+ * 각자 사본을 들고 있으면 한쪽 페이로드에 필드가 추가될 때 다른 쪽이 조용히 뒤처져,
+ * 같은 실패인데 화면이 다르게 안내하게 됩니다.
+ *
+ * @since 7.0.11
+ */
+trait BuildsAuthFailureResponses
+{
+    /**
+     * 계정 잠금 응답(423)을 구성합니다.
+     *
+     * @param  AccountLockedException  $e  잠금 예외
+     * @return JsonResponse 423 응답
+     */
+    protected function lockedResponse(AccountLockedException $e): JsonResponse
+    {
+        // 영구 잠금(무한대 설정)은 해제 시각·잔여 시간이 없다 — null 그대로 노출.
+        return $this->error(
+            $e->isPermanent() ? 'auth.account_locked_permanently' : 'auth.account_locked',
+            423,
+            [
+                'locked_until' => $e->lockedUntil?->toIso8601String(),
+                'retry_after_seconds' => $e->remainingMinutes === null ? null : $e->remainingMinutes * 60,
+                'permanent' => $e->isPermanent(),
+            ],
+            ['minutes' => $e->remainingMinutes]
+        );
+    }
+
+    /**
+     * 인증번호 발송 실패 응답(503)을 구성합니다.
+     *
+     * 자격 증명은 올바르므로 401 로 답하지 않는다 — 사용자는 비밀번호를 의심하며 같은
+     * 실패를 반복하고, 운영자는 메일 설정이 깨진 사실을 알 방법이 없다.
+     *
+     * @return JsonResponse 503 응답
+     */
+    protected function deliveryFailedResponse(): JsonResponse
+    {
+        return $this->error('auth.two_factor_delivery_failed', 503);
+    }
+}