# BAT-008 Design

- Status: confirmed
- Batch: BAT-008

## Architecture Summary
- 코드 변경 없이 baseline 4종 문서(`docs/interface-contract.md`, `docs/runtime-flows.md`, `docs/data-model.md`, `docs/project-structure.md`)를 편집한다.
- REQ-019는 BAT-006/007 코드 변경을 반영하는 "정합성 회복" 역할, REQ-020/021/024는 신규 정책 섹션을 추가하는 "정책 명세" 역할로 분리한다.

## Changed Areas
- Docs:
  - `docs/data-model.md` — auth_tokens 인덱스 조건 갱신, client token 제거
  - `docs/interface-contract.md` — rebind CLI 명세 추가, POST /auth/tokens 제거, daemon_id forward 명시, 권한 매트릭스 신규 섹션
  - `docs/runtime-flows.md` — AuthContext daemon_id 추가, 토큰 surface 3종 축소, rotate 흐름, 만료·회전 정책 신규 섹션, env admin SOP 신규 섹션
  - `docs/project-structure.md` — migrate-null-daemon CLI 서브커맨드, revoke_tokens_by_daemon_id 추가 반영 (필요 시)
- Modules: 없음 (코드 변경 없음)
- Interfaces: 없음

## Key Decisions

1. **파일별 REQ 담당 분리 (충돌 방지)**
   - `docs/data-model.md`: REQ-019 단독 담당 (인덱스 변경, client 타입 제거)
   - `docs/interface-contract.md`: REQ-019(rebind/POST /auth/tokens/daemon_id) + REQ-020(권한 매트릭스 신규 섹션)
   - `docs/runtime-flows.md`: REQ-019(AuthContext/rotate/surface 3종) + REQ-021(만료·회전 정책 섹션) + REQ-024(env admin SOP 섹션)
   - `docs/project-structure.md`: REQ-019(선택 — CLI/메서드 추가 반영)

2. **권한 매트릭스 구조 (REQ-020)**
   - 차원: token type(session/service/env) × 동사(issue/rotate/rebind/revoke/list) × 발급자 권한(admin/trade-write/read)
   - client token 제외 (REQ-016 폐지 반영)
   - admin 자기 발급 허용 + 최소 권한 권장 주석 포함 (dcy-004 OQ-4)
   - 매트릭스 위반 → HTTP 403 fail-closed (dcy-004 NFR-4)

3. **만료·회전 정책 섹션 위치 (REQ-021)**
   - `docs/runtime-flows.md`에 "토큰 만료·회전 정책" 섹션 신규 추가
   - type별 TTL: session=settings.session_token_ttl_hours, service=365일 default, env=만료 없음
   - no_expiry 허용 범위: service 한정, session 거부 시 ValueError/HTTP 422

4. **env admin SOP 위치 (REQ-024)**
   - `docs/runtime-flows.md`에 "env admin token 운영 SOP" 섹션 추가 (README.md 링크 선택)
   - 7단계 회전 절차 + rollback + token 강도 가이드 + 권장 회전 주기(분기)

5. **POST /auth/tokens 처리 방식 (REQ-019 AC-2)**
   - 명세 항목 완전 제거 (또는 "Deprecated: REQ-016에서 폐지" 표시로 잔존)
   - 구현 편의상 "Deprecated" 주석 표시 후 섹션 삭제하는 방식으로 진행

6. **project-structure.md 갱신 범위 (REQ-019)**
   - migrate-null-daemon CLI 서브커맨드 추가 사실 반영
   - `revoke_tokens_by_daemon_id`, `list_service_tokens_with_null_daemon` 저장소 메서드 추가 사실 반영
   - 파일 자체 신규 생성 없이 기존 섹션 보강

## Edge Cases
- REQ-021 no_expiry session 거부: 현행 코드에서 session 경로에 no_expiry 파라미터가 없어 코드 level 거부가 구현되지 않음 → 정책 문서에 "policy: 거부, code: 현행 미구현, follow-up 필요" 형태로 명시
- 매트릭스 코드 불일치 발견 시: REQ-020 AC-4에 따라 불일치 항목을 별도 follow-up으로 기록하고 매트릭스 본문에 "⚠ 불일치" 표시

## Architecture Impact
- none (문서 전용, 코드·런타임 변경 없음)

## Reference Doc Update Plan
- project-structure.md: CLI 서브커맨드·저장소 메서드 추가 사실 반영 (소규모 갱신)
- runtime-flows.md: 신규 정책 섹션 2개 추가 + AuthContext 갱신 + rotate 흐름 보강