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

84 lines
4.3 KiB
Markdown

# 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.