Files
clean-architecture-backend-…/docs/fileserver/security.md
T
donghyeon-kaandClaude Opus 5.5 64a8391889 review-followup Wave 3 라운드 2(P24): fileserver·object storage 구조, S3 조건부 retire, 소유자 결정 28–31 기록
- object storage: legacy `ObjectStoragePort` 세대(byte[] 포트·legacy S3/filesystem 어댑터·`app.object-storage.legacy.*`) 삭제,
  router 어댑터 `routing/`·managed publish `kernel/`, 식별자 record 4개·bounded-token guard 하나
- S3 retire를 버전 ID 조건 삭제로 구현(MinIO에서 DELETE가 If-Match를 무시함을 확인), versioning 미사용 bucket 거부(P14-new-4)
- S3 응답 bridge 순서 경합 수정(P24-new-1 — P14-new-2·P16-new-4 간헐 실패의 원인)
- fileserver: 전이표를 `FileState`로, 구현 1개 인터페이스·content SPI 확장 4개·통과 gateway 삭제, 예외 17개 → `FileserverException`+코드,
  outbound 포트 `*Port`, `UploadPolicy`가 namespace·만료 결정, admin force-delete도 진행 중 upload 정리(P14-new-1)
- 보류(결정 필요): S1-#6b(fileserver 연산을 use case로 → `@RequiresPermission` 이중 gate), S1-#18b inbound 절반
- 현황표: 소유자 결정 28–31(INTERNAL_ERROR retryable=false, messaging 테스트 snakeyaml, 변경 모듈만 실행 안 함, cosign 서명), P27·P28 묶음 추가

검증: ./gradlew check architectureCheck verifyDependencyLocks verifyPublicPathSnapshot :sample-portfolio:systemTest
:app-bootstrap:integrationTest --continue 통과(652 task, sample spotlessApply 1건 후). 묶음 worktree에서 fileserver PG lane·MinIO lane 통과

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-28 17:15:00 +09:00

4.3 KiB

Fileserver security model

The rule everything else follows

Uploaded content is attacker-controlled. Every guard below exists because some part of the request — the filename, the declared media type, the range, the offset — is a value the caller chose.

Path safety

A client value never becomes a path. The physical key is server-generated, and ContentKey's character class excludes . entirely, so no traversal or extension-shaped segment survives validation. DefaultPhysicalPathResolver is the only place an identifier becomes a Path, and it normalizes and re-checks containment after construction rather than trusting the input.

Symlink refusal happens at open time, not only at construction. A parent directory can be replaced between the two, so a check that ran only at path-building time would be a race, not a guard.

Filename handling

OriginalFilenamePolicy strips path separators, NUL, quoting characters, and the colon — the last because on Windows it opens both a drive reference and an NTFS alternate data stream, so a name that keeps it is still path-shaped after the slashes are gone. Control characters and bidirectional overrides are removed, dot runs collapsed, reserved device names guarded, and the result is bounded in UTF-8 bytes.

The sanitized name is display data. It is never used to build a key, and it reaches a header only through ContentDispositionFactory, which restricts the ASCII form and percent-encodes the UTF-8 form.

Content type

The client's Content-Type is stored as a claim. The verified type comes from the verification pipeline, and only the verified type is served. A claimed type that contradicts the content is quarantined rather than corrected.

Scriptable types are never served inline, whatever the caller asked for: serving stored HTML or SVG inline from an upload origin is a stored cross-site scripting primitive. Every download also carries X-Content-Type-Options: nosniff.

Verification precedence

REJECT > QUARANTINE > RETRY > ACCEPT. A verifier that times out or throws is RETRY, never a silent pass, and an empty verifier chain answers RETRY rather than accepting. A file becomes publicly readable only after an ACCEPT.

Range safety

The range budget is enforced before content is opened, so a request naming many ranges is rejected without amplifying into storage work. An unsatisfiable range answers 416 with the real length and opens nothing.

Authorization

Every public operation calls the injected FileAccessPolicyPort before any quota reservation or storage mutation, so a denial leaves no record, no reservation, and no staging object. Finalize is authorized as FINALIZE, and management-plane reads as ADMIN_READ. Startup refuses to run a production profile with an allow-all policy.

Each file records its owner: the principal that created it and, when the transport resolved one, its tenant (the tenant subject attribute). The default role policy grants an operation on an existing file only to its owner in the same tenant, so two callers holding the same role cannot read, download, finalize, delete, copy or move each other's files. An admin role does not bypass this — acting on another caller's file is what the audited management plane is for. A file created before ownership was recorded (migration V5) has no owner and is reachable only through the management plane. Anonymous read, when enabled, publishes every file and skips the owner check.

Delegation

X-Accel-Redirect is emitted only after authorization and the READY gate, and only for a full, unconditional response. The internal prefix must be an internal Nginx location; the front proxy also strips any client-supplied delegation header so a caller cannot name an internal object.

Telemetry

No metric label, span attribute, or audit record carries a file id, upload id, filename, path, or user id. Where correlation is needed the value is a keyed HMAC fingerprint — keyed because the identifier space is enumerable and an unkeyed digest of it is reversible by brute force.

Ambiguous failures

A failure whose operation may already have taken effect is reported as ambiguous and is never retryable. On a network filesystem a lost response is indistinguishable from a rejection at the socket level, so anything not provably safe is treated as ambiguous and sent to reconciliation.