Files
clean-architecture-backend-…/docs/jpa/security.md
T
DongHyeonka b1cda0307b docs(jpa): JPA 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: `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 없음).
2026-11-07 17:56:34 +09:00

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를 다시 본다.

  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가 연결이 무엇을 할 수 있는지 서버에 묻는다.

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

값은 늘 묶는다. 식별자는 늘 등록한다.