portfolio-hub/docs/technical/auth-and-token-lifecycle.md

Auth and Token Lifecycle

• Related REQ: REQ-004

목표

정적 토큰과 DB 발급 토큰을 병행하는 현재 인증 모델의 동작 기준을 명확히 한다.

권한 모델

Permission	허용 범위
read	조회 계열 API
trade-write	조회 + 포트폴리오 변경 API
admin	전체 API + 사용자/봇 관리

소유권 결합 정책:

• admin이 아닌 주체는 포트폴리오 접근 시 리소스 소유주(owner_user_id) 일치 조건을 추가로 만족해야 한다.
• admin은 소유권 제약 없이 전체 포트폴리오를 접근할 수 있다.

인증 방식

• 보호된 API는 Authorization: Bearer <token> 헤더를 사용한다.
• 인증 소스는 정적 토큰과 DB 저장 토큰을 병행한다.

권한 계층:

• admin은 전체 엔드포인트 접근 가능
• trade-write는 trade-write와 read 범위 접근 가능
• read는 조회 엔드포인트만 접근 가능

인증 소스

• 환경변수 기반 정적 토큰: PORTFOLIOHUB_*_TOKENS
• DB 저장 토큰: 로그인 세션/클라이언트 토큰/봇 토큰

토큰 라이프사이클

1. 사용자 로그인(POST /auth/login) 또는 토큰 발급 API 호출
2. 토큰 해시 저장 및 prefix 관리
3. 요청 처리 시 해시 비교와 만료/폐기 상태 검증
4. DELETE /auth/tokens/{token_id} 또는 봇 비활성화로 토큰 폐기

실패 응답 기준

• bearer 헤더 누락 또는 형식 오류: 401
• 알 수 없는 토큰: 401
• 권한 부족: 403

부트스트랩 사용자 규칙

• PORTFOLIOHUB_BOOTSTRAP_USERNAME과 PORTFOLIOHUB_BOOTSTRAP_PASSWORD가 설정되고 users 테이블이 비어 있으면 초기 admin을 1회 생성한다.
• 이미 사용자가 존재하면 추가 생성하지 않는다.

Validation Notes

• 만료된 토큰은 항상 인증 실패로 처리해야 한다.
• 비활성 봇(is_active=false)의 토큰은 거부되어야 한다.
• 권한 계층 승격 우회가 없는지 API/CLI 양쪽에서 검증한다.

Open Implementation Points

• 정적 토큰과 DB 토큰의 우선순위/병합 정책을 명문화할지 결정한다.
• 감사 로그(audit trail)에 토큰 발급/폐기 이벤트를 표준 포맷으로 남길지 확정한다.