문제: `docs/jpa`의 문서 12개가 영어였고 `security.md`도 영어 절이 남아 있었다.
`repository-adaptation.md`는 Spring Boot 버전과 leaf 개수를 복사했다(number 예외).
번역하며 대조하니 지금 코드와 다른 주장이 여럿 있었다.
고친 것:
- 13개를 번역했다. 코드·명령·경로·표 구조는 그대로다. `support-matrix.md`의 DB 표와
gate 표는 `JpaReleaseRendering`이 읽는 모양(`| PostgreSQL 17 | Stable |`,
`` | `osiv-disabled` | gate | ``)을 그대로 둔다. 절 번호(§1~§5)는 코드가 인용해 그대로다.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Who may change the schema", "Bound the
lock wait", "Concurrent index builds", "An invalid index exists", "Associations")은
한국어 제목 뒤 괄호에 영어를 남겼다.
- 코드에 맞춘 주장:
- support-matrix: 없는 `JpaPlatformAutoConfiguration.capabilities()` →
`JpaPlatformReport.platformCapabilities()`. COPY 수준은 보고대로 Advanced.
- repository-adaptation: leaf 개수·Boot 버전 → registry와 `libs.versions.toml`,
`src/testkit` → `src/testFixtures`, outbox relay `app-bootstrap` →
`composition:outbox-relay`, 「build-logic이 없다」 → `src/build-logic` convention
plugin, 없는 `runtime_memberships`, 없는 `JpaDataSourceSettings`, 여러 major 선택은
`JpaPlatformContractSupport.start()`가 거부한다(`StablePostgreSqlMatrixContractTest`만
여러 개를 받는다), 이미지는 `container-images.properties`의 digest.
- experimental-promotion-checklist: 결과 이름은 지운 gate의 것임을 밝혔다.
- 테스트: `JpaDocumentationContractTest`가 H2 단락의 「운영 보장이 아니」·「PostgreSQL 계약
증거」와 「알려진 빈틈」을 본다. `PoolLaneClaimTest`는 한국어 금지 문구 셋을 더 본다.
고친 두 테스트의 영어 `@DisplayName`은 AGENTS.md 규칙대로 한국어로 바꿨다.
- 예외 목록에서 JPA language 줄 12개와 number 줄 2개를 지웠다.
버린 대안: H2 단락의 영어 문구를 괄호로 남겨 단언을 그대로 두기. 독자가 읽는 것은
한국어 문장이므로 단언도 그 문장을 붙잡아야 한다.
위험·한계: `PoolLaneClaimTest`의 한국어 금지 문구는 지금 문서를 기준으로 고른 것이라,
다른 말로 쓴 인증 주장은 잡지 못한다. 영어 문구 검사는 그대로 남아 있다.
검증: 최종 트리 기준(첫 커밋 본문 참고).
검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:persistence-jpa:check` rc=0(666개 실패 0. `JpaDocumentationContractTest` 4,
`JpaReleaseRenderingTest` 13, `PoolLaneClaimTest` 3), `:mainCheck` rc=0, `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `JpaDocumentationContractTest`의 H2 단락·알려진 빈틈 2개가 실패한다.
`PoolLaneClaimTest`는 금지 문구를 더한 것이라 옛 영어 문서에서도 통과한다(RED 없음).
96 lines
5.9 KiB
Markdown
96 lines
5.9 KiB
Markdown
# 보안
|
|
|
|
설계서 §36. 자격 증명 분리, 권한 검증, 프로세스 밖으로 절대 나가지 않는 것.
|
|
|
|
## 자격 증명 셋
|
|
|
|
| 역할 | 할 수 있는 것 |
|
|
|---|---|
|
|
| `app_migration` | schema 소유, 마이그레이션 적용(DDL) |
|
|
| `app_runtime` | select, insert, update, delete(DML만) |
|
|
| `app_admin` | J4 작업 — COPY, backfill, 정비 |
|
|
|
|
이 분리가 「schema 변경은 Flyway가 가진다」를 바람이 아니라 강제할 수 있는 규칙으로 만든다. 애플리케이션 자신의 자격 증명이
|
|
DDL을 실행할 수 없으면, 애플리케이션이 무엇을 의도했든 어떤 코드 경로도, 라이브러리도, 주입된 문장도 실행 중에 schema를 바꿀
|
|
수 없다.
|
|
|
|
### 역할과 권한 — 운영 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 본체 기능이다.
|
|
|
|
## 기동 검증
|
|
|
|
`PostgreSqlRuntimeRoleVerifier`가 연결이 무엇을 할 수 있는지 *서버*에 묻는다.
|
|
|
|
```sql
|
|
select current_user,
|
|
current_setting('search_path'),
|
|
has_schema_privilege(current_user, current_schema(), 'CREATE'),
|
|
has_database_privilege(current_user, current_database(), 'CREATE')
|
|
```
|
|
|
|
설정으로는 이것에 답할 수 없다. 실제 권한은 직접 grant, 물려받은 역할 membership, `PUBLIC` grant, schema 소유에서 오고, 배포
|
|
manifest를 읽어서는 그 조합을 믿을 만하게 되살릴 수 없다.
|
|
|
|
런타임 역할이 허용 목록에 없거나, schema나 데이터베이스에 `CREATE`를 가지면 기동이 실패한다.
|
|
|
|
## search_path
|
|
|
|
`SearchPathPolicy`는 허용 목록이다. `search_path`는 이름만 쓴 객체가 어느 schema로 풀리는지 정한다. 그래서 그 위에 쓸 수 있는
|
|
믿지 못할 schema가 있으면(전형적으로 `public`. PostgreSQL 15 전에는 `CREATE`가 넓게 주어졌다) 심어 둔 테이블, 함수, 연산자가
|
|
진짜 것을 가리고, 애플리케이션은 알아채지 못한 채 그것을 실행한다. `$user`는 예외다. 연결한 역할만 그것을 소유한다.
|
|
|
|
런타임 역할에게 `CREATE`를 주지 않는 것이 같은 길을 반대쪽에서 막는다.
|
|
|
|
## 프로세스 밖으로 절대 나가지 않는 것
|
|
|
|
- SQL 파라미터 값, entity id, tenant id, PII. 예외 메시지에도, 메트릭 태그에도, 로그에도 없다. `JpaFailureContext`는 상한 있는
|
|
값으로만 메시지를 만든다.
|
|
- 제약 이름은 등록된 `ConstraintCode`로 애플리케이션에 닿는다. 등록되지 않은 물리 이름은 그대로 넘기지 않고 상한 있는 unknown
|
|
코드로 매핑한다.
|
|
- cursor는 HMAC으로 서명한다. 서명 없는 cursor는 클라이언트가 다루는 정렬 상태다.
|
|
- actuator 보고에는 JDBC URL, 사용자 이름, SQL이 없다.
|
|
|
|
## 주입 표면과 각각을 막는 법
|
|
|
|
| 표면 | 파라미터가 될 수 없는 이유 | 막는 것 |
|
|
|---|---|---|
|
|
| 정렬 칸 | ORDER BY의 일부 | `SafeSortRegistry` 허용 목록 |
|
|
| JSON 경로 | 문장의 일부 | 등록한 `JsonPathName` |
|
|
| schema 이름 | 식별자 | 등록한 `SchemaTenantRegistry` |
|
|
| COPY 테이블 | 식별자 | 등록한 `RegisteredCopyStatement` |
|
|
|
|
값은 늘 묶는다. 식별자는 늘 등록한다.
|