koa-classic-server 2.6.1 → 3.0.0

package/__tests__/dt-unknown.test.js

@@ -97,7 +97,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['index.html'],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -120,7 +120,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['subdir'],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -143,7 +143,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['nonexistent.html'],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -172,7 +172,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['index.html'],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -190,14 +190,18 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
         });
 
         test('should return false for DT_UNKNOWN entry pointing to a regular file', async () => {
-            // Files should NOT be treated as directories
-            // If only files exist and no index pattern matches, dir listing should show
+            // Files should NOT be treated as directories.
+            // Use a RegExp index pattern to force the readdir-based slow-path in
+            // findIndexFile (the string fast-path uses stat() directly and would bypass
+            // the mock). The regex never matches, so no index file is found and the
+            // directory listing is shown, confirming the DT_UNKNOWN files are treated
+            // as regular files (not directories).
             const spy = mockReaddirWithDtUnknown(tmpDir, ['style.css', 'readme.txt']);
 
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
-                index: ['index.html'],
-                showDirContents: true
+                index: [/NOMATCH_SENTINEL/],
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -224,7 +228,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['index.html'],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -246,7 +250,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['index.ejs'],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -254,8 +258,9 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             try {
                 const res = await request.get('/');
                 expect(res.status).toBe(200);
-                expect(res.text).toContain('EJS DT_UNKNOWN');
-                expect(res.text).not.toContain('Index of');
+                const body = res.text !== undefined ? res.text : res.body.toString('utf8');
+                expect(body).toContain('EJS DT_UNKNOWN');
+                expect(body).not.toContain('Index of');
             } finally {
                 server.close();
                 spy.mockRestore();
@@ -268,7 +273,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [/index\.[eE][jJ][sS]/],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -276,8 +281,9 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             try {
                 const res = await request.get('/');
                 expect(res.status).toBe(200);
-                expect(res.text).toContain('EJS DT_UNKNOWN');
-                expect(res.text).not.toContain('Index of');
+                const body = res.text !== undefined ? res.text : res.body.toString('utf8');
+                expect(body).toContain('EJS DT_UNKNOWN');
+                expect(body).not.toContain('Index of');
             } finally {
                 server.close();
                 spy.mockRestore();
@@ -285,12 +291,17 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
         });
 
         test('should not find index in directory with only subdirectories (all DT_UNKNOWN)', async () => {
+            // Use a RegExp to force the readdir-based slow-path (the string fast-path
+            // would stat() index.html directly, finding the real file on disk).
+            // The regex never matches, so the mocked readdir result (['subdir']) is used:
+            // 'subdir' has DT_UNKNOWN → stat fallback → isDirectory() → not a file →
+            // fileNames stays empty → no index found → directory listing shown.
             const spy = mockReaddirWithDtUnknown(tmpDir, ['subdir']);
 
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
-                index: ['index.html'],
-                showDirContents: true
+                index: [/NOMATCH_SENTINEL/],
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -298,7 +309,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             try {
                 const res = await request.get('/');
                 expect(res.status).toBe(200);
-                // No file matches index.html, so directory listing should appear
+                // No file matches the pattern, so directory listing should appear
                 expect(res.text).toContain('Index of');
             } finally {
                 server.close();
@@ -317,7 +328,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -345,7 +356,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -375,7 +386,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -399,7 +410,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -429,7 +440,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['index.html'],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -454,7 +465,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -475,7 +486,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -511,7 +522,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['index.ejs'],
-                showDirContents: true,
+                dirListing: { enabled: true },
                 template: {
                     ext: ['ejs'],
                     render: async (ctx, next, filePath) => {
@@ -562,7 +573,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: [],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -604,7 +615,7 @@ describe('DT_UNKNOWN filesystem support (NixOS buildFHSEnv, overlayfs, FUSE)', (
             const app = new Koa();
             app.use(koaClassicServer(tmpDir, {
                 index: ['index.html', 'index.ejs'],
-                showDirContents: true
+                dirListing: { enabled: true }
             }));
             const server = app.listen();
             const request = supertest(server);

package/__tests__/ejs.test.js

@@ -19,7 +19,7 @@ describe('EJS Template Engine Integration Tests', () => {
         app.use(
             koaClassicServer(rootDir, {
                 method: ['GET'],
-                showDirContents: true,
+                dirListing: { enabled: true },
                 template: {
                     ext: ['ejs'],
                     render: async (ctx, next, filePath) => {

package/__tests__/hidden-fixtures/.dot-dir/inside.txt

@@ -0,0 +1 @@
+dot dir file

package/__tests__/hidden-fixtures/.env

@@ -0,0 +1,2 @@
+SECRET_KEY=mysecretvalue
+DB_PASSWORD=hidden123

package/__tests__/hidden-fixtures/.well-known/acme-challenge.txt

@@ -0,0 +1 @@
+acme

package/__tests__/hidden-fixtures/config/secrets/password.txt

@@ -0,0 +1 @@
+password

package/__tests__/hidden-fixtures/data.key

@@ -0,0 +1 @@
+key data

package/__tests__/hidden-fixtures/file.secret

@@ -0,0 +1 @@
+secret data

package/__tests__/hidden-fixtures/index.html

@@ -0,0 +1 @@
+regular

package/__tests__/hidden-fixtures/normal.txt

@@ -0,0 +1 @@
+normal

package/__tests__/hidden-fixtures/subdir/.env

@@ -0,0 +1 @@
+NESTED_SECRET=nestedvalue

package/__tests__/hidden-fixtures/subdir/regular.txt

@@ -0,0 +1 @@
+regular in subdir

package/__tests__/hidden-option.test.js

@@ -0,0 +1,407 @@
+const supertest = require('supertest');
+const koaClassicServer = require('../index.cjs');
+const Koa = require('koa');
+const path = require('path');
+
+const root = path.join(__dirname, 'hidden-fixtures');
+
+function createApp(hiddenOpts) {
+  const app = new Koa();
+  app.use(koaClassicServer(root, { dirListing: { enabled: true }, hidden: hiddenOpts }));
+  return app.listen();
+}
+
+// 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 ────────────────────────────────────────────────────────
+
+describe('hidden option — validation', () => {
+  test('throws when dotFiles.default is not "hidden" or "visible"', () => {
+    expect(() =>
+      koaClassicServer(root, { hidden: { dotFiles: { default: 'yes' } } })
+    ).toThrow(/hidden\.dotFiles\.default must be "hidden" or "visible"/);
+  });
+
+  test('throws when dotDirs.default is not "hidden" or "visible"', () => {
+    expect(() =>
+      koaClassicServer(root, { hidden: { dotDirs: { default: 'yes' } } })
+    ).toThrow(/hidden\.dotDirs\.default must be "hidden" or "visible"/);
+  });
+
+  test('does not throw when hidden option is omitted', () => {
+    expect(() => koaClassicServer(root, {})).not.toThrow();
+  });
+
+  test('does not throw when hidden is a valid object', () => {
+    expect(() =>
+      koaClassicServer(root, {
+        hidden: {
+          dotFiles: { default: 'hidden', whitelist: ['.well-known'], blacklist: ['.env'] },
+          dotDirs:  { default: 'visible', blacklist: [/^\.git/] },
+          alwaysHide: ['*.secret', /\.key$/]
+        }
+      })
+    ).not.toThrow();
+  });
+});
+
+// ─── dotFiles — default visible (system default in v3.0+) ────────────────────
+
+describe('dotFiles — default visible (system default)', () => {
+  let server;
+  beforeAll(() => { server = createApp(undefined); });
+  afterAll(() => server.close());
+
+  // 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);
+  });
+
+  test('GET /.gitignore returns 404', async () => {
+    const res = await supertest(server).get('/.gitignore');
+    expect(res.status).toBe(404);
+  });
+
+  test('GET /subdir/.env returns 404 (dot-file in subdirectory)', async () => {
+    const res = await supertest(server).get('/subdir/.env');
+    expect(res.status).toBe(404);
+  });
+
+  test('directory listing does not include .env', async () => {
+    const res = await supertest(server).get('/');
+    expect(res.status).toBe(200);
+    expect(res.text).not.toContain('.env');
+  });
+
+  test('directory listing does not include .gitignore', async () => {
+    const res = await supertest(server).get('/');
+    expect(res.text).not.toContain('.gitignore');
+  });
+
+  test('regular files remain accessible', async () => {
+    const res = await supertest(server).get('/normal.txt');
+    expect(res.status).toBe(200);
+  });
+});
+
+// ─── dotFiles default: 'visible' (kept for completeness with explicit opt-in) ─
+
+describe('dotFiles — default visible', () => {
+  let server;
+  beforeAll(() => {
+    server = createApp({ dotFiles: { default: 'visible' } });
+  });
+  afterAll(() => server.close());
+
+  test('GET /.env returns 200 when dotFiles.default is "visible"', async () => {
+    const res = await supertest(server).get('/.env');
+    expect(res.status).toBe(200);
+  });
+
+  test('directory listing includes .env when dotFiles.default is "visible"', async () => {
+    const res = await supertest(server).get('/');
+    expect(res.text).toContain('.env');
+  });
+});
+
+// ─── dotFiles whitelist ───────────────────────────────────────────────────────
+
+describe('dotFiles — whitelist exceptions', () => {
+  let server;
+  beforeAll(() => {
+    server = createApp({
+      dotFiles: { default: 'hidden', whitelist: ['.well-known'] },
+      dotDirs:  { default: 'hidden', whitelist: ['.well-known'] }
+    });
+  });
+  afterAll(() => server.close());
+
+  test('GET /.well-known/ is accessible (whitelisted dir)', async () => {
+    const res = await supertest(server).get('/.well-known/');
+    expect(res.status).toBe(200);
+  });
+
+  test('GET /.well-known/acme-challenge.txt is accessible (inside whitelisted dir)', async () => {
+    const res = await supertest(server).get('/.well-known/acme-challenge.txt');
+    expect(res.status).toBe(200);
+  });
+
+  test('.well-known appears in root listing', async () => {
+    const res = await supertest(server).get('/');
+    expect(res.text).toContain('.well-known');
+  });
+
+  test('GET /.env still returns 404 (not whitelisted)', async () => {
+    const res = await supertest(server).get('/.env');
+    expect(res.status).toBe(404);
+  });
+
+  test('whitelist with RegExp: /^\\.public/ matches .public-assets', async () => {
+    // This tests the regex matching logic; .public-assets doesn't exist so we
+    // expect 404 from "not found", not from "hidden" — indirectly confirms regex is not blocking
+    const server2 = createApp({
+      dotFiles: { default: 'hidden', whitelist: [/^\.public/] }
+    });
+    // .env is not matched by /^\.public/ so it stays hidden
+    const res = await supertest(server2).get('/.env');
+    expect(res.status).toBe(404);
+    server2.close();
+  });
+});
+
+// ─── dotFiles blacklist ───────────────────────────────────────────────────────
+
+describe('dotFiles — blacklist', () => {
+  let server;
+  beforeAll(() => {
+    server = createApp({
+      dotFiles: { default: 'visible', blacklist: ['.env'] }
+    });
+  });
+  afterAll(() => server.close());
+
+  test('GET /.env returns 404 (blacklisted even with default: visible)', async () => {
+    const res = await supertest(server).get('/.env');
+    expect(res.status).toBe(404);
+  });
+
+  test('GET /.gitignore returns 200 (visible, not blacklisted)', async () => {
+    const res = await supertest(server).get('/.gitignore');
+    expect(res.status).toBe(200);
+  });
+
+  test('.env not in listing when blacklisted', async () => {
+    const res = await supertest(server).get('/');
+    expect(res.text).not.toContain('.env');
+  });
+});
+
+// ─── blacklist beats whitelist ────────────────────────────────────────────────
+
+describe('dotFiles — blacklist beats whitelist', () => {
+  let server;
+  beforeAll(() => {
+    server = createApp({
+      dotFiles: { default: 'visible', whitelist: ['.env'], blacklist: ['.env'] }
+    });
+  });
+  afterAll(() => server.close());
+
+  test('GET /.env returns 404 (blacklist wins over whitelist)', async () => {
+    const res = await supertest(server).get('/.env');
+    expect(res.status).toBe(404);
+  });
+});
+
+// ─── dotDirs default: 'visible' (system default) ─────────────────────────────
+
+describe('dotDirs — default visible (system default)', () => {
+  let server;
+  beforeAll(() => { server = createApp(undefined); });
+  afterAll(() => server.close());
+
+  test('.dot-dir appears in root listing by default', async () => {
+    const res = await supertest(server).get('/');
+    expect(res.text).toContain('.dot-dir');
+  });
+
+  test('GET /.dot-dir/ returns 200 (directory listing) by default', async () => {
+    const res = await supertest(server).get('/.dot-dir/');
+    expect(res.status).toBe(200);
+  });
+
+  test('GET /.dot-dir/inside.txt returns 200 by default', async () => {
+    const res = await supertest(server).get('/.dot-dir/inside.txt');
+    expect(res.status).toBe(200);
+  });
+});
+
+// ─── dotDirs blacklist ────────────────────────────────────────────────────────
+
+describe('dotDirs — blacklist', () => {
+  let server;
+  beforeAll(() => {
+    server = createApp({ dotDirs: { blacklist: ['.dot-dir'] } });
+  });
+  afterAll(() => server.close());
+
+  test('GET /.dot-dir/ returns 404 (blacklisted dir)', async () => {
+    const res = await supertest(server).get('/.dot-dir/');
+    expect(res.status).toBe(404);
+  });
+
+  test('GET /.dot-dir/inside.txt returns 404 (inside blocked dir)', async () => {
+    const res = await supertest(server).get('/.dot-dir/inside.txt');
+    expect(res.status).toBe(404);
+  });
+
+  test('.dot-dir not in root listing when blacklisted', async () => {
+    const res = await supertest(server).get('/');
+    expect(res.text).not.toContain('.dot-dir');
+  });
+});
+
+// ─── dotDirs blacklist with RegExp ────────────────────────────────────────────
+
+describe('dotDirs — blacklist with RegExp', () => {
+  let server;
+  beforeAll(() => {
+    server = createApp({ dotDirs: { blacklist: [/^\.dot/] } });
+  });
+  afterAll(() => server.close());
+
+  test('GET /.dot-dir/ returns 404 (RegExp blacklist match)', async () => {
+    const res = await supertest(server).get('/.dot-dir/');
+    expect(res.status).toBe(404);
+  });
+
+  test('.well-known accessible (does not match /^\\.dot/)', async () => {
+    const res = await supertest(server).get('/.well-known/');
+    expect(res.status).toBe(200);
+  });
+});
+
+// ─── alwaysHide ───────────────────────────────────────────────────────────────
+
+describe('alwaysHide — glob and regex patterns', () => {
+  let server;
+  beforeAll(() => {
+    server = createApp({
+      dotFiles: { default: 'visible' }, // dot-files visible so we can test alwaysHide separately
+      alwaysHide: ['*.secret', /\.key$/]
+    });
+  });
+  afterAll(() => server.close());
+
+  test('GET /file.secret returns 404 (glob *.secret)', async () => {
+    const res = await supertest(server).get('/file.secret');
+    expect(res.status).toBe(404);
+  });
+
+  test('GET /data.key returns 404 (regex /\\.key$/)', async () => {
+    const res = await supertest(server).get('/data.key');
+    expect(res.status).toBe(404);
+  });
+
+  test('file.secret not in directory listing', async () => {
+    const res = await supertest(server).get('/');
+    expect(res.text).not.toContain('file.secret');
+  });
+
+  test('data.key not in directory listing', async () => {
+    const res = await supertest(server).get('/');
+    expect(res.text).not.toContain('data.key');
+  });
+
+  test('regular files remain accessible', async () => {
+    const res = await supertest(server).get('/normal.txt');
+    expect(res.status).toBe(200);
+  });
+});
+
+// ─── alwaysHide — path-anchored patterns ─────────────────────────────────────
+
+describe('alwaysHide — path-anchored glob (config/secrets/**)', () => {
+  let server;
+  beforeAll(() => {
+    server = createApp({ alwaysHide: ['config/secrets/**'] });
+  });
+  afterAll(() => server.close());
+
+  test('GET /config/secrets/password.txt returns 404', async () => {
+    const res = await supertest(server).get('/config/secrets/password.txt');
+    expect(res.status).toBe(404);
+  });
+
+  test('password.txt not in /config/secrets/ listing', async () => {
+    const res = await supertest(server).get('/config/secrets/');
+    expect(res.status).toBe(200);
+    expect(res.text).not.toContain('password.txt');
+  });
+
+  test('GET /normal.txt remains accessible (not under config/secrets/)', async () => {
+    const res = await supertest(server).get('/normal.txt');
+    expect(res.status).toBe(200);
+  });
+});
+
+// ─── alwaysHide secondary to whitelist ───────────────────────────────────────
+
+describe('alwaysHide — secondary to dotFiles whitelist', () => {
+  let server;
+  beforeAll(() => {
+    server = createApp({
+      dotFiles: { default: 'hidden', whitelist: ['.env'] },
+      alwaysHide: ['.env']  // both alwaysHide and whitelist target .env
+    });
+  });
+  afterAll(() => server.close());
+
+  test('GET /.env returns 200 (whitelist wins over alwaysHide)', async () => {
+    const res = await supertest(server).get('/.env');
+    expect(res.status).toBe(200);
+  });
+});
+
+// ─── deep tree: dot-files hidden at any depth ─────────────────────────────────
+
+describe('hidden entries at any depth in directory tree (opt-in dotFiles.default=hidden)', () => {
+  let server;
+  beforeAll(() => { server = createApp({ dotFiles: { default: 'hidden' } }); });
+  afterAll(() => server.close());
+
+  test('GET /subdir/.env returns 404 (dot-file hidden at any depth)', async () => {
+    const res = await supertest(server).get('/subdir/.env');
+    expect(res.status).toBe(404);
+  });
+
+  test('/subdir/.env not in /subdir/ listing', async () => {
+    const res = await supertest(server).get('/subdir/');
+    expect(res.text).not.toContain('.env');
+  });
+
+  test('GET /subdir/regular.txt returns 200 (regular file accessible)', async () => {
+    const res = await supertest(server).get('/subdir/regular.txt');
+    expect(res.status).toBe(200);
+  });
+});