slower 1.1.11 → 1.1.13

package/lib/router.js

@@ -1,6 +1,6 @@
 const http = require('http');
 const fs = require('fs');
-const { noop, slugify, isSparseEqual, last, renderDynamicHTML, setSocketLocals } = require('./utils');
+const { clone, noop, slugify, isSparseEqual, last, renderDynamicHTML, setSocketLocals, setSocketSecurityHeaders } = require('./utils');
 
 class Route {
     constructor (path, type, callback) {
@@ -33,13 +33,28 @@ class SlowerRouter {
     }
 
     constructor () {
+        this.strictHeaders = false;
         this.routes = [];
         this.middleware = [noop];
         this.fallback = noop;
-        this.allowedMethods = [];
+        this.allowedMethods = clone(SlowerRouter.http_methods);
         this.blockedMethodCallback = noop;
     }
 
+    enableStrictHeaders () {
+        // This activates the responses with many security-related response headers.
+        //  It is not enabled by default, as some header are very restrictive
+        this.strictHeaders = true;
+        return this;
+    }
+
+    disableStrictHeaders () {
+        // This deactivates the responses with many security-related response headers.
+        //  It is not enabled by default, as some headers are very restrictive
+        this.strictHeaders = false;
+        return this;
+    }
+
     /**
      * Defines a route for a determined request method 
      * @category Router
@@ -57,7 +72,7 @@ class SlowerRouter {
     setRoute = function (path = '/', type = 'GET', callback) {
         let stat = new Route(path, type, callback);
         this.routes.push(stat);
-        return stat;
+        return this;
     }
 
     /**
@@ -67,13 +82,10 @@ class SlowerRouter {
      * @returns {Array} The used middlewares list
     */
     setMiddleware = function (callback) {
-        return this.middleware.push((typeof callback == 'function' ? callback : noop));
+        this.middleware.push((typeof callback == 'function' ? callback : noop));
+        return this;
     }
     
-    // SERVES FILES FOR SPECIFIC PATHS. WILDCARS ALLOWED. BE CAREFUL - PATH TRAVERSAL MAY BE POSSIBLE
-    // Use app.setStatic('/*', __dirname+'/') for serving all local files. 
-    // or use app.setStatic('/*', __dirname+'/public/') for serving files in a specific folder (public). 
-    // This is a one-liner for the setRoute function, when the route responds with a simple page or document
     /**
      * Defines a route for a determined request method 
      * @category Router
@@ -82,8 +94,6 @@ class SlowerRouter {
      * @param {String} mime The file's mime type
      * @param {Object} replacementData The replacement data map for the dynamic HTML rendering
      * @returns {Object} An Route object already configured
-     * @example <caption> Defining a simple GET route:</caption>
-     * setStatic('/login', __dirname+'/public/static/views/login.html', 'text/html', 'utf8');
     */
     /**
     * Dynamic rendering example:
@@ -102,7 +112,7 @@ class SlowerRouter {
         *   age: 29
         * }));
     */
-    setDynamic = function (path, file = '', mime = '', replacementData) {
+    setDynamic = function (path, file = '', mime = '', replacementData = null) {
         let encoding = (mime === SlowerRouter.mime_table['default'] ? undefined : 'utf-8')
         let stat = new Route(path, 'GET', (req, res) => {
             let data, targetFile, extension, targetMime, targetEncoding;
@@ -128,7 +138,7 @@ class SlowerRouter {
             res.end();
         });
         this.routes.push(stat);
-        return stat;
+        return this;
     }
     
     // SERVES FILES FOR SPECIFIC PATHS. WILDCARS ALLOWED. BE CAREFUL - PATH TRAVERSAL MAY BE POSSIBLE
@@ -141,10 +151,9 @@ class SlowerRouter {
      * @param {String} path The route that will be defined
      * @param {String} file The file path that will be used to respond to the route
      * @param {String} mime The file's mime type
-     * @param {String} encoding The file's encoding (defaults to UTF-8)
      * @returns {Object} An Route object already configured
      * @example <caption> Defining a simple GET route:</caption>
-     * setStatic('/login', __dirname+'/public/static/views/login.html', 'text/html', 'utf8');
+     * setStatic('/login', __dirname+'/public/static/views/login.html', 'text/html');
     */
     setStatic = function (path, file = '', mime = '') {
         let encoding = (mime === SlowerRouter.mime_table['default'] ? undefined : 'utf-8')
@@ -169,7 +178,7 @@ class SlowerRouter {
             res.end(); 
         });
         this.routes.push(stat);
-        return stat;
+        return this;
     }
 
     /**
@@ -177,10 +186,8 @@ class SlowerRouter {
      * @category Router
      * @param {String} callback The function to execute for unhandled routes
      * @returns {undefined}
-     * @example <caption> Defining a simple GET route:</caption>
-     * setStatic('/login', __dirname+'/public/static/views/login.html', 'text/html', 'utf8');
     */
-    setFallback = function (callback) { this.fallback = callback; }
+    setFallback = function (callback) { this.fallback = callback; return this; }
 
     // SERVES FILES FOR SPECIFIC PATHS. WILDCARS ALLOWED. BE CAREFUL - PATH TRAVERSAL MAY BE POSSIBLE
     // Use app.setStatic('/*', __dirname+'/') for serving all local files. 
@@ -214,7 +221,7 @@ class SlowerRouter {
         *   age: 29
         * }));
     */
-    setFallbackFile = function (file = '', mime = '', replacementData) {
+    setFallbackFile = function (file = '', mime = '', replacementData = null) {
         this.fallback = function fb (req,res) {
             let encoding = (mime === SlowerRouter.mime_table['default'] ? undefined : 'utf-8')
             let data, targetFile, extension, targetMime, targetEncoding;
@@ -239,6 +246,7 @@ class SlowerRouter {
             res.write(data);
             res.end();
         }
+        return this;
     }
 
     // Sets the methods that the application will respond to. The rest is simply discarded with empty responses.
@@ -267,7 +275,7 @@ class SlowerRouter {
             res.writeHead(405); // sends the meme error 418 'i am a teapot'
             res.end();
         };
-        return this.allowedMethods;
+        return this;
     }
 
     // Starts the server - listening at <host>:<port>
@@ -275,10 +283,8 @@ class SlowerRouter {
      * @category Router
      * @param {Number} port The port number the server will listen to.
      * @param {String} host The host's network interface address the server will listen into (use a falsy value or '0.0.0.0' for listening on all).
-     * @param {Function} methods The methods that are allowed by the application. Methods that do not conform with standards are ignored.
-     * @returns {Object} The AllowedMethods Array object.
-     * @example <caption> Allowing only GET and POST:</caption>
-     * app.setAllowedMethods(['GET', 'POST']);
+     * @param {Function} callback The function to execute after starting the server.
+     * @returns {Object<http.Server>} The server instance 
     */
     start = function (port = 8080, host = undefined, callback = () => {}) {
         let routes = this.routes;
@@ -291,6 +297,10 @@ class SlowerRouter {
             try {
                 // Sets local req.session object
                 setSocketLocals(req);
+                // Sets security headers in req.headers
+                // This is set before custom callbacks are applies
+                // so it is possible to override all of the headers
+                if (!!this.strictHeaders) setSocketSecurityHeaders(req); 
                 // Runs all middlewares
                 for (let i = 0; i < middle.length; i++) { middle[i](req, res); }
                 // Only respond to allowed methods with callbacks, else, use the default empty response.
@@ -320,7 +330,8 @@ class SlowerRouter {
         });
         callback(server);
         if (!host) host = undefined; // Turn falsy values into undefined, for default behaviour
-        return server.listen(port, host);
+        // return server.listen(port, host);
+        return this;
     }
 }
 

package/lib/utils.js

@@ -86,6 +86,61 @@ const setSocketLocals = (socket) => {
     return socket;
 }
 
+const setSocketSecurityHeaders = (req) => {
+    // This should be set in a regular website:
+    // Forces the use of HTTPS for a long time, including subDomains - and prevent MitM attacks
+    // Does not work in servers that don't allow HTTPS (like this one)
+    // req.setHeader('Strict-Transport-Security', ['max-age=31536000', 'includeSubDomains']); // Only works on HTTPS
+
+    // This blocks requests with MIME type different from style/css and */script
+    // TODO test this - probably gonna break the server, as MIMEs are not overriden here
+    // req.setHeader('X-Content-Type-Options', 'nosniff'); 
+
+    // This deines the main security policy - Usually, when using a website, 
+    // this should be highly customized, but, for simple sites, it can be leaved like that:
+    req.setHeader('Content-Security-Policy', [
+        'default-src=none',
+        'script-src=self',
+        'connect-src=self',
+        'img-src=self',
+        'style-src=self',
+        'frame-ancestors=none',
+        'form-action=self',
+        // 'upgrade-insecure-requests' // Only works on HTTPS
+    ]);
+    // Isolates the browsing context exclusively to same-origin documents. 
+    // Cross-origin documents are not loaded in the same browsing context.
+    req.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+    // The HTTP Cross-Origin-Resource-Policy response header conveys a desire 
+    // that the browser blocks no-cors cross-origin/cross-site requests to the given resource.
+    req.setHeader('Cross-Origin-Resource-Policy', 'same-site');
+    // A new HTTP response header that instructs the browser 
+    // to prevent synchronous scripting access between same-site cross-origin pages.
+    req.setHeader('Origin-Agent-Cluster', '?1');
+    // Blocks information about the website when sending 
+    // local requests or redirections to other sites
+    req.setHeader('Referrer-Policy', 'no-referrer');
+    // Enabling this makes all URLs in a page (even the cross domain ones)
+    // to be prefetched - This is dangerouns in terms of DNS queries
+    req.setHeader('X-DNS-Prefetch-Control', 'off');
+    // A legacy header, just for IE, and is highly dangerous
+    // Not setting this as disabled can cause malicious 
+    // HTML+JS code to be loaded in the wrong context
+    req.setHeader('X-Download-Options', 'noopen');
+    // Blocks attempts to display the website as an IFrame
+    // If another website tries to display this website as a frame,
+    // this header will block it
+    req.setHeader('X-Frame-Options', 'DENY');
+    // Set the unnecessary XSS-Protection legacy header to disabled
+    // This header increases the number of vulnerabilities, and is used only in IE
+    req.setHeader('X-XSS-Protection', 0);
+    // Remove X-Powered-By - This header allows attackers to 
+    // gather information about the application engine
+    if (req.hasHeader('X-Powered-By')) req.removeHeader('X-Powered-By');
+}
+
 const toBool = [() => true, () => false];
 
-module.exports = { noop, slugify, isSparseEqual, toBool, last, renderDynamicHTML, setSocketLocals };
+const clone = (object) => JSON.parse(JSON.stringify(object));
+
+module.exports = { clone, noop, slugify, isSparseEqual, toBool, last, renderDynamicHTML, setSocketLocals, setSocketSecurityHeaders };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slower",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "description": "A package for simple HTTP server routing.",
   "main": "index.js",
   "directories": {

package/readme.md

@@ -3,6 +3,106 @@
 Slower is a small web framework, express-like, but simpler and limited.
 It allows for generic route-declaration, fallback pages, and multiple middleware functions.
 
+### API Methods:
+
+```
+app.enableStrictHeaders(): this
+
+> Enables the use of the set of 'Strict Headers'.
+> These headers increase security levels, and are a good practice to apply.
+> However, using these headers in testing scenarios are not a need, 
+  and may have buggy or negative effects. So, apply those to simulate scenarios only.
+> Headers configured:
+    > Content-Security-Policy
+    > Cross-Origin-Opener-Policy
+    > Cross-Origin-Resource-Policy 
+    > Origin-Agent-Cluster
+    > Referrer-Policy 
+    > X-DNS-Prefetch-Control (disabled)
+    > X-Download-Options
+    > X-Frame-Options
+    > X-XSS-Protection (disabled)
+    > X-Powered-By (removed)
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.disableStrictHeaders(): this
+
+> Disables the use of the set of 'Strict Headers'.
+> See 'enableStrictHeaders()' for more information.
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setRoute(string: path = '/', string: type = 'GET', function: callback): this
+
+> Creates a new route for path defined in 'path', responding to the HTTP verb defined in 'type' argument.
+> The callback is executed when the route is accessed.
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setMiddleware(function: callback): this
+
+> Sets a new middleware function: callback function will be accessed for every server access.
+> Many middlewares can be defined, and will be applied in the order they are defined.
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setDynamic(string: path, string: file = '', string: mime = '', object: replacementData = null): this
+
+> Creates a new GET route for path defined in 'path'. 
+> This is a custom file-response route, configured for template rendering just before response.
+> Providing an object as 'replacementData' in this format { valueToBeReplaced: valueToReplace },
+  allows for template rendering. The value to replace in the file, uses this notation: '<{content}>'.
+> Example:
+  Responding a route for '/custom' with file 'custom.html':
+    app.setDynamic('/custom', './templates/custom.html', 'text/html', { smile: ':)' })
+  In file './templates/custom.html':
+    "<h2> This is a custom thing:        <{smile}>      </h2>"
+  Rendered in browser:
+    <h2> This is a custom thing:        :)      </h2>
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setStatic(string: path, string: file = '', string: mime = ''): this
+
+> Creates a new GET route for path defined in 'path', responding with the specified file and MIME type.
+> Example: A route for '/login' page, responding with 'login.html' file
+    setStatic('/login', __dirname+'/public/static/views/login.html', 'text/html');
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setFallback(function: callback): this
+
+> Creates a function for fallback state. When no other routes intercept the route, this will be used.
+> Special use for 'page not found' fallback pages or highly customized routes and situations.
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setFallbackFile (string: file = '', string: mime = '', object: replacementData = null): this
+
+> Creates a function for fallback state. When no other routes intercept the route, this will be used.
+> Equivalent to setFallback, but responds with a file. Allows for template rendering.
+> See 'setDynamic' for more information about template rendering.
+> Special use for 'page not found' fallback pages, ex: './e404.html'.
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setAllowedMethods(array: methods = []): this
+
+> Sets a list of methods to respond to.
+> By using this, it is possible to restrict the application to avoid
+  responding to dangerous HTTP verbs, such as 'DELETE'.
+> By default, all methods are allowed (see Slower.constructor.http_methods)
+> Calling this function without parameters is an easy way to block responses to all requests (lock server). 
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.start(number|string: port = 8080, string: host = undefined, function: callback = ()=>{}): this
+
+> Starts the server, at a specific host and port, then calling the callback function.
+> Not defining a specific port or host will start the server at '0.0.0.0:8080'.
+> Returns the own object instance, so that methods can be chained.
+```
 
 Example usage:
 ```
@@ -46,6 +146,7 @@ app.start(port, null, () => {
     console.log(`Running on localhost:${port}`);
     console.log(app);
 });
+
 ```
 ### API modifications on 'net.Socket' instances:
  - The API modifies every ```net.Socket``` instance BEFORE it is passed 
@@ -63,4 +164,26 @@ a socket will receive the modified socket instead.
 during the lifetime of a single connection. Useful for keeping short-life local variables.
 
 - In HTTP ```http.IncomingMessage``` instances, the 'socket' instance is found over 'request'.
-So, considering the common callback of ```(req, res)```, the session container will be ```req.session```
+So, considering the common callback of ```(req, res)```, the session container will be ```req.session```
+
+### API security headers implementation:
+ - It is possible to enforce a higher set of security headers on responses 
+   without having to set them manually. The API 'enableStrictHeaders' and 'disableStrictHeaders' 
+   methods do exacly that. The strict headers are disabled by default, as some resources are too strict, 
+   but it is also possible to enable them all, and then set a middleware to override any header.
+ - Headers set by 'enableStrictHeaders':
+```
+    Content-Security-Policy: default-src=none; script-src=self; connect-src=self; img-src=self;
+        style-src=self; frame-ancestors=none; form-action=self;
+    Cross-Origin-Opener-Policy:  same-origin
+    Cross-Origin-Resource-Policy: same-site
+    Origin-Agent-Cluster: ?1
+    Referrer-Policy: no-referrer
+    Strict-Transport-Security: max-age=31536000; includeSubDomains // temporarily disabled for maintenance
+    X-Content-Type-Options: nosniff // temporarily disabled for maintenance
+    X-DNS-Prefetch-Control: off
+    X-Download-Options: noopen
+    X-Frame-Options: DENY
+    X-Powered-By: (This header is removed if a response includes it)
+    X-XSS-Protection: 0 
+```