roster-server 2.2.12 → 2.3.2

package/README.md

@@ -8,6 +8,7 @@ Welcome to **RosterServer**, the ultimate domain host router with automatic HTTP
 
 - **Automatic HTTPS** with Let's Encrypt via Greenlock.
 - **Dynamic Site Loading**: Just drop your Node.js apps in the `www` folder.
+- **Static Sites**: No code? No problem. Drop a folder with `index.html` (and assets) and RosterServer serves it automatically—modular static handler with path-traversal protection and strict 404s.
 - **Virtual Hosting**: Serve multiple domains from a single server.
 - **Automatic Redirects**: Redirect `www` subdomains to the root domain.
 - **Zero Configuration**: Well, almost zero. Just a tiny bit of setup.
@@ -48,12 +49,20 @@ Your project should look something like this:
     │   └── index.js
     ├── subdomain.example.com/
     │   └── index.js
+    ├── static-site.com/        # Static site: no index.js needed
+    │   ├── index.html
+    │   ├── css/
+    │   └── images/
     ├── other-domain.com/
     │   └── index.js
     └── *.example.com/          # Wildcard: one handler for all subdomains (api.example.com, app.example.com, etc.)
         └── index.js
 ```
 
+Each domain folder can have either:
+- **Node app**: `index.js`, `index.mjs`, or `index.cjs` (exporting a request handler).
+- **Static site**: `index.html` (and any assets). If no JS entry exists, RosterServer serves the folder as static files. Node takes precedence when both exist.
+
 ### Wildcard DNS (*.example.com)
 
 You can serve all subdomains of a domain with a single handler in three ways:
@@ -107,7 +116,10 @@ server.start();
 
 ### Your Site Handlers
 
-Each domain should have its own folder under `www`, containing an `index.js` that exports a request handler function.
+Each domain has its own folder under `www`. You can use:
+
+- **Node app**: Put `index.js` (or `index.mjs` / `index.cjs`) that exports a request handler function.
+- **Static site**: Put `index.html` and your assets (CSS, JS, images). RosterServer will serve files from that folder. `GET /` serves `index.html`; other paths serve the file if it exists, or 404. Path traversal is blocked. If both an index script and `index.html` exist, the script is used.
 
 ### Examples
 
@@ -203,6 +215,17 @@ And that's it! Your server is now hosting multiple HTTPS-enabled sites. 🎉
 
 ## 🤯 But Wait, There's More!
 
+### Static Sites (index.html)
+
+Domains under `www` that have no `index.js`/`index.mjs`/`index.cjs` but do have `index.html` are served as static sites. The logic lives in `lib/static-site-handler.js` and `lib/resolve-site-app.js`:
+
+- **`GET /`** and **`GET /index.html`** serve `index.html`.
+- Any other path serves the file under the domain folder if it exists; otherwise **404** (strict, no SPA fallback).
+- Path traversal (e.g. `/../`) is rejected with **403**.
+- Content-Type is set from extension (html, css, js, images, fonts, etc.).
+
+No Express or extra dependencies—plain Node. At startup you’ll see `(✔) Loaded site: https://example.com (static)` for these domains.
+
 ### Automatic SSL Certificate Management
 
 RosterServer uses [greenlock-express](https://www.npmjs.com/package/greenlock-express) to automatically obtain and renew SSL certificates from Let's Encrypt. No need to manually manage certificates ever again. Unless you enjoy that sort of thing. 🧐
@@ -213,7 +236,7 @@ All requests to `www.yourdomain.com` are automatically redirected to `yourdomain
 
 ### Dynamic Site Loading
 
-Add a new site? Just drop it into the `www` folder with an `index.js` file, and RosterServer will handle the rest. No need to restart the server. Well, you might need to restart the server. But that's what `nodemon` is for, right? 😅
+Add a new site? Drop it into the `www` folder: either an `index.js` (or `.mjs`/`.cjs`) for a Node app, or an `index.html` (plus assets) for a static site. RosterServer picks the right handler automatically. Restart the server to load new sites—nodemon has your back. 😅
 
 ## ⚙️ Configuration Options 
 

package/index.js

@@ -7,6 +7,7 @@ const crypto = require('crypto');
 const { EventEmitter } = require('events');
 const Greenlock = require('./vendor/greenlock-express/greenlock-express.js');
 const GreenlockShim = require('./vendor/greenlock-express/greenlock-shim.js');
+const { resolveSiteApp } = require('./lib/resolve-site-app.js');
 const log = require('lemonlog')('roster');
 
 const isBunRuntime = typeof Bun !== 'undefined' || (typeof process !== 'undefined' && process.release?.name === 'bun');
@@ -308,49 +309,38 @@ class Roster {
             const domain = dirent.name;
             const domainPath = path.join(this.wwwPath, domain);
 
-            const possibleIndexFiles = ['js', 'mjs', 'cjs'].map(ext => `${this.filename}.${ext}`);
-            let siteApp;
+            let resolved;
+            try {
+                resolved = await resolveSiteApp(domainPath, { filename: this.filename });
+            } catch (err) {
+                log.warn(`⚠️  Error loading site in ${domainPath}:`, err);
+                continue;
+            }
 
-            for (const indexFile of possibleIndexFiles) {
-                const indexPath = path.join(domainPath, indexFile);
-                if (fs.existsSync(indexPath)) {
-                    try {
-                        // Try dynamic import first
-                        siteApp = await import(indexPath).catch(() => {
-                            // Fallback to require for CommonJS modules
-                            return require(indexPath);
-                        });
-                        // Handle default exports
-                        siteApp = siteApp.default || siteApp;
-                        break;
-                    } catch (err) {
-                        log.warn(`⚠️  Error loading ${indexPath}:`, err);
-                    }
-                }
+            if (!resolved) {
+                log.warn(`⚠️  No index file (js/mjs/cjs or index.html) found in ${domainPath}`);
+                continue;
             }
 
-            if (siteApp) {
-                if (domain.startsWith('*.')) {
-                    if (this.disableWildcard) {
-                        log.warn(`⚠️  Wildcard site skipped (disableWildcard enabled): ${domain}`);
-                        continue;
-                    }
-                    // Wildcard site: one handler for all subdomains (e.g. *.example.com)
-                    this.domains.push(domain);
-                    this.sites[domain] = siteApp;
-                    const root = wildcardRoot(domain);
-                    if (root) this.wildcardZones.add(root);
-                    log.info(`(✔) Loaded wildcard site: https://${domain}`);
-                } else {
-                    const domainEntries = [domain, `www.${domain}`];
-                    this.domains.push(...domainEntries);
-                    domainEntries.forEach(d => {
-                        this.sites[d] = siteApp;
-                    });
-                    log.info(`(✔) Loaded site: https://${domain}`);
+            const { siteApp, type } = resolved;
+
+            if (domain.startsWith('*.')) {
+                if (this.disableWildcard) {
+                    log.warn(`⚠️  Wildcard site skipped (disableWildcard enabled): ${domain}`);
+                    continue;
                 }
+                this.domains.push(domain);
+                this.sites[domain] = siteApp;
+                const root = wildcardRoot(domain);
+                if (root) this.wildcardZones.add(root);
+                log.info(`(✔) Loaded wildcard site: https://${domain}${type === 'static' ? ' (static)' : ''}`);
             } else {
-                log.warn(`⚠️  No index file (js/mjs/cjs) found in ${domainPath}`);
+                const domainEntries = [domain, `www.${domain}`];
+                this.domains.push(...domainEntries);
+                domainEntries.forEach(d => {
+                    this.sites[d] = siteApp;
+                });
+                log.info(`(✔) Loaded site: https://${domain}${type === 'static' ? ' (static)' : ''}`);
             }
         }
     }

package/lib/resolve-site-app.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createStaticHandler } = require('./static-site-handler.js');
+
+/**
+ * Resolve a site app for a domain directory.
+ * Tries index.js / index.mjs / index.cjs first; falls back to static (index.html) if present.
+ * @param {string} domainPath - Absolute path to the domain folder (e.g. www/example.com)
+ * @param {{ filename?: string }} options - Optional. filename defaults to 'index'.
+ * @returns {Promise<{ siteApp: function, type: 'js' | 'static' } | null>}
+ */
+async function resolveSiteApp(domainPath, options = {}) {
+    const filename = options.filename || 'index';
+    const possibleIndexFiles = ['js', 'mjs', 'cjs'].map(ext => `${filename}.${ext}`);
+
+    for (const indexFile of possibleIndexFiles) {
+        const indexPath = path.join(domainPath, indexFile);
+        if (fs.existsSync(indexPath)) {
+            try {
+                let siteApp = await import(indexPath).catch(() => {
+                    return require(indexPath);
+                });
+                siteApp = siteApp.default || siteApp;
+                return { siteApp, type: 'js' };
+            } catch (err) {
+                throw err;
+            }
+        }
+    }
+
+    const indexHtmlPath = path.join(domainPath, 'index.html');
+    if (fs.existsSync(indexHtmlPath)) {
+        const siteApp = createStaticHandler(domainPath);
+        return { siteApp, type: 'static' };
+    }
+
+    return null;
+}
+
+module.exports = { resolveSiteApp };

package/lib/static-site-handler.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MIME_BY_EXT = {
+    html: 'text/html',
+    htm: 'text/html',
+    css: 'text/css',
+    js: 'application/javascript',
+    json: 'application/json',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    ico: 'image/x-icon',
+    svg: 'image/svg+xml',
+    webp: 'image/webp',
+    woff: 'font/woff',
+    woff2: 'font/woff2',
+    ttf: 'font/ttf',
+    eot: 'application/vnd.ms-fontobject',
+    map: 'application/json',
+    txt: 'text/plain',
+    xml: 'application/xml',
+    pdf: 'application/pdf'
+};
+
+const DEFAULT_MIME = 'application/octet-stream';
+
+/**
+ * Resolve request path to a safe filesystem path under rootPath.
+ * Returns null if path escapes rootPath (traversal) or is invalid.
+ * @param {string} rootPath - Absolute directory root
+ * @param {string} requestPath - URL path (e.g. /css/style.css)
+ * @returns {string|null} Absolute file path or null
+ */
+function resolvePath(rootPath, requestPath) {
+    const normalized = path.normalize(requestPath.replace(/^\//, '').replace(/\/+/g, path.sep));
+    if (normalized.startsWith('..') || normalized.includes('..' + path.sep) || normalized.includes(path.sep + '..')) {
+        return null;
+    }
+    const realRoot = path.resolve(rootPath);
+    const absolute = path.resolve(rootPath, normalized);
+    if (absolute !== realRoot && !absolute.startsWith(realRoot + path.sep)) {
+        return null;
+    }
+    return absolute;
+}
+
+/**
+ * Get Content-Type for a file path.
+ * @param {string} filePath
+ * @returns {string}
+ */
+function getContentType(filePath) {
+    const ext = path.extname(filePath).slice(1).toLowerCase();
+    return MIME_BY_EXT[ext] || DEFAULT_MIME;
+}
+
+/**
+ * Create a static site handler that serves files from rootPath.
+ * Compatible with Roster contract: (virtualServer) => (req, res) => void.
+ * - GET / or /index.html serves index.html
+ * - Serves existing files by path; 404 otherwise (strict mode)
+ * - Path traversal protected
+ * @param {string} rootPath - Absolute path to site root (e.g. www/example.com)
+ * @returns {function(virtualServer): function(req, res): void}
+ */
+function createStaticHandler(rootPath) {
+    const root = path.resolve(rootPath);
+
+    return function staticSiteFactory(virtualServer) {
+        return function staticHandler(req, res) {
+            if (req.method !== 'GET' && req.method !== 'HEAD') {
+                res.writeHead(405, { 'Content-Type': 'text/plain' });
+                res.end('Method Not Allowed');
+                return;
+            }
+
+            let requestPath = (req.url || '/').split('?')[0];
+            if (requestPath === '' || requestPath === '/') {
+                requestPath = '/index.html';
+            }
+
+            const filePath = resolvePath(root, requestPath);
+            if (!filePath) {
+                res.writeHead(403, { 'Content-Type': 'text/plain' });
+                res.end('Forbidden');
+                return;
+            }
+
+            if (!fs.existsSync(filePath)) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('Not Found');
+                return;
+            }
+
+            const stat = fs.statSync(filePath);
+            let servePath = filePath;
+            if (!stat.isFile()) {
+                if (!stat.isDirectory()) {
+                    res.writeHead(404, { 'Content-Type': 'text/plain' });
+                    res.end('Not Found');
+                    return;
+                }
+                const indexInDir = path.join(filePath, 'index.html');
+                if (!fs.existsSync(indexInDir) || !fs.statSync(indexInDir).isFile()) {
+                    res.writeHead(404, { 'Content-Type': 'text/plain' });
+                    res.end('Not Found');
+                    return;
+                }
+                servePath = indexInDir;
+            }
+
+            const contentType = getContentType(servePath);
+            const content = fs.readFileSync(servePath);
+
+            res.writeHead(200, {
+                'Content-Type': contentType,
+                'Content-Length': content.length
+            });
+            if (req.method === 'GET') {
+                res.end(content);
+            } else {
+                res.end();
+            }
+        };
+    };
+}
+
+module.exports = { createStaticHandler, resolvePath, getContentType, MIME_BY_EXT };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "roster-server",
-    "version": "2.2.12",
+    "version": "2.3.2",
     "description": "👾 RosterServer - A domain host router to host multiple HTTPS.",
     "main": "index.js",
     "scripts": {

package/skills/roster-server/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: roster-server
-description: Virtual hosting for multiple HTTPS sites with Let's Encrypt SSL automation. Each domain gets isolated VirtualServer instance, supports Express/Socket.IO/custom handlers, local HTTP dev mode with CRC32-based ports, automatic www redirects, and SNI certificate management.
+description: Virtual hosting for multiple HTTPS sites with Let's Encrypt SSL automation. Each domain gets isolated VirtualServer instance, supports Express/Socket.IO/custom handlers, static sites (index.html only, no Node), local HTTP dev mode with CRC32-based ports, automatic www redirects, and SNI certificate management. Static site logic is modular (lib/static-site-handler.js, lib/resolve-site-app.js).
 ---
 
 ## Quick Setup
@@ -42,14 +42,22 @@ project/
 │   │   └── index.js   # Handler for example.com
 │   ├── api.example.com/
 │   │   └── index.js   # Handler for subdomain
+│   ├── static-site.com/   # Static site (no index.js)
+│   │   ├── index.html
+│   │   ├── css/
+│   │   └── images/
 │   └── *.example.com/
 │       └── index.js   # Wildcard: one handler for all subdomains
 └── server.js          # Your setup
 ```
 
+**Site resolution**: For each domain folder, RosterServer looks for `index.js` / `index.mjs` / `index.cjs` first. If none exist but `index.html` exists, it serves the folder as a static site (modular handler in `lib/static-site-handler.js`). Node app takes precedence when both exist.
+
 ## Handler Patterns
 
-Each `www/{domain}/index.js` must export a function that receives `httpsServer` and returns a request handler.
+**Node app**: Each `www/{domain}/index.js` (or `.mjs`/`.cjs`) must export a function that receives `httpsServer` and returns a request handler.
+
+**Static site**: If the domain folder has no index script but has `index.html`, RosterServer serves the folder as static files (`GET /` → `index.html`, other paths → file or 404, path-traversal protected). No code required.
 
 ### Pattern 1: Basic HTTP Handler
 ```javascript
@@ -112,6 +120,9 @@ roster.register('*.example.com', handler);
 roster.register('*.example.com:8080', handler);
 ```
 
+### Pattern 5: Static Site (no code)
+Place only `index.html` (and assets) in `www/example.com/`. No `index.js` needed. RosterServer serves files with path-traversal protection; `/` → `index.html`, other paths → file or 404. Implemented in `lib/static-site-handler.js` and `lib/resolve-site-app.js`.
+
 ## Key Configuration Options
 
 ```javascript
@@ -183,7 +194,7 @@ Each domain gets isolated server instance that simulates `http.Server`:
 
 **Port 443 in use**: Use different port `{ port: 8443 }`  
 **Certificate failed**: Check firewall (ports 80, 443), verify DNS, try `staging: true`  
-**Site not found**: Verify directory name matches domain, check `index.js` exports function  
+**Site not found**: Verify directory name matches domain. For Node: check `index.js` exports function. For static: ensure `index.html` exists (no index script).  
 **Local port conflict**: Adjust `minLocalPort`/`maxLocalPort` range  
 **Socket.IO not working**: Ensure handler checks `io.opts.path` and returns properly
 
@@ -253,7 +264,7 @@ roster.start();
 When implementing RosterServer:
 
 - [ ] Create `www/` directory structure with domain folders
-- [ ] Each domain has `index.js` exporting `(httpsServer) => handler`
+- [ ] Each domain has either `index.js` (or `.mjs`/`.cjs`) exporting `(httpsServer) => handler`, or `index.html` (and assets) for a static site
 - [ ] Configure email for Let's Encrypt notifications
 - [ ] Test with `local: true` first
 - [ ] Test with `staging: true` before production

package/test/roster-server.test.js

@@ -539,6 +539,120 @@ describe('Roster loadSites', () => {
         });
         await assert.doesNotReject(roster.loadSites());
     });
+
+    it('loads static site from www/domain when index.html exists and no index.js', async () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'roster-test-'));
+        const wwwPath = path.join(tmpDir, 'www');
+        const siteDir = path.join(wwwPath, 'static.example');
+        fs.mkdirSync(siteDir, { recursive: true });
+        fs.writeFileSync(path.join(siteDir, 'index.html'), '<html>hello</html>', 'utf8');
+        try {
+            const roster = new Roster({ wwwPath, local: true });
+            await roster.loadSites();
+            assert.ok(roster.sites['static.example']);
+            assert.ok(roster.sites['www.static.example']);
+            const handler = roster.sites['static.example'];
+            assert.strictEqual(typeof handler, 'function');
+            const appHandler = handler(roster.createVirtualServer('static.example'));
+            assert.strictEqual(typeof appHandler, 'function');
+        } finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+
+    it('loads index.js over index.html when both exist', async () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'roster-test-'));
+        const wwwPath = path.join(tmpDir, 'www');
+        const siteDir = path.join(wwwPath, 'both.example');
+        fs.mkdirSync(siteDir, { recursive: true });
+        fs.writeFileSync(path.join(siteDir, 'index.html'), '<html>static</html>', 'utf8');
+        fs.writeFileSync(
+            path.join(siteDir, 'index.js'),
+            'module.exports = () => (req, res) => { res.writeHead(200); res.end("js"); };',
+            'utf8'
+        );
+        try {
+            const roster = new Roster({ wwwPath, local: true });
+            await roster.loadSites();
+            const handler = roster.sites['both.example'];
+            const appHandler = handler(roster.createVirtualServer('both.example'));
+            let body = '';
+            const res = { writeHead: () => {}, end: (b) => { body = (b || '').toString(); } };
+            appHandler({ url: '/', method: 'GET' }, res);
+            assert.strictEqual(body, 'js');
+        } finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+
+    it('static site serves index.html for / in local mode', async () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'roster-test-'));
+        const wwwPath = path.join(tmpDir, 'www');
+        const siteDir = path.join(wwwPath, 'staticlocal.example');
+        fs.mkdirSync(siteDir, { recursive: true });
+        const html = '<html><body>static ok</body></html>';
+        fs.writeFileSync(path.join(siteDir, 'index.html'), html, 'utf8');
+        const roster = new Roster({ wwwPath, local: true, minLocalPort: 19200, maxLocalPort: 19209 });
+        try {
+            await roster.start();
+            const port = roster.domainPorts['staticlocal.example'];
+            assert.ok(typeof port === 'number');
+            await new Promise((r) => setTimeout(r, 50));
+            const result = await httpGet('localhost', port, '/');
+            assert.strictEqual(result.statusCode, 200);
+            assert.ok(result.body.includes('static ok'));
+        } finally {
+            closePortServers(roster);
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+
+    it('static site returns 404 for non-existent path', async () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'roster-test-'));
+        const wwwPath = path.join(tmpDir, 'www');
+        const siteDir = path.join(wwwPath, 'static404.example');
+        fs.mkdirSync(siteDir, { recursive: true });
+        fs.writeFileSync(path.join(siteDir, 'index.html'), '<html>ok</html>', 'utf8');
+        const roster = new Roster({ wwwPath, local: true, minLocalPort: 19210, maxLocalPort: 19219 });
+        try {
+            await roster.start();
+            const port = roster.domainPorts['static404.example'];
+            assert.ok(typeof port === 'number');
+            await new Promise((r) => setTimeout(r, 50));
+            const result = await httpGet('localhost', port, '/nonexistent.html');
+            assert.strictEqual(result.statusCode, 404);
+        } finally {
+            closePortServers(roster);
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+
+    it('static site serves index.html for subpath directory (/en/)', async () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'roster-test-'));
+        const wwwPath = path.join(tmpDir, 'www');
+        const siteDir = path.join(wwwPath, 'subpath.example');
+        fs.mkdirSync(siteDir, { recursive: true });
+        fs.writeFileSync(path.join(siteDir, 'index.html'), '<html>root</html>', 'utf8');
+        const enDir = path.join(siteDir, 'en');
+        fs.mkdirSync(enDir, { recursive: true });
+        fs.writeFileSync(path.join(enDir, 'index.html'), '<html><body>en page</body></html>', 'utf8');
+        const roster = new Roster({ wwwPath, local: true, minLocalPort: 19220, maxLocalPort: 19229 });
+        try {
+            await roster.start();
+            const port = roster.domainPorts['subpath.example'];
+            assert.ok(typeof port === 'number');
+            await new Promise((r) => setTimeout(r, 50));
+            const resultSlash = await httpGet('localhost', port, '/en/');
+            assert.strictEqual(resultSlash.statusCode, 200);
+            assert.ok(resultSlash.body.includes('en page'));
+            const resultNoSlash = await httpGet('localhost', port, '/en');
+            assert.strictEqual(resultNoSlash.statusCode, 200);
+            assert.ok(resultNoSlash.body.includes('en page'));
+        } finally {
+            closePortServers(roster);
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
 });
 
 describe('Roster generateConfigJson', () => {

package/tasks/lessons.md

@@ -1,5 +0,0 @@
-# Lessons Learned
-
-- When wildcard TLS must run under Bun, do not rely on manual DNS instructions; default to API-driven DNS-01 TXT creation/removal (Linode/Akamai) with propagation polling, then fall back to manual mode only when no provider token is configured.
-- Do not keep speculative resolver/workaround attempts that are not the root cause; if a change does not resolve the issue with evidence, revert/simplify immediately so temporary experiments do not become permanent complexity.
-- Never declare TLS/wildcard fixed based only on ACME success logs; always verify the certificate actually served to the target host with `openssl s_client` before closing the issue.