koa-classic-server 1.0.6 → 1.2.0

package/.vscode/OLD_launch.json

@@ -0,0 +1,26 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+    {
+        "name": "Attach by Process ID",
+        "processId": "${command:PickProcess}",
+        "request": "attach",
+        "skipFiles": [
+            "<node_internals>/**"
+        ],
+        "type": "node"
+    },
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Launch Program",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}/index.cjs"
+        }
+    ]
+}

package/.vscode/launch.json

@@ -0,0 +1,41 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+      {
+        "name": "Attach by Process ID",
+        "processId": "${command:PickProcess}",
+        "request": "attach",
+        "skipFiles": [
+          "<node_internals>/**"
+        ],
+        "type": "node"
+      },
+      {
+        "type": "node",
+        "request": "launch",
+        "name": "Launch Program",
+        "skipFiles": [
+          "<node_internals>/**"
+        ],
+        "program": "${workspaceFolder}/index.cjs"
+      },
+      {
+        "name": "Debug Jest Tests",
+        "type": "node",
+        "request": "launch",
+        "runtimeExecutable": "node",
+        "runtimeArgs": [
+          "--inspect-brk",
+          "${workspaceFolder}/node_modules/jest/bin/jest.js",
+          "--runInBand"
+        ],
+        "port": 9229,
+        "console": "integratedTerminal",
+        "internalConsoleOptions": "neverOpen",
+        "skipFiles": [
+          "<node_internals>/**"
+        ]
+      }
+    ]
+  }
+  

package/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+All notable changes to koa-classic-server will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2025-11-17
+
+### 🎉 SECURITY & BUG FIX RELEASE
+
+This release contains **critical security fixes** and important bug fixes. All users should upgrade immediately.
+
+### 🔒 Security Fixes (CRITICAL)
+
+#### Fixed Path Traversal Vulnerability
+- **Issue**: Attackers could access files outside the served directory using `../` sequences
+- **Impact**: CRITICAL - Unauthorized file access
+- **Fix**: Added path normalization and validation to ensure all file access stays within `rootDir`
+- **Code**: `index.cjs:106-124`
+
+#### Fixed Template Rendering Crash
+- **Issue**: Unhandled errors in template rendering could crash the entire server
+- **Impact**: CRITICAL - Denial of Service
+- **Fix**: Added try-catch around template render calls with proper error handling
+- **Code**: `index.cjs:195-205`
+
+### ✅ Bug Fixes
+
+#### Fixed HTTP Status Code 404
+- **Issue**: Missing files returned HTML "Not Found" with HTTP 200 status instead of 404
+- **Impact**: HIGH - Violates HTTP standards, affects SEO, breaks caching
+- **Fix**: Properly set `ctx.status = 404` when resources are not found
+- **Locations**:
+  - `index.cjs:130` - File/directory not found
+  - `index.cjs:158` - Directory listing disabled
+
+#### Fixed Race Condition in File Access
+- **Issue**: Files could be deleted between existence check and reading, causing uncaught errors
+- **Impact**: HIGH - Server crashes on file access errors
+- **Fix**: Added `fs.promises.access()` check before streaming files with error handling
+- **Code**: `index.cjs:208-216`
+
+#### Fixed File Extension Extraction
+- **Issue**: Using `split(".")` failed for:
+  - Files without extension (`README`)
+  - Hidden files (`.gitignore`)
+  - Paths with dots (`/folder.backup/file`)
+- **Impact**: HIGH - Template rendering activated incorrectly
+- **Fix**: Use `path.extname()` for robust extension extraction
+- **Code**: `index.cjs:192`
+
+#### Fixed Directory Read Errors
+- **Issue**: `fs.readdirSync()` could throw unhandled errors (permissions, deleted directories)
+- **Impact**: MEDIUM - Server crashes on directory access errors
+- **Fix**: Added try-catch with user-friendly error message
+- **Code**: `index.cjs:245-264`
+
+#### Fixed Content-Disposition Header
+- **Issue**: Filename in Content-Disposition header was not quoted and included full path
+- **Impact**: MEDIUM - Download issues with special characters in filenames
+- **Fix**:
+  - Use only basename (not full path)
+  - Quote filename and escape quotes
+- **Code**: `index.cjs:234-239`
+
+### 🎨 Improvements
+
+#### Added Input Validation
+- Validate `rootDir` is a non-empty string
+- Validate `rootDir` is an absolute path
+- Throw meaningful errors for invalid input
+
+#### Added XSS Protection
+- HTML-escape all user-controlled content in directory listings
+- Escapes filenames, paths, and MIME types
+- Prevents XSS attacks through malicious filenames
+
+#### Improved Error Messages
+- More descriptive error messages
+- Console logging for debugging
+- Stream error handling
+
+#### Code Quality
+- Fixed usage of `Array()` constructor to literal syntax `[]`
+- Better code organization and comments
+- Improved HTML output formatting
+
+### 📝 Added Files
+
+- **`__tests__/security.test.js`**: Comprehensive security and bug tests
+- **`DEBUG_REPORT.md`**: Detailed analysis of all bugs and fixes
+- **`DOCUMENTATION.md`**: Complete documentation (1500+ lines)
+- **`CHANGELOG.md`**: This file
+
+### 🧪 Testing
+
+- All 71 tests passing
+- Added security test suite
+- Path traversal tests
+- Template error handling tests
+- Status code validation tests
+- Race condition tests
+- Content-Disposition tests
+
+### 📦 Package Changes
+
+- **Version**: `1.1.0` → `1.2.0`
+- **Description**: Enhanced with security fixes
+- **Keywords**: Added `secure`, `middleware`, `file-server`, `directory-listing`
+- **Scripts**: Added `test:security` command
+
+### ⚠️ Breaking Changes
+
+**None** - This is a backwards-compatible release. However, behavior changes for security:
+
+1. **404 Status Codes**: Now properly returns 404 instead of 200 for missing resources
+2. **Path Traversal**: Requests with `../` now return 403 Forbidden instead of allowing access
+3. **Error Handling**: Template errors return 500 instead of crashing the server
+
+These changes fix bugs and security issues. The new behavior is correct and standards-compliant.
+
+### 🔄 Migration Guide
+
+No code changes required! Simply update:
+
+```bash
+npm update koa-classic-server
+```
+
+**Recommended**: Verify that:
+1. `rootDir` is an absolute path (e.g., `__dirname + '/public'`)
+2. Your error handling expects proper 404/403/500 status codes
+3. Your tests pass with the new behavior
+
+### 📊 Statistics
+
+- **Lines of code fixed**: ~200
+- **Security vulnerabilities fixed**: 2 critical
+- **Bugs fixed**: 6
+- **Tests added**: 12 security tests
+- **Documentation added**: 2000+ lines
+- **Test coverage**: 71 tests passing
+
+### 🙏 Credits
+
+- **Author**: Italo Paesano
+- **Security Audit**: Comprehensive code analysis
+- **Testing**: Jest & Supertest
+
+---
+
+## [1.1.0] - Previous Release
+
+### Features
+- Basic static file serving
+- Directory listing
+- Template engine support
+- URL prefixes
+- Reserved URLs
+
+### Known Issues (Fixed in 1.2.0)
+- Path traversal vulnerability ⚠️ CRITICAL
+- Missing 404 status codes
+- Unhandled template errors ⚠️ CRITICAL
+- Race condition in file access
+- Fragile file extension extraction
+- Missing error handling
+
+---
+
+## Links
+
+- [Full Documentation](./DOCUMENTATION.md)
+- [Debug Report](./DEBUG_REPORT.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.