baron-sso/docs/AGENTS.md

AGENTS 가이드 (Baron SSO)

목적

• Inbound Auth/Launcher와 관리(Admin) 기능을 하나의 백엔드에서 운영하되, 네임스페이스·도메인·권한으로 강하게 분리한다.
• 사용자 플로우(가입/로그인)와 관리 플로우(Descope Management Key 사용)를 명확히 구분해 보안 사고면을 축소한다.

현재 원칙

• 경계 분리: /admin/* + admin 서브도메인에서만 관리 기능 노출. 일반 사용자 번들과 관리자 번들(또는 라우트)을 분리.
• 관리 키 취급: Descope Management Key는 서버 내부에서만 사용, 비동기 잡/관리 API에서 래핑. 모든 관리 액션을 감사 로그/알람/레이트리밋으로 보호.
• 권한/가드: role/permission 기반 접근 제어. 관리자 세션 TTL은 짧게, step-up MFA 고려.

인증 플로우 핵심

• 최초 회원가입: SMS 인증(Enchanted Link/OTP) 필수 → 인증 성공 후 계정 생성 및 초기 세션 발급.
• 재로그인 분기 (앱 세션 보유 + 사용자 선택):
  • 앱 로그인 상태 + 사용자가 “앱 승인” 선택: 앱을 MFA/IDPW 대체 수단으로 사용(푸시/딥링크 승인) → 승인 시 웹 세션 발급.
  • 앱 세션이 없거나, 사용자가 이번 로그인에서 앱을 사용하지 않기로 선택: SMS 또는 이메일/비밀번호 경로로 진행.
• 세션 TTL: 앱 기반 세션 유지시간을 APP_SESSION_TTL_MINUTES 환경 변수로 관리(기본 예: 30분).

작업 시 체크리스트

• 관리 기능 개발 시 admin 네임스페이스, 권한 체크, 감사 로깅, 레이트리밋을 기본 포함.
• 인증/로그인 변경 시 “폴백은 사용자 선택일 때만” 규칙을 준수하고, UI에도 선택 흐름을 노출.
• 새 설정/비밀값은 .env.sample에 반영하고 서버에서만 소비하게 설계한다.