From f993cebf01e04f06d1665b9a8c13a3906491ff64 Mon Sep 17 00:00:00 2001 From: Jinhwan Ko Date: Wed, 15 Apr 2026 00:06:50 +0900 Subject: [PATCH] docs: confirm design draft dsn-001 --- ...4-14_cli-bot-token-lifecycle-cli.design.md | 171 ++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 docs/sdlc/design/dsn-001_2026-04-14_cli-bot-token-lifecycle-cli.design.md diff --git a/docs/sdlc/design/dsn-001_2026-04-14_cli-bot-token-lifecycle-cli.design.md b/docs/sdlc/design/dsn-001_2026-04-14_cli-bot-token-lifecycle-cli.design.md new file mode 100644 index 0000000..339954e --- /dev/null +++ b/docs/sdlc/design/dsn-001_2026-04-14_cli-bot-token-lifecycle-cli.design.md @@ -0,0 +1,171 @@ +# 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 단계 전달 체크 +- [x] 우선순위 상위 작업의 설계 근거(대안 비교 + 선택 이유)가 존재함 +- [x] 전체 작업의 인터페이스(입력/출력/오류 경로)가 정의됨 +- [x] AC와 검증 포인트가 매핑됨 +- [x] Planning 리스크에 대한 설계 대응이 반영됨 +- [x] 최종 승인 + +# 8. 파일 처리 결과 +- 생성/갱신 경로: docs/sdlc/design/dsn-001_2026-04-14_cli-bot-token-lifecycle-cli.design.md + +# 9. 사용자 결정 필요 항목 요약 +현재 미해결 플레이스홀더 없음