feat(i18n): apply ORY bypass whitelist policy and add error-code tests

docs/API_DESIGN_POLICY.md

@@ -86,11 +86,13 @@
 ```json
 {
   "error": "사람이 읽을 수 있는 에러 메시지",
-  "code": "MACHINE_READABLE_CODE", // 선택적 (예: USER_NOT_FOUND, HYDRA_CONN_ERR)
+  "code": "MACHINE_READABLE_CODE", // 1차 표준 필드 (예: invalid_session, rate_limited)
   "details": { ... } // 선택적 (Validation error 필드별 상세 등)
 }
 ```
 
+- `code`는 프론트 분기 기준이므로 신규/변경 API에서는 포함을 기본값으로 합니다.
+
 ## 5. 헤더 및 보안 (Headers & Security)
 
 ### 5.1 인증 (Authentication)

docs/i18n.md

@@ -165,6 +165,18 @@ TOML에서는 `[Section]`을 사용하여 계층을 표현합니다.
 #### 5.2.4 Flutter (User) 구현 가이드
 Flutter는 런타임에 TOML을 파싱하기 위해 `toml` 패키지와 `easy_localization`의 커스텀 로더를 사용합니다.
 
+#### 5.2.5 UserFront 에러 표시 정책 (Production)
+UserFront(`/error`)는 프로덕션에서 다음 규칙으로 에러를 표시합니다.
+
+1. **Internal whitelist 코드**
+   - `msg.userfront.error.whitelist.{code}` 메시지를 노출합니다.
+2. **ORY bypass 코드**
+   - `msg.userfront.error.ory.{code}` 메시지를 노출합니다.
+3. **그 외 코드**
+   - `unknown_error`로 처리하고 일반 안내 문구(`msg.userfront.error.detail_contact`)를 노출합니다.
+
+코드 집합은 `userfront/lib/core/constants/error_whitelist.dart`를 단일 기준으로 유지합니다.
+
 *   **패키지 추가 (`pubspec.yaml`)**:
     ```yaml
     dependencies:

docs/userfront_error_handling_policy.md

@@ -0,0 +1,72 @@
+# UserFront Error Handling Policy
+
+## 1. 목적
+- UserFront의 `/error` 화면에서 에러 코드 노출 정책을 일관되게 유지합니다.
+- Ory에서 전달되는 표준 에러 코드는 별도 bypass 규칙으로 처리합니다.
+- 내부 코드와 번역 리소스의 누락을 자동 검증합니다.
+
+## 2. 처리 원칙
+1. 프로덕션에서 에러 분기 기준은 `error` 문자열이 아니라 `code`입니다.
+2. `ORY error code`는 bypass 규칙으로 처리합니다.
+3. ORY 코드 외 항목은 내부 whitelist를 기준으로 노출합니다.
+4. whitelist/bypass에 없는 코드는 `unknown_error`로 처리합니다.
+
+## 3. 코드 분류
+기준 파일: `userfront/lib/core/constants/error_whitelist.dart`
+
+### 3.1 Internal whitelist
+- `settings_disabled`
+- `invalid_session`
+- `verification_required`
+- `recovery_expired`
+- `recovery_invalid`
+- `rate_limited`
+- `not_found`
+- `bad_request`
+- `password_or_email_mismatch`
+
+### 3.2 ORY bypass
+- `access_denied`
+- `consent_required`
+- `interaction_required`
+- `invalid_client`
+- `invalid_grant`
+- `invalid_request`
+- `invalid_scope`
+- `login_required`
+- `request_forbidden`
+- `server_error`
+- `temporarily_unavailable`
+- `unauthorized_client`
+- `unsupported_response_type`
+
+## 4. i18n 키 구조
+- 내부 whitelist: `msg.userfront.error.whitelist.{code}`
+- ORY bypass: `msg.userfront.error.ory.{code}`
+
+리소스는 아래 파일 모두에 키가 있어야 합니다.
+- `locales/template.toml`
+- `locales/ko.toml`
+- `locales/en.toml`
+- `userfront/assets/translations/template.toml`
+- `userfront/assets/translations/ko.toml`
+- `userfront/assets/translations/en.toml`
+
+## 5. 검증
+키 누락 검증 스크립트:
+
+```bash
+./scripts/verify_userfront_error_i18n.sh
+```
+
+화면 동작 테스트:
+
+```bash
+cd userfront
+flutter test test/error_screen_test.dart
+```
+
+## 6. 관련 이슈
+- `#164` `[UserFront] 에러 노출 whitelist 정의 및 적용`
+- `#259` `백엔드 i18n/에러 메시지 fallback 정책 재정리 및 반영 계획 수립`
+- `#260` `[Backend] 에러 응답 code 통일 구현 계획 (phase rollout)`