v0.0

화이트리스트 주소 관리 정책 설계서¶

1. Executive Summary¶

본 문서는 D'CENT 엔터프라이즈 콜드월렛 커스터디 솔루션의 화이트리스트 주소 관리 정책을 설계한다. 화이트리스트는 사전 승인된 수신 주소로만 트랜잭션을 허용하여 무단 자산 유출을 원천 차단하는 핵심 보안 메커니즘이다.

핵심 원칙: - Deny-by-Default: 화이트리스트 미등록 주소로의 전송은 전면 차단 - 쿼럼 기반 관리: 주소 등록/삭제는 Admin 쿼럼 승인 필수 (AC-TX-04) - 쿨다운 기간: 신규 주소 등록 후 활성화까지 대기 시간 적용 (소셜 엔지니어링 방어) - 대시보드 마스터: 화이트리스트의 단일 진실 원천(Single Source of Truth)은 온라인 대시보드

2. 화이트리스트 개요¶

2.1. 화이트리스트의 역할¶

기능	설명
무단 유출 방지	사전 승인된 주소로만 전송 가능 — 내부자 위협, 키 탈취 시에도 미등록 주소로 전송 불가
소셜 엔지니어링 방어	쿨다운 기간이 악의적 주소 등록 시도에 대한 시간적 방어선
운영 효율	반복 거래 주소를 사전 등록하여 매번 주소 검증 불필요
감사 추적	모든 화이트리스트 변경 이력이 감사 로그에 기록

2.2. 화이트리스트 유형¶

유형	범위	관리 권한	사용 시나리오
글로벌 (전사)	전체 조직의 모든 월렛 적용	Super Admin / Admin 쿼럼	거래소 입금 주소, 자주 사용하는 외부 주소
월렛별	특정 월렛에만 적용	Admin 쿼럼	특정 프로젝트/부서 전용 주소
자산 유형별	특정 자산(BTC/ETH/USDT 등)에만 적용	Admin 쿼럼	체인별 전용 주소, 토큰 컨트랙트 주소

2.3. 화이트리스트 데이터 모델¶

WhitelistEntry = {
  id: UUID,
  address: string,             // 블록체인 주소
  chain: string,               // 체인 유형 (BTC, ETH, etc.)
  label: string,               // 인간 판독 라벨 (예: "Binance 입금")
  type: "global" | "wallet" | "asset",
  scope_id: string (optional), // wallet_id 또는 asset_type
  category: "internal" | "external",
  status: "pending" | "cooldown" | "active" | "inactive",
  cooldown_until: timestamp,   // 쿨다운 종료 시각
  created_by: user_id,         // 등록 요청자
  approved_by: [user_id, ...], // 승인한 Admin 목록
  created_at: timestamp,
  updated_at: timestamp,
  deactivated_at: timestamp (optional),
  deactivated_by: user_id (optional),
  audit_hash: string           // 해시 체인 연결
}

3. 화이트리스트 CRUD 워크플로우¶

3.1. 등록 (Create)¶

Step 1: 등록 요청
 - 요청자: Initiator 또는 Admin
 - 입력: 블록체인 주소, 체인 유형, 라벨, 적용 범위
    │
    ▼
Step 2: 주소 유효성 검증 (자동)
 - 주소 포맷 검증 (checksum, 길이, 체인 매칭)
 - 체인 불일치 방지 (BTC 주소를 ETH 화이트리스트에 등록 시도 차단)
 - 중복 등록 확인
 - 블랙리스트 대조 (제재 목록, 알려진 해킹 주소)
    │
    ▼
Step 3: Admin 쿼럼 승인 (AC-TX-04)
 - 최소 2명의 Admin 승인
 - 각 Admin: 주소 정확성, 사용 목적, 위험도 검토
 - 상태: pending → cooldown
    │
    ▼
Step 4: 쿨다운 기간 (Cooling-off Period)
 - 기본: 48시간 (설정 가능 범위: 0-168시간)
 - 쿨다운 동안: 주소 표시되나 TX 생성 불가
 - 쿨다운 중 취소 가능 (단독 Admin으로 취소 가능 — 긴급 방어)
    │
    ▼
Step 5: 활성화
 - 쿨다운 완료 → 상태: cooldown → active
 - 자동 활성화 (Admin 추가 개입 불필요)
    │
    ▼
Step 6: 감사 로그 기록
 - 등록 요청, 검증 결과, 승인자, 쿨다운 시작/종료, 활성화

3.2. 조회 (Read)¶

역할	조회 범위
Super Admin	전체 화이트리스트 + 비활성 이력
Admin	전체 화이트리스트
Initiator	자신의 담당 월렛 범위의 활성 화이트리스트
Approver	승인 대상 TX 관련 화이트리스트
Viewer	전체 활성 화이트리스트 (읽기 전용)

3.3. 수정 (Update)¶

변경 유형	승인 수준	처리
라벨 변경	단독 Admin	즉시 적용, 쿨다운 없음
범위 변경 (글로벌→월렛별)	Admin 쿼럼	새 범위 적용, 쿨다운 없음
주소 변경	= 삭제 + 등록	기존 삭제 후 신규 등록 절차 (쿼럼 + 쿨다운)
체인 변경	= 삭제 + 등록	체인 변경은 사실상 다른 주소 → 신규 등록

3.4. 삭제 (Delete)¶

Step 1: 삭제 요청
 - 요청자: Admin
 - 삭제 사유 입력 (필수)
    │
    ▼
Step 2: Admin 쿼럼 승인
 - 최소 2명의 Admin 승인
    │
    ▼
Step 3: 즉시 비활성화
 - 상태: active → inactive
 - 즉시 효력 발생 — 해당 주소로의 신규 TX 생성 차단
    │
    ▼
Step 4: 대기 트랜잭션 처리
 ├─ PENDING_APPROVAL 상태 TX: 자동 차단 + Initiator 알림
 ├─ PARTIALLY_SIGNED 상태 TX: 경고 표시 + Admin 결정
 │   ├─ 차단: TX 만료 처리
 │   └─ 예외 허용: 현재 TX만 완료 허용 (1회성)
 └─ BROADCASTING 이후 TX: 영향 없음 (이미 전파)
    │
    ▼
Step 5: 감사 로그 기록
 - 삭제 사유, 승인자, 영향받은 TX 목록

4. 쿨다운(Cooling-off) 기간¶

4.1. 쿨다운의 목적¶

목적	설명
소셜 엔지니어링 방어	공격자가 Admin을 속여 악성 주소를 등록하더라도 48시간 내 발견 가능
내부 위협 방어	내부자의 악의적 주소 등록 시 다른 Admin이 검토할 시간 확보
실수 방지	오타 또는 잘못된 주소 등록 시 쿨다운 중 취소 가능
감사 대비	변경 사항에 대한 검토 시간을 제도적으로 보장

4.2. 쿨다운 설정¶

항목	기본값	설정 범위	비고
글로벌 화이트리스트	48시간	24-168시간	전사 적용이므로 긴 쿨다운
월렛별 화이트리스트	24시간	12-72시간	범위가 제한적이므로 단축 가능
내부 주소	12시간	0-24시간	기업 내부 월렛 간은 단축
긴급 등록	0시간	0 (스킵)	상위 쿼럼 + 사후 감사 조건

4.3. 긴급 화이트리스트 등록¶

긴급 등록 요청
 - 사유: 보안 위협으로 인한 긴급 자산 이전 등
    │
    ▼
상위 쿼럼 승인 (일반보다 높은 수준)
 - 일반: Admin 2명 → 긴급: Admin 3명 + Super Admin 1명
    │
    ▼
쿨다운 스킵 → 즉시 활성화
    │
    ▼
사후 의무:
 - 24시간 내 전체 Admin 보고
 - 72시간 내 사후 감사
 - 7일 내 정규 화이트리스트 등록 절차로 전환 (또는 삭제)

5. 오프라인 디바이스 동기화¶

5.1. 동기화 아키텍처¶

온라인 대시보드 (마스터)
    │
    ├─ QR/USB-C ──▶ 오프라인 서명 앱 (복제본)
    │                │
    │                └─ 정책 평가 시 로컬 화이트리스트 참조
    │
    └─ Phase 4: 콜드월렛 SE 내 화이트리스트 캐시 (DIF-02)

5.2. 동기화 메커니즘 (개념 수준)¶

항목	설명
동기화 시점	오프라인 앱이 대시보드와 QR/USB-C 교환 시 자동 동기화
동기화 데이터	화이트리스트 엔트리 전체 + 버전 해시
증분 동기화	마지막 동기화 이후 변경분만 전송 (페이로드 최소화)
무결성 검증	화이트리스트 Merkle Root 비교 → 불일치 시 전체 재동기화

5.3. 동기화 충돌 해결¶

시나리오	처리
대시보드에서 삭제, 오프라인 앱에 아직 존재	다음 동기화 시 오프라인 앱에서도 삭제 → 대시보드 마스터 원칙
오프라인 상태에서 TX 시도 → 주소 검증 불가	오프라인 앱의 로컬 캐시로 검증. 캐시 만료(기본 7일) 시 서명 거부
동기화 중단 (QR 스캔 실패 등)	이전 동기화 상태 유지, 재시도

5.4. 콜드월렛 화이트리스트 캐시 (Phase 4 DIF-02 연계)¶

Phase 4에서 하드웨어 정책 엔진(DIF-02)이 구현되면: - SE 내부에 화이트리스트 해시 캐시 저장 - 서명 요청 시 수신 주소의 화이트리스트 포함 여부를 SE에서 직접 검증 - 미등록 주소 → SE가 서명 자체를 거부 (최종 방어선) - 캐시 용량 제한으로 Bloom Filter 또는 해시 세트 사용 고려

6. 내부 주소 vs 외부 주소 구분¶

6.1. 구분 기준¶

구분	정의	식별 방법
내부 주소	기업이 관리하는 월렛의 주소 (콜드/웜/핫 월렛)	대시보드에 등록된 자사 월렛 주소
외부 주소	기업 외부의 수신 주소 (거래소, 파트너, 개인)	자사 월렛이 아닌 모든 주소

6.2. 차등 정책¶

항목	내부 주소	외부 주소
승인 수준	간소화 (2-of-3)	전체 (정책 기반 M-of-N)
쿨다운	단축 (12시간)	기본 (48시간)
화이트리스트 등록	월렛 생성 시 자동 등록	수동 등록 + 쿼럼 승인
금액 한도	완화 (내부 재배분 목적)	엄격 (유출 방지)
감사 수준	표준	강화 (수신자 정보 추가 기록)

7. 체인별 주소 검증¶

7.1. 주소 포맷 유효성¶

체인	주소 포맷	검증 방법
BTC (Taproot)	bc1p... (Bech32m)	Bech32m 체크섬 검증
BTC (SegWit)	bc1q... (Bech32)	Bech32 체크섬 검증
BTC (Legacy)	1... / 3... (Base58Check)	Base58Check 검증
ETH/EVM	0x... (40 hex chars)	EIP-55 mixed-case checksum
Solana	Base58 (32 bytes)	길이 + Base58 디코딩 검증

7.2. 체인 불일치 방지¶

화이트리스트 등록 시:
  chain 필드와 address 포맷 교차 검증
    ├─ BTC 화이트리스트에 0x... 주소 → 차단 + 경고
    ├─ ETH 화이트리스트에 bc1... 주소 → 차단 + 경고
    └─ 주소 포맷이 선택 체인과 일치 → 통과

TX 생성 시:
  TX의 chain과 수신 주소의 화이트리스트 chain 매칭 확인
    └─ 불일치 → 즉시 차단

8. 컴플라이언스 매핑¶

제약조건 ID	설명	충족 방식
AC-TX-04	화이트리스트 주소 관리 (관리자 쿼럼 승인, 오프라인 동기화)	CRUD 전 과정 Admin 쿼럼 승인. 오프라인 앱 Merkle Root 동기화
AC-AC-03	관리자 쿼럼 승인 기반 권한 변경	화이트리스트 등록/삭제에 Admin 쿼럼(최소 2명) 필수
AC-AU-01	변조 불가 감사 로그	모든 화이트리스트 변경에 해시 체인 연결 감사 이벤트

본 문서는 Phase 3 Core Product Design의 일부로, 정책 엔진(policy-engine.md)의 화이트리스트 주소 검증 규칙이 본 문서의 화이트리스트 데이터를 참조한다. 에어갭 서명 플로우(airgap-signing-flow.md)의 Request 단계에서 화이트리스트 사전 검증이 수행된다.