portfolio-hub/docs/sdlc/sdlc-001_20240414_cli-bot-token-lifecycle-cli.design/3_design.md

0. 문서 상태

• 상태: confirmed
• 승인자: Justin
• 승인 시각: 2026-04-15

1. Design 개요

• 입력 Planning: pln-001
• 목적: CLI bot 토큰 발급/삭제 기능을 정책 일관성, 보안성, 운영성 기준으로 구현 가능하도록 인터페이스/흐름/검증 포인트를 확정한다.
• 설계 대상 작업 (WSJF 상위 3개):
  • 1순위: P-002 만기 정책 및 권한 가드 구현
  • 2순위: P-003 토큰 출력 마스킹 및 감사 로그 구현
  • 3순위: P-001 CLI bot 토큰 발급/삭제 명령 추가

2. 설계 대안 비교 (우선순위 상위 작업)

P-002: 만기 정책 및 권한 가드 구현

대안 A

• 설명: CLI 입력 단계(Typer 옵션 파싱/검증)에서 TTL 기본값, --no-expiry 상호배타성, 관리자 정책 검증을 선처리한다.
• 장점:
  • 잘못된 입력을 서비스 호출 전에 차단해 오류 원인이 명확하다.
  • 단위 테스트가 간단하며 사용자 피드백이 빠르다.
• 단점:
  • 정책 검증 로직이 CLI 계층에 치우치면 API 계층과 중복될 수 있다.

대안 B

• 설명: 정책 검증을 auth/service 계층에서 처리하고 CLI는 입력 전달만 수행한다.
• 장점:
  • 정책 소스가 단일화되어 API/CLI 일관성이 높다.
  • 다른 채널(예: 배치, API)에서도 동일 정책 재사용이 쉽다.
• 단점:
  • CLI 사용자 입장에서는 오류 맥락이 늦게 반환될 수 있다.
  • 서비스 에러를 CLI 친화 메시지로 재매핑하는 추가 코드가 필요하다.

선택 결정

• 선택: 대안 A+B 혼합
• 근거: 상호배타성/입력 형식 검증은 CLI에서 조기 차단하고, 권한 및 최종 만기 정책 강제는 서비스 계층에서 재검증해 정책 일관성과 UX를 동시에 확보한다.

P-003: 토큰 출력 마스킹 및 감사 로그 구현

대안 A

• 설명: 발급 응답 DTO 생성 시점에서 마스킹된 값만 남기고 원문을 폐기한다.
• 장점:
  • 출력/로그 경로를 일괄 통제해 원문 노출 위험이 낮다.
  • 후속 렌더링 계층(table/json)에서 추가 안전장치 부담이 줄어든다.
• 단점:
  • 발급 직후 1회 원문 출력 요구를 처리하기 위해 예외 흐름이 필요하다.

대안 B

• 설명: 출력 직전 렌더링 함수에서 마스킹을 적용하고 내부 모델에는 원문을 유지한다.
• 장점:
  • 기존 데이터 모델 변경이 적다.
  • 일부 디버깅 시 내부 상태 확인이 쉽다.
• 단점:
  • 로그/예외 경로에서 원문 누출 가능성이 높다.
  • 마스킹 누락 지점이 생기기 쉽다.

선택 결정

• 선택: 대안 A
• 근거: NFR-1/NFR-2와 R-3 완화 우선순위가 높아, 원문 보존 경로를 최소화하는 구조가 안전하다.

P-001: CLI bot 토큰 발급/삭제 명령 추가

대안 A

• 설명: 기존 user/portfolio/strategy와 동일하게 bot Typer group을 추가하고 token issue, token revoke 서브커맨드로 구성한다.
• 장점:
  • 현재 CLI 구조와 일관되어 학습 비용이 낮다.
  • 명령 확장(예: token list) 시 구조가 자연스럽다.
• 단점:
  • 초기 구현 시 커맨드 트리/도움말 정비가 필요하다.

대안 B

• 설명: 기존 user 그룹에 user bot-token issue/revoke 형태로 통합한다.
• 장점:
  • 새로운 최상위 그룹 추가가 없어 변경 범위가 작다.
• 단점:
  • 사용자 관리와 bot 토큰 수명주기가 섞여 명령 의미가 불명확해진다.

선택 결정

• 선택: 대안 A
• 근거: P-004의 UX 일관성 요구를 충족하고 장기 확장성(봇/토큰 명령 확장)에 유리하다.

3. 인터페이스 정의

P-002: 만기 정책 및 권한 가드 구현

• 입력: --ttl-days(optional), --no-expiry(flag), 실행자 컨텍스트(admin 여부)
• 출력: 정책 유효성 통과 시 정규화된 만기 정책 객체(expires_at 또는 never_expires=true)
• 오류 경로: 옵션 상충, 음수/0 TTL, 비관리자 --no-expiry 사용 시 검증 오류 반환

P-003: 토큰 출력 마스킹 및 감사 로그 구현

• 입력: 발급/삭제 결과 객체(token_id, raw_token optional, actor_id, bot_id, timestamp)
• 출력: 사용자 출력용 마스킹 토큰 값, 감사 로그 이벤트 레코드
• 오류 경로: 감사 로그 기록 실패 시 issue는 트랜잭션 롤백으로 발급을 취소하고 명령을 실패 처리한다. revoke는 보안 우선 원칙에 따라 폐기는 유지하고 명령은 실패 처리하며 운영 경고를 발생시킨다.

P-001: CLI bot 토큰 발급/삭제 명령 추가

• 입력: bot_id, 발급 옵션(--ttl-days/--no-expiry), 공통 옵션(--force, --format)
• 출력: issue 시 token_id/expires_at/revoked(false) + 1회 토큰 원문, revoke 시 token_id/revoked(true)
• 오류 경로: 미존재 bot/token, 권한 부족, 정책 위반, 저장소/서비스 예외

P-004: CLI UX 정합성 보강

• 입력: 커맨드 실행 컨텍스트(확인 프롬프트 응답, --force, 출력 모드)
• 출력: 표준화된 성공/실패 출력(table/json)
• 오류 경로: 포맷 미지원, 사용자 취소 시 정상 종료(code 0), 도메인 오류 시 비정상 종료(code != 0)

P-005: 테스트/문서 동기화

• 입력: 테스트 케이스 정의, docs sync 규칙 대상 파일 목록
• 출력: 테스트 결과 리포트, 업데이트된 README/API 계약 문서
• 오류 경로: 테스트 실패, docs sync 체크 실패, 누락 문서 갱신 감지

4. 데이터/흐름 설계

P-002: 만기 정책 및 권한 가드 구현

• 주요 데이터 경로:
  • CLI 옵션 파싱 -> 입력 검증 -> 서비스 계층 정책 재검증 -> repository 요청 페이로드 구성
• 상태 변화:
  • draft_policy -> validated_policy -> persistable_policy

P-003: 토큰 출력 마스킹 및 감사 로그 구현

• 주요 데이터 경로:
  • 서비스 발급/삭제 결과 -> 마스킹 변환 -> 출력 렌더링 + 감사 로그 sink 기록
• 상태 변화:
  • raw_token_state -> masked_view_state -> audited_state

P-001: CLI bot 토큰 발급/삭제 명령 추가

• 주요 데이터 경로:
  • command dispatch -> service 호출(issue/revoke) -> 결과 DTO -> renderer(table/json)
• 상태 변화:
  • issue: requested -> issued(active)
  • revoke: issued(active) -> revoked(inactive)

P-004: CLI UX 정합성 보강

• 주요 데이터 경로:
  • confirmation gate -> command executor -> unified output/error handler
• 상태 변화:
  • pending_confirmation -> executed 또는 cancelled

P-005: 테스트/문서 동기화

• 주요 데이터 경로:
  • code change set -> test run -> docs sync check -> verification evidence bundle
• 상태 변화:
  • unverified -> verified 또는 failed-with-evidence

5. 테스트 전략 연계 (AC 매핑)

작업 ID	AC	검증 방법	검증 포인트
P-002	AC-1	CLI 통합 테스트	ttl-days 미입력 시 expires_at이 현재+365일로 계산됨
P-002	AC-2	권한 예외 테스트	비관리자 컨텍스트에서 --no-expiry 요청 시 오류 코드/메시지 확인
P-002	AC-3	옵션 조합 검증 테스트	--ttl-days와 --no-expiry 동시 지정 시 검증 실패
P-003	AC-1	출력 스냅샷 테스트	issue 이후 재조회/목록 출력에서 앞6/뒤4 외 마스킹 확인
P-003	AC-2	감사 로그 검증 테스트	issue/revoke 각각에 actor/bot/token_id(마스킹)/결과 로그 생성 확인
P-003	AC-3	보안 회귀 테스트	로그 파일/콘솔에 raw token 미노출 확인
P-001	AC-1	커맨드 help 테스트	bot token issue, bot token revoke help 노출 확인
P-001	AC-2	성공 경로 E2E	issue 응답 필수 필드(token_id/expires_at/revoked) 존재 확인
P-001	AC-3	revoke E2E	revoke 이후 동일 토큰 인증 실패 확인
P-004	AC-1	UX 동작 테스트	기본 프롬프트 표시, --force 시 생략 확인
P-004	AC-2	예외 메시지 테스트	잘못된 bot/token 입력에서 사용자 지침 포함 메시지 확인
P-005	AC-1/AC-2	CI 파이프라인 검증	정상+예외 테스트 최소 1건씩 통과 및 docs sync 통과

6. 리스크 대응 설계

리스크 ID	리스크 내용	설계 대응 전략
R-1	만기 정책 모호성으로 무기한 토큰 남발 가능	CLI+서비스 이중 검증, 기본 TTL 365일 강제, --no-expiry 제한 경로 및 감사 로그 필수화
R-2	명령 체계 확장 시 오사용 가능	bot 전용 그룹으로 분리, help 명세 표준화, 오류 메시지에 다음 행동 가이드 포함
R-3	토큰 출력/로그 유출 위험	원문 1회 출력 후 즉시 마스킹 전환, 로그 저장 시 원문 금지, 보안 회귀 테스트 추가

7. Implementation 단계 전달 체크

• 우선순위 상위 작업의 설계 근거(대안 비교 + 선택 이유)가 존재함
• 전체 작업의 인터페이스(입력/출력/오류 경로)가 정의됨
• AC와 검증 포인트가 매핑됨
• Planning 리스크에 대한 설계 대응이 반영됨
• 최종 승인

8. 파일 처리 결과

• 생성/갱신 경로: docs/sdlc/design/dsn-001_2026-04-14_cli-bot-token-lifecycle-cli.design.md

9. 사용자 결정 필요 항목 요약

현재 미해결 플레이스홀더 없음