협업 리포트 — 마송훈 × 칸 HMAC 지문 canonical 규약 (2026-04-19)

판정: 협업 PR merge 완료, 재발방지 규약 명문화. PR: meneco/metaquant-bridge #1 — c1cc3c9 merge commit 파일 변경: docs/key-management.md +30 / -0 (docs only)

배경

2026-04-19 Starium Finance 복구 + Wiki v1 sprint 진행 중, Vercel 프론트(마송훈) ↔ kahan 백엔드(칸) 통신에서 /internal/snapshot 404 발생.

1차 진단 (Telegram msg 5290, 칸)

체크	결과
systemd 3종 active	✅
/internal/snapshot 엔드포인트 존재	✅
nginx location (path rewrite 없음)	✅
HMAC pathname 일치 (/internal/snapshot 풀패스)	✅
HMAC_SECRET_V1 fingerprint	17f8396cfacec937 (canonical)

→ 404 = first-sync 현상 (Vercel이 보낸 mq_user_id=69b027fd918ad2f484da50fa 가 gunja_users.db 에 아직 없음). → api/routes/snapshot.py 패치: if snap is None: return {"status":"not_synced", ...} (404 → 200 + status).

지문 대조 혼선

마송훈 측 1차 시도에서 printf '%s' 로 계산 → acea19aab4445b8e (오답). echo 로 재계산 → 17f8396cfacec937 (일치). 실제 시크릿은 일치했으나 trailing \n 포함 여부 한 가지 차이로 불일치로 인식.

산출물

A. Vercel 측 (마송훈 직접 커밋)

• Songhoonma/metaquant#7 — snapshot not_synced UI 대응 머지·배포 완료
• COLLABORATION-GUIDE.md §4 직접 커밋 완료

B. kahan 측 mirror PR (칸 merge)

• docs/key-management.md — "지문(fingerprint) 대조 규약" 섹션 추가
• Canonical 계산식 고정:

  echo "$HMAC_SECRET_VN" | shasum -a 256 | head -c 16
  

• 금지: printf '%s', echo -n (trailing \n 누락)
• RSA 공개키는 별도 포맷 (openssl pkey … sha256, sha256:<64-hex> prefix)

검증

• PR #1 내용: docs only, 충돌 없음, git merge --no-ff
• push 3ed0de9..c1cc3c9 → origin/main
• feature branch docs/hmac-fingerprint-canonical 원격 삭제 완료

다음 로테이션 (월간)

• HMAC_SECRET_V2 생성 시 반드시 이 canonical 식으로 지문 확인
• Vercel ↔ kahan 양측 동일 16자 지문 일치 확인 → rotate

감사

송훈 PR 커밋 메시지:

"first-sync 원인을 Telegram msg 5290 한 번에 짚어주신 덕에 대응이 단순해졌습니다."