136 lines
5.4 KiB
Markdown
136 lines
5.4 KiB
Markdown
|
|
![[file_download_flow.svg]]
|
|
## 단계별 상세
|
|
|
|
### 1. 사용자 인증 / 공유 링크 접근
|
|
|
|
요청의 진입점으로, 두 가지 접근 경로를 처리한다.
|
|
|
|
- **인증 사용자**: `Authorization` 헤더의 JWT Bearer 토큰을 파싱 및 검증
|
|
- **공유 링크**: URL 쿼리 파라미터의 `share_token`을 파싱
|
|
|
|
두 경로 모두 이후 단계에서 동일한 인터페이스로 처리될 수 있도록 내부적으로 정규화한다.
|
|
|
|
---
|
|
|
|
### 2. 파일 권한 / 공유 상태 검증
|
|
|
|
DB를 조회하여 요청자가 해당 파일에 접근할 수 있는지 확인한다.
|
|
|
|
- 인증 사용자: 파일의 소유자 또는 공유 대상 여부 확인
|
|
- 공유 링크: 링크의 활성화 여부, 만료 여부, 비밀번호 보호 여부 확인
|
|
- 권한이 없으면 즉시 **`403 Forbidden`** 반환 (이후 단계로 진행하지 않음)
|
|
|
|
##### Risk
|
|
권한이 없는 경우 `403`, 파일이 없는 경우 `404`를 분리 반환한다. 이 차이를 이용하면 공격자가 파일 ID를 열거하여 존재하는 파일 목록을 추론할 수 있다.
|
|
|
|
---
|
|
|
|
### 3. 다운로드 토큰 발급
|
|
|
|
실제 스트리밍 요청에 사용할 단명(short-lived) 토큰을 생성한다.
|
|
|
|
- TTL은 **약 60초** 권장 (재사용·탈취 위험 최소화)
|
|
- 토큰에는 파일 ID, 요청자 식별자, 만료 시각을 포함
|
|
- HMAC 서명 또는 JWT로 위변조 방지
|
|
|
|
```
|
|
# Redis 기반 원자적 무효화
|
|
result = REDIS.SET(f"dl_token:{token}", "used", NX=True, EX=60)
|
|
# NX: key가 없을 때만 SET → 원자적 보장
|
|
# result가 None이면 이미 사용된 토큰 → 401
|
|
|
|
```
|
|
|
|
> API 서버와 스트리밍 서버를 분리 운영할 때 특히 유용하다.
|
|
> 클라이언트는 이 토큰을 받아 스트리밍 엔드포인트에 직접 요청한다.
|
|
|
|
---
|
|
|
|
### 4. 다운로드 토큰으로 파일 스트림 요청
|
|
|
|
클라이언트가 발급받은 토큰으로 스트리밍 엔드포인트에 요청한다.
|
|
|
|
```
|
|
GET /files/stream?token={download_token}
|
|
Range: bytes=0-1048575 (선택, Range 요청 시)
|
|
```
|
|
|
|
- 토큰이 만료되었거나 유효하지 않으면 **`401 Unauthorized`** 반환
|
|
- 토큰은 1회 사용 후 무효화하는 것을 권장 (재생 공격 방어)
|
|
|
|
#### Risk
|
|
- "토큰은 1회 사용 후 무효화하는 것을 권장"이라고만 기술되어 있으나, 동시에 같은 토큰으로 2개 이상의 요청이 들어오는 경우의 원자적 무효화 전략이 없다.
|
|
- 토큰을 1회 사용 후 무효화하면, 대용량 파일의 Range 기반 이어받기(resume)가 불가능해진다. 네트워크 끊김 후 클라이언트가 `Range: bytes=10485760-`으로 재요청하면, 이미 무효화된 토큰이므로 `401`이 반환된다.
|
|
-
|
|
---
|
|
|
|
### 5. storage_key → 로컬 FS 경로 resolve
|
|
|
|
`storage_key`를 실제 파일 시스템 경로로 변환한다.
|
|
|
|
- 키-경로 맵(DB 또는 설정 파일)을 조회하여 절대 경로 획득
|
|
- **Path traversal 방어 필수**: `realpath()` 등으로 경로를 정규화하고, 허용된 루트 디렉터리(`/data/uploads/` 등) 내에 있는지 반드시 검증
|
|
- 파일이 존재하지 않으면 **`404 Not Found`** 반환
|
|
|
|
---
|
|
|
|
### 6. 파일 스트림 응답 (Range 지원 권장)
|
|
|
|
파일을 청크 단위로 스트리밍하여 응답한다.
|
|
|
|
**응답 헤더:**
|
|
|
|
|헤더|값|
|
|
|---|---|
|
|
|`Content-Type`|파일 MIME 타입|
|
|
|`Content-Disposition`|`attachment; filename="파일명"`|
|
|
|`Accept-Ranges`|`bytes`|
|
|
|`Content-Length`|파일 크기 (전체 또는 청크)|
|
|
|
|
**Range 지원 시 동작:**
|
|
|
|
- `Range` 헤더가 있으면 **`206 Partial Content`** 로 응답
|
|
- `Range` 헤더가 없으면 **`200 OK`** 로 전체 파일 응답
|
|
- Range를 지원하면 대용량 파일 resume, 미디어 스트리밍, 멀티파트 다운로드 모두 대응 가능
|
|
|
|
|
|
#### Risk
|
|
- 응답 헤더에 `Content-Type: 파일 MIME 타입`이라고만 되어 있고, 이 값을 **어디서 가져오는지** 명시되어 있지 않다. 업로드 시 클라이언트가 보낸 값을 DB에 저장하고 그대로 사용하는 경우, 공격자가 `text/html`이나 `image/svg+xml`로 위장한 악성 파일을 업로드할 수 있다.
|
|
- 로컬 FS에서 직접 스트리밍하므로 API/스트리밍 서버의 egress 대역폭이 병목이 된다. 동시 다운로드 수 제한, 사용자별 대역폭 제한, 전체 서버 대역폭 보호 정책이 없다.
|
|
|
|
|
|
---
|
|
|
|
### 7. 로그 기록 / 카운트 증가
|
|
|
|
다운로드 완료 후 감사(Audit) 로그를 기록하고, 공유 링크의 경우 카운트를 증가시킨다.
|
|
|
|
- **로그 항목**: 파일 ID, 요청자, IP, User-Agent, 다운로드 시각, 파일 크기
|
|
- **카운트 증가**: 공유 링크에만 적용 (`download_count++`)
|
|
- **타이밍 주의**: 스트림이 **완전히 전송된 이후**에 카운트를 올린다. 요청 시점에 올리면 중단된 다운로드도 집계된다.
|
|
|
|
---
|
|
|
|
## 에러 응답 정리
|
|
|
|
|상황|HTTP 상태 코드|
|
|
|---|---|
|
|
|인증 실패 / 토큰 만료|`401 Unauthorized`|
|
|
|권한 없음|`403 Forbidden`|
|
|
|파일 없음|`404 Not Found`|
|
|
|Range 범위 초과|`416 Range Not Satisfiable`|
|
|
|정상 전체 응답|`200 OK`|
|
|
|정상 부분 응답 (Range)|`206 Partial Content`|
|
|
|
|
---
|
|
|
|
## 보안 체크리스트
|
|
|
|
- [ ] JWT / share_token 서명 검증
|
|
- [ ] 파일 접근 권한 DB 조회 (캐시 사용 시 TTL 주의)
|
|
- [ ] 다운로드 토큰 단명 발급 (TTL ≤ 60s)
|
|
- [ ] 토큰 1회 사용 후 무효화
|
|
- [ ] Path traversal 방어 (`realpath` + 루트 경로 검증)
|
|
- [ ] `Content-Disposition: attachment` 헤더 명시
|
|
- [ ] 다운로드 완료 후 감사 로그 기록 |