portfolio-hub/docs/srs/Interface/req-015_broker-credential-cli.md

req-015: CLI credential 명령 그룹 구현 (브로커 인증 정보 관리)

• Status: Implemented
• Type: Interface
• Priority: Medium
• Owner: repository-maintainers

Intent

• 운영자가 CLI(pfhub credential)를 통해 KIS 브로커 인증 정보를 안전하게 등록, 조회, 삭제할 수 있어야 한다.
• broker_credentials 테이블(migration 0014)과 기존 Fernet 암호화 인프라(app/core/encryption.py, CREDENTIAL_ENCRYPTION_KEY)를 재사용해 CLI 레이어만 추가한다.

Requirement

• 시스템은 pfhub credential set --user <username> --broker <broker> --account-ref <ref> --app-key <key> --app-secret <secret> 명령을 제공해야 한다. 이 명령은 {"app_key": ..., "app_secret": ...} JSON을 Fernet으로 암호화한 뒤 broker_credentials 테이블에 upsert한다.
• 시스템은 pfhub credential list --user <username> 명령을 제공해야 한다. 이 명령은 사용자의 브로커 인증 정보 목록을 반환하되, encrypted_payload는 출력하지 않는다.
• 시스템은 pfhub credential remove --user <username> --broker <broker> [--force] 명령을 제공해야 한다. 이 명령은 해당 인증 정보 레코드를 삭제한다.
• 존재하지 않는 사용자를 지정하면 에러 메시지와 함께 exit code 1로 종료해야 한다.

Acceptance Criteria

1. Given alice 사용자와 유효한 CREDENTIAL_ENCRYPTION_KEY가 설정된 환경에서, When pfhub credential set --user alice --broker kis --account-ref REF --app-key KEY --app-secret SECRET을 실행하면, Then broker_credentials 테이블에 암호화된 payload로 레코드가 생성(또는 갱신)된다.
2. Given broker_credentials에 alice의 kis 레코드가 있을 때, When pfhub credential list --user alice를 실행하면, Then broker, account_ref, credential_version, last_rotated_at이 출력되고 encrypted_payload는 포함되지 않는다.
3. Given 존재하지 않는 username을 지정할 때, When pfhub credential set --user unknown ...을 실행하면, Then 에러 메시지와 함께 exit code 1로 종료된다.
4. Given alice의 kis 인증 정보가 있을 때, When pfhub credential remove --user alice --broker kis --force를 실행하면, Then 해당 레코드가 삭제되고 pfhub credential list --user alice에서 더 이상 표시되지 않는다.
5. Given CREDENTIAL_ENCRYPTION_KEY가 설정되지 않은 환경에서, When pfhub credential set ...을 실행하면, Then 설정 미비 에러 메시지와 함께 exit code 1로 종료된다.

Impacted Area

• Docs: docs/project-structure.md (CLI 모듈 목록 갱신)
• Modules:
  • app/cli/commands/credential.py (신규 — credential_app, set, list, remove 명령)
  • app/cli/main.py (credential_app 등록 추가)
  • app/repositories/postgres.py (delete_broker_credential 메서드 추가)
• Tests: tests/test_cli.py (credential 명령 통합 테스트 추가)

Notes

• broker_credentials 테이블 DDL과 upsert_broker_credential, list_broker_credentials, get_broker_credential 메서드는 migration 0014에서 이미 구현됨. delete_broker_credential 메서드는 이번 REQ에서 추가.
• app/core/encryption.py의 encrypt_payload(key, plaintext) 사용.
• 기존 CLI 패턴(_with_service 헬퍼, execute_command, render_output, _confirm) 동일하게 적용.
• --broker 기본값은 kis.

Change Log

CHG-20260511-01

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

Change Summary

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

Intent

• BAT-005 verification.md에서 REQ-015 AC-1~5가 모두 passed이고 regression 없음이 확인되어 Implemented로 승격한다.

Acceptance Criteria Delta

• Added: none
• Updated: none
• Removed: none

Impacted Area Delta

• Docs: none
• Modules: none
• Tests: none

Delivery Trace Delta

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

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: implemented
• Follow-up Action: tooling release에 포함 시 credential smoke 절차 포함

Validation Plan

• BAT-005 verification.md의 AC-1~5 passed evidence와 residual risk 없음 확인

CHG-20260503-02

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

Change Summary

• REQ-015 Approved 전환 — minor-change fast path (단일 저위험 REQ, CLI 레이어만 추가, 구조/런타임 영향 없음)

Intent

• Acceptance Criteria 5개 모두 구현 판단에 충분하며 blocking assumption 없음

Acceptance Criteria Delta

• Added: none
• Updated: none
• Removed: none

Impacted Area Delta

• Docs: none
• Modules: none
• Tests: none

Delivery Trace Delta

• Batches: BAT-005 (batch-lite)
• Releases: 미정

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: run-batch-implementation 진행

Validation Plan

• BAT-005 verification 통과 확인

---

CHG-20260503-01

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

Change Summary

• REQ-015 최초 작성 — CLI credential 명령 그룹 구현 (브로커 인증 정보 관리)

Intent

• 운영자가 KIS 브로커 인증 정보를 CLI로 관리할 수 있도록 Interface 레이어 추가

Acceptance Criteria Delta

• Added:
  • 위 Acceptance Criteria 1~5 전체
• Updated: none
• Removed: none

Impacted Area Delta

• Docs: docs/project-structure.md
• Modules: app/cli/commands/credential.py (신규), app/cli/main.py, app/repositories/postgres.py
• Tests: tests/test_cli.py

Delivery Trace Delta

• Batches: 미정 (BAT-005 예정)
• Releases: 미정

Revalidation Impact

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

Validation Plan

• tests/test_cli.py에 credential 명령 통합 테스트 작성 후 pytest tests/test_cli.py 전체 통과 확인