Files
clean-architecture-backend-…/docs/upgrade/2026-11-round9-public-surface.md
T
DongHyeonka db81994490 fix(security)!: 공개 경로 스냅숏이 profile 덮어쓰기와 모듈 chain의 permitAll까지 고정한다
문제: 공개 경로 스냅숏(publicPathSnapshotTest)은 config/security.yml의
기본값 한 줄만 읽었다. 문서(docs/build.md, gates.md 「공개 경로·보안 체인」)는
보안 체인 전체를 지킨다고 했다. 그래서 둘이 검사를 지나갔다.
- application-local.yml이 public-paths를 /api/healthcheck로 덮는다.
- web-notification의 callback chain이 /internal/notification/callbacks/**를
  anyRequest().permitAll()로 연다. actuator chain의 health·info·prometheus도
  같다.
docs/build.md는 지운 PublicPathSnapshotPlugin.java와 없는
updatePublicPathSnapshot 태스크를 승인 방법으로 적었다.

관리 포트도 문서와 compose가 갈렸다. 관리 포트가 컨테이너 loopback에 묶인
뒤(MANAGEMENT_SERVER_ADDRESS 기본 127.0.0.1) compose.yaml·dev lane의
127.0.0.1:9001 publish는 아무것도 답하지 않는 줄이 됐고, service-runtime
README·Dockerfile은 Kubernetes 프로브가 닿는다고 적었다. dev lane은 원격
JMX(9999)를 인증·TLS 없이, jmxremote.host 없이 열었다(주석은 「localhost
only」).

고른 방법:
- 스냅숏에 두 절을 더한다. profile 파일이 public-paths를 리터럴로 덮으면
  그 값, 모든 leaf 운영 코드에서 Spring Security를 import한 파일의
  permitAll·securityMatcher 문장(파일 경로와 함께, 정렬). 그 소스와 baseline을
  lane 입력으로 선언해 캐시가 변경을 놓치지 않게 했다.
- 기동한 SecurityFilterChain의 matcher를 reflection으로 읽는 안은 버렸다.
  matcher가 Spring의 private 필드에 있어 버전마다 깨진다. 문장 글자만 보므로
  상수로 만든 matcher의 값은 못 본다. 그 한계를 docs/build.md에 적었다.
- 관리 포트 publish 줄과 dev lane JMX를 지웠다. 컨테이너 안에서 읽는 명령
  (docker compose exec app wget …, jcmd)을 주석에 적었다. Kubernetes는
  MANAGEMENT_SERVER_ADDRESS를 바꾸거나 sidecar로 읽어야 한다고
  service-runtime README·Dockerfile·docs/build.md에 적었다.

위험·한계: 파생 서비스가 자기 chain이나 profile 덮어쓰기를 두었다면 merge 뒤
스냅숏이 실패한다. 읽고 승인하면 된다(upgrade 안내 1). dev lane에서 원격
JMX로 보던 사람은 jcmd로 바꾼다(안내 4).

검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10에 permitAll chain을 더한 탐침 트리에서 기존
  publicPathSnapshotTest가 통과했다(rc=0) — 틈이 있다.
- GREEN: spotlessApply 뒤 :app-bootstrap:test --tests '*PublicPathSnapshotTest'
  (새 렌더링 시험 둘), :app-bootstrap:publicPathSnapshotTest,
  repositoryContractTest, spotlessCheck, :verifyComposeProfiles(18 lane) —
  67건 실패 0, skip 1, rc=0.
- 변이: 새 스냅숏을 커밋한 트리에서 callback chain의 securityMatcher를
  "/internal/**"로 넓히면 publicPathSnapshotTest가 실패한다.

BREAKING CHANGE: 공개 경로 스냅숏이 profile 덮어쓰기와 모든 모듈의
permitAll·securityMatcher 문장을 본다. compose가 관리 포트 9001과 dev lane
JMX 9999를 publish하지 않는다. 할 일은
docs/upgrade/2026-11-round9-public-surface.md.
2026-11-13 03:47:30 +09:00

3.0 KiB

업그레이드 안내 — 2026-11 공개 경로 스냅숏과 관리 포트

  • 범위: 공개 경로 스냅숏(docs/security/public-paths-snapshot.txt)이 보는 범위를 넓힌 변경과, compose가 관리 포트·JMX를 publish하던 줄을 지운 변경. 앱이 여는 경로와 기본 설정은 바뀌지 않았다.
  • 근거: 2026-11-12 전체 리뷰(docs/reviews/2026-11-12-round9-review/)의 공개 경로·관리 포트 발견

1. 누가 읽나

이 템플릿을 upstream remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 자기 모듈에 Spring Security filter chain을 둔 서비스, profile 파일에서 app.security.public-paths를 덮은 서비스, Kubernetes에 배포하는 서비스, dev compose lane으로 JVM을 원격 JMX로 보던 사람이다.

2. 할 일

# 할 일 안 하면 해당 서비스
1 merge 뒤 ./gradlew verifyPublicPathSnapshot을 돌린다. 실패하면 스냅숏에 새로 든 두 절(profile이 덮는 값, filter chain의 permitAll·securityMatcher 문장)을 읽고, 의도한 공개면 ./gradlew verifyPublicPathSnapshot -PapprovePublicPathChange로 다시 쓴 파일을 보안 리뷰와 함께 커밋한다 mainCheck·releaseCheck의 :app-bootstrap:publicPathSnapshotTest가 실패한다 자기 chain이나 profile 덮어쓰기가 있는 서비스
2 Kubernetes 배포는 MANAGEMENT_SERVER_ADDRESS를 pod IP에서 닿는 주소(예: 0.0.0.0과 NetworkPolicy)로 두거나 같은 pod의 sidecar로 읽는다. 기본값 127.0.0.1은 2026-11-12 main 병합(관리 포트 loopback 고정)부터다 kubelet 프로브가 관리 포트에 닿지 않아 liveness 실패로 재시작하고 readiness가 오지 않는다. Prometheus도 못 읽는다 Kubernetes 배포
3 compose에서 관리 포트를 호스트로 읽던 명령(curl localhost:9001/...)을 docker compose exec app wget -qO- http://localhost:9001/actuator/health로 바꾼다 호스트 포트가 없어 연결이 거절된다. 지운 publish 줄도 컨테이너 loopback에 닿지 않아 원래 아무것도 답하지 않았다 compose로 띄우는 사람
4 dev lane에서 원격 JMX(9999) 대신 docker compose exec app jcmd 1 <명령>(VM.flags, Thread.print, JFR.start)을 쓴다 9999 연결이 거절된다 dev lane으로 JVM을 보던 사람

3. 바뀐 것

  • 스냅숏은 세 절이다: 기본 공개 경로(config/security.yml), profile이 덮는 값(application-<profile>.yml), 모든 leaf 운영 코드의 permitAll·securityMatcher 문장. 알림 callback chain과 actuator chain이 셋째 절에 든다.
  • 스냅숏이 못 보는 것은 운영자가 배포 env(SECURITY_PUBLIC_PATHS)로 준 값과, matcher를 상수나 변수로 다른 줄에서 만든 경우의 그 값이다. 그런 변경은 리뷰가 본다(docs/build.md 「verifyPublicPathSnapshot」).
  • dev lane의 원격 JMX는 인증·TLS 없이 열려 있었고 jmxremote.host가 없어 모든 인터페이스에 묶였다. 그래서 지웠다.