---
task_id: task-2263
type: context
scope: task
created: 2026-04-28
updated: 2026-04-28
status: completed
---

# 맥락 노트: task-2263

**task**: task-2263

---

## 결정 근거

### SSRF 방지: 도메인 화이트리스트 방식 채택
- 도메인 화이트리스트(supabase.co, drive.google.com, storage.googleapis.com)로 제한
- IP 블랙리스트만으로는 DNS rebinding 공격에 취약
- 화이트리스트 + IP 검증 이중 방어 채택

### JWT verify_signature 처리: 검증 실패 시 탐지 스킵
- 미들웨어에서 서명 검증 후 사용하면 JWKS 조회 오버헤드 발생
- 대안: 서명 검증 시도 → 실패 시 탐지 스킵 (차단이 아닌 모니터링이므로 허용)
- 채택: 검증 실패 시 탐지 스킵 방식 (성능 영향 최소화)

### 에러 메시지 일반화: 내부 로그 + 일반 응답 분리
- `logger.exception()`으로 내부 로그 기록 보존
- 클라이언트 응답은 일반 메시지로 통일
- generation_queue/pipeline의 내부 상태 필드는 에러 타입만 기록 (상세 제거)

## 3 Step Why

### 1st Why: "왜 이 보안 수정이 필요한가?"
- SSRF로 내부 네트워크(AWS 메타데이터 등) 접근 가능, 서비스 키 탈취 위험
- JWT 미검증으로 조작된 토큰 사용 가능, 다중 계정 탐지 우회
- 에러 메시지에 스택트레이스 노출은 공격 벡터 정보 제공

### 2nd Why: "왜 이 접근법이 최선인가?"
- 화이트리스트: 허용 도메인이 3개로 한정적이므로 블랙리스트보다 안전
- JWT 탐지 스킵: 미들웨어 목적이 '차단'이 아닌 '모니터링'이므로 검증 실패=스킵이 합리적
- 에러 일반화: OWASP A01 권장사항이며, 로거로 디버깅 정보 보존

### 3rd Why: "왜 다른 대안보다 나은가?"
- 대안 A(프록시 서버 분리): 인프라 변경 필요, 현재 규모에 과도
- 대안 B(JWT 미들웨어 제거): 다중 계정 탐지 기능 자체가 사라짐
- 대안 C(에러 코드 매핑): 현재 11개소에 각각 고유 코드 부여는 과설계

## 참조 자료

- 보안 감사 보고서: `/home/jay/workspace/memory/reports/insuro-security-audit-2026-04.md`
- OWASP Top 10 (2021): A10-SSRF, A07-Authentication, A04-Insecure Design

## 주의사항

- main.py 5068줄 대형 파일 — Edit 실패 주의, offset/limit으로 정확한 위치 확인 후 수정
- verify_aud 활성화 시 audience 값 정확히 설정 필요 (Supabase 기본: "authenticated")
- npm audit fix 시 breaking change 여부 확인 필수
- 파일 변환 엔드포인트에 verify_jwt 추가 시 프론트엔드 호출 코드도 확인 필요