optimize: crash guard, yt-dlp url validation, dead-key cleanup

전체 코드 재검토 기반의 안전한 개선 1차 배치.
- 메인 설치기에 전역 uncaughtException/unhandledRejection 가드 추가. nat-upnp
  (detectExternalIpUpnp)의 비동기 소켓 오류로 앱이 조용히 종료되던 잠재 크래시
  방지(포트포워딩 도구 v0.3.18 과 동일 대비).
- 서버: fetchVideoMeta/fetchPlaylistEntries 에 http(s) URL 검증 추가(운영자 입력이
  yt-dlp 플래그로 오인되는 인자 주입 차단). /file/mods/:folder/index.json 의 async
  throw → next(error) 로 위임(unhandledRejection 방지). index 라우트 pack 정의
  병렬 로드.
- 죽은 i18n 키 정리: installer 로케일의 UPnP/run.bat 관련 19개 + pf 로케일 2개
  제거(코드에서 미참조 확인). 크래시 가드용 log.internalError, youtube.invalidUrl 추가.
v0.3.23.

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

electron-builder-dev.yml

@@ -0,0 +1,35 @@
+appId: kr.tkrmagid.musicquiz.installer.dev
+productName: MusicQuizInstaller
+# 개발자용 빌드: manifest 의 public===false 인 pack 만 노출한다.
+# musicQuizAudience 를 package.json 에 박아 런타임에서 대상(audience)을 판별.
+extraMetadata:
+  main: dist/installer/main.js
+  musicQuizAudience: developer
+directories:
+  output: release
+  buildResources: build
+files:
+  - dist/installer/**
+  - dist/shared/**
+  - installer/**
+  - build/icon.*
+  - package.json
+  - "!node_modules/@img/sharp-linux-*"
+  - "!node_modules/@img/sharp-linuxmusl-*"
+  - "!node_modules/@img/sharp-libvips-linux-*"
+  - "!node_modules/@img/sharp-libvips-linuxmusl-*"
+extraResources:
+  - from: .
+    to: .
+    filter:
+      - .env.build
+  - from: locales
+    to: locales
+    filter:
+      - "**/*"
+win:
+  target: portable
+  artifactName: MusicQuizInstaller-Dev-${version}-Portable.${ext}
+  icon: build/icon.ico
+portable:
+  artifactName: MusicQuizInstaller-Dev-${version}-Portable.${ext}

electron-builder-rp-dev.yml

@@ -0,0 +1,35 @@
+appId: kr.tkrmagid.musicquiz.installer-rp.dev
+productName: MusicQuizResourcepackInstaller
+# 개발자용 리소스팩 설치기: manifest 의 public===false 인 pack 만 노출.
+extraMetadata:
+  main: dist/installer-rp/main.js
+  musicQuizAudience: developer
+directories:
+  output: release
+  buildResources: build
+files:
+  - dist/installer-rp/**
+  - dist/shared/**
+  - installer-rp/**
+  - installer/styles.css
+  - build/icon.*
+  - package.json
+  - "!node_modules/@img/sharp-linux-*"
+  - "!node_modules/@img/sharp-linuxmusl-*"
+  - "!node_modules/@img/sharp-libvips-linux-*"
+  - "!node_modules/@img/sharp-libvips-linuxmusl-*"
+extraResources:
+  - from: .
+    to: .
+    filter:
+      - .env.build
+  - from: locales
+    to: locales
+    filter:
+      - "**/*"
+win:
+  target: portable
+  artifactName: MusicQuizResourcepackInstaller-Dev-${version}-Portable.${ext}
+  icon: build/icon.ico
+portable:
+  artifactName: MusicQuizResourcepackInstaller-Dev-${version}-Portable.${ext}

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 })

installer/renderer.js

@@ -148,7 +148,7 @@ function renderStep1() {
     if (!state.selectedPackKey) return
     await installerApi.setSelectedPack(state.selectedPackKey)
     state.stepDone[1] = true
-    renderAgreement()
+    renderCloseNotice()
   })
 
   ;(async function () {
@@ -162,6 +162,24 @@ function renderStep1() {
   })()
 }
 
+// 퀴즈팩 선택 직후 노출하는 "마인크래프트/런처 종료" 강조 안내. 크게 표시.
+function renderCloseNotice() {
+  setActiveStep(1)
+  clearPage()
+  var section = document.createElement('section')
+  section.className = 'page'
+  section.innerHTML =
+    '<div style="margin:24px 0;padding:30px 24px;border:2px solid var(--danger);border-radius:14px;background:rgba(248,81,73,0.12);text-align:center;">' +
+    '  <div style="font-size:15px;font-weight:800;color:var(--danger);letter-spacing:2px;">' + escapeHtml(tt('closeNotice.badge')) + '</div>' +
+    '  <div style="font-size:30px;font-weight:900;line-height:1.45;margin-top:16px;">' + escapeHtml(tt('closeNotice.message')) + '</div>' +
+    '  <div style="font-size:14px;color:var(--text-muted);margin-top:18px;">' + escapeHtml(tt('closeNotice.sub')) + '</div>' +
+    '</div>' +
+    '<div class="actionRow"><button class="secondaryBtn" id="back">' + tt('common.back') + '</button><button class="primaryBtn" id="next">' + tt('common.next') + '</button></div>'
+  pageHost.appendChild(section)
+  section.querySelector('#back').addEventListener('click', renderStep1)
+  section.querySelector('#next').addEventListener('click', renderAgreement)
+}
+
 // 약관 동의 페이지: 음악퀴즈 선택 직후, 싱글/멀티 선택(step2) 진입 전에 노출.
 // v0.3.4~ : 어떤 약관을 표시할지는 사이트(/manifest/terms/<pack>/index.json) 가
 // 결정. 메인 인스톨러용으로 표시 토글된 항목만 받아 탭을 만든다. 목록이 비어 있는 (terms:[])
@@ -820,16 +838,20 @@ function renderSubStep35(host, back, done) {
       var result = await installerApi.checkPortForward(port)
       state.serverInstall.portStatus = result
       var address = formatServerAddress(result.externalIp, result.port)
-      if (result.status === 'preForwarded') {
+      if (result.status === 'open') {
-        resultMsg.innerHTML = tt('step3.sub35.preForwarded', { address: address })
+        // 열려 있으면 외부 접속 주소를 크게 표시.
-        resultMsg.classList.add('success')
+        resultMsg.innerHTML =
-      } else if (result.status === 'upnpOk') {
+          '<div style="margin-top:12px;padding:18px;border:1px solid var(--success);border-radius:10px;background:rgba(63,185,80,0.12);text-align:center;">' +
-        resultMsg.innerHTML = tt('step3.sub35.upnpOk', { address: address })
+          '<div style="font-size:14px;color:var(--text-muted);">' + escapeHtml(tt('step3.sub35.openTitle')) + '</div>' +
-        resultMsg.classList.add('success')
+          '<div style="font-size:30px;font-weight:800;margin-top:8px;user-select:all;word-break:break-all;">' + escapeHtml(address) + '</div>' +
+          '</div>'
       } else {
-        resultMsg.innerHTML = (result.message || tt('step3.sub35.manualHint')) +
+        // 안 열려 있으면 "직접 포트포워딩 해주세요" 를 크게 표시.
-          tt('step3.sub35.manualDetail', { address: address })
+        resultMsg.innerHTML =
-        resultMsg.classList.add('warn')
+          '<div style="margin-top:12px;padding:18px;border:1px solid var(--danger);border-radius:10px;background:rgba(248,81,73,0.10);text-align:center;">' +
+          '<div style="font-size:26px;font-weight:800;">' + escapeHtml(tt('step3.sub35.notOpenBig')) + '</div>' +
+          '<div style="font-size:13px;color:var(--text-muted);margin-top:10px;">' + escapeHtml(tt('step3.sub35.notOpenHint', { address: address, port: result.port })) + '</div>' +
+          '</div>'
       }
       nextBtn.disabled = false
     } catch (err) {

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,13 +36,14 @@
   "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}}",
     "externalIpHttpFail": "외부 IP HTTP 조회 실패 → UPnP 게이트웨이로 폴백",
-    "externalIpUpnp": "외부 IP(UPnP): {{ip}}",
-    "externalIpFail": "외부 IP 확인 실패",
     "probeStart": "외부 포트 점검 시작…",
     "probeResult": "점검 결과: {{verdict}} ({{detail}})",
     "preForwarded": "이미 외부에서 접속 가능한 상태입니다.",
@@ -54,6 +56,7 @@
     "closeTry": "UPnP 매핑 제거 시도: TCP {{port}}",
     "upnpRemoveAttempt": "UPnP 매핑 제거 시도: {{message}}",
     "upnpRemoveDone": "UPnP 매핑 제거 완료: TCP {{port}}",
+    "internalError": "내부 오류(무시하고 계속): {{message}}",
     "upnpClientFail": "UPnP 클라이언트 생성 실패: {{message}}",
     "portInUse": "포트 {{port}}이(가) 이미 사용 중 → 임시 리스너 없이 외부 서비스 응답만으로 판정.",
     "listenerBindFail": "임시 리스너 바인딩 실패: {{message}}",

locales/installer/ko-kr.json

@@ -3,6 +3,11 @@
     "heading": "시작하기 전에",
     "message": "마인크래프트 런처를 끄고 시작해주세요."
   },
+  "closeNotice": {
+    "badge": "⚠ 매우 중요",
+    "message": "마인크래프트와 마인크래프트 런처를 종료한 뒤 진행해주세요",
+    "sub": "실행 중이면 설치 설정이 제대로 적용되지 않을 수 있습니다."
+  },
   "common": {
     "back": "이전",
     "next": "다음",
@@ -124,14 +129,13 @@
     },
     "sub35": {
       "heading": "포트포워딩",
-      "description": "UPNP를 개방해 외부 접속을 허용합니다.",
+      "description": "포트가 외부에서 열려 있는지 확인합니다. (설치기가 직접 열지는 않습니다)",
       "portLabel": "포트",
       "recheck": "재점검",
       "checking": "확인 중...",
-      "preForwarded": "포트포워딩 성공! 친구는 <strong>{{address}}</strong> 주소로 서버에 접속할 수 있습니다. (이미 외부 개방되어 있음)",
+      "openTitle": "포트가 열려 있습니다! 친구 접속 주소",
-      "upnpOk": "포트포워딩 성공! 친구는 <strong>{{address}}</strong> 주소로 서버에 접속할 수 있습니다. (UPnP로 자동 개방 완료)",
+      "notOpenBig": "직접 포트포워딩 해주세요.",
-      "manualHint": "직접 포트포워딩을 해주세요.",
+      "notOpenHint": "공유기에서 외부 TCP {{port}} 를 이 PC 로 포워딩하세요. (외부 주소: {{address}})",
-      "manualDetail": "<br><small>외부 주소: {{address}}</small>",
       "checkFailed": "점검 실패: {{message}}",
       "ipUnknown": "확인 불가"
     }
@@ -187,7 +191,6 @@
     "fabricLoaderRequired": "Fabric 로더 버전이 음악퀴즈에 지정되지 않았습니다. 관리 사이트에서 platform.loaderVersion 을 설정해 주세요.",
     "fabricInstallerListEmpty": "Fabric installer 목록을 받지 못했습니다.",
     "portAllocFail": "포트를 할당할 수 없습니다.",
-    "upnpTimeout": "UPnP 응답 없음(타임아웃 15s). 라우터의 UPnP가 꺼져 있거나 SSDP 패킷이 차단됐을 수 있습니다.",
     "parseResponseFailed": "응답 파싱 실패: {{snippet}}"
   },
   "log": {
@@ -218,15 +221,10 @@
     "skipResourcepack": "resourcepackPath가 비어 있어 리소스팩 다운로드를 건너뜁니다.",
     "resourcepackDownload": "리소스팩 다운로드: {{url}}",
     "serverInstallPath": "서버 설치 경로: {{path}}",
-    "runBatMissing": "run.bat 이 없어 UPnP 자동 등록 스크립트 주입을 건너뜁니다.",
-    "runBatAlreadyInjected": "run.bat 에 이미 UPnP 자동 등록 스크립트가 들어 있어 건너뜁니다.",
-    "runBatNoJava": "run.bat 에서 java 호출 라인을 찾지 못해 UPnP 자동 등록 주입을 건너뜁니다.",
-    "runBatInjected": "run.bat 에 서버 기동/종료 시 UPnP 자동 등록·해제 스크립트를 추가했습니다.",
     "mojangEulaFetchFail": "Minecraft EULA 페이지 조회 실패: {{message}}",
     "eulaAccepted": "EULA 동의 저장 완료.",
     "configEditorOpen": "서버 설정 편집기 실행: {{url}}",
     "portCheckStart": "포트포워딩 점검 시작: 포트 {{port}}",
-    "upnpCleanup": "이전 실행의 UPnP 매핑이 남아 있으면 제거합니다(중복 방지)...",
     "externalIpHttp": "외부 IP 확인(HTTP): {{ip}}",
     "externalIpHttpFail": "외부 IP 확인 실패(HTTP). UPnP 게이트웨이를 통한 조회 시도...",
     "externalIpUpnp": "외부 IP 확인(UPnP): {{ip}}",
@@ -238,15 +236,6 @@
     "probeVerdictUnknown": "확인 불가",
     "probePreForwarded": "외부에서 {{addr}}:{{port}} 접근 확인됨. 사용자 규칙으로 포워딩 됨.",
     "ipUnknown": "(IP 미상)",
-    "upnpTryOpen": "UPnP로 포트 {{port}} 자동 개방 시도(TCP)...",
-    "upnpReqOk": "UPnP portMapping 요청 성공. 외부 접근을 재확인합니다.",
-    "upnpTryFail": "UPnP 시도 실패: {{message}}",
-    "upnpFailDetail": "UPnP 실패: {{message}}. 라우터에서 UPnP가 꺼져 있을 수 있습니다. 직접 포트포워딩을 해주세요.",
-    "upnpRecheck": "UPnP 적용 후 재점검 {{attempt}}/3...",
-    "upnpDone": "UPnP로 포트 {{port}} 자동 개방 완료. 테스트 매핑을 제거합니다(실제 개방은 run.bat 이 서버 기동 시 자동으로 처리).",
-    "upnpCleanupTest": "테스트용 UPnP 매핑을 정리합니다.",
-    "upnpFailReason1": "UPnP 매핑은 등록됐지만 외부 포트체크 서비스에서 연결이 닿지 않았습니다. ISP 차단, 이중 NAT, 또는 방화벽 설정을 확인하세요.",
-    "upnpFailReason2": "외부 포트체크 결과를 받지 못했습니다({{detail}}). UPnP 매핑은 등록됐을 수 있습니다.",
     "upnpClientFail": "UPnP 클라이언트 생성 실패: {{message}}",
     "upnpExternalTimeout": "UPnP externalIp 조회 타임아웃(8s).",
     "upnpExternalErr": "UPnP externalIp 오류: {{message}}",
@@ -257,10 +246,6 @@
     "detailIfconfig": "ifconfig.co reachable={{reachable}} ip={{ip}}",
     "detailIfconfigFail": "ifconfig.co 실패={{error}}",
     "detailNone": "결과 없음",
-    "upnpClientFailRemove": "UPnP 클라이언트 생성 실패(매핑 제거 단계): {{message}}",
-    "upnpRemoveTimeout": "UPnP 매핑 제거 응답 없음(타임아웃 8s). 라우터에 우리가 만든 규칙이 없을 수 있습니다.",
-    "upnpRemoveAttempt": "UPnP 매핑 제거 시도 결과: {{message}} (없으면 정상)",
-    "upnpRemoveDone": "UPnP 매핑 제거 완료(포트 {{port}}).",
     "platformDownload": "플랫폼({{type}}) 다운로드: {{url}}",
     "platformSaved": "플랫폼 설치파일 저장: {{path}} (사용자가 직접 실행하거나 마인크래프트 런처에서 인식할 수 있습니다.)",
     "platformSkipped": "플랫폼 설치 건너뜀. 바닐라로 진행합니다.",
@@ -297,7 +282,8 @@
     "launcherAppsFolderFail": "AppsFolder 실행 실패: {{message}}",
     "launcherUrlSchemeFallback": "마지막 시도: minecraft:// URL 스킴 (런처가 없으면 MS Store 가 열릴 수 있음).",
     "launcherUrlSchemeFail": "URL 스킴 실행 실패: {{message}}.",
-    "launcherAllFail": "Minecraft Launcher 실행 시도가 모두 실패했습니다. minecraft.net 또는 Microsoft Store 에서 \"Minecraft Launcher\" 를 설치한 뒤 다시 시도해 주세요."
+    "launcherAllFail": "Minecraft Launcher 실행 시도가 모두 실패했습니다. minecraft.net 또는 Microsoft Store 에서 \"Minecraft Launcher\" 를 설치한 뒤 다시 시도해 주세요.",
+    "internalError": "내부 오류(무시하고 계속): {{message}}"
   },
   "candidates": {
     "winProgramFiles86": "Win32 설치(Program Files (x86))",

locales/server/ko-kr.json

@@ -229,6 +229,7 @@
     "ytdlpInstallFailed": "yt-dlp 자동 설치에 실패했습니다: {{message}}",
     "ytdlpVideoFailed": "yt-dlp 영상 조회 실패 (code={{code}}): {{detail}}",
     "ytdlpPlaylistFailed": "yt-dlp 플레이리스트 조회 실패 (code={{code}}): {{detail}}",
-    "tooManyRedirects": "redirect 가 너무 많습니다."
+    "tooManyRedirects": "redirect 가 너무 많습니다.",
+    "invalidUrl": "올바르지 않은 URL 입니다. http/https 주소만 허용됩니다."
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-music-quiz-installer",
-  "version": "0.3.16",
+  "version": "0.3.23",
   "description": "마인크래프트 음악퀴즈 간편설치기 + 관리 사이트",
   "main": "dist/installer/main.js",
   "scripts": {
@@ -14,7 +14,9 @@
     "build:launcher-icon": "node scripts/build-launcher-icon.cjs",
     "dist:win": "npm run preinstall:sharp-win32 && npm run build:launcher-icon && tsc -p tsconfig.installer.json && electron-builder --win --config electron-builder.yml",
     "dist:win:rp": "npm run preinstall:sharp-win32 && tsc -p tsconfig.installer-rp.json && electron-builder --win --config electron-builder-rp.yml",
-    "dist:win:pf": "tsc -p tsconfig.installer-pf.json && electron-builder --win --config electron-builder-pf.yml"
+    "dist:win:pf": "tsc -p tsconfig.installer-pf.json && electron-builder --win --config electron-builder-pf.yml",
+    "dist:win:dev": "npm run preinstall:sharp-win32 && npm run build:launcher-icon && tsc -p tsconfig.installer.json && electron-builder --win --config electron-builder-dev.yml",
+    "dist:win:rp:dev": "npm run preinstall:sharp-win32 && tsc -p tsconfig.installer-rp.json && electron-builder --win --config electron-builder-rp-dev.yml"
   },
   "dependencies": {
     "@types/archiver": "^7.0.0",

src/installer-pf/main.ts

@@ -38,6 +38,16 @@ function sendLog(line: string): void {
   mainWindow.webContents.send('log', stamped)
 }
 
+// nat-upnp 는 라우터가 UPnP 를 거부/미지원할 때 콜백 밖에서 비동기 소켓 오류를
+// 낼 수 있다. 처리되지 않으면 Electron 메인 프로세스가 그대로 종료되어 창이 갑자기
+// 닫힌다("오류나면서 끝남"). 전역 가드로 잡아 로그만 남기고 앱은 계속 살려 둔다.
+process.on('uncaughtException', (err) => {
+  try { sendLog(t('log.internalError', { message: (err as Error)?.message || String(err) })) } catch {}
+})
+process.on('unhandledRejection', (reason) => {
+  try { sendLog(t('log.internalError', { message: reason instanceof Error ? reason.message : String(reason) })) } catch {}
+})
+
 const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
 
 /** 이 PC 의 LAN IPv4(사설 대역 우선). 수동 포워딩 대상 IP 안내에 쓴다. */
@@ -55,7 +65,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 +73,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 +150,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 +338,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 +361,17 @@ ipcMain.handle('pf:open', async (_event, portInput: number): Promise<PortForward
 
   let externalIp = await detectExternalIpHttp()
   if (externalIp) sendLog(t('log.externalIpHttp', { ip: externalIp }))
-  else {
+  else sendLog(t('log.externalIpHttpFail'))
-    sendLog(t('log.externalIpHttpFail'))
+  // 라우터 WAN(IGD 외부) IP 를 UPnP 로 조회해 HTTP 공인 IP 와 비교 → CGNAT/이중 NAT 판별.
-    externalIp = await detectExternalIpUpnp()
+  const wanIp = await detectExternalIpUpnp()
-    if (externalIp) sendLog(t('log.externalIpUpnp', { ip: externalIp }))
+  if (wanIp) sendLog(t('log.routerWan', { ip: wanIp }))
-    else sendLog(t('log.externalIpFail'))
+  else sendLog(t('log.routerWanUnknown'))
-  }
+  if (!externalIp && wanIp) externalIp = wanIp
-  const cgnat = isCgnat(externalIp)
+  const cgnat = classifyCgnat(externalIp, wanIp)
-  if (cgnat) sendLog(t('log.cgnatDetected', { ip: externalIp }))
+  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'))

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

src/installer-rp/main.ts

@@ -12,6 +12,7 @@ import { normalizePackDefinition } from '../shared/store.js'
 import { getAppDataDir, getMcCustomDir } from '../shared/paths.js'
 import { loadEnv, getManifestUrl } from '../shared/env.js'
 import { loadComponentI18n } from '../shared/i18n.js'
+import { resolveAudience, isPackVisibleForAudience, type Audience } from '../shared/audience.js'
 import type { RpFetchedPack } from './types.js'
 import { ensureYtDlpExe } from './ytdlp.js'
 import { ensureFfmpegExe } from './ffmpeg.js'
@@ -112,6 +113,16 @@ const state: RpInstallerState = {
 
 let mainWindow: BrowserWindow | null = null
 
+// 이 빌드의 대상(일반/개발자용). package.json 의 musicQuizAudience 로 결정.
+function getAudience(): Audience {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(app.getAppPath(), 'package.json'), 'utf8'))
+    return resolveAudience(pkg.musicQuizAudience)
+  } catch {
+    return resolveAudience(undefined)
+  }
+}
+
 function deriveBaseUrl(manifestUrl: string): string {
   try {
     const parsed = new URL(manifestUrl)
@@ -202,9 +213,12 @@ ipcMain.handle('rp:packs:load', async (_event, manifestUrlInput?: string): Promi
   }
   sendLog(t('log.manifestDownload', { url: state.manifestUrl }))
   const manifest = await fetchJson<Manifest>(state.manifestUrl)
+  const audience = getAudience()
   const results: RpFetchedPack[] = []
   for (const entry of manifest.packs ?? []) {
     if (typeof entry?.file !== 'string') continue
+    // 대상(audience)에 맞지 않는 pack 은 건너뛴다(일반=public, 개발자용=non-public).
+    if (!isPackVisibleForAudience(entry.public, audience)) continue
     const listUrl = `${state.baseUrl}/file/list/${encodeURIComponent(entry.file)}.json`
     const packUrl = `${state.baseUrl}/manifest/${encodeURIComponent(entry.file)}.json`
     try {

src/installer/main.ts

@@ -22,10 +22,21 @@ import type { Manifest, PackDefinition } from '../shared/types.js'
 import { normalizePackDefinition } from '../shared/store.js'
 import { loadEnv, getManifestUrl } from '../shared/env.js'
 import { loadComponentI18n } from '../shared/i18n.js'
+import { resolveAudience, isPackVisibleForAudience, type Audience } from '../shared/audience.js'
 import { LAUNCHER_PROFILE_ICON } from './launcherIcon.js'
 
 loadEnv()
 
+// 이 빌드의 대상(일반/개발자용). package.json 의 musicQuizAudience 로 결정.
+function getAudience(): Audience {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(app.getAppPath(), 'package.json'), 'utf8'))
+    return resolveAudience(pkg.musicQuizAudience)
+  } catch {
+    return resolveAudience(undefined)
+  }
+}
+
 const i18n = loadComponentI18n('installer')
 const t = i18n.t
 export const localeDict = i18n.dict
@@ -87,6 +98,16 @@ function sendLog(line: string): void {
   mainWindow.webContents.send('log', stamped)
 }
 
+// nat-upnp(detectExternalIpUpnp) 등이 콜백 밖에서 비동기 소켓 오류를 내면 처리되지
+// 않아 Electron 메인이 종료되며 창이 갑자기 닫힐 수 있다. 전역 가드로 잡아 로그만
+// 남기고 앱은 계속 살려 둔다(포트포워딩 전용 도구 v0.3.18 과 동일한 대비책).
+process.on('uncaughtException', (err) => {
+  try { sendLog(t('log.internalError', { message: (err as Error)?.message || String(err) })) } catch {}
+})
+process.on('unhandledRejection', (reason) => {
+  try { sendLog(t('log.internalError', { message: reason instanceof Error ? reason.message : String(reason) })) } catch {}
+})
+
 function fetchBuffer(url: string): Promise<Buffer> {
   return new Promise((resolve, reject) => {
     const target = new URL(url)
@@ -136,9 +157,12 @@ ipcMain.handle('packs:load', async (_event, manifestUrlInput?: string): Promise<
   }
   sendLog(t('log.manifestDownload', { url: state.manifestUrl }))
   const manifest = await fetchJson<Manifest>(state.manifestUrl)
+  const audience = getAudience()
   const results: FetchedPack[] = []
   for (const entry of manifest.packs ?? []) {
     if (typeof entry?.file !== 'string') continue
+    // 대상(audience)에 맞지 않는 pack 은 건너뛴다(일반=public, 개발자용=non-public).
+    if (!isPackVisibleForAudience(entry.public, audience)) continue
     const packUrl = `${state.baseUrl}/manifest.json`.replace(/manifest\.json$/, `manifest/${entry.file}.json`)
     try {
       const raw = await fetchJson<Partial<PackDefinition>>(packUrl)
@@ -603,83 +627,10 @@ ipcMain.handle('server:install', async (_event, payload: ServerInstallPayload) =
   await downloadServerZip(pack.pack, installPath)
   // 다운로드한 zip에 들어있을 수 있는 eula.txt를 그대로 보존한다.
   // 동의 흐름은 renderer가 별도 IPC로 읽고 동의 시 덮어쓴다.
-
+  // 설치기는 포트를 직접 열지 않는다(요청). run.bat 에 UPnP 자동 개방을 주입하지
-  // run.bat 에 서버 기동/종료시 UPnP 자동 등록/해제 로직 주입.
+  // 않으며, 사용자가 라우터에서 수동 포워딩을 하고 포트포워딩 페이지에서 확인만 한다.
-  // 이렇게 해야 서버가 안 떠 있는 동안에는 포트가 닫혀 있게 된다.
-  await injectUpnpToRunBat(installPath)
 })
 
-/**
- * 추출된 서버 zip 의 run.bat 에 UPnP 자동 등록(서버 시작 시) / 자동 해제(서버 종료 후)
- * 스크립트를 끼워 넣는다. 이미 우리가 주입했던 마커가 있으면 다시 건드리지 않는다.
- *
- * 동작:
- *   1) 서버 시작 직전: server.properties 의 server-port 값(없으면 25565) 으로 PowerShell
- *      을 통해 HNetCfg.NATUPnP.1 COM 객체를 이용해 정적 포트 매핑 추가.
- *   2) 서버 프로세스 종료 후(=pause 직전 또는 파일 끝): 동일한 포트의 매핑 제거.
- *
- * 제한: 사용자가 콘솔 창을 X 버튼으로 강제 종료하면 teardown 이 실행되지 않는다.
- *       이 경우 라우터의 UPnP TTL 에 의해 자동 만료되며, 다음 실행 시 Add 전에 Remove 를
- *       시도하므로 idempotent.
- */
-async function injectUpnpToRunBat(installPath: string): Promise<void> {
-  const runBat = path.join(installPath, 'run.bat')
-  if (!fs.existsSync(runBat)) {
-    sendLog(t('log.runBatMissing'))
-    return
-  }
-  const MARKER = 'REM === UPNP MANAGED BY MUSICQUIZ INSTALLER ==='
-  const original = await fsp.readFile(runBat, 'utf8')
-  if (original.includes(MARKER)) {
-    sendLog(t('log.runBatAlreadyInjected'))
-    return
-  }
-
-  const lines = original.split(/\r?\n/)
-  const javaIdx = lines.findIndex((line) => /^\s*java(\.exe)?[\s"]/i.test(line))
-  if (javaIdx === -1) {
-    sendLog(t('log.runBatNoJava'))
-    return
-  }
-  let pauseIdx = -1
-  for (let i = javaIdx + 1; i < lines.length; i++) {
-    if (/^\s*pause\b/i.test(lines[i])) { pauseIdx = i; break }
-  }
-  if (pauseIdx === -1) pauseIdx = lines.length
-
-
-  // PowerShell 한 줄로 처리: server.properties 의 server-port 우선, 없으면 25565.
-  // Add 전에 같은 포트의 매핑이 남아 있으면 먼저 Remove 하여 idempotent 하게 만든다.
-  const addBlock = [
-    MARKER,
-    'REM 서버 시작 직전: server-port 추출 후 UPnP 매핑 등록.',
-    'set "_MQ_PORT=25565"',
-    'for /f "tokens=2 delims==" %%a in (\'findstr /b /c:"server-port=" server.properties 2^>nul\') do set "_MQ_PORT=%%a"',
-    'set "_MQ_PORT=%_MQ_PORT: =%"',
-    'echo [MusicQuiz] UPnP 등록 시도: TCP %_MQ_PORT%',
-    'powershell -NoProfile -Command "$port=[int]$env:_MQ_PORT; $ip=(Get-NetIPAddress -AddressFamily IPv4 -PrefixOrigin Dhcp,Manual -ErrorAction SilentlyContinue | Where-Object {$_.IPAddress -notlike \'169.254.*\' -and $_.IPAddress -ne \'127.0.0.1\'} | Select-Object -First 1).IPAddress; if (-not $ip) { Write-Host \'[MusicQuiz] 로컬 IPv4 검색 실패\'; exit 1 }; try { $u = New-Object -ComObject HNetCfg.NATUPnP.1; $c=$u.StaticPortMappingCollection; if ($c) { try { $c.Remove($port,\'TCP\') | Out-Null } catch {}; $c.Add($port,\'TCP\',$port,$ip,$true,\'MusicQuiz Minecraft Server\') | Out-Null; Write-Host (\'[MusicQuiz] UPnP 등록 성공: \' + $ip + \':\' + $port + \' TCP\') } else { Write-Host \'[MusicQuiz] UPnP 컬렉션 사용 불가(라우터 UPnP 꺼짐?)\' } } catch { Write-Host (\'[MusicQuiz] UPnP 등록 실패: \' + $_.Exception.Message) }"'
-  ]
-
-  const removeBlock = [
-    'REM 서버 종료 후: UPnP 매핑 해제.',
-    'echo [MusicQuiz] UPnP 해제 시도: TCP %_MQ_PORT%',
-    'powershell -NoProfile -Command "$port=[int]$env:_MQ_PORT; try { $u = New-Object -ComObject HNetCfg.NATUPnP.1; $c=$u.StaticPortMappingCollection; if ($c) { $c.Remove($port,\'TCP\') | Out-Null; Write-Host (\'[MusicQuiz] UPnP 해제 완료: TCP \' + $port) } } catch { Write-Host (\'[MusicQuiz] UPnP 해제 실패: \' + $_.Exception.Message) }"'
-  ]
-
-  const merged: string[] = []
-  merged.push(...lines.slice(0, javaIdx))
-  merged.push(...addBlock)
-  merged.push(lines[javaIdx])
-  merged.push(...lines.slice(javaIdx + 1, pauseIdx))
-  merged.push(...removeBlock)
-  merged.push(...lines.slice(pauseIdx))
-
-  // bat 파일은 CRLF 가 안전.
-  const output = merged.join('\r\n')
-  await fsp.writeFile(runBat, output, 'utf8')
-  sendLog(t('log.runBatInjected'))
-}
-
 ipcMain.handle('server:readEula', async (_event, installPath: string): Promise<{ exists: boolean; content: string }> => {
   if (!installPath) return { exists: false, content: '' }
   const target = path.join(path.resolve(installPath), 'eula.txt')
@@ -860,12 +811,7 @@ ipcMain.handle('server:portForward', async (_event, port: number): Promise<PortF
   const targetPort = Number.isFinite(port) && port > 0 ? port : 25565
   sendLog(t('log.portCheckStart', { port: targetPort }))
 
-  // 1차 점검 전에 우리가 이전 실행에서 만든 UPnP 매핑이 남아 있으면 먼저 제거한다.
+  // 설치기는 포트를 직접 열지 않는다. 외부에서 이미 열려 있는지만 확인한다.
-  // 이렇게 해야 "사용자 라우터 규칙이 활성화돼서 외부 접근이 가능한 상태" 와 "UPnP 매핑 덕분에 접근 가능한 상태" 가 구별된다.
-  // 사용자 규칙이 비활성/없으면 1차 점검은 false 가 되어 UPnP 시도 단계로 자연스럽게 넘어간다.
-  sendLog(t('log.upnpCleanup'))
-  await removeUpnpMapping(targetPort)
-
   // 외부 IP 확보: 공용 API → 실패 시 UPnP 게이트웨이의 외부 IP로 폴백.
   let externalIp = await detectExternalIpHttp()
   if (externalIp) {
@@ -877,9 +823,9 @@ ipcMain.handle('server:portForward', async (_event, port: number): Promise<PortF
     else sendLog(t('log.externalIpUpnpFail'))
   }
 
-  // 1차 점검: 외부에서 이미 접근 가능한지 (서버가 떠 있거나, 우리가 임시 리스너 띄워서 검증).
+  // 외부에서 포트가 닿는지 점검(서버가 떠 있거나, 임시 리스너로 검증).
   sendLog(t('log.probeStart'))
-  let probe = await probePortFromOutside(targetPort, externalIp)
+  const probe = await probePortFromOutside(targetPort, externalIp)
   if (!externalIp && probe.detectedIp) externalIp = probe.detectedIp
   const verdict = probe.reachable === true
     ? t('log.probeVerdictSuccess')
@@ -888,47 +834,9 @@ ipcMain.handle('server:portForward', async (_event, port: number): Promise<PortF
 
   if (probe.reachable === true) {
     sendLog(t('log.probePreForwarded', { addr: externalIp || t('log.ipUnknown'), port: targetPort }))
-    return { status: 'preForwarded', externalIp, port: targetPort }
+    return { status: 'open', externalIp, port: targetPort }
   }
-
+  return { status: 'notOpen', externalIp, port: targetPort }
-  // UPnP 시도.
-  sendLog(t('log.upnpTryOpen', { port: targetPort }))
-  try {
-    await openPortViaUpnp(targetPort)
-    sendLog(t('log.upnpReqOk'))
-  } catch (error) {
-    const msg = (error as Error).message || String(error)
-    sendLog(t('log.upnpTryFail', { message: msg }))
-    return {
-      status: 'upnpFailed',
-      externalIp,
-      port: targetPort,
-      message: t('log.upnpFailDetail', { message: msg })
-    }
-  }
-
-  // NAT 반영 지연을 고려해 최대 3회 재점검.
-  for (let attempt = 1; attempt <= 3; attempt++) {
-    await sleep(1500)
-    sendLog(t('log.upnpRecheck', { attempt }))
-    probe = await probePortFromOutside(targetPort, externalIp)
-    if (!externalIp && probe.detectedIp) externalIp = probe.detectedIp
-    if (probe.reachable === true) {
-      sendLog(t('log.upnpDone', { port: targetPort }))
-      await removeUpnpMapping(targetPort)
-      return { status: 'upnpOk', externalIp, port: targetPort }
-    }
-  }
-
-  // 테스트 목적으로 만든 매핑 정리. 실제 개방은 run.bat 이 담당.
-  sendLog(t('log.upnpCleanupTest'))
-  await removeUpnpMapping(targetPort)
-
-  const reason = probe.reachable === false
-    ? t('log.upnpFailReason1')
-    : t('log.upnpFailReason2', { detail: probe.detail })
-  sendLog(reason)
-  return { status: 'upnpFailed', externalIp, port: targetPort, message: reason }
 })
 
 async function detectExternalIpHttp(): Promise<string> {
@@ -1124,64 +1032,6 @@ function fetchIfconfigCoPortOnce(port: number): Promise<IfconfigPortResult> {
   })
 }
 
-function removeUpnpMapping(port: number): Promise<void> {
-  return new Promise((resolve) => {
-    let settled = false
-    const done = () => { if (!settled) { settled = true; resolve() } }
-    let client: ReturnType<typeof natUpnp.createClient> | null = null
-    try {
-      client = natUpnp.createClient()
-    } catch (err) {
-      sendLog(t('log.upnpClientFailRemove', { message: (err as Error).message }))
-      done()
-      return
-    }
-    const timer = setTimeout(() => {
-      try { client && client.close() } catch {}
-      sendLog(t('log.upnpRemoveTimeout'))
-      done()
-    }, 8000)
-    client.portUnmapping({ public: port, protocol: 'tcp' }, (err: Error | null) => {
-      clearTimeout(timer)
-      try { client && client.close() } catch {}
-      if (err) sendLog(t('log.upnpRemoveAttempt', { message: err.message }))
-      else sendLog(t('log.upnpRemoveDone', { port }))
-      done()
-    })
-  })
-}
-
-function openPortViaUpnp(port: number): Promise<void> {
-  return new Promise((resolve, reject) => {
-    let settled = false
-    const done = (err?: Error) => {
-      if (settled) return
-      settled = true
-      if (err) reject(err)
-      else resolve()
-    }
-    let client: ReturnType<typeof natUpnp.createClient> | null = null
-    try {
-      client = natUpnp.createClient()
-    } catch (err) {
-      done(err as Error)
-      return
-    }
-    const timer = setTimeout(() => {
-      try { client && client.close() } catch {}
-      done(new Error(t('errors.upnpTimeout')))
-    }, 15000)
-    client.portMapping(
-      { public: port, private: port, ttl: 0, description: 'MusicQuiz Server', protocol: 'tcp' },
-      (error: Error | null) => {
-        clearTimeout(timer)
-        try { client && client.close() } catch {}
-        done(error || undefined)
-      }
-    )
-  })
-}
-
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }

src/installer/types.ts

@@ -36,7 +36,8 @@ export interface RamCheckResult {
 }
 
 export interface PortForwardResult {
-  status: 'preForwarded' | 'upnpOk' | 'upnpFailed'
+  // 설치기는 포트를 직접 열지 않고 "열려 있는지"만 확인한다.
+  status: 'open' | 'notOpen'
   externalIp?: string
   port: number
   message?: string

src/server/app.ts

@@ -143,7 +143,7 @@ app.use((req, res, next) => {
 })
 
 // 모드 폴더 안의 .jar 파일 목록을 JSON으로 반환. 설치기가 자동 다운로드용으로 사용.
-app.get('/file/mods/:folder/index.json', async (req, res) => {
+app.get('/file/mods/:folder/index.json', async (req, res, next) => {
   const folder = req.params.folder
   if (!/^[a-zA-Z0-9_\-]+$/.test(folder)) {
     res.status(404).json({ files: [] })
@@ -162,7 +162,8 @@ app.get('/file/mods/:folder/index.json', async (req, res) => {
       res.status(404).json({ files: [] })
       return
     }
-    throw error
+    // async 핸들러의 throw 는 Express4 가 잡지 못해 unhandledRejection 이 되므로 next 로 위임.
+    next(error)
   }
 })
 

src/server/routes/index.ts

@@ -8,9 +8,9 @@ indexRouter.get('/', async (_req, res, next) => {
     const manifest = await readManifest()
     const definitionMap = new Map<string, Awaited<ReturnType<typeof loadPackDefinition>>>()
     const keys = await listPackKeys()
-    for (const key of keys) {
+    // 팩 정의를 병렬 로드(op.ts 와 동일 패턴). 순차 await 보다 빠름.
-      definitionMap.set(key, await loadPackDefinition(key))
+    const definitions = await Promise.all(keys.map((key) => loadPackDefinition(key)))
-    }
+    keys.forEach((key, i) => definitionMap.set(key, definitions[i]))
     const packs = manifest.packs.map((entry) => ({
       name: entry.name,
       file: entry.file,

src/server/routes/op.ts

@@ -16,10 +16,12 @@ import {
   normalizePackDefinition,
   normalizePackList,
   readAccounts,
+  readManifest,
   renamePack,
   sanitizePackKey,
   saveTerm,
   savePackList,
+  setPackPublic,
   setTermVisibility
 } from '../../shared/store.js'
 import { fetchReleaseVersions } from '../../shared/mojang.js'
@@ -122,11 +124,15 @@ opRouter.get('/op/dashboard/:packName', requireAuth, async (req, res, next) => {
       return
     }
     const releases = await fetchReleaseVersions()
+    const manifest = await readManifest()
+    const entry = manifest.packs.find((e) => e.file === packKey)
+    const isPublic = entry ? entry.public !== false : true
     res.render('op/editor', {
       userId: req.session.userId,
       packKey,
       pack: definition,
-      releases
+      releases,
+      isPublic
     })
   } catch (error) {
     next(error)
@@ -519,6 +525,9 @@ opRouter.post('/op/dashboard/:packName', requireAuth, async (req, res, next) =>
       return
     }
     const finalKey = await renamePack(packKey, requestedKey, normalized)
+    // 체크박스는 체크됐을 때만 전송되므로, 없으면 비공개(개발자용).
+    const isPublic = pickFirstValue(req.body.isPublic) === 'on' || pickFirstValue(req.body.isPublic) === 'true'
+    await setPackPublic(finalKey, isPublic)
     res.redirect(`/op/dashboard/${finalKey}`)
   } catch (error) {
     next(error)

src/server/youtube.ts

@@ -299,7 +299,15 @@ async function runYtDlp(args: string[], makeError: (code: string, detail: string
  * 단일 영상 URL 의 메타데이터를 가져온다.
  * `--no-playlist` 로 플레이리스트 URL 이 들어와도 단일 영상 정보만 뽑음.
  */
+/** 운영자 입력 URL 이 yt-dlp 인자(플래그)로 오인되지 않도록 http(s) 스킴만 허용. */
+function assertHttpUrl(url: string): void {
+  if (!/^https?:\/\//i.test(url.trim())) {
+    throw new Error(t('youtube.invalidUrl'))
+  }
+}
+
 export async function fetchVideoMeta(url: string): Promise<YtPlaylistEntry | null> {
+  assertHttpUrl(url)
   const stdout = await runYtDlp(
     ['--dump-json', '--no-warnings', '--no-playlist', '--skip-download', url],
     (code, detail) => new Error(t('youtube.ytdlpVideoFailed', { code, detail }))
@@ -327,6 +335,7 @@ export async function fetchVideoMeta(url: string): Promise<YtPlaylistEntry | nul
  * `--flat-playlist --dump-json` 출력은 한 줄당 한 JSON.
  */
 export async function fetchPlaylistEntries(url: string): Promise<YtPlaylistEntry[]> {
+  assertHttpUrl(url)
   const stdout = await runYtDlp(
     ['--flat-playlist', '--dump-json', '--no-warnings', url],
     (code, detail) => new Error(t('youtube.ytdlpPlaylistFailed', { code, detail }))

src/shared/audience.ts

@@ -0,0 +1,20 @@
+// 설치기 "대상(audience)" 구분. 빌드 시 package.json 에 박히는 musicQuizAudience
+// 값으로 결정한다(electron-builder extraMetadata).
+//   - 'public'    : 일반 설치기. manifest 의 public!==false 인 pack 만 노출.
+//   - 'developer' : 개발자용 설치기. public===false 인 pack 만 노출.
+// 이 모듈은 electron 에 의존하지 않는 순수 로직만 둔다(server 빌드에도 포함되므로).
+
+export type Audience = 'public' | 'developer'
+
+export function resolveAudience(raw: unknown): Audience {
+  return raw === 'developer' ? 'developer' : 'public'
+}
+
+/**
+ * 주어진 pack 의 public 플래그가 현재 audience 에게 보여야 하는지.
+ * public 미지정(undefined)은 공개로 간주한다(하위호환).
+ */
+export function isPackVisibleForAudience(isPublic: boolean | undefined, audience: Audience): boolean {
+  const isPublicPack = isPublic !== false
+  return audience === 'developer' ? !isPublicPack : isPublicPack
+}

src/shared/store.ts

@@ -18,8 +18,15 @@ export async function readManifest(): Promise<Manifest> {
       return { packs: [] }
     }
     return {
-      packs: parsed.packs.filter((entry): entry is ManifestEntry =>
+      packs: parsed.packs
+        .filter((entry): entry is ManifestEntry =>
           typeof entry?.name === 'string' && typeof entry?.file === 'string')
+        .map((entry) => ({
+          name: entry.name,
+          file: entry.file,
+          // public 은 명시적 boolean 만 보존. 미지정은 그대로 undefined(=공개 취급).
+          ...(typeof entry.public === 'boolean' ? { public: entry.public } : {})
+        }))
     }
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
@@ -245,15 +252,32 @@ type ManifestSyncAction = 'add' | 'remove' | 'upsert'
 
 async function syncManifestWith(key: string, name: string, action: ManifestSyncAction): Promise<void> {
   const manifest = await readManifest()
+  const existing = manifest.packs.find((entry) => entry.file === key)
   const filtered = manifest.packs.filter((entry) => entry.file !== key)
   if (action === 'remove') {
     await writeManifest({ packs: filtered })
     return
   }
-  filtered.push({ name: name || key, file: key })
+  const entry: ManifestEntry = { name: name || key, file: key }
+  // 기존 public 값은 이름 변경/수정(upsert) 시에도 보존. 신규(add)는 기본 공개(true).
+  entry.public = existing && typeof existing.public === 'boolean' ? existing.public : true
+  filtered.push(entry)
   await writeManifest({ packs: filtered })
 }
 
+/** manifest 엔트리의 public(공개 여부) 플래그를 설정한다. */
+export async function setPackPublic(key: string, isPublic: boolean): Promise<void> {
+  const manifest = await readManifest()
+  let changed = false
+  for (const entry of manifest.packs) {
+    if (entry.file === key) {
+      entry.public = isPublic
+      changed = true
+    }
+  }
+  if (changed) await writeManifest(manifest)
+}
+
 function defaultPackList(): PackList {
   return { musicPlaylistUrl: '', imagePlaylistUrl: '', music: [], images: [] }
 }

src/shared/types.ts

@@ -37,6 +37,11 @@ export interface PackDefinition {
 export interface ManifestEntry {
   name: string
   file: string
+  /**
+   * 공개 여부. true(또는 미지정)면 일반 설치기(간편/리소스팩)에 노출,
+   * false 면 개발자용 설치기에만 노출된다. 하위호환: 값이 없으면 공개로 간주.
+   */
+  public?: boolean
 }
 
 export interface Manifest {

views/op/editor.ejs

@@ -30,6 +30,11 @@
         </label>
       </div>
 
+      <label style="display:flex;align-items:center;gap:10px;margin:8px 0;">
+        <input type="checkbox" name="isPublic" <%= (typeof isPublic === 'undefined' || isPublic) ? 'checked' : '' %> style="width:auto;" />
+        <span>공개 (체크 시 일반 설치기에 표시 / 해제 시 개발자용 설치기에만 표시)</span>
+      </label>
+
       <div class="gridTwo">
         <label>
           <span><%= t('editor.mcVersion') %></span>