custom claim 권한체크 확인

docs/SoT_Architecture_Policy.md

@@ -1,44 +1,54 @@
-# Baron SSO Data SoT (Source of Truth) Architecture Policy
+# Baron SSO Data SoT Architecture Policy
 
-## 1. Core Principle: "Ory Stack is the Single Source of Truth"
-Baron SSO 시스템에서 인증(Identity), 인가(Authorization), OAuth2 위임(Delegation)의 데이터 원천은 **Ory Stack (Kratos, Keto, Hydra)** 입니다.
-Backend의 로컬 데이터베이스(PostgreSQL)는 성능 최적화, 검색, 감사(Audit), 비즈니스 메타데이터 관리를 위한 **Read-Model** 및 **Cold Storage**의 역할만 수행합니다.
+## 1. Core Principle: Ory Stack is the Single Source of Truth
+
+Baron SSO에서 인증 identity, 권한 관계, OAuth/OIDC 위임의 원장은 Ory Stack입니다.
+
+- Identity/profile 인증 원장: Ory Kratos
+- Authorization/ReBAC 원장: Ory Keto
+- OAuth/OIDC client, consent, token state 원장: Ory Hydra
+
+Backend DB는 Ory를 대체하는 원장이 아닙니다. Ory에 저장되지 않거나 Ory API로 필요한 방식의 조회가 불가능한 업무 데이터의 read model, 감사 로그, 처리 상태, 성능 cache 보조 데이터만 허용합니다.
+
+Ory에서 Redis cache로 웜업된 데이터는 Backend가 cursor 기반 API로 front 또는 외부 API에 제공합니다. frontend는 Redis나 Backend DB 복제본을 원장처럼 직접 소비하지 않습니다.
 
 ## 2. Component Policies
 
-### 2.1 Identity & User Profile (Ory Kratos)
-*   **SoT:** Ory Kratos Identity (`traits`, `metadata_public`)
-*   **Local DB (`users` Table):** **Read-Model & Search Index**
-    *   **목적:** 대규모 사용자 목록의 고속 검색(`LIKE`), 필터링, 정렬, 테넌트 조인(Join) 지원.
-    *   **동기화 전략:** `Async Write-Behind`
-        *   사용자 생성/수정 API는 Kratos 처리가 성공하면 즉시 성공 응답을 반환합니다.
-        *   로컬 DB 동기화는 별도 고루틴(Goroutine)에서 비동기로 수행됩니다.
-    *   **장애 격리:** 로컬 DB 장애가 사용자의 로그인/가입 프로세스를 차단하지 않습니다.
+### 2.1 Identity & User Profile
 
-### 2.2 Permissions & Relationships (Ory Keto)
-*   **SoT:** Ory Keto (Relation Tuples)
-*   **Local DB:**
-    *   권한 판단 로직을 로컬 DB에 저장하지 않습니다.
-    *   `Tenant`, `TenantGroup` 등 비즈니스 객체의 **생성/삭제 이벤트**를 Keto의 관계(Relation)로 비동기 동기화합니다.
-    *   모든 권한 검증(`CheckPermission`)은 반드시 Keto API를 통해 실시간으로 수행합니다.
+- Ory Kratos identity가 subject, credentials, recovery/verification address, 인증 식별자의 원장입니다.
+- Kratos identity 변경은 Backend의 중앙 `IdentityWriteService`를 경유해야 합니다.
+- Redis identity mirror는 빠른 단건/목록/검색 조회를 위한 cache입니다. stale 가능성을 API 응답에 드러내야 합니다.
+- Backend DB `users`는 Ory에 저장되지 않거나 Ory에서 필요한 방식으로 조회할 수 없는 Baron 운영 데이터의 read model입니다.
 
-### 2.3 OAuth2 Clients & Sessions (Ory Hydra)
-*   **SoT:** Ory Hydra (OAuth2 Clients, Access/Refresh Tokens, Consent Sessions)
-*   **Local DB (`client_secrets`, `client_consents`):** **Backup & Query-Model**
-    *   `client_secrets`: Hydra는 해시된 시크릿만 저장하므로, 시크릿 재발급 및 관리를 위한 **원본 보관소(Cold Storage)**로 사용합니다.
-    *   `client_consents`: Hydra API는 "특정 사용자의 동의 내역" 조회만 지원하므로, "특정 클라이언트의 전체 사용자 동의 목록"을 제공하기 위한 **조회용 모델(Query-Model)**로 사용합니다.
+### 2.2 Permissions & Relationships
+
+- 권한 판단과 관계 tuple의 원장은 Ory Keto입니다.
+- Backend DB는 relation command outbox, 처리 상태, 조직 표시/검색에 필요한 read model을 보관할 수 있습니다.
+- 보안상 중요한 권한 판정은 Backend DB metadata나 token claim만으로 수행하지 않고 Keto check를 거쳐야 합니다.
+
+### 2.3 OAuth2 Clients & Sessions
+
+- OAuth2 client, consent, token state의 프로토콜 원장은 Ory Hydra입니다.
+- `client_consents` 같은 Backend read model은 Hydra가 제공하지 않는 조회 축을 보완하기 위한 모델입니다.
+- client secret 원문처럼 Hydra가 해시만 보관하는 값은 재발급/운영 목적의 별도 보관 정책과 감사 로그를 가져야 합니다.
 
 ## 3. Data Flow & Synchronization Strategy
 
-### 3.1 Write Path (Command)
-1.  **Request:** 클라이언트가 Backend API 요청.
-2.  **Ory Exec:** Backend가 Ory 서비스(Kratos/Hydra/Keto) API를 동기(Synchronous) 호출.
-3.  **Response:** Ory 성공 시 클라이언트에게 즉시 성공 응답 반환 (SoT 확정).
-4.  **Sync:** Backend가 비동기(Goroutine)로 로컬 DB 테이블을 갱신.
+### 3.1 Write Path
 
-### 3.2 Read Path (Query)
-*   **Self Context (내 정보, 내 권한):** Ory Session/Token을 통해 직접 검증하거나 Kratos/Keto를 실시간 조회 (Always Fresh).
-*   **Admin Context (목록 조회, 검색):** 로컬 DB를 조회하여 빠른 응답 제공 (Eventually Consistent).
+1. 클라이언트 또는 운영 도구가 Backend API/CLI를 호출합니다.
+2. Backend가 중앙 service를 통해 Ory API를 동기 호출합니다.
+3. Ory write 성공 후 Ory ID로 재조회합니다.
+4. Redis mirror를 갱신하거나 갱신 실패 시 `stale`/`failed` 상태를 기록합니다.
+5. Ory에 저장되지 않거나 조회 불가능한 read model만 Backend DB에 갱신합니다.
+
+### 3.2 Read Path
+
+- Self context: Ory session/token 또는 Ory API를 기준으로 검증합니다.
+- Admin/list context: Backend가 Redis mirror와 허용된 read model을 조합해 cursor 기반 API로 제공합니다.
+- API response는 `identityTotal`, read model count, mirror status를 구분해야 합니다.
 
 ### 3.3 Conflict Resolution
-*   데이터 불일치가 발견될 경우, 항상 **Ory Stack의 데이터를 기준(Authority)**으로 로컬 DB를 보정(Self-healing)합니다.
+
+불일치가 발견되면 Ory Stack의 데이터를 기준으로 Redis mirror와 Backend read model을 보정합니다. Backend read model이나 token claim assembly 결과를 Ory보다 우선하는 근거로 사용하지 않습니다.