koa-classic-server 3.0.0-alpha.0 → 3.0.1

package/__tests__/head-method.test.js

@@ -0,0 +1,160 @@
+const Koa = require('koa');
+const koaClassicServer = require('../index.cjs');
+const supertest = require('supertest');
+const path = require('path');
+const fs = require('fs');
+const ejs = require('ejs');
+
+// Regression tests for the HEAD-method HTTP-conformance bug.
+//
+// RFC 9110 §9.3.2: a HEAD response must be identical to the GET response for the
+// same resource, minus the message body — same status code, same headers
+// (notably Content-Type and Content-Length).
+//
+// Before the fix, a route served by the template engine returned 200 on GET but
+// 404 on HEAD whenever the operator's render function did not itself handle HEAD
+// (e.g. it returned early on non-GET requests). The static-file branch already
+// handled HEAD correctly, and directory listings happened to work because Koa
+// strips the string body for HEAD — only the template branch was broken.
+
+const ROOT = path.join(__dirname, 'publicWwwTest');
+
+// Minimal data for the templates exercised here. ejs-templates/index.ejs needs no
+// variables; simple.ejs needs these four. Anything else renders with no locals.
+function templateData(filePath) {
+    if (path.basename(filePath, '.ejs') === 'simple') {
+        return {
+            title: 'Simple EJS Test',
+            heading: 'Hello from EJS',
+            message: 'This is a simple template test',
+            timestamp: '2025-11-18',
+        };
+    }
+    return {};
+}
+
+// A method-AWARE render: it only produces a body on GET. This is a common
+// real-world pattern (operators guard render work behind a GET check) and is
+// exactly what exposed the bug — on HEAD it never set ctx.body, so the status
+// stayed at Koa's default 404. This render is what makes the regression real:
+// with a naive render the test would pass even without the fix, because Koa
+// strips the body of a 200 GET response for HEAD on its own.
+const methodAwareRender = async (ctx, next, filePath) => {
+    if (ctx.method !== 'GET') return;
+    const tpl = await fs.promises.readFile(filePath, 'utf-8');
+    ctx.type = 'text/html';
+    ctx.body = ejs.render(tpl, templateData(filePath));
+};
+
+// A method-AGNOSTIC render: sets the body regardless of method. Proves the fix
+// does not regress renders that already worked.
+const naiveRender = async (ctx, next, filePath) => {
+    const tpl = await fs.promises.readFile(filePath, 'utf-8');
+    ctx.type = 'text/html';
+    ctx.body = ejs.render(tpl, templateData(filePath));
+};
+
+function buildServer(render) {
+    const app = new Koa();
+    app.use(
+        koaClassicServer(ROOT, {
+            method: ['GET', 'HEAD'],
+            index: ['index.html', 'index.ejs'],
+            dirListing: { enabled: true },
+            template: { ext: ['ejs'], render },
+        })
+    );
+    return app.listen();
+}
+
+// Asserts the HEAD response for `urlPath` matches the corresponding GET in status,
+// Content-Type and Content-Length, and that HEAD carries no body.
+async function expectHeadMatchesGet(request, urlPath, expectedStatus) {
+    const get = await request.get(urlPath);
+    const head = await request.head(urlPath);
+
+    expect(get.status).toBe(expectedStatus);
+    expect(head.status).toBe(expectedStatus);
+
+    // Same headers as GET (RFC 9110 §9.3.2)
+    expect(head.headers['content-type']).toBe(get.headers['content-type']);
+    expect(head.headers['content-length']).toBe(get.headers['content-length']);
+    // Content-Length must actually be populated for a body-bearing response
+    expect(head.headers['content-length']).toBeDefined();
+
+    // HEAD must not send a body (supertest surfaces an empty object for HEAD)
+    expect(head.text).toBeFalsy();
+    expect(head.body).toEqual({});
+
+    return { get, head };
+}
+
+describe('HEAD method — template engine routes (method-aware render)', () => {
+    let server;
+    let request;
+    beforeAll(() => { server = buildServer(methodAwareRender); request = supertest(server); });
+    afterAll(() => server.close());
+
+    // The headline bug: a directory whose index is a template (index.ejs as the
+    // index of /ejs-templates/). GET 200, HEAD must also be 200 — not 404.
+    test('HEAD on a directory whose index is a template → 200, matches GET', async () => {
+        const { get } = await expectHeadMatchesGet(request, '/ejs-templates/', 200);
+        // sanity: GET really did render the template
+        expect(get.text).toContain('Test Templates EJS');
+        expect(get.headers['content-type']).toMatch(/text\/html/);
+    });
+
+    test('HEAD on a directly-requested template file → 200, matches GET', async () => {
+        const { get } = await expectHeadMatchesGet(request, '/ejs-templates/simple.ejs', 200);
+        expect(get.text).toContain('Hello from EJS');
+    });
+
+    test('HEAD on a static file → 200, matches GET', async () => {
+        const { head } = await expectHeadMatchesGet(request, '/test.txt', 200);
+        // static branch advertises range support
+        expect(head.headers['accept-ranges']).toBe('bytes');
+    });
+
+    test('HEAD on a listable directory (no index) → 200, matches GET', async () => {
+        const { get } = await expectHeadMatchesGet(request, '/cartella/', 200);
+        expect(get.headers['content-type']).toMatch(/text\/html/);
+    });
+
+    test('HEAD on a non-existent template path → 404, matches GET', async () => {
+        const get = await request.get('/ejs-templates/non-existent.ejs');
+        const head = await request.head('/ejs-templates/non-existent.ejs');
+        expect(get.status).toBe(404);
+        expect(head.status).toBe(404);
+        expect(head.headers['content-type']).toBe(get.headers['content-type']);
+        expect(head.text).toBeFalsy();
+    });
+
+    test('HEAD on a non-existent static path → 404, matches GET', async () => {
+        const get = await request.get('/does-not-exist.txt');
+        const head = await request.head('/does-not-exist.txt');
+        expect(get.status).toBe(404);
+        expect(head.status).toBe(404);
+        expect(head.text).toBeFalsy();
+    });
+});
+
+describe('HEAD method — template engine routes (method-agnostic render, no regression)', () => {
+    let server;
+    let request;
+    beforeAll(() => { server = buildServer(naiveRender); request = supertest(server); });
+    afterAll(() => server.close());
+
+    test('HEAD on template index still matches GET → 200', async () => {
+        await expectHeadMatchesGet(request, '/ejs-templates/', 200);
+    });
+
+    test('HEAD on direct template still matches GET → 200', async () => {
+        await expectHeadMatchesGet(request, '/ejs-templates/simple.ejs', 200);
+    });
+
+    test('HEAD on non-existent template → 404', async () => {
+        const head = await request.head('/ejs-templates/non-existent.ejs');
+        expect(head.status).toBe(404);
+        expect(head.text).toBeFalsy();
+    });
+});

package/__tests__/hidden-option.test.js

@@ -7,66 +7,16 @@ const root = path.join(__dirname, 'hidden-fixtures');
 
 function createApp(hiddenOpts) {
   const app = new Koa();
-  app.use(koaClassicServer(root, { showDirContents: true, hidden: hiddenOpts }));
+  app.use(koaClassicServer(root, { dirListing: { enabled: true }, hidden: hiddenOpts }));
   return app.listen();
 }
 
-// ─── Implicit default warning ─────────────────────────────────────────────────
-// This describe block MUST be first: the warning flag is module-level and fires
-// only once per Jest worker process.  Jest isolates each test FILE into its own
-// module registry, so the flag starts as false when this file loads.
-
-describe('hidden option — implicit default warning', () => {
-  let warnSpy;
-
-  beforeAll(() => {
-    warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
-  });
-
-  afterAll(() => {
-    warnSpy.mockRestore();
-  });
-
-  test('warns when dotFiles.default and dotDirs.default are not explicitly set', () => {
-    warnSpy.mockClear();
-    koaClassicServer(root, {}); // no hidden config at all — both defaults implicit
-    const warnings = warnSpy.mock.calls.filter(c =>
-      c[1] && c[1].includes('dotFiles') && c[1].includes('dotDirs')
-    );
-    expect(warnings.length).toBe(1);
-    expect(warnings[0][1]).toContain('hidden.dotFiles.default');
-    expect(warnings[0][1]).toContain('v3.0.0');
-  });
-
-  test('does not warn again on subsequent calls (once per process)', () => {
-    warnSpy.mockClear();
-    koaClassicServer(root, {}); // flag already set from the test above
-    const warnings = warnSpy.mock.calls.filter(c =>
-      c[1] && c[1].includes('dotFiles')
-    );
-    expect(warnings.length).toBe(0);
-  });
-
-  test('no warning when both dotFiles.default and dotDirs.default are explicitly set', () => {
-    // Use jest.isolateModules to obtain a fresh copy of index.cjs whose flag is false,
-    // then verify that an explicit configuration emits no warning.
-    let fresh;
-    jest.isolateModules(() => {
-      fresh = require('../index.cjs');
-    });
-    warnSpy.mockClear();
-    fresh(root, {
-      hidden: {
-        dotFiles: { default: 'hidden' },
-        dotDirs:  { default: 'visible' },
-      }
-    });
-    const warnings = warnSpy.mock.calls.filter(c =>
-      c[1] && c[1].includes('dotFiles')
-    );
-    expect(warnings.length).toBe(0);
-  });
-});
+// Note: prior to v3.0.0 the dotFiles default was 'hidden' (a v3-alpha
+// security-by-default choice) and a once-per-process warning was emitted
+// when the option was implicit. The default was reverted to 'visible' to
+// align with the "HTTP file server first" design philosophy (see
+// CLAUDE.md). The warning is no longer emitted because the default is no
+// longer a surprising restriction; tests for it have been removed.
 
 // ─── Option validation ────────────────────────────────────────────────────────
 
@@ -100,14 +50,49 @@ describe('hidden option — validation', () => {
   });
 });
 
-// ─── dotFiles default: 'hidden' (system default) ─────────────────────────────
+// ─── dotFiles — default visible (system default in v3.0+) ────────────────────
 
-describe('dotFiles — default hidden (system default)', () => {
+describe('dotFiles — default visible (system default)', () => {
   let server;
   beforeAll(() => { server = createApp(undefined); });
   afterAll(() => server.close());
 
-  test('GET /.env returns 404', async () => {
+  // Per the V3 "HTTP file server first" philosophy (see CLAUDE.md), dot-files
+  // are visible by default. Operators harden by setting hidden.dotFiles.default
+  // to 'hidden' or by using blacklist / alwaysHide.
+  test('GET /.env returns 200 by default', async () => {
+    const res = await supertest(server).get('/.env');
+    expect(res.status).toBe(200);
+  });
+
+  test('GET /.gitignore returns 200 by default', async () => {
+    const res = await supertest(server).get('/.gitignore');
+    expect(res.status).toBe(200);
+  });
+
+  test('directory listing includes dot-files', async () => {
+    const res = await supertest(server).get('/');
+    expect(res.status).toBe(200);
+    expect(res.text).toContain('.env');
+    expect(res.text).toContain('.gitignore');
+  });
+
+  test('regular files remain accessible', async () => {
+    const res = await supertest(server).get('/normal.txt');
+    expect(res.status).toBe(200);
+  });
+});
+
+// ─── dotFiles default: 'hidden' (opt-in hardening) ───────────────────────────
+
+describe('dotFiles — explicit default hidden (opt-in)', () => {
+  let server;
+  beforeAll(() => {
+    server = createApp({ dotFiles: { default: 'hidden' } });
+  });
+  afterAll(() => server.close());
+
+  test('GET /.env returns 404 when dotFiles.default = "hidden"', async () => {
     const res = await supertest(server).get('/.env');
     expect(res.status).toBe(404);
   });
@@ -139,7 +124,7 @@ describe('dotFiles — default hidden (system default)', () => {
   });
 });
 
-// ─── dotFiles default: 'visible' ─────────────────────────────────────────────
+// ─── dotFiles default: 'visible' (kept for completeness with explicit opt-in) ─
 
 describe('dotFiles — default visible', () => {
   let server;
@@ -400,9 +385,9 @@ describe('alwaysHide — secondary to dotFiles whitelist', () => {
 
 // ─── deep tree: dot-files hidden at any depth ─────────────────────────────────
 
-describe('hidden entries at any depth in directory tree', () => {
+describe('hidden entries at any depth in directory tree (opt-in dotFiles.default=hidden)', () => {
   let server;
-  beforeAll(() => { server = createApp(undefined); });
+  beforeAll(() => { server = createApp({ dotFiles: { default: 'hidden' } }); });
   afterAll(() => server.close());
 
   test('GET /subdir/.env returns 404 (dot-file hidden at any depth)', async () => {

package/__tests__/hideExtension.test.js

@@ -31,7 +31,7 @@ describe('hideExtension option tests', () => {
         beforeAll(() => {
             app = new Koa();
             app.use(koaClassicServer(rootDir, {
-                showDirContents: true,
+                dirListing: { enabled: true },
                 index: ['index.ejs'],
                 hideExtension: { ext: '.ejs' },
                 template: {
@@ -83,7 +83,7 @@ describe('hideExtension option tests', () => {
         beforeAll(() => {
             app = new Koa();
             app.use(koaClassicServer(rootDir, {
-                showDirContents: true,
+                dirListing: { enabled: true },
                 index: ['index.ejs'],
                 hideExtension: { ext: '.ejs' },
                 template: {
@@ -141,7 +141,7 @@ describe('hideExtension option tests', () => {
         beforeAll(() => {
             app = new Koa();
             app.use(koaClassicServer(rootDir, {
-                showDirContents: true,
+                dirListing: { enabled: true },
                 index: ['index.ejs'],
                 hideExtension: { ext: '.ejs', redirect: 302 }
             }));
@@ -159,15 +159,15 @@ describe('hideExtension option tests', () => {
     });
 
     // ==========================================
-    // Directory/file conflict (showDirContents: true)
+    // Directory/file conflict (dirListing: { enabled: true })
     // ==========================================
-    describe('Directory/file conflict with showDirContents: true', () => {
+    describe('Directory/file conflict with dirListing: { enabled: true }', () => {
         let app, server, request;
 
         beforeAll(() => {
             app = new Koa();
             app.use(koaClassicServer(rootDir, {
-                showDirContents: true,
+                dirListing: { enabled: true },
                 index: ['index.html'],
                 hideExtension: { ext: '.ejs' },
                 template: {
@@ -208,7 +208,7 @@ describe('hideExtension option tests', () => {
         beforeAll(() => {
             app = new Koa();
             app.use(koaClassicServer(rootDir, {
-                showDirContents: true,
+                dirListing: { enabled: true },
                 hideExtension: { ext: '.ejs' }
             }));
             server = app.listen();
@@ -232,7 +232,7 @@ describe('hideExtension option tests', () => {
         beforeAll(() => {
             app = new Koa();
             app.use(koaClassicServer(rootDir, {
-                showDirContents: true,
+                dirListing: { enabled: true },
                 hideExtension: { ext: '.ejs' },
                 template: {
                     ext: ['ejs'],
@@ -275,7 +275,7 @@ describe('hideExtension option tests', () => {
             });
 
             const middleware = koaClassicServer(rootDir, {
-                showDirContents: true,
+                dirListing: { enabled: true },
                 index: ['index.ejs'],
                 urlsReserved: ['/blog'],
                 hideExtension: { ext: '.ejs' },
@@ -335,7 +335,7 @@ describe('hideExtension option tests', () => {
             });
 
             app.use(koaClassicServer(rootDir, {
-                showDirContents: true,
+                dirListing: { enabled: true },
                 useOriginalUrl: false,
                 hideExtension: { ext: '.ejs' },
                 template: {
@@ -377,7 +377,7 @@ describe('hideExtension option tests', () => {
         beforeAll(() => {
             app = new Koa();
             app.use(koaClassicServer(rootDir, {
-                showDirContents: true,
+                dirListing: { enabled: true },
                 hideExtension: { ext: '.ejs' }
             }));
             server = app.listen();
@@ -404,7 +404,7 @@ describe('hideExtension option tests', () => {
         beforeAll(() => {
             app = new Koa();
             app.use(koaClassicServer(rootDir, {
-                showDirContents: true,
+                dirListing: { enabled: true },
                 hideExtension: { ext: '.ejs' }
             }));
             server = app.listen();
@@ -442,7 +442,7 @@ describe('hideExtension option tests', () => {
         beforeAll(() => {
             app = new Koa();
             app.use(koaClassicServer(rootDir, {
-                showDirContents: true,
+                dirListing: { enabled: true },
                 index: ['index.ejs'],
                 hideExtension: { ext: '.ejs' },
                 template: {
@@ -547,4 +547,61 @@ describe('hideExtension option tests', () => {
             }).not.toThrow();
         });
     });
+
+    // ==========================================
+    // Security: open-redirect via protocol-relative URL
+    // ==========================================
+    describe('Open-redirect guard on hideExtension Location header', () => {
+        let app, server, port;
+
+        beforeAll((done) => {
+            app = new Koa();
+            app.use(koaClassicServer(rootDir, {
+                dirListing: { enabled: true },
+                hideExtension: { ext: '.ejs' }
+            }));
+            server = app.listen(0, () => {
+                port = server.address().port;
+                done();
+            });
+        });
+
+        afterAll(() => { server.close(); });
+
+        // Send the request path as raw bytes so the leading "//" survives any
+        // client-side URL normalization. supertest/url.parse would collapse it.
+        function rawGet(path) {
+            const http = require('http');
+            return new Promise((resolve, reject) => {
+                const req = http.request({
+                    host: '127.0.0.1',
+                    port,
+                    method: 'GET',
+                    path
+                }, (res) => {
+                    res.resume();
+                    resolve({ status: res.statusCode, location: res.headers.location });
+                });
+                req.on('error', reject);
+                req.end();
+            });
+        }
+
+        test('GET //evil.com/foo.ejs → Location must not be protocol-relative', async () => {
+            const res = await rawGet('//evil.com/foo.ejs');
+            expect(res.status).toBe(301);
+            expect(res.location).toBeDefined();
+            // The Location must not start with "//" or "/\" (would navigate off-origin)
+            expect(res.location.startsWith('//')).toBe(false);
+            expect(res.location.startsWith('/\\')).toBe(false);
+            expect(res.location).toBe('/evil.com/foo');
+        });
+
+        test('GET ///a/b.ejs → leading slashes collapsed in Location', async () => {
+            const res = await rawGet('///a/b.ejs');
+            expect(res.status).toBe(301);
+            expect(res.location.startsWith('//')).toBe(false);
+            expect(res.location).toBe('/a/b');
+        });
+    });
 });

package/__tests__/index.test.js

@@ -33,7 +33,7 @@ const filesAndDirArray = getFilesRecursivelySync(rootDir);
 const options0 = {  
   urlPrefix: '/public', // Il prefisso URL che il middleware dovrà intercettare
   method: ['GET'],// I metodi HTTP ammessi (default 'GET')
-  showDirContents: true,// Se mostrare il contenuto della directory in caso di richiesta ad una cartella
+  dirListing: { enabled: true },// Se mostrare il contenuto della directory in caso di richiesta ad una cartella
   //index: 'index.html', // Nome del file index da cercare all'interno di una directory (se presente)
 };
 
@@ -79,7 +79,7 @@ describe(` koaClassicServer options0: ${JSON.stringify(options0)}`, () => {
 //START option1
 const options1 = {
   method: ['GET'],
-  showDirContents: true,
+  dirListing: { enabled: true },
 };
 
 describe(` koaClassicServer options1: ${JSON.stringify(options1)}`, () => {
@@ -114,7 +114,7 @@ describe(` koaClassicServer options1: ${JSON.stringify(options1)}`, () => {
 //STASRT option2
 const options2 = {
   method: ['GET'],
-  showDirContents: false,
+  dirListing: { enabled: false },
   index: ['index.html'],
 };
 
@@ -141,7 +141,7 @@ describe(` koaClassicServer options2: ${JSON.stringify(options2)}`, () => {
 //STASRT option3
 const options3 = {
   method: ['GET'],
-  showDirContents: false,
+  dirListing: { enabled: false },
   urlsReserved : Array('/percorso_riservato', '/percorso riservato con spazi')
 };
 
@@ -188,7 +188,7 @@ describe(` koaClassicServer options2: ${JSON.stringify(options2)}`, () => {
   // I metodi HTTP ammessi (default 'GET')
   method: ['GET'],
   // Se mostrare il contenuto della directory in caso di richiesta ad una cartella
-  showDirContents: true,
+  dirListing: { enabled: true },
   // Nome del file index da cercare all'interno di una directory (se presente)
   //index: 'index.html',
 }; */
@@ -268,7 +268,7 @@ function testAllPathByFileList(filesAndDirArray, getServer, options) {
             const responseBody = res.text !== undefined ? res.text : res.body.toString('utf8');
             expect(responseBody).toBe(content);
           } else {//è una directory
-            if( options.showDirContents === false ){
+            if( options.dirListing && options.dirListing.enabled === false ){
               // FIX: Quando directory listing è disabilitato, restituisce 404
               expect(res.status).toBe(404);
               expect(res.type).toBe('text/html');