portfolio-hub/docs/srs/Documentation/req-019_token-surface-baseline-docs-consistency.md

REQ-019: 토큰 surface baseline 문서 정합성 회복

• Status: Approved
• Type: Documentation
• Priority: Medium
• Owner: Justin Ko

Intent

• 현행 baseline 문서가 토큰 surface 결함(rebind 명세 누락, AuthContext daemon_id 필드 누락) + 본 batch 변경 사항(client token 폐지, rotate index 보강, HTTP daemon_id forward, auth_tokens 인덱스 변경)을 모두 반영해 후속 REQ·batch가 단일 source of truth로 사용할 수 있도록 정합성을 회복한다.
• dcy-004 FR-4와 FR-10을 단일 REQ로 통합 처리한다(둘 다 baseline 갱신 작업).

Requirement

• docs/interface-contract.md 갱신:
  • pfhub service-token rebind CLI 명세 추가(app/cli/commands/service_tokens.py:119-141 구현 반영)
  • POST /auth/tokens(client token 발급) 명세 제거(REQ-016 처리 반영)
  • POST /auth/service-tokens body daemon_id forward 동작 명시(REQ-018 처리 반영)
• docs/runtime-flows.md 갱신:
  • AuthContext 필드 목록에 daemon_id 추가(docs/runtime-flows.md:76 보강)
  • 토큰 surface 3종(session/service/env)으로 축소 반영
  • rotate runtime_id 갱신 + daemon_id invariant 보존 흐름 명시(REQ-017 처리 반영)
• docs/data-model.md 갱신:
  • auth_tokens 인덱스 변경(idx_auth_tokens_service_name_unique에 AND revoked_at IS NULL 조건 추가) 반영
  • 토큰 타입 surface 정리(client 제거)
• docs/project-structure.md 갱신:
  • 신규 마이그레이션 스크립트 또는 CLI 서브커맨드(REQ-022 자동 revoke, REQ-023 NULL daemon 마이그레이션) 추가에 따른 패키지 책임 갱신 — 필요 시
• 갱신은 baseline 정합성 회복에 한정한다. 새 정책 정의(매트릭스, TTL 정책, SOP)는 REQ-020/021/024가 별도로 다룬다.

Acceptance Criteria

1. Given grep -n "service-token rebind" docs/interface-contract.md, When 본 REQ 구현 후, Then 명세 entry가 1건 이상 발견된다.
2. Given grep -n "POST /auth/tokens" docs/interface-contract.md, When 본 REQ 구현 후, Then client token 발급 명세가 제거되어 0건이거나 deprecated 표시로만 잔존한다.
3. Given grep -n "AuthContext.*daemon_id\|daemon_id.*AuthContext" docs/runtime-flows.md, When 본 REQ 구현 후, Then AuthContext 필드 목록에 daemon_id가 명시된다.
4. Given grep -n "revoked_at IS NULL\|active service token" docs/data-model.md, When 본 REQ 구현 후, Then idx_auth_tokens_service_name_unique 변경 사항이 반영되어 발견된다.
5. Given 사람 리뷰, When baseline 4종 문서를 점검, Then client token 잔재(예: token_type='client' 발급 경로 언급)가 모두 제거되거나 deprecated 표시되어 있다.

Impacted Area

• Docs:
  • docs/interface-contract.md
  • docs/runtime-flows.md
  • docs/data-model.md
  • docs/project-structure.md (필요 시)
• Modules: 없음 (문서 전용)
• Tests: 없음 (문서 전용. AC-1~5는 grep + 사람 리뷰)

Notes

• 본 REQ는 REQ-016/017/018/022/023 코드 변경 후 또는 동일 batch에서 함께 처리하는 것이 적절하다. baseline 문서가 코드 변경 사항을 반영하지 않으면 후속 REQ/batch가 잘못된 source of truth를 참조한다.
• 본 REQ는 surface 정합성 회복만 다루고 신규 정책 명세는 다음 REQ에서 처리:
  • REQ-020: 토큰 발급 권한 매트릭스
  • REQ-021: 토큰 만료·회전 정책
  • REQ-024: env admin token 운영 SOP
• Source: dcy-004 FR-4, dcy-004 FR-10.

Change Log

CHG-20260520-02

• Date: 2026-05-20
• Author: Justin Ko

Change Summary

• Status: Proposed → Approved

Intent

• 승인 게이트 통과: 필수 필드(Status/Type/Priority/Owner/Intent/Requirement/AC/Impacted Area/Change Log) 모두 충족, AC 구체성 확인 완료, blocker 없음

Acceptance Criteria Delta

• No change

Impacted Area Delta

• No change

Delivery Trace Delta

• Batches: none (미정)
• Releases: none (미정)

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: promote-to-approved
• Follow-up Action: batch 계획 편입

CHG-20260520-01

• Date: 2026-05-20
• Author: Justin Ko

Change Summary

• 최초 생성 — dcy-004 confirm-discovery 후 draft-req 실행. dcy-004 FR-4 + FR-10 통합 산출물.

Intent

• 토큰 surface baseline 4종 문서의 정합성 회복(rebind 명세 누락, AuthContext daemon_id 누락, client token 잔재 제거, auth_tokens 인덱스 변경 반영).

Acceptance Criteria Delta

• Added:
  • AC-1~5 최초 작성

Impacted Area Delta

• Docs: docs/interface-contract.md, docs/runtime-flows.md, docs/data-model.md, docs/project-structure.md — 최초 지정
• Modules: 없음
• Tests: 없음

Delivery Trace Delta

• Batches: none (미정)
• Releases: none (미정)

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req 후 batch 계획 편입; REQ-016/017/018/022/023 코드 변경 후 또는 동일 batch에서 처리

Validation Plan

• grep 명령 + 사람 리뷰로 AC-1~5 검증