feat: 주요 CLI, 인증, 서비스 로직 및 문서 개선

docs/sdlc/implementation/imp-001_2026-04-15_cli-bot-token-lifecycle-cli.implementation.md

@@ -0,0 +1,109 @@
+# 0. 문서 상태
+- 상태: draft
+- 승인자: 고진환
+- 승인 시각: {{CONFIRM: 승인 후 기재}}
+
+# 1. Implementation 개요
+- 입력 Design: dsn-001
+- 목적: CLI bot 토큰 발급/삭제 기능을 설계 기준에 따라 작은 구현 단위로 분해하고, Verification 단계에 즉시 전달 가능한 검증 근거를 준비한다.
+- 이번 구현 우선순위 작업:
+  - 1순위: P-002 만기 정책 및 권한 가드 구현
+  - 2순위: P-003 토큰 출력 마스킹 및 감사 로그 구현
+  - 3순위: P-001 CLI bot 토큰 발급/삭제 명령 추가
+
+# 2. 이번 구현 범위
+## In Scope
+- `bot token issue`, `bot token revoke` CLI 명령 추가 및 help 노출
+- `--ttl-days`/`--no-expiry` 입력 검증(상호배타, 값 범위)과 서비스 계층 정책 재검증
+- 기본 TTL 365일 정책 반영 및 비관리자 무기한 토큰 금지
+- issue/revoke 결과의 마스킹 출력 처리 및 감사 로그 기록 경로 구현
+- revoke 확인 프롬프트/`--force` 분기와 표준 출력(table/json) 정합성 반영
+- 정상/예외 테스트 및 문서 동기화 반영
+
+## Out of Scope
+- bot token list/rotate 등 신규 명령 확장
+- 감사 로그 저장소 아키텍처 재설계(외부 로그 파이프라인 교체 포함)
+- API 채널의 대규모 인터페이스 재정의
+
+# 3. 작업 단위 분해
+| Impl ID | 작업명 | 연결 설계/AC | 변경 유형 | 우선순위 | 상태 |
+|---|---|---|---|---|---|
+| I-001 | bot 토큰 CLI 그룹/서브커맨드 골격 추가 | P-001 AC-1 | 코드(명령 라우팅) | High | 완료 |
+| I-002 | issue 입력 옵션 검증(상호배타/범위) | P-002 AC-3 | 코드(입력 검증) | High | 완료 |
+| I-003 | 만기 정책 서비스 재검증 및 기본 TTL 365일 적용 | P-002 AC-1, AC-2 | 코드(도메인/서비스) | High | 완료 |
+| I-004 | issue/revoke 서비스 호출 및 결과 DTO 정규화 | P-001 AC-2, AC-3 | 코드(서비스 통합) | High | 완료 |
+| I-005 | 토큰 출력 마스킹 정책 적용(원문 1회 출력 후 차단) | P-003 AC-1, AC-3 | 코드(출력/보안) | High | 완료 |
+| I-006 | 감사 로그 이벤트 기록 및 실패 분기 처리 | P-003 AC-2 | 코드(로깅/오류 처리) | Medium | 완료 |
+| I-007 | revoke UX 가드(확인 프롬프트, --force, 오류 메시지) | P-004 AC-1, AC-2 | 코드(UX/CLI) | Medium | 완료 |
+| I-008 | 테스트/문서 동기화 및 근거 번들 준비 | P-005 AC-1/AC-2 | 테스트+문서 | High | 완료 |
+
+# 4. 파일 변경 계획
+| Impl ID | 대상 파일 | 변경 목적 | 변경 종류(생성/수정) | 상태 |
+|---|---|---|---|---|
+| I-001 | app/cli/main.py | `bot` 그룹 등록 및 커맨드 엔트리 연결 | 수정 | 완료 |
+| I-001 | app/cli/commands/bot_tokens.py | `token issue/revoke` 커맨드 골격 정의 | 생성 | 완료 |
+| I-002 | app/cli/commands/bot_tokens.py | `--ttl-days`/`--no-expiry` 검증 로직 추가 | 수정 | 완료 |
+| I-003 | app/services/auth_service.py | 만기 정책 재검증, 기본 TTL/권한 정책 강제 | 수정 | 완료 |
+| I-003 | app/domain/services.py | 정책 객체 정규화 규칙 보완(필요 시) | 수정 | 완료 |
+| I-004 | app/services/auth_service.py | issue/revoke 결과 DTO 필드 정규화 | 수정 | 완료 |
+| I-004 | app/schemas/auth.py | 응답 스키마(`token_id/expires_at/revoked`) 정렬 | 수정 | 완료 |
+| I-005 | app/cli/core/output.py | table/json 출력 시 마스킹 렌더링 추가 | 수정 | 완료 |
+| I-006 | app/core/security.py | 감사 로그 payload 표준화 및 민감정보 필터링 | 수정 | 완료 |
+| I-006 | app/repositories/postgres.py | 감사 로그 쓰기 경로(트랜잭션 연계) 보강 | 수정 | 완료 |
+| I-007 | app/cli/commands/bot_tokens.py | revoke 확인 프롬프트, `--force` 분기, 사용자 지침 메시지 | 수정 | 완료 |
+| I-008 | tests/test_cli.py | bot token help/성공/취소 흐름 테스트 추가 | 수정 | 완료 |
+| I-008 | tests/test_auth.py | 정책 검증(관리자/비관리자/no-expiry) 테스트 추가 | 수정 | 완료 |
+| I-008 | tests/test_app.py | 출력 마스킹 및 보안 회귀 시나리오 보강 | 수정 | 완료 |
+| I-008 | README.md | CLI 사용 예시 및 정책 제약 문서화 | 수정 | 완료 |
+| I-008 | docs/technical/auth-and-token-lifecycle.md | 토큰 수명주기/감사 로그 동작 반영 | 수정 | 완료 |
+
+# 5. 테스트/검증 계획
+| Impl ID | 검증 방법 | 성공 기준 | 근거 |
+|---|---|---|---|
+| I-001 | CLI help 테스트 | `bot token issue/revoke`가 help에 노출된다 | `tests/test_cli.py` |
+| I-002 | 옵션 조합 예외 테스트 | `--ttl-days`와 `--no-expiry` 동시 입력 시 실패한다 | `tests/test_auth.py` |
+| I-003 | 권한/기본값 테스트 | 기본 TTL 365일, 비관리자 `--no-expiry` 차단 | `tests/test_auth.py` |
+| I-004 | 성공 경로 통합 테스트 | issue 응답에 `token_id/expires_at/revoked`가 존재한다 | `tests/test_cli.py` |
+| I-005 | 출력 스냅샷/회귀 테스트 | 재출력/로그에 raw token이 노출되지 않는다 | `tests/test_app.py` |
+| I-006 | 감사 로그 실패 분기 테스트 | issue는 롤백 실패 처리, revoke는 폐기 유지+경고를 만족한다 | `tests/test_auth.py` |
+| I-007 | UX 동작 테스트 | revoke 시 확인 프롬프트, `--force` 시 생략, 취소는 code 0 | `tests/test_cli.py` |
+| I-008 | 회귀+문서 동기화 확인 | 변경 경로 테스트 통과 및 문서 업데이트 반영 | 테스트 실행 로그 + 변경 문서 diff |
+
+# 6. 영향도 및 의존성 점검
+| 항목 | 영향 내용 | 대응 방안 |
+|---|---|---|
+| 코드 | CLI 진입점, 인증 서비스, 출력/로깅 경로가 동시에 변경되어 회귀 범위가 넓다 | 단위+통합 테스트를 분리 실행하고 민감정보 노출 회귀 테스트를 추가한다 |
+| 문서 | CLI 사용법과 토큰 수명주기 운영 규칙이 불일치할 수 있다 | README/기술문서를 같은 변경 세트에서 동기 갱신한다 |
+| 설정/의존성 | 로그 sink/DB 쓰기 실패 시 issue/revoke 실패 정책이 다르므로 운영 혼선 위험이 있다 | 실패 분기 정책을 테스트로 고정하고 운영 경고 기준을 문서에 명시한다 |
+
+# 7. Verification 단계 전달 체크
+- [x] 구현 범위가 설계 문서와 연결됨
+- [x] 작업 단위별 검증 방법이 정의됨
+- [x] 영향 파일과 의존성 점검 결과가 기록됨
+- [x] Verification에 전달할 실행/검증 근거가 정의됨
+- [ ] 최종 승인
+  - {{CONFIRM: Implementation 초안 승인 여부를 확인하라}}
+
+# 8. 파일 처리 결과
+- 생성 경로: app/cli/commands/bot_tokens.py
+- 생성 경로: app/cli/core/output.py
+- 수정 경로: app/cli/main.py
+- 수정 경로: app/services/auth_service.py
+- 수정 경로: app/domain/services.py
+- 수정 경로: app/schemas/auth.py
+- 수정 경로: app/core/security.py
+- 수정 경로: app/repositories/postgres.py
+- 수정 경로: tests/test_cli.py
+- 수정 경로: tests/test_auth.py
+- 수정 경로: tests/test_app.py
+- 수정 경로: README.md
+- 수정 경로: docs/technical/auth-and-token-lifecycle.md
+- 수정 경로: docs/sdlc/implementation/imp-001_2026-04-15_cli-bot-token-lifecycle-cli.implementation.md
+
+# 9. 사용자 결정 필요 항목 요약
+## {{CONFIRM}} (2건)
+- 승인 후 기재 (위치: #0)
+- Implementation 초안 승인 여부를 확인하라. (위치: #7)
+
+## {{DATA}}
+- 현재 미해결 플레이스홀더 없음

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

@@ -64,6 +64,26 @@
 3. 요청 처리 시 해시 비교와 만료/폐기 상태 검증
 4. `DELETE /auth/tokens/{token_id}` 또는 봇 비활성화로 토큰 폐기
 
+CLI 봇 토큰 라이프사이클:
+
+1. `bot token issue <bot_id>` 실행 시 `--ttl-days`/`--no-expiry` 정책을 먼저 검증한다.
+2. 정책 검증 후 서비스 계층에서 권한과 만기 정책을 재검증한다.
+3. 발급 성공 시 응답은 마스킹된 토큰만 재출력 가능하며, 원문 토큰은 1회 출력 경로로 제한한다.
+4. `bot token revoke <bot_id> <token_id>` 실행 시 확인 프롬프트(`--force`로 생략 가능)를 거쳐 폐기한다.
+
+만기 정책:
+
+- 기본 TTL은 365일이다.
+- `--ttl-days`와 `--no-expiry` 동시 사용은 거부한다.
+- 비관리자 컨텍스트에서는 `--no-expiry`를 거부한다.
+
+감사 로그 정책:
+
+- `issue/revoke`는 `auth.bot_token` 이벤트를 감사 로그로 남긴다.
+- 감사 로그에는 마스킹된 `token_id/token_ref`만 기록한다.
+- issue 경로에서 감사 로그 기록이 실패하면 발급 토큰을 즉시 폐기하고 실패 처리한다.
+- revoke 경로에서 감사 로그 기록이 실패해도 폐기는 유지하고 명령은 실패로 반환한다.
+
 ## 실패 응답 기준
 
 - bearer 헤더 누락 또는 형식 오류: `401`