Fix recovery codes being unreadable (light-on-light) when OS is in light mode but app theme is dark (v0.11.120)

README.md

@@ -12,7 +12,7 @@
     <img alt="Docker" src="https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white">
     <img alt="Architectures" src="https://img.shields.io/badge/platform-amd64%20%7C%20arm64-5965F2">
     <img alt="Caddy" src="https://img.shields.io/badge/powered%20by-Caddy-1F88C0">
-    <img alt="Version" src="https://img.shields.io/badge/version-0.11.101-62E6A7">
+    <img alt="Version" src="https://img.shields.io/badge/version-0.11.118-62E6A7">
   </p>
   <p>
     <a href="#why-site-gateway">Why Site Gateway</a> ·
@@ -42,7 +42,7 @@ It's intentionally narrower than a general-purpose proxy manager. You describe *
 - **Automatic HTTPS** — Caddy issues and renews public certificates; internal, HTTP-only, and uploaded custom-certificate modes are also supported.
 - **Live dashboard** — gateway/HTTP/HTTPS/storage health, hosted and proxy counts, certificate status, throughput, uptime, memory, disk, and version info at a glance.
 - **Access Lists** — reusable login/network policies combining accounts, groups, and IP/CIDR rules across any host.
-- **Two-factor authentication** — TOTP-based MFA for administrator and user accounts, with recovery codes.
+- **Two-factor authentication** — TOTP-based MFA for administrator and user accounts, with recovery codes, plus an administrator-side override to disable a locked-out user's 2FA when they've lost their authenticator and used up their recovery codes.
 - **Users, groups, and roles** — Administrator and Standard User roles, with account lifecycle controls.
 - **Backups** — configuration or complete `.sgbackup` archives, downloadable, importable, schedulable, and optionally AES-256-GCM encrypted.
 - **Certificates page** — issuer, expiration, days remaining, and renewal health for every managed and uploaded certificate.

ROADMAP.md

@@ -2,7 +2,7 @@
 
 ## Current release status
 
-`v0.11.101` is a stable, day-to-day release. The product has moved well past the original alpha creation flow described in earlier versions of this document — Hosted Sites, Proxy Hosts, Redirect Hosts, and Streaming Hosts are all implemented, along with authentication, access control, certificates, backups, and full dashboard reporting. This document reflects what's actually shipped and what's genuinely still ahead.
+`v0.11.118` is a stable, day-to-day release. The product has moved well past the original alpha creation flow described in earlier versions of this document — Hosted Sites, Proxy Hosts, Redirect Hosts, and Streaming Hosts are all implemented, along with authentication, access control, certificates, backups, and full dashboard reporting. This document reflects what's actually shipped and what's genuinely still ahead.
 
 ## Product direction
 
@@ -23,7 +23,7 @@ Site Gateway stays simpler than a general-purpose proxy manager: one dashboard,
 - Local users with Administrator and Standard User roles, account lifecycle controls (disable/archive/restore).
 - Groups, used to grant Access List membership without managing users one by one.
 - Access Lists combining accounts, groups, and IP/CIDR network rules behind a themed sign-in page.
-- Optional two-factor authentication (TOTP) with a self-service My Account view for enrolling and managing it.
+- Optional two-factor authentication (TOTP) with a self-service My Account view for enrolling and managing it, plus an administrator-side override (Administration → Users → “•••” → Disable 2FA) for a user who's locked out with no recovery codes left. Logged to the Audit log.
 - First-time setup flow that finalizes the persistent administrator account from bootstrap credentials.
 
 ### Certificates and TLS
@@ -36,9 +36,10 @@ Site Gateway stays simpler than a general-purpose proxy manager: one dashboard,
 
 - Live dashboard health for the gateway, HTTP, HTTPS, and storage, plus hosted/proxy/certificate counts and throughput.
 - System panel: uptime, memory, persistent-data size, disk space, installed app/Caddy versions, public IP.
-- Performance view with request throughput, response times, and per-route breakdowns.
+- Performance view with request throughput, response times, and per-route breakdowns — the host filter applies to the throughput table as well as the trend chart, average response times display in seconds once they pass 1000ms, and per-domain error counts open a themed breakdown by status code.
 - Rotating access and activity logs.
 - Update-available banner when a newer image is deployed.
+- A redacted support-report export exists (version, config health, certificate readiness, upstream checks, recent events) but its UI entry point is currently hidden pending a readability rewrite of the report's output format.
 
 ### Data and operations
 
@@ -49,14 +50,16 @@ Site Gateway stays simpler than a general-purpose proxy manager: one dashboard,
 ### Brand and docs
 
 - Current icon and wordmark (v0.11.99) used consistently across the login screen, sidebar, themed default pages, and this README.
-- Integrated, searchable in-app documentation covering every configurable field, including 2FA and the update-notification banner.
+- A sitewide design-token system (colors, spacing, radius, and type scale defined once and reused everywhere) underpins the interface, so new UI stays visually consistent by default.
+- Integrated, searchable in-app documentation covering every configurable field, including 2FA (self-service and the administrator override) and the update-notification banner.
+- Toast notifications are color-coded — error toasts render distinctly from success/neutral ones, using the same token-driven theming as the rest of the interface.
 - Companion marketing site with an installation guide covering Docker Compose, plain `docker run`, and Unraid.
 
 ## What's next
 
 Roughly in priority order:
 
-- **Richer certificate diagnostics** — on-demand checks that distinguish DNS, inbound port, TLS, and upstream failures per domain, plus a redacted support-report export.
+- **Richer certificate diagnostics** — on-demand checks that distinguish DNS, inbound port, TLS, and upstream failures per domain.
 - **Wildcard/DNS-challenge certificates** — selected DNS-provider integrations for domains that can't use HTTP-01 validation. Needs encrypted secret storage for provider API credentials before it ships.
 - **Browsable backup/restore history** — today a restore validates and rolls back safely, but there's no UI history of past backups beyond what's on disk.
 - **Container picker for Proxy/Streaming targets** — letting a target be selected from a list of running Docker containers instead of typed as an IP/hostname, gated behind an opt-in Docker-socket mount since it needs real access to the Engine API. Also needs a shared Docker network between Site Gateway and the target container to actually be reachable, not just discoverable.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "site-gateway",
-  "version": "0.11.102",
+  "version": "0.11.120",
   "private": true,
   "description": "Site Gateway: simple self-hosted website publishing, reverse proxying, and automatic HTTPS.",
   "type": "module",

src/public/app.js

@@ -1,11 +1,25 @@
+// ============================================================================
+// app.js -- core client application: state, API helper, theme, dashboard,
+// Hosted Sites & Proxy Hosts rendering, routing between views, dialogs (create/
+// edit/icon/user/account/MFA), and every event listener for those areas. The
+// remaining views (Streaming, Redirects, Access Lists, Administration panels)
+// live in features.js and are invoked from here via window.renderExtendedViews.
+// ============================================================================
+
+// --- Shared DOM shortcut and app state ----------------------------------------
 const $ = selector => document.querySelector(selector);
-const state = { sites: [], proxies: [], redirects: [], streams: [], accessLists: [], groups: [], backups: [], settings: null, dashboard: null, certificates: null, readiness: null, logs: null, users: [], user: null, config: null, view: "overview", loaded: false, pendingDelete: null, pendingReplace: null, editing: null, iconTarget: null, passwordTarget: null, healthTimer: null, updateCheckTimer: null, loadedVersion: null, updateAvailable: false };
+const state = { sites: [], proxies: [], redirects: [], streams: [], accessLists: [], groups: [], backups: [], settings: null, dashboard: null, certificates: null, readiness: null, logs: null, users: [], user: null, config: null, view: "overview", loaded: false, pendingDelete: null, pendingReplace: null, editing: null, iconTarget: null, passwordTarget: null, healthTimer: null, updateCheckTimer: null, loadedVersion: null, updateAvailable: false, performanceErrorBreakdowns: {} };
+
+// One-time DOM patches: move the Access List field into the create/settings
+// forms (features.js owns the Access List data, this file owns these forms).
 document.querySelector("#create-form [name=domain]")?.closest("label")?.childNodes[0] && (document.querySelector("#create-form [name=domain]").closest("label").childNodes[0].textContent = "Primary domain ");
 if (!document.querySelector("#create-form [name=accessListId]")) { const anchor = document.querySelector("#create-form [name=tls]")?.closest("label"); if (anchor) { const label = document.createElement("label"); label.innerHTML = '<span>Access List <span class="optional">Optional</span></span><select name="accessListId"><option value="">Public — no Access List</option></select><small>Protect this hosted site and all of its domains.</small>'; anchor.before(label); } }
 if (!document.querySelector("#settings-access-list")) { const anchor = document.querySelector("#settings-form [name=domain]")?.closest("label"); if (anchor) { const label = document.createElement("label"); label.innerHTML = '<span>Access List <span class="optional">Optional</span></span><select id="settings-access-list" name="accessListId"><option value="">Public — no Access List</option></select><small>Protect this route and all of its domains.</small>'; anchor.after(label); } }
 const proxyAccessLabel = document.querySelector("#proxy-form [name=accessListId]")?.closest("label"); const proxyTlsLabel = document.querySelector("#proxy-form [name=tls]")?.closest("label"); if (proxyAccessLabel && proxyTlsLabel) proxyTlsLabel.before(proxyAccessLabel);
 const settingsAccessLabel = document.querySelector("#settings-access-list")?.closest("label"); const settingsTlsLabel = document.querySelector("#settings-form [name=tls]")?.closest("label"); if (settingsAccessLabel && settingsTlsLabel) settingsTlsLabel.before(settingsAccessLabel);
 document.querySelector("#settings-advanced [name=accessListId]")?.closest("label")?.remove();
+
+// --- Theme (light/dark/system) -------------------------------------------------
 const systemTheme = window.matchMedia("(prefers-color-scheme: dark)");
 
 function applyTheme(preference) {
@@ -18,17 +32,22 @@ $("#theme-select").value = savedTheme; applyTheme(savedTheme);
 $("#theme-select").addEventListener("change", event => { localStorage.setItem("webserver-theme", event.target.value); applyTheme(event.target.value); });
 systemTheme.addEventListener("change", () => { if ($("#theme-select").value === "system") applyTheme("system"); });
 
+// --- API helper ------------------------------------------------------------------
+
 async function api(url, options = {}) {
   const response = await fetch(url, options);
   if (response.status === 401) { showLogin(); throw new Error("Please sign in again."); }
   if (!response.ok) { const body = await response.json().catch(() => ({})); throw new Error(body.error || "Request failed."); }
   return response.status === 204 ? null : response.json();
 }
+
+// --- Login/dashboard shell, toast, and small formatting helpers ------------------
 function showLogin(message = "") { state.user = null; state.users = []; state.view = "overview"; const form = $("#login-form"); form.reset(); form.elements.username.value = ""; form.elements.password.value = ""; $("#login").classList.remove("hidden"); $("#dashboard").classList.add("hidden"); $("#login-error").textContent = message; $("#mfa-login-form").reset(); $("#mfa-login-form").classList.add("hidden"); $("#login-form").classList.remove("hidden"); $("#mfa-login-error").textContent = ""; setTimeout(() => form.elements.username.focus(), 0); }
 function showDashboard() { $("#login").classList.add("hidden"); $("#dashboard").classList.remove("hidden"); }
-function toast(message) { const el = $("#toast"); el.textContent = message; el.classList.add("show"); setTimeout(() => el.classList.remove("show"), 2800); }
+function toast(message, type = "success") { const el = $("#toast"); el.textContent = message; el.classList.toggle("toast-error", type === "error"); el.classList.add("show"); setTimeout(() => el.classList.remove("show"), 2800); }
 function escapeHtml(value) { const el = document.createElement("div"); el.textContent = value ?? ""; return el.innerHTML; }
 function publicUrl(item) { return item.domain ? `${item.tls === "http" ? "http" : "https"}://${item.domain}` : `${location.protocol}//${location.hostname}:${item.port}`; }
+
 function formatBytes(value) {
   if (!Number.isFinite(value)) return "Unavailable";
   if (value < 1024) return `${value} B`;
@@ -36,15 +55,18 @@ function formatBytes(value) {
   for (let index = 1; size >= 1024 && index < units.length; index++) { size /= 1024; unit = units[index]; }
   return `${size >= 10 ? size.toFixed(0) : size.toFixed(1)} ${unit}`;
 }
+
 function formatDuration(seconds) {
   if (!Number.isFinite(seconds)) return "Unavailable";
   const days = Math.floor(seconds / 86400), hours = Math.floor(seconds % 86400 / 3600), minutes = Math.floor(seconds % 3600 / 60);
   if (days) return `${days}d ${hours}h`; if (hours) return `${hours}h ${minutes}m`; return `${minutes}m`;
 }
+
 function formatTime(value) {
   if (!value) return "Just now";
   const date = new Date(value); return Number.isNaN(date.getTime()) ? "Recently" : date.toLocaleString([], { dateStyle: "medium", timeStyle: "short" });
 }
+
 function formatRelativeTime(value) {
   if (!value) return "Just now";
   const date = new Date(value); if (Number.isNaN(date.getTime())) return "Recently";
@@ -59,19 +81,25 @@ function formatRelativeTime(value) {
   if (days < 7) return `${days} day${days === 1 ? "" : "s"} ago`;
   return formatTime(value);
 }
+
 function certificateStatusLabel(status) { return ({ healthy:"Healthy", warning:"Renewal due soon", critical:"Renewal required urgently", expired:"Expired", pending:"Awaiting Caddy / ACME certificate", mismatch:"Certificate does not cover this domain" }[status] || String(status || "Unknown")).replaceAll("-", " "); }
 function parseHeaderLines(value) { return String(value || "").split("\n").map(line => { const index = line.indexOf(":"); return index > 0 ? { name:line.slice(0,index).trim(), value:line.slice(index+1).trim() } : null; }).filter(Boolean); }
 function monitoringChecked(form, kind) { const scope = kind === "proxy" ? "#settings-advanced" : "#settings-hosted-advanced"; return Boolean(form.querySelector(`${scope} [name="healthEnabled"]`)?.checked); }
+
 // event.submitter is null on implicit form submission (e.g. pressing Enter in a field instead of
 // clicking the button), which previously crashed every save handler below on `button.disabled = true`
 // and silently dropped the whole save. Fall back to the form's actual submit button.
 function resolveSubmitter(event) { return event.submitter || event.target.querySelector('button:not([type="button"])'); }
 function scopedValue(form, scope, name, fallback = "") { return form.querySelector(`${scope} [name="${name}"]`)?.value || fallback; }
+
 // #settings-form reuses field names (healthEnabled, healthPath, accessListId, compression, etc.) between the
 // hidden site-scoped (#settings-hosted-advanced) and proxy-scoped (#settings-advanced) sections. form.elements.NAME
 // resolves to a RadioNodeList when a name is duplicated, and assigning .value/.checked to a RadioNodeList of
 // non-radio inputs silently does nothing — so every one of these fields must be read/written through its scope.
 function setScoped(form, scope, name, value) { const el = form.querySelector(`${scope} [name="${name}"]`); if (!el) return; if (el.type === "checkbox") el.checked = Boolean(value); else el.value = value; }
+
+// advancedFormBody -- reads the scoped or unscoped "advanced options" fields off
+// a create/edit form and merges them into the outgoing request body.
 function advancedFormBody(form, body, scoped) {
   // scoped = { scope, formEl } — pass this when `form` came from a shared form (like #settings-form) where
   // field names collide with another section, so every ambiguous field is read from its own scope instead of
@@ -88,6 +116,8 @@ function advancedFormBody(form, body, scoped) {
   delete body.requestHeadersText; delete body.responseHeadersText; delete body.customLocationsText;
   return body;
 }
+
+// --- Proxy/Hosted settings dialog: submit handler ---------------------------------
 // Single capture-path for monitoring settings: unchecked checkboxes must be sent as false.
 document.addEventListener("submit", async event => {
   if (event.target?.id !== "settings-form" || !state.editing) return;
@@ -112,6 +142,8 @@ document.addEventListener("submit", async event => {
   finally { button.disabled = false; }
 }, true);
 
+
+// --- Dashboard rendering ----------------------------------------------------------
 function healthCopy(group, label) {
   if (!group.total) return "Nothing configured";
   if (group.errors) return `${group.errors} ${group.errors === 1 ? label.replace(/s$/, "") : label} need attention`;
@@ -126,6 +158,7 @@ function probeCopy(service, ready, error, unconfigured = "Not configured") {
   return service.status === "ready" ? ready : error;
 }
 
+
 function renderDashboardJobs(system) { const columns = document.querySelector("#dashboard-view .dashboard-columns"), health = columns?.firstElementChild; if (!columns) return; let panel = document.querySelector("#dashboard-jobs"); if (!panel) { panel = document.createElement("section"); panel.id = "dashboard-jobs"; panel.className = "dashboard-panel dashboard-jobs-panel"; columns.insertBefore(panel, columns.children[1] || null); } if (health && health.parentElement === columns) columns.parentElement.insertBefore(health, columns); panel.innerHTML = `<div class="panel-heading"><div><p class="eyebrow">Operations</p><h2>Scheduled jobs</h2></div></div><div class="dashboard-jobs-list">${(system.jobs || []).map(job => `<div class="dashboard-list-item"><span class="status-dot ${job.enabled ? "running" : "idle"}"></span><span><strong>${escapeHtml(job.name)}</strong><small>${job.enabled ? `Active · ${escapeHtml(job.schedule)}` : "Disabled"}</small></span></div>`).join("")}</div>`; }
 function updateDashboardUptime(seconds) { const started = window.__dashboardStartedAt || (window.__dashboardStartedAt = Date.now() - Number(seconds || 0) * 1000); const target = document.querySelector("#system-uptime"); if (!target) return; const elapsed = Math.max(0, Math.floor((Date.now() - started) / 1000)); target.textContent = formatDuration(elapsed); }
 function renderDashboard() {
@@ -181,8 +214,11 @@ function renderDashboard() {
   $("#attention-list").innerHTML = data.attention.length ? data.attention.map(item => `<${item.target ? "button" : "div"} class="attention-tile ${item.target ? "issue-link" : ""}" ${item.target ? `data-issue-target="${escapeHtml(item.target)}"` : ""}><span class="status-dot error"></span><span class="attention-copy"><strong>${escapeHtml(item.name)}</strong><small>${escapeHtml(item.message)}</small></span></${item.target ? "button" : "div"}>`).join("") : '<div class="all-clear"><span class="status-dot running"></span><span>Everything looks good — no issues to review.</span></div>';
   $("#activity-list").innerHTML = data.activity.length ? data.activity.slice(0, 5).map(item => `<div class="activity-tile"><span class="activity-mark ${item.status === "error" ? "bad" : item.status === "warning" ? "warn" : ""}">${item.status === "error" || item.status === "warning" ? "!" : "✓"}</span><span class="activity-copy"><strong>${escapeHtml(item.message)}</strong><small title="${escapeHtml(formatTime(item.at))}">${escapeHtml(formatRelativeTime(item.at))}</small></span></div>`).join("") : '<p class="quiet-state">No recent activity.</p>';
 }
+
 setInterval(() => { if (!document.querySelector("#dashboard-view.hidden")) updateDashboardUptime(); }, 1000);
 
+
+// --- Card rendering helpers (icons, permissions) -----------------------------------
 function initials(name) {
   const words = String(name || "").trim().split(/\s+/).map(word => word.replace(/[^a-z0-9]/gi, "")).filter(Boolean);
   if (!words.length) return "??";
@@ -193,6 +229,8 @@ document.addEventListener('error', event => { const image = event.target; if (!(
 function canManage() { return ["administrator", "standard"].includes(state.user?.role); }
 function canAdmin() { return state.user?.role === "administrator"; }
 
+
+// --- Hosted Sites & Proxy Hosts: card templates ------------------------------------
 function hostedCard(site) {
   const status = site.status === "running" ? "running" : site.status === "error" ? "error" : "disabled";
   const upstream = !site.enabled || site.upstream?.status === "unmonitored" ? "Monitoring paused" : !site.upstream || site.upstream.status === "pending" ? "Upstream check pending" : site.upstream.status === "healthy" ? `Upstream ${site.upstream.httpStatus} · ${site.upstream.responseMs} ms` : `Upstream unavailable · ${escapeHtml(site.upstream.error || "check failed")}`;
@@ -209,6 +247,8 @@ function proxyCard(proxy) {
   return `<article class="site-card proxy" data-id="${proxy.id}" data-kind="proxy"><div class="card-top"><div class="site-icon">${iconMarkup(proxy)}</div>${menu}</div><h2>${escapeHtml(proxy.name)}</h2><p class="address">${escapeHtml(proxy.target)}</p><p class="gateway-address ${proxy.tls !== "http" ? "secure" : ""}">${escapeHtml(publicUrl(proxy))}</p><p class="upstream-copy ${proxy.upstream?.status === "unhealthy" ? "bad" : ""}">${upstream}</p><p class="access-summary">${escapeHtml(access)}</p><div class="card-footer"><span class="status-pill"><span class="status-dot ${status}"></span>${status === "error" ? "Needs attention" : status[0].toUpperCase() + status.slice(1)}</span><div class="card-actions">${toggle}<a class="launch" href="${publicUrl(proxy)}" target="_blank" rel="noopener" aria-label="Open ${escapeHtml(proxy.name)}">↗</a></div></div></article>`;
 }
 
+
+// --- Certificates view --------------------------------------------------------------
 function renderCertificates() {
   const data = state.certificates; if (!data) return;
   $("#certificate-count").textContent = data.summary.total;
@@ -219,6 +259,8 @@ function renderCertificates() {
   renderReadiness();
 }
 
+
+// --- Domain readiness (used inside the Certificates view) ---------------------------
 function renderReadiness() {
   const routes = state.readiness?.routes || [];
   $("#readiness-list").innerHTML = routes.length ? routes.map(item => {
@@ -232,6 +274,8 @@ function renderReadiness() {
   }).join("") : '<p class="quiet-state">No configured domains to check.</p>';
 }
 
+
+// --- Logs view -------------------------------------------------------------------------
 function renderLogs() {
   const data = state.logs; if (!data) return;
   const selected = $("#log-host").value; $("#log-host").innerHTML = '<option value="">All domains</option>' + data.hosts.map(host => `<option value="${escapeHtml(host)}">${escapeHtml(host)}</option>`).join(""); $("#log-host").value = selected;
@@ -245,6 +289,9 @@ function renderLogs() {
   $("#gateway-log-list").innerHTML = activity.length ? activity.map(item => { const eventCategory = categoryOf(item.message); const indicatorClass = item.status === "error" ? "disabled" : item.status === "warning" ? "error" : "running"; return `<div class="event-row"><span class="status-dot ${indicatorClass}" aria-label="${escapeHtml(item.status || "ok")}"></span><span><strong>${escapeHtml(item.message)}</strong><small>${escapeHtml(eventCategory)} · ${escapeHtml(formatTime(item.at))}</small></span></div>`; }).join("") : '<div class="gateway-empty-state"><span class="status-dot"></span><strong>No matching gateway events</strong><small>Try a different severity or category filter.</small></div>';
 }
 
+
+// --- Performance view: summary, request trend chart (hand-drawn SVG sparkline),
+//     and the per-domain throughput table -----------------------------------------------
 function renderPerformance() {
   const data = state.performance; if (!data) return;
   const selected = $("#performance-host").value;
@@ -290,12 +337,16 @@ function renderPerformance() {
   $("#performance-sparkline").setAttribute("viewBox", `0 0 ${width} ${height}`);
   $("#performance-sparkline").innerHTML = points.length ? `${gridLines}<path d="${areaPath}" fill="var(--green)" opacity="0.12" stroke="none" /><path d="${smoothLine}" fill="none" stroke="var(--green)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />` : "";
   if (!points.length) $("#performance-sparkline-labels").innerHTML = '<span class="axis-label" style="left:0;width:100%;top:45%;text-align:center">No request data for this window yet.</span>';
-  const routes = data.routes || [];
+  const routes = (data.routes || []).filter(route => !selected || route.host === selected);
-  const countCell = (count, errors, breakdown) => { const title = breakdown?.length ? ` title="${escapeHtml(breakdown.map(item => `${item.status}: ${item.count.toLocaleString()}`).join(" · "))}"` : ""; return `${count.toLocaleString()}${errors ? ` <span class="count-divider">·</span> <span class="http-status bad"${title}>${errors.toLocaleString()}</span>` : ""}`; };
+  state.performanceErrorBreakdowns = {};
-  $("#performance-rows").innerHTML = routes.length ? routes.map(route => `<tr class="${selected && route.host === selected ? "row-highlight" : ""}"><td title="${escapeHtml(route.host)}">${escapeHtml(route.host)}</td><td>${countCell(route.hourRequests, route.hourErrors)}</td><td>${countCell(route.dayRequests, route.dayErrors, route.errorBreakdown)}</td><td>${route.dayAvgMs == null ? "—" : `${route.dayAvgMs} ms`}</td></tr>`).join("") : '<tr><td colspan="4" class="quiet-state">No requests have been logged yet.</td></tr>';
+  const countCell = (count, errors, breakdown, host) => { if (!errors) return `${count.toLocaleString()}`; if (!breakdown?.length) return `${count.toLocaleString()} <span class="count-divider">·</span> <span class="http-status bad">${errors.toLocaleString()}</span>`; state.performanceErrorBreakdowns[host] = { total: errors, breakdown }; return `${count.toLocaleString()} <span class="count-divider">·</span> <button type="button" class="http-status bad count-link-button" data-error-host="${escapeHtml(host)}">${errors.toLocaleString()}</button>`; };
+  const formatAvgMs = ms => ms == null ? "—" : ms >= 1000 ? `${(ms / 1000).toFixed(1)} s` : `${ms} ms`;
+  $("#performance-rows").innerHTML = routes.length ? routes.map(route => `<tr class="${selected && route.host === selected ? "row-highlight" : ""}"><td title="${escapeHtml(route.host)}">${escapeHtml(route.host)}</td><td>${countCell(route.hourRequests, route.hourErrors)}</td><td>${countCell(route.dayRequests, route.dayErrors, route.errorBreakdown, route.host)}</td><td>${formatAvgMs(route.dayAvgMs)}</td></tr>`).join("") : '<tr><td colspan="4" class="quiet-state">No requests have been logged yet.</td></tr>';
   if (selected) $(`#performance-rows tr.row-highlight`)?.scrollIntoView({ block: "nearest" });
 }
 
+
+// --- Administration > Users view ---------------------------------------------------------
 function renderUsers() {
   const counts = { administrator: 0, standard: 0, viewer: 0, disabled: 0, archived: 0 };
   state.users.forEach(user => { if (user.status === "active") counts[user.role] = (counts[user.role] || 0) + 1; else if (counts[user.status] !== undefined) counts[user.status] += 1; });
@@ -308,13 +359,15 @@ function renderUsers() {
     const roleLabel = user.role === "administrator" ? "Administrator" : user.role === "viewer" ? "Viewer" : "Standard User";
     const lifecycle = user.status === "archived" ? `<button class="button secondary" data-user-action="status" data-value="active">Restore</button>` : `<button class="button secondary danger-text" data-user-action="status" data-value="archived">Archive</button>`;
     const statusToggle = user.status === "archived" ? "" : `<button class="toggle ${user.status === "active" ? "on" : ""}" data-user-action="status" data-value="${user.status === "active" ? "disabled" : "active"}" aria-label="${user.status === "active" ? "Disable" : "Enable"} ${escapeHtml(user.username)}"><span></span></button>`;
-    const menu = `<div class="menu-wrap"><button class="icon-button menu-button" type="button" aria-label="User options" aria-expanded="false">•••</button><div class="menu"><button data-user-action="icon">Change icon</button>${!isSelf ? `<button data-user-action="delete" class="danger-text">Delete</button>` : ""}</div></div>`;
+    const menu = `<div class="menu-wrap"><button class="icon-button menu-button" type="button" aria-label="User options" aria-expanded="false">•••</button><div class="menu"><button data-user-action="icon">Change icon</button>${!isSelf && user.mfaEnabled ? `<button data-user-action="mfa-disable">Disable 2FA</button>` : ""}${!isSelf ? `<button data-user-action="delete" class="danger-text">Delete</button>` : ""}</div></div>`;
     return `<article class="user-card" data-user-id="${user.id}"><div class="user-card-head"><div class="user-avatar">${escapeHtml(initials(user.displayName))}</div><div class="user-head-actions"><span class="status-pill"><span class="status-dot ${statusClass}"></span>${escapeHtml(user.status)}</span>${menu}</div></div><h2>${escapeHtml(user.displayName)}${isSelf ? ' <small>You</small>' : ""}</h2><p class="address">${escapeHtml(user.username)}</p><div class="user-meta"><span>${roleLabel}</span><span>${user.lastLoginAt ? `Last login ${escapeHtml(formatTime(user.lastLoginAt))}` : "Never signed in"}</span></div><div class="user-actions"><button class="button secondary" data-user-action="role" data-value="${roleAction}">Make ${roleAction === "administrator" ? "Administrator" : roleAction === "viewer" ? "Viewer" : "Standard"}</button><button class="button secondary" data-user-action="password">Reset password</button>${lifecycle}</div><div class="card-footer">${statusToggle}</div></article>`;
   }).join("") : '<p class="quiet-state">No users found.</p>';
   document.querySelectorAll("#user-list .user-card").forEach(card => { card.style.position = "relative"; card.style.minHeight = "250px"; card.style.paddingBottom = "64px"; const head = card.querySelector(".user-card-head"), status = head?.querySelector(".status-pill"), footer = card.querySelector(".card-footer"); if (!head || !footer) return; if (status) footer.prepend(status); });
-  document.querySelectorAll("#user-list .user-card").forEach(card => { const user = state.users.find(item => item.id === card.dataset.userId); const old = card.querySelector('[data-user-action="role"]'); if (!user || !old) return; const select = document.createElement("select"); select.className = "user-role-select"; select.setAttribute("aria-label", `Role for ${user.username}`); select.innerHTML = '<option value="administrator">Administrator</option><option value="standard">Standard User</option><option value="viewer">Viewer</option>'; select.value = user.role; select.addEventListener("change", async () => { try { await api(`/api/users/${user.id}`, { method:"PATCH", headers:{"Content-Type":"application/json"}, body:JSON.stringify({ role:select.value }) }); await loadFeatureView(); toast("User role updated."); } catch (error) { select.value = user.role; toast(error.message); } }); old.replaceWith(select); });
+  document.querySelectorAll("#user-list .user-card").forEach(card => { const user = state.users.find(item => item.id === card.dataset.userId); const old = card.querySelector('[data-user-action="role"]'); if (!user || !old) return; const select = document.createElement("select"); select.className = "user-role-select"; select.setAttribute("aria-label", `Role for ${user.username}`); select.innerHTML = '<option value="administrator">Administrator</option><option value="standard">Standard User</option><option value="viewer">Viewer</option>'; select.value = user.role; select.addEventListener("change", async () => { try { await api(`/api/users/${user.id}`, { method:"PATCH", headers:{"Content-Type":"application/json"}, body:JSON.stringify({ role:select.value }) }); await loadFeatureView(); toast("User role updated."); } catch (error) { select.value = user.role; toast(error.message, "error"); } }); old.replaceWith(select); });
 }
 
+
+// --- Account panel (profile, MFA status) --------------------------------------------------
 function renderAccount() {
   if (!state.user) return;
   $("#account-display-name").textContent = state.user.displayName || "—";
@@ -328,6 +381,8 @@ function renderAccount() {
   $("#account-mfa-recovery").classList.toggle("hidden", !enabled);
 }
 
+
+// --- View routing: what data to (re)load and what to show for state.view ------------------
 async function loadFeatureView() {
   if (state.view === "certificates") { [state.certificates, state.readiness] = await Promise.all([api("/api/certificates"), api("/api/readiness")]); renderCertificates(); }
   if (state.view === "logs") { state.logs = await api(`/api/logs?host=${encodeURIComponent($("#log-host").value)}`); renderLogs(); }
@@ -336,6 +391,9 @@ async function loadFeatureView() {
   if (["redirects","access","documentation"].includes(state.view)) window.renderExtendedViews?.();
   restoreAdminTab();
 }
+// render() -- the main view switcher. Shows/hides each top-level section based on
+// state.view, and for the Hosted/Proxy "management" view, renders the card grid,
+// empty state, and summary indicator bar directly.
 function render() {
   const viewHash = state.view === "administration" ? `administration/${state.adminTab || "users"}` : state.view;
   if (location.hash !== `#${viewHash}`) history.pushState(null, "", `${location.pathname}${location.search}#${viewHash}`);
@@ -357,7 +415,7 @@ function render() {
     return;
   }
   if (!management) {
-    const headings = { certificates:["Certificates","Expiration, issuer, and certificate-detection status for automatic HTTPS."], logs:["Access Logs & Gateway Events","Recent requests, upstream responses, and gateway health events served through Caddy."], performance:["Performance","Live and historical request throughput across your gateway."], administration:["Administration","Users, gateway defaults, backups, security, and updates."], streaming:["Streaming hosts","Forward raw TCP/UDP traffic on a specific port straight to another host and port."], redirects:["Redirect hosts","Send domains to a new destination with clear, predictable rules."], access:["Access Lists","Create reusable network and login protection for your hosts."], documentation:["Documentation","Plain-language guidance and real-world Site Gateway examples."], account:["My Account","Manage your profile, password, and two-factor authentication."] };
+    const headings = { certificates:["Certificates","Expiration, issuer, and certificate-detection status for automatic HTTPS."], logs:["Access Logs & Gateway Events","Recent requests, upstream responses, and gateway health events served through Caddy."], performance:["Performance","Live and historical request throughput across your gateway."], administration:["Administration","Users, gateway defaults, backups, and updates."], streaming:["Streaming hosts","Forward raw TCP/UDP traffic on a specific port straight to another host and port."], redirects:["Redirect hosts","Send domains to a new destination with clear, predictable rules."], access:["Access Lists","Create reusable network and login protection for your hosts."], documentation:["Documentation","Plain-language guidance and real-world Site Gateway examples."], account:["My Account","Manage your profile, password, and two-factor authentication."] };
     const heading = headings[state.view] || ["Site Gateway",""]; $("#page-title").textContent = heading[0]; $("#page-subtitle").textContent = heading[1];
     $("#open-create").textContent = state.view === "administration" ? "＋ Create user" : state.view === "streaming" ? "＋ New streaming host" : state.view === "redirects" ? "＋ New redirect host" : state.view === "access" ? "＋ New Access List" : $("#open-create").textContent;
     if (state.view === "streaming") $("#stream-empty").classList.toggle("hidden", !state.loaded || state.streams.length > 0);
@@ -386,6 +444,8 @@ function render() {
   $("#running-label").textContent = running ? "Running" : "None running"; $("#disabled-label").textContent = disabled ? "Disabled" : "None disabled"; $("#error-label").textContent = errors ? "Needs attention" : "No issues";
   $("#running-dot").className = `status-dot ${running ? "running" : "inactive"}`; $("#disabled-dot").className = `status-dot ${disabled ? "disabled" : "inactive"}`; $("#error-dot").className = `status-dot ${errors ? "error" : "inactive"}`;
 }
+
+// --- Data refresh helpers ------------------------------------------------------------------
 async function refresh() { const requests = [api("/api/sites"), api("/api/proxies"), api("/api/redirects"), api("/api/streams"), api("/api/access-lists"), canAdmin() ? api("/api/groups") : Promise.resolve([]), api("/api/dashboard"), api("/api/certificates")]; const results = await Promise.allSettled(requests); results.forEach((result, index) => { if (result.status !== "fulfilled") return; const keys = ["sites", "proxies", "redirects", "streams", "accessLists", "groups", "dashboard", "certificates"]; state[keys[index]] = result.value; }); state.loaded = true; render(); window.renderExtendedViews?.(); const pending = state.proxies.filter(proxy => proxy.enabled !== false && !proxy.upstream).map(proxy => proxy.id); if (pending.length && !state.pendingProxyRefresh) { state.pendingProxyRefresh = true; refreshPendingProxies(pending).finally(() => { state.pendingProxyRefresh = false; }); } }
 async function refreshPendingProxies(ids = []) {
   const pending = new Set(ids.map(String));
@@ -401,6 +461,8 @@ async function refreshDashboard() {
   try { state.dashboard = await api("/api/dashboard"); renderDashboard(); }
   finally { button.disabled = false; button.classList.remove("spinning"); }
 }
+
+// --- Boot: session check, initial routing, periodic health/update checks -------------------
 function restoreAdminTab() { if (state.view === "administration") document.querySelector(`[data-admin-tab="${state.adminTab || "users"}"]`)?.click(); }
 async function boot() {
   const requestedHash = location.hash.slice(1); state.adminTab = requestedHash.startsWith("administration/") ? requestedHash.split("/")[1] || "users" : "users"; if (requestedHash.startsWith("administration/")) history.replaceState(null, "", `${location.pathname}${location.search}#administration`);
@@ -414,36 +476,54 @@ async function boot() {
   if (!state.loadedVersion) state.loadedVersion = state.config.version;
   $("#port-range").textContent = `${state.config.minPort}–${state.config.maxPort}`; $("#port-help").textContent = `Direct LAN access range: ${state.config.minPort}–${state.config.maxPort}`;
   $("#create-form [name=port]").min = state.config.minPort; $("#create-form [name=port]").max = state.config.maxPort; await refresh(); if (state.view !== "overview") await loadFeatureView();
-  if (!state.healthTimer) state.healthTimer = setInterval(() => { if (state.view === "overview" && !$("#dashboard").classList.contains("hidden")) refreshDashboard().catch(error => toast(error.message)); }, 30000);
+  if (!state.healthTimer) state.healthTimer = setInterval(() => { if (state.view === "overview" && !$("#dashboard").classList.contains("hidden")) refreshDashboard().catch(error => toast(error.message, "error")); }, 30000);
   if (!state.updateCheckTimer) state.updateCheckTimer = setInterval(() => { if (!$("#dashboard").classList.contains("hidden")) checkForUpdate().catch(() => {}); }, 60000);
 }
+
 async function checkForUpdate() {
   if (state.updateAvailable || !state.loadedVersion) return;
   const config = await api("/api/config");
   if (config.version && config.version !== state.loadedVersion) { state.updateAvailable = true; $("#update-banner").classList.remove("hidden"); }
 }
+
+// --- Update-available banner --------------------------------------------------------------
 $("#update-banner-refresh").addEventListener("click", () => location.reload());
 $("#update-banner-dismiss").addEventListener("click", () => { $("#update-banner").classList.add("hidden"); state.updateAvailable = false; });
 
+
+// --- Login, MFA login, first-run setup, and logout -----------------------------------------
 $("#login-form").addEventListener("submit", async event => { event.preventDefault(); $("#login-error").textContent = ""; try { const result = await api("/api/login", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(Object.fromEntries(new FormData(event.target))) }); if (result?.mfaRequired) { $("#login-form").classList.add("hidden"); $("#mfa-login-form").classList.remove("hidden"); $("#mfa-login-form [name=code]").focus(); return; } event.target.reset(); history.replaceState(null, "", `${location.pathname}${location.search}`); await boot(); } catch (error) { $("#login-error").textContent = error.message; } });
 $("#mfa-login-form").addEventListener("submit", async event => { event.preventDefault(); $("#mfa-login-error").textContent = ""; try { const response = await fetch("/api/login/mfa", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(Object.fromEntries(new FormData(event.target))) }); const body = await response.json().catch(() => ({})); if (!response.ok) throw new Error(body.error || "That code didn't match. Try again."); event.target.reset(); history.replaceState(null, "", `${location.pathname}${location.search}`); await boot(); } catch (error) { $("#mfa-login-error").textContent = error.message; } });
 $("#mfa-login-cancel").addEventListener("click", () => { $("#mfa-login-form").reset(); $("#mfa-login-error").textContent = ""; $("#mfa-login-form").classList.add("hidden"); $("#login-form").classList.remove("hidden"); $("#login-form").elements.password.value = ""; setTimeout(() => $("#login-form").elements.password.focus(), 0); });
 $("#setup-form").addEventListener("submit", async event => { event.preventDefault(); $("#setup-error").textContent = ""; try { await api("/api/setup/admin", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(Object.fromEntries(new FormData(event.target))) }); $("#setup-dialog").close(); event.target.reset(); await boot(); showLogin("Administrator account saved. Sign in with your finalized credentials."); } catch (error) { $("#setup-error").textContent = error.message; } });
 $("#setup-dialog").addEventListener("cancel", event => event.preventDefault());
 $("#logout").addEventListener("click", async () => { await fetch("/api/logout", { method: "POST" }); showLogin(); });
-$("#check-health").addEventListener("click", async event => { const button = event.currentTarget; button.disabled = true; button.textContent = "Checking…"; try { const result = await api("/api/health/check", { method:"POST" }); state.dashboard = result.dashboard; state.certificates = result.certificates; state.readiness = { routes:result.readiness }; renderCertificates(); toast("Certificate and domain checks completed."); } catch (error) { toast(error.message); } finally { button.disabled = false; button.textContent = "Run certificate check"; } });
+
-$("#download-support").addEventListener("click", () => { location.href = "/api/support-report"; });
+// --- Dashboard actions: run certificate check, download support report, jump to
-$("#attention-list").addEventListener("click", event => { const target = event.target.closest("[data-issue-target]")?.dataset.issueTarget; if (target) { state.view = target; render(); loadFeatureView().catch(error => toast(error.message)); } });
+//     an attention item's view -------------------------------------------------------------
+$("#check-health").addEventListener("click", async event => { const button = event.currentTarget; button.disabled = true; button.textContent = "Checking…"; try { const result = await api("/api/health/check", { method:"POST" }); state.dashboard = result.dashboard; state.certificates = result.certificates; state.readiness = { routes:result.readiness }; renderCertificates(); toast("Certificate and domain checks completed."); } catch (error) { toast(error.message, "error"); } finally { button.disabled = false; button.textContent = "Run certificate check"; } });
+$("#download-support")?.addEventListener("click", () => { location.href = "/api/support-report"; });
+$("#attention-list").addEventListener("click", event => { const target = event.target.closest("[data-issue-target]")?.dataset.issueTarget; if (target) { state.view = target; render(); loadFeatureView().catch(error => toast(error.message, "error")); } });
+
+// --- Primary navigation (sidebar view switching) -------------------------------------------
 function closeMenus() { document.querySelectorAll(".menu-open").forEach(card => { card.classList.remove("menu-open"); card.querySelector(".menu-button")?.setAttribute("aria-expanded", "false"); }); }
-document.querySelectorAll("nav, .aside-utilities, .brand").forEach(nav => nav.addEventListener("click", event => { const button = event.target.closest("[data-view]"); if (button) { closeMenus(); state.view = button.dataset.view; render(); loadFeatureView().catch(error => toast(error.message)); } }));
+document.querySelectorAll("nav, .aside-utilities, .brand").forEach(nav => nav.addEventListener("click", event => { const button = event.target.closest("[data-view]"); if (button) { closeMenus(); state.view = button.dataset.view; render(); loadFeatureView().catch(error => toast(error.message, "error")); } }));
-$("#dashboard-view").addEventListener("click", event => { const target = event.target.closest("[data-target], [data-view]"); if (!target) return; state.view = target.dataset.target || target.dataset.view; render(); loadFeatureView().catch(error => toast(error.message)); });
+$("#dashboard-view").addEventListener("click", event => { const target = event.target.closest("[data-target], [data-view]"); if (!target) return; state.view = target.dataset.target || target.dataset.view; render(); loadFeatureView().catch(error => toast(error.message, "error")); });
-$("#refresh-logs").addEventListener("click", () => loadFeatureView().catch(error => toast(error.message)));
+
-$("#log-host").addEventListener("change", () => loadFeatureView().catch(error => toast(error.message)));
+// --- Logs & Performance filter controls -----------------------------------------------------
-$("#performance-host").addEventListener("change", () => loadFeatureView().catch(error => toast(error.message)));
+$("#refresh-logs").addEventListener("click", () => loadFeatureView().catch(error => toast(error.message, "error")));
-$("#performance-range").addEventListener("change", () => loadFeatureView().catch(error => toast(error.message)));
+$("#log-host").addEventListener("change", () => loadFeatureView().catch(error => toast(error.message, "error")));
+$("#performance-host").addEventListener("change", () => loadFeatureView().catch(error => toast(error.message, "error")));
+$("#performance-range").addEventListener("change", () => loadFeatureView().catch(error => toast(error.message, "error")));
+
+// --- Performance: themed error-breakdown popup, replacing the old hover tooltip ------------
+function showErrorBreakdown(host, total, breakdown) { let dialog = document.querySelector("#error-breakdown-dialog"); if (!dialog) { dialog = document.createElement("dialog"); dialog.id = "error-breakdown-dialog"; document.body.append(dialog); } const rows = breakdown.map(item => `<div class="error-breakdown-row"><span>${escapeHtml(item.status)}</span><span>${item.count.toLocaleString()}</span></div>`).join(""); dialog.innerHTML = `<form method="dialog" class="dialog-card compact"><div class="dialog-heading"><div><p class="eyebrow">Performance · Last 24h</p><h2>${escapeHtml(host)}</h2></div></div><p class="muted">${total.toLocaleString()} error response${total === 1 ? "" : "s"} in the last 24 hours, by status code.</p><div class="error-breakdown-list">${rows}</div><div class="dialog-actions"><button value="cancel" class="button secondary">Close</button></div></form>`; dialog.showModal(); }
+$("#performance-rows").addEventListener("click", event => { const button = event.target.closest("[data-error-host]"); if (!button) return; const entry = state.performanceErrorBreakdowns[button.dataset.errorHost]; if (!entry) return; showErrorBreakdown(button.dataset.errorHost, entry.total, entry.breakdown); });
 $("#log-status").addEventListener("change", renderLogs);
 $("#event-severity").addEventListener("change", renderLogs);
 $("#event-category").addEventListener("change", renderLogs);
+
+// --- "Create" dialog: opens the right create form/dialog for the current view --------------
 function openCreate() {
   if (state.view === "administration") { $("#user-form").reset(); $("#user-error").textContent = ""; return $("#user-dialog").showModal(); }
   if (state.view === "streaming") { $("#stream-form").reset(); delete $("#stream-form").dataset.editing; $("#stream-title").textContent = "Create a streaming host"; $("#stream-form .button.primary").textContent = "Create streaming host"; $("#stream-error").textContent = ""; return $("#stream-dialog").showModal(); }
@@ -453,15 +533,23 @@ function openCreate() {
   $("#create-form").reset(); $("#create-form").querySelectorAll("details").forEach(details => details.open = false); $("#create-error").textContent = ""; const used = new Set(state.sites.map(site => site.port)); let port = state.config.minPort; while (used.has(port)) port++; $("#create-form [name=port]").value = port; $("#create-dialog").showModal();
 }
 $("#open-create").addEventListener("click", openCreate);
+
+// --- Global dialog/menu behavior (Escape to close menus, dialog close resets state) ---------
 document.addEventListener("click", event => { if (event.target.closest(".create-trigger")) openCreate(); if (event.target.closest(".close-dialog")) event.target.closest("dialog").close(); if (!event.target.closest(".menu-wrap")) closeMenus(); });
 document.addEventListener("keydown", event => { if (event.key === "Escape") closeMenus(); });
 document.querySelectorAll("dialog").forEach(dialog => dialog.addEventListener("close", () => { closeMenus(); dialog.querySelectorAll('input[type="password"]').forEach(input => input.value = ""); }));
-$("#refresh-health").addEventListener("click", () => refreshDashboard().catch(error => toast(error.message)));
+
+// --- Hosted Sites & Proxy Hosts: create form submit handlers --------------------------------
+$("#refresh-health").addEventListener("click", () => refreshDashboard().catch(error => toast(error.message, "error")));
 $("#create-form").addEventListener("submit", async event => { event.preventDefault(); const button = resolveSubmitter(event); button.disabled = true; button.textContent = "Publishing…"; $("#create-error").textContent = ""; try { await api("/api/sites", { method: "POST", body: new FormData(event.target) }); $("#create-dialog").close(); await refresh(); toast("Hosted site created and gateway applied."); } catch (error) { $("#create-error").textContent = error.message; } finally { button.disabled = false; button.textContent = "Create & publish"; } });
 $("#proxy-form").addEventListener("submit", async event => { event.preventDefault(); const button = resolveSubmitter(event); button.disabled = true; button.textContent = "Publishing…"; $("#proxy-error").textContent = ""; const form = new FormData(event.target), certificate = form.get("certificateFile"), privateKey = form.get("privateKeyFile"), wantsCustom = form.get("tls") === "custom"; if (wantsCustom && (!certificate?.size || !privateKey?.size)) { $("#proxy-error").textContent = "Choose both the certificate and private key for Custom HTTPS."; button.disabled = false; button.textContent = "Create & publish"; return; } const body = advancedFormBody(form, Object.fromEntries(form)); delete body.certificateFile; delete body.privateKeyFile; if (wantsCustom) body.tls = "http"; try { const created = await api("/api/proxies", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }); if (wantsCustom) { const files = new FormData(); files.append("certificate", certificate); files.append("privateKey", privateKey); await api(`/api/proxies/${created.id}/certificate`, { method:"POST", body:files }); } $("#proxy-dialog").close(); await refresh(); toast(wantsCustom ? "Proxy host created with its custom certificate." : "Proxy host created. Certificate provisioning runs automatically."); } catch (error) { $("#proxy-error").textContent = error.message; } finally { button.disabled = false; button.textContent = "Create & publish"; } });
 
+
+// --- Health-check field visibility polish for the create forms ------------------------------
 function ensureHostedHealthFields() { [document.querySelector("#create-form details"), document.querySelector("#settings-hosted-advanced")].forEach(details => { if (!details || details.querySelector("[name=healthEnabled]")) return; const access = details.querySelector("[name=accessListId]")?.closest("label"); if (!access) return; access.insertAdjacentHTML("afterend", '<label>Health-check path<input name="healthPath" value="/"></label><label>Health-check method<select name="healthMethod"><option value="GET">GET — retrieve a response</option><option value="HEAD">HEAD — headers only</option></select></label><label>Expected status<input name="healthExpected" value="200-499"><small>Examples: 200, 200,204, or 200-399.</small></label><label>Timeout in seconds<input name="healthTimeoutSeconds" type="number" min="1" max="60" value="4"></label><label>Retries<input name="healthRetries" type="number" min="0" max="3" value="0"></label><label class="check-control"><input name="healthEnabled" type="checkbox" checked><span>Monitor this site</span></label>'); }); }
 setInterval(ensureHostedHealthFields, 300);
+
+// --- Hosted/Proxy edit ( "Domain & TLS" / "Edit proxy host" ) settings dialog ---------------
 function openSettings(kind, id) {
   if (kind === "hosted") kind = "site";
   const item = (kind === "proxy" ? state.proxies : state.sites).find(value => value.id === id); if (!item) return; state.editing = { kind, id }; const form = $("#settings-form"); form.reset(); form.querySelectorAll("details").forEach(details => details.open = false);
@@ -482,24 +570,33 @@ function openSettings(kind, id) {
   document.querySelector("#settings-form .custom-certificate-fields")?.classList.toggle("custom-certificate-visible", kind === "proxy" && form.elements.tls.value === "custom");
 }
 
+
+// --- Hosted/Proxy card actions: toggle / edit / delete / replace files / change icon --------
 $("#site-grid").addEventListener("click", async event => {
   const card = event.target.closest(".site-card"); if (!card) return; const action = event.target.closest("[data-action]")?.dataset.action, kind = card.dataset.kind;
   if (event.target.closest(".menu-button")) { const opening = !card.classList.contains("menu-open"); closeMenus(); card.classList.toggle("menu-open", opening); card.querySelector(".menu-button").setAttribute("aria-expanded", String(opening)); return; } if (!action) return;
   closeMenus();
-  if (action === "toggle") { const toggleButton = event.target.closest(".toggle"), wasOn = toggleButton.classList.contains("on"); toggleButton.classList.toggle("on", !wasOn); toggleButton.disabled = true; const base = kind === "proxy" ? "proxies" : "sites"; try { await api(`/api/${base}/${card.dataset.id}/toggle`, { method: "POST" }); await refresh(); toast("Status and gateway configuration updated."); } catch (error) { toggleButton.classList.toggle("on", wasOn); toggleButton.disabled = false; toast(error.message || "Could not update status."); } }
+  if (action === "toggle") { const toggleButton = event.target.closest(".toggle"), wasOn = toggleButton.classList.contains("on"); toggleButton.classList.toggle("on", !wasOn); toggleButton.disabled = true; const base = kind === "proxy" ? "proxies" : "sites"; try { await api(`/api/${base}/${card.dataset.id}/toggle`, { method: "POST" }); await refresh(); toast("Status and gateway configuration updated."); } catch (error) { toggleButton.classList.toggle("on", wasOn); toggleButton.disabled = false; toast(error.message || "Could not update status.", "error"); } }
   if (action === "settings") openSettings(kind, card.dataset.id);
   if (action === "delete") { state.pendingDelete = { kind, id: card.dataset.id }; $("#confirm-title").textContent = kind === "proxy" ? "Delete this proxy host?" : "Delete this hosted site?"; $("#confirm-copy").textContent = kind === "proxy" ? "Its domain route will be removed from the gateway." : "Its route and uploaded files will be permanently removed."; $("#confirm-dialog").showModal(); }
   if (action === "replace") { state.pendingReplace = card.dataset.id; $("#replace-files").click(); }
   if (action === "icon") openIconPicker(kind, card.dataset.id);
 });
+
+// --- Redirect card actions delegated from the site grid (menu open/close, edit/
+//     icon/delete/toggle) ---------------------------------------------------------------------
 document.querySelector("#redirect-list")?.addEventListener("click", event => {
   const card = event.target.closest(".redirect-card"); if (!card) return;
   if (event.target.closest(".menu-button")) { const opening = !card.classList.contains("menu-open"); closeMenus(); card.classList.toggle("menu-open", opening); card.querySelector(".menu-button")?.setAttribute("aria-expanded", String(opening)); return; }
   const action = event.target.closest("[data-redirect-action]")?.dataset.redirectAction; if (action === "icon") { closeMenus(); openIconPicker("redirect", card.dataset.redirectId); }
 });
-$("#confirm-dialog").addEventListener("close", async () => { if ($("#confirm-dialog").returnValue === "confirm" && state.pendingDelete) { const base = state.pendingDelete.kind === "proxy" ? "proxies" : "sites"; await api(`/api/${base}/${state.pendingDelete.id}`, { method: "DELETE" }); await refresh(); toast("Entry deleted and gateway updated."); } state.pendingDelete = null; });
-$("#replace-files").addEventListener("change", async event => { if (!event.target.files[0] || !state.pendingReplace) return; const data = new FormData(); data.append("files", event.target.files[0]); try { await api(`/api/sites/${state.pendingReplace}/files`, { method: "POST", body: data }); toast("Site files updated."); } catch (error) { toast(error.message); } event.target.value = ""; state.pendingReplace = null; });
 
+// --- Delete confirmation dialog and replace-files handler ------------------------------------
+$("#confirm-dialog").addEventListener("close", async () => { if ($("#confirm-dialog").returnValue === "confirm" && state.pendingDelete) { const base = state.pendingDelete.kind === "proxy" ? "proxies" : "sites"; await api(`/api/${base}/${state.pendingDelete.id}`, { method: "DELETE" }); await refresh(); toast("Entry deleted and gateway updated."); } state.pendingDelete = null; });
+$("#replace-files").addEventListener("change", async event => { if (!event.target.files[0] || !state.pendingReplace) return; const data = new FormData(); data.append("files", event.target.files[0]); try { await api(`/api/sites/${state.pendingReplace}/files`, { method: "POST", body: data }); toast("Site files updated."); } catch (error) { toast(error.message, "error"); } event.target.value = ""; state.pendingReplace = null; });
+
+
+// --- Icon picker dialog: search, upload, URL, and reset-to-fallback -------------------------
 function openIconPicker(kind, id) {
   state.iconTarget = { kind, id }; $("#icon-search").value = ""; $("#icon-url").value = ""; $("#icon-upload").value = ""; $("#icon-error").textContent = ""; $("#icon-results").innerHTML = '<p class="quiet-state">Enter at least two characters to search.</p>'; $("#icon-dialog").showModal(); setTimeout(() => $("#icon-search").focus(), 0);
 }
@@ -537,6 +634,8 @@ $("#save-icon-url").addEventListener("click", async () => {
   try { await api(`/api/${base}/${state.iconTarget.id}/icon`, { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ url: value }) }); $("#icon-dialog").close(); await refresh(); toast("Icon URL saved."); }
   catch (error) { $("#icon-error").textContent = error.message; }
 });
+
+// --- User management: create, edit (role/status), password reset, delete --------------------
 $("#user-form").addEventListener("submit", async event => {
   event.preventDefault(); const button = resolveSubmitter(event); button.disabled = true; $("#user-error").textContent = "";
   try {
@@ -545,6 +644,7 @@ $("#user-form").addEventListener("submit", async event => {
   } catch (error) { $("#user-error").textContent = error.message; }
   finally { button.disabled = false; }
 });
+
 function themedUserConfirm(message, title = "Confirm action") { let dialog = document.querySelector("#user-confirm-dialog"); if (!dialog) { dialog = document.createElement("dialog"); dialog.id = "user-confirm-dialog"; document.body.append(dialog); } dialog.innerHTML = `<form method="dialog" class="dialog-card compact"><div class="dialog-heading"><div><p class="eyebrow">Administration</p><h2>${escapeHtml(title)}</h2></div></div><p class="muted">${escapeHtml(message)}</p><div class="dialog-actions"><button value="cancel" class="button secondary">Cancel</button><button value="confirm" class="button danger">Confirm</button></div></form>`; dialog.showModal(); return new Promise(resolve => dialog.addEventListener("close", () => resolve(dialog.returnValue === "confirm"), { once: true })); }
 $("#user-list").addEventListener("click", async event => {
   const menuCard = event.target.closest(".user-card");
@@ -556,11 +656,18 @@ $("#user-list").addEventListener("click", async event => {
     closeMenus();
     state.passwordTarget = user.id; $("#password-form").reset(); $("#password-error").textContent = ""; $("#password-title").textContent = `Reset ${user.username} password`; $("#password-dialog").showModal(); return;
   }
+  if (button.dataset.userAction === "mfa-disable") {
+    closeMenus();
+    if (!await themedUserConfirm(`Disable two-factor authentication for “${user.username}”? They’ll be able to sign in with just their password until they set it up again.`, "Disable 2FA")) return;
+    button.disabled = true;
+    try { await api(`/api/users/${user.id}/mfa/disable`, { method: "POST" }); await loadFeatureView(); toast("Two-factor authentication disabled."); } catch (error) { toast(error.message, "error"); } finally { button.disabled = false; }
+    return;
+  }
   if (button.dataset.userAction === "delete") {
     closeMenus();
     if (!await themedUserConfirm(`Permanently delete user “${user.username}”? This cannot be undone.`, "Delete user")) return;
     button.disabled = true;
-    try { await api(`/api/users/${user.id}`, { method: "DELETE" }); await loadFeatureView(); toast("User deleted."); } catch (error) { toast(error.message); } finally { button.disabled = false; }
+    try { await api(`/api/users/${user.id}`, { method: "DELETE" }); await loadFeatureView(); toast("User deleted."); } catch (error) { toast(error.message, "error"); } finally { button.disabled = false; }
     return;
   }
   button.disabled = true;
@@ -568,9 +675,10 @@ $("#user-list").addEventListener("click", async event => {
     const body = button.dataset.userAction === "role" ? { role: button.dataset.value } : { status: button.dataset.value };
     await api(`/api/users/${user.id}`, { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
     await loadFeatureView(); toast("User updated.");
-  } catch (error) { toast(error.message); }
+  } catch (error) { toast(error.message, "error"); }
   finally { button.disabled = false; }
 });
+
 $("#password-form").addEventListener("submit", async event => {
   event.preventDefault(); const button = resolveSubmitter(event); button.disabled = true; $("#password-error").textContent = "";
   try {
@@ -579,6 +687,8 @@ $("#password-form").addEventListener("submit", async event => {
   } catch (error) { $("#password-error").textContent = error.message; }
   finally { button.disabled = false; }
 });
+
+// --- Hash-based routing: back/forward and deep links (#view or #administration/tab) ---------
 window.addEventListener("hashchange", () => {
   if (!state.user) return; // Not logged in yet; boot() handles initial routing.
   const requestedHash = location.hash.slice(1);
@@ -586,10 +696,13 @@ window.addEventListener("hashchange", () => {
   if (requestedHash.startsWith("administration/")) history.replaceState(null, "", `${location.pathname}${location.search}#administration`);
   state.view = location.hash.slice(1) || "overview";
   render();
-  loadFeatureView().catch(error => toast(error.message));
+  loadFeatureView().catch(error => toast(error.message, "error"));
 });
-boot().catch(error => toast(error.message));
 
+boot().catch(error => toast(error.message, "error"));
+
+
+// --- Proxy form: keep the upstream-TLS fields in sync with the target URL scheme ------------
 function syncUpstreamTlsControls(form) {
   if (!form || !form.elements.target) return;
   const targets = [form.elements.target.value, form.elements.upstreamsText?.value || ""].join("\n").split(/\n+/).map(value => value.trim()).filter(Boolean);
@@ -603,14 +716,22 @@ function syncUpstreamTlsControls(form) {
   const lbPolicy = form.elements.lbPolicy;
   if (lbPolicy) { const poolTargets = String(form.elements.upstreamsText?.value || "").split("\n").map(value => value.trim()).filter(Boolean); const multi = poolTargets.length > 1; lbPolicy.disabled = !multi; lbPolicy.closest("label")?.classList.toggle("control-disabled", !multi); if (!multi) lbPolicy.value = "random"; }
 }
+
 document.addEventListener("input", event => { if (event.target.matches('#proxy-form [name="target"],#proxy-form [name="upstreamsText"],#settings-form [name="target"],#settings-form [name="upstreamsText"]')) syncUpstreamTlsControls(event.target.form); });
 document.addEventListener("change", event => { if (event.target.matches('#proxy-form [name="target"],#proxy-form [name="upstreamsText"],#settings-form [name="target"],#settings-form [name="upstreamsText"]')) syncUpstreamTlsControls(event.target.form); });
 document.querySelectorAll("#proxy-form,#settings-form").forEach(form => syncUpstreamTlsControls(form));
+
+// --- Misc global click delegation (create triggers, generic [data-action] handlers) ---------
 document.addEventListener("click", event => { if (event.target.closest(".create-trigger,[data-action=edit],[data-card-action=edit]")) setTimeout(() => { syncUpstreamTlsControls(document.querySelector("#proxy-form")); syncUpstreamTlsControls(document.querySelector("#settings-form")); }, 0); });
 document.addEventListener("click", event => { const trigger = event.target.closest("[data-action=settings],[data-card-action=settings]"); if (!trigger) return; setTimeout(() => { const item = (state.editing?.kind === "proxy" ? state.proxies : state.sites).find(value => value.id === state.editing?.id); if (!item) return; const scope = state.editing.kind === "proxy" ? "#settings-advanced" : "#settings-hosted-advanced"; const checkbox = document.querySelector(`${scope} [name="healthEnabled"]`); if (checkbox) checkbox.checked = !(item.healthEnabled === false || String(item.healthEnabled).toLowerCase() === "false"); }, 0); });
+
+// --- Access Lists: periodic live refresh while that view is open ----------------------------
 setInterval(() => { if (state.view !== 'access') return; const items = state.accessLists || []; const enabled = items.filter(item => item.enabled !== false).length; const disabled = items.length - enabled; $('#running-count').textContent = enabled; $('#disabled-count').textContent = disabled; $('#error-count').textContent = 0; $('#running-label').textContent = enabled ? 'Enabled' : 'None enabled'; $('#disabled-label').textContent = disabled ? 'Disabled' : 'None disabled'; $('#error-label').textContent = 'No issues'; $('#running-dot').className = `status-dot ${enabled ? 'running' : 'inactive'}`; $('#disabled-dot').className = `status-dot ${disabled ? 'disabled' : 'inactive'}`; $('#error-dot').className = 'status-dot inactive'; $('.port-note').classList.add('hidden'); }, 500);
+
 function renderDashboardJobsSafe(system) { const slot = document.querySelector("#dashboard-jobs-slot"); if (!slot) return; let panel = document.querySelector("#dashboard-jobs"); if (!panel) { panel = document.createElement("section"); panel.id = "dashboard-jobs"; panel.className = "dashboard-panel dashboard-jobs-panel"; slot.appendChild(panel); } panel.innerHTML = `<div class="panel-heading"><div><p class="eyebrow">Operations</p><h2>Scheduled jobs</h2></div></div><div class="health-grid">${(system.jobs || []).map(job => `<div class="health-tile"><span class="status-dot ${job.enabled ? "running" : "idle"}"></span><span class="health-tile-copy"><strong>${escapeHtml(job.name)}</strong><small>${job.enabled ? `Active · ${escapeHtml(job.schedule)}` : "Disabled"}</small></span></div>`).join("")}</div>`; }
 
+
+// --- Account: change password form ------------------------------------------------------------
 $("#account-password-form").addEventListener("submit", async event => {
   event.preventDefault();
   $("#account-password-error").textContent = "";
@@ -623,6 +744,9 @@ $("#account-password-form").addEventListener("submit", async event => {
   } catch (error) { $("#account-password-error").textContent = error.message; }
 });
 
+
+// --- MFA: password re-confirmation dialog used before disabling MFA or
+//     regenerating recovery codes --------------------------------------------------------------
 let mfaPasswordResolve = null;
 function requestMfaPassword(title, heading) {
   $("#mfa-password-title").textContent = title;
@@ -641,6 +765,8 @@ $("#mfa-password-form").addEventListener("submit", event => {
 });
 $("#mfa-password-cancel").addEventListener("click", () => { $("#mfa-password-dialog").close(); mfaPasswordResolve?.(null); mfaPasswordResolve = null; });
 
+
+// --- MFA: enable / setup / confirm flow --------------------------------------------------------
 $("#account-mfa-enable").addEventListener("click", async () => {
   try {
     const result = await api("/api/account/mfa/setup", { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}" });
@@ -649,7 +775,7 @@ $("#account-mfa-enable").addEventListener("click", async () => {
     $("#mfa-setup-error").textContent = "";
     $("#mfa-setup-confirm-form").reset();
     $("#mfa-setup-dialog").showModal();
-  } catch (error) { toast(error.message); }
+  } catch (error) { toast(error.message, "error"); }
 });
 $("#mfa-setup-cancel").addEventListener("click", () => { $("#mfa-setup-dialog").close(); });
 $("#mfa-setup-confirm-form").addEventListener("submit", async event => {
@@ -662,12 +788,14 @@ $("#mfa-setup-confirm-form").addEventListener("submit", async event => {
     state.user.mfaEnabled = true;
     renderAccount();
     $("#mfa-recovery-codes").textContent = result.recoveryCodes.join("\n");
-    $("#mfa-recovery-dialog").showModal();
+    requestAnimationFrame(() => $("#mfa-recovery-dialog").showModal());
     toast("Two-factor authentication enabled.");
   } catch (error) { $("#mfa-setup-error").textContent = error.message; }
 });
 $("#mfa-recovery-done").addEventListener("click", () => { $("#mfa-recovery-dialog").close(); });
 
+
+// --- MFA: disable and regenerate recovery codes -------------------------------------------------
 $("#account-mfa-disable").addEventListener("click", async () => {
   const password = await requestMfaPassword("Disable two-factor authentication", "Confirm your password to continue");
   if (!password) return;
@@ -676,7 +804,7 @@ $("#account-mfa-disable").addEventListener("click", async () => {
     state.user.mfaEnabled = false;
     renderAccount();
     toast("Two-factor authentication disabled.");
-  } catch (error) { toast(error.message); }
+  } catch (error) { toast(error.message, "error"); }
 });
 $("#account-mfa-recovery").addEventListener("click", async () => {
   const password = await requestMfaPassword("Regenerate recovery codes", "Confirm your password to continue");
@@ -684,7 +812,7 @@ $("#account-mfa-recovery").addEventListener("click", async () => {
   try {
     const result = await api("/api/account/mfa/recovery-codes", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ password }) });
     $("#mfa-recovery-codes").textContent = result.recoveryCodes.join("\n");
-    $("#mfa-recovery-dialog").showModal();
+    requestAnimationFrame(() => $("#mfa-recovery-dialog").showModal());
     toast("Recovery codes regenerated. Your old codes no longer work.");
-  } catch (error) { toast(error.message); }
+  } catch (error) { toast(error.message, "error"); }
 });

src/server.js

@@ -69,6 +69,8 @@ const probeFailures = { gateway: 0, http: 0, https: 0 };
 let iconCatalog = null;
 let storage;
 
+
+// --- Small utility helpers (activity log, dir sizing, env parsing, passwords) -----------
 function recordActivity(message, status = "ok") {
   const entry = { message, status, at: new Date().toISOString() };
   recentActivity.unshift(entry);
@@ -121,6 +123,8 @@ function activeAdministrators() {
   return users.filter(user => user.role === "administrator" && user.status === "active");
 }
 
+
+// --- Sessions & auth cookies --------------------------------------------------------------
 function slugify(value) {
   return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48);
 }
@@ -151,6 +155,8 @@ const saveStreams = async () => storage.saveCollection("streams", streams);
 const saveAccessLists = async () => storage.saveCollection("access_lists", accessLists);
 const saveSettings = async () => storage.saveSettings(settings);
 
+
+// --- Data loading (hosted sites) and shared validation helpers -----------------------------
 async function clearDirectoryContents(directory) {
   await fsp.mkdir(directory, { recursive: true });
   let lastError = null;
@@ -214,6 +220,8 @@ async function loadSites() {
   await saveSettings();
 }
 
+
+// --- Domain / target / stream-port validation -----------------------------------------------
 function normalizeDomain(value) {
   return String(value || "").trim().toLowerCase().replace(/^https?:\/\//, "").replace(/\/$/, "");
 }
@@ -263,6 +271,8 @@ function streamPortConflict(port, exceptId) {
   return null;
 }
 
+
+// --- Header / location / custom-config sanitizing for Proxy & Hosted advanced options -------
 function cleanHeaders(value) {
   if (!Array.isArray(value)) return [];
   return value.slice(0, 30).map(item => ({ name: String(item.name || "").trim(), value: String(item.value || "").trim() }))
@@ -285,6 +295,7 @@ function cleanCustomConfig(value) {
   return config;
 }
 
+
 function applyAdvancedSettings(item, body) {
   if (body.upstreams !== undefined) {
     if (!Array.isArray(body.upstreams) || body.upstreams.length > 10) throw Object.assign(new Error("Add up to 10 upstream targets."), { status: 400 });
@@ -313,6 +324,9 @@ function applyAdvancedSettings(item, body) {
   if (body.locations !== undefined) item.locations = cleanLocations(body.locations);
 }
 
+
+// --- Caddyfile generation: turns hosted sites/proxies/redirects/streams/access lists
+//     into the actual Caddy configuration and reloads Caddy with it -------------------------
 function expectedStatusMatches(status, specification = "200-499") {
   return String(specification).split(",").some(part => {
     const value = part.trim();
@@ -383,6 +397,10 @@ function proxyBlock(target, item, indent = "  ") {
   return output;
 }
 
+
+// Writes the themed default ("no route configured") static HTML page to disk. Keep
+// this HTML in sync with the client-side preview in features.js's
+// defaultSiteThemedHtml() -- see the comment there.
 async function writeDefaultSitePage() {
   const selected = settings.defaultSite || {};
   const title = String(selected.title || (selected.mode === "welcome" ? "Gateway ready" : "Route not found")).replace(/[<>]/g, "");
@@ -393,6 +411,9 @@ async function writeDefaultSitePage() {
   await fsp.writeFile(path.join(defaultSiteDir, "index.html"), html);
 }
 
+
+// renderCaddyfile -- builds the full Caddy JSON/Caddyfile config from current state
+// (sites, proxies, redirects, streams, access lists, default site settings).
 function renderCaddyfile() {
   const email = String(process.env.ACME_EMAIL || "").trim();
   const lines = ["{", "  admin localhost:2019", "  persist_config off", `  storage file_system ${managedCertificatesDir}`];
@@ -425,6 +446,9 @@ function renderCaddyfile() {
   return `${lines.join("\n")}\n`;
 }
 
+
+// syncCaddy -- applies the generated config to the running Caddy instance and
+// records success/failure (gatewayError, lastGatewayReload) for the dashboard.
 async function syncCaddy() {
   const nextPath = `${caddyfilePath}.next`;
   const previous = await fsp.readFile(caddyfilePath, "utf8").catch(() => null);
@@ -457,6 +481,8 @@ async function syncCaddy() {
   }
 }
 
+
+// --- Status helpers & public (client-facing, secret-stripped) view builders ------------------
 function siteStatus(site) {
   if (!site.enabled) return "disabled";
   if (site.domain && gatewayError) return "error";
@@ -477,6 +503,8 @@ function publicStream(stream) {
   return { ...stream, status: stream.enabled === false ? "disabled" : activeStreams.has(stream.id) ? "running" : "error", upstream: upstreamHealth.get(stream.id) || null };
 }
 
+
+// --- Certificate inventory & domain readiness diagnostics --------------------------------------
 async function walkFiles(directory) {
   const output = [];
   for (const entry of await fsp.readdir(directory, { withFileTypes: true }).catch(error => error.code === "ENOENT" ? [] : Promise.reject(error))) {
@@ -541,6 +569,7 @@ async function pruneOrphanedCertificates(candidateDomains) {
   if (removed.size) recordActivity(`Removed stored certificate data for ${orphaned.join(", ")} (no longer in use).`);
 }
 
+
 async function domainReadiness() {
   const routes = [...sites.map(item => ({ ...item, kind: "Hosted site" })), ...proxies.map(item => ({ ...item, kind: "Proxy host" })), ...redirects.map(item => ({ ...item, kind: "Redirect host" }))].filter(item => item.enabled && item.domain).flatMap(item => normalizeDomains(item.domain, item.domains).map(domain => ({ ...item, domain })));
   const certs = await certificateInventory();
@@ -554,6 +583,8 @@ async function domainReadiness() {
   }));
 }
 
+
+// --- Upstream (proxy target) health checks ------------------------------------------------------
 async function checkProxy(proxy) {
   if (!proxy.enabled) { const result = { status: "disabled", checkedAt: new Date().toISOString(), history: [] }; upstreamHealth.set(proxy.id, result); return result; }
   if (proxy.healthEnabled === false) { const result = { status: "unmonitored", checkedAt: null, history: [] }; upstreamHealth.set(proxy.id, result); return result; }
@@ -584,6 +615,8 @@ async function checkAllProxies() {
 
 const SENSITIVE_QUERY_PARAM_PATTERNS = [/token/i, /secret/i, /password/i, /passwd/i, /auth/i, /session/i, /api[-_]?key/i, /credential/i];
 
+
+// --- Access log ingestion (tailing Caddy's access log into SQLite) ------------------------------
 function redactUri(uri) {
   const str = String(uri || "");
   const queryIndex = str.indexOf("?");
@@ -624,6 +657,8 @@ async function importAccessLogsToSqlite() {
   } catch (error) { console.warn("Could not import access logs into SQLite:", error.message); }
 }
 
+
+// --- Raw TCP probing, used for streaming-host health checks --------------------------------------
 function tcpProbe(port, timeoutMs = 1000) {
   return new Promise(resolve => {
     const socket = net.createConnection({ host: "127.0.0.1", port });
@@ -655,6 +690,8 @@ function stableProbe(name, responding) {
     : { status: "error", healthy: false, responding: false };
 }
 
+
+// --- Icon catalog (searchable dashboard-icons list) & icon caching -------------------------------
 async function loadIconCatalog() {
   if (iconCatalog) return iconCatalog;
   try {
@@ -691,6 +728,9 @@ async function cacheIcon(slug) {
   return `/site-icons/${filename}`;
 }
 
+
+// --- Dashboard snapshot: aggregates health/status across every subsystem for the
+//     Overview page and the /api/dashboard endpoint --------------------------------------------
 async function dashboardSnapshot() {
   const hosted = sites.map(publicSite);
   const proxyHosts = proxies.map(publicProxy);
@@ -757,6 +797,8 @@ async function dashboardSnapshot() {
   };
 }
 
+
+// --- Hosted site process/lifecycle control --------------------------------------------------------
 async function startSite(site) {
   if (!site.enabled || activeServers.has(site.id)) return;
   const root = path.join(sitesDir, site.id);
@@ -788,6 +830,8 @@ async function restartSite(site) {
 // Streaming hosts relay raw TCP/UDP on a specific port straight to a host:port target — no domain, no HTTP,
 // no Caddy involvement. This is the same pattern as startSite()/stopSite() above: a dedicated listener Site
 // Gateway owns directly, just for a plain socket instead of an HTTP server.
+
+// --- Streaming host process/lifecycle control -------------------------------------------------------
 async function startStream(stream) {
   if (stream.enabled === false || activeStreams.has(stream.id)) return;
   const [targetHost, targetPortRaw] = String(stream.target || "").split(":");
@@ -869,6 +913,8 @@ async function checkStream(stream) {
   return result;
 }
 
+
+// --- Upload handling (hosted site ZIP install) ------------------------------------------------------
 function validatePort(port, exceptId) {
   if (!Number.isInteger(port) || port < minPort || port > maxPort) return `Port must be between ${minPort} and ${maxPort}.`;
   if (sites.some(site => site.port === port && site.id !== exceptId)) return "That port is already assigned.";
@@ -913,6 +959,8 @@ async function installUpload(site, file) {
 
 const portableCollections = { "sites.json": () => sites, "proxies.json": () => proxies, "redirects.json": () => redirects, "streams.json": () => streams, "access-lists.json": () => accessLists, "users.json": () => users, "groups.json": () => groups, "settings.json": () => settings };
 
+
+// --- Backups: create / open / list / restore, including encryption -----------------------------------
 async function protectBackup(buffer, password) {
   if (!password) return buffer;
   const salt = crypto.randomBytes(16), iv = crypto.randomBytes(12), key = await scryptAsync(password, salt, 32), cipher = crypto.createCipheriv("aes-256-gcm", key, iv), encrypted = Buffer.concat([cipher.update(buffer), cipher.final()]);
@@ -1041,6 +1089,11 @@ const upload = multer({ dest: uploadDir, limits: { fileSize: 250 * 1024 * 1024,
 const certificateUpload = multer({ dest: uploadDir, limits: { fileSize: 5 * 1024 * 1024, files: 2 } });
 const iconUpload = multer({ dest: uploadDir, limits: { fileSize: 2 * 1024 * 1024, files: 1 } });
 app.disable("x-powered-by");
+
+// ============================================================================================
+// HTTP layer: Express app setup, auth middleware, and every /api/* route.
+// Routes below are grouped by area; see the section comments for each group.
+// ============================================================================================
 app.use(express.json());
 app.use(express.urlencoded({ extended: false }));
 app.get(["/", "/index.html"], (req, res) => {
@@ -1052,6 +1105,8 @@ app.get(["/", "/index.html"], (req, res) => {
 app.use(express.static(publicDir));
 app.use("/site-icons", express.static(iconsDir, { immutable: true, maxAge: "30d", setHeaders: res => res.setHeader("Content-Security-Policy", "default-src 'none'; style-src 'unsafe-inline'") }));
 
+
+// --- Session / login / MFA login / logout ------------------------------------------------------------
 app.get("/api/session", (req, res) => {
   const user = sessionUser(req);
   res.json({ authenticated: Boolean(user), setupRequired: Boolean(user?.setupRequired), installationSetupPending: users.some(item => item.setupRequired), user: user ? publicUser(user) : null, username: user?.username || null });
@@ -1129,6 +1184,8 @@ app.post("/api/logout", (req, res) => {
   res.setHeader("Set-Cookie", "webserver_session=; Path=/; HttpOnly; SameSite=Strict; Max-Age=0");
   res.json({ ok: true });
 });
+
+// --- Public access-check endpoint used by Caddy's forward_auth for Access Lists -----------------------
 function accessSession(req, listId) {
   const token = cookieMap(req.headers.cookie).site_gateway_access; if (!token) return null;
   const [storedList, username, expires, signature] = token.split(".");
@@ -1143,6 +1200,8 @@ app.get("/api/access-check", (req, res) => {
   const original = String(req.headers["x-forwarded-uri"] || "/"); const safeReturn = original.startsWith("/") && !original.startsWith("//") ? original : "/";
   res.redirect(302, `/_site-gateway/login?list=${encodeURIComponent(listId)}&return=${encodeURIComponent(safeReturn)}`);
 });
+
+// --- Themed login page served for Access-List-protected routes ------------------------------------------
 app.get("/_site-gateway/login", (req, res) => {
   const listId = String(req.query.list || ""), list = accessLists.find(item => item.id === listId && item.enabled !== false);
   if (!list) return res.status(404).send("Access policy not found."); const safeReturn = String(req.query.return || "/").startsWith("/") ? String(req.query.return || "/") : "/";
@@ -1157,6 +1216,8 @@ app.post("/_site-gateway/login", async (req, res, next) => {
     res.setHeader("Set-Cookie", `site_gateway_access=${value}.${sign(value)}; Path=/; HttpOnly; SameSite=Lax; Max-Age=43200${secure}`); res.redirect(303, safeReturn);
   } catch (error) { next(error); }
 });
+
+// --- First-run admin setup ---------------------------------------------------------------------------------
 app.use("/api", (req, res, next) => {
   const user = sessionUser(req);
   if (!user) return res.status(401).json({ error: "Please sign in." });
@@ -1182,8 +1243,12 @@ app.post("/api/setup/admin", async (req, res, next) => {
     res.json({ ok: true });
   } catch (error) { next(error); }
 });
+
+// --- Everything below requires an authenticated session (auth middleware applied above) --------------------
 app.use("/api", (req, res, next) => { currentAuditActor = req.user?.id || null; return req.user.setupRequired ? res.status(428).json({ error: "Complete the initial administrator setup before continuing." }) : next(); });
 app.use("/api", (req, res, next) => { if (req.path.startsWith("/account/")) return next(); if (req.method === "GET" || req.user.role === "administrator") return next(); const operational = /^\/(sites|proxies|redirects|streams|access-lists)(\/|$)/.test(req.path); if (req.user.role === "standard" && operational) return next(); return res.status(403).json({ error: "Administrator access is required for this action." }); });
+
+// --- Account: password change & MFA setup/confirm/disable/recovery-codes -----------------------------------
 app.post("/api/account/password", async (req, res, next) => {
   try {
     const currentPassword = String(req.body.currentPassword || "");
@@ -1242,6 +1307,8 @@ app.post("/api/account/mfa/recovery-codes", async (req, res, next) => {
     res.json({ ok: true, recoveryCodes: codes });
   } catch (error) { next(error); }
 });
+
+// --- Config, Users, Audit log, Groups, Access List <-> Group assignment --------------------------------------
 app.get("/api/config", (req, res) => res.json({ version: appVersion, minPort, maxPort, adminPort, storage: { engine: "sqlite", databasePath: storage.databasePath, instanceId: LOCAL_INSTANCE_ID, backupsPath: backupsDir, certificatesPath: certificatesRoot }, gateway: { enabled: true, error: gatewayError } }));
 app.get("/api/users", (req, res) => req.user.role === "administrator" ? res.json(users.map(publicUser)) : res.status(403).json({ error: "Administrator access is required." }));
 app.get("/api/audit", (req, res) => req.user.role === "administrator" ? res.json(storage.listAudit({ user: req.query.user, action: req.query.action, status: req.query.status }).map(item => ({ ...item, actor: users.find(user => user.id === item.actor_id)?.username || "System" }))) : res.status(403).json({ error: "Administrator access is required." }));
@@ -1301,6 +1368,19 @@ app.delete("/api/users/:id", async (req, res, next) => {
     res.status(204).end();
   } catch (error) { next(error); }
 });
+app.post("/api/users/:id/mfa/disable", async (req, res, next) => {
+  try {
+    if (req.user.role !== "administrator") return res.status(403).json({ error: "Administrator access is required." });
+    const user = users.find(item => item.id === req.params.id);
+    if (!user) return res.status(404).json({ error: "User not found." });
+    if (!user.mfaEnabled) return res.status(400).json({ error: "Two-factor authentication isn\u2019t enabled for this user." });
+    user.mfaEnabled = false; user.mfaSecret = null; user.mfaPendingSecret = null; user.mfaRecoveryCodes = [];
+    user.updatedAt = new Date().toISOString();
+    await saveUsers();
+    recordActivity(`Administrator “${req.user.username}” disabled two-factor authentication for “${user.username}”.`, "warning");
+    res.json({ ok: true });
+  } catch (error) { next(error); }
+});
 app.get("/api/sites", (req, res) => res.json(sites.map(publicSite)));
 app.get("/api/proxies", (req, res) => res.json(proxies.map(proxy => publicProxy(proxy, req.user.role === "administrator"))));
 app.get("/api/redirects", (req, res) => res.json(redirects));
@@ -1310,6 +1390,8 @@ app.post("/api/access-lists/:id/groups", async (req, res, next) => { try { if (r
 app.post("/api/groups", async (req, res, next) => { try { if (req.user.role !== "administrator") return res.status(403).json({ error: "Administrator access is required." }); const name = String(req.body.name || "").trim().slice(0, 80); if (!name) return res.status(400).json({ error: "Group name is required." }); if (groups.some(group => group.name.toLowerCase() === name.toLowerCase())) return res.status(409).json({ error: "That group already exists." }); const group = { id: "group-" + crypto.randomBytes(4).toString("hex"), name, enabled: true, members: [], createdAt: new Date().toISOString() }; groups.push(group); await saveGroups(); recordActivity("Group “" + name + "” created."); res.status(201).json(group); } catch (error) { next(error); } });
 app.patch("/api/groups/:id", async (req, res, next) => { try { if (req.user.role !== "administrator") return res.status(403).json({ error: "Administrator access is required." }); const group = groups.find(value => value.id === req.params.id); if (!group) return res.status(404).json({ error: "Group not found." }); if (req.body.name !== undefined) { const name = String(req.body.name || "").trim().slice(0, 80); if (!name) return res.status(400).json({ error: "Group name is required." }); group.name = name; } if (req.body.enabled !== undefined) group.enabled = Boolean(req.body.enabled); if (Array.isArray(req.body.members)) group.members = [...new Set(req.body.members)].filter(id => users.some(user => user.id === id)); await saveGroups(); recordActivity("Group “" + group.name + "” updated."); res.json(group); } catch (error) { next(error); } });
 app.delete("/api/groups/:id", async (req, res, next) => { try { if (req.user.role !== "administrator") return res.status(403).json({ error: "Administrator access is required." }); const index = groups.findIndex(value => value.id === req.params.id); if (index < 0) return res.status(404).json({ error: "Group not found." }); const [group] = groups.splice(index, 1); await saveGroups(); recordActivity("Group “" + group.name + "” deleted."); res.status(204).end(); } catch (error) { next(error); } });
+
+// --- Settings, dashboard, certificates, health checks, domain readiness ---------------------------------------
 app.get("/api/settings", (req, res) => req.user.role === "administrator" ? res.json({ ...settings, backupDirectory: backupsDir }) : res.status(403).json({ error: "Administrator access is required." }));
 app.post("/api/settings/verify-admin", async (req, res, next) => { try { if (req.user.role !== "administrator") return res.status(403).json({ error:"Administrator access is required." }); if (String(req.body.username || "").trim().toLowerCase() !== String(req.user.username || "").toLowerCase() || !await passwordMatches(String(req.body.password || ""), req.user.password)) return res.status(422).json({ error:"Administrator username or password is incorrect." }); res.json({ ok:true }); } catch (error) { next(error); } });
 app.post("/api/settings/verify-username", (req, res) => { if (req.user.role !== "administrator") return res.status(403).json({ error:"Administrator access is required." }); const username = String(req.body.username || "").trim().toLowerCase(); res.json({ valid: Boolean(username && username === String(req.user.username || "").toLowerCase()) }); });
@@ -1326,6 +1408,10 @@ app.post("/api/health/check", async (req, res, next) => {
   catch (error) { next(error); }
 });
 app.get("/api/readiness", async (req, res, next) => { try { res.json({ checkedAt: new Date().toISOString(), routes: await domainReadiness() }); } catch (error) { next(error); } });
+
+// GET /api/support-report -- generates the downloadable diagnostics report (gateway
+// health, storage integrity, every route's config, certificate status, domain
+// readiness, and recent activity) used for troubleshooting.
 app.get("/api/support-report", async (req, res, next) => {
   try {
     if (req.user.role !== "administrator") return res.status(403).json({ error: "Administrator access is required." });
@@ -1335,6 +1421,8 @@ app.get("/api/support-report", async (req, res, next) => {
     res.setHeader("Content-Disposition", `attachment; filename="site-gateway-support-${new Date().toISOString().slice(0,10)}.json"`); res.type("json").send(JSON.stringify(report, null, 2));
   } catch (error) { next(error); }
 });
+
+// --- Upstream health, Logs, and Performance (request throughput/trend) endpoints --------------------------------
 app.get("/api/upstreams", (req, res) => res.json(proxies.map(publicProxy)));
 app.post("/api/upstreams/check", async (req, res, next) => {
   try { res.json(await checkAllProxies()); }
@@ -1363,6 +1451,8 @@ app.get("/api/performance", (req, res, next) => {
     });
   } catch (error) { next(error); }
 });
+
+// --- Icon search and per-entity icon upload/URL/removal -----------------------------------------------------------
 app.get("/api/icons/search", async (req, res, next) => {
   try {
     const query = String(req.query.q || "").trim().toLowerCase().slice(0, 80);
@@ -1422,6 +1512,8 @@ app.post("/api/:kind/:id/icon", iconUpload.single("icon"), async (req, res, next
   } catch (error) { next(error); }
   finally { if (req.file?.path) await fsp.rm(req.file.path, { force: true }).catch(() => {}); }
 });
+
+// --- Hosted Sites: create / toggle / replace files / delete / edit --------------------------------------------------
 app.post("/api/sites", upload.single("files"), async (req, res, next) => {
   try {
     const name = String(req.body.name || "").trim();
@@ -1516,6 +1608,8 @@ app.patch("/api/sites/:id", async (req, res, next) => {
     res.json(publicSite(site));
   } catch (error) { next(error); }
 });
+
+// --- Proxy Hosts: create / edit / custom certificate upload / toggle / delete ---------------------------------------
 app.post("/api/proxies", async (req, res, next) => {
   try {
     const name = String(req.body.name || "").trim();
@@ -1620,6 +1714,8 @@ app.delete("/api/proxies/:id", async (req, res, next) => {
   } catch (error) { next(error); }
 });
 
+
+// --- Access Lists: create / edit / assignments / delete ------------------------------------------------------------
 app.post("/api/access-lists", async (req, res, next) => {
   try {
     const name = String(req.body.name || "").trim();
@@ -1685,6 +1781,8 @@ app.delete("/api/access-lists/:id", async (req, res, next) => {
   } catch (error) { next(error); }
 });
 
+
+// --- Redirect Hosts: create / edit / delete -------------------------------------------------------------------------
 app.post("/api/redirects", async (req, res, next) => {
   try {
     const name = String(req.body.name || "").trim(); const domain = normalizeDomain(req.body.domain); const domains = normalizeDomains(domain, req.body.domains); const target = String(req.body.target || "").trim().replace(/\/$/, "");
@@ -1713,6 +1811,8 @@ app.delete("/api/redirects/:id", async (req, res, next) => {
   try { const index = redirects.findIndex(item => item.id === req.params.id); if (index < 0) return res.status(404).json({ error: "Redirect Host not found." }); const [item] = redirects.splice(index, 1); await syncCaddy(); await pruneOrphanedCertificates(normalizeDomains(item.domain, item.domains)); await saveRedirects(); recordActivity(`Redirect Host “${item.name}” deleted.`); res.status(204).end(); } catch (error) { next(error); }
 });
 
+
+// --- Streaming Hosts: list / create / edit / toggle / delete -----------------------------------------------------------
 app.get("/api/streams", (req, res) => res.json(streams.map(publicStream)));
 app.post("/api/streams", async (req, res, next) => {
   try {
@@ -1777,6 +1877,8 @@ app.delete("/api/streams/:id", async (req, res, next) => {
   } catch (error) { next(error); }
 });
 
+
+// --- Settings (general), log retention/pruning, log download, factory reset ---------------------------------------------
 app.patch("/api/settings", async (req, res, next) => {
   try {
     if (req.body.defaultSite) {
@@ -1802,6 +1904,8 @@ app.get("/api/logs/prune/preview", (req, res, next) => { try { if (req.user.role
 app.get("/api/logs/download", async (req, res, next) => { try { if (req.user.role !== "administrator") return res.status(403).json({ error: "Administrator access is required." }); const payload = { product: "Site Gateway", generatedAt: new Date().toISOString(), access: storage.listAccessEvents(500), activity: storage.listActivity(500), audit: storage.listAudit({}) }; res.setHeader("Content-Disposition", `attachment; filename="site-gateway-logs-${new Date().toISOString().slice(0, 10)}.json"`); res.json(payload); } catch (error) { next(error); } });
 app.post("/api/settings/reset-defaults", async (req, res, next) => { try { if (req.user.role !== "administrator") return res.status(403).json({ error:"Administrator access is required." }); if (String(req.body.confirmation || "") !== "RESTORE DEFAULT") return res.status(400).json({ error:"Type RESTORE DEFAULT exactly to continue." }); if (String(req.body.username || "").trim().toLowerCase() !== String(req.user.username || "").toLowerCase() || !await passwordMatches(String(req.body.password || ""), req.user.password)) return res.status(401).json({ error:"Administrator credentials were not accepted." }); settings.defaultSite = { mode:"themed404", redirectUrl:"", redirectCode:302, preservePath:true, title:"Route not found", message:"The gateway is responding, but this address has not been configured.", customHtml:"" }; settings.backups = { enabled:false, frequency:"daily", hour:2, retention:7, type:"complete", includeLogs:false, encrypt:false, lastRunAt:null, lastStatus:null }; settings.certificateHealth = { warningDays:30, criticalDays:7, staleMinutes:10 }; await saveSettings(); recordActivity("Gateway preferences restored to defaults."); res.json({ ...settings, backupDirectory:backupsDir }); } catch (error) { next(error); } });
 app.post("/api/factory-reset", async (req, res, next) => { try { if (String(req.body.confirmation || "") !== "FACTORY RESET") return res.status(400).json({ error:"Type FACTORY RESET exactly to continue." }); if (String(req.body.username || "").toLowerCase() !== String(req.user.username || "").toLowerCase() || !await passwordMatches(String(req.body.password || ""), req.user.password)) return res.status(401).json({ error:"Administrator credentials were not accepted." }); await Promise.all([...activeServers.keys()].map(stopSite)); await Promise.all([...activeStreams.keys()].map(stopStream)); storage.close(); for (const directory of [sitesDir, uploadDir, caddyDir, iconsDir, logsDir, backupsDir, defaultSiteDir, certificatesRoot, path.join(dataDir,"database")]) await clearDirectoryContents(directory); storage = await openStorage(dataDir, backupsDir); sites = []; proxies = []; users = []; redirects = []; streams = []; accessLists = []; groups = []; settings = {}; recentActivity.splice(0); await loadSites(); await syncCaddy(); res.setHeader("Set-Cookie", "webserver_session=; Path=/; HttpOnly; SameSite=Strict; Max-Age=0"); res.status(202).json({ ok:true }); } catch (error) { next(error); } });
+
+// --- Backups: list / create / import / download / restore / delete -----------------------------------------------------
 app.use("/api/backups", (req, res, next) => req.user.role === "administrator" ? next() : res.status(403).json({ error: "Administrator access is required." }));
 app.get("/api/backups", async (req, res, next) => { try { res.json(await listBackups()); } catch (error) { next(error); } });
 app.post("/api/backups", async (req, res, next) => {
@@ -1825,8 +1929,11 @@ app.post("/api/backups/:filename/restore", async (req, res, next) => {
 app.delete("/api/backups/:filename", async (req, res, next) => {
   try { const filename = path.basename(req.params.filename); if (!filename.endsWith(".sgbackup")) return res.status(400).json({ error: "Invalid backup." }); await fsp.rm(path.join(backupsDir, filename)); recordActivity(`Backup ${filename} deleted.`); res.status(204).end(); } catch (error) { next(error); }
 });
+
 function humanizeGatewayActivityError(message) { const text = String(message || "Unexpected gateway error"); if (/upstream address scheme is HTTP but transport is configured for HTTP\+TLS/i.test(text)) return "Gateway configuration rejected: HTTP upstream cannot use HTTPS transport. Disable upstream TLS verification or change the upstream URL to HTTPS."; if (/upstream address scheme is HTTPS but transport is configured for plain HTTP/i.test(text)) return "Gateway configuration rejected: HTTPS upstream requires HTTPS transport settings. Change the upstream URL or transport setting."; if (/duplicate.*address|already.*site address/i.test(text)) return "Gateway configuration rejected: This hostname or address is already used by another host. Choose a unique hostname and port."; if (/dial tcp|no such host|lookup .* no such host|upstream.*(invalid|malformed)/i.test(text)) return "Gateway configuration rejected: The upstream address could not be reached or is invalid. Check the hostname, IP address, and port."; if (/invalid hostname|host name.*invalid|malformed.*host/i.test(text)) return "Gateway configuration rejected: The hostname is not valid. Use a valid domain name without a protocol or path."; if (/unrecognized directive|unknown directive|parsing caddyfile tokens/i.test(text)) return "Gateway configuration rejected: The gateway configuration contains an unsupported or malformed directive. Check the selected host settings."; if (/certificate|tls.*(config|handshake)|no certificate/i.test(text)) return "Gateway configuration rejected: The TLS certificate configuration is invalid or unavailable. Check the certificate, key, and HTTPS settings."; return text.replace(/^Gateway configuration was rejected:\s*/i, "Gateway configuration rejected: ").replace(/\s+Details:\s+[\s\S]*$/i, ""); }
 const GATEWAY_CONFIG_ROUTE = /^\/api\/(sites|proxies|redirects|streams|access-lists)(\/|$)/i;
+
+// --- Error handling middleware & server startup -------------------------------------------------------------------------
 app.use((error, req, res, next) => {
   console.error(error);
   const rawMessage = error.message || "Something went wrong.";
@@ -1848,6 +1955,8 @@ app.listen(adminPort, "0.0.0.0", () => {
 setTimeout(() => checkAllProxies().catch(error => console.warn("Initial upstream checks failed:", error.message)), 1500).unref();
 setInterval(() => checkAllProxies().catch(error => console.warn("Upstream checks failed:", error.message)), 60000).unref();
 
+
+// --- Scheduled jobs: automatic backups, log pruning, public IP checks, graceful shutdown ---------------------------------
 async function runScheduledBackup() {
   const schedule = settings.backups || {}; if (!schedule.enabled || Number(schedule.hour) !== new Date().getHours()) return;
   const last = schedule.lastRunAt ? new Date(schedule.lastRunAt) : null; const elapsed = last ? Date.now() - last.getTime() : Infinity;