BaronSSO/baron-sso/docs/AGENTS.md

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.-를 따른다.