From 005c7bf44c67b998c4bd0d543d88557f70145848 Mon Sep 17 00:00:00 2001
From: claude-bot <claude-bot@tkrmagid.kr>
Date: Sun, 5 Jul 2026 21:26:13 +0900
Subject: [PATCH] installer-pf: accurate CGNAT detection via router WAN vs
 public IP
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

리뷰 지적 반영. 기존엔 HTTP 공인 egress IP 만 100.64/10 검사라, 전형적 CGNAT
(egress 는 ISP 공인, 라우터 WAN 만 100.64)을 놓치고 "CGNAT 아님"처럼 오진 가능.
- 라우터 WAN(IGD 외부) IP 를 UPnP 로 조회해 HTTP 공인 IP 와 비교.
- cgnat 를 3-state(yes/no/unknown)로: WAN 이 사설/CGNAT 이거나 공인 IP 와 다르면
  yes, 같으면 no, WAN 못 읽으면 unknown.
- unknown 이면 "외부 IP만으론 CGNAT 확정/배제 불가, 라우터 WAN 확인" 안내.
- WAN 조회 타임아웃 8s→6s. v0.3.17.

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>
---
 installer-pf/renderer.js        |  7 +++--
 locales/installer-pf/ko-kr.json |  8 ++++--
 package.json                    |  2 +-
 src/installer-pf/main.ts        | 49 +++++++++++++++++++++++++--------
 src/installer-pf/preload.ts     |  3 ++
 5 files changed, 52 insertions(+), 17 deletions(-)

diff --git a/installer-pf/renderer.js b/installer-pf/renderer.js
index 5ce4838..ae5ee28 100644
--- a/installer-pf/renderer.js
+++ b/installer-pf/renderer.js
@@ -112,9 +112,12 @@ function renderMain() {
     // 실패/확인불가일 때 다음 조치 안내: CGNAT 경고 + 수동 포워딩 방법.
     var extra = ''
     if (outcome.reachable !== true) {
-      if (outcome.cgnat) {
+      if (outcome.cgnat === 'yes') {
         extra += '<p class="formMessage error" style="margin-top:8px;">' +
-          escapeHtml(tt('main.cgnatWarn', { ip: outcome.externalIp || '?' })) + '</p>'
+          escapeHtml(tt('main.cgnatWarn', { public: outcome.externalIp || '?', wan: outcome.wanIp || '?' })) + '</p>'
+      } else if (outcome.cgnat === 'unknown') {
+        extra += '<p class="formMessage" style="margin-top:8px;">' +
+          escapeHtml(tt('main.cgnatUnknown', { ip: outcome.externalIp || '?' })) + '</p>'
       }
       var manual = outcome.localIp
         ? tt('main.manualForward', { port: outcome.port, localIp: outcome.localIp })
diff --git a/locales/installer-pf/ko-kr.json b/locales/installer-pf/ko-kr.json
index 544ed0a..6b2fa96 100644
--- a/locales/installer-pf/ko-kr.json
+++ b/locales/installer-pf/ko-kr.json
@@ -27,7 +27,8 @@
     "unknownMsg": "외부 도달 여부를 확정하지 못했습니다(외부 점검 서비스 응답 없음). 포트 매핑은 등록되었을 수 있습니다. 잠시 후 다시 시도하거나, 실제 접속으로 확인하세요.",
     "manualForward": "자동(UPnP) 개방이 안 되면 라우터 관리페이지에서 수동 포워딩: 외부 TCP {{port}} → 이 PC({{localIp}}) : {{port}}. 그리고 Windows 방화벽에서 TCP {{port}} 인바운드를 허용하세요.",
     "manualForwardNoIp": "이 PC 의 LAN IP 를 확인하지 못했습니다. 라우터에서 이 PC 로 외부 TCP {{port}} 포워딩과 Windows 방화벽 인바운드 허용을 설정하세요.",
-    "cgnatWarn": "주의: 외부 IP({{ip}})가 CGNAT(이중 NAT) 대역입니다. 이 경우 공유기 포트포워딩만으로는 외부 접속이 불가능하며, ISP 에 공인 IP 를 요청하거나 별도 터널링이 필요합니다.",
+    "cgnatWarn": "주의: CGNAT/이중 NAT 로 보입니다(공인 IP {{public}} ≠ 라우터 WAN {{wan}}, 또는 WAN 이 사설/CGNAT 대역). 이 경우 공유기 포트포워딩만으로는 외부 접속이 불가능하며, ISP 에 공인 IP 를 요청하거나 별도 터널링이 필요합니다.",
+    "cgnatUnknown": "참고: 외부 IP({{ip}})만으로는 CGNAT(이중 NAT) 를 확정하거나 배제할 수 없습니다(라우터 UPnP 미응답으로 WAN IP 미확인). 라우터 관리페이지의 WAN(인터넷) IP 가 100.64~100.127 이거나 10.x / 192.168.x / 172.16~31 대역이면 이중 NAT 라 공유기 포워딩만으론 외부 접속이 안 됩니다.",
     "detailLabel": "점검 상세: {{detail}}",
     "error": "오류: {{message}}",
     "closed": "포트 {{port}} 매핑을 제거했습니다."
@@ -35,7 +36,10 @@
   "log": {
     "start": "포트포워딩 시작: TCP {{port}}",
     "localIp": "이 PC LAN IP: {{ip}}",
-    "cgnatDetected": "CGNAT(이중 NAT) 감지: 외부 IP {{ip}} 는 100.64~100.127 대역. 공유기 포워딩만으론 외부 접속 불가.",
+    "routerWan": "라우터 WAN(UPnP) IP: {{ip}}",
+    "routerWanUnknown": "라우터 WAN IP 확인 불가(UPnP 미응답/거부) → 외부 IP 만으로는 CGNAT 확정/배제 불가",
+    "cgnatDetected": "CGNAT/이중 NAT 감지: 공인 IP {{public}} vs 라우터 WAN {{wan}}. 공유기 포워딩만으론 외부 접속 불가.",
+    "cgnatUnknown": "CGNAT 여부 확정 불가(라우터 WAN IP 미확인). 라우터 관리페이지에서 WAN IP 를 확인하세요.",
     "upnpUnavailable": "라우터가 UPnP 제어 연결을 거부/미지원(ECONNREFUSED/타임아웃). 라우터에서 UPnP 를 켜거나 수동 포워딩이 필요합니다.",
     "cleanup": "이전 UPnP 매핑 정리 중…",
     "externalIpHttp": "외부 IP(HTTP): {{ip}}",
diff --git a/package.json b/package.json
index ad8e58a..1c70ec2 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "minecraft-music-quiz-installer",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "description": "마인크래프트 음악퀴즈 간편설치기 + 관리 사이트",
   "main": "dist/installer/main.js",
   "scripts": {
diff --git a/src/installer-pf/main.ts b/src/installer-pf/main.ts
index f459d1d..6f4eada 100644
--- a/src/installer-pf/main.ts
+++ b/src/installer-pf/main.ts
@@ -55,7 +55,7 @@ function detectLocalIpv4(): string {
   return priv || candidates[0] || ''
 }
 
-/** CGNAT(이중 NAT) 대역 100.64.0.0/10 인지. 이 경우 공유기 포워딩만으론 외부 접속 불가. */
+/** CGNAT(이중 NAT) 대역 100.64.0.0/10 인지. */
 function isCgnat(ip: string): boolean {
   const m = ip.match(/^100\.(\d+)\./)
   if (!m) return false
@@ -63,6 +63,29 @@ function isCgnat(ip: string): boolean {
   return octet >= 64 && octet <= 127
 }
 
+/** 사설(RFC1918) IPv4 인지. 라우터 WAN 이 사설이면 앞단에 NAT 이 또 있다는 뜻(이중 NAT). */
+function isPrivateIpv4(ip: string): boolean {
+  return /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(ip)
+}
+
+/**
+ * CGNAT/이중 NAT 여부 판별. HTTP 로 본 공인 egress IP 하나만으로는 배제할 수 없다
+ * (전형적 CGNAT 은 egress 는 ISP 공인 IP, 라우터 WAN 만 100.64/10 이라 egress 검사로는 놓침).
+ * 그래서 라우터 WAN(IGD 외부) IP 를 함께 보고 비교한다.
+ *   - 'yes'     : 공인 IP 가 CGNAT 대역이거나, 라우터 WAN 이 사설/CGNAT 이거나 공인 IP 와 다름.
+ *   - 'no'      : 라우터 WAN 이 HTTP 공인 IP 와 동일 → 단일 NAT 확정.
+ *   - 'unknown' : 라우터 WAN 을 못 읽음(UPnP 미응답/거부) → 외부 IP 만으로는 확정/배제 불가.
+ */
+function classifyCgnat(publicIp: string, wanIp: string): 'yes' | 'no' | 'unknown' {
+  if (publicIp && isCgnat(publicIp)) return 'yes'
+  if (wanIp) {
+    if (isCgnat(wanIp) || isPrivateIpv4(wanIp)) return 'yes'
+    if (publicIp && wanIp !== publicIp) return 'yes'
+    if (publicIp && wanIp === publicIp) return 'no'
+  }
+  return 'unknown'
+}
+
 function fetchBuffer(url: string): Promise<Buffer> {
   return new Promise((resolve, reject) => {
     const target = new URL(url)
@@ -117,7 +140,7 @@ function detectExternalIpUpnp(): Promise<string> {
     const timer = setTimeout(() => {
       try { client && client.close() } catch {}
       finish('')
-    }, 8000)
+    }, 6000)
     client.externalIp((err: Error | null, ip?: string) => {
       clearTimeout(timer)
       try { client && client.close() } catch {}
@@ -305,7 +328,8 @@ async function probePortFromOutside(
 interface PortForwardOutcome {
   externalIp: string
   localIp: string
-  cgnat: boolean
+  wanIp: string
+  cgnat: 'yes' | 'no' | 'unknown'
   port: number
   reachable: boolean | null
   preForwarded: boolean
@@ -327,16 +351,17 @@ ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForward
 
   let externalIp = await detectExternalIpHttp()
   if (externalIp) sendLog(t('log.externalIpHttp', { ip: externalIp }))
-  else {
-    sendLog(t('log.externalIpHttpFail'))
-    externalIp = await detectExternalIpUpnp()
-    if (externalIp) sendLog(t('log.externalIpUpnp', { ip: externalIp }))
-    else sendLog(t('log.externalIpFail'))
-  }
-  const cgnat = isCgnat(externalIp)
-  if (cgnat) sendLog(t('log.cgnatDetected', { ip: externalIp }))
+  else sendLog(t('log.externalIpHttpFail'))
+  // 라우터 WAN(IGD 외부) IP 를 UPnP 로 조회해 HTTP 공인 IP 와 비교 → CGNAT/이중 NAT 판별.
+  const wanIp = await detectExternalIpUpnp()
+  if (wanIp) sendLog(t('log.routerWan', { ip: wanIp }))
+  else sendLog(t('log.routerWanUnknown'))
+  if (!externalIp && wanIp) externalIp = wanIp
+  const cgnat = classifyCgnat(externalIp, wanIp)
+  if (cgnat === 'yes') sendLog(t('log.cgnatDetected', { public: externalIp || '?', wan: wanIp || '?' }))
+  else if (cgnat === 'unknown') sendLog(t('log.cgnatUnknown'))
   const wrap = (reachable: boolean | null, preForwarded: boolean, detail: string): PortForwardOutcome =>
-    ({ externalIp, localIp, cgnat, port, reachable, preForwarded, detail })
+    ({ externalIp, localIp, wanIp, cgnat, port, reachable, preForwarded, detail })
 
   // 1차 점검: 이미 외부에서 닿는지.
   sendLog(t('log.probeStart'))
diff --git a/src/installer-pf/preload.ts b/src/installer-pf/preload.ts
index 3d015e1..aabad0c 100644
--- a/src/installer-pf/preload.ts
+++ b/src/installer-pf/preload.ts
@@ -2,6 +2,9 @@ import { contextBridge, ipcRenderer } from 'electron'
 
 interface PortForwardOutcome {
   externalIp: string
+  localIp: string
+  wanIp: string
+  cgnat: 'yes' | 'no' | 'unknown'
   port: number
   reachable: boolean | null
   preForwarded: boolean