installer-pf: guide manual forwarding + detect CGNAT on failure

포트포워딩 도구가 실패/확인불가일 때 다음 조치를 바로 안내하도록 보강.
- 이 PC LAN IPv4 자동 감지 → "외부 TCP {port} → {localIp}:{port} 수동 포워딩 +
  Windows 방화벽 인바운드 허용" 안내.
- 외부 IP 가 CGNAT(100.64/10) 대역이면 경고(공유기 포워딩만으론 불가).
- UPnP 가 ECONNREFUSED/타임아웃이면 "라우터 UPnP 거부/미지원" 로그 힌트.
실제 사용자 로그(라우터 UPnP ECONNREFUSED, 공인 IP, ifconfig false)에 기반한
개선. v0.3.16.

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>

src/installer-pf/main.ts

@@ -2,6 +2,7 @@ import { app, BrowserWindow, ipcMain } from 'electron'
 import http from 'node:http'
 import https from 'node:https'
 import net from 'node:net'
+import os from 'node:os'
 import path from 'node:path'
 import { URL } from 'node:url'
 import natUpnp from 'nat-upnp'
@@ -39,6 +40,29 @@ function sendLog(line: string): void {
 
 const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
 
+/** 이 PC 의 LAN IPv4(사설 대역 우선). 수동 포워딩 대상 IP 안내에 쓴다. */
+function detectLocalIpv4(): string {
+  const ifaces = os.networkInterfaces()
+  const candidates: string[] = []
+  for (const name of Object.keys(ifaces)) {
+    for (const info of ifaces[name] || []) {
+      if (info.family === 'IPv4' && !info.internal && !info.address.startsWith('169.254.')) {
+        candidates.push(info.address)
+      }
+    }
+  }
+  const priv = candidates.find((a) => /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(a))
+  return priv || candidates[0] || ''
+}
+
+/** CGNAT(이중 NAT) 대역 100.64.0.0/10 인지. 이 경우 공유기 포워딩만으론 외부 접속 불가. */
+function isCgnat(ip: string): boolean {
+  const m = ip.match(/^100\.(\d+)\./)
+  if (!m) return false
+  const octet = Number(m[1])
+  return octet >= 64 && octet <= 127
+}
+
 function fetchBuffer(url: string): Promise<Buffer> {
   return new Promise((resolve, reject) => {
     const target = new URL(url)
@@ -280,6 +304,8 @@ async function probePortFromOutside(
 
 interface PortForwardOutcome {
   externalIp: string
+  localIp: string
+  cgnat: boolean
   port: number
   reachable: boolean | null
   preForwarded: boolean
@@ -292,6 +318,9 @@ ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForward
   const port = Number.isFinite(portInput) && portInput > 0 && portInput < 65536 ? Math.floor(portInput) : 25565
   sendLog(t('log.start', { port }))
 
+  const localIp = detectLocalIpv4()
+  if (localIp) sendLog(t('log.localIp', { ip: localIp }))
+
   // 이전에 남은 매핑을 먼저 제거해 "사용자 라우터 규칙으로 이미 열린 상태" 와 구별.
   sendLog(t('log.cleanup'))
   await removeUpnpMapping(port)
@@ -304,6 +333,10 @@ ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForward
     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 }))
+  const wrap = (reachable: boolean | null, preForwarded: boolean, detail: string): PortForwardOutcome =>
+    ({ externalIp, localIp, cgnat, port, reachable, preForwarded, detail })
 
   // 1차 점검: 이미 외부에서 닿는지.
   sendLog(t('log.probeStart'))
@@ -312,7 +345,7 @@ ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForward
   sendLog(t('log.probeResult', { verdict: verdictText(probe.reachable), detail: probe.detail }))
   if (probe.reachable === true) {
     sendLog(t('log.preForwarded'))
-    return { externalIp, port, reachable: true, preForwarded: true, detail: probe.detail }
+    return wrap(true, true, probe.detail)
   }
 
   // UPnP 개방 시도.
@@ -321,8 +354,11 @@ ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForward
     await openPortViaUpnp(port)
     sendLog(t('log.upnpReqOk'))
   } catch (error) {
-    sendLog(t('log.upnpTryFail', { message: (error as Error).message }))
-    return { externalIp, port, reachable: probe.reachable, preForwarded: false, detail: probe.detail }
+    const msg = (error as Error).message
+    sendLog(t('log.upnpTryFail', { message: msg }))
+    // ECONNREFUSED/타임아웃 = 라우터가 UPnP 제어를 거부/미지원. 수동 포워딩 안내로 유도.
+    if (/ECONNREFUSED|ETIMEDOUT|timed out|시간 초과/i.test(msg)) sendLog(t('log.upnpUnavailable'))
+    return wrap(probe.reachable, false, probe.detail)
   }
 
   // NAT 반영 지연 고려 재점검.
@@ -333,11 +369,11 @@ ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForward
     if (!externalIp && probe.detectedIp) externalIp = probe.detectedIp
     if (probe.reachable === true) {
       sendLog(t('log.upnpDone', { port }))
-      return { externalIp, port, reachable: true, preForwarded: false, detail: probe.detail }
+      return wrap(true, false, probe.detail)
     }
   }
   sendLog(t('log.upnpUnconfirmed'))
-  return { externalIp, port, reachable: probe.reachable, preForwarded: false, detail: probe.detail }
+  return wrap(probe.reachable, false, probe.detail)
 })
 
 ipcMain.handle('pf:close', async (_event, portInput: number): Promise<void> => {