# Shadow Account Policy (Identity Sovereignty)

## 1. 개요 (Overview)
Baron SSO는 외부 IDP(Descope 등)에 의존하지 않고, **식별자 주권(Identity Sovereignty)**을 갖기 위해 **Shadow Account (그림자 계정)** 모델을 채택합니다.
외부 IDP는 단지 "인증 수단"일 뿐이며, 서비스 내부의 모든 비즈니스 로직, 로그, RP 연동은 Baron SSO가 발급한 고유 식별자(`Baron ID`)를 기준으로 수행됩니다.

## 2. 식별자 정책 (Identifier Policy)

### 2.1. Baron ID (Internal User ID)
- **Format**: **UUID v7** (Time-ordered 128-bit)
- **특징**: 생성 시간 순 정렬 가능, DB 인덱싱 효율 최적화, 외부 시스템 충돌 없음.
- **용도**: `users` 테이블 PK, `audit_logs`의 Actor ID, RP에 전달되는 `sub` 값.
- **원칙**: **불변(Immutable)**. 사용자가 이메일이나 연동 IDP를 변경해도 Baron ID는 변하지 않아야 합니다.

### 2.2. Audit Log ID
- **Format**: **Snowflake** (64-bit Integer)
- **용도**: 감사 로그의 Primary Key.
- **이유**: 초당 대량으로 발생하는 로그 데이터의 적재 성능과 ClickHouse 압축 효율을 위해 정수형 ID 사용.

## 3. 데이터 모델 (Shadow Schema)

### 3.1. Users Table (Core)
서비스가 바라보는 사용자의 실체입니다.
```sql
CREATE TABLE users (
    id UUID PRIMARY KEY, -- Baron ID (UUID v7)
    email VARCHAR(255),  -- 검색 및 알림용 (Unique X, 여러 계정 가능성)
    name VARCHAR(100),
    status VARCHAR(20),  -- 'active', 'blocked'
    created_at TIMESTAMPTZ,
    last_login_at TIMESTAMPTZ
);
```

### 3.2. Federated Identities Table (Mapping)
외부 IDP 계정과 Baron 계정을 연결하는 매핑 테이블입니다. N:1 매핑이 가능합니다.
```sql
CREATE TABLE federated_identities (
    provider VARCHAR(50), -- 'descope', 'google', 'legacy_db'
    provider_sub VARCHAR(255), -- IDP의 원천 User ID
    user_id UUID REFERENCES users(id),
    created_at TIMESTAMPTZ,
    PRIMARY KEY (provider, provider_sub)
);
```

## 4. 동기화 및 로그인 흐름 (Sync Flow)

1. **인증 성공**: 백엔드가 IDP(Descope) 토큰을 검증하고 `Provider Sub`(예: `U12345`)를 획득.
2. **조회 (Lookup)**: `federated_identities` 테이블에서 `(provider='descope', provider_sub='U12345')` 조회.
3. **분기 처리**:
   - **Case A (기존 회원)**: 매핑된 `user_id` 획득. `users` 테이블의 정보(이메일, 이름)를 IDP 토큰 정보로 **업데이트(Sync)**.
   - **Case B (신규 회원)**: 새로운 `UUID v7` 생성 -> `users` Insert -> `federated_identities` Insert.
4. **세션 발급**: Baron ID(`user_id`)를 Payload로 담은 Baron 자체 세션/토큰을 발급하여 클라이언트에 전달.

## 5. IDP 마이그레이션 전략 (Migration Strategy)

### 5.1. 식별자 유지
IDP가 `Descope`에서 `Keycloak`으로 바뀌더라도, 백엔드는 새로운 IDP의 `sub`를 기존 사용자의 `Baron ID`와 매핑(`federated_identities` 추가)하기만 하면 됩니다. RP와 클라이언트는 아무런 변화를 감지하지 못합니다.

### 5.2. 비밀번호 처리 (Password Handling)
- 해시된 비밀번호는 이관하지 않습니다 (불가능/비효율).
- **Magic Link / Passwordless 우선**: 사용자는 비밀번호 입력 없이 계속 이용 가능.
- **재설정 유도**: 비밀번호 사용 필수 시, "보안 정책 변경" 안내와 함께 리셋 링크 발송.