Wellcoms Remote Control v1.0 — 원격 제어 기능 기획서

기존 /remote-support/ WebRTC 화면공유 인프라를 확장하여 원격 키보드/마우스 제어 기능을 추가.
고객은 전용 Windows .exe 다운로드, 관리자는 기존 브라우저 뷰어에서 그대로 제어.

• URL: https://www.wellcoms.co.kr/remote-support/
• 플러그인: wp-content/plugins/wellcoms-remote/ (v2.0.0 → v3.0.0)
• 신규 컴포넌트: wellcoms-remote-client/ (Windows .exe, 별도 GitLab 리포)
• 기준일: 2026-06-18
• 예상 기간: 5-6주 (Week 0 스파이크 + Week 1-5 개발, v1.0 출시 기준)

1. 개요

1.1 배경

/remote-support/ 페이지는 Phase 1(화면 공유/시청)이 완성된 상태로 운영 중이며, 개발문서 12장에 명시된 Phase 3 "원격 조작 (포터블 .exe 필요)" 단계에 해당한다.

1.2 목표

고객이 다운로드한 Windows .exe를 실행하면 기존과 동일하게 4자리 PIN이 발급되고, 관리자가 PIN으로 연결하여 화면 시청 + 키보드/마우스 제어를 수행할 수 있도록 한다. 단, 기존 브라우저 기반 "화면만 보기" 경로는 100% 보존한다(fallback 용도).

1.3 핵심 원칙

⚠️ 기존 "서버 코드 0줄 변경" 주장은 철회됨. Momus 검토 결과 시그널링 서버가 관리자를 인증하지 않는 보안 구멍 발견. 자세한 내용은 §4.4 참조.

1.4 v1.0 성공 기준 (Definition of Done)

다음 항목 모두 충족 시 v1.0 출시:

1.5 대상 사용자

1.6 범위 (In/Out)

2. 시스템 아키텍처

2.1 전체 구조

graph TB
    subgraph "고객 Windows"
        EXE["wellcoms-remote-client.exe
(C# .NET 8 + WPF)"]
        CAP["Windows.Graphics.Capture
화면 캡처 (하드웨어 가속)"]
        SI["user32!SendInput
키보드/마우스 주입"]
        EXE --> CAP
        EXE --> SI
    end


    subgraph "wellcoms.co.kr 서버 (대부분 기존 그대로)"
        WP["wellcoms_wp
WordPress + wellcoms-remote 플러그인 v3.0"]
        SIG["wellcoms_signal
Node.js WebSocket :3000
(관리자 토큰 검증 추가 — §4.4)"]
        TURN["wellcoms_turn
coturn :3478 (변경 없음)"]
    end


    subgraph "관리자 브라우저 (기존 뷰어 확장)"
        ADM["/remote-support/
(관리자 로그인)"]
        VIEW["📺 비디오 뷰어 (기존)"]
        INPUT["🖱️⌨️ 입력 오버레이 (신규)"]
        ADM --> VIEW
        ADM --> INPUT
    end


    CAP -->|"WebRTC Video Track"| VIEW
    INPUT -->|"WebRTC DataChannel 'input'"| SI
    EXE -->|"WSS 시그널링"| SIG
    ADM -->|"WSS 시그널링"| SIG
    CAP -.->|"P2P/TURN 릴레이"| VIEW
    INPUT -.->|"P2P/TURN 릴레이"| SI

2.2 WebRTC 연결 구조

graph LR
    subgraph "PeerConnection (1개)"
        VT["Video Track
(고객 → 관리자)"]
        DC_VID["DataChannel 'ctrl'
(양방향 제어 메시지)"]
        DC_IN["DataChannel 'input'
(관리자 → 고객 입력 이벤트)"]
    end

    EXE_C["고객 .exe"] --> VT
    EXE_C --> DC_VID
    ADM_C["관리자 브라우저"] --> DC_VID
    ADM_C --> DC_IN
    DC_IN --> EXE_C

핵심: 기존 비디오 트랙 1개에 DataChannel 2개를 추가한다. PeerConnection 자체는 1개이므로 NAT/TURN 협상 로직이 그대로 재사용된다.

2.3 Docker 구성 (signal 서버에 환경변수만 추가)

기존 docker-compose.yml에 WR_SECRET 환경변수만 추가:

services:
  wellcoms_db: ...           # MariaDB (동일)
  wordpress: ...             # WordPress (플러그인만 v3.0으로 업그레이드)
  wellcoms_signal:
    image: wellcoms-signal:latest
    environment:
      SIGNAL_PORT: "3000"
      WR_SECRET: ${WR_SECRET}   # 신규 — WordPress와 공유 (HMAC 서명용, §4.4)
  wellcoms_turn: ...         # TURN (동일)

신규 컨테이너 없음, 신규 포트 없음. signal 서버 이미지만 코드 수정 후 rebuild.

2.4 네트워크 프로토콜 (기존 + 확장)

기존 시그널링 메시지

신규 DataChannel 메시지 (P2P 직접, 서버 경유 안 함)

3. 구성요소별 설계

3.1 Windows 클라이언트 (.exe)

3.1.1 기술 스택

3.1.2 화면 캡처 파이프라인

graph LR
    DWM["DWM Compositor"] --> GC["GraphicsCaptureItem"]
    GC --> DF["Direct3D11CaptureFramePool"]
    DF --> TXT["D3D11Texture2D
(GPU 메모리)"]
    TXT --> ENC["MediaFoundation H.264 Encoder
(하드웨어 가속)"]
    ENC --> RTS["RTP 패킷"]
    RTS --> PC["RTCRtpSender"]
    PC -.->|"WebRTC Video Track"| ADM_C["관리자 브라우저"]

포인트: Direct3D11 텍스처를 H.264로 직접 인코딩 → CPU/GPU 오버헤드 최소화.

3.1.3 입력 주입 로직

// 마우스 무브 (절대 좌표 0..65535 정규화)
private static void MouseMove(int x, int y) {
    var input = new INPUT {
        type = INPUT_MOUSE,
        u = new InputUnion {
            mi = new MOUSEINPUT {
                dx = x * 65535 / Screen.PrimaryScreen.Bounds.Width,
                dy = y * 65535 / Screen.PrimaryScreen.Bounds.Height,
                dwFlags = MOUSEEVENTF_MOVE | MOUSEEVENTF_ABSOLUTE
            }
        }
    };
    SendInput(1, ref input, Marshal.SizeOf(input));
}


// 키보드 (가상 키 코드)
private static void KeyPress(ushort vk, bool down) {
    var input = new INPUT {
        type = INPUT_KEYBOARD,
        u = new InputUnion {
            ki = new KEYBDINPUT {
                wVk = vk,
                dwFlags = down ? 0 : KEYEVENTF_KEYUP
            }
        }
    };
    SendInput(1, ref input, Marshal.SizeOf(input));
}

3.1.4 클라이언트 상태 머신

stateDiagram-v2
    [*] --> Launching: exe 실행
    Launching --> Connecting: WSS 연결 시도
    Connecting --> Waiting: create_room → PIN 발급
    Waiting --> Connected: 관리자 입장 (peer_joined)
    Connected --> Signaling: SDP/ICE 교환
    Signaling --> Streaming: P2P 연결 완료
    Streaming --> AwaitingApproval: 관리자 request_control
    AwaitingApproval --> Controlled: 사용자 승인
    AwaitingApproval --> Streaming: 사용자 거절/타임아웃
    Controlled --> Streaming: 관리자/사용자 제어 중지
    Controlled --> Controlled: 입력 이벤트 수신
    Streaming --> Ended: 연결 종료
    Waiting --> Ended: 30분 타임아웃
    Ended --> [*]

3.1.5 UI (WPF 단일 창)

┌──────────────────────────────────────┐
│ 웰컴스 원격 지원              [_][□][×]│
├──────────────────────────────────────┤
│                                       │
│          4 8 2 7                      │
│      (PIN, 48pt 굵게)                 │
│                                       │
│   📺 화면 공유 중 (관리자 대기)        │
│                                       │
│   [복사] [소리로 듣기]                 │
│                                       │
│ ─────────────────────────────────────│
│ ℹ️ 이 번호를 전화로 안내해주세요       │
│ ⚠️ 원격 제어 요청 시 이 창에서         │
│    반드시 [허용]을 눌러주세요          │
│                                       │
│ [공유 중지]                            │
└──────────────────────────────────────┘

3.2 관리자 뷰어 확장 (wellcoms-remote.php)

3.2.1 변경 사항 요약

기존 shortcode [wellcoms_screen_share] 내부에 다음을 추가:

1. DataChannel 'input' 생성 (관리자가 Offer 시 createDataChannel)
2. <video> 위 입력 오버레이 (투명 div로 마우스 캡처)
3. "원격 제어" 토글 버튼 (기본 OFF — 보기 전용)
4. 제어 요청 모달 (고객에게 승인 프롬프트 표시)
5. 관리자 커서 시각화 (고객 화면에 커서 위치 표시)

3.2.2 입력 오버레이 (JS 의사코드)

// 비디오 위에 투명 div를 올려서 모든 입력 이벤트 가로채기
const overlay = document.createElement('div');
overlay.className = 'wr-input-overlay';
overlay.style.display = 'none';  // 기본 OFF


// 토글 ON 시
function enableControl() {
  if (!inputDC || inputDC.readyState !== 'open') {
    toast('제어 채널이 없습니다', 'error'); return;
  }
  // 고객에게 제어 권한 요청
  inputDC.send(JSON.stringify({type: 'request_control'}));
  // 고객 승인 대기 모달 표시
  showControlRequestModal();
}


overlay.addEventListener('mousemove', e => {
  const rect = video.getBoundingClientRect();
  const scaleX = video.videoWidth / rect.width;
  const scaleY = video.videoHeight / rect.height;
  const x = Math.floor((e.clientX - rect.left) * scaleX);
  const y = Math.floor((e.clientY - rect.top) * scaleY);
  inputDC.send(JSON.stringify({type: 'mouse_move', x, y}));
});


overlay.addEventListener('mousedown', e => {
  const btn = e.button === 0 ? 'left' : e.button === 2 ? 'right' : 'middle';
  inputDC.send(JSON.stringify({type: 'mouse_down', button: btn}));
});


// wheel, keydown, keyup, mouseup, contextmenu(차단) 유사 패턴

3.2.3 좌표 변환

graph LR
    MM["관리자 마우스
clientX, clientY"] --> RECT["video.getBoundingClientRect()"]
    RECT --> SCALE["videoWidth / rect.width"]
    SCALE --> NORM["원격 해상도 기준 x, y"]
    NORM --> DC["DataChannel mouse_move"]
    DC --> EXE["고객 .exe 수신"]
    EXE --> SI["SendInput 절대 좌표 (0..65535)"]

주의점:

• 비디오가 object-fit: contain이면 레터박스 영역은 무시해야 함 (rect와 실제 비디오 영역이 다름)
• 줌/전체화면 모드에서도 비율 유지
• 고객 모니터 해상도가 관리자 화면보다 크면 정밀도 저하 → v2에서 가속도/상대좌표 모드 옵션

3.3 시그널링 서버 (관리자 토큰 검증 추가)

⚠️ 기존 "변경 없음" 주장은 철회. §4.4에서 설명한 보안 구멍(누구나 PIN으로 join 가능)을 막기 위해 관리자 토큰 검증 로직이 추가되어야 한다.

3.3.1 변경 사항

signal/server.js의 join_room 케이스에 토큰 검증을 추가:

// AS-IS (취약)
case 'join_room': {
    const pin = String(msg.pin || '');
    // ... PIN만 체크
}


// TO-BE (안전)
case 'join_room': {
    const pin = String(msg.pin || '');
    const adminPayload = verifyAdminToken(msg.token);
    if (!adminPayload) {
        send(ws, { type: 'error', message: '관리자 인증 필요' });
        ws.close(1008, 'unauthorized');
        return;
    }
    ws._admin_id = adminPayload.admin_id;
    ws._admin_name = adminPayload.admin_name;
    // ... 이후 기존 로직
    send(room.host, { type: 'peer_joined', admin_name: adminPayload.admin_name });
}

3.3.2 v1 호환성 전략

• Phase 1 브라우저 고객(viewer)용 호환 모드: 토큰 없는 join도 3개월간 허용하되 제어 권한 없음 (view only). 이후 강제.
• Phase 3 .exe 고객용: 토큰 없는 join 시도 → 즉시 거부

3.3.3 docker-compose.yml 변경

wellcoms_signal 컨테이너에 환경변수 추가:

wellcoms_signal:
  image: wellcoms-signal:latest
  environment:
    SIGNAL_PORT: "3000"
    WR_SECRET: ${WR_SECRET}  # WordPress와 공유 (HMAC 서명용)

.env 파일에 WR_SECRET=<랜덤 64바이트 hex> 추가.

3.3.4 세션 로깅 (부가)

토큰에서 얻은 admin_id를 DB 세션 로그에 기록:

// peer_joined 시
db.query('INSERT INTO wp_wr_sessions SET ?', {
    pin, customer_ip: host._ip, admin_user_id: adminPayload.admin_id,
    started_at: new Date()
});

3.4 워드프레스 플러그인 확장

3.4.1 신규 메뉴/기능

3.4.2 세션 감사 로그 (DB)

CREATE TABLE wp_wr_sessions (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  pin VARCHAR(4) NOT NULL,
  customer_ip VARCHAR(45),
  admin_user_id BIGINT,
  started_at DATETIME,
  ended_at DATETIME,
  control_enabled TINYINT DEFAULT 0,
  control_duration_sec INT DEFAULT 0,
  exit_reason VARCHAR(32),  -- 'admin_disconnect' | 'customer_disconnect' | 'timeout' | 'error'
  INDEX idx_pin (pin),
  INDEX idx_started (started_at)
);

로깅 시점: create_room 시 INSERT, peer_left/cleanup 시 UPDATE.

3.5 .exe 배포 전략

3.5.1 문제 상황

유료 코드 서명 인증서($200-400/년) 없이 Windows .exe를 배포할 때:

• Edge/Chrome 다운로드 차단: "일반적으로 다운로드하지 않음" 경고
• SmartScreen: "Windows가 PC를 보호했습니다" 파란 창
• Windows Defender: 휴리스틱 false positive 가능성
• MOTW (Mark of the Web): 인터넷에서 다운로드된 파일 자동 의심

3.5.2 옵션 분석

3.5.3 추천 전략 (2단계)

1단계 (v1 출시, 무료): .zip 묶음 + 다운로드 페이지 상세 안내

• 고객은 wellcoms-remote-v1.zip 다운로드 (내부에 .exe 1개 + 사용법.txt)
• ZIP은 Edge/Chrome에서 직접 .exe보다 덜 공격적으로 차단
• /remote-support/ 페이지에 다운로드 방법 스크린샷 + 음성 안내
• 관리자가 전화로 "파란 창 뜨면 '추가 정보' → '실행' 누르세요" 안내 (이미 전화 연결 상태이므로 마찰 적음)
• PE 헤더에 버전/회사/저작권 정보 명시 (일부 AV 휴리스틽 완화)

2단계 (v1.1+, $10/월): Microsoft Trusted Signing 도입

• SmartScreen 경고 완전 제거
• Azure Trusted Signing 서비스 가입 ($9.99/월, 비즈니스 인증 필요 1-2주)
• 빌드 파이프라인에서 자동 서명
• 월 50건 트래픽에 $10/월이면 충분히 가성비

3.5.4 .exe 자체 최적화 (서명과 무관)

• PE 헤더 메타데이터: Version Info, Company Name, Copyright, Description 명시
• 매니페스트: requestedExecutionLevel="asInvoker" (UAC 프롬프트 회피)
• DPI 인식: Windows 10/11 호환성 매니페스트 포함
• AV 제출: VirusTotal 제출 + Microsoft Security Intelligence false positive 제보
• 단일 파일 publish: .NET trim + PublishSingleFile=true (의존성 누락 방지)
• Rust 고려: C# .NET 단일 파일 exe는 일부 AV(특히 Kaspersky)에서 false positive 높음. Rust는 훨씬 낮음. 만약 AV 문제 심하면 Rust + libdatachannel로 전환 검토

3.5.5 다운로드 페이지 UX

┌──────────────────────────────────────────────────┐
│ 🖥️ 원격 지원 — Windows 프로그램 다운로드            │
├──────────────────────────────────────────────────┤
│                                                   │
│  [💼 wellcoms-remote-v1.zip 다운로드] (28MB)      │
│                                                   │
│  📋 사용 순서:                                     │
│  1. 위 버튼 클릭 → 다운로드                         │
│  2. 다운로드된 ZIP 파일 압축 해제                   │
│  3. wellcoms-remote.exe 실행                       │
│  4. 화면에 표시된 4자리 번호를 전화로 안내           │
│                                                   │
│  ⚠️ "Windows가 PC를 보호했습니다" 파란 창이 뜨면:    │
│     → [추가 정보] 클릭                             │
│     → [실행] 버튼 클릭                             │
│                                                   │
│  📞 문의: 02-XXXX-XXXX                            │
│                                                   │
└──────────────────────────────────────────────────┘

3.6 통신 흐름 (전체 시퀀스)

sequenceDiagram
    actor C as 고객
    participant EXE as .exe 클라이언트
    participant SIG as 시그널링 서버
    participant ADM as 관리자 브라우저
    actor A as 관리자


    Note over C,A: Phase 1 — PIN 발급

    C->>EXE: wellcoms-remote.exe 실행
    EXE->>SIG: WSS 연결
    EXE->>SIG: create_room
    SIG-->>EXE: room_created {pin: "4827"}
    EXE-->>C: PIN 4827 표시
    C->>A: (전화) "4827번입니다"


    Note over C,A: Phase 2 — 관리자 연결

    A->>ADM: /remote-support/ 접속 (로그인)
    A->>ADM: PIN 4827 입력 + 연결
    ADM->>SIG: join_room {pin}
    SIG-->>EXE: peer_joined
    SIG-->>ADM: peer_joined


    Note over C,A: Phase 3 — WebRTC 협상

    EXE->>SIG: sdp_offer (video track + DataChannels)
    SIG->>ADM: sdp_offer
    ADM->>SIG: sdp_answer
    SIG->>EXE: sdp_answer
    Note over EXE,ADM: ICE candidates 교환


    Note over C,A: Phase 4 — 스트리밍 + 제어

    EXE-->>ADM: Video Track (고객 화면)
    ADM-->>A: 

4. 보안 설계

4.1 위협 모델

graph LR
    subgraph "위협"
        T1["무단 제어"]
        T2["PIN 브루트포스"]
        T3["세션 하이재킹"]
        T4["입력 인젝션 악용"]
        T5["변조된 exe 배포"]
    end

    subgraph "대응"
        D1["WP 관리자 인증 + 승인 프롬프트"]
        D2["PIN 5회 실패 시 5분 차단 (기존)"]
        D3["WSS TLS + SRTP (기존)"]
        D4["제어는 명시적 허용 후에만, 언제든 철회 가능"]
        D5["HTTPS 다운로드 + SHA256 체크섬 게시"]
    end

    T1 --> D1
    T2 --> D2
    T3 --> D3
    T4 --> D4
    T5 --> D5

4.2 보안 체크리스트

4.3 사용자 승인 프롬프트 (.exe 측)

┌──────────────────────────────────────┐
│ ⚠️ 원격 제어 요청                       │
├──────────────────────────────────────┤
│                                       │
│  상담원이 회원님의 컴퓨터를             │
│  직접 조작하려고 합니다.                │
│                                       │
│  • 마우스와 키보드를 제어할 수 있습니다 │
│  • 언제든 [제어 중지]로 중단 가능합니다 │
│  • 세션 종료 시 모든 권한이 사라집니다  │
│                                       │
│  [거절]      [10초 후 자동 거절]       │
│             [✓ 허용]                   │
│                                       │
└──────────────────────────────────────┘

기본 동작: 15초 내 응답 없으면 자동 거절 (보수적 설계).

승인 모달에 표시되는 관리자 정보 (토큰 인증 도입 시 — §4.4):

✓ wellcoms.co.kr 인증된 관리자
  이름: 김철수 (jskim)
  접속 시각: 2026-06-18 14:32

4.4 관리자 토큰 인증 (필수 — 신규 추가)

⚠️ 이 섹션은 Momus 검토에서 발견된 critical 보안 구멍에 대한 대응이다.
기존 signal/server.js는 join_room {pin} 메시지를 받으면 PIN만 맞으면 무조건 viewer로 등록한다.
WordPress의 wr_is_admin() 체크는 페이지 렌더링 시점에만 수행되며, WS 연결 자체를 인증하지 않는다.
Phase 1(보기 전용)에서는 감수 가능했으나, Phase 3(제어 권한 부여)에서는 심각한 취약점이 된다.

4.4.1 공격 시나리오 (방어하지 않을 경우)

1. 공격자가 정당한 고객의 PIN을 우연히/사회공학적으로 입수
   (예: 전화 도청, 화면 캡처, PIN 재사용 등)
2. 공격자가 브라우저 개발자 도구 또는 커스텀 WS 클라이언트로
   wss://wellcoms.co.kr/signal/ 에 직접 연결
3. {type: 'join_room', pin: '4827'} 전송 → 서버가 무조건 수락
4. 고객 화면 WebRTC 스트림 수신 → **개인정보 유출**
5. 여기에 Phase 3 제어 권한이 더해지면:
   - {type: 'request_control'} 전송
   - 고객이 "관리자가 요청했다"고 착각하고 승인
   - 공격자가 마우스/키보드 완전 제어 → **랜섬웨어 설치, 금융 정보 탈취 등**

4.4.2 해결책: 관리자 토큰 (HMAC 서명)

sequenceDiagram
    participant A as 관리자 브라우저
    participant WP as WordPress (PHP)
    participant SIG as Signal 서버
    participant EXE as 고객 .exe

    Note over A,WP: 페이지 로드 시
    A->>WP: /remote-support/ 접속
    WP->>WP: wr_is_admin() 검증
    WP->>WP: 토큰 생성
{admin_id, exp, nonce} + HMAC-SHA256(WR_SECRET)
    WP-->>A: 페이지에 토큰 주입 (JS 변수)

    Note over A,SIG: WS 연결 시
    A->>SIG: join_room {pin, token}
    SIG->>SIG: 토큰 검증 (HMAC + 만료 + nonce)
    alt 토큰 유효
        SIG-->>A: peer_joined
        SIG->>EXE: peer_joined {admin_name, admin_id}
        EXE->>EXE: "김철수 관리자 연결됨" 표시
    else 토큰 무효
        SIG-->>A: error "인증 실패"
    end

4.4.3 토큰 명세

생성 (PHP, 플러그인 내):

function wr_generate_admin_token() {
    if (!wr_is_admin()) return null;
    $payload = [
        'admin_id' => get_current_user_id(),
        'admin_name' => wp_get_current_user()->display_name,
        'exp' => time() + 300,  // 5분 유효
        'nonce' => wp_create_nonce('wr_admin_token'),
    ];
    $payload_b64 = base64_encode(json_encode($payload));
    $sig = hash_hmac('sha256', $payload_b64, WR_SECRET);
    return $payload_b64 . '.' . $sig;
}

검증 (Node.js, signal/server.js에 추가):

const WR_SECRET = process.env.WR_SECRET;  // docker-compose로 주입


function verifyAdminToken(token) {
    if (!token || !WR_SECRET) return null;
    const [payload_b64, sig] = token.split('.');
    if (!payload_b64 || !sig) return null;

    const expectedSig = crypto
        .createHmac('sha256', WR_SECRET)
        .update(payload_b64)
        .digest('hex');

    if (sig !== expectedSig) return null;  // 서명 불일치

    let payload;
    try { payload = JSON.parse(Buffer.from(payload_b64, 'base64')); }
    catch { return null; }

    if (Date.now() / 1000 > payload.exp) return null;  // 만료
    return payload;  // {admin_id, admin_name, exp, nonce}
}


// join_room 처리 시 (기존 코드 수정)
case 'join_room': {
    const payload = verifyAdminToken(msg.token);
    if (!payload) {
        send(ws, { type: 'error', message: '관리자 인증 실패' });
        ws.close(1008, 'unauthorized');
        return;
    }
    ws._admin_id = payload.admin_id;
    ws._admin_name = payload.admin_name;
    // ... 기존 room 매칭 로직 ...
    // 고객에게 admin_name 전달
    send(room.host, { type: 'peer_joined', admin_name: payload.admin_name });
}

WR_SECRET 공유: docker-compose.yml에 환경변수로 동일한 값 주입 (WP와 signal 컨테이너 양쪽).

4.4.4 v1과 v2 호환성

• 기존 브라우저 고객 (토큰 없는 브라우저 viewer): Phase 1 호환을 위해 토큰 없는 join도 일단 허용하되 제어 권한은 부여하지 않음 (view only)
• 새 .exe 고객 + 토큰 있는 관리자: 완전한 기능 (view + control)
• 마이그레이션: 3개월 후 토큰 강제 (Phase 1 브라우저 viewer도 토큰 발급받도록 플러그인 업데이트)

4.5 입력 채널 추가 보안

4.5.1 입력 이벤트 속도 제한 (Rate Limiting)

악성/버그 관리자가 입력 이벤트 폭탄으로 고객 .exe에 부하를 가하는 것을 방지:

고객 .exe에서 버퍼와 타임스탬프로 검사. 초과 분은 조용히 무시.

4.5.2 브라우저 예약 키 필터링 (관리자 측)

관리자 브라우저에서 다음 키 조합은 고객에게 전송하지 않고 브라우저가 처리하도록 허용:

구현: keydown 핸들러에서 이 키들은 e.preventDefault() 하지 않고 return.

4.5.3 관리자 입력 캡처 중 절대 차단 키

다음 키는 고객에게 보내면 안 되는 위험한 키이므로 하드코트 차단:

5. UI/UX 설계

5.1 고객 .exe UI 흐름

graph TD
    L["exe 실행"] --> CONN["WSS 연결 중..."]
    CONN --> WAIT["PIN 표시 대기 화면"]
    WAIT --> STREAM["📺 화면 공유 중 + 관리자 대기"]
    STREAM --> CTRL_REQ["⚠️ 관리자 제어 요청 모달"]
    CTRL_REQ -->|"허용"| ACTIVE["🔴 제어 중 (빨간 테두리)"]
    CTRL_REQ -->|"거절"| STREAM
    ACTIVE -->|"관리자/고객 중지"| STREAM
    STREAM --> END["종료"]

5.2 관리자 브라우저 UI (확장)

기존 관리자 화면에 다음 요소 추가:

<!-- 기존: 비디오 + 전체화면 + 연결종료 버튼 -->
<div class="wr-toolbar">
  <button id="btnFullscreen">전체화면</button>
  <!-- 신규 -->
  <button id="btnControlToggle">🎮 원격 제어</button>
  <button id="btnDisconnect">연결 종료</button>
</div>


<!-- 비디오 위 투명 오버레이 (제어 시 표시) -->
<div id="inputOverlay" class="wr-input-overlay">
  <!-- 마우스 이벤트 캡처용 -->
  <div id="remoteCursor"></div>
</div>


<!-- 상태 표시 추가 -->
<div class="wr-status">
  <span class="wr-dot active"></span>
  <span>시청 중</span>
  <!-- 신규 -->
  <span id="ctrlStatus" class="wr-ctrl-status">보기 전용</span>
</div>

5.3 시각적 피드백 (고객 측)

6. 구현 단계 (5-6주)

Week 0: 기술 검증 스파이크 (3-5일, 병렬 수행 가능)

🚨 필수 스파이크. SIPSorcery가 비디오 + DataChannel 동시 지원하는지 먼저 검증한다.
실패 시 전체 계획 재검토 (Rust + libdatachannel 전환 등).

실패 시 폴백:

• SIPSorcery 불안정 → Rust + libdatachannel + gfx-rs 전환 (개발 기간 +2주)
• GraphicsCapture 복잡 → SharpDX 또는 ScreenCaptureLib 래퍼 사용

Week 1: 기반 구축 + .exe 프로토타입

Week 2: 화면 캡처 + 비디오 스트리밍

Week 3: 입력 제어 채널

Week 4: 보안 + UX 폴리싱

Week 5: 배포 + 테스트

7. 리스크와 대응

8. 테스트 계획

8.1 단위 테스트

8.2 통합 테스트

8.3 호환성 매트릭스

8.4 성능 목표

9. 운영 / 유지보수

9.1 일상 운영

• 서버 모니터링: 기존 wellcoms_signal, wellcoms_turn 로그 확인
• 세션 로그 검토: 주간으로 wp_wr_sessions 테이블 확인
• 버전 관리: GitLab에 wp-wellcoms-remote-client 리포 운영

9.2 장애 대응

9.3 업데이트 정책

10. 향후 확장 (v2+)

graph TD
    V1["v1.0
원격 제어 기본
(이번 구현)"]
    V11["v1.1
자동 업데이트
세션 녹화"]
    V12["v1.2
파일 전송
클립보드 동기화"]
    V13["v1.3
멀티 모니터
관리자 커서 시각화"]
    V2["v2.0
UAC 권한 제어
(서비스 모드)"]
    V3["v3.0
음성 통화
재부팅 후 재연결"]

    V1 --> V11 --> V12 --> V13
    V13 --> V2 --> V3

우선순위 후보

1. 세션 녹화 (v1.1) — 법적 보호, 품질 관리. WebRTC MediaRecorder로 mp4 저장
2. 자동 업데이트 (v1.1) — .exe 버전 체크, 백그라운드 다운로드, 재시작
3. 파일 전송 (v1.2) — DataChannel 'file' 추가, 드래그 앤 드롭
4. 클립보드 동기화 (v1.2) — 텍스트만 1차, 이미지는 v2
5. UAC 권한 (v2.0) — 서비스 모드 exe (별도 Windows Service), 관리자 권한 앱 제어
6. 재부팅 후 재연결 (v3.0) — 서비스 + 부팅 시 자동 재연결
7. 음성 통화 (v3.0) — WebRTC Audio Track 추가 (마이크)
8. 세션 메모/태그 — 관리자가 메모, 티켓 시스템 연동

11. 파일 구조 (예상)

11.1 기존 플러그인 (수정)

wp-content/plugins/wellcoms-remote/
├── wellcoms-remote.php                    ← v2.0.0 → v3.0.0 (입력 오버레이, 토글, 로깅 추가)
├── templates/
│   └── page-remote.php                    ← 다운로드 섹션 추가
├── signal/
│   ├── server.js                          ← 변경 없음 (옵션: 로깅 추가)
│   ├── package.json
│   └── Dockerfile
├── includes/                              ← 신규
│   ├── class-wr-session-log.php           ← 세션 로그 DB
│   └── class-wr-rest.php                  ← REST API (버전, 다운로드)
└── assets/                                ← 신규 (입력 오버레이 CSS)
    └── css/input-overlay.css

11.2 신규 클라이언트 리포

wp-wellcoms-remote-client/                  ← GitLab 별도 리포
├── WellcomsRemote.sln                      ← Visual Studio 솔루션
├── WellcomsRemote/
│   ├── App.xaml / App.xaml.cs              ← WPF 진입점
│   ├── MainWindow.xaml / .cs               ← 메인 UI (PIN, 상태)
│   ├── ControlApprovalWindow.xaml / .cs    ← 승인 모달
│   ├── Core/
│   │   ├── SignalingClient.cs              ← WS 클라이언트 (기존 프로토콜)
│   │   ├── WebRtcPeer.cs                   ← SIPSorcery 래퍼
│   │   ├── ScreenCapturer.cs               ← GraphicsCapture 통합
│   │   ├── H264Encoder.cs                  ← MediaFoundation 인코더
│   │   ├── InputInjector.cs                ← SendInput P/Invoke
│   │   └── InputChannel.cs                 ← DataChannel 'input' 처리
│   ├── Models/
│   │   ├── InputEvent.cs                   ← JSON → C# 모델
│   │   └── SessionState.cs                 ← 상태 머신
│   └── docs/
│       └── README.md
├── WellcomsRemote.Tests/                   ← xUnit 단위 테스트
└── scripts/
    ├── publish.ps1                          ← Single-file publish 스크립트
    └── sign.ps1                            ← (향후) Trusted Signing 연동

11.3 배포 아티팩트

wellcoms-remote-v1.0.0.zip                  ← GitHub Release / WP uploads
├── WellcomsRemote.exe                      ← 단일 파일 (~30-50MB)
├── 사용법.txt                              ← 한국어 안내
└── version.txt                             ← 버전 + SHA256

12. 의사결정 기록 (ADR)

ADR-001: RustDesk 대신 기존 WebRTC 확장

• 결정: RustDesk 화이트래블 도입하지 않고 기존 wellcoms-remote 인프라 확장
• 이유: 기존 signal/turn/플러그 인 대부분 재사용, 관리자 UX 동일, 100% 자체 코드
• 수정 (Momus 검토 반영): "100% 재사용"은 과장. signal 서버에 관리자 토큰 검증 로직 추가 필요 (기존 보안 구멍 수습)
• 트레이드오프: 개발 기간 5-6주 vs RustDesk 셋업 2-4주 (하지만 통합 비용 추가)

ADR-002: C# .NET 8 선택

• 결정: 클라이언트를 C# .NET 8 + WPF로 개발
• 이유: Windows API 접근 용이, WPF 간단한 UI, 단일 exe 배포, 팀 학습 곡선 완만
• 트레이드오프: AV false positive (Rust보다 높음), 파일 크기 (~30MB vs Rust ~10MB)
• 폴백: AV 문제 심하면 Rust + libdatachannel로 전환 검토

ADR-003: 1단계 무료 배포, 2단계 Trusted Signing

• 결정: v1은 ZIP+안내 무료 배포, v1.1+에서 Microsoft Trusted Signing 도입
• 이유: 초기 검증 우선, $10/월 가성비로 SmartScreen 완전 제거
• 트레이드오프: v1 사용자 마찰 (전화 안내로 완화)

ADR-004: DataChannel 'input' 단일 채널

• 결정: 입력 이벤트를 별도 채널이 아닌 DataChannel 'input' 하나로 멀티플렉싱
• 이유: 채널 수 최소화, 순서 보장 (ordered mode), 구현 단순
• 트레이드오프: 입력 이벤트 폭주 시 채널 혼잡 (throttle로 완화)

ADR-005: v1은 asInvoker (UAC 미권한)

• 결정: v1은 관리자 권한 요청하지 않음 (asInvoker 매니페스트)
• 이유: UAC 프롬프트 회피로 UX 개선, 대부분의 일반 앱 제어 가능
• 트레이드오행: 관리자 권한 앱(예: 작업 관리자, 일부 설정) 제어 불가 → v2 서비스 모드로 해결

ADR-006: 관리자 토큰 인증 추가 (Momus 검토 반영)

• 결정: 시그널링 서버에 HMAC 기반 관리자 토큰 검증 추가 (§4.4)
• 배경: 기존 signal 서버는 PIN만으로 viewer를 승인. WordPress 페이지 렌더링 시점의 wr_is_admin() 체크와 무관하게 WS 직접 연결로 우회 가능. Phase 1(view only)에서는 감수 가능했으나 Phase 3(control)에서는 critical 취약점.
• 이유:
  • PIN 유출 + WS 직접 연결 → 무단 제어 가능 (랜섬웨어, 정보 탈취 위험)
  • 관리자 토큰 (HMAC 서명, 5분 만료, nonce)으로 WS 레벨 인증 추가
  • 고객 .exe에서 "어떤 관리자가 연결했는지" 표시 가능 (승인 프롬프트 신뢰성 향상)
• 트레이드오프:
  • signal 서버 코드 변경 (약 50줄 추가)
  • docker-compose에 WR_SECRET 환경변수 추가
  • WP 플러그인에서 토큰 발급 로직 추가
  • 기존 Phase 1 브라우저 viewer와 3개월 호환 모드 유지
• 대안 검토:
  • JWT (JSON Web Token) — 표준이지만 의존성 추가. HMAC 직접 구현이 더 단순
  • WS 연결 시 WP 쿠키 검증 — WP와 signal이 다른 컨테이너라 세션 공유 복잡
  • mTLS — 오버킬, 관리자 브라우저에 인증서 설치 불가

ADR-007: Week 0 스파이크 의무화

• 결정: 본 개발 착수 전 3-5일간 기술 검증 스파이크 수행 (§6 Week 0)
• 배경: SIPSorcery의 비디오+DataChannel 동시 처리 능력, MediaFoundation H.264 인코딩 성능, SendInput 정확도를 사전 검증하지 않으면 Week 2-3에 재앙 발생 가능
• Go/No-Go 기준: 4개 스파이크 모두 PASS. 1개라도 FAIL → 대안 기술 검토 (Rust 전환 등)
• 트레이드오프: 개발 기간 +1주 (5-6주 → 6-7주), 하지만 리스크 대폭 감소

13. 참조

• 기존 개발문서: 웹화면뷰어-개발.md (Phase 1-2 완료 내역)
• 공개 소개서: 웹화면뷰어-개발-공개.md
• 워드프레스 플러그인: data/wp-content/plugins/wellcoms-remote/
• 시그널링 서버: signal/server.js (관리자 토큰 검증 추가 — §3.3, §4.4 참조)
• 관련 GitLab: gitlab.wellcoms.co.kr/jskim/wp-wellcoms-remote (기존)

외부 기술 참조

• Windows.Graphics.Capture API — 공식 화면 캡처
• SendInput function — 입력 주입
• SIPSorcery — C# WebRTC 라이브러리
• Microsoft Trusted Signing — 클라우드 코드 서명
• WebRTC DataChannel API — 브라우저 측

부록 A: 핵심 용어