문제: `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 없음).
5.9 KiB
보안
설계서 §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를 다시 본다.
- 애플리케이션 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 본체 기능이다.
기동 검증
PostgreSqlRuntimeRoleVerifier가 연결이 무엇을 할 수 있는지 서버에 묻는다.
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 |
값은 늘 묶는다. 식별자는 늘 등록한다.