문제: infra/ 43개 중 12개는 코드·테스트·workflow·스크립트 어디서도
읽지 않는다(httpclient·jpa·messaging·notification의 toxiproxy compose와
README). nginx 설정, Kubernetes PVC 인증 job, DB 역할 SQL 셋은 운영
인프라라 개발 repo에 둘 것이 아니다(소유자 결정 2026-11-07). release.yml
의 fileserver-pvc-certification job은 그 매니페스트 문자열만 grep했다.
고른 방법:
- 15개를 지운다.
- 운영 조건만 그 기능 문서에 한국어로 남긴다.
docs/fileserver/operations.md 「운영 환경이 지켜야 할 조건」(nginx
internal location·alias·X-Accel-Redirect 헤더 제거·스트리밍, PVC
ReadWriteOnce·fsGroup), storage-certification.md(인증 절차),
docs/jpa/security.md 「역할과 권한」·「서버 설정」(역할 SQL과
jpa/postgres README 내용), docs/messaging/security.md(인증서 SAN).
httpclient TLS README 내용은 docs/httpclient/security.md에 이미 있다.
- release.yml job과 needs 줄, fileserver-pr.yml·pr-adapters.yml의 지운
경로 필터를 지운다.
- fileserver 지원 표의 "Kubernetes ReadWriteOnce PVC — Limited" 행은
근거 job이 없어져 「주장하지 않음」으로 옮긴다.
버린 대안: 인프라 파일을 project-infra로 옮기기(설계 Q6). 그 repo는
특정 프로젝트용이라 범용 템플릿 파일을 받을 자리가 없다.
위험·한계: 지원 표에서 PVC 주장이 빠진다. 파생 서비스가 그 파일을
배포에 썼다면 병합이 지운다(B-50). 클러스터 인증은 이제 배포하는 쪽이
문서 절차로 한다.
검증(desktop, 트리 749a3328, ~/t1-layout-logs/):
- :composition:fileserver-platform:check :app-bootstrap:check
:app-bootstrap:documentContractTest rc=0 (repositoryContractTest,
FileserverDocumentationCoverageTest 실행)
- :verifyStrictLaneStages --dry-run rc=0
- scripts/verify-compose-profile-contracts.sh rc=0 (18 lane)
- check-work-docs.py, 상대 링크 검사 rc=0
Refs: design-docs repo-structure/01-backend-layout.md 4.4, 6.3
BREAKING CHANGE: infra/fileserver/nginx, infra/fileserver/kubernetes, infra/jpa, infra/httpclient, infra/messaging, infra/notification/toxiproxy와 release.yml fileserver-pvc-certification job이 없어진다. docs/upgrade/2026-11-maturity-review.md B-50.
5.6 KiB
Security
Design §36. Credential separation, privilege verification, and what never leaves the process.
Three credentials
| Role | May |
|---|---|
app_migration |
own the schema, apply migrations (DDL) |
app_runtime |
select, insert, update, delete (DML only) |
app_admin |
J4 operations — COPY, backfill, maintenance |
The separation is what makes "Flyway owns schema change" enforceable rather than aspirational. If the application's own credential cannot execute DDL, then no code path, no library, and no injected statement can alter the schema at runtime, regardless of what the application intended.
역할과 권한 — 운영 DB가 갖춰야 할 것
이 repo는 역할을 만드는 SQL 파일을 두지 않는다(2026-11-07 소유자 결정. 운영 DB 준비는 배포하는 쪽의
일이다). 운영 DB는 아래 조건을 지켜야 한다. 기동 때 PostgreSqlRuntimeRoleVerifier가 그중 런타임 역할의
CREATE 권한과 search_path를 다시 본다.
- 애플리케이션 schema(예:
app)는 migration 역할이 소유한다. 런타임 역할이 소유하지 않는다. PUBLIC에서 데이터베이스 권한 전체와publicschema의CREATE를 거둔다. PostgreSQL 15 전에는PUBLIC이publicschema에CREATE를 가져, 권한 없는 역할이search_path로 진짜 객체를 가리는 객체를 만들 수 있었다.- 런타임 역할에는
CONNECT, 애플리케이션 schema의USAGE, 그 schema 테이블의SELECT·INSERT·UPDATE·DELETE, sequence의USAGE·SELECT만 준다. - migration 역할이 앞으로 만들 테이블·sequence에도 같은 권한이 가도록
ALTER DEFAULT PRIVILEGES를 건다. 빠뜨리면 새 테이블을 더한 첫 배포가 런타임 권한 오류로 실패한다. - 런타임 역할에서 schema와 데이터베이스의
CREATE를 명시적으로 거둔다. 기동 검사가 보는 두 권한이다. - 관리 역할(COPY·backfill·정비용)은 런타임 역할과 같은 행 권한을 갖되 schema를 소유하지 않는다. 요청 경로는 이 역할을 쓰지 않는다.
- 런타임·관리 역할의
search_path를app, pg_catalog처럼 고정한다.
비밀번호는 배포 환경의 비밀 저장소에서 넣는다. repo에 두지 않는다.
서버 설정 — 플랫폼의 보장이 기대는 것
계약 테스트는 자기 컨테이너를 띄우므로(PostgreSqlContainerFactory) 이 설정이 필요 없다. 운영 DB에서
플랫폼의 보장이 성립하려면 아래 설정이 있어야 한다. 값은 출발점이다. 가장 느린 정상 쿼리를 재 보고 정한다.
| 설정 | 출발 값 | 왜 필요한가 |
|---|---|---|
statement_timeout |
30s |
트랜잭션 안의 문장 하나가 요청보다 오래 사는 것을 막는 마지막 상한 |
idle_in_transaction_session_timeout |
60s |
열어 둔 채 쉬는 트랜잭션이 잠금과 snapshot을 붙잡아 쓰기와 vacuum을 막는 시간을 줄인다 |
lock_timeout |
10s |
PostgreSqlLockOptions의 요청별 잠금 상한 아래에 까는 바닥 |
max_connections |
배포 수에 맞춤 | 모든 인스턴스의 pool 합과, REQUIRES_NEW가 두 번째 연결을 잡는 경우를 함께 견딘다 |
default_transaction_isolation |
read committed |
바꾸면 격리 수준을 고르지 않은 모든 트랜잭션이 조용히 달라진다 |
확장(extension)은 필요 없다. JSONB, 배열, 범위, SKIP LOCKED, ON CONFLICT는 모두 PostgreSQL 본체 기능이다.
Startup verification
PostgreSqlRuntimeRoleVerifier asks the server what the connection can do:
select current_user,
current_setting('search_path'),
has_schema_privilege(current_user, current_schema(), 'CREATE'),
has_database_privilege(current_user, current_database(), 'CREATE')
Configuration cannot answer this. Effective privileges come from direct grants, inherited role
memberships, PUBLIC grants, and schema ownership, and no reading of a deployment manifest
reconstructs that combination reliably.
Startup fails when the runtime role is not on the allowlist, or holds CREATE on the schema or the
database.
search_path
SearchPathPolicy is an allowlist. search_path decides which schema an unqualified name resolves
to, so a writable untrusted schema on it — classically public, where CREATE was granted broadly
before PostgreSQL 15 — lets a planted table, function, or operator shadow the real one, and the
application executes it without noticing. $user is exempt: only the connected role owns it.
Refusing the runtime role CREATE closes the same route from the other side.
What never leaves the process
- SQL parameter values, entity ids, tenant ids, and PII: not in exception messages, not in metric
tags, not in logs.
JpaFailureContextcomposes messages from bounded values only. - Constraint names reach the application as registered
ConstraintCodes; an unregistered physical name maps to a bounded unknown code rather than being passed through. - Cursors are HMAC-signed. An unsigned cursor is client-controlled ordering state.
- The actuator report carries no JDBC URL, username, or SQL.
Injection surfaces, and how each is closed
| Surface | Why it cannot be a parameter | Closed by |
|---|---|---|
| sort field | part of ORDER BY | SafeSortRegistry allowlist |
| JSON path | part of the statement | registered JsonPathName |
| schema name | an identifier | registered SchemaTenantRegistry |
| COPY table | an identifier | registered RegisteredCopyStatement |
Values are always bound. Identifiers are always registered.