# AGENTS 가이드 (Baron SSO)

## 버그 수정 절차 대원칙 (강제)
- 버그 대응 시 **재현 테스트를 먼저 작성**합니다.
- 재현 테스트가 실패하는 상태를 확인한 뒤에만 수정 작업을 시작합니다.
- 수정 후에는 테스트를 반복 실행하여 재현 테스트가 안정적으로 통과할 때까지 계속 보완합니다.
- 재현 테스트 없이 “감으로 수정”하거나, 실패 테스트를 남긴 채 성공으로 보고하지 않습니다.
- 이슈 종료 전에는 최소 1회 이상 실제 사용자 경로(예: 로그인/새로고침/리다이렉트)를 확인합니다.
- 테스트/원인/조치 내역은 문서(`docs/test-plan/*`, `docs/trouble-shooting/*`)에 반영합니다.

## 목적
- 인증/인가 허브로서 **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` 경로에서 처리
- 토큰/쿠키 전달 방식 변경 시 `https://gitea.hmac.kr/baron/baron-sso/wiki/Authentication-and-Login-Flow.-`를 반드시 갱신

## 작업 체크리스트
- 인증/로그인 변경 시
  - `https://gitea.hmac.kr/baron/baron-sso/wiki/Authentication-and-Login-Flow.-` 업데이트
  - 세션/쿠키/Authorization 전달 방식 영향도 점검
  - UserFront가 Ory/Oathkeeper 직접 호출하지 않도록 확인

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

- 환경 변수 추가/변경 시
  - `.env.sample` 반영
  - 문서/가이드 갱신
  - 클라이언트 로그 정책 영향 확인 (`CLIENT_LOG_DEBUG`, `USERFRONT_DEBUG_LOG`)

- 배포/운영 변경 시
  - `Makefile`/compose 실행 절차 영향 확인
  - 최소 Smoke 테스트 수행
  - 로그 수집 레벨이 운영 기본 정책(`WARN/ERROR`)을 유지하는지 확인

## 클라이언트 로그 정책
- 상세 정책은 `docs/client-log-policy.md`를 기준으로 유지합니다.
- 원칙:
  - 운영 기본값은 `WARN/ERROR`만 수집
  - 운영 디버그는 `CLIENT_LOG_DEBUG=true`로만 일시 허용
  - 민감정보 마스킹은 환경과 무관하게 항상 적용

## 테스트 참고
- 테스트 계획 및 수동 실행 기준은 `https://gitea.hmac.kr/baron/baron-sso/wiki/Test-Plan-and-Principles.-`를 따른다.