# task-579.1 완료 보고서: InsuWiki 보안 강화 — guest 역할 DB/API 레벨 차단

## SCQA

**S**: InsuWiki의 인증 시스템은 Firebase Auth 기반으로 운영되며, guest/member/admin 3가지 역할이 AuthContext에 정의되어 있다.

**C**: guest 차단이 UI 레벨에서만 이루어져 있어, guest 사용자가 Firestore Rules(isAuthenticated()만 체크)와 API 미들웨어(토큰 유효성만 검사)를 통해 DB 직접 접근 및 AI API 호출이 가능한 보안 취약점이 존재한다. 또한 firestore.ts의 UserRole(`admin|editor|viewer`)이 AuthContext(`guest|member|admin`)와 불일치한다.

**Q**: Firestore Rules와 API 미들웨어 레벨에서 guest를 차단하고, UserRole 타입을 통일하여 보안 취약점을 해소할 수 있는가?

**A**: `isMemberOrAdmin()` 헬퍼 함수를 Firestore Rules에 추가하여 12개 컬렉션 규칙에 적용하고, `verifyMember()` / `verifyMemberFromParam()` 미들웨어를 구현하여 8개 AI API 라우트 + share-target 라우트에 적용 완료. UserRole 타입도 `admin|member|guest`로 통일. autocomplete 테스트 14건 전체 통과, guest 403 테스트 4건 추가.

## 작업 내용

### 1. Firestore Rules — guest DB 접근 차단
- `isMemberOrAdmin()` 헬퍼 함수 추가
- 12개 컬렉션 규칙에 `&& isMemberOrAdmin()` 조건 추가
- 대상: documents(+subcollections), dailyNotes, links, tags, insurance_metadata(read), insurance_summaries(read), conversation_sessions, drafts
- 유지: users(본인 프로필), whitelist(가입 확인), server-side only 컬렉션

### 2. auth-middleware.ts — member 이상만 허용 미들웨어
- `verifyMember(req)`: 토큰 검증 + Firestore role 확인, guest→403
- `verifyMemberFromParam(token)`: 쿼리 파라미터 버전 동일 로직
- 기존 `verifyAuth` / `verifyAuthFromParam` 유지 (하위 호환)

### 3. API 라우트 교체 (8개 + share-target)
- query, vector-search, autocomplete, summarize, feedback, versions, settings, status
- share-target: `verifyAuthFromParam` → `verifyMemberFromParam`

### 4. UserRole 타입 통일
- `firestore.ts`: `'admin' | 'editor' | 'viewer'` → `'admin' | 'member' | 'guest'`
- `AuthContext.tsx`는 이미 `'guest' | 'member' | 'admin'`으로 정의 → 정합성 확보

### 5. 테스트 수정
- autocomplete, feedback 테스트: `verifyAuth` mock → `verifyMember` mock 교체
- guest 403 테스트 케이스 각 1건씩 추가

## 생성/수정 파일 (14건)

- `firestore.rules` — isMemberOrAdmin() 추가 + 12개 규칙 업데이트
- `nextapp/src/lib/auth-middleware.ts` — verifyMember, verifyMemberFromParam 추가
- `nextapp/src/app/api/ai/query/route.ts` — verifyAuth → verifyMember
- `nextapp/src/app/api/ai/vector-search/route.ts` — verifyAuth → verifyMember
- `nextapp/src/app/api/ai/autocomplete/route.ts` — verifyAuth → verifyMember
- `nextapp/src/app/api/ai/summarize/route.ts` — verifyAuth → verifyMember
- `nextapp/src/app/api/ai/feedback/route.ts` — verifyAuth → verifyMember
- `nextapp/src/app/api/ai/versions/route.ts` — verifyAuth → verifyMember
- `nextapp/src/app/api/ai/settings/route.ts` — verifyAuth → verifyMember
- `nextapp/src/app/api/ai/status/route.ts` — verifyAuth → verifyMember
- `nextapp/src/app/api/share-target/route.ts` — verifyAuthFromParam → verifyMemberFromParam
- `nextapp/src/types/firestore.ts` — UserRole 타입 변경
- `nextapp/src/app/api/ai/autocomplete/__tests__/route.test.ts` — mock 교체 + guest 403 테스트
- `nextapp/src/app/api/ai/feedback/__tests__/route.test.ts` — mock 교체 + guest 403 테스트

## 테스트 결과

- **autocomplete**: 14/14 통과 (기존 12 + guest 403 추가 2건)
- **feedback**: 19/44 통과 (25건 기존 실패 — 본 작업 범위 외, PATCH 핸들러 관련 기존 이슈)
- ⚠️ 기존 테스트 실패 25건 (본 작업 범위 외): feedback route PATCH 핸들러 테스트 — 메인 브랜치에서도 동일하게 25건 실패 확인

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **share-target에 guest 차단 누락 가능성** — `verifyMemberFromParam()` 함수를 별도 생성하여 share-target 라우트에도 guest 차단 적용
2. **UserRole 타입 불일치** — firestore.ts의 UserRole을 AuthContext와 동일한 `admin|member|guest`로 통일
3. **verifyMember에서 role 미설정(null/undefined) 처리** — `!role || role === 'guest'` 조건으로 role이 없는 사용자도 guest로 처리

### 범위 외 미해결 (2건)
1. **feedback route PATCH 핸들러 테스트 25건 실패** — 메인 브랜치에서도 동일 실패, 본 작업과 무관한 기존 이슈
2. **스키마 문서 `docs/decisions/260208-20.59-firestore-schema.md`에 구버전 UserRole 기재** — 문서 업데이트는 코드 변경 범위 밖

## 머지 판단

- **머지 필요**: Yes
- **브랜치**: task/task-579.1-dev1
- **워크트리 경로**: /home/jay/projects/insuwiki/.worktrees/task-579.1-dev1
- **머지 의견**: autocomplete 테스트 14/14 전체 통과, 기존 feedback 실패 25건은 메인 브랜치와 동일(회귀 없음). Firestore Rules 배포(`firebase deploy --only firestore:rules`)는 제이회장님 확인 후 별도 진행 필요.

## 커밋 내역 (6건)

1. `731aadf` [task-579.1] UserRole 타입 통일: admin|editor|viewer → admin|member|guest
2. `3ed06da` [task-579.1] firestore.rules에 isMemberOrAdmin() 추가 및 guest 접근 차단
3. `96c112b` [task-579.1] 테스트 verifyAuth→verifyMember 교체 + guest 403 테스트 추가
4. `968f409` [task-579.1] auth-middleware.ts에 verifyMember/verifyMemberFromParam 함수 추가
5. `361f1d4` [task-579.1] AI API 라우트 8개에서 verifyAuth → verifyMember 교체
6. `1207fa6` [task-579.1] share-target 라우트 verifyAuthFromParam → verifyMemberFromParam 교체

## 배포 참고사항

- Firestore Rules 적용: `firebase deploy --only firestore:rules` 필요 (제이회장님 확인 후 별도)
- API 미들웨어 변경은 Next.js 재배포 시 자동 적용