@zero-server/sdk 0.9.0

package/lib/middleware/compress.js

@@ -0,0 +1,230 @@
+/**
+ * @module compress
+ * @description Response compression middleware using Node's built-in `zlib`.
+ *              Supports gzip, deflate, and brotli (Node >= 11.7).
+ *              Zero external dependencies.
+ */
+const zlib = require('zlib');
+const log = require('../debug')('zero:compress');
+
+/**
+ * Default minimum response size (in bytes) to bother compressing.
+ * Responses smaller than this are sent uncompressed.
+ * @type {number}
+ */
+const DEFAULT_THRESHOLD = 1024;
+
+/**
+ * MIME types that are worth compressing.
+ * Binary formats (images, video, zip) are already compressed and gain little.
+ * @type {RegExp}
+ */
+const COMPRESSIBLE = /^text\/|^application\/(json|javascript|xml|x-www-form-urlencoded|ld\+json|graphql|wasm)|^image\/svg\+xml/;
+
+/**
+ * Create a compression middleware.
+ *
+ * @param {object}  [opts] - Configuration options.
+ * @param {number}  [opts.threshold=1024]  - Minimum body size in bytes to compress.
+ * @param {number}  [opts.level]           - Compression level (zlib.constants.Z_DEFAULT_COMPRESSION).
+ * @param {string|string[]} [opts.encoding] - Force specific encoding(s). Default: auto-negotiate.
+ * @param {Function} [opts.filter]         - `(req, res) => boolean` — return false to skip compression.
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   const { createApp, compress } = require('@zero-server/sdk');
+ *   const app = createApp();
+ *   app.use(compress());                // gzip/deflate/br auto-negotiated
+ *   app.use(compress({ threshold: 0 })) // compress everything
+ */
+function compress(opts = {})
+{
+    const threshold = opts.threshold !== undefined ? opts.threshold : DEFAULT_THRESHOLD;
+    const level = opts.level !== undefined ? opts.level : undefined;
+    const filterFn = typeof opts.filter === 'function' ? opts.filter : null;
+    const hasBrotli = typeof zlib.createBrotliCompress === 'function';
+
+    /**
+     * Choose the best encoding from the Accept-Encoding header.
+     * Parses quality values (RFC 7231) and picks the highest-priority match.
+     * Priority when equal quality: br > gzip > deflate.
+     * @private
+     * @param {string} header - HTTP header value.
+     * @returns {string|null} Best encoding name, or `null` if none acceptable.
+     */
+    function negotiate(header)
+    {
+        if (!header) return null;
+        const encodings = { br: 0, gzip: 0, deflate: 0 };
+        const parts = header.toLowerCase().split(',');
+        for (let i = 0; i < parts.length; i++)
+        {
+            const part = parts[i].trim();
+            const semi = part.indexOf(';');
+            const name = (semi !== -1 ? part.substring(0, semi).trim() : part);
+            let q = 1;
+            if (semi !== -1)
+            {
+                const qMatch = /q\s*=\s*([0-9.]+)/.exec(part.substring(semi));
+                if (qMatch) q = parseFloat(qMatch[1]);
+            }
+            if (name in encodings) encodings[name] = q;
+        }
+        // Filter available encodings
+        if (!hasBrotli) encodings.br = 0;
+        // Pick highest quality; break ties with priority order
+        let best = null;
+        let bestQ = 0;
+        const order = hasBrotli ? ['br', 'gzip', 'deflate'] : ['gzip', 'deflate'];
+        for (let i = 0; i < order.length; i++)
+        {
+            if (encodings[order[i]] > bestQ)
+            {
+                bestQ = encodings[order[i]];
+                best = order[i];
+            }
+        }
+        return best;
+    }
+
+    /**
+     * Create a compression stream for the chosen encoding.
+     * @private
+     * @param {string} encoding - Content encoding.
+     * @returns {import('stream').Transform} Compression transform stream.
+     */
+    function createStream(encoding)
+    {
+        const zlibOpts = {};
+        if (level !== undefined) zlibOpts.level = level;
+        switch (encoding)
+        {
+            case 'br':
+                return zlib.createBrotliCompress(level !== undefined
+                    ? { params: { [zlib.constants.BROTLI_PARAM_QUALITY]: level } }
+                    : undefined);
+            case 'gzip':
+                return zlib.createGzip(zlibOpts);
+            case 'deflate':
+                return zlib.createDeflate(zlibOpts);
+            default:
+                return null;
+        }
+    }
+
+    return (req, res, next) =>
+    {
+        // Skip if client doesn't accept encoding
+        const acceptEncoding = req.headers['accept-encoding'] || '';
+        const encoding = negotiate(acceptEncoding);
+        if (!encoding) return next();
+
+        // Allow user to skip compression
+        if (filterFn && !filterFn(req, res)) return next();
+
+        // Monkey-patch the raw response's write/end to pipe through compression
+        const raw = res.raw;
+        const origWrite = raw.write.bind(raw);
+        const origEnd = raw.end.bind(raw);
+        let compressStream = null;
+        let headersWritten = false;
+        const chunks = [];
+
+        /** @private */
+        function initCompress()
+        {
+            if (compressStream) return true;
+
+            // If headers were already committed (e.g. res.sse() calls
+            // writeHead before write), we can no longer modify them.
+            if (raw.headersSent) return false;
+
+            // Check Content-Type — skip non-compressible types
+            const ct = raw.getHeader('content-type') || '';
+            if (ct && !COMPRESSIBLE.test(ct))
+            {
+                return false;
+            }
+
+            // Never compress SSE streams — compression buffers
+            // the small frames and prevents real-time delivery.
+            if (ct.includes('text/event-stream'))
+            {
+                return false;
+            }
+
+            compressStream = createStream(encoding);
+            if (!compressStream) return false;
+
+            // Remove Content-Length (we don't know compressed size ahead of time)
+            raw.removeHeader('content-length');
+            raw.removeHeader('Content-Length');
+            raw.setHeader('Content-Encoding', encoding);
+            raw.setHeader('Vary', 'Accept-Encoding');
+            log.debug('compressing with %s', encoding);
+
+            compressStream.on('data', (chunk) => origWrite(chunk));
+            compressStream.on('end', () => origEnd());
+            compressStream.on('error', (err) =>
+            {                log.error('compression error: %s', err.message);                // On compression error, remove encoding header and end raw stream
+                try { raw.removeHeader('Content-Encoding'); } catch (e) { }
+                try { origEnd(); } catch (e) { }
+            });
+            return true;
+        }
+
+        raw.write = function (chunk, enc, callback)
+        {
+            if (!headersWritten)
+            {
+                headersWritten = true;
+                const ct = raw.getHeader('content-type') || '';
+                initCompress();
+                if (compressStream)
+                {
+                    compressStream.write(chunk, enc, callback);
+                    return true;
+                }
+            }
+            if (compressStream)
+            {
+                compressStream.write(chunk, enc, callback);
+                return true;
+            }
+            return origWrite(chunk, enc, callback);
+        };
+
+        raw.end = function (chunk, encoding, callback)
+        {
+            if (!headersWritten)
+            {
+                headersWritten = true;
+
+                // Check threshold — if the total body is small, skip compression
+                const totalChunk = chunk ? (Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))) : null;
+                if (totalChunk && totalChunk.length < threshold)
+                {
+                    return origEnd(chunk, encoding, callback);
+                }
+
+                if (initCompress())
+                {
+                    if (chunk) compressStream.end(chunk, encoding, callback);
+                    else compressStream.end(callback);
+                    return;
+                }
+            }
+            if (compressStream)
+            {
+                if (chunk) compressStream.end(chunk, encoding, callback);
+                else compressStream.end(callback);
+                return;
+            }
+            return origEnd(chunk, encoding, callback);
+        };
+
+        next();
+    };
+}
+
+module.exports = compress;

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} `true` if the signature is valid.
+ * @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] - Configuration options.
+ * @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

@@ -0,0 +1,93 @@
+/**
+ * @module cors
+ * @description CORS middleware.  Supports exact origins, wildcard `'*'`,
+ *              arrays of allowed origins, and suffix matching with a leading dot
+ *              (e.g. `'.example.com'` matches `sub.example.com`).
+ */
+
+/**
+ * Create a CORS middleware.
+ *
+ * @param {object}           [options] - Configuration options.
+ * @param {string|string[]}  [options.origin='*']          - Allowed origin(s).  Use `'*'` for any,
+ *                                                           an array for a whitelist, or a string
+ *                                                           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 {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`.
+ *
+ * @example
+ *   app.use(cors());                                  // allow all origins
+ *   app.use(cors({ origin: 'https://example.com' })); // single origin
+ *   app.use(cors({                                     // fine-grained
+ *       origin: ['https://my.example.com', '.example.com'],
+ *       credentials: true,
+ *       maxAge: 86400,
+ *   }));
+ */
+function cors(options = {})
+{
+    const allowOrigin = (options.hasOwnProperty('origin')) ? options.origin : '*';
+    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.
+     *
+     * @private
+     * @param {string|undefined} reqOrigin - The request's `Origin` header.
+     * @returns {string|null} Origin value to set, or `null`.
+     */
+    function matchOrigin(reqOrigin)
+    {
+        if (!allowOrigin) return null; // origin explicitly disabled
+        if (typeof allowOrigin === 'string') return allowOrigin === '*' ? '*' : allowOrigin;
+        if (Array.isArray(allowOrigin))
+        {
+            if (!reqOrigin) return null;
+            for (const o of allowOrigin)
+            {
+                if (!o) continue;
+                if (o === reqOrigin) return reqOrigin;
+                // allow suffix match with leading dot (e.g. .example.com)
+                if (o[0] === '.' && reqOrigin.endsWith(o)) return reqOrigin;
+            }
+            return null;
+        }
+        return null;
+    }
+
+    return (req, res, next) =>
+    {
+        const reqOrigin = req.headers && (req.headers.origin || req.headers.Origin);
+        const originValue = matchOrigin(reqOrigin);
+
+        if (originValue)
+        {
+            res.set('Access-Control-Allow-Origin', originValue);
+            // 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();
+    };
+}
+
+module.exports = cors;

package/lib/middleware/csrf.js

@@ -0,0 +1,137 @@
+/**
+ * @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-server/sdk');
+ *   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] - Configuration 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 || [];
+
+    /** @private */
+    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; }
+    }
+
+    /** @private */
+    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;