mastercontroller 1.2.4 → 1.2.5

package/MasterControl.js

@@ -1,10 +1,11 @@
 // MasterControl - by Alexander rich
-// version 1.0.245
+// version 1.0.246
 
 var url = require('url');
 var fileserver = require('fs');
 var http = require('http');
 var https = require('https');
+var tls = require('tls');
 var fs = require('fs');
 var url = require('url');
 var path = require('path');
@@ -20,6 +21,8 @@ class MasterControl {
     _serverProtocol = null
     _scopedList = []
     _loadedFunc = null
+    _tlsOptions = null
+    _hstsEnabled = false
 
     #loadTransientListClasses(name, params){
         Object.defineProperty(this.requestList, name, {
@@ -169,11 +172,12 @@ class MasterControl {
 
         if(settings.httpPort || settings.requestTimeout){
             this.server.timeout = settings.requestTimeout;
-            if(settings.http){
-                this.server.listen(settings.httpPort, settings.http);   
+            var host = settings.hostname || settings.host || settings.http;
+            if(host){
+                this.server.listen(settings.httpPort, host);
             }else{
-                this.server.listen(settings.httpPort);   
-            }       
+                this.server.listen(settings.httpPort);
+            }
         }
         else{
             throw "HTTP, HTTPS, HTTPPORT and REQUEST TIMEOUT MISSING";
@@ -201,7 +205,16 @@ class MasterControl {
             }
             if(type === "https"){
                 $that.serverProtocol = "https";
+                // Initialize TLS from env if no credentials passed
+                if(!credentials){
+                    $that._initializeTlsFromEnv();
+                    credentials = $that._tlsOptions;
+                }
+                // Apply secure defaults if missing
                 if(credentials){
+                    if(!credentials.minVersion){ credentials.minVersion = 'TLSv1.2'; }
+                    if(credentials.honorCipherOrder === undefined){ credentials.honorCipherOrder = true; }
+                    if(!credentials.ALPNProtocols){ credentials.ALPNProtocols = ['h2', 'http/1.1']; }
                     return https.createServer(credentials, async function(req, res) {
                         $that.serverRun(req, res);
                     });
@@ -216,6 +229,130 @@ class MasterControl {
         }
     }
 
+    // Creates an HTTP server that 301-redirects to HTTPS counterpart
+    startHttpToHttpsRedirect(redirectPort, bindHost){
+        var $that = this;
+        return http.createServer(function (req, res) {
+            try{
+                var host = req.headers['host'] || '';
+                // Force original host, just change scheme
+                var location = 'https://' + host + req.url;
+                res.statusCode = 301;
+                res.setHeader('Location', location);
+                res.end();
+            }catch(e){
+                res.statusCode = 500;
+                res.end();
+            }
+        }).listen(redirectPort, bindHost);
+    }
+
+    // Load TLS configuration from env and build SNI contexts with live reload
+    _initializeTlsFromEnv(){
+        try{
+            var cfg = this.env;
+            if(!cfg || !cfg.server || !cfg.server.tls){
+                return;
+            }
+            var tlsCfg = cfg.server.tls;
+
+            var defaultCreds = this._buildSecureContextFromPaths(tlsCfg.default);
+            var defaultContext = defaultCreds ? tls.createSecureContext(defaultCreds) : null;
+
+            var sniMap = {};
+            if(tlsCfg.sni && typeof tlsCfg.sni === 'object'){
+                for (var domain in tlsCfg.sni){
+                    if (Object.prototype.hasOwnProperty.call(tlsCfg.sni, domain)){
+                        var domCreds = this._buildSecureContextFromPaths(tlsCfg.sni[domain]);
+                        if(domCreds){
+                            sniMap[domain] = tls.createSecureContext(domCreds);
+                            // watch domain certs for reload
+                            this._watchTlsFilesAndReload(tlsCfg.sni[domain], function(){
+                                try{
+                                    var updated = tls.createSecureContext(
+                                        this._buildSecureContextFromPaths(tlsCfg.sni[domain])
+                                    );
+                                    sniMap[domain] = updated;
+                                }catch(e){
+                                    console.error('Failed to reload TLS context for domain', domain, e);
+                                }
+                            }.bind(this));
+                        }
+                    }
+                }
+            }
+
+            var options = defaultCreds ? Object.assign({}, defaultCreds) : {};
+            options.SNICallback = function(servername, cb){
+                var ctx = sniMap[servername];
+                if(!ctx && defaultContext){ ctx = defaultContext; }
+                if(cb){ return cb(null, ctx); }
+                return ctx;
+            };
+
+            // Apply top-level TLS defaults/hardening from env if provided
+            if(tlsCfg.minVersion){ options.minVersion = tlsCfg.minVersion; }
+            if(tlsCfg.honorCipherOrder !== undefined){ options.honorCipherOrder = tlsCfg.honorCipherOrder; }
+            if(tlsCfg.ciphers){ options.ciphers = tlsCfg.ciphers; }
+            if(tlsCfg.alpnProtocols){ options.ALPNProtocols = tlsCfg.alpnProtocols; }
+
+            // HSTS
+            this._hstsEnabled = !!tlsCfg.hsts;
+            this._hstsMaxAge = tlsCfg.hstsMaxAge || 15552000; // 180 days by default
+
+            // Watch default certs for reload
+            if(tlsCfg.default){
+                this._watchTlsFilesAndReload(tlsCfg.default, function(){
+                    try{
+                        var updatedCreds = this._buildSecureContextFromPaths(tlsCfg.default);
+                        defaultContext = tls.createSecureContext(updatedCreds);
+                        // keep key/cert on options for non-SNI connections
+                        Object.assign(options, updatedCreds);
+                    }catch(e){
+                        console.error('Failed to reload default TLS context', e);
+                    }
+                }.bind(this));
+            }
+
+            this._tlsOptions = options;
+        }catch(e){
+            console.error('Failed to initialize TLS from env', e);
+        }
+    }
+
+    _buildSecureContextFromPaths(desc){
+        if(!desc){ return null; }
+        var opts = {};
+        try{
+            if(desc.keyPath){ opts.key = fs.readFileSync(desc.keyPath); }
+            if(desc.certPath){ opts.cert = fs.readFileSync(desc.certPath); }
+            if(desc.caPath){ opts.ca = fs.readFileSync(desc.caPath); }
+            if(desc.pfxPath){ opts.pfx = fs.readFileSync(desc.pfxPath); }
+            if(desc.passphrase){ opts.passphrase = desc.passphrase; }
+            return opts;
+        }catch(e){
+            console.error('Failed to read TLS files', e);
+            return null;
+        }
+    }
+
+    _watchTlsFilesAndReload(desc, onChange){
+        var paths = [];
+        if(desc.keyPath){ paths.push(desc.keyPath); }
+        if(desc.certPath){ paths.push(desc.certPath); }
+        if(desc.caPath){ paths.push(desc.caPath); }
+        if(desc.pfxPath){ paths.push(desc.pfxPath); }
+        paths.forEach(function(p){
+            try{
+                fs.watchFile(p, { interval: 5000 }, function(){
+                    onChange();
+                });
+            }catch(e){
+                console.error('Failed to watch TLS file', p, e);
+            }
+        });
+    }
+
     async serverRun(req, res){
         var $that = this;
         console.log("path", `${req.method} ${req.url}`);
@@ -271,6 +408,10 @@ class MasterControl {
         if(ext === ""){
           var requestObject = await this.middleware(req, res);
           if(requestObject !== -1){
+            // HSTS header if enabled
+            if(this.serverProtocol === 'https' && this._hstsEnabled){
+                res.setHeader('strict-transport-security', `max-age=${this._hstsMaxAge}; includeSubDomains`);
+            }
             var loadedDone = false;
             if (typeof $that._loadedFunc === 'function') {
                loadedDone = $that._loadedFunc(requestObject);

package/README.md

@@ -0,0 +1,58 @@
+## MasterController Framework
+
+MasterController is a lightweight MVC-style server framework for Node.js with routing, controllers, views, dependency injection, CORS, sessions, sockets, and more.
+
+### Install
+```
+npm install mastercontroller
+```
+
+### Quickstart
+```js
+// server.js
+const master = require('./MasterControl');
+
+master.root = __dirname;                    // your project root
+master.environmentType = 'development';     // or process.env.NODE_ENV
+
+const server = master.setupServer('http');  // or 'https'
+master.start(server);
+master.serverSettings({ httpPort: 3000, hostname: '127.0.0.1', requestTimeout: 60000 });
+
+// Or load from config/environments/env.<env>.json
+// master.serverSettings(master.env.server);
+
+// Load your routes
+master.startMVC('app');
+```
+
+### Routes
+Create `app/config/routes.js` and define routes with `master.router.start()` API.
+
+### Controllers
+Place controllers under `app/controllers/*.js` and export methods matching your routes.
+
+### Views and Templates
+Views live under `app/views/<controller>/<action>.html` with a layout at `app/views/layouts/master.html`.
+
+### CORS and Preflight
+`MasterCors` configures CORS headers. Preflight `OPTIONS` requests are short-circuited with 204.
+
+### HTTPS
+Use `setupServer('https', credentials)` or configure via environment TLS; see docs in `docs/` for multiple setups.
+
+### Docs
+- `docs/server-setup-http.md`
+- `docs/server-setup-https-credentials.md`
+- `docs/server-setup-https-env-tls-sni.md`
+- `docs/server-setup-hostname-binding.md`
+- `docs/server-setup-nginx-reverse-proxy.md`
+- `docs/environment-tls-reference.md`
+
+### Production tips
+- Prefer a reverse proxy for TLS and serve Node on a high port.
+- If keeping TLS in Node, harden TLS and manage cert rotation.
+
+### License
+ISC
+

package/docs/environment-tls-reference.md

@@ -0,0 +1,60 @@
+## Environment TLS/SNI reference
+
+Place environment files at `config/environments/env.<environment>.json`.
+
+### server section
+```json
+{
+  "server": {
+    "httpPort": 3000,
+    "hostname": "127.0.0.1",
+    "requestTimeout": 60000,
+    "tls": { /* optional, for HTTPS when using setupServer('https') without credentials */ }
+  }
+}
+```
+
+### tls section
+```json
+"tls": {
+  "hsts": true,                 // add HSTS header on HTTPS responses
+  "hstsMaxAge": 15552000,       // HSTS max-age in seconds (default 180 days)
+  "minVersion": "TLSv1.2",     // minimum TLS version ('TLSv1.2' or 'TLSv1.3')
+  "honorCipherOrder": true,     // prefer server cipher order
+  "alpnProtocols": ["h2", "http/1.1"], // enable HTTP/2 and HTTP/1.1
+  "default": {                  // fallback certificate if SNI host doesn't match
+    "keyPath": "/path/to/key.pem",
+    "certPath": "/path/to/cert.pem",
+    "caPath": "/path/to/chain.pem",
+    "pfxPath": null,            // optional if using PFX
+    "passphrase": null          // optional if key is encrypted
+  },
+  "sni": {                      // per-domain certificates
+    "example.com": {
+      "keyPath": "/path/to/example.key",
+      "certPath": "/path/to/example.crt",
+      "caPath": "/path/to/chain.pem"
+    },
+    "api.example.com": {
+      "keyPath": "/path/to/api.key",
+      "certPath": "/path/to/api.crt",
+      "caPath": "/path/to/chain.pem"
+    }
+  }
+}
+```
+
+### Terminology
+- tls: Transport Layer Security. Encrypts traffic between client and server.
+- SNI: Server Name Indication. Lets the server present different certificates based on the requested hostname during TLS handshake.
+- default: The certificate used when no SNI match is found.
+
+### Behavior
+- If you call `setupServer('https')` without credentials, MasterControl reads `server.tls` and builds secure contexts (default + SNI) and watches the key/cert files for changes. Updates apply in-memory without restart.
+- If you pass credentials directly to `setupServer('https', credentials)`, those are used instead and env `tls` is ignored.
+
+### Tips
+- Keep private keys readable only by the process user.
+- Prefer `TLSv1.2`+ and enable HTTP/2 via ALPN.
+- If binding to 443 without a proxy, consider using a high port (8443) or grant `CAP_NET_BIND_SERVICE` to avoid running as root.
+

package/docs/server-setup-hostname-binding.md

@@ -0,0 +1,24 @@
+## Server setup: Hostname binding
+
+Bind the listener to a specific interface using `hostname` (or `host`/`http`).
+
+### server.js
+```js
+const master = require('./MasterControl');
+
+master.root = __dirname;
+master.environmentType = process.env.NODE_ENV || 'development';
+
+const server = master.setupServer('http');
+master.start(server);
+
+// Bind to localhost only
+master.serverSettings({ httpPort: 3000, hostname: '127.0.0.1', requestTimeout: 60000 });
+
+master.startMVC('app');
+```
+
+### Notes
+- Use `0.0.0.0` to accept connections on all interfaces.
+- In production with a reverse proxy, bind to `127.0.0.1` so only the proxy can reach the app.
+

package/docs/server-setup-http.md

@@ -0,0 +1,32 @@
+## Server setup: HTTP
+
+This example starts a plain HTTP server. Useful for local development, or when you run behind a reverse proxy that terminates TLS.
+
+### server.js (HTTP)
+```js
+const master = require('./MasterControl');
+
+// Point master to your project root and environment
+master.root = __dirname;
+master.environmentType = process.env.NODE_ENV || 'development';
+
+// Create HTTP server and bind it
+const server = master.setupServer('http');
+master.start(server);
+
+// Use either explicit settings or your environment JSON
+// Option A: explicit
+// master.serverSettings({ httpPort: 3000, hostname: '127.0.0.1', requestTimeout: 60000 });
+
+// Option B: from env config at config/environments/env.<env>.json
+master.serverSettings(master.env.server);
+
+// Load your routes and controllers
+// If your routes are under <root>/app/**/routes.js
+master.startMVC('app');
+```
+
+### Notes
+- `master.serverSettings` now honors `hostname` (or `host`/`http`) if provided; otherwise it listens on all interfaces.
+- For production, prefer running behind a reverse proxy and keep the app on a high port (e.g., 3000).
+

package/docs/server-setup-https-credentials.md

@@ -0,0 +1,32 @@
+## Server setup: HTTPS with direct credentials
+
+Pass key/cert (and optional chain/ca) directly to `setupServer('https', credentials)`.
+
+### server.js (HTTPS credentials)
+```js
+const fs = require('fs');
+const master = require('./MasterControl');
+
+master.root = __dirname;
+master.environmentType = process.env.NODE_ENV || 'production';
+
+const credentials = {
+  key: fs.readFileSync('/etc/ssl/private/site.key'),
+  cert: fs.readFileSync('/etc/ssl/certs/site.crt'),
+  ca: fs.readFileSync('/etc/ssl/certs/chain.pem'),
+  minVersion: 'TLSv1.2',
+  honorCipherOrder: true,
+  ALPNProtocols: ['h2', 'http/1.1']
+};
+
+const server = master.setupServer('https', credentials);
+master.start(server);
+master.serverSettings({ httpPort: 8443, hostname: '0.0.0.0', requestTimeout: 60000 });
+master.startMVC('app');
+```
+
+### Notes
+- Use a high port (e.g., 8443) to avoid running as root, or grant `CAP_NET_BIND_SERVICE` if binding to 443.
+- Strong defaults are ensured if you omit them, but explicitly setting them is recommended.
+- For multiple domains, see the TLS/SNI guide.
+

package/docs/server-setup-https-env-tls-sni.md

@@ -0,0 +1,62 @@
+## Server setup: HTTPS via environment TLS (with SNI and live reload)
+
+This uses `config/environments/env.<env>.json` to configure TLS, SNI (multi-domain), HSTS, and watches cert files for live reload.
+
+### Example env.production.json
+```json
+{
+  "server": {
+    "httpPort": 8443,
+    "hostname": "0.0.0.0",
+    "requestTimeout": 60000,
+    "tls": {
+      "hsts": true,
+      "hstsMaxAge": 15552000,
+      "minVersion": "TLSv1.2",
+      "honorCipherOrder": true,
+      "alpnProtocols": ["h2", "http/1.1"],
+      "default": {
+        "keyPath": "/etc/ssl/private/site.key",
+        "certPath": "/etc/ssl/certs/site.crt",
+        "caPath": "/etc/ssl/certs/chain.pem"
+      },
+      "sni": {
+        "example.com": {
+          "keyPath": "/etc/ssl/private/example.key",
+          "certPath": "/etc/ssl/certs/example.crt",
+          "caPath": "/etc/ssl/certs/chain.pem"
+        },
+        "api.example.com": {
+          "keyPath": "/etc/ssl/private/api.key",
+          "certPath": "/etc/ssl/certs/api.crt",
+          "caPath": "/etc/ssl/certs/chain.pem"
+        }
+      }
+    }
+  }
+}
+```
+
+### server.js (HTTPS from env)
+```js
+const master = require('./MasterControl');
+
+master.root = __dirname;
+master.environmentType = process.env.NODE_ENV || 'production';
+
+// No credentials passed; MasterControl will auto-load TLS from env
+const server = master.setupServer('https');
+master.start(server);
+master.serverSettings(master.env.server);
+master.startMVC('app');
+
+// Optional: HTTP->HTTPS redirect (listen on 80)
+// master.startHttpToHttpsRedirect(80, '0.0.0.0');
+```
+
+### How it works
+- `default`: certs used when SNI domain does not match any entry.
+- `sni`: per-domain certificates; the server chooses the right cert via `SNICallback`.
+- Live reload: when any `keyPath`/`certPath`/`caPath` changes, the secure context is rebuilt in-memory (no restart needed).
+- HSTS: when enabled, responses over HTTPS include `strict-transport-security` with the configured max-age.
+

package/docs/server-setup-nginx-reverse-proxy.md

@@ -0,0 +1,46 @@
+## Server setup: Nginx reverse proxy with HTTP→HTTPS redirect
+
+Recommended production pattern: Node app on a high port (HTTP), Nginx on 80/443 handling TLS and redirects.
+
+### server.js (app on HTTP localhost:3000)
+```js
+const master = require('./MasterControl');
+
+master.root = __dirname;
+master.environmentType = process.env.NODE_ENV || 'production';
+
+const server = master.setupServer('http');
+master.start(server);
+master.serverSettings({ httpPort: 3000, hostname: '127.0.0.1', requestTimeout: 60000 });
+master.startMVC('app');
+```
+
+### Nginx config
+```nginx
+server {
+  listen 80;
+  server_name yourdomain.com;
+  return 301 https://$host$request_uri;
+}
+
+server {
+  listen 443 ssl http2;
+  server_name yourdomain.com;
+
+  ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
+  ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
+
+  location / {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+}
+```
+
+### Notes
+- Use certbot or another ACME client to manage certificates and renewals automatically.
+- This keeps Node unprivileged (no need to bind to 443) and simplifies TLS.
+

package/package.json

@@ -18,5 +18,5 @@
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "version": "1.2.4"
+  "version": "1.2.5"
 }