server.js

require('dotenv').config();

const http          = require('http');
const https         = require('https');
const fs            = require('fs');
const zlib          = require('zlib');
const { AsyncLocalStorage } = require('async_hooks');
const fsp           = fs.promises;
const path          = require('path');
const os            = require('os');
const crypto        = require('crypto');
const { spawn, spawnSync } = require('child_process');

// ── Auto-build dist/ if stale or missing ────────────────────────────────────
// The package.json `prestart` hook only runs under `npm start`. Deployments
// that invoke `node server.js` directly (the systemd unit in docs/install-ubuntu.md,
// docker, a fresh clone) would otherwise serve a stale or empty dist/ — users
// see old UI even after pulling new src/. Compare the newest src/ mtime
// against the dist/app.js marker and rebuild only when needed so warm
// restarts stay fast (one stat per source file, zero subprocess).
(function ensureBuildFresh() {
  const distMarker = path.join(__dirname, 'dist', 'app.js');
  const srcDir     = path.join(__dirname, 'src');
  if (!fs.existsSync(srcDir)) return; // not a source tree (e.g. extracted dist-only build)
  let distMtime = 0;
  try { distMtime = fs.statSync(distMarker).mtimeMs; } catch { /* missing */ }
  let srcMtime = 0;
  (function walk(dir) {
    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
      const p = path.join(dir, entry.name);
      if (entry.isDirectory()) walk(p);
      else { const m = fs.statSync(p).mtimeMs; if (m > srcMtime) srcMtime = m; }
    }
  })(srcDir);
  if (distMtime > 0 && distMtime >= srcMtime) return; // already fresh
  console.log(distMtime === 0
    ? '  [build] dist/ missing — running build.js…'
    : '  [build] dist/ older than src/ — running build.js…');
  const r = spawnSync(process.execPath, [path.join(__dirname, 'build.js')], { stdio: 'inherit' });
  if (r.status !== 0) console.warn(`  [build] build.js exited with status ${r.status}; serving existing dist/ as-is`);
})();

// ── Mod extraction libraries (loaded lazily to avoid startup errors if missing) ─
// Each format has an optional dependency. We log a clear banner at startup if a
// library is missing so ops can see "RAR support disabled" before users hit a 500.
let StreamZip, Unrar, sevenZ, sevenBin;
const _missingExtractors = [];
try { StreamZip = require('node-stream-zip'); } catch { _missingExtractors.push('zip (node-stream-zip)'); }
try { Unrar    = require('node-unrar-js');   } catch { _missingExtractors.push('rar (node-unrar-js)'); }
try { sevenZ   = require('node-7z');         } catch { _missingExtractors.push('7z (node-7z)'); }
try { sevenBin = require('7zip-bin');        } catch { _missingExtractors.push('7z binary (7zip-bin)'); }
// Some npm installs (--ignore-scripts, tarball restores, or node_modules
// copied across machines) drop the +x bit on the bundled 7za binary, so
// spawn() later throws EACCES and chunked mod uploads fail with HTTP 500.
// chmod is a no-op on Windows and idempotent everywhere else.
if (sevenBin && sevenBin.path7za && process.platform !== 'win32') {
  try { fs.chmodSync(sevenBin.path7za, 0o755); } catch { /* read-only fs etc. — surfaced later at spawn time */ }
}
if (_missingExtractors.length) {
  console.warn(`  Mod extraction limited — missing: ${_missingExtractors.join(', ')}. Run "npm install" to enable.`);
}

// ── Logging ──────────────────────────────────────────────────────────────────
// Each HTTP request runs inside an AsyncLocalStorage scope holding a short
// request id, surfaced as the `X-Request-Id` response header. log.info / .warn /
// .error pick up that id automatically — no extra parameter to thread through.
// Outside a request scope (startup, sweepers, AC spawn callbacks…) the id is
// omitted and the line still gets a timestamp + level.
const _reqContext = new AsyncLocalStorage();
// Re-entrant guard. log.* feeds appendLog, which iterates SSE clients and may
// trigger a write failure that someone in the future could decide to log via
// log.warn — instant infinite loop. The flag short-circuits the inner call
// to a console-only emit, breaking the cycle without losing the message.
let _logEmitDepth = 0;
function _logEmit(level, args) {
  const ctx    = _reqContext.getStore();
  const ts     = new Date().toISOString();
  const prefix = ctx?.reqId ? `${ts} ${level} [${ctx.reqId}]` : `${ts} ${level}`;
  const stream = (level === 'ERROR' || level === 'WARN') ? console.error : console.log;
  stream(prefix, ...args);
  if (_logEmitDepth > 0) return; // mid-broadcast — don't loop back through appendLog
  // Mirror into logBuffer so the Dashboard activity card sees [UDP] events
  // and other panel-internal log lines, not just stdout from a spawned
  // BeamMP-Server child (which is empty whenever the panel adopts an existing PID).
  _logEmitDepth++;
  try {
    if (typeof appendLog === 'function') {
      const body = args.map(a => typeof a === 'string' ? a : (a && a.stack) || String(a)).join(' ');
      appendLog(`${prefix} ${body}`);
    }
  } catch {} finally { _logEmitDepth--; }
}
const log = {
  info:  (...args) => _logEmit('INFO',  args),
  warn:  (...args) => _logEmit('WARN',  args),
  error: (...args) => _logEmit('ERROR', args),
};
function newRequestId() {
  // 8 hex chars is plenty for in-process correlation — collisions are not security-relevant
  return require('crypto').randomBytes(4).toString('hex');
}

// ── Config ────────────────────────────────────────────────────────────────────
// Two BEAMMP_* env vars are the only ones a fresh install must supply:
// BEAMMP_SERVER_DIR (the directory holding BeamMP-Server + ServerConfig.toml +
// Resources/) and BEAMMP_BIN (the BeamMP-Server binary path). Everything else
// — log file, mods directory, ServerConfig.toml path — is derived from those.
function _firstExistingPath(candidates) {
  for (const p of candidates) {
    if (!p) continue;
    try { fs.accessSync(p); return p; } catch {}
  }
  return null;
}
const _DEFAULT_SERVER_ROOTS = [
  process.env.HOME && path.join(process.env.HOME, 'beammp'),
  '/srv/beammp',
  '/opt/beammp',
].filter(Boolean);
const _detectedServerRoot = _firstExistingPath(_DEFAULT_SERVER_ROOTS);
// When neither the env var nor any auto-detect candidate exists, the panel
// still needs *some* string for the BEAMMP_* constants so error messages
// mention a real-looking path. Default to ~/beammp so the user sees a path
// they recognise from .env.example, not a system path they never chose.
const _FALLBACK_SERVER_ROOT = process.env.HOME ? path.join(process.env.HOME, 'beammp') : '/opt/beammp';

const HOST         = process.env.HOST              || '127.0.0.1';
const PORT         = parseInt(process.env.PORT     || '3000', 10);

// BEAMMP_SERVER_DIR is the anchor. Other paths fall back to subdirs of it.
const BEAMMP_SERVER_DIR = process.env.BEAMMP_SERVER_DIR
  || _detectedServerRoot
  || _FALLBACK_SERVER_ROOT;
const BEAMMP_BIN        = process.env.BEAMMP_BIN
  || path.join(BEAMMP_SERVER_DIR, 'BeamMP-Server');
const BEAMMP_CFG_FILE   = process.env.BEAMMP_CFG
  || path.join(BEAMMP_SERVER_DIR, 'ServerConfig.toml');
const BEAMMP_LOG_FILE   = process.env.BEAMMP_LOG
  || path.join(__dirname, 'logs', 'beammp.log');
// BeamMP serves mods out of two parallel directories: Client/ is what the
// game's auto-download pump streams to connecting players, Server/ holds Lua
// plugins that run on the server side only.
const BEAMMP_RESOURCES_DIR        = path.join(BEAMMP_SERVER_DIR, 'Resources');
const BEAMMP_CLIENT_RESOURCES_DIR = path.join(BEAMMP_RESOURCES_DIR, 'Client');
const BEAMMP_SERVER_RESOURCES_DIR = path.join(BEAMMP_RESOURCES_DIR, 'Server');

// PanelBridge Lua plugin drop-box (tools/beammp-plugin/PanelBridge in this
// repo, installed into Resources/Server/PanelBridge on the BeamMP host).
// The plugin writes player state into state.json and reads moderation
// commands from commands.json. See docs/live-state.md.
const BEAMMP_PLUGIN_BRIDGE_DIR    = path.join(BEAMMP_SERVER_RESOURCES_DIR, 'PanelBridge');
const BEAMMP_PLUGIN_STATE_FILE    = path.join(BEAMMP_PLUGIN_BRIDGE_DIR, 'state.json');
const BEAMMP_PLUGIN_CHAT_FILE     = path.join(BEAMMP_PLUGIN_BRIDGE_DIR, 'chat.json');
const BEAMMP_PLUGIN_COMMANDS_FILE = path.join(BEAMMP_PLUGIN_BRIDGE_DIR, 'commands.json');
// Ban list published to the plugin so onPlayerAuth in main.lua can refuse
// re-connections without the panel having to babysit every join — kicks for
// players already online still go through commands.json as before. Schema is
// a JSON object keyed by ban id (matches bans.id PRIMARY KEY, which is the
// player identifier from MP.GetPlayerIdentifiers). Value carries the reason
// so the plugin can echo it back to the client as the kick message.
const BEAMMP_PLUGIN_BANS_FILE     = path.join(BEAMMP_PLUGIN_BRIDGE_DIR, 'bans.json');
// Voting bridge (PanelBridge v4). vote_config goes panel → plugin, the
// other two go plugin → panel. vote_result is one-shot — the panel deletes
// it after applying the result so the plugin doesn't try to re-trigger.
const BEAMMP_PLUGIN_VOTE_CONFIG_FILE = path.join(BEAMMP_PLUGIN_BRIDGE_DIR, 'vote_config.json');
const BEAMMP_PLUGIN_VOTE_STATE_FILE  = path.join(BEAMMP_PLUGIN_BRIDGE_DIR, 'vote_state.json');
const BEAMMP_PLUGIN_VOTE_RESULT_FILE = path.join(BEAMMP_PLUGIN_BRIDGE_DIR, 'vote_result.json');

// Vanilla maps that ship with BeamNG.drive. The internal `level` matches the
// path BeamMP-Server expects in ServerConfig.toml#Map (e.g. /levels/<x>/info.json
// — the client resolves it against its own install). Metadata here drives the
// visual catalogue on the Maps page: `theme` selects the SVG thumbnail variant
// (city/offroad/racetrack/test/derby/training), `size` is a coarse S/M/L
// indicator, and `description` gives the operator a one-line summary so they
// don't have to remember which internal name maps to which place. Source:
// official BeamMP server-maintenance docs + BeamNG documentation site.
const VANILLA_MAPS_META = [
  { id: 'gridmap_v2',             level: '/levels/gridmap_v2/info.json',             name: 'Gridmap v2',             nameEs: 'Mapa de prueba v2',                  theme: 'test',      size: 'M', description: 'Flat grid test environment with ramps, jumps and material patches.' },
  { id: 'west_coast_usa',         level: '/levels/west_coast_usa/info.json',         name: 'West Coast, USA',        nameEs: 'Costa Oeste, EE. UU.',               theme: 'city',      size: 'L', description: 'Coastal California sandbox: highway, harbour, downtown and off-road backroads.' },
  { id: 'east_coast_usa',         level: '/levels/east_coast_usa/info.json',         name: 'East Coast, USA',        nameEs: 'Costa Este, EE. UU.',                theme: 'offroad',   size: 'L', description: 'Rural New England with twisty backroads, small towns and a forested mountain pass.' },
  { id: 'italy',                  level: '/levels/italy/info.json',                  name: 'Italy',                  nameEs: 'Italia',                             theme: 'offroad',   size: 'L', description: 'Huge open Tuscan map with hill roads, vineyards, a coastal village and a circuit.' },
  { id: 'utah',                   level: '/levels/utah/info.json',                   name: 'Utah',                   nameEs: 'Utah, EE. UU.',                      theme: 'offroad',   size: 'L', description: 'High-desert canyon roads, salt flats and a small interstate stretch.' },
  { id: 'johnson_valley',         level: '/levels/johnson_valley/info.json',         name: 'Johnson Valley',         nameEs: 'Johnson Valley',                     theme: 'offroad',   size: 'L', description: 'Dry-lake-bed playground and rocky off-road trails.' },
  { id: 'jungle_rock_island',     level: '/levels/jungle_rock_island/info.json',     name: 'Jungle Rock Island',     nameEs: 'Isla Jungle Rock',                   theme: 'offroad',   size: 'M', description: 'Tropical island with jungle trails, beaches and a small airstrip.' },
  { id: 'hirochi_raceway',        level: '/levels/hirochi_raceway/info.json',        name: 'Hirochi Raceway',        nameEs: 'Pista de carreras Hirochi',          theme: 'racetrack', size: 'M', description: 'Japanese-style closed circuit with multiple layout configurations.' },
  { id: 'automation_test_track',  level: '/levels/automation_test_track/info.json',  name: 'Automation Test Track',  nameEs: 'Automation Test Track',              theme: 'racetrack', size: 'M', description: 'Manufacturer-style proving ground: oval, handling course and acceleration straight.' },
  { id: 'industrial',             level: '/levels/industrial/info.json',             name: 'Industrial Site',        nameEs: 'Polígono industrial',                theme: 'city',      size: 'M', description: 'Dense warehouse + factory district with narrow service roads and loading bays.' },
  { id: 'driver_training',        level: '/levels/driver_training/info.json',        name: 'Driver Training',        nameEs: 'Centro ETK de formación de pilotos', theme: 'training',  size: 'S', description: 'Closed asphalt pad with cones, slaloms and exercises — perfect for learning car physics.' },
  { id: 'derby',                  level: '/levels/derby/info.json',                  name: 'Derby Arenas',           nameEs: 'Circuitos de demolición',            theme: 'derby',     size: 'S', description: 'Three demolition-derby arenas (figure-8, mud, stadium).' },
  { id: 'small_island',           level: '/levels/small_island/info.json',           name: 'Small Island',           nameEs: 'Isla pequeña, EE. UU.',              theme: 'offroad',   size: 'S', description: 'Compact island with a single lap road and an off-road interior.' },
  { id: 'smallgrid',              level: '/levels/smallgrid/info.json',              name: 'Small Grid',             nameEs: 'Cuadrícula, pequeño, sencillo',      theme: 'test',      size: 'S', description: 'Minimal flat plane for low-overhead testing and prop spawning.' },
  { id: 'cliff',                  level: '/levels/cliff/info.json',                  name: 'Cliff',                  nameEs: 'Acantilado',                         theme: 'offroad',   size: 'S', description: 'Small cliffside map with a beach below and a coastal road, popular for stunts and photo runs.' },
];

const DB_PATH        = process.env.DB_PATH || path.join(__dirname, 'panel.db');
const ADMIN_TOKEN    = process.env.ADMIN_TOKEN || '';
const ROOT           = __dirname;

// Boot-time path summary. Logged once on startup so operators can verify the
// auto-detection picked sane defaults without grepping the source. Failures
// here are non-fatal — the panel boots and shows a setup banner inside the UI.
function _logBootConfig() {
  const exists = p => { try { fs.accessSync(p); return true; } catch { return false; } };
  const status = (label, p) => `    ${label.padEnd(22)} ${p || '(unset)'} ${p ? (exists(p) ? '✓' : '✗ MISSING') : ''}`;
  console.log('  BeamMP paths:');
  console.log(status('BEAMMP_SERVER_DIR', BEAMMP_SERVER_DIR));
  console.log(status('BEAMMP_BIN',        BEAMMP_BIN));
  console.log(status('BEAMMP_CFG',        BEAMMP_CFG_FILE));
  if (!process.env.BEAMMP_SERVER_DIR && _detectedServerRoot) {
    console.log(`    (auto-detected root: ${_detectedServerRoot})`);
  }
  if (!exists(BEAMMP_CFG_FILE)) {
    console.warn(`  ⚠️  ServerConfig.toml not found at ${BEAMMP_CFG_FILE}. The Config page will`);
    console.warn(`     show an error until you point BEAMMP_SERVER_DIR at the directory that holds it.`);
  }
}

// BeamMP-Server child process handle, when the panel itself spawned it. NULL
// when the panel restarted while the server was already running — in that
// case the server is "adopted" via findBeamMPPid() / pgrep on every health
// check, and kill paths SIGTERM the adopted PID directly.
let beammpChild = null;

// ── Log buffer + SSE ──────────────────────────────────────────────────────────
const LOG_MAX = 500;
let logBuffer = [];
let logSeq    = 0;
const sseClients = new Set();

function appendLog(raw) {
  if (!raw || !raw.trim()) return;
  const entry = parseLine(raw.trim(), logSeq++);
  logBuffer.push(entry);
  if (logBuffer.length > LOG_MAX) logBuffer.shift();
  const data = JSON.stringify(entry);
  // Iterate a snapshot so deleting on write-failure doesn't skip the next client
  for (const res of [...sseClients]) {
    try { res.write(`data: ${data}\n\n`); } catch { sseClients.delete(res); }
  }
}

function loadLogFileIntoBuffer() {
  try {
    fs.mkdirSync(path.dirname(BEAMMP_LOG_FILE), { recursive: true });
    const content = fs.readFileSync(BEAMMP_LOG_FILE, 'utf8');
    const lines = content.trim().split('\n').filter(Boolean).slice(-LOG_MAX);
    logBuffer = lines.map((l, i) => parseLine(l, i));
    logSeq = logBuffer.length;
  } catch {}
}

// Tail BEAMMP_LOG_FILE for new lines and push them to appendLog. BeamMP-Server
// writes its stdout/stderr directly to the file via a passed-in FD (so it
// survives a panel restart without dying of SIGPIPE on broken pipes); the
// panel reads them back via inotify + delta-read. Polling fallback covers
// edge cases where fs.watch misses events (e.g. log file truncated by the
// "Clear logs" admin action, or replaced under us by a rotator).
let _logTailPos     = 0;
let _logTailWatcher = null;
let _logTailBuffer  = '';
function startLogTail() {
  if (_logTailWatcher) return;
  try { _logTailPos = fs.statSync(BEAMMP_LOG_FILE).size; } catch { _logTailPos = 0; }

  const LINE_BUF_MAX = 8 * 1024;
  const flush = () => {
    let size;
    try { size = fs.statSync(BEAMMP_LOG_FILE).size; } catch { return; }
    if (size < _logTailPos) _logTailPos = 0;       // truncated or rotated
    if (size === _logTailPos) return;
    const len = size - _logTailPos;
    let fd;
    try { fd = fs.openSync(BEAMMP_LOG_FILE, 'r'); } catch { return; }
    const buf = Buffer.alloc(len);
    try { fs.readSync(fd, buf, 0, len, _logTailPos); }
    finally { try { fs.closeSync(fd); } catch {} }
    _logTailPos = size;
    _logTailBuffer += buf.toString('utf8');
    const parts = _logTailBuffer.split('\n');
    _logTailBuffer = parts.pop();
    for (const line of parts) appendLog(line);
    if (_logTailBuffer.length > LINE_BUF_MAX) {
      appendLog(_logTailBuffer.slice(0, LINE_BUF_MAX) + ' …(truncated)');
      _logTailBuffer = '';
    }
  };

  try { _logTailWatcher = fs.watch(BEAMMP_LOG_FILE, { persistent: false }, flush); }
  catch (e) { log.warn('[LOG] fs.watch failed, falling back to poll-only:', e.message); }
  // Safety-net poll @ 2s for environments where fs.watch under-reports
  // (some networked filesystems, log rotators that replace the inode, etc.).
  setInterval(flush, 2000).unref();
}

// Called when the admin truncates BEAMMP_LOG_FILE via /api/logs/clear so the
// tail watcher doesn't mistake the new (smaller) file for a missed write.
function resetLogTailPosition() { _logTailPos = 0; _logTailBuffer = ''; }

// ── Session store (SQLite-backed, survives server restarts) ───────────────────
const SESSION_TTL = 7 * 24 * 60 * 60 * 1000; // 7 days
const _sessionsMemory = new Map(); // fallback when DB not ready

function createSession(username, role) {
  const token = crypto.randomBytes(32).toString('hex');
  const expiresAt = Date.now() + SESSION_TTL;
  if (db) {
    try {
      db.prepare('DELETE FROM sessions WHERE expires_at < ?').run(Date.now());
      db.prepare('INSERT OR REPLACE INTO sessions (token, username, role, expires_at) VALUES (?, ?, ?, ?)').run(token, username, role, expiresAt);
    } catch { _sessionsMemory.set(token, { username, role, expiresAt }); }
  } else {
    _sessionsMemory.set(token, { username, role, expiresAt });
  }
  return token;
}

// Parse a cookie name out of the request header by exact name match (split on `=`),
// not by `startsWith('name=')` — that would also match `name_alt=…`, `name-other=…`,
// or any future cookie whose name happens to share a prefix.
function readCookie(req, name) {
  const raw = req.headers.cookie || '';
  for (const part of raw.split(';')) {
    const eq = part.indexOf('=');
    if (eq < 0) continue;
    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();
  }
  return null;
}

function getSession(req) {
  const token = readCookie(req, 'sid');
  if (!token) return null;
  if (db) {
    try {
      return db.prepare('SELECT username, role FROM sessions WHERE token = ? AND expires_at > ?').get(token, Date.now()) || null;
    } catch {}
  }
  const s = _sessionsMemory.get(token);
  if (!s) return null;
  if (Date.now() > s.expiresAt) { _sessionsMemory.delete(token); return null; }
  return s;
}

function deleteSession(token) {
  if (db) { try { db.prepare('DELETE FROM sessions WHERE token = ?').run(token); } catch {} }
  _sessionsMemory.delete(token);
}

// True when the request arrived over TLS, either directly or via a trusted proxy
// that set X-Forwarded-Proto. Browsers refuse Secure cookies on plain HTTP, so
// we only attach the flag when the connection is actually encrypted — otherwise
// dev/local installations would silently lose the cookie.
function requestIsHttps(req) {
  if (req?.connection?.encrypted) return true;
  const proto = (req?.headers?.['x-forwarded-proto'] || '').split(',')[0].trim().toLowerCase();
  return proto === 'https';
}

function sessionCookieHeader(token, isHttps) {
  return `sid=${token}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${SESSION_TTL / 1000}`
    + (isHttps ? '; Secure' : '');
}

function checkAdminAuth(req) {
  const sess = getSession(req);
  if (sess?.role === 'admin' && !userMustChangePassword(sess.username)) return true;
  if (!ADMIN_TOKEN) return false;
  const h = req.headers['x-admin-token'] || req.headers['authorization']?.replace(/^Bearer\s+/i, '') || '';
  // Constant-time compare so the header is not a timing oracle for ADMIN_TOKEN.
  // Length must match for timingSafeEqual; mismatched length is a non-secret
  // upper bound on the token, so the early return is fine.
  if (!h || h.length !== ADMIN_TOKEN.length) return false;
  try {
    return crypto.timingSafeEqual(Buffer.from(h), Buffer.from(ADMIN_TOKEN));
  } catch { return false; }
}

function checkAnyAuth(req) {
  return getSession(req);
}

function userMustChangePassword(username) {
  if (!db || !username) return false;
  try {
    const row = db.prepare('SELECT must_change_password FROM panel_users WHERE username = ?').get(username);
    return row?.must_change_password === 1;
  } catch { return false; }
}

// Canonical list of granular permissions exposed via the Usuarios card. Any
// permission referenced in route guards must appear here so the UI surfaces
// it and the defaults block above seeds a value for it.
const ROLE_PERMISSIONS = [
  'serverControl', 'serverConfig', 'mapActivate', 'whitelistManage',
  'playerModeration', 'modUpload', 'discordWebhook', 'auditView', 'dbBackup',
];

// Logical implications between permissions — declared once so the same set
// of derived grants applies everywhere the User role's permission map is
// computed (login response, admin update endpoint, route guards). Each key
// is "the permission that implies", value is the list of permissions that
// are implicitly granted too. Spares the operator from having to tick
// "Change active map" separately for a user who already has full server-
// config rights.
const PERMISSION_IMPLICATIONS = {
  serverConfig: ['mapActivate'],
};
function _applyImplications(perms) {
  for (const src of Object.keys(PERMISSION_IMPLICATIONS)) {
    if (perms[src]) for (const dst of PERMISSION_IMPLICATIONS[src]) perms[dst] = true;
  }
  return perms;
}

function getUserRolePermissions() {
  const fallback = Object.fromEntries(ROLE_PERMISSIONS.map(p => [p, false]));
  if (!db) return fallback;
  try {
    const row = db.prepare(`SELECT value FROM panel_settings WHERE key = 'role_permissions_user'`).get();
    if (!row?.value) return fallback;
    const parsed = JSON.parse(row.value);
    // Re-key against the canonical list so a stale row (older deploy that knew
    // fewer permissions) cannot accidentally grant something we just added.
    const out = {};
    for (const p of ROLE_PERMISSIONS) out[p] = !!parsed[p];
    return _applyImplications(out);
  } catch { return fallback; }
}

// Per-request permission check. Admin always passes (subject to the must-
// change-password gate, same as checkAdminAuth). Users consult the stored
// JSON for this role. Callers should follow the pattern:
//   if (!checkPermission(req, 'X')) return json(res, 403, { error: ... });
function checkPermission(req, perm) {
  const sess = getSession(req);
  if (!sess) return false;
  if (userMustChangePassword(sess.username)) return false;
  if (sess.role === 'admin') return true;
  const perms = getUserRolePermissions();
  return !!perms[perm];
}

// ── MIME ──────────────────────────────────────────────────────────────────────
const MIME = {
  '.html':        'text/html; charset=utf-8',
  '.css':         'text/css; charset=utf-8',
  '.js':          'application/javascript; charset=utf-8',
  '.jsx':         'application/javascript; charset=utf-8',
  '.json':        'application/json; charset=utf-8',
  '.webmanifest': 'application/manifest+json; charset=utf-8',
  '.svg':         'image/svg+xml',
  '.webp':        'image/webp',
  '.png':         'image/png',
  '.jpg':         'image/jpeg',
  '.ico':         'image/x-icon',
  '.woff2':       'font/woff2',
  '.woff':        'font/woff',
};

// ── Database ──────────────────────────────────────────────────────────────────
let db = null;
try {
  const Database = require('better-sqlite3');
  db = new Database(DB_PATH);
  db.pragma('journal_mode = WAL');
  db.exec(`
    CREATE TABLE IF NOT EXISTS panel_users (
      username      TEXT PRIMARY KEY,
      password_hash TEXT NOT NULL,
      salt          TEXT NOT NULL,
      role          TEXT DEFAULT 'user',
      created_at    TEXT DEFAULT (datetime('now'))
    );

    CREATE TABLE IF NOT EXISTS panel_settings (
      key   TEXT PRIMARY KEY,
      value TEXT NOT NULL
    );

    CREATE TABLE IF NOT EXISTS sessions (
      token      TEXT PRIMARY KEY,
      username   TEXT NOT NULL,
      role       TEXT NOT NULL,
      expires_at INTEGER NOT NULL
    );

    CREATE TABLE IF NOT EXISTS mod_history (
      id              INTEGER PRIMARY KEY AUTOINCREMENT,
      ok              INTEGER NOT NULL,
      filename        TEXT,
      mod_type        TEXT,
      mod_id          TEXT,
      destination     TEXT,
      files_extracted INTEGER,
      error           TEXT,
      uploaded_by     TEXT,
      uploaded_at     TEXT NOT NULL DEFAULT (datetime('now'))
    );

    CREATE TABLE IF NOT EXISTS audit_log (
      id         INTEGER PRIMARY KEY AUTOINCREMENT,
      actor      TEXT NOT NULL,
      action     TEXT NOT NULL,
      target     TEXT DEFAULT '',
      detail     TEXT DEFAULT '',
      logged_at  TEXT NOT NULL DEFAULT (datetime('now'))
    );
    CREATE INDEX IF NOT EXISTS idx_audit_logged_at ON audit_log(logged_at);

    CREATE TABLE IF NOT EXISTS login_attempts (
      ip       TEXT PRIMARY KEY,
      count    INTEGER NOT NULL,
      reset_at INTEGER NOT NULL
    );
  `);
  // ── Schema migrations ─────────────────────────────────────────────────────
  // Numbered, idempotent, recorded in schema_migrations so we know which ones
  // have run on a given DB. Each migration is a {id, sql} pair; run order is
  // ascending by id. Adding a new one means appending to the array — never
  // rewriting an older entry, otherwise existing DBs would skip your change.
  //
  // The migrations table itself uses INSERT OR IGNORE so re-running a freshly
  // initialised DB is a no-op. Failing migrations log loudly and skip the
  // record-insert so the next boot retries; an environment-specific failure
  // (CREATE UNIQUE INDEX against duplicate rows, for instance) doesn't poison
  // the chain — fix the data, restart, the migration runs again.
  db.exec(`CREATE TABLE IF NOT EXISTS schema_migrations (
    id      INTEGER PRIMARY KEY,
    name    TEXT    NOT NULL,
    applied_at TEXT NOT NULL DEFAULT (datetime('now'))
  )`);
  const MIGRATIONS = [
    { id: 1, name: 'add_must_change_password',
      sql: `ALTER TABLE panel_users ADD COLUMN must_change_password INTEGER NOT NULL DEFAULT 0` },
    { id: 2, name: 'audit_chain_prev_hash',
      sql: `ALTER TABLE audit_log ADD COLUMN prev_hash TEXT NOT NULL DEFAULT ''` },
    { id: 3, name: 'audit_chain_row_hash',
      sql: `ALTER TABLE audit_log ADD COLUMN row_hash TEXT NOT NULL DEFAULT ''` },
    { id: 4, name: 'audit_chain_version',
      sql: `ALTER TABLE audit_log ADD COLUMN chain_version INTEGER NOT NULL DEFAULT 0` },
    { id: 5, name: 'audit_compound_indices',
      sql: `CREATE INDEX IF NOT EXISTS idx_audit_actor  ON audit_log(actor);
            CREATE INDEX IF NOT EXISTS idx_audit_action ON audit_log(action);` },
    { id: 6, name: 'panel_users_totp_secret',
      sql: `ALTER TABLE panel_users ADD COLUMN totp_secret TEXT NOT NULL DEFAULT ''` },
    { id: 7, name: 'panel_users_totp_enabled',
      sql: `ALTER TABLE panel_users ADD COLUMN totp_enabled INTEGER NOT NULL DEFAULT 0` },
    { id: 8, name: 'panel_users_totp_pending',
      sql: `ALTER TABLE panel_users ADD COLUMN totp_pending TEXT NOT NULL DEFAULT ''` },
    { id: 9, name: 'bans_table',
      sql: `CREATE TABLE IF NOT EXISTS bans (
              id            TEXT PRIMARY KEY,
              name          TEXT NOT NULL DEFAULT '',
              reason        TEXT NOT NULL DEFAULT '',
              banned_by     TEXT NOT NULL DEFAULT '',
              banned_at     TEXT NOT NULL DEFAULT (datetime('now')),
              expires_at    TEXT DEFAULT NULL
            );
            CREATE INDEX IF NOT EXISTS idx_bans_expires_at ON bans(expires_at);` },
    { id: 10, name: 'player_events',
      // History of join/leave events derived from PanelBridge state.json
      // diffs. One row per transition. action ∈ ('join', 'leave'). The
      // identifiers blob carries the JSON-encoded MP.GetPlayerIdentifiers
      // table from the Lua plugin so we can show "this player connected
      // from IP X" without re-querying the running server.
      sql: `CREATE TABLE IF NOT EXISTS player_events (
              id            INTEGER PRIMARY KEY AUTOINCREMENT,
              player_id     TEXT NOT NULL,
              player_name   TEXT NOT NULL,
              action        TEXT NOT NULL,
              identifiers   TEXT NOT NULL DEFAULT '',
              event_at      TEXT NOT NULL DEFAULT (datetime('now'))
            );
            CREATE INDEX IF NOT EXISTS idx_player_events_at  ON player_events(event_at);
            CREATE INDEX IF NOT EXISTS idx_player_events_pid ON player_events(player_id);` },
    { id: 11, name: 'player_nicknames',
      // SUPERSEDED by migration 12 (players table). Kept in the chain so the
      // numbering stays monotonic on existing DBs that already applied it.
      sql: `CREATE TABLE IF NOT EXISTS player_nicknames (
              player_id  TEXT PRIMARY KEY,
              nickname   TEXT NOT NULL,
              set_by     TEXT NOT NULL DEFAULT '',
              updated_at TEXT NOT NULL DEFAULT (datetime('now'))
            );` },
    { id: 12, name: 'players',
      // Canonical one-row-per-player table, mirroring the AC fork's `players`
      // table. Populated on join by the PanelBridge event loop (UPSERT with
      // first_seen on insert, last_seen on update). The Players page and the
      // history endpoint join on this so the operator-set nickname renders
      // alongside the in-game name on both live + past lists. Backfills from
      // player_events on first apply so DBs with pre-existing history get a
      // fully populated players list immediately, without waiting for every
      // historical id to reconnect once.
      sql: `CREATE TABLE IF NOT EXISTS players (
              id         TEXT PRIMARY KEY,
              name       TEXT NOT NULL DEFAULT '',
              nickname   TEXT NOT NULL DEFAULT '',
              first_seen TEXT NOT NULL DEFAULT (datetime('now')),
              last_seen  TEXT NOT NULL DEFAULT (datetime('now'))
            );
            CREATE INDEX IF NOT EXISTS idx_players_last_seen ON players(last_seen);
            INSERT OR IGNORE INTO players (id, name, first_seen, last_seen)
              SELECT player_id, MAX(player_name), MIN(event_at), MAX(event_at)
              FROM player_events
              GROUP BY player_id;` },
    { id: 13, name: 'players_stable_id_purge',
      // Up to this migration the PanelBridge consumer was using BeamMP's
      // per-session SLOT NUMBER (0, 1, 2…) as the canonical player_id,
      // collapsing every guest that ever held slot 0 into a single row.
      // Stable IDs (now prefixed bmp:/ip:/slot:) land starting with this
      // commit, so the cleanest path is to drop the pre-fix history — it
      // can't be reattributed and keeping it just confuses the history
      // view. Stable rows survive because their player_id is no longer
      // purely numeric.
      sql: `DELETE FROM player_events WHERE player_id GLOB '[0-9]*' AND player_id NOT GLOB '*:*';
            DELETE FROM players       WHERE id        GLOB '[0-9]*' AND id        NOT GLOB '*:*';
            DELETE FROM bans          WHERE id        GLOB '[0-9]*' AND id        NOT GLOB '*:*';` },
  ];
  const _appliedRows = db.prepare('SELECT id FROM schema_migrations').all();
  const _applied = new Set(_appliedRows.map(r => r.id));
  const _recordMigration = db.prepare('INSERT OR IGNORE INTO schema_migrations (id, name) VALUES (?, ?)');
  for (const m of MIGRATIONS) {
    if (_applied.has(m.id)) continue;
    try {
      db.exec(m.sql);
      _recordMigration.run(m.id, m.name);
      console.log(`  migration ${String(m.id).padStart(3, '0')}: ${m.name} ✓`);
    } catch (e) {
      // ALTER TABLE on an existing column throws "duplicate column" — that's
      // exactly the upgrade-in-place case where the column was added by the
      // pre-migrations-runner ALTER+catch code. Record the migration as
      // applied so we don't retry next boot, but log it for visibility.
      const msg = String(e && e.message || e);
      if (/duplicate column|already exists/i.test(msg)) {
        _recordMigration.run(m.id, m.name);
        console.log(`  migration ${String(m.id).padStart(3, '0')}: ${m.name} (already present, recorded)`);
      } else {
        console.error(`  migration ${String(m.id).padStart(3, '0')} ${m.name} FAILED:`, msg);
      }
    }
  }

  // Seed default settings
  db.prepare(`INSERT OR IGNORE INTO panel_settings (key, value) VALUES ('upload_max_mb', '500')`).run();
  db.prepare(`INSERT OR IGNORE INTO panel_settings (key, value) VALUES ('lang', 'en')`).run();
  db.prepare(`INSERT OR IGNORE INTO panel_settings (key, value) VALUES ('chunked_upload', '0')`).run();
  db.prepare(`INSERT OR IGNORE INTO panel_settings (key, value) VALUES ('discord_webhook', '')`).run();
  // Public per-player profile pages reachable at /p/<guid> with a matching
  // JSON view at /api/public/players/<guid>. On by default so the feature is
  // discoverable; admins can flip it off if the server isn't meant to be
  // visible at all (e.g. development boxes behind Cloudflare Access).
  db.prepare(`INSERT OR IGNORE INTO panel_settings (key, value) VALUES ('public_profiles_enabled', '1')`).run();
  // Default permission set for the `user` role. Server control and mod upload
  // were already open to users before granular permissions shipped, so an
  // upgrade in place doesn't yank capabilities away from existing accounts.
  db.prepare(`INSERT OR IGNORE INTO panel_settings (key, value) VALUES ('role_permissions_user', ?)`)
    .run(JSON.stringify({
      serverControl:    true,
      modUpload:        true,
      serverConfig:     false,
      whitelistManage:  false,
      playerModeration: false,
      discordWebhook:   false,
      auditView:        false,
      dbBackup:         false,
    }));
  console.log('  Database ready:', DB_PATH);
} catch (e) {
  console.error('  Database init failed:', e.message);
}

// ── Auth helpers ─────────────────────────────────────────────────────────────
// Stored hash format: "scrypt$<hex>" (current) or bare hex (legacy pbkdf2).
// Legacy hashes are upgraded in-place on the next successful login.
//
// Both hash and verify must use IDENTICAL scrypt parameters; relying on Node's
// defaults to "happen to match" is brittle (if a future Node release bumps the
// defaults, every existing password silently fails to verify). Pin the cost
// explicitly in one constant and pass it to both code paths.
const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1 };
const SCRYPT_KEYLEN = 64;
function hashPasswordScrypt(password, salt) {
  return 'scrypt$' + crypto.scryptSync(password, salt, SCRYPT_KEYLEN, SCRYPT_PARAMS).toString('hex');
}
function hashPasswordPbkdf2(password, salt) {
  return crypto.pbkdf2Sync(password, salt, 100000, 64, 'sha512').toString('hex');
}
function hashPassword(password, salt) {
  return hashPasswordScrypt(password, salt);
}

// Pre-computed dummy hash used by apiAuthLogin when the username is unknown.
// Without this the login path returns ~immediately for non-existent users but
// spends ~50ms in scryptSync for real users — a measurable timing oracle that
// lets an attacker enumerate valid usernames. By running verifyPassword against
// this dummy in the not-found branch, both paths perform exactly one scrypt.
// Computed once at module load with a fixed salt — never used to authenticate.
const _DUMMY_LOGIN_SALT = 'a'.repeat(64);
const _DUMMY_LOGIN_HASH = hashPasswordScrypt('not-a-real-password-do-not-use', _DUMMY_LOGIN_SALT);

function verifyPassword(password, salt, stored) {
  if (typeof stored !== 'string' || !stored) return false;
  try {
    if (stored.startsWith('scrypt$')) {
      const expected = stored.slice(7);
      const candidate = crypto.scryptSync(password, salt, SCRYPT_KEYLEN, SCRYPT_PARAMS).toString('hex');
      return safeHexEqual(candidate, expected);
    }
    // Legacy pbkdf2 (bare hex)
    const candidate = hashPasswordPbkdf2(password, salt);
    return safeHexEqual(candidate, stored);
  } catch { return false; }
}
// Server-side password policy. Returns null when accepted, otherwise a human
// readable error message. Mirror this in the UI for nicer feedback, but the
// check here is the authoritative gate.
function passwordPolicyError(pw) {
  if (typeof pw !== 'string') return 'Password must be a string';
  if (pw.length < 12) {
    // Allow ≥8 chars only when the password mixes at least three character classes
    if (pw.length < 8) return 'Password must be at least 8 characters';
    const classes = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^a-zA-Z0-9]/].filter(rx => rx.test(pw)).length;
    if (classes < 3) return 'Short passwords (8–11 chars) need a mix of lowercase, UPPERCASE, digits and a symbol';
  }
  if (pw.length > 128) return 'Password must be at most 128 characters';
  // Reject the most obvious sentinels
  const banned = new Set(['password', 'qwerty12', 'admin1234', 'admin1234!', '12345678', 'changeme', 'letmein!']);
  if (banned.has(pw.toLowerCase())) return 'This password is too common — choose something different';
  return null;
}

function safeHexEqual(a, b) {
  if (typeof a !== 'string' || typeof b !== 'string' || a.length !== b.length) return false;
  try {
    return crypto.timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
  } catch { return false; }
}

// ── TOTP (RFC 6238) ──────────────────────────────────────────────────────────
// Time-based one-time password generator + verifier, implemented inline so we
// don't pull in another npm dep. Standard parameters (SHA-1, 30-second step,
// 6 digits) — every off-the-shelf authenticator app (Aegis, Authy, Bitwarden,
// 2FAS, Google Authenticator, etc.) reads them out of the otpauth:// URI.
//
// The secret is stored as base32 in panel_users.totp_secret. Setup writes the
// candidate into totp_pending; only after the user confirms by entering a
// valid code from their app does it move into totp_secret + totp_enabled=1.
// This prevents a half-setup state where 2FA is "on" but the user never
// scanned the QR.
const _BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
function _base32Encode(buf) {
  let bits = '';
  for (const b of buf) bits += b.toString(2).padStart(8, '0');
  let out = '';
  for (let i = 0; i < bits.length; i += 5) {
    out += _BASE32_ALPHABET[parseInt(bits.slice(i, i + 5).padEnd(5, '0'), 2)];
  }
  return out;
}
function _base32Decode(str) {
  const clean = String(str || '').toUpperCase().replace(/[^A-Z2-7]/g, '');
  let bits = '';
  for (const c of clean) bits += _BASE32_ALPHABET.indexOf(c).toString(2).padStart(5, '0');
  const bytes = [];
  for (let i = 0; i + 8 <= bits.length; i += 8) bytes.push(parseInt(bits.slice(i, i + 8), 2));
  return Buffer.from(bytes);
}
function _totpCode(secretBuf, time = Math.floor(Date.now() / 1000), step = 30, digits = 6) {
  const counter = Math.floor(time / step);
  const buf = Buffer.alloc(8);
  buf.writeBigUInt64BE(BigInt(counter), 0);
  const hmac = crypto.createHmac('sha1', secretBuf).update(buf).digest();
  const off = hmac[hmac.length - 1] & 0x0f;
  const bin = ((hmac[off]     & 0x7f) << 24) |
              ((hmac[off + 1] & 0xff) << 16) |
              ((hmac[off + 2] & 0xff) <<  8) |
              ( hmac[off + 3] & 0xff);
  return String(bin % (10 ** digits)).padStart(digits, '0');
}
// Constant-time string compare so the verifier doesn't leak which digit
// failed via timing. Both sides must be the same length already.
function _ctEqual(a, b) {
  if (typeof a !== 'string' || typeof b !== 'string' || a.length !== b.length) return false;
  try { return crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b)); } catch { return false; }
}
function totpVerify(secretB32, code, drift = 1) {
  if (!secretB32 || !code || !/^\d{6}$/.test(String(code))) return false;
  const key = _base32Decode(secretB32);
  if (!key.length) return false;
  const now = Math.floor(Date.now() / 1000);
  for (let i = -drift; i <= drift; i++) {
    if (_ctEqual(_totpCode(key, now + i * 30), String(code))) return true;
  }
  return false;
}
function totpProvisioningUri({ secret, account, issuer }) {
  // otpauth://totp/<issuer>:<account>?secret=...&issuer=...&algorithm=SHA1&digits=6&period=30
  const label = encodeURIComponent(`${issuer}:${account}`);
  const params = new URLSearchParams({ secret, issuer, algorithm: 'SHA1', digits: '6', period: '30' });
  return `otpauth://totp/${label}?${params}`;
}

function seedDefaultUsers() {
  if (!db) return;
  try {
    const DEFAULT_PASS = 'Admin1234!';
    for (const [username, role] of [['Admin', 'admin']]) {
      const existing = db.prepare('SELECT 1 FROM panel_users WHERE username = ?').get(username);
      if (!existing) {
        const salt = crypto.randomBytes(32).toString('hex');
        db.prepare('INSERT INTO panel_users (username, password_hash, salt, role, must_change_password) VALUES (?, ?, ?, ?, 1)')
          .run(username, hashPassword(DEFAULT_PASS, salt), salt, role);
      }
    }
  } catch (e) {
    console.error('  User seed failed:', e.message);
  }
}

// ── Helpers ───────────────────────────────────────────────────────────────────
function getNetworkIP() {
  for (const ifaces of Object.values(os.networkInterfaces())) {
    for (const iface of ifaces) {
      if (iface.family === 'IPv4' && !iface.internal) return iface.address;
    }
  }
  return '127.0.0.1';
}

function setSecurityHeaders(req, res) {
  // Stash the request on the response so downstream helpers (respond, json)
  // can negotiate Content-Encoding without every call site threading req
  // through manually. Set once per request inside the handler.
  res._acReq = req;
  res.setHeader('X-Frame-Options', 'DENY');
  res.setHeader('X-Content-Type-Options', 'nosniff');
  res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
  // The panel is an admin tool, not a public website — keep it out of search
  // engines so the login URL never surfaces in Google/Bing results when an
  // operator forgets to gate the panel behind a private network. The meta tag
  // in index.html covers HTML navigation; this header is what crawlers see on
  // every other response (assets, JSON, JS bundles) and on the index.html
  // fetch itself when only the headers are read.
  res.setHeader('X-Robots-Tag', 'noindex, nofollow, noarchive, nosnippet, noimageindex');
  // Lock down browser features the panel never uses
  res.setHeader('Permissions-Policy',
    'accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()');
  // Content Security Policy. JSX is now pre-transpiled by build.js (esbuild) and
  // served from /dist/ as plain JS, so 'unsafe-eval' / 'unsafe-inline' are no
  // longer required. 'unsafe-inline' for style stays — many components use inline
  // style props which compile to inline `style="..."` attributes.
  res.setHeader('Content-Security-Policy', [
    "default-src 'self'",
    "script-src 'self' https://unpkg.com",
    "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
    "font-src 'self' https://fonts.gstatic.com data:",
    "img-src 'self' data: https:",
    "connect-src 'self'",
    "frame-ancestors 'none'",
    "base-uri 'self'",
    "form-action 'self'",
    "object-src 'none'",
  ].join('; '));
  // HSTS only when the connection actually arrived over HTTPS (or via a TLS-terminating proxy).
  if (requestIsHttps(req)) {
    res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
  }
}

// Content types worth compressing. Already-compressed formats (webp, png,
// jpeg, woff2, …) come from MIME elsewhere and skip this path; for JSON, HTML,
// CSS, JS the saving over the wire is typically 4–8x and the CPU cost of
// gzip/brotli at default levels is negligible compared to the bytes saved.
const _COMPRESSIBLE_MIME = /^(?:application\/(?:json|javascript|manifest\+json)|text\/(?:plain|html|css|csv|event-stream))(?:\b|;)/i;
const _COMPRESS_MIN_BYTES = 1024; // skip compression for tiny payloads where the headers cost more than they save

function _negotiateEncoding(req, mime, bodyLen) {
  if (!_COMPRESSIBLE_MIME.test(mime)) return null;
  if (bodyLen < _COMPRESS_MIN_BYTES) return null;
  const ae = (req?.headers?.['accept-encoding'] || '').toLowerCase();
  if (!ae) return null;
  // Prefer brotli (smaller) when offered, otherwise gzip. Identity ('') is
  // always acceptable as a fallback.
  if (ae.includes('br')) return 'br';
  if (ae.includes('gzip')) return 'gzip';
  return null;
}

function _compress(body, encoding) {
  const buf = Buffer.isBuffer(body) ? body : Buffer.from(body);
  if (encoding === 'br') return zlib.brotliCompressSync(buf, { params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 5 } });
  if (encoding === 'gzip') return zlib.gzipSync(buf, { level: 6 });
  return buf;
}

// `req` for Accept-Encoding negotiation is pulled from res._acReq (stashed by
// setSecurityHeaders) so existing call sites don't have to thread it through.
// Older callers (or paths that bypass setSecurityHeaders) still work — they
// just don't benefit from compression.
function respond(res, status, mime, body, extraHeaders) {
  const headers = {
    'Content-Type':  mime,
    'Cache-Control': 'no-cache, no-store, must-revalidate',
    'Vary':          'Accept-Encoding',
    ...extraHeaders,
  };
  let payload = body;
  const req = res._acReq;
  if (req && body && !headers['Content-Encoding']) {
    const bodyLen = Buffer.isBuffer(body) ? body.length : Buffer.byteLength(body);
    const enc = _negotiateEncoding(req, mime, bodyLen);
    if (enc) {
      payload = _compress(body, enc);
      headers['Content-Encoding'] = enc;
    }
  }
  res.writeHead(status, headers);
  res.end(payload);
}

function respondImage(res, data, mime = 'image/png') {
  res.writeHead(200, {
    'Content-Type':  mime,
    'Cache-Control': 'public, max-age=3600',
  });
  res.end(data);
}

function serveAssetFallback(res, candidates) {
  const tryNext = (index) => {
    if (index >= candidates.length) return json(res, 404, { error: 'Asset not found' });
    const { path: p, mime } = candidates[index];
    fs.readFile(p, (err, data) => {
      if (err) tryNext(index + 1);
      else respondImage(res, data, mime);
    });
  };
  tryNext(0);
}

function json(res, status, data) {
  respond(res, status, 'application/json; charset=utf-8', JSON.stringify(data));
}

function readBody(req) {
  const ct = req.headers['content-type'] || '';
  if (!ct.includes('application/json')) return Promise.reject(new Error('Content-Type must be application/json'));
  return new Promise((resolve, reject) => {
    let raw = '';
    let settled = false;
    const settle = (fn, arg) => { if (settled) return; settled = true; clearTimeout(timer); fn(arg); };
    // Hard timeout: a slow-loris client could otherwise stream a few bytes
    // every minute and tie up a file descriptor + this promise forever. 30s
    // is far longer than any real JSON body needs (the largest legitimate
    // payload is ~10 MB chunked upload, which streams in seconds).
    const timer = setTimeout(() => {
      try { req.destroy(); } catch {}
      settle(reject, new Error('Request body timeout'));
    }, 30000);
    req.on('data', chunk => {
      raw += chunk;
      if (raw.length > 512_000) {
        try { req.destroy(); } catch {}
        settle(reject, new Error('Body too large'));
      }
    });
    req.on('end', () => { try { settle(resolve, JSON.parse(raw)); } catch { settle(reject, new Error('Invalid JSON')); } });
    req.on('error', e => settle(reject, e));
  });
}

// Best-effort prettifier for raw mod ids: turn `some_long_mod_id` into a more
// human-readable `Some Long Mod Id`. Used when no proper display name is
// available from the mod metadata.
function formatName(id) {
  return id
    .replace(/_/g, ' ')
    .replace(/\b([a-z])/g, (_, c) => c.toUpperCase())
    .trim();
}

function getPanelLang() {
  try {
    const row = db?.prepare(`SELECT value FROM panel_settings WHERE key = 'lang'`).get();
    const v = row?.value;
    return DISCORD_RECORD_TEMPLATES[v] ? v : 'en';
  } catch { return 'en'; }
}

function getDiscordWebhook() {
  try {
    const row = db?.prepare(`SELECT value FROM panel_settings WHERE key = 'discord_webhook'`).get();
    return row?.value || '';
  } catch { return ''; }
}

// Discord webhook hosts — the only acceptable destinations for postDiscordMessage
// and apiDiscordWebhookTest. Defense in depth on top of isValidDiscordWebhook's
// regex: the regex validates the string shape, but `new URL(...)` could in
// principle yield a hostname that differs (IDN normalisation, unicode tricks,
// future regex relaxation). Comparing parsed.hostname against this Set is the
// authoritative gate — anything else and we refuse to make the HTTPS request,
// closing the SSRF window for good.
const DISCORD_WEBHOOK_HOSTS = new Set([
  'discord.com',
  'discordapp.com',
  'canary.discord.com',
  'ptb.discord.com',
]);

// Fire-and-forget POST to the Discord webhook. Times out after 5s so a Discord
// outage cannot stall the UDP handler. Errors are logged at warn level only —
// missing a notification is never worth crashing the server for.
function postDiscordMessage(content) {
  const url = getDiscordWebhook();
  if (!url) return;
  let parsed;
  try { parsed = new URL(url); } catch { return; }
  if (!DISCORD_WEBHOOK_HOSTS.has(parsed.hostname.toLowerCase())) {
    log.warn(`[discord] refusing webhook with non-Discord hostname: ${parsed.hostname}`);
    return;
  }
  const payload = JSON.stringify({ content });
  const req = https.request({
    method: 'POST',
    hostname: parsed.hostname,
    path: parsed.pathname + parsed.search,
    headers: {
      'Content-Type':   'application/json',
      'Content-Length': Buffer.byteLength(payload),
      'User-Agent':     'beamng-server-panel',
    },
    timeout: 5000,
  }, (res) => {
    // Drain so the socket can be reused / closed.
    res.on('data', () => {});
    res.on('end', () => {
      if (res.statusCode >= 400) {
        log.warn(`[discord] webhook returned ${res.statusCode}`);
      }
    });
  });
  req.on('timeout', () => { req.destroy(new Error('discord webhook timeout')); });
  req.on('error', (e) => { log.warn('[discord] webhook error:', e.message); });
  req.write(payload);
  req.end();
}

// ── System metrics ────────────────────────────────────────────────────────────
function getCPUName() {
  try {
    const m = fs.readFileSync('/proc/cpuinfo', 'utf8').match(/model name\s*:\s*(.+)/);
    return m ? m[1].trim() : (os.cpus()[0]?.model || 'Unknown');
  } catch { return os.cpus()[0]?.model || 'Unknown'; }
}

function getOSInfo() {
  try {
    const raw  = fs.readFileSync('/etc/os-release', 'utf8');
    const get  = k => { const m = raw.match(new RegExp(`^${k}="?([^"\\n]+)"?`, 'm')); return m ? m[1] : ''; };
    return { name: get('NAME') || os.type(), version: get('VERSION_ID') || '' };
  } catch { return { name: os.type(), version: '' }; }
}

function getCPU() {
  return new Promise(resolve => {
    // /proc/stat is Linux-only. On macOS / FreeBSD / Windows readFileSync throws —
    // fall back to a 0 % reading so the dashboard still works.
    const read = () => {
      try {
        const v = fs.readFileSync('/proc/stat', 'utf8').split('\n')[0].split(/\s+/).slice(1).map(Number);
        return { idle: v[3] + (v[4] || 0), total: v.reduce((a, b) => a + b, 0) };
      } catch { return null; }
    };
    const s1 = read();
    if (!s1) return resolve(0);
    setTimeout(() => {
      const s2 = read();
      if (!s2) return resolve(0);
      const di = s2.idle - s1.idle, dt = s2.total - s1.total;
      resolve(dt === 0 ? 0 : Math.round((1 - di / dt) * 100));
    }, 250);
  });
}

// Public IP discovery. Hits api.ipify.org once and caches with a TTL so a
// transient bad response (DNS hijack, MITM, or ipify simply going wrong for a
// second) does not get pinned in memory forever. Validates that the body looks
// like an IPv4/IPv6 address before accepting — otherwise a malicious upstream
// could return arbitrary HTML and we'd surface it to every /api/metrics caller.
// Override entirely with PUBLIC_IP=1.2.3.4 in .env when behind NAT/CGNAT.
let _publicIpCache = { value: null, fetchedAt: 0 };
const PUBLIC_IP_TTL_MS = 60 * 60 * 1000; // 1h — long enough to spare ipify, short enough to recover from a bad result
function _looksLikeIp(s) {
  if (typeof s !== 'string' || !s) return false;
  if (s.length > 45) return false; // longest valid IPv6 textual form
  return /^\d{1,3}(\.\d{1,3}){3}$/.test(s) || /^[0-9a-fA-F:]+$/.test(s);
}
async function getPublicIp() {
  if (process.env.PUBLIC_IP) return process.env.PUBLIC_IP;
  const now = Date.now();
  if (_publicIpCache.value && now - _publicIpCache.fetchedAt < PUBLIC_IP_TTL_MS) {
    return _publicIpCache.value;
  }
  try {
    const res = await new Promise((resolve, reject) => {
      const req = require('https').get('https://api.ipify.org', r => {
        if (r.statusCode !== 200) { r.destroy(); return resolve(null); }
        let d = '';
        // Cap at 64 bytes — a real IP is at most 45 chars; anything bigger is
        // garbage and we don't want to buffer megabytes from a hostile upstream.
        r.on('data', chunk => { if (d.length < 64) d += chunk.toString().slice(0, 64 - d.length); });
        r.on('end', () => resolve(d.trim()));
      });
      req.on('error', reject);
      req.setTimeout(2000, () => { req.destroy(); resolve(null); });
    });
    if (_looksLikeIp(res)) {
      _publicIpCache = { value: res, fetchedAt: now };
      return res;
    }
    return getNetworkIP();
  } catch {
    return getNetworkIP();
  }
}

// Best-effort CPU temperature via /sys/class/thermal — pure Linux kernel
// surface, no external binary, no extra package to install, no sudo. Walks
// every thermal_zone, prefers zones whose `type` looks like a CPU sensor
// (x86_pkg_temp, coretemp, cpu-thermal, core_N, package_N) and reports the
// highest reading among the preferred set (multi-package boxes). If no
// zones exist or all readings look bogus (the file is missing, the value
// is out of plausible range, the host is a VPS with thermal hidden by
// the hypervisor, …) the helper returns null and the frontend hides the
// badge — there is no fallback temperature to show, just absence.
async function _getCpuTempC() {
  try {
    const base = '/sys/class/thermal';
    const zones = await fsp.readdir(base).catch(() => []);
    const candidates = [];
    for (const z of zones) {
      if (!/^thermal_zone\d+$/.test(z)) continue;
      try {
        const type = (await fsp.readFile(path.join(base, z, 'type'), 'utf8')).trim();
        const tempRaw = await fsp.readFile(path.join(base, z, 'temp'), 'utf8');
        const tempC = parseInt(tempRaw, 10) / 1000;
        if (!Number.isFinite(tempC) || tempC <= 0 || tempC > 200) continue;
        const isCpuLike = /(x86_pkg_temp|coretemp|cpu[-_]thermal|core_?\d|package_?\d)/i.test(type);
        candidates.push({ tempC, isCpuLike });
      } catch { /* unreadable zone — skip */ }
    }
    if (!candidates.length) return null;
    const cpu = candidates.filter(c => c.isCpuLike);
    const pool = cpu.length ? cpu : candidates;
    return Math.round(Math.max(...pool.map(c => c.tempC)));
  } catch { return null; }
}

function getRAM() {
  const d = fs.readFileSync('/proc/meminfo', 'utf8');
  const g = k => { const m = d.match(new RegExp(k + ':\\s+(\\d+)')); return m ? parseInt(m[1]) : 0; };
  const total = g('MemTotal'), avail = g('MemAvailable');
  return { used: Math.round((total - avail) / 1024), total: Math.round(total / 1024) };
}

// Pure helpers (_csvCell, parseLine) live in lib/pure.js so unit tests can
// load them without booting the HTTP server / DB / log watcher. See that
// file's header for the rule about what belongs there.
const { parseLine } = require('./lib/pure.js');

// ── API handlers ──────────────────────────────────────────────────────────────

// ── Stubs for handlers whose AC implementations were ripped ──────────────────
// /api/players and /api/players/kick stay as no-op pass-throughs so the
// frontend's polling loop and player management UI don't 404 in the gap
// before the BeamMP HTTP-API / Lua-plugin source lands.

// ── /api/config — ServerConfig.toml editor ────────────────────────────────────
// GET: parses the [General] section into JSON. The AuthKey is REDACTED — the
// value never leaves the host, the response carries a `hasAuthKey` boolean
// instead so the UI can show "set / not set" without exposing the secret to
// anyone with a panel session (audit-page screenshots, support-channel
// pastes, browser dev-tools network tab, …).
//
// PUT: validates {key: value} pairs against TOML_FIELD_SCHEMA, rejects
// unknown keys, runs the line-edit serializer that preserves comments + key
// order, writes through a backup rotation (ServerConfig.toml.bak +
// ServerConfig.toml.<datetime>.bak with retention from CFG_BACKUPS_KEEP),
// emits an audit row listing the changed keys (NOT values — AuthKey rotation
// would otherwise leak through the audit log), and auto-restarts the
// BeamMP-Server when it's currently up so the change takes effect (BeamMP
// doesn't support SIGHUP-style reload; a restart is the only way).
const TOML_FIELD_SCHEMA = {
  Port:               { type: 'number',  min: 1024, max: 65535 },
  AuthKey:            { type: 'string',  maxLen: 100, secret: true },
  AllowGuests:        { type: 'boolean' },
  LogChat:            { type: 'boolean' },
  Debug:              { type: 'boolean' },
  IP:                 { type: 'string',  maxLen: 45 },           // INET6_ADDRSTRLEN
  Private:            { type: 'boolean' },
  InformationPacket:  { type: 'boolean' },
  Name:               { type: 'string',  maxLen: 250 },          // BeamMP backend cap
  Tags:               { type: 'string',  maxLen: 100 },          // BeamMP backend cap
  MaxCars:            { type: 'number',  min: 1, max: 1000 },
  MaxPlayers:         { type: 'number',  min: 1, max: 1000 },
  Map:                { type: 'string',  maxLen: 100 },          // BeamMP backend cap
  Description:        { type: 'string',  maxLen: 1000 },         // BeamMP backend cap
  ResourceFolder:     { type: 'string',  maxLen: 1024 },
  ImScaredOfUpdates:  { type: 'boolean' },
  UpdateReminderTime: { type: 'string',  maxLen: 32, pattern: /^\d+(s|min|h|d)$/ },
};

function _validateTomlUpdates(updates) {
  if (!updates || typeof updates !== 'object' || Array.isArray(updates)) {
    return { error: 'Body must be a JSON object of key→value pairs' };
  }
  const cleaned = {};
  for (const [key, value] of Object.entries(updates)) {
    const schema = TOML_FIELD_SCHEMA[key];
    if (!schema) {
      // The schema is open-source so the set of valid keys isn't a secret,
      // but an unauthenticated probe (in a hypothetical future where this
      // endpoint relaxed its auth) could otherwise enumerate "is this key
      // a real one?" from the error shape alone. Generic 400 to the client,
      // specific WARN to the operator's log so an admin debugging a typo
      // (e.g. "MaxPlayers" vs "MaxCarsPerPlayer") still gets the actionable
      // info — just out-of-band from the HTTP response.
      log.warn(`config update: rejected unknown key "${key}"`);
      return { error: 'Unknown configuration key' };
    }
    // AuthKey: null / undefined means "don't touch the existing value". An
    // empty string means "explicitly clear the AuthKey". A non-empty string
    // means "set this new value". The frontend should always send `null`
    // when the user didn't touch the input so we don't accidentally wipe it.
    if (schema.secret && (value === null || value === undefined)) continue;
    if (schema.type === 'boolean') {
      if (typeof value !== 'boolean') return { error: `${key} must be boolean (got ${typeof value})` };
      cleaned[key] = value;
    } else if (schema.type === 'number') {
      const n = typeof value === 'string' ? parseFloat(value) : value;
      if (!Number.isFinite(n)) return { error: `${key} must be a number` };
      if (schema.min !== undefined && n < schema.min) return { error: `${key} must be >= ${schema.min}` };
      if (schema.max !== undefined && n > schema.max) return { error: `${key} must be <= ${schema.max}` };
      cleaned[key] = Math.trunc(n);
    } else if (schema.type === 'string') {
      if (typeof value !== 'string') return { error: `${key} must be a string` };
      if (schema.maxLen !== undefined && value.length > schema.maxLen) {
        return { error: `${key} exceeds ${schema.maxLen} characters` };
      }
      if (schema.pattern && value !== '' && !schema.pattern.test(value)) {
        return { error: `${key} does not match the expected format` };
      }
      // Strip control characters except \n + \t (BeamMP's TOML reader chokes
      // on raw NUL / CR / VT inside string values).
      // eslint-disable-next-line no-control-regex
      cleaned[key] = value.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
    }
  }
  return { cleaned };
}

function apiConfig(req, res) {
  if (!checkPermission(req, 'serverConfig')) return json(res, 403, { error: 'Forbidden' });
  try {
    let raw;
    try { raw = fs.readFileSync(BEAMMP_CFG_FILE, 'utf8'); }
    catch (e) {
      if (e.code === 'ENOENT') {
        return json(res, 200, {
          exists: false,
          config: {},
          hasAuthKey: false,
          path: BEAMMP_CFG_FILE,
        });
      }
      throw e;
    }
    const parsed = parseServerConfig(raw);
    const general = parsed.sections.General || {};
    // Strip the secret before responding. The frontend gets a boolean it can
    // use to render "AuthKey: set ✓" or "AuthKey: not set ✗".
    const { AuthKey, ...redacted } = general;
    return json(res, 200, {
      exists: true,
      config: redacted,
      hasAuthKey: typeof AuthKey === 'string' && AuthKey.length > 0,
      path: BEAMMP_CFG_FILE,
    });
  } catch (e) { return json(res, 500, { error: e.message }); }
}

// Admin-only: returns the AuthKey value in cleartext. The regular GET /api/config
// redacts it to a boolean; an admin who needs to copy the existing key (cross-host
// migration, paste into keymaster.beammp.com, etc.) hits this endpoint instead.
// Every reveal is audit-logged as `config.authkey.reveal` so the chain shows who
// fetched the secret and when. Rate-limited to prevent log-flooding.
function apiConfigAuthKey(req, res) {
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  if (!checkRateLimit('authkey-reveal', clientIp(req), 10, 60 * 1000))
    return json(res, 429, { error: 'Rate limit: too many AuthKey reveals' });
  const actor = getSession(req)?.username || 'unknown';
  let raw;
  try { raw = fs.readFileSync(BEAMMP_CFG_FILE, 'utf8'); }
  catch (e) {
    if (e.code === 'ENOENT') return json(res, 404, { error: 'ServerConfig.toml not found' });
    return json(res, 500, { error: e.message });
  }
  const parsed = parseServerConfig(raw);
  const authKey = parsed.sections.General?.AuthKey;
  if (typeof authKey !== 'string' || authKey.length === 0)
    return json(res, 200, { authKey: '', hasAuthKey: false });
  insertAuditLog(actor, 'config.authkey.reveal', '', '');
  return json(res, 200, { authKey, hasAuthKey: true });
}

async function apiConfigUpdate(req, res) {
  if (!checkPermission(req, 'serverConfig')) return json(res, 403, { error: 'Forbidden' });
  if (!checkRateLimit('config-save', clientIp(req), 30, 60 * 1000))
    return json(res, 429, { error: 'Rate limit: too many config saves' });
  let body;
  try { body = await readBody(req); }
  catch (e) { return json(res, 400, { error: e.message }); }
  const v = _validateTomlUpdates(body);
  if (v.error) return json(res, 400, { error: v.error });
  if (Object.keys(v.cleaned).length === 0) return json(res, 400, { error: 'No valid keys to update' });

  return withServerActionLock(req, res, async () => {
    const actor = checkAnyAuth(req)?.username || 'unknown';
    let raw;
    try { raw = fs.readFileSync(BEAMMP_CFG_FILE, 'utf8'); }
    catch (e) {
      if (e.code !== 'ENOENT') return json(res, 500, { error: `Cannot read config: ${e.message}` });
      // No file yet → start from an empty [General] section. Operators who
      // never ran BeamMP-Server once still get a sensible file written.
      raw = '[General]\n';
    }
    let next;
    try { next = editServerConfig(raw, 'General', v.cleaned); }
    catch (e) { return json(res, 500, { error: `Cannot serialise config: ${e.message}` }); }

    // Backup THEN atomic-write THEN audit. If anything fails before the
    // rename, we still have ServerConfig.toml.bak as a snapshot to roll
    // back to manually.
    try {
      // rotateConfigBackup is best-effort (silently swallows IO errors and
      // logs a warning) so we don't block the save on a bad backup.
      await rotateConfigBackup();
      // Atomic write via temp file + rename. POSIX rename(2) is atomic on
      // the same filesystem so the config either has the OLD content or
      // the NEW content — never a half-written state.
      const tmp = BEAMMP_CFG_FILE + '.tmp';
      await fsp.writeFile(tmp, next, 'utf8');
      await fsp.rename(tmp, BEAMMP_CFG_FILE);
    } catch (e) {
      insertAuditLog(actor, 'server.config.update.fail', '', e.message);
      return json(res, 500, { error: `Write failed: ${e.message}` });
    }

    // Audit row carries the changed keys (sorted) but never the values —
    // AuthKey rotation would otherwise leak through the audit log into
    // anyone with auditView permission.
    const keysChanged = Object.keys(v.cleaned).sort().join(',');
    insertAuditLog(actor, 'server.config.update', keysChanged);

    // Auto-restart if the server is currently up. BeamMP-Server reads
    // ServerConfig.toml only at startup, so a change without restart sits
    // dormant until the next manual restart. Mirror the AC panel behaviour
    // where /api/config saves transparently bounce the server.
    let restarted = false;
    try {
      const wasRunning = (beammpChild && !beammpChild.killed) || !!(await findBeamMPPid()) || (await getServerInfo()).running;
      if (wasRunning) {
        await killBeamMP();
        await waitForBeamMPDown(6000);
        await sleep(500);
        const s = await spawnBeamMP();
        if (s.ok) { await waitForBeamMPUp(12000); restarted = true; }
      }
    } catch (e) { log.warn('config.update auto-restart failed:', e.message); }

    return json(res, 200, { ok: true, keysChanged: Object.keys(v.cleaned), restarted });
  });
}

// ── Maps catalogue ────────────────────────────────────────────────────────────
// The Map field in ServerConfig.toml takes an opaque `/levels/<x>/info.json`
// path that the client resolves against its OWN BeamNG.drive install — the
// server has no copy of the assets. So the catalogue here is twofold:
//   1. The 14 vanilla maps every player has by virtue of owning the game
//      (hardcoded in VANILLA_MAPS_META up top).
//   2. Any custom map mod uploaded to Resources/Client/*.zip — detected by
//      scanning the zip's entries for `levels/<x>/info.json`. The .zip is
//      streamed to connecting clients on join (BeamMP's auto-download pump),
//      so as long as the operator uploaded the zip, the level path is valid.
// BeamNG ships info.json in a tolerant JSONC dialect: trailing commas and
// occasional /* … */ or // … comments are common. JSON.parse rejects both,
// so we sanitise before parsing rather than pull in a runtime dep. The
// trailing-comma stripper is the load-bearing one in practice — the
// Nordschleife mod that triggered this work has a trailing comma in its
// spawnPoints array. Returns null on any parse error so the caller can
// gracefully degrade to bare filename metadata.
function _parseLooseJson(text) {
  let s = String(text);
  // Drop a UTF-8 BOM if the zip entry has one (some mod tools save with it).
  if (s.charCodeAt(0) === 0xFEFF) s = s.slice(1);
  s = s
    .replace(/\/\*[\s\S]*?\*\//g, '')   // /* … */ block comments
    .replace(/^\s*\/\/[^\n]*$/gm, '');  // // … line comments (whole-line only — avoids eating URL "://" inside strings)
  // Generalised missing-comma fix. Whenever a value-end token (string, },
  // ], true/false/null, number) is followed by whitespace including at
  // least one newline and then a value-start token (string-key + colon,
  // `{` or `[`), insert a comma. BeamNG.drive's lenient parser tolerates
  // these missing commas but JSON.parse doesn't. Map mods produced by
  // popular packagers (2K-Sadamine, 2K-Happogahara, …) ship info.json
  // files with dropped commas between properties AND between array
  // elements; the regex covers both. The string sub-pattern uses the
  // standard JSON escape form so a backslash-escaped quote inside the
  // value doesn't terminate the match early.
  s = s.replace(
    /("(?:[^"\\]|\\.)*"|\}|\]|true|false|null|-?\d+(?:\.\d+)?)(\s*\n\s*)(?="(?:[^"\\]|\\.)*"\s*:|\{|\[)/g,
    '$1,$2'
  );
  s = s.replace(/,(\s*[}\]])/g, '$1');  // trailing commas before } or ]
  try { return JSON.parse(s); } catch { return null; }
}

// Derive the S/M/L bucket VANILLA_MAPS_META uses from the [width,height]
// size array BeamNG mods put in info.json. Threshold is by longest side: <
// 2 km = S, < 8 km = M, >= 8 km = L. Returns '?' if size is missing or
// non-numeric.
function _bucketSize(arr) {
  if (!Array.isArray(arr) || !arr.length) return '?';
  const dim = Math.max(...arr.map(n => Number(n) || 0));
  if (!Number.isFinite(dim) || dim <= 0) return '?';
  if (dim < 2048) return 'S';
  if (dim < 8000) return 'M';
  return 'L';
}

// info.json's country field is usually a translation key like
// "levels.common.country.germany". The translation tables live inside the
// mod, not in the panel, so we surface the last dotted segment, title-cased,
// as a best-effort short label. "Germany" beats "levels.common.country.
// germany" on a badge, and the operator can read the long form in the
// modal if they really want to.
function _shortCountry(raw) {
  if (typeof raw !== 'string' || !raw.trim()) return null;
  const last = raw.split('.').pop();
  if (!last) return null;
  return last[0].toUpperCase() + last.slice(1);
}

// Resolve a level's preview image inside a zip. Two strategies, in priority:
//   1. The canonical `levels/<X>/preview.(png|jpe?g)` file. Most mods ship it.
//   2. Fall back to `info.json["previews"][0]` — BeamNG's official way for
//      modders to declare a preview path that isn't the canonical one (some
//      mods, e.g. 2K-Sadamine, point at `quickrace/TH.jpg` from the JSON
//      instead of bundling a `preview.jpg`). The path is relative to the
//      level directory and must resolve to a .png/.jpg/.jpeg actually
//      present in the archive — we reject anything with `..` or an
//      absolute slash so a malicious info.json can't redirect us to
//      another mod's file or outside the zip layout.
// Returns `{ key, ext }` with the zip entry path + lowercase extension, or
// null when no preview is recoverable.
async function _resolveLevelPreview(zip, entryNames, levelName, parsedMeta) {
  const escaped = levelName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  const canonical = new RegExp(`(?:^|/)levels/${escaped}/preview\\.(png|jpe?g)$`, 'i');
  let key = null, ext = null;
  for (const n of entryNames) {
    const m = n.match(canonical);
    if (!m) continue;
    // Prefer .png when both formats coexist — sharper at small sizes.
    if (!key || (m[1].toLowerCase() === 'png' && ext !== 'png')) {
      key = n; ext = m[1].toLowerCase();
    }
  }
  if (key) return { key, ext };
  // Fallback: pick the path declared in info.json. Read+parse only if the
  // caller didn't pre-parse it for us.
  let meta = parsedMeta;
  if (meta === undefined) {
    const infoRe = new RegExp(`(?:^|/)levels/${escaped}/info\\.json$`);
    const infoKey = entryNames.find(n => infoRe.test(n));
    if (!infoKey) return null;
    try {
      const buf = await zip.entryData(infoKey);
      meta = _parseLooseJson(buf.toString('utf8'));
    } catch { return null; }
  }
  if (!meta || !Array.isArray(meta.previews) || !meta.previews.length) return null;
  const rel = String(meta.previews[0] || '').trim();
  if (!rel || rel.startsWith('/') || rel.includes('..')) return null;
  const tail = `levels/${levelName}/${rel}`.toLowerCase();
  for (const n of entryNames) {
    const lc = n.toLowerCase();
    if (lc !== tail && !lc.endsWith('/' + tail)) continue;
    const m = n.match(/\.(png|jpe?g)$/i);
    if (m) return { key: n, ext: m[1].toLowerCase() };
  }
  return null;
}

async function enumerateCustomMaps() {
  if (!StreamZip) return [];
  const out = [];
  let entries;
  try { entries = await fsp.readdir(BEAMMP_CLIENT_RESOURCES_DIR, { withFileTypes: true }); }
  catch { return []; }
  for (const e of entries) {
    if (!e.isFile() || !/\.zip$/i.test(e.name)) continue;
    const zipPath = path.join(BEAMMP_CLIENT_RESOURCES_DIR, e.name);
    let zip;
    try { zip = new StreamZip.async({ file: zipPath }); }
    catch { continue; }
    try {
      const zipEntries = await zip.entries();
      // Look for levels/<name>/info.json — that's BeamNG's marker for "this
      // archive contains a map called <name>". We accept any nesting depth in
      // case the modder bundled it as e.g. `mymap/levels/<name>/info.json`.
      // We also pair each level with its sibling preview.png (same nesting),
      // so the catalogue card can render the modder's screenshot instead of
      // the themed SVG fallback. A zip can carry multiple levels — each is
      // emitted as its own catalogue entry with its own hasPreview flag.
      const levels = new Map(); // levelName -> { hasInfo, hasPreview, infoKey }
      for (const path0 of Object.keys(zipEntries)) {
        const mi = path0.match(/(?:^|\/)levels\/([^/]+)\/info\.json$/);
        if (mi) {
          const ln = mi[1];
          const slot = levels.get(ln) || { hasInfo: false, hasPreview: false, infoKey: null };
          slot.hasInfo = true;
          slot.infoKey = path0;
          levels.set(ln, slot);
          continue;
        }
        const mp = path0.match(/(?:^|\/)levels\/([^/]+)\/preview\.(?:png|jpe?g)$/i);
        if (mp) {
          const ln = mp[1];
          const slot = levels.get(ln) || { hasInfo: false, hasPreview: false, infoKey: null };
          slot.hasPreview = true;
          levels.set(ln, slot);
        }
      }
      const entryNames = Object.keys(zipEntries);
      for (const [levelName, flags] of levels) {
        if (!flags.hasInfo) continue;
        // Extract + parse the level's info.json so the catalogue card can
        // show the modder's chosen title and metadata rather than the bare
        // directory name. Pure additive — every field below falls back to
        // the pre-parse defaults when the JSON is missing, unreadable, or
        // doesn't contain that key.
        let meta = null;
        try {
          const buf = await zip.entryData(flags.infoKey);
          meta = _parseLooseJson(buf.toString('utf8'));
        } catch { /* unreadable info.json — fall back to defaults */ }
        // If we didn't spot a canonical preview.png/jpg during the entries
        // pass, _resolveLevelPreview will read info.json's `previews[0]`
        // and check whether it actually resolves to a file in the zip.
        // Pre-parsed meta is passed so we don't decompress info.json twice.
        let hasPreview = flags.hasPreview;
        if (!hasPreview) {
          const resolved = await _resolveLevelPreview(zip, entryNames, levelName, meta || undefined);
          if (resolved) hasPreview = true;
        }
        const m = meta && typeof meta === 'object' ? meta : {};
        const title       = (typeof m.title       === 'string' && m.title.trim())       || levelName;
        const description = (typeof m.description === 'string' && m.description.trim()) || `Custom map from ${e.name}`;
        const authors     = (typeof m.authors     === 'string' && m.authors.trim())     || null;
        const biome       = (typeof m.biome       === 'string' && m.biome.trim())       || null;
        const features    = (typeof m.features    === 'string' && m.features.trim())    || null;
        const suitableFor = (typeof m.suitablefor === 'string' && m.suitablefor.trim()) || null;
        const country     = _shortCountry(m.country);
        const size        = _bucketSize(m.size);
        out.push({
          id:          `${e.name}::${levelName}`,
          level:       `/levels/${levelName}/info.json`,
          name:        title,
          levelName,                     // raw directory name (technical, surfaced under Level path)
          theme:       'custom',
          size,
          description,
          authors,
          biome,
          country,
          features,
          suitableFor,
          source:      e.name,
          hasPreview,
        });
      }
    } catch { /* corrupt zip — skip */ }
    finally { try { await zip.close(); } catch {} }
  }
  return out;
}

// Companion to enumerateCustomMaps for the Cars catalogue. BeamMP doesn't
// "activate" cars the way it activates a map — every connected client uses
// whichever car they have installed, and any car mod under Resources/Client
// is auto-streamed to joiners. So this is read-only catalogue data: list
// every vehicles/<X>/info.json across all .zips, parse the modder's
// metadata, emit one entry per vehicle. Vanilla BeamNG.drive cars are
// deliberately NOT enumerated here — they live in the player's BeamNG
// install, not on the server, so the panel has nothing to scan.
async function enumerateCustomCars() {
  if (!StreamZip) return [];
  const out = [];
  let entries;
  try { entries = await fsp.readdir(BEAMMP_CLIENT_RESOURCES_DIR, { withFileTypes: true }); }
  catch { return []; }
  for (const e of entries) {
    if (!e.isFile() || !/\.zip$/i.test(e.name)) continue;
    const zipPath = path.join(BEAMMP_CLIENT_RESOURCES_DIR, e.name);
    let zip;
    try { zip = new StreamZip.async({ file: zipPath }); }
    catch { continue; }
    try {
      const zipEntries = await zip.entries();
      // Same pairing dance as enumerateCustomMaps but for vehicles/<X>/.
      // info.json marks "this archive contains a vehicle"; default.png/jpg
      // is BeamNG's per-vehicle thumbnail (the one BeamNG.drive shows in
      // the garage browser). default.jpg is the dominant form in the wild;
      // .png shows up in older mods.
      const cars = new Map(); // carName -> { hasInfo, hasPreview, infoKey }
      for (const path0 of Object.keys(zipEntries)) {
        const mi = path0.match(/(?:^|\/)vehicles\/([^/]+)\/info\.json$/);
        if (mi) {
          const cn = mi[1];
          if (cn === 'common') continue;          // BeamNG's shared/common assets, not a vehicle
          const slot = cars.get(cn) || { hasInfo: false, hasPreview: false, infoKey: null };
          slot.hasInfo = true;
          slot.infoKey = path0;
          cars.set(cn, slot);
          continue;
        }
        const mp = path0.match(/(?:^|\/)vehicles\/([^/]+)\/default\.(?:png|jpe?g)$/i);
        if (mp) {
          const cn = mp[1];
          if (cn === 'common') continue;
          const slot = cars.get(cn) || { hasInfo: false, hasPreview: false, infoKey: null };
          slot.hasPreview = true;
          cars.set(cn, slot);
        }
      }
      for (const [carName, flags] of cars) {
        if (!flags.hasInfo) continue;
        let meta = null;
        try {
          const buf = await zip.entryData(flags.infoKey);
          meta = _parseLooseJson(buf.toString('utf8'));
        } catch { /* unreadable info — fall back */ }
        const m = meta && typeof meta === 'object' ? meta : {};
        // BeamNG's vehicle info.json varies more than levels — some mods use
        // PascalCase (Name, Brand) and some camelCase. We accept both.
        const pick = (...keys) => {
          for (const k of keys) {
            const v = m[k];
            if (typeof v === 'string' && v.trim()) return v.trim();
          }
          return null;
        };
        const title       = pick('Name', 'name') || carName;
        const brand       = pick('Brand', 'brand');
        const description = pick('Description', 'description') || `Custom car from ${e.name}`;
        const country     = _shortCountry(pick('Country', 'country'));
        const years       = pick('Years', 'years');
        const type        = pick('Type', 'type', 'BodyStyle', 'bodyStyle');
        const authors     = pick('Authors', 'authors');
        // Player-character packs live under vehicles/ too (BeamNG models the
        // avatar as a vehicle) but are not drivable cars — keep them out of the
        // Cars catalogue, matching the Mods page's 'character' classification.
        if (type && type.toLowerCase() === 'characters') continue;
        out.push({
          id:          `${e.name}::${carName}`,
          carName,                         // raw directory name inside vehicles/
          name:        title,
          brand,
          description,
          country,
          years,
          type,
          authors,
          source:      e.name,
          hasPreview:  flags.hasPreview,
        });
      }
    } catch { /* corrupt zip — skip */ }
    finally { try { await zip.close(); } catch {} }
  }
  // Stable sort: brand, then name
  out.sort((a, b) => {
    const ab = (a.brand || '').toLowerCase();
    const bb = (b.brand || '').toLowerCase();
    if (ab !== bb) return ab.localeCompare(bb);
    return (a.name || '').toLowerCase().localeCompare((b.name || '').toLowerCase());
  });
  return out;
}

async function apiCars(req, res) {
  if (!checkPermission(req, 'mapActivate')) return json(res, 403, { error: 'Forbidden' });
  try {
    const custom = await enumerateCustomCars();
    return json(res, 200, { custom });
  } catch (e) { return json(res, 500, { error: e.message }); }
}

// Per-vehicle preview extractor. Same shape as apiMapPreview but addresses
// vehicles/<carName>/default.(png|jpg|jpeg) inside the zip. Gate on
// mapActivate (the Cars page permission, implied by serverConfig).
async function apiCarPreview(req, res, source, carName) {
  if (!checkPermission(req, 'mapActivate')) return json(res, 403, { error: 'Forbidden' });
  if (!source || /[\\/]|\.\./.test(source) || source.startsWith('.') || !/\.zip$/i.test(source)) {
    return json(res, 400, { error: 'Invalid source' });
  }
  if (!carName || /[\\/]|\.\./.test(carName) || carName.startsWith('.')) {
    return json(res, 400, { error: 'Invalid car name' });
  }
  if (!StreamZip) return json(res, 503, { error: 'zip extractor not available' });
  const zipPath = path.join(BEAMMP_CLIENT_RESOURCES_DIR, source);
  const st = await _statSafe(zipPath);
  if (!st || !st.isFile()) return json(res, 404, { error: 'Source not found' });
  let zip;
  try { zip = new StreamZip.async({ file: zipPath }); }
  catch { return json(res, 500, { error: 'Cannot open zip' }); }
  try {
    const entries = await zip.entries();
    const escaped = carName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
    const re = new RegExp(`(?:^|/)vehicles/${escaped}/default\\.(png|jpe?g)$`, 'i');
    let previewKey = null;
    let previewExt = null;
    for (const n of Object.keys(entries)) {
      const m = n.match(re);
      if (!m) continue;
      if (!previewKey || (m[1].toLowerCase() === 'png' && previewExt !== 'png')) {
        previewKey = n;
        previewExt = m[1].toLowerCase();
      }
    }
    if (!previewKey) return json(res, 404, { error: 'No preview for this car' });
    const buf = await zip.entryData(previewKey);
    res.setHeader('Content-Type', previewExt === 'png' ? 'image/png' : 'image/jpeg');
    res.setHeader('Cache-Control', 'private, max-age=86400');
    res.setHeader('ETag', `"${st.mtimeMs}-${buf.length}"`);
    res.end(buf);
  } catch (e) {
    return json(res, 500, { error: 'Cannot extract preview: ' + e.message });
  } finally { try { await zip.close(); } catch {} }
}

function _readActiveMap() {
  try {
    const raw = fs.readFileSync(BEAMMP_CFG_FILE, 'utf8');
    const m = raw.match(/^Map\s*=\s*"([^"]*)"/m);
    return m ? m[1] : '';
  } catch { return ''; }
}

async function apiMaps(req, res) {
  if (!checkPermission(req, 'mapActivate')) return json(res, 403, { error: 'Forbidden' });
  try {
    const custom = await enumerateCustomMaps();
    return json(res, 200, {
      active: _readActiveMap(),
      vanilla: VANILLA_MAPS_META,
      custom,
    });
  } catch (e) { return json(res, 500, { error: e.message }); }
}

// Shared activation primitive: write Map = "..." to ServerConfig.toml with
// the backup-rotate-then-atomic-rename dance, audit-log the change, and
// optionally restart the server. Called from both the manual /api/maps/activate
// endpoint (where restart is operator-confirmed) and the automatic map
// rotation timer (where restart is the whole point). Returns { running,
// restarted } so callers can report what actually happened.
async function _doActivateMap(actor, level, { autoRestart }) {
  let raw;
  try { raw = fs.readFileSync(BEAMMP_CFG_FILE, 'utf8'); }
  catch (e) {
    if (e.code !== 'ENOENT') throw e;
    raw = '[General]\n';
  }
  const next = editServerConfig(raw, 'General', { Map: level });
  await rotateConfigBackup();
  const tmp = BEAMMP_CFG_FILE + '.tmp';
  await fsp.writeFile(tmp, next, 'utf8');
  await fsp.rename(tmp, BEAMMP_CFG_FILE);
  insertAuditLog(actor, 'server.map.activate', level);
  const running = (beammpChild && !beammpChild.killed) || !!(await findBeamMPPid()) || (await getServerInfo()).running;
  let restarted = false;
  if (autoRestart && running) {
    try {
      await killBeamMP();
      await waitForBeamMPDown(6000);
      await sleep(500);
      const s = await spawnBeamMP();
      if (s.ok) { await waitForBeamMPUp(12000); restarted = true; }
    } catch (e) { log.warn('map activate auto-restart failed:', e.message); }
  }
  return { running, restarted };
}

async function apiMapsActivate(req, res) {
  if (!checkPermission(req, 'mapActivate')) return json(res, 403, { error: 'Forbidden' });
  if (!checkRateLimit('config-save', clientIp(req), 30, 60 * 1000))
    return json(res, 429, { error: 'Rate limit: too many config saves' });
  let body;
  try { body = await readBody(req); }
  catch (e) { return json(res, 400, { error: e.message }); }
  const level = String(body?.level || '').trim();
  if (!level) return json(res, 400, { error: 'level required' });
  // Validate against the vanilla list ∪ scanned custom list. Refuses arbitrary
  // strings so an attacker with serverConfig can't write a multi-line payload
  // into ServerConfig.toml via this endpoint (the line-edit serialiser already
  // quotes the value but we want defence-in-depth on the path shape).
  const customMaps = await enumerateCustomMaps();
  const allowed = new Set([
    ...VANILLA_MAPS_META.map(m => m.level),
    ...customMaps.map(m => m.level),
  ]);
  if (!allowed.has(level)) return json(res, 400, { error: 'Unknown map' });

  return withServerActionLock(req, res, async () => {
    const actor = checkAnyAuth(req)?.username || 'unknown';
    try {
      const { running, restarted } = await _doActivateMap(actor, level, { autoRestart: false });
      // Activation endpoint reports restartRequired but doesn't restart — the
      // frontend's MapModal pops a confirmation prompt before calling
      // /api/server/restart explicitly. Auto-rotation goes through
      // _doActivateMap directly with autoRestart:true (the whole point of
      // a rotation is that no one is in the chair to confirm).
      return json(res, 200, { ok: true, level, restartRequired: !!running, restarted });
    } catch (e) {
      insertAuditLog(actor, 'server.config.update.fail', '', e.message);
      return json(res, 500, { error: `Write failed: ${e.message}` });
    }
  });
}

// Map rotation: persists a config in panel_settings.map_rotation as JSON and
// runs an in-process timer that activates the next map in the list every
// intervalMin minutes (round-robin, with the index persisted so a panel
// restart resumes from where it was rather than rolling back to the start).
function _readMapRotation() {
  try {
    const row = db?.prepare(`SELECT value FROM panel_settings WHERE key = 'map_rotation'`).get();
    if (!row?.value) return null;
    return JSON.parse(row.value);
  } catch { return null; }
}
function _writeMapRotation(cfg) {
  if (!db) return;
  db.prepare(`INSERT INTO panel_settings (key, value) VALUES ('map_rotation', ?)
              ON CONFLICT(key) DO UPDATE SET value = excluded.value`)
    .run(JSON.stringify(cfg));
}

let _mapRotationTimer = null;
let _mapRotationLastRunMs = 0;
async function _tickMapRotation() {
  const cfg = _readMapRotation();
  if (!cfg || !cfg.enabled || !Array.isArray(cfg.maps) || cfg.maps.length < 2) return;
  const intervalMs = Math.max(1, cfg.intervalMin || 30) * 60 * 1000;
  const now = Date.now();
  const lastAt = cfg.lastAt || _mapRotationLastRunMs || 0;
  if (now - lastAt < intervalMs) return;
  // Pick the next map (round-robin) — skip whichever one matches the current
  // Map setting, so a manual change between rotations doesn't immediately
  // jump back to it on the next tick.
  const current = _readActiveMap();
  const idx = cfg.maps.indexOf(current);
  const nextIdx = ((idx >= 0 ? idx : -1) + 1) % cfg.maps.length;
  const nextLevel = cfg.maps[nextIdx];
  if (!nextLevel || nextLevel === current) return;
  try {
    const { restarted } = await _doActivateMap('map-rotation', nextLevel, { autoRestart: true });
    _mapRotationLastRunMs = now;
    _writeMapRotation({ ...cfg, lastAt: now });
    log.info(`map rotation: activated ${nextLevel}${restarted ? ' (restarted)' : ''}`);
  } catch (e) { log.warn('map rotation tick failed:', e.message); }
}
function startMapRotationTimer() {
  if (_mapRotationTimer) clearInterval(_mapRotationTimer);
  // Check every 30 s — the timer doesn't need minute precision, and a half-minute
  // delay between scheduled activation and actual activation is invisible to
  // operators (the rotation is on the scale of minutes-to-hours).
  _mapRotationTimer = setInterval(() => { _tickMapRotation().catch(() => {}); }, 30 * 1000);
}

// Restart scheduler: cron-simple "restart every day at HH:MM on these weekdays".
// Persisted in panel_settings.restart_schedule as JSON. The timer wakes once a
// minute, checks the current local time against the schedule, and fires the
// restart at most once per minute boundary (debounced via _lastScheduledRestart).
function _readRestartSchedule() {
  try {
    const row = db?.prepare(`SELECT value FROM panel_settings WHERE key = 'restart_schedule'`).get();
    if (!row?.value) return null;
    return JSON.parse(row.value);
  } catch { return null; }
}
function _writeRestartSchedule(cfg) {
  if (!db) return;
  db.prepare(`INSERT INTO panel_settings (key, value) VALUES ('restart_schedule', ?)
              ON CONFLICT(key) DO UPDATE SET value = excluded.value`)
    .run(JSON.stringify(cfg));
}
let _restartSchedulerTimer = null;
let _lastScheduledRestartKey = '';
async function _tickRestartScheduler() {
  const cfg = _readRestartSchedule();
  if (!cfg || !cfg.enabled) return;
  const hour = Math.max(0, Math.min(23, parseInt(cfg.hour, 10) || 0));
  const minute = Math.max(0, Math.min(59, parseInt(cfg.minute, 10) || 0));
  const days = Array.isArray(cfg.weekdays) && cfg.weekdays.length > 0 ? cfg.weekdays : [0,1,2,3,4,5,6];
  const now = new Date();
  if (!days.includes(now.getDay())) return;
  if (now.getHours() !== hour || now.getMinutes() !== minute) return;
  // Debounce: a minute window covers ~60 ticks of the 1s timer (we run at 60s
  // intervals so only 1 tick lands inside it, but make the guard explicit).
  const key = `${now.getFullYear()}-${now.getMonth()}-${now.getDate()}-${hour}-${minute}`;
  if (_lastScheduledRestartKey === key) return;
  _lastScheduledRestartKey = key;
  log.info(`scheduled restart: firing at ${now.toISOString()}`);
  insertAuditLog('restart-scheduler', 'server.restart.scheduled', key);
  try {
    const running = (beammpChild && !beammpChild.killed) || !!(await findBeamMPPid()) || (await getServerInfo()).running;
    if (!running) { log.info('scheduled restart: server not running, skipping'); return; }
    await killBeamMP();
    await waitForBeamMPDown(6000);
    await sleep(500);
    const s = await spawnBeamMP();
    if (s.ok) await waitForBeamMPUp(12000);
  } catch (e) { log.warn('scheduled restart failed:', e.message); }
}
function startRestartSchedulerTimer() {
  if (_restartSchedulerTimer) clearInterval(_restartSchedulerTimer);
  // Once-per-minute is the natural cadence (the schedule has minute resolution).
  _restartSchedulerTimer = setInterval(() => { _tickRestartScheduler().catch(() => {}); }, 60 * 1000);
}

// MOTD loop: periodic in-game broadcast of a configured message. Enqueues a
// `broadcast` command on commands.json every intervalMin minutes when enabled,
// piggybacking on PanelBridge's existing broadcast handler. Stops emitting
// when the server isn't running so we don't queue dead messages.
function _readMotdLoop() {
  try {
    const row = db?.prepare(`SELECT value FROM panel_settings WHERE key = 'motd_loop'`).get();
    if (!row?.value) return null;
    return JSON.parse(row.value);
  } catch { return null; }
}
function _writeMotdLoop(cfg) {
  if (!db) return;
  db.prepare(`INSERT INTO panel_settings (key, value) VALUES ('motd_loop', ?)
              ON CONFLICT(key) DO UPDATE SET value = excluded.value`)
    .run(JSON.stringify(cfg));
}
let _motdLoopTimer = null;
let _motdLoopLastAt = 0;
async function _tickMotdLoop() {
  const cfg = _readMotdLoop();
  if (!cfg || !cfg.enabled || !cfg.text) return;
  const intervalMs = Math.max(1, cfg.intervalMin || 15) * 60 * 1000;
  const now = Date.now();
  if (now - _motdLoopLastAt < intervalMs) return;
  // Skip if BeamMP-Server isn't running — broadcasting to nobody just pollutes
  // the commands.json queue (PanelBridge will keep replaying old commands if
  // the server's down for a while).
  const running = (beammpChild && !beammpChild.killed) || !!(await findBeamMPPid());
  if (!running) return;
  try {
    await _enqueueBridgeCommand({ action: 'broadcast', message: cfg.text });
    _motdLoopLastAt = now;
    insertAuditLog('motd-loop', 'chat.broadcast.motd', '', cfg.text.slice(0, 100));
  } catch (e) { log.warn('motd loop broadcast failed:', e.message); }
}
function startMotdLoopTimer() {
  if (_motdLoopTimer) clearInterval(_motdLoopTimer);
  _motdLoopTimer = setInterval(() => { _tickMotdLoop().catch(() => {}); }, 30 * 1000);
}

// BeamMP-Server version check: cached against GitHub's latest release tag.
// We compare against the running binary's reported `--version` so the panel
// can surface a "new version available" banner without nag-spamming GitHub
// (the cache is 6h, refreshed lazily when an authenticated request hits the
// endpoint). Failures are best-effort — if GitHub is unreachable or the
// binary doesn't expose --version, the banner just doesn't appear.
let _bmpVersionCache = null;
const VERSION_CACHE_TTL_MS = 6 * 60 * 60 * 1000;

function _parseSemver(s) {
  const m = String(s || '').match(/v?(\d+)\.(\d+)\.(\d+)/);
  if (!m) return null;
  return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)];
}
function _semverCmp(a, b) {
  if (!a || !b) return 0;
  for (let i = 0; i < 3; i++) {
    if (a[i] < b[i]) return -1;
    if (a[i] > b[i]) return 1;
  }
  return 0;
}
async function _getLocalBmpVersion() {
  try {
    const out = await new Promise((resolve, reject) => {
      const cp = require('child_process');
      const p = cp.spawn(BEAMMP_BIN, ['--version'], { timeout: 3000 });
      let buf = '';
      p.stdout.on('data', d => { buf += d.toString(); });
      p.stderr.on('data', d => { buf += d.toString(); });
      p.on('close', () => resolve(buf));
      p.on('error', reject);
    });
    const m = out.match(/v?(\d+\.\d+\.\d+)/);
    return m ? m[1] : null;
  } catch { return null; }
}
async function _getLatestBmpVersion() {
  return new Promise((resolve) => {
    const https = require('https');
    https.get({
      host: 'api.github.com', path: '/repos/BeamMP/BeamMP-Server/releases/latest',
      headers: { 'User-Agent': 'beamng-server-panel', 'Accept': 'application/vnd.github+json' },
      timeout: 5000,
    }, (resp) => {
      let body = '';
      resp.on('data', d => { body += d.toString(); });
      resp.on('end', () => {
        try {
          const json = JSON.parse(body);
          // Normalise tag — GitHub publishes "v3.9.3" but every consumer in
          // this codebase (banner template, semver comparator, toast) wants
          // the bare number. _getLocalBmpVersion already strips its 'v'; we
          // do the same here so the two sides agree and the banner doesn't
          // read "vv3.9.3" after a template adds its own prefix.
          const tag = json.tag_name ? String(json.tag_name).replace(/^v/i, '') : null;
          resolve({ tag, htmlUrl: json.html_url || null, publishedAt: json.published_at || null });
        } catch { resolve({ tag: null }); }
      });
    }).on('error', () => resolve({ tag: null })).on('timeout', () => resolve({ tag: null }));
  });
}
// BeamMP-specific KPIs for the Dashboard's second row. Pure read endpoint.
async function apiDashboardExtra(req, res) {
  if (!checkAnyAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  // Active map: parse from ServerConfig.toml and resolve to display metadata.
  // Two paths: vanilla maps come from VANILLA_MAPS_META (bundled with the
  // panel, thumbnail is /src/assets/maps/<id>.jpg); custom maps come from
  // enumerateCustomMaps() which reads each Resources/Client/*.zip's
  // levels/<X>/info.json and ships the modder's title + a hasPreview flag
  // that points at /api/maps/preview/<source>/<levelName>. The Dashboard
  // tile uses the same /api/maps/preview URL the Maps catalogue card uses,
  // so the active-map thumbnail and the catalogue thumbnail stay in sync.
  const activeMapLevel = _readActiveMap();
  const activeMapMeta = VANILLA_MAPS_META.find(m => m.level === activeMapLevel);
  let activeMapName = activeMapMeta ? activeMapMeta.name : null;
  let activeMapNameEs = activeMapMeta ? (activeMapMeta.nameEs || activeMapMeta.name) : null;
  let activeMapId = activeMapMeta ? activeMapMeta.id : null;
  let activeMapTheme = activeMapMeta ? activeMapMeta.theme : null;
  let activeMapCustom = null;
  if (!activeMapMeta && activeMapLevel) {
    try {
      const customs = await enumerateCustomMaps();
      const m = customs.find(c => c.level === activeMapLevel);
      if (m) {
        activeMapName = m.name;          // modder-supplied title from info.json
        activeMapTheme = m.theme || 'custom';
        activeMapCustom = {
          source: m.source,
          levelName: m.levelName,
          hasPreview: !!m.hasPreview,
        };
      } else {
        // Map activated but its .zip is missing from Resources/Client — fall
        // back to the directory name so the tile shows something legible.
        activeMapName = activeMapLevel.replace(/^\/levels\/|\/info\.json$/g, '');
      }
    } catch { /* enumerate failed — silent fallback */ }
    if (!activeMapName) activeMapName = activeMapLevel.replace(/^\/levels\/|\/info\.json$/g, '');
  }
  // Total joins today (from player_events, action='join').
  let joinsToday = 0;
  try {
    const row = db?.prepare(`
      SELECT COUNT(*) AS n FROM player_events
      WHERE action='join' AND event_at >= datetime('now', '-1 day')`).get();
    joinsToday = row?.n || 0;
  } catch {}
  // Disk used by Resources/ (capped at 5 GB walk to bound the cost).
  let resourcesBytes = 0;
  try { resourcesBytes = await _dirSizeBytes(BEAMMP_RESOURCES_DIR); } catch {}
  // BMP binary version from the cache (no fresh shell-out — apiServerVersionCheck
  // refreshes it on its own 6 h cadence).
  const bmpVersion = _bmpVersionCache?.data?.local || null;
  return json(res, 200, {
    activeMapLevel: activeMapLevel || null,
    activeMapName: activeMapName || null,
    activeMapNameEs: activeMapNameEs || null,
    activeMapId: activeMapId || null,
    activeMapTheme: activeMapTheme || null,
    activeMapCustom,
    joinsToday,
    resourcesBytes,
    bmpVersion,
  });
}

// Settings export: download the live ServerConfig.toml as an attachment with
// the AuthKey value redacted to a placeholder. Operators use this for backup
// (versioning the config) and for cross-host migration (paste into a fresh
// install). The AuthKey redaction is mandatory — sharing a TOML with the key
// intact is the same as handing over server ownership to whoever sees it.
function apiConfigExport(req, res) {
  if (!checkPermission(req, 'serverConfig')) return json(res, 403, { error: 'Forbidden' });
  let raw;
  try { raw = fs.readFileSync(BEAMMP_CFG_FILE, 'utf8'); }
  catch (e) {
    if (e.code === 'ENOENT') return json(res, 404, { error: 'No ServerConfig.toml on disk' });
    return json(res, 500, { error: e.message });
  }
  // Redact AuthKey line in-place — preserves the rest of the file as-is so
  // an operator round-tripping (export → import) doesn't lose comments or
  // key ordering. The placeholder is recognised by the import path and left
  // untouched when reapplying (so a missing key stays missing).
  const redacted = raw.replace(/^(AuthKey\s*=\s*)"([^"]*)"/m, (_, prefix) => `${prefix}"<REDACTED-PASTE-NEW-KEY-HERE>"`);
  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
  res.setHeader('Content-Type', 'application/toml; charset=utf-8');
  res.setHeader('Content-Disposition', `attachment; filename="ServerConfig.${stamp}.toml"`);
  res.end(redacted);
  insertAuditLog(checkAnyAuth(req)?.username || 'unknown', 'server.config.export', '');
}

// Settings import: accept a TOML payload (multipart/form-data field `file`
// OR raw text/plain body), parse it, and apply the [General] keys via the
// existing _validateTomlUpdates pipeline so the same per-key validation and
// audit logging applies. AuthKey is special-cased: the redaction placeholder
// from /export is ignored (the existing key stays in place), any other value
// is applied as-is.
async function apiConfigImport(req, res) {
  if (!checkPermission(req, 'serverConfig')) return json(res, 403, { error: 'Forbidden' });
  // Read body as raw text — the frontend POSTs text/plain to keep things
  // simple. We cap at 64 KB (ServerConfig.toml is normally < 4 KB; this is
  // generous slack for operators with heavy commenting).
  let raw;
  try {
    const chunks = [];
    let total = 0;
    for await (const chunk of req) {
      total += chunk.length;
      if (total > 64 * 1024) return json(res, 413, { error: 'Payload too large (max 64 KB)' });
      chunks.push(chunk);
    }
    raw = Buffer.concat(chunks).toString('utf8');
  } catch (e) { return json(res, 400, { error: 'Cannot read body: ' + e.message }); }
  if (!raw.trim()) return json(res, 400, { error: 'Empty payload' });
  let parsed;
  try { parsed = parseServerConfig(raw); }
  catch (e) { return json(res, 400, { error: 'Not valid TOML: ' + e.message }); }
  const general = parsed.sections?.General;
  if (!general || typeof general !== 'object') return json(res, 400, { error: 'Missing [General] section' });
  // Strip the AuthKey placeholder so the current secret stays in place.
  if (general.AuthKey === '<REDACTED-PASTE-NEW-KEY-HERE>') delete general.AuthKey;
  const v = _validateTomlUpdates(general);
  if (v.error) return json(res, 400, { error: 'Validation: ' + v.error });
  if (Object.keys(v.cleaned).length === 0) return json(res, 400, { error: 'No valid keys to import' });
  return withServerActionLock(req, res, async () => {
    const actor = checkAnyAuth(req)?.username || 'unknown';
    let existing;
    try { existing = fs.readFileSync(BEAMMP_CFG_FILE, 'utf8'); } catch { existing = '[General]\n'; }
    let next;
    try { next = editServerConfig(existing, 'General', v.cleaned); }
    catch (e) { return json(res, 500, { error: 'Cannot serialise: ' + e.message }); }
    try {
      await rotateConfigBackup();
      const tmp = BEAMMP_CFG_FILE + '.tmp';
      await fsp.writeFile(tmp, next, 'utf8');
      await fsp.rename(tmp, BEAMMP_CFG_FILE);
    } catch (e) {
      insertAuditLog(actor, 'server.config.import.fail', '', e.message);
      return json(res, 500, { error: 'Write failed: ' + e.message });
    }
    const keysChanged = Object.keys(v.cleaned).sort().join(',');
    insertAuditLog(actor, 'server.config.import', keysChanged);
    return json(res, 200, { ok: true, applied: Object.keys(v.cleaned) });
  });
}

// One-shot binary updater. Downloads the BeamMP-Server asset matching the
// host's distro/arch from the latest GitHub release, replaces the running
// binary atomically (with a .bak so we can roll back if the new one is
// busted), restarts the server if it was running, and audit-logs the change.
//
// Risk model: replacing the binary is destructive but recoverable — we keep
// the previous binary as <bin>.bak; if the new one doesn't report --version
// we rollback before anyone notices. Concurrency: a process-wide flag stops
// two simultaneous calls; concurrent operators would otherwise race on the
// rename and one of them ends up with a half-copied binary.
let _binaryUpdateInProgress = false;

// Maps /etc/os-release + process.arch onto the BeamMP-Server release asset
// naming convention. Known shapes (as of release v3.9.3): debian 12/13,
// ubuntu 22.04/24.04, in x86_64 + arm64. Returns null if the host doesn't
// match any of those — we'd rather refuse the update than ship the wrong
// libc-linked binary.
function _detectLinuxAsset() {
  if (process.platform !== 'linux') return null;
  let id = null, versionId = null;
  try {
    const raw = fs.readFileSync('/etc/os-release', 'utf8');
    const idM = raw.match(/^ID=("?)([A-Za-z]+)\1/m);
    const vM  = raw.match(/^VERSION_ID=("?)([\d.]+)\1/m);
    if (idM) id        = idM[2].toLowerCase();
    if (vM)  versionId = vM[2];
  } catch { return null; }
  if (!id || !versionId) return null;
  const arch = process.arch === 'x64' ? 'x86_64'
             : process.arch === 'arm64' ? 'arm64'
             : null;
  if (!arch) return null;
  const known = { debian: ['12', '13'], ubuntu: ['22.04', '24.04'] };
  if (!known[id]) return null;
  // Exact-match if possible; otherwise pick the highest known version <= ours.
  // Ubuntu reports point releases like "24.04.4" — we trim to "major.minor"
  // before matching since BeamMP publishes one asset per LTS series.
  let v = versionId;
  if (!known[id].includes(versionId)) {
    if (id === 'ubuntu') {
      const mm = versionId.match(/^(\d+)\.(\d+)/);
      if (!mm) return null;
      const candidate = `${mm[1]}.${mm[2]}`;
      if (known[id].includes(candidate)) v = candidate;
      else {
        const ours = parseFloat(candidate);
        const sorted = known[id].map(parseFloat).sort((a, b) => b - a);
        const match = sorted.find(x => x <= ours);
        if (match == null) return null;
        v = match.toFixed(2);
      }
    } else if (id === 'debian') {
      const ours = parseInt(versionId, 10);
      if (!Number.isFinite(ours)) return null;
      const sorted = known[id].map(n => parseInt(n, 10)).sort((a, b) => b - a);
      const match = sorted.find(x => x <= ours);
      if (match == null) return null;
      v = String(match);
    } else return null;
  }
  return `BeamMP-Server.${id}.${v}.${arch}`;
}

async function _getLatestReleaseMeta() {
  return new Promise((resolve) => {
    const https = require('https');
    https.get({
      host: 'api.github.com',
      path: '/repos/BeamMP/BeamMP-Server/releases/latest',
      headers: { 'User-Agent': 'beamng-server-panel', 'Accept': 'application/vnd.github+json' },
      timeout: 5000,
    }, (resp) => {
      let body = '';
      resp.on('data', d => { body += d.toString(); });
      resp.on('end', () => { try { resolve(JSON.parse(body)); } catch { resolve(null); } });
    }).on('error', () => resolve(null)).on('timeout', () => resolve(null));
  });
}

// Streaming HTTPS download with redirect-follow. GitHub release downloads
// redirect at least once (api → objects.githubusercontent.com) and sometimes
// chain through codeload too, so we cap at 5 hops. Size check is mandatory:
// a short-read with no error would otherwise leave a truncated binary in
// place after rename, and BeamMP-Server's --version would still appear to
// work for some prefixes — we'd only find out on first connect.
function _downloadToFile(url, dest, expectedSize) {
  return new Promise((resolve) => {
    const https = require('https');
    const tryGet = (u, hops) => {
      if (hops > 5) return resolve({ ok: false, error: 'Too many redirects' });
      let parsed;
      try { parsed = new URL(u); } catch { return resolve({ ok: false, error: 'Bad URL' }); }
      const req = https.get({
        host: parsed.hostname,
        path: parsed.pathname + parsed.search,
        headers: { 'User-Agent': 'beamng-server-panel', 'Accept': 'application/octet-stream' },
        timeout: 30000,
      }, (resp) => {
        if (resp.statusCode >= 300 && resp.statusCode < 400 && resp.headers.location) {
          resp.resume();
          return tryGet(resp.headers.location, hops + 1);
        }
        if (resp.statusCode !== 200) {
          resp.resume();
          return resolve({ ok: false, error: `HTTP ${resp.statusCode}` });
        }
        const out = fs.createWriteStream(dest);
        let bytes = 0;
        resp.on('data', d => { bytes += d.length; });
        resp.pipe(out);
        out.on('finish', () => {
          out.close(() => {
            if (expectedSize && bytes !== expectedSize) {
              return resolve({ ok: false, error: `Size mismatch: got ${bytes}, expected ${expectedSize}` });
            }
            resolve({ ok: true, bytes });
          });
        });
        out.on('error', e => resolve({ ok: false, error: e.message }));
        resp.on('error', e => resolve({ ok: false, error: e.message }));
      });
      req.on('error', e => resolve({ ok: false, error: e.message }));
      req.on('timeout', () => { try { req.destroy(); } catch {} resolve({ ok: false, error: 'Download timeout' }); });
    };
    tryGet(url, 0);
  });
}

async function apiServerUpdateBinary(req, res) {
  if (!checkPermission(req, 'serverControl')) return json(res, 403, { error: 'Forbidden' });
  if (_binaryUpdateInProgress) return json(res, 409, { error: 'An update is already in progress' });
  _binaryUpdateInProgress = true;
  const actor = checkAnyAuth(req)?.username || 'unknown';
  const targetDir = path.dirname(BEAMMP_BIN);
  const tmpPath   = path.join(targetDir, `BeamMP-Server.new.${Date.now()}.${process.pid}`);
  const bakPath   = `${BEAMMP_BIN}.bak`;
  try {
    const assetName = _detectLinuxAsset();
    if (!assetName) {
      return json(res, 400, {
        error: 'Cannot auto-pick a BeamMP-Server asset for this host. The release publishes binaries for Debian 12/13 and Ubuntu 22.04/24.04 (x86_64 + arm64) — replace the binary manually if you run a different distro.',
      });
    }
    const meta = await _getLatestReleaseMeta();
    if (!meta || !Array.isArray(meta.assets)) return json(res, 502, { error: 'Could not fetch latest release metadata from GitHub' });
    const asset = meta.assets.find(a => a.name === assetName);
    if (!asset || !asset.browser_download_url) return json(res, 404, { error: `Latest release does not include asset ${assetName}` });

    // Are we already on this tag? If yes, refuse — re-downloading the same
    // binary is almost always a misclick, and the disruption (stop + start)
    // is real.
    const localBefore = await _getLocalBmpVersion();
    if (localBefore && meta.tag_name) {
      const localSv  = _parseSemver(localBefore);
      const remoteSv = _parseSemver(meta.tag_name);
      if (localSv && remoteSv && _semverCmp(localSv, remoteSv) >= 0) {
        return json(res, 200, { ok: true, alreadyLatest: true, local: localBefore, latest: meta.tag_name });
      }
    }

    // 1. download
    const dl = await _downloadToFile(asset.browser_download_url, tmpPath, asset.size);
    if (!dl.ok) {
      try { await fsp.unlink(tmpPath); } catch {}
      return json(res, 502, { error: `Download failed: ${dl.error}` });
    }
    await fsp.chmod(tmpPath, 0o755);

    // 2. stop running server (panel-spawned OR adopted via pgrep)
    const wasRunning = (beammpChild && !beammpChild.killed) || !!(await findBeamMPPid());
    if (wasRunning) {
      await killBeamMP();
      await waitForBeamMPDown(8000);
    }

    // 3. backup current binary, then move new into place. If anything below
    // throws we restore from .bak before returning the error.
    let hadCurrent = false;
    try {
      const st = await fsp.stat(BEAMMP_BIN);
      if (st.isFile()) {
        hadCurrent = true;
        await fsp.rename(BEAMMP_BIN, bakPath);
      }
    } catch (e) { if (e.code !== 'ENOENT') throw e; }

    try {
      await fsp.rename(tmpPath, BEAMMP_BIN);
    } catch (e) {
      if (hadCurrent) { try { await fsp.rename(bakPath, BEAMMP_BIN); } catch {} }
      try { await fsp.unlink(tmpPath); } catch {}
      return json(res, 500, { error: `Failed to move new binary into place: ${e.message}` });
    }

    // 4. verify the new binary reports a version. Anything else means we got
    // a corrupted / wrong-arch download; roll back.
    const newVer = await _getLocalBmpVersion();
    if (!newVer) {
      try { await fsp.unlink(BEAMMP_BIN); } catch {}
      if (hadCurrent) { try { await fsp.rename(bakPath, BEAMMP_BIN); } catch {} }
      return json(res, 500, { error: 'New binary does not report --version; rolled back to previous version' });
    }

    // 5. restart server if it was running before. We don't fail the whole
    // update if the restart times out — the binary is in place and the next
    // manual start will use it.
    let restarted = false;
    if (wasRunning) {
      try {
        await sleep(500);
        const s = await spawnBeamMP();
        if (s.ok) { await waitForBeamMPUp(12000); restarted = true; }
      } catch {}
    }

    // 6. flush the version cache so the banner immediately reflects the new
    // state instead of waiting up to 6 h for the next refresh.
    _bmpVersionCache = null;

    insertAuditLog(actor, 'server.binary.update', `${localBefore || '?'} → ${newVer} (asset=${asset.name})`);
    return json(res, 200, {
      ok: true,
      asset: asset.name,
      previousVersion: localBefore || null,
      newVersion: newVer,
      tag: meta.tag_name ? String(meta.tag_name).replace(/^v/i, '') : null,
      wasRunning,
      restarted,
    });
  } catch (e) {
    try { await fsp.unlink(tmpPath); } catch {}
    return json(res, 500, { error: e.message });
  } finally {
    _binaryUpdateInProgress = false;
  }
}

async function apiServerVersionCheck(req, res) {
  if (!checkAnyAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  const now = Date.now();
  if (_bmpVersionCache && now - _bmpVersionCache.checkedAt < VERSION_CACHE_TTL_MS) {
    return json(res, 200, _bmpVersionCache.data);
  }
  const [local, remote] = await Promise.all([_getLocalBmpVersion(), _getLatestBmpVersion()]);
  const localSv = _parseSemver(local);
  const remoteSv = _parseSemver(remote.tag);
  const data = {
    local: local || null,
    latest: remote.tag || null,
    updateAvailable: !!(localSv && remoteSv && _semverCmp(localSv, remoteSv) < 0),
    releaseUrl: remote.htmlUrl || null,
    publishedAt: remote.publishedAt || null,
    checkedAt: now,
  };
  _bmpVersionCache = { checkedAt: now, data };
  return json(res, 200, data);
}

function apiMotdLoop(req, res) {
  if (!checkPermission(req, 'playerModeration')) return json(res, 403, { error: 'Forbidden' });
  const cfg = _readMotdLoop() || { enabled: false, text: '', intervalMin: 15 };
  return json(res, 200, cfg);
}
async function apiMotdLoopUpdate(req, res) {
  if (!checkPermission(req, 'playerModeration')) return json(res, 403, { error: 'Forbidden' });
  let body;
  try { body = await readBody(req); }
  catch (e) { return json(res, 400, { error: e.message }); }
  const enabled = !!body?.enabled;
  const text = (typeof body?.text === 'string' ? body.text : '').slice(0, 500).trim();
  const intervalMin = Math.max(1, Math.min(1440, parseInt(body?.intervalMin || 15, 10) || 15));
  const cfg = { enabled, text, intervalMin };
  _writeMotdLoop(cfg);
  const actor = checkAnyAuth(req)?.username || 'unknown';
  insertAuditLog(actor, 'chat.broadcast.motd.config', `enabled=${enabled} interval=${intervalMin}`);
  return json(res, 200, { ok: true, ...cfg });
}

function apiRestartSchedule(req, res) {
  if (!checkPermission(req, 'serverControl')) return json(res, 403, { error: 'Forbidden' });
  const cfg = _readRestartSchedule() || { enabled: false, hour: 6, minute: 0, weekdays: [0,1,2,3,4,5,6] };
  return json(res, 200, cfg);
}
async function apiRestartScheduleUpdate(req, res) {
  if (!checkPermission(req, 'serverControl')) return json(res, 403, { error: 'Forbidden' });
  let body;
  try { body = await readBody(req); }
  catch (e) { return json(res, 400, { error: e.message }); }
  const enabled = !!body?.enabled;
  const hour = Math.max(0, Math.min(23, parseInt(body?.hour, 10) || 0));
  const minute = Math.max(0, Math.min(59, parseInt(body?.minute, 10) || 0));
  const weekdays = Array.isArray(body?.weekdays)
    ? body.weekdays.map(n => parseInt(n, 10)).filter(n => n >= 0 && n <= 6)
    : [0,1,2,3,4,5,6];
  const cfg = { enabled, hour, minute, weekdays };
  _writeRestartSchedule(cfg);
  const actor = checkAnyAuth(req)?.username || 'unknown';
  insertAuditLog(actor, 'server.restart.schedule', `enabled=${enabled} ${String(hour).padStart(2,'0')}:${String(minute).padStart(2,'0')} days=${weekdays.join(',')}`);
  return json(res, 200, { ok: true, ...cfg });
}

function apiMapsRotation(req, res) {
  if (!checkPermission(req, 'serverConfig')) return json(res, 403, { error: 'Forbidden' });
  const cfg = _readMapRotation() || { enabled: false, maps: [], intervalMin: 30, lastAt: 0 };
  return json(res, 200, cfg);
}
async function apiMapsRotationUpdate(req, res) {
  if (!checkPermission(req, 'serverConfig')) return json(res, 403, { error: 'Forbidden' });
  let body;
  try { body = await readBody(req); }
  catch (e) { return json(res, 400, { error: e.message }); }
  const enabled = !!body?.enabled;
  const intervalMin = Math.max(1, Math.min(1440, parseInt(body?.intervalMin || 30, 10) || 30));
  const maps = Array.isArray(body?.maps) ? body.maps.filter(s => typeof s === 'string' && s.startsWith('/levels/')) : [];
  // Validate every entry against the known map set so this endpoint can't be
  // used to seed arbitrary paths that the auto-activation will later write
  // into ServerConfig.toml.
  const customMaps = await enumerateCustomMaps();
  const allowed = new Set([
    ...VANILLA_MAPS_META.map(m => m.level),
    ...customMaps.map(m => m.level),
  ]);
  const cleanMaps = maps.filter(m => allowed.has(m));
  const prev = _readMapRotation() || {};
  const next = { enabled, maps: cleanMaps, intervalMin, lastAt: prev.lastAt || 0 };
  _writeMapRotation(next);
  const actor = checkAnyAuth(req)?.username || 'unknown';
  insertAuditLog(actor, 'server.map.rotation', `enabled=${enabled} count=${cleanMaps.length} interval=${intervalMin}`);
  return json(res, 200, { ok: true, ...next });
}

// ── Live player state via PanelBridge Lua plugin ─────────────────────────────
// The plugin (tools/beammp-plugin/PanelBridge) writes Resources/Server/
// PanelBridge/state.json on every join, every disconnect and every 5 s as
// a heartbeat. We watch the file with fs.watch + a 5 s safety-net poll,
// parse it, diff against the in-memory map, and emit player_events rows
// for each transition we detect. The map is the source of truth for
// /api/players; the SQLite table is the source of truth for
// /api/players/history.
//
// When the plugin is NOT installed (no state.json appears) both lists
// stay empty — the panel boots fine, the Players page just shows the
// empty state. docs/live-state.md walks operators through the install.
const _connectedPlayers = new Map(); // id (string) → { name, isGuest, identifiers, joinedAt }
let _lastBridgeMtime = 0;
let _bridgeWatcher = null;

function _logBridge(level, ...args) { log[level]('[PanelBridge]', ...args); }

// Derive a stable identifier from the BeamMP-Server identifiers blob the
// plugin ships in state.json. The numeric `id` field BeamMP gives us is just
// a per-session slot number (0, 1, 2…) that gets re-handed-out as players
// disconnect and new ones join — so persisting it as the canonical player_id
// collapses every guest that ever held slot 0 into a single DB row, which is
// the bug this helper exists to prevent. Priority:
//   1. `identifiers.beammp` — authoritative forum UID for registered users.
//      Stable across sessions, IPs, and name changes. Format: "bmp:<uid>".
//   2. `identifiers.ip` — for guests (and anyone without a forum UID) the IP
//      is the only stable signal BeamMP hands the server. BeamMP assigns each
//      guest a session-random handle like "guest8099544" that RE-ROLLS every
//      time the client relaunches the game, so keying on the name spawns a
//      fresh row per session — the exact duplication this build is meant to
//      avoid while forum registration is disabled. Keying on IP collapses a
//      returning guest back onto one row. Format: "ip:<ip>". Trade-off the
//      operator has accepted: two distinct people behind the same public IP
//      (one household / CGNAT) merge into a single entry, and a dynamic IP
//      that the ISP rotates eventually spawns a new row — but that drifts on
//      a weeks/months cadence, vs. the per-relaunch churn of guest names. The
//      manual-merge tool (apiPlayersMerge) cleans up whatever residual drift
//      this leaves. When BeamMP re-enables registration, the bmp: branch
//      above takes over for anyone who logs in and this never fires for them.
//   3. Guest with `p.name` but no IP — shouldn't happen (the bridge always
//      ships an ip), but keeps a nameless-IP guest in the catalogue rather
//      than dropping them. Format: "guest:<name>".
//   4. `p.name` for any non-guest without a BeamMP UID or IP. Format: "named:<name>".
//   5. slot id — absolute last resort. Format: "slot:<n>:<name>". Same
//      collision-prone shape we'd get from raw slot reuse, but better than
//      no entry at all.
// Returns null only if `p` itself is unusable.
function _stableIdFor(p) {
  if (!p) return null;
  const ids = (p && p.identifiers && typeof p.identifiers === 'object') ? p.identifiers : {};
  if (ids.beammp) return `bmp:${ids.beammp}`;
  if (ids.ip) return `ip:${ids.ip}`;
  if (p.isGuest && p.name) return `guest:${p.name}`;
  if (p.name) return `named:${p.name}`;
  if (p.id !== undefined && p.id !== null) return `slot:${p.id}:${p.name || ''}`;
  return null;
}

function _persistPlayerEvent(id, name, action, identifiers) {
  if (!db) return;
  try {
    db.prepare(`
      INSERT INTO player_events (player_id, player_name, action, identifiers, event_at)
      VALUES (?, ?, ?, ?, datetime('now'))
    `).run(String(id), String(name || ''), action, JSON.stringify(identifiers || {}));
  } catch (e) { _logBridge('warn', 'persist event failed:', e.message); }
}

// Mirror of AC's UDP NEW_CONNECTION upsert: keep the canonical players table
// synced on every join so Whitelist/Ban/nickname buttons light up on the first
// connection and the history view shows the player even before they leave.
// INSERT OR IGNORE first to seed first_seen for new ids, then UPDATE name +
// last_seen so a returning player picks up their latest in-game name without
// clobbering first_seen.
function _persistPlayerJoin(id, name) {
  if (!db) return;
  try {
    db.prepare(`
      INSERT OR IGNORE INTO players (id, name, first_seen, last_seen)
      VALUES (?, ?, datetime('now'), datetime('now'))
    `).run(String(id), String(name || ''));
    db.prepare(`UPDATE players SET name = ?, last_seen = datetime('now') WHERE id = ?`)
      .run(String(name || ''), String(id));
  } catch (e) { _logBridge('warn', 'player upsert failed:', e.message); }
}

function _consumeBridgeState() {
  // Read state.json, parse, diff vs _connectedPlayers, emit events.
  let raw;
  try { raw = fs.readFileSync(BEAMMP_PLUGIN_STATE_FILE, 'utf8'); }
  catch (e) {
    if (e.code === 'ENOENT') return; // plugin not installed → silent
    _logBridge('warn', 'read failed:', e.message);
    return;
  }
  let parsed;
  try { parsed = JSON.parse(raw); }
  catch (e) { _logBridge('warn', 'bad JSON in state.json:', e.message); return; }

  const players = Array.isArray(parsed.players) ? parsed.players : [];
  const seen = new Set();
  for (const p of players) {
    if (p == null || (p.id === undefined && p.name === undefined)) continue;
    const stableId = _stableIdFor(p);
    if (!stableId) continue;
    // slotId stays alongside as the live-session number BeamMP-Server uses
    // for MP.DropPlayer; we resolve from stableId → slotId on every kick
    // so the panel + audit log + bans table all see the durable identifier
    // while the plugin still gets the slot it needs to act on the player.
    const slotId = (p.id !== undefined && p.id !== null) ? Number(p.id) : null;
    seen.add(stableId);
    // Update slotId on every tick even for already-tracked players — BeamMP
    // re-orders slots when someone disconnects, so the same stableId might
    // map to slot 0 on Monday and slot 2 on Tuesday.
    const existing = _connectedPlayers.get(stableId);
    if (existing) {
      existing.slotId = slotId;
      existing.name = String(p.name || existing.name);
    } else {
      _connectedPlayers.set(stableId, {
        slotId,
        name: String(p.name || ''),
        isGuest: !!p.isGuest,
        identifiers: p.identifiers || {},
        joinedAt: Date.now(),
      });
      _persistPlayerEvent(stableId, p.name, 'join', p.identifiers);
      _persistPlayerJoin(stableId, p.name);
    }
  }
  for (const [stableId, cur] of [..._connectedPlayers]) {
    if (!seen.has(stableId)) {
      _connectedPlayers.delete(stableId);
      _persistPlayerEvent(stableId, cur.name, 'leave', cur.identifiers);
    }
  }
}

function startPlayerBridgeWatcher() {
  // fs.watch fires on rename/write; poll every 5 s as a safety net for the
  // platforms where fs.watch silently drops events (network filesystems,
  // some Docker volume drivers, atomic rename-over-write under inotify).
  const flush = () => {
    let mtime = 0;
    try { mtime = fs.statSync(BEAMMP_PLUGIN_STATE_FILE).mtimeMs; }
    catch { return; }
    if (mtime === _lastBridgeMtime) return;
    _lastBridgeMtime = mtime;
    _consumeBridgeState();
  };
  // Initial read so we don't lose the first heartbeat after the panel boots.
  flush();
  try {
    _bridgeWatcher = fs.watch(BEAMMP_PLUGIN_BRIDGE_DIR, { persistent: false }, flush);
  } catch {
    // Plugin directory doesn't exist yet (plugin not installed). The
    // safety-net poll below still picks up state.json if it appears later.
  }
  setInterval(flush, 5000).unref();
}

// Write commands.json atomically. The plugin polls every 5 s, so a write
// may not be picked up for up to that long — the response carries
// `queued: true` to clarify this is fire-and-forget, not synchronous.
async function _enqueueBridgeCommand(cmd) {
  let existing = [];
  try {
    const raw = await fsp.readFile(BEAMMP_PLUGIN_COMMANDS_FILE, 'utf8');
    const parsed = JSON.parse(raw);
    if (Array.isArray(parsed)) existing = parsed;
  } catch (e) {
    if (e.code !== 'ENOENT') _logBridge('warn', 'read commands.json:', e.message);
  }
  existing.push(cmd);
  await fsp.mkdir(BEAMMP_PLUGIN_BRIDGE_DIR, { recursive: true });
  const tmp = BEAMMP_PLUGIN_COMMANDS_FILE + '.tmp';
  try {
    await fsp.writeFile(tmp, JSON.stringify(existing), 'utf8');
    await fsp.rename(tmp, BEAMMP_PLUGIN_COMMANDS_FILE);
  } finally {
    // If rename succeeded, tmp is already gone — unlink() is a no-op.
    // If rename failed (cross-device link, ENOSPC mid-write, plugin dir
    // deleted between mkdir and rename, …) tmp is left behind and would
    // accumulate on every retry. Best-effort cleanup keeps the dir tidy.
    await fsp.unlink(tmp).catch(() => {});
  }
}

// Publish the current effective ban list to the plugin so onPlayerAuth in
// main.lua can refuse re-connections without the panel having to babysit
// every join. The plugin reads this file on every join attempt; it lives
// alongside state.json / chat.json / commands.json in the bridge directory.
//
// We filter expired bans here (not in the plugin) so the plugin stays
// minimal — it just decides "is this id in the list" without doing time
// math. The shape is { ts, bans: { <id>: { name, reason, expires_at } } }
// so the plugin can echo the operator-provided reason back to the client
// as the kick message, instead of a generic "banned".
async function _publishBans() {
  if (!db) return;
  let rows = [];
  try {
    const nowIso = new Date().toISOString().replace('T', ' ').slice(0, 19);
    rows = db.prepare(`
      SELECT id, name, reason, expires_at
      FROM bans
      WHERE expires_at IS NULL OR expires_at > ?
    `).all(nowIso);
  } catch (e) {
    _logBridge('warn', 'read bans for publish:', e.message);
    return;
  }
  const obj = {};
  for (const r of rows) {
    const rec = { name: r.name || '', reason: r.reason || '', expires_at: r.expires_at };
    // Primary key — the prefixed stable id ("bmp:12345" / "ip:1.2.3.4"). A
    // future plugin version that knows about the prefix scheme would match
    // by constructing "<type>:<value>" itself.
    obj[r.id] = rec;
    // Secondary key — the same record under the raw identifier value, so
    // the current PanelBridge plugin (which iterates identifiers without
    // building any prefix) still catches the ban via its existing
    // bans[value] lookup. Cheap aliasing — the payload is small even with
    // a few hundred bans, and it keeps the plugin contract stable across
    // this server-side rename.
    const colon = r.id.indexOf(':');
    if (colon > 0) {
      const raw = r.id.slice(colon + 1);
      if (raw && !obj[raw]) obj[raw] = rec;
    }
  }
  const payload = { ts: Math.floor(Date.now() / 1000), bans: obj };
  await fsp.mkdir(BEAMMP_PLUGIN_BRIDGE_DIR, { recursive: true }).catch(() => {});
  const tmp = BEAMMP_PLUGIN_BANS_FILE + '.tmp';
  try {
    await fsp.writeFile(tmp, JSON.stringify(payload), 'utf8');
    await fsp.rename(tmp, BEAMMP_PLUGIN_BANS_FILE);
  } catch (e) {
    _logBridge('warn', 'publish bans.json:', e.message);
  } finally {
    await fsp.unlink(tmp).catch(() => {});
  }
}

// ── Map voting (PanelBridge v4) ─────────────────────────────────────────────
// The plugin handles the in-chat voting state machine and writes:
//   - vote_state.json on every transition (open / ballot change / close)
//   - vote_result.json one-shot when a vote closes with quorum reached
// The panel reads both: vote_state.json for the live Dashboard card, and
// vote_result.json to trigger the announce-then-activate-then-restart flow
// using the same _doActivateMap primitive the Maps page uses.
//
// Config (durationSec / quorumPercent / minVotes / countdownSec /
// suggestIntervalSec / allowedMaps) is persisted in panel_settings under
// key 'vote_config' and re-published to vote_config.json whenever it
// changes, so the plugin reads it fresh on every tick without the operator
// having to reload anything.

const VOTE_DEFAULTS = {
  enabled:            true,
  durationSec:        60,
  quorumPercent:      50,
  minVotes:           2,
  countdownSec:       30,
  suggestIntervalSec: 600,
  allowedMaps:        [],   // empty = any level (plugin accepts unrestricted)
};

function _getVoteConfig() {
  // Hardcoded defaults first, then overlay whatever's in panel_settings.
  // We re-validate every field on read so a stale row from an older deploy
  // can't sneak in an unknown shape.
  const out = { ...VOTE_DEFAULTS };
  if (!db) return out;
  try {
    const row = db.prepare(`SELECT value FROM panel_settings WHERE key = 'vote_config'`).get();
    if (!row || !row.value) return out;
    const parsed = JSON.parse(row.value);
    if (parsed.enabled            != null) out.enabled            = !!parsed.enabled;
    if (Number.isFinite(parsed.durationSec))        out.durationSec        = Math.max(15, Math.min(600, parsed.durationSec));
    if (Number.isFinite(parsed.quorumPercent))      out.quorumPercent      = Math.max(0, Math.min(100, parsed.quorumPercent));
    if (Number.isFinite(parsed.minVotes))           out.minVotes           = Math.max(1, Math.min(64, parsed.minVotes));
    if (Number.isFinite(parsed.countdownSec))       out.countdownSec       = Math.max(0, Math.min(300, parsed.countdownSec));
    if (Number.isFinite(parsed.suggestIntervalSec)) out.suggestIntervalSec = Math.max(0, Math.min(86400, parsed.suggestIntervalSec));
    if (Array.isArray(parsed.allowedMaps)) {
      out.allowedMaps = parsed.allowedMaps
        .filter(m => m && typeof m === 'object' && typeof m.level === 'string' && typeof m.name === 'string')
        .slice(0, 100);
    }
  } catch (e) { _logBridge('warn', 'read vote_config:', e.message); }
  return out;
}

async function _publishVoteConfig() {
  const cfg = _getVoteConfig();
  await fsp.mkdir(BEAMMP_PLUGIN_BRIDGE_DIR, { recursive: true }).catch(() => {});
  const tmp = BEAMMP_PLUGIN_VOTE_CONFIG_FILE + '.tmp';
  try {
    await fsp.writeFile(tmp, JSON.stringify(cfg), 'utf8');
    await fsp.rename(tmp, BEAMMP_PLUGIN_VOTE_CONFIG_FILE);
  } catch (e) {
    _logBridge('warn', 'publish vote_config.json:', e.message);
  } finally {
    await fsp.unlink(tmp).catch(() => {});
  }
}

function _putVoteConfig(next) {
  if (!db) return;
  const cur = _getVoteConfig();
  const merged = { ...cur, ...next };
  // Re-clamp through the getter validator by writing then re-reading.
  db.prepare(`
    INSERT INTO panel_settings (key, value) VALUES ('vote_config', ?)
    ON CONFLICT(key) DO UPDATE SET value = excluded.value
  `).run(JSON.stringify(merged));
  return _getVoteConfig();
}

function _readVoteState() {
  try {
    const raw = fs.readFileSync(BEAMMP_PLUGIN_VOTE_STATE_FILE, 'utf8');
    return JSON.parse(raw);
  } catch { return { ts: 0, active: false }; }
}

// One-shot result handler. Reads vote_result.json, deletes it, fires the
// countdown announcement, then activates the chosen map with autoRestart.
// Guarded by a single-flight flag so a misfiring watcher can't queue two
// flows for the same result.
let _voteResultBusy = false;
async function _consumeVoteResult() {
  if (_voteResultBusy) return;
  let raw;
  try { raw = await fsp.readFile(BEAMMP_PLUGIN_VOTE_RESULT_FILE, 'utf8'); }
  catch (e) { if (e.code !== 'ENOENT') _logBridge('warn', 'read vote_result:', e.message); return; }
  // Delete BEFORE parsing so a malformed result file doesn't trap us in
  // a retry loop on every tick. If parse fails the result is lost — same
  // semantics as commands.json.
  await fsp.unlink(BEAMMP_PLUGIN_VOTE_RESULT_FILE).catch(() => {});
  _voteResultBusy = true;
  try {
    const r = JSON.parse(raw);
    if (!r || typeof r.level !== 'string') return;
    const level = r.level;
    const name  = String(r.name || level);
    const countdown = Math.max(0, Math.min(300, Number.isFinite(r.countdownSec) ? r.countdownSec : 30));
    const proposer = String(r.proposer || '').slice(0, 100);
    insertAuditLog('vote:' + proposer, 'server.map.vote.pass', level,
      `yes=${r.yes || 0} no=${r.no || 0} countdown=${countdown}s`);
    // Announce a few countdown ticks so players know the restart is
    // coming. The plugin already said "restarting in X s…", we add 5/3/1
    // markers and the final restart fire-and-forget.
    const announcer = async (msg) => {
      try { await _enqueueBridgeCommand({ action: 'broadcast', message: msg }); } catch {}
    };
    if (countdown >= 10) { await announcer(`[Vote] ${name} — restart in 10 s.`); await sleep(Math.min(countdown - 5, countdown) * 1000); }
    else { await sleep(Math.max(0, countdown - 5) * 1000); }
    if (countdown >= 5) { await announcer(`[Vote] Restart in 5 s…`); await sleep(5000); }
    // Now activate the map with auto-restart. _doActivateMap rotates the
    // config backup, writes the new Map = "...", kicks the server down
    // and brings it back up.
    try { await _doActivateMap('vote:' + proposer, level, { autoRestart: true }); }
    catch (e) { _logBridge('warn', 'vote map activate failed:', e.message); }
  } catch (e) {
    _logBridge('warn', 'vote result handler:', e.message);
  } finally {
    _voteResultBusy = false;
  }
}

// Plugged into startPlayerBridgeWatcher() — see below.
function _startVoteResultWatcher() {
  const tick = () => { _consumeVoteResult().catch(() => {}); };
  // 1 s polling so the countdown starts within ~1 s of the plugin writing
  // the result. The file is tiny (under 200 bytes) so this is cheap.
  setInterval(tick, 1000).unref();
  // Also drain any leftover result from a previous panel run.
  tick();
}

// API endpoints ------------------------------------------------------------

function apiVoteGet(req, res) {
  if (!checkAnyAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  const config = _getVoteConfig();
  const state  = _readVoteState();
  return json(res, 200, { config, state });
}

async function apiVoteConfigUpdate(req, res) {
  // Vote configuration is admin-only — letting a `mapActivate` user tune
  // quorum + duration would make the in-game flow trivial to game.
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  let body;
  try { body = await readBody(req); }
  catch (e) { return json(res, 400, { error: e.message }); }
  if (!body || typeof body !== 'object') return json(res, 400, { error: 'Bad payload' });
  const merged = _putVoteConfig(body);
  await _publishVoteConfig();
  const actor = checkAnyAuth(req)?.username || 'unknown';
  insertAuditLog(actor, 'server.map.vote.config', '',
    `enabled=${merged.enabled} duration=${merged.durationSec}s quorum=${merged.quorumPercent}% min=${merged.minVotes} countdown=${merged.countdownSec}s tease=${merged.suggestIntervalSec}s maps=${merged.allowedMaps.length}`);
  return json(res, 200, { ok: true, config: merged });
}

async function apiVoteCancel(req, res) {
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  try {
    await _enqueueBridgeCommand({ action: 'vote_cancel' });
    const actor = checkAnyAuth(req)?.username || 'unknown';
    insertAuditLog(actor, 'server.map.vote.cancel', '');
    return json(res, 202, { ok: true, queued: true });
  } catch (e) {
    return json(res, 500, { error: `Cannot enqueue: ${e.message}` });
  }
}

async function apiPlayers(req, res) {
  // The Players page polls this every 5 s; gate it on a session so anon
  // visitors can't enumerate names + IPs from the public side.
  if (!checkAnyAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  // Resolve nicknames in one batched query so the 5 s polling stays at O(1)
  // DB calls regardless of how many players are connected. Mirrors AC's
  // byGuid lookup pattern in apiPlayers.
  let nickMap = {};
  if (db && _connectedPlayers.size > 0) {
    try {
      const ids = [..._connectedPlayers.keys()];
      const placeholders = ids.map(() => '?').join(',');
      const rows = db.prepare(`SELECT id, nickname FROM players WHERE id IN (${placeholders})`).all(...ids);
      for (const r of rows) if (r.nickname) nickMap[r.id] = r.nickname;
    } catch {}
  }
  const list = [];
  for (const [id, p] of _connectedPlayers) {
    list.push({
      id,
      name: p.name,
      nickname: nickMap[id] || '',
      isGuest: !!p.isGuest,
      identifiers: p.identifiers || {},
      joinedAt: new Date(p.joinedAt).toISOString(),
    });
  }
  list.sort((a, b) => a.name.localeCompare(b.name));
  return json(res, 200, list);
}

// Live chat viewer — reads the chat.json ring buffer written by PanelBridge v2
// (Resources/Server/PanelBridge/chat.json). Returns the last N lines from
// what the plugin keeps in memory. Polled by the panel's chat-feed UI every
// 5-10 s; chat.json is rewritten by the plugin on every chat event so a poll
// is cheap (one fs.readFileSync of a ~50 KB file at the buffer ceiling).
function apiChat(req, res) {
  if (!checkAnyAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  // Optional `?since=<unix-seconds>` to fetch only newer lines — saves
  // bandwidth on tight polling, and the UI uses it for incremental render.
  const url = new URL(req.url, 'http://x');
  const since = parseInt(url.searchParams.get('since') || '0', 10) || 0;
  let raw;
  try { raw = fs.readFileSync(BEAMMP_PLUGIN_CHAT_FILE, 'utf8'); }
  catch (e) {
    // No plugin installed (or no chat yet) → empty result; UI shows an empty
    // state with a hint about installing PanelBridge v2.
    if (e.code === 'ENOENT') return json(res, 200, { ts: 0, lines: [], pluginInstalled: false });
    return json(res, 500, { error: e.message });
  }
  let parsed;
  try { parsed = JSON.parse(raw); }
  catch (e) { return json(res, 200, { ts: 0, lines: [], pluginInstalled: true, error: 'malformed chat.json' }); }
  const lines = Array.isArray(parsed.lines) ? parsed.lines : [];
  const filtered = since > 0 ? lines.filter(l => (l.ts || 0) > since) : lines;
  return json(res, 200, { ts: parsed.ts || 0, lines: filtered, pluginInstalled: true });
}

function apiPlayersHistory(req, res) {
  if (!checkAnyAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  if (!db) return json(res, 200, []);
  try {
    // Collapse to one row per player_id with the latest event we have,
    // keeping totals. The Players page's history widget renders one row
    // per past name; this matches the AC fork's shape so the existing
    // frontend just works.
    // Primary source = canonical players table (one row per id, carries the
    // admin nickname + first_seen + last_seen). LEFT JOIN player_events for
    // the join/leave counters. Same shape as AC's apiPlayersHistory.
    const rows = db.prepare(`
      SELECT p.id, p.name, p.nickname, p.first_seen, p.last_seen,
             SUM(CASE WHEN pe.action='join'  THEN 1 ELSE 0 END) AS join_count,
             SUM(CASE WHEN pe.action='leave' THEN 1 ELSE 0 END) AS leave_count
      FROM players p
      LEFT JOIN player_events pe ON pe.player_id = p.id
      GROUP BY p.id
      ORDER BY p.last_seen DESC
      LIMIT 1000
    `).all();
    return json(res, 200, rows.map(r => ({
      id:        r.id,
      name:      r.name || '',
      nickname:  r.nickname || '',
      firstSeen: r.first_seen,
      lastSeen:  r.last_seen,
      joins:     r.join_count || 0,
      leaves:    r.leave_count || 0,
    })));
  } catch (e) { return json(res, 500, { error: e.message }); }
}

async function apiPlayerKick(req, res) {
  if (!checkPermission(req, 'playerModeration')) return json(res, 403, { error: 'Forbidden' });
  if (!checkRateLimit('player-mod', clientIp(req), 30, 60 * 1000))
    return json(res, 429, { error: 'Rate limit: too many moderation actions' });
  let body;
  try { body = await readBody(req); }
  catch (e) { return json(res, 400, { error: e.message }); }
  const rawId = body?.id;
  if (rawId === undefined || rawId === null || rawId === '') return json(res, 400, { error: 'Missing player id' });
  const stableId = String(rawId);
  // Resolve the durable id (e.g. "bmp:12345" or "ip:1.2.3.4") to the slot
  // number BeamMP-Server uses for MP.DropPlayer. If the player has gone
  // offline since the panel last refreshed, the lookup misses — there's
  // nothing to kick. Backwards-compat: if the body still carries a bare
  // numeric id from an older client build (pre-stable-id), fall through to
  // the legacy code path so the kick still happens.
  const cur = _connectedPlayers.get(stableId);
  let numericId = cur?.slotId;
  if (!Number.isFinite(numericId)) {
    // Legacy fallback for clients that didn't migrate yet
    const maybeNumeric = parseInt(rawId, 10);
    if (Number.isFinite(maybeNumeric) && maybeNumeric >= 0 && String(maybeNumeric) === stableId) {
      numericId = maybeNumeric;
    }
  }
  if (!Number.isFinite(numericId) || numericId < 0) {
    return json(res, 404, { error: 'Player is no longer online' });
  }
  const reason = typeof body?.reason === 'string' ? body.reason.slice(0, 200) : '';
  try {
    await _enqueueBridgeCommand({ action: 'kick', id: numericId, reason });
    const actor = checkAnyAuth(req)?.username || 'unknown';
    insertAuditLog(actor, 'player.kick', stableId, reason);
    return json(res, 202, { ok: true, queued: true });
  } catch (e) {
    return json(res, 500, { error: `Cannot enqueue command: ${e.message}` });
  }
}

async function apiPlayerBan(req, res) {
  // Ban inserts a row into the bans table immediately + kicks the player
  // if they're currently online via the same commands.json bridge. Enforcing
  // the ban on the NEXT connection still requires the PanelBridge plugin to
  // grow an onPlayerAuth handler that reads a bans.json file — that lands
  // in a follow-up plugin version. For now this hardcodes the bans table
  // and kicks if online, which matches "moderate now, prevent later".
  if (!checkPermission(req, 'playerModeration')) return json(res, 403, { error: 'Forbidden' });
  if (!checkRateLimit('player-mod', clientIp(req), 30, 60 * 1000))
    return json(res, 429, { error: 'Rate limit: too many moderation actions' });
  let body;
  try { body = await readBody(req); }
  catch (e) { return json(res, 400, { error: e.message }); }
  const id = String(body?.id || '').trim();
  if (!id) return json(res, 400, { error: 'Missing player id' });
  const reason = typeof body?.reason === 'string' ? body.reason.slice(0, 500) : '';
  const expiresAt = body?.expiresAt ? String(body.expiresAt) : null;
  if (!db) return json(res, 503, { error: 'Database unavailable' });
  try {
    const actor = checkAnyAuth(req)?.username || 'unknown';
    const cur = _connectedPlayers.get(id);
    const name = cur?.name || body?.name || '';
    db.prepare(`
      INSERT INTO bans (id, name, reason, banned_by, banned_at, expires_at)
      VALUES (?, ?, ?, ?, datetime('now'), ?)
      ON CONFLICT(id) DO UPDATE SET
        name = excluded.name,
        reason = excluded.reason,
        banned_by = excluded.banned_by,
        banned_at = excluded.banned_at,
        expires_at = excluded.expires_at
    `).run(id, name, reason, actor, expiresAt);
    // Publish the updated ban list so the plugin's onPlayerAuth refuses the
    // next re-connection attempt from this id. Doing this BEFORE the kick
    // means even a race-condition reconnect (player kicked, immediately
    // tries to come back) hits the refusal path.
    await _publishBans().catch(() => {});
    // If the player is online right now, also kick them so the ban is
    // visible immediately. The plugin's commands.json polling means up to
    // 5 s of latency before the kick fires. Slot id comes from the live
    // _connectedPlayers entry; the stable id we banned by is no longer a
    // number, so resolving via the Map is the only way to get a value
    // BeamMP-Server's MP.DropPlayer will accept.
    if (cur && Number.isFinite(cur.slotId)) {
      await _enqueueBridgeCommand({ action: 'kick', id: cur.slotId, reason: reason || 'You have been banned' }).catch(() => {});
    }
    insertAuditLog(actor, 'player.ban', id, reason);
    return json(res, 200, { ok: true });
  } catch (e) { return json(res, 500, { error: e.message }); }
}

async function apiPlayerUnban(req, res, id) {
  if (!checkPermission(req, 'playerModeration')) return json(res, 403, { error: 'Forbidden' });
  if (!db) return json(res, 503, { error: 'Database unavailable' });
  try {
    const r = db.prepare('DELETE FROM bans WHERE id = ?').run(id);
    if (r.changes === 0) return json(res, 404, { error: 'Ban not found' });
    const actor = checkAnyAuth(req)?.username || 'unknown';
    await _publishBans().catch(() => {});
    insertAuditLog(actor, 'player.unban', id);
    return json(res, 200, { ok: true });
  } catch (e) { return json(res, 500, { error: e.message }); }
}

async function apiBroadcast(req, res) {
  if (!checkPermission(req, 'playerModeration')) return json(res, 403, { error: 'Forbidden' });
  if (!checkRateLimit('player-mod', clientIp(req), 30, 60 * 1000))
    return json(res, 429, { error: 'Rate limit: too many broadcasts' });
  let body;
  try { body = await readBody(req); }
  catch (e) { return json(res, 400, { error: e.message }); }
  const message = typeof body?.message === 'string' ? body.message.trim() : '';
  if (!message) return json(res, 400, { error: 'Missing message' });
  if (message.length > 500) return json(res, 400, { error: 'Message exceeds 500 characters' });
  try {
    await _enqueueBridgeCommand({ action: 'broadcast', message });
    const actor = checkAnyAuth(req)?.username || 'unknown';
    insertAuditLog(actor, 'chat.broadcast', '', message.slice(0, 100));
    return json(res, 202, { ok: true, queued: true });
  } catch (e) { return json(res, 500, { error: e.message }); }
}

function apiBansList(req, res) {
  if (!checkPermission(req, 'playerModeration')) return json(res, 403, { error: 'Forbidden' });
  if (!db) return json(res, 200, []);
  try {
    const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
    const rows = db.prepare(`
      SELECT id, name, reason, banned_by, banned_at, expires_at
      FROM bans
      WHERE expires_at IS NULL OR expires_at > ?
      ORDER BY banned_at DESC
    `).all(now);
    return json(res, 200, rows.map(r => ({
      id:        r.id,
      name:      r.name || '',
      reason:    r.reason || '',
      bannedBy:  r.banned_by || '',
      bannedAt:  r.banned_at || '',
      expiresAt: r.expires_at || null,
      permanent: !r.expires_at,
      expired:   false, // by construction (filtered above)
    })));
  } catch (e) { return json(res, 500, { error: e.message }); }
}

// Admin-set display name for a player — stored alongside the in-game name in
// the canonical players table so the live + history views (joined by id) can
// render "Apodo (in-game)" without touching the events the PanelBridge plugin
// already wrote. Mirrors the AC fork's apiPlayerNickname signature: empty
// nickname clears the column (treated as "no nickname"), 404 when the player
// has never been seen by the bridge yet.
async function apiPlayerNickname(req, res, id) {
  if (!checkPermission(req, 'playerModeration')) return json(res, 403, { error: 'Forbidden' });
  if (!db) return json(res, 500, { error: 'Database unavailable' });
  if (!id || !String(id).trim()) return json(res, 400, { error: 'Player id required' });
  try {
    const body = await readBody(req);
    // Allow clearing with empty string. Cap at 64 chars (same as AC) and strip
    // control characters so the modal can't be used to inject weird glyphs
    // into the players list.
    const raw = typeof body.nickname === 'string' ? body.nickname : '';
    const nickname = raw.replace(/[\r\n\t\0]/g, ' ').trim().slice(0, 64);
    const r = db.prepare('UPDATE players SET nickname = ? WHERE id = ?').run(nickname, id);
    if (r.changes === 0) return json(res, 404, { error: 'Player not found' });
    const actor = checkAnyAuth(req)?.username || 'unknown';
    insertAuditLog(actor, 'player.nickname', id, nickname);
    const row = db.prepare('SELECT id, name, nickname FROM players WHERE id = ?').get(id);
    json(res, 200, { ok: true, player: row });
  } catch (e) { json(res, 500, { error: e.message }); }
}

// Manual merge — fold one or more duplicate player rows into a single
// canonical id. With registration disabled, guests are keyed by IP
// (_stableIdFor), so the same person still accrues a fresh row whenever their
// ISP rotates the public IP — or two people behind one IP collapse and the
// operator wants to split-then-remerge correctly. This lets the operator pick
// the survivor (targetId) and the rows to absorb (sourceIds): we re-point
// every reference (events, nicknames, bans) at the target, widen the target's
// first_seen/last_seen to span the whole merged history, then drop the source
// rows. Irreversible (the source ids are gone afterwards), so admin-only.
async function apiPlayersMerge(req, res) {
  if (!checkAdminAuth(req)) return json(res, 403, { error: 'Forbidden (admin only)' });
  if (!db) return json(res, 503, { error: 'Database unavailable' });
  let body;
  try { body = await readBody(req); }
  catch (e) { return json(res, 400, { error: e.message }); }
  const targetId = String(body?.targetId || '').trim();
  let sourceIds = Array.isArray(body?.sourceIds) ? body.sourceIds.map(s => String(s).trim()) : [];
  // Dedupe, drop blanks, and never let the target appear in its own source set.
  sourceIds = [...new Set(sourceIds)].filter(s => s && s !== targetId);
  if (!targetId) return json(res, 400, { error: 'Missing targetId' });
  if (sourceIds.length === 0) return json(res, 400, { error: 'No source players to merge' });
  if (sourceIds.length > 100) return json(res, 400, { error: 'Too many players in one merge (max 100)' });
  try {
    const target = db.prepare('SELECT id FROM players WHERE id = ?').get(targetId);
    if (!target) return json(res, 404, { error: 'Target player not found' });
    const ph0 = sourceIds.map(() => '?').join(',');
    const found = db.prepare(`SELECT id FROM players WHERE id IN (${ph0})`).all(...sourceIds);
    if (found.length === 0) return json(res, 404, { error: 'No matching source players found' });
    const srcs = found.map(r => r.id);
    const ph = srcs.map(() => '?').join(',');

    db.transaction(() => {
      // Re-point history onto the survivor.
      db.prepare(`UPDATE player_events SET player_id = ? WHERE player_id IN (${ph})`).run(targetId, ...srcs);
      // player_nicknames + bans are keyed by player id (PK), so a plain UPDATE
      // would throw if the target already holds a row. UPDATE OR IGNORE keeps
      // the target's row and leaves the source row for the DELETE below.
      db.prepare(`UPDATE OR IGNORE player_nicknames SET player_id = ? WHERE player_id IN (${ph})`).run(targetId, ...srcs);
      db.prepare(`DELETE FROM player_nicknames WHERE player_id IN (${ph})`).run(...srcs);
      db.prepare(`UPDATE OR IGNORE bans SET id = ? WHERE id IN (${ph})`).run(targetId, ...srcs);
      db.prepare(`DELETE FROM bans WHERE id IN (${ph})`).run(...srcs);
      // Widen the survivor's lifespan to cover the absorbed rows (they still
      // exist at this point), then drop them.
      db.prepare(`
        UPDATE players SET
          first_seen = (SELECT MIN(first_seen) FROM players WHERE id = ? OR id IN (${ph})),
          last_seen  = (SELECT MAX(last_seen)  FROM players WHERE id = ? OR id IN (${ph}))
        WHERE id = ?
      `).run(targetId, ...srcs, targetId, ...srcs, targetId);
      db.prepare(`DELETE FROM players WHERE id IN (${ph})`).run(...srcs);
    })();

    await _publishBans().catch(() => {});
    const actor = checkAnyAuth(req)?.username || 'unknown';
    insertAuditLog(actor, 'player.merge', targetId, srcs.join(','));
    const row = db.prepare(`
      SELECT p.id, p.name, p.nickname, p.first_seen, p.last_seen,
             SUM(CASE WHEN pe.action='join'  THEN 1 ELSE 0 END) AS join_count,
             SUM(CASE WHEN pe.action='leave' THEN 1 ELSE 0 END) AS leave_count
      FROM players p LEFT JOIN player_events pe ON pe.player_id = p.id
      WHERE p.id = ? GROUP BY p.id
    `).get(targetId);
    return json(res, 200, {
      ok: true,
      merged: srcs,
      player: row && {
        id: row.id, name: row.name || '', nickname: row.nickname || '',
        firstSeen: row.first_seen, lastSeen: row.last_seen,
        joins: row.join_count || 0, leaves: row.leave_count || 0,
      },
    });
  } catch (e) { return json(res, 500, { error: e.message }); }
}

// Whitelist read/write/append. Backing storage is panel_settings.whitelist
// (JSON array of ids) until BeamMP's preferred allowlist format is decided.
function apiWhitelistGet(res) {
  if (!db) return json(res, 200, { ids: [] });
  try {
    const row = db.prepare("SELECT value FROM panel_settings WHERE key = 'whitelist'").get();
    const ids = row ? JSON.parse(row.value || '[]') : [];
    return json(res, 200, { ids: Array.isArray(ids) ? ids : [] });
  } catch { return json(res, 200, { ids: [] }); }
}

async function apiWhitelistPut(req, res) {
  if (!checkPermission(req, 'whitelistManage')) return json(res, 403, { error: 'Forbidden' });
  try {
    const body = await readBody(req);
    const ids = Array.isArray(body?.ids) ? body.ids.filter(v => typeof v === 'string' && v && !/\s/.test(v)).slice(0, 1024) : [];
    const json_ = JSON.stringify(ids);
    db.prepare(`
      INSERT INTO panel_settings (key, value) VALUES ('whitelist', ?)
      ON CONFLICT(key) DO UPDATE SET value = excluded.value
    `).run(json_);
    insertAuditLog(checkAnyAuth(req)?.username || '', 'whitelist.update', String(ids.length));
    return json(res, 200, { ok: true, saved: ids.length });
  } catch (e) { return json(res, 500, { error: e.message }); }
}

async function apiWhitelistAdd(req, res) {
  if (!checkPermission(req, 'whitelistManage')) return json(res, 403, { error: 'Forbidden' });
  try {
    const body = await readBody(req);
    const id = String(body?.id || '').trim();
    if (!id || /\s/.test(id)) return json(res, 400, { error: 'invalid id' });
    const row = db.prepare("SELECT value FROM panel_settings WHERE key = 'whitelist'").get();
    const ids = row ? JSON.parse(row.value || '[]') : [];
    if (!Array.isArray(ids)) return json(res, 200, { ok: true, alreadyPresent: false });
    if (ids.includes(id)) return json(res, 200, { ok: true, alreadyPresent: true });
    ids.push(id);
    db.prepare(`
      INSERT INTO panel_settings (key, value) VALUES ('whitelist', ?)
      ON CONFLICT(key) DO UPDATE SET value = excluded.value
    `).run(JSON.stringify(ids));
    insertAuditLog(checkAnyAuth(req)?.username || '', 'whitelist.add', id);
    return json(res, 200, { ok: true, alreadyPresent: false });
  } catch (e) { return json(res, 500, { error: e.message }); }
}


async function apiMetrics(res) {
  try {
    const [cpu, ram, info, publicIp, cpuTemp] = await Promise.all([getCPU(), Promise.resolve(getRAM()), getServerInfo(), getPublicIp(), _getCpuTempC()]);
    json(res, 200, {
      cpu, ram, cpuTemp,
      running:   info.running,
      uptime:    getServerUptime(),
      cpuName:   getCPUName(),
      osInfo:    getOSInfo(),
      publicIp,
      // The configured game port that the BeamMP-Server listens on. Named
      // `httpPort` for frontend back-compat with the AC panel topbar widget
      // (it just renders the number as a "Connect on :N" hint).
      httpPort:  info.port || 0,
      // Player count is reported by a Lua plugin in a later phase; until then
      // the panel cannot enumerate live players, so we report 0.
      players:   0,
    });
  } catch (e) { json(res, 500, { error: e.message }); }
}

function apiLogs(req, res) {
  const n = Math.min(500, parseInt(new URL(req.url, 'http://x').searchParams.get('n') || '150'));
  json(res, 200, { lines: logBuffer.slice(-n) });
}

// Persistent clear — drops the in-memory buffer, truncates BEAMMP_LOG_FILE so the
// next server restart doesn't reload the old lines via loadLogFileIntoBuffer,
// and broadcasts a `clear` SSE event so every open tab wipes its state.
// Admin-only because it affects every connected viewer + persists across
// restarts; non-admins still see the (now hidden) button as a no-op.
function apiLogsClear(req, res) {
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  try {
    logBuffer = [];
    // Keep logSeq monotonic so older client refs (clearedSeqRef) don't accidentally
    // un-suppress freshly-issued ids that happen to overlap with the pre-clear range.
    try { fs.truncateSync(BEAMMP_LOG_FILE, 0); } catch {}
    // The tail watcher tracks how many bytes it has already read; resetting
    // it here makes sure the post-truncate file is read from byte 0 instead
    // of skipped (size < stored pos triggers the rotation branch anyway, but
    // doing it explicitly avoids depending on that ordering).
    resetLogTailPosition();
    for (const r of [...sseClients]) {
      try { r.write(`event: clear\ndata: {}\n\n`); } catch { sseClients.delete(r); }
    }
    insertAuditLog(checkAnyAuth(req)?.username || 'unknown', 'logs.clear');
    json(res, 200, { ok: true });
  } catch (e) { json(res, 500, { error: e.message }); }
}

// Per-user concurrent SSE connection cap. Without this an authenticated user can
// open arbitrarily many `/api/logs/stream` connections (one per browser tab × N
// tabs × N devices) and pin file descriptors + heartbeat timers. Six is generous
// for normal usage (a few tabs, a phone, an ops dashboard) and well below any
// reasonable fd budget.
const _sseByUser = new Map(); // username -> Set<res>
const SSE_PER_USER_CAP = 6;

function apiLogsStream(req, res) {
  // Router has already gated /api/* on a valid session, so getSession(req) is
  // expected to return one. Fall back to '' for the (impossible) no-session
  // case so the cap still applies in aggregate.
  const user = getSession(req)?.username || '';
  const userSet = _sseByUser.get(user) || new Set();
  if (userSet.size >= SSE_PER_USER_CAP) {
    return json(res, 429, { error: 'Too many concurrent log streams for this user — close other tabs and retry' });
  }

  res.writeHead(200, {
    'Content-Type':  'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection':    'keep-alive',
    'X-Accel-Buffering': 'no',
  });
  res.write(`event: init\ndata: ${JSON.stringify(logBuffer)}\n\n`);
  sseClients.add(res);
  userSet.add(res);
  _sseByUser.set(user, userSet);

  // Single cleanup path used by every termination route (req close, write
  // failure during heartbeat, write failure during appendLog broadcast).
  // Without this the heartbeat-failure branch would only stop the timer,
  // leaving the res object pinned in sseClients and _sseByUser forever and
  // burning per-user SSE cap until the next legitimate close.
  let cleaned = false;
  const cleanup = () => {
    if (cleaned) return;
    cleaned = true;
    clearInterval(heartbeat);
    sseClients.delete(res);
    const set = _sseByUser.get(user);
    if (set) {
      set.delete(res);
      if (set.size === 0) _sseByUser.delete(user);
    }
  };

  const heartbeat = setInterval(() => {
    try { res.write(': ping\n\n'); }
    catch { cleanup(); try { res.destroy(); } catch {} }
  }, 25000);
  req.on('close', cleanup);
  req.on('error', cleanup);
  res.on('close', cleanup);
  res.on('error', cleanup);
}

// Catalogue cache invalidation hook. The current /api/mods listing rebuilds
// from disk on every GET so there's nothing to invalidate, but the call site
// in the upload pipeline keeps this stub so a future memoised listing can
// drop in without touching the upload code.
function invalidateContentCache(_which) {}

// ── Server control ────────────────────────────────────────────────────────────
// BeamMP-Server lifecycle. Mirrors the AC version's detach + log-FD trick so
// the binary survives a panel restart (systemd reloads us, the BeamMP-Server
// keeps running, we re-adopt it on boot via pgrep -f against BEAMMP_BIN).
// Differences from AC:
//   - Health-check is a TCP probe against the configured Port (BeamMP-Server
//     listens on both TCP and UDP on the same port; we probe TCP because UDP
//     gives no connection-refused signal).
//   - PID lookup uses pgrep -f against the absolute binary path. The BeamMP
//     binary name on Linux is often suffixed with the distro (BeamMP-Server-ubuntu-22.04)
//     so a bare `pidof BeamMP-Server` would miss it.
//   - No HTTP /INFO endpoint to read player count / map / name from at runtime.
//     Those will come from a Lua plugin in a later phase.
const sleep = ms => new Promise(r => setTimeout(r, ms));
let _serverRunSince = null;
let _serverFailCount = 0;

// ── ServerConfig.toml mini parser + line-edit serializer ─────────────────────
// Why custom instead of a TOML library: BeamMP's config is small (~15 keys in
// one [General] section) and we need to PRESERVE the original file verbatim
// when saving — comments, blank lines, key order, indentation, even inline
// comments after a value (`Name = "x"  # don't change this`). Off-the-shelf
// parsers stringify back from an AST and lose all formatting unless they ship
// a separate "preserving" emitter (smol-toml doesn't, @iarna/toml doesn't,
// @ltd/j-toml keeps key order but not comments). The simplest way to keep
// 100% of the file is a line-edit: for each key the user changes we sub
// `Key = oldValue` → `Key = newValue` in-place, preserving everything around
// it. New keys are appended at the end of the target section. Anything we
// can't handle (multi-line strings, arrays, inline tables, nested keys) we
// fall through unchanged — BeamMP's ServerConfig.toml uses none of those.
function _stripInlineComment(s) {
  // Strip a trailing `# comment`, BUT only when the # is NOT inside a string.
  // Simple state machine — good enough for BeamMP's flat key=value lines.
  let inQuote = null; // " or '
  for (let i = 0; i < s.length; i++) {
    const c = s[i];
    if (inQuote) {
      if (c === '\\' && i + 1 < s.length) { i++; continue; }
      if (c === inQuote) inQuote = null;
    } else {
      if (c === '"' || c === "'") inQuote = c;
      else if (c === '#') return s.slice(0, i).trimEnd();
    }
  }
  return s.trimEnd();
}
function _parseTomlValue(raw) {
  const s = raw.trim();
  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
    return s.slice(1, -1)
      .replace(/\\"/g, '"').replace(/\\'/g, "'").replace(/\\\\/g, '\\')
      .replace(/\\n/g, '\n').replace(/\\t/g, '\t');
  }
  if (s === 'true')  return true;
  if (s === 'false') return false;
  if (/^-?\d+$/.test(s))         return parseInt(s, 10);
  if (/^-?\d+\.\d+$/.test(s))    return parseFloat(s);
  return s; // bare word; pass through as string
}
function _serializeTomlValue(v) {
  if (typeof v === 'boolean') return v ? 'true' : 'false';
  if (typeof v === 'number' && Number.isFinite(v)) return String(v);
  const s = String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
  return `"${s}"`;
}
// Sections BeamMP-Server itself recognises. Anything else in the file is
// silently ignored by the server but probably indicates an operator typo
// (e.g. `[Genral]` for `[General]`) — parseServerConfig warns when it sees
// one of those AND it has keys inside, so the operator finds out before
// the next restart fails to apply their "edit".
const _KNOWN_TOML_SECTIONS = new Set(['General', 'Misc']);

function parseServerConfig(rawText) {
  const sections = Object.create(null);
  let cur = null;
  for (const line of rawText.split(/\r?\n/)) {
    const trimmed = _stripInlineComment(line).trim();
    if (!trimmed) continue;
    const sec = trimmed.match(/^\[([^\]]+)\]$/);
    if (sec) { cur = sec[1]; sections[cur] ??= Object.create(null); continue; }
    if (!cur) continue;
    const m = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.+)$/);
    if (!m) continue;
    sections[cur][m[1]] = _parseTomlValue(m[2]);
  }
  // Surface unknown sections only when they actually carry keys — an empty
  // `[CustomComment]` is almost certainly intentional, but `[Genral]` with
  // five Server keys underneath is a typo the operator wants to know about.
  for (const [name, keys] of Object.entries(sections)) {
    if (_KNOWN_TOML_SECTIONS.has(name)) continue;
    const keyCount = Object.keys(keys).length;
    if (keyCount > 0 && typeof log !== 'undefined' && log?.warn) {
      log.warn(`ServerConfig.toml: unknown section [${name}] with ${keyCount} key${keyCount === 1 ? '' : 's'} — those keys will be ignored. Typo for [General]?`);
    }
  }
  return { sections };
}
// Line-edit serializer: take the original file text + a target section name +
// a {key: newValue} dict, return the file text with those keys substituted in
// place (preserving spacing + inline comments) and any new keys appended at
// the end of the target section. Untouched keys, comments and blank lines
// pass through unchanged.
function editServerConfig(rawText, sectionName, updates) {
  if (!updates || typeof updates !== 'object' || Array.isArray(updates)) {
    throw new Error('updates must be a plain object');
  }
  const remaining = new Map(Object.entries(updates));
  const lines = rawText.split(/\r?\n/);
  // Track whether the file already ends with a trailing newline so we can
  // restore it on output (split/join would otherwise add a phantom blank).
  const trailingNewline = rawText.endsWith('\n');
  const out = [];
  let cur = null;
  const flushRemainingIntoCurrentSection = () => {
    if (cur !== sectionName || remaining.size === 0) return;
    for (const [k, v] of remaining) out.push(`${k} = ${_serializeTomlValue(v)}`);
    remaining.clear();
  };
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    const sec = _stripInlineComment(line).trim().match(/^\[([^\]]+)\]$/);
    if (sec) {
      flushRemainingIntoCurrentSection();
      cur = sec[1];
      out.push(line);
      continue;
    }
    if (cur === sectionName) {
      // Capture (leading-ws)(key)(equals-with-padding)(value)(trailing inline-comment+ws)
      const m = line.match(/^(\s*)([A-Za-z_][A-Za-z0-9_]*)(\s*=\s*)(.+?)(\s*(?:#.*)?)$/);
      if (m && remaining.has(m[2])) {
        const newVal = remaining.get(m[2]);
        remaining.delete(m[2]);
        out.push(`${m[1]}${m[2]}${m[3]}${_serializeTomlValue(newVal)}${m[5]}`);
        continue;
      }
    }
    out.push(line);
  }
  flushRemainingIntoCurrentSection();
  if (remaining.size) {
    // Target section never appeared in the file — append a new section block.
    if (out.length && out[out.length - 1].trim() !== '') out.push('');
    out.push(`[${sectionName}]`);
    for (const [k, v] of remaining) out.push(`${k} = ${_serializeTomlValue(v)}`);
  }
  return out.join('\n') + (trailingNewline && !out[out.length - 1]?.endsWith('\n') ? '' : '');
}

// Read the configured Port out of ServerConfig.toml so health-check probes
// hit the right TCP socket. Falls back to BeamMP's default (30814) when the
// file is missing or doesn't declare a Port key.
function _readConfiguredPort() {
  const DEFAULT_PORT = 30814;
  try {
    const raw = fs.readFileSync(BEAMMP_CFG_FILE, 'utf8');
    const p = parseServerConfig(raw).sections.General?.Port;
    if (Number.isFinite(p) && p >= 1 && p <= 65535) return p;
    return DEFAULT_PORT;
  } catch { return DEFAULT_PORT; }
}

// pgrep -f matches against the full command line, so the absolute BEAMMP_BIN
// path is the most reliable identifier — survives both the AppImage-style
// distro suffixes (BeamMP-Server-ubuntu-22.04) and the unlikely case where
// two BeamMP installs share a host.
function findBeamMPPid() {
  return new Promise(resolve => {
    const p = spawn('pgrep', ['-f', BEAMMP_BIN]);
    let out = '';
    p.stdout.on('data', d => out += d);
    p.on('close', () => {
      // pgrep prints one pid per line; pick the first that isn't our own.
      const ours = process.pid;
      const pid = out.split('\n')
        .map(s => parseInt(s.trim(), 10))
        .find(n => Number.isFinite(n) && n > 0 && n !== ours);
      resolve(pid || null);
    });
    p.on('error', () => resolve(null));
  });
}

function pidAlive(pid) {
  if (!pid) return false;
  try { process.kill(pid, 0); return true; } catch { return false; }
}

// TCP probe — opens a connection, closes immediately. "running" means the
// server accepted the SYN (port is bound + listening). A connection-refused
// or timeout means down. Matches what an external player would see.
function _probeTcpPort(host, port, timeoutMs = 600) {
  return new Promise(resolve => {
    const net = require('net');
    const sock = new net.Socket();
    let done = false;
    const finish = ok => { if (done) return; done = true; try { sock.destroy(); } catch {} resolve(ok); };
    sock.setTimeout(timeoutMs);
    sock.once('connect', () => finish(true));
    sock.once('timeout', () => finish(false));
    sock.once('error',   () => finish(false));
    try { sock.connect(port, host); } catch { finish(false); }
  });
}

async function getServerInfo() {
  const port = _readConfiguredPort();
  // Fast path: if neither our tracked child nor an adopted PID is alive,
  // skip the TCP probe (no point asking a dead socket).
  const childAlive   = beammpChild && !beammpChild.killed && pidAlive(beammpChild.pid);
  const adoptedPid   = childAlive ? null : await findBeamMPPid();
  if (!childAlive && !adoptedPid) {
    if (_serverRunSince) _serverRunSince = null;
    return { running: false, port };
  }
  // PID is alive but the listening socket may not be up yet (startup grace
  // period) or may have crashed without the process dying. The TCP probe is
  // the source of truth for "can players connect right now".
  const listening = await _probeTcpPort('127.0.0.1', port);
  if (listening && !_serverRunSince) _serverRunSince = Date.now();
  if (!listening && _serverRunSince) _serverRunSince = null;
  return { running: listening, port };
}

function getServerUptime() {
  if (!_serverRunSince) return '—';
  const sec = Math.floor((Date.now() - _serverRunSince) / 1000);
  const h   = Math.floor(sec / 3600);
  const m   = Math.floor((sec % 3600) / 60);
  return `${h}h ${String(m).padStart(2, '0')}m`;
}

async function waitForBeamMPUp(timeoutMs = 12000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const { running } = await getServerInfo();
    if (running) return true;
    await sleep(400);
  }
  return false;
}

async function waitForBeamMPDown(timeoutMs = 8000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const childAlive = beammpChild && !beammpChild.killed && pidAlive(beammpChild.pid);
    const adoptedAlive = !childAlive && !!(await findBeamMPPid());
    if (!childAlive && !adoptedAlive) {
      const { running } = await getServerInfo();
      if (!running) return true;
    }
    await sleep(300);
  }
  return false;
}

function _checkBeamMPBinary() {
  try {
    const st = fs.statSync(BEAMMP_BIN);
    if (!st.isFile()) return `BEAMMP_BIN is not a file: ${BEAMMP_BIN}`;
    fs.accessSync(BEAMMP_BIN, fs.constants.X_OK);
    return null;
  } catch (e) {
    if (e.code === 'ENOENT') return `Binary not found: ${BEAMMP_BIN} (check BEAMMP_BIN in .env)`;
    if (e.code === 'EACCES') return `Binary not executable: ${BEAMMP_BIN} (run chmod +x)`;
    return `Binary inaccessible: ${e.message}`;
  }
}

function spawnBeamMP() {
  return new Promise((resolve) => {
    const err = _checkBeamMPBinary();
    if (err) { log.error('[BeamMP] spawn error:', err); _serverRunSince = null; return resolve({ ok: false, error: err }); }

    // Same survive-panel-restart trick as the AC implementation: open the log
    // file, hand its FD to the child as stdout+stderr, then drop our reference.
    // The child writes through its own dup'd FD, so when the panel exits the
    // BeamMP-Server keeps running without SIGPIPE.
    let logFd;
    try {
      fs.mkdirSync(path.dirname(BEAMMP_LOG_FILE), { recursive: true });
      logFd = fs.openSync(BEAMMP_LOG_FILE, 'a');
    } catch (e) {
      log.error('[BeamMP] cannot open log file:', e.message);
      _serverRunSince = null;
      return resolve({ ok: false, error: `Cannot open log: ${e.message}` });
    }

    try {
      // BeamMP-Server's working directory determines where it looks for
      // ServerConfig.toml and writes Server.log + Resources/. We point it at
      // BEAMMP_SERVER_DIR so the layout matches what the operator configured.
      const child = spawn(BEAMMP_BIN, [], {
        cwd:      BEAMMP_SERVER_DIR,
        stdio:    ['ignore', logFd, logFd],
        detached: true,
      });
      try { fs.closeSync(logFd); } catch {}
      try { child.unref(); } catch {}

      let settled = false;
      child.once('error', e => {
        if (settled) return;
        settled = true;
        log.error('[BeamMP] spawn error:', e.message);
        beammpChild = null;
        resolve({ ok: false, error: e.message });
      });
      child.once('exit', (code, signal) => {
        if (beammpChild === child) beammpChild = null;
        if (!settled) {
          settled = true;
          resolve({ ok: false, error: `Process exited at start (code=${code} signal=${signal})` });
        }
      });
      beammpChild = child;
      setTimeout(() => {
        if (settled) return;
        settled = true;
        if (beammpChild && !beammpChild.killed) resolve({ ok: true });
        else resolve({ ok: false, error: 'Process did not survive past startup' });
      }, 500);
    } catch (e) {
      try { fs.closeSync(logFd); } catch {}
      log.error('[BeamMP] spawn exception:', e.message);
      beammpChild = null;
      resolve({ ok: false, error: e.message });
    }
  });
}

async function killBeamMP() {
  if (beammpChild && !beammpChild.killed) {
    try { beammpChild.kill('SIGTERM'); } catch {}
  }
  let adoptedPid = await findBeamMPPid();
  if (adoptedPid) {
    try { process.kill(adoptedPid, 'SIGTERM'); } catch {}
  }

  const deadline = Date.now() + 6000;
  while (Date.now() < deadline) {
    const childAlive = beammpChild && !beammpChild.killed && pidAlive(beammpChild.pid);
    if (!childAlive) beammpChild = null;
    adoptedPid = await findBeamMPPid();
    if (!childAlive && !adoptedPid) {
      _serverRunSince  = null;
      _serverFailCount = 0;
      return { ok: true };
    }
    await sleep(250);
  }

  // SIGKILL fallback
  if (beammpChild) { try { beammpChild.kill('SIGKILL'); } catch {} beammpChild = null; }
  adoptedPid = await findBeamMPPid();
  if (adoptedPid) { try { process.kill(adoptedPid, 'SIGKILL'); } catch {} }
  await sleep(400);

  const stillUp = await findBeamMPPid();
  _serverRunSince  = null;
  _serverFailCount = 0;
  if (stillUp) return { ok: false, error: 'Failed to terminate BeamMP-Server' };
  return { ok: true };
}

// Single global mutex over start/stop/restart. Without this two requests
// racing could leave the panel pointing at a stale child while a second
// BeamMP-Server runs orphaned (and binds the same port → port conflict).
let _serverActionInFlight = false;
function _acquireServerLock() {
  if (_serverActionInFlight) return null;
  _serverActionInFlight = true;
  return () => { _serverActionInFlight = false; };
}
async function withServerActionLock(req, res, fn) {
  const release = _acquireServerLock();
  if (!release) return json(res, 409, { error: 'Another server action is in progress' });
  try { return await fn(); }
  finally { release(); }
}

async function apiServerStart(req, res) {
  if (!checkPermission(req, 'serverControl')) return json(res, 403, { error: 'Forbidden' });
  if (!checkRateLimit('server-ctl', clientIp(req), 20, 60 * 1000))
    return json(res, 429, { error: 'Rate limit: too many server actions' });
  return withServerActionLock(req, res, async () => {
    const actor = checkAnyAuth(req)?.username || 'unknown';
    if (beammpChild && !beammpChild.killed) return json(res, 409, { error: 'Server is already running' });
    if (await findBeamMPPid())              return json(res, 409, { error: 'Server is already running' });

    const r = await spawnBeamMP();
    if (!r.ok) {
      insertAuditLog(actor, 'server.start.fail', '', r.error || 'spawn failed');
      return json(res, 500, { error: r.error || 'Failed to start server' });
    }
    // BeamMP-Server can take a few seconds to bind its port after authkey
    // validation against the master server. 12s is generous but matches the
    // common case where the network handshake adds 1-3s on top of local start.
    const up = await waitForBeamMPUp(12000);
    if (!up) {
      insertAuditLog(actor, 'server.start.fail', '', 'TCP port did not respond within 12s');
      return json(res, 500, { error: 'BeamMP-Server started but its port did not respond within 12s — check AuthKey and logs' });
    }
    insertAuditLog(actor, 'server.start');
    json(res, 200, { ok: true });
  });
}

async function apiServerStop(req, res) {
  if (!checkPermission(req, 'serverControl')) return json(res, 403, { error: 'Forbidden' });
  if (!checkRateLimit('server-ctl', clientIp(req), 20, 60 * 1000))
    return json(res, 429, { error: 'Rate limit: too many server actions' });
  return withServerActionLock(req, res, async () => {
    const actor = checkAnyAuth(req)?.username || 'unknown';
    const r = await killBeamMP();
    if (!r.ok) {
      insertAuditLog(actor, 'server.stop.fail', '', r.error || 'kill failed');
      return json(res, 500, { error: r.error || 'Failed to stop server' });
    }
    await waitForBeamMPDown(6000);
    insertAuditLog(actor, 'server.stop');
    json(res, 200, { ok: true });
  });
}

async function apiServerRestart(req, res) {
  if (!checkPermission(req, 'serverControl')) return json(res, 403, { error: 'Forbidden' });
  if (!checkRateLimit('server-ctl', clientIp(req), 20, 60 * 1000))
    return json(res, 429, { error: 'Rate limit: too many server actions' });
  return withServerActionLock(req, res, async () => {
    const actor = checkAnyAuth(req)?.username || 'unknown';
    const k = await killBeamMP();
    if (!k.ok) {
      insertAuditLog(actor, 'server.restart.fail', '', `stop: ${k.error || 'kill failed'}`);
      return json(res, 500, { error: k.error || 'Failed to stop server' });
    }
    await waitForBeamMPDown(6000);
    await sleep(500);
    const s = await spawnBeamMP();
    if (!s.ok) {
      insertAuditLog(actor, 'server.restart.fail', '', `spawn: ${s.error || 'spawn failed'}`);
      return json(res, 500, { error: s.error || 'Failed to start server' });
    }
    const up = await waitForBeamMPUp(12000);
    if (!up) {
      insertAuditLog(actor, 'server.restart.fail', '', 'TCP port did not respond within 12s');
      return json(res, 500, { error: 'BeamMP-Server restarted but its port did not respond within 12s — check logs' });
    }
    insertAuditLog(actor, 'server.restart');
    json(res, 200, { ok: true });
  });
}

// BeamMP-Server doesn't support SIGHUP for config reload — a "reload" is just
// a quick restart. Alias kept so the UI's Reload button keeps working.
async function apiServerReload(req, res) { return apiServerRestart(req, res); }

// ── Rate limiting ─────────────────────────────────────────────────────────────
// Login attempts persist to SQLite so a brute-forcer cannot reset by triggering
// a server restart. Other rate buckets (mod uploads, server control) stay in
// memory — those are operational throttles, not a security boundary.
const _loginAttempts = new Map(); // memory cache to avoid hitting DB on every request when the IP is well-behaved
const _rateBuckets   = new Map(); // `${kind}|${ip}` → { count, resetAt }
function _loadLoginAttempt(ip) {
  if (_loginAttempts.has(ip)) return _loginAttempts.get(ip);
  if (!db) return null;
  try {
    const row = db.prepare('SELECT count, reset_at FROM login_attempts WHERE ip = ?').get(ip);
    if (!row) return null;
    const e = { count: row.count, resetAt: row.reset_at };
    _loginAttempts.set(ip, e);
    return e;
  } catch { return null; }
}
function _saveLoginAttempt(ip, e) {
  _loginAttempts.set(ip, e);
  if (!db) return;
  try {
    db.prepare(`INSERT INTO login_attempts (ip, count, reset_at) VALUES (?, ?, ?)
      ON CONFLICT(ip) DO UPDATE SET count = excluded.count, reset_at = excluded.reset_at`)
      .run(ip, e.count, e.resetAt);
  } catch {}
}
function _clearLoginAttempt(ip) {
  _loginAttempts.delete(ip);
  if (!db) return;
  try { db.prepare('DELETE FROM login_attempts WHERE ip = ?').run(ip); } catch {}
}
function checkLoginRateLimit(ip) {
  const now = Date.now();
  const e   = _loadLoginAttempt(ip);
  if (e && now < e.resetAt) {
    if (e.count >= 5) return false;
    e.count++;
    _saveLoginAttempt(ip, e);
  } else {
    _saveLoginAttempt(ip, { count: 1, resetAt: now + 15 * 60 * 1000 });
  }
  return true;
}
function checkRateLimit(kind, ip, limit, windowMs) {
  const now = Date.now();
  const key = `${kind}|${ip || '_'}`;
  const e   = _rateBuckets.get(key);
  if (e && now < e.resetAt) {
    if (e.count >= limit) return false;
    e.count++;
  } else {
    _rateBuckets.set(key, { count: 1, resetAt: now + windowMs });
  }
  return true;
}
// Behind Cloudflare / a trusted proxy, every request shares the same socket IP and the
// rate limiter would either DoS everyone (one bucket) or be useless. Set TRUST_PROXY=1
// in .env to honour CF-Connecting-IP / X-Forwarded-For instead.
//
// CRITICAL: only honour those headers when the **socket-level** peer is itself a
// trusted proxy. Without this check, any client that can reach the panel directly
// can send `CF-Connecting-IP: 1.2.3.4` to spoof IPs, bypassing the per-IP login
// lockout and framing other IPs in the audit log.
//
// The trusted-proxy set defaults to Cloudflare's published edge ranges
// (https://www.cloudflare.com/ips/) plus loopback. Override with
// TRUST_PROXY_FROM=cidr1,cidr2,... when sitting behind a different proxy (nginx,
// Caddy, Tailscale Funnel, etc.). When TRUST_PROXY=1 but the request did not
// arrive from a trusted IP, the headers are ignored and the socket IP wins —
// so a misconfigured `HOST=0.0.0.0` no longer means "anyone can spoof".
const TRUST_PROXY = process.env.TRUST_PROXY === '1';

// Cloudflare edge IPs (https://www.cloudflare.com/ips/). Refresh if/when CF
// publishes new ranges; the panel's own loopback covers direct healthchecks.
const DEFAULT_PROXY_CIDRS = [
  // IPv4
  '173.245.48.0/20', '103.21.244.0/22', '103.22.200.0/22', '103.31.4.0/22',
  '141.101.64.0/18', '108.162.192.0/18', '190.93.240.0/20', '188.114.96.0/20',
  '197.234.240.0/22', '198.41.128.0/17', '162.158.0.0/15', '104.16.0.0/13',
  '104.24.0.0/14', '172.64.0.0/13', '131.0.72.0/22',
  // IPv6 (prefix string match; coarse but adequate for /32–/48 CF ranges)
  '2400:cb00::', '2606:4700::', '2803:f800::', '2405:b500::',
  '2405:8100::', '2a06:98c0::', '2c0f:f248::',
  // Loopback
  '127.0.0.0/8', '::1',
];

function _parseProxyEntry(entry) {
  if (!entry) return null;
  const v4 = entry.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)(?:\/(\d+))?$/);
  if (v4) {
    const ip   = ((+v4[1]) << 24 | (+v4[2]) << 16 | (+v4[3]) << 8 | (+v4[4])) >>> 0;
    const bits = v4[5] !== undefined ? +v4[5] : 32;
    const mask = bits === 0 ? 0 : (0xFFFFFFFF << (32 - bits)) >>> 0;
    return { type: 'v4', net: ip & mask, mask };
  }
  if (entry.includes(':')) {
    // Coarse IPv6 prefix: strip trailing `::` or `/N` and match by string prefix.
    // Works for the common /32, /48 ranges Cloudflare publishes; not a full
    // CIDR engine. Refine if a future operator needs tighter IPv6 buckets.
    const prefix = entry.split('/')[0].replace(/::$/, ':').toLowerCase();
    return { type: 'v6', prefix };
  }
  return null;
}

// Returns { matchers, source, rejected } so the boot banner can surface a
// misconfiguration that would otherwise silently disable forward-IP trust:
// - source: 'env' if TRUST_PROXY_FROM was set, 'default' if we fell back to
//   the published Cloudflare ranges.
// - rejected: list of entries that didn't parse (typo, wrong CIDR shape, …).
//   When TRUST_PROXY=1 and matchers is empty AFTER parsing, the panel can
//   still boot but every clientIp() call ignores the headers — exactly the
//   silent "TRUST_PROXY=1 but nothing works" trap we want to flag loudly.
function _buildTrustedProxyMatchers() {
  const envRaw    = process.env.TRUST_PROXY_FROM;
  const usedEnv   = envRaw !== undefined && envRaw !== '';
  const raw       = usedEnv ? envRaw : DEFAULT_PROXY_CIDRS.join(',');
  const entries   = raw.split(',').map(s => s.trim()).filter(Boolean);
  const matchers  = [];
  const rejected  = [];
  for (const e of entries) {
    const m = _parseProxyEntry(e);
    if (m) matchers.push(m); else rejected.push(e);
  }
  return { matchers, source: usedEnv ? 'env' : 'default', rejected };
}
const _trustedProxyConfig   = _buildTrustedProxyMatchers();
const _trustedProxyMatchers = _trustedProxyConfig.matchers;

function _ipv4ToInt(ip) {
  const m = ip.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
  if (!m) return null;
  return (((+m[1]) << 24 | (+m[2]) << 16 | (+m[3]) << 8 | (+m[4])) >>> 0);
}

function isTrustedProxyIp(rawIp) {
  if (!rawIp) return false;
  // Normalise IPv4-mapped IPv6 (::ffff:1.2.3.4) — Node hands this shape out of
  // dual-stack sockets, and we want to match it against the v4 allowlist.
  const ip = rawIp.startsWith('::ffff:') ? rawIp.slice(7) : rawIp;
  const v4 = _ipv4ToInt(ip);
  if (v4 !== null) {
    for (const e of _trustedProxyMatchers) {
      if (e.type === 'v4' && (v4 & e.mask) === e.net) return true;
    }
    return false;
  }
  const lower = ip.toLowerCase();
  for (const e of _trustedProxyMatchers) {
    if (e.type === 'v6' && lower.startsWith(e.prefix)) return true;
  }
  return false;
}

function clientIp(req) {
  const socketIp = req.socket?.remoteAddress || '';
  if (TRUST_PROXY && isTrustedProxyIp(socketIp)) {
    const cf = req.headers['cf-connecting-ip'];
    if (cf) return String(cf).trim();
    const xff = req.headers['x-forwarded-for'];
    if (xff) return String(xff).split(',')[0].trim();
  }
  // Untrusted source (or TRUST_PROXY off) — never honour spoofable headers.
  return socketIp;
}

// ── Auth API ─────────────────────────────────────────────────────────────────
async function apiAuthLogin(req, res) {
  try {
    const ip   = clientIp(req);
    if (!checkLoginRateLimit(ip))
      return json(res, 429, { error: 'Too many attempts. Wait 15 minutes.' });

    const body = await readBody(req);
    const { username, password } = body;
    if (!username || !password) return json(res, 400, { error: 'Username and password are required' });

    if (!db) return json(res, 503, { error: 'Database unavailable' });

    const user = db.prepare('SELECT * FROM panel_users WHERE username = ?').get(username);
    if (!user) {
      // Run verifyPassword against the dummy hash so the no-user branch costs
      // the same wall-clock time as the bad-password branch. Without this, an
      // attacker can enumerate valid usernames by measuring response time —
      // ~50ms for real users (scrypt) vs <1ms for unknowns.
      verifyPassword(password, _DUMMY_LOGIN_SALT, _DUMMY_LOGIN_HASH);
      return json(res, 401, { error: 'Invalid username or password' });
    }

    if (!verifyPassword(password, user.salt, user.password_hash))
      return json(res, 401, { error: 'Invalid username or password' });

    // Second factor. When 2FA is enabled on this account, password alone is
    // not enough — the client must also send a 6-digit TOTP code in `totp`.
    // We respond { needsTotp: true } so the UI can render the second field
    // instead of treating the absence of `totp` as a generic auth failure.
    // The TOTP check itself counts against the same rate-limit bucket as a
    // bad password so a brute-forcer cannot grind through the 1M code space.
    if (user.totp_enabled === 1 && user.totp_secret) {
      const submittedCode = String(body.totp || '').replace(/\s/g, '');
      if (!submittedCode) {
        return json(res, 200, { ok: false, needsTotp: true });
      }
      if (!totpVerify(user.totp_secret, submittedCode)) {
        return json(res, 401, { error: 'Invalid 2FA code', needsTotp: true });
      }
    }

    // Lazy upgrade: re-hash legacy pbkdf2 entries with scrypt on successful login
    if (!user.password_hash.startsWith('scrypt$')) {
      try { db.prepare('UPDATE panel_users SET password_hash = ? WHERE username = ?')
        .run(hashPasswordScrypt(password, user.salt), username); } catch {}
    }

    _clearLoginAttempt(ip); // reset on success
    const token = createSession(username, user.role);
    res.setHeader('Set-Cookie', sessionCookieHeader(token, requestIsHttps(req)));
    const permissions = user.role === 'admin'
      ? Object.fromEntries(ROLE_PERMISSIONS.map(p => [p, true]))
      : getUserRolePermissions();
    json(res, 200, { ok: true, user: { name: username, role: user.role, mustChangePassword: user.must_change_password === 1, twoFactorEnabled: user.totp_enabled === 1, permissions } });
  } catch (e) { json(res, 500, { error: e.message }); }
}

// ── 2FA / TOTP endpoints ─────────────────────────────────────────────────────
// Three-step flow:
//   1. POST /api/auth/2fa/setup     → server generates a fresh base32 secret,
//                                     stores it in totp_pending, returns the
//                                     secret + otpauth:// URI for the client
//                                     to render as QR + manual-entry key.
//   2. POST /api/auth/2fa/confirm   → client sends a 6-digit code; if valid
//                                     against totp_pending, the secret is
//                                     promoted to totp_secret + totp_enabled=1
//                                     and the pending slot cleared. Now the
//                                     account requires 2FA on every login.
//   3. POST /api/auth/2fa/disable   → requires the current password (proves
//                                     it's the live user, not a stolen cookie)
//                                     and a TOTP code (proves the user still
//                                     has the authenticator). Clears the
//                                     secret + enabled flag.
async function apiAuth2faSetup(req, res) {
  const sess = getSession(req);
  if (!sess) return json(res, 401, { error: 'Unauthorized' });
  if (!db) return json(res, 503, { error: 'Database unavailable' });
  // 20 random bytes → 32-char base32 secret (RFC 4226 minimum is 16 bytes for
  // SHA-1; 20 matches what most authenticator apps assume).
  const secret = _base32Encode(crypto.randomBytes(20));
  try {
    db.prepare('UPDATE panel_users SET totp_pending = ? WHERE username = ?').run(secret, sess.username);
  } catch (e) { return json(res, 500, { error: e.message }); }
  const otpauth = totpProvisioningUri({
    secret,
    account: sess.username,
    issuer:  'BeamNG Server Panel',
  });
  json(res, 200, { ok: true, secret, otpauth });
}

async function apiAuth2faConfirm(req, res) {
  try {
    const sess = getSession(req);
    if (!sess) return json(res, 401, { error: 'Unauthorized' });
    const ip = clientIp(req);
    if (!checkLoginRateLimit(ip))
      return json(res, 429, { error: 'Too many attempts. Wait 15 minutes.' });
    const body = await readBody(req);
    const code = String(body.code || '').replace(/\s/g, '');
    if (!/^\d{6}$/.test(code)) return json(res, 400, { error: 'code must be 6 digits' });
    if (!db) return json(res, 503, { error: 'Database unavailable' });
    const row = db.prepare('SELECT totp_pending FROM panel_users WHERE username = ?').get(sess.username);
    if (!row?.totp_pending) return json(res, 400, { error: 'No pending 2FA setup. Call /api/auth/2fa/setup first.' });
    if (!totpVerify(row.totp_pending, code)) return json(res, 401, { error: 'Invalid code. Make sure your authenticator clock is in sync.' });
    db.prepare(`UPDATE panel_users
                   SET totp_secret = totp_pending,
                       totp_pending = '',
                       totp_enabled = 1
                 WHERE username = ?`).run(sess.username);
    _clearLoginAttempt(ip);
    insertAuditLog(sess.username, 'user.2fa.enable', sess.username);
    json(res, 200, { ok: true });
  } catch (e) { json(res, 500, { error: e.message }); }
}

async function apiAuth2faDisable(req, res) {
  try {
    const sess = getSession(req);
    if (!sess) return json(res, 401, { error: 'Unauthorized' });
    const ip = clientIp(req);
    if (!checkLoginRateLimit(ip))
      return json(res, 429, { error: 'Too many attempts. Wait 15 minutes.' });
    const body = await readBody(req);
    const currentPassword = String(body.currentPassword || '');
    const code = String(body.code || '').replace(/\s/g, '');
    if (!currentPassword || !code) return json(res, 400, { error: 'currentPassword and code are required' });
    if (!db) return json(res, 503, { error: 'Database unavailable' });
    const user = db.prepare('SELECT * FROM panel_users WHERE username = ?').get(sess.username);
    if (!user) return json(res, 404, { error: 'User not found' });
    if (!verifyPassword(currentPassword, user.salt, user.password_hash))
      return json(res, 401, { error: 'Current password is incorrect' });
    if (!user.totp_enabled || !user.totp_secret)
      return json(res, 400, { error: '2FA is not currently enabled' });
    if (!totpVerify(user.totp_secret, code))
      return json(res, 401, { error: 'Invalid 2FA code' });
    db.prepare(`UPDATE panel_users
                   SET totp_secret = '',
                       totp_pending = '',
                       totp_enabled = 0
                 WHERE username = ?`).run(sess.username);
    _clearLoginAttempt(ip);
    insertAuditLog(sess.username, 'user.2fa.disable', sess.username);
    json(res, 200, { ok: true });
  } catch (e) { json(res, 500, { error: e.message }); }
}

// Rotate the TOTP secret without going through disable → setup. The user
// already has 2FA on, wants a fresh secret (lost device, new authenticator
// app, periodic rotation), and shouldn't have to leave the account
// without a second factor in between. Atomic in two phases like setup:
//   1. This endpoint requires currentPassword + a code from the CURRENT
//      secret (so a stolen session cookie can't replace the secret) and
//      stages a fresh base32 in totp_pending. totp_secret stays put, so
//      the old code still logs the user in if they back out here.
//   2. The user confirms with the existing /api/auth/2fa/confirm flow,
//      which promotes totp_pending → totp_secret and the old secret is
//      gone for good. Until that confirm, the rotation is reversible —
//      just don't re-scan the QR.
async function apiAuth2faRotate(req, res) {
  try {
    const sess = getSession(req);
    if (!sess) return json(res, 401, { error: 'Unauthorized' });
    const ip = clientIp(req);
    if (!checkLoginRateLimit(ip))
      return json(res, 429, { error: 'Too many attempts. Wait 15 minutes.' });
    const body = await readBody(req);
    const currentPassword = String(body.currentPassword || '');
    const code = String(body.code || '').replace(/\s/g, '');
    if (!currentPassword || !code) return json(res, 400, { error: 'currentPassword and code are required' });
    if (!db) return json(res, 503, { error: 'Database unavailable' });
    const user = db.prepare('SELECT * FROM panel_users WHERE username = ?').get(sess.username);
    if (!user) return json(res, 404, { error: 'User not found' });
    if (!user.totp_enabled || !user.totp_secret)
      return json(res, 400, { error: '2FA is not currently enabled — call /api/auth/2fa/setup instead' });
    if (!verifyPassword(currentPassword, user.salt, user.password_hash))
      return json(res, 401, { error: 'Current password is incorrect' });
    if (!totpVerify(user.totp_secret, code))
      return json(res, 401, { error: 'Invalid 2FA code' });
    // Stage the new secret. Same shape as apiAuth2faSetup so the Profile
    // page can reuse its existing QR + confirm flow with one extra header
    // saying "you're rotating, not enrolling".
    const secret = _base32Encode(crypto.randomBytes(20));
    db.prepare('UPDATE panel_users SET totp_pending = ? WHERE username = ?').run(secret, sess.username);
    const otpauth = totpProvisioningUri({
      secret,
      account: sess.username,
      issuer:  'BeamNG Server Panel',
    });
    _clearLoginAttempt(ip);
    insertAuditLog(sess.username, 'user.2fa.rotate', sess.username);
    json(res, 200, { ok: true, secret, otpauth, rotating: true });
  } catch (e) { json(res, 500, { error: e.message }); }
}

// Status endpoint for the Profile page UI — returns whether 2FA is on for the
// current session's user, and whether a pending (un-confirmed) setup exists.
function apiAuth2faStatus(req, res) {
  const sess = getSession(req);
  if (!sess) return json(res, 401, { error: 'Unauthorized' });
  if (!db) return json(res, 200, { enabled: false, pending: false });
  const row = db.prepare('SELECT totp_enabled, totp_pending FROM panel_users WHERE username = ?').get(sess.username);
  json(res, 200, {
    enabled: row?.totp_enabled === 1,
    pending: !!(row?.totp_pending && row.totp_pending.length > 0),
  });
}

function apiAuthLogout(req, res) {
  const token = readCookie(req, 'sid');
  if (token) deleteSession(token);
  // Mirror the Secure flag on the clearing cookie. Some browsers refuse to
  // overwrite a Secure cookie via a non-Secure Set-Cookie response, so the
  // expired sid would linger in the jar.
  const secure = requestIsHttps(req) ? '; Secure' : '';
  res.setHeader('Set-Cookie', `sid=; HttpOnly; SameSite=Strict; Path=/; Max-Age=0${secure}`);
  json(res, 200, { ok: true });
}

function apiAuthMe(req, res) {
  const sess = getSession(req);
  if (!sess) return json(res, 401, { error: 'Not authenticated' });
  // db can be null when SQLite init failed at startup. Guard the lookup so the
  // request returns a sensible payload instead of crashing the handler with
  // "Cannot read properties of undefined (reading 'get')".
  let mustChange = false;
  let twoFactorEnabled = false;
  if (db) {
    try {
      const row = db.prepare('SELECT must_change_password, totp_enabled FROM panel_users WHERE username = ?').get(sess.username);
      mustChange = row?.must_change_password === 1;
      twoFactorEnabled = row?.totp_enabled === 1;
    } catch {}
  }
  const permissions = sess.role === 'admin'
    ? Object.fromEntries(ROLE_PERMISSIONS.map(p => [p, true]))
    : getUserRolePermissions();
  json(res, 200, { username: sess.username, role: sess.role, mustChangePassword: mustChange, twoFactorEnabled, permissions });
}

async function apiAuthChangePassword(req, res) {
  try {
    // Require a valid session — username is derived from it, not from the body
    const sess = getSession(req);
    if (!sess) return json(res, 401, { error: 'Unauthorized' });

    const ip = clientIp(req);
    if (!checkLoginRateLimit(ip))
      return json(res, 429, { error: 'Too many attempts. Wait 15 minutes.' });

    const body = await readBody(req);
    const { currentPassword, newPassword } = body;
    if (!currentPassword || !newPassword)
      return json(res, 400, { error: 'All fields are required' });
    const policyErr = passwordPolicyError(newPassword);
    if (policyErr) return json(res, 400, { error: policyErr });
    if (!db) return json(res, 503, { error: 'Database unavailable' });

    const username = sess.username;
    const user = db.prepare('SELECT * FROM panel_users WHERE username = ?').get(username);
    if (!user) return json(res, 404, { error: 'User not found' });

    if (!verifyPassword(currentPassword, user.salt, user.password_hash))
      return json(res, 401, { error: 'Current password is incorrect' });

    const newSalt = crypto.randomBytes(32).toString('hex');
    db.prepare('UPDATE panel_users SET password_hash = ?, salt = ?, must_change_password = 0 WHERE username = ?')
      .run(hashPassword(newPassword, newSalt), newSalt, username);

    // Purge every existing session for this user — including the one that just
    // changed the password — and mint a fresh one for the active request. If
    // the request that reached this endpoint was actually an attacker on a
    // stolen cookie, the legitimate user's password change now invalidates
    // every device that had cached state, not just future ones. Then refresh
    // the response cookie so the legitimate browser stays logged in.
    try { db.prepare('DELETE FROM sessions WHERE username = ?').run(username); } catch {}
    const newToken = createSession(username, user.role);
    res.setHeader('Set-Cookie', sessionCookieHeader(newToken, requestIsHttps(req)));

    _clearLoginAttempt(ip);
    insertAuditLog(username, 'user.update', username, 'self password change');
    json(res, 200, { ok: true });
  } catch (e) { json(res, 500, { error: e.message }); }
}

// ── Panel users CRUD ─────────────────────────────────────────────────────────
function apiPanelUsers(req, res) {
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  if (!db) return json(res, 200, []);
  const rows = db.prepare('SELECT username, role, created_at FROM panel_users ORDER BY created_at').all();
  json(res, 200, rows.map(r => ({
    id:      r.username,
    name:    r.username,
    role:    r.role,
    created: (r.created_at || '').slice(0, 10),
  })));
}

async function apiPanelUserCreate(req, res) {
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  try {
    const body = await readBody(req);
    const { username, password, role } = body;
    if (!username || !password) return json(res, 400, { error: 'Username and password are required' });
    if (typeof username !== 'string' || !/^[a-zA-Z0-9_-]{1,64}$/.test(username))
      return json(res, 400, { error: 'Username must be 1–64 chars: letters, numbers, _ and - only' });
    {
      const policyErr = passwordPolicyError(password);
      if (policyErr) return json(res, 400, { error: policyErr });
    }
    // Reject unknown roles instead of silently coercing — caller intent stays explicit
    if (role !== undefined && role !== 'admin' && role !== 'user')
      return json(res, 400, { error: 'role must be "admin" or "user"' });
    if (!db) return json(res, 503, { error: 'Database unavailable' });
    // Case-insensitive uniqueness — 'admin' and 'Admin' must not coexist
    const exists = db.prepare('SELECT 1 FROM panel_users WHERE LOWER(username) = LOWER(?)').get(username);
    if (exists) return json(res, 409, { error: 'Username already exists' });
    const salt = crypto.randomBytes(32).toString('hex');
    const finalRole = role || 'user';
    db.prepare('INSERT INTO panel_users (username, password_hash, salt, role) VALUES (?, ?, ?, ?)')
      .run(username, hashPassword(password, salt), salt, finalRole);
    insertAuditLog(checkAnyAuth(req)?.username || 'unknown', 'user.create', username, finalRole);
    json(res, 200, { ok: true });
  } catch (e) { json(res, 500, { error: e.message }); }
}

async function apiPanelUserUpdate(req, res, username) {
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  try {
    const body = await readBody(req);
    if (!db) return json(res, 503, { error: 'Database unavailable' });
    const user = db.prepare('SELECT * FROM panel_users WHERE username = ?').get(username);
    if (!user) return json(res, 404, { error: 'User not found' });
    const changes = [];
    if (body.role !== undefined && (body.role === 'admin' || body.role === 'user')) {
      // Refuse to demote the last admin — mirrors apiPanelUserDelete. Without
      // this guard an admin could promote themselves out of the role and lock
      // the panel for everyone (no admin = no recoverable login).
      if (body.role === 'user' && user.role === 'admin') {
        const adminCount = db.prepare(`SELECT COUNT(*) AS n FROM panel_users WHERE role = 'admin'`).get().n;
        if (adminCount <= 1) return json(res, 400, { error: 'Cannot demote the last admin' });
      }
      db.prepare('UPDATE panel_users SET role = ? WHERE username = ?').run(body.role, username);
      // Sessions cache the role at login time (see createSession), so a live
      // session for this user would keep the old role until it expires. Wipe
      // every session so the new role takes effect on the next request — both
      // demotions (admin → user must lose admin instantly) and promotions
      // (user → admin should reload permissions) need the bounce.
      if (body.role !== user.role) {
        try { db.prepare('DELETE FROM sessions WHERE username = ?').run(username); } catch {}
      }
      changes.push(`role=${body.role}`);
    }
    if (body.password) {
      const policyErr = passwordPolicyError(body.password);
      if (policyErr) return json(res, 400, { error: policyErr });
      const s = crypto.randomBytes(32).toString('hex');
      db.prepare('UPDATE panel_users SET password_hash = ?, salt = ? WHERE username = ?')
        .run(hashPassword(body.password, s), s, username);
      // Revoke all live sessions for this user — admin reset must kick the user out
      try { db.prepare('DELETE FROM sessions WHERE username = ?').run(username); } catch {}
      changes.push('password changed');
    }
    if (changes.length) insertAuditLog(checkAnyAuth(req)?.username || 'unknown', 'user.update', username, changes.join(', '));
    json(res, 200, { ok: true });
  } catch (e) { json(res, 500, { error: e.message }); }
}

function apiPanelUserDelete(req, res, username) {
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  if (!db) return json(res, 503, { error: 'Database unavailable' });
  // Refuse to leave the panel without admins
  try {
    const target = db.prepare('SELECT role FROM panel_users WHERE username = ?').get(username);
    if (target?.role === 'admin') {
      const adminCount = db.prepare(`SELECT COUNT(*) AS n FROM panel_users WHERE role = 'admin'`).get().n;
      if (adminCount <= 1) return json(res, 400, { error: 'Cannot delete the last admin' });
    }
  } catch {}
  db.prepare('DELETE FROM panel_users WHERE username = ?').run(username);
  try { db.prepare('DELETE FROM sessions WHERE username = ?').run(username); } catch {}
  insertAuditLog(checkAnyAuth(req)?.username || 'unknown', 'user.delete', username);
  json(res, 200, { ok: true });
}

// ── Panel settings (upload_max_mb, etc.) ──────────────────────────────────────
function apiPanelSettingsGet(req, res) {
  if (!db) return json(res, 200, { uploadMaxMb: 500, chunkedUpload: false, lang: 'en', discordWebhook: '', publicProfilesEnabled: true });
  const mbRow       = db.prepare(`SELECT value FROM panel_settings WHERE key = 'upload_max_mb'`).get();
  const langRow     = db.prepare(`SELECT value FROM panel_settings WHERE key = 'lang'`).get();
  const chunkedRow  = db.prepare(`SELECT value FROM panel_settings WHERE key = 'chunked_upload'`).get();
  const webhookRow  = db.prepare(`SELECT value FROM panel_settings WHERE key = 'discord_webhook'`).get();
  const publicRow   = db.prepare(`SELECT value FROM panel_settings WHERE key = 'public_profiles_enabled'`).get();
  // The webhook URL is effectively a secret (anyone with it can post to the
  // channel). Return the raw value only to admins or to users with the
  // discordWebhook permission. Everyone else just gets the configured flag so
  // the UI can render a disabled placeholder.
  const canSeeWebhook = checkPermission(req, 'discordWebhook');
  json(res, 200, {
    uploadMaxMb:    parseInt(mbRow?.value || '500', 10),
    lang:           langRow?.value || 'en',
    chunkedUpload:  chunkedRow?.value === '1',
    discordWebhook: canSeeWebhook ? (webhookRow?.value || '') : '',
    discordConfigured: !!(webhookRow?.value),
    publicProfilesEnabled: publicRow?.value !== '0',
  });
}

function isValidDiscordWebhook(url) {
  if (typeof url !== 'string') return false;
  if (url === '') return true; // empty clears the setting
  return /^https:\/\/(canary\.|ptb\.)?discord(app)?\.com\/api\/webhooks\/\d{17,20}\/[A-Za-z0-9_-]{50,}$/.test(url);
}

async function apiPanelSettingsPut(req, res) {
  // discordWebhook is the only field a permissioned user can edit; everything
  // else here (upload limits, panel-wide language default, chunked toggle)
  // stays admin-only because they affect every panel user.
  const isAdmin       = checkAdminAuth(req);
  const canSetWebhook = checkPermission(req, 'discordWebhook');
  if (!isAdmin && !canSetWebhook) return json(res, 403, { error: 'Forbidden' });
  if (!db) return json(res, 503, { error: 'Database unavailable' });
  try {
    const body = await readBody(req);
    if (body.uploadMaxMb !== undefined) {
      if (!isAdmin) return json(res, 403, { error: 'Forbidden (admin only)' });
      const mb = parseInt(body.uploadMaxMb, 10);
      if (!mb || mb < 1 || mb > 10240) return json(res, 400, { error: 'Invalid value (1–10240 MB)' });
      db.prepare(`INSERT OR REPLACE INTO panel_settings (key, value) VALUES ('upload_max_mb', ?)`).run(String(mb));
    }
    if (body.lang !== undefined) {
      if (!isAdmin) return json(res, 403, { error: 'Forbidden (admin only)' });
      if (!['en', 'es', 'it'].includes(body.lang)) return json(res, 400, { error: 'Unsupported language' });
      db.prepare(`INSERT OR REPLACE INTO panel_settings (key, value) VALUES ('lang', ?)`).run(body.lang);
    }
    if (body.chunkedUpload !== undefined) {
      if (!isAdmin) return json(res, 403, { error: 'Forbidden (admin only)' });
      db.prepare(`INSERT OR REPLACE INTO panel_settings (key, value) VALUES ('chunked_upload', ?)`).run(body.chunkedUpload ? '1' : '0');
    }
    if (body.discordWebhook !== undefined) {
      if (!canSetWebhook) return json(res, 403, { error: 'Forbidden' });
      const url = typeof body.discordWebhook === 'string' ? body.discordWebhook.trim() : '';
      if (!isValidDiscordWebhook(url)) return json(res, 400, { error: 'Invalid Discord webhook URL' });
      db.prepare(`INSERT OR REPLACE INTO panel_settings (key, value) VALUES ('discord_webhook', ?)`).run(url);
      insertAuditLog(checkAnyAuth(req)?.username || 'unknown', 'panel.discord_webhook', '', url ? 'set' : 'cleared');
    }
    if (body.publicProfilesEnabled !== undefined) {
      if (!isAdmin) return json(res, 403, { error: 'Forbidden (admin only)' });
      const next = body.publicProfilesEnabled ? '1' : '0';
      db.prepare(`INSERT OR REPLACE INTO panel_settings (key, value) VALUES ('public_profiles_enabled', ?)`).run(next);
      insertAuditLog(checkAnyAuth(req)?.username || 'unknown', 'panel.public_profiles', '', next === '1' ? 'enabled' : 'disabled');
    }
    json(res, 200, { ok: true });
  } catch (e) { json(res, 500, { error: e.message }); }
}

// ── Role permissions ─────────────────────────────────────────────────────────
// Admin-managed toggles that control what users with role='user' can do.
// Effective perms for the current session are returned by /api/auth/me; these
// endpoints are for the admin UI to read/write the canonical role config.

function apiRolePermissionsGet(req, res) {
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  json(res, 200, { permissions: getUserRolePermissions() });
}

async function apiRolePermissionsPut(req, res) {
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  if (!db) return json(res, 503, { error: 'Database unavailable' });
  try {
    const body = await readBody(req);
    const next = {};
    for (const p of ROLE_PERMISSIONS) next[p] = !!body[p];
    db.prepare(`INSERT OR REPLACE INTO panel_settings (key, value) VALUES ('role_permissions_user', ?)`)
      .run(JSON.stringify(next));
    insertAuditLog(checkAnyAuth(req)?.username || 'unknown', 'role.permissions.update', 'user',
      Object.entries(next).filter(([, v]) => v).map(([k]) => k).join(',') || '(none)');
    json(res, 200, { ok: true, permissions: next });
  } catch (e) { json(res, 500, { error: e.message }); }
}

// Posts a synchronous test message to the Discord webhook. Accepts an optional
// `url` in the body so the UI can verify a URL before saving it; if absent, the
// stored one is used. Responds only after Discord answers (or times out) so the
// admin gets a definitive ok/error in the toast.
async function apiDiscordWebhookTest(req, res) {
  if (!checkPermission(req, 'discordWebhook')) return json(res, 403, { error: 'Forbidden' });
  try {
    const body = await readBody(req);
    let url = typeof body.url === 'string' ? body.url.trim() : '';
    if (!url) url = getDiscordWebhook();
    if (!url)          return json(res, 400, { error: 'No webhook configured' });
    if (!isValidDiscordWebhook(url) || url === '') return json(res, 400, { error: 'Invalid Discord webhook URL' });

    const lang = getPanelLang();
    const content = DISCORD_TEST_TEMPLATES[lang] || DISCORD_TEST_TEMPLATES.en;
    const payload = JSON.stringify({ content });

    let parsed;
    try { parsed = new URL(url); } catch { return json(res, 400, { error: 'Invalid Discord webhook URL' }); }
    // Authoritative SSRF gate — even if isValidDiscordWebhook's regex were to
    // accept a unicode-trick URL (or a future regex relaxation lets something
    // through), the resolved hostname must literally be on the Discord list.
    if (!DISCORD_WEBHOOK_HOSTS.has(parsed.hostname.toLowerCase())) {
      return json(res, 400, { error: 'Invalid Discord webhook URL' });
    }

    // Cap how much of Discord's response body we buffer. The previous code
    // sliced each chunk to 512 bytes but appended to `buf` without limit, so a
    // pathological server returning many tiny chunks could grow `buf`
    // unbounded. Limit `buf` total length at 1 KB — plenty for an error message.
    const BUF_CAP = 1024;
    await new Promise((resolve) => {
      const r = https.request({
        method: 'POST',
        hostname: parsed.hostname,
        path: parsed.pathname + parsed.search,
        headers: {
          'Content-Type':   'application/json',
          'Content-Length': Buffer.byteLength(payload),
          'User-Agent':     'beamng-server-panel',
        },
        timeout: 5000,
      }, (resp) => {
        let buf = '';
        resp.on('data', (c) => {
          if (buf.length < BUF_CAP) buf += c.toString().slice(0, BUF_CAP - buf.length);
        });
        resp.on('end', () => {
          if (resp.statusCode < 400) {
            json(res, 200, { ok: true });
          } else {
            json(res, 502, { error: `Discord responded ${resp.statusCode}: ${buf.slice(0, 200)}` });
          }
          resolve();
        });
      });
      r.on('timeout', () => { r.destroy(); json(res, 504, { error: 'Discord webhook timed out' }); resolve(); });
      r.on('error', (e) => { json(res, 502, { error: e.message }); resolve(); });
      r.write(payload);
      r.end();
    });
  } catch (e) { try { json(res, 500, { error: e.message }); } catch {} }
}

// ── Multipart parser (native, no dependencies) ────────────────────────────────
// Streaming multipart parser. The file field is piped directly to a temp file
// as bytes arrive, so the panel never holds the full upload (potentially up to
// UPLOAD_HARD_CAP_BYTES) in RAM. Other fields are kept as small buffers — they
// are typically just option flags.
//
// Returned shape (compatible with the buffered version it replaces):
//   { fieldName: { filename, filePath, size }   for the file part
//     fieldName: 'string value'                 for plain text fields }
//
// Caller owns filePath and must unlink() it when done.
function parseMultipart(req, maxBytes) {
  return new Promise((resolve, reject) => {
    const ct = req.headers['content-type'] || '';
    const bmatch = ct.match(/boundary=([^\s;]+)/);
    if (!bmatch) return reject(new Error('Missing multipart boundary'));
    const dashBoundary = Buffer.from('--' + bmatch[1]);
    const dashBoundaryWithCRLF = Buffer.from('\r\n--' + bmatch[1]);

    const result = {};
    let total    = 0;
    let buf      = Buffer.alloc(0);
    let state    = 'PREAMBLE'; // PREAMBLE → HEADERS → DATA(field|file) → PREAMBLE…
    let curName  = null;
    let curFilename = null;
    let fieldBuf = null;
    let fileWriter = null;
    let filePath   = null;
    let bytesWritten = 0;
    let aborted    = false;

    const fail = (err) => {
      if (aborted) return;
      aborted = true;
      try { req.destroy(); } catch {}
      if (fileWriter) {
        try { fileWriter.destroy(); } catch {}
        if (filePath) fsp.unlink(filePath).catch(() => {});
      }
      reject(err);
    };

    const finishPart = () => {
      if (!curName) return;
      if (curFilename != null) {
        // Close file writer; record filePath/size in result
        if (fileWriter) {
          fileWriter.end();
          fileWriter = null;
        }
        result[curName] = { filename: curFilename, filePath, size: bytesWritten };
        filePath = null;
        bytesWritten = 0;
      } else {
        result[curName] = (fieldBuf || Buffer.alloc(0)).toString('utf8');
      }
      curName = null;
      curFilename = null;
      fieldBuf = null;
    };

    req.on('data', (chunk) => {
      if (aborted) return;
      total += chunk.length;
      if (total > maxBytes)
        return fail(Object.assign(new Error('File too large'), { code: 'ELIMIT' }));
      buf = buf.length === 0 ? chunk : Buffer.concat([buf, chunk]);
      processBuffer();
    });
    req.on('error', fail);
    req.on('end', () => {
      if (aborted) return;
      processBuffer(true);
      finishPart();
      resolve(result);
    });

    function processBuffer(isEnd = false) {
      while (true) {
        if (state === 'PREAMBLE') {
          // Skip everything up to the first boundary marker
          const idx = buf.indexOf(dashBoundary);
          if (idx === -1) { buf = buf.slice(Math.max(0, buf.length - dashBoundary.length)); return; }
          buf = buf.slice(idx + dashBoundary.length);
          // Closing boundary?
          if (buf.length >= 2 && buf[0] === 0x2d && buf[1] === 0x2d) { buf = Buffer.alloc(0); return; }
          // Skip the trailing CRLF after the boundary marker
          if (buf.length >= 2 && buf[0] === 0x0d && buf[1] === 0x0a) buf = buf.slice(2);
          state = 'HEADERS';
        } else if (state === 'HEADERS') {
          const headerEnd = buf.indexOf(Buffer.from('\r\n\r\n'));
          if (headerEnd === -1) {
            if (isEnd) return fail(new Error('Truncated multipart headers'));
            return;
          }
          const headerStr = buf.slice(0, headerEnd).toString('utf8');
          buf = buf.slice(headerEnd + 4);
          const nameMatch = headerStr.match(/name="([^"]+)"/);
          const fileMatch = headerStr.match(/filename="([^"]+)"/);
          if (!nameMatch) return fail(new Error('Multipart part missing name'));
          curName = nameMatch[1];
          curFilename = fileMatch ? fileMatch[1] : null;
          if (curFilename != null) {
            // Open a temp file for streaming
            const safeName = path.basename(curFilename).replace(/[^a-zA-Z0-9_.\-]/g, '_').slice(0, 64);
            filePath = path.join(os.tmpdir(), `ac-upload-${Date.now()}-${crypto.randomBytes(4).toString('hex')}-${safeName}`);
            fileWriter = fs.createWriteStream(filePath);
            fileWriter.on('error', e => fail(Object.assign(new Error(`Disk write failed: ${e.message}`), { status: 500 })));
            bytesWritten = 0;
          } else {
            fieldBuf = Buffer.alloc(0);
          }
          state = 'DATA';
        } else if (state === 'DATA') {
          const idx = buf.indexOf(dashBoundaryWithCRLF);
          if (idx === -1) {
            // Keep enough bytes to detect a boundary that spans the next chunk
            const safe = Math.max(0, buf.length - dashBoundaryWithCRLF.length);
            if (safe > 0) {
              const slice = buf.slice(0, safe);
              if (curFilename != null) {
                bytesWritten += slice.length;
                if (!fileWriter.write(slice)) {
                  // backpressure — we don't drain since req.on('data') has already been delivered;
                  // the writer is still buffering, esbuild ones are fine in practice
                }
              } else {
                fieldBuf = Buffer.concat([fieldBuf, slice]);
              }
              buf = buf.slice(safe);
            }
            if (isEnd) return fail(new Error('Truncated multipart body'));
            return;
          }
          // Found the next boundary — write everything before it as the part's data
          const partData = buf.slice(0, idx);
          if (curFilename != null) {
            bytesWritten += partData.length;
            fileWriter.write(partData);
          } else {
            fieldBuf = Buffer.concat([fieldBuf, partData]);
          }
          buf = buf.slice(idx + 2); // consume the leading \r\n; leave the boundary itself for next state
          finishPart();
          state = 'PREAMBLE';
        }
      }
    }
  });
}

// ── Archive extractor — returns flat list of { name, getData } ────────────────
const ALLOWED_MOD_EXTS = new Set([
  '.kn5','.acd','.ini','.json','.csv','.txt','.xml','.lua',
  '.png','.jpg','.jpeg','.webp','.dds','.bmp',
  '.wav','.ogg','.mp3','.bank',
  '.bin','.lut','.rto','.sfx','.ksanim','.ksemitter',
  '.hdr','.pfm','.tga','.raw','.ksg','.kn5',
]);

function isSafeEntry(entryName, destRoot) {
  // Anti Zip-Slip: resolved path must start with destRoot
  const resolved = path.resolve(destRoot, entryName.replace(/[\\/]+/g, path.sep));
  return resolved.startsWith(destRoot + path.sep) || resolved === destRoot;
}

// POSIX file-mode constant for a symbolic link. ZIP entries store the unix
// permission bits in the upper 16 bits of `attr` (the external file
// attributes field). We use this to flag symlink entries and reject them at
// the processing layer — see processModBuffer.
const S_IFLNK = 0o120000;
const S_IFMT  = 0o170000;

async function extractZip(buffer) {
  if (!StreamZip) throw new Error('node-stream-zip not available');
  // node-stream-zip v1.x only accepts a file path, not a buffer
  const tmpIn = path.join(os.tmpdir(), `ac-mod-${Date.now()}-${crypto.randomBytes(4).toString('hex')}.zip`);
  await fsp.writeFile(tmpIn, buffer);
  const zip = new StreamZip.async({ file: tmpIn });
  const entries = await zip.entries();
  const list = [];
  for (const [name, entry] of Object.entries(entries)) {
    // ZIP stores Unix permissions in the high 16 bits of the external attrs.
    // If the file-type bits say "symlink", flag it so processModBuffer can
    // refuse the whole archive instead of writing the symlink target text
    // out as a regular file (or, worse, following an earlier symlink entry).
    const unixMode = ((entry.attr || 0) >>> 16) & 0xFFFF;
    const isSymlink = (unixMode & S_IFMT) === S_IFLNK;
    list.push({
      name,
      isDirectory: entry.isDirectory,
      isSymlink,
      getData: async () => entry.isDirectory ? null : zip.entryData(name),
    });
  }
  return {
    entries: list,
    close: async () => {
      await Promise.resolve(zip.close()).catch(() => {});
      await fsp.rm(tmpIn, { force: true }).catch(() => {});
    },
  };
}

async function extract7z(buffer) {
  if (!sevenZ || !sevenBin) throw new Error('node-7z / 7zip-bin not available');
  const stamp  = `${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
  const tmpIn  = path.join(os.tmpdir(), `ac-mod-${stamp}.7z`);
  const tmpOut = path.join(os.tmpdir(), `ac-mod-${stamp}`);
  await fsp.writeFile(tmpIn, buffer);
  await fsp.mkdir(tmpOut, { recursive: true });
  await new Promise((resolve, reject) => {
    const stream = sevenZ.extractFull(tmpIn, tmpOut, { $bin: sevenBin.path7za });
    stream.on('end', resolve);
    stream.on('error', reject);
  });
  // Walk tmpOut and collect entries. Crucially: use lstat (via withFileTypes)
  // so a symlink restored by 7za is reported as `isSymbolicLink`, not followed
  // through to its target. processModBuffer then refuses the whole archive.
  // Without this, an entry like `data -> /etc` in the .7z would let a later
  // `physics.bin` entry land at `/etc/physics.bin` once an admin extracts.
  const list = [];
  const walk = async (dir, rel) => {
    const items = await fsp.readdir(dir, { withFileTypes: true });
    for (const item of items) {
      const itemRel = rel ? rel + '/' + item.name : item.name;
      if (item.isSymbolicLink()) {
        list.push({ name: itemRel, isDirectory: false, isSymlink: true, getData: async () => null });
        // Don't recurse through symlinks even if they point at directories.
        continue;
      }
      if (item.isDirectory()) {
        list.push({ name: itemRel + '/', isDirectory: true, isSymlink: false, getData: async () => null });
        await walk(path.join(dir, item.name), itemRel);
      } else {
        const fullPath = path.join(dir, item.name);
        list.push({ name: itemRel, isDirectory: false, isSymlink: false, getData: async () => fsp.readFile(fullPath) });
      }
    }
  };
  await walk(tmpOut, '');
  return {
    entries: list,
    close: async () => {
      await fsp.rm(tmpIn,  { force: true });
      await fsp.rm(tmpOut, { recursive: true, force: true });
    },
  };
}

async function extractRar(buffer) {
  if (!Unrar) throw new Error('node-unrar-js not available');
  // node-unrar-js v2 API
  const extractor = await Unrar.createExtractorFromData({ data: buffer });
  const { files } = extractor.extract();
  const list = [];
  for (const file of files) {
    const flags  = file.fileHeader.flags || {};
    const isDir  = !!flags.directory;
    // node-unrar-js v2 exposes a `symlink` flag on the header. It's optional —
    // older RARs without the link bit just produce `undefined` (falsy), which
    // is the safe default. Anything truthy here gets refused by processModBuffer.
    const isSymlink = !!flags.symlink;
    const data   = (isDir || isSymlink) ? null : Buffer.from(file.extraction);
    list.push({
      name:        file.fileHeader.name,
      isDirectory: isDir,
      isSymlink,
      getData:     async () => data,
    });
  }
  return { entries: list, close: () => {} };
}

async function extractArchive(buffer, ext) {
  if (ext === '.zip') return extractZip(buffer);
  if (ext === '.7z')  return extract7z(buffer);
  if (ext === '.rar') return extractRar(buffer);
  throw new Error(`Unsupported format: ${ext}`);
}

// ── Mod processing (shared by single and chunked upload) ─────────────────────
function insertModHistory(entry) {
  if (!db) return;
  try {
    db.prepare(`
      INSERT INTO mod_history (ok, filename, mod_type, mod_id, destination, files_extracted, error, uploaded_by)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
    `).run(
      entry.ok ? 1 : 0,
      entry.filename || null,
      entry.modType  || null,
      entry.modId    || null,
      entry.destination || null,
      entry.filesExtracted ?? null,
      entry.error    || null,
      entry.uploadedBy || null
    );
  } catch {}
}

// Hash-chain the audit log for tamper-evidence. Each row's row_hash =
// sha256(JSON.stringify([chain_version, prev, logged_at, actor, action, target, detail])).
// `tools/verify-audit.js` (or any consumer) can walk the table and recompute the
// chain — a tampered or deleted row breaks every subsequent hash. This does not
// prevent deletion (any admin with DB access can DROP), but it does prevent silent
// edits and lets external backups detect tampering by comparing chains.
//
// Chain versions:
//   0 — legacy `${prev}|${loggedAt}|${actor}|${action}|${target}|${detail}` (still
//       verified by the tool but no longer written; vulnerable to a separator-shift
//       collision when a field contained `|`).
//   1 — current. JSON.stringify of the field array; element boundaries are explicit
//       so a `|` inside detail/target cannot collide with a different field assignment.
const AUDIT_CHAIN_VERSION = 1;
function insertAuditLog(actor, action, target = '', detail = '') {
  if (!db) return;
  try {
    const tx = db.transaction(() => {
      const last = db.prepare('SELECT row_hash FROM audit_log ORDER BY id DESC LIMIT 1').get();
      const prev = last?.row_hash || '';
      const loggedAt = new Date().toISOString().replace('T', ' ').slice(0, 19);
      const data = JSON.stringify([AUDIT_CHAIN_VERSION, prev, loggedAt, actor, action, target, detail]);
      const rowHash = crypto.createHash('sha256').update(data).digest('hex');
      db.prepare(
        'INSERT INTO audit_log (actor, action, target, detail, logged_at, prev_hash, row_hash, chain_version) VALUES (?, ?, ?, ?, ?, ?, ?, ?)'
      ).run(actor, action, target, detail, loggedAt, prev, rowHash, AUDIT_CHAIN_VERSION);
    });
    tx();
  } catch (e) { log.warn('audit log insert failed:', e.message); }
}

// Admin: Prometheus exposition format. Scrape with HTTP basic / token auth or
// from a sidecar with the panel cookie. Each metric is a snapshot — no rate
// stats are kept in memory beyond the basic counters in `_sweeperState`.
async function apiAdminMetricsProm(req, res) {
  if (!checkAdminAuth(req)) return respond(res, 401, 'text/plain', 'Unauthorized');
  const lines = [];
  const m = (name, type, help, value, labels) => {
    lines.push(`# HELP ${name} ${help}`);
    lines.push(`# TYPE ${name} ${type}`);
    const lbl = labels ? `{${Object.entries(labels).map(([k, v]) => `${k}="${v}"`).join(',')}}` : '';
    lines.push(`${name}${lbl} ${value}`);
  };
  m('panel_uptime_seconds',         'counter', 'Process uptime in seconds',                          Math.floor(process.uptime()));
  m('panel_memory_rss_bytes',       'gauge',   'Resident memory size of the Node process',          process.memoryUsage().rss);
  m('panel_sse_clients',            'gauge',   'Active Server-Sent-Events connections',              sseClients.size);
  m('panel_active_uploads',         'gauge',   'Per-user uploads currently in-flight',               _userUploads.size);
  m('panel_server_action_in_flight','gauge',   'Whether an AC start/stop/restart is running (0/1)',  _serverActionInFlight ? 1 : 0);
  if (db) {
    try { m('panel_sessions_total',          'gauge', 'Active panel sessions',          db.prepare('SELECT COUNT(*) AS n FROM sessions').get().n); } catch {}
    try { m('panel_panel_users_total',       'gauge', 'Configured panel users',         db.prepare('SELECT COUNT(*) AS n FROM panel_users').get().n); } catch {}
    try { m('panel_audit_log_total',         'gauge', 'Audit log entries',              db.prepare('SELECT COUNT(*) AS n FROM audit_log').get().n); } catch {}
    try { m('panel_login_attempts_total',    'gauge', 'Tracked login attempt buckets',  db.prepare('SELECT COUNT(*) AS n FROM login_attempts').get().n); } catch {}
    try { m('panel_mod_history_total',       'gauge', 'Mod uploads recorded',           db.prepare('SELECT COUNT(*) AS n FROM mod_history').get().n); } catch {}
  }
  // BeamMP-Server presence — best-effort from cached state, no fresh probe.
  m('beammp_server_up', 'gauge', 'Whether BeamMP-Server was up at the last poll (0/1)', _serverRunSince ? 1 : 0);
  if (_serverRunSince) m('beammp_server_uptime_seconds', 'counter', 'BeamMP-Server uptime since first detection', Math.floor((Date.now() - _serverRunSince) / 1000));
  for (const [name, st] of Object.entries(_sweeperState)) {
    if (st.lastRunAt) m('panel_sweeper_last_run_seconds', 'gauge', `Seconds since last sweep for ${name}`, Math.floor((Date.now() - st.lastRunAt) / 1000), { sweeper: name });
    m('panel_sweeper_last_removed_total', 'counter', `Last sweep removed count for ${name}`, st.lastRemoved, { sweeper: name });
  }
  respond(res, 200, 'text/plain; version=0.0.4; charset=utf-8', lines.join('\n') + '\n');
}

// Admin: panel internals snapshot for ops debugging. Returns sweeper status,
// table sizes, and current in-flight counters. Useful when "is the panel still
// alive?" can't be answered from the UI alone.
// Quick existence + type check for the BeamMP paths the panel needs. Used by
// /api/admin/stats and /api/setup/status to drive a setup banner in the UI.
async function _pathHealth() {
  const probe = async (p, kind) => {
    if (!p) return { path: p, exists: false, kind, missing: true };
    try {
      const st = await fsp.stat(p);
      const ok = kind === 'dir' ? st.isDirectory() : st.isFile();
      return { path: p, exists: true, kind, ok };
    } catch { return { path: p, exists: false, kind, missing: true }; }
  };
  return {
    serverDir:  await probe(BEAMMP_SERVER_DIR,            'dir'),
    serverBin:  await probe(BEAMMP_BIN,                   'file'),
    cfgFile:    await probe(BEAMMP_CFG_FILE,              'file'),
    resources:  await probe(BEAMMP_RESOURCES_DIR,         'dir'),
    clientMods: await probe(BEAMMP_CLIENT_RESOURCES_DIR,  'dir'),
    serverMods: await probe(BEAMMP_SERVER_RESOURCES_DIR,  'dir'),
  };
}

// Public endpoint: tells the frontend whether the panel is fully configured.
// Returns the boolean `ready` plus the per-path summary so the UI can render
// an actionable banner pointing operators at the specific path that's
// missing. No auth required because the same data is needed before any
// login can succeed if BEAMMP_SERVER_DIR is wrong.
//
// Absolute paths and the auto-detected root are stripped for unauthenticated
// callers — they're useful to an admin staring at the setup banner but pure
// signal to an external scanner trying to fingerprint the host's filesystem
// layout. Authenticated callers still see the full path so the banner stays
// actionable after login.
async function apiSetupStatus(req, res) {
  const paths = await _pathHealth();
  const critical = ['serverDir', 'cfgFile'];
  const issues = critical.filter(k => !paths[k] || !paths[k].exists);
  const isAuthed = !!checkAnyAuth(req);
  const publicPaths = {};
  for (const [k, v] of Object.entries(paths)) {
    publicPaths[k] = isAuthed
      ? v
      : { exists: v.exists, kind: v.kind, ok: v.ok, missing: v.missing };
  }
  json(res, 200, {
    ready: issues.length === 0,
    issues,
    paths: publicPaths,
    detectedServerRoot: isAuthed ? (_detectedServerRoot || null) : null,
  });
}

async function apiAdminStats(req, res) {
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  const counts = {};
  if (db) {
    try { counts.sessions       = db.prepare('SELECT COUNT(*) AS n FROM sessions').get().n; } catch {}
    try { counts.audit_log      = db.prepare('SELECT COUNT(*) AS n FROM audit_log').get().n; } catch {}
    try { counts.login_attempts = db.prepare('SELECT COUNT(*) AS n FROM login_attempts').get().n; } catch {}
    try { counts.panel_users    = db.prepare('SELECT COUNT(*) AS n FROM panel_users').get().n; } catch {}
    try { counts.bans           = db.prepare('SELECT COUNT(*) AS n FROM bans').get().n; } catch {}
    try { counts.mod_history    = db.prepare('SELECT COUNT(*) AS n FROM mod_history').get().n; } catch {}
  }
  let chunkDirs = 0;
  try { chunkDirs = (await fsp.readdir(CHUNK_TMP_DIR).catch(() => [])).length; } catch {}
  json(res, 200, {
    nodeVersion:        process.version,
    panelVersion:       require('./package.json').version,
    uptimeSec:          Math.floor(process.uptime()),
    memoryMb:           Math.round(process.memoryUsage().rss / 1024 / 1024),
    auditRetentionDays: AUDIT_RETENTION_DAYS,
    trustProxy:         TRUST_PROXY,
    serverActionInFlight: _serverActionInFlight,
    activeUploads:      _userUploads.size,
    pendingChunkDirs:   chunkDirs,
    sseClients:         sseClients.size,
    sweepers:           _sweeperState,
    counts,
    paths:              await _pathHealth(),
    backupConfig: {
      intervalHours: BACKUP_INTERVAL_HOURS,
      keep:          BACKUP_KEEP,
      dir:           BACKUP_DIR,
    },
  });
}

// Clinical-style health endpoint for ops dashboards / Kubernetes readiness
// probes / Uptime-Kuma. Unlike the public /api/health (which returns just
// { ok: true } and intentionally leaks no fingerprintable signal), this one
// is admin-gated and aggregates the disk + DB + process + BeamMP-Server
// checks into a status verdict the operator can alert on. HTTP code mirrors
// the verdict so an alerting rule can be a simple "non-2xx" check:
//   healthy   → 200 OK   (everything within thresholds)
//   degraded  → 200 OK   (advisory: free disk getting low, server expected up but down, …)
//   unhealthy → 503      (DB unavailable, disk effectively full, …)
async function apiAdminHealth(req, res) {
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  const checks = {};
  let worst = 'healthy';
  const escalate = level => {
    if (level === 'unhealthy' || worst === 'unhealthy') worst = 'unhealthy';
    else if (level === 'degraded') worst = 'degraded';
  };

  try {
    db.prepare('SELECT 1').get();
    const st = await fsp.stat(DB_PATH).catch(() => null);
    checks.db = { status: 'healthy', sizeMb: st ? Math.round(st.size / 1024 / 1024 * 100) / 100 : null };
  } catch (e) {
    checks.db = { status: 'unhealthy', error: e.message };
    escalate('unhealthy');
  }

  try {
    const sf = fs.statfsSync(path.dirname(DB_PATH));
    const freeBytes  = sf.bavail * sf.bsize;
    const totalBytes = sf.blocks * sf.bsize;
    const freeGb     = Math.round(freeBytes / 1024 / 1024 / 1024 * 100) / 100;
    const totalGb    = Math.round(totalBytes / 1024 / 1024 / 1024 * 100) / 100;
    let status = 'healthy';
    if (freeBytes < 500 * 1024 * 1024)       { status = 'unhealthy'; escalate('unhealthy'); }
    else if (freeBytes < 5 * 1024 * 1024 * 1024) { status = 'degraded';  escalate('degraded'); }
    checks.disk = { status, freeGb, totalGb };
  } catch (e) {
    checks.disk = { status: 'degraded', error: e.message };
    escalate('degraded');
  }

  const rss = process.memoryUsage().rss;
  const rssMb = Math.round(rss / 1024 / 1024);
  checks.process = {
    status: rss > 1024 * 1024 * 1024 ? 'degraded' : 'healthy',
    memoryMb: rssMb,
    uptimeSec: Math.floor(process.uptime()),
  };
  if (rss > 1024 * 1024 * 1024) escalate('degraded');

  // BeamMP-Server presence: best-effort from cached _serverRunSince so this
  // endpoint stays fast (a fresh getServerInfo() does a TCP probe that adds
  // ~1 s to every scrape). The Servers control page already polls fresh.
  checks.beammpServer = {
    status: _serverRunSince ? 'healthy' : 'degraded',
    running: !!_serverRunSince,
    uptimeSec: _serverRunSince ? Math.floor((Date.now() - _serverRunSince) / 1000) : 0,
  };
  if (!_serverRunSince) escalate('degraded');

  const httpCode = worst === 'unhealthy' ? 503 : 200;
  json(res, httpCode, {
    status: worst,
    version: require('./package.json').version,
    uptimeSec: Math.floor(process.uptime()),
    checks,
  });
}

// Admin: download a consistent DB snapshot via SQLite VACUUM INTO. Streams the
// resulting file as `panel-YYYY-MM-DD.db`, then deletes the temp copy.
async function apiAdminBackup(req, res) {
  if (!checkPermission(req, 'dbBackup')) return respond(res, 401, 'text/plain', 'Unauthorized');
  if (!db) return json(res, 503, { error: 'Database unavailable' });
  const stamp = new Date().toISOString().slice(0, 10);
  const tmpPath = path.join(os.tmpdir(), `panel-backup-${stamp}-${crypto.randomBytes(4).toString('hex')}.db`);
  try {
    await fsp.unlink(tmpPath).catch(() => {});
    db.prepare(`VACUUM INTO ?`).run(tmpPath);
    const stat = await fsp.stat(tmpPath);
    res.writeHead(200, {
      'Content-Type':  'application/octet-stream',
      'Content-Length': stat.size,
      'Content-Disposition': `attachment; filename="panel-${stamp}.db"`,
      'Cache-Control': 'no-store',
    });
    const stream = fs.createReadStream(tmpPath);
    stream.pipe(res);
    stream.on('close', () => { fsp.unlink(tmpPath).catch(() => {}); });
    stream.on('error', () => { fsp.unlink(tmpPath).catch(() => {}); });
    insertAuditLog(checkAnyAuth(req)?.username || 'unknown', 'admin.backup', `${stat.size} bytes`);
  } catch (e) {
    await fsp.unlink(tmpPath).catch(() => {});
    json(res, 500, { error: e.message });
  }
}

function apiAuditGet(req, res) {
  if (!checkPermission(req, 'auditView')) return json(res, 403, { error: 'Forbidden' });
  if (!db) return json(res, 200, { rows: [], hasMore: false });
  const qs     = new URLSearchParams(req.url.split('?')[1] || '');
  const limit  = Math.min(Math.max(parseInt(qs.get('limit')) || 50, 1), 500);
  const before = parseInt(qs.get('before')); // cursor: id strictly less than this
  const where  = isFinite(before) && before > 0 ? 'WHERE id < ?' : '';
  const params = isFinite(before) && before > 0 ? [before, limit + 1] : [limit + 1];
  const rows = db.prepare(`
    SELECT id, actor, action, target, detail, logged_at
    FROM audit_log ${where} ORDER BY id DESC LIMIT ?
  `).all(...params);
  const hasMore = rows.length > limit;
  if (hasMore) rows.pop();
  json(res, 200, { rows, hasMore, nextCursor: hasMore ? rows[rows.length - 1].id : null });
}

// Audit export: streams the audit_log as CSV or JSON for offline analysis.
// Filters (since/until ISO 8601, actor, action substring) compose into a
// single WHERE clause so the export can target an incident window without
// pulling the whole table. The CSV path streams row-by-row to keep memory
// flat on large exports; the JSON path renders an array in one shot because
// JSON.stringify on N rows of audit data is cheap and the output is meant
// for jq / SIEM ingestion which prefers one well-formed document over NDJSON.
// _csvCell lives in lib/pure.js so the CSV-quoting invariants can be unit-tested.
const { _csvCell } = require('./lib/pure.js');
function apiAuditExport(req, res) {
  if (!checkPermission(req, 'auditView')) return json(res, 403, { error: 'Forbidden' });
  if (!db) return json(res, 503, { error: 'Database unavailable' });
  const qs       = new URLSearchParams(req.url.split('?')[1] || '');
  const format   = (qs.get('format') || 'csv').toLowerCase();
  if (format !== 'csv' && format !== 'json') return json(res, 400, { error: 'format must be csv or json' });
  const normTs = s => {
    if (!s) return null;
    const m = String(s).match(/^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2})/);
    return m ? `${m[1]} ${m[2]}` : null;
  };
  const since  = normTs(qs.get('since'));
  const until  = normTs(qs.get('until'));
  const actor  = qs.get('actor');
  const action = qs.get('action');
  const where  = [];
  const params = [];
  if (since)  { where.push('logged_at >= ?'); params.push(since); }
  if (until)  { where.push('logged_at <= ?'); params.push(until); }
  if (actor)  { where.push('actor = ?');      params.push(actor); }
  if (action) { where.push('action LIKE ?');  params.push(`%${action}%`); }
  const sql = `SELECT id, actor, action, target, detail, logged_at FROM audit_log
               ${where.length ? 'WHERE ' + where.join(' AND ') : ''}
               ORDER BY id DESC`;
  insertAuditLog(checkAnyAuth(req)?.username || 'unknown', 'audit.export', format, where.join(' AND '));
  const stamp = new Date().toISOString().slice(0, 19).replace(/[T:]/g, '-');
  if (format === 'csv') {
    res.writeHead(200, {
      'Content-Type':        'text/csv; charset=utf-8',
      'Content-Disposition': `attachment; filename="beamng-audit-${stamp}.csv"`,
      'Cache-Control':       'no-store',
    });
    res.write('id,actor,action,target,detail,logged_at\n');
    for (const r of db.prepare(sql).iterate(...params)) {
      res.write(`${r.id},${_csvCell(r.actor)},${_csvCell(r.action)},${_csvCell(r.target)},${_csvCell(r.detail)},${_csvCell(r.logged_at)}\n`);
    }
    return res.end();
  }
  const rows = db.prepare(sql).all(...params);
  res.writeHead(200, {
    'Content-Type':        'application/json; charset=utf-8',
    'Content-Disposition': `attachment; filename="beamng-audit-${stamp}.json"`,
    'Cache-Control':       'no-store',
  });
  res.end(JSON.stringify({ exportedAt: new Date().toISOString(), filter: { since, until, actor, action }, count: rows.length, rows }, null, 2));
}

function apiModHistoryGet(res) {
  if (!db) return json(res, 200, []);
  const rows = db.prepare(`
    SELECT id, ok, filename, mod_type, mod_id, destination, files_extracted, error, uploaded_by, uploaded_at
    FROM mod_history ORDER BY id DESC LIMIT 100
  `).all();
  json(res, 200, rows.map(r => ({
    id:             r.id,
    ok:             !!r.ok,
    filename:       r.filename,
    modType:        r.mod_type,
    modId:          r.mod_id,
    destination:    r.destination,
    filesExtracted: r.files_extracted,
    error:          r.error,
    uploadedBy:     r.uploaded_by,
    time:           r.uploaded_at,
  })));
}

function apiModHistoryDelete(req, res) {
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  if (!db) return json(res, 200, { ok: true });
  db.prepare('DELETE FROM mod_history').run();
  json(res, 200, { ok: true });
}

// ── Mod catalogue ─────────────────────────────────────────────────────────────
// Enumerates the mods currently installed on disk under Resources/Client
// (single .zip files, served verbatim to players) and Resources/Server
// (one folder per Lua plugin). The catalogue is the source of truth — the
// `mod_history` table only records upload events, NOT the live state on
// disk (an operator can scp a mod in by hand, or rm one out, and the
// catalogue surfaces the real situation).
async function _statSafe(p) {
  try { return await fsp.stat(p); } catch { return null; }
}
async function _countFilesRecursive(dir, cap = 5000) {
  let n = 0;
  const stack = [dir];
  while (stack.length) {
    const cur = stack.pop();
    let entries;
    try { entries = await fsp.readdir(cur, { withFileTypes: true }); } catch { continue; }
    for (const e of entries) {
      if (e.isDirectory()) stack.push(path.join(cur, e.name));
      else { n++; if (n >= cap) return n; }
    }
  }
  return n;
}
async function _dirSizeBytes(dir, cap = 5 * 1024 * 1024 * 1024) {
  let total = 0;
  const stack = [dir];
  while (stack.length) {
    const cur = stack.pop();
    let entries;
    try { entries = await fsp.readdir(cur, { withFileTypes: true }); } catch { continue; }
    for (const e of entries) {
      const p = path.join(cur, e.name);
      if (e.isDirectory()) stack.push(p);
      else {
        const st = await _statSafe(p);
        if (st?.isFile()) {
          total += st.size;
          if (total >= cap) return total;
        }
      }
    }
  }
  return total;
}
// Classify a client mod .zip by peeking at its top-level structure. Detection
// is deliberately shallow (read the entry list, no decompression) so this is
// cheap to run on every catalogue request even for large archives. Returns
// one of: 'map', 'car', 'skin', 'other'. Cached per (path, mtime) so a 2nd
// request on an unchanged archive is a single map lookup.
const _modKindCache = new Map(); // `${path}|${mtime_ms}` → { kind, hasPreview }
async function _classifyClientMod(zipPath, mtimeMs) {
  const cacheKey = `${zipPath}|${mtimeMs}`;
  if (_modKindCache.has(cacheKey)) return _modKindCache.get(cacheKey);
  let result = { kind: 'other', hasPreview: false };
  if (!StreamZip) { _modKindCache.set(cacheKey, result); return result; }
  let zip;
  try { zip = new StreamZip.async({ file: zipPath }); }
  catch { _modKindCache.set(cacheKey, result); return result; }
  try {
    const entries = await zip.entries();
    const names = Object.keys(entries);
    // Map: contains /levels/<name>/info.json at any nesting depth.
    // Car: contains /vehicles/<name>/<name>.jbeam (or info.json under vehicles/).
    // Skin: contains /vehicles/<name>/skins/<skin>/ entries.
    let isMap = false, isSkin = false, previewKey = null;
    const vehicleInfoKeys = [];
    for (const n of names) {
      if (!isMap && /(?:^|\/)levels\/[^/]+\/info\.json$/.test(n)) isMap = true;
      // Strict car detection: requires vehicles/<X>/info.json. The previous
      // `.jbeam` heuristic caught full-vehicle mods but also flagged mods
      // that only EXTEND existing vehicles (license-plate packs, body kits,
      // bumper / trim / tuning add-ons) as "car" — those ship
      // `vehicles/<X>/<part>.jbeam` for a stock vehicle's directory but no
      // info.json of their own. enumerateCustomCars (which feeds the Cars
      // page) has always required info.json, so the .jbeam path was the
      // sole source of disagreement between the Mods page badge and the
      // Cars catalogue. Dropping it lines the two views up.
      const vm = n.match(/(?:^|\/)vehicles\/([^/]+)\/info\.json$/);
      if (vm && vm[1] !== 'common') vehicleInfoKeys.push(n);
      if (!isSkin && /(?:^|\/)vehicles\/[^/]+\/skins\/[^/]+\//.test(n)) isSkin = true;
    }
    // vehicles/<X>/info.json marks a unit the engine loads under vehicles/ —
    // but that covers drivable cars AND player-character packs, since BeamNG
    // models the walking avatar as a "vehicle". A character pack (e.g.
    // Characters_By_ApiK ships vehicles/characters/info.json with
    // "Type": "Characters") would otherwise badge as "Coche" and leak into the
    // Cars catalogue. Read the Type: "Characters" → character, anything else →
    // a real car. Stop at the first real car — the kind is "car" regardless of
    // any character entry alongside it.
    let isCar = false, isCharacter = false;
    for (const infoKey of vehicleInfoKeys) {
      let type = '';
      try {
        const meta = _parseLooseJson((await zip.entryData(infoKey)).toString('utf8'));
        if (meta && typeof meta.Type === 'string') type = meta.Type.trim().toLowerCase();
      } catch { /* unreadable info.json → assume a generic car */ }
      if (type === 'characters') { isCharacter = true; }
      else { isCar = true; break; }
    }
    // Find a usable preview image. Priority: level preview > vehicle thumb > any preview.png/jpg.
    // For maps we reuse the same two-step resolver the Maps catalogue uses
    // (canonical levels/<X>/preview.png|jpg|jpeg, then info.json's
    // `previews[0]`) so mods like 2K-Sadamine — which ships its thumbnail
    // as quickrace/TH.jpg declared in info.json — light up here too. The
    // old loop only matched `preview.png` literal, so jpeg-shipping mods
    // and previews-array-only mods both fell through to the SVG fallback.
    if (isMap) {
      const levelNames = new Set();
      for (const n of names) {
        const m = n.match(/(?:^|\/)levels\/([^/]+)\/info\.json$/);
        if (m) levelNames.add(m[1]);
      }
      for (const lvl of levelNames) {
        const res = await _resolveLevelPreview(zip, names, lvl);
        if (res) { previewKey = res.key; break; }
      }
    }
    if (!previewKey) {
      for (const n of names) {
        if (/(?:^|\/)vehicles\/[^/]+\/default\.(?:jpg|png)$/i.test(n)) { previewKey = n; break; }
      }
    }
    if (!previewKey) {
      for (const n of names) {
        if (/preview\.(?:png|jpe?g)$/i.test(n)) { previewKey = n; break; }
      }
    }
    const kind = isMap ? 'map'
      : (isSkin && !isCar ? 'skin'
      : (isCar ? 'car'
      : (isCharacter ? 'character' : 'other')));
    result = { kind, hasPreview: !!previewKey, previewKey };
  } catch { /* corrupt zip */ }
  finally { try { await zip.close(); } catch {} }
  _modKindCache.set(cacheKey, result);
  return result;
}

async function apiMods(req, res) {
  // Reusable read permission: anyone with modUpload (or admin) can list the
  // catalogue too. Without this, a non-admin uploader could install mods
  // but not see what's already there, which is confusing.
  if (!checkPermission(req, 'modUpload')) return json(res, 403, { error: 'Forbidden' });
  const client = [];
  const server = [];
  try {
    // Client: flat list of .zip files. Anything else under Resources/Client
    // is operator-managed (README, .gitignore, whatever) — we ignore it.
    const clientEntries = await fsp.readdir(BEAMMP_CLIENT_RESOURCES_DIR, { withFileTypes: true }).catch(() => []);
    for (const e of clientEntries) {
      if (!e.isFile()) continue;
      if (!/\.zip$/i.test(e.name)) continue;
      const st = await _statSafe(path.join(BEAMMP_CLIENT_RESOURCES_DIR, e.name));
      if (!st) continue;
      const c = await _classifyClientMod(path.join(BEAMMP_CLIENT_RESOURCES_DIR, e.name), st.mtimeMs);
      client.push({ name: e.name, size: st.size, mtime: st.mtime.toISOString(), kind: c.kind, hasPreview: c.hasPreview });
    }
    // Server: one folder per plugin. We count files + check for main.lua at
    // any depth so the UI can flag folders that are missing the entry point.
    const serverEntries = await fsp.readdir(BEAMMP_SERVER_RESOURCES_DIR, { withFileTypes: true }).catch(() => []);
    for (const e of serverEntries) {
      if (!e.isDirectory()) continue;
      const pluginDir = path.join(BEAMMP_SERVER_RESOURCES_DIR, e.name);
      const st = await _statSafe(pluginDir);
      if (!st) continue;
      const files = await _countFilesRecursive(pluginDir);
      const size  = await _dirSizeBytes(pluginDir);
      // main.lua at any depth — BeamMP loads .lua files only from the
      // top-level of each plugin folder, but the operator may have organised
      // subdirectories for libraries, so the deep-search is informational.
      let hasMainLua = false;
      const stack = [pluginDir];
      while (stack.length && !hasMainLua) {
        const cur = stack.pop();
        const ents = await fsp.readdir(cur, { withFileTypes: true }).catch(() => []);
        for (const ent of ents) {
          if (ent.isFile() && ent.name.toLowerCase() === 'main.lua') { hasMainLua = true; break; }
          if (ent.isDirectory()) stack.push(path.join(cur, ent.name));
        }
      }
      server.push({ name: e.name, size, files, hasMainLua, mtime: st.mtime.toISOString() });
    }
    client.sort((a, b) => a.name.localeCompare(b.name));
    server.sort((a, b) => a.name.localeCompare(b.name));
    return json(res, 200, { client, server });
  } catch (e) { return json(res, 500, { error: e.message }); }
}

async function apiModDelete(req, res, loc, name) {
  // Deletion is strictly admin-only — `modUpload` grants upload but not
  // destructive removal, because the wrong delete on a busy server (the
  // operator picks the wrong row, the modder's hash mismatches mid-rotation,
  // …) kicks every connected player and forces a manual reupload. Same
  // approach as the assetto-server-panel sibling, where content delete also
  // goes through checkAdminAuth and not a granular permission.
  if (!checkAdminAuth(req)) return json(res, 401, { error: 'Unauthorized' });
  if (loc !== 'client' && loc !== 'server') return json(res, 400, { error: 'Unknown location' });
  // Reject anything that even hints at a path-traversal — the name comes
  // straight off the URL so a malformed segment could otherwise resolve
  // outside Resources/{Client,Server}.
  if (!name || /[\\/]|\.\./.test(name) || name.startsWith('.')) {
    return json(res, 400, { error: 'Invalid mod name' });
  }
  const base = loc === 'client' ? BEAMMP_CLIENT_RESOURCES_DIR : BEAMMP_SERVER_RESOURCES_DIR;
  const target = path.join(base, name);
  // Belt-and-braces: confirm the resolved path is inside the expected base.
  // A symlink dropped under Resources/Client could otherwise let us follow
  // it out of the BeamMP tree on rm.
  const realBase = await fsp.realpath(base).catch(() => base);
  const realTarget = await fsp.realpath(target).catch(() => target);
  if (!realTarget.startsWith(realBase + path.sep)) {
    return json(res, 400, { error: 'Resolved path escapes resources directory' });
  }
  try {
    const st = await fsp.stat(target).catch(() => null);
    if (!st) return json(res, 404, { error: 'Mod not found' });
    if (loc === 'client') {
      if (!st.isFile()) return json(res, 400, { error: 'Client entry must be a file' });
      await fsp.unlink(target);
    } else {
      if (!st.isDirectory()) return json(res, 400, { error: 'Server entry must be a directory' });
      await fsp.rm(target, { recursive: true, force: true });
    }
    const actor = checkAnyAuth(req)?.username || 'unknown';
    insertAuditLog(actor, 'mod.delete', `${loc}/${name}`);
    return json(res, 200, { ok: true });
  } catch (e) { return json(res, 500, { error: e.message }); }
}

// Extract and stream the cached preview image from a client mod .zip. The
// _classifyClientMod cache (above) remembers which entry inside the archive
// holds the preview, so this endpoint just opens the zip, pipes that one
// entry out, and closes — no decompression of the whole archive. Cached on
// the client side via mtime-bound Cache-Control so the catalogue grid doesn't
// re-extract 30 previews on every visit.
async function apiModPreview(req, res, name) {
  if (!checkPermission(req, 'modUpload')) return json(res, 403, { error: 'Forbidden' });
  if (!name || /[\\/]|\.\./.test(name) || name.startsWith('.') || !/\.zip$/i.test(name)) {
    return json(res, 400, { error: 'Invalid mod name' });
  }
  if (!StreamZip) return json(res, 503, { error: 'zip extractor not available' });
  const zipPath = path.join(BEAMMP_CLIENT_RESOURCES_DIR, name);
  const st = await _statSafe(zipPath);
  if (!st || !st.isFile()) return json(res, 404, { error: 'Mod not found' });
  const c = await _classifyClientMod(zipPath, st.mtimeMs);
  if (!c.hasPreview || !c.previewKey) return json(res, 404, { error: 'No preview' });
  let zip;
  try { zip = new StreamZip.async({ file: zipPath }); }
  catch { return json(res, 500, { error: 'Cannot open zip' }); }
  try {
    const buf = await zip.entryData(c.previewKey);
    const ct = /\.png$/i.test(c.previewKey) ? 'image/png' : 'image/jpeg';
    res.setHeader('Content-Type', ct);
    res.setHeader('Cache-Control', 'private, max-age=86400');
    res.setHeader('ETag', `"${st.mtimeMs}-${buf.length}"`);
    res.end(buf);
  } catch (e) {
    return json(res, 500, { error: 'Cannot extract preview: ' + e.message });
  } finally { try { await zip.close(); } catch {} }
}

// Per-level preview extractor for the Maps catalogue. The mods page has its
// own /api/mods/client/<zip>/preview that returns the FIRST preview.png found
// in the archive — that's fine when one .zip = one mod, but a single map mod
// can legitimately ship multiple levels (e.g. a track pack), and the maps grid
// must show the right preview next to each level. So this endpoint targets a
// specific levels/<level>/preview.png inside the zip and gates on mapActivate
// (the Maps page permission, implied by serverConfig) rather than modUpload,
// so an operator who can change the map but not upload new mods still sees
// thumbnails.
async function apiMapPreview(req, res, source, levelName) {
  if (!checkPermission(req, 'mapActivate')) return json(res, 403, { error: 'Forbidden' });
  if (!source || /[\\/]|\.\./.test(source) || source.startsWith('.') || !/\.zip$/i.test(source)) {
    return json(res, 400, { error: 'Invalid source' });
  }
  if (!levelName || /[\\/]|\.\./.test(levelName) || levelName.startsWith('.')) {
    return json(res, 400, { error: 'Invalid level name' });
  }
  if (!StreamZip) return json(res, 503, { error: 'zip extractor not available' });
  const zipPath = path.join(BEAMMP_CLIENT_RESOURCES_DIR, source);
  const st = await _statSafe(zipPath);
  if (!st || !st.isFile()) return json(res, 404, { error: 'Source not found' });
  let zip;
  try { zip = new StreamZip.async({ file: zipPath }); }
  catch { return json(res, 500, { error: 'Cannot open zip' }); }
  try {
    const entries = await zip.entries();
    // _resolveLevelPreview encapsulates the two-step resolution (canonical
    // preview.png/jpg first, then info.json's `previews[0]`) so a mod like
    // 2K-Sadamine that ships its screenshot under `quickrace/TH.jpg` and
    // declares it via info.json still serves a thumbnail here.
    const resolved = await _resolveLevelPreview(zip, Object.keys(entries), levelName);
    if (!resolved) return json(res, 404, { error: 'No preview for this level' });
    const buf = await zip.entryData(resolved.key);
    res.setHeader('Content-Type', resolved.ext === 'png' ? 'image/png' : 'image/jpeg');
    res.setHeader('Cache-Control', 'private, max-age=86400');
    res.setHeader('ETag', `"${st.mtimeMs}-${buf.length}"`);
    res.end(buf);
  } catch (e) {
    return json(res, 500, { error: 'Cannot extract preview: ' + e.message });
  } finally { try { await zip.close(); } catch {} }
}

// Decompression bomb caps: refuse archives that look pathological before we touch disk
const MAX_ARCHIVE_ENTRIES   = 50_000;                 // total entries
const MAX_ARCHIVE_TOTAL_B   = 5 * 1024 * 1024 * 1024; // 5 GB extracted total
const MAX_ARCHIVE_ENTRY_B   = 2 * 1024 * 1024 * 1024; // 2 GB single file

// Cap how many extractors can run at once. processModBuffer reads the whole
// archive buffer into RAM (the extractors operate on Buffer), so with the
// 2 GB hard cap a handful of concurrent uploads could OOM the panel. Two
// concurrent extractors is enough to keep one user productive while a slow
// upload runs in the background; a third waits in line.
const MAX_CONCURRENT_EXTRACTORS = 2;
let _activeExtractors = 0;
const _extractorWaiters = [];
function _acquireExtractor() {
  if (_activeExtractors < MAX_CONCURRENT_EXTRACTORS) {
    _activeExtractors++;
    return Promise.resolve();
  }
  return new Promise(resolve => _extractorWaiters.push(resolve));
}
function _releaseExtractor() {
  const next = _extractorWaiters.shift();
  if (next) {
    // Hand off the slot directly so the count stays at MAX while we wake the
    // next waiter; otherwise a parallel call could race in between.
    next();
  } else {
    _activeExtractors = Math.max(0, _activeExtractors - 1);
  }
}

// Refuse uploads when the destination filesystem doesn't have enough free
// space to safely expand the archive. We estimate the worst case as
// `compressed × 5` (matches what BeamMP mod packs typically expand to).
// fs.statfs is Node 19+; on older versions or non-POSIX FS the call throws
// and we skip the check — better to attempt the upload than to refuse
// blindly when we can't measure.
async function _checkFreeSpace(extractedDir, compressedBytes) {
  if (!fsp.statfs) return null; // older Node — silently skip
  try {
    // Walk up until we find a path that actually exists. Brand-new content
    // dirs (first-ever mod) won't exist yet; their parent will.
    let probe = extractedDir;
    for (let i = 0; i < 8; i++) {
      try { await fsp.stat(probe); break; } catch { probe = path.dirname(probe); if (probe === '/' || !probe) break; }
    }
    const s = await fsp.statfs(probe);
    const free = Number(s.bavail) * Number(s.bsize);
    const need = Math.max(compressedBytes * 5, 256 * 1024 * 1024); // floor at 256 MB so a tiny mod still has headroom
    if (free < need) {
      return { ok: false, free, need };
    }
    return { ok: true, free, need };
  } catch { return null; }
}

async function processModBuffer(buffer, filename) {
  await _acquireExtractor();
  try {
    // Disk-space gate. Refuse the upload before extracting if the destination
    // looks dangerously full — running out of disk mid-extract leaves a
    // half-installed mod that's worse than a clean rejection.
    const ext = path.extname(filename).toLowerCase();
    const probeDir = ext === '.zip' || ext === '.rar' || ext === '.7z'
      ? BEAMMP_CLIENT_RESOURCES_DIR // either BEAMMP_CLIENT_RESOURCES_DIR or BEAMMP_SERVER_RESOURCES_DIR works as a probe; both live on the same volume in practice
      : os.tmpdir();
    const space = await _checkFreeSpace(probeDir, buffer.length);
    if (space && !space.ok) {
      const freeMb = Math.floor(space.free / 1024 / 1024);
      const needMb = Math.ceil(space.need / 1024 / 1024);
      throw Object.assign(
        new Error(`Not enough disk space (free=${freeMb} MB, estimated need=${needMb} MB)`),
        { status: 507 } // 507 Insufficient Storage
      );
    }
    return await _processModBufferInner(buffer, filename);
  } finally {
    _releaseExtractor();
  }
}

async function _processModBufferInner(buffer, filename) {
  const ext = path.extname(filename).toLowerCase();
  if (!['.zip', '.rar', '.7z'].includes(ext))
    throw Object.assign(new Error(`Unsupported format: ${ext}. Use .zip, .rar or .7z`), { status: 400 });

  let archive = null;
  try {
    archive = await extractArchive(buffer, ext);
    const entries = archive.entries;

    if (entries.length > MAX_ARCHIVE_ENTRIES)
      throw Object.assign(new Error(`Archive has too many entries (${entries.length} > ${MAX_ARCHIVE_ENTRIES})`), { status: 413 });

    // Symlinks have no legitimate role in a BeamMP mod. Both branches reject
    // them up-front: server plugins because they'd let an archive write
    // outside Resources/Server, client mods because the zip will be served
    // verbatim to game clients which makes a poisoned mod a vector against
    // every connected player.
    for (const e of entries) {
      if (e.isSymlink)
        throw Object.assign(new Error(`Symlink entry rejected: ${e.name}`), { status: 400 });
    }

    const dummyRoot = path.join(os.tmpdir(), 'bp-slip-check');
    for (const e of entries) {
      if (!isSafeEntry(e.name, dummyRoot))
        throw Object.assign(new Error(`Zip-Slip path rejected: ${e.name}`), { status: 400 });
    }

    const names      = entries.map(e => e.name.replace(/\\/g, '/').toLowerCase());
    const allFiles   = names.filter(n => !n.endsWith('/'));
    // A `main.lua` at any depth USED to flag the archive as a BeamMP server
    // plugin — except BeamNG vehicle and level mods routinely carry their
    // own `main.lua` underneath `vehicles/<X>/lua/` or `levels/<X>/scripts/`
    // for client-side behaviour (turbo / TC / scripted gimmicks on cars,
    // mission scripts on tracks). Those are content the client downloads
    // and runs locally, NOT a server-side plugin to extract into
    // Resources/Server/. We only treat a main.lua as a server-plugin
    // signal when it sits OUTSIDE the vehicles/ and levels/ subtrees —
    // i.e. in the archive root or under a custom plugin folder. The
    // Nissan 180 RPS13 mod was the trigger: `vehicles/RPS13/lua/main.lua`
    // is a car script, the panel kept misclassifying it as a server
    // plugin and refusing extraction because of the "single root folder"
    // rule below.
    const hasMainLua = allFiles.some(n => {
      if (!/(^|\/)main\.lua$/.test(n)) return false;
      if (/(^|\/)(vehicles|levels)\//.test(n)) return false;
      return true;
    });
    const modType    = hasMainLua ? 'server-plugin' : 'client-mod';

    if (modType === 'client-mod') {
      // BeamMP's Resources/Client only accepts .zip files served verbatim to
      // connecting players. We DO NOT extract — the zip stays packed and
      // BeamMP streams it as-is. So .rar / .7z uploads have to be rejected
      // here (the operator can repack and resubmit). The full-archive scans
      // above (entry count, symlink reject, zip-slip reject) still apply as
      // safety — an archive that fails any of them shouldn't end up on
      // disk where game clients would auto-download it.
      if (ext !== '.zip')
        throw Object.assign(new Error(`Client mods must be .zip (BeamMP serves them verbatim). Repack the .${ext.slice(1)} as a .zip and try again.`), { status: 415 });

      // The destination filename is the upload's basename, sanitised to a
      // safe shape. Operators can re-upload to overwrite — we don't suffix
      // a timestamp because BeamMP-Server keys mods by exact filename.
      const safeName = path.basename(filename).replace(/[^A-Za-z0-9._-]/g, '_');
      if (!/\.zip$/i.test(safeName))
        throw Object.assign(new Error('Client mod filename must end in .zip'), { status: 400 });

      const destFile = path.join(BEAMMP_CLIENT_RESOURCES_DIR, safeName);
      if (!destFile.startsWith(BEAMMP_CLIENT_RESOURCES_DIR + path.sep))
        throw Object.assign(new Error('Invalid destination path'), { status: 400 });

      await fsp.mkdir(BEAMMP_CLIENT_RESOURCES_DIR, { recursive: true });
      return await withDestPathLock(destFile, async () => {
        // O_NOFOLLOW: refuse to write through an existing symlink — a previous
        // mod or an attacker could have left one pointing outside the dir.
        const fh = await fsp.open(destFile, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW);
        try { await fh.writeFile(buffer); } finally { await fh.close().catch(() => {}); }
        return { modType, modId: safeName, destination: destFile, filesExtracted: 1 };
      });
    }

    // Server-plugin branch: extract into Resources/Server/<root>/ so the
    // BeamMP-Server picks up the .lua files at startup.
    const roots = new Set();
    for (const n of names) { const p = n.split('/'); if (p[0]) roots.add(p[0]); }
    if (roots.size !== 1)
      throw Object.assign(new Error(`Server plugin archive must contain exactly one root folder. Found: ${[...roots].join(', ')}`), { status: 422 });

    const modRoot  = [...roots][0];
    const destDir  = path.join(BEAMMP_SERVER_RESOURCES_DIR, modRoot);
    if (!destDir.startsWith(BEAMMP_SERVER_RESOURCES_DIR + path.sep))
      throw Object.assign(new Error('Invalid destination path'), { status: 400 });

    await fsp.mkdir(destDir, { recursive: true });

    return await withDestPathLock(destDir, async () => {
      let filesExtracted = 0;
      let totalBytes     = 0;
      for (const entry of entries) {
        const normalName = entry.name.replace(/\\/g, '/');
        if (!normalName.startsWith(modRoot + '/')) continue;
        if (entry.isDirectory) {
          const relDir = normalName.slice(modRoot.length + 1);
          if (relDir) await fsp.mkdir(path.join(destDir, relDir), { recursive: true });
          continue;
        }
        const fileExt = path.extname(normalName).toLowerCase();
        if (!ALLOWED_MOD_EXTS.has(fileExt)) continue;
        const destFile = path.join(destDir, normalName.slice(modRoot.length + 1));
        if (!destFile.startsWith(destDir + path.sep))
          throw Object.assign(new Error(`Zip-Slip path rejected: ${entry.name}`), { status: 400 });
        const data = await entry.getData();
        if (!data) continue;
        if (data.length > MAX_ARCHIVE_ENTRY_B)
          throw Object.assign(new Error(`Entry too large: ${normalName} (${data.length} bytes)`), { status: 413 });
        totalBytes += data.length;
        if (totalBytes > MAX_ARCHIVE_TOTAL_B)
          throw Object.assign(new Error(`Archive expands beyond size cap (${MAX_ARCHIVE_TOTAL_B} bytes)`), { status: 413 });
        await fsp.mkdir(path.dirname(destFile), { recursive: true });
        const fh = await fsp.open(destFile, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW);
        try { await fh.writeFile(data); } finally { await fh.close().catch(() => {}); }
        filesExtracted++;
      }

      return { modType, modId: modRoot, destination: destDir, filesExtracted };
    });
  } finally {
    if (archive?.close) await Promise.resolve(archive.close()).catch(() => {});
  }
}

// ── Chunked upload ─────────────────────────────────────────────────────────────
const CHUNK_TMP_DIR    = path.join(os.tmpdir(), 'ac-upload-chunks');
// Hard ceiling for any single archive, regardless of panel_settings.upload_max_mb.
// The frontend setting goes in admin Configuración; this cap is a safety net so
// a misconfigured value (or hostile DB edit) cannot OOM the panel.
const UPLOAD_HARD_CAP_BYTES = 2 * 1024 * 1024 * 1024; // 2 GB

// Atomic per-uploadId lock. Used to serialise every operation that touches the
// same uploadId — chunk write, readdir count, and assembly all happen inside
// the same critical section, so two concurrent final-chunk requests can never
// both pass the "received == totalChunks" check and double-extract. Releasing
// happens in the finally block of withUploadLock so a thrown exception or
// process crash mid-flight still drops the lock for the next request.
const _uploadLocks = new Map(); // uploadId -> Promise (resolves when current op done)
async function withUploadLock(uploadId, fn) {
  // Chain onto any in-flight lock for the same uploadId. Multiple waiters all
  // resolve when the previous holder releases, then the JS scheduler picks one
  // to actually run next; the others loop and wait again. Cooperative FIFO.
  while (_uploadLocks.has(uploadId)) {
    try { await _uploadLocks.get(uploadId); } catch {}
  }
  let release;
  const p = new Promise(r => { release = r; });
  _uploadLocks.set(uploadId, p);
  try { return await fn(); }
  finally { _uploadLocks.delete(uploadId); release(); }
}
// Per-destination-path lock used by processModBuffer to serialise writes that
// target the same file or directory on disk. Two uploads with DIFFERENT
// uploadIds (so withUploadLock doesn't serialise them) can still resolve to
// the same client-mod filename or the same server-plugin root — without this
// lock they race on O_TRUNC and produce a corrupt zip that BeamMP would then
// stream to every connecting player. Keyed by the absolute destination path
// (destFile for client mods, destDir for server plugins).
const _destPathLocks = new Map();
async function withDestPathLock(destPath, fn) {
  while (_destPathLocks.has(destPath)) {
    try { await _destPathLocks.get(destPath); } catch {}
  }
  let release;
  const p = new Promise(r => { release = r; });
  _destPathLocks.set(destPath, p);
  try { return await fn(); }
  finally { _destPathLocks.delete(destPath); release(); }
}
// Per-user state: at most one active upload at a time. A new uploadId from the
// same user is rejected until the current one finishes or stales out (no chunks
// for STALE_MS). Cleared on success/failure of the assembly.
const _userUploads = new Map(); // username -> { uploadId, lastChunkAt }
const USER_UPLOAD_STALE_MS = 5 * 60 * 1000;
function noteUserUpload(username, uploadId) {
  _userUploads.set(username, { uploadId, lastChunkAt: Date.now() });
}
function clearUserUpload(username) { _userUploads.delete(username); }
function userHasOtherUploadActive(username, uploadId) {
  const entry = _userUploads.get(username);
  if (!entry) return false;
  if (entry.uploadId === uploadId) return false;
  if (Date.now() - entry.lastChunkAt > USER_UPLOAD_STALE_MS) {
    _userUploads.delete(username);
    return false;
  }
  return true;
}

async function cleanupOldChunks() {
  let removed = 0;
  try {
    const entries = await fsp.readdir(CHUNK_TMP_DIR).catch(() => []);
    const now = Date.now();
    for (const entry of entries) {
      const dir = path.join(CHUNK_TMP_DIR, entry);
      const stat = await fsp.stat(dir).catch(() => null);
      if (stat && now - stat.mtimeMs > 2 * 60 * 60 * 1000) {
        await fsp.rm(dir, { recursive: true }).catch(() => {});
        removed++;
      }
    }
  } catch {}
  _sweeperState.chunks = { lastRunAt: Date.now(), lastRemoved: removed };
}

async function apiModUploadChunk(req, res) {
  if (!checkPermission(req, 'modUpload')) return json(res, 403, { error: 'Forbidden' });
  const uploadedBy = checkAnyAuth(req)?.username || 'unknown';
  // Each chunk is a separate request; allow up to 4096 chunks/hour per IP (≈ one full
  // 20 GB upload at 5 MB/chunk before lockout). Stops scripted spam without breaking
  // legitimate uploads.
  if (!checkRateLimit('mod-chunk', clientIp(req), 4096, 60 * 60 * 1000))
    return json(res, 429, { error: 'Rate limit: too many chunks' });

  // Body is JSON with base64-encoded chunk data — same format as other API calls,
  // avoids multipart/form-data and binary bodies which Cloudflare WAF may block
  let body;
  try {
    body = await new Promise((resolve, reject) => {
      const MAX = 10 * 1024 * 1024; // 10 MB JSON limit (base64 of 7 MB chunk)
      let raw = '';
      req.on('data', c => { raw += c; if (raw.length > MAX) { req.destroy(); reject(new Error('Body too large')); } });
      req.on('end', () => { try { resolve(JSON.parse(raw)); } catch { reject(new Error('Invalid JSON')); } });
      req.on('error', reject);
    });
  } catch (e) { return json(res, 400, { error: e.message }); }

  const uploadId    = (body.uploadId    || '').replace(/[^a-zA-Z0-9_-]/g, '');
  const chunkIndex  = parseInt(body.chunkIndex  ?? '-1', 10);
  const totalChunks = parseInt(body.totalChunks ?? '0',  10);
  const filename    = body.filename || '';
  const dataB64     = body.data || '';

  // Bounds: prevents an inflated chunkIndex (e.g. 9999) from inflating the readdir
  // count and triggering early assembly with missing chunks.
  const MAX_TOTAL_CHUNKS = 4096; // 4096 × 5 MB ≈ 20 GB ceiling — much higher than any real mod
  if (!uploadId || chunkIndex < 0 || totalChunks < 1 || !filename || !dataB64)
    return json(res, 400, { error: 'Invalid chunk parameters' });
  if (totalChunks > MAX_TOTAL_CHUNKS)
    return json(res, 400, { error: `totalChunks > ${MAX_TOTAL_CHUNKS}` });
  if (userHasOtherUploadActive(uploadedBy, uploadId))
    return json(res, 429, { error: 'You already have an upload in progress — wait for it to finish or 5 min' });
  noteUserUpload(uploadedBy, uploadId);
  if (chunkIndex >= totalChunks)
    return json(res, 400, { error: 'chunkIndex out of range' });

  const uploadDir = path.join(CHUNK_TMP_DIR, uploadId);
  if (!uploadDir.startsWith(CHUNK_TMP_DIR + path.sep))
    return json(res, 400, { error: 'Invalid uploadId' });

  let chunkData;
  try { chunkData = Buffer.from(dataB64, 'base64'); }
  catch { return json(res, 400, { error: 'Invalid base64 data' }); }

  // Optional client-supplied sha256 of the raw chunk bytes. When present, verify
  // — a mismatch means the chunk got corrupted in transit (or somebody is trying
  // to swap chunk contents mid-upload). When absent, fall back to byte-equality
  // on duplicates below; the client is encouraged to send the hash for safety.
  if (body.sha256 != null) {
    if (typeof body.sha256 !== 'string' || !/^[a-fA-F0-9]{64}$/.test(body.sha256)) {
      return json(res, 400, { error: 'sha256 must be 64 hex chars' });
    }
    const have = crypto.createHash('sha256').update(chunkData).digest('hex');
    if (have !== body.sha256.toLowerCase()) {
      return json(res, 400, { error: 'sha256 mismatch — chunk corrupted in transit' });
    }
  }

  try {
    await fsp.mkdir(uploadDir, { recursive: true });

    // Everything from here is serialised per uploadId. Without this, two
    // requests carrying the same final chunk index could both reach the
    // `received === totalChunks` check between each other's awaits and both
    // proceed to assembly — extracting the same archive twice (and triggering
    // mod-install audit rows twice). The lock also covers chunk-duplicate
    // handling: a retry of the same chunk while assembly is in progress sees
    // the lock and waits, instead of racing the unlink during assembly.
    return await withUploadLock(uploadId, async () => {
      // Refuse duplicate chunks unless they are byte-identical to the existing
      // copy. O_EXCL on a fresh fd makes the "first write wins" semantics
      // explicit: a legitimate client retry of a flaky chunk is idempotent;
      // an attacker (or buggy client) trying to swap chunk content with a
      // different payload gets 409.
      const chunkPath = path.join(uploadDir, `chunk-${chunkIndex}`);
      try {
        const fh = await fsp.open(chunkPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL);
        try { await fh.writeFile(chunkData); } finally { await fh.close().catch(() => {}); }
      } catch (e) {
        if (e.code === 'EEXIST') {
          const existing = await fsp.readFile(chunkPath).catch(() => null);
          if (!existing || !existing.equals(chunkData)) {
            return json(res, 409, { error: `chunk ${chunkIndex} already received with different contents` });
          }
          // Same bytes — accept the duplicate as idempotent.
        } else { throw e; }
      }

      const received = (await fsp.readdir(uploadDir)).filter(f => f.startsWith('chunk-')).length;
      if (received < totalChunks)
        return json(res, 200, { ok: true, done: false, received, total: totalChunks });

      // Assemble chunks into a single temp file on disk — never `Buffer.concat` the
      // whole upload, which would peak at 2× the file size in RAM. Read each chunk,
      // append it to the output stream, free the buffer. Peak RAM stays at one
      // chunk (≈5 MB).
      const assembledPath = path.join(os.tmpdir(), `ac-assembled-${uploadId}.bin`);
      try {
        const out = fs.createWriteStream(assembledPath);
        let totalBytes = 0;
        for (let i = 0; i < totalChunks; i++) {
          const cPath = path.join(uploadDir, `chunk-${i}`);
          const buf = await fsp.readFile(cPath);
          totalBytes += buf.length;
          if (totalBytes > UPLOAD_HARD_CAP_BYTES) {
            out.destroy();
            throw Object.assign(new Error(`Upload exceeds hard cap of ${UPLOAD_HARD_CAP_BYTES} bytes`), { status: 413 });
          }
          await new Promise((resolve, reject) => {
            out.write(buf, e => e ? reject(e) : resolve());
          });
          await fsp.unlink(cPath).catch(() => {});
        }
        await new Promise(r => out.end(r));
        await fsp.rm(uploadDir, { recursive: true }).catch(() => {});

        // Pass the assembled file to processModBuffer. We still read it into a Buffer
        // here because the extractors operate on Buffer; refactoring them to streaming
        // input is a follow-up task. At least we no longer hold N + 1 copies in RAM.
        const fileBuf = await fsp.readFile(assembledPath);
        const result = await processModBuffer(fileBuf, filename);
        invalidateContentCache(result.modType);
        insertModHistory({ ok: true, filename, uploadedBy, ...result });
        insertAuditLog(uploadedBy || 'unknown', 'mod.install', result.modId || filename, `${result.modType}, ${result.filesExtracted} files`);
        clearUserUpload(uploadedBy);
        return json(res, 200, { ok: true, done: true, ...result });
      } finally {
        await fsp.unlink(assembledPath).catch(() => {});
      }
    });
  } catch (e) {
    await fsp.rm(uploadDir, { recursive: true }).catch(() => {});
    clearUserUpload(uploadedBy);
    insertModHistory({ ok: false, filename, uploadedBy, error: e.message });
    log.error('chunk upload failed:', e.message);
    json(res, e.status || 500, { error: e.message });
  }
}

// ── Mod upload endpoint ───────────────────────────────────────────────────────
async function apiModUpload(req, res) {
  if (!checkPermission(req, 'modUpload')) return json(res, 403, { error: 'Forbidden' });
  if (!checkRateLimit('mod-upload', clientIp(req), 30, 60 * 60 * 1000))
    return json(res, 429, { error: 'Rate limit: too many uploads (max 30/hour)' });

  let maxMb = 500;
  if (db) {
    const row = db.prepare(`SELECT value FROM panel_settings WHERE key = 'upload_max_mb'`).get();
    if (row) maxMb = parseInt(row.value, 10) || 500;
  }
  // Cap whatever the admin configured — UPLOAD_HARD_CAP_BYTES is the absolute
  // ceiling so a runaway setting cannot OOM the panel.
  const effectiveCap = Math.min(maxMb * 1024 * 1024, UPLOAD_HARD_CAP_BYTES);

  let parts;
  try { parts = await parseMultipart(req, effectiveCap); }
  catch (e) {
    if (e.code === 'ELIMIT') return json(res, 413, { error: `File too large (max ${Math.floor(effectiveCap / 1024 / 1024)} MB)` });
    return json(res, 400, { error: `Error en la subida: ${e.message}` });
  }
  const filePart = parts.file;
  if (!filePart?.filePath) return json(res, 400, { error: 'No file received (field: file)' });

  const uploadedBy = checkAnyAuth(req)?.username || null;
  try {
    // The streaming parser wrote the upload straight to disk — read it back as a
    // Buffer here for the existing processModBuffer pipeline. Peak RAM is now 1×
    // file size (the readFile) instead of the previous 2× (buffered chunks +
    // concat). Refactoring the extractors to consume a stream is a follow-up.
    const fileBuf = await fsp.readFile(filePart.filePath);
    const result = await processModBuffer(fileBuf, filePart.filename);
    invalidateContentCache(result.modType);
    insertModHistory({ ok: true, filename: filePart.filename, uploadedBy, ...result });
    insertAuditLog(uploadedBy || 'unknown', 'mod.install', result.modId || filePart.filename, `${result.modType}, ${result.filesExtracted} files`);
    json(res, 200, { ok: true, ...result });
  } catch (e) {
    insertModHistory({ ok: false, filename: filePart.filename, uploadedBy, error: e.message });
    log.error('mod upload failed:', e.message);
    json(res, e.status || 500, { error: e.message });
  } finally {
    fsp.unlink(filePart.filePath).catch(() => {});
  }
}

// CSRF: reject unsafe methods whose Origin/Referer does not match Host.
// Cookie is SameSite=Strict so cross-site requests already lose the cookie,
// but the Origin check is a belt-and-braces second layer (e.g. against
// subtle browser bugs or a same-site malicious context).
//
// CSRF only matters for cookie-based auth. A request with no `sid` cookie
// cannot replay the user's session (a malicious site has no way to forge a
// cookie that is HttpOnly + SameSite=Strict); such requests bypass the
// Origin check so headless ADMIN_TOKEN callers (which use X-Admin-Token /
// Authorization: Bearer, never cookies) keep working.
//
// When a session cookie IS present, the request MUST carry a matching
// Origin or Referer. Modern browsers always attach Origin to
// POST/PUT/DELETE/PATCH; a missing pair would only come from a hand-crafted
// client or a `Referrer-Policy: no-referrer` form from another origin —
// the exact shape of a CSRF attempt. Refuse.
function isUnsafeMethod(m) { return m === 'POST' || m === 'PUT' || m === 'DELETE' || m === 'PATCH'; }
function checkOrigin(req) {
  const host = (req.headers.host || '').toLowerCase();
  if (!host) return false;
  // No session cookie = no cookie-based auth = no CSRF vector. Token-only
  // headless callers (ADMIN_TOKEN) hit this branch and pass without an Origin.
  if (!readCookie(req, 'sid')) return true;
  const raw = req.headers.origin || req.headers.referer || '';
  if (!raw) {
    console.warn(`[checkOrigin] reject ${req.method} ${req.url} — session cookie present but no Origin/Referer header (peer=${req.socket?.remoteAddress || '?'})`);
    return false;
  }
  try {
    const u = new URL(raw);
    const originHost = u.host.toLowerCase();
    if (originHost === host) return true;
    // Behind a reverse proxy that rewrites the Host header to the upstream socket
    // (nginx without `proxy_set_header Host`, Caddy with default reverse_proxy,
    // cloudflared with `httpHostHeader: localhost`), Origin will match the public
    // hostname while Host arrives as `localhost:PORT`. Accept the forwarded host
    // when the peer is a trusted proxy — same trust gate the rate limiter uses.
    if (TRUST_PROXY && isTrustedProxyIp(req.socket?.remoteAddress || '')) {
      const xfh = (req.headers['x-forwarded-host'] || '').toLowerCase().split(',')[0].trim();
      if (xfh && originHost === xfh) return true;
    }
    console.warn(`[checkOrigin] reject ${req.method} ${req.url} — origin "${originHost}" ≠ host "${host}"` +
      (TRUST_PROXY ? ` (x-forwarded-host="${req.headers['x-forwarded-host'] || ''}", peer=${req.socket?.remoteAddress || '?'})` : ''));
    return false;
  } catch {
    console.warn(`[checkOrigin] reject ${req.method} ${req.url} — invalid Origin/Referer "${raw}"`);
    return false;
  }
}

// ── Router ────────────────────────────────────────────────────────────────────
function handler(req, res) {
  setSecurityHeaders(req, res);
  const urlPath = req.url.split('?')[0];

  // Belt-and-braces alongside the X-Robots-Tag header and the <meta robots> in
  // index.html: a polite crawler reads /robots.txt before anything else and a
  // Disallow: / here stops it cold. Served unauthenticated and cached for a
  // day so it never causes load. Lives above the /api prefix so the static
  // fallback never gets a shot at returning a 404 for it.
  if (urlPath === '/robots.txt' && req.method === 'GET') {
    res.setHeader('Cache-Control', 'public, max-age=86400');
    return respond(res, 200, 'text/plain; charset=utf-8',
      'User-agent: *\nDisallow: /\n');
  }

  if (urlPath.startsWith('/api/')) {
    if (req.method === 'OPTIONS') {
      res.writeHead(204, { 'Allow': 'GET, PUT, POST, DELETE, OPTIONS' });
      return res.end();
    }

    // CSRF guard: unsafe methods must come from same-origin contexts
    if (isUnsafeMethod(req.method) && !checkOrigin(req)) {
      return json(res, 403, { error: 'Cross-origin request blocked' });
    }

    // Public endpoints — no auth required. Don't leak process.uptime to anonymous
    // clients; it is a fingerprinting signal worth nothing to legitimate health probes.
    if (urlPath === '/api/health' && req.method === 'GET')
      return json(res, 200, { ok: true });
    // /api/setup/status is also public: the login screen reads it to render a
    // configuration banner before any login can succeed when BEAMMP_SERVER_DIR is
    // wrong. No secrets leak — only the filesystem paths the operator chose.
    if (urlPath === '/api/setup/status' && req.method === 'GET') return apiSetupStatus(req, res);

    // Auth
    if (urlPath === '/api/auth/me'              && req.method === 'GET')  return apiAuthMe(req, res);
    if (urlPath === '/api/auth/login'           && req.method === 'POST') return apiAuthLogin(req, res);
    if (urlPath === '/api/auth/logout'          && req.method === 'POST') return apiAuthLogout(req, res);
    if (urlPath === '/api/auth/change-password' && req.method === 'POST') return apiAuthChangePassword(req, res);
    // Second-factor management. Each endpoint requires a valid session and is
    // self-gated; they live alongside change-password so they remain reachable
    // even while the must_change_password flag is set on the user.
    if (urlPath === '/api/auth/2fa/status'      && req.method === 'GET')  return apiAuth2faStatus(req, res);
    if (urlPath === '/api/auth/2fa/setup'       && req.method === 'POST') return apiAuth2faSetup(req, res);
    if (urlPath === '/api/auth/2fa/confirm'     && req.method === 'POST') return apiAuth2faConfirm(req, res);
    if (urlPath === '/api/auth/2fa/rotate'      && req.method === 'POST') return apiAuth2faRotate(req, res);
    if (urlPath === '/api/auth/2fa/disable'     && req.method === 'POST') return apiAuth2faDisable(req, res);

    // All routes below require a valid session
    const sess = checkAnyAuth(req);
    if (!sess) return json(res, 401, { error: 'Unauthorized' });

    // While must_change_password is set, deny everything except the change-password
    // flow (already handled above as a public endpoint with credential proof).
    if (userMustChangePassword(sess.username)) {
      return json(res, 403, { error: 'Password change required', mustChangePassword: true });
    }

    // Panel users CRUD
    if (urlPath === '/api/panel/users' && req.method === 'GET')  return apiPanelUsers(req, res);
    if (urlPath === '/api/panel/users' && req.method === 'POST') return apiPanelUserCreate(req, res);

    // Panel settings
    if (urlPath === '/api/panel/settings' && req.method === 'GET') return apiPanelSettingsGet(req, res);
    if (urlPath === '/api/panel/settings' && req.method === 'PUT') return apiPanelSettingsPut(req, res);
    if (urlPath === '/api/discord/webhook/test' && req.method === 'POST') return apiDiscordWebhookTest(req, res);

    // Role permissions
    if (urlPath === '/api/permissions/role' && req.method === 'GET') return apiRolePermissionsGet(req, res);
    if (urlPath === '/api/permissions/role' && req.method === 'PUT') return apiRolePermissionsPut(req, res);

    // Mod upload & history
    if (urlPath === '/api/mods/upload'       && req.method === 'POST')   return apiModUpload(req, res);
    if (urlPath === '/api/mods/upload/chunk' && req.method === 'POST')   return apiModUploadChunk(req, res);
    if (urlPath === '/api/mods/history'      && req.method === 'GET')    return apiModHistoryGet(res);
    if (urlPath === '/api/mods/history'      && req.method === 'DELETE') return apiModHistoryDelete(req, res);
    if (urlPath === '/api/mods'              && req.method === 'GET')    return apiMods(req, res);
    const modDelMatch = urlPath.match(/^\/api\/mods\/(client|server)\/([^/]+)$/);
    if (modDelMatch && req.method === 'DELETE') return apiModDelete(req, res, modDelMatch[1], decodeURIComponent(modDelMatch[2]));
    const modPreviewMatch = urlPath.match(/^\/api\/mods\/client\/([^/]+)\/preview$/);
    if (modPreviewMatch && req.method === 'GET') return apiModPreview(req, res, decodeURIComponent(modPreviewMatch[1]));

    // Maps catalogue
    if (urlPath === '/api/maps'          && req.method === 'GET')  return apiMaps(req, res);
    if (urlPath === '/api/maps/activate' && req.method === 'POST') return apiMapsActivate(req, res);
    const mapPreviewMatch = urlPath.match(/^\/api\/maps\/preview\/([^/]+)\/([^/]+)$/);
    if (mapPreviewMatch && req.method === 'GET') return apiMapPreview(req, res, decodeURIComponent(mapPreviewMatch[1]), decodeURIComponent(mapPreviewMatch[2]));
    if (urlPath === '/api/cars'          && req.method === 'GET')  return apiCars(req, res);
    const carPreviewMatch = urlPath.match(/^\/api\/cars\/preview\/([^/]+)\/([^/]+)$/);
    if (carPreviewMatch && req.method === 'GET') return apiCarPreview(req, res, decodeURIComponent(carPreviewMatch[1]), decodeURIComponent(carPreviewMatch[2]));
    if (urlPath === '/api/maps/rotation' && req.method === 'GET')  return apiMapsRotation(req, res);
    if (urlPath === '/api/maps/rotation' && req.method === 'PUT')  return apiMapsRotationUpdate(req, res);
    if (urlPath === '/api/maps/vote'        && req.method === 'GET')  return apiVoteGet(req, res);
    if (urlPath === '/api/maps/vote/config' && req.method === 'PUT')  return apiVoteConfigUpdate(req, res);
    if (urlPath === '/api/maps/vote/cancel' && req.method === 'POST') return apiVoteCancel(req, res);
    if (urlPath === '/api/server/restart-schedule' && req.method === 'GET') return apiRestartSchedule(req, res);
    if (urlPath === '/api/server/restart-schedule' && req.method === 'PUT') return apiRestartScheduleUpdate(req, res);
    if (urlPath === '/api/broadcast/motd' && req.method === 'GET') return apiMotdLoop(req, res);
    if (urlPath === '/api/broadcast/motd' && req.method === 'PUT') return apiMotdLoopUpdate(req, res);
    if (urlPath === '/api/server/version-check' && req.method === 'GET') return apiServerVersionCheck(req, res);
    if (urlPath === '/api/server/update-binary' && req.method === 'POST') return apiServerUpdateBinary(req, res);
    if (urlPath === '/api/dashboard/extra'      && req.method === 'GET') return apiDashboardExtra(req, res);
    if (urlPath === '/api/config/export'        && req.method === 'GET')  return apiConfigExport(req, res);
    if (urlPath === '/api/config/import'        && req.method === 'POST') return apiConfigImport(req, res);
    if (urlPath === '/api/audit'             && req.method === 'GET')    return apiAuditGet(req, res);
    if (urlPath === '/api/audit/export'      && req.method === 'GET')    return apiAuditExport(req, res);
    if (urlPath === '/api/admin/backup'      && req.method === 'GET')    return apiAdminBackup(req, res);
    if (urlPath === '/api/admin/stats'       && req.method === 'GET')    return apiAdminStats(req, res);
    if (urlPath === '/api/admin/health'      && req.method === 'GET')    return apiAdminHealth(req, res);
    if (urlPath === '/api/admin/metrics'     && req.method === 'GET')    return apiAdminMetricsProm(req, res);
    const panelUserM = urlPath.match(/^\/api\/panel\/users\/([^/]+)$/);
    if (panelUserM && req.method === 'PUT')    return apiPanelUserUpdate(req, res, decodeURIComponent(panelUserM[1]));
    if (panelUserM && req.method === 'DELETE') return apiPanelUserDelete(req, res, decodeURIComponent(panelUserM[1]));

    // Server control (auth-protected)
    if (urlPath === '/api/server/start'   && req.method === 'POST') return apiServerStart(req, res);
    if (urlPath === '/api/server/stop'    && req.method === 'POST') return apiServerStop(req, res);
    if (urlPath === '/api/server/restart' && req.method === 'POST') return apiServerRestart(req, res);
    if (urlPath === '/api/server/reload'  && req.method === 'POST') return apiServerReload(req, res);

    // Player control
    if (urlPath === '/api/players/kick'   && req.method === 'POST') return apiPlayerKick(req, res);
    if (urlPath === '/api/players/ban'    && req.method === 'POST') return apiPlayerBan(req, res);
    if (urlPath === '/api/players/merge'  && req.method === 'POST') return apiPlayersMerge(req, res);
    if (urlPath === '/api/bans'           && req.method === 'GET')  return apiBansList(req, res);
    const unbanMatch = urlPath.match(/^\/api\/players\/([^/]+)\/ban$/);
    if (unbanMatch && req.method === 'DELETE') return apiPlayerUnban(req, res, decodeURIComponent(unbanMatch[1]));
    const playerNickMatch = urlPath.match(/^\/api\/players\/([^/]+)\/nickname$/);
    if (playerNickMatch && req.method === 'PUT') return apiPlayerNickname(req, res, decodeURIComponent(playerNickMatch[1]));

    // Whitelist
    if (urlPath === '/api/whitelist'     && req.method === 'GET')  return apiWhitelistGet(res);
    if (urlPath === '/api/whitelist'     && req.method === 'PUT')  return apiWhitelistPut(req, res);
    if (urlPath === '/api/whitelist/add' && req.method === 'POST') return apiWhitelistAdd(req, res);

    // Data endpoints
    if (urlPath === '/api/metrics'         && req.method === 'GET') return apiMetrics(res);
    if (urlPath === '/api/logs'            && req.method === 'GET') return apiLogs(req, res);
    if (urlPath === '/api/logs/clear'      && req.method === 'POST') return apiLogsClear(req, res);
    if (urlPath === '/api/logs/stream'     && req.method === 'GET') return apiLogsStream(req, res);
    if (urlPath === '/api/config'          && req.method === 'GET') return apiConfig(req, res);
    if (urlPath === '/api/config'          && req.method === 'PUT') return apiConfigUpdate(req, res);
    if (urlPath === '/api/config/authkey'  && req.method === 'GET') return apiConfigAuthKey(req, res);
    if (urlPath === '/api/players'         && req.method === 'GET') return apiPlayers(req, res);
    if (urlPath === '/api/chat'            && req.method === 'GET') return apiChat(req, res);
    if (urlPath === '/api/players/history' && req.method === 'GET') return apiPlayersHistory(req, res);
    if (urlPath === '/api/broadcast'       && req.method === 'POST') return apiBroadcast(req, res);
    return json(res, 404, { error: 'Unknown endpoint' });
  }

  if (req.method !== 'GET' && req.method !== 'HEAD') {
    return respond(res, 405, 'text/plain', 'Method Not Allowed');
  }

  // Static files: allow-list of public roots only. Blocks /.env, /panel.db,
  // /.git, /server.js, /node_modules, /package.json, /tools, etc.
  const STATIC_ALLOWED_FILES = new Set([
    '/index.html',
    '/sw.js',
    '/manifest.webmanifest',
    '/src/styles.css',
  ]);
  // /src/assets/ holds the panel's branded icons (icon.png + icon-192.png +
  // icon-512.png referenced by index.html, the PWA manifest and the service
  // worker). JSX is served from /dist/ now (pre-transpiled by build.js).
  const STATIC_ALLOWED_PREFIXES = ['/src/assets/', '/dist/'];
  const requested = urlPath === '/' ? '/index.html' : urlPath;
  const isAllowed = STATIC_ALLOWED_FILES.has(requested)
    || STATIC_ALLOWED_PREFIXES.some(p => requested.startsWith(p));
  if (!isAllowed) {
    return respond(res, 404, 'text/plain', '404 Not Found');
  }

  const filePath = path.resolve(ROOT, '.' + requested);
  if (!filePath.startsWith(ROOT + path.sep)) {
    return respond(res, 403, 'text/plain', '403 Forbidden');
  }

  fs.readFile(filePath, (err, data) => {
    if (err) {
      return respond(res, err.code === 'ENOENT' ? 404 : 500, 'text/plain', `${err.code} — ${urlPath}`);
    }
    // Smart Cache-Control: long for /dist/ JS and /src/assets/ images (rare changes,
    // network-first SW handles the few that matter); short for index.html / sw.js so
    // updates propagate quickly; no-store for /api/ already handled by `respond()`'s
    // default. Lets Cloudflare cache the heavy stuff and saves bandwidth.
    const mime = MIME[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
    let cache = 'no-store';
    if (requested.startsWith('/dist/'))            cache = 'public, max-age=600';
    else if (requested.startsWith('/src/assets/')) cache = 'public, max-age=86400, immutable';
    else if (requested === '/src/styles.css')      cache = 'public, max-age=600';
    else if (requested === '/manifest.webmanifest')cache = 'public, max-age=3600';
    else if (requested === '/sw.js')               cache = 'no-cache';
    else if (requested === '/index.html')          cache = 'no-cache';
    // Rewrite index.html to append a cache-busting ?v=BUILD_VERSION to each
    // /dist/*.js script source. Cloudflare aggressively upgrades the bundle
    // max-age downstream regardless of origin's `no-cache`, so without
    // versioned URLs a deploy can stay invisible for hours in browser caches.
    // The query param is stripped on the server side (urlPath ignores it),
    // so the same physical files keep serving — only the cache key changes.
    if (requested === '/index.html') {
      const v = getBuildVersion();
      data = Buffer.from(
        data.toString('utf8')
          // Cache-bust /dist/*.js script tags
          .replace(/(src="(?:[^"]*\/)?dist\/[^"]+\.js)"/g, `$1?v=${v}"`)
          // Cache-bust src/styles.css link too — Cloudflare honours the
          // origin's max-age=600 on the file so without a versioned URL a
          // CSS-only deploy stays invisible for up to 10 min while the
          // edge replays the previous stylesheet.
          .replace(/(href="(?:[^"]*\/)?src\/styles\.css)"/g, `$1?v=${v}"`),
        'utf8'
      );
    }
    respond(res, 200, mime, data, { 'Cache-Control': cache });
  });
}

// Build identity used to invalidate bundle URLs after every redeploy. Re-read
// from dist/app.js's mtime on each call, with a 5-second memoization to avoid
// stat-ing on every static request. Previously this was computed once at
// module load, which left `?v=…` frozen at the boot-time value — a deploy
// that ran `git pull && npm run build` without a node restart kept serving
// the old query string, so Cloudflare's edge happily replayed the previous
// bundle under that URL until the next node restart. With this, every
// rebuild reaches browsers on the next /index.html fetch (the cache is at
// most 5s stale; well below the 'visit panel after deploy' latency).
const _BUILD_VERSION_TTL_MS = 5000;
let _buildVersionCached = null;
let _buildVersionStaleAt = 0;
function getBuildVersion() {
  const now = Date.now();
  if (_buildVersionCached && now < _buildVersionStaleAt) return _buildVersionCached;
  try {
    const st = fs.statSync(path.join(ROOT, 'dist', 'app.js'));
    _buildVersionCached = String(Math.floor(st.mtimeMs));
  } catch {
    _buildVersionCached = String(now);
  }
  _buildVersionStaleAt = now + _BUILD_VERSION_TTL_MS;
  return _buildVersionCached;
}

// Rotate up to N timestamped backups of ServerConfig.toml before each save.
// Without rotation, a single .bak file is overwritten on every save — two bad
// saves in a row would lose the last good config. We keep the legacy single
// .bak (ServerConfig.toml.bak — always the last save) plus per-save dated
// copies (ServerConfig.toml.2026-05-19-21-37-04.bak) up to CFG_BACKUPS_KEEP.
const CFG_BACKUPS_KEEP = Math.max(1, parseInt(process.env.CFG_BACKUPS_KEEP, 10) || 10);
async function rotateConfigBackup() {
  try {
    const dir   = path.dirname(BEAMMP_CFG_FILE);
    const base  = path.basename(BEAMMP_CFG_FILE);
    const stamp = new Date().toISOString().replace(/[:T]/g, '-').slice(0, 19);
    const dated = path.join(dir, `${base}.${stamp}.bak`);
    await fsp.copyFile(BEAMMP_CFG_FILE, BEAMMP_CFG_FILE + '.bak');     // legacy single .bak
    await fsp.copyFile(BEAMMP_CFG_FILE, dated).catch(() => {});    // dated rotation
    // Trim oldest dated backups beyond the limit
    const entries = await fsp.readdir(dir).catch(() => []);
    const ours    = entries
      .filter(n => n.startsWith(base + '.') && n.endsWith('.bak') && n !== base + '.bak')
      .sort();
    while (ours.length > CFG_BACKUPS_KEEP) {
      const drop = ours.shift();
      await fsp.unlink(path.join(dir, drop)).catch(() => {});
    }
  } catch (e) { log.warn('config backup rotation failed:', e.message); }
}

// ── Start ─────────────────────────────────────────────────────────────────────
seedDefaultUsers();
loadLogFileIntoBuffer();
startLogTail();
startPlayerBridgeWatcher();
_startVoteResultWatcher();
// Publish vote_config.json at boot so the plugin reads the latest panel
// settings on its first tick (no plugin restart required after a config
// change — the plugin re-reads the file on every tick).
_publishVoteConfig().catch(() => {});
cleanupOldChunks();
setInterval(cleanupOldChunks, 60 * 60 * 1000); // sweep abandoned chunk dirs every hour

// Sweeper status counters surfaced via /api/admin/stats so ops can see whether
// the background tasks are firing in prod without grepping logs.
const _sweeperState = {
  audit:    { lastRunAt: null, lastRemoved: 0 },
  login:    { lastRunAt: null, lastRemoved: 0 },
  chunks:   { lastRunAt: null, lastRemoved: 0 },
  sessions: { lastRunAt: null, lastRemoved: 0 },
};

// Audit log retention: keep entries for AUDIT_RETENTION_DAYS (env, default 365),
// sweep daily. Without this the table grows unbounded forever.
//
// The hash chain (insertAuditLog) is broken by definition when we delete the
// oldest rows — the next surviving row's prev_hash points at a now-gone row.
// We can't avoid that without unbounded retention, but we CAN make the gap
// visible: before deleting, insert an `audit.retention.sweep` row containing
// the count of rows being removed and the row_hash of the most recent
// row being kept. Any external verifier that walks the chain from the boundary
// row forward gets a continuous chain; tampering with the cutoff (e.g. an
// attacker deleting the most recent row to hide their tracks) makes the
// boundary row's `detail` disagree with the actual database state.
const AUDIT_RETENTION_DAYS = Math.max(1, parseInt(process.env.AUDIT_RETENTION_DAYS, 10) || 365);
function sweepAuditLog() {
  if (!db) return;
  try {
    const cutoff = new Date(Date.now() - AUDIT_RETENTION_DAYS * 86400 * 1000)
      .toISOString().replace('T', ' ').slice(0, 19);
    // Count what we're about to delete; if zero, skip the boundary row entirely.
    const countRow = db.prepare('SELECT COUNT(*) AS n FROM audit_log WHERE logged_at < ?').get(cutoff);
    const toDelete = countRow?.n || 0;
    if (toDelete > 0) {
      // Record the boundary BEFORE the delete so the new row's prev_hash chains
      // off the surviving most-recent row, not the row we're about to remove.
      // Note the most recent kept row's hash too, so an external verifier can
      // reconcile: boundary.prev_hash === (most recent kept row).row_hash.
      const mostRecentKept = db.prepare(`SELECT row_hash FROM audit_log WHERE logged_at >= ? ORDER BY id DESC LIMIT 1`).get(cutoff);
      insertAuditLog('system', 'audit.retention.sweep', String(toDelete),
        `${toDelete} rows older than ${cutoff} pruned; tail=${(mostRecentKept?.row_hash || '').slice(0, 16)}`);
    }
    const r = db.prepare('DELETE FROM audit_log WHERE logged_at < ?').run(cutoff);
    _sweeperState.audit = { lastRunAt: Date.now(), lastRemoved: r.changes };
    if (r.changes > 0) log.info(`audit sweep: removed ${r.changes} entries older than ${AUDIT_RETENTION_DAYS}d`);
  } catch (e) { log.warn('audit sweep failed:', e.message); }
}
sweepAuditLog();
setInterval(sweepAuditLog, 24 * 60 * 60 * 1000);

// Drop expired login_attempts every 30 min so the table doesn't grow unbounded
function sweepLoginAttempts() {
  if (!db) return;
  try {
    const r = db.prepare('DELETE FROM login_attempts WHERE reset_at < ?').run(Date.now());
    _sweeperState.login = { lastRunAt: Date.now(), lastRemoved: r.changes };
  } catch {}
}
sweepLoginAttempts();
setInterval(sweepLoginAttempts, 30 * 60 * 1000);

// Drop expired sessions every hour. createSession opportunistically clears
// expired rows when minting a new token, but if the panel has zero logins
// for weeks the table grows unbounded. getSession already filters by
// `expires_at > ?` at read time, so this is for table hygiene rather than
// correctness — keeps /api/admin/stats honest and the rows count tiny.
function sweepExpiredSessions() {
  if (!db) return;
  try {
    const r = db.prepare('DELETE FROM sessions WHERE expires_at < ?').run(Date.now());
    _sweeperState.sessions = { lastRunAt: Date.now(), lastRemoved: r.changes };
  } catch {}
}
sweepExpiredSessions();
setInterval(sweepExpiredSessions, 60 * 60 * 1000);

// Lift bans whose TTL has passed. Runs hourly. Drops the bans row and writes
// a `player.unban.expired` audit-log line so an operator can still see who was
// banned, by whom, and when the ban was cleared. Once the BeamMP-Server
// integration lands, this is also the place to push the unban to the
// allowlist/blocklist that BeamMP-Server consults.
_sweeperState.bans = { lastRunAt: null, lastRemoved: 0 };
async function sweepExpiredBans() {
  if (!db) return;
  try {
    const nowIso = new Date().toISOString().replace('T', ' ').slice(0, 19);
    const rows = db.prepare('SELECT id, name FROM bans WHERE expires_at IS NOT NULL AND expires_at <= ?').all(nowIso);
    let removed = 0;
    for (const r of rows) {
      try {
        db.prepare('DELETE FROM bans WHERE id = ?').run(r.id);
        insertAuditLog('system', 'player.unban.expired', r.id, r.name || '');
        removed++;
      } catch (e) { log.warn('expired-ban removal failed:', e.message); }
    }
    _sweeperState.bans = { lastRunAt: Date.now(), lastRemoved: removed };
    if (removed > 0) {
      log.info(`bans sweep: auto-unbanned ${removed} expired entr${removed === 1 ? 'y' : 'ies'}`);
      // Republish so the plugin's onPlayerAuth stops refusing players whose
      // ban just expired. Without this, an expired ban would still be in
      // bans.json until the next manual ban/unban triggered a refresh.
      await _publishBans().catch(() => {});
    }
  } catch (e) { log.warn('bans sweep failed:', e.message); }
}
// Boot-time publish so bans.json reflects current DB state before the plugin
// even starts polling — covers the case where the panel restarts with bans
// already in the table (otherwise the file would be missing or stale from
// the previous run until the next ban/unban action).
_publishBans().catch(() => {});
sweepExpiredBans();
setInterval(sweepExpiredBans, 60 * 60 * 1000);

// ── Scheduled DB backups ─────────────────────────────────────────────────────
// VACUUM INTO produces a consistent snapshot of the live DB without locking
// readers/writers, so the sweep can run while the panel is serving requests.
// BACKUP_INTERVAL_HOURS=0 (default) disables auto-backups; the manual
// /api/admin/backup endpoint still works either way.
//
// Files land in BACKUP_DIR (default: a `backups/` dir next to the DB) with
// names like `panel-2026-05-16T14-30-00.db`. Anything older than the most
// recent BACKUP_KEEP files is deleted.
const BACKUP_INTERVAL_HOURS = Math.max(0, parseInt(process.env.BACKUP_INTERVAL_HOURS, 10) || 0);
const BACKUP_KEEP           = Math.max(1, parseInt(process.env.BACKUP_KEEP, 10) || 14);
const BACKUP_DIR            = path.resolve(process.env.BACKUP_DIR || path.join(path.dirname(DB_PATH), 'backups'));
_sweeperState.backups = { lastRunAt: null, lastRemoved: 0, lastFile: null, lastError: null };

async function runScheduledBackup() {
  if (!db) return;
  try {
    await fsp.mkdir(BACKUP_DIR, { recursive: true });
    const stamp = new Date().toISOString().replace(/[:T]/g, '-').slice(0, 19);
    const dest  = path.join(BACKUP_DIR, `panel-${stamp}.db`);
    // VACUUM INTO refuses to overwrite. The timestamp resolution is 1 s so
    // two manually-forced sweeps in the same second would collide; unlink
    // any pre-existing file first to keep the cron robust.
    await fsp.unlink(dest).catch(() => {});
    db.prepare('VACUUM INTO ?').run(dest);
    // Retention: keep the newest BACKUP_KEEP files, drop the rest.
    const files = (await fsp.readdir(BACKUP_DIR))
      .filter(n => /^panel-.*.db$/.test(n))
      .sort()
      .reverse();
    let removed = 0;
    for (const f of files.slice(BACKUP_KEEP)) {
      await fsp.unlink(path.join(BACKUP_DIR, f)).catch(() => {});
      removed++;
    }
    _sweeperState.backups = { lastRunAt: Date.now(), lastRemoved: removed, lastFile: dest, lastError: null };
    const st = await fsp.stat(dest);
    insertAuditLog('system', 'admin.backup.auto', path.basename(dest), `${st.size} bytes; pruned ${removed} older snapshot(s)`);
    log.info(`backup sweep: wrote ${path.basename(dest)} (${st.size} bytes), pruned ${removed} old file(s)`);
  } catch (e) {
    _sweeperState.backups.lastError = e.message;
    log.warn('backup sweep failed:', e.message);
  }
}
if (BACKUP_INTERVAL_HOURS > 0) {
  // Don't run on boot — wait a full interval so a panel that restarts every
  // few minutes (during initial setup) doesn't spam backup files. The first
  // backup fires BACKUP_INTERVAL_HOURS hours after boot.
  setInterval(runScheduledBackup, BACKUP_INTERVAL_HOURS * 60 * 60 * 1000);
  log.info(`scheduled backups enabled: every ${BACKUP_INTERVAL_HOURS}h, keeping ${BACKUP_KEEP} snapshots in ${BACKUP_DIR}`);
}

const server = http.createServer((req, res) => {
  // Honour an upstream X-Request-Id (e.g. from Cloudflare) to keep correlation
  // across the proxy → panel → AC server hops; otherwise mint a fresh one.
  // Strip anything that isn't [A-Za-z0-9-] — control chars or spaces in this
  // header land in our log lines (see _logEmit) and downstream parsers, so
  // letting them through is a log-injection vector.
  const reqIdRaw = String(req.headers['x-request-id'] || '').replace(/[^A-Za-z0-9-]/g, '').slice(0, 64);
  const reqId = reqIdRaw || newRequestId();
  res.setHeader('X-Request-Id', reqId);
  _reqContext.run({ reqId }, () => handler(req, res));
});

server.listen(PORT, HOST, () => {
  const ip   = getNetworkIP();
  const line = '─'.repeat(44);
  console.log(`\n  ${line}`);
  console.log(`    BeamNG Server Panel v${require('./package.json').version}`);
  console.log(`  ${line}`);
  console.log(`    Local    →  http://localhost:${PORT}`);
  console.log(`    Network  →  http://${ip}:${PORT}`);
  console.log(`  ${line}\n`);
  _logBootConfig();
  console.log('');

  // Boot-time misconfiguration warning. TRUST_PROXY=1 plus HOST=0.0.0.0 used to
  // let any LAN client spoof CF-Connecting-IP and frame the audit log / bypass
  // the login lockout. clientIp now ignores the headers when the socket peer
  // isn't in the trusted-proxy allowlist (see _trustedProxyMatchers), so the
  // worst case is "spoof attempts get ignored" rather than "spoof attempts
  // succeed" — but the combination is still operator error worth surfacing.
  if (TRUST_PROXY && (HOST === '0.0.0.0' || HOST === '::')) {
    console.warn(`  ⚠️  TRUST_PROXY=1 with HOST=${HOST} — the panel is reachable directly from any LAN client.`);
    console.warn(`     Forwarded-IP headers will only be honoured from the Cloudflare ranges (or your`);
    console.warn(`     TRUST_PROXY_FROM override). Set HOST=127.0.0.1 in .env when behind Cloudflare`);
    console.warn(`     Tunnel / a local reverse proxy to remove direct LAN exposure entirely.\n`);
  }
  if (TRUST_PROXY) {
    // Surface what TRUST_PROXY=1 will actually trust at runtime. The defensive
    // fallback in clientIp() means an empty matcher set just makes the panel
    // ignore forward-IP headers — but the operator who set TRUST_PROXY=1
    // expected those headers to do something, so making the discrepancy noisy
    // is what flips this from "silent footgun" to "obvious misconfiguration".
    const cfg = _trustedProxyConfig;
    console.log(`  trust-proxy: ${cfg.matchers.length} trusted ${cfg.matchers.length === 1 ? 'range' : 'ranges'} (source: ${cfg.source === 'env' ? 'TRUST_PROXY_FROM' : 'Cloudflare defaults'})`);
    if (cfg.rejected.length > 0) {
      console.warn(`  ⚠️  TRUST_PROXY_FROM has ${cfg.rejected.length} unparseable ${cfg.rejected.length === 1 ? 'entry' : 'entries'}: ${cfg.rejected.join(', ')}`);
      console.warn(`     These are silently dropped — fix the CIDR shape (e.g. 192.168.0.0/24) or the`);
      console.warn(`     IPv6 prefix (e.g. 2606:4700::) and restart.\n`);
    }
    if (cfg.matchers.length === 0) {
      console.warn(`  ⚠️  TRUST_PROXY=1 but the trusted-proxy allowlist is EMPTY after parsing.`);
      console.warn(`     Every request will be read as coming directly from the socket peer —`);
      console.warn(`     CF-Connecting-IP / X-Forwarded-For / X-Forwarded-Host will be ignored.`);
      console.warn(`     Either unset TRUST_PROXY (if you have no proxy in front) or fix`);
      console.warn(`     TRUST_PROXY_FROM to list your proxy's source CIDRs.\n`);
    }
  }

  // Background timers — map rotation, restart scheduler, etc. — start after
  // the HTTP server is listening so any errors during their first tick can't
  // race the boot banner. Each timer is self-rescheduling and a noop if the
  // corresponding config is missing/disabled in panel_settings.
  try { startMapRotationTimer(); } catch (e) { log.warn('startMapRotationTimer failed:', e.message); }
  try { startRestartSchedulerTimer(); } catch (e) { log.warn('startRestartSchedulerTimer failed:', e.message); }
  try { startMotdLoopTimer(); } catch (e) { log.warn('startMotdLoopTimer failed:', e.message); }
});

server.on('error', err => {
  if (err.code === 'EADDRINUSE') {
    console.error(`\n  ✖  Port ${PORT} already in use — change PORT in .env\n`);
  } else {
    console.error('\n  ✖ ', err.message, '\n');
  }
  process.exit(1);
});

// ── Graceful shutdown ──────────────────────────────────────────────────────────
function shutdown() {
  console.log('\n  Shutting down…');
  // Detach the BeamMP-Server child so the panel can exit without taking the
  // game server with it. The child was already spawned with `detached: true`
  // and its own session, but an explicit unref() makes sure the node event
  // loop doesn't keep us alive waiting on it.
  if (beammpChild && !beammpChild.killed) { try { beammpChild.unref(); } catch {} }
  server.close(() => {
    cleanupOldChunks().finally(() => {
      process.exit(0);
    });
  });
  // Force-exit after 10 s if in-flight requests don't finish
  setTimeout(() => process.exit(0), 10_000).unref();
}
process.on('SIGTERM', shutdown);
process.on('SIGINT',  shutdown);

// Last-resort error handlers. Without these, any unhandled exception or
// rejection inside an async route handler crashes the panel — and on crash
// systemd restarts the process, but the in-flight request never sees a
// response (browser hangs until timeout) and the audit trail loses the
// triggering event. Log loudly so ops can find the root cause; let systemd
// restart us on a *fatal* error (uncaughtException with no recovery).
process.on('unhandledRejection', (reason) => {
  try { log.error('unhandled rejection:', reason && (reason.stack || reason.message || String(reason))); }
  catch { /* swallow — never let the handler itself crash */ }
});
process.on('uncaughtException', (err) => {
  try { log.error('uncaught exception:', err && (err.stack || err.message || String(err))); }
  catch {}
  // The process is in an undefined state after an uncaughtException. Don't
  // pretend we can keep serving — let systemd Restart=on-failure pick us up.
  setTimeout(() => process.exit(1), 100).unref();
});