@zero-server/middleware 0.9.1 → 0.9.2

package/lib/middleware/helmet.js

@@ -0,0 +1,176 @@
+/**
+ * @module helmet
+ * @description Security headers middleware.
+ *              Sets common security-related HTTP response headers to help
+ *              protect against well-known web vulnerabilities (XSS, clickjacking,
+ *              MIME sniffing, etc.).
+ *
+ *              Inspired by the `helmet` npm package but zero-dependency.
+ */
+
+/**
+ * Create a security headers middleware.
+ *
+ * @param {object}  [opts] - Configuration options.
+ * @param {object|false}  [opts.contentSecurityPolicy]      - CSP directive object or `false` to disable.
+ * @param {boolean}       [opts.crossOriginEmbedderPolicy=false]  - Set COEP header.
+ * @param {string|false}  [opts.crossOriginOpenerPolicy='same-origin'] - COOP value.
+ * @param {string|false}  [opts.crossOriginResourcePolicy='same-origin'] - CORP value.
+ * @param {boolean}       [opts.dnsPrefetchControl=true]    - Set X-DNS-Prefetch-Control: off.
+ * @param {string|false}  [opts.frameguard='deny']          - X-Frame-Options value ('deny' | 'sameorigin').
+ * @param {boolean}       [opts.hidePoweredBy=true]         - Remove X-Powered-By header.
+ * @param {boolean|number}[opts.hsts=true]                  - Set Strict-Transport-Security.
+ * @param {number}        [opts.hstsMaxAge=15552000]        - HSTS max-age in seconds (default ~180 days).
+ * @param {boolean}       [opts.hstsIncludeSubDomains=true] - HSTS includeSubDomains directive.
+ * @param {boolean}       [opts.hstsPreload=false]          - HSTS preload directive.
+ * @param {boolean}       [opts.ieNoOpen=true]              - Set X-Download-Options: noopen.
+ * @param {boolean}       [opts.noSniff=true]               - Set X-Content-Type-Options: nosniff.
+ * @param {string|false}  [opts.permittedCrossDomainPolicies='none'] - X-Permitted-Cross-Domain-Policies.
+ * @param {string|false}  [opts.referrerPolicy='no-referrer'] - Referrer-Policy value.
+ * @param {boolean}       [opts.xssFilter=false]            - Set X-XSS-Protection (legacy, off by default).
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   app.use(helmet());
+ *   app.use(helmet({ frameguard: 'sameorigin', hsts: false }));
+ *   app.use(helmet({
+ *       contentSecurityPolicy: {
+ *           directives: {
+ *               defaultSrc: ["'self'"],
+ *               scriptSrc: ["'self'", "'unsafe-inline'"],
+ *               styleSrc: ["'self'", "'unsafe-inline'"],
+ *               imgSrc: ["'self'", "data:", "https:"],
+ *           }
+ *       }
+ *   }));
+ */
+function helmet(opts = {})
+{
+    return (req, res, next) =>
+    {
+        const raw = res.raw || res;
+
+        // -- Content-Security-Policy --------------------
+        if (opts.contentSecurityPolicy !== false)
+        {
+            const csp = opts.contentSecurityPolicy || {};
+            const directives = csp.directives || {
+                defaultSrc: ["'self'"],
+                baseUri: ["'self'"],
+                fontSrc: ["'self'", 'https:', 'data:'],
+                formAction: ["'self'"],
+                frameAncestors: ["'self'"],
+                imgSrc: ["'self'", 'data:'],
+                objectSrc: ["'none'"],
+                scriptSrc: ["'self'"],
+                scriptSrcAttr: ["'none'"],
+                styleSrc: ["'self'", "'unsafe-inline'"],
+                upgradeInsecureRequests: [],
+            };
+
+            const cspString = Object.entries(directives)
+                .map(([key, values]) =>
+                {
+                    const directive = key.replace(/([A-Z])/g, '-$1').toLowerCase();
+                    if (Array.isArray(values) && values.length === 0) return directive;
+                    return `${directive} ${Array.isArray(values) ? values.join(' ') : values}`;
+                })
+                .join('; ');
+
+            if (cspString)
+            {
+                try { raw.setHeader('Content-Security-Policy', cspString); } catch (e) { }
+            }
+        }
+
+        // -- Cross-Origin-Embedder-Policy ---------------
+        if (opts.crossOriginEmbedderPolicy)
+        {
+            try { raw.setHeader('Cross-Origin-Embedder-Policy', 'require-corp'); } catch (e) { }
+        }
+
+        // -- Cross-Origin-Opener-Policy -----------------
+        if (opts.crossOriginOpenerPolicy !== false)
+        {
+            const coop = opts.crossOriginOpenerPolicy || 'same-origin';
+            try { raw.setHeader('Cross-Origin-Opener-Policy', coop); } catch (e) { }
+        }
+
+        // -- Cross-Origin-Resource-Policy ---------------
+        if (opts.crossOriginResourcePolicy !== false)
+        {
+            const corp = opts.crossOriginResourcePolicy || 'same-origin';
+            try { raw.setHeader('Cross-Origin-Resource-Policy', corp); } catch (e) { }
+        }
+
+        // -- DNS Prefetch Control -----------------------
+        if (opts.dnsPrefetchControl !== false)
+        {
+            try { raw.setHeader('X-DNS-Prefetch-Control', 'off'); } catch (e) { }
+        }
+
+        // -- Frameguard (X-Frame-Options) ---------------
+        if (opts.frameguard !== false)
+        {
+            const frame = (opts.frameguard || 'deny').toUpperCase();
+            try { raw.setHeader('X-Frame-Options', frame); } catch (e) { }
+        }
+
+        // -- Hide X-Powered-By -------------------------
+        if (opts.hidePoweredBy !== false)
+        {
+            try { raw.removeHeader('X-Powered-By'); } catch (e) { }
+        }
+
+        // -- HSTS ---------------------------------------
+        if (opts.hsts !== false)
+        {
+            const maxAge = opts.hstsMaxAge || 15552000;
+            let hstsValue = `max-age=${maxAge}`;
+            if (opts.hstsIncludeSubDomains !== false) hstsValue += '; includeSubDomains';
+            if (opts.hstsPreload) hstsValue += '; preload';
+            try { raw.setHeader('Strict-Transport-Security', hstsValue); } catch (e) { }
+        }
+
+        // -- IE No Open --------------------------------
+        if (opts.ieNoOpen !== false)
+        {
+            try { raw.setHeader('X-Download-Options', 'noopen'); } catch (e) { }
+        }
+
+        // -- No Sniff -----------------------------------
+        if (opts.noSniff !== false)
+        {
+            try { raw.setHeader('X-Content-Type-Options', 'nosniff'); } catch (e) { }
+        }
+
+        // -- Permitted Cross Domain Policies ------------
+        if (opts.permittedCrossDomainPolicies !== false)
+        {
+            const pcdp = opts.permittedCrossDomainPolicies || 'none';
+            try { raw.setHeader('X-Permitted-Cross-Domain-Policies', pcdp); } catch (e) { }
+        }
+
+        // -- Referrer Policy ----------------------------
+        if (opts.referrerPolicy !== false)
+        {
+            const rp = opts.referrerPolicy || 'no-referrer';
+            try { raw.setHeader('Referrer-Policy', rp); } catch (e) { }
+        }
+
+        // -- XSS Filter (legacy) -----------------------
+        if (opts.xssFilter)
+        {
+            try { raw.setHeader('X-XSS-Protection', '1; mode=block'); } catch (e) { }
+        }
+        else
+        {
+            // Modern best practice: disable legacy XSS auditor
+            try { raw.setHeader('X-XSS-Protection', '0'); } catch (e) { }
+        }
+
+        next();
+    };
+}
+
+module.exports = helmet;

package/lib/middleware/index.js

@@ -0,0 +1,19 @@
+/**
+ * @module middleware
+ * @description Built-in middleware for zero-server.
+ *              Re-exports all middleware.
+ */
+const cors = require('./cors');
+const logger = require('./logger');
+const rateLimit = require('./rateLimit');
+const compress = require('./compress');
+const serveStatic = require('./static');
+const helmet = require('./helmet');
+const timeout = require('./timeout');
+const requestId = require('./requestId');
+const cookieParser = require('./cookieParser');
+const errorHandler = require('./errorHandler');
+const csrf = require('./csrf');
+const validate = require('./validator');
+
+module.exports = { cors, logger, rateLimit, compress, static: serveStatic, helmet, timeout, requestId, cookieParser, errorHandler, csrf, validate };

package/lib/middleware/logger.js

@@ -0,0 +1,74 @@
+/**
+ * @module middleware/logger
+ * @description Simple request-logging middleware.
+ *              Logs method, url, status code, and response time.
+ *
+ * @param {object}  [opts] - Configuration options.
+ * @param {function} [opts.logger]   - Custom log function (default: console.log).
+ * @param {boolean}  [opts.colors]   - Colorize output (default: true when TTY).
+ * @param {string}   [opts.format]   - 'tiny' | 'short' | 'dev' (default: 'dev').
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   app.use(logger());                           // default 'dev' format
+ *   app.use(logger({ format: 'tiny' }));          // minimal output
+ *   app.use(logger({ colors: false, logger: msg => fs.appendFileSync('access.log', msg + '\n') }));
+ */
+function logger(opts = {})
+{
+    const log = typeof opts.logger === 'function' ? opts.logger : console.log;
+    const useColors = opts.colors !== undefined ? opts.colors : (process.stdout.isTTY || false);
+    const format = opts.format || 'dev';
+
+    // ANSI color helpers
+    const c = {
+        reset: useColors ? '\x1b[0m' : '',
+        green: useColors ? '\x1b[32m' : '',
+        yellow: useColors ? '\x1b[33m' : '',
+        red: useColors ? '\x1b[31m' : '',
+        cyan: useColors ? '\x1b[36m' : '',
+        dim: useColors ? '\x1b[2m' : '',
+    };
+
+    function statusColor(code)
+    {
+        if (code >= 500) return c.red;
+        if (code >= 400) return c.yellow;
+        if (code >= 300) return c.cyan;
+        return c.green;
+    }
+
+    return (req, res, next) =>
+    {
+        const start = Date.now();
+
+        // Hook into the raw response 'finish' event
+        const raw = res.raw;
+        const onFinish = () =>
+        {
+            raw.removeListener('finish', onFinish);
+            const ms = Date.now() - start;
+            const status = raw.statusCode || res._status;
+            const sc = statusColor(status);
+
+            if (format === 'tiny')
+            {
+                log(`${req.method} ${req.url} ${status} - ${ms}ms`);
+            }
+            else if (format === 'short')
+            {
+                log(`${req.ip || '-'} ${req.method} ${req.url} ${sc}${status}${c.reset} ${ms}ms`);
+            }
+            else
+            {
+                // dev format
+                log(`  ${c.dim}${req.method}${c.reset} ${req.url} ${sc}${status}${c.reset} ${c.dim}${ms}ms${c.reset}`);
+            }
+        };
+        raw.on('finish', onFinish);
+
+        next();
+    };
+}
+
+module.exports = logger;

package/lib/middleware/rateLimit.js

@@ -0,0 +1,88 @@
+/**
+ * @module middleware/rateLimit
+ * @description In-memory rate-limiting middleware.
+ *              Limits requests per IP address within a fixed time window.
+ */
+const log = require('../debug')('zero:rateLimit');
+
+/**
+ * Create a rate-limiting middleware.
+ *
+ * @param {object}  [opts] - Configuration options.
+ * @param {number}  [opts.windowMs=60000]   - Time window in milliseconds.
+ * @param {number}  [opts.max=100]          - Maximum requests per window per IP.
+ * @param {string}  [opts.message]          - Custom error message.
+ * @param {number}  [opts.statusCode=429]   - HTTP status for rate-limited responses.
+ * @param {function} [opts.keyGenerator]    - (req) => string; custom key extraction (default: req.ip).
+ * @param {function} [opts.skip]            - (req) => boolean; return true to skip rate limiting.
+ * @param {function} [opts.handler]         - (req, res) => void; custom handler for rate-limited requests.
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   app.use(rateLimit());                           // 100 req/min per IP
+ *   app.use(rateLimit({ windowMs: 15 * 60000, max: 50 })); // 50 req per 15 min
+ *   app.use(rateLimit({
+ *       max: 10,
+ *       keyGenerator: req => req.headers['x-api-key'],
+ *       skip: req => req.path === '/health',
+ *   }));
+ */
+function rateLimit(opts = {})
+{
+    const windowMs = opts.windowMs || 60_000;
+    const max = opts.max || 100;
+    const statusCode = opts.statusCode || 429;
+    const message = opts.message || 'Too many requests, please try again later.';
+    const keyGenerator = typeof opts.keyGenerator === 'function' ? opts.keyGenerator : (req) => req.ip || 'unknown';
+    const skipFn = typeof opts.skip === 'function' ? opts.skip : null;
+    const handlerFn = typeof opts.handler === 'function' ? opts.handler : null;
+
+    const hits = new Map(); // key → { count, resetTime }
+
+    // Periodic cleanup to prevent memory leaks
+    const cleanupInterval = setInterval(() =>
+    {
+        const now = Date.now();
+        for (const [key, entry] of hits)
+        {
+            if (now >= entry.resetTime) hits.delete(key);
+        }
+    }, windowMs);
+    if (cleanupInterval.unref) cleanupInterval.unref();
+
+    return (req, res, next) =>
+    {
+        // Allow skipping rate limit for certain requests
+        if (skipFn && skipFn(req)) return next();
+
+        const key = keyGenerator(req);
+        const now = Date.now();
+        let entry = hits.get(key);
+
+        if (!entry || now >= entry.resetTime)
+        {
+            entry = { count: 0, resetTime: now + windowMs };
+            hits.set(key, entry);
+        }
+
+        entry.count++;
+
+        // Set rate-limit headers
+        const remaining = Math.max(0, max - entry.count);
+        res.set('X-RateLimit-Limit', String(max));
+        res.set('X-RateLimit-Remaining', String(remaining));
+        res.set('X-RateLimit-Reset', String(Math.ceil(entry.resetTime / 1000)));
+
+        if (entry.count > max)
+        {
+            log.warn('rate limit exceeded for %s', key);
+            res.set('Retry-After', String(Math.ceil(windowMs / 1000)));
+            if (handlerFn) return handlerFn(req, res);
+            return res.status(statusCode).json({ error: message });
+        }
+
+        next();
+    };
+}
+
+module.exports = rateLimit;

package/lib/middleware/requestId.js

@@ -0,0 +1,54 @@
+/**
+ * @module requestId
+ * @description Request ID middleware.
+ *              Assigns a unique identifier to each incoming request for
+ *              tracing and debugging. Sets the ID on both the request
+ *              object and as a response header.
+ */
+const crypto = require('crypto');
+
+/**
+ * Create a request ID middleware.
+ *
+ * @param {object}   [opts] - Configuration options.
+ * @param {string}   [opts.header='X-Request-Id']   - Response header name.
+ * @param {Function} [opts.generator]               - Custom ID generator `() => string`.
+ * @param {boolean}  [opts.trustProxy=false]         - Trust incoming X-Request-Id header from proxy.
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   app.use(requestId());
+ *   app.get('/', (req, res) => {
+ *       console.log(req.id); // e.g. '7f3a2b1c-...'
+ *   });
+ */
+function requestId(opts = {})
+{
+    const headerName = opts.header || 'X-Request-Id';
+    const trustProxy = !!opts.trustProxy;
+    const generator = typeof opts.generator === 'function'
+        ? opts.generator
+        : () => crypto.randomUUID();
+
+    return (req, res, next) =>
+    {
+        let id;
+
+        if (trustProxy)
+        {
+            const existing = req.headers[headerName.toLowerCase()];
+            if (existing && typeof existing === 'string' && existing.length <= 128)
+            {
+                id = existing;
+            }
+        }
+
+        if (!id) id = generator();
+
+        req.id = id;
+        res.set(headerName, id);
+        next();
+    };
+}
+
+module.exports = requestId;