Files
clean-architecture-backend-…/docs/design/2026-09-19-prod-secret-consumer-alignment.md
T
DongHyeonka 74108497d4 docs(records): 기록과 ADR 맨 위에 한국어 머리 블록을 단다
문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시
없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는
거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다.

고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의
.md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일·
요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄
두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함).
- 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거).
- 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는
  설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」.
  capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」,
  2026-07-20 하네스 설계·계획과 production capability platform 설계는
  「대체됨」이다.
- 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신
  docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다.
docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와
코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록
충돌 가능성을 적었다.

버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이
파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는
안은 폴더와 같은 정보를 두 번 쓰게 한다.

위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지
아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을
끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다
(납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는
아직 머리 블록을 달지 않았다.

검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py
rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
2026-11-07 12:23:32 +09:00

2.9 KiB

기록 · 설계서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 확인 안 함
  • 작성일: 2026-09-19
  • 요약: 운영 기동이 실제로 쓰는 시크릿만 요구하게 맞추는 설계다.
  • 현재 정본: docs/registries/env-keys.yaml

Prod Secret Consumer Alignment

Goal

Close tech-lead H3: production startup must require only secret keys that the shipped runtime actually consumes.

Defect

SecretSourceValidator.REQUIRED_PROD_SECRETS includes three keys with no runtime consumer:

  • APP_SECURITY_JWT_SIGNING_KEY
  • APP_SECURITY_OAUTH_CLIENT_SECRET
  • APP_EXTERNAL_API_KEY

The application is a JWT resource server and verifies tokens through issuer/JWKS discovery; it does not sign JWTs. No shipped OAuth client or generic external API adapter consumes the other two keys.

Requiring unused credentials inflates the deployment secret surface and allows smoke fixtures to hide the mismatch by injecting random values that have no effect.

Decision

Remove all three unused keys from the unconditional prod-secret contract.

Alignment must happen in every contract surface:

  • SecretSourceValidator.REQUIRED_PROD_SECRETS;
  • docs/registries/secrets-classification.yaml;
  • APP_SECURITY_JWT_SIGNING_KEY in docs/registries/env-keys.yaml and .env.example;
  • compose runtime smoke generated-secret injection;
  • SecretSourceValidator tests.

No replacement consumer is invented.

The generic sentinel guard remains: any environment property whose value begins with the local-dev sentinel prefix is still forbidden in prod, independent of whether the key is in the required-secret list.

Verification

  • the three keys have zero non-review references in the repository;
  • secret classification registry remains exactly aligned with REQUIRED_PROD_SECRETS;
  • prod startup succeeds without the three unused keys when actual required secrets are present;
  • missing real required material still fails closed;
  • verifyEnvKeys remains green.

Verified result

  • APP_SECURITY_JWT_SIGNING_KEY, APP_SECURITY_OAUTH_CLIENT_SECRET and APP_EXTERNAL_API_KEY were removed from the unconditional production secret contract because the shipped runtime has no consumer for them;
  • APP_SECURITY_JWT_SIGNING_KEY was removed from .env.example and env-keys.yaml;
  • all three were removed from secrets-classification.yaml;
  • compose runtime smoke no longer generates dummy values for those keys;
  • the prod sentinel test now exercises the real APP_DATASOURCE_PASSWORD requirement;
  • SecretSourceValidatorTest and SecretsClassificationRegistryTest: PASS;
  • verifyEnvKeys: PASS with no orphan warning;
  • smoke script syntax: PASS;
  • app-bootstrap Spotless, full test and architectureTest: PASS;
  • git diff --check: PASS.