[mirotalk-admin] - security: enforce HTTPS-only on the admin dashboard, kill plaintext fall-through

Author: miroslavpejic85

.gitignore

@@ -6,4 +6,5 @@ backend/config/index.js
 docker-compose.yml
 node_modules
 npm-debug.log
-security
+security
+backend/ssl/dev

README.md

@@ -162,3 +162,119 @@ MIROTALK_ADMIN_DIR=/root/mirotalk-admin
 > Regularly review and update your `.env` settings to keep your MiroTalk instance secure and manageable.
 
 ---
+
+### 🔒 TLS / HTTPS in Production
+
+The dashboard listens on a single HTTPS port (`ADMIN_PORT`) via the
+Node.js stdlib `https` module, plaintext HTTP requests on this port are
+rejected at the TLS layer and cannot reach the application.
+
+- Defense-in-depth: when `NODE_ENV=production`, any request whose
+  `req.secure` is false (e.g. arriving through a misconfigured reverse
+  proxy that did not set `X-Forwarded-Proto: https`) is 301-redirected
+  to HTTPS for `GET`/`HEAD` and rejected with `403` for any other
+  method. Plaintext `ws://` socket upgrades are likewise refused.
+- The bundled certificate in [backend/ssl/](backend/ssl/) is **self-signed**
+  and intended for first-boot / local development only. For production,
+  either:
+    - replace `backend/ssl/key.pem` and `backend/ssl/cert.pem` with a
+      certificate issued by a trusted CA (e.g. Let's Encrypt), or
+    - put the dashboard behind a TLS-terminating reverse proxy
+      (nginx, Caddy, Traefik, an ALB, etc.) and bind the dashboard to
+      `127.0.0.1`. When doing so, set `TRUST_PROXY=true` so the
+      `X-Forwarded-Proto` and `X-Forwarded-For` headers are honored.
+- Responses include `Strict-Transport-Security: max-age=63072000; includeSubDomains`
+  to pin compliant browsers to HTTPS.
+
+#### Local development with a trusted cert
+
+The bundled `backend/ssl/cert.pem` is self-signed, so on the first visit
+your browser will show a "Not secure / self-signed certificate" warning.
+Click through it once (Chrome: type `thisisunsafe` on the warning page,
+or **Advanced → Proceed**; Firefox: **Accept the Risk and Continue**) and
+the dashboard at <https://localhost:9999/admin> will load.
+
+To remove the warning entirely in development, install
+[`mkcert`](https://github.com/FiloSottile/mkcert) and issue a cert that
+your OS / browsers actually trust. Place the dev cert in
+`backend/ssl/dev/`, the server auto-detects it when `NODE_ENV` is not
+`production` and falls back to `backend/ssl/` otherwise:
+
+<details>
+<summary>🍎 macOS</summary>
+
+<br/>
+
+```bash
+brew install mkcert nss
+mkcert -install
+
+mkdir -p backend/ssl/dev
+cd backend/ssl/dev
+mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1
+```
+
+</details>
+
+<details>
+<summary>🐧 Linux (Debian / Ubuntu)</summary>
+
+<br/>
+
+```bash
+sudo apt update
+sudo apt install -y libnss3-tools
+# install the mkcert binary (pick the latest release for your arch)
+curl -fsSLo /tmp/mkcert "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
+sudo install -m 0755 /tmp/mkcert /usr/local/bin/mkcert
+mkcert -install
+
+mkdir -p backend/ssl/dev
+cd backend/ssl/dev
+mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1
+```
+
+> On Fedora/RHEL use `sudo dnf install nss-tools`; on Arch use
+> `sudo pacman -S nss mkcert`. For Firefox to trust the cert, make sure
+> `libnss3-tools` (or `nss-tools`) is installed **before** running
+> `mkcert -install`.
+
+</details>
+
+<details>
+<summary>🪟 Windows (PowerShell, run as Administrator)</summary>
+
+<br/>
+
+```powershell
+# Easiest path: Chocolatey
+choco install mkcert
+# …or Scoop:
+# scoop bucket add extras; scoop install mkcert
+mkcert -install
+
+mkdir backend\ssl\dev
+cd backend\ssl\dev
+mkcert -key-file key.pem -cert-file cert.pem localhost 127.0.0.1 ::1
+```
+
+> Firefox on Windows uses its own trust store. After `mkcert -install`,
+> restart Firefox so it picks up the new local CA. Chrome / Edge use the
+> Windows trust store and work immediately.
+
+</details>
+
+<br/>
+
+`backend/ssl/dev/` is gitignored, so the locally-trusted cert never
+ships with the repo. In production the server always uses
+`backend/ssl/key.pem` + `backend/ssl/cert.pem`, which should hold a
+CA-issued cert (or be replaced by a TLS-terminating reverse proxy as
+described above).
+
+Restart the server and the lock icon will be green. The dev workflow is
+otherwise unchanged, the dashboard is HTTPS-only in every environment
+so behavior in dev matches production (`Secure` cookies, HSTS, mixed
+content, `wss://` upgrades, etc.).
+
+---

backend/app.js

@@ -27,6 +27,17 @@ app.set('trust proxy', TRUST_PROXY === true);
 app.use(cors(utils.getCorsOptions()));
 
 app.use(helmet.noSniff());
+// HTTP Strict Transport Security: instruct compliant browsers to only ever
+// reach this origin over HTTPS for the next 2 years, mitigating the
+// plaintext-HTTP fall-through that httpolyglot would otherwise allow on
+// the same port.
+app.use(
+    helmet.hsts({
+        maxAge: 63072000,
+        includeSubDomains: true,
+        preload: false,
+    })
+);
 app.use(express.urlencoded({ extended: true }));
 app.use(express.json());
 

backend/handlers/index.js

@@ -15,7 +15,9 @@ const { Logs, getIP } = require('../utils');
 const config = require('../config');
 const logger = new Logs('AdminSocket');
 
-const { ADMIN_DASHBOARD_ENABLED, ADMIN_ALLOWED_IPS } = config;
+const { ADMIN_DASHBOARD_ENABLED, ADMIN_ALLOWED_IPS, NODE_ENV } = config;
+
+const IS_PRODUCTION = NODE_ENV === 'production';
 
 /**
  * Socket.IO transport-level gate.
@@ -34,6 +36,19 @@ function socketAccessGate(socket, next) {
         logger.warn('Socket connection refused: dashboard disabled');
         return next(new Error('dashboard disabled'));
     }
+    // Reject plaintext ws:// upgrades in production. httpolyglot accepts
+    // both HTTP and HTTPS on the same port, so without this check an
+    // attacker on the wire could open an unauthenticated WebSocket in the
+    // clear and intercept the JWT used to upgrade it.
+    if (IS_PRODUCTION) {
+        const encrypted = Boolean(socket.request && socket.request.socket && socket.request.socket.encrypted);
+        const xfProto = socket.request && socket.request.headers && socket.request.headers['x-forwarded-proto'];
+        const viaTlsProxy = typeof xfProto === 'string' && xfProto.split(',')[0].trim().toLowerCase() === 'https';
+        if (!encrypted && !viaTlsProxy) {
+            logger.warn('Socket connection refused: plaintext transport');
+            return next(new Error('https required'));
+        }
+    }
     const allowed = Array.isArray(ADMIN_ALLOWED_IPS) ? ADMIN_ALLOWED_IPS : [];
     if (allowed.length > 0 && !allowed.includes('*')) {
         const ip = getIP(socket.request);

backend/middleware/dashboardGuard.js

@@ -14,10 +14,24 @@ const config = require('../config');
 const utils = require('../utils');
 const Logs = utils.Logs;
 const logger = new Logs('DashboardGuardMiddleware');
-const { ADMIN_DASHBOARD_ENABLED } = config;
+const { ADMIN_DASHBOARD_ENABLED, NODE_ENV } = config;
+
+const IS_PRODUCTION = NODE_ENV === 'production';
 
 /**
- * Middleware to check if the dashboard is enabled.
+ * Middleware to check if the dashboard is enabled and, in production, to
+ * enforce HTTPS. Because the server is started with httpolyglot (the same
+ * port accepts both plaintext HTTP and TLS), an on-path attacker could
+ * otherwise intercept the admin login and steal the JWT in cleartext.
+ *
+ * In production, any plaintext-HTTP request is rejected. GET/HEAD requests
+ * are 301-redirected to the equivalent https:// URL so an operator who
+ * typed http:// (or followed a bad link) still lands on the secure
+ * endpoint; all other methods are refused with 403 to avoid silently
+ * "fixing up" requests whose body has already been sent in cleartext.
+ *
+ * In non-production environments the check is a warning-only no-op so
+ * local development against the self-signed cert is not disrupted.
  *
  * @param {express.Request} req - Express request object
  * @param {express.Response} res - Express response object
@@ -28,6 +42,22 @@ const dashboardEnabledAndHttps = (req, res, next) => {
         logger.warn('Admin dashboard is disabled', { url: req.originalUrl });
         return res.status(503).json({ error: 'Admin dashboard is disabled' });
     }
+    // `req.secure` is true when the request arrived over TLS directly, or
+    // (when `trust proxy` is set) when a trusted upstream proxy set
+    // X-Forwarded-Proto=https. Both cases are acceptable.
+    if (!req.secure) {
+        if (IS_PRODUCTION) {
+            const host = req.headers.host;
+            const safeUrl = { url: req.originalUrl, ip: req.ip };
+            if ((req.method === 'GET' || req.method === 'HEAD') && host) {
+                logger.warn('Redirecting plaintext HTTP request to HTTPS', safeUrl);
+                return res.redirect(301, `https://${host}${req.originalUrl}`);
+            }
+            logger.warn('Rejecting plaintext HTTP request', { ...safeUrl, method: req.method });
+            return res.status(403).json({ error: 'HTTPS required' });
+        }
+        logger.warn('Plaintext HTTP request accepted (non-production)', { url: req.originalUrl });
+    }
     next();
 };
 

backend/server.js

@@ -11,6 +11,7 @@
 
 const path = require('path');
 const fs = require('fs');
+const https = require('https');
 const app = require('./app');
 const config = require('./config');
 const utils = require('./utils');
@@ -21,18 +22,38 @@ const logger = new Logs('AdminServer');
 
 const { ADMIN_PORT } = config;
 
-// Define paths to the SSL key and certificate files
-const keyPath = path.join(__dirname, 'ssl/key.pem');
-const certPath = path.join(__dirname, 'ssl/cert.pem');
+// Define paths to the SSL key and certificate files.
+// In non-production environments, prefer `backend/ssl/dev/` if present
+// (e.g. a locally-trusted cert issued via `mkcert`), so the browser does
+// not show a self-signed-cert warning during day-to-day development.
+// In production, always use the canonical `backend/ssl/` pair, which
+// should hold a CA-issued certificate (Let's Encrypt, internal PKI, …)
+// or be fronted by a TLS-terminating reverse proxy.
+const IS_PRODUCTION = config.NODE_ENV === 'production';
+const devKeyPath = path.join(__dirname, 'ssl/dev/key.pem');
+const devCertPath = path.join(__dirname, 'ssl/dev/cert.pem');
+const prodKeyPath = path.join(__dirname, 'ssl/key.pem');
+const prodCertPath = path.join(__dirname, 'ssl/cert.pem');
+
+const useDevCerts = !IS_PRODUCTION && fs.existsSync(devKeyPath) && fs.existsSync(devCertPath);
+const keyPath = useDevCerts ? devKeyPath : prodKeyPath;
+const certPath = useDevCerts ? devCertPath : prodCertPath;
+
+if (useDevCerts) {
+    logger.info('Using development SSL certificates from backend/ssl/dev/');
+}
 
 // Read SSL key and certificate files securely
 const options = {
     key: fs.readFileSync(keyPath, 'utf-8'),
     cert: fs.readFileSync(certPath, 'utf-8'),
 };
 
-// Serve both http and https and attach Socket.IO
-const server = require('httpolyglot').createServer(options, app);
+// HTTPS-only listener. Previously this used `httpolyglot`, which accepts
+// both HTTP and HTTPS on the same port and made the dashboard reachable
+// in cleartext (login + JWT). Using `https.createServer` makes plaintext
+// access structurally impossible on this port.
+const server = https.createServer(options, app);
 const { Server } = require('socket.io');
 const io = new Server(server, {
     cors: utils.getCorsOptions(),

package-lock.json

@@ -29,7 +29,6 @@
         "express": "^5.2.1",
         "express-rate-limit": "^8.5.2",
         "helmet": "^8.1.0",
-        "httpolyglot": "0.1.2",
         "jsonwebtoken": "^9.0.3",
         "node-pty": "^1.1.0",
         "nodemailer": "^8.0.7",