koa-classic-server 2.6.1 → 3.0.0

package/__tests__/security.test.js

@@ -1,7 +1,7 @@
 //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 //
 //  SECURITY & BUG TESTS
-//  Questi test verificano le vulnerabilità e i bug identificati nel DEBUG_REPORT.md
+//  These tests verify the security properties and bug fixes documented in DEBUG_REPORT.md
 //
 //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
@@ -13,6 +13,8 @@ const path = require('path');
 
 const rootDir = path.join(__dirname, 'publicWwwTest');
 
+// ─── Path Traversal ───────────────────────────────────────────────────────────
+
 describe('Security Tests - Path Traversal', () => {
   let app;
   let server;
@@ -20,44 +22,56 @@ describe('Security Tests - Path Traversal', () => {
   beforeAll(() => {
     app = new Koa();
     app.use(koaClassicServer(rootDir, {
-      showDirContents: true
+      dirListing: { enabled: true }
     }));
     server = app.listen();
   });
 
-  test('VULNERABILITY: Path traversal con ../ dovrebbe essere bloccato', async () => {
-    // Tenta di accedere al file package.json che è fuori da publicWwwTest
-    const res = await supertest(server).get('/../package.json');
+  afterAll(() => {
+    server.close();
+  });
 
-    // Il file NON dovrebbe essere accessibile
-    // ATTUALMENTE FALLISCE - questa è la vulnerabilità!
-    // expect(res.status).toBe(403); // Dovrebbe essere forbidden
-    // expect(res.text).not.toContain('"name"'); // Non dovrebbe vedere il contenuto
+  // On Linux, path.normalize() cannot escape '/' (the OS root), so '/../package.json'
+  // resolves to rootDir/package.json — which simply does not exist → 404.
+  // On Windows, backslash sequences can escape rootDir and the startsWith() check
+  // fires → 403. Both outcomes prove the traversal was blocked (no 200 with file content).
 
-    // Per ora verifichiamo che la vulnerabilità esista
-    console.log('⚠️  Path Traversal Test - Status:', res.status);
-    // Se vedi status 200 e contenuto di package.json, la vulnerabilità è confermata
+  test('../ traversal is blocked (403 or 404, never 200 with file content)', async () => {
+    const res = await supertest(server).get('/../package.json');
+    expect([403, 404]).toContain(res.status);
+    expect(res.text).not.toContain('"name"');
   });
 
-  test('VULNERABILITY: Path traversal con encoding dovrebbe essere bloccato', async () => {
-    // Tenta con encoding URL
+  test('URL-encoded ../ traversal (%2e%2e%2f) is blocked (403 or 404)', async () => {
     const res = await supertest(server).get('/%2e%2e%2f%2e%2e%2fpackage.json');
-
-    console.log('⚠️  Path Traversal Encoded Test - Status:', res.status);
+    expect([403, 404]).toContain(res.status);
+    expect(res.text).not.toContain('"name"');
   });
 
-  test('VULNERABILITY: Path traversal assoluto dovrebbe essere bloccato', async () => {
-    // Tenta path assoluto
+  test('multi-level traversal (/../../../etc/hosts) is blocked (403 or 404)', async () => {
     const res = await supertest(server).get('/../../../etc/hosts');
+    expect([403, 404]).toContain(res.status);
+  });
 
-    console.log('⚠️  Path Traversal Absolute Test - Status:', res.status);
+  test('null byte in path is rejected with 400', async () => {
+    // path.normalize() throws ERR_INVALID_ARG_VALUE for paths with \0;
+    // the null byte guard returns 400 before reaching fs operations.
+    const res = await supertest(server).get('/file%00.txt');
+    expect(res.status).toBe(400);
   });
 
-  afterAll(() => {
-    server.close();
+  test('backslash sequences are not treated as path separators on Linux', async () => {
+    // On Linux, \\ is a literal filename character, not a path separator.
+    // path.normalize leaves it intact and the resolved path stays within rootDir.
+    // The file simply does not exist → 404 (not a traversal escape).
+    const res = await supertest(server).get('/..%5C..%5Cetc%5Chosts');
+    expect([403, 404]).toContain(res.status);
+    // On Windows, path.normalize converts \ to / and the traversal check catches it → 403.
   });
 });
 
+// ─── Status Code 404 ─────────────────────────────────────────────────────────
+
 describe('Bug Tests - Status Code 404', () => {
   let app;
   let server;
@@ -65,34 +79,25 @@ describe('Bug Tests - Status Code 404', () => {
   beforeAll(() => {
     app = new Koa();
     app.use(koaClassicServer(rootDir, {
-      showDirContents: true
+      dirListing: { enabled: true }
     }));
     server = app.listen();
   });
 
-  test('FIXED: File inesistente dovrebbe restituire status 404', async () => {
+  test('FIXED: Non-existent file returns 404', async () => {
     const res = await supertest(server).get('/file-che-non-esiste-xyz123.txt');
-
-    console.log('✅ 404 Status Test - Status Code:', res.status);
-    console.log('   Expected: 404, Got:', res.status);
-
-    // FIXED: Now returns proper 404 status
     expect(res.status).toBe(404);
     expect(res.text).toContain('Not Found');
   });
 
-  test('FIXED: Directory con showDirContents=false dovrebbe restituire 404', async () => {
+  test('FIXED: Directory with dirListing.enabled=false returns 404', async () => {
     const app2 = new Koa();
     app2.use(koaClassicServer(rootDir, {
-      showDirContents: false
+      dirListing: { enabled: false }
     }));
     const server2 = app2.listen();
 
     const res = await supertest(server2).get('/');
-
-    console.log('✅ 404 Directory Test - Status Code:', res.status);
-
-    // FIXED: Now returns proper 404 status
     expect(res.status).toBe(404);
 
     server2.close();
@@ -103,11 +108,12 @@ describe('Bug Tests - Status Code 404', () => {
   });
 });
 
+// ─── Template Rendering Errors ────────────────────────────────────────────────
+
 describe('Bug Tests - Template Rendering Errors', () => {
-  test('BUG: Template render error dovrebbe essere gestito, non crashare', async () => {
+  test('FIXED: Template render error returns 500 HTML page, server does not crash', async () => {
     const app = new Koa();
 
-    // Template che lancia errore
     const brokenRender = async (ctx, next, filePath) => {
       throw new Error('Simulated template rendering error');
     };
@@ -115,39 +121,29 @@ describe('Bug Tests - Template Rendering Errors', () => {
     app.use(koaClassicServer(rootDir, {
       template: {
         render: brokenRender,
-        ext: ['txt'] // Usa .txt per test
+        ext: ['txt']
       }
     }));
 
     const server = app.listen();
-
-    // Crea un file .txt per il test
     const testFile = path.join(rootDir, 'test-template.txt');
     fs.writeFileSync(testFile, 'test content');
 
     try {
       const res = await supertest(server).get('/test-template.txt');
 
-      console.log('🐛 Template Error Test - Status:', res.status);
-
-      // Dovrebbe gestire l'errore e restituire 500
-      // expect(res.status).toBe(500);
-
-      // ATTUALMENTE POTREBBE CRASHARE IL SERVER
-      // Se arriviamo qui senza crash, il test passa
-      console.log('   Server did not crash (good)');
-    } catch (error) {
-      console.log('⚠️  Template error caused request to fail:', error.message);
+      expect(res.status).toBe(500);
+      expect(res.headers['content-type']).toMatch(/html/);
+      expect(res.text).toContain('Internal Server Error');
     } finally {
-      // Cleanup
-      if (fs.existsSync(testFile)) {
-        fs.unlinkSync(testFile);
-      }
+      if (fs.existsSync(testFile)) fs.unlinkSync(testFile);
       server.close();
     }
   });
 });
 
+// ─── File Extension Extraction ────────────────────────────────────────────────
+
 describe('Bug Tests - File Extension Extraction', () => {
   let app;
   let server;
@@ -155,10 +151,7 @@ describe('Bug Tests - File Extension Extraction', () => {
   beforeAll(() => {
     app = new Koa();
 
-    let renderCalled = false;
     const trackingRender = async (ctx, next, filePath) => {
-      renderCalled = true;
-      ctx.renderCalled = true;
       ctx.body = 'Rendered: ' + path.basename(filePath);
     };
 
@@ -172,134 +165,96 @@ describe('Bug Tests - File Extension Extraction', () => {
     server = app.listen();
   });
 
-  test('BUG: File senza estensione non dovrebbe attivare template rendering', async () => {
-    // Crea file senza estensione
+  afterAll(() => {
+    server.close();
+  });
+
+  test('FIXED: File without extension does not trigger template rendering', async () => {
     const testFile = path.join(rootDir, 'README');
     fs.writeFileSync(testFile, 'readme content');
 
     try {
       const res = await supertest(server).get('/README');
-
-      console.log('🐛 No Extension Test - Render called?', res.text.includes('Rendered'));
-
-      // Non dovrebbe essere renderizzato
-      expect(res.text).not.toContain('Rendered');
+      const responseBody = res.text !== undefined ? res.text : res.body.toString('utf8');
+      expect(responseBody).not.toContain('Rendered');
     } finally {
-      if (fs.existsSync(testFile)) {
-        fs.unlinkSync(testFile);
-      }
+      if (fs.existsSync(testFile)) fs.unlinkSync(testFile);
     }
   });
 
-  test('BUG: File nascosto Unix non dovrebbe essere trattato con estensione sbagliata', async () => {
-    // Crea file nascosto
+  test('Unix hidden file (.gitignore) is served as a regular file, not rendered', async () => {
+    // dotFiles are hidden by default; make them visible for this test so we can
+    // verify that the extension check (not the template renderer) handles the file.
+    const appVisible = new Koa();
+    appVisible.use(koaClassicServer(rootDir, {
+      hidden: { dotFiles: { default: 'visible' } },
+      template: {
+        render: async (ctx, next, filePath) => { ctx.body = 'Rendered: ' + path.basename(filePath); },
+        ext: ['txt']
+      }
+    }));
+    const serverVisible = appVisible.listen();
+
     const testFile = path.join(rootDir, '.gitignore');
     fs.writeFileSync(testFile, 'node_modules/');
 
     try {
-      const res = await supertest(server).get('/.gitignore');
-
-      console.log('🐛 Hidden File Test - Status:', res.status);
-
-      // .gitignore non ha estensione .txt, non dovrebbe essere renderizzato
-      // Ma con il bug attuale, potrebbe essere processato come estensione "gitignore"
+      const res = await supertest(serverVisible).get('/.gitignore');
+      // .gitignore has no .txt extension — template must not be invoked
+      expect(res.status).toBe(200);
+      const responseBody = res.text !== undefined ? res.text : res.body.toString('utf8');
+      expect(responseBody).not.toContain('Rendered');
+      expect(responseBody).toContain('node_modules/');
     } finally {
-      if (fs.existsSync(testFile)) {
-        fs.unlinkSync(testFile);
-      }
+      if (fs.existsSync(testFile)) fs.unlinkSync(testFile);
+      serverVisible.close();
     }
   });
-
-  afterAll(() => {
-    server.close();
-  });
 });
 
-describe('Bug Tests - Race Condition File Access', () => {
-  test('BUG: File cancellato tra check ed access dovrebbe essere gestito', async () => {
-    const app = new Koa();
-    app.use(koaClassicServer(rootDir));
-    const server = app.listen();
-
-    // Crea file temporaneo
-    const testFile = path.join(rootDir, 'temp-race-test.txt');
-    fs.writeFileSync(testFile, 'temporary content');
-
-    // Simula race condition: cancella il file appena dopo la richiesta
-    setTimeout(() => {
-      if (fs.existsSync(testFile)) {
-        fs.unlinkSync(testFile);
-      }
-    }, 5);
-
-    try {
-      const res = await supertest(server).get('/temp-race-test.txt');
-
-      console.log('🐛 Race Condition Test - Status:', res.status);
+// ─── Race Condition File Access ───────────────────────────────────────────────
+//
+// BEHAVIOUR GUARANTEE (not tested — timing is non-deterministic):
+//   If a file is deleted between the access check and the stream open,
+//   the stream error handler fires and — if headers have not been sent yet —
+//   the server returns 500. When rawFile cache is warm the race cannot occur
+//   because the file is served entirely from memory.
+//
+// ─────────────────────────────────────────────────────────────────────────────
 
-      // Dovrebbe gestire l'errore gracefully
-      // expect(res.status).toBe(404) o 500;
-    } catch (error) {
-      console.log('⚠️  Race condition caused error:', error.message);
-    } finally {
-      // Cleanup
-      if (fs.existsSync(testFile)) {
-        fs.unlinkSync(testFile);
-      }
-      server.close();
-    }
-  });
-});
+// ─── Directory Read Errors ────────────────────────────────────────────────────
 
 describe('Bug Tests - Directory Read Errors', () => {
-  test('BUG: Errore lettura directory dovrebbe essere gestito', async () => {
-    const app = new Koa();
-
-    // Crea una directory temporanea
-    const tempDir = path.join(rootDir, 'temp-test-dir');
-    if (!fs.existsSync(tempDir)) {
-      fs.mkdirSync(tempDir);
-    }
+  test('FIXED: Unreadable directory returns 500, server does not crash', async () => {
+    // Skip on Windows (chmod has no effect) and when running as root
+    // (root ignores permission bits, so chmod 0o000 has no effect).
+    if (process.platform === 'win32') return;
+    if (typeof process.getuid === 'function' && process.getuid() === 0) return;
 
-    app.use(koaClassicServer(rootDir, {
-      showDirContents: true
-    }));
+    const app = new Koa();
+    const tempDir = path.join(rootDir, 'temp-perm-test-dir');
+    if (!fs.existsSync(tempDir)) fs.mkdirSync(tempDir);
 
+    app.use(koaClassicServer(rootDir, { dirListing: { enabled: true } }));
     const server = app.listen();
 
     try {
-      // Prima richiesta normale
-      const res1 = await supertest(server).get('/temp-test-dir');
+      const res1 = await supertest(server).get('/temp-perm-test-dir');
       expect(res1.status).toBe(200);
 
-      // Ora cambia i permessi (solo su Unix)
-      if (process.platform !== 'win32') {
-        fs.chmodSync(tempDir, 0o000); // Nessun permesso
-
-        const res2 = await supertest(server).get('/temp-test-dir');
-
-        console.log('🐛 Directory Permission Test - Status:', res2.status);
-
-        // Dovrebbe gestire l'errore
-        // expect(res2.status).toBe(500) o 403;
-      }
-    } catch (error) {
-      console.log('⚠️  Directory read error:', error.message);
+      fs.chmodSync(tempDir, 0o000);
+      const res2 = await supertest(server).get('/temp-perm-test-dir');
+      expect([403, 500]).toContain(res2.status);
     } finally {
-      // Ripristina permessi e cleanup
-      if (process.platform !== 'win32' && fs.existsSync(tempDir)) {
-        try {
-          fs.chmodSync(tempDir, 0o755);
-        } catch (e) {}
-      }
-      if (fs.existsSync(tempDir)) {
-        fs.rmdirSync(tempDir);
-      }
+      try { fs.chmodSync(tempDir, 0o755); } catch { /* ignore */ }
+      if (fs.existsSync(tempDir)) fs.rmdirSync(tempDir);
       server.close();
     }
   });
 });
 
+// ─── Content-Disposition ──────────────────────────────────────────────────────
+
 describe('Bug Tests - Content-Disposition', () => {
   let app;
   let server;
@@ -310,27 +265,58 @@ describe('Bug Tests - Content-Disposition', () => {
     server = app.listen();
   });
 
-  test('BUG: Filename con caratteri speciali dovrebbe essere quotato', async () => {
-    // Crea file con spazi e caratteri speciali
+  afterAll(() => {
+    server.close();
+  });
+
+  test('FIXED: Filename with spaces is quoted in Content-Disposition', async () => {
+    const testFile = path.join(rootDir, 'file with spaces.txt');
+    fs.writeFileSync(testFile, 'test content');
+
+    try {
+      const res = await supertest(server).get('/file%20with%20spaces.txt');
+      const contentDisp = res.headers['content-disposition'];
+      // quoted-string form must wrap the filename in double quotes
+      expect(contentDisp).toMatch(/filename="file with spaces\.txt"/);
+    } finally {
+      if (fs.existsSync(testFile)) fs.unlinkSync(testFile);
+    }
+  });
+
+  test('FIXED: Filename with special chars has RFC 5987 extended form', async () => {
     const testFile = path.join(rootDir, 'file with spaces & special.txt');
     fs.writeFileSync(testFile, 'test content');
 
     try {
       const res = await supertest(server).get('/file%20with%20spaces%20%26%20special.txt');
-
       const contentDisp = res.headers['content-disposition'];
-      console.log('🐛 Content-Disposition:', contentDisp);
-
-      // Dovrebbe essere quotato
-      // expect(contentDisp).toMatch(/"file with spaces & special.txt"/);
+      // RFC 5987 extended form must be present with UTF-8 encoding prefix
+      expect(contentDisp).toMatch(/filename\*=UTF-8''/);
+      // The & must be percent-encoded as %26 in the extended form
+      expect(contentDisp).toContain('%26');
     } finally {
-      if (fs.existsSync(testFile)) {
-        fs.unlinkSync(testFile);
-      }
+      if (fs.existsSync(testFile)) fs.unlinkSync(testFile);
     }
   });
 
-  afterAll(() => {
-    server.close();
+  test('FIXED: Filename with double-quote is safely escaped', async () => {
+    // Create file with a double-quote in its name (valid on Linux)
+    let testFile;
+    try {
+      testFile = path.join(rootDir, 'file"name.txt');
+      fs.writeFileSync(testFile, 'test');
+    } catch {
+      // Some filesystems disallow " in filenames — skip gracefully
+      return;
+    }
+
+    try {
+      const res = await supertest(server).get('/file%22name.txt');
+      const contentDisp = res.headers['content-disposition'];
+      // The " inside the quoted-string must be escaped as \"
+      expect(contentDisp).toMatch(/filename="file\\"name\.txt"/);
+    } finally {
+      if (fs.existsSync(testFile)) fs.unlinkSync(testFile);
+    }
   });
 });

package/__tests__/server-cache-fixtures/large.txt

@@ -0,0 +1 @@
+BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB

package/__tests__/server-cache-fixtures/small.txt

@@ -0,0 +1 @@
+AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA