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

package/__tests__/security-headers.test.js

@@ -1,11 +1,21 @@
 const supertest = require('supertest');
+const crypto = require('crypto');
 const koaClassicServer = require('../index.cjs');
 const Koa = require('koa');
 const path = require('path');
 
 const root = path.join(__dirname, 'publicWwwTest');
 
-const LISTING_CSP = "default-src 'none'; style-src 'sha256-9izM/ygZXy3xF1fZ8DQP0Tovpqy5fBMn4e6vf7Xs04A='; frame-ancestors 'none'; base-uri 'none'; form-action 'none'";
+// Compute the expected CSP hash from the actual inline CSS in the response, so
+// CSS edits to the listing template do not require updating a hardcoded hash here.
+async function expectedListingCsp(server, requestPath = '/') {
+    const res = await supertest(server).get(requestPath);
+    const m = res.text.match(/<style>([\s\S]*?)<\/style>/);
+    if (!m) throw new Error('No <style> block in listing HTML — cannot compute expected CSP');
+    const cssHash = 'sha256-' + crypto.createHash('sha256').update(m[1], 'utf8').digest('base64');
+    return `default-src 'none'; style-src '${cssHash}'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'`;
+}
+
 const NOT_FOUND_CSP = "default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'";
 
 const COMMON_HEADERS = {
@@ -17,7 +27,7 @@ const COMMON_HEADERS = {
 
 function createApp(opts = {}) {
   const app = new Koa();
-  app.use(koaClassicServer(root, { showDirContents: true, ...opts }));
+  app.use(koaClassicServer(root, { dirListing: { enabled: true }, ...opts }));
   return app.listen();
 }
 
@@ -30,7 +40,7 @@ describe('Security headers — directory listing page', () => {
 
   test('Content-Security-Policy uses hash-based style-src', async () => {
     const res = await supertest(server).get('/');
-    expect(res.headers['content-security-policy']).toBe(LISTING_CSP);
+    expect(res.headers['content-security-policy']).toBe(await expectedListingCsp(server));
   });
 
   test('X-Content-Type-Options: nosniff', async () => {
@@ -62,8 +72,10 @@ describe('Security headers — directory listing page', () => {
 
   test('CSP style-src hash in listing matches actual inline CSS', async () => {
     const res = await supertest(server).get('/');
-    // The hash must appear in the CSP header
-    expect(res.headers['content-security-policy']).toContain('sha256-9izM/ygZXy3xF1fZ8DQP0Tovpqy5fBMn4e6vf7Xs04A=');
+    const styleMatch = res.text.match(/<style>([\s\S]*?)<\/style>/);
+    expect(styleMatch).toBeTruthy();
+    const expectedHash = 'sha256-' + crypto.createHash('sha256').update(styleMatch[1], 'utf8').digest('base64');
+    expect(res.headers['content-security-policy']).toContain(expectedHash);
   });
 });
 
@@ -93,11 +105,11 @@ describe('Security headers — 404 Not Found page', () => {
   });
 });
 
-// ─── Directory listing disabled (showDirContents: false) ─────────────────────
+// ─── Directory listing disabled (dirListing: { enabled: false }) ─────────────────────
 
 describe('Security headers — 404 when directory listing disabled', () => {
   let server;
-  beforeAll(() => { server = createApp({ showDirContents: false }); });
+  beforeAll(() => { server = createApp({ dirListing: { enabled: false } }); });
   afterAll(() => server.close());
 
   test('Security headers present when directory listing disabled', async () => {
@@ -145,7 +157,7 @@ describe('Security headers — subdirectory listing page', () => {
   test('Listing of subdirectory also has security headers', async () => {
     const res = await supertest(server).get('/cartella/');
     expect(res.status).toBe(200);
-    expect(res.headers['content-security-policy']).toBe(LISTING_CSP);
+    expect(res.headers['content-security-policy']).toBe(await expectedListingCsp(server, '/cartella/'));
     for (const [header, value] of Object.entries(COMMON_HEADERS)) {
       expect(res.headers[header]).toBe(value);
     }

package/__tests__/security.test.js

@@ -22,7 +22,7 @@ describe('Security Tests - Path Traversal', () => {
   beforeAll(() => {
     app = new Koa();
     app.use(koaClassicServer(rootDir, {
-      showDirContents: true
+      dirListing: { enabled: true }
     }));
     server = app.listen();
   });
@@ -79,7 +79,7 @@ describe('Bug Tests - Status Code 404', () => {
   beforeAll(() => {
     app = new Koa();
     app.use(koaClassicServer(rootDir, {
-      showDirContents: true
+      dirListing: { enabled: true }
     }));
     server = app.listen();
   });
@@ -90,10 +90,10 @@ describe('Bug Tests - Status Code 404', () => {
     expect(res.text).toContain('Not Found');
   });
 
-  test('FIXED: Directory with showDirContents=false returns 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();
 
@@ -235,7 +235,7 @@ describe('Bug Tests - Directory Read Errors', () => {
     const tempDir = path.join(rootDir, 'temp-perm-test-dir');
     if (!fs.existsSync(tempDir)) fs.mkdirSync(tempDir);
 
-    app.use(koaClassicServer(rootDir, { showDirContents: true }));
+    app.use(koaClassicServer(rootDir, { dirListing: { enabled: true } }));
     const server = app.listen();
 
     try {

package/__tests__/server-cache.test.js

@@ -28,7 +28,7 @@ const fixturesDir = path.join(__dirname, 'server-cache-fixtures');
 
 function createApp(opts = {}) {
     const app = new Koa();
-    app.use(koaClassicServer(fixturesDir, { showDirContents: false, ...opts }));
+    app.use(koaClassicServer(fixturesDir, { dirListing: { enabled: false }, ...opts }));
     return app.listen();
 }
 
@@ -124,7 +124,7 @@ describe('serverCache.rawFile — cache invalidation on file change', () => {
 
         const app = new Koa();
         app.use(koaClassicServer(tmpDir, {
-            showDirContents: false,
+            dirListing: { enabled: false },
             serverCache: { rawFile: { enabled: true } }
         }));
         server = app.listen();
@@ -156,6 +156,177 @@ describe('serverCache.rawFile — cache invalidation on file change', () => {
     });
 });
 
+// ─── maxAge: factory validation ───────────────────────────────────────────────
+
+describe('serverCache.*.maxAge — factory validation', () => {
+    test('rejects negative rawFile.maxAge', () => {
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { rawFile: { enabled: true, maxAge: -1 } }
+        })).toThrow(/rawFile\.maxAge must be a finite number/);
+    });
+
+    test('rejects NaN rawFile.maxAge', () => {
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { rawFile: { enabled: true, maxAge: NaN } }
+        })).toThrow(/rawFile\.maxAge must be a finite number/);
+    });
+
+    test('rejects Infinity rawFile.maxAge', () => {
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { rawFile: { enabled: true, maxAge: Infinity } }
+        })).toThrow(/rawFile\.maxAge must be a finite number/);
+    });
+
+    test('rejects string rawFile.maxAge', () => {
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { rawFile: { enabled: true, maxAge: '5000' } }
+        })).toThrow(/rawFile\.maxAge must be a finite number/);
+    });
+
+    test('rejects negative compressedFile.maxAge', () => {
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { compressedFile: { maxAge: -1 } }
+        })).toThrow(/compressedFile\.maxAge must be a finite number/);
+    });
+
+    test('accepts 0 (disabled) and positive integers', () => {
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { rawFile: { enabled: true, maxAge: 0 } }
+        })).not.toThrow();
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { rawFile: { enabled: true, maxAge: 1000 } }
+        })).not.toThrow();
+    });
+});
+
+// ─── maxAge: rawFile staleness ────────────────────────────────────────────────
+
+describe('serverCache.rawFile.maxAge — time-based staleness', () => {
+    // Verify maxAge triggers a fresh disk read even when mtime+size are unchanged.
+    // Simulates the NFS attribute-cache scenario by manually restoring mtime after
+    // editing the file, so the mtime-based invariant alone cannot detect the change.
+    let tmpDir;
+    let filePath;
+    let server;
+
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kcs-maxage-raw-'));
+        filePath = path.join(tmpDir, 'data.txt');
+        fs.writeFileSync(filePath, 'version-A');
+
+        const app = new Koa();
+        app.use(koaClassicServer(tmpDir, {
+            dirListing: { enabled: false },
+            serverCache: { rawFile: { enabled: true, maxAge: 100 } }
+        }));
+        server = app.listen();
+    });
+
+    afterAll(() => {
+        server.close();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    test('within maxAge: cache is served (no disk re-read)', async () => {
+        const first = await supertest(server).get('/data.txt').set('Accept-Encoding', 'identity');
+        expect(first.text).toBe('version-A');
+
+        // Replace content but freeze mtime to its original value (simulates NFS lying about mtime).
+        // Length must stay identical so the size check doesn't invalidate independently of maxAge.
+        const originalStat = fs.statSync(filePath);
+        fs.writeFileSync(filePath, 'version-B'); // same 9 bytes as 'version-A'
+        fs.utimesSync(filePath, originalStat.atime, originalStat.mtime);
+
+        // Within maxAge → stale check passes → still serves cached A
+        const second = await supertest(server).get('/data.txt').set('Accept-Encoding', 'identity');
+        expect(second.text).toBe('version-A');
+    });
+
+    test('after maxAge: cache is refreshed (disk re-read) even when mtime+size unchanged', async () => {
+        await new Promise(r => setTimeout(r, 120)); // exceeds 100 ms maxAge
+
+        const third = await supertest(server).get('/data.txt').set('Accept-Encoding', 'identity');
+        expect(third.text).toBe('version-B');
+    });
+});
+
+describe('serverCache.rawFile.maxAge — disabled (0) preserves previous behaviour', () => {
+    let tmpDir;
+    let server;
+
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kcs-maxage-off-'));
+        fs.writeFileSync(path.join(tmpDir, 'stable.txt'), 'unchanged');
+
+        const app = new Koa();
+        app.use(koaClassicServer(tmpDir, {
+            dirListing: { enabled: false },
+            serverCache: { rawFile: { enabled: true, maxAge: 0 } }
+        }));
+        server = app.listen();
+    });
+
+    afterAll(() => {
+        server.close();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    test('cache served indefinitely while mtime+size unchanged', async () => {
+        await supertest(server).get('/stable.txt').set('Accept-Encoding', 'identity');
+        await new Promise(r => setTimeout(r, 150));
+        const res = await supertest(server).get('/stable.txt').set('Accept-Encoding', 'identity');
+        expect(res.status).toBe(200);
+        expect(res.text).toBe('unchanged');
+    });
+});
+
+// ─── maxAge: compressedFile staleness ─────────────────────────────────────────
+
+describe('serverCache.compressedFile.maxAge — time-based staleness', () => {
+    let tmpDir;
+    let filePath;
+    let server;
+
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kcs-maxage-cmp-'));
+        filePath = path.join(tmpDir, 'data.css');
+        fs.writeFileSync(filePath, 'a'.repeat(2048)); // above minFileSize=1024 to ensure compression
+
+        const app = new Koa();
+        app.use(koaClassicServer(tmpDir, {
+            dirListing: { enabled: false },
+            serverCache: { compressedFile: { maxAge: 100 } }
+        }));
+        server = app.listen();
+    });
+
+    afterAll(() => {
+        server.close();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    test('after maxAge, compressed cache is rebuilt from updated content', async () => {
+        const first = await supertest(server).get('/data.css').set('Accept-Encoding', 'gzip');
+        expect(first.status).toBe(200);
+        expect(first.headers['content-encoding']).toBe('gzip');
+        expect(first.text).toBe('a'.repeat(2048));
+
+        // Replace content with same length, freeze mtime to simulate NFS staleness.
+        const originalStat = fs.statSync(filePath);
+        fs.writeFileSync(filePath, 'b'.repeat(2048));
+        fs.utimesSync(filePath, originalStat.atime, originalStat.mtime);
+
+        // Within maxAge → cached gzip of A still served.
+        const second = await supertest(server).get('/data.css').set('Accept-Encoding', 'gzip');
+        expect(second.text).toBe('a'.repeat(2048));
+
+        // After maxAge → cache refreshed → gzip of B served.
+        await new Promise(r => setTimeout(r, 120));
+        const third = await supertest(server).get('/data.css').set('Accept-Encoding', 'gzip');
+        expect(third.text).toBe('b'.repeat(2048));
+    });
+});
+
 // ─── rawFile + Range requests ─────────────────────────────────────────────────
 
 describe('serverCache.rawFile — Range request served from buffer', () => {
@@ -194,7 +365,7 @@ describe('serverCache.rawFile + compression — rawFile feeds compressedFile', (
     let server;
     beforeAll(() => {
         server = createApp({
-            compression: { minSize: false }, // compress small.txt too
+            compression: { minFileSize: false }, // compress small.txt too
             serverCache: { rawFile: { enabled: true } }
         });
     });
@@ -276,7 +447,7 @@ describe('serverCache.rawFile — LFU eviction when maxSize exceeded', () => {
 
         const app = new Koa();
         app.use(koaClassicServer(tmpDir, {
-            showDirContents: false,
+            dirListing: { enabled: false },
             serverCache: {
                 rawFile: {
                     enabled: true,
@@ -321,7 +492,7 @@ describe('serverCache.rawFile — warnInterval throttles warnings', () => {
 
         const app = new Koa();
         app.use(koaClassicServer(tmpDir, {
-            showDirContents: false,
+            dirListing: { enabled: false },
             serverCache: {
                 rawFile: {
                     enabled: true,
@@ -360,7 +531,7 @@ describe('serverCache.rawFile — buffer passed as 4th param to render function'
 
         const app = new Koa();
         app.use(koaClassicServer(tmpDir, {
-            showDirContents: false,
+            dirListing: { enabled: false },
             serverCache: { rawFile: { enabled: true } },
             template: {
                 ext: ['tmpl'],
@@ -404,7 +575,7 @@ describe('serverCache.rawFile — buffer passed as 4th param to render function'
         let bufferWhenDisabled;
         const appNoCache = new Koa();
         appNoCache.use(koaClassicServer(tmpDir, {
-            showDirContents: false,
+            dirListing: { enabled: false },
             // rawFile.enabled: false by default
             template: {
                 ext: ['tmpl'],

package/__tests__/symlink.test.js

@@ -124,7 +124,7 @@ describeIfSymlinks('koa-classic-server - symlink support', () => {
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['index.html'],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             server = app.listen();
             request = supertest(server);
@@ -150,7 +150,7 @@ describeIfSymlinks('koa-classic-server - symlink support', () => {
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['index.ejs'],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             server = app.listen();
             request = supertest(server);
@@ -177,7 +177,7 @@ describeIfSymlinks('koa-classic-server - symlink support', () => {
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             server = app.listen();
             request = supertest(server);
@@ -210,7 +210,7 @@ describeIfSymlinks('koa-classic-server - symlink support', () => {
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['index.ejs'],
-                showDirContents: true,
+                dirListing: { enabled: true },
                 template: {
                     ext: ['ejs'],
                     render: async (ctx, next, filePath) => {
@@ -244,7 +244,7 @@ describeIfSymlinks('koa-classic-server - symlink support', () => {
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             server = app.listen();
             request = supertest(server);
@@ -275,7 +275,7 @@ describeIfSymlinks('koa-classic-server - symlink support', () => {
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             server = app.listen();
             request = supertest(server);
@@ -301,7 +301,7 @@ describeIfSymlinks('koa-classic-server - symlink support', () => {
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             server = app.listen();
             request = supertest(server);
@@ -330,7 +330,7 @@ describeIfSymlinks('koa-classic-server - symlink support', () => {
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['index.html'],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             server = app.listen();
             request = supertest(server);
@@ -356,7 +356,7 @@ describeIfSymlinks('koa-classic-server - symlink support', () => {
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             server = app.listen();
             request = supertest(server);
@@ -422,7 +422,7 @@ describeIfSymlinks('koa-classic-server - symlink support', () => {
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [/index\.[eE][jJ][sS]/],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             server = app.listen();
             request = supertest(server);