feat: Refresh Token 회전·로그아웃과 안전한 데모 인증 기반 구현

[hywznn]

왜 필요한가요?

Closes #4

PR #33에서 구현한 로그인·JWT·사업장 권한 기반 위에 Access Token 재발급과 로그아웃을 완성합니다. Refresh Token 재사용·동시 요청·쿠키 보안 정책을 명시하지 않으면 탈취된 토큰이나 중복 재발급이 새 로그인 상태를 계속 만들 수 있고, 데모 환경의 초기 계정도 안전하게 준비하기 어렵습니다.

무엇이 바뀌나요?

• API·도메인·DB 변경:
  • POST /api/v1/auth/refresh: HttpOnly 쿠키 전용 Refresh Token rotation
  • POST /api/v1/auth/logout: token family 폐기와 멱등 204
  • 사용·만료·폐기·알 수 없는 Refresh Token은 외부에 동일한 401 INVALID_REFRESH_TOKEN 반환
  • 원본 Refresh Token은 응답 JSON·DB·일반 로그에 저장하지 않고 SHA-256 hash만 사용
  • 기존 V2 Auth schema를 그대로 사용하며 새 migration은 없음
• 권한·보안 변경:
  • token family 단위 비관적 잠금과 재사용 탐지 시 family 전체 폐기
  • CSRF/Origin 보호 전에는 Refresh 쿠키의 SameSite=None을 금지하고 Strict·Lax만 허용
  • 로그아웃은 다른 로그인 family를 폐기하지 않음
  • 오류 응답도 삭제 쿠키와 Cache-Control: no-store 반환
• 감사·운영 변경:
  • 로그인·재발급·재사용·family 폐기·로그아웃의 privacy-safe typed event와 AuthAuditPort 정의
  • 현재 adapter는 request_id가 포함된 안전한 진단 로그이며 append-only 영구 저장은 #11에서 연결
  • 기본 비활성인 opt-in 데모 Company·ADMIN Seed 추가
  • Seed 비밀번호는 환경 Secret이 필수이며 BCrypt hash만 저장하고 기존 계정을 덮어쓰지 않음
• 문서 변경:
  • OpenAPI, README, ADR-0002, .env.example에 canonical path, cookie 계약, single-flight, JWT 만료 정책과 Seed 방법 반영

어떻게 검증했나요?

• ./gradlew clean test
• ./gradlew build
• Health·OpenAPI 애플리케이션 통합 테스트
• 정상 로그인·재발급·로그아웃
• 누락·변조·만료·폐기·재사용 토큰
• VIEWER 쓰기 권한 거부
• 다른 사업장 리소스 은닉
• 로그아웃 멱등성과 로그인 family 격리
• 데모 Seed 멱등성·비밀번호 hash 저장
• GitHub Actions의 실제 PostgreSQL 동시성 테스트

로컬 전체 테스트와 build가 통과했습니다. 로컬에는 PostgreSQL/Docker가 없어 PostgreSQL 전용 테스트는 skip됩니다. GitHub Actions의 실제 PostgreSQL 환경에서 동일 토큰 동시 요청이 정확히 200 1건 + 401 1건인지 검증했고 통과했습니다.

보안·개인정보

• DTO·로그·AI 입력에 불필요한 개인정보가 없습니다.
• JWT, Refresh Token 원문, API Key, 비밀번호를 저장소와 로그에 남기지 않습니다.
• 사용자 조회는 user_id + company_id를 함께 검증합니다.
• 인증 실패가 계정·토큰 존재 여부를 외부에 구분해 주지 않습니다.
• Auth 보안 이벤트에는 안전한 ID와 action·시각만 전달합니다.
• ADR-0002의 canonical API·tenant·오류 계약을 따릅니다.
• Server에 Prompt Builder·Provider SDK·모델 routing을 추가하지 않았습니다.

API·DB·운영 영향

• Client는 로그인·재발급·로그아웃에 credentials: "include"를 사용해야 합니다.
• 여러 API가 동시에 401을 받아도 Refresh 요청은 single-flight로 한 번만 보내야 합니다.
• 로그아웃 뒤 기존 stateless Access Token은 기본 TTL 기준 최대 15분 유효하므로 Client가 즉시 삭제해야 합니다.
• DB migration은 추가하지 않았고, PR #33의 V2 refresh_token 제약과 index를 사용합니다.
• 새 환경변수 이름만 .env.example에 추가했으며 실제 Seed 비밀번호는 포함하지 않았습니다.
• 롤백은 이 PR을 revert하고 DEMO_SEED_ENABLED=false를 유지하면 됩니다. 새 migration이 없어 DB rollback은 필요하지 않습니다.

응답 예시

{
  "access_token": "<redacted-jwt>",
  "token_type": "Bearer",
  "expires_in_seconds": 900,
  "expires_at": "2026-07-22T01:15:00Z"
}

새 Refresh Token은 위 JSON에 포함되지 않고 Set-Cookie로만 전달됩니다.

[hywznn]

로그인 기능을 최대한 고도화 해봤습니다 한번 나중에 어디다가 써먹어보려구여

Refresh Token Rotation, Token Family, 재사용 탐지(Re-use Detection), HttpOnly 쿠키, 토큰 해시 저장, 동시 재발급 제어(Single-flight/동시성 제어)까지 포함되어 있어, JWT 인증 시스템에서 중요한 보안 요구사항들을 종합적으로 반영한 구현