Files
DongHyeonka 6583cc2e02 docs(fileserver): 파일서버 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: docs/fileserver 아래 살아 있는 문서 8개가 영어였다(language 예외). 번역하며
본 주장 중 지금 코드와 다른 것이 있었다.
- design-deviations.md: 지운 `FileStateMachine`·`FileserverStorageConfiguration`·
  content-store SPI 넷(`AsyncContentStore` 등)을 지금 있는 것처럼 적었다. 고정 테스트로
  없는 `SampleApplicationContextTest`·`LocalOrphanScanAdapterTest`·
  `FileserverRoundTripContractTest`를 댔다. JPA 저장소가 persistence-jpa에 있다고 했지만
  지금은 persistence-fileserver의 `FileserverJpaPersistenceConfig` 조건 하나 뒤에 있다.
  지운 reactive transport가 아직 스트리밍한다고 했다.
- security.md: 「익명 읽기를 켜면」이라고 했지만 설정 스위치가 없다
  (`FileserverSecurityConfiguration`이 늘 false로 만든다). 이름 `ContentDispositionFactory`는
  지금 `HttpContentDispositionFactory`다.
- upgrade-guide.md: batch 실패를 `results[].problem`으로, 결과 모름을 problem document로
  읽으라고 했다. 지금은 `results[].error`와 Envelope `error.details.ambiguous`다. 확인 명령이
  Fileserver 테스트가 없는 `:app-bootstrap:test --tests '*Fileserver*'`와 fileserver 코드가 없는
  `:application-core:check`·`:adapter:inbound:web:check`를 돌렸다.
- operations.md: 「NFS 결과 모름」 신호를 problem document로 적었다(지금은 Envelope).

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 지원 등급
이름(Stable, Beta, Limited, Compatibility, Experimental)은 표와 테스트가 읽는 꼬리표라
원문으로 둔다(messaging 지원 매트릭스와 같다). configuration.md의 절 제목은 테스트가 읽는
「… — `key`」 꼴을 지킨다. 위 불일치는 코드에 맞춰 고쳤다.

테스트: FileserverDocumentationCoverageTest가 runbook 제목 일곱과 「Explicitly not
claimed」를 영어 문자열로 단언했다. 같은 계약(runbook마다 제목이 있고, 주장하지 않는 것을
따로 밝힌다)을 한국어 제목 `## 저장소 가득 참` 등과 `## 주장하지 않는 것`으로 단언한다.
제목 앞에 `## `를 붙여 본문 어딘가에 낱말만 있어도 통과하던 것을 제목으로 좁혔다.
metric 이름·CI job·endpoint·설정 key 단언은 그대로다.

버린 대안: runbook 제목을 영어로 남기기. 살아 있는 문서를 한국어로 쓴다는 소유자 결정과
맞지 않는다.

위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다.

검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0). 테스트의 단언을 같은 정규식으로
문서에 돌려 보았다(runbook 제목·job 존재·설정 key 44개가 번역 전과 같음).
2026-11-07 17:29:57 +09:00

5.1 KiB

Fileserver 보안 모델

나머지가 모두 따르는 규칙

올라온 content는 공격자가 정한다. 아래 보호 장치는 모두 요청의 어떤 부분(파일 이름, 선언한 media type, range, offset)이 호출자가 고른 값이기 때문에 있다.

경로 안전

client 값은 절대 경로가 되지 않는다. 물리 key는 서버가 만들고, ContentKey의 글자 집합에는 .이 아예 없다. 그래서 경로 거슬러 오르기나 확장자 모양의 조각은 검증을 통과하지 못한다. 식별자가 Path가 되는 곳은 DefaultPhysicalPathResolver 하나다. 입력을 믿지 않고, 만든 뒤 정규화해서 root 안에 있는지 다시 확인한다.

symlink 거부는 경로를 만들 때만이 아니라 열 때도 한다. 그 사이에 부모 폴더가 바뀔 수 있으므로, 경로를 만들 때만 검사하면 보호 장치가 아니라 경쟁 조건이다.

파일 이름 처리

OriginalFilenamePolicy는 경로 구분자, NUL, 따옴표 문자, 콜론을 지운다. 콜론은 Windows에서 드라이브 참조와 NTFS alternate data stream을 모두 열기 때문에, 슬래시를 지워도 콜론이 남으면 여전히 경로 모양이다. 제어 문자와 양방향 override를 지우고, 이어진 점을 하나로 줄이고, 예약된 장치 이름을 막고, 결과를 UTF-8 바이트로 제한한다.

정리한 이름은 표시용 데이터다. key를 만드는 데 절대 쓰지 않는다. 헤더에는 HttpContentDispositionFactory를 거쳐서만 들어가고, 이것이 ASCII 형태를 제한하고 UTF-8 형태를 percent-encoding한다.

Content 형식

client의 Content-Type은 주장으로 저장한다. 검증한 형식은 검증 pipeline에서 오고, 검증한 형식만 내보낸다. content와 어긋나는 주장 형식은 고치지 않고 격리한다.

스크립트가 될 수 있는 형식은 호출자가 무엇을 요청했든 절대 inline으로 내보내지 않는다. 업로드 origin에서 저장된 HTML이나 SVG를 inline으로 내보내면 stored cross-site scripting의 재료가 된다. 모든 다운로드는 X-Content-Type-Options: nosniff도 붙인다.

검증 우선순위

REJECT > QUARANTINE > RETRY > ACCEPT. 시간 초과나 예외를 낸 검증기는 RETRY이고 조용한 통과가 아니다. 검증기가 하나도 없으면 받아들이지 않고 RETRY로 답한다. 파일은 ACCEPT 뒤에야 공개로 읽을 수 있다.

Range 안전

range 예산은 content를 열기 전에 강제한다. 그래서 range를 많이 적은 요청은 저장소 작업을 불리지 않고 거부된다. 만족할 수 없는 range는 실제 길이를 담은 416으로 답하고 아무것도 열지 않는다.

권한

모든 공개 연산은 할당량 예약이나 저장소 변경 전에 주입한 FileAccessPolicyPort를 부른다. 그래서 거부하면 기록도, 예약도, staging 객체도 남지 않는다. finalize는 FINALIZE로, management plane 읽기는 ADMIN_READ로 권한을 본다. 시작 단계는 모두 허락하는 정책으로 운영 profile을 돌리는 것을 거부한다.

파일마다 소유자를 기록한다. 그 파일을 만든 principal, 그리고 transport가 하나를 풀었다면 그 tenant(tenant subject 속성)다. 기본 role 정책은 이미 있는 파일에 대한 연산을 같은 tenant의 소유자에게만 허락한다. 그래서 같은 role을 가진 두 호출자도 서로의 파일을 읽거나, 다운로드하거나, finalize하거나, 지우거나, copy하거나, move할 수 없다. admin role도 이것을 건너뛰지 않는다. 다른 호출자의 파일을 다루라고 감사하는 management plane이 있다. 소유자를 기록하기 전(마이그레이션 V5)에 만든 파일은 소유자가 없고 management plane으로만 닿는다.

익명 읽기는 설정으로 켤 수 없다(configuration.md 「권한」). role-based 정책은 늘 끈 채로 만든다. RoleBasedFileAccessPolicy를 직접 만들면서 익명 읽기를 켜면 모든 파일을 공개하고 소유자 검사를 건너뛴다.

위임

X-Accel-Redirect는 권한 확인과 READY 관문을 지난 뒤, 조건 없는 전체 응답에만 내보낸다. 내부 접두사는 Nginx의 internal location이어야 한다. 프런트 프록시는 client가 보낸 위임 헤더도 지워서 호출자가 내부 객체를 가리키지 못하게 한다.

Telemetry

metric label, span 속성, 감사 기록 어디에도 file id, upload id, 파일 이름, 경로, user id를 담지 않는다. 상관관계가 필요한 곳은 key를 쓴 HMAC fingerprint를 쓴다. 식별자 공간은 셀 수 있으므로 key 없는 digest는 전수 대입으로 되돌릴 수 있다. 그래서 key가 필요하다.

결과를 모르는 실패

연산이 이미 효과를 냈을 수 있는 실패는 결과를 모르는 것(ambiguous)으로 보고하고 절대 재시도할 수 있다고 하지 않는다. 네트워크 파일 시스템에서는 사라진 응답과 socket 수준의 거부를 구분할 수 없다. 그래서 안전하다고 증명할 수 없는 것은 모두 결과를 모르는 것으로 보고 맞춰 보기로 보낸다.