portfolio-hub/docs/srs/Interface/req-005_service-token-runtime-id-issuance.md

req-005: service-token 발급 시 runtime_id 동시 생성

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

Intent

• trex-basic 계열 consumer는 runtime_id를 런타임 세대 식별자로 사용하되, asset assignment와 운영 provenance는 stable daemon_id를 기준으로 추적해야 한다.
• service-token 발급 시 runtime_id를 새로 생성하면서도, 토큰은 기존 daemon registry에 존재하는 daemon_id에 바인딩되어 저장되어야 한다.
• CLI(pfhub service-token issue)와 API 엔드포인트 양쪽에서 발급 결과에 runtime_id와 daemon_id가 함께 포함되어야 한다.

Requirement

• pfhub service-token issue CLI 커맨드와 대응 API 엔드포인트(POST /auth/service-tokens)는 service-token 발급 시 고유 runtime_id를 생성하고, 기존 daemon registry에 존재하는 daemon_id에 토큰을 바인딩해 auth_tokens에 함께 저장한 뒤 발급 결과(token, runtime_id, daemon_id)를 반환해야 한다.
• 발급 경로는 unknown daemon 자동 생성 또는 upsert를 허용하면 안 되며, binding 대상은 사전에 생성된 daemon registry entry여야 한다.
• runtime_id는 발급마다 새로 생성되는 런타임 식별자이고, daemon_id는 rotate/재기동과 무관하게 유지되는 stable logical identity다.

Acceptance Criteria

1. Given pfhub service-token issue <name> --user <username> --daemon-id <daemon_id> 실행 시, When 발급이 성공하면, Then 출력에 token 문자열, runtime_id, daemon_id가 모두 포함되어야 한다.
2. Given API 엔드포인트(POST /auth/service-tokens)로 existing daemon_id를 지정해 service-token 발급 시, When 성공 응답을 받으면, Then 응답 JSON에 token, runtime_id, daemon_id가 포함되어야 한다.
3. Given runtime_id와 daemon_id가 발급된 service-token으로 GET /v1/user_info를 호출하면, Then 응답의 runtime_id, daemon_id가 발급 시 저장된 값과 동일해야 한다.
4. Given 동일 daemon에 대해 두 번의 service-token 발급을 수행하면, Then 각각 다른 runtime_id가 반환되어야 하고 daemon_id는 요청한 binding 값을 유지해야 한다.
5. Given auth_tokens 테이블을 직접 조회하면, Then 발급된 service-token 행에 runtime_id와 daemon_id 값이 모두 저장되어 있어야 한다.
6. Given 존재하지 않는 daemon_id로 service-token 발급을 요청하면, Then 명시적 validation 오류가 반환되어야 하고 auth_tokens 행은 생성되지 않아야 한다.

Impacted Area

• Docs: docs/runtime-flows.md, docs/interface-contract.md (REQ-011에서 갱신 예정), README.md token provenance 절차 (REQ-021에서 갱신 예정)
• Modules: app/cli/commands/service_tokens.py, app/schemas/auth.py, app/api/auth_routes.py, app/domain/models.py, app/services/auth_service.py, app/repositories/portfolio_repository.py, app/repositories/postgres.py
• Tests: tests/test_auth.py, tests/test_cli.py, tests/test_v1.py

Notes

• runtime_id 포맷은 UUID v4를 권장한다. 설계 단계에서 확정한다.
• auth_tokens 테이블의 runtime_id, daemon_id 컬럼 및 daemon registry 스키마는 REQ-009 migration에서 처리한다.
• daemon provisioning(create/update)은 별도 관리 경로에서 수행하며, issue 경로는 binding만 담당한다.
• 기존 daemon-less service-token은 transition 구간에서 daemon_id = NULL로 남을 수 있고, daemon-scoped API에서는 fail-closed로 처리한다.
• Source Discovery: dcy-002 (FR-2, A-2), dcy-006 (FR-1, FR-5, NFR-1)

Change Log

CHG-20260513-01

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

Change Summary

• runtime_id-only service-token 발급 요구사항을 existing daemon binding + daemon_id diagnostics 포함 구조로 확장하고, 기존 Implemented 상태를 Approved로 되돌림

Intent

• dcy-006에서 runtime_id는 runtime identity, daemon_id는 stable logical identity로 역할이 분리됐다. 현재 BAT-001/REL-001 구현은 runtime_id만 저장·노출하므로 revised issuance contract와 daemon-scoped authorization 전제를 충족하지 못한다.

Acceptance Criteria Delta

• Added:
  • AC-6: unknown daemon_id 발급 요청 거부
• Updated:
  • AC-1~5: CLI/API issue, /v1/user_info, DB persistence 기준을 daemon_id binding 포함으로 재정의
• Removed:
  • none

Impacted Area Delta

• Docs:
  • docs/runtime-flows.md, docs/interface-contract.md — issue flow와 response contract에 daemon_id 추가 필요
  • README.md — daemon-aware provenance 절차 반영 필요
• Modules:
  • app/cli/commands/service_tokens.py, app/schemas/auth.py, app/api/auth_routes.py, app/services/auth_service.py, app/repositories/portfolio_repository.py, app/repositories/postgres.py
• Tests:
  • tests/test_auth.py, tests/test_cli.py, tests/test_v1.py

Delivery Trace Delta

• Batches:
  • BAT-001 (release-candidate; REL-001 released input) — runtime_id-only issuance evidence는 daemon binding 요구사항 기준으로 재설계 및 재검증 필요
• Releases:
  • REL-001 (released) — service-token issuance release evidence가 revised REQ를 충족하지 않으므로 후속 app-service release가 필요

Revalidation Impact

• Reverification Needed: yes
• Existing Implementation Invalidated: yes
• Status Recommendation: rollback-to-approved
• Follow-up Action: dcy-006 후속 batch에서 daemon registry binding, issue API/CLI contract, /v1/user_info diagnostics를 함께 구현하고 재검증한다.

Validation Plan

• dcy-006 FR-1/FR-5와 app/services/auth_service.py, app/api/auth_routes.py, app/cli/commands/service_tokens.py의 현재 구현 차이를 코드 리뷰로 대조한다.
• 구현 후 tests/test_auth.py, tests/test_cli.py, tests/test_v1.py에 daemon-bound issuance/user_info 케이스를 추가해 targeted validation을 수행한다.

CHG-20260511-02

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

Change Summary

• REQ-005 AC-2의 API 경로를 실제 구현 경로인 POST /auth/service-tokens로 명확화

Intent

• CONFLICT-4 분석 결과를 반영해 "POST /auth/tokens 또는 동등 경로"라는 모호한 표현을 제거하고, BAT-001 verification과 runtime flow에 이미 반영된 실제 엔드포인트로 REQ를 정렬한다.

Acceptance Criteria Delta

• Added:
  • none
• Updated:
  • AC-2: API 발급 경로를 POST /auth/service-tokens로 구체화
• Removed:
  • none

Impacted Area Delta

• Docs:
  • docs/srs/Interface/req-005_service-token-runtime-id-issuance.md: AC-2 경로 문구 명확화
• Modules:
  • none
• Tests:
  • none

Delivery Trace Delta

• Batches:
  • BAT-001 (release-candidate) — verification evidence는 이미 POST /auth/service-tokens 기준으로 정렬되어 있어 추가 재검증은 불필요
• Releases:
  • REL-001 (draft) — release scope 문서도 동일 경로를 사용 중이라 추가 수정 없음

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: none

Validation Plan

• REQ-005 AC-2, BAT-001 verification evidence, runtime-flows.md의 API 경로가 모두 POST /auth/service-tokens로 일치하는지 코드 리뷰로 확인

CHG-20260511-01

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

Change Summary

• Implemented 전환 — BAT-001 re-verified verification passed, confirm-req-implemented 게이트 통과

Intent

• BAT-001 verification.md (re-verified, 2026-05-03) AC-1~5 모두 PASS. Blocking Issues 없음. AC5 DB 미확인은 REQ-009와 동일 제약으로 non-blocker 처리.

Acceptance Criteria Delta

• none

Impacted Area Delta

• none

Delivery Trace Delta

• Batches: BAT-001 (release-candidate)
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: implemented
• Follow-up Action: draft-release (BAT-001)

Validation Plan

• BAT-001 verification.md (re-verified) AC-1~5 evidence 연결 확인 완료

CHG-20260502-02

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

Change Summary

• REQ-005 confirm-req 승인 전환 (Status: Proposed → Approved)

Intent

• 필수 필드(Status, Type, Priority, Owner, Intent, Requirement, Acceptance Criteria 5개, Impacted Area, Change Log) 모두 충족 확인 후 승인

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: keep-current
• Follow-up Action: suggest-batch-reqs → draft-batch

CHG-20260502-01

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

Change Summary

• REQ-005 최초 생성 (source Discovery: dcy-002 FR-2)

Intent

• service-token 발급 시 runtime_id 동시 생성 요구사항을 REQ backlog로 정규화

Acceptance Criteria Delta

• Added:
  • 전체 Acceptance Criteria 신규 작성

Impacted Area Delta

• Docs:
  • docs/runtime-flows.md (REQ-011에서 갱신 예정)
• Modules:
  • app/cli/commands/service_tokens.py
  • app/api/auth_routes.py
  • app/domain/models.py
• Tests:
  • tests/test_auth.py 확장 또는 tests/test_service_tokens.py 신규

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-009 migration과 함께 delivery 단위 구성 권장.