refactor docs into technical specs

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

@@ -0,0 +1,54 @@
+# Auth and Token Lifecycle
+
+- Related REQ: N/A
+
+## 목표
+정적 토큰과 DB 발급 토큰을 병행하는 현재 인증 모델의 동작 기준을 명확히 한다.
+
+## 권한 모델
+
+| Permission | 허용 범위 |
+| --- | --- |
+| `read` | 조회 계열 API |
+| `trade-write` | 조회 + 포트폴리오 변경 API |
+| `admin` | 전체 API + 사용자/봇 관리 |
+
+## 인증 방식
+
+- 보호된 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)에 토큰 발급/폐기 이벤트를 표준 포맷으로 남길지 확정한다.