@zero-server/sdk 0.9.0 → 0.9.2

package/lib/middleware/helmet.js

@@ -1,176 +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.
- *
+/**
+ * @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;
+ * @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

@@ -1,17 +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');
-
-module.exports = { cors, logger, rateLimit, compress, static: serveStatic, helmet, timeout, requestId, cookieParser, errorHandler };
+/**
+ * @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

@@ -1,74 +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;
+/**
+ * @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;