작업 내용 저장

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

@@ -11,7 +11,7 @@
 | --- | --- |
 | `read` | 조회 계열 API |
 | `trade-write` | 조회 + 포트폴리오 변경 API |
-| `admin` | 전체 API + 사용자/봇 관리 |
+| `admin` | 전체 API + 사용자/서비스토큰 관리 |
 
 소유권 결합 정책:
 
@@ -31,51 +31,42 @@
 
 ## 인증 소스
 - 환경변수 기반 정적 토큰: `PORTFOLIOHUB_*_TOKENS`
-- DB 저장 토큰: 로그인 세션/클라이언트 토큰/봇 토큰
+- DB 저장 토큰: 로그인 세션 토큰 / 클라이언트 토큰 / 서비스 토큰
 
-봇 토큰 사용자 컨텍스트 정책:
+서비스 토큰 사용자 컨텍스트 정책:
 
-- 봇 principal은 `owner_user_id`를 가진다.
-- 봇 토큰 인증 시 실효 사용자 식별자는 `bot_principals.owner_user_id`로 해석한다.
-- 따라서 소유권이 필요한 포트폴리오 API에서 봇 토큰은 소유 사용자 경계 내에서만 동작한다.
+- 서비스 토큰은 특정 사용자(`user_id`)에 귀속되며 `token_type = 'service'`로 식별된다.
+- 토큰 이름(`name`)은 서비스 토큰 내에서 유일하며 CLI 관리의 기본 키로 사용된다.
+- 소유권이 필요한 포트폴리오 API에서 서비스 토큰은 귀속 사용자 경계 내에서만 동작한다.
 
-## 봇 관리 API 정책
+## 서비스 토큰 CLI 관리
 
-- Admin 경로:
-	- `POST /auth/bots`
-	- `GET /auth/bots`
-	- `GET /auth/bots/{bot_id}`
-	- `DELETE /auth/bots/{bot_id}`
-	- `POST/GET/DELETE /auth/bots/{bot_id}/tokens*`
-- Self-service 경로(사용자 본인 전용):
-	- `POST /auth/me/bots`
-	- `GET /auth/me/bots`
-	- `POST/GET/DELETE /auth/me/bots/{bot_id}/tokens*`
+- `pfhub service-token issue <name> --user <username>` — 서비스 토큰 발급 (기본 TTL 365일)
+- `pfhub service-token revoke <name>` — 서비스 토큰 폐기
 
 제약:
 
-- self-service 경로는 DB 사용자 컨텍스트가 있는 사용자 토큰에서만 허용한다.
-- self-service 경로는 요청자의 소유 봇(`owner_user_id == auth_context.user_id`)에만 허용한다.
-- 봇 권한은 `read` 또는 `trade-write`만 허용한다.
+- `--ttl-days`와 `--no-expiry` 동시 사용은 거부한다.
+- 동일 이름의 서비스 토큰은 중복 발급할 수 없다.
+- `--user`로 지정한 사용자가 존재하지 않으면 발급 실패 처리한다.
 
 ## 토큰 라이프사이클
 1. 사용자 로그인(`POST /auth/login`) 또는 토큰 발급 API 호출
 2. 토큰 해시 저장 및 prefix 관리
 3. 요청 처리 시 해시 비교와 만료/폐기 상태 검증
-4. `DELETE /auth/tokens/{token_id}` 또는 봇 비활성화로 토큰 폐기
+4. `DELETE /auth/tokens/{token_id}` 또는 서비스 토큰 폐기(`pfhub service-token revoke`)로 토큰 폐기
 
-CLI 봇 토큰 라이프사이클:
+서비스 토큰 라이프사이클:
 
-1. `bot token issue <bot_id>` 실행 시 `--ttl-days`/`--no-expiry` 정책을 먼저 검증한다.
-2. 정책 검증 후 서비스 계층에서 권한과 만기 정책을 재검증한다.
-3. 발급 성공 시 응답은 마스킹된 토큰만 재출력 가능하며, 원문 토큰은 1회 출력 경로로 제한한다.
-4. `bot token revoke <bot_id> <token_id>` 실행 시 확인 프롬프트(`--force`로 생략 가능)를 거쳐 폐기한다.
+1. `pfhub service-token issue <name> --user <username>` 실행 시 `--ttl-days`/`--no-expiry` 정책을 먼저 검증한다.
+2. 정책 검증 후 서비스 계층에서 사용자 존재 및 이름 중복 여부를 검증한다.
+3. 발급 성공 시 원문 토큰은 1회만 출력된다.
+4. `pfhub service-token revoke <name>` 실행 시 확인 프롬프트(`--force`로 생략 가능)를 거쳐 폐기한다.
 
 만기 정책:
 
 - 기본 TTL은 365일이다.
 - `--ttl-days`와 `--no-expiry` 동시 사용은 거부한다.
-- 비관리자 컨텍스트에서는 `--no-expiry`를 거부한다.
 
 감사 로그 정책:
 
@@ -96,9 +87,7 @@ CLI 봇 토큰 라이프사이클:
 
 ## Validation Notes
 - 만료된 토큰은 항상 인증 실패로 처리해야 한다.
-- 비활성 봇(`is_active=false`)의 토큰은 거부되어야 한다.
 - 권한 계층 승격 우회가 없는지 API/CLI 양쪽에서 검증한다.
 
 ## Open Implementation Points
 - 정적 토큰과 DB 토큰의 우선순위/병합 정책을 명문화할지 결정한다.
-- 감사 로그(audit trail)에 토큰 발급/폐기 이벤트를 표준 포맷으로 남길지 확정한다.