pixl-server-web 3.0.3 → 3.0.4

package/README.md

@@ -66,6 +66,7 @@ This module is a component for use in [pixl-server](https://www.github.com/jhuck
 	* [debug_ttl](#debug_ttl)
 	* [debug_bind_local](#debug_bind_local)
 	* [chaos](#chaos)
+	* [auth](#auth)
 	* [https](#https)
 	* [https_port](#https_port)
 	* [https_alt_ports](#https_alt_ports)
@@ -863,6 +864,26 @@ Use the `chaos` feature to introduce optional and random fault injection into yo
 
 Set the `chaos.enabled` flag to `true` to enable fault injection.  By default, all URIs will be affected, unless you specify a `chaos.uri` (regular expression) to limit the requests.  Set `chaos.delay.min` and `chaos.delay.max` to the range you want to delay requests (in milliseconds).  Fill the `chaos.errors` object the HTTP repsonse codes (and status messages) you want to see, and how often.  The values are interpreted as probabilities from `0.0` (never) to `1.0` (always).  In the above example, the `HTTP 503` error code will be injected approximately 10% of the time.  When errors are injected, you can include additional response headers in the `chaos.headers` object.
 
+## auth
+
+Use the `auth` feature to protect URI patterns behind HTTP authentication challenges.  Each key in the `auth` object should be a URI regular expression, and each value should be an auth definition.  Here is an example:
+
+```json
+"auth": {
+	"^/protected": {
+		"enabled": true,
+		"type": "basic",
+		"realm": "Secret Area",
+		"username": "foo",
+		"password": "bar"
+	}
+}
+```
+
+Set `auth.URI.enabled` to `true` to enable auth for that URI pattern.  Set `auth.URI.type` to `basic` to enable HTTP Basic Auth.  Currently, `basic` is the only supported authentication scheme.  The server will challenge unauthorized clients with the configured `auth.URI.realm`, and then compare `auth.URI.username` and `auth.URI.password` against the credentials provided by the client.
+
+The URI match key (e.g. `^/protected`) is treated as a regular expression and is evaluated as a request URI filter.  If credentials are missing or invalid, the request is rejected with `HTTP 401 Unauthorized`.
+
 ## https
 
 This boolean allows you to enable HTTPS (SSL) support in the web server.  It defaults to `false`.  Note that you must also set `https_port`, and possibly `https_cert_file` and `https_key_file` for this to work.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pixl-server-web",
-	"version": "3.0.3",
+	"version": "3.0.4",
 	"description": "A web server component for the pixl-server framework.",
 	"author": "Joseph Huckaby <jhuckaby@gmail.com>",
 	"homepage": "https://github.com/jhuckaby/pixl-server-web",

package/prompt.md

@@ -0,0 +1,40 @@
+Hello there, friend!  Welcome to my Node.js web server, called pixl-server-web, which is a full-featured web server for Node.js.
+
+This is the full source code, and the library is code complete.  I would like some help with all kinds of things, but my focus is the documentation at this stage.  Please feel free to get a feel for the place first.  Look into all the directories, read all the files, and learn all that you can.  In particular:
+
+- The app is Node.js with vanilla JavaScript.
+- There is NO TypeScript, and NO React.
+- All of the documentation in `README.md` is complete.  Feel free to read it.
+- This local sandbox has a full `node_modules/` folder with all dependencies installed, for local development.  Be careful about eating up your context window by digging into this directory.  The `package.json` file should tell you all you need to know about deps, but in some cases I may ask you to dive into a specific dependency.
+- Do not make a git branch or PR -- just edit the documentation files directly.
+- Please write all docs using GitHub Flavored Markdown.
+- Please do not use Emoji in the documentation -- especially not in headers / links.
+- No em dashes please.
+
+Let's work on the `README.md` file today.  This is the only file you should edit.
+
+I've just added a new feature to the web server where users can protect certain URIs behind HTTP Basic Auth.  Please perform a local dit diff to see my changes, as they are uncommitted.  If you have trouble doing a git diff, the changes are isolated to the `web_server.js` file.  See the `setupAuth()` function.
+
+Can you please add documentation for this new feature?  I think it should go just below the "chaos" section, and above the https section.
+
+Please read the existing docs so you can mimic the same format and style.
+
+Example use in the config:
+
+```json
+"auth": {
+	"^/protected": {
+		"enabled": true,
+		"type": "basic",
+		"realm": "Secret Area",
+		"username": "foo",
+		"password": "bar"
+	}
+},
+```
+
+Make sense?
+
+If you are confused about anything, please feel free to pause the conversation and ask me.  I'm here to help, and we can colaborate on these changes.
+
+Any questions for me before we begin?

package/test/test.js

@@ -68,6 +68,15 @@ var server = new PixlServer({
 					"status": "301 Moved Permanently"
 				}
 			},
+			"auth": {
+				"^/protected": {
+					"enabled": true,
+					"type": "basic",
+					"realm": "Secret Area",
+					"username": "foo",
+					"password": "bar"
+				}
+			},
 			
 			"https": 1,
 			"https_port": 3021,
@@ -163,6 +172,14 @@ module.exports = {
 					callback( server.WebServer.getStats() );
 				} );
 				
+				web_server.addURIHandler( '/protected', 'Protected Test', function(args, callback) {
+					// auth protected endpoint
+					callback( {
+						code: 0,
+						description: "Protected endpoint success"
+					} );
+				} );
+				
 				web_server.addURIHandler( '/binary-force-compress', 'Force Compress Test', function(args, callback) {
 					// send custom compressed response
 					callback( 
@@ -1666,6 +1683,59 @@ module.exports = {
 			);
 		},
 		
+		function testAuthRequired(test) {
+			// no auth header should be challenged
+			request.get( 'http://127.0.0.1:3020/protected',
+				function(err, resp, data, perf) {
+					test.ok( !err, "No error from PixlRequest: " + err );
+					test.ok( !!resp, "Got resp from PixlRequest" );
+					test.ok( resp.statusCode == 401, "Got 401 response: " + resp.statusCode );
+					test.ok( !!resp.headers['www-authenticate'], "Got WWW-Authenticate header" );
+					test.ok( !!resp.headers['www-authenticate'].match(/Basic realm="Secret Area"/), "Correct WWW-Authenticate header: " + resp.headers['www-authenticate'] );
+					test.ok( data.toString() == "Unauthorized", "Correct response body: " + data.toString() );
+					test.done();
+				}
+			);
+		},
+		
+		function testAuthBadCredentials(test) {
+			// invalid basic auth should fail
+			request.get( 'http://127.0.0.1:3020/protected',
+				{
+					headers: {
+						"Authorization": "Basic " + Buffer.from("foo:nope").toString('base64')
+					}
+				},
+				function(err, resp, data, perf) {
+					test.ok( !err, "No error from PixlRequest: " + err );
+					test.ok( !!resp, "Got resp from PixlRequest" );
+					test.ok( resp.statusCode == 401, "Got 401 response: " + resp.statusCode );
+					test.ok( data.toString() == "Unauthorized", "Correct response body: " + data.toString() );
+					test.done();
+				}
+			);
+		},
+		
+		function testAuthGoodCredentials(test) {
+			// valid basic auth should pass through
+			request.json( 'http://127.0.0.1:3020/protected', false,
+				{
+					headers: {
+						"Authorization": "Basic " + Buffer.from("foo:bar").toString('base64')
+					}
+				},
+				function(err, resp, json, perf) {
+					test.ok( !err, "No error from PixlRequest: " + err );
+					test.ok( !!resp, "Got resp from PixlRequest" );
+					test.ok( resp.statusCode == 200, "Got 200 response: " + resp.statusCode );
+					test.ok( !!json, "Got JSON in response" );
+					test.ok( json.code == 0, "Correct code in JSON response: " + json.code );
+					test.ok( json.description == "Protected endpoint success", "Correct description in JSON response: " + json.description );
+					test.done();
+				}
+			);
+		},
+		
 		// blacklist
 		function testBlacklistedIP(test) {
 			request.get( 'http://127.0.0.1:3020/json', 

package/web_server.js

@@ -5,6 +5,7 @@
 
 const fs = require('fs');
 const os = require('os');
+const crypto = require('crypto');
 const zlib = require('zlib');
 const async = require('async');
 const Class = require("class-plus");
@@ -186,10 +187,66 @@ class WebServer extends Component {
 		// optional chaos (fault injection)
 		if (this.config.getPath('chaos.enabled')) this.setupChaos();
 		
+		// optional auth endpoints
+		if (this.config.get('auth')) this.setupAuth();
+		
 		// start listeners
 		this.startAll(callback);
 	}
 	
+	setupAuth() {
+		// basic auth behind custom URI patterns
+		// auth: { "URI": { enabled, type, realm, username, password } }
+		var self = this;
+		var auth_config = this.config.get('auth');
+		
+		// constant-time comparison to avoid timing attacks
+		var safeCompare = function(a, b) {
+			const bufA = Buffer.from(a);
+			const bufB = Buffer.from(b);
+			if (bufA.length !== bufB.length) return false;
+			return crypto.timingSafeEqual(bufA, bufB);
+		};
+		
+		var checkBasicAuth = function(req, auth) {
+			const header = req.headers['authorization'];
+			if (!header) return false;
+			
+			const [scheme, encoded] = header.split(' ');
+			if (scheme !== 'Basic' || !encoded) return false;
+			
+			const decoded = Buffer.from(encoded, 'base64').toString('utf8');
+			const index = decoded.indexOf(':');
+			if (index === -1) return false;
+			
+			const username = decoded.slice(0, index);
+			const password = decoded.slice(index + 1);
+			
+			return safeCompare(username, auth.username) && safeCompare(password, auth.password);
+		};
+		
+		Object.keys(auth_config).forEach( function(uri_match) {
+			var auth = auth_config[uri_match];
+			if (!auth.enabled) return;
+			if (auth.type != 'basic') {
+				self.logError('auth', "Unsupported auth type: " + auth.type);
+				return;
+			}
+			
+			self.addURIFilter( new RegExp(uri_match), "Auth", function(args, callback) {
+				self.logDebug(9, "Checking auth for: " + uri_match, { realm: auth.realm });
+				if (!checkBasicAuth(args.request, auth)) {
+					return callback( "401 Unauthorized", {
+						'WWW-Authenticate': `Basic realm="${auth.realm}"`,
+						'Content-Type': 'text/plain'
+					}, "Unauthorized" );
+				}
+				self.logDebug(9, "Authentication successful for: " + uri_match, { realm: auth.realm, username: auth.username });
+				callback(false); // passthru
+			} ); // addURIFilter
+		} ); // foreach auth
+	}
+	
 	setupChaos() {
 		// setup chaos system (random delays, errors, etc.)
 		// chaos: { enabled, uri?, delay?: { min:0, max:250 }, errors?: { "503 Service Unavailable": 0.1 }, headers? }