zero-http 0.2.5 → 0.3.1

package/lib/middleware/cookieParser.js

@@ -0,0 +1,237 @@
+/**
+ * @module cookieParser
+ * @description Cookie parsing middleware.
+ *              Parses the `Cookie` header and populates `req.cookies`.
+ *              Supports signed cookies, JSON cookies, secret rotation,
+ *              and timing-safe signature verification.
+ */
+const crypto = require('crypto');
+
+// -- Internal helpers ------------------------------------
+
+/**
+ * Timing-safe HMAC-SHA256 signature comparison.
+ * Prevents timing-based side-channel attacks on cookie signatures.
+ *
+ * @param {string} data    - The cookie payload.
+ * @param {string} sig     - The provided signature (base64, no padding).
+ * @param {string} secret  - Secret to verify against.
+ * @returns {boolean}
+ * @private
+ */
+function _timingSafeVerify(data, sig, secret)
+{
+    try
+    {
+        const expected = crypto
+            .createHmac('sha256', secret)
+            .update(data)
+            .digest('base64')
+            .replace(/=+$/, '');
+        if (expected.length !== sig.length) return false;
+        return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
+    }
+    catch (e) { return false; }
+}
+
+/**
+ * Verify and unsign a signed cookie value.
+ * Signed cookies have the format: `s:<value>.<signature>`.
+ * All secret(s) are attempted to support key rotation.
+ *
+ * @param {string}   val     - Raw cookie value.
+ * @param {string[]} secrets - Array of secrets to try.
+ * @returns {string|false} Unsigned value on success, `false` on failure.
+ * @private
+ */
+function _unsign(val, secrets)
+{
+    if (typeof val !== 'string' || !val.startsWith('s:')) return val;
+    const payload = val.slice(2);
+    const dotIdx = payload.lastIndexOf('.');
+    if (dotIdx === -1) return false;
+
+    const data = payload.slice(0, dotIdx);
+    const sig = payload.slice(dotIdx + 1);
+
+    for (const s of secrets)
+    {
+        if (_timingSafeVerify(data, sig, s)) return data;
+    }
+    return false;
+}
+
+/**
+ * Try to parse a value as a JSON cookie (prefixed with `j:`).
+ *
+ * @param {string} val - Cookie value.
+ * @returns {*} Parsed value or original string.
+ * @private
+ */
+function _parseJSONCookie(val)
+{
+    if (typeof val !== 'string' || !val.startsWith('j:')) return val;
+    try { return JSON.parse(val.slice(2)); }
+    catch (e) { return val; }
+}
+
+// -- Middleware factory ----------------------------------
+
+/**
+ * Create a cookie parsing middleware.
+ *
+ * Features:
+ *   - Signed cookies with HMAC-SHA256 and timing-safe verification
+ *   - Secret rotation (array of secrets, newest first)
+ *   - JSON cookies (`j:` prefix, auto-parsed)
+ *   - `req.secret` / `req.secrets` exposed for downstream middleware
+ *   - URI-decode toggle
+ *
+ * @param {string|string[]} [secret] - Secret(s) for signing / verifying cookies.
+ * @param {object}          [opts]
+ * @param {boolean}         [opts.decode=true] - URI-decode cookie values.
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   app.use(cookieParser());
+ *   app.use(cookieParser('my-secret'));
+ *   app.use(cookieParser(['new-secret', 'old-secret'])); // key rotation
+ */
+function cookieParser(secret, opts = {})
+{
+    const secrets = secret
+        ? (Array.isArray(secret) ? secret : [secret])
+        : [];
+    const decode = opts.decode !== false;
+
+    return (req, res, next) =>
+    {
+        const header = req.headers.cookie;
+        req.cookies = {};
+        req.signedCookies = {};
+
+        // Expose secret(s) for downstream use (res.cookie signed:true, csrf, etc.)
+        if (secrets.length)
+        {
+            req.secret = secrets[0];
+            req.secrets = secrets;
+        }
+
+        if (!header)
+        {
+            return next();
+        }
+
+        const pairs = header.split(';');
+        for (const pair of pairs)
+        {
+            const eqIdx = pair.indexOf('=');
+            if (eqIdx === -1) continue;
+
+            const name = pair.slice(0, eqIdx).trim();
+            let val = pair.slice(eqIdx + 1).trim();
+
+            // Remove surrounding quotes if any
+            if (val.length >= 2 && val[0] === '"' && val[val.length - 1] === '"')
+            {
+                val = val.slice(1, -1);
+            }
+
+            // URI decode
+            if (decode)
+            {
+                try { val = decodeURIComponent(val); } catch (e) { /* keep raw */ }
+            }
+
+            // Signed cookies → verify, then JSON-parse if j: prefixed
+            if (secrets.length > 0 && val.startsWith('s:'))
+            {
+                const unsigned = _unsign(val, secrets);
+                if (unsigned !== false)
+                {
+                    req.signedCookies[name] = _parseJSONCookie(unsigned);
+                }
+                // Failed-verification signed cookies are silently dropped
+            }
+            // JSON cookies → auto-parse
+            else if (val.startsWith('j:'))
+            {
+                req.cookies[name] = _parseJSONCookie(val);
+            }
+            else
+            {
+                req.cookies[name] = val;
+            }
+        }
+
+        next();
+    };
+}
+
+// -- Static helpers --------------------------------------
+
+/**
+ * Sign a cookie value with the given secret.
+ *
+ * @param {string} val    - Cookie value to sign.
+ * @param {string} secret - Signing secret.
+ * @returns {string} Signed value in format `s:<value>.<signature>`.
+ *
+ * @example
+ *   const signed = cookieParser.sign('hello', 'my-secret');
+ *   // => 's:hello.DGDyS...'
+ */
+cookieParser.sign = function sign(val, secret)
+{
+    const sig = crypto
+        .createHmac('sha256', secret)
+        .update(String(val))
+        .digest('base64')
+        .replace(/=+$/, '');
+    return `s:${val}.${sig}`;
+};
+
+/**
+ * Verify and unsign a signed cookie value.
+ *
+ * @param {string}          val    - Signed cookie value (`s:data.sig`).
+ * @param {string|string[]} secret - Secret or array of secrets (for rotation).
+ * @returns {string|false} Unsigned value on success, `false` on failure.
+ *
+ * @example
+ *   const value = cookieParser.unsign('s:hello.DGDyS...', 'my-secret');
+ *   // => 'hello' or false
+ */
+cookieParser.unsign = function unsign(val, secret)
+{
+    const secrets = Array.isArray(secret) ? secret : [secret];
+    return _unsign(val, secrets);
+};
+
+/**
+ * Serialize a value as a JSON cookie string (prefixed with `j:`).
+ *
+ * @param {*} val - Value to serialize (object, array, etc.).
+ * @returns {string} JSON cookie string.
+ *
+ * @example
+ *   const jcookie = cookieParser.jsonCookie({ cart: [1,2,3] });
+ *   // => 'j:{"cart":[1,2,3]}'
+ */
+cookieParser.jsonCookie = function jsonCookie(val)
+{
+    return 'j:' + JSON.stringify(val);
+};
+
+/**
+ * Parse a JSON cookie string (must start with `j:`).
+ *
+ * @param {string} str - JSON cookie string.
+ * @returns {*} Parsed value, or the original string if not a valid JSON cookie.
+ */
+cookieParser.parseJSON = function parseJSON(str)
+{
+    return _parseJSONCookie(str);
+};
+
+module.exports = cookieParser;

package/lib/middleware/cors.js

@@ -14,7 +14,9 @@
  *                                                           starting with `'.'` for suffix matching.
  * @param {string}           [options.methods='GET,POST,PUT,DELETE,OPTIONS'] - Allowed HTTP methods.
  * @param {string}           [options.allowedHeaders='Content-Type,Authorization'] - Allowed request headers.
- * @param {boolean}          [options.credentials=false]   - Whether to set `Access-Control-Allow-Credentials`.
+ * @param {string}           [options.exposedHeaders]       - Headers the browser is allowed to read.
+ * @param {boolean}          [options.credentials=false]    - Whether to set `Access-Control-Allow-Credentials`.
+ * @param {number}           [options.maxAge]               - Preflight cache duration in seconds.
  * @returns {Function} Middleware `(req, res, next) => void`.
  */
 function cors(options = {})
@@ -23,6 +25,12 @@ function cors(options = {})
     const allowMethods = (options.methods || 'GET,POST,PUT,DELETE,OPTIONS');
     const allowHeaders = (options.allowedHeaders || 'Content-Type,Authorization');
 
+    // RFC 6454: credentials cannot be used with wildcard origin
+    if (options.credentials && allowOrigin === '*')
+    {
+        throw new Error('CORS credentials cannot be used with wildcard origin "*". Specify explicit origins instead.');
+    }
+
     /**
      * Resolve the Origin header value to echo back based on the configured
      * allow-list.  Returns `null` when the origin should not be allowed.
@@ -57,12 +65,15 @@ function cors(options = {})
         if (originValue)
         {
             res.set('Access-Control-Allow-Origin', originValue);
-            // allow credentials when matching specific origin
+            // Set Vary: Origin when not using wildcard (important for caching proxies)
+            if (originValue !== '*') res.vary('Origin');
             if (options.credentials) res.set('Access-Control-Allow-Credentials', 'true');
         }
 
         if (allowMethods) res.set('Access-Control-Allow-Methods', allowMethods);
         if (allowHeaders) res.set('Access-Control-Allow-Headers', allowHeaders);
+        if (options.exposedHeaders) res.set('Access-Control-Expose-Headers', options.exposedHeaders);
+        if (options.maxAge !== undefined) res.set('Access-Control-Max-Age', String(options.maxAge));
 
         if (req.method === 'OPTIONS') return res.status(204).send();
         next();

package/lib/middleware/csrf.js

@@ -0,0 +1,135 @@
+/**
+ * @module middleware/csrf
+ * @description CSRF (Cross-Site Request Forgery) protection middleware.
+ *              Uses the double-submit cookie + header/body token pattern.
+ *
+ *              Safe methods (GET, HEAD, OPTIONS) are skipped automatically.
+ *              For state-changing requests (POST, PUT, PATCH, DELETE), the
+ *              middleware checks for a matching token in:
+ *                1. `req.headers['x-csrf-token']`
+ *                2. `req.body._csrf` (if body parsed)
+ *                3. `req.query._csrf`
+ *
+ * @example
+ *   const { createApp, csrf } = require('zero-http');
+ *   const app = createApp();
+ *
+ *   app.use(csrf());                   // default options
+ *   app.use(csrf({ cookie: 'tok' }));  // custom cookie name
+ *
+ *   // In a route, read the token for forms / SPA:
+ *   app.get('/form', (req, res) => {
+ *       res.json({ csrfToken: req.csrfToken });
+ *   });
+ */
+const crypto = require('crypto');
+const log = require('../debug')('zero:csrf');
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.cookie='_csrf']       - Name of the double-submit cookie.
+ * @param {string} [options.header='x-csrf-token'] - Request header that carries the token.
+ * @param {number} [options.saltLength=18]        - Bytes of randomness for token generation.
+ * @param {string} [options.secret]               - HMAC secret. Auto-generated per process if omitted.
+ * @param {string[]} [options.ignoreMethods]      - HTTP methods to skip. Default: GET, HEAD, OPTIONS.
+ * @param {string[]} [options.ignorePaths]        - Path prefixes to skip (e.g. ['/api/webhooks']).
+ * @param {Function} [options.onError]            - Custom error handler `(req, res) => {}`.
+ * @returns {Function} Middleware function.
+ */
+function csrf(options = {})
+{
+    const cookieName    = options.cookie || '_csrf';
+    const headerName    = (options.header || 'x-csrf-token').toLowerCase();
+    const saltLen       = options.saltLength || 18;
+    const secret        = options.secret || crypto.randomBytes(32).toString('hex');
+    const ignoreMethods = new Set((options.ignoreMethods || ['GET', 'HEAD', 'OPTIONS']).map(m => m.toUpperCase()));
+    const ignorePaths   = options.ignorePaths || [];
+
+    function generateToken()
+    {
+        try
+        {
+            const salt = crypto.randomBytes(saltLen).toString('hex');
+            const hash = crypto.createHmac('sha256', secret).update(salt).digest('hex');
+            return `${salt}.${hash}`;
+        }
+        catch (e) { return null; }
+    }
+
+    function verifyToken(token)
+    {
+        if (!token || typeof token !== 'string') return false;
+        const parts = token.split('.');
+        if (parts.length !== 2) return false;
+        const [salt, hash] = parts;
+        try
+        {
+            const expected = crypto.createHmac('sha256', secret).update(salt).digest('hex');
+            // Constant-time comparison
+            if (expected.length !== hash.length) return false;
+            return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(hash));
+        }
+        catch (e) { return false; }
+    }
+
+    return function csrfMiddleware(req, res, next)
+    {
+        // Skip safe methods
+        if (ignoreMethods.has(req.method))
+        {
+            // Ensure a token exists in the cookie for the client to read
+            const existing = req.cookies && req.cookies[cookieName];
+            if (!existing || !verifyToken(existing))
+            {
+                const token = generateToken();
+                const secure = req.secure ? '; Secure' : '';
+                res.set('Set-Cookie',
+                    `${cookieName}=${token}; Path=/; HttpOnly; SameSite=Strict${secure}`
+                );
+                req.csrfToken = token;
+            }
+            else
+            {
+                req.csrfToken = existing;
+            }
+            return next();
+        }
+
+        // Skip ignored paths
+        const pathname = req.url.split('?')[0];
+        for (const prefix of ignorePaths)
+        {
+            if (pathname.startsWith(prefix)) return next();
+        }
+
+        // Extract the token the client sent
+        const clientToken =
+            req.headers[headerName] ||
+            (req.body && req.body._csrf) ||
+            (req.query && req.query._csrf) ||
+            null;
+
+        // Extract the cookie token
+        const cookieToken = req.cookies && req.cookies[cookieName];
+
+        // Both must exist and be valid, and must match
+        if (!clientToken || !cookieToken || clientToken !== cookieToken || !verifyToken(clientToken))
+        {
+            log.warn('CSRF validation failed for %s %s', req.method, pathname);
+            if (options.onError) return options.onError(req, res);
+            res.status(403).json({ error: 'CSRF token missing or invalid' });
+            return;
+        }
+
+        // Rotate token on each state-changing request
+        const newToken = generateToken();
+        const secure = req.secure ? '; Secure' : '';
+        res.set('Set-Cookie',
+            `${cookieName}=${newToken}; Path=/; HttpOnly; SameSite=Strict${secure}`
+        );
+        req.csrfToken = newToken;
+        next();
+    };
+}
+
+module.exports = csrf;

package/lib/middleware/errorHandler.js

@@ -0,0 +1,90 @@
+/**
+ * @module middleware/errorHandler
+ * @description Configurable error-handling middleware that formats error responses
+ *              based on environment (dev vs production), supports custom formatters,
+ *              and integrates with HttpError classes.
+ *
+ * @param {object}   [opts]
+ * @param {boolean}  [opts.stack]      - Include stack traces in responses (default: true when NODE_ENV !== 'production').
+ * @param {boolean}  [opts.log]        - Log errors to console (default: true).
+ * @param {function} [opts.logger]     - Custom log function (default: console.error).
+ * @param {function} [opts.formatter]  - Custom response formatter: (err, req, isDev) => object.
+ * @param {function} [opts.onError]    - Callback on every error: (err, req, res) => void.
+ * @returns {function} Error-handling middleware `(err, req, res, next) => void`.
+ */
+const { HttpError, isHttpError } = require('../errors');
+
+function errorHandler(opts = {})
+{
+    const isDev = opts.stack !== undefined
+        ? opts.stack
+        : (process.env.NODE_ENV !== 'production');
+
+    const shouldLog = opts.log !== undefined ? opts.log : true;
+    const logFn = typeof opts.logger === 'function' ? opts.logger : console.error;
+    const formatter = typeof opts.formatter === 'function' ? opts.formatter : null;
+    const onError = typeof opts.onError === 'function' ? opts.onError : null;
+
+    return (err, req, res, next) =>
+    {
+        // Resolve status code
+        let statusCode = err.statusCode || err.status || 500;
+        if (typeof statusCode !== 'number' || statusCode < 100 || statusCode > 599) statusCode = 500;
+
+        // Log the error
+        if (shouldLog)
+        {
+            const method = req.method || 'UNKNOWN';
+            const url = req.url || req.originalUrl || '/';
+            const prefix = `[${method} ${url}]`;
+
+            if (statusCode >= 500)
+            {
+                logFn(`${prefix} ${statusCode} - ${err.message}`);
+                if (err.stack) logFn(err.stack);
+            }
+            else
+            {
+                logFn(`${prefix} ${statusCode} - ${err.message}`);
+            }
+        }
+
+        // Callback hook
+        if (onError) onError(err, req, res);
+
+        // Don't send if headers already sent
+        if (res.headersSent || (res.raw && res.raw.headersSent))
+        {
+            return;
+        }
+
+        // Build response body
+        let body;
+
+        if (formatter)
+        {
+            body = formatter(err, req, isDev);
+        }
+        else if (isHttpError(err))
+        {
+            body = err.toJSON ? err.toJSON() : { error: err.message, code: err.code, statusCode };
+            if (isDev && err.stack) body.stack = err.stack.split('\n');
+        }
+        else
+        {
+            // Generic error
+            body = {
+                error: statusCode >= 500 && !isDev
+                    ? 'Internal Server Error'  // Hide internal details in production
+                    : (err.message || 'Internal Server Error'),
+                statusCode,
+            };
+            if (err.code) body.code = err.code;
+            if (isDev && err.stack) body.stack = err.stack.split('\n');
+        }
+
+        res.status(statusCode).json(body);
+    };
+}
+
+module.exports = errorHandler;

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]
+ * @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;