muxmind-ai 2.1.1

package/server.js

@@ -0,0 +1,265 @@
+/**
+ * MuxMind AI (v1.0 Enterprise Edition) — High-Concurrency Multi-Core Server
+ * Node.js `cluster` module fans requests across all available CPU cores.
+ * No provider API keys are ever read from process.env — each request
+ * supplies its own vault entries. A local .env is only used for PORT,
+ * cluster toggle, and the login password/session secret.
+ */
+
+'use strict';
+
+require('dotenv').config();
+const cluster = require('cluster');
+const os = require('os');
+const express = require('express');
+const cors = require('cors');
+const rateLimit = require('express-rate-limit');
+const multer = require('multer');
+const path = require('path');
+
+const { SERVER_CONFIG, PROVIDERS, IMAGE_PROVIDERS } = require('./src/config');
+const { healthCheckAll } = require('./src/api-manager');
+const { staggeredMultiModelStream } = require('./src/router');
+const { generateImage } = require('./src/image-engine');
+const { buildSpeechJob } = require('./src/tts-engine');
+const { parseUpload, buildContextFromUploads } = require('./src/file-parser');
+const { createTaskTracker, recordProviderTurn, completeTask, failTask } = require('./src/ui-render');
+const { issueToken, checkPassword, changePassword, requireAuth } = require('./src/auth');
+
+const numCPUs = os.cpus().length || 1;
+
+if (cluster.isPrimary && process.env.MUXMIND_CLUSTER !== 'off') {
+  console.log(`[MuxMind AI] Primary ${process.pid} launching ${numCPUs} worker(s)...`);
+  for (let i = 0; i < numCPUs; i++) cluster.fork();
+  cluster.on('exit', (worker, code, signal) => {
+    console.warn(`[MuxMind AI] Worker ${worker.process.pid} died (${signal || code}). Restarting...`);
+    cluster.fork();
+  });
+} else {
+  startWorker();
+}
+
+function startWorker() {
+  const app = express();
+
+  app.use(cors());
+  app.use(express.json({ limit: SERVER_CONFIG.BODY_LIMIT }));
+  app.use(express.static(path.join(__dirname), { index: false }));
+
+  // Basic security headers (no extra dependency required).
+  app.use((req, res, next) => {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('X-Frame-Options', 'DENY');
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    res.setHeader('Permissions-Policy', 'geolocation=(), microphone=(self), camera=()');
+    next();
+  });
+
+  const apiLimiter = rateLimit({
+    windowMs: SERVER_CONFIG.RATE_LIMIT_WINDOW_MS,
+    max: SERVER_CONFIG.RATE_LIMIT_MAX,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: 'Rate limit exceeded. Please slow down.' },
+  });
+
+  const loginLimiter = rateLimit({
+    windowMs: SERVER_CONFIG.RATE_LIMIT_WINDOW_MS,
+    max: SERVER_CONFIG.LOGIN_RATE_LIMIT_MAX,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: 'Too many login attempts. Please wait a minute.' },
+  });
+
+  app.use('/api/', apiLimiter);
+
+  const upload = multer({
+    storage: multer.memoryStorage(),
+    limits: { fileSize: SERVER_CONFIG.MAX_UPLOAD_SIZE_BYTES },
+  });
+
+  // ---------------------------------------------------------------------
+  // Health / auth
+  // ---------------------------------------------------------------------
+  app.get('/api/ping', (req, res) => {
+    res.json({ ok: true, pid: process.pid, worker: cluster.worker?.id || 'single', time: Date.now() });
+  });
+
+  app.post('/api/auth/login', loginLimiter, (req, res) => {
+    const { password } = req.body || {};
+    if (!checkPassword(password)) {
+      return res.status(401).json({ ok: false, error: 'Incorrect password.' });
+    }
+    res.json({ ok: true, token: issueToken() });
+  });
+
+  // Change password from inside the app (Settings page). Requires the
+  // current valid session AND re-confirmation of the current password.
+  app.post('/api/auth/change-password', requireAuth, loginLimiter, (req, res) => {
+    const { currentPassword, newPassword } = req.body || {};
+    const result = changePassword(currentPassword, newPassword);
+    if (!result.ok) return res.status(400).json({ ok: false, error: result.error });
+    res.json({ ok: true, token: result.token });
+  });
+
+  // ---------------------------------------------------------------------
+  // Provider directory (for the sidebar "Providers" page): id, label,
+  // color, and the official console URL to obtain an API key. No secrets.
+  // ---------------------------------------------------------------------
+  app.get('/api/providers', requireAuth, (req, res) => {
+    const list = Object.values(PROVIDERS).map((p) => ({
+      id: p.id,
+      label: p.label,
+      color: p.color,
+      keyConsoleUrl: p.keyConsoleUrl,
+      docsUrl: p.docsUrl,
+      keyPrefix: p.keyPrefix,
+    }));
+    res.json({ ok: true, providers: list });
+  });
+
+  // ---------------------------------------------------------------------
+  // Vault: smart live health-check + real-model probing for a batch of
+  // user-supplied provider keys. Keys used only in-memory, never persisted.
+  // ---------------------------------------------------------------------
+  app.post('/api/vault/health-check', requireAuth, async (req, res) => {
+    try {
+      const { entries } = req.body || {};
+      if (!Array.isArray(entries) || entries.length === 0) {
+        return res.status(400).json({ error: 'entries[] is required.' });
+      }
+      const results = await healthCheckAll(entries);
+      res.json({ ok: true, results });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  });
+
+  // ---------------------------------------------------------------------
+  // File upload / multi-modal parsing
+  // ---------------------------------------------------------------------
+  app.post('/api/upload', requireAuth, upload.array('files', 10), (req, res) => {
+    try {
+      const files = req.files || [];
+      const parsed = files.map((f) =>
+        parseUpload({ filename: f.originalname, mimetype: f.mimetype, buffer: f.buffer })
+      );
+      const context = buildContextFromUploads(parsed);
+      res.json({ ok: true, parsed, ...context });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  });
+
+  // ---------------------------------------------------------------------
+  // Image generation — uses whichever vault key the client marks capable
+  // (OpenAI or Gemini keys the client has already smart-validated).
+  // ---------------------------------------------------------------------
+  app.post('/api/image/generate', requireAuth, async (req, res) => {
+    try {
+      const { providerId, apiKey, model, prompt, size } = req.body || {};
+      if (!prompt || !prompt.trim()) return res.status(400).json({ ok: false, error: 'prompt is required.' });
+      if (!IMAGE_PROVIDERS[providerId]) {
+        return res.status(400).json({ ok: false, error: `${providerId || 'This provider'} does not support image generation here. Use OpenAI or Gemini.` });
+      }
+      if (!apiKey) return res.status(400).json({ ok: false, error: 'apiKey is required.' });
+
+      const images = await generateImage({ providerId, apiKey, model, prompt: prompt.trim(), size });
+      res.json({ ok: true, images });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  });
+
+  // ---------------------------------------------------------------------
+  // TTS job builder
+  // ---------------------------------------------------------------------
+  app.post('/api/tts/prepare', requireAuth, (req, res) => {
+    try {
+      const { text, lang } = req.body || {};
+      if (!text) return res.status(400).json({ error: 'text is required.' });
+      const job = buildSpeechJob(text, lang === 'off' ? null : lang);
+      res.json({ ok: true, job });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  });
+
+  // ---------------------------------------------------------------------
+  // Core chat/orchestration endpoint — SSE stream driven by the smart
+  // staggered multi-model token optimization engine.
+  // ---------------------------------------------------------------------
+  app.post('/api/chat/stream', requireAuth, async (req, res) => {
+    const { vault: rawVault, messages, compressionLevel = 50, taskId = `task_${Date.now()}` } = req.body || {};
+
+    // Only ever route to providers we recognize and that carry a concrete
+    // model id — this is the server-side guarantee behind "Smart Saver
+    // only ever uses working models": nothing is invented or guessed here,
+    // only what the client already smart-validated (status: 'active') and
+    // forwarded with an explicit model.
+    const vault = (Array.isArray(rawVault) ? rawVault : []).filter(
+      (v) => v && PROVIDERS[v.providerId] && typeof v.apiKey === 'string' && v.apiKey && typeof v.model === 'string' && v.model
+    );
+
+    if (vault.length === 0) {
+      return res.status(400).json({ error: 'vault[] with at least one valid, verified provider configuration is required.' });
+    }
+    if (!Array.isArray(messages) || messages.length === 0) {
+      return res.status(400).json({ error: 'messages[] is required.' });
+    }
+
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    });
+
+    const tracker = createTaskTracker(taskId);
+    const send = (event, data) => res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+
+    let aborted = false;
+    req.on('close', () => { aborted = true; });
+
+    send('start', { taskId, pid: process.pid });
+
+    try {
+      const fullText = await staggeredMultiModelStream({
+        vault,
+        messages,
+        compressionLevel: Number(compressionLevel),
+        abortSignal: { get aborted() { return aborted; } },
+        onProviderSwitch: (provider, model) => {
+          recordProviderTurn(tracker, provider, model, tracker.providerTimeline.length);
+          send('provider', { provider, model, turn: tracker.providerTimeline.length });
+        },
+        onChunk: (text, meta) => send('chunk', { text, ...meta }),
+      });
+
+      completeTask(tracker, fullText);
+      send('done', { taskId, tokensApprox: tracker.tokensApprox, providerTimeline: tracker.providerTimeline });
+    } catch (err) {
+      failTask(tracker, err.message);
+      send('error', { taskId, error: err.message });
+    } finally {
+      res.end();
+    }
+  });
+
+  // ---------------------------------------------------------------------
+  // Serve index.html for everything else (single-page app)
+  // ---------------------------------------------------------------------
+  app.get('*', (req, res, next) => {
+    if (req.path.startsWith('/api/')) return next();
+    res.sendFile(path.join(__dirname, 'index.html'));
+  });
+
+  app.use((err, req, res, next) => {
+    console.error('[MuxMind AI] Unhandled error:', err);
+    res.status(500).json({ error: 'Internal server error.' });
+  });
+
+  app.listen(SERVER_CONFIG.PORT, () => {
+    console.log(`[MuxMind AI] Worker ${process.pid} listening on port ${SERVER_CONFIG.PORT}`);
+  });
+}

package/src/api-manager.js

@@ -0,0 +1,227 @@
+/**
+ * MuxMind AI — API Manager
+ * Handles server-side health-check proxying for provider keys.
+ * IMPORTANT: Keys are never stored server-side. They arrive per-request
+ * in the request body/headers from the client's own local vault and are
+ * used only for the duration of that single request, then discarded.
+ *
+ * SMART MODEL VALIDATION (fixes "404" issue):
+ * A model appearing in a provider's /models list does NOT guarantee it is
+ * usable by our account/key (some are gated, deprecated, or list-only).
+ * So after listing, we do a tiny real completion probe against a small
+ * shortlist of the most likely-useful models and keep only the ones that
+ * actually respond with HTTP 200. This is what "Live: X models" reflects
+ * in the UI — every model shown there has been proven callable.
+ */
+
+'use strict';
+
+const { PROVIDERS, MODEL_HINTS } = require('./config');
+
+function maskKey(key) {
+  if (!key || typeof key !== 'string') return '****';
+  if (key.length <= 8) return '*'.repeat(key.length);
+  return `${key.slice(0, 6)}...${'*'.repeat(4)}`;
+}
+
+function classifyModel(modelId) {
+  for (const hint of MODEL_HINTS) {
+    if (hint.pattern.test(modelId)) return { tier: hint.tier, power: hint.power };
+  }
+  return { tier: 'balanced', power: 2 };
+}
+
+/**
+ * List raw models from a provider's /models endpoint.
+ */
+async function listModels(providerId, apiKey) {
+  const provider = PROVIDERS[providerId];
+  let url = `${provider.baseUrl}${provider.modelsEndpoint}`;
+  const headers = { 'Content-Type': 'application/json', ...provider.authHeader(apiKey) };
+  if (provider.authQuery) url += `?${provider.authQuery(apiKey)}`;
+
+  const res = await fetch(url, { method: 'GET', headers });
+  if (!res.ok) {
+    return { ok: false, status: res.status, models: [] };
+  }
+  const data = await res.json().catch(() => ({}));
+  return { ok: true, status: res.status, models: extractModelList(providerId, data) };
+}
+
+function extractModelList(providerId, data) {
+  try {
+    if (providerId === 'gemini') {
+      return (data.models || [])
+        .map((m) => (m.name || '').replace('models/', ''))
+        .filter(Boolean);
+    }
+    if (Array.isArray(data.data)) {
+      return data.data.map((m) => m.id).filter(Boolean);
+    }
+    if (Array.isArray(data.models)) {
+      return data.models.map((m) => m.id || m.name).filter(Boolean);
+    }
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Send a minimal 1-token probe completion to confirm a model is genuinely
+ * callable with this key (catches 404 "listed but not accessible" cases).
+ */
+async function probeModel(providerId, apiKey, modelId) {
+  const provider = PROVIDERS[providerId];
+  try {
+    let url, headers, body;
+
+    if (providerId === 'anthropic') {
+      url = `${provider.baseUrl}/messages`;
+      headers = { 'Content-Type': 'application/json', ...provider.authHeader(apiKey) };
+      body = JSON.stringify({ model: modelId, max_tokens: 1, messages: [{ role: 'user', content: 'hi' }] });
+    } else if (providerId === 'gemini') {
+      url = `${provider.baseUrl}/models/${modelId}:generateContent?${provider.authQuery(apiKey)}`;
+      headers = { 'Content-Type': 'application/json' };
+      body = JSON.stringify({ contents: [{ role: 'user', parts: [{ text: 'hi' }] }], generationConfig: { maxOutputTokens: 1 } });
+    } else {
+      url = `${provider.baseUrl}${provider.chatEndpoint}`;
+      headers = { 'Content-Type': 'application/json', ...provider.authHeader(apiKey) };
+      body = JSON.stringify({ model: modelId, messages: [{ role: 'user', content: 'hi' }], max_tokens: 1 });
+    }
+
+    const res = await fetch(url, { method: 'POST', headers, body });
+    return { modelId, live: res.ok, status: res.status };
+  } catch (err) {
+    return { modelId, live: false, status: 0, error: err.message };
+  }
+}
+
+/**
+ * Pick a small, high-value shortlist to probe instead of every listed
+ * model (keeps health-check fast). Prefers the provider's known-good
+ * defaults first, then fills with a few discovered ones across tiers.
+ */
+function buildProbeShortlist(providerId, discoveredModels) {
+  const provider = PROVIDERS[providerId];
+  const shortlist = [];
+  const seen = new Set();
+
+  // Hardcoded defaults can go stale the moment a provider renames/retires
+  // a model, so they're only tried first when the live /models listing
+  // actually confirms they still exist. If listing failed (empty array),
+  // we still try them as a last resort further down.
+  for (const m of provider.defaultModels) {
+    if (discoveredModels.includes(m) && !seen.has(m)) { shortlist.push(m); seen.add(m); }
+  }
+
+  // Primary source of truth: whatever the provider's /models endpoint
+  // actually returned right now, spread across tiers so we don't only
+  // probe (and fail on) one family.
+  const byTier = { fast: [], balanced: [], heavy: [] };
+  for (const m of discoveredModels) {
+    if (seen.has(m)) continue;
+    const { tier } = classifyModel(m);
+    byTier[tier].push(m);
+  }
+  // Round-robin across tiers until we have a generous pool to probe.
+  let added = true;
+  while (shortlist.length < 12 && added) {
+    added = false;
+    for (const tier of ['fast', 'balanced', 'heavy']) {
+      const next = byTier[tier].find((m) => !seen.has(m));
+      if (next) { shortlist.push(next); seen.add(next); added = true; }
+      if (shortlist.length >= 12) break;
+    }
+  }
+
+  // Fall back to the hardcoded defaults even if listing didn't confirm
+  // them (e.g. /models call failed or is incomplete for this provider) —
+  // better to attempt a probe than to give up with zero candidates.
+  if (shortlist.length === 0) {
+    for (const m of provider.defaultModels) {
+      if (!seen.has(m)) { shortlist.push(m); seen.add(m); }
+    }
+  }
+
+  return shortlist.slice(0, 12);
+}
+
+/**
+ * Full smart health-check: list models, then probe a shortlist for real
+ * callability, returning only models proven live plus tier classification.
+ */
+async function healthCheckProvider(providerId, apiKey) {
+  const provider = PROVIDERS[providerId];
+  if (!provider) return { ok: false, error: `Unknown provider: ${providerId}`, models: [] };
+  if (!apiKey) return { ok: false, error: 'No API key supplied', models: [] };
+
+  try {
+    const listing = await listModels(providerId, apiKey);
+
+    if (!listing.ok && (listing.status === 401 || listing.status === 403)) {
+      return {
+        ok: false,
+        error: `Key rejected by provider (HTTP ${listing.status})`,
+        models: [],
+        maskedKey: maskKey(apiKey),
+      };
+    }
+
+    const discovered = listing.ok ? listing.models : [];
+    const shortlist = buildProbeShortlist(providerId, discovered);
+
+    if (shortlist.length === 0) {
+      return { ok: false, error: 'No candidate models to probe', models: [], maskedKey: maskKey(apiKey) };
+    }
+
+    const probes = await Promise.all(shortlist.map((m) => probeModel(providerId, apiKey, m)));
+    const liveModels = probes
+      .filter((p) => p.live)
+      .map((p) => ({ id: p.modelId, ...classifyModel(p.modelId) }));
+
+    if (liveModels.length === 0) {
+      const statuses = [...new Set(probes.map((p) => p.status).filter(Boolean))];
+      const triedList = shortlist.join(', ');
+      const hint = statuses.includes(404)
+        ? ' — model name(s) not found on this account/region; the provider may have renamed or retired them.'
+        : '';
+      return {
+        ok: false,
+        error: `Key reached ${provider.label} but none of the probed models worked (tried: ${triedList}; statuses: ${statuses.join(', ') || 'n/a'})${hint}`,
+        models: [],
+        maskedKey: maskKey(apiKey),
+      };
+    }
+
+    return {
+      ok: true,
+      provider: providerId,
+      label: provider.label,
+      color: provider.color,
+      maskedKey: maskKey(apiKey),
+      models: liveModels,
+      checkedAt: new Date().toISOString(),
+    };
+  } catch (err) {
+    return { ok: false, error: `Connection failed: ${err.message}`, models: [], maskedKey: maskKey(apiKey) };
+  }
+}
+
+async function healthCheckAll(entries) {
+  const results = await Promise.all(
+    entries.map(async ({ providerId, apiKey, label }) => {
+      const result = await healthCheckProvider(providerId, apiKey);
+      return { ...result, providerId, customLabel: label || null };
+    })
+  );
+  return results;
+}
+
+module.exports = {
+  maskKey,
+  healthCheckProvider,
+  healthCheckAll,
+  extractModelList,
+  classifyModel,
+};

package/src/auth.js

@@ -0,0 +1,159 @@
+/**
+ * MuxMind AI — Authentication
+ * Lightweight session-token auth so the app can sit behind a login screen.
+ *
+ * Password storage:
+ * - On first boot, the password is seeded from MUXMIND_PASSWORD in .env
+ *   (or a built-in default if unset) and immediately hashed (scrypt +
+ *   random salt) into a local file (.muxmind-auth.json, gitignored).
+ * - From then on, the hash file is the source of truth. The Settings page
+ *   can change the password at runtime via /api/auth/change-password —
+ *   no server restart or .env edit required.
+ * - Sessions are stateless (HMAC-signed tokens) so any cluster worker can
+ *   verify a token without shared session storage. Changing the password
+ *   rotates the signing secret too, which invalidates old sessions.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const crypto = require('crypto');
+const { SERVER_CONFIG } = require('./config');
+
+const DEFAULT_PASSWORD = 'muxmind2026';
+const STORE_PATH = SERVER_CONFIG.AUTH_STORE_PATH;
+const SESSION_TTL_MS = SERVER_CONFIG.SESSION_TTL_MS || 12 * 60 * 60 * 1000;
+
+function hashPassword(password, salt) {
+  return crypto.scryptSync(password, salt, 64).toString('hex');
+}
+
+function loadStore() {
+  try {
+    const raw = fs.readFileSync(STORE_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && parsed.salt && parsed.hash && parsed.secret) return parsed;
+  } catch {
+    // fall through to seeding a fresh store
+  }
+  return seedStore();
+}
+
+function seedStore() {
+  const seedPassword = process.env.MUXMIND_PASSWORD || DEFAULT_PASSWORD;
+  const salt = crypto.randomBytes(16).toString('hex');
+  const hash = hashPassword(seedPassword, salt);
+  const secret = crypto.randomBytes(32).toString('hex');
+  const store = { salt, hash, secret, updatedAt: new Date().toISOString() };
+  persistStore(store);
+  if (!process.env.MUXMIND_PASSWORD) {
+    console.warn(
+      '[MuxMind AI] WARNING: Using default login password. Change it from Settings once signed in, or set MUXMIND_PASSWORD in .env before first boot.'
+    );
+  }
+  return store;
+}
+
+function persistStore(store) {
+  try {
+    fs.writeFileSync(STORE_PATH, JSON.stringify(store, null, 2), { mode: 0o600 });
+  } catch (err) {
+    console.error('[MuxMind AI] Failed to persist auth store:', err.message);
+  }
+}
+
+let authStore = loadStore();
+
+function sign(payload) {
+  const hmac = crypto.createHmac('sha256', authStore.secret);
+  hmac.update(payload);
+  return hmac.digest('hex');
+}
+
+/**
+ * Issue a signed, stateless session token: base64(expiry) + "." + hmac.
+ */
+function issueToken() {
+  const expiresAt = Date.now() + SESSION_TTL_MS;
+  const payload = String(expiresAt);
+  const sig = sign(payload);
+  return Buffer.from(`${payload}.${sig}`).toString('base64url');
+}
+
+function verifyToken(token) {
+  try {
+    if (!token) return false;
+    const decoded = Buffer.from(token, 'base64url').toString('utf8');
+    const [payload, sig] = decoded.split('.');
+    if (!payload || !sig) return false;
+
+    const expected = sign(payload);
+    const sigBuf = Buffer.from(sig, 'hex');
+    const expectedBuf = Buffer.from(expected, 'hex');
+    if (sigBuf.length !== expectedBuf.length) return false;
+    if (!crypto.timingSafeEqual(sigBuf, expectedBuf)) return false;
+
+    const expiresAt = Number(payload);
+    if (Number.isNaN(expiresAt) || Date.now() > expiresAt) return false;
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Constant-time password check against the current stored hash.
+ */
+function checkPassword(candidate) {
+  if (typeof candidate !== 'string' || candidate.length === 0) return false;
+  const candidateHash = hashPassword(candidate, authStore.salt);
+  const a = Buffer.from(candidateHash);
+  const b = Buffer.from(authStore.hash);
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+
+/**
+ * Change the password at runtime. Requires the current password to match
+ * first. Rotates the session secret, so all existing tokens (this device
+ * included) are invalidated — the caller should re-login immediately with
+ * the new password and store the fresh token.
+ */
+function changePassword(currentPassword, newPassword) {
+  if (!checkPassword(currentPassword)) {
+    return { ok: false, error: 'Current password is incorrect.' };
+  }
+  if (typeof newPassword !== 'string' || newPassword.length < 6) {
+    return { ok: false, error: 'New password must be at least 6 characters.' };
+  }
+  const salt = crypto.randomBytes(16).toString('hex');
+  const hash = hashPassword(newPassword, salt);
+  const secret = crypto.randomBytes(32).toString('hex');
+  authStore = { salt, hash, secret, updatedAt: new Date().toISOString() };
+  persistStore(authStore);
+  return { ok: true, token: issueToken() };
+}
+
+/**
+ * Express middleware — protects /api/* routes (except /api/auth/*) behind
+ * a valid session token sent as "Authorization: Bearer <token>".
+ */
+function requireAuth(req, res, next) {
+  const authHeader = req.headers.authorization || '';
+  const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : null;
+
+  if (!verifyToken(token)) {
+    return res.status(401).json({ error: 'Unauthorized. Please log in again.' });
+  }
+  next();
+}
+
+module.exports = {
+  issueToken,
+  verifyToken,
+  checkPassword,
+  changePassword,
+  requireAuth,
+  DEFAULT_PASSWORD,
+};