From 5c19b88230a0c4baf02bd20b3cf8d45d72dab35e Mon Sep 17 00:00:00 2001
From: Lectom C Han <hchy0730@gmail.com>
Date: Tue, 27 Jan 2026 17:56:17 +0900
Subject: [PATCH] =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=EC=97=85=EB=8D=B0?=
 =?UTF-8?q?=EC=9D=B4=ED=8A=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                     | 77 +++++++++++++++++++++++++++--------
 AGENTS.md => docs/AGENTS.md   |  0
 Gemini.md => docs/Gemini.md   |  0
 docs/idp_policy.md            | 27 ++++++++++++
 PRD.md => docs/initial_PRD.md |  0
 docs/shadowing_policy.md      | 64 +++++++++++++++++++++++++++++
 docs/tenant_policy.md         | 61 ---------------------------
 to-do.md                      | 27 ------------
 8 files changed, 152 insertions(+), 104 deletions(-)
 rename AGENTS.md => docs/AGENTS.md (100%)
 rename Gemini.md => docs/Gemini.md (100%)
 create mode 100644 docs/idp_policy.md
 rename PRD.md => docs/initial_PRD.md (100%)
 create mode 100644 docs/shadowing_policy.md
 delete mode 100644 docs/tenant_policy.md
 delete mode 100644 to-do.md

diff --git a/README.md b/README.md
index 99c2f8aa..7b6ba87f 100644
--- a/README.md
+++ b/README.md
@@ -5,27 +5,68 @@
 
 ## 🏗 아키텍처 (Architecture)
 
-### 1. Frontend (Flutter Web)
-- **Framework**: Flutter 3.32+
-- **Organization**: `kr.co.baroncs`
-- **Key Packages**: `descope`, `flutter_riverpod`, `go_router`
-- **Features**:
-  - 탭 기반 로그인 UI (이메일 / SMS)
-  - Descope SDK 연동 (Enchanted Link)
+### 0. Ory Stack
+- Ory Kratos: 사용자 인증/계정 관리(Identity).
+- Kratos Selfservice UI: Kratos 셀프서비스 플로우 UI.
+- Ory Hydra: OAuth2/OIDC 발급 및 토큰 관리.
+- Ory Keto: 권한/정책 기반 접근 제어.
+- Oathkeeper: 인증/인가 프록시 및 라우팅 게이트웨이.
 
-### 2. Backend (Go Fiber)
+### 1. Backend (Go Fiber)
 - **Language**: Go 1.25+
 - **Framework**: Fiber v2.25+
 - **Database**:
   - **ClickHouse**: 감사 로그 (고성능 데이터 수집)
   - **PostgreSQL**: 메타데이터 저장소 (Primary)
 - **Features**:
+  - 인증용 SMS 발송 등 Ory-Stack으로 구현 어려운 부분 직접 구현
   - `POST /api/v1/audit`: 감사 로그 수집 API
+  - User-Front가 바라보는 backend
+
+### 2. User-Front(Flutter Web/App)
+- **Framework**: Flutter 3.32+
+- **Key Packages**: `flutter_riverpod`, `go_router`
+- **Features**:
+  - 탭 기반 로그인 UI (비밀번호 기반 / 링크 기반 / QR 기반 등)
+
+### 3. Admin-Front(Web)
+- **Framework**: Vite, React 19+, Shadcn/ui 등
+- **Features**:
+  - 사용자 관리, 권한 부여 등 관리자 기능
+  - 앱 별 사용량(호출량) 등 통계
+  - 핵심 Audit 대상 
+
+### 4. Dev-Front(Web) - 향후 분리 예정
+- **Framework**: Vite, React 19+, Shadcn/ui 등
+- **Features**:
+  - RP 등록 및 관리
+  - RP별 Consent 관리
+
 
 ### 4. 주요 시나리오 (Core Scenarios)
-1.  **Same Browser SSO**: Baron SSO에 로그인된 상태에서 런처를 통해 타 앱/서비스로 이동 (자동 로그인).
-2.  **Cross-Device Auth**: PC에서 로그인 시도 시, 이미 로그인된 모바일 앱으로 알림을 보내 승인 (Enchanted Link 활용).
-3.  **Clean Login**: 최초 진입 시 이메일 또는 SMS를 통한 로그인 (향후 OTP, MFA 확장 예정).
+1.  **Same Browser SSO**: Baron 통합로그인 서비스에 로그인된 상태에서 런처를 통해 타 앱/서비스로 이동 (자동 로그인).
+  1.1. 단 약관동의(Consent) 이력이 없으면 Consent 단계로 이동
+2.  **Cross-Device Auth**: 이메일 SMS 등의 수단으로 링크를 전달받고 해당 링크를 사용자가 클릭하면 최초 로그인 요청한 세션이 활성화
+  2.1 향후 App Push 등 2차 인증 강화수단 검토 필요
+3.  **QR Login**: 최초 진입 시 사전 로그인되어 있는 웹/앱을 이용해 QR 코드를 스캔하여, QR코드가 로딩된 Device를 로그인 상태로 전환
+
+
+### 전체 연결 구조도
+
+```mermaid
+flowchart LR
+  AF[Admin Front] -->|"OIDC authorize/token (PKCE)"| HY["Hydra (OIDC 엔진)"]
+  DF[Dev Front] -->|"OIDC authorize/token (PKCE)"| HY
+  UF["User Front (Login/Consent UI)"] <-->|Hydra login/consent redirect| HY
+  UF -->|Kratos Browser Flow| KR["Kratos (SoT: identities/traits)"]
+  KR -->|subject=identity.id| HY
+  HY -->|ID/Access Token| RP[Relying Party Apps]
+  MG["Magic Link Wrapper (Fiber)"] -->|1회용 토큰→Kratos CreateSession| KR
+  MG -->|"Hydra Login Accept (옵션)"| HY
+  DS["Descope/Social IDP"] -->|Kratos Social/OIDC| KR
+```
+
+Kratos가 사용자 SoT이며 Hydra는 순수 OIDC 토큰 엔진입니다. Magic Link는 Fiber 래퍼가 Kratos 세션을 만들고 필요 시 Hydra Login Accept를 수행합니다. Descope 등 보조 IDP는 Kratos Social/OIDC provider로 연결합니다.
 
 ---
 
@@ -91,9 +132,13 @@ baron_sso/
 │   ├── cmd/server/     # 진입점 (Entry point)
 │   ├── internal/       # 도메인, 핸들러, 저장소(Repository)
 │   └── Dockerfile
-├── frontend/           # Flutter 애플리케이션
-│   ├── lib/            # UI 및 로직
+├── user-front/          # Flutter 애플리케이션
+│   ├── src/            # UI 및 로직
 │   └── pubspec.yaml
+├── admin-front/         # React 기반 관리
+│   ├── src/            # UI 및 로직
+│   └── pubspec.yaml
+├── compose.ory-stack.yaml  # DB 서비스 (Postgres, ClickHouse)
 ├── compose.infra.yaml  # DB 서비스 (Postgres, ClickHouse)
 ├── docker-compose.yaml # 앱 서비스 (Front, Back)
 ├── .env.sample         # 환경 설정 템플릿
@@ -102,7 +147,7 @@ baron_sso/
 
 ## 📝 상태 및 로드맵 (Status & Roadmap)
 - [x] **Phase 1**: 초기 설정 및 아키텍처 설계 (완료)
-- [x] **Phase 2**: Backend Audit API 구현 (완료)
-- [x] **Phase 3**: Frontend 로그인 UI 및 Descope 인증 로직 (완료)
-- [ ] **Phase 4**: Frontend - Backend 연동 (Audit 전송) (예정)
+- [x] **Phase 2**: Backend Audit API 구현 (일부 완료)
+- [x] **Phase 3**: User Front 로그인 UI 인증 로직 (완료)
+- [ ] **Phase 4**: Admin Front 기능 추가 (예정)
 - [ ] **Phase 5**: 대시보드 및 통합 런처 구현 (예정)
diff --git a/AGENTS.md b/docs/AGENTS.md
similarity index 100%
rename from AGENTS.md
rename to docs/AGENTS.md
diff --git a/Gemini.md b/docs/Gemini.md
similarity index 100%
rename from Gemini.md
rename to docs/Gemini.md
diff --git a/docs/idp_policy.md b/docs/idp_policy.md
new file mode 100644
index 00000000..71544392
--- /dev/null
+++ b/docs/idp_policy.md
@@ -0,0 +1,27 @@
+# IDP Abstraction & Perfect Wrapping Policy
+
+## 1. 핵심 원칙 (Core Principles)
+
+**"사용자와 클라이언트 개발자는 IDP가 무엇인지 알 수도 없고, 알아서도 안 된다."**
+
+Baron SSO의 가장 중요한 아키텍처 원칙은 **IDP Agnostic(IDP 불가지론)**입니다. 현재 Descope를 사용하더라도, 내일 당장 Hydra, Authentik, Keycloak 또는 자체 구축 인증 서버로 변경하더라도 **Frontend, Client App, 그리고 최종 사용자에게는 단 1줄의 코드 변경이나 경험의 변화가 없어야 합니다.**
+
+## 2. 세부 지침 (Guidelines)
+
+### 2.1. Frontend & Client Side
+- **No Vendor SDK**: 프론트엔드 코드(User App, Admin Front)에서 `descope-sdk` 등 특정 벤더의 SDK를 직접 import하여 비즈니스 로직에 사용하는 것을 금지합니다.
+- **Unified Interface**: 모든 인증 요청은 Baron SSO Backend API (`/api/v1/auth/*`)를 통해서만 수행합니다.
+- **Response Format**: 클라이언트가 수신하는 토큰 및 사용자 정보는 Baron SSO가 정의한 표준 스키마(`BrokerUser`)여야 하며, IDP의 Raw Data가 노출되어서는 안 됩니다.
+
+### 2.2. Backend Side
+- **Provider Pattern**: 모든 IDP 관련 로직은 `interface IDPProvider` 뒤에 숨겨야 합니다. 핸들러(Handler) 계층은 구체적인 구현체(DescopeService 등)를 알지 못해야 합니다.
+- **Error Mapping**: IDP에서 발생한 에러(예: `E062907`)는 반드시 Baron SSO의 표준 에러(예: `AUTH_PROVIDER_ERROR`)로 변환되어 클라이언트에 전달되어야 합니다.
+- **Configuration Isolation**: IDP 설정(Project ID, API Key)은 환경 변수와 팩토리 내부로 격리하며, 비즈니스 로직에 하드코딩하지 않습니다.
+
+### 2.3. OIDC/OAuth2 Compliance
+- 외부 서비스(RP) 연동 시, Baron SSO 자체가 OIDC Provider로 동작해야 합니다.
+- RP는 `Issuer`를 Baron SSO의 URL로 설정하며, 원천 IDP의 URL을 바라보지 않습니다.
+
+## 3. 마이그레이션 보장 (Migration Guarantee)
+이 정책의 최종 목표는 **"IDP 교체 비용을 0에 수렴하게 만드는 것"**입니다.
+IDP 변경 시 백엔드의 `IDPProvider` 구현체만 교체하면, 데이터 마이그레이션을 제외한 모든 서비스가 중단 없이 동작해야 합니다.
diff --git a/PRD.md b/docs/initial_PRD.md
similarity index 100%
rename from PRD.md
rename to docs/initial_PRD.md
diff --git a/docs/shadowing_policy.md b/docs/shadowing_policy.md
new file mode 100644
index 00000000..4922cbe1
--- /dev/null
+++ b/docs/shadowing_policy.md
@@ -0,0 +1,64 @@
+# 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 우선**: 사용자는 비밀번호 입력 없이 계속 이용 가능.
+- **재설정 유도**: 비밀번호 사용 필수 시, "보안 정책 변경" 안내와 함께 리셋 링크 발송.
diff --git a/docs/tenant_policy.md b/docs/tenant_policy.md
deleted file mode 100644
index 08cff53a..00000000
--- a/docs/tenant_policy.md
+++ /dev/null
@@ -1,61 +0,0 @@
-# Tenant 정책 (Tenant Policy)
-
-## 1. 개요 (Overview)
-Baron SSO는 **Multi-Tenancy**를 지원하여, 단일 인스턴스에서 여러 조직(Tenant)의 데이터와 사용자를 격리하여 관리할 수 있다. 이 문서는 테넌트의 계층 구조, 리소스 소유권, 데이터 모델링 및 보안 정책을 정의한다.
-
----
-
-## 2. 계층 구조 및 제약 (Hierarchy & Constraints)
-
-### 2.1 계층 제한 (Depth Limit)
-복잡성을 통제하기 위해 테넌트 계층은 **최대 2 Depth (1단계 깊이)**까지만 허용한다.
-*   **Root Tenant (Level 1)**: 최상위 조직 (예: 본사, 고객사 A)
-*   **Sub Tenant (Level 2)**: 하위 조직 (예: 인사팀, 지사 B)
-*   **제약**: Sub Tenant 밑에 또 다른 Tenant를 둘 수 없다.
-
-### 2.2 리소스 소유권 (Resource Ownership)
-*   **Root Tenant Only**:
-    *   **Relying Party (Client App)**, **IDP 설정** 등 시스템의 핵심 리소스는 **오직 Root Tenant만 생성하고 소유**할 수 있다.
-    *   모든 정책(Policy) 결정 권한은 Root Tenant에게 있다.
-*   **Sub Tenant**:
-    *   독자적인 RP나 IDP 설정을 가질 수 **없다**.
-    *   Root Tenant가 설정한 리소스를 공유하며, 단순히 사용자를 그룹핑하거나 조직 단위(Organizational Unit)로 관리하는 역할만 수행한다.
-
----
-
-## 3. 데이터 모델 (Data Model)
-
-### 3.1 사용자 관계 (User Membership)
-사용자는 **단일 계정(User ID)으로 여러 Tenant에 동시에 소속(N:M 관계)**될 수 있다.
-*   **`users` 테이블**: 사용자의 고유 식별자 및 전역 속성(Email, Name, Phone)만 저장.
-*   **`tenants` 테이블**: 테넌트 메타데이터 (`id`, `parent_id`, `name` 등). `parent_id`가 NULL이면 Root Tenant이다.
-*   **`user_tenants` 테이블 (Membership)**: `user_id`와 `tenant_id`를 매핑하며, 해당 테넌트 내에서의 `roles`(권한) 정보를 저장한다.
-
-### 3.2 ID 식별 및 매핑 (Identification)
-*   **Internal Tenant ID**: 시스템 내부적으로는 항상 **UUID** 기반의 고유 식별자를 사용한다.
-*   **External Mapping**: Descope, Ory Hydra 등 외부 IDP의 Tenant ID 형식이 다를 수 있으므로, `provider_mappings` 컬럼(또는 테이블)을 통해 외부 ID와 내부 UUID를 매핑한다.
-
----
-
-## 4. 인증 및 인가 (Authentication & Authorization)
-
-### 4.1 Active Tenant Context
-사용자가 여러 Tenant에 속할 수 있으므로, 모든 API 요청은 **"현재 어떤 Tenant 문맥에서 작업 중인가"**를 명확히 해야 한다.
-*   **Header**: `X-Tenant-ID` (필수)
-*   **Middleware 검증 로직**:
-    1.  요청 헤더에서 `TargetTenantID`를 추출한다.
-    2.  User의 JWT Claims(또는 DB)를 확인하여, 사용자가 `TargetTenantID`에 소속되어 있는지 확인한다.
-    3.  해당 Tenant에서의 Role(예: Tenant Admin)이 요청한 작업을 수행할 권한이 있는지 검증한다.
-
----
-
-## 5. 보안 및 감사 (Security & Audit)
-
-### 5.1 Audit Log 정책
-`X-Tenant-ID` 헤더의 존재 여부와 관계없이, **모든 보안 이벤트는 반드시 기록**되어야 한다.
-*   **Tenant Context 존재 시**: 해당 `tenant_id`와 함께 로그 저장.
-*   **Tenant Context 부재 시** (예: 로그인 직후, 프로필 수정, 내 테넌트 목록 조회): `tenant_id`를 `NULL` 또는 예약어(`system`, `personal`)로 저장.
-
-### 5.2 API 접근 제어 정책
-*   **Tenant-Scoped API** (예: RP 생성, 멤버 초대): 헤더 누락 시 **400 Bad Request** 거절.
-*   **User/Global API** (예: 내 정보 수정): 헤더 누락 허용 (Global Context).
diff --git a/to-do.md b/to-do.md
deleted file mode 100644
index e8d6f769..00000000
--- a/to-do.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# Baron SSO 작업 목록 (To-Do)
-
-## 1. 백엔드 개발 (Go Fiber)
-- [x] Go 모듈 초기화
-- [x] Fiber 아키텍처 (Clean Arch) 구성
-- [x] Audit Log DB 구축 (PostgreSQL + ClickHouse)
-- [x] 프론트엔드 연동용 API 생성 (`POST /api/v1/audit`)
-
-## 2. Descope 연동 전략
-- [x] Ncloud SMS 커넥터 설정 (Descope Console)
-- [x] Audit Log Webhook/API 설계
-
-## 3. 프론트엔드 개발 (Flutter Web PoC)
-- [x] Flutter 프로젝트 초기화
-- [x] 로그인 UI 구현 (탭: 이메일/비번 & SMS)
-- [x] Enchanted Link 핸들링 로직 구현 (Cross-Device Auth 지원)
-- [ ] 대시보드 구현 (세션 리스트)
-- [ ] 통합 런처 UI 구현 (Same Browser SSO)
-- [ ] 관리자 모드 (Descope 관리 기능)
-
-## 4. 검증 (Verification)
-- [ ] End-to-End 로그인 흐름 테스트
-- [ ] Audit Log 저장 확인
-
-## 5. 향후 마일스톤 (Milestones)
-- [ ] Passkey 지원 (Scenario 2, 3)
-- [ ] 심화 MFA (OTP 등) 확장