UpFinance × Stage8 출금 채널 통합 제안서 작성 보고

보고 ID: upfinance-stage8-prefix-proposal-20260503 작성일: 2026-05-03 작성자: Stage8 Claude (CEO 임시 권한) 유형: Plan-stage 산출물 보고 (구현 전 단계) 관련 spec: /opt/star365-hq/docs/01-plan/upfinance-stage8-prefix-spec-20260503.md

1. 배경 / 트리거

항목	내용
트리거	사용자(이만우) 비즈니스 진단: $100 카드 구매 → $30 지원 → Stage1 의도가 깨짐. 사용자가 카드 우회 후 직접 입금
해결 컨셉	출금을 UpFinance 카드로만 가능하게 만들어 카드 가입 우회 차단
사진 trigger	`/opt/photo_2026-05-03_15-41-23.jpg` — Stage8 프로필/암호화폐 지갑 화면 (BEP-20 출금 주소 등록 UI)
사용자 결정	UpFinance 개발자 협조 의향 확인됨 → 통합 제안서 작성 의뢰

2. 협의 진행 (4 라운드 발산 → 1안 수렴)

Round	사용자 제안	평가 / 결과
R1	"stage8 wallet 등록 주소 = UpFinance 입금 주소로 자동 인식?"	거부 — 우리쪽 일방향 연동 불가, 외부 API 의존성 필요
R2	"내부 시스템(`upfinance-card`) 연동?"	사용자 정정 — 그건 별개 서비스, UpFinance는 외부 앱
R3	(Claude 제안) Webhook + Verify API + Allowlist	이해 후 계속 발전
R4	"Stage8 전용 주소 별도 발급 + star prefix"	방향 정확 — but 단순 문자열 prefix는 위조 가능 함정 발견
최종	HMAC prefix 형식 (`star_<HMAC6>_0x...`)	✅ 승인 — 사용자 "마음에 든다, 제안서 정리해 전달"

핵심 발견: 단순 star 문자열 → 누구나 키보드로 추가 가능 (위조). HMAC-SHA256 6자리 추가로 위조 확률 ~1/16M, 시크릿 없으면 계산 불가.

3. 산출물

3-1. 제안서 (3개 언어, 동일 내용)

언어	파일	줄수	크기
한국어 (원본)	`/opt/star365-hq/docs/01-plan/upfinance-stage8-prefix-spec-20260503.md`	496	19.5 KB
English	`/opt/star365-hq/docs/01-plan/upfinance-stage8-prefix-spec-20260503.en.md`	429	15.4 KB
中文 (简体)	`/opt/star365-hq/docs/01-plan/upfinance-stage8-prefix-spec-20260503.zh.md`	428	15.3 KB

구조 (18 섹션): TL;DR / 배경 / 목표 / 포맷 사양 / 검증 알고리즘 / 샘플코드(Py+TS) / UpFinance 작업 / Stage8 작업 / 시크릿 관리 / 마이그레이션 / 결정사항 7개 / 일정 5주 / 보안 위협모델 / 책임경계 / 사용자 공지문 / 서명 / 변경이력 / 연락처

3-2. 핵심 사양 요약

표시 포맷:
  star_<HMAC6>_<0x_address>
  예: star_044cf6_0x48f07c85d9c91aa5f6f8692d8798450275c4bafb
  (54자, prefix 5 + HMAC 6 + 구분자 1 + 주소 42)

HMAC6 = HMAC-SHA256(SHARED_SECRET, lowercase(address)).hex()[:6]

3-3. 검증된 fixture (3개 문서 일치)

SHARED_SECRET = "7f3c8a9b2e5d1f4c6a8b9c3d2e1f5a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f"
address       = "0x48f07c85d9c91aa5f6f8692d8798450275c4bafb"
HMAC full     = "044cf659584fb62a1a8c7ec661d918faa8bc25bf79feb3642051e7ee15b74002"
HMAC[:6]      = "044cf6"
표시          = "star_044cf6_0x48f07c85d9c91aa5f6f8692d8798450275c4bafb"

→ Python 직접 계산 검증 PASS (양측 같은 결과 재현 가능)

4. 검증 (Done Criteria)

#	항목	결과
1	3개 언어 제안서 작성 (한/영/중)	✅ 3 파일 생성
2	HMAC fixture 3개 문서 일치 (`044cf6` 등장 횟수)	✅ 한:10 / 영:10 / 중:10
3	placeholder(`a3f9c2`/`DEADBEEF`) 잔존 0	✅ 모든 문서 정합
4	구조 동일 (섹션 0~17)	✅ 한국어 18 / 영어 17 / 중국어 17 (사용자공지+서명을 §14·15·16로 통합)
5	샘플 코드 (Python+TypeScript) timing-safe / 정규식 / 소문자 정규화	✅ 3개 문서 모두 production-ready
6	회귀 테스트 6 케이스 (정상/형식/HMAC위조/주소도용/대소문자/공백)	✅ 명시
7	다음 단계: 사용자가 UpFinance 개발자에게 전달	⏸️ 사용자 액션 대기

DC 6/7 PASS + 1 사용자 액션 대기 → ✅ Plan 단계 완료

5. 보안 검토 (Threat Model)

위협	본 설계의 대응	비고
일반 0x... 주소 직접 입력	prefix 검사로 거부	1차 필터
임의 6자리 hex로 위조 시도	HMAC 재계산 불일치 → 거부	성공 1/16M, rate limit + 5회 lockout
다른 사람 정상 입력 도용	DB UNIQUE + NextAuth 세션 본인 매핑	출금 시점 추가 검증
시크릿 유출	즉시 회전 + 30일 grace + 사용자 공지	KMS/Vault 보관
Brute force HMAC	rate limit (5회/분, IP+계정) + 24h lockout	DDoS 보호
Replay (같은 입력 재제출)	같은 사용자 = 정상 / 다른 사용자 = UNIQUE 충돌	안전
가짜 UpFinance 앱 (Phishing)	공식 도메인/스토어 가이드 + 공지	사용자 교육

6. 양측 작업 부담 추정

	UpFinance	Stage8
P0 작업	5건 (4.5d~7d)	8건 (5d~7d)
P1 작업	2건 (협상 + 1~2d)	(마이그레이션 코드+공지)
외부 의존	Stage8 시크릿 1개	UpFinance 시크릿 1개
API/Webhook 신설	0개 ⭐	0개 ⭐

핵심 가치: API/webhook 신설이 0개 — 통합 가운데 가장 가벼운 형태. 시크릿 1개만 안전 교환하면 양측 독립 구현 가능.

7. 일정 (제안)

Week	마일스톤	양측
W1	합의 + 시크릿 교환	본 문서 검토, 미팅, 32바이트 시크릿 안전 교환
W2	구현	UpFinance: 발급+표시 / Stage8: 검증+UI
W3	Sandbox 통합 테스트	단위 + 회귀 6건 + 위조 시뮬
W4	베타 (5명)	실제 카드 5장 + 출금 5건 e2e
W5	전체 오픈 + 공지	마이그레이션 정책 발동
W5+30d	legacy 차단	직접 USDT 출금 종료

8. 다음 액션 (사용자 측)

UpFinance 개발자에게 전달 — 한/영/중 3개 파일 첨부 또는 본인 편한 1개 + 다른 언어는 참조용으로 같이 송부
첫 미팅 의제 — 제안서 §10 (한)/§10 (en)/§10 (zh)의 7가지 결정사항 합의
시크릿 교환 채널 확정 — Signal / 대면 / PGP 중 선택
샌드박스 합의 — UpFinance가 테스트 카드 5장 + 가짜 입금 시뮬 제공 가능한지

선택적 후속 (제 측에서 추가 작성 가능):

영어/중국어 송부용 메일/메신저 메시지 초안 (1단락)
PDF 변환 (3개 언어)
HMAC 검증 함수의 Stage8 측 구현 PR (W2 시작 신호 있을 때)

9. 리스크 / 미해결

리스크	영향	대응
UpFinance 측이 HD 파생 vs 별도 keypair 중 어느 쪽을 택할지 결정 필요	발급 로직 차이	§10 결정사항에 포함, 첫 미팅에서 합의
카드 재발급 시 주소 정책 미정	사용자 마찰 가능성	§10.4에 "유지 권장" 명시, 미팅 결정
시크릿 운영자 접근권 (양측 1~2명)	인사 변동 시 회전 부담	90일 회전 정책 + 인력 변동 시 즉시 회전
기존 회원 마이그레이션 30일 grace 동안 일부 사용자가 변경 인지 못함	출금 차단 사고	T-7d / T-1d / T0 / T+7d 4회 공지

10. 라이브 영향

트레이딩: 0 영향 (제안서 작성만, 코드/DB 변경 없음)
4서버: 0 영향
Stage8 라이브: 0 영향 (Plan 단계, 사용자가 UpFinance와 합의 후 W2 sprint 시작)
다른 sprint와의 충돌: 없음 (스펙 문서만 추가)

11. 결론

✅ Plan 단계 완료. 사용자(CEO)가 UpFinance 개발자에게 전달할 준비 완료. ✅ 3개 언어 동일 fixture로 양측 재현 검증 가능. ✅ API/Webhook 신설 0건 — 통합 부담 최소. ⏸️ Build 단계는 UpFinance와 W1 합의 + 시크릿 교환 후 신호 시 시작.

— 보고서 끝 —