Bump version to 2.3.8

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

.github/CODE_OF_CONDUCT.md

@@ -36,7 +36,7 @@ This Code of Conduct applies within all community spaces, and also applies when
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [Discord Server, message Founders/Devs](https://discord.gg/hf2pdc). All complaints will be reviewed and investigated promptly and fairly.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [Discord Server, message Founders/Devs](https://discord.gg/Fhbb9Yk5WW). All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the reporter of any incident.
 

.github/ISSUE_TEMPLATE/support_request.yml

@@ -22,7 +22,7 @@ body:
       value: |
         If you need help or support with using the launcher, please fill out this support request.
         Provide as much detail as possible so we can assist you effectively.
-        **Need a quick assistance?** Please Open-A-Ticket in our [Discord Server](https://discord.gg/gME8rUy3MB)!
+        **Need a quick assistance?** Please Open-A-Ticket in our [Discord Server](https://discord.gg/Fhbb9Yk5WW)!
 
   - type: textarea
     id: question

.gitignore

@@ -17,6 +17,9 @@ dist/
 # Project Specific: Downloaded patcher (from hytale-auth-server)
 backend/patcher/
 
+# Private docs (local only)
+docs/PATCH_CDN_INFRASTRUCTURE.md
+
 # macOS Specific
 .DS_Store
 *.zst.DS_Store

GUI/js/script.js

@@ -53,7 +53,7 @@ window.closeDiscordPopup = function() {
 };
 
 window.joinDiscord = async function() {
-  await window.electronAPI?.openExternal('https://discord.gg/hf2pdc');
+  await window.electronAPI?.openExternal('https://discord.gg/Fhbb9Yk5WW');
   
   try {
     await window.electronAPI?.saveConfig({ discordPopup: true });

GUI/js/ui.js

@@ -1103,7 +1103,7 @@ function getRetryContextMessage() {
 }
 
 window.openDiscordExternal = function() {
-  window.electronAPI?.openExternal('https://discord.gg/hf2pdc');
+  window.electronAPI?.openExternal('https://discord.gg/Fhbb9Yk5WW');
 };
 
 window.toggleMaximize = toggleMaximize;

README.md

@@ -18,7 +18,7 @@
 
 ### ⚠️ **WARNING: READ [QUICK START](#-quick-start) before Downloading & Installing the Launcher!** ⚠️
 
-#### 🛑 **Found a problem? [Join the HF2P Discord](https://discord.gg/hf2pdc) and head to `#-⚠️-community-help`** 🛑
+#### 🛑 **Found a problem? [Join the HF2P Discord](https://discord.gg/Fhbb9Yk5WW) and head to `#-⚠️-community-help`** 🛑
 
 <p>
   👍 If you like the project, <b>feel free to support us via Buy Me a Coffee!</b> ☕<br>
@@ -455,7 +455,7 @@ See [BUILD.md](docs/BUILD.md) for comprehensive build instructions.
 <div align="center">
 
 **Questions? Ads? Collaboration? Endorsement? Other business-related?** 
-Message the founders at https://discord.gg/hf2pdc
+Message the founders at https://discord.gg/Fhbb9Yk5WW
 
 </div>
 

SERVER.md

@@ -2,7 +2,7 @@
 
 Play with friends online! This guide covers both easy in-game hosting and advanced dedicated server setup.
 
-### **DOWNLOAD SERVER FILES (JAR/RAR/SCRIPTS) HERE: https://discord.gg/hf2pdc** 
+### **DOWNLOAD SERVER FILES (JAR/RAR/SCRIPTS) HERE: https://discord.gg/Fhbb9Yk5WW** 
 
 **Table of Contents**
 

TROUBLESHOOTING.md

@@ -1,6 +1,6 @@
 # Hytale F2P Launcher - Troubleshooting Guide
 
-This guide covers common issues and their solutions. If your issue isn't listed here, please check [existing issues](https://github.com/amiayweb/Hytale-F2P/issues) or join our [Discord](https://discord.gg/gME8rUy3MB).
+This guide covers common issues and their solutions. If your issue isn't listed here, please check [existing issues](https://github.com/amiayweb/Hytale-F2P/issues) or join our [Discord](https://discord.gg/Fhbb9Yk5WW).
 
 ---
 
@@ -437,7 +437,7 @@ Game sessions have a 10-hour TTL. This is by design for security.
 If your issue isn't resolved by this guide:
 
 1. **Check existing issues:** [GitHub Issues](https://github.com/amiayweb/Hytale-F2P/issues)
-2. **Join Discord:** [discord.gg/gME8rUy3MB](https://discord.gg/gME8rUy3MB)
+2. **Join Discord:** [discord.gg/Fhbb9Yk5WW](https://discord.gg/Fhbb9Yk5WW)
 3. **Open a new issue** with:
    - Your operating system and version
    - Launcher version

backend/core/config.js

@@ -54,6 +54,7 @@ function getAppDir() {
 const CONFIG_FILE = path.join(getAppDir(), 'config.json');
 const CONFIG_BACKUP = path.join(getAppDir(), 'config.json.bak');
 const CONFIG_TEMP = path.join(getAppDir(), 'config.json.tmp');
+const UUID_STORE_FILE = path.join(getAppDir(), 'uuid-store.json');
 
 // =============================================================================
 // CONFIG VALIDATION
@@ -152,6 +153,22 @@ function saveConfig(update) {
 
       // Load current config
       const currentConfig = loadConfig();
+
+      // SAFETY: If config file exists on disk but loadConfig() returned empty,
+      // something is wrong (file locked, corrupted, etc.). Refuse to save
+      // because merging with {} would wipe all existing data (userUuids, username, etc.)
+      if (Object.keys(currentConfig).length === 0 && fs.existsSync(CONFIG_FILE)) {
+        const fileSize = fs.statSync(CONFIG_FILE).size;
+        if (fileSize > 2) { // More than just "{}"
+          console.error(`[Config] REFUSING to save — loaded empty but file exists (${fileSize} bytes). Retrying load...`);
+          // Wait and retry the load
+          const delay = attempt * 200;
+          const start = Date.now();
+          while (Date.now() - start < delay) { /* busy wait */ }
+          continue;
+        }
+      }
+
       const newConfig = { ...currentConfig, ...update };
       const data = JSON.stringify(newConfig, null, 2);
 
@@ -238,11 +255,18 @@ function saveUsername(username) {
   // Check if we're actually changing the username (case-insensitive comparison)
   const isRename = currentName && currentName.toLowerCase() !== newName.toLowerCase();
 
+  // Also update UUID store (source of truth)
+  migrateUuidStoreIfNeeded();
+  const uuidStore = loadUuidStore();
+
   if (isRename) {
     // Find the UUID for the current username
     const currentKey = Object.keys(userUuids).find(
       k => k.toLowerCase() === currentName.toLowerCase()
     );
+    const currentStoreKey = Object.keys(uuidStore).find(
+      k => k.toLowerCase() === currentName.toLowerCase()
+    );
 
     if (currentKey && userUuids[currentKey]) {
       // Check if target username already exists (would be a different identity)
@@ -258,6 +282,9 @@ function saveUsername(username) {
         const uuid = userUuids[currentKey];
         delete userUuids[currentKey];
         userUuids[newName] = uuid;
+        // Same in UUID store
+        if (currentStoreKey) delete uuidStore[currentStoreKey];
+        uuidStore[newName] = uuid;
         console.log(`[Config] Renamed identity: "${currentKey}" → "${newName}" (UUID preserved: ${uuid})`);
       }
     }
@@ -270,11 +297,20 @@ function saveUsername(username) {
       const uuid = userUuids[currentKey];
       delete userUuids[currentKey];
       userUuids[newName] = uuid;
+      // Same in UUID store
+      const storeKey = Object.keys(uuidStore).find(k => k.toLowerCase() === currentName.toLowerCase());
+      if (storeKey) {
+        delete uuidStore[storeKey];
+        uuidStore[newName] = uuid;
+      }
       console.log(`[Config] Updated username case: "${currentKey}" → "${newName}"`);
     }
   }
 
-  // Save both username and updated userUuids
+  // Save UUID store
+  saveUuidStore(uuidStore);
+
+  // Save both username and updated userUuids to config
   saveConfig({ username: newName, userUuids });
   console.log(`[Config] Username saved: "${newName}"`);
   return newName;
@@ -310,6 +346,7 @@ function hasUsername() {
 
 // =============================================================================
 // UUID MANAGEMENT - Persistent and safe
+// Uses separate uuid-store.json as source of truth (survives config.json corruption)
 // =============================================================================
 
 /**
@@ -320,10 +357,55 @@ function normalizeUsername(username) {
   return username.trim().toLowerCase();
 }
 
+/**
+ * Load UUID store from separate file (independent of config.json)
+ */
+function loadUuidStore() {
+  try {
+    if (fs.existsSync(UUID_STORE_FILE)) {
+      const data = fs.readFileSync(UUID_STORE_FILE, 'utf8');
+      if (data.trim()) {
+        return JSON.parse(data);
+      }
+    }
+  } catch (err) {
+    console.error('[UUID Store] Failed to load:', err.message);
+  }
+  return {};
+}
+
+/**
+ * Save UUID store to separate file (atomic write)
+ */
+function saveUuidStore(store) {
+  try {
+    const dir = path.dirname(UUID_STORE_FILE);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const tmpFile = UUID_STORE_FILE + '.tmp';
+    fs.writeFileSync(tmpFile, JSON.stringify(store, null, 2), 'utf8');
+    fs.renameSync(tmpFile, UUID_STORE_FILE);
+  } catch (err) {
+    console.error('[UUID Store] Failed to save:', err.message);
+  }
+}
+
+/**
+ * One-time migration: copy userUuids from config.json to uuid-store.json
+ */
+function migrateUuidStoreIfNeeded() {
+  if (fs.existsSync(UUID_STORE_FILE)) return; // Already migrated
+  const config = loadConfig();
+  if (config.userUuids && Object.keys(config.userUuids).length > 0) {
+    console.log('[UUID Store] Migrating', Object.keys(config.userUuids).length, 'UUIDs from config.json');
+    saveUuidStore(config.userUuids);
+  }
+}
+
 /**
  * Get UUID for a username
- * Creates new UUID only if user explicitly doesn't exist
+ * Source of truth: uuid-store.json (separate from config.json)
- * Uses case-insensitive lookup to prevent duplicates, but preserves original case for display
+ * Also writes to config.json for backward compatibility
+ * Creates new UUID only if user doesn't exist in EITHER store
  */
 function getUuidForUser(username) {
   const { v4: uuidv4 } = require('uuid');
@@ -335,32 +417,69 @@ function getUuidForUser(username) {
   const displayName = username.trim();
   const normalizedLookup = displayName.toLowerCase();
 
-  const config = loadConfig();
+  // Ensure UUID store exists (one-time migration from config.json)
-  const userUuids = config.userUuids || {};
+  migrateUuidStoreIfNeeded();
 
-  // Case-insensitive lookup - find existing key regardless of case
+  // 1. Check UUID store first (source of truth)
-  const existingKey = Object.keys(userUuids).find(k => k.toLowerCase() === normalizedLookup);
+  const uuidStore = loadUuidStore();
+  const storeKey = Object.keys(uuidStore).find(k => k.toLowerCase() === normalizedLookup);
 
-  if (existingKey) {
+  if (storeKey) {
-    // Found existing - return UUID, update display name if case changed
+    const existingUuid = uuidStore[storeKey];
-    const existingUuid = userUuids[existingKey];
 
-    // If user typed different case, update the key to new case (preserving UUID)
+    // Update case if needed
-    if (existingKey !== displayName) {
+    if (storeKey !== displayName) {
-      console.log(`[Config] Updating username case: "${existingKey}" → "${displayName}"`);
+      console.log(`[UUID Store] Updating username case: "${storeKey}" → "${displayName}"`);
-      delete userUuids[existingKey];
+      delete uuidStore[storeKey];
-      userUuids[displayName] = existingUuid;
+      uuidStore[displayName] = existingUuid;
-      saveConfig({ userUuids });
+      saveUuidStore(uuidStore);
     }
 
+    // Sync to config.json (backward compat, non-critical)
+    try {
+      const config = loadConfig();
+      const configUuids = config.userUuids || {};
+      const configKey = Object.keys(configUuids).find(k => k.toLowerCase() === normalizedLookup);
+      if (!configKey || configUuids[configKey] !== existingUuid) {
+        if (configKey) delete configUuids[configKey];
+        configUuids[displayName] = existingUuid;
+        saveConfig({ userUuids: configUuids });
+      }
+    } catch (e) {
+      // Non-critical — UUID store is the source of truth
+    }
+
+    console.log(`[UUID] ${displayName} → ${existingUuid} (from uuid-store)`);
     return existingUuid;
   }
 
-  // Create new UUID for new user - store with original case
+  // 2. Fallback: check config.json (recovery if uuid-store.json was lost)
+  const config = loadConfig();
+  const userUuids = config.userUuids || {};
+  const configKey = Object.keys(userUuids).find(k => k.toLowerCase() === normalizedLookup);
+
+  if (configKey) {
+    const recoveredUuid = userUuids[configKey];
+    console.warn(`[UUID] RECOVERED "${displayName}" → ${recoveredUuid} from config.json (uuid-store was missing)`);
+
+    // Save to UUID store
+    uuidStore[displayName] = recoveredUuid;
+    saveUuidStore(uuidStore);
+
+    return recoveredUuid;
+  }
+
+  // 3. New user — generate UUID, save to BOTH stores
   const newUuid = uuidv4();
+  console.log(`[UUID] NEW user "${displayName}" → ${newUuid}`);
+
+  // Save to UUID store (source of truth)
+  uuidStore[displayName] = newUuid;
+  saveUuidStore(uuidStore);
+
+  // Save to config.json (backward compat)
   userUuids[displayName] = newUuid;
   saveConfig({ userUuids });
-  console.log(`[Config] Created new UUID for "${displayName}": ${newUuid}`);
 
   return newUuid;
 }
@@ -380,22 +499,26 @@ function getCurrentUuid() {
  * Get all UUID mappings (raw object)
  */
 function getAllUuidMappings() {
+  migrateUuidStoreIfNeeded();
+  const uuidStore = loadUuidStore();
+  // Fallback to config if uuid-store is empty
+  if (Object.keys(uuidStore).length === 0) {
     const config = loadConfig();
     return config.userUuids || {};
   }
+  return uuidStore;
+}
 
 /**
  * Get all UUID mappings as array with current user flag
  */
 function getAllUuidMappingsArray() {
-  const config = loadConfig();
+  const allMappings = getAllUuidMappings();
-  const userUuids = config.userUuids || {};
   const currentUsername = loadUsername();
-  // Case-insensitive comparison for isCurrent
   const normalizedCurrent = currentUsername ? currentUsername.toLowerCase() : null;
 
-  return Object.entries(userUuids).map(([username, uuid]) => ({
+  return Object.entries(allMappings).map(([username, uuid]) => ({
-    username,  // Original case preserved
+    username,
     uuid,
     isCurrent: username.toLowerCase() === normalizedCurrent
   }));
@@ -419,16 +542,20 @@ function setUuidForUser(username, uuid) {
 
   const displayName = username.trim();
   const normalizedLookup = displayName.toLowerCase();
+
+  // 1. Update UUID store (source of truth)
+  migrateUuidStoreIfNeeded();
+  const uuidStore = loadUuidStore();
+  const storeKey = Object.keys(uuidStore).find(k => k.toLowerCase() === normalizedLookup);
+  if (storeKey) delete uuidStore[storeKey];
+  uuidStore[displayName] = uuid;
+  saveUuidStore(uuidStore);
+
+  // 2. Update config.json (backward compat)
   const config = loadConfig();
   const userUuids = config.userUuids || {};
-
-  // Remove any existing entry with same name (case-insensitive)
   const existingKey = Object.keys(userUuids).find(k => k.toLowerCase() === normalizedLookup);
-  if (existingKey) {
+  if (existingKey) delete userUuids[existingKey];
-    delete userUuids[existingKey];
-  }
-
-  // Store with original case
   userUuids[displayName] = uuid;
   saveConfig({ userUuids });
 
@@ -454,20 +581,30 @@ function deleteUuidForUser(username) {
   }
 
   const normalizedLookup = username.trim().toLowerCase();
+  let deleted = false;
+
+  // 1. Delete from UUID store (source of truth)
+  migrateUuidStoreIfNeeded();
+  const uuidStore = loadUuidStore();
+  const storeKey = Object.keys(uuidStore).find(k => k.toLowerCase() === normalizedLookup);
+  if (storeKey) {
+    delete uuidStore[storeKey];
+    saveUuidStore(uuidStore);
+    deleted = true;
+  }
+
+  // 2. Delete from config.json (backward compat)
   const config = loadConfig();
   const userUuids = config.userUuids || {};
-
-  // Case-insensitive lookup
   const existingKey = Object.keys(userUuids).find(k => k.toLowerCase() === normalizedLookup);
-
   if (existingKey) {
     delete userUuids[existingKey];
     saveConfig({ userUuids });
-    console.log(`[Config] UUID deleted for "${username}"`);
+    deleted = true;
-    return true;
   }
 
-  return false;
+  if (deleted) console.log(`[Config] UUID deleted for "${username}"`);
+  return deleted;
 }
 
 /**
@@ -788,5 +925,6 @@ module.exports = {
   loadVersionBranch,
 
   // Constants
-  CONFIG_FILE
+  CONFIG_FILE,
+  UUID_STORE_FILE
 };

backend/managers/differentialUpdateManager.js

@@ -3,7 +3,7 @@ const path = require('path');
 const { execFile } = require('child_process');
 const { downloadFile, retryDownload } = require('../utils/fileManager');
 const { getOS, getArch } = require('../utils/platformUtils');
-const { validateChecksum, extractVersionDetails, getInstalledClientVersion, getUpdatePlan, extractVersionNumber } = require('../services/versionManager');
+const { validateChecksum, extractVersionDetails, getInstalledClientVersion, getUpdatePlan, extractVersionNumber, getAllMirrorUrls, getPatchesBaseUrl } = require('../services/versionManager');
 const { installButler } = require('./butlerManager');
 const { GAME_DIR, CACHE_DIR, TOOLS_DIR } = require('../core/paths');
 const { saveVersionClient } = require('../core/config');
@@ -31,15 +31,62 @@ async function acquireGameArchive(downloadUrl, targetPath, checksum, progressCal
 
   console.log(`Downloading game archive from: ${downloadUrl}`);
 
-  try {
+  // Try primary URL first, then mirror URLs on timeout/connection failure
-    if (allowRetry) {
+  const mirrors = await getAllMirrorUrls();
-      await retryDownload(downloadUrl, targetPath, progressCallback);
+  const primaryBase = await getPatchesBaseUrl();
-    } else {
+  const urlsToTry = [downloadUrl];
-      await downloadFile(downloadUrl, targetPath, progressCallback);
+
+  // Build mirror URLs by replacing the base URL
+  for (const mirror of mirrors) {
+    if (mirror !== primaryBase && downloadUrl.startsWith(primaryBase)) {
+      const mirrorUrl = downloadUrl.replace(primaryBase, mirror);
+      if (!urlsToTry.includes(mirrorUrl)) {
+        urlsToTry.push(mirrorUrl);
       }
+    }
+  }
+
+  let lastError;
+  for (let i = 0; i < urlsToTry.length; i++) {
+    const url = urlsToTry[i];
+    try {
+      if (i > 0) {
+        console.log(`[Download] Trying mirror ${i}: ${url}`);
+        if (progressCallback) {
+          progressCallback(`Trying alternative mirror (${i}/${urlsToTry.length - 1})...`, 0, null, null, null);
+        }
+        // Clean up partial download from previous attempt
+        if (fs.existsSync(targetPath)) {
+          try { fs.unlinkSync(targetPath); } catch (e) {}
+        }
+      }
+      if (allowRetry) {
+        await retryDownload(url, targetPath, progressCallback);
+      } else {
+        await downloadFile(url, targetPath, progressCallback);
+      }
+      lastError = null;
+      break; // Success
     } catch (error) {
-    const enhancedError = new Error(`Archive download failed: ${error.message}`);
+      lastError = error;
-    enhancedError.originalError = error;
+      const isConnectionError = error.message && (
+        error.message.includes('ETIMEDOUT') ||
+        error.message.includes('ECONNREFUSED') ||
+        error.message.includes('ECONNABORTED') ||
+        error.message.includes('timeout')
+      );
+      if (isConnectionError && i < urlsToTry.length - 1) {
+        console.warn(`[Download] Connection failed (${error.message}), will try mirror...`);
+        continue;
+      }
+      // Non-connection error or last mirror — throw
+      break;
+    }
+  }
+
+  if (lastError) {
+    const enhancedError = new Error(`Archive download failed: ${lastError.message}`);
+    enhancedError.originalError = lastError;
     enhancedError.downloadUrl = downloadUrl;
     enhancedError.targetPath = targetPath;
     throw enhancedError;

backend/managers/gameLauncher.js

@@ -250,6 +250,7 @@ async function launchGame(playerNameOverride = null, progressCallback, javaPathO
   }
 
   const uuid = getUuidForUser(playerName);
+  console.log(`[Launcher] UUID for "${playerName}": ${uuid} (verify this stays constant across launches)`);
 
   // Fetch tokens from auth server
   if (progressCallback) {
@@ -439,7 +440,7 @@ exec "$REAL_JAVA" "\${ARGS[@]}"
   // This enables runtime auth patching without modifying the server JAR
   const agentJar = path.join(gameLatest, 'Server', 'dualauth-agent.jar');
   if (fs.existsSync(agentJar)) {
-    const agentFlag = `-javaagent:${agentJar}`;
+    const agentFlag = `-javaagent:"${agentJar}"`;
     env.JAVA_TOOL_OPTIONS = env.JAVA_TOOL_OPTIONS
       ? `${env.JAVA_TOOL_OPTIONS} ${agentFlag}`
       : agentFlag;

backend/managers/gameManager.js

@@ -64,7 +64,7 @@ async function safeRemoveDirectory(dirPath, maxRetries = 3) {
   }
 }
 
-async function downloadPWR(branch = 'release', fileName = 'v8', progressCallback, cacheDir = CACHE_DIR, manualRetry = false, directUrl = null) {
+async function downloadPWR(branch = 'release', fileName = 'v8', progressCallback, cacheDir = CACHE_DIR, manualRetry = false, directUrl = null, expectedSize = null) {
   const osName = getOS();
   const arch = getArch();
 
@@ -85,23 +85,54 @@ async function downloadPWR(branch = 'release', fileName = 'v8', progressCallback
       console.log(`[DownloadPWR] Mirror URL: ${url}`);
     } catch (error) {
       console.error(`[DownloadPWR] Failed to get mirror URL: ${error.message}`);
-      const { MIRROR_BASE_URL } = require('../services/versionManager');
+      const { getPatchesBaseUrl } = require('../services/versionManager');
-      url = `${MIRROR_BASE_URL}/${osName}/${arch}/${branch}/0_to_${extractVersionNumber(fileName)}.pwr`;
+      const baseUrl = await getPatchesBaseUrl();
+      url = `${baseUrl}/${osName}/${arch}/${branch}/0_to_${extractVersionNumber(fileName)}.pwr`;
       console.log(`[DownloadPWR] Fallback URL: ${url}`);
     }
   }
 
+  // Look up expected file size from manifest if not provided
+  if (!expectedSize) {
+    try {
+      const { fetchMirrorManifest } = require('../services/versionManager');
+      const manifest = await fetchMirrorManifest();
+      // Try to match: "0_to_11" format or "v11" format
+      const versionMatch = fileName.match(/^(\d+)_to_(\d+)$/);
+      let manifestKey;
+      if (versionMatch) {
+        manifestKey = `${osName}/${arch}/${branch}/${fileName}.pwr`;
+      } else {
+        const buildNum = extractVersionNumber(fileName);
+        manifestKey = `${osName}/${arch}/${branch}/0_to_${buildNum}.pwr`;
+      }
+      if (manifest.files[manifestKey]) {
+        expectedSize = manifest.files[manifestKey].size;
+        console.log(`[PWR] Expected size from manifest: ${(expectedSize / 1024 / 1024).toFixed(2)} MB`);
+      }
+    } catch (e) {
+      console.log(`[PWR] Could not fetch expected size from manifest: ${e.message}`);
+    }
+  }
+
   const dest = path.join(cacheDir, `${branch}_${fileName}.pwr`);
 
   // Check if file exists and validate it
   if (fs.existsSync(dest) && !manualRetry) {
     const stats = fs.statSync(dest);
     if (stats.size > 1024 * 1024) {
+      // Validate against expected size - reject if file is truncated (< 99% of expected)
+      if (expectedSize && stats.size < expectedSize * 0.99) {
+        console.log(`[PWR] Cached file truncated: ${(stats.size / 1024 / 1024).toFixed(2)} MB, expected ${(expectedSize / 1024 / 1024).toFixed(2)} MB. Deleting and re-downloading.`);
+        fs.unlinkSync(dest);
+      } else {
         console.log(`[PWR] Using cached file: ${dest} (${(stats.size / 1024 / 1024).toFixed(2)} MB)`);
         return dest;
       }
+    } else {
       console.log(`[PWR] Cached file too small (${stats.size} bytes), re-downloading`);
     }
+  }
 
   console.log(`[DownloadPWR] Downloading from: ${url}`);
   
@@ -129,7 +160,7 @@ async function downloadPWR(branch = 'release', fileName = 'v8', progressCallback
         const retryStats = fs.statSync(dest);
         console.log(`PWR file downloaded (auto-retry), size: ${(retryStats.size / 1024 / 1024).toFixed(2)} MB`);
         
-        if (!validatePWRFile(dest)) {
+        if (!validatePWRFile(dest, expectedSize)) {
           console.log(`[PWR Validation] PWR file validation failed after auto-retry, deleting corrupted file: ${dest}`);
           fs.unlinkSync(dest);
           throw new Error('Downloaded PWR file is corrupted or invalid after automatic retry. Please retry manually');
@@ -180,7 +211,7 @@ async function downloadPWR(branch = 'release', fileName = 'v8', progressCallback
   const stats = fs.statSync(dest);
   console.log(`PWR file downloaded, size: ${(stats.size / 1024 / 1024).toFixed(2)} MB`);
 
-  if (!validatePWRFile(dest)) {
+  if (!validatePWRFile(dest, expectedSize)) {
     console.log(`[PWR Validation] PWR file validation failed, deleting corrupted file: ${dest}`);
     fs.unlinkSync(dest);
     throw new Error('Downloaded PWR file is corrupted or invalid. Please retry');
@@ -440,7 +471,7 @@ async function updateGameFiles(newVersion, progressCallback, gameDir = GAME_DIR,
           progressCallback(`Downloading patch ${i + 1}/${updatePlan.steps.length} (${stepName})...`, progress, null, null, null);
         }
 
-        const pwrFile = await downloadPWR(branch, stepName, progressCallback, cacheDir, false, step.url);
+        const pwrFile = await downloadPWR(branch, stepName, progressCallback, cacheDir, false, step.url, step.size);
 
         if (!pwrFile) {
           throw new Error(`Failed to download patch ${stepName}`);
@@ -891,7 +922,7 @@ function validateGameDirectory(gameDir, stagingDir) {
 
 // Enhanced PWR file validation
 // Accepts intermediate patches (50+ MB) and full installs (1.5+ GB)
-function validatePWRFile(filePath) {
+function validatePWRFile(filePath, expectedSize = null) {
   try {
     if (!fs.existsSync(filePath)) {
       return false;
@@ -906,6 +937,13 @@ function validatePWRFile(filePath) {
       return false;
     }
 
+    // Validate against expected size if known (reject if < 99% of expected)
+    if (expectedSize && stats.size < expectedSize * 0.99) {
+      const expectedMB = expectedSize / 1024 / 1024;
+      console.log(`[PWR Validation] File truncated: ${sizeInMB.toFixed(2)} MB, expected ${expectedMB.toFixed(2)} MB`);
+      return false;
+    }
+
     console.log(`[PWR Validation] File size: ${sizeInMB.toFixed(2)} MB - OK`);
     return true;
   } catch (error) {

backend/services/versionManager.js

@@ -1,22 +1,191 @@
 const axios = require('axios');
 const crypto = require('crypto');
 const fs = require('fs');
+const path = require('path');
 const { getOS, getArch } = require('../utils/platformUtils');
 
-// Patches CDN via auth server redirect gateway (allows instant CDN switching)
+// Patches base URL fetched dynamically via multi-source fallback chain
 const AUTH_DOMAIN = process.env.HYTALE_AUTH_DOMAIN || 'auth.sanasol.ws';
-const MIRROR_BASE_URL = `https://${AUTH_DOMAIN}/patches`;
+const PATCHES_CONFIG_SOURCES = [
-const MIRROR_MANIFEST_URL = `${MIRROR_BASE_URL}/manifest.json`;
+  { type: 'http', url: `https://${AUTH_DOMAIN}/api/patches-config`, name: 'primary' },
+  { type: 'http', url: 'https://htdwnldsan.top/patches-config', name: 'backup-1' },
+  { type: 'http', url: 'https://dl1.htdwnldsan.top/patches-config', name: 'backup-2' },
+  { type: 'doh',  name: '_patches.htdwnldsan.top', name_label: 'dns-txt' },
+];
+const HARDCODED_FALLBACK = 'https://dl.vboro.de/patches';
+
+// Alternative mirrors (non-Cloudflare) for regions where CF is blocked
+const NON_CF_MIRRORS = [
+  'https://dl1.htdwnldsan.top',
+  'https://htdwnldsan.top/patches',
+];
 
 // Fallback: latest known build number if manifest is unreachable
 const FALLBACK_LATEST_BUILD = 11;
 
+let patchesBaseUrl = null;
+let patchesConfigTime = 0;
+const PATCHES_CONFIG_CACHE_DURATION = 300000; // 5 minutes
+
 let manifestCache = null;
 let manifestCacheTime = 0;
 const MANIFEST_CACHE_DURATION = 60000; // 1 minute
 
+// Disk cache path for patches URL (survives restarts)
+function getDiskCachePath() {
+  const os = require('os');
+  const home = os.homedir();
+  let appDir;
+  if (process.platform === 'win32') {
+    appDir = path.join(home, 'AppData', 'Local', 'HytaleF2P');
+  } else if (process.platform === 'darwin') {
+    appDir = path.join(home, 'Library', 'Application Support', 'HytaleF2P');
+  } else {
+    appDir = path.join(home, '.hytalef2p');
+  }
+  return path.join(appDir, 'patches-url-cache.json');
+}
+
+function saveDiskCache(url) {
+  try {
+    const cachePath = getDiskCachePath();
+    const dir = path.dirname(cachePath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(cachePath, JSON.stringify({ patches_url: url, ts: Date.now() }), 'utf8');
+  } catch (e) {
+    // Non-critical, ignore
+  }
+}
+
+function loadDiskCache() {
+  try {
+    const cachePath = getDiskCachePath();
+    if (fs.existsSync(cachePath)) {
+      const data = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+      if (data && data.patches_url) return data.patches_url;
+    }
+  } catch (e) {
+    // Non-critical, ignore
+  }
+  return null;
+}
+
 /**
- * Fetch the mirror manifest from MEGA S4
+ * Fetch patches URL from a single HTTP config endpoint
+ */
+async function fetchFromHttp(url) {
+  const response = await axios.get(url, {
+    timeout: 8000,
+    headers: { 'User-Agent': 'Hytale-F2P-Launcher' }
+  });
+  if (response.data && response.data.patches_url) {
+    return response.data.patches_url.replace(/\/+$/, '');
+  }
+  throw new Error('Invalid response');
+}
+
+/**
+ * Fetch patches URL from DNS TXT record via DNS-over-HTTPS
+ */
+async function fetchFromDoh(recordName) {
+  const dohEndpoints = [
+    { url: 'https://dns.google/resolve', params: { name: recordName, type: 'TXT' } },
+    { url: 'https://cloudflare-dns.com/dns-query', params: { name: recordName, type: 'TXT' }, headers: { 'Accept': 'application/dns-json' } },
+  ];
+
+  for (const endpoint of dohEndpoints) {
+    try {
+      const response = await axios.get(endpoint.url, {
+        params: endpoint.params,
+        headers: { 'User-Agent': 'Hytale-F2P-Launcher', ...(endpoint.headers || {}) },
+        timeout: 5000
+      });
+      const answers = response.data && response.data.Answer;
+      if (answers && answers.length > 0) {
+        // TXT records are quoted, strip quotes
+        const txt = answers[0].data.replace(/^"|"$/g, '');
+        if (txt.startsWith('http')) return txt.replace(/\/+$/, '');
+      }
+    } catch (e) {
+      // Try next DoH endpoint
+    }
+  }
+  throw new Error('All DoH endpoints failed');
+}
+
+/**
+ * Fetch patches base URL with hardened multi-source fallback chain:
+ * 1. Memory cache (5 min)
+ * 2. HTTP: auth.sanasol.ws (primary)
+ * 3. HTTP: htdwnldsan.top (backup, different host/domain/registrar)
+ * 4. DNS TXT: _patches.htdwnldsan.top via DoH (different protocol layer)
+ * 5. Disk cache (survives restarts, never expires)
+ * 6. Hardcoded fallback URL (last resort)
+ */
+async function getPatchesBaseUrl() {
+  const now = Date.now();
+
+  // 1. Memory cache
+  if (patchesBaseUrl && (now - patchesConfigTime) < PATCHES_CONFIG_CACHE_DURATION) {
+    return patchesBaseUrl;
+  }
+
+  // 2-4. Try all sources: HTTP endpoints first, then DoH
+  for (const source of PATCHES_CONFIG_SOURCES) {
+    try {
+      let url;
+      if (source.type === 'http') {
+        console.log(`[Mirror] Trying ${source.name}: ${source.url}`);
+        url = await fetchFromHttp(source.url);
+      } else if (source.type === 'doh') {
+        console.log(`[Mirror] Trying ${source.name_label}: ${source.name}`);
+        url = await fetchFromDoh(source.name);
+      }
+      if (url) {
+        patchesBaseUrl = url;
+        patchesConfigTime = now;
+        saveDiskCache(url);
+        console.log(`[Mirror] Patches URL (via ${source.name || source.name_label}): ${url}`);
+        return url;
+      }
+    } catch (e) {
+      console.warn(`[Mirror] ${source.name || source.name_label} failed: ${e.message}`);
+    }
+  }
+
+  // 5. Stale memory cache (any age)
+  if (patchesBaseUrl) {
+    console.log('[Mirror] All sources failed, using stale memory cache:', patchesBaseUrl);
+    return patchesBaseUrl;
+  }
+
+  // 6. Disk cache (survives restarts)
+  const diskUrl = loadDiskCache();
+  if (diskUrl) {
+    patchesBaseUrl = diskUrl;
+    console.log('[Mirror] All sources failed, using disk cache:', diskUrl);
+    return diskUrl;
+  }
+
+  // 7. Hardcoded fallback
+  console.warn('[Mirror] All sources + caches exhausted, using hardcoded fallback:', HARDCODED_FALLBACK);
+  patchesBaseUrl = HARDCODED_FALLBACK;
+  return HARDCODED_FALLBACK;
+}
+
+/**
+ * Get all available mirror base URLs (primary + non-Cloudflare fallbacks)
+ * Used by download logic to retry on different mirrors when primary is blocked
+ */
+async function getAllMirrorUrls() {
+  const primary = await getPatchesBaseUrl();
+  // Deduplicate: don't include mirrors that match primary
+  const mirrors = NON_CF_MIRRORS.filter(m => m !== primary);
+  return [primary, ...mirrors];
+}
+
+/**
+ * Fetch the mirror manifest — tries primary URL first, then non-Cloudflare mirrors
  */
 async function fetchMirrorManifest() {
   const now = Date.now();
@@ -26,28 +195,48 @@ async function fetchMirrorManifest() {
     return manifestCache;
   }
 
+  const mirrors = await getAllMirrorUrls();
+
+  for (let i = 0; i < mirrors.length; i++) {
+    const baseUrl = mirrors[i];
+    const manifestUrl = `${baseUrl}/manifest.json`;
     try {
-    console.log('[Mirror] Fetching manifest from:', MIRROR_MANIFEST_URL);
+      console.log(`[Mirror] Fetching manifest from: ${manifestUrl}`);
-    const response = await axios.get(MIRROR_MANIFEST_URL, {
+      const response = await axios.get(manifestUrl, {
         timeout: 15000,
+        maxRedirects: 5,
         headers: { 'User-Agent': 'Hytale-F2P-Launcher' }
       });
 
       if (response.data && response.data.files) {
         manifestCache = response.data;
         manifestCacheTime = now;
+        // If a non-primary mirror worked, switch to it for downloads too
+        if (i > 0) {
+          console.log(`[Mirror] Primary unreachable, switching to mirror: ${baseUrl}`);
+          patchesBaseUrl = baseUrl;
+          patchesConfigTime = now;
+          saveDiskCache(baseUrl);
+        }
         console.log('[Mirror] Manifest fetched successfully');
         return response.data;
       }
       throw new Error('Invalid manifest structure');
     } catch (error) {
-    console.error('[Mirror] Error fetching manifest:', error.message);
+      const isTimeout = error.code === 'ETIMEDOUT' || error.code === 'ECONNABORTED' || error.message.includes('timeout');
+      console.error(`[Mirror] Error fetching manifest from ${baseUrl}: ${error.message}${isTimeout ? ' (Cloudflare may be blocked)' : ''}`);
+      if (i < mirrors.length - 1) {
+        console.log(`[Mirror] Trying next mirror...`);
+      }
+    }
+  }
+
+  // All mirrors failed — use cached manifest if available
   if (manifestCache) {
-      console.log('[Mirror] Using expired cache');
+    console.log('[Mirror] All mirrors failed, using expired cache');
     return manifestCache;
   }
-    throw error;
+  throw new Error('All mirrors failed and no cached manifest available');
-  }
 }
 
 /**
@@ -82,9 +271,10 @@ function getPlatformPatches(manifest, branch = 'release') {
  * Find optimal patch path using BFS with download size minimization
  * Returns array of { from, to, url, size, key } steps, or null if no path found
  */
-function findOptimalPatchPath(currentBuild, targetBuild, patches) {
+async function findOptimalPatchPath(currentBuild, targetBuild, patches) {
   if (currentBuild >= targetBuild) return [];
 
+  const baseUrl = await getPatchesBaseUrl();
   const edges = {};
   for (const patch of patches) {
     if (!edges[patch.from]) edges[patch.from] = [];
@@ -118,7 +308,7 @@ function findOptimalPatchPath(currentBuild, targetBuild, patches) {
         path: [...path, {
           from: edge.from,
           to: edge.to,
-          url: `${MIRROR_BASE_URL}/${edge.key}`,
+          url: `${baseUrl}/${edge.key}`,
           size: edge.size,
           key: edge.key
         }],
@@ -139,7 +329,7 @@ async function getUpdatePlan(currentBuild, targetBuild, branch = 'release') {
   const patches = getPlatformPatches(manifest, branch);
 
   // Try optimal path
-  const steps = findOptimalPatchPath(currentBuild, targetBuild, patches);
+  const steps = await findOptimalPatchPath(currentBuild, targetBuild, patches);
 
   if (steps && steps.length > 0) {
     const totalSize = steps.reduce((sum, s) => sum + s.size, 0);
@@ -150,10 +340,11 @@ async function getUpdatePlan(currentBuild, targetBuild, branch = 'release') {
   // Fallback: full install 0 -> target
   const fullPatch = patches.find(p => p.from === 0 && p.to === targetBuild);
   if (fullPatch) {
+    const baseUrl = await getPatchesBaseUrl();
     const step = {
       from: 0,
       to: targetBuild,
-      url: `${MIRROR_BASE_URL}/${fullPatch.key}`,
+      url: `${baseUrl}/${fullPatch.key}`,
       size: fullPatch.size,
       key: fullPatch.key
     };
@@ -200,7 +391,8 @@ async function getPWRUrl(branch = 'release', version = 'v11') {
     const fullPatch = patches.find(p => p.from === 0 && p.to === targetBuild);
 
     if (fullPatch) {
-      const url = `${MIRROR_BASE_URL}/${fullPatch.key}`;
+      const baseUrl = await getPatchesBaseUrl();
+      const url = `${baseUrl}/${fullPatch.key}`;
       console.log(`[Mirror] PWR URL: ${url}`);
       return url;
     }
@@ -216,7 +408,8 @@ async function getPWRUrl(branch = 'release', version = 'v11') {
   }
 
   // Construct mirror URL (will work if patch was uploaded but manifest is stale)
-  return `${MIRROR_BASE_URL}/${os}/${arch}/${branch}/0_to_${targetBuild}.pwr`;
+  const baseUrl = await getPatchesBaseUrl();
+  return `${baseUrl}/${os}/${arch}/${branch}/0_to_${targetBuild}.pwr`;
 }
 
 // Backward-compatible alias
@@ -240,14 +433,15 @@ function extractVersionNumber(version) {
   return isNaN(num) ? 0 : num;
 }
 
-function buildArchiveUrl(buildNumber, branch = 'release') {
+async function buildArchiveUrl(buildNumber, branch = 'release') {
+  const baseUrl = await getPatchesBaseUrl();
   const os = getOS();
   const arch = getArch();
-  return `${MIRROR_BASE_URL}/${os}/${arch}/${branch}/0_to_${buildNumber}.pwr`;
+  return `${baseUrl}/${os}/${arch}/${branch}/0_to_${buildNumber}.pwr`;
 }
 
 async function checkArchiveExists(buildNumber, branch = 'release') {
-  const url = buildArchiveUrl(buildNumber, branch);
+  const url = await buildArchiveUrl(buildNumber, branch);
   try {
     const response = await axios.head(url, { timeout: 10000 });
     return response.status === 200;
@@ -269,7 +463,7 @@ async function discoverAvailableVersions(latestKnown, branch = 'release') {
 
 async function extractVersionDetails(targetVersion, branch = 'release') {
   const buildNumber = extractVersionNumber(targetVersion);
-  const fullUrl = buildArchiveUrl(buildNumber, branch);
+  const fullUrl = await buildArchiveUrl(buildNumber, branch);
 
   return {
     version: targetVersion,
@@ -340,5 +534,6 @@ module.exports = {
   extractVersionNumber,
   getPlatformPatches,
   findOptimalPatchPath,
-  MIRROR_BASE_URL
+  getPatchesBaseUrl,
+  getAllMirrorUrls
 };

backend/utils/clientPatcher.js

@@ -9,7 +9,9 @@ const MAX_DOMAIN_LENGTH = 16;
 
 // DualAuth ByteBuddy Agent (runtime class transformation, no JAR modification)
 const DUALAUTH_AGENT_URL = 'https://github.com/sanasol/hytale-auth-server/releases/latest/download/dualauth-agent.jar';
+const DUALAUTH_AGENT_VERSION_API = 'https://api.github.com/repos/sanasol/hytale-auth-server/releases/latest';
 const DUALAUTH_AGENT_FILENAME = 'dualauth-agent.jar';
+const DUALAUTH_AGENT_VERSION_FILE = 'dualauth-agent.version';
 
 function getTargetDomain() {
   if (process.env.HYTALE_AUTH_DOMAIN) {
@@ -511,30 +513,70 @@ class ClientPatcher {
    */
   async ensureAgentAvailable(serverDir, progressCallback) {
     const agentPath = this.getAgentPath(serverDir);
+    const versionPath = path.join(serverDir, DUALAUTH_AGENT_VERSION_FILE);
 
     console.log('=== DualAuth Agent (ByteBuddy) ===');
     console.log(`Target: ${agentPath}`);
 
-    // Check if agent already exists and is valid
+    // Check local version and whether file exists
+    let localVersion = null;
+    let agentExists = false;
     if (fs.existsSync(agentPath)) {
       try {
         const stats = fs.statSync(agentPath);
         if (stats.size > 1024) {
-          console.log(`DualAuth Agent present (${(stats.size / 1024).toFixed(0)} KB)`);
+          agentExists = true;
-          if (progressCallback) progressCallback('DualAuth Agent ready', 100);
+          if (fs.existsSync(versionPath)) {
-          return { success: true, agentPath, alreadyExists: true };
+            localVersion = fs.readFileSync(versionPath, 'utf8').trim();
           }
-        // File exists but too small - corrupt, re-download
+        } else {
           console.log('Agent file appears corrupt, re-downloading...');
           fs.unlinkSync(agentPath);
+        }
       } catch (e) {
         console.warn('Could not check agent file:', e.message);
       }
     }
 
+    // Check for updates from GitHub
+    let remoteVersion = null;
+    let needsDownload = !agentExists;
+    if (agentExists) {
+      try {
+        if (progressCallback) progressCallback('Checking for agent updates...', 5);
+        const axios = require('axios');
+        const resp = await axios.get(DUALAUTH_AGENT_VERSION_API, {
+          timeout: 5000,
+          headers: { 'Accept': 'application/vnd.github.v3+json' }
+        });
+        remoteVersion = resp.data.tag_name; // e.g. "v1.1.10"
+        if (localVersion && localVersion === remoteVersion) {
+          console.log(`DualAuth Agent up to date (${localVersion})`);
+          if (progressCallback) progressCallback('DualAuth Agent ready', 100);
+          return { success: true, agentPath, alreadyExists: true, version: localVersion };
+        }
+        console.log(`Agent update available: ${localVersion || 'unknown'} → ${remoteVersion}`);
+        needsDownload = true;
+      } catch (e) {
+        // GitHub API failed - use existing agent if available
+        console.warn(`Could not check for updates: ${e.message}`);
+        if (agentExists) {
+          console.log(`Using existing agent (${localVersion || 'unknown version'})`);
+          if (progressCallback) progressCallback('DualAuth Agent ready', 100);
+          return { success: true, agentPath, alreadyExists: true, version: localVersion };
+        }
+      }
+    }
+
+    if (!needsDownload) {
+      if (progressCallback) progressCallback('DualAuth Agent ready', 100);
+      return { success: true, agentPath, alreadyExists: true, version: localVersion };
+    }
+
     // Download agent from GitHub releases
-    if (progressCallback) progressCallback('Downloading DualAuth Agent...', 20);
+    const action = agentExists ? 'Updating' : 'Downloading';
-    console.log(`Downloading from: ${DUALAUTH_AGENT_URL}`);
+    if (progressCallback) progressCallback(`${action} DualAuth Agent...`, 20);
+    console.log(`${action} from: ${DUALAUTH_AGENT_URL}`);
 
     try {
       // Ensure server directory exists
@@ -548,7 +590,7 @@ class ClientPatcher {
       const stream = await smartDownloadStream(DUALAUTH_AGENT_URL, (chunk, downloadedBytes, total) => {
         if (progressCallback && total) {
           const percent = 20 + Math.floor((downloadedBytes / total) * 70);
-          progressCallback(`Downloading agent... ${(downloadedBytes / 1024).toFixed(0)} KB`, percent);
+          progressCallback(`${action} agent... ${(downloadedBytes / 1024).toFixed(0)} KB`, percent);
         }
       });
 
@@ -575,9 +617,13 @@ class ClientPatcher {
       }
       fs.renameSync(tmpPath, agentPath);
 
-      console.log(`DualAuth Agent downloaded (${(stats.size / 1024).toFixed(0)} KB)`);
+      // Save version
+      const version = remoteVersion || 'unknown';
+      fs.writeFileSync(versionPath, version, 'utf8');
+
+      console.log(`DualAuth Agent ${agentExists ? 'updated' : 'downloaded'} (${(stats.size / 1024).toFixed(0)} KB, ${version})`);
       if (progressCallback) progressCallback('DualAuth Agent ready', 100);
-      return { success: true, agentPath };
+      return { success: true, agentPath, updated: agentExists, version };
 
     } catch (downloadError) {
       console.error(`Failed to download DualAuth Agent: ${downloadError.message}`);
@@ -586,6 +632,11 @@ class ClientPatcher {
       if (fs.existsSync(tmpPath)) {
         try { fs.unlinkSync(tmpPath); } catch (e) { /* ignore */ }
       }
+      // If we had an existing agent, still use it
+      if (agentExists) {
+        console.log('Using existing agent despite update failure');
+        return { success: true, agentPath, alreadyExists: true, version: localVersion };
+      }
       return { success: false, error: downloadError.message };
     }
   }

docs/PATCH_CDN_INFRASTRUCTURE.md

@@ -1,217 +0,0 @@
-# Patch CDN Infrastructure & Game Update System
-
-## Overview
-
-The F2P launcher downloads game patches through a CDN redirect gateway hosted on the auth server. This allows instant CDN switching (e.g., for DMCA takedowns) without releasing a new launcher version.
-
-## Architecture
-
-```
-Launcher --> GET auth.sanasol.ws/patches/manifest.json
-          --> 302 --> mega.io/.../manifest.json
-
-Launcher --> GET auth.sanasol.ws/patches/windows/amd64/release/0_to_11.pwr
-          --> 302 --> mega.io/.../windows/amd64/release/0_to_11.pwr
-```
-
-The auth server acts as a pure redirect gateway (302). No bandwidth is consumed on the auth server - all actual file transfers happen directly between the launcher and the CDN.
-
-## URLs
-
-| URL | Purpose |
-|-----|---------|
-| `https://auth.sanasol.ws/patches/*` | Redirect gateway (302 -> CDN) |
-| `https://auth.sanasol.ws/patches/manifest.json` | Patch manifest (redirects to CDN) |
-| `https://auth.sanasol.ws/admin/page/settings` | Admin panel to change CDN URL |
-| `https://auth.sanasol.ws/admin/api/settings/patches-cdn` | API to GET/POST CDN base URL |
-
-### Default CDN (MEGA S4)
-
-```
-Base URL: https://s3.g.s4.mega.io/kcvismkrtfcalgwxzsazbq46l72dwsypqaham/hytale/patches
-```
-
-### Changing CDN (DMCA response)
-
-1. Go to `https://auth.sanasol.ws/admin/page/settings`
-2. Find "Patches CDN Base URL" section
-3. Change URL to new CDN (e.g., `https://new-cdn.example.com/patches`)
-4. Click "Save" - all launcher requests instantly redirect to new CDN
-5. No launcher update needed
-
-## Manifest Format
-
-The manifest is a JSON file listing all available patch files:
-
-```json
-{
-  "updated": "2026-02-20T13:20:09.776Z",
-  "files": {
-    "windows/amd64/release/0_to_11.pwr": { "size": 1618804736 },
-    "windows/amd64/release/10_to_11.pwr": { "size": 62914560 },
-    "darwin/arm64/release/0_to_11.pwr": { "size": 1617100800 },
-    "server/release": { "version": "2026.02.19-1a311a592", "size": 1509949440, "sha256": "..." },
-    ...
-  }
-}
-```
-
-### Key Structure
-
-File keys follow the pattern: `{os}/{arch}/{branch}/{from}_to_{to}.pwr`
-
-- **OS**: `windows`, `linux`, `darwin`
-- **Arch**: `amd64`, `arm64`
-- **Branch**: `release`, `pre-release`
-- **Patch**: `{from}_to_{to}.pwr` (e.g., `0_to_11.pwr` for full install, `10_to_11.pwr` for differential)
-
-Server builds use: `server/{branch}` with `version`, `size`, `sha256` fields.
-
-## Game Update Process
-
-### 1. Version Check
-
-```
-Launcher calls: getLatestClientVersion(branch)
-  -> Fetches manifest from auth.sanasol.ws/patches/manifest.json
-  -> Finds highest build number for current platform/branch
-  -> Returns "v{buildNumber}" (e.g., "v11")
-```
-
-### 2. Update Plan (Optimal Patch Routing)
-
-```
-Launcher calls: getUpdatePlan(currentBuild, targetBuild, branch)
-  -> Fetches manifest
-  -> Finds available patches for platform
-  -> Uses BFS to find optimal path (minimizes total download size)
-  -> Example: build 5 -> 11 might use: 5->10 (148MB) + 10->11 (60MB)
-    instead of: 0->11 (1.5GB)
-```
-
-### 3. Download & Apply
-
-```
-For each step in the update plan:
-  1. Download .pwr file from auth.sanasol.ws/patches/{key}
-     (redirects to CDN, supports resume via Range headers)
-  2. Apply patch using butler tool:
-     butler apply --staging-dir <staging> <pwr_file> <game_dir>
-  3. Save version after each step
-```
-
-### 4. Fresh Install
-
-For first-time installs (currentBuild = 0):
-- Downloads `0_to_{target}.pwr` (full install, ~1.5GB)
-- Applies with butler to create the full game directory
-
-### 5. Differential Update
-
-For existing installations:
-- Finds optimal patch chain (e.g., `10_to_11.pwr` at ~60MB)
-- Applies incrementally, saving progress after each step
-- Falls back to full install if no patch path found
-
-## Mirror Sync Script
-
-The mirror script (`scripts/hytale-mirror.js`) downloads patches from the official Hytale API and uploads to MEGA S4.
-
-### Usage
-
-```bash
-cd scripts
-node hytale-mirror.js download   # Download patches locally
-node hytale-mirror.js upload     # Upload to MEGA S4 via rclone
-node hytale-mirror.js sync       # Download + Upload in one step
-```
-
-### What It Does
-
-1. **Discovery**: Calls Hytale API to find available patches for all platforms
-2. **Download**: Downloads .pwr files to `scripts/mirror/` directory
-3. **Manifest Generation**: Creates `manifest.json` with file sizes (no local paths)
-4. **Upload**: Uses `rclone` to sync to MEGA S4
-
-### SOCKS5 Proxy
-
-- API discovery calls use SOCKS5 proxy rotation (for rate limiting)
-- File downloads do NOT use proxy (too slow for large files)
-- Proxy list in `proxies.json` (auto-refreshed from proxy service)
-
-### Prerequisites
-
-- `rclone` configured with `megas4` remote pointing to MEGA S4
-- Node.js 20+
-- Network access to Hytale API endpoints
-
-## Launcher Configuration
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `HYTALE_AUTH_DOMAIN` | `auth.sanasol.ws` | Auth domain (used for patch redirects) |
-
-### Key Files
-
-| File | Description |
-|------|-------------|
-| `backend/services/versionManager.js` | Manifest fetching, version checking, update planning |
-| `backend/managers/differentialUpdateManager.js` | Download orchestration, butler integration |
-| `backend/utils/fileManager.js` | File download with retry, resume, stall detection |
-| `backend/managers/gameLauncher.js` | Game launch with token fetch, patching, signing |
-
-### Constants (versionManager.js)
-
-```javascript
-const AUTH_DOMAIN = process.env.HYTALE_AUTH_DOMAIN || 'auth.sanasol.ws';
-const MIRROR_BASE_URL = `https://${AUTH_DOMAIN}/patches`;
-const MIRROR_MANIFEST_URL = `${MIRROR_BASE_URL}/manifest.json`;
-const MANIFEST_CACHE_DURATION = 60000; // 1 minute cache
-const FALLBACK_LATEST_BUILD = 11; // If manifest unreachable
-```
-
-## Auth Server Implementation
-
-### Routes
-
-```
-GET /patches/*  -> handlePatchRedirect()
-  - Extracts path after /patches/
-  - Reads CDN base URL from Redis settings
-  - Returns 302 redirect to {baseUrl}/{path}
-  - Tracks download metrics
-
-GET /admin/api/settings/patches-cdn -> getPatchesCdnBaseUrl()
-POST /admin/api/settings/patches-cdn -> setPatchesCdnBaseUrl()
-```
-
-### Redis Storage
-
-```
-settings:global -> { patchesCdnBaseUrl: "https://s3.g.s4.mega.io/..." }
-metrics:downloads -> { "patch:manifest.json": count, ... }
-```
-
-## Troubleshooting
-
-### "Invalid manifest structure" error
-- Check manifest.json is valid JSON with `files` object
-- Verify CDN is accessible: `curl -sL https://auth.sanasol.ws/patches/manifest.json | python3 -m json.tool`
-- Check admin settings for correct CDN URL
-
-### 0-byte downloads
-- Verify redirect works: `curl -sI https://auth.sanasol.ws/patches/darwin/arm64/release/0_to_11.pwr`
-- Should show `302` with `Location` header
-- Test actual download: `curl -sL -o /dev/null -w "%{size_download}" -r 0-1023 <url>`
-
-### Manifest has local paths
-- Regenerate manifest: `node scripts/hytale-mirror.js download` (re-scans files)
-- Re-upload: `node scripts/hytale-mirror.js upload`
-- Verify: entries should only have `{ size: <bytes> }`, no `path` field
-
-### CDN switch not taking effect
-- Check Redis: CDN URL stored in `settings:global`
-- Verify via API: `curl https://auth.sanasol.ws/admin/api/settings/patches-cdn`
-- Manifest is cached for 1 minute in launcher - wait or restart

main.js

@@ -84,12 +84,12 @@ function setDiscordActivity() {
       largeImageText: 'Hytale F2P Launcher',
       buttons: [
         {
-          label: 'GitHub',
+          label: 'Download',
-          url: 'https://github.com/amiayweb/Hytale-F2P'
+          url: 'https://git.sanhost.net/sanasol/hytale-f2p/releases'
         },
         {
           label: 'Discord',
-          url: 'https://discord.gg/hf2pdc'
+          url: 'https://discord.gg/Fhbb9Yk5WW'
         }
       ]
     });
@@ -964,8 +964,8 @@ ipcMain.handle('open-external', async (event, url) => {
 
 ipcMain.handle('open-download-page', async () => {
   try {
-    // Open GitHub releases page for manual download
+    // Open Forgejo releases page for manual download
-    await shell.openExternal('https://github.com/amiayweb/Hytale-F2P/releases/latest');
+    await shell.openExternal('https://git.sanhost.net/sanasol/hytale-f2p/releases/latest');
     return { success: true };
   } catch (error) {
     console.error('Failed to open download page:', error);

package.json

@@ -1,8 +1,8 @@
 {
   "name": "hytale-f2p-launcher",
-  "version": "2.3.1",
+  "version": "2.3.8",
   "description": "A modern, cross-platform launcher for Hytale with automatic updates and multi-client support",
-  "homepage": "https://github.com/amiayweb/Hytale-F2P",
+  "homepage": "https://git.sanhost.net/sanasol/hytale-f2p",
   "main": "main.js",
   "scripts": {
     "start": "electron .",

test-uuid-persistence.js

@@ -0,0 +1,523 @@
+#!/usr/bin/env node
+/**
+ * UUID Persistence Tests
+ *
+ * Simulates the exact conditions that caused character data loss:
+ * - Config file corruption during updates
+ * - File locks making config temporarily unreadable
+ * - Username re-entry after config wipe
+ *
+ * Run: node test-uuid-persistence.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Use a temp directory so we don't mess with real config
+const TEST_DIR = path.join(os.tmpdir(), 'hytale-uuid-test-' + Date.now());
+const CONFIG_FILE = path.join(TEST_DIR, 'config.json');
+const CONFIG_BACKUP = path.join(TEST_DIR, 'config.json.bak');
+const CONFIG_TEMP = path.join(TEST_DIR, 'config.json.tmp');
+const UUID_STORE_FILE = path.join(TEST_DIR, 'uuid-store.json');
+
+// Track test results
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(condition, message) {
+  if (condition) {
+    passed++;
+    console.log(`  ✓ ${message}`);
+  } else {
+    failed++;
+    failures.push(message);
+    console.log(`  ✗ FAIL: ${message}`);
+  }
+}
+
+function assertEqual(actual, expected, message) {
+  if (actual === expected) {
+    passed++;
+    console.log(`  ✓ ${message}`);
+  } else {
+    failed++;
+    failures.push(`${message} (expected: ${expected}, got: ${actual})`);
+    console.log(`  ✗ FAIL: ${message} (expected: "${expected}", got: "${actual}")`);
+  }
+}
+
+function cleanup() {
+  try {
+    if (fs.existsSync(TEST_DIR)) {
+      fs.rmSync(TEST_DIR, { recursive: true });
+    }
+  } catch (e) {}
+}
+
+function setup() {
+  cleanup();
+  fs.mkdirSync(TEST_DIR, { recursive: true });
+}
+
+// ============================================================================
+// Inline the config functions so we can override paths
+// (We can't require config.js directly because it uses hardcoded getAppDir())
+// ============================================================================
+
+function validateConfig(config) {
+  if (!config || typeof config !== 'object') return false;
+  if (config.userUuids !== undefined && typeof config.userUuids !== 'object') return false;
+  if (config.username !== undefined && (typeof config.username !== 'string')) return false;
+  return true;
+}
+
+function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      const data = fs.readFileSync(CONFIG_FILE, 'utf8');
+      if (data.trim()) {
+        const config = JSON.parse(data);
+        if (validateConfig(config)) return config;
+        console.warn('[Config] Primary config invalid structure, trying backup...');
+      }
+    }
+  } catch (err) {
+    console.error('[Config] Failed to load primary config:', err.message);
+  }
+
+  try {
+    if (fs.existsSync(CONFIG_BACKUP)) {
+      const data = fs.readFileSync(CONFIG_BACKUP, 'utf8');
+      if (data.trim()) {
+        const config = JSON.parse(data);
+        if (validateConfig(config)) {
+          console.log('[Config] Recovered from backup successfully');
+          try { fs.writeFileSync(CONFIG_FILE, data, 'utf8'); } catch (e) {}
+          return config;
+        }
+      }
+    }
+  } catch (err) {}
+
+  return {};
+}
+
+function saveConfig(update) {
+  const maxRetries = 3;
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      if (!fs.existsSync(TEST_DIR)) fs.mkdirSync(TEST_DIR, { recursive: true });
+
+      const currentConfig = loadConfig();
+
+      // SAFETY CHECK: refuse to save if file exists but loaded empty
+      if (Object.keys(currentConfig).length === 0 && fs.existsSync(CONFIG_FILE)) {
+        const fileSize = fs.statSync(CONFIG_FILE).size;
+        if (fileSize > 2) {
+          console.error(`[Config] REFUSING to save — loaded empty but file exists (${fileSize} bytes). Retrying...`);
+          const delay = attempt * 50; // shorter delay for tests
+          const start = Date.now();
+          while (Date.now() - start < delay) {}
+          continue;
+        }
+      }
+
+      const newConfig = { ...currentConfig, ...update };
+      const data = JSON.stringify(newConfig, null, 2);
+
+      fs.writeFileSync(CONFIG_TEMP, data, 'utf8');
+      const verification = JSON.parse(fs.readFileSync(CONFIG_TEMP, 'utf8'));
+      if (!validateConfig(verification)) throw new Error('Validation failed');
+
+      if (fs.existsSync(CONFIG_FILE)) {
+        try {
+          const currentData = fs.readFileSync(CONFIG_FILE, 'utf8');
+          if (currentData.trim()) fs.writeFileSync(CONFIG_BACKUP, currentData, 'utf8');
+        } catch (e) {}
+      }
+
+      fs.renameSync(CONFIG_TEMP, CONFIG_FILE);
+      return true;
+    } catch (err) {
+      try { if (fs.existsSync(CONFIG_TEMP)) fs.unlinkSync(CONFIG_TEMP); } catch (e) {}
+      if (attempt >= maxRetries) throw err;
+    }
+  }
+}
+
+function loadUuidStore() {
+  try {
+    if (fs.existsSync(UUID_STORE_FILE)) {
+      const data = fs.readFileSync(UUID_STORE_FILE, 'utf8');
+      if (data.trim()) return JSON.parse(data);
+    }
+  } catch (err) {}
+  return {};
+}
+
+function saveUuidStore(store) {
+  const tmpFile = UUID_STORE_FILE + '.tmp';
+  fs.writeFileSync(tmpFile, JSON.stringify(store, null, 2), 'utf8');
+  fs.renameSync(tmpFile, UUID_STORE_FILE);
+}
+
+function migrateUuidStoreIfNeeded() {
+  if (fs.existsSync(UUID_STORE_FILE)) return;
+  const config = loadConfig();
+  if (config.userUuids && Object.keys(config.userUuids).length > 0) {
+    console.log('[UUID Store] Migrating', Object.keys(config.userUuids).length, 'UUIDs');
+    saveUuidStore(config.userUuids);
+  }
+}
+
+function getUuidForUser(username) {
+  const { v4: uuidv4 } = require('uuid');
+  if (!username || !username.trim()) throw new Error('Username required');
+
+  const displayName = username.trim();
+  const normalizedLookup = displayName.toLowerCase();
+
+  migrateUuidStoreIfNeeded();
+
+  // 1. Check UUID store (source of truth)
+  const uuidStore = loadUuidStore();
+  const storeKey = Object.keys(uuidStore).find(k => k.toLowerCase() === normalizedLookup);
+  if (storeKey) {
+    const existingUuid = uuidStore[storeKey];
+    if (storeKey !== displayName) {
+      delete uuidStore[storeKey];
+      uuidStore[displayName] = existingUuid;
+      saveUuidStore(uuidStore);
+    }
+    // Sync to config (non-critical)
+    try {
+      const config = loadConfig();
+      const configUuids = config.userUuids || {};
+      const configKey = Object.keys(configUuids).find(k => k.toLowerCase() === normalizedLookup);
+      if (!configKey || configUuids[configKey] !== existingUuid) {
+        if (configKey) delete configUuids[configKey];
+        configUuids[displayName] = existingUuid;
+        saveConfig({ userUuids: configUuids });
+      }
+    } catch (e) {}
+    return existingUuid;
+  }
+
+  // 2. Fallback: check config.json
+  const config = loadConfig();
+  const userUuids = config.userUuids || {};
+  const configKey = Object.keys(userUuids).find(k => k.toLowerCase() === normalizedLookup);
+  if (configKey) {
+    const recoveredUuid = userUuids[configKey];
+    uuidStore[displayName] = recoveredUuid;
+    saveUuidStore(uuidStore);
+    return recoveredUuid;
+  }
+
+  // 3. New user — generate UUID
+  const newUuid = uuidv4();
+  uuidStore[displayName] = newUuid;
+  saveUuidStore(uuidStore);
+  userUuids[displayName] = newUuid;
+  saveConfig({ userUuids });
+  return newUuid;
+}
+
+// ============================================================================
+// OLD CODE (before fix) — for comparison testing
+// ============================================================================
+
+function getUuidForUser_OLD(username) {
+  const { v4: uuidv4 } = require('uuid');
+  if (!username || !username.trim()) throw new Error('Username required');
+  const displayName = username.trim();
+  const normalizedLookup = displayName.toLowerCase();
+
+  const config = loadConfig();
+  const userUuids = config.userUuids || {};
+  const existingKey = Object.keys(userUuids).find(k => k.toLowerCase() === normalizedLookup);
+
+  if (existingKey) {
+    return userUuids[existingKey];
+  }
+
+  // New user
+  const newUuid = uuidv4();
+  userUuids[displayName] = newUuid;
+  saveConfig({ userUuids });
+  return newUuid;
+}
+
+function saveConfig_OLD(update) {
+  // OLD saveConfig without safety check
+  if (!fs.existsSync(TEST_DIR)) fs.mkdirSync(TEST_DIR, { recursive: true });
+  const currentConfig = loadConfig();
+  // NO SAFETY CHECK — this is the bug
+  const newConfig = { ...currentConfig, ...update };
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(newConfig, null, 2), 'utf8');
+  return true;
+}
+
+// ============================================================================
+// TESTS
+// ============================================================================
+
+console.log('\n' + '='.repeat(70));
+console.log('UUID PERSISTENCE TESTS — Simulating update corruption scenarios');
+console.log('='.repeat(70));
+
+// --------------------------------------------------------------------------
+// TEST 1: Normal flow — UUID stays consistent
+// --------------------------------------------------------------------------
+console.log('\n--- Test 1: Normal flow — UUID stays consistent ---');
+setup();
+
+const uuid1 = getUuidForUser('SpecialK');
+const uuid2 = getUuidForUser('SpecialK');
+const uuid3 = getUuidForUser('specialk'); // case insensitive
+
+assertEqual(uuid1, uuid2, 'Same username returns same UUID');
+assertEqual(uuid1, uuid3, 'Case-insensitive lookup returns same UUID');
+assert(uuid1.match(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i), 'UUID is valid v4 format');
+
+// --------------------------------------------------------------------------
+// TEST 2: Simulate update corruption (THE BUG) — old code
+// --------------------------------------------------------------------------
+console.log('\n--- Test 2: OLD CODE — Config wipe during update loses UUID ---');
+setup();
+
+// Setup: player has UUID
+const oldConfig = { username: 'SpecialK', userUuids: { 'SpecialK': 'aaaaaaaa-bbbb-4ccc-9ddd-eeeeeeeeeeee' }, hasLaunchedBefore: true };
+fs.writeFileSync(CONFIG_FILE, JSON.stringify(oldConfig, null, 2), 'utf8');
+
+const uuidBefore = getUuidForUser_OLD('SpecialK');
+assertEqual(uuidBefore, 'aaaaaaaa-bbbb-4ccc-9ddd-eeeeeeeeeeee', 'UUID correct before corruption');
+
+// Simulate: config.json gets corrupted (loadConfig returns {} because file locked)
+// This simulates what happens when saveConfig reads an empty/locked file
+fs.writeFileSync(CONFIG_FILE, '', 'utf8'); // Simulate corruption: empty file
+
+// Old saveConfig behavior: reads empty, merges with update, saves
+// This wipes userUuids
+saveConfig_OLD({ hasLaunchedBefore: true });
+
+const configAfterCorruption = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+assert(!configAfterCorruption.userUuids, 'OLD CODE: userUuids wiped after corruption');
+assert(!configAfterCorruption.username, 'OLD CODE: username wiped after corruption');
+
+// Player re-enters name, gets NEW UUID (character data lost!)
+const uuidAfterOld = getUuidForUser_OLD('SpecialK');
+assert(uuidAfterOld !== uuidBefore, 'OLD CODE: UUID changed after corruption (BUG!)');
+
+// --------------------------------------------------------------------------
+// TEST 3: NEW CODE — Config wipe during update, UUID survives via uuid-store
+// --------------------------------------------------------------------------
+console.log('\n--- Test 3: NEW CODE — Config wipe + UUID survives via uuid-store ---');
+setup();
+
+// Setup: player has UUID (stored in both config.json AND uuid-store.json)
+const initialConfig = { username: 'SpecialK', userUuids: { 'SpecialK': 'aaaaaaaa-bbbb-4ccc-9ddd-eeeeeeeeeeee' }, hasLaunchedBefore: true };
+fs.writeFileSync(CONFIG_FILE, JSON.stringify(initialConfig, null, 2), 'utf8');
+
+// First call migrates to uuid-store
+const uuidFirst = getUuidForUser('SpecialK');
+assertEqual(uuidFirst, 'aaaaaaaa-bbbb-4ccc-9ddd-eeeeeeeeeeee', 'UUID correct before corruption');
+assert(fs.existsSync(UUID_STORE_FILE), 'uuid-store.json created');
+
+// Simulate: config.json gets wiped (same as the update bug)
+fs.writeFileSync(CONFIG_FILE, '{}', 'utf8');
+
+// Verify config is empty
+const wipedConfig = loadConfig();
+assert(!wipedConfig.userUuids || Object.keys(wipedConfig.userUuids).length === 0, 'Config wiped — no userUuids');
+assert(!wipedConfig.username, 'Config wiped — no username');
+
+// Player re-enters same name → UUID recovered from uuid-store!
+const uuidAfterNew = getUuidForUser('SpecialK');
+assertEqual(uuidAfterNew, 'aaaaaaaa-bbbb-4ccc-9ddd-eeeeeeeeeeee', 'NEW CODE: UUID preserved after config wipe!');
+
+// --------------------------------------------------------------------------
+// TEST 4: saveConfig safety check — refuses to overwrite good data with empty
+// --------------------------------------------------------------------------
+console.log('\n--- Test 4: saveConfig safety check — blocks destructive writes ---');
+setup();
+
+// Setup: valid config file with data
+const goodConfig = { username: 'SpecialK', userUuids: { 'SpecialK': 'aaaaaaaa-bbbb-4ccc-9ddd-eeeeeeeeeeee' }, hasLaunchedBefore: true, installPath: 'C:\\Games\\Hytale' };
+fs.writeFileSync(CONFIG_FILE, JSON.stringify(goodConfig, null, 2), 'utf8');
+
+// Make the file temporarily unreadable by writing garbage (simulates file lock/corruption)
+const originalContent = fs.readFileSync(CONFIG_FILE, 'utf8');
+fs.writeFileSync(CONFIG_FILE, 'NOT VALID JSON!!!', 'utf8');
+
+// Try to save — should refuse because file exists but can't be parsed
+let saveThrew = false;
+try {
+  saveConfig({ someNewField: true });
+} catch (e) {
+  saveThrew = true;
+}
+
+// The file should still have the garbage (not overwritten with { someNewField: true })
+const afterContent = fs.readFileSync(CONFIG_FILE, 'utf8');
+
+// Restore original for backup recovery test
+fs.writeFileSync(CONFIG_FILE, JSON.stringify(goodConfig, null, 2), 'utf8');
+
+// Note: with invalid JSON, loadConfig returns {} and safety check triggers
+// The save may eventually succeed on retry if the file becomes readable
+// What matters is that it doesn't blindly overwrite
+assert(afterContent !== '{\n  "someNewField": true\n}', 'Safety check prevented blind overwrite of corrupted file');
+
+// --------------------------------------------------------------------------
+// TEST 5: Backup recovery — config.json corrupted, recovered from .bak
+// --------------------------------------------------------------------------
+console.log('\n--- Test 5: Backup recovery — auto-recover from .bak ---');
+setup();
+
+// Create config and backup
+const validConfig = { username: 'SpecialK', userUuids: { 'SpecialK': 'aaaaaaaa-bbbb-4ccc-9ddd-eeeeeeeeeeee' } };
+fs.writeFileSync(CONFIG_BACKUP, JSON.stringify(validConfig, null, 2), 'utf8');
+fs.writeFileSync(CONFIG_FILE, 'CORRUPTED', 'utf8');
+
+const recovered = loadConfig();
+assertEqual(recovered.username, 'SpecialK', 'Username recovered from backup');
+assert(recovered.userUuids && recovered.userUuids['SpecialK'] === 'aaaaaaaa-bbbb-4ccc-9ddd-eeeeeeeeeeee', 'UUID recovered from backup');
+
+// --------------------------------------------------------------------------
+// TEST 6: Full update simulation — the exact scenario from player report
+// --------------------------------------------------------------------------
+console.log('\n--- Test 6: Full update simulation (player report scenario) ---');
+setup();
+
+// Step 1: Player installs v2.3.4, sets username, plays game
+console.log('  Step 1: Player sets up profile...');
+saveConfig({ username: 'Special K', hasLaunchedBefore: true });
+const originalUuid = getUuidForUser('Special K');
+console.log(`  Original UUID: ${originalUuid}`);
+
+// Step 2: v2.3.5 auto-update — new app launches
+console.log('  Step 2: Simulating v2.3.5 update...');
+
+// Simulate the 3 saveConfig calls that happen during startup
+// But first, simulate config being temporarily locked (returns empty)
+const preUpdateContent = fs.readFileSync(CONFIG_FILE, 'utf8');
+fs.writeFileSync(CONFIG_FILE, '', 'utf8'); // Simulate: file empty during write (race condition)
+
+// These are the 3 calls from: profileManager.init, migrateUserDataToCentralized, handleFirstLaunchCheck
+// With our safety check, they should NOT wipe the data
+try { saveConfig({ hasLaunchedBefore: true }); } catch (e) { /* expected — safety check blocks it */ }
+
+// Simulate file becomes readable again (antivirus releases lock)
+fs.writeFileSync(CONFIG_FILE, preUpdateContent, 'utf8');
+
+// Step 3: Player re-enters username (because UI might show empty)
+console.log('  Step 3: Player re-enters username...');
+const postUpdateUuid = getUuidForUser('Special K');
+console.log(`  Post-update UUID: ${postUpdateUuid}`);
+
+assertEqual(postUpdateUuid, originalUuid, 'UUID survived the full update cycle!');
+
+// --------------------------------------------------------------------------
+// TEST 7: Multiple users — UUIDs stay independent
+// --------------------------------------------------------------------------
+console.log('\n--- Test 7: Multiple users — UUIDs stay independent ---');
+setup();
+
+const uuidAlice = getUuidForUser('Alice');
+const uuidBob = getUuidForUser('Bob');
+const uuidCharlie = getUuidForUser('Charlie');
+
+assert(uuidAlice !== uuidBob, 'Alice and Bob have different UUIDs');
+assert(uuidBob !== uuidCharlie, 'Bob and Charlie have different UUIDs');
+
+// Wipe config, all should survive
+fs.writeFileSync(CONFIG_FILE, '{}', 'utf8');
+
+assertEqual(getUuidForUser('Alice'), uuidAlice, 'Alice UUID survived config wipe');
+assertEqual(getUuidForUser('Bob'), uuidBob, 'Bob UUID survived config wipe');
+assertEqual(getUuidForUser('Charlie'), uuidCharlie, 'Charlie UUID survived config wipe');
+
+// --------------------------------------------------------------------------
+// TEST 8: UUID store deleted — recovery from config.json
+// --------------------------------------------------------------------------
+console.log('\n--- Test 8: UUID store deleted — recovery from config.json ---');
+setup();
+
+// Create UUID via normal flow (saves to both stores)
+const uuidOriginal = getUuidForUser('TestPlayer');
+
+// Delete uuid-store.json (simulates user manually deleting it or disk issue)
+fs.unlinkSync(UUID_STORE_FILE);
+assert(!fs.existsSync(UUID_STORE_FILE), 'uuid-store.json deleted');
+
+// UUID should be recovered from config.json
+const uuidRecovered = getUuidForUser('TestPlayer');
+assertEqual(uuidRecovered, uuidOriginal, 'UUID recovered from config.json after uuid-store deletion');
+assert(fs.existsSync(UUID_STORE_FILE), 'uuid-store.json recreated after recovery');
+
+// --------------------------------------------------------------------------
+// TEST 9: Both stores deleted — new UUID generated (fresh install)
+// --------------------------------------------------------------------------
+console.log('\n--- Test 9: Both stores deleted — new UUID (fresh install) ---');
+setup();
+
+const uuidFresh = getUuidForUser('NewPlayer');
+
+// Delete both
+fs.unlinkSync(UUID_STORE_FILE);
+fs.unlinkSync(CONFIG_FILE);
+
+const uuidAfterWipe = getUuidForUser('NewPlayer');
+assert(uuidAfterWipe !== uuidFresh, 'New UUID generated when both stores are gone (expected for true fresh install)');
+
+// --------------------------------------------------------------------------
+// TEST 10: Worst case — config.json wiped AND uuid-store.json exists
+// Simulates the EXACT player-reported scenario with new code
+// --------------------------------------------------------------------------
+console.log('\n--- Test 10: Exact player scenario with new code ---');
+setup();
+
+// Player has been playing for a while
+saveConfig({
+  username: 'Special K',
+  hasLaunchedBefore: true,
+  installPath: 'C:\\Games\\Hytale',
+  version_client: '2026.02.19-1a311a592',
+  version_branch: 'release',
+  userUuids: { 'Special K': '11111111-2222-4333-9444-555555555555' }
+});
+
+// First call creates uuid-store.json
+const originalUuid10 = getUuidForUser('Special K');
+assertEqual(originalUuid10, '11111111-2222-4333-9444-555555555555', 'Original UUID loaded');
+
+// BOOM: Update happens, config.json completely wiped
+fs.writeFileSync(CONFIG_FILE, '{}', 'utf8');
+
+// Username lost — player has to re-enter
+const loadedUsername = loadConfig().username;
+assert(!loadedUsername, 'Username is gone from config (simulating what player saw)');
+
+// Player types "Special K" again in settings
+saveConfig({ username: 'Special K' });
+
+// Player clicks Play — getUuidForUser called
+const recoveredUuid10 = getUuidForUser('Special K');
+assertEqual(recoveredUuid10, '11111111-2222-4333-9444-555555555555', 'UUID recovered — character data preserved!');
+
+// ============================================================================
+// RESULTS
+// ============================================================================
+console.log('\n' + '='.repeat(70));
+console.log(`RESULTS: ${passed} passed, ${failed} failed`);
+if (failed > 0) {
+  console.log('\nFailures:');
+  failures.forEach(f => console.log(`  ✗ ${f}`));
+}
+console.log('='.repeat(70));
+
+cleanup();
+process.exit(failed > 0 ? 1 : 0);