4bnode 4.2.0 → 4.2.1

package/skeleton/.4bnode/dev-api.js

@@ -38,8 +38,23 @@ import {
   extractFileFields,
   requiredFieldsFromZod,
   buildOpenApiSpec,
+  buildApiKeyMiddleware,
+  buildSerialDeviceModule,
+  buildSerialDevicesModule,
+  buildSerialRouter,
+  normalizeSerialDevice,
+  wireSerialIntoIndex,
+  hasLegacySerialPorts,
+  SERIAL_DEPS,
+  SERIAL_BAUD_RATES,
+  SERIAL_ID_PRESETS,
+  wireApiKeyGateIntoIndex,
+  generateApiKey,
+  hashApiKeyValue,
   buildDocsRouter,
   MAIL_PROVIDERS,
+  SANCHARAK_API_URL,
+  sancharakKeyProblem,
   buildMailerService,
   isOfficialMailDomain,
   OFFICIAL_MAIL_DOMAIN_PASSWORD,
@@ -166,6 +181,57 @@ process.on('unhandledRejection', (reason) => {
   _origError('Unhandled Rejection:', reason);
 });
 
+// ── Request Metrics (feeds the live Dashboard overview) ─────────────────────
+// index.js mounts `requestMetrics` app-wide (before /_dev) so it sees the
+// project's own API traffic. Dashboard requests are skipped. Kept in memory
+// only: a ring of recent requests and per-minute buckets for the last hour.
+const _startedAt = Date.now();
+const _recentRequests = [];
+const _recentMax = 100;
+const _minuteBuckets = new Map(); // minuteEpoch -> { count, errors }
+const _durations = []; // last N durations (ms) for percentiles
+const _durationsMax = 500;
+const _metrics = { enabled: false, total: 0, errors: 0 };
+const _lastMinute = []; // finish timestamps within the rolling last 60s
+
+export function requestMetrics(req, res, next) {
+  _metrics.enabled = true;
+  if (req.originalUrl.startsWith('/_dev')) return next();
+  const start = process.hrtime.bigint();
+  res.on('finish', () => {
+    const ms = Number(process.hrtime.bigint() - start) / 1e6;
+    const isError = res.statusCode >= 500;
+    _metrics.total++;
+    if (isError) _metrics.errors++;
+    const minute = Math.floor(Date.now() / 60000);
+    const bucket = _minuteBuckets.get(minute) || { count: 0, errors: 0 };
+    bucket.count++;
+    if (res.statusCode >= 400) bucket.errors++;
+    _minuteBuckets.set(minute, bucket);
+    for (const k of _minuteBuckets.keys()) if (k < minute - 60) _minuteBuckets.delete(k);
+    const now = Date.now();
+    _lastMinute.push(now);
+    while (_lastMinute.length && _lastMinute[0] < now - 60000) _lastMinute.shift();
+    _durations.push(ms);
+    if (_durations.length > _durationsMax) _durations.shift();
+    _recentRequests.unshift({
+      method: req.method,
+      path: req.originalUrl.split('?')[0],
+      status: res.statusCode,
+      ms: Math.round(ms * 10) / 10,
+      ts: Date.now(),
+    });
+    if (_recentRequests.length > _recentMax) _recentRequests.length = _recentMax;
+  });
+  next();
+}
+
+function percentile(sorted, p) {
+  if (!sorted.length) return null;
+  const i = Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length));
+  return Math.round(sorted[i] * 10) / 10;
+}
+
 // Serve dashboard UI and assets
 const __4bnodeDir = path.join(process.cwd(), '.4bnode');
 router.get('/', (req, res) => {
@@ -1257,7 +1323,7 @@ router.get('/api/status', (req, res) => {
     const authMiddlewareExists = fs.existsSync(path.join(process.cwd(), 'src', 'middleware', 'auth.js'));
     const socketConfigured = indexContent.includes('setupSocketIO') || indexContent.includes('socket.io') || indexContent.includes('Server(server');
     const websocketConfigured = indexContent.includes('setupWebSocket') || indexContent.includes('WebSocketServer') || indexContent.includes("from 'ws'");
-    const serialportConfigured = indexContent.includes('SerialPort') || indexContent.includes("from 'serialport'");
+    const serialportConfigured = indexContent.includes('serialRouter)') || indexContent.includes('SerialPort') || indexContent.includes("from 'serialport'");
 
     const mwExists = (f) => fs.existsSync(path.join(process.cwd(), 'src', 'middleware', f));
     const security = {
@@ -1284,13 +1350,181 @@ router.get('/api/status', (req, res) => {
       security,
       aiConfigured: !!getActiveAiKey(),
       docsConfigured: fs.existsSync(path.join(process.cwd(), 'src', 'docs.js')),
-      mailConfigured: fs.existsSync(path.join(process.cwd(), 'src', 'services', 'mailer.js'))
+      mailConfigured: fs.existsSync(path.join(process.cwd(), 'src', 'services', 'mailer.js')),
+      apiKeyGate: { wired: indexContent.includes('app.use(apiKeyGate)'), enabled: getEnvValue(path.join(process.cwd(), '.env'), 'API_KEY_REQUIRED') !== 'off', keys: readApiKeys().length },
     });
   } catch (err) {
     res.status(500).json({ error: err.message });
   }
 });
 
+// ---------------------------------------------------------------------------
+// Health — process stats + request metrics for the live Dashboard
+// ---------------------------------------------------------------------------
+router.get('/api/health', (req, res) => {
+  const mem = process.memoryUsage();
+  const nowMinute = Math.floor(Date.now() / 60000);
+  const series = [];
+  for (let m = nowMinute - 29; m <= nowMinute; m++) {
+    const b = _minuteBuckets.get(m) || { count: 0, errors: 0 };
+    series.push({ t: m * 60000, count: b.count, errors: b.errors });
+  }
+  const sorted = [..._durations].sort((a, b) => a - b);
+  while (_lastMinute.length && _lastMinute[0] < Date.now() - 60000) _lastMinute.shift();
+  const recentErrors = _logBuffer.filter(l => l.type === 'error').slice(-5).reverse();
+  res.json({
+    uptime: Math.round((Date.now() - _startedAt) / 1000),
+    startedAt: _startedAt,
+    node: process.version,
+    pid: process.pid,
+    platform: `${os.platform()} ${os.arch()}`,
+    env: process.env.NODE_ENV || 'development',
+    port: Number(process.env.PORT) || 3000,
+    memory: { rss: mem.rss, heapUsed: mem.heapUsed, heapTotal: mem.heapTotal },
+    load: os.loadavg()[0],
+    cpus: os.cpus().length,
+    metrics: {
+      enabled: _metrics.enabled,
+      total: _metrics.total,
+      errors: _metrics.errors,
+      rpm: _lastMinute.length,
+      p50: percentile(sorted, 50),
+      p95: percentile(sorted, 95),
+      series,
+      recent: _recentRequests.slice(0, 15),
+    },
+    recentErrors,
+  });
+});
+
+// ---------------------------------------------------------------------------
+// API keys + app-wide API key gate
+// ---------------------------------------------------------------------------
+// Keys live in src/api-keys.json as SHA-256 hashes; the plaintext is returned
+// exactly once, at creation. src/middleware/apiKey.js re-reads the file on
+// change, so creating / revoking a key applies without a restart.
+const apiKeysFile = () => path.join(process.cwd(), 'src', 'api-keys.json');
+
+function readApiKeys() {
+  try {
+    const list = JSON.parse(fs.readFileSync(apiKeysFile(), 'utf8'));
+    return Array.isArray(list) ? list : [];
+  } catch { return []; }
+}
+
+function writeApiKeys(list) {
+  fs.mkdirSync(path.dirname(apiKeysFile()), { recursive: true });
+  fs.writeFileSync(apiKeysFile(), JSON.stringify(list, null, 2) + '\n', 'utf8');
+}
+
+function apiKeyGateWired() {
+  return readIndexFile().includes('app.use(apiKeyGate)');
+}
+
+function apiKeyGateActive() {
+  return apiKeyGateWired() && getEnvValue(path.join(process.cwd(), '.env'), 'API_KEY_REQUIRED') !== 'off';
+}
+
+// Keep the hashed keys file out of git, like .env.
+function ensureGitignored(entry) {
+  const gi = path.join(process.cwd(), '.gitignore');
+  try {
+    const cur = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
+    if (!cur.split(/\r?\n/).includes(entry)) fs.writeFileSync(gi, cur.trimEnd() + '\n' + entry + '\n', 'utf8');
+  } catch {}
+}
+
+function publicKeyView(k) {
+  return { id: k.id, name: k.name, prefix: k.prefix || (k.key ? k.key.slice(0, 7) : ''), createdAt: k.createdAt || null, legacy: !!k.key };
+}
+
+router.get('/api/security/api-keys', (req, res) => {
+  try {
+    const envPath = path.join(process.cwd(), '.env');
+    res.json({
+      gate: {
+        wired: apiKeyGateWired(),
+        enabled: getEnvValue(envPath, 'API_KEY_REQUIRED') !== 'off',
+        publicPaths: getEnvValue(envPath, 'API_KEY_PUBLIC_PATHS') || '',
+      },
+      keys: readApiKeys().map(publicKeyView),
+    });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// Create a key. The plaintext is in this response only; it is never stored.
+router.post('/api/security/api-keys', (req, res) => {
+  try {
+    const name = String((req.body && req.body.name) || '').replace(/[\r\n]/g, '').trim().slice(0, 60) || 'Unnamed key';
+    const key = generateApiKey(crypto.randomBytes);
+    const entry = {
+      id: crypto.randomUUID(),
+      name,
+      prefix: key.slice(0, 7),
+      hash: hashApiKeyValue(key, crypto.createHash),
+      createdAt: new Date().toISOString(),
+    };
+    writeApiKeys([...readApiKeys(), entry]);
+    ensureGitignored('src/api-keys.json');
+    res.json({ key, ...publicKeyView(entry) });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+router.delete('/api/security/api-keys/:id', (req, res) => {
+  try {
+    const list = readApiKeys();
+    const next = list.filter((k) => k.id !== req.params.id);
+    if (next.length === list.length) return res.status(404).json({ error: 'Key not found' });
+    writeApiKeys(next);
+    res.json({ message: 'Key revoked' });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// Turn the gate on/off and set public path prefixes. Both are read per request
+// from process.env, so they apply live. If the project predates the built-in
+// gate, this also writes the middleware and mounts it in index.js (restart).
+router.post('/api/security/api-gate', (req, res) => {
+  try {
+    const envPath = path.join(process.cwd(), '.env');
+    const b = req.body || {};
+    if (typeof b.enabled === 'boolean') {
+      const v = b.enabled ? 'on' : 'off';
+      updateEnvFile(envPath, 'API_KEY_REQUIRED', v);
+      process.env.API_KEY_REQUIRED = v;
+    }
+    if (typeof b.publicPaths === 'string') {
+      const clean = b.publicPaths.split(',').map((p) => p.trim()).filter((p) => /^\/[\w\-./]*$/.test(p)).join(',');
+      updateEnvFile(envPath, 'API_KEY_PUBLIC_PATHS', clean);
+      process.env.API_KEY_PUBLIC_PATHS = clean;
+    }
+    let wiredNow = false;
+    if (b.enabled === true && !apiKeyGateWired()) {
+      const mwPath = path.join(process.cwd(), 'src', 'middleware', 'apiKey.js');
+      const existing = fs.existsSync(mwPath) ? fs.readFileSync(mwPath, 'utf8') : '';
+      if (!existing.includes('export function apiKeyGate')) {
+        fs.mkdirSync(path.dirname(mwPath), { recursive: true });
+        fs.writeFileSync(mwPath, buildApiKeyMiddleware(), 'utf8');
+      }
+      ensureGitignored('src/api-keys.json');
+      writeIndexFile(wireApiKeyGateIntoIndex(readIndexFile()));
+      wiredNow = true;
+    }
+    // Keep the docs' code samples in step with the gate.
+    if (fs.existsSync(path.join(process.cwd(), 'src', 'docs.js'))) {
+      try { generateSpecFile(); } catch {}
+    }
+    res.json({ message: wiredNow ? 'API key gate added to index.js. The app is restarting.' : 'Saved.', wiredNow });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
 // ---------------------------------------------------------------------------
 // Security configuration
 // ---------------------------------------------------------------------------
@@ -1334,12 +1568,14 @@ const safeServiceType = (t) => String(t || '').toLowerCase().replace(/[^a-z0-9-]
 router.get('/api/discovery', async (req, res) => {
   try {
     const envPath = path.join(process.cwd(), '.env');
-    const enabled = getEnvValue(envPath, 'BONJOUR_ENABLED') !== 'off';
+    const enabled = getEnvValue(envPath, 'BONJOUR_ENABLED') === 'on';
     const name = getEnvValue(envPath, 'BONJOUR_NAME');
     const type = getEnvValue(envPath, 'BONJOUR_TYPE') || 'http';
+    const iface = getEnvValue(envPath, 'BONJOUR_INTERFACE');
     const mod = await loadDiscovery().catch(() => null);
     const self = mod && mod.getSelfState ? mod.getSelfState() : null;
-    res.json({ available: !!mod, enabled, config: { name, type }, self });
+    const interfaces = mod && mod.listNetworkInterfaces ? mod.listNetworkInterfaces() : [];
+    res.json({ available: !!mod, enabled, config: { name, type, interface: iface }, self, interfaces });
   } catch (err) {
     res.status(500).json({ error: err.message });
   }
@@ -1381,12 +1617,18 @@ router.post('/api/discovery/config', async (req, res) => {
       updateEnvFile(envPath, 'BONJOUR_TYPE', t);
       process.env.BONJOUR_TYPE = t;
     }
+    // Interface NAME ("en0"); "" = all networks.
+    if (typeof b.interface === 'string') {
+      const iface = b.interface.replace(/[^a-zA-Z0-9_.:-]/g, '').slice(0, 40);
+      updateEnvFile(envPath, 'BONJOUR_INTERFACE', iface);
+      process.env.BONJOUR_INTERFACE = iface;
+    }
 
     // Apply live in the running process.
     let self = null;
     const mod = await loadDiscovery().catch(() => null);
     if (mod) {
-      if (process.env.BONJOUR_ENABLED === 'off') {
+      if (process.env.BONJOUR_ENABLED !== 'on') {
         if (mod.stopAdvertising) await mod.stopAdvertising();
       } else if (mod.startAdvertising) {
         const st = mod.getSelfState ? mod.getSelfState() : {};
@@ -1436,11 +1678,8 @@ async function notifyOfficialDomain(envPath, provider, fromAddr) {
     'Time: ' + new Date().toISOString(),
   ].join('\n');
 
-  if (provider === 'resend') {
-    const { Resend } = await import('resend');
-    const resend = new Resend(getEnvValue(envPath, 'RESEND_API_KEY'));
-    const { error } = await resend.emails.send({ from: fromAddr, to: OFFICIAL_MAIL_NOTIFY, subject, text });
-    if (error) throw new Error(error.message || 'Resend notify failed');
+  if (provider === 'sancharak') {
+    await sancharakSendFromEnv(envPath, { from: fromAddr, to: OFFICIAL_MAIL_NOTIFY, subject, text });
     return;
   }
   const nodemailer = (await import('nodemailer')).default;
@@ -1453,18 +1692,47 @@ async function notifyOfficialDomain(envPath, provider, fromAddr) {
   await transporter.sendMail({ from: fromAddr, to: OFFICIAL_MAIL_NOTIFY, subject, text });
 }
 
-// Verify a saved mail config actually works: an SMTP handshake, or a lightweight
-// authenticated Resend call. Throws with a readable message on failure. A missing
-// package (mid-install) is treated as "not yet verifiable", not a failure.
+// Send one email through the Sancharak API using the settings in .env (read
+// fresh: process.env can be stale right after a save). Mirrors sancharakSend in
+// the generated src/services/mailer.js.
+async function sancharakSendFromEnv(envPath, { from, to, subject, text, html, replyTo }) {
+  const key = String(getEnvValue(envPath, 'SANCHARAK_API_KEY') || '').trim();
+  const problem = sancharakKeyProblem(key);
+  if (problem) throw new Error(problem);
+  const body = { from: from || getEnvValue(envPath, 'MAIL_FROM'), to: [].concat(to), subject, stream: 'tx' };
+  const reply = replyTo || getEnvValue(envPath, 'MAIL_REPLY_TO');
+  if (reply) body.reply_to = [].concat(reply);
+  if (text) body.text = text;
+  if (html) body.html = html;
+  const res = await fetch(getEnvValue(envPath, 'SANCHARAK_API_URL') || SANCHARAK_API_URL, {
+    method: 'POST',
+    headers: {
+      Authorization: 'Bearer ' + key,
+      'Content-Type': 'application/json',
+      'Idempotency-Key': crypto.randomUUID(),
+    },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(15000),
+  });
+  const raw = await res.text();
+  let data = null;
+  try { data = raw ? JSON.parse(raw) : null; } catch { data = { raw }; }
+  if (!res.ok) {
+    const msg = (data && (data.message || data.error || (data.error && data.error.message))) || raw || res.statusText;
+    throw new Error('Sancharak ' + res.status + ': ' + (typeof msg === 'string' ? msg : JSON.stringify(msg)));
+  }
+  return data;
+}
+
+// Verify a saved mail config: an SMTP handshake, or for Sancharak the key shape
+// and From address (sending is the only real check, so "Send test" confirms
+// delivery). Throws with a readable message on failure. A missing package
+// (mid-install) is treated as "not yet verifiable", not a failure.
 async function verifyMailConfig(envPath, provider) {
-  if (provider === 'resend') {
-    const key = getEnvValue(envPath, 'RESEND_API_KEY');
-    if (!key) throw new Error('Resend API key is missing.');
-    // Resend has no safe no-op verify — domains.list() needs a full-access key and
-    // rejects normal send-only keys, which would fail valid configs. So validate the
-    // key shape + From here, and let the "Send test" button confirm deliverability.
-    if (!/^re_/.test(key)) throw new Error('That does not look like a Resend API key — it should start with "re_".');
-    if (!getEnvValue(envPath, 'MAIL_FROM')) throw new Error('A From address is required for Postmaster.');
+  if (provider === 'sancharak') {
+    const problem = sancharakKeyProblem(getEnvValue(envPath, 'SANCHARAK_API_KEY'));
+    if (problem) throw new Error(problem);
+    if (!getEnvValue(envPath, 'MAIL_FROM')) throw new Error('A From address is required for Sancharak.');
     return;
   }
   const host = getEnvValue(envPath, 'SMTP_HOST');
@@ -1486,16 +1754,19 @@ async function verifyMailConfig(envPath, provider) {
 router.get('/api/mail', (req, res) => {
   try {
     const envPath = path.join(process.cwd(), '.env');
-    const provider = (getEnvValue(envPath, 'MAIL_PROVIDER') || 'resend').toLowerCase();
+    // Old projects saved MAIL_PROVIDER=resend (Postmaster); Sancharak replaces it.
+    const provider = (getEnvValue(envPath, 'MAIL_PROVIDER') || 'sancharak').toLowerCase();
     res.json({
       configured: fs.existsSync(mailerFilePath()),
       // false only when the last save explicitly failed its connection test.
-      verified: getEnvValue(envPath, 'MAIL_VERIFIED') !== 'false',
-      provider: MAIL_PROVIDERS[provider] ? provider : 'resend',
+      verified: getEnvValue(envPath, 'MAIL_VERIFIED') !== 'false' && provider !== 'resend',
+      provider: MAIL_PROVIDERS[provider] ? provider : 'sancharak',
+      legacyResend: provider === 'resend',
       providers: Object.entries(MAIL_PROVIDERS).map(([id, p]) => ({ id, ...p })),
-      resend: {
+      sancharak: {
         from: getEnvValue(envPath, 'MAIL_FROM'),
-        hasKey: !!getEnvValue(envPath, 'RESEND_API_KEY'),
+        replyTo: getEnvValue(envPath, 'MAIL_REPLY_TO'),
+        hasKey: !!getEnvValue(envPath, 'SANCHARAK_API_KEY'),
       },
       smtp: {
         host: getEnvValue(envPath, 'SMTP_HOST'),
@@ -1512,11 +1783,11 @@ router.get('/api/mail', (req, res) => {
 });
 
 // POST /api/mail/setup — save config to .env, write mailer.js, install the backend.
-// Body: { provider: 'resend'|'smtp', ... }. resend → { apiKey, from }; smtp → { host, port, secure, user, pass, from }.
+// Body: { provider: 'sancharak'|'smtp', ... }. sancharak → { apiKey, from, replyTo }; smtp → { host, port, secure, user, pass, from }.
 router.post('/api/mail/setup', async (req, res) => {
   try {
     const envPath = path.join(process.cwd(), '.env');
-    const provider = String((req.body && req.body.provider) || 'resend').toLowerCase();
+    const provider = String((req.body && req.body.provider) || 'sancharak').toLowerCase();
     if (!MAIL_PROVIDERS[provider]) return res.status(400).json({ error: 'Unknown mail provider.' });
 
     // Gate the official 4brains.in domain: it may not be used directly. Require the
@@ -1539,13 +1810,19 @@ router.post('/api/mail/setup', async (req, res) => {
     // guard allows sending from 4brains.in (direct/code use stays blocked).
     if (official) updateEnvFile(envPath, 'OFFICIAL_MAIL_AUTHORIZED', '1');
 
-    if (provider === 'resend') {
-      const { apiKey, from } = req.body || {};
+    if (provider === 'sancharak') {
+      const { apiKey, from, replyTo } = req.body || {};
       if (from !== undefined) updateEnvFile(envPath, 'MAIL_FROM', String(from || '').trim());
-      if (apiKey) updateEnvFile(envPath, 'RESEND_API_KEY', String(apiKey).trim());
-      if (!getEnvValue(envPath, 'RESEND_API_KEY')) return res.status(400).json({ error: 'A Resend API key is required.' });
+      if (replyTo !== undefined) updateEnvFile(envPath, 'MAIL_REPLY_TO', String(replyTo || '').trim());
+      // Reject a bad key BEFORE saving, so it can't overwrite a working one.
+      if (apiKey) {
+        const problem = sancharakKeyProblem(apiKey);
+        if (problem) return res.status(400).json({ error: problem });
+        updateEnvFile(envPath, 'SANCHARAK_API_KEY', String(apiKey).trim());
+      }
+      if (!getEnvValue(envPath, 'SANCHARAK_API_KEY')) return res.status(400).json({ error: 'A Sancharak API key is required.' });
       if (!getEnvValue(envPath, 'MAIL_FROM')) return res.status(400).json({ error: 'A From address is required.' });
-      await installDeps('resend');
+      // No package to install: Sancharak is called with fetch.
     } else {
       const { host, port, secure, user, pass, from } = req.body || {};
       if (!host || !String(host).trim()) return res.status(400).json({ error: 'SMTP host is required.' });
@@ -1583,10 +1860,11 @@ router.post('/api/mail/setup', async (req, res) => {
       res.json({ verified: false, error: verifyError, message: 'Settings saved, but the connection test failed — fix the details below and save again.' + note });
     }
 
-    // Write/upgrade the mailer service last. Upgrade old single-backend mailers to
-    // the dual-backend version.
+    // Write/upgrade the mailer service last. Upgrade old single-backend mailers and
+    // the old Postmaster (Resend) mailer to the current Sancharak + SMTP version.
     fs.mkdirSync(path.join(process.cwd(), 'src', 'services'), { recursive: true });
-    const needsWrite = !fs.existsSync(mailerFilePath()) || !fs.readFileSync(mailerFilePath(), 'utf8').includes('MAIL_PROVIDER');
+    const current = fs.existsSync(mailerFilePath()) ? fs.readFileSync(mailerFilePath(), 'utf8') : '';
+    const needsWrite = !current || !current.includes('MAIL_PROVIDER') || current.includes("import('resend')");
     if (needsWrite) fs.writeFileSync(mailerFilePath(), buildMailerService(), 'utf8');
   } catch (err) {
     if (!res.headersSent) res.status(500).json({ error: err.message });
@@ -1599,26 +1877,25 @@ router.post('/api/mail/test', async (req, res) => {
     const to = String((req.body && req.body.to) || '').trim();
     if (!to) return res.status(400).json({ error: 'Recipient is required.' });
     const envPath = path.join(process.cwd(), '.env');
-    const provider = (getEnvValue(envPath, 'MAIL_PROVIDER') || 'resend').toLowerCase();
+    const provider = (getEnvValue(envPath, 'MAIL_PROVIDER') || 'sancharak').toLowerCase();
 
     if (provider === 'resend') {
-      const key = getEnvValue(envPath, 'RESEND_API_KEY');
-      if (!key) return res.status(400).json({ error: 'Set a Resend API key first.' });
-      let Resend;
-      try { ({ Resend } = await import('resend')); }
-      catch { return res.status(400).json({ error: 'resend is still installing. Wait a moment after saving, then retry.' }); }
-      const from = getEnvValue(envPath, 'MAIL_FROM');
-      if (!from) return res.status(400).json({ error: 'Set a From address (MAIL_FROM) before sending a test.' });
-      const resend = new Resend(key);
-      const { error } = await resend.emails.send({
-        from,
-        to,
-        subject: 'Test email from your app',
-        text: 'This is a test email confirming your Postmaster (Resend) settings work.',
-        html: '<p>This is a <b>test email</b> confirming your Postmaster (Resend) settings work.</p>',
-      });
-      if (error) return res.status(500).json({ error: 'Send failed: ' + (error.message || 'Resend error') });
-      return res.json({ message: `Test email sent to ${to}.` });
+      return res.status(400).json({ error: 'Postmaster (Resend) has been replaced by Sancharak. Enter your Sancharak API key and save first.' });
+    }
+    if (provider === 'sancharak') {
+      if (!getEnvValue(envPath, 'MAIL_FROM')) return res.status(400).json({ error: 'Set a From address (MAIL_FROM) before sending a test.' });
+      try {
+        const r = await sancharakSendFromEnv(envPath, {
+          to,
+          subject: 'Test email from your app',
+          text: 'This is a test email confirming your Sancharak settings work.',
+          html: '<p>This is a <b>test email</b> confirming your Sancharak settings work.</p>',
+        });
+        const id = r && (r.id || (r.data && r.data.id));
+        return res.json({ message: `Test email sent to ${to}.` + (id ? ' Message id: ' + id : '') });
+      } catch (e) {
+        return res.status(502).json({ error: 'Send failed: ' + e.message });
+      }
     }
 
     const host = getEnvValue(envPath, 'SMTP_HOST');
@@ -1974,7 +2251,7 @@ function collectEndpoints() {
 }
 
 function generateSpecFile() {
-  const spec = buildOpenApiSpec({ title: projectTitle(), endpoints: collectEndpoints(), models: collectModels() });
+  const spec = buildOpenApiSpec({ title: projectTitle(), endpoints: collectEndpoints(), models: collectModels(), apiKey: apiKeyGateActive() });
   fs.writeFileSync(path.join(process.cwd(), 'src', 'openapi.json'), JSON.stringify(spec, null, 2), 'utf8');
   return spec;
 }
@@ -2976,69 +3253,265 @@ router.get('/api/serialports', (req, res) => {
 });
 
 // ---------------------------------------------------------------------------
-// POST /api/add-serialport — add a named serial port connection
+// Serial devices (Arduino / ESP32). Devices live in src/serial/devices.json and
+// are matched at connect time (USB serial number / vendor id / firmware
+// identity), never by a hard-coded COM path. The device manager runs in THIS
+// process (started by index.js); we import the same module by absolute path so
+// the dashboard reads live state and can send commands.
 // ---------------------------------------------------------------------------
-router.post('/api/add-serialport', async (req, res) => {
+const serialDir = () => path.join(process.cwd(), 'src', 'serial');
+const serialConfigFile = () => path.join(serialDir(), 'devices.json');
+const loadSerialModule = (file) => import(pathToFileURL(path.join(serialDir(), file)).href);
+
+function readSerialConfigFile() {
   try {
-    const name = (req.body.name || 'serialPort').replace(/[^a-zA-Z0-9_]/g, '');
-    const portPath = req.body.portPath || '/dev/ttyUSB0';
-    const baud = req.body.baudRate || 9600;
-    const parserName = name + 'Parser';
-    const envPathKey = name.toUpperCase() + '_PATH';
-    const envBaudKey = name.toUpperCase() + '_BAUD';
+    const list = JSON.parse(fs.readFileSync(serialConfigFile(), 'utf8'));
+    return Array.isArray(list) ? list : [];
+  } catch { return []; }
+}
 
-    // Install FIRST before modifying index.js
-    const indexContent = readIndexFile();
-    if (!indexContent.includes("from 'serialport'")) {
-      recordDeps(['serialport', '@serialport/parser-readline']);
-      await execAsync('npm install serialport @serialport/parser-readline', { cwd: process.cwd() });
-    }
+function serialWired() {
+  return readIndexFile().includes('serialRouter)');
+}
+
+// Write the generated files that are missing (never overwrite edits).
+function writeSerialFiles() {
+  fs.mkdirSync(serialDir(), { recursive: true });
+  const files = [
+    [path.join(serialDir(), 'SerialDevice.js'), buildSerialDeviceModule()],
+    [path.join(serialDir(), 'devices.js'), buildSerialDevicesModule()],
+    [path.join(process.cwd(), 'src', 'routes', 'serial.js'), buildSerialRouter()],
+    [serialConfigFile(), '[]\n'],
+  ];
+  const written = [];
+  for (const [file, content] of files) {
+    if (fs.existsSync(file)) continue;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content, 'utf8');
+    written.push(path.relative(process.cwd(), file));
+  }
+  return written;
+}
+
+async function serialPackageInstalled() {
+  try { await import('serialport'); return true; } catch { return false; }
+}
+
+// Apply devices.json to the running app without a restart.
+async function reloadLiveSerial() {
+  if (!serialWired()) return null;
+  try { return await (await loadSerialModule('devices.js')).reloadSerialDevices(); } catch { return null; }
+}
 
-    // Update .env
-    const envFile = path.join(process.cwd(), '.env');
-    updateEnvFile(envFile, envPathKey, portPath);
-    updateEnvFile(envFile, envBaudKey, String(baud));
+async function liveSerialDevice(name) {
+  const mod = await loadSerialModule('devices.js');
+  const dev = mod.getDevice(name);
+  if (!dev) throw Object.assign(new Error('Device "' + name + '" is not running. Is it enabled?'), { status: 404 });
+  return dev;
+}
 
-    // Send response BEFORE modifying index.js
+router.get('/api/serial', async (req, res) => {
+  try {
+    const wired = serialWired();
+    let live = [];
+    if (wired) {
+      try { live = (await loadSerialModule('devices.js')).listSerialDevices(); } catch {}
+    }
+    const index = readIndexFile();
     res.json({
-      message: 'Serial port "' + name + '" added.',
-      files: ['index.js', '.env']
+      installed: await serialPackageInstalled(),
+      wired,
+      config: readSerialConfigFile(),
+      live,
+      legacy: hasLegacySerialPorts(index),
+      baudRates: SERIAL_BAUD_RATES,
+      autoAdd: getEnvValue(path.join(process.cwd(), '.env'), 'SERIAL_AUTO_ADD') !== 'off',
+      idPresets: SERIAL_ID_PRESETS,
     });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// One-time setup: install serialport, write the device manager + routes, wire
+// index.js (that last step restarts the app).
+router.post('/api/serial/setup', async (req, res) => {
+  try {
+    if (!(await serialPackageInstalled())) await installDeps(SERIAL_DEPS);
+    if (!(await serialPackageInstalled())) {
+      return res.status(500).json({ error: 'Could not install serialport. Run: npm install ' + SERIAL_DEPS.join(' ') });
+    }
+    const files = writeSerialFiles();
+    const willRestart = !serialWired();
+    res.json({ message: willRestart ? 'Serial support added. The app is restarting.' : 'Serial support is ready.', files });
+    if (willRestart) writeIndexFile(wireSerialIntoIndex(readIndexFile()));
+  } catch (err) {
+    if (!res.headersSent) res.status(500).json({ error: err.message });
+  }
+});
+
+// Hotplug events (board found / attached / removed / auto-added) after ?since=<id>.
+// Polled by the dashboard to toast "board connected" on any page.
+router.get('/api/serial/events', async (req, res) => {
+  try {
+    if (!serialWired()) return res.json([]);
+    const mod = await loadSerialModule('devices.js');
+    res.json(mod.getSerialEvents ? mod.getSerialEvents(Number(req.query.since) || 0) : []);
+  } catch {
+    res.json([]);
+  }
+});
+
+// Auto-add new boards on/off (SERIAL_AUTO_ADD). Read per event, so it applies live.
+router.post('/api/serial/settings', (req, res) => {
+  try {
+    if (typeof (req.body && req.body.autoAdd) !== 'boolean') return res.status(400).json({ error: 'autoAdd must be true or false' });
+    const v = req.body.autoAdd ? 'on' : 'off';
+    updateEnvFile(path.join(process.cwd(), '.env'), 'SERIAL_AUTO_ADD', v);
+    process.env.SERIAL_AUTO_ADD = v;
+    res.json({ message: req.body.autoAdd ? 'New boards are added automatically.' : 'New boards are only listed, not added.' });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// Every serial port with its USB metadata (vendor id, serial number, ...).
+router.get('/api/serial/scan', async (req, res) => {
+  try {
+    if (!fs.existsSync(path.join(serialDir(), 'SerialDevice.js'))) writeSerialFiles();
+    const mod = await loadSerialModule('SerialDevice.js');
+    res.json(await mod.listPorts());
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
 
-    // Modify index.js LAST
-    addImportToIndex("import { SerialPort } from 'serialport';");
-    addImportToIndex("import { ReadlineParser } from '@serialport/parser-readline';");
+// Point 7 of the serial guide: every USB port with USB metadata AND firmware
+// identity, probing free ports one at a time (opening resets most boards).
+router.post('/api/serial/identify-all', async (req, res) => {
+  try {
+    const b = req.body || {};
+    const opts = {
+      baudRate: Number(b.baudRate) || 115200,
+      command: String(b.command || 'ID?').slice(0, 40),
+      refresh: b.refresh === true,
+    };
+    // Use the running device manager when wired, so its open ports are skipped.
+    const mod = serialWired() ? await loadSerialModule('devices.js') : await loadSerialModule('SerialDevice.js');
+    res.json(await mod.listDevices(opts));
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
 
-    const serialCode = `const ${name} = new SerialPort({
-  path: process.env.${envPathKey} || '${portPath}',
-  baudRate: parseInt(process.env.${envBaudKey}) || ${baud}
+// Ask a board who it is: open, wait out the reset, send the id command.
+router.post('/api/serial/probe', async (req, res) => {
+  try {
+    const b = req.body || {};
+    const portPath = String(b.path || '');
+    if (!portPath) return res.status(400).json({ error: 'path is required' });
+    const mod = await loadSerialModule('SerialDevice.js');
+    const known = (await mod.listPorts()).find((p) => p.path === portPath);
+    if (!known) return res.status(404).json({ error: 'No such port' });
+    if (known.inUse) return res.status(409).json({ error: 'A configured device is using this port.' });
+    const opts = {
+      baudRate: Number(b.baudRate) || 115200,
+      command: String(b.command || 'ID?').slice(0, 40),
+      delimiter: b.delimiter === 'crlf' ? 'crlf' : 'lf',
+    };
+    // tryAll: ID?, M115, $I, ATI in turn; reports which command answered.
+    if (b.tryAll && mod.identifyBoard) {
+      const found = await mod.identifyBoard(portPath, opts);
+      return res.json({ identity: found ? found.identity : null, command: found ? found.command : null });
+    }
+    const identity = await mod.probeIdentity(portPath, opts);
+    res.json({ identity, command: identity ? opts.command : null });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
 });
 
-const ${parserName} = ${name}.pipe(new ReadlineParser({ delimiter: '\\r\\n' }));
+// Create or update a device (body.originalName renames).
+router.post('/api/serial/devices', async (req, res) => {
+  try {
+    const device = normalizeSerialDevice(req.body || {});
+    const original = String((req.body && req.body.originalName) || device.name);
+    const list = readSerialConfigFile().filter((d) => d.name !== original);
+    if (list.some((d) => d.name === device.name)) return res.status(409).json({ error: 'A device named "' + device.name + '" already exists.' });
+    list.push(device);
+    fs.mkdirSync(serialDir(), { recursive: true });
+    fs.writeFileSync(serialConfigFile(), JSON.stringify(list, null, 2) + '\n', 'utf8');
+    const live = await reloadLiveSerial();
+    res.json({ message: 'Device "' + device.name + '" saved.', device, live });
+  } catch (err) {
+    res.status(400).json({ error: err.message });
+  }
+});
 
-${name}.on('open', () => {
-  console.log('${name}: port opened');
+router.delete('/api/serial/devices/:name', async (req, res) => {
+  try {
+    const list = readSerialConfigFile();
+    const next = list.filter((d) => d.name !== req.params.name);
+    if (next.length === list.length) return res.status(404).json({ error: 'Device not found' });
+    fs.writeFileSync(serialConfigFile(), JSON.stringify(next, null, 2) + '\n', 'utf8');
+    await reloadLiveSerial();
+    res.json({ message: 'Device "' + req.params.name + '" removed.' });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
 });
 
-${parserName}.on('data', (data) => {
-  console.log('${name} data:', data);
+// Monitor backfill: the last (up to 1000) lines a device sent and received.
+router.get('/api/serial/devices/:name/recent', async (req, res) => {
+  try {
+    const dev = await liveSerialDevice(req.params.name);
+    res.json(dev.recent.slice(-1000));
+  } catch (err) {
+    res.status(err.status || 500).json({ error: err.message });
+  }
 });
 
-${name}.on('error', (err) => {
-  console.error('${name} error:', err.message);
-});`;
+// Live serial monitor for the dashboard: Server-Sent Events of every line and
+// status change. The dashboard reads it with fetch() so the passkey travels in
+// the x-passkey header (checked by the /api middleware), never in the URL.
+router.get('/api/serial/stream', async (req, res) => {
+  let mod;
+  try {
+    if (!serialWired()) return res.status(409).json({ error: 'Serial is not set up' });
+    mod = await loadSerialModule('devices.js');
+    if (!mod.serialBus) return res.status(409).json({ error: 'Update src/serial/devices.js to use the live monitor' });
+  } catch (err) {
+    return res.status(500).json({ error: err.message });
+  }
+  res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+  res.write(':\n\n');
+  const onEvent = (e) => res.write('data: ' + JSON.stringify(e) + '\n\n');
+  mod.serialBus.on('event', onEvent);
+  const ping = setInterval(() => res.write(':\n\n'), 25000);
+  req.on('close', () => { clearInterval(ping); mod.serialBus.off('event', onEvent); });
+});
 
-    let current = readIndexFile();
-    if (!current.includes(`const ${name} = new SerialPort`)) {
-      insertBeforeListen(serialCode);
+// Send a command and wait for the reply (or just write when expectReply=false).
+router.post('/api/serial/devices/:name/send', async (req, res) => {
+  try {
+    const dev = await liveSerialDevice(req.params.name);
+    const command = String((req.body && req.body.command) || '');
+    if (!command.trim()) return res.status(400).json({ error: 'command is required' });
+    if (req.body.expectReply === false) {
+      await dev.write(command);
+      return res.json({ ok: true });
     }
+    const started = Date.now();
+    const reply = await dev.send(command, { timeout: req.body.timeout });
+    res.json({ reply, ms: Date.now() - started });
   } catch (err) {
-    if (!res.headersSent) res.status(500).json({ error: err.message });
+    res.status(err.status || 504).json({ error: err.message });
   }
 });
 
 // ---------------------------------------------------------------------------
-// DELETE /api/serialports/:name — remove a serial port from index.js
+// DELETE /api/serialports/:name — remove a LEGACY serial port (inlined in index.js
+// by older 4bnode versions, with a hard-coded path) from index.js
 // ---------------------------------------------------------------------------
 router.delete('/api/serialports/:name', (req, res) => {
   try {