koa-classic-server 1.1.0 → 2.0.0

package/README.md

@@ -1,149 +1,324 @@
-# koa-classic-file
+# koa-classic-server
 
-koa-cleassic-server is a mildwere aiming for similar but not identical behavior to apache2 . the contents of a folder on the server will be shown remotely and if you want to access a file, click on it. note: not a highly inexperienced programmer use this code with caution, suggestions are welcome.
+🔒 **Secure Koa middleware for serving static files** with Apache-like directory listing, template engine support, and comprehensive security fixes.
 
-middleware serving static files from a directory. The middleware accepts an options object that allows customization of the serving behavior. For example, it allows setting the supported HTTP methods, whether to show the contents of a directory, the name of the index file, an array of URLs that are reserved and not accessible, and an optional template rendering function for certain file types.
+[![npm version](https://img.shields.io/npm/v/koa-classic-server.svg)](https://www.npmjs.com/package/koa-classic-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-71%20passing-brightgreen.svg)]()
 
-    The middleware takes in two arguments: rootDir which is the directory that contains the static files and opts which is the options object.
+## ⚠️ Version 1.2.0 - Critical Security Update
 
-    In the options object, the following properties are set to default values if they are not provided:
-        method: an array of supported HTTP methods. Default is ['GET'].
-        showDirContents: a boolean value indicating whether the contents of a directory should be shown. Default is true.
-        index: the name of the index file. Default is an empty string.
-        urlPrefix: the prefix of the path , such as localhost:3000/views. Default is an empty string.
-        urlsReserved: an array of reserved URLs that files cannot be read from. Default is an empty array.
-        template: an object with two properties:
-            render: a function for rendering templates. Default is undefined.
-            ext: an array of file extensions for which the render function should be used. Default is an empty array.
+Version 1.2.0 includes **critical security fixes** for path traversal vulnerabilities and other important improvements. **Upgrade immediately** if you're using version 1.1.0 or earlier.
 
-    The middleware then checks if the requested HTTP method is in the list of supported methods. If it is not, the middleware calls next and returns.
+### What's New in 1.2.0
 
-    The middleware then checks if the pageHref is a sub-path of the urlPrefix. If it is not, the middleware calls next and returns.
+✅ **Fixed Path Traversal Vulnerability** - No more unauthorized file access
+✅ **Proper HTTP 404 Status Codes** - Standards-compliant error handling
+✅ **Template Error Handling** - No more server crashes
+✅ **XSS Protection** - HTML escaping in directory listings
+✅ **Race Condition Fixes** - Robust file access
+✅ **71 Tests Passing** - Comprehensive test coverage
 
-    The middleware checks if the requested URL is in the urlsReserved array. If it is, the middleware calls next and returns.
+[See full changelog](./CHANGELOG.md)
 
-    The middleware then generates the file path by combining the rootDir and the pathname of the pageHref.
+## Features
 
-    The middleware then checks if the file exists, and if it does, it sets the content type of the response and sends the file contents. If the file is a directory and showDirContents is true, the contents of the directory are shown. If the index file exists in the directory, it is shown instead.
+koa-classic-server is a middleware for serving static files from a directory with Apache 2-like behavior. The contents of a folder on the server will be shown remotely and if you want to access a file, click on it.
 
-    If the file does not exist, the middleware calls next to let the next middleware handle the request.
+**Key Features:**
 
-    If the file extension is in the template.ext array and the template.render function is provided, the function is called to render the file contents.
+- 🗂️ **Directory Listing** - Apache-style browseable directories
+- 📄 **Static File Serving** - Automatic MIME type detection
+- 🎨 **Template Engine Support** - Integrate EJS, Pug, Handlebars, etc.
+- 🔒 **Security** - Path traversal protection, XSS prevention
+- ⚙️ **Configurable** - URL prefixes, reserved paths, index files
+- 🧪 **Well-Tested** - 71 tests with security coverage
+- 📦 **Dual Module Support** - CommonJS and ES Modules
 
 ## Installation
 
-```js
-npm i koa-classic-server
+```bash
+npm install koa-classic-server
 ```
 
-next import 
+## Quick Start
 
-```js
+```javascript
+const Koa = require('koa');
 const koaClassicServer = require('koa-classic-server');
+
+const app = new Koa();
+
+// Serve files from "public" directory
+app.use(koaClassicServer(__dirname + '/public'));
+
+app.listen(3000);
+console.log('Server running on http://localhost:3000');
 ```
-or
-```js
-import koaClassicServer from "koa-classic-server";
-'''
 
-## API
+## Usage
 
-## Options
+### Import
 
-```js
-opts = {
-  method: Array("GET"), // methods enabled, otherwise it will have called the next() function
-  showDirContents: true, //show or not the contents of the current directory
-  index: "", // the index file , if a file with this name is found it will be loaded automatically Es index.html
-  //indexExt: array(),// futures supported extensions for the index file
-  urlPrefix: "", // prefix of the URL that will be skipped es "/admin" 
-  urlsReserved: Array(), //paths on disk that will not be accessible remotely e.g. array('/api','/views') warning nested folders are not allowed
-  template: {
-    render: undefined, //function that will take care of the rendering if there is a template engine  ES --> const templateRender = async ( ctx, next, filePath) => {
-    ext: Array(), // template engine file extension ES :Array("ejs", "EJS"),
-  }, // emd template
-}; // end optio
+```javascript
+// CommonJS
+const koaClassicServer = require('koa-classic-server');
+
+// ES Modules
+import koaClassicServer from 'koa-classic-server';
 ```
 
-## Exsample
+### Basic Examples
 
-### exsaple0
+#### Example 1: Simple File Server
 
-```js
-const Koa = require("koa");
-const koaClassicServer = require("koa-classic-server");
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
 
 const app = new Koa();
 
-app.use(koaClassicServer(__dirname + "/public"));
+app.use(koaClassicServer(__dirname + '/public', {
+  showDirContents: true,
+  index: ['index.html']  // Array format (recommended)
+}));
 
 app.listen(3000);
 ```
 
-### exsample1
-
-```js
-const koa = require("koa");
-const app = new koa();
-const port = 3000;
-
-const classicServer = require("koa-classic-server");
-
-const ejs = require("ejs");
-
-app.use(
-  classicServer(
-    __dirname + "/public",
-    (opt = {
-      showDirContents: true,
-      template: {
-        render: async (ctx, next, filePath) => {
-          ctx.body = await ejs.renderFile(filePath, {
-            filePath: filePath,
-            href: ctx.href,
-            query: ctx.query,
-          });
-        },
-        ext: Array("ejs", "EJS"),
-      },
-    })
-  )
-);
-
-app.listen(port, console.log("server started on port:" + port));
+#### Example 2: With URL Prefix
+
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+
+const app = new Koa();
+
+// Files accessible under /static
+// e.g., http://localhost:3000/static/image.png
+app.use(koaClassicServer(__dirname + '/public', {
+  urlPrefix: '/static',
+  showDirContents: true
+}));
+
+app.listen(3000);
 ```
 
-### exsample2
+#### Example 3: With Template Engine (EJS)
 
-```js
-const koa = require("koa");
-const app = new koa();
-const port = 3000;
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+const ejs = require('ejs');
 
-const classicServer = require("koa-classic-server");
+const app = new Koa();
 
-const ejs = require("ejs");
+app.use(koaClassicServer(__dirname + '/views', {
+  template: {
+    render: async (ctx, next, filePath) => {
+      ctx.body = await ejs.renderFile(filePath, {
+        title: 'My App',
+        user: ctx.state.user
+      });
+    },
+    ext: ['ejs', 'html']
+  }
+}));
 
-const templateRender = async (ctx, next, filePath) => {
-  ctx.body = await ejs.renderFile(filePath, { filePath: filePath });
+app.listen(3000);
+```
+
+## API
+
+### koaClassicServer(rootDir, options)
+
+Creates a Koa middleware for serving static files.
+
+**Parameters:**
+
+- `rootDir` (String, required): Absolute path to the directory containing static files
+- `options` (Object, optional): Configuration options
+
+**Returns:** Koa middleware function
+
+## Options
+
+```javascript
+const options = {
+  // HTTP methods allowed (default: ['GET'])
+  method: ['GET', 'HEAD'],
+
+  // Show directory contents (default: true)
+  showDirContents: true,
+
+  // Index file configuration (default: [])
+  // RECOMMENDED: Use array format (string format is deprecated)
+  // Formats:
+  //   - Array of strings: ['index.html', 'index.htm', 'default.html']
+  //   - Array of RegExp: [/index\.html/i] (case-insensitive)
+  //   - Mixed array: ['index.html', /INDEX\.HTM/i]
+  // Priority: First match wins (array order determines search priority)
+  //
+  // DEPRECATED: String format 'index.html' still works but will be removed
+  // in future versions. Please use array format: ['index.html']
+  //
+  // See INDEX_OPTION_PRIORITY.md for detailed behavior documentation
+  index: ['index.html'],
+
+  // URL path prefix (default: '')
+  // Files will be served under this prefix
+  urlPrefix: '/static',
+
+  // Reserved paths (default: [])
+  // These directories won't be accessible
+  // Note: Only works for first-level directories
+  urlsReserved: ['/admin', '/private'],
+
+  // Template engine configuration
+  template: {
+    // Template rendering function
+    render: async (ctx, next, filePath) => {
+      // Your rendering logic
+      ctx.body = await yourTemplateEngine.render(filePath, data);
+    },
+
+    // File extensions to process with template.render
+    ext: ['ejs', 'pug', 'hbs']
+  }
 };
+```
+
+### Options Details
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `method` | Array | `['GET']` | Allowed HTTP methods |
+| `showDirContents` | Boolean | `true` | Show directory listing |
+| `index` | String | `''` | Index file name |
+| `urlPrefix` | String | `''` | URL path prefix |
+| `urlsReserved` | Array | `[]` | Reserved directory paths |
+| `template.render` | Function | `undefined` | Template rendering function |
+| `template.ext` | Array | `[]` | Extensions for template rendering |
+
+## Security
+
+### Path Traversal Protection
+
+koa-classic-server 1.2.0 protects against path traversal attacks:
+
+```javascript
+// ❌ These requests are blocked (return 403 Forbidden)
+GET /../../../etc/passwd
+GET /../config/database.yml
+GET /%2e%2e%2fpackage.json
+```
+
+### Protected Directories
+
+Use `urlsReserved` to protect sensitive directories:
 
-app.use(
-  classicServer(
-    __dirname + "/public",
-    (opt = {
-      showDirContents: true,
-      template: {
-        render: templateRender,
-        ext: Array("ejs", "EJS"),
-      },
-    })
-  )
-);
-
-app.listen(port, console.log("server started on port:" + port));
+```javascript
+app.use(koaClassicServer(__dirname + '/www', {
+  urlsReserved: ['/config', '/private', '/.git', '/node_modules']
+}));
 ```
 
+### XSS Protection
+
+All filenames and paths in directory listings are HTML-escaped to prevent XSS attacks.
+
+## Error Handling
+
+koa-classic-server properly handles errors:
+
+- **404** - File/directory not found
+- **403** - Forbidden (path traversal attempts, reserved directories)
+- **500** - Template rendering errors, file access errors
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run security tests only
+npm run test:security
+```
+
+## Middleware Behavior
+
+### Directory Handling
+
+1. If `index` file exists → serve index file
+2. If `showDirContents: true` → show directory listing
+3. If `showDirContents: false` → return 404
+
+### File Handling
+
+1. Check if file extension matches `template.ext`
+2. If yes → call `template.render()`
+3. If no → serve static file with appropriate MIME type
+
+### Reserved URLs
+
+Requests to reserved paths are passed to the next middleware.
+
+## Migration from 1.1.0
+
+Upgrading is simple! No code changes required:
+
+```bash
+npm update koa-classic-server
+```
+
+**What changed:**
+- 404 status codes now correct (was 200)
+- Path traversal blocked (was allowed)
+- Template errors return 500 (was crash)
+
+See [CHANGELOG.md](./CHANGELOG.md) for detailed information.
+
+## Complete Documentation
+
+For complete documentation with all features, examples, troubleshooting, and best practices, see:
+
+- **[DOCUMENTATION.md](./DOCUMENTATION.md)** - Complete API reference and usage guide
+- **[INDEX_OPTION_PRIORITY.md](./INDEX_OPTION_PRIORITY.md)** - Detailed priority behavior for `index` option (string, array, RegExp)
+- **[EXAMPLES_INDEX_OPTION.md](./EXAMPLES_INDEX_OPTION.md)** - 10 practical examples of `index` option with RegExp
+- **[PERFORMANCE_ANALYSIS.md](./PERFORMANCE_ANALYSIS.md)** - Performance optimization analysis
+- **[PERFORMANCE_COMPARISON.md](./PERFORMANCE_COMPARISON.md)** - Before/after performance benchmarks
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Known Limitations
+
+- Reserved URLs only work for first-level directories
+- Single index file name (no fallback array)
+
+See [DEBUG_REPORT.md](./DEBUG_REPORT.md) for technical details.
+
 ## License
 
 MIT
+
+## Author
+
+Italo Paesano
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md)
+
+## Links
+
+- [Full Documentation](./DOCUMENTATION.md)
+- [Debug Report](./DEBUG_REPORT.md)
+- [Changelog](./CHANGELOG.md)
+- [Repository](https://github.com/italopaesano/koa-classic-server)
+- [npm Package](https://www.npmjs.com/package/koa-classic-server)
+
+---
+
+**⚠️ Security Notice:** Version 1.2.0 fixes critical vulnerabilities. Update immediately if using 1.1.0 or earlier.