# RBAC / ReBAC 미들웨어 정책 정리

## 1. 목적
- `backend/internal/middleware/rbac.go`는 **역할 기반(RBAC)**과 **관계 기반(ReBAC, Keto)**을 조합해 접근 제어를 일관되게 적용합니다.
- 핵심 목표는 **운영 단순성 + 권한 정밀도**의 균형입니다.

## 2. 구성 요소와 역할

### 2.1 RequireRole
- 역할(Role) 기반 접근 제어를 담당합니다.
- Super Admin은 즉시 통과합니다.
- 허용된 역할 목록에 포함되지 않으면 차단합니다.
- API Key 인증은 우회합니다(시스템/운영 경로).

### 2.2 RequireKetoPermission
- Ory Keto(ReBAC) 권한 체크를 수행합니다.
- Super Admin은 즉시 통과합니다.
- Keto의 관계 튜플에 기반해 `CheckPermission`을 수행합니다.

### 2.3 RequireTenantMatch
- 테넌트 관리자 권한을 가진 사용자가 **자신의 테넌트**에만 접근하도록 보장합니다.
- Super Admin은 즉시 통과합니다.
- API Key 인증은 우회합니다.

## 3. ReBAC 기반인데도 RBAC가 필요한 이유

1) **정책 단순화**
- Super Admin 같은 전역 정책은 ReBAC로 표현할 수도 있지만, RBAC가 더 빠르고 명확합니다.

2) **운영 경로 단축**
- API Key, 배치성 요청 등은 일반 사용자 흐름과 분리해 처리합니다.
- 불필요한 ReBAC 호출을 줄여 장애 전파를 줄입니다.

3) **테넌트 범위 제어의 명확성**
- "Tenant Admin은 자기 테넌트만"은 자주 쓰는 규칙으로, 미들웨어 단에서 즉시 판단이 효율적입니다.

4) **성능 및 안정성**
- Keto는 외부 서비스 호출이므로 지연/실패 가능성이 있습니다.
- RBAC로 1차 필터링을 하여 호출 수를 줄입니다.

## 4. SoT(단일 진실 공급원) 충돌 시 우선순위 정책

### 4.1 사용자/인증 SoT
- **1순위: Kratos Identity / Session**
  - 사용자 식별과 세션 유효성의 최종 판단 기준
- **2순위: Backend 프로필 DB / 캐시**
  - Kratos와 동기화가 보장되는 범위에서만 보조 사용

### 4.2 권한/정책 SoT
- **1순위: Keto(ReBAC) 관계 튜플**
  - 리소스 접근 권한의 최종 판단 기준
- **2순위: RBAC(Role)**
  - 전역/상위 정책의 단축 규칙
  - ReBAC와 충돌 시, ReBAC 결과가 항상 우선

### 4.3 테넌트 컨텍스트 SoT
- **1순위: 서버 측 프로필(예: UserProfile.tenantId)**
- **2순위: 요청 헤더(X-Tenant-ID)**
  - 헤더는 "요청 의도"를 나타내지만, 항상 서버 프로필과 일치해야 함
  - 불일치 시 차단

### 4.4 OIDC/RP 정보 SoT
- **1순위: Hydra Client/Consent 데이터**
- **2순위: Backend audit details**
  - 과거 데이터 재현을 위해 audit details에 client_id/client_name을 기록

## 5. 충돌 시 처리 원칙 (확정)

1) **RBAC는 필터이고, 허용의 최종 판단은 ReBAC**
- RBAC 통과는 ReBAC 호출의 전제일 뿐, 허용 조건이 아니다.
- ReBAC 결과가 "허용"이어야만 최종 통과한다.

2) **RBAC 통과 + ReBAC 실패 → 차단**
- ReBAC가 최종 권한을 가진다.

3) **RBAC 실패 + ReBAC 통과 → 차단**
- 역할 기반 정책 위반은 즉시 차단한다.

4) **Super Admin 예외**
- Super Admin이라도 기본 흐름에서는 ReBAC 판단을 거친다.
- 예외가 필요한 API는 별도로 명시하고, 감사 로그에 명확히 남긴다.

5) **API Key 우회 범위**
- API Key 우회는 최소 범위로 제한한다.
- 우회 대상 API와 사유를 별도 문서로 관리한다.

## 6. 정책 보완 필요 지점 (결정 필요)

1) **Tenant 헤더 불일치 정책**
- `X-Tenant-ID`가 프로필 테넌트와 불일치할 때 차단은 확정
- 테넌트 전환 UI/흐름에 따라 정책 확정 필요

2) **API Key 우회 범위 문서화**
- 현재는 `RequireRole`/`RequireTenantMatch`에서 우회 처리
- 우회 허용 API 목록과 사유를 문서로 고정 필요

## 7. 관련 코드
- `backend/internal/middleware/rbac.go`
- `backend/internal/handler/auth_handler.go`
- `backend/internal/service/keto_service.go`

