portfolio-hub/docs/srs/Documentation/req-024_env-admin-token-rotation-sop.md

REQ-024: env admin token 운영 SOP 정의

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

Intent

• 현행 env admin token(PORTFOLIOHUB_ADMIN_TOKENS 환경 변수)의 회전·폐기·강도 기준이 baseline에 명시되지 않아 운영 단계에서 회전이 잘못 적용되면 운영자 admin 접근이 차단될 수 있는 운영 리스크가 있다(dcy-004 R-4).
• dcy-004 OQ-6 결정에 따라 분기(3개월) 권장 회전 주기, 강제 회전 없음 정책으로 SOP를 baseline에 명시한다.

Requirement

• docs/runtime-flows.md 또는 README.md에 "env admin token 운영 SOP" 섹션을 추가한다. 명시 항목:
  • 권장 회전 주기: 분기(3개월). 강제 회전·만료 알람 없음. 운영자 자율로 회전 시점 결정.
  • 회전 트리거 조건: (a) 정기(분기), (b) token leak 의심, (c) 운영자 교체·퇴사, (d) 보안 사고 대응.
  • 다단계 회전 절차:
    1. 강한 무작위 token 생성: python3 -c "import secrets; print(secrets.token_urlsafe(48))"
    2. PORTFOLIOHUB_ADMIN_TOKENS에 신규 token을 콤마 분리로 추가(다중 token 동시 운영)
    3. service rolling restart
    4. 신규 token으로 admin 호출 검증(예: GET /health, admin 작업 sanity check)
    5. 구 token을 PORTFOLIOHUB_ADMIN_TOKENS에서 제거
    6. service rolling restart(구 token 무효화)
    7. evidence 기록(회전 일자, 운영자, 신규 token 강도 확인, sanity check 결과)
  • rollback 절차: 회전 실패 시 환경 변수에 구 token 재추가 후 rolling restart. fallback admin 접근 경로(예: DB 직접 접근으로 token 재생성) 보장.
  • 운영자 권한 매트릭스: env admin token 추가/제거는 인프라 운영자 권한. release approver 또는 운영자 교체 시 SOP를 참조.
  • token 강도 가이드: 최소 48-byte URL-safe 무작위. 평문 단어·예측 가능한 패턴(예: admin-token-789) 금지.
• SOP는 dev/test 환경과 prod 환경 모두에 적용되며, prod 환경의 약한 placeholder token이 발견된 경우(R-7) 본 SOP를 즉시 적용하도록 권고한다.

Acceptance Criteria

1. Given docs/runtime-flows.md 또는 README.md 검토, When 본 REQ 구현 후, Then "env admin token 운영 SOP" 섹션이 존재하고 권장 회전 주기 + 강제 회전 없음 정책이 명시된다.
2. Given SOP의 다단계 회전 절차 항목, When 검토, Then 7단계(token 생성 → 추가 → restart → 검증 → 구 token 제거 → restart → evidence 기록)가 명시된다.
3. Given SOP의 rollback 절차 항목, When 검토, Then 회전 실패 시 환경 변수 복구 + fallback admin 접근 경로 명시.
4. Given SOP의 token 강도 가이드, When 검토, Then 최소 48-byte URL-safe 무작위 요구 + 약한 placeholder 금지 명시.
5. Given staging 환경에서 SOP에 따라 dry-run 회전 실행, When 7단계 절차 수행, Then 각 단계가 실제 환경에서 적용 가능함이 확인된다(release plan verification).

Impacted Area

• Docs:
  • docs/runtime-flows.md — "env admin token 운영 SOP" 섹션 신규 추가 (또는 README.md에 추가 후 runtime-flows에서 참조)
  • README.md — daemon provisioning runbook에 env admin token SOP 링크 추가 (선택)
• Modules: 없음 (정책 baseline 문서. 코드 변경 없음. 환경 변수 자체는 운영 작업)
• Tests: 없음 (문서 전용. AC-5는 release plan verification 영역)

Notes

• dcy-004 R-7(prod 환경 약한 admin token)은 본 SOP의 첫 번째 적용 사례로, dcy-004 confirm-discovery 시점 또는 이전에 운영자가 본 SOP의 7단계 절차를 적용해 admin-token-789를 강한 무작위 값으로 교체하기를 권고. hotfix 추적은 dcy-004 §10 DATA_PROD_ADMIN_TOKEN_HOTFIX 항목으로 관리.
• env admin token 다중 운영 허용은 현행 app/core/auth.py:_resolve_permission이 set 기반으로 처리하므로 코드 변경 없이 가능(app/core/auth.py:43-50).
• 본 SOP는 prod 환경 적용을 우선으로 작성됐으나 dev/test 환경에서도 약한 placeholder 사용을 금지한다. dev 환경 사용자는 secrets.token_urlsafe 또는 동등한 강도의 값을 생성해 .env 파일에 보관.
• Source: dcy-004 FR-9, dcy-004 OQ-6 결정.

Change Log

CHG-20260521-01

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

Change Summary

• Status: Approved → Implemented

Intent

• BAT-008 confirm-batch-verification 완료: AC-1~4 검증됨(grep + 사람 리뷰). docs/runtime-flows.md에 "env admin token 운영 SOP" 섹션 신규 추가 확인. AC-5(staging dry-run)는 release plan verification 영역으로 분리됨.

Acceptance Criteria Delta

• No change

Impacted Area Delta

• No change

Delivery Trace Delta

• Batches: BAT-008 (release-candidate)
• Releases: none (미정)

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: promote-to-implemented
• Follow-up Action: AC-5(staging dry-run)는 release plan verification 단계에서 수행

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-9 산출물.

Intent

• env admin token 운영 SOP source of truth 확보 + 분기 권장 회전 주기 baseline 명시 + dcy-004 R-7 hotfix 표준 절차 정의.

Acceptance Criteria Delta

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

Impacted Area Delta

• Docs: docs/runtime-flows.md, README.md — 최초 지정
• Modules: 없음
• Tests: 없음

Delivery Trace Delta

• Batches: none (미정)
• Releases: none (미정). dcy-004 R-7 hotfix는 본 REQ confirm-req 이전이라도 본 SOP 절차로 즉시 적용 권장.

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req 후 batch 계획 편입; REQ-019/020/021과 동일 batch 권장

Validation Plan

• 사람 리뷰로 AC-1~4 검증; AC-5는 staging 환경 dry-run으로 release plan 검증