genichinandClaude Sonnet 4.6
4bf6b554a7
dcy-003/004 기반 v1 API surface 완성 및 BAT-008~011 구현·검증 완료:
- BAT-008 (REQ-019~021,024): 토큰 surface baseline 문서 갱신
- BAT-009 (REQ-025~028): POST/PATCH/DELETE/GET /v1/portfolios CRUD 신설
- _require_write_token, _get_portfolio_or_404, soft delete, daemon-scoped list
- BAT-010 (REQ-030~032): portfolio tag/comment 서브 라우트 신설 + baseline 갱신
- GET/POST/DELETE /v1/portfolios/{id}/tags
- POST/GET/PATCH/DELETE /v1/portfolios/{id}/comments
- BAT-011 (REQ-029): ledger path migration
- POST /v1/assets/{asset_id}/ledger/trades → /v1/portfolios/{portfolio_id}/ledger/trades
- v1_ledger.py 제거, disabled 차단(409) 추가
- test_v1.py / test_daemon_assignment.py 구 path 갱신
- 신규 tests: test_v1_portfolios_crud.py, test_v1_portfolios_list.py,
test_v1_portfolios_tags_comments.py, test_v1_portfolios_ledger.py
- 전체 suite: 340 passed
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
134 lines
6.7 KiB
Markdown
134 lines
6.7 KiB
Markdown
# 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](app/core/auth.py#L43-L50)).
|
|
- 본 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 검증
|