12 KiB
12 KiB
Keycloak branch-note consistency 적용 상태
일자: 2026-07-18
범위: Keycloak 관련 branch-note 38개
상태: COMPLETE
원본 리뷰: docs/superpowers/specs/2026-07-18-keycloak-branch-note-consistency-report.md
1. Summary
- 38개 문서를 4개 비중복 lane으로
READ_FULL처리했다. - 36개 문서를 수정했고, 2개 문서는 리뷰 finding과 직접 관련된 변경이 없어 본문을 유지했다.
- adversarial review의 60개 finding을 모두 판정했다.
KEEP 21 + DOWNGRADE 27의 retained 48건은 반영했고,REJECT 12는 독립 결함으로 재도입하지 않았다. REJECT중 다른 retained finding과 같은 원인을 공유하거나 active 문구 정리가 필요했던 항목은 대표 owner 수정에 통합했다.- 후속 의미 재감사 20건은
Ready, blocking 0, should-fix 0으로 종료됐다.
2. Evidence Matrix
| Path | Status | Evidence | Application |
|---|---|---|---|
raw/branch-notes/experiment-nplus1-highlight-feed.md |
READ_FULL | lines 1-326 | MODIFIED — branch-note 필수 구조 보강 |
raw/branch-notes/feature-authentication-authorization-contract.md |
READ_FULL | lines 1-341 | MODIFIED — raw role / authority 경계 정렬 |
raw/branch-notes/feature-boundary-validation-mapping-contract.md |
READ_FULL | lines 1-407 | NO_CHANGE — 적용 대상 finding 없음 |
raw/branch-notes/feature-keycloak-account-linking-spa-ux.md |
READ_FULL | lines 1-228 | MODIFIED — linking owner 직접 참조와 UX 책임 분리 |
raw/branch-notes/feature-keycloak-account-linking-sub-vs-email.md |
READ_FULL | lines 1-279 | MODIFIED — persistent federation key 단일 owner |
raw/branch-notes/feature-keycloak-bff-vs-spa-direct.md |
READ_FULL | lines 1-274 | MODIFIED — SPA/TMB 조건과 stale risk 정리 |
raw/branch-notes/feature-keycloak-docker-compose-stack.md |
READ_FULL | lines 1-286 | MODIFIED — issuer/JWKS profile owner 위임과 Compose wiring 분리 |
raw/branch-notes/feature-keycloak-edge-forwardauth-google-federation.md |
READ_FULL | lines 1-323 | MODIFIED — P1B header-only trust 정렬 |
raw/branch-notes/feature-keycloak-edge-forwardauth-no-google.md |
READ_FULL | lines 1-316 | MODIFIED — ingress/auth-service 선택축과 cookie custody 구분 |
raw/branch-notes/feature-keycloak-federation-spa-zero-change.md |
READ_FULL | lines 1-193 | MODIFIED — backend validation 실제 owner 직접 참조 |
raw/branch-notes/feature-keycloak-first-broker-login-flow.md |
READ_FULL | lines 1-263 | MODIFIED — silent-link 방지와 custom SPI variant 분리 |
raw/branch-notes/feature-keycloak-google-claim-attribute-mapping.md |
READ_FULL | lines 1-238 | MODIFIED — IdP sync owner와 role freshness owner 분리 |
raw/branch-notes/feature-keycloak-google-redirect-uri-policy.md |
READ_FULL | lines 1-262 | MODIFIED — basic scope 예외·JS origins·decision ref 정렬 |
raw/branch-notes/feature-keycloak-header-spoofing-defense.md |
READ_FULL | lines 1-255 | NO_CHANGE — 적용 대상 finding 없음 |
raw/branch-notes/feature-keycloak-https-termination-caddy-nginx.md |
READ_FULL | lines 1-284 | MODIFIED — HSTS explicit configuration 경계 |
raw/branch-notes/feature-keycloak-idp-brokering-google-client.md |
READ_FULL | lines 1-251 | MODIFIED — server-side brokering JS origins owner 참조 |
raw/branch-notes/feature-keycloak-idp-mappers-claim-to-role.md |
READ_FULL | lines 1-153 | MODIFIED — mapper-level override와 linking owner 위임 |
raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation.md |
READ_FULL | lines 1-467 | MODIFIED — foreign detail을 owner pointer로 축소 |
raw/branch-notes/feature-keycloak-internal-spa-direct-no-google.md |
READ_FULL | lines 1-416 | MODIFIED — token custody/audience owner 직접 참조 |
raw/branch-notes/feature-keycloak-iss-claim-hostname-mismatch.md |
READ_FULL | lines 1-284 | MODIFIED — public issuer/internal JWKS profile owner |
raw/branch-notes/feature-keycloak-nginx-auth-request-integration.md |
READ_FULL | lines 1-306 | MODIFIED — auth_request/proxy body forwarding 층위 구분 |
raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow.md |
READ_FULL | lines 1-275 | MODIFIED — local JWT validation 용어와 decision ref 정렬 |
raw/branch-notes/feature-keycloak-patterns.md |
READ_FULL | lines 1-223 | MODIFIED — superseded naming과 hub 필수 구조 보강 |
raw/branch-notes/feature-keycloak-pkce-flow-stages.md |
READ_FULL | lines 1-188 | MODIFIED — target UI label과 필수 구조 보강 |
raw/branch-notes/feature-keycloak-public-domain-tunneling.md |
READ_FULL | lines 1-220 | MODIFIED — provider selection/operational profile owner 분리 |
raw/branch-notes/feature-keycloak-realm-client-export.md |
READ_FULL | lines 1-239 | MODIFIED — import wiring 위임과 credential 검증 상태 정리 |
raw/branch-notes/feature-keycloak-refresh-rotation-and-logout.md |
READ_FULL | lines 1-255 | MODIFIED — 실행 관찰 owner로 범위 축소 |
raw/branch-notes/feature-keycloak-refresh-token-rotation.md |
READ_FULL | lines 1-283 | MODIFIED — policy owner와 Max Reuse 검증 계약 정리 |
raw/branch-notes/feature-keycloak-reverse-proxy-headers.md |
READ_FULL | lines 1-297 | MODIFIED — Caddy prefix 보존과 하위 owner 경계 |
raw/branch-notes/feature-keycloak-single-ec2-google-federation.md |
READ_FULL | lines 1-349 | MODIFIED — integration invariant와 child detail owner 분리 |
raw/branch-notes/feature-keycloak-single-ec2-no-google.md |
READ_FULL | lines 1-344 | MODIFIED — audience owner, library-first, pure-SPA 기준선 |
raw/branch-notes/feature-keycloak-spa-token-storage-tradeoff.md |
READ_FULL | lines 1-258 | MODIFIED — pure SPA memory-only와 TMB/BFF variant 분리 |
raw/branch-notes/feature-keycloak-spring-rs-audience-validator.md |
READ_FULL | lines 1-270 | MODIFIED — expected audience backend-client-id 단일화 |
raw/branch-notes/feature-keycloak-spring-rs-role-mapping.md |
READ_FULL | lines 1-216 | MODIFIED — RBAC 범위와 audience owner 참조 분리 |
raw/branch-notes/feature-keycloak-three-leg-trust-chain.md |
READ_FULL | lines 1-229 | MODIFIED — OIDC nonce 의무와 제품 동작 검증 상태 분리 |
raw/branch-notes/feature-keycloak-traefik-forwardauth-alternative.md |
READ_FULL | lines 1-238 | MODIFIED — AP4 분류와 redirect 생성/전달 주체 분리 |
raw/branch-notes/feature-keycloak-vanilla-js-spa-pkce.md |
READ_FULL | lines 1-259 | MODIFIED — library-first, absolute/runtime endpoint, explicit memory store |
raw/branch-notes/feature-security-operational-baseline.md |
READ_FULL | lines 1-416 | MODIFIED — historical/current-known/needs-confirmation 분리 |
3. Finding Disposition
상태 의미:
APPLIED: retained finding을 owner-first 기준으로 반영.CONSOLIDATED: adversarialREJECT를 독립 결함으로 적용하지 않고 대표 retained finding 또는 active 문구 정리에 통합.REJECTED_NO_CHANGE: adversarial 반증을 수용해 별도 수정하지 않음.
| Finding | Adversarial | Application |
|---|---|---|
| L1-F01 | KEEP | APPLIED |
| L1-F02 | DOWNGRADE | APPLIED |
| L1-F03 | DOWNGRADE | APPLIED |
| L1-F04 | DOWNGRADE | APPLIED |
| L1-F05 | DOWNGRADE | APPLIED |
| L1-F06 | REJECT | REJECTED_NO_CHANGE |
| L1-F07 | DOWNGRADE | APPLIED |
| L1-F08 | KEEP | APPLIED |
| L1-F09 | KEEP | APPLIED |
| L1-F10 | KEEP | APPLIED |
| L1-F11 | DOWNGRADE | APPLIED |
| L1-F12 | DOWNGRADE | APPLIED |
| L1-F13 | REJECT | REJECTED_NO_CHANGE |
| L1-F14 | REJECT | CONSOLIDATED — L4-F08 audience owner/value 정리 |
| L2-F01 | REJECT | CONSOLIDATED — unsupported CVE 문구의 active 영향만 축소 |
| L2-F02 | KEEP | APPLIED |
| L2-F03 | DOWNGRADE | APPLIED |
| L2-F04 | KEEP | APPLIED |
| L2-F05 | DOWNGRADE | APPLIED |
| L2-F06 | KEEP | APPLIED |
| L2-F07 | KEEP | APPLIED |
| L2-F08 | KEEP | APPLIED |
| L2-F09 | REJECT | CONSOLIDATED — L4-F04 token custody 경계에 통합 |
| L3-F01 | DOWNGRADE | APPLIED |
| L3-F02 | REJECT | REJECTED_NO_CHANGE |
| L3-F03 | KEEP | APPLIED |
| L3-F04 | KEEP | APPLIED |
| L3-F05 | DOWNGRADE | APPLIED |
| L3-F06 | REJECT | REJECTED_NO_CHANGE |
| L3-F07 | KEEP | APPLIED |
| L3-F08 | KEEP | APPLIED |
| L3-F09 | DOWNGRADE | APPLIED |
| L3-F10 | DOWNGRADE | APPLIED |
| L3-F11 | DOWNGRADE | APPLIED |
| L3-F12 | DOWNGRADE | APPLIED |
| L3-F13 | DOWNGRADE | APPLIED |
| L3-F14 | KEEP | APPLIED |
| L3-F15 | KEEP | APPLIED |
| L3-F16 | DOWNGRADE | APPLIED |
| L4-F01 | REJECT | CONSOLIDATED — L1-F08 issuer/network profile에 통합 |
| L4-F02 | KEEP | APPLIED |
| L4-F03 | REJECT | CONSOLIDATED — active manual-first 문구를 historical/superseded 처리 |
| L4-F04 | KEEP | APPLIED |
| L4-F05 | DOWNGRADE | APPLIED |
| L4-F06 | DOWNGRADE | APPLIED |
| L4-F07 | DOWNGRADE | APPLIED |
| L4-F08 | KEEP | APPLIED |
| L4-F09 | DOWNGRADE | APPLIED |
| L4-F10 | DOWNGRADE | APPLIED |
| L4-F11 | REJECT | REJECTED_NO_CHANGE |
| L4-F12 | KEEP | APPLIED |
| L4-F13 | REJECT | REJECTED_NO_CHANGE |
| L4-F14 | KEEP | APPLIED |
| L4-F15 | DOWNGRADE | APPLIED |
| L4-F16 | KEEP | APPLIED |
| L4-F17 | DOWNGRADE | APPLIED |
| L4-F18 | REJECT | REJECTED_NO_CHANGE |
| L4-F19 | DOWNGRADE | APPLIED |
| L4-F20 | DOWNGRADE | APPLIED |
| L4-F21 | DOWNGRADE | APPLIED |
4. Owner Decisions Applied
- Audience는 backend API용
backend-client-id하나를 owner 값으로 사용한다. - Docker dev는 public issuer identity와 bridge-container JWKS retrieval address를 분리하며, exact profile은 issuer mismatch branch D6이 소유한다.
- P1A/P1B backend trust는 header-only이고 Google federation 여부만 다르다.
- Google persistent federation key는
(IdP alias, sub)owner 하나로 수거한다. email_verified=falsecore 정책은 silent auto-link 차단이며, hard-reject는 구현된 custom SPI variant가 있을 때만 별도 채택한다.- Pure SPA는 access/refresh token 모두 memory-only이고 reload 시 재인증한다. HttpOnly refresh cookie는 TMB/BFF variant다.
- Stable Google callback은 named tunnel과 managed custom domain을 사용하고 quick tunnel은 임시 dev 용도로 제한한다.
- Caddy method B는
/keycloakprefix를 보존한다. - 실제 SPA 구현 순서는
oidc-client-ts우선이며 manual PKCE는 비교 학습 단계다. - Traefik + oauth2-proxy는 edge ForwardAuth AP4이며, SPA 요청 URL은 static-only nginx topology에 맞춘 runtime/absolute endpoint를 사용한다.
5. Verification
| Gate | Result |
|---|---|
| Scope partition | 38 = 10 + 10 + 10 + 8, duplicate 0, missing 0 |
| Full-read coverage | 38/38 READ_FULL |
| Structure lint | 38/38 PASS |
| Deterministic consistency, Keycloak scope | 0 findings |
| Deterministic consistency, whole repository | 136 pre-existing out-of-scope findings (BARE_OWNER_REF 74, BARE_DECISION_REF 62) |
| Link validation | 38/38 per-file lint PASS; Keycloak scope broken link 0 |
| Semantic audit round 1 | Not-ready: blocking 1, should-fix 3 |
| Semantic audit round 2 | Ready: blocking 0, should-fix 0; 20/20 processed |
| Semantic round 2 classifications | original candidates: CONSISTENT 11, NOT_AN_EDGE 9; current actual/replacement edges 14/14 CONSISTENT |
git diff --check |
PASS |
실행한 대표 명령:
python3 .claude/hooks/wiki_structure_lint.py --file <각 scope 문서>
python3 .claude/hooks/wiki_consistency_check.py --all
python3 .claude/hooks/wiki_structure_lint.py --all --links-only
git diff --check -- <scope 문서>
6. Residual Risk
문서 간 의미 모순은 이번 scope에서 닫혔다. 다음 항목은 문서에 planned 또는 needs-confirmation으로 유지했다.
- target Keycloak release의 account unlink guard와 Admin UI label 확인
- Docker Linux host-gateway JWKS E2E 및 key rotation
- realm export의 credential/secret 포함 범위
email_verified=false와 First Broker Login 실제 flow E2E- audience mapper가 발급 token의
aud에backend-client-id를 넣는지 확인 - nonce wire trace, Traefik redirect 전달, Caddy route, tunnel callback E2E
- Max Reuse 0/1과 refresh token reuse 영향 측정
- pinned SPA library의 storage/renew 동작 확인
- Phase C2 security baseline의 실제 code/test 재확인
저장소 전체 consistency 136건과 links-only 29건은 Keycloak scope 밖의 기존 항목이며 이번 적용에서 수정하지 않았다.
7. Stats
found: 60
processed: 60
dropped: 0
modified_files: 36
no_change_files: 2
semantic_candidates: 20
semantic_ready: true