From af177de0aa4d403316a51a49f4549f5e498630a9 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 17:18:18 +0900 Subject: [PATCH] =?UTF-8?q?docs(compose):=20Keycloak=20realm=EA=B3=BC=20Re?= =?UTF-8?q?dis=20ACL=20=EC=95=88=EB=82=B4=EB=A5=BC=20=ED=95=9C=EA=B5=AD?= =?UTF-8?q?=EC=96=B4=EB=A1=9C=20=EC=98=AE=EA=B8=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: `compose/keycloak/README.md`와 `compose/redis/acl/README.md`가 영어라 언어 검사 예외에 있다. ACL README의 파일 표에는 폴더에 있는 `sentinel-accounts.acl`이 없다. 고른 방법: 뜻을 그대로 옮긴다. 긴 문단은 목록으로 나눈다. 파일 표에 `sentinel-accounts.acl` 행을 더하고, 지금 이 파일을 `aclfile`로 읽는 compose 파일이 없다고 적는다(`git grep sentinel-accounts`가 이 README 밖에서 0건). 위험·한계: `sentinel-accounts.acl`을 지울지는 정하지 않았다. 검증: `python3 scripts/check-docs.py` rc=0(언어 예외 줄 둘을 지움). --- compose/keycloak/README.md | 54 +++++++--------- compose/redis/acl/README.md | 104 ++++++++++++++++-------------- scripts/check-docs-exceptions.txt | 2 - 3 files changed, 80 insertions(+), 80 deletions(-) diff --git a/compose/keycloak/README.md b/compose/keycloak/README.md index 57266885..c44a9531 100644 --- a/compose/keycloak/README.md +++ b/compose/keycloak/README.md @@ -1,37 +1,33 @@ -# Keycloak realm artifact +# Keycloak realm 파일 -`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in the root `compose.yaml` -and is the same realm every GraphQL qualification lane authenticates against. +루트 `compose.yaml`의 `keycloak` 서비스가 `realms/ca-skeleton-realm.json`을 가져온다(import). 모든 GraphQL +qualification lane이 인증하는 realm도 이 파일이다. -## The client secret is a reference, never a value +## client secret은 값이 아니라 참조다 -The confidential client `ca-skeleton-api` carries `"secret": "${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET}"`. -`entrypoint.sh` reads the value from the Compose secret mounted at -`/run/secrets/keycloak-graphql-smoke-client-secret`, exports it, and execs `kc.sh start-dev ---import-realm`, so the value never reaches Git, a rendered Compose config, a command line, or an -evidence file. A realm file with a working credential in it is a credential in the repository, and -"it is only for smoke tests" is not something a scanner or a fork can tell. +confidential client `ca-skeleton-api`는 `"secret": "${KEYCLOAK_GRAPHQL_SMOKE_CLIENT_SECRET}"`를 가진다. +`entrypoint.sh`가 `/run/secrets/keycloak-graphql-smoke-client-secret`에 마운트된 Compose secret에서 값을 읽어 +export하고, `kc.sh start-dev --import-realm`을 exec한다. 그래서 값이 Git, 렌더링된 Compose 설정, 명령줄, +증거 파일 어디에도 닿지 않는다. 동작하는 자격 증명이 든 realm 파일은 저장소 안의 자격 증명이다. 「smoke +테스트에만 쓴다」는 사정은 스캐너도 fork도 알 수 없다. -## No comment keys in the realm JSON +## realm JSON에 주석 키를 두지 않는다 -Keycloak deserializes this file into `RealmRepresentation` with unknown fields **rejected**, not -ignored. A `"_comment"` key here fails the whole import with `Unrecognized field "_comment"`, the -container exits 1, and the lane fails on Keycloak rather than on anything it was testing. That is -why this rationale lives in Markdown next to the artifact instead of inside it. +Keycloak은 이 파일을 `RealmRepresentation`으로 역직렬화할 때 모르는 필드를 무시하지 않고 **거절한다**. +`"_comment"` 키 하나가 `Unrecognized field "_comment"`로 import 전체를 실패시키고, 컨테이너가 1로 끝나고, +lane은 시험하던 것이 아니라 Keycloak에서 실패한다. 그래서 이 근거를 파일 안이 아니라 옆의 Markdown에 둔다. -## What the realm grants +## realm이 주는 권한 -- realm role `user` — the baseline role the application authorizes ordinary calls on -- client role `ca-skeleton-api:graphql-query` — permission to execute a GraphQL query -- client roles `notification-submit`, `notification-template-publish`, `operation-submit` — the - platform permissions `security.yml` maps them to -- client roles `ROLE_FILE_READ` and `ROLE_FILE_WRITE` — the fileserver's read and write tiers, which - `security.yml` also maps to `file:read` and to `file:upload`, `file:delete`, `file:copy`, - `file:move`; `ROLE_FILE_ADMIN` (`file:admin`) is defined but not granted to the service account, - since the management plane is off by default -- a service account for the client-credentials grant the qualification lane uses -- audience and realm/client role mappers, so the issued token carries what the resource server - validates +- realm role `user`: 애플리케이션이 보통 호출을 허가하는 기본 role +- client role `ca-skeleton-api:graphql-query`: GraphQL query를 실행할 권한 +- client role `notification-submit`, `notification-template-publish`, `operation-submit`: `security.yml`이 + 플랫폼 권한으로 바꾸는 role +- client role `ROLE_FILE_READ`, `ROLE_FILE_WRITE`: 파일 서버의 읽기·쓰기 등급. `security.yml`이 각각 + `file:read`와 `file:upload`·`file:delete`·`file:copy`·`file:move`로 바꾼다. `ROLE_FILE_ADMIN` + (`file:admin`)은 정의만 하고 service account에 주지 않는다. 관리 기능은 기본으로 꺼져 있다 +- qualification lane이 쓰는 client credentials grant용 service account +- audience mapper와 realm·client role mapper. 발급한 토큰에 resource server가 검증하는 값이 실린다 -Standard flow and direct access grants are disabled: the lane authenticates as a service, and an -enabled password grant is a second way in that nothing tests. +standard flow와 direct access grant는 꺼 두었다. lane은 서비스로 인증하고, 켜 둔 password grant는 아무도 +시험하지 않는 두 번째 입구가 된다. diff --git a/compose/redis/acl/README.md b/compose/redis/acl/README.md index adfc2118..01a388bc 100644 --- a/compose/redis/acl/README.md +++ b/compose/redis/acl/README.md @@ -1,58 +1,64 @@ -# ACL accounts — test fixtures, not a deployment file +# ACL 계정 — 배포 파일이 아니라 시험용 fixture -**Nothing in this directory is loaded by a deployment.** Every file here is a fixture for the local -and test lanes: its passwords are public (`fixture-*`, written in this repository), and -`lane-fixture-accounts.acl` also provisions three accounts that only a lane topology needs — among -them `ca-skeleton-cluster-bootstrap`, which has `~* &* +@all`, every command on every key. Loaded into -a real Redis, that line alone gives anyone who can reach the server and read this repository full -control of it (`CONFIG`, `MODULE`, every key). A deployment writes its own ACL file of the same -shape: the application accounts it actually uses, passwords from its secret store, and none of the -lane-only accounts (review 2026-11-03 RR-07-04). The application enforces its half of that: under -the `prod` runtime profile it refuses to start while a secret holds a value beginning with -`fixture-` (`SecretSourceValidator`): a key the secrets registry classifies `secret`, a variable a -module's `RequiredProductionSecrets` bean names, or the variable a `secret://…/` credential -reference in the environment names. A reference held in code — the typed SDK's admin account, -contributed as a `RedisAccountContribution` bean — is none of those: the composer names its variable -in a `RequiredProductionSecrets` bean too (`src/adapter/outbound/redis-sdk/README.md`), or the -`fixture-admin` password passes. A deployment that copied a lane's -`APP_REDIS_AUTHENTICATION_*_REFERENCE` and `REDIS_LANE_*` values stops before it connects. Values -that are not secrets — a pod's `HOSTNAME`, an application name — are not read, because `fixture-` -is an ordinary word as well. +**이 폴더의 어떤 파일도 배포에서 읽지 않는다.** 모든 파일이 로컬·테스트 lane용 fixture다. -One file per `CommandAccess` level. Each account is deliberately narrower than the SDK's own rules: -the account is the last enforcement boundary and a permit issued inside the process never widens it, -so a mistake in the SDK is still refused by the server. +- 비밀번호가 공개돼 있다(`fixture-*`, 이 저장소에 적혀 있다). +- `lane-fixture-accounts.acl`은 lane 구성에만 필요한 계정 셋도 만든다. 그중 + `ca-skeleton-cluster-bootstrap`은 `~* &* +@all`, 곧 모든 key에 모든 명령을 가진다. +- 이 줄 하나를 실제 Redis에 올리면, 서버에 닿을 수 있고 이 저장소를 읽을 수 있는 누구나 서버 전체 + (`CONFIG`, `MODULE`, 모든 key)를 다룰 수 있다. -A Redis ACL file accepts nothing but complete `user` lines — no comments and no line continuations — -which is why the rationale lives here instead of inline. +배포는 같은 모양의 자기 ACL 파일을 쓴다. 실제로 쓰는 애플리케이션 계정만 두고, 비밀번호는 자기 secret +store에서 가져오고, lane 전용 계정은 두지 않는다(review 2026-11-03 RR-07-04). -Every account here carries a **fixture** password (`fixture-*`). They are written down rather than -left as `nopass` because an account that accepts any password makes every assertion about -authentication pass for the same reason a typo would have — and because these files are what a fork -copies. The four per-role files carried `nopass` long after the combined lane file had been fixed; -a fork that copied one of them got an open account and a green lane. +애플리케이션도 자기 몫을 강제한다. `prod` 런타임 profile에서 비밀값이 `fixture-`로 시작하면 기동을 +거부한다(`SecretSourceValidator`). 보는 비밀값은 셋이다. -| File | Account | Grants | +- 비밀 레지스트리가 `secret`으로 분류한 키 +- 모듈의 `RequiredProductionSecrets` bean이 이름을 댄 변수 +- 환경 안의 `secret://…/` 자격 증명 참조가 가리키는 변수 + +코드에 있는 참조(typed SDK의 admin 계정을 `RedisAccountContribution` bean으로 기여하는 경우)는 이 셋 중 +어디에도 들지 않는다. 조립하는 쪽이 그 변수도 `RequiredProductionSecrets` bean에 적어야 한다 +(`src/adapter/outbound/redis-sdk/README.md`). 그러지 않으면 `fixture-admin` 비밀번호가 통과한다. +lane의 `APP_REDIS_AUTHENTICATION_*_REFERENCE`와 `REDIS_LANE_*` 값을 복사한 배포는 연결하기 전에 멈춘다. +비밀이 아닌 값(pod의 `HOSTNAME`, 애플리케이션 이름)은 읽지 않는다. `fixture-`는 보통 낱말이기도 하다. + +`CommandAccess` 등급마다 파일이 하나다. 각 계정은 SDK 자체 규칙보다 일부러 더 좁다. 계정이 마지막 +강제 경계이고 프로세스 안에서 내준 허가는 그 경계를 넓히지 못한다. 그래서 SDK에 실수가 있어도 서버가 +거절한다. + +Redis ACL 파일은 완전한 `user` 줄만 받는다. 주석도, 줄 이어 쓰기도 안 된다. 그래서 근거를 파일 안이 +아니라 여기에 둔다. + +여기의 모든 계정은 **fixture** 비밀번호(`fixture-*`)를 가진다. `nopass`로 두지 않고 적어 둔 이유는 둘이다. + +- 아무 비밀번호나 받는 계정에서는 인증에 대한 모든 단언이 오타가 있어도 통과한다. +- fork가 복사하는 것이 이 파일들이다. 역할별 파일 넷은 합친 lane 파일을 고친 뒤에도 오래 `nopass`였고, + 그중 하나를 복사한 fork는 열린 계정과 녹색 lane을 함께 얻었다. + +| 파일 | 계정 | 주는 권한 | | --- | --- | --- | -| `application.acl` | `CommandAccess.APPLICATION` | the typed data-structure commands over `prod:*`, with the dangerous and deprecated names denied | -| `application-advanced.acl` | `APPLICATION_ADVANCED` | the above plus pub/sub, transactions, and the registered-script path. `EVAL` is absent: only `EVALSHA` of an already loaded digest is reachable. `+time` is granted because the rate-limit and idempotency scripts read the server clock with `redis.call('TIME')`, and `TIME` is in no data category (`@read`/`@write`): without it every such script fails with an ACL error. The startup SCRIPT probe runs `TIME` so a template missing it fails at boot | -| `raw-gateway.acl` | `RAW_GATEWAY` | exactly the commands the catalog classifies `RAW_ONLY`, and nothing else | -| `lane-fixture-accounts.acl` | – | what the lanes load (Redis takes one `aclfile`): `user default off`, the four per-role accounts of this table, and three lane-only accounts — `ca-skeleton-replication` (replica sync) and `ca-skeleton-sentinel` for the replicated and sentinel topologies, `ca-skeleton-cluster-bootstrap` (`+@all`) to create the cluster lane's slots. Never a deployment file | -| `admin-readonly.acl` | `ADMIN_READONLY` | read-only diagnostics. Every destructive counterpart is denied here and blocked in the command policy catalog — two independent controls for the same rule | +| `application.acl` | `CommandAccess.APPLICATION` | `prod:*` 위의 typed 자료구조 명령. 위험한 명령과 폐기된 명령 이름은 막는다 | +| `application-advanced.acl` | `APPLICATION_ADVANCED` | 위 권한에 pub/sub, 트랜잭션, 등록된 script 경로를 더한다. `EVAL`은 없다: 이미 올린 digest의 `EVALSHA`만 닿는다. `+time`을 주는 이유: rate-limit·idempotency script가 `redis.call('TIME')`으로 서버 시계를 읽는데, `TIME`은 어떤 데이터 범주(`@read`/`@write`)에도 없다. 없으면 그런 script가 모두 ACL 오류로 실패한다. 기동 때의 SCRIPT 확인이 `TIME`을 돌려서, 이 권한이 빠진 템플릿은 기동에서 실패한다 | +| `raw-gateway.acl` | `RAW_GATEWAY` | catalog가 `RAW_ONLY`로 분류한 명령만, 그 밖에는 없다 | +| `lane-fixture-accounts.acl` | – | lane이 읽는 파일(Redis는 `aclfile` 하나만 받는다): `user default off`, 이 표의 역할별 계정 넷, lane 전용 계정 셋 — `ca-skeleton-replication`(replica 동기화)과 `ca-skeleton-sentinel`(replicated·sentinel 구성용), `ca-skeleton-cluster-bootstrap`(`+@all`, cluster lane의 slot을 만든다). 배포 파일이 아니다 | +| `admin-readonly.acl` | `ADMIN_READONLY` | 읽기 전용 진단. 파괴적인 짝 명령은 모두 여기서 막고 명령 정책 catalog에서도 막는다 — 같은 규칙에 서로 독립인 통제 둘 | +| `sentinel-accounts.acl` | – | sentinel 프로세스용 계정(`ca-skeleton-sentinel-client`, `ca-skeleton-sentinel-peer`, `ca-skeleton-sentinel-operator`). 지금 이 파일을 `aclfile`로 읽는 compose 파일은 없다 | -## Who loads `lane-fixture-accounts.acl` +## 누가 `lane-fixture-accounts.acl`을 읽나 -The Redis topology lanes (`src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}`), the -application's Compose lanes that switch Redis on (`local-redis`, `all-adapters` in -`src/app-bootstrap/compose-lanes/compose-profile-contracts.json`), and the development stack's -`redis` service (root `compose.yaml`). They all mount this directory read-only; neither -keeps a copy, because a second copy of these lines is a second place for a password or a key -pattern to drift. +- Redis 구성(topology) lane: `src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}` +- Redis를 켜는 애플리케이션 Compose lane: `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`의 + `local-redis`, `all-adapters` +- 개발 환경의 `redis` 서비스(루트 `compose.yaml`) -The Compose lanes connect the application as `ca-skeleton-application` and -`ca-skeleton-application-advanced`, through `secret://@environment/` references -whose variables carry the fixture passwords above. They run with the Redis namespace environment -`prod`, because every account here is fenced to `~prod:*`. `scripts/verify-compose-profile-contracts.sh` -compares each Redis lane's references, passwords and namespace with the account lines in this file, -so changing a password or a key pattern here without the lanes fails that check rather than the -lane's first command. +모두 이 폴더를 읽기 전용으로 마운트한다. 복사본을 두지 않는다. 이 줄들의 두 번째 사본은 비밀번호나 key +패턴이 따로 어긋날 두 번째 자리다. + +Compose lane은 애플리케이션을 `ca-skeleton-application`과 `ca-skeleton-application-advanced`로 연결한다. +연결은 `secret://@environment/` 참조를 거치고, 그 변수가 위 fixture 비밀번호를 가진다. +여기의 모든 계정이 `~prod:*`로 묶여 있어서, lane은 Redis namespace 환경을 `prod`로 두고 돈다. +`scripts/verify-compose-profile-contracts.sh`가 Redis lane마다 참조·비밀번호·namespace를 이 파일의 계정 줄과 +비교한다. 그래서 lane을 고치지 않고 여기의 비밀번호나 key 패턴만 바꾸면, lane의 첫 명령이 아니라 그 검사가 +실패한다. diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 8a5aa7f4..a2395d6d 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -5,8 +5,6 @@ # - 형식: <검사><탭><경로>[<탭><걸린 값>]. 「#」으로 시작하는 줄과 빈 줄은 읽지 않는다. # 언어: 아직 한국어로 옮기지 않은 살아 있는 문서와 ADR. 다음 단계(살아 있는 문서 번역, ADR 번역)에서 지운다. -language compose/keycloak/README.md -language compose/redis/acl/README.md language docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md language docs/adr/ADR-GQL-001-graphql-context-and-storage-ownership.md language docs/adr/ADR-GRPC-001-platform-family-and-registry-shape.md