roster-server 2.4.4 → 2.4.8

package/README.md

@@ -11,6 +11,7 @@ Welcome to **RosterServer**, the ultimate domain host router with automatic HTTP
 - **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.
+- **Optional Request Plugins**: Run synchronous filters before site handlers, including the bundled scanner blocker.
 - **Zero Configuration**: Well, almost zero. Just a tiny bit of setup.
 - **Bun compatible**: Works with both Node.js and [Bun](https://bun.sh).
 
@@ -114,6 +115,34 @@ const server = new Roster(options);
 server.start();
 ```
 
+### Blocking vulnerability scanners
+
+RosterServer includes an optional request plugin that rejects common PHP, WordPress, repository, and sensitive-file probes before they reach a site handler. Suspicious paths always receive a `404`; after the configured number of strikes, every request from that client is rejected until the ban expires.
+
+```javascript
+import Roster from 'roster-server';
+import { createScannerBlocker } from 'roster-server/plugins/scanner-blocker.js';
+
+const roster = new Roster(options);
+
+roster.use(createScannerBlocker({
+    windowMs: 60_000,
+    strikeThreshold: 3,
+    banDurationMs: 15 * 60_000,
+    maxTrackedClients: 10_000,
+    trustProxy: false,
+    onBlock(event) {
+        // Send event to the application's existing logger if desired.
+    }
+}));
+
+roster.start();
+```
+
+All operational values are required. Keep `trustProxy: false` when RosterServer receives traffic directly. Set it to `true` only when a trusted reverse proxy overwrites `X-Forwarded-For`; otherwise clients can spoof the address used for bans.
+
+The in-memory strike and ban state is bounded by `maxTrackedClients`, belongs to one RosterServer process, and is cleared on restart. Use the optional `onBlock(event)` callback to feed a shared firewall or Fail2ban when bans must persist or span multiple workers. Routes such as `/atom` and `/articles/config` are not classified as scanner probes.
+
 ### Your Site Handlers
 
 Each domain has its own folder under `www`. You can use:
@@ -386,6 +415,36 @@ process.on('message', (msg, connection) => {
 });
 ```
 
+### Production Pattern: Single Certificate Manager + Workers
+
+For robust ACME behavior with cluster runtimes, run a single certificate manager process (primary) and keep workers in serving-only mode. This avoids challenge race conditions while keeping certificate lifecycle automatic.
+
+```javascript
+// primary
+const certManager = new Roster({
+    email: 'admin@example.com',
+    greenlockStorePath: '/srv/greenlock.d',
+    wwwPath: '/srv/www'
+});
+certManager.register('example.com', () => (req, res) => res.end('manager'));
+await certManager.start();                    // enables ACME challenge lifecycle
+await certManager.ensureCertificate('example.com');
+
+// worker
+const workerRoster = new Roster({
+    email: 'admin@example.com',
+    greenlockStorePath: '/srv/greenlock.d',
+    wwwPath: '/srv/www',
+    autoCertificates: false
+});
+workerRoster.register('example.com', () => (req, res) => res.end('worker'));
+await workerRoster.init();
+const server = await workerRoster.createServingHttpsServer({ servername: 'example.com' });
+server.listen(4336);
+```
+
+Reference implementation: `demo/https-cluster-configurable.js`.
+
 ### API Reference
 
 #### `roster.init()` → `Promise<Roster>`
@@ -396,6 +455,10 @@ Loads sites, generates SSL config (production), creates VirtualServers and initi
 
 Returns the Host-header dispatch function for a given port (defaults to `defaultPort`). Handles www→non-www redirects, wildcard matching, and VirtualServer dispatch.
 
+#### `roster.use(plugin)` → `Roster`
+
+Registers a synchronous request plugin and returns `this`. Plugins receive `(req, res, { host, domain })`; return `true` after sending a response to stop dispatch, or `false`/`undefined` to continue. Plugins run in registration order before redirects and site handlers.
+
 #### `roster.upgradeHandler(port?)` → `(req, socket, head) => void`
 
 Returns the WebSocket upgrade dispatcher for a given port. Routes upgrades to the correct VirtualServer.
@@ -404,6 +467,22 @@ Returns the WebSocket upgrade dispatcher for a given port. Routes upgrades to th
 
 Returns a TLS SNI callback. It resolves certificates from `greenlockStorePath` and, when `autoCertificates` is enabled (default), can issue missing certificates automatically. Not available in local mode.
 
+#### `roster.ensureCertificate(servername)` → `Promise<{ key, cert }>`
+
+Ensures a certificate exists for `servername`. With `autoCertificates` enabled (default), it issues missing certificates automatically and returns PEMs.
+
+#### `roster.loadCertificate(servername)` → `{ key, cert }`
+
+Loads an existing certificate from `greenlockStorePath` without issuing new certificates. Useful for serving-only workers.
+
+#### `roster.createManagedHttpsServer({ servername, port?, ensureCertificate?, tlsOptions? })` → `Promise<https.Server>`
+
+Creates an HTTPS server prewired with default cert, SNI callback, and request/upgrade routing. By default it ensures certificate issuance before returning.
+
+#### `roster.createServingHttpsServer({ servername, port?, tlsOptions? })` → `Promise<https.Server>`
+
+Convenience alias for serving-only workers. Equivalent to `createManagedHttpsServer(..., ensureCertificate: false)`.
+
 #### `roster.attach(server, { port }?)` → `Roster`
 
 Convenience method. Wires `requestHandler` and `upgradeHandler` onto `server.on('request', ...)` and `server.on('upgrade', ...)`. Returns `this` for chaining.
@@ -447,4 +526,4 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 ---
 
-Happy hosting! 🎈
+Happy hosting! 🎈

package/demo/https-cluster-configurable.js

@@ -1,30 +1,36 @@
 const cluster = require('cluster');
 const os = require('os');
 const path = require('path');
-const https = require('https');
 const Roster = require('../index.js');
 
 // Change these values to your target domain and HTTPS port.
 const CONFIG = {
-    domain: 'chinchon.blyts.com',
+    domain: 'example.com',
     httpsPort: 4336,
     workers: Math.max(1, Math.min(2, os.cpus().length)),
+    certificateManagerHttpsPort: 0, // 0 = ephemeral, manager does not serve public traffic
     wwwPath: path.join(__dirname, 'www'),
     greenlockStorePath: path.join(__dirname, '..', 'greenlock.d'),
-    email: 'mclasen@blyts.com',
-    staging: false,
-    autoCertificates: true
+    email: 'mclasen@example.com',
+    staging: false
 };
 
-async function startWorker() {
+function createRoster({ isCertificateManager }) {
     const roster = new Roster({
         local: false,
         email: CONFIG.email,
         staging: CONFIG.staging,
         wwwPath: CONFIG.wwwPath,
         greenlockStorePath: CONFIG.greenlockStorePath,
-        autoCertificates: CONFIG.autoCertificates
+        autoCertificates: isCertificateManager,
+        // Certificate manager can bind an ephemeral HTTPS port; workers serve real traffic.
+        port: isCertificateManager ? CONFIG.certificateManagerHttpsPort : 443
     });
+    return roster;
+}
+
+async function startWorker() {
+    const roster = createRoster({ isCertificateManager: false });
 
     // Domain is configured from CONFIG (single source of truth).
     roster.register(CONFIG.domain, () => {
@@ -35,19 +41,10 @@ async function startWorker() {
     });
 
     await roster.init();
-    // Automatic cert issuance by roster-server (and renewal loop) in cluster-friendly mode.
-    const defaultPems = await roster.ensureCertificate(CONFIG.domain);
-
-    const server = https.createServer({
-        key: defaultPems.key,
-        cert: defaultPems.cert,
-        SNICallback: roster.sniCallback(),
-        minVersion: 'TLSv1.2',
-        maxVersion: 'TLSv1.3'
+    const server = await roster.createServingHttpsServer({
+        servername: CONFIG.domain
     });
 
-    roster.attach(server);
-
     server.listen(CONFIG.httpsPort, () => {
         console.log(`[worker ${process.pid}] listening on https://0.0.0.0:${CONFIG.httpsPort} for domain ${CONFIG.domain}`);
     });
@@ -58,7 +55,21 @@ async function startPrimary() {
     console.log(`domain=${CONFIG.domain} port=${CONFIG.httpsPort}`);
     console.log(`wwwPath=${CONFIG.wwwPath}`);
     console.log(`greenlockStorePath=${CONFIG.greenlockStorePath}\n`);
-    console.log(`[primary] cert lifecycle managed by roster-server (autoCertificates=${CONFIG.autoCertificates})\n`);
+    console.log('[primary] cert lifecycle managed by roster-server\n');
+
+    // Primary is the single certificate manager to avoid ACME race conditions.
+    // It starts Roster standalone lifecycle so ACME http-01 challenge server (:80) is active.
+    const certificateManager = createRoster({ isCertificateManager: true });
+    certificateManager.register(CONFIG.domain, () => {
+        return (req, res) => {
+            res.writeHead(200);
+            res.end('certificate-manager');
+        };
+    });
+    await certificateManager.start();
+    await certificateManager.ensureCertificate(CONFIG.domain);
+    const subject = CONFIG.domain;
+    console.log(`[primary] certificate ready for ${CONFIG.domain} (subject=${subject})\n`);
 
     for (let i = 0; i < CONFIG.workers; i++) {
         cluster.fork();

package/index.js

@@ -247,6 +247,7 @@ class Roster {
         this.local = options.local || false;
         this.domains = [];
         this.sites = {};
+        this.plugins = [];
         this.wildcardZones = new Set(); // Root domains that have a wildcard site (e.g. "example.com" for *.example.com)
         this.domainServers = {}; // Store separate servers for each domain
         this.portServers = {}; // Store servers by port
@@ -540,6 +541,11 @@ class Roster {
 
     handleRequest(req, res) {
         const host = req.headers.host || '';
+        const hostWithoutPort = host.split(':')[0];
+        const normalizedHost = hostWithoutPort.toLowerCase();
+        const domain = normalizedHost.startsWith('www.') ? normalizedHost.slice(4) : normalizedHost;
+
+        if (this._runRequestPlugins(req, res, { host: normalizedHost, domain })) return;
 
         if (host.startsWith('www.')) {
             const newHost = host.slice(4);
@@ -548,7 +554,6 @@ class Roster {
             return;
         }
 
-        const hostWithoutPort = host.split(':')[0];
         const siteApp = this.getHandlerForHost(hostWithoutPort);
         if (siteApp) {
             siteApp(req, res);
@@ -597,6 +602,25 @@ class Roster {
         return this;
     }
 
+    use(plugin) {
+        if (typeof plugin !== 'function') {
+            throw new Error('plugin must be a function');
+        }
+        this.plugins.push(plugin);
+        return this;
+    }
+
+    _runRequestPlugins(req, res, context) {
+        for (const plugin of this.plugins) {
+            const handled = plugin(req, res, context);
+            if (handled && typeof handled.then === 'function') {
+                throw new Error('Request plugins must be synchronous');
+            }
+            if (handled === true) return true;
+        }
+        return false;
+    }
+
     parseDomainWithPort(domainString) {
         const parts = domainString.split(':');
         if (parts.length === 2) {
@@ -737,6 +761,8 @@ class Roster {
             const hostWithoutPort = host.split(':')[0].toLowerCase();
             const domain = hostWithoutPort.startsWith('www.') ? hostWithoutPort.slice(4) : hostWithoutPort;
 
+            if (this._runRequestPlugins(req, res, { host: hostWithoutPort, domain })) return;
+
             if (hostWithoutPort.startsWith('www.')) {
                 const protocol = this.local ? 'http' : 'https';
                 res.writeHead(301, { Location: `${protocol}://${domain}${req.url}` });
@@ -935,6 +961,24 @@ class Roster {
         return pems;
     }
 
+    loadCertificate(servername) {
+        if (this.local) {
+            throw new Error('loadCertificate() is not available in local mode');
+        }
+        if (!this._initialized) {
+            throw new Error('Call init() before loadCertificate()');
+        }
+        const normalizedServername = this._normalizeHostInput(servername).trim().toLowerCase();
+        if (!normalizedServername) {
+            throw new Error('servername is required');
+        }
+        const pems = this._resolvePemsForServername(normalizedServername);
+        if (!pems) {
+            throw new Error(`No certificate files available for ${normalizedServername}`);
+        }
+        return pems;
+    }
+
     async init() {
         if (this._initialized) return this;
         await this.loadSites();
@@ -991,6 +1035,46 @@ class Roster {
         return this;
     }
 
+    async createManagedHttpsServer(options = {}) {
+        if (this.local) throw new Error('createManagedHttpsServer() is not available in local mode');
+        if (!this._initialized) throw new Error('Call init() before createManagedHttpsServer()');
+
+        const {
+            servername,
+            port,
+            ensureCertificate = true,
+            tlsOptions = {}
+        } = options;
+
+        const normalizedServername = this._normalizeHostInput(servername).trim().toLowerCase();
+        if (!normalizedServername) {
+            throw new Error('servername is required');
+        }
+
+        const pems = ensureCertificate
+            ? await this.ensureCertificate(normalizedServername)
+            : this.loadCertificate(normalizedServername);
+
+        const server = https.createServer({
+            minVersion: this.tlsMinVersion,
+            maxVersion: this.tlsMaxVersion,
+            ...tlsOptions,
+            key: pems.key,
+            cert: pems.cert,
+            SNICallback: this.sniCallback()
+        });
+
+        this.attach(server, { port });
+        return server;
+    }
+
+    async createServingHttpsServer(options = {}) {
+        return this.createManagedHttpsServer({
+            ...options,
+            ensureCertificate: false
+        });
+    }
+
     startLocalMode() {
         this.domainPorts = {};
 
@@ -1004,6 +1088,8 @@ class Roster {
                 const appHandler = portData.appHandlers[domain];
 
                 const dispatcher = (req, res) => {
+                    const host = (req.headers.host || '').split(':')[0].toLowerCase();
+                    if (this._runRequestPlugins(req, res, { host, domain })) return;
                     virtualServer.fallbackHandler = appHandler;
                     if (virtualServer.requestListeners.length > 0) {
                         virtualServer.processRequest(req, res);
@@ -1263,4 +1349,4 @@ module.exports.wildcardRoot = wildcardRoot;
 module.exports.hostMatchesWildcard = hostMatchesWildcard;
 module.exports.wildcardSubjectForHost = wildcardSubjectForHost;
 module.exports.buildCertLookupCandidates = buildCertLookupCandidates;
-module.exports.certCoversName = certCoversName;
+module.exports.certCoversName = certCoversName;

package/package.json

@@ -1,53 +1,53 @@
 {
-    "name": "roster-server",
-    "version": "2.4.4",
-    "description": "👾 RosterServer - A domain host router to host multiple HTTPS.",
-    "main": "index.js",
-    "scripts": {
-        "test": "node --test 'test/**/*.test.js'"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/clasen/RosterServer.git"
-    },
-    "keywords": [
-        "greenlock",
-        "https",
-        "domain",
-        "multi-domain",
-        "letsencrypt",
-        "hosting",
-        "ssl",
-        "host",
-        "vhost",
-        "virtual-host",
-        "socket.io",
-        "websocket",
-        "express",
-        "greenlock-express",
-        "shotx",
-        "bun",
-        "clasen"
-    ],
-    "author": "Martin Clasen",
-    "license": "MIT",
-    "bugs": {
-        "url": "https://github.com/clasen/RosterServer/issues"
-    },
-    "homepage": "https://github.com/clasen/RosterServer#readme",
-    "dependencies": {
-        "@greenlock/manager": "^3.1.0",
-        "@root/acme": "^3.1.0",
-        "@root/csr": "^0.8.1",
-        "@root/keypairs": "^0.10.0",
-        "@root/mkdirp": "^1.0.0",
-        "@root/request": "^1.6.1",
-        "acme-dns-01-cli": "^3.0.7",
-        "acme-http-01-standalone": "^3.0.5",
-        "cert-info": "^1.5.1",
-        "greenlock-store-fs": "^3.2.2",
-        "lemonlog": "^1.2.0",
-        "redirect-https": "^1.3.1",
-        "safe-replace": "^1.1.0"
-    }
-}
+  "name": "roster-server",
+  "version": "2.4.8",
+  "description": "👾 RosterServer - A domain host router to host multiple HTTPS.",
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clasen/RosterServer.git"
+  },
+  "keywords": [
+    "greenlock",
+    "https",
+    "domain",
+    "multi-domain",
+    "letsencrypt",
+    "hosting",
+    "ssl",
+    "host",
+    "vhost",
+    "virtual-host",
+    "socket.io",
+    "websocket",
+    "express",
+    "greenlock-express",
+    "shotx",
+    "bun",
+    "clasen"
+  ],
+  "author": "Martin Clasen",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/clasen/RosterServer/issues"
+  },
+  "homepage": "https://github.com/clasen/RosterServer#readme",
+  "dependencies": {
+    "@greenlock/manager": "^3.1.0",
+    "@root/acme": "^3.1.0",
+    "@root/csr": "^0.8.1",
+    "@root/keypairs": "^0.10.0",
+    "@root/mkdirp": "^1.0.0",
+    "@root/request": "^1.6.1",
+    "acme-dns-01-cli": "^3.0.7",
+    "acme-http-01-standalone": "^3.0.5",
+    "cert-info": "^1.5.1",
+    "greenlock-store-fs": "^3.2.2",
+    "lemonlog": "^1.2.0",
+    "redirect-https": "^1.3.1",
+    "safe-replace": "^1.1.0"
+  },
+  "scripts": {
+    "test": "node --test 'test/**/*.test.js'"
+  }
+}

package/plugins/scanner-blocker.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const PHP_PATH = /(?:^|\/)[^/]*\.php(?:$|\/)/i;
+const SCANNER_PATH = /(?:^|\/)(?:\.git|\.hg|\.svn|\.ssh|\.aws|cgi-bin|server-status|vendor\/phpunit|wp-admin|wp-content|wp-includes|wp-json)(?:\/|$)/i;
+const SCANNER_FILE = /(?:^|\/)(?:\.env(?:\.[^/]*)?|\.htaccess|composer\.(?:json|lock)|web\.config)(?:\/|$)/i;
+
+function requirePositiveInteger(options, name) {
+    const value = options[name];
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return value;
+}
+
+function normalizeRequestPath(url) {
+    let requestPath = String(url || '/').split(/[?#]/, 1)[0];
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const decoded = decodeURIComponent(requestPath);
+            if (decoded === requestPath) break;
+            requestPath = decoded;
+        } catch {
+            break;
+        }
+    }
+    return requestPath.replace(/\\/g, '/').replace(/\/+/g, '/').toLowerCase();
+}
+
+function scannerReason(url) {
+    const requestPath = normalizeRequestPath(url);
+    if (PHP_PATH.test(requestPath)) return 'php-path';
+    if (SCANNER_PATH.test(requestPath)) return 'scanner-path';
+    if (SCANNER_FILE.test(requestPath)) return 'sensitive-file';
+    return null;
+}
+
+function normalizeIp(value) {
+    const ip = String(value || '').trim();
+    return ip.startsWith('::ffff:') ? ip.slice(7) : ip;
+}
+
+function clientIp(req, trustProxy) {
+    if (trustProxy) {
+        const forwardedFor = req.headers?.['x-forwarded-for'];
+        const firstForwardedIp = Array.isArray(forwardedFor)
+            ? forwardedFor[0]
+            : String(forwardedFor || '').split(',')[0];
+        const normalizedForwardedIp = normalizeIp(firstForwardedIp);
+        if (normalizedForwardedIp) return normalizedForwardedIp;
+    }
+    return normalizeIp(req.socket?.remoteAddress);
+}
+
+function rejectRequest(req, res) {
+    const body = 'Not Found';
+    res.writeHead(404, {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Content-Length': Buffer.byteLength(body),
+        'Cache-Control': 'no-store'
+    });
+    res.end(req.method === 'HEAD' ? undefined : body);
+}
+
+function createScannerBlocker(options) {
+    if (!options || typeof options !== 'object') {
+        throw new Error('scanner-blocker options are required');
+    }
+
+    const windowMs = requirePositiveInteger(options, 'windowMs');
+    const strikeThreshold = requirePositiveInteger(options, 'strikeThreshold');
+    const banDurationMs = requirePositiveInteger(options, 'banDurationMs');
+    const maxTrackedClients = requirePositiveInteger(options, 'maxTrackedClients');
+    if (typeof options.trustProxy !== 'boolean') {
+        throw new Error('trustProxy must be a boolean');
+    }
+    if (options.onBlock !== undefined && typeof options.onBlock !== 'function') {
+        throw new Error('onBlock must be a function');
+    }
+    if (options.now !== undefined && typeof options.now !== 'function') {
+        throw new Error('now must be a function');
+    }
+
+    const trustProxy = options.trustProxy;
+    const onBlock = options.onBlock;
+    const now = options.now || Date.now;
+    const clients = new Map();
+
+    function removeExpiredClients(timestamp) {
+        for (const [ip, state] of clients) {
+            const banExpired = state.bannedUntil !== null && timestamp >= state.bannedUntil;
+            const windowExpired = state.bannedUntil === null && timestamp - state.windowStartedAt >= windowMs;
+            if (banExpired || windowExpired) clients.delete(ip);
+        }
+    }
+
+    function addClient(ip, state, timestamp) {
+        if (!clients.has(ip) && clients.size >= maxTrackedClients) {
+            removeExpiredClients(timestamp);
+        }
+        if (!clients.has(ip) && clients.size >= maxTrackedClients) {
+            clients.delete(clients.keys().next().value);
+        }
+        clients.delete(ip);
+        clients.set(ip, state);
+    }
+
+    function reportBlock(details) {
+        if (onBlock) onBlock(details);
+    }
+
+    return function scannerBlocker(req, res, context = {}) {
+        const timestamp = now();
+        const ip = clientIp(req, trustProxy);
+        let state = ip ? clients.get(ip) : null;
+
+        if (state && state.bannedUntil !== null) {
+            if (timestamp < state.bannedUntil) {
+                rejectRequest(req, res);
+                reportBlock({
+                    type: 'banned-client',
+                    clientIp: ip,
+                    host: context.host || '',
+                    url: req.url || '/',
+                    bannedUntil: state.bannedUntil
+                });
+                return true;
+            }
+            clients.delete(ip);
+            state = null;
+        }
+
+        const reason = scannerReason(req.url);
+        if (!reason) return false;
+
+        let bannedUntil = null;
+        if (ip) {
+            if (!state || timestamp - state.windowStartedAt >= windowMs) {
+                state = { strikes: 0, windowStartedAt: timestamp, bannedUntil: null };
+            }
+            state.strikes += 1;
+            if (state.strikes >= strikeThreshold) {
+                state.bannedUntil = timestamp + banDurationMs;
+            }
+            bannedUntil = state.bannedUntil;
+            addClient(ip, state, timestamp);
+        }
+
+        rejectRequest(req, res);
+        reportBlock({
+            type: 'scanner-path',
+            reason,
+            clientIp: ip,
+            host: context.host || '',
+            url: req.url || '/',
+            bannedUntil
+        });
+        return true;
+    };
+}
+
+module.exports = { createScannerBlocker };

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  '@root/acme': true

package/skills/roster-server/SKILL.md

@@ -147,6 +147,49 @@ process.on('message', (msg, connection) => {
 });
 ```
 
+### Pattern 7: Cluster Production (single cert manager + workers)
+```javascript
+// PRIMARY: certificate manager (single process)
+const manager = new Roster({
+    email: 'admin@example.com',
+    greenlockStorePath: '/srv/greenlock.d',
+    wwwPath: '/srv/www'
+});
+manager.register('example.com', () => (req, res) => res.end('manager'));
+await manager.start();
+await manager.ensureCertificate('example.com');
+
+// WORKER: serving-only process
+const worker = new Roster({
+    email: 'admin@example.com',
+    greenlockStorePath: '/srv/greenlock.d',
+    wwwPath: '/srv/www',
+    autoCertificates: false
+});
+worker.register('example.com', () => (req, res) => res.end('worker'));
+await worker.init();
+const httpsServer = await worker.createServingHttpsServer({ servername: 'example.com' });
+httpsServer.listen(4336);
+```
+
+### Pattern 8: Optional Scanner Blocking
+```javascript
+const Roster = require('roster-server');
+const { createScannerBlocker } = require('roster-server/plugins/scanner-blocker.js');
+
+const roster = new Roster({ local: true, wwwPath: './www' });
+roster.use(createScannerBlocker({
+    windowMs: 60_000,
+    strikeThreshold: 3,
+    banDurationMs: 15 * 60_000,
+    maxTrackedClients: 10_000,
+    trustProxy: false
+}));
+roster.start();
+```
+
+The plugin blocks common PHP, WordPress, repository, and sensitive-file probes before site handlers. All operational values are required. Set `trustProxy: true` only behind a trusted reverse proxy that overwrites `X-Forwarded-For`. Ban state is per process and in memory; use `onBlock` to integrate a shared firewall or Fail2ban.
+
 ## Key Configuration Options
 
 ```javascript
@@ -194,12 +237,24 @@ Returns `(servername, callback) => void` TLS SNI callback that resolves certs fr
 ### `roster.ensureCertificate(servername)`
 Forces certificate availability for a domain and returns `{ key, cert }`. With `autoCertificates` enabled (default), it issues certs automatically when missing.
 
+### `roster.loadCertificate(servername)`
+Loads existing `{ key, cert }` from `greenlockStorePath` without issuing new certificates.
+
+### `roster.createManagedHttpsServer(options)`
+Creates a pre-wired `https.Server` with default cert, SNI callback, and attached request/upgrade handlers.
+
+### `roster.createServingHttpsServer(options)`
+Serving-only helper for worker processes. Same as `createManagedHttpsServer(..., ensureCertificate: false)`.
+
 ### `roster.attach(server, { port }?)`
 Convenience: wires `requestHandler` + `upgradeHandler` onto an external `http.Server` or `https.Server`. Returns `this`. Requires `init()` first.
 
 ### `roster.register(domain, handler)`
 Manually register a domain handler. Domain can include port: `'api.com:8443'`. For wildcards use `'*.example.com'` or `'*.example.com:8080'`.
 
+### `roster.use(plugin)`
+Registers a synchronous request plugin. It receives `(req, res, { host, domain })` and stops dispatch when it returns `true`.
+
 ### `roster.getUrl(domain)`
 Get environment-aware URL:
 - Local mode: `http://localhost:{port}`

package/test/roster-server.test.js

@@ -7,6 +7,7 @@ const fs = require('fs');
 const http = require('http');
 const os = require('os');
 const Roster = require('../index.js');
+const { createScannerBlocker } = require('../plugins/scanner-blocker.js');
 const {
     wildcardRoot,
     hostMatchesWildcard,
@@ -432,6 +433,13 @@ describe('Roster local mode (local: true)', () => {
             hostname: 'localhost'
         });
         const body = 'local-mode-ok';
+        roster.use(createScannerBlocker({
+            windowMs: 60_000,
+            strikeThreshold: 2,
+            banDurationMs: 300_000,
+            maxTrackedClients: 100,
+            trustProxy: false
+        }));
         roster.register('testlocal.example', (server) => {
             return (req, res) => {
                 res.writeHead(200, { 'Content-Type': 'text/plain' });
@@ -446,6 +454,9 @@ describe('Roster local mode (local: true)', () => {
             const result = await httpGet('localhost', port, '/');
             assert.strictEqual(result.statusCode, 200);
             assert.strictEqual(result.body, body);
+            const probe = await httpGet('localhost', port, '/wp-login.php');
+            assert.strictEqual(probe.statusCode, 404);
+            assert.strictEqual(probe.body, 'Not Found');
         } finally {
             closePortServers(roster);
         }
@@ -933,6 +944,60 @@ describe('Roster ensureCertificate()', () => {
     });
 });
 
+describe('Roster loadCertificate()', () => {
+    it('throws if called before init()', () => {
+        const roster = new Roster({ local: false });
+        assert.throws(() => roster.loadCertificate('example.com'), /Call init\(\) before loadCertificate/);
+    });
+
+    it('throws in local mode', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('local-load.example', () => () => {});
+        await roster.init();
+        assert.throws(() => roster.loadCertificate('local-load.example'), /not available in local mode/);
+    });
+});
+
+describe('Roster createManagedHttpsServer()', () => {
+    it('throws if called before init()', async () => {
+        const roster = new Roster({ local: false });
+        await assert.rejects(
+            () => roster.createManagedHttpsServer({ servername: 'example.com' }),
+            /Call init\(\) before createManagedHttpsServer/
+        );
+    });
+
+    it('throws in local mode', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('local-managed.example', () => () => {});
+        await roster.init();
+        await assert.rejects(
+            () => roster.createManagedHttpsServer({ servername: 'local-managed.example' }),
+            /not available in local mode/
+        );
+    });
+});
+
+describe('Roster createServingHttpsServer()', () => {
+    it('throws if called before init()', async () => {
+        const roster = new Roster({ local: false });
+        await assert.rejects(
+            () => roster.createServingHttpsServer({ servername: 'example.com' }),
+            /Call init\(\) before createManagedHttpsServer/
+        );
+    });
+
+    it('throws in local mode', async () => {
+        const roster = new Roster({ local: true });
+        roster.register('local-serving.example', () => () => {});
+        await roster.init();
+        await assert.rejects(
+            () => roster.createServingHttpsServer({ servername: 'local-serving.example' }),
+            /not available in local mode/
+        );
+    });
+});
+
 describe('Roster attach()', () => {
     it('throws if called before init()', () => {
         const roster = new Roster({ local: true });

package/test/scanner-blocker.test.js

@@ -0,0 +1,189 @@
+'use strict';
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+const Roster = require('../index.js');
+const { createScannerBlocker } = require('../plugins/scanner-blocker.js');
+
+function invoke(plugin, { url = '/', ip = '192.0.2.10', headers = {}, method = 'GET' } = {}) {
+    let statusCode;
+    let responseHeaders;
+    let body;
+    const req = {
+        method,
+        url,
+        headers,
+        socket: { remoteAddress: ip }
+    };
+    const res = {
+        writeHead(code, nextHeaders) {
+            statusCode = code;
+            responseHeaders = nextHeaders;
+        },
+        end(nextBody) {
+            body = nextBody;
+        }
+    };
+    const handled = plugin(req, res, { host: 'example.com', domain: 'example.com' });
+    return { handled, statusCode, responseHeaders, body };
+}
+
+function blocker(overrides = {}) {
+    return createScannerBlocker({
+        windowMs: 60_000,
+        strikeThreshold: 2,
+        banDurationMs: 300_000,
+        maxTrackedClients: 100,
+        trustProxy: false,
+        ...overrides
+    });
+}
+
+describe('scanner-blocker plugin', () => {
+    it('requires every operational option explicitly', () => {
+        assert.throws(() => createScannerBlocker(), /options are required/);
+        assert.throws(() => createScannerBlocker({}), /windowMs/);
+        assert.throws(() => blocker({ trustProxy: undefined }), /trustProxy/);
+        assert.throws(() => blocker({ maxTrackedClients: 0 }), /maxTrackedClients/);
+    });
+
+    it('blocks PHP, WordPress, and sensitive-file probes', () => {
+        const urls = [
+            '/install.php',
+            '/user-new\\.php',
+            '/wp-json',
+            '/.git/config',
+            '/%252eenv'
+        ];
+
+        for (const [index, url] of urls.entries()) {
+            const result = invoke(blocker(), { url, ip: `192.0.2.${index + 1}` });
+            assert.strictEqual(result.handled, true, url);
+            assert.strictEqual(result.statusCode, 404, url);
+            assert.strictEqual(result.body, 'Not Found', url);
+            assert.strictEqual(result.responseHeaders['Cache-Control'], 'no-store');
+        }
+    });
+
+    it('does not classify ordinary article, atom, or config routes as scanner probes', () => {
+        const plugin = blocker();
+        assert.strictEqual(invoke(plugin, { url: '/en/an-article' }).handled, false);
+        assert.strictEqual(invoke(plugin, { url: '/atom' }).handled, false);
+        assert.strictEqual(invoke(plugin, { url: '/articles/config' }).handled, false);
+    });
+
+    it('bans a client after the configured number of probes', () => {
+        const timestamp = 1_000;
+        const events = [];
+        const plugin = blocker({
+            now: () => timestamp,
+            onBlock: event => events.push(event)
+        });
+
+        assert.strictEqual(invoke(plugin, { url: '/wp-login.php' }).handled, true);
+        assert.strictEqual(invoke(plugin, { url: '/xmlrpc.php' }).handled, true);
+        assert.strictEqual(invoke(plugin, { url: '/legitimate-page' }).handled, true);
+        assert.strictEqual(events[1].bannedUntil, 301_000);
+        assert.strictEqual(events[2].type, 'banned-client');
+
+        assert.strictEqual(invoke(plugin, { url: '/legitimate-page', ip: '192.0.2.11' }).handled, false);
+    });
+
+    it('expires bans without extending them on blocked requests', () => {
+        let timestamp = 1_000;
+        const events = [];
+        const plugin = blocker({
+            strikeThreshold: 1,
+            banDurationMs: 5_000,
+            now: () => timestamp,
+            onBlock: event => events.push(event)
+        });
+
+        invoke(plugin, { url: '/wp-login.php' });
+        assert.strictEqual(events[0].bannedUntil, 6_000);
+        timestamp = 5_999;
+        assert.strictEqual(invoke(plugin, { url: '/ordinary' }).handled, true);
+        timestamp = 6_000;
+        assert.strictEqual(invoke(plugin, { url: '/ordinary' }).handled, false);
+    });
+
+    it('trusts X-Forwarded-For only when explicitly configured', () => {
+        const headers = { 'x-forwarded-for': '198.51.100.1, 198.51.100.2' };
+        const directPlugin = blocker({ strikeThreshold: 1, trustProxy: false });
+        invoke(directPlugin, { url: '/install.php', headers, ip: '192.0.2.20' });
+        assert.strictEqual(invoke(directPlugin, { url: '/', headers, ip: '192.0.2.20' }).handled, true);
+        assert.strictEqual(invoke(directPlugin, { url: '/', headers, ip: '192.0.2.21' }).handled, false);
+
+        const proxyPlugin = blocker({ strikeThreshold: 1, trustProxy: true });
+        invoke(proxyPlugin, { url: '/install.php', headers, ip: '192.0.2.20' });
+        assert.strictEqual(invoke(proxyPlugin, { url: '/', headers, ip: '192.0.2.21' }).handled, true);
+    });
+
+    it('keeps tracked client state within the configured bound', () => {
+        const plugin = blocker({ maxTrackedClients: 1 });
+        invoke(plugin, { url: '/install.php', ip: '192.0.2.30' });
+        invoke(plugin, { url: '/install.php', ip: '192.0.2.31' });
+        invoke(plugin, { url: '/xmlrpc.php', ip: '192.0.2.30' });
+        assert.strictEqual(invoke(plugin, { url: '/ordinary', ip: '192.0.2.30' }).handled, false);
+    });
+
+    it('does not send a response body for HEAD probes', () => {
+        const result = invoke(blocker(), { method: 'HEAD', url: '/wp-login.php' });
+        assert.strictEqual(result.handled, true);
+        assert.strictEqual(result.body, undefined);
+    });
+});
+
+describe('Roster request plugins', () => {
+    it('runs plugins before dispatching to the site handler', async () => {
+        let siteRequests = 0;
+        const roster = new Roster({ local: true });
+        roster.use(createScannerBlocker({
+            windowMs: 60_000,
+            strikeThreshold: 2,
+            banDurationMs: 300_000,
+            maxTrackedClients: 100,
+            trustProxy: false
+        }));
+        roster.register('example.com', () => (req, res) => {
+            siteRequests += 1;
+            res.writeHead(200);
+            res.end('site');
+        });
+        await roster.init();
+
+        const handler = roster.requestHandler();
+        const probe = invoke(handler, {
+            url: '/wp-login.php',
+            headers: { host: 'example.com' }
+        });
+        assert.strictEqual(probe.statusCode, 404);
+        assert.strictEqual(siteRequests, 0);
+
+        const ordinary = invoke(handler, {
+            url: '/ordinary',
+            ip: '192.0.2.11',
+            headers: { host: 'example.com' }
+        });
+        assert.strictEqual(ordinary.statusCode, 200);
+        assert.strictEqual(ordinary.body, 'site');
+        assert.strictEqual(siteRequests, 1);
+    });
+
+    it('validates plugins and rejects asynchronous request plugins', async () => {
+        const roster = new Roster({ local: true });
+        assert.throws(() => roster.use({}), /plugin must be a function/);
+        assert.strictEqual(roster.use(() => false), roster);
+
+        const asyncRoster = new Roster({ local: true });
+        asyncRoster.use(async () => false);
+        asyncRoster.register('example.com', () => () => {});
+        await asyncRoster.init();
+        assert.throws(() => {
+            asyncRoster.requestHandler()(
+                { headers: { host: 'example.com' }, url: '/', socket: {} },
+                { writeHead() {}, end() {} }
+            );
+        }, /must be synchronous/);
+    });
+});

package/.greenlockrc

@@ -1 +0,0 @@
-{"configDir":"/Users/martinclasen/Stuff/greenlock.d"}

package/demo/cluster-sticky-worker.js

@@ -1,60 +0,0 @@
-const http = require('http');
-const Roster = require('../index.js');
-
-async function main() {
-    const roster = new Roster({
-        local: true,
-        minLocalPort: 19500,
-        maxLocalPort: 19550
-    });
-
-    roster.register('example.com', () => {
-        return (req, res) => {
-            res.writeHead(200, { 'Content-Type': 'text/plain' });
-            res.end('[example.com] hello from external worker wiring');
-        };
-    });
-
-    roster.register('api.example.com:9000', () => {
-        return (req, res) => {
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ ok: true, source: 'api.example.com:9000' }));
-        };
-    });
-
-    // init() prepares virtual-host routing, but does not create/listen sockets.
-    await roster.init();
-
-    // This server represents your external runtime-owned worker server.
-    const server443 = http.createServer();
-    roster.attach(server443); // defaultPort routes (443)
-
-    const server9000 = http.createServer();
-    roster.attach(server9000, { port: 9000 }); // custom port routes
-
-    await new Promise((resolve, reject) => {
-        server443.listen(19501, 'localhost', resolve);
-        server443.on('error', reject);
-    });
-
-    await new Promise((resolve, reject) => {
-        server9000.listen(19502, 'localhost', resolve);
-        server9000.on('error', reject);
-    });
-
-    console.log('\n✅ Cluster-friendly worker demo running');
-    console.log('Roster did not bind ports itself. External servers own listen().\n');
-    console.log('Try requests with Host headers:');
-    console.log('curl -H "Host: example.com" http://localhost:19501/');
-    console.log('curl -H "Host: api.example.com" http://localhost:19502/\n');
-
-    // Sticky-session runtimes normally pass accepted sockets into the worker:
-    // process.on('message', (msg, socket) => {
-    //     if (msg === 'sticky-session:connection') server443.emit('connection', socket);
-    // });
-}
-
-main().catch((err) => {
-    console.error('Demo failed:', err);
-    process.exit(1);
-});