# AGENTS 가이드 (Baron SSO)

## 목적
- 인증/인가 허브로서 **Backend + Ory Stack** 중심 아키텍처를 유지
- 사용자 플로우(UserFront)와 관리 플로우(Admin/DevFront)를 명확히 분리
- 네트워크/보안 경계를 문서화해 회귀/설정 오류를 방지

## 시스템 요약
- **Backend**: Command 단일 진입점, 감사 로그를 ClickHouse에 적재
- **Ory Stack**: Kratos/Hydra/Keto/Oathkeeper (인증/토큰/정책)
- **Front**: UserFront(Flutter)-사용자 접점, AdminFront/DevFront(React)-내부 관리도구
- **원칙**: Front는 Backend API를 통해서만 IDP 기능을 호출

## 네트워크/보안 경계
- `ory-net`: Ory 내부 통신 전용 네트워크
- `baron_net`: App(backend/userfront/adminfront/devfront) 네트워크
- `public_net`: Oathkeeper, userfront 외부 공개. Gateway를 이용해 Proxy 분기

핵심 규칙:
- **Ory Admin 포트는 외부 노출 금지** (Backend만 `ory-net`을 통해 접근)
- **UserFront는 Oathkeeper 뒤에 있지 않음**
- **모든 Front(User/Admin/Dev)는 Ory Admin 엔드포인트에 직접 접근하지 않음**

## 인증/세션 핵심
- `IDP_PROVIDER` Ory 전용 저장 구조지만 향후 마이그레이션으로 추가 스택 지원할 수 있음
- `sessionJwt`는 **JWT가 아닐 수 있음** (Kratos session token은 opaque 가능)
- OIDC Consent 플로우는 UserFront의 `/consent` 경로에서 처리
- 토큰/쿠키 전달 방식 변경 시 `docs/auth-flow.md`를 반드시 갱신

## 작업 체크리스트
- 인증/로그인 변경 시
  - `docs/auth-flow.md` 업데이트
  - 세션/쿠키/Authorization 전달 방식 영향도 점검
  - UserFront가 Ory/Oathkeeper 직접 호출하지 않도록 확인

- Ory 설정 변경 시
  - `compose.ory.yaml`, `docker/ory/*` 변경 범위 명시
  - `ory-net`/`public_net` 경계 유지 여부 확인

- 환경 변수 추가/변경 시
  - `.env.sample` 반영
  - 문서/가이드 갱신

- 배포/운영 변경 시
  - `Makefile`/compose 실행 절차 영향 확인
  - 최소 Smoke 테스트 수행

## 테스트 참고
- 테스트 계획 및 수동 실행 기준은 `docs/test-plan.md`를 따른다.