docs: add rel-005 production operator runbook and credential matrix (REQ-020~022)

Release: REL-005_20260512 — Production Operator Runbook and Credential Matrix Requirements Approved (REQ-020~022): - REQ-020: production admin bootstrap and steady-state operator access runbook (Deployment) - REQ-021: release credential matrix and token provenance procedures (Documentation) - REQ-022: operator log access and release evidence recording procedures (Documentation) Batch: BAT-009 - Enhance README.md Production Operator Runbook section with: - Deployment secret custodian role labels - Release approver and production operator role definitions - Credential matrix table (public/read/trade-write/admin permission levels) - Canonical smoke environment specifications - HTTP status code interpretation (401/403/404) - Release evidence recording fields Documentation Updates: - Add README.md Section 2: deployment roles and responsibilities - Add README.md Section 3: 4-tier credential matrix with token usage patterns - Enhance README.md Section 6: smoke test procedures and evidence capture - Add bootstrap/steady-state/break-glass 3-tier access pathway clarification - Create REQ-020 Deployment runbook document - Create REQ-021 credential matrix procedures document - Create REQ-022 operator log access procedures document Discovery & Release: - Update dcy-005 with operator access requirements analysis - Create rel-005 with docs-only profile and deployment notes - Update docs/batches/index.md with BAT-009 entry - Update docs/srs/index.md with REQ-020~022 entries and change log
2026-05-12 23:19:48 +00:00
parent 7bcf5cbb2b
commit 03bc3dcd8f
14 changed files with 748 additions and 63 deletions
@@ -0,0 +1,109 @@
+# 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 문서 기록 정책 준수 여부 확인
@@ -0,0 +1,114 @@
+# req-022: 운영 로그 접근 및 release evidence 기록 절차
+
+- Status: Approved
+- Type: Documentation
+- Priority: Medium
+- Owner: repository-maintainers
+
+## Intent
+- 운영자가 startup/request 로그 접근 경로와 auth/permission/resource 오류 판독 방법을 모르면 release smoke의 증적을 재현 가능하게 수집할 수 없고, 장애 시 원인 분류가 불가능해진다.
+- systemd journal 기반 canonical log access 경로와 401/403/404 구분 판독 기준, release evidence 기록 필드를 README.md에 정의한다.
+
+## Requirement
+- README.md Production Operator Runbook 섹션은 아래 로그 접근 및 evidence 기록 절차를 포함해야 한다.
+  1. **애플리케이션 startup/runtime 로그**: `sudo journalctl -u portfoliohub -n 200 --no-pager` 또는 `-f` 옵션으로 실시간 확인. primary log path.
+  2. **reverse proxy/access 로그**: `sudo journalctl -u caddy -n 200 --no-pager` 또는 `-f` 옵션. primary log path.
+  3. **Loki**: `LOKI_ENABLED`와 실제 수집 파이프라인이 운영 환경에서 확인된 경우에만 보조 집계 경로로 취급.
+  4. **auth/permission/resource 오류 구분**:
+     - 401: 인증 정보 없음 또는 만료 — bearer token 미제공 또는 유효하지 않은 token
+     - 403: 권한 부족 — token은 유효하나 해당 엔드포인트에 필요한 permission 미보유
+     - 404: 리소스 없음 — 인증/권한은 통과했으나 대상 리소스가 DB에 존재하지 않음
+  5. **release evidence 기록 필드**: 시각(executed_at, completed_at), 요청 경로, HTTP 상태 코드, 소스 시스템(journalctl unit name), 상관 가능한 요청 식별자. raw secret, raw token 값은 포함하지 않는다.
+- canonical acceptance smoke는 production에서 수행하고, staging smoke는 optional preflight로만 사용한다.
+- 절차의 source of truth는 README runbook으로 유지하고, 실행 evidence의 canonical record는 해당 release 문서에 남긴다.
+
+## Acceptance Criteria
+1. Given README.md Production Operator Runbook이 존재할 때, When 운영자가 로그 접근 절차를 참조할 때, Then `journalctl -u portfoliohub`와 `journalctl -u caddy`를 각각 어느 용도로 사용하는지가 명시되어 있어야 한다.
+2. Given release smoke 중 HTTP 오류가 발생했을 때, When 운영자가 오류를 분류할 때, Then README runbook에 401(인증 없음), 403(권한 부족), 404(리소스 없음)의 의미가 분리되어 재현 가능하게 설명되어 있어야 한다.
+3. Given release 문서에 evidence를 기록할 때, When smoke 실행 결과를 기재할 때, Then 시각, 요청 경로, HTTP 상태 코드, 소스 시스템 필드가 포함되고 raw secret은 포함되지 않아야 한다.
+4. Given canonical acceptance 환경이 명시되어 있을 때, When 운영자가 smoke 환경을 선택할 때, Then production이 canonical acceptance이고 staging은 optional preflight임이 README runbook에 명시되어 있어야 한다.
+
+## Impacted Area
+- Docs: `README.md` — Production Operator Runbook 로그 접근 절차 및 오류 구분 기준 보강
+- Modules: 없음 (문서화 중심 REQ)
+- Tests: 없음
+
+## Notes
+- NFR-2 (401/403/404 구분 설명): AC-2에 흡수.
+- NFR-1 (raw credential 비노출): AC-3에 흡수.
+- 외부 URL만으로는 startup log 접근이 불가능하다는 제약을 README에 명시해야 한다. (REL-001 Deployment Facts 참조)
+- Loki 관련 설정(`LOKI_ENABLED`, `LOKI_URL`)은 `app/core/config.py`에 존재하지만 현재 production에서 활성화가 확인되지 않으므로 기본 표준 경로로 다루지 않는다.
+- Source Discovery: dcy-005 FR-3
+
+## 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-3 기반)
+
+#### Intent
+- 운영 로그 접근 및 release evidence 기록 절차 문서화 요구사항 정의
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~4 초안 생성
+
+#### Impacted Area Delta
+- Docs:
+  - README.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: none
+
+#### Validation Plan
+- README.md journalctl 명령 존재 및 401/403/404 구분 기술 확인
+- release evidence 기록 필드 정책 준수 확인