koa-classic-server 1.1.0 → 2.0.0

package/DEBUG_REPORT.md

@@ -0,0 +1,593 @@
+# DEBUG REPORT - koa-classic-server
+
+**Data Analisi:** 2025-11-17
+**Versione Analizzata:** 1.1.0
+**Branch:** claude/featuring-koa-smart-server-016TZsdaPURgHLiQHmCFJFsk
+
+---
+
+## Sommario Esecutivo
+
+Sono stati identificati **8 problemi** di cui:
+- 🔴 **CRITICI:** 2 (sicurezza)
+- 🟠 **ALTA PRIORITÀ:** 3 (funzionalità core)
+- 🟡 **MEDIA PRIORITÀ:** 2 (robustezza)
+- 🔵 **BASSA PRIORITÀ:** 1 (qualità codice)
+
+---
+
+## 🔴 PROBLEMI CRITICI
+
+### 1. Path Traversal Vulnerability (CRITICO - SICUREZZA)
+
+**Location:** `index.cjs:104`
+
+**Codice:**
+```javascript
+toOpen = rootDir + decodeURIComponent(pageHrefOutPrefix.pathname);
+```
+
+**Problema:**
+Non c'è validazione del path per prevenire attacchi di path traversal. Un attaccante può accedere a file al di fuori di `rootDir`.
+
+**Attacco Esempio:**
+```
+GET /../../../etc/passwd
+GET /../config/database.yml
+GET /../.env
+```
+
+**Impatto:**
+- Accesso non autorizzato a file sensibili del server
+- Potenziale lettura di credenziali, configurazioni, chiavi private
+- Violazione della sicurezza del sistema
+
+**Severità:** 🔴 CRITICA
+
+**Fix Raccomandato:**
+```javascript
+const path = require('path');
+
+// Normalizza e verifica che il path risultante sia dentro rootDir
+const requestedPath = path.normalize(decodeURIComponent(pageHrefOutPrefix.pathname));
+const fullPath = path.join(rootDir, requestedPath);
+
+// Verifica che il path finale sia dentro rootDir
+if (!fullPath.startsWith(path.resolve(rootDir))) {
+    ctx.status = 403;
+    ctx.body = 'Forbidden';
+    return;
+}
+
+toOpen = fullPath;
+```
+
+**Riferimenti:**
+- OWASP: Path Traversal
+- CWE-22: Improper Limitation of a Pathname to a Restricted Directory
+
+---
+
+### 2. Mancanza di Gestione Errori Template Rendering (CRITICO - DISPONIBILITÀ)
+
+**Location:** `index.cjs:167`
+
+**Codice:**
+```javascript
+await options.template.render(ctx, next, toOpen);
+```
+
+**Problema:**
+Nessun try-catch attorno alla chiamata `template.render`. Se il rendering fallisce, l'errore non gestito può crashare l'applicazione.
+
+**Impatto:**
+- Crash del server su errore di rendering
+- Denial of Service potenziale
+- Esperienza utente degradata
+
+**Severità:** 🔴 CRITICA
+
+**Fix Raccomandato:**
+```javascript
+if (options.template.ext.includes(fileExt)) {
+    try {
+        await options.template.render(ctx, next, toOpen);
+        return;
+    } catch (error) {
+        console.error('Template rendering error:', error);
+        ctx.status = 500;
+        ctx.body = 'Internal Server Error - Template Rendering Failed';
+        return;
+    }
+}
+```
+
+---
+
+## 🟠 PROBLEMI ALTA PRIORITÀ
+
+### 3. Status Code 404 Non Settato (ALTA - STANDARD HTTP)
+
+**Location:**
+- `index.cjs:110` (file non esiste)
+- `index.cjs:128` (directory listing disabilitato)
+
+**Codice:**
+```javascript
+// Linea 110
+if (!fs.existsSync(toOpen)) {
+    ctx.body = requestedUrlNotFound();
+    // Manca: ctx.status = 404;
+    return;
+}
+
+// Linea 128
+} else {
+    // allora non devo mostrare il contenuto della directory
+    ctx.body = requestedUrlNotFound();
+    // Manca: ctx.status = 404;
+}
+```
+
+**Problema:**
+Quando una risorsa non viene trovata, viene restituito un body HTML con "Not Found", ma lo status HTTP rimane 200 (OK) invece di 404 (Not Found).
+
+**Impatto:**
+- Violazione standard HTTP
+- Cache proxy potrebbero cachare errori come successi
+- SEO negativo (motori di ricerca indicizzano pagine 404 come valide)
+- Client non possono distinguere successo da errore basandosi sullo status code
+
+**Verifica:**
+```bash
+curl -I http://localhost:3000/file-che-non-esiste.txt
+# Atteso: HTTP/1.1 404 Not Found
+# Attuale: HTTP/1.1 200 OK
+```
+
+**Severità:** 🟠 ALTA
+
+**Fix Raccomandato:**
+```javascript
+// Linea 110
+if (!fs.existsSync(toOpen)) {
+    ctx.status = 404;
+    ctx.body = requestedUrlNotFound();
+    return;
+}
+
+// Linea 128
+} else {
+    ctx.status = 404;
+    ctx.body = requestedUrlNotFound();
+}
+```
+
+---
+
+### 4. Race Condition nella Lettura File (ALTA - AFFIDABILITÀ)
+
+**Location:** `index.cjs:107-172`
+
+**Codice:**
+```javascript
+if (!fs.existsSync(toOpen)) {
+    // ...
+}
+// ... altre operazioni ...
+const src = fs.createReadStream(toOpen);  // Linea 172
+```
+
+**Problema:**
+C'è un gap temporale (TOCTOU - Time-of-check to Time-of-use) tra:
+1. Controllo esistenza file (`existsSync`)
+2. Lettura file (`createReadStream`)
+
+Se il file viene cancellato tra questi due momenti, `createReadStream` lancia un errore non gestito.
+
+**Impatto:**
+- Possibile crash del server
+- Errore non gestito raggiunge l'utente
+- Log inquinati da stack trace
+
+**Severità:** 🟠 ALTA
+
+**Fix Raccomandato:**
+```javascript
+async function loadFile(toOpen) {
+    // Template rendering logic...
+
+    try {
+        // Verifica esistenza prima di stream
+        await fs.promises.access(toOpen, fs.constants.R_OK);
+
+        let mimeType = mime.lookup(toOpen);
+        const src = fs.createReadStream(toOpen);
+
+        // Gestisci errori stream
+        src.on('error', (err) => {
+            console.error('Stream error:', err);
+            if (!ctx.headerSent) {
+                ctx.status = 500;
+                ctx.body = 'Error reading file';
+            }
+        });
+
+        ctx.response.set("content-type", mimeType);
+        ctx.response.set("content-disposition",
+            `inline; filename=${pageHrefOutPrefix.pathname.substring(1)}`);
+        ctx.body = src;
+    } catch (error) {
+        console.error('File access error:', error);
+        ctx.status = 404;
+        ctx.body = requestedUrlNotFound();
+    }
+}
+```
+
+---
+
+### 5. Estrazione Estensione File Fragile (ALTA - ROBUSTEZZA)
+
+**Location:** `index.cjs:163-164`
+
+**Codice:**
+```javascript
+const a_path = toOpen.split(".");
+const fileExt = a_path[a_path.length - 1];
+```
+
+**Problema:**
+Metodo fragile per estrarre l'estensione:
+- File senza estensione: `README` → estensione = "README" (errato)
+- File con più punti: `archive.tar.gz` → estensione = "gz" (potrebbe essere errato)
+- File nascosti Unix: `.gitignore` → estensione = "gitignore" (errato)
+- Path con punti: `/folder.backup/file` → estensione = "backup/file" (errato)
+
+**Impatto:**
+- Template rendering potrebbe attivarsi su file sbagliati
+- File nascosti potrebbero essere processati erroneamente
+
+**Severità:** 🟠 ALTA
+
+**Fix Raccomandato:**
+```javascript
+const path = require('path');
+
+async function loadFile(toOpen) {
+    if (options.template.ext.length > 0) {
+        // Usa path.extname che gestisce correttamente tutti i casi
+        const fileExt = path.extname(toOpen).slice(1); // .slice(1) rimuove il punto
+
+        if (fileExt && options.template.ext.includes(fileExt)) {
+            try {
+                await options.template.render(ctx, next, toOpen);
+                return;
+            } catch (error) {
+                console.error('Template rendering error:', error);
+                ctx.status = 500;
+                ctx.body = 'Internal Server Error';
+                return;
+            }
+        }
+    }
+    // ... resto del codice
+}
+```
+
+---
+
+## 🟡 PROBLEMI MEDIA PRIORITÀ
+
+### 6. Mancanza Gestione Errori fs.readdirSync (MEDIA - ROBUSTEZZA)
+
+**Location:** `index.cjs:183`
+
+**Codice:**
+```javascript
+function show_dir(toOpen) {
+    dir = fs.readdirSync(toOpen, { withFileTypes: true }); // possibile error error.code == "ENOENT" ???
+```
+
+**Problema:**
+Il commento stesso riconosce il problema: `readdirSync` può lanciare errori (permessi insufficienti, directory cancellata, etc.) ma non c'è gestione.
+
+**Errori Possibili:**
+- `ENOENT`: Directory non esiste più
+- `EACCES`: Permessi insufficienti
+- `ENOTDIR`: Path non è una directory
+
+**Impatto:**
+- Crash su errori filesystem
+- Messaggi di errore criptici all'utente
+
+**Severità:** 🟡 MEDIA
+
+**Fix Raccomandato:**
+```javascript
+function show_dir(toOpen) {
+    let dir;
+    try {
+        dir = fs.readdirSync(toOpen, { withFileTypes: true });
+    } catch (error) {
+        console.error('Directory read error:', error);
+        return `
+            <!DOCTYPE html>
+            <html>
+            <head><title>Error</title></head>
+            <body>
+                <h1>Error Reading Directory</h1>
+                <p>Unable to access directory contents.</p>
+            </body>
+            </html>
+        `;
+    }
+
+    // ... resto della funzione
+}
+```
+
+---
+
+### 7. Gestione Inconsistente Content-Disposition (MEDIA - QUALITÀ)
+
+**Location:** `index.cjs:174-177`
+
+**Codice:**
+```javascript
+ctx.response.set(
+    "content-disposition",
+    `inline; filename=${pageHrefOutPrefix.pathname.substring(1)}`
+);
+```
+
+**Problema:**
+Il filename in Content-Disposition non è quotato e non è sanitizzato:
+- Caratteri speciali nel filename potrebbero causare problemi
+- Spazi e caratteri non-ASCII non sono gestiti
+- Secondo RFC 6266, il filename dovrebbe essere quotato se contiene caratteri speciali
+
+**Impatto:**
+- Download file con nomi strani potrebbero fallire
+- Alcuni browser potrebbero interpretare male il filename
+
+**Severità:** 🟡 MEDIA
+
+**Fix Raccomandato:**
+```javascript
+const path = require('path');
+
+// Estrai solo il basename, non l'intero path
+const filename = path.basename(pageHrefOutPrefix.pathname);
+
+// Quota il filename per sicurezza
+ctx.response.set(
+    "content-disposition",
+    `inline; filename="${filename.replace(/"/g, '\\"')}"`
+);
+
+// O ancora meglio, usa una libreria come content-disposition:
+// const contentDisposition = require('content-disposition');
+// ctx.response.set("content-disposition", contentDisposition(filename, { type: 'inline' }));
+```
+
+---
+
+## 🔵 PROBLEMI BASSA PRIORITÀ
+
+### 8. Uso di Array() Invece di [] (BASSA - STILE)
+
+**Location:** Multiple locations
+
+**Codice:**
+```javascript
+options.method = Array.isArray( options.method ) ? options.method : Array('GET');
+options.urlsReserved = Array.isArray( options.urlsReserved ) ? options.urlsReserved : Array();
+options.template.ext = ( Array.isArray(options.template.ext) ) ? options.template.ext : Array();
+```
+
+**Problema:**
+`Array('GET')` crea un array con un elemento, ma è meno idiomatico di `['GET']`. Inoltre `Array()` è meno leggibile di `[]`.
+
+**Impatto:**
+- Nessun impatto funzionale
+- Ridotta leggibilità codice
+
+**Severità:** 🔵 BASSA
+
+**Fix Raccomandato:**
+```javascript
+options.method = Array.isArray(options.method) ? options.method : ['GET'];
+options.urlsReserved = Array.isArray(options.urlsReserved) ? options.urlsReserved : [];
+options.template.ext = Array.isArray(options.template.ext) ? options.template.ext : [];
+```
+
+---
+
+## Test dei Problemi
+
+### Test Path Traversal (Problema #1)
+
+```javascript
+// test-path-traversal.js
+const supertest = require('supertest');
+const Koa = require('koa');
+const koaClassicServer = require('./index.cjs');
+
+const app = new Koa();
+app.use(koaClassicServer(__dirname + '/public'));
+const server = app.listen();
+
+// Test attacco path traversal
+supertest(server)
+    .get('/../package.json')  // Tenta di accedere fuori da public/
+    .end((err, res) => {
+        console.log('Status:', res.status);
+        console.log('Body contains package.json?', res.text.includes('"name"'));
+        // Se vedi il contenuto di package.json, la vulnerabilità è confermata
+        server.close();
+    });
+```
+
+### Test Status Code 404 (Problema #3)
+
+```javascript
+// test-404-status.js
+const supertest = require('supertest');
+const Koa = require('koa');
+const koaClassicServer = require('./index.cjs');
+
+const app = new Koa();
+app.use(koaClassicServer(__dirname + '/public'));
+const server = app.listen();
+
+supertest(server)
+    .get('/file-che-non-esiste.txt')
+    .end((err, res) => {
+        console.log('Status Code:', res.status);
+        console.log('Expected: 404, Got:', res.status);
+        console.log('BUG CONFIRMED:', res.status === 200); // true = bug presente
+        server.close();
+    });
+```
+
+### Test Template Error (Problema #2)
+
+```javascript
+// test-template-error.js
+const Koa = require('koa');
+const koaClassicServer = require('./index.cjs');
+
+const app = new Koa();
+
+// Template render che lancia errore
+const brokenRender = async (ctx, next, filePath) => {
+    throw new Error('Simulated template error');
+};
+
+app.use(koaClassicServer(__dirname + '/public', {
+    template: {
+        render: brokenRender,
+        ext: ['html']
+    }
+}));
+
+const server = app.listen(3000);
+
+// Accedi a un file .html
+// Il server crasherà con errore non gestito
+```
+
+---
+
+## Priorità di Fix
+
+### Immediate (Prima del Deploy)
+1. **Path Traversal** (Problema #1) - CRITICO
+2. **Status Code 404** (Problema #3) - ALTA
+
+### Breve Termine (Prossimo Release)
+3. **Template Error Handling** (Problema #2) - CRITICO
+4. **Race Condition File** (Problema #4) - ALTA
+5. **Estrazione Estensione** (Problema #5) - ALTA
+
+### Medio Termine (Miglioramenti)
+6. **fs.readdirSync Error** (Problema #6) - MEDIA
+7. **Content-Disposition** (Problema #7) - MEDIA
+
+### Opzionale (Refactoring)
+8. **Array() vs []** (Problema #8) - BASSA
+
+---
+
+## Miglioramenti Generali Raccomandati
+
+### 1. Aggiungere Validazione Input
+```javascript
+// All'inizio della funzione principale
+if (!rootDir || typeof rootDir !== 'string') {
+    throw new TypeError('rootDir must be a non-empty string');
+}
+
+if (!path.isAbsolute(rootDir)) {
+    throw new Error('rootDir must be an absolute path');
+}
+```
+
+### 2. Logging Strutturato
+```javascript
+// Opzione per logging
+options.logger = options.logger || console;
+
+// Usa nel codice
+options.logger.error('File not found:', toOpen);
+options.logger.warn('Template rendering failed:', error);
+```
+
+### 3. Timeout per Template Rendering
+```javascript
+// Previeni template rendering infiniti
+const renderWithTimeout = (renderFn, timeout = 5000) => {
+    return Promise.race([
+        renderFn(),
+        new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('Render timeout')), timeout)
+        )
+    ]);
+};
+```
+
+### 4. Sanitizzazione HTML in Directory Listing
+```javascript
+// Previeni XSS in nomi file
+function escapeHtml(unsafe) {
+    return unsafe
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#039;");
+}
+
+// Usa quando mostri nomi file
+s_dir += ` <a href="${itemUri}">${escapeHtml(s_name)}</a>`;
+```
+
+---
+
+## Metriche Codice
+
+### Complessità Ciclomatica
+- **Funzione principale:** ~25 (Alta - da ridurre)
+- **show_dir:** ~15 (Media)
+- **loadFile:** ~5 (Bassa)
+
+### Raccomandazione
+Spezzare la funzione principale in sottofunzioni più piccole:
+- `validateRequest()`
+- `checkReservedUrls()`
+- `resolveFilePath()`
+- `handleResource()`
+
+---
+
+## Conclusioni
+
+Il progetto koa-classic-server presenta **2 vulnerabilità critiche di sicurezza** che devono essere risolte immediatamente prima di qualsiasi deploy in produzione:
+
+1. **Path Traversal** - permette accesso a file arbitrari
+2. **Template Error Unhandled** - può causare crash del server
+
+Inoltre, ci sono **3 problemi di alta priorità** che impattano conformità agli standard HTTP e affidabilità:
+
+3. Status code 404 mancante
+4. Race condition nella lettura file
+5. Estrazione estensione fragile
+
+**Raccomandazione:** Implementare i fix per problemi #1, #2, #3 prima del prossimo release.
+
+---
+
+**Report compilato da:** Claude Code Analysis
+**Branch analizzata:** claude/featuring-koa-smart-server-016TZsdaPURgHLiQHmCFJFsk
+**Commit:** f8693a0