auth(2fa): add one-time recovery codes with regenerate/status APIs

tests/test_auth_flow.py

@@ -148,3 +148,52 @@ async def test_twofa_setup_is_blocked_when_already_enabled(client, db_session):
 
     setup_again_response = await client.post("/api/v1/auth/2fa/setup", headers=headers)
     assert setup_again_response.status_code == 400
+
+
+async def test_twofa_recovery_codes_can_login_once(client, db_session):
+    payload = {
+        "email": "erin@example.com",
+        "name": "Erin",
+        "username": "erin",
+        "password": "strongpass123",
+    }
+    await client.post("/api/v1/auth/register", json=payload)
+    token_row = await db_session.execute(select(EmailVerificationToken).order_by(EmailVerificationToken.id.desc()))
+    verify_token = token_row.scalar_one().token
+    await client.post("/api/v1/auth/verify-email", json={"token": verify_token})
+
+    login_response = await client.post(
+        "/api/v1/auth/login",
+        json={"email": payload["email"], "password": payload["password"]},
+    )
+    assert login_response.status_code == 200
+    access_token = login_response.json()["access_token"]
+    headers = {"Authorization": f"Bearer {access_token}"}
+
+    setup_response = await client.post("/api/v1/auth/2fa/setup", headers=headers)
+    assert setup_response.status_code == 200
+    secret = setup_response.json()["secret"]
+    enable_response = await client.post("/api/v1/auth/2fa/enable", headers=headers, json={"code": _totp_code(secret)})
+    assert enable_response.status_code == 200
+
+    regen_response = await client.post(
+        "/api/v1/auth/2fa/recovery-codes/regenerate",
+        headers=headers,
+        json={"code": _totp_code(secret)},
+    )
+    assert regen_response.status_code == 200
+    codes = regen_response.json()["codes"]
+    assert len(codes) >= 1
+    first_code = codes[0]
+
+    login_with_recovery = await client.post(
+        "/api/v1/auth/login",
+        json={"email": payload["email"], "password": payload["password"], "recovery_code": first_code},
+    )
+    assert login_with_recovery.status_code == 200
+
+    reuse_recovery_code = await client.post(
+        "/api/v1/auth/login",
+        json={"email": payload["email"], "password": payload["password"], "recovery_code": first_code},
+    )
+    assert reuse_recovery_code.status_code == 401