Merge krystie-improvements into main

Resolves 24 conflicts between Hermes (DC-008/009/010 + response-helper
envelope standardization) and Krystie (DC-005 src/ refactor path fixes,
DC-006 TOTP integration, DC-007 new test suites, cloud backup
destinations).

Conflict resolutions:
- src/utils/logging.js:    took ours (consumers depend on logError/
                            safeErrorMessage/createLogger exports)
- src/config/site.js:      merged (her factored validateAndLogConfig +
                            applyConfigFields helpers)
- src/context/dns.js:      took hers (admin/readonly role iteration for
                            write operations)
- src/utilities/backup-
  manager.js:              took hers (Dropbox/WebDAV/SFTP cloud feature)
- status/dist/*, status/
  sw.js:                   took hers (minified bundles + newer SW cache)

Additional fix (post-merge regression):
- src/monitoring/health-checker.js: fixed DC-005 path miss —
  'require(./platform-paths)' → 'require(../../platform-paths)'

Test status: 921/922 passing. One known failure in logging.test.js
(async file-handle timing) tracked as follow-up.

dashcaddy-api/src/config/index.js

@@ -4,7 +4,7 @@
  */
 const paths = require('./paths');
 const site = require('./site');
-const { APP, LIMITS, TIMEOUTS, RETRIES, CADDY } = require('../../constants');
+const { APP, LIMITS, TIMEOUTS, RETRIES, CADDY } = require('../utilities/constants');
 
 // Load logging level
 const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };

dashcaddy-api/src/config/migrations.js

@@ -0,0 +1,142 @@
+/**
+ * Config migration system
+ *
+ * When config.json schema changes between versions, register a migration
+ * function here. On load, the loader detects the stored version, runs all
+ * migrations from that version forward, and writes the result back.
+ *
+ * Migration format:
+ *   migrations[<toVersion>] = (rawConfig) => { ...mutations, _version: toVersion }
+ *
+ * Each migration is responsible for transforming the previous version's
+ * shape into the next version's shape. They run sequentially, so v1→v2→v3
+ * all execute in order.
+ *
+ * For first-time users with no config file, the loader creates a fresh
+ * config with CURRENT_VERSION, so they start at the latest schema.
+ */
+const fs = require('fs');
+const path = require('path');
+const _platformPaths = require('../../platform-paths');
+
+const CURRENT_VERSION = 2;
+
+/**
+ * Migrations: keys are the version they PRODUCE.
+ * Each migration takes a raw config object and returns the next version.
+ */
+const migrations = {
+  // v0 (unversioned) → v1: add _version field, normalize dns structure
+  1: (raw) => {
+    const migrated = { ...raw };
+    if (!migrated._version) migrated._version = 1;
+    // Normalize: older configs may have dns as a string IP, convert to object
+    if (typeof migrated.dns === 'string') {
+      migrated.dns = { ip: migrated.dns, port: 5380 };
+    } else if (!migrated.dns) {
+      migrated.dns = { ip: '', port: 5380 };
+    }
+    return migrated;
+  },
+
+  // v1 → v2: add dns.provider field (default: 'technitium' for backwards compat)
+  2: (raw) => {
+    const migrated = { ...raw };
+    if (migrated.dns && !migrated.dns.provider) {
+      migrated.dns.provider = 'technitium';
+    }
+    migrated._version = 2;
+    return migrated;
+  }
+};
+
+/**
+ * Run all migrations from `fromVersion` (or detected) to CURRENT_VERSION.
+ * @param {object} raw - The raw config object (may or may not have _version)
+ * @returns {object} The migrated config
+ */
+function migrate(raw) {
+  if (!raw || typeof raw !== 'object') {
+    // First-time load: return minimal config at current version
+    return { _version: CURRENT_VERSION };
+  }
+
+  const fromVersion = raw._version || 0;
+  if (fromVersion > CURRENT_VERSION) {
+    // Config from a future version — bail out, don't corrupt it
+    // The validation step will catch any actual issues
+    return raw;
+  }
+
+  let current = { ...raw };
+  for (let v = fromVersion + 1; v <= CURRENT_VERSION; v++) {
+    if (migrations[v]) {
+      current = migrations[v](current);
+    } else {
+      // No migration defined for this version, just bump _version
+      current._version = v;
+    }
+  }
+  return current;
+}
+
+/**
+ * Load config from disk, run migrations if needed, and write back the
+ * migrated version. Safe to call on every startup.
+ * @param {string} configFile - Absolute path to config.json
+ * @param {object} log - Logger instance
+ * @returns {object} The migrated config object
+ */
+function loadAndMigrate(configFile, log) {
+  let raw = null;
+  let fileExisted = false;
+
+  if (fs.existsSync(configFile)) {
+    fileExisted = true;
+    try {
+      raw = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+    } catch (e) {
+      if (log && log.error) {
+        log.error('config-migration', 'Failed to parse config.json, using defaults', { error: e.message });
+      }
+      raw = null;
+    }
+  }
+
+  const fromVersion = raw && raw._version ? raw._version : 0;
+  const migrated = migrate(raw);
+
+  // Only write back to disk if:
+  //   1. The file already existed (we don't create configs on fresh installs —
+  //      the loader's defaults handle that case), AND
+  //   2. The version actually changed (no point rewriting identical content)
+  if (fileExisted && fromVersion < CURRENT_VERSION) {
+    if (log && log.info) {
+      log.info('config-migration', `Migrated config v${fromVersion} → v${CURRENT_VERSION}`, {
+        from: fromVersion,
+        to: CURRENT_VERSION,
+        path: configFile
+      });
+    }
+    // Write back the migrated config
+    try {
+      // Ensure parent dir exists
+      const dir = path.dirname(configFile);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(configFile, JSON.stringify(migrated, null, 2));
+    } catch (e) {
+      if (log && log.warn) {
+        log.warn('config-migration', 'Failed to write migrated config back to disk', { error: e.message });
+      }
+    }
+  }
+
+  return migrated;
+}
+
+module.exports = {
+  CURRENT_VERSION,
+  migrations,
+  migrate,
+  loadAndMigrate
+};

dashcaddy-api/src/config/site.js

@@ -1,10 +1,15 @@
 /**
  * Site configuration loader
  * Loads and manages site-wide settings from config.json
+ *
+ * Includes automatic migration from older config versions (see migrations.js).
+ * Users never see the migration — it runs silently on startup, writes the
+ * updated config back, and the rest of the app only ever sees the current
+ * schema.
  */
-const fs = require('fs');
-const { validateConfig } = require('../../config-schema');
-const { CADDY } = require('../../constants');
+const { validateConfig } = require('../utilities/config-schema');
+const { CADDY } = require('../utilities/constants');
+const { loadAndMigrate, CURRENT_VERSION } = require('./migrations');
 
 const siteConfig = {
   tld: '.home',
@@ -19,7 +24,7 @@ const siteConfig = {
   routingMode: 'subdomain'
 };
 
-function applyRawConfig(raw) {
+function applyConfigFields(raw) {
   siteConfig.tld = raw.tld || '.home';
   if (!siteConfig.tld.startsWith('.')) siteConfig.tld = '.' + siteConfig.tld;
   siteConfig.caName = raw.caName || '';
@@ -33,24 +38,27 @@ function applyRawConfig(raw) {
   siteConfig.routingMode = raw.routingMode || 'subdomain';
   siteConfig.pylon = raw.pylon || null;
 }
+function validateAndLogConfig(raw, log) {
+  const { valid, errors: configErrors, warnings: configWarnings } = validateConfig(raw);
+  if (log && log.warn) {
+    if (!valid) {
+      log.warn('config', 'Config validation errors', { errors: configErrors });
+    }
+    for (const w of configWarnings) {
+      log.warn('config', w);
+    }
+  }
+}
 
 function loadSiteConfig(CONFIG_FILE, log) {
   try {
-    if (fs.existsSync(CONFIG_FILE)) {
-      const raw = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    // Run migrations first — this handles config.json files from older
+    // versions of DashCaddy and writes the migrated version back to disk.
+    const raw = loadAndMigrate(CONFIG_FILE, log);
 
-      // Validate config and log any issues
-      const { valid, errors: configErrors, warnings: configWarnings } = validateConfig(raw);
-      if (log && log.warn) {
-        if (!valid) {
-          log.warn('config', 'Config validation errors', { errors: configErrors });
-        }
-        for (const w of configWarnings) {
-          log.warn('config', w);
-        }
-      }
-
-      applyRawConfig(raw);
+    if (raw && Object.keys(raw).length > 0) {
+      validateAndLogConfig(raw, log);
+      applyConfigFields(raw);
     }
   } catch (e) {
     if (log && log.error) {
@@ -80,4 +88,5 @@ module.exports = {
   loadSiteConfig,
   buildDomain,
   buildServiceUrl,
+  CURRENT_VERSION
 };