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

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');