woodland 22.0.3 → 22.0.5

package/README.md

@@ -6,9 +6,9 @@
 Secure HTTP framework for Node.js. Express-compatible with built-in security, no performance tradeoff.
 
 [![npm version](https://badge.fury.io/js/woodland.svg)](https://badge.fury.io/js/woodland)
-[![Node.js Version](https://img.shields.io/node/v/woodland.svg)](https://nodejs.org/)
+[![Node.js Version](https://img.shields.io/badge/node.js-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
-[![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/avoidwork/woodland)
+[![Test Coverage](https://img.shields.io/badge/coverage-100%25%20line-brightgreen.svg)](https://github.com/avoidwork/woodland)
 
 </div>
 
@@ -54,9 +54,10 @@ createServer(app.route).listen(3000, () => console.log("Server running at http:/
 - **Built-in security** - CORS, path traversal, XSS prevention (no additional packages)
 - **Secure by default** - CORS deny-all, path traversal blocked, HTML escaping automatic
 - **TypeScript first** - Full type definitions included
-- **No performance tradeoff** - Security features add ~0.02ms overhead per request
+- **No performance tradeoff** - Security features add minimal overhead
 - **Lightweight** - Minimal dependencies (6 packages)
 - **Dual module support** - CommonJS and ESM
+- **Production ready** - Event emitters for custom monitoring, examples for graceful shutdown
 
 **Built-in Security Features:**
 
@@ -69,21 +70,53 @@ createServer(app.route).listen(3000, () => console.log("Server running at http:/
 
 ## Common Patterns
 
-### REST API
+### REST API with Error Handling
 
 ```javascript
 const users = new Map();
 
-app.get("/users", (req, res) => res.json(Array.from(users.values())));
+app.get("/users", (req, res) => {
+	try {
+		const list = Array.from(users.values());
+		res.json(list);
+	} catch (error) {
+		res.error(500, error.message);
+	}
+});
+
 app.get("/users/:id", (req, res) => {
-  const user = users.get(req.params.id);
-  user ? res.json(user) : res.error(404);
+	try {
+		const user = users.get(req.params.id);
+		if (!user) {
+			return res.error(404, "User not found");
+		}
+		res.json(user);
+	} catch (error) {
+		res.error(500, error.message);
+	}
 });
-app.post("/users", (req, res) => {
-  const id = Date.now().toString();
-  const user = { ...req.body, id };
-  users.set(id, user);
-  res.json(user, 201);
+
+app.post("/users", async (req, res) => {
+	try {
+		const id = Date.now().toString();
+		const user = { ...req.body, id };
+		users.set(id, user);
+		res.status(201).json(user);
+	} catch (error) {
+		res.error(400, error.message);
+	}
+});
+```
+
+### Health Check Endpoint
+
+```javascript
+app.get("/health", (req, res) => {
+	res.json({
+		status: "healthy",
+		timestamp: new Date().toISOString(),
+		uptime: process.uptime(),
+	});
 });
 ```
 
@@ -108,17 +141,17 @@ app.files("/static", "./public");
 ```javascript
 // Global middleware
 app.always((req, res, next) => {
-  req.startTime = Date.now();
-  next();
+	req.startTime = Date.now();
+	next();
 });
 
 // Route-specific middleware
 app.get("/protected", authenticate, handler);
 
-// Error handler (register last, 4 params)
-app.use("/(.*)", (error, req, res, next) => {
-  console.error(error);
-  res.error(500);
+// Error handler (register last with 4 params)
+app.use((error, req, res, next) => {
+	console.error(error);
+	res.error(500, error.message);
 });
 ```
 
@@ -126,18 +159,18 @@ app.use("/(.*)", (error, req, res, next) => {
 
 ```javascript
 const app = woodland({
-  origins: [], // CORS allowlist (empty = deny all)
-  autoIndex: false, // Directory browsing
-  etags: true, // ETag support
-  cacheSize: 1000, // Route cache size
-  cacheTTL: 10000, // Cache TTL in ms
-  charset: "utf-8", // Default charset
-  logging: {
-    enabled: true,
-    level: "info",
-  },
-  time: false, // X-Response-Time header
-  silent: false, // Disable server headers
+	origins: process.env.ALLOWED_ORIGINS?.split(",") || [],
+	autoIndex: process.env.AUTO_INDEX === "true",
+	etags: true,
+	cacheSize: 1000,
+	cacheTTL: 10000,
+	charset: "utf-8",
+	logging: {
+		enabled: true,
+		level: process.env.LOG_LEVEL || "info",
+	},
+	time: true,
+	silent: process.env.NODE_ENV === "production",
 });
 ```
 
@@ -174,6 +207,36 @@ app.on("error", (req, res, err) => console.error(`Error ${res.statusCode}:`, err
 app.on("stream", (req, res) => console.log(`Streaming file`));
 ```
 
+## Graceful Shutdown
+
+```javascript
+import { createServer } from "node:http";
+import { woodland } from "woodland";
+
+const app = woodland();
+const server = createServer(app.route);
+
+const gracefulShutdown = (signal) => {
+	console.log(`Received ${signal}, shutting down gracefully...`);
+
+	server.close(() => {
+		console.log("Server closed");
+		process.exit(0);
+	});
+
+	// Force shutdown after 30s
+	setTimeout(() => {
+		console.error("Forced shutdown");
+		process.exit(1);
+	}, 30000);
+};
+
+process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+
+server.listen(3000);
+```
+
 ## CLI
 
 ```bash
@@ -190,7 +253,7 @@ npx woodland --ip=0.0.0.0
 ## Testing
 
 ```bash
-npm test              # Run tests (100% line coverage)
+npm test              # Run tests (334 tests, 100% line, 99.37% function, 95.90% branch coverage)
 npm run coverage      # Generate coverage report
 npm run benchmark     # Performance benchmarks
 npm run lint          # Check linting
@@ -198,14 +261,14 @@ npm run lint          # Check linting
 
 ## Documentation
 
-- [API Reference](https://github.com/avoidwork/woodland/tree/master/docs/API.md) - Complete method documentation
-- [Technical Documentation](https://github.com/avoidwork/woodland/tree/master/docs/TECHNICAL_DOCUMENTATION.md) - Architecture, OWASP security, internals
-- [Code Style Guide](https://github.com/avoidwork/woodland/tree/master/docs/CODE_STYLE_GUIDE.md) - Conventions and best practices
-- [Benchmarks](https://github.com/avoidwork/woodland/tree/master/docs/BENCHMARKS.md) - Performance testing results
+- [API Reference](docs/API.md) - Complete method documentation
+- [Technical Documentation](docs/TECHNICAL_DOCUMENTATION.md) - Architecture, OWASP security, internals
+- [Code Style Guide](docs/CODE_STYLE_GUIDE.md) - Conventions and best practices
+- [Benchmarks](docs/BENCHMARKS.md) - Performance testing results
 
 ## Performance
 
-Woodland delivers **enterprise-grade security without sacrificing performance**. Security features add minimal overhead (~0.02ms per request).
+Woodland delivers **enterprise-grade security without sacrificing performance**. Security features add minimal overhead.
 
 | Framework | Security Approach | Mean Response Time |
 |-----------|------------------|-------------------|
@@ -222,6 +285,8 @@ Woodland implements multiple layers of protection:
 3. **Input Validation** - IP addresses validated, URLs parsed securely
 4. **Output Encoding** - HTML escaping automatic
 5. **Secure Error Handling** - No internal paths exposed
+6. **Header Injection Prevention** - Type validation for headers
+7. **Prototype Pollution Protection** - Safe ETag generation
 
 **Production Setup:**
 
@@ -230,16 +295,37 @@ import helmet from "helmet";
 import rateLimit from "express-rate-limit";
 
 app.always(helmet());
-app.always(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
+app.always(
+	rateLimit({
+		windowMs: 15 * 60 * 1000,  // 15 minutes
+		max: 100,                   // Limit each IP to 100 requests
+		standardHeaders: true,
+		legacyHeaders: false,
+	}),
+);
 ```
 
+**Security Warning:**
+> ⚠️ **Production Deployment**: Always use a reverse proxy (nginx, Cloudflare) in production for SSL/TLS termination, DDoS protection, and additional security layers.
+
 ## License
 
 Copyright (c) 2026 Jason Mulligan
 
 Licensed under the **BSD-3-Clause** license.
 
+## Contributing
+
+Contributions are welcome!
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
 ## Support
 
 - **Issues**: [GitHub Issues](https://github.com/avoidwork/woodland/issues)
 - **Discussions**: [GitHub Discussions](https://github.com/avoidwork/woodland/discussions)
+- **Email**: jason@mulligan.me

package/dist/cli.cjs

@@ -4,17 +4,17 @@
  *
  * @copyright 2026 Jason Mulligan <jason.mulligan@avoidwork.com>
  * @license BSD-3-Clause
- * @version 22.0.3
+ * @version 22.0.5
  */
 'use strict';
 
 var node_http = require('node:http');
-var node_url = require('node:url');
-var node_path = require('node:path');
-var tinyCoerce = require('tiny-coerce');
 var woodland = require('woodland');
 var node_module = require('node:module');
+var node_path = require('node:path');
+var node_url = require('node:url');
 var mimeDb = require('mime-db');
+var tinyCoerce = require('tiny-coerce');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 const __dirname$1 = node_url.fileURLToPath(new node_url.URL(".", (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli.cjs', document.baseURI).href))));
@@ -37,20 +37,23 @@ const INT_10 = 10;
 const INT_255 = 255;
 const INT_8000 = 8000;
 const INT_65535 = 65535;
+const INT_NEG_1 = -1;
 const COLON = ":";
 const DOUBLE_COLON = "::";
 const EMPTY = "";
 const EQUAL = "=";
 const HYPHEN = "-";
-const WOODLAND = "woodland";
 const STRING = "string";
 `nodejs/${process.version}, ${process.platform}/${process.arch}`;
 const LOCALHOST = "127.0.0.1";
 const EXTENSIONS = "extensions";
 const INFO = "info";
+const MSG_INVALID_IP = "Invalid IP: must be a valid IPv4 or IPv6 address.";
+const MSG_INVALID_PORT = "Invalid port: must be an integer between 0 and 65535.";
 const NO_CACHE = "no-cache";
 const EN_US = "en-US";
 const SHORT = "short";
+const EVT_LISTENING = "listening";
 
 Object.freeze(
 	Array.from({ length: 12 }, (_, idx) => {
@@ -60,56 +63,55 @@ Object.freeze(
 		return Object.freeze(d.toLocaleString(EN_US, { month: SHORT }));
 	}),
 );
+const IPV4_PATTERN = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+const IPV6_CHAR_PATTERN = /^[0-9a-fA-F:.]+$/;
+const IPV4_MAPPED_PATTERN = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i;
+const HEX_GROUP_PATTERN = /^[0-9a-fA-F]{1,4}$/;
 
-const valid = Object.entries(mimeDb).filter((i) => EXTENSIONS in i[1]);
+const valid = Object.entries(mimeDb).filter((i) => EXTENSIONS in i[INT_1]);
 	valid.reduce((a, v) => {
-		const result = Object.assign({ type: v[0] }, v[1]);
+		const result = Object.assign({ type: v[INT_0] }, v[INT_1]);
 		const extCount = result.extensions.length;
-		for (let i = 0; i < extCount; i++) {
+		for (let i = INT_0; i < extCount; i++) {
 			a[`.${result.extensions[i]}`] = result;
 		}
 		return a;
 	}, {});
 
-const IPV4_PATTERN = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/,
-	IPV6_CHAR_PATTERN = /^[0-9a-fA-F:.]+$/,
-	IPV4_MAPPED_PATTERN = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i,
-	HEX_GROUP_PATTERN = /^[0-9a-fA-F]{1,4}$/;
-
 /**
- * Validates if an IP address is properly formatted
- * @param {string} ip - IP address to validate
- * @returns {boolean} True if IP is valid format
+ * Validates IPv4 address format
+ * @param {string} ip - IPv4 address to validate
+ * @returns {boolean} True if valid IPv4
  */
-function isValidIP(ip) {
-	if (!ip || typeof ip !== STRING) {
+function isValidIPv4(ip) {
+	const match = IPV4_PATTERN.exec(ip);
+	if (!match) {
 		return false;
 	}
 
-	if (ip.indexOf(COLON) === -1) {
-		const match = IPV4_PATTERN.exec(ip);
-
-		if (!match) {
+	for (let i = INT_1; i < INT_5; i++) {
+		const num = parseInt(match[i], INT_10);
+		if (num > INT_255) {
 			return false;
 		}
-
-		for (let i = 1; i < INT_5; i++) {
-			const num = parseInt(match[i], INT_10);
-			if (num > INT_255) {
-				return false;
-			}
-		}
-
-		return true;
 	}
 
+	return true;
+}
+
+/**
+ * Validates IPv6 address format
+ * @param {string} ip - IPv6 address to validate
+ * @returns {boolean} True if valid IPv6
+ */
+function isValidIPv6(ip) {
 	if (!IPV6_CHAR_PATTERN.test(ip)) {
 		return false;
 	}
 
 	const ipv4MappedMatch = IPV4_MAPPED_PATTERN.exec(ip);
 	if (ipv4MappedMatch) {
-		return isValidIP(ipv4MappedMatch[1]);
+		return isValidIPv4(ipv4MappedMatch[INT_1]);
 	}
 
 	if (ip === DOUBLE_COLON) {
@@ -117,75 +119,95 @@ function isValidIP(ip) {
 	}
 
 	const doubleColonIndex = ip.indexOf(DOUBLE_COLON);
-	const isCompressed = doubleColonIndex !== -1;
+	const isCompressed = doubleColonIndex !== INT_NEG_1;
 
 	if (isCompressed) {
-		if (ip.indexOf(DOUBLE_COLON, doubleColonIndex + INT_2) !== -1) {
-			return false;
-		}
+		return validateCompressedIPv6(ip, doubleColonIndex);
+	}
 
-		if (
-			(doubleColonIndex > INT_0 && ip.charAt(doubleColonIndex - INT_1) === COLON) ||
-			(doubleColonIndex + INT_2 < ip.length && ip.charAt(doubleColonIndex + INT_2) === COLON)
-		) {
-			return false;
-		}
+	return validateUncompressedIPv6(ip);
+}
 
-		const beforeDoubleColon = ip.substring(INT_0, doubleColonIndex);
-		const afterDoubleColon = ip.substring(doubleColonIndex + INT_2);
+/**
+ * Validates compressed IPv6 address (with ::)
+ * @param {string} ip - IPv6 address
+ * @param {number} doubleColonIndex - Position of ::
+ * @returns {boolean} True if valid
+ */
+function validateCompressedIPv6(ip, doubleColonIndex) {
+	if (ip.indexOf(DOUBLE_COLON, doubleColonIndex + INT_2) !== INT_NEG_1) {
+		return false;
+	}
 
-		let leftGroups;
-		if (beforeDoubleColon) {
-			leftGroups = beforeDoubleColon.split(COLON);
-		} else {
-			leftGroups = [];
-		}
+	if (
+		(doubleColonIndex > INT_0 && ip.charAt(doubleColonIndex - INT_1) === COLON) ||
+		(doubleColonIndex + INT_2 < ip.length && ip.charAt(doubleColonIndex + INT_2) === COLON)
+	) {
+		return false;
+	}
 
-		let rightGroups;
-		if (afterDoubleColon) {
-			rightGroups = afterDoubleColon.split(COLON);
-		} else {
-			rightGroups = [];
-		}
+	const beforeDoubleColon = ip.substring(INT_0, doubleColonIndex);
+	const afterDoubleColon = ip.substring(doubleColonIndex + INT_2);
 
-		const nonEmptyLeft = leftGroups.filter((g) => g !== EMPTY);
-		const nonEmptyRight = rightGroups.filter((g) => g !== EMPTY);
-		const totalGroups = nonEmptyLeft.length + nonEmptyRight.length;
+	const leftGroups = beforeDoubleColon ? beforeDoubleColon.split(COLON) : [];
+	const rightGroups = afterDoubleColon ? afterDoubleColon.split(COLON) : [];
 
-		if (totalGroups >= INT_8) {
-			return false;
-		}
+	const totalGroups =
+		leftGroups.filter((g) => g !== EMPTY).length + rightGroups.filter((g) => g !== EMPTY).length;
 
-		/* node:coverage ignore next 5 */
-		for (let i = INT_0; i < nonEmptyLeft.length; i++) {
-			if (!HEX_GROUP_PATTERN.test(nonEmptyLeft[i])) {
-				return false;
-			}
-		}
+	if (totalGroups >= INT_8) {
+		return false;
+	}
 
-		/* node:coverage ignore next 5 */
-		for (let i = INT_0; i < nonEmptyRight.length; i++) {
-			if (!HEX_GROUP_PATTERN.test(nonEmptyRight[i])) {
-				return false;
-			}
-		}
+	return validateHexGroups(leftGroups) && validateHexGroups(rightGroups);
+}
 
-		return true;
-	} else {
-		const groups = ip.split(COLON);
-		if (groups.length !== INT_8) {
+/**
+ * Validates uncompressed IPv6 address
+ * @param {string} ip - IPv6 address
+ * @returns {boolean} True if valid
+ */
+function validateUncompressedIPv6(ip) {
+	const groups = ip.split(COLON);
+	if (groups.length !== INT_8) {
+		return false;
+	}
+
+	return validateHexGroups(groups);
+}
+
+/**
+ * Validates hex groups in IPv6 address
+ * @param {Array} groups - Array of hex group strings
+ * @returns {boolean} True if all groups are valid
+ */
+function validateHexGroups(groups) {
+	const groupCount = groups.length;
+
+	for (let i = INT_0; i < groupCount; i++) {
+		/* node:coverage ignore next 3 */
+		if (!groups[i] || !HEX_GROUP_PATTERN.test(groups[i])) {
 			return false;
 		}
+	}
+	return true;
+}
 
-		/* node:coverage ignore next 5 */
-		for (let i = INT_0; i < INT_8; i++) {
-			if (!groups[i] || !HEX_GROUP_PATTERN.test(groups[i])) {
-				return false;
-			}
-		}
+/**
+ * Validates if an IP address is properly formatted
+ * @param {string} ip - IP address to validate
+ * @returns {boolean} True if IP is valid format
+ */
+function isValidIP(ip) {
+	if (!ip || typeof ip !== STRING) {
+		return false;
+	}
 
-		return true;
+	if (ip.indexOf(COLON) === INT_NEG_1) {
+		return isValidIPv4(ip);
 	}
+
+	return isValidIPv6(ip);
 }
 
 /**
@@ -195,10 +217,10 @@ function isValidIP(ip) {
  */
 function parseArgs(args) {
 	return args
-		.filter((i) => i.charAt(0) === HYPHEN && i.charAt(1) === HYPHEN)
+		.filter((i) => i.charAt(INT_0) === HYPHEN && i.charAt(INT_1) === HYPHEN)
 		.reduce((a, v) => {
-			const x = v.split(`${HYPHEN}${HYPHEN}`)[1].split(EQUAL);
-			a[x[0]] = tinyCoerce.coerce(x[1]);
+			const x = v.split(`${HYPHEN}${HYPHEN}`)[INT_1].split(EQUAL);
+			a[x[INT_0]] = tinyCoerce.coerce(x[INT_1]);
 			return a;
 		}, {});
 }
@@ -209,13 +231,12 @@ function parseArgs(args) {
  * @returns {Object} Validation result with valid flag and error message
  */
 function validatePort(port) {
-	// Reject empty strings and whitespace-only values
 	if (port === EMPTY || (typeof port === STRING && port.trim() === EMPTY)) {
-		return { valid: false, error: "Invalid port: must be an integer between 0 and 65535." };
+		return { valid: false, error: MSG_INVALID_PORT };
 	}
 	const validPort = Number(port);
 	if (!Number.isInteger(validPort) || validPort < INT_0 || validPort > INT_65535) {
-		return { valid: false, error: "Invalid port: must be an integer between 0 and 65535." };
+		return { valid: false, error: MSG_INVALID_PORT };
 	}
 	return { valid: true, port: validPort };
 }
@@ -228,7 +249,7 @@ function validatePort(port) {
 function validateIP(ip) {
 	const validIP = isValidIP(ip);
 	if (!validIP) {
-		return { valid: false, error: "Invalid IP: must be a valid IPv4 or IPv6 address." };
+		return { valid: false, error: MSG_INVALID_IP };
 	}
 	return { valid: true, ip };
 }
@@ -270,7 +291,7 @@ function main(args = process.argv) {
 	const server = node_http.createServer(app.route);
 	server.listen(portValidation.port, ip);
 	/* node:coverage ignore next 6 */
-	server.on("listening", () => {
+	server.on(EVT_LISTENING, () => {
 		const actualPort = server.address().port;
 		app.logger.log(
 			`id=woodland, hostname=${process.env.HOSTNAME ?? "localhost"}, ip=${ip}, port=${actualPort}`,
@@ -281,17 +302,8 @@ function main(args = process.argv) {
 	return server;
 }
 
-// CLI entry point - only run when executed directly
-const __filename$1 = node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli.cjs', document.baseURI).href)));
-/* node:coverage ignore next 6 */
-if (process.argv[1]) {
-	const scriptPath = node_path.resolve(process.argv[1]);
-	if (scriptPath === __filename$1 || node_path.basename(scriptPath) === WOODLAND) {
-		main();
-	}
-}
+// CLI entry point - always run main
+/* node:coverage ignore next */
+main();
 
 exports.main = main;
-exports.parseArgs = parseArgs;
-exports.validateIP = validateIP;
-exports.validatePort = validatePort;