3.9 KiB
3.9 KiB
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 저장 토큰: 로그인 세션 토큰 / 클라이언트 토큰 / 서비스 토큰
서비스 토큰 사용자 컨텍스트 정책:
- 서비스 토큰은 특정 사용자(
user_id)에 귀속되며token_type = 'service'로 식별된다. - 토큰 이름(
name)은 서비스 토큰 내에서 유일하며 CLI 관리의 기본 키로 사용된다. - 소유권이 필요한 포트폴리오 API에서 서비스 토큰은 귀속 사용자 경계 내에서만 동작한다.
서비스 토큰 CLI 관리
pfhub service-token issue <name> --user <username>— 서비스 토큰 발급 (기본 TTL 365일)pfhub service-token revoke <name>— 서비스 토큰 폐기
제약:
--ttl-days와--no-expiry동시 사용은 거부한다.- 동일 이름의 서비스 토큰은 중복 발급할 수 없다.
--user로 지정한 사용자가 존재하지 않으면 발급 실패 처리한다.
토큰 라이프사이클
- 사용자 로그인(
POST /auth/login) 또는 토큰 발급 API 호출 - 토큰 해시 저장 및 prefix 관리
- 요청 처리 시 해시 비교와 만료/폐기 상태 검증
DELETE /auth/tokens/{token_id}또는 서비스 토큰 폐기(pfhub service-token revoke)로 토큰 폐기
서비스 토큰 라이프사이클:
pfhub service-token issue <name> --user <username>실행 시--ttl-days/--no-expiry정책을 먼저 검증한다.- 정책 검증 후 서비스 계층에서 사용자 존재 및 이름 중복 여부를 검증한다.
- 발급 성공 시 원문 토큰은 1회만 출력된다.
pfhub service-token revoke <name>실행 시 확인 프롬프트(--force로 생략 가능)를 거쳐 폐기한다.
만기 정책:
- 기본 TTL은 365일이다.
--ttl-days와--no-expiry동시 사용은 거부한다.
감사 로그 정책:
issue/revoke는auth.bot_token이벤트를 감사 로그로 남긴다.- 감사 로그에는 마스킹된
token_id/token_ref만 기록한다. - issue 경로에서 감사 로그 기록이 실패하면 발급 토큰을 즉시 폐기하고 실패 처리한다.
- revoke 경로에서 감사 로그 기록이 실패해도 폐기는 유지하고 명령은 실패로 반환한다.
실패 응답 기준
- bearer 헤더 누락 또는 형식 오류:
401 - 알 수 없는 토큰:
401 - 권한 부족:
403
부트스트랩 사용자 규칙
PORTFOLIOHUB_BOOTSTRAP_USERNAME과PORTFOLIOHUB_BOOTSTRAP_PASSWORD가 설정되고 users 테이블이 비어 있으면 초기 admin을 1회 생성한다.- 이미 사용자가 존재하면 추가 생성하지 않는다.
Validation Notes
- 만료된 토큰은 항상 인증 실패로 처리해야 한다.
- 권한 계층 승격 우회가 없는지 API/CLI 양쪽에서 검증한다.
Open Implementation Points
- 정적 토큰과 DB 토큰의 우선순위/병합 정책을 명문화할지 결정한다.