portfolio-hub/docs/srs/Documentation/req-021_release-credential-matrix-and-token-provenance-procedures.md

req-021: release 검증 credential matrix 및 token provenance 운영 절차

• Status: Approved
• Type: Documentation
• Priority: High
• Owner: repository-maintainers

Intent

• release 검증에 사용하는 credential의 용도, 발급 주체, 보관 위치, 폐기 절차가 정의되지 않으면 smoke 재현성이 없어지고 secret leakage 위험이 높아진다.
• public/no-auth, read service-token, trade-write service-token, admin auth context 4개 credential 관점의 matrix를 문서화하고, 기존 CLI/API를 token provenance 확인 canonical path로 명시한다.

Requirement

• README.md Production Operator Runbook 또는 연결된 운영 문서는 아래 credential matrix를 명시해야 한다.
  • public/no-auth: GET /health, /docs, /openapi.json. 인증 불필요. 배포 직후 공개 smoke에 사용.
  • read service-token: GET /v1/assets, GET /v1/user_info. 환경 단위 운영 credential. 발급: admin context로 POST /auth/service-tokens. 보관: /opt/portfoliohub/.env 또는 동일 접근 통제 하 운영 절차. 공동 소유자: release approver / repository-maintainers.
  • trade-write service-token: POST /v1/assets/{asset_id}/ledger/trades. 환경 단위 운영 credential. 발급: admin context로 POST /auth/service-tokens. 보관: read token과 동일 정책. 공동 소유자: release approver / repository-maintainers.
  • admin auth context: POST /auth/service-tokens. 운영자 개인 소유. 공유 금지. 발급: steady-state는 /auth/login 경유 DB-issued session, break-glass는 env token.
• release 문서에는 name, token_prefix, permission, runtime_id, issued_at, revoked_at만 기록하고 raw token값은 기록하지 않는다.
• 운영자는 pfhub service-token list, pfhub service-token issue, pfhub service-token rotate, pfhub user get, GET /v1/user_info를 token provenance 확인 canonical support path로 사용한다. 각 명령의 출력 필드(name, token_prefix, token_id, user_id, permission, created_at, last_used_at, revoked_at, runtime_id)를 provenance 확인 기준으로 명시한다.

Acceptance Criteria

1. Given README.md 또는 연결된 운영 문서가 존재할 때, When 운영자가 credential matrix를 참조할 때, Then public/read/trade-write/admin 4개 credential의 용도, 발급 주체, 보관 위치, 공동 소유 역할이 구분되어 기술되어 있어야 한다.
2. Given release 문서(docs/releases/*.md)가 존재할 때, When smoke evidence를 기록할 때, Then name, token_prefix, permission, runtime_id, issued_at, revoked_at 필드만 남기고 raw token 값은 포함되지 않아야 한다.
3. Given 운영자가 service-token provenance를 확인할 때, When pfhub service-token list를 실행할 때, Then name, permission, created_at, last_used_at, revoked_at 필드가 출력되고, GET /v1/user_info의 runtime_id와 대조해 배포된 토큰의 provenance를 재현 가능하게 확인할 수 있어야 한다.
4. Given admin auth context가 필요한 smoke를 수행할 때, When 운영자가 credential matrix를 따를 때, Then admin context는 개인 소유로 취급되고 read/trade-write token은 release approver 역할과 공동 소유 형태로 관리되는 것이 문서에 명시되어 있어야 한다.

Impacted Area

• Docs: README.md — credential matrix 항목 및 token provenance CLI 절차 추가/보강
• Modules: app/api/v1_user_info.py (runtime_id 반환 확인), app/cli/commands/service_token.py (list/rotate 출력 필드 확인)
• Tests: 없음 (문서화 중심 REQ)

Notes

• NFR-1 (raw credential 비노출): 이 REQ의 핵심 제약. AC-2에 명시.
• FR-4와 FR-2를 통합한 REQ. token provenance 확인 수단과 credential matrix는 운영자가 같은 맥락에서 참조하므로 분리 시 중복이 발생한다.
• runtime_id는 service-token rotate 후 변경되므로 rotate 후 consumer가 재조회해야 한다는 사실도 matrix 문서에 포함할 것을 권장 (REQ-012 CHG-20260511-01 참조).
• Source Discovery: dcy-005 FR-2, FR-4

Change Log

CHG-20260512-02

• Date: 2026-05-12
• Author: repository-maintainers

Change Summary

• Status: Proposed → Approved (confirm-req 게이트 통과)

Intent

• 필수 필드, AC, Notes blocker 없음 확인 후 승인 전환

Acceptance Criteria Delta

• Added: 없음
• Updated: 없음
• Removed: 없음

Impacted Area Delta

• Docs: 없음
• 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: none

Validation Plan

• 승인 전환만 수행, 추가 검증 불필요

CHG-20260512-01

• Date: 2026-05-12
• Author: repository-maintainers

Change Summary

• REQ 초안 생성 (dcy-005 FR-2, FR-4 통합 기반)

Intent

• release 검증 credential matrix 및 token provenance 확인 절차 문서화 요구사항 정의

Acceptance Criteria Delta

• Added:
  • AC-1~4 초안 생성

Impacted Area Delta

• Docs:
  • README.md credential matrix 및 token provenance 절차
• 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: none

Validation Plan

• README.md credential matrix 항목 구분 및 token provenance CLI 절차 존재 확인
• release 문서 기록 정책 준수 여부 확인