문제: 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.
99 lines
5.6 KiB
Markdown
99 lines
5.6 KiB
Markdown
# 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`를 다시 본다.
|
|
|
|
1. 애플리케이션 schema(예: `app`)는 migration 역할이 소유한다. 런타임 역할이 소유하지 않는다.
|
|
2. `PUBLIC`에서 데이터베이스 권한 전체와 `public` schema의 `CREATE`를 거둔다. PostgreSQL 15 전에는
|
|
`PUBLIC`이 `public` schema에 `CREATE`를 가져, 권한 없는 역할이 `search_path`로 진짜 객체를 가리는
|
|
객체를 만들 수 있었다.
|
|
3. 런타임 역할에는 `CONNECT`, 애플리케이션 schema의 `USAGE`, 그 schema 테이블의
|
|
`SELECT`·`INSERT`·`UPDATE`·`DELETE`, sequence의 `USAGE`·`SELECT`만 준다.
|
|
4. migration 역할이 앞으로 만들 테이블·sequence에도 같은 권한이 가도록 `ALTER DEFAULT PRIVILEGES`를
|
|
건다. 빠뜨리면 새 테이블을 더한 첫 배포가 런타임 권한 오류로 실패한다.
|
|
5. 런타임 역할에서 schema와 데이터베이스의 `CREATE`를 명시적으로 거둔다. 기동 검사가 보는 두 권한이다.
|
|
6. 관리 역할(COPY·backfill·정비용)은 런타임 역할과 같은 행 권한을 갖되 schema를 소유하지 않는다. 요청
|
|
경로는 이 역할을 쓰지 않는다.
|
|
7. 런타임·관리 역할의 `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:
|
|
|
|
```sql
|
|
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. `JpaFailureContext` composes messages from bounded values only.
|
|
- Constraint names reach the application as registered `ConstraintCode`s; 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.
|