portfolio-hub/docs/discovery/dcy-010_20260627_daemon-scoped-broker-credential-provisioning.md

0. 문서 상태

이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.

• 상태: confirmed
• 문서 ID: dcy-010_20260627_daemon-scoped-broker-credential-provisioning
• 이슈명: daemon-scoped 브로커(KIS) 인증정보 소유·전달 — 다중 인스턴스 trex-core가 daemon별 다른 계좌로 거래 (교차 발원 trex-core 중장기 멀티 인스턴스)
• 작성 시각(KST): 2026-06-27
• 마지막 갱신 시각(KST): 2026-06-28
• 대체됨: 없음
• 후속 Discovery 참조: trex-core 소비자측 day-start fetch + fail-safe 로드 = 별도 trex-core Discovery로 분리 확정(2026-06-28). trex-core repo에 신규 Discovery 생성 예정(미생성).
• 생성된 REQ 참조: REQ-046, REQ-047, REQ-048, REQ-049, REQ-050, REQ-051

1. 계획 상태 요약

현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.

• 연계 문서 현황:
  • 관련 점수 파일: 미생성
  • 관련 TODO/메모: TREX 워크스페이스 M3 메인 목표(중장기 trex-core 인스턴스 추가). GitHub org 보드 fourblocks2020/trex #7. 교차 발원 = trex-core 멀티 인스턴스(instance_key) + dcy-008(WAC cost-basis seed)
• 해석:
  • 사장님이 "다중 인스턴스 trex-core를 완벽히 지원하려면 KIS API 인증정보를 portfolio-hub에서 받아야 하고, 그 인증정보는 universe와 동일하게 daemon_id로 매칭되어야 한다"고 방향을 확정했다. 현재 portfolio-hub는 broker 인증정보를 user_id 단위로만 소유해(broker_credentials PK=(user_id,broker)) 같은 user의 두 데몬에 서로 다른 계좌를 줄 수 없다.
  • 이번 Discovery에서 판단할 핵심: 브로커 인증정보를 daemon_id 차원으로 확장(스키마 PK 변경 + daemon-scoped 전달 엔드포인트)하고, "1 데몬 = 1 계좌" 불변식 하에 응답을 단일 broker로 정규화하는 범위·리스크·마이그레이션을 확정한다.

2. 요구사항 판정 결과

이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.

• 판정: 신규
• 근거
  • 기존 broker_credentials + /v1/user_info(dcy-004 토큰 정비 계열)는 user-scoped 인증정보 소유·전달을 다뤘으나, daemon_id 차원의 스코프·1:1 불변식·daemon 부트스트랩 전달은 정의된 바 없다.
  • 변경이 테이블 PK와 전달 엔드포인트 응답 형태(brokers 리스트→단일 broker)를 바꾸는 구조 변경이라 기존 Discovery의 미세 조정이 아닌 독립 주기로 추적한다.

3. 문제점의 요약

문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다.

• 현재 상태
  • broker_credentials 테이블 PK=(user_id, broker) — 인증정보가 user 단위. 컬럼: user_id, broker, account_ref, encrypted_payload(Fernet 암호화 JSON {app_key, app_secret}), credential_version, last_rotated_at. (migrations/versions/20260502_0014_v1_api_schema.py, app/domain/models.py:178)
  • 전달: GET /v1/user_info — service token 전용(token이 daemon_id/runtime_id 바인딩), 토큰의 user_id로 조회 → 서버에서 Fernet 복호화 → brokers: list[BrokerItem](credential_payload, account_ref, credential_version) + trading_enabled(user.is_active) 반환. (app/api/v1_user_info.py)
  • 반면 universe(포트폴리오)는 이미 daemon-scoped — Portfolio.managed_by_daemon_id, /v1/portfolios가 service token의 auth.daemon_id == managed_by_daemon_id 일치로 필터·인가. (app/api/v1_portfolios.py:254,260,554)
  • 결과 비대칭: 토큰은 daemon_id를 들고 universe는 daemon으로 거르는데, 인증정보만 user로 걸러 같은 user의 두 데몬이 같은 계좌를 공유하게 된다.
  • trex-core 측은 현재 KIS를 TREX_KIS_BROKER_* env로만 주입(trex-core/runtime/config.py:257)하며 portfolio-hub에서 인증정보를 받지 않는다. 멀티 인스턴스 토대(instance_key, longterm.example.toml)는 존재.
• 기대 상태
  • 한 trex-core 데몬 인스턴스가 자기 service token(daemon_id 바인딩)으로 부트스트랩 시 그 daemon에 매칭된 단일 KIS 계좌 인증정보를 받는다.
  • 같은 user가 단기·중장기 데몬을 동시에 소유해도 데몬마다 다른 KIS 계좌로 거래할 수 있다.
  • 인증정보는 universe와 동일하게 daemon_id로 인가·스코프되어, 계좌-인스턴스 매칭이 단일 출처(portfolio-hub)에서 결정된다.
• 이해관계자
  • 사장님(제품 방향·계좌/인증 정책 결정·결재)
  • 팀장(Discovery·거버넌스·검수)
  • portfolio-hub-dev(스키마·엔드포인트·CLI 구현), trex-core-dev(소비자 어댑터 — 별도 Discovery)
  • 운영자(계좌 인증정보 등록/회전, 데몬-계좌 바인딩 관리)
• 제약사항
  • KIS app_secret = 시스템 최민감 시크릿(실계좌=실자금). 복호화 평문이 응답 본문으로 네트워크 전송됨 → 내부망/TLS·service-token 게이트 유지 필수.
  • portfolio-hub는 M3에서 trex-web 프론트로 노출될 서비스 — 인증정보 경로를 web 노출 표면과 격리 유지(service-token 전용).
  • PK 변경은 기존 데이터·제약·인덱스에 영향(마이그레이션 비가역성 주의).

주요 사용자 시나리오

• 운영자가 단기 전략 데몬 A와 중장기 전략 데몬 B를 같은 user 소유로 등록하고, 각각 다른 KIS 계좌 인증정보를 portfolio-hub에 등록한다. A·B는 각자 자기 계좌로 거래한다.
• trex-core 중장기 인스턴스가 그날 시작(아침 스냅샷) 시 service token으로 부트스트랩을 호출해 자기 daemon의 universe + KIS 인증정보를 한 번에 받아 그날 거래를 개시한다.
• 운영자가 데몬 B의 KIS app_secret을 회전(rotate)하면, B만 새 버전을 받고 A는 영향받지 않는다.

4. 이번에 정의할 변경

이번 Discovery에서 다루는 핵심 변경 항목.

• (C1) broker_credentials에 daemon_id 차원 도입 — 인증정보를 daemon-scope로 소유. PK를 (user_id, broker) → daemon 포함 형태로 변경.
• (C2) daemon-scoped 전달 — service token의 auth.daemon_id로 해당 데몬의 인증정보만 복호화·반환. "1 데몬 = 1 계좌" 불변식 하에 응답을 단일 broker(리스트 아님)로 정규화.
• (C3) 인증정보 관리 경로(CLI/관리 API)에 daemon_id 바인딩 추가 — 등록·회전·삭제 시 데몬-계좌 매칭 지정.

영향 범위

• 코드 영향:
  • app/domain/models.py(BrokerCredential), app/repositories/*(upsert/list/delete 시그니처 + 쿼리 daemon_id 필터), migrations/versions/*(PK·컬럼 마이그레이션)
  • app/api/v1_user_info.py(기존 /v1/user_info daemon-scoped 확장 — 결정 2026-06-28, 신규 엔드포인트 없음), app/schemas/v1.py(UserInfoResponse: brokers 리스트→단일 broker)
  • app/cli/commands/credential.py(--daemon-id 추가)
  • 교차 서비스(별도 Discovery): trex-core — KISConfig를 env-only → portfolio-hub fetch 소스에서 구성하는 소비자 어댑터 + 그날-시작 fail-safe 로드 게이트(trex-core/runtime/config.py, daemon 부트스트랩)
• 문서 영향:
  • docs/srs/(신규 REQ), docs/discovery/index.md(본 문서 등록)
  • baseline 런타임 흐름에 "daemon 부트스트랩 시 인증정보 전달" 추가 검토(§ runtime-flows 갱신은 NFR/후속에서 판단)
• 운영 영향:
  • 운영자 인증정보 등록 절차에 daemon_id 지정 추가. 기존 user-scoped 인증정보 마이그레이션(데몬 매핑) 1회 필요.
  • CREDENTIAL_ENCRYPTION_KEY 관리·회전 정책(기존 의존 유지).

5. 요구사항 목록

기능 요구사항

• FR-1: broker_credentials가 daemon_id로 인증정보를 스코프한다. 한 (daemon, broker) 조합당 활성 인증정보는 정확히 1건이다. PK = (daemon_id, broker), daemon-scoped 강제(user-기본 폴백 없음 — 공유계좌 footgun 차단). 결정 2026-06-28. 마이그레이션은 nullable daemon_id 컬럼 추가 → 백필(데몬 매핑) → PK 전환의 단계적 경로.
• FR-2: 기존 GET /v1/user_info를 daemon-scoped로 확장한다(신규 엔드포인트 미신설 — confirm 2026-06-28). service token 호출 시 토큰의 daemon_id에 매칭된 단일 broker 인증정보(account_ref + 복호화된 credential_payload + credential_version)와 trading_enabled를 반환한다. 토큰에 daemon_id가 없으면 거부(403)한다(universe 인가와 동일 규율). 1데몬1계좌 불변식(A-2 confirmed)상 응답은 리스트가 아닌 단일 broker로 정규화한다. 기존 소비자는 trex-core hub_read.whoami() 하나뿐이며 daemon_id만 읽으므로 broker 필드 reshape는 무영향(안전).
• FR-3: 인증정보 등록/회전/삭제 경로(CLI 및/또는 관리 API)가 daemon_id를 받아 데몬-계좌 매칭을 지정한다.
• FR-4: 기존 user-scoped 인증정보를 daemon-scoped로 이전하는 마이그레이션 경로를 제공한다(데이터 손실 없이).

비기능 요구사항

• NFR-1 (보안): 복호화된 app_secret은 service-token 전용·내부망/TLS 경로로만 전달된다. trex-web 등 user 토큰 경로로는 접근 불가해야 한다. at-rest는 기존 Fernet 암호화 유지.
• NFR-2 (일관성): 인증정보 스코프(daemon_id)가 universe 스코프(managed_by_daemon_id)와 동일한 인가 규율을 따른다(불일치/누락 → 403).
• NFR-3 (가용성/degrade): 인증정보 조회·복호화 실패가 부트스트랩 응답의 필수 필드(daemon_id, trading_enabled)를 크래시시키지 않는다(기존 graceful degrade 원칙 유지). 단, 인증정보 부재는 그날 거래 개시 차단 신호로 전달된다.

범위 경계

• In Scope
  • portfolio-hub: daemon_id 차원 인증정보 소유(PK 변경) + daemon-scoped 단일 broker 전달 + 관리 경로 daemon_id 바인딩 + 마이그레이션.
  • "1 데몬 = 1 계좌" 불변식 확정 및 응답 단일화.
• Out of Scope
  • trex-core 소비자 어댑터(KISConfig fetch) + 그날-시작 fail-safe 로드 게이트 — 별도 trex-core Discovery로 분리(본 문서는 계약·전달 형태만 확정).
  • {{DECIDE_SCOPE_BOOTSTRAP_UNIFY:부트스트랩 응답에 universe까지 한 엔드포인트로 묶을지(단일 부트스트랩) vs 인증정보만 별도 경로로 둘지 — 사장님/팀장 확정 필요}}
  • 시크릿 매니저(Vault 등) 외부화 — 현 단계는 portfolio-hub 내부 처리 유지(가정 A-3).

6. 리스크/가정 목록

리스크

• R-1 (High): broker_credentials PK 변경 마이그레이션이 기존 데이터·제약을 깨거나 롤백이 어려움.
  • 완화 방안: nullable daemon_id 컬럼 추가 → 백필(데몬 매핑) → 새 PK/유니크 제약 전환의 단계적 마이그레이션. 사전 백업·드라이런·롤백 스크립트. 비가역 단계는 사장님 결재.
• R-2 (High): 최민감 시크릿(app_secret) 평문이 네트워크 전송되며, portfolio-hub가 web 노출 서비스라 표면이 큼.
  • 완화 방안: service-token 전용 + daemon_id 인가 + 내부망/TLS 한정. web의 user 토큰 경로와 라우트/권한 분리. 감사 로깅.
• R-3 (Medium): /v1/user_info 응답 형태(brokers 리스트→단일)의 파괴적 변경이 기존 소비자를 깸.
  • 완화 방안: 기존 소비자 인벤토리 확인 후, 신규 daemon-scoped 경로 신설(기존 user-level 리스트는 admin/UI용으로 유지) 또는 버전드 전환.

가정

• A-1: portfolio-hub가 universe·전략·인증정보의 단일 진실원천이다. (사장님 확정)
• A-2: "1 데몬(trex-core 인스턴스) = 1 브로커 계좌" 불변식이 성립한다. trex-core KISConfig가 현재 단일인 점과 정합. (사장님 confirmed 2026-06-28 → 단일 broker 응답 근거)
• A-3: 현 단계는 portfolio-hub 내부 인증정보 소유(기존 Fernet + CREDENTIAL_ENCRYPTION_KEY)를 유지하고 외부 시크릿 매니저로 가지 않는다.
• A-4: 데몬-계좌 매칭은 service token의 daemon_id 바인딩(AuthToken.daemon_id)을 통해 결정된다.

오픈 질문

• OQ-1: PK 전환 형태 + 폴백 정책.
  • 상태: Answered (2026-06-28)
  • 결정: PK = (daemon_id, broker), daemon-scoped 강제(폴백 없음). 마이그레이션 = nullable daemon_id 컬럼 추가 → 백필 → PK 전환 단계적. 본문 FR-1·R-1에 반영.
  • 반영 위치: §5 FR-1, §6 R-1 완화 방안.
• OQ-2: 전달 형태 — 기존 /v1/user_info reshape vs daemon-scoped 신규 엔드포인트.
  • 상태: Answered (2026-06-28)
  • 결정: 기존 /v1/user_info를 daemon-scoped로 확장(신규 엔드포인트 미신설, 사장님). 소비자 인벤토리 조사 결과 유일 소비자=trex-core adapters/portfolio/hub_read.py::whoami()이며 daemon_id만 읽음(brokers 미참조) → 단일 broker reshape 무영향(안전). 본문 FR-2에 반영.
  • 반영 위치: §4 영향범위, §5 FR-2, §7 S-1/S-2.
• OQ-3: 부트스트랩 통합 범위 — universe + 인증정보 + trading_enabled를 단일 부트스트랩 응답으로 묶을지.
  • 상태: Deferred
  • 처리 방안: trex-core 소비자 Discovery와 함께 결정(전달 계약 공동 설계). 본 문서는 인증정보 전달 형태만 확정.
  • 종료 조건: trex-core 소비자 Discovery 착수 시점.
• OQ-4: 그날-시작 fail-safe 로드 의미론(진입 게이트 vs 청산 보존, 장중 무중단)의 trex-core측 구현 책임 분배.
  • 상태: Deferred
  • 처리 방안: 별도 trex-core Discovery로 인계(아래 §10 참조). 본 문서엔 전달측 가정으로만 기록.
  • 종료 조건: trex-core 소비자 Discovery 생성.

7. 초기 성공 기준

• S-1: 같은 user가 소유한 두 데몬이 각각 다른 KIS account_ref/app_key를 부트스트랩으로 수신함을 검증할 수 있다.
• S-2: service token에 daemon_id가 없거나 인증정보가 daemon에 매칭되지 않으면 전달이 403/차단됨이 테스트로 확인된다.
• S-3: 기존 user-scoped 인증정보가 마이그레이션 후 손실 없이 daemon-scoped로 조회된다.

측정 방식 및 데이터 출처

• S-1 측정 방식: 두 데몬용 service token으로 부트스트랩 호출 → 응답 account_ref/credential_payload 상이 확인 / 데이터 출처: 통합테스트 + broker_credentials 행
• S-2 측정 방식: daemon_id 누락/불일치 토큰 요청의 403 단위·통합 테스트 / 데이터 출처: 엔드포인트 테스트
• S-3 측정 방식: 마이그레이션 전후 인증정보 복호화 결과 동등성 비교 / 데이터 출처: 마이그레이션 드라이런 로그 + 테스트

8. REQ로 넘기기 전 확인 체크

• 범위(In Scope/Out of Scope) 확정
  • 기준: trex-core 소비자측 분리 확정(별도 Discovery), 부트스트랩 통합(OQ-3) Deferred 처리
• 성공 지표의 측정 방식/데이터 출처 확정
  • 기준: S-1~S-3 측정 가능성 검토 완료
• High 영향 리스크 우선순위 및 해소 책임자 지정
  • 기준: R-1(마이그레이션 — 단계적 PK 전환·롤백, portfolio-hub-dev)·R-2(시크릿 표면 — service-token+내부망) 완화안 확정
• 모든 오픈 질문(OQ) Open 상태 없음 확인
  • 기준: OQ-1·OQ-2 Answered, OQ-3·OQ-4 Deferred 처리 완료
• Freeze 확정 담당자(CONFIRMED_BY) 지정
  • 기준: 사장님+팀장 confirm-discovery (DECIDE/CONFIRM 전건 해소)

9. 파일 처리 결과

• 처리 결과: 생성
• 생성 경로: docs/discovery/dcy-010_20260627_daemon-scoped-broker-credential-provisioning.md
• 참조 문서:
  • docs/discovery/dcy-004_20260520_token-issuance-and-lifecycle-overhaul.md (service token·daemon 바인딩)
  • docs/discovery/dcy-008_20260625_current-holding-wac-cost-basis-read.md (교차 발원 trex-core 중장기 cold-start)
  • app/api/v1_user_info.py / app/domain/models.py(BrokerCredential) / app/api/v1_portfolios.py(daemon-scope 선례)

10. 사용자 결정 필요 항목 요약

DECIDE

• PK 전환 형태 (OQ-1) → RESOLVED 2026-06-28: PK (daemon_id, broker) + daemon-scoped 강제(폴백 없음), 단계적 마이그레이션
• 엔드포인트 형태 (OQ-2) → RESOLVED 2026-06-28: 기존 /v1/user_info daemon-scoped 확장
• 부트스트랩 통합 (OQ-3) → Deferred: trex-core 소비자 Discovery 공동 결정

CONFIRM

• 1데몬1계좌 불변식 → RESOLVED 2026-06-28: 확정(A-2 confirmed) → 단일 broker 응답
• trex-core 소비자측 분리 → RESOLVED 2026-06-28: 별도 trex-core Discovery로 분리 확정

DATA

• 기존 /v1/user_info 소비자 인벤토리 → RESOLVED 2026-06-28: 유일 소비자=trex-core hub_read.whoami(daemon_id만 읽음), brokers 미참조 → reshape 안전

11. Discovery Freeze

REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다.

섹션 참조

• 범위: # 5. 요구사항 목록 > 범위 경계
• 리스크/오픈 질문: # 6. 리스크/가정 목록
• 성공 기준: # 7. 초기 성공 기준
• 인계 전 확인: # 8. REQ로 넘기기 전 확인 체크
• 사용자 결정 필요: # 10. 사용자 결정 필요 항목 요약

Freeze 플래그

• Handoff Decision: REQ Drafting 진행 가능
• Handoff Rationale: confirm-discovery 완료(2026-06-28). DECIDE 전건 해소 — OQ-1(PK (daemon_id, broker)+폴백없음), OQ-2(기존 /v1/user_info 확장), OQ-3(Deferred). CONFIRM 전건 — A-2(1데몬1계좌→단일 broker), trex-core 소비자측 별도 Discovery 분리. DATA(소비자 인벤토리) 해소. 잔여 Open 0건 → REQ 초안 인계 가능.
• Ready for REQ Drafting: true
• Confirmed By: 팀장(Claude)
• Confirmed At (KST): 2026-06-28