@zero-server/body 0.9.1 → 0.9.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Tony Wiedman
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Tony Wiedman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.js

@@ -1,11 +1,11 @@
 // AUTO-GENERATED by .tools/generate-package-stubs.js — edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
 'use strict';
-const sdk = require("@zero-server/sdk");
+const lib = require("./lib/body");
 
 module.exports = {
-    json: sdk.json,
-    urlencoded: sdk.urlencoded,
-    text: sdk.text,
-    raw: sdk.raw,
-    multipart: sdk.multipart,
+    json: lib.json,
+    urlencoded: lib.urlencoded,
+    text: lib.text,
+    raw: lib.raw,
+    multipart: lib.multipart,
 };

package/lib/body/index.js

@@ -0,0 +1,14 @@
+/**
+ * @module body
+ * @description Barrel export for all body-parsing utilities and middleware.
+ */
+const rawBuffer = require('./rawBuffer');
+const isTypeMatch = require('./typeMatch');
+const sendError = require('./sendError');
+const json = require('./json');
+const urlencoded = require('./urlencoded');
+const text = require('./text');
+const raw = require('./raw');
+const multipart = require('./multipart');
+
+module.exports = { rawBuffer, isTypeMatch, sendError, json, urlencoded, text, raw, multipart };

package/lib/body/json.js

@@ -0,0 +1,109 @@
+/**
+ * @module body/json
+ * @description JSON body-parsing middleware.
+ *              Reads the request body, parses it as JSON, and sets `req.body`.
+ *              Stores the raw buffer on `req.rawBody` for signature verification.
+ */
+const rawBuffer = require('./rawBuffer');
+const { charsetFromContentType } = require('./rawBuffer');
+const isTypeMatch = require('./typeMatch');
+const sendError = require('./sendError');
+
+/** @private Recursively remove __proto__, constructor, and prototype keys to prevent prototype pollution. */
+function _sanitize(obj)
+{
+    if (!obj || typeof obj !== 'object') return;
+    const keys = Object.keys(obj);
+    for (let i = 0; i < keys.length; i++)
+    {
+        const k = keys[i];
+        if (k === '__proto__' || k === 'constructor' || k === 'prototype')
+        {
+            delete obj[k];
+        }
+        else if (typeof obj[k] === 'object' && obj[k] !== null)
+        {
+            _sanitize(obj[k]);
+        }
+    }
+}
+
+/**
+ * Create a JSON body-parsing middleware.
+ *
+ * @param {object}          [options] - Configuration options.
+ * @param {string|number}   [options.limit]    - Max body size (e.g. `'10kb'`). Default `'1mb'`.
+ * @param {Function}        [options.reviver]  - `JSON.parse` reviver function.
+ * @param {boolean}         [options.strict=true] - When true, reject non-object/array roots.
+ * @param {string|string[]|Function} [options.type='application/json'] - Content-Type(s) to match.
+ * @param {boolean}         [options.requireSecure=false] - When true, reject non-HTTPS requests with 403.
+ * @param {Function}        [options.verify]   - `verify(req, res, buf, encoding)` — called before parsing. Throw to reject with 403.
+ * @param {boolean}         [options.inflate=true] - Decompress gzip/deflate/br bodies. When false, compressed bodies return 415.
+ * @returns {Function} Async middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   const { json } = require('@zero-server/sdk');
+ *
+ *   app.use(json({ limit: '500kb', strict: true }));
+ *
+ *   app.post('/api/data', (req, res) => {
+ *       console.log(req.body); // parsed JSON object
+ *       res.json({ ok: true });
+ *   });
+ */
+function json(options = {})
+{
+  const opts = options || {};
+  const limit = opts.limit !== undefined ? opts.limit : '1mb';
+  const reviver = opts.reviver;
+  const strict = (opts.hasOwnProperty('strict')) ? !!opts.strict : true;
+  const typeOpt = opts.type || 'application/json';
+  const requireSecure = !!opts.requireSecure;
+  const verify = opts.verify;
+  const inflate = opts.inflate !== undefined ? opts.inflate : true;
+
+  return async (req, res, next) =>
+  {
+    if (requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
+    const ct = (req.headers['content-type'] || '');
+    if (!isTypeMatch(ct, typeOpt)) return next();
+    try
+    {
+      const buf = await rawBuffer(req, { limit, inflate });
+      const encoding = charsetFromContentType(ct) || 'utf8';
+
+      // Store raw body for webhook signature verification (Stripe, GitHub, etc.)
+      req.rawBody = buf;
+
+      // Optional verification callback (e.g. HMAC signature check)
+      if (verify)
+      {
+        try { verify(req, res, buf, encoding); }
+        catch (e) { return sendError(res, 403, e.message || 'verification failed'); }
+      }
+
+      const txt = buf.toString(encoding);
+      if (!txt) { req.body = null; return next(); }
+      let parsed;
+      try { parsed = JSON.parse(txt, reviver); } catch (e) { return sendError(res, 400, 'invalid JSON'); }
+      if (strict && (typeof parsed !== 'object' || parsed === null))
+      {
+        return sendError(res, 400, 'invalid JSON: root must be object or array');
+      }
+      // Prevent prototype pollution
+      if (parsed && typeof parsed === 'object')
+      {
+        _sanitize(parsed);
+      }
+      req.body = parsed;
+    } catch (err)
+    {
+      if (err && err.status === 413) return sendError(res, 413, 'payload too large');
+      if (err && err.status === 415) return sendError(res, 415, err.message || 'unsupported encoding');
+      req.body = null;
+    }
+    next();
+  };
+}
+
+module.exports = json;

package/lib/body/multipart.js

@@ -0,0 +1,440 @@
+/**
+ * @module body/multipart
+ * @description Streaming multipart/form-data parser.
+ *              Writes uploaded files to a temp directory and collects
+ *              form fields.  Sets `req.body = { fields, files }`.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const sendError = require('./sendError');
+
+/**
+ * Generate a unique filename with an optional prefix.
+ *
+ * @private
+ * @param {string} [prefix='miniex'] - Filename prefix.
+ * @returns {string} Formatted string.
+ */
+function uniqueName(prefix = 'miniex')
+{
+    return `${prefix}-${Date.now()}-${Math.floor(Math.random() * 1e9)}`;
+}
+
+/**
+ * Recursively create a directory if it doesn't exist.
+ *
+ * @private
+ * @param {string} dir - Directory path.
+ */
+function ensureDir(dir)
+{
+    try { fs.mkdirSync(dir, { recursive: true }); } catch (e) { }
+}
+
+/**
+ * Parse raw MIME header text (CRLF-separated) into a plain object.
+ *
+ * @private
+ * @param {string} headerText - Raw header block.
+ * @returns {Object<string, string>} Lower-cased header key/value map.
+ */
+function parseHeaders(headerText)
+{
+    const lines = headerText.split('\r\n');
+    const obj = {};
+    for (const l of lines)
+    {
+        const idx = l.indexOf(':');
+        if (idx === -1) continue;
+        const k = l.slice(0, idx).trim().toLowerCase();
+        const v = l.slice(idx + 1).trim();
+        obj[k] = v;
+    }
+    return obj;
+}
+
+/**
+ * Sanitize a filename by stripping path traversal characters and
+ * null bytes. Keeps only the basename.
+ *
+ * @private
+ * @param {string} filename - Raw filename from the upload.
+ * @returns {string} Sanitized filename.
+ */
+function sanitizeFilename(filename)
+{
+    if (!filename) return '';
+    // Strip null bytes
+    let safe = filename.replace(/\0/g, '');
+    // Take only the basename (strip directory traversal)
+    safe = safe.replace(/^.*[/\\]/, '');
+    // Remove leading dots (prevent dotfile creation)
+    safe = safe.replace(/^\.+/, '');
+    // Replace potentially dangerous characters
+    safe = safe.replace(/[<>:"|?*]/g, '_');
+    return safe || 'unnamed';
+}
+
+/**
+ * Extract `name` and `filename` fields from a `Content-Disposition` header.
+ *
+ * @private
+ * @param {string} cd - Content-Disposition value.
+ * @returns {Object<string, string>} Parsed disposition parameters.
+ */
+function parseContentDisposition(cd)
+{
+    const m = /form-data;(.*)/i.exec(cd);
+    if (!m) return {};
+    const parts = m[1].split(';').map(s => s.trim());
+    const out = {};
+    for (const p of parts)
+    {
+        const mm = /([^=]+)="?([^"]+)"?/.exec(p);
+        if (mm)
+        {
+            const key = mm[1].trim();
+            let val = mm[2];
+            // Sanitize filename values
+            if (key === 'filename') val = sanitizeFilename(val);
+            out[key] = val;
+        }
+    }
+    return out;
+}
+
+/**
+ * Create a streaming multipart/form-data parsing middleware.
+ *
+ * @param {object}   [opts] - Configuration options.
+ * @param {string}   [opts.dir]              - Upload directory (default: OS temp dir).
+ * @param {number}   [opts.maxFileSize]      - Maximum size per file in bytes.
+ * @param {boolean}  [opts.requireSecure=false] - When true, reject non-HTTPS requests with 403.
+ * @param {number}   [opts.maxFields=1000]   - Maximum number of non-file fields. Prevents DoS via field flooding.
+ * @param {number}   [opts.maxFiles=10]      - Maximum number of uploaded files.
+ * @param {number}   [opts.maxFieldSize]     - Maximum size of a single field value in bytes. Default 1 MB.
+ * @param {string[]} [opts.allowedMimeTypes] - Whitelist of MIME types for uploaded files (e.g. `['image/png', 'image/jpeg']`).
+ * @param {number}   [opts.maxTotalSize]     - Maximum combined size of all uploaded files in bytes.
+ * @returns {Function} Async middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   const { multipart } = require('@zero-server/sdk');
+ *
+ *   app.use(multipart({
+ *       dir: './uploads',
+ *       maxFileSize: 10 * 1024 * 1024, // 10 MB
+ *       maxFiles: 5,
+ *       allowedMimeTypes: ['image/png', 'image/jpeg'],
+ *   }));
+ *
+ *   app.post('/upload', (req, res) => {
+ *       const { fields, files } = req.body;
+ *       res.json({ fields, uploaded: Object.keys(files) });
+ *   });
+ */
+function multipart(opts = {})
+{
+    return async (req, res, next) =>
+    {
+        if (opts.requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
+        const ct = req.headers['content-type'] || '';
+        const m = /boundary=(?:"([^"]+)"|([^;\s]+))/i.exec(ct);
+        if (!m) return next();
+        const boundary = (m[1] || m[2] || '').replace(/^"|"$/g, '');
+        const dashBoundary = `--${boundary}`;
+        const dashBoundaryBuf = Buffer.from('\r\n' + dashBoundary);
+        const startBoundaryBuf = Buffer.from(dashBoundary);
+
+        let tmpDir;
+        if (opts.dir)
+        {
+            tmpDir = path.isAbsolute(opts.dir) ? opts.dir : path.join(process.cwd(), opts.dir);
+        } else
+        {
+            tmpDir = path.join(os.tmpdir(), 'zero-server-uploads');
+        }
+        const maxFileSize = opts.maxFileSize || null; // bytes
+        const maxFields = opts.maxFields !== undefined ? opts.maxFields : 1000;
+        const maxFiles = opts.maxFiles !== undefined ? opts.maxFiles : 10;
+        const maxFieldSize = opts.maxFieldSize !== undefined ? opts.maxFieldSize : (1024 * 1024); // 1 MB
+        const allowedMimeTypes = opts.allowedMimeTypes || null;
+        const maxTotalSize = opts.maxTotalSize || null;
+        ensureDir(tmpDir);
+
+        const fields = {};
+        const files = {};
+        let fieldCount = 0;
+        let fileCount = 0;
+        let totalFileSize = 0;
+
+        let buffer = Buffer.alloc(0);
+        let state = 'start'; // start, headers, body
+        let current = null; // { headers, name, filename, contentType, writeStream, collectedSize }
+
+        const pendingWrites = [];
+
+        function abortFileTooLarge()
+        {
+            if (current.writeStream) { current.writeStream.on('error', () => {}); try { current.writeStream.destroy(); } catch (e) { } }
+            try { fs.unlinkSync(current.filePath); } catch (e) { }
+            if (!req._multipartErrorHandled)
+            {
+                req._multipartErrorHandled = true;
+                sendError(res, 413, 'file too large');
+                req.raw.pause && req.raw.pause();
+            }
+        }
+
+        function closeCurrent()
+        {
+            if (!current) return;
+            if (current.writeStream)
+            {
+                // end the stream and record file after it's flushed to disk
+                // capture values so we don't rely on `current` later
+                const info = { name: current.name, filename: current.filename, filePath: current.filePath, contentType: current.contentType, size: current.collectedSize };
+                const p = new Promise((resolve) =>
+                {
+                    current.writeStream.on('finish', () =>
+                    {
+                        files[info.name] = { originalFilename: info.filename, storedName: path.basename(info.filePath), path: info.filePath, contentType: info.contentType, size: info.size };
+                        resolve();
+                    });
+                    current.writeStream.on('error', () =>
+                    {
+                        resolve();
+                    });
+                });
+                pendingWrites.push(p);
+                current.writeStream.end();
+            } else
+            {
+                fields[current.name] = current.value || '';
+            }
+            current = null;
+        }
+
+        req.raw.on('data', (chunk) =>
+        {
+            buffer = Buffer.concat([buffer, chunk]);
+
+            while (true)
+            {
+                if (state === 'start')
+                {
+                    // look for starting boundary
+                    const idx = buffer.indexOf(startBoundaryBuf);
+                    if (idx === -1)
+                    {
+                        // boundary not yet found
+                        if (buffer.length > startBoundaryBuf.length) buffer = buffer.slice(buffer.length - startBoundaryBuf.length);
+                        break;
+                    }
+                    // consume up to after boundary and CRLF
+                    const after = idx + startBoundaryBuf.length;
+                    if (buffer.length < after + 2) break; // wait for CRLF
+                    buffer = buffer.slice(after);
+                    if (buffer.slice(0, 2).toString() === '\r\n') buffer = buffer.slice(2);
+                    state = 'headers';
+                } else if (state === 'headers')
+                {
+                    const idx = buffer.indexOf('\r\n\r\n');
+                    if (idx === -1)
+                    {
+                        // wait for more
+                        if (buffer.length > 1024 * 1024)
+                        {
+                            // keep buffer bounded
+                            buffer = buffer.slice(buffer.length - 1024 * 16);
+                        }
+                        break;
+                    }
+                    const headerText = buffer.slice(0, idx).toString('utf8');
+                    buffer = buffer.slice(idx + 4);
+                    const hdrs = parseHeaders(headerText);
+                    const disp = hdrs['content-disposition'] || '';
+                    const cd = parseContentDisposition(disp);
+                    const name = cd.name;
+                    const filename = cd.filename;
+                    const contentType = hdrs['content-type'] || null;
+                    current = { headers: hdrs, name, filename, contentType, collectedSize: 0 };
+                    if (filename)
+                    {
+                        // Enforce file count limit
+                        fileCount++;
+                        if (maxFiles && fileCount > maxFiles)
+                        {
+                            if (!req._multipartErrorHandled)
+                            {
+                                req._multipartErrorHandled = true;
+                                sendError(res, 413, 'too many files');
+                                req.raw.pause && req.raw.pause();
+                            }
+                            return;
+                        }
+                        // Enforce MIME type whitelist
+                        if (allowedMimeTypes && contentType && !allowedMimeTypes.includes(contentType))
+                        {
+                            if (!req._multipartErrorHandled)
+                            {
+                                req._multipartErrorHandled = true;
+                                sendError(res, 415, 'file type not allowed: ' + contentType);
+                                req.raw.pause && req.raw.pause();
+                            }
+                            return;
+                        }
+                        // create temp file; preserve the original extension when possible
+                        const ext = path.extname(filename) || '';
+                        const safeExt = ext.replace(/[^a-z0-9.]/gi, '');
+                        let fname = uniqueName('upload');
+                        if (safeExt) fname = fname + (safeExt.startsWith('.') ? safeExt : ('.' + safeExt));
+                        const filePath = path.join(tmpDir, fname);
+                        current.filePath = filePath;
+                        current.writeStream = fs.createWriteStream(filePath);
+                    } else
+                    {
+                        // Enforce field count limit
+                        fieldCount++;
+                        if (maxFields && fieldCount > maxFields)
+                        {
+                            if (!req._multipartErrorHandled)
+                            {
+                                req._multipartErrorHandled = true;
+                                sendError(res, 413, 'too many fields');
+                                req.raw.pause && req.raw.pause();
+                            }
+                            return;
+                        }
+                        current.value = '';
+                    }
+                    state = 'body';
+                } else if (state === 'body')
+                {
+                    // look for boundary preceded by CRLF
+                    const idx = buffer.indexOf(dashBoundaryBuf);
+                    if (idx === -1)
+                    {
+                        // keep tail in buffer to match partial boundary
+                        const keep = Math.max(dashBoundaryBuf.length, 1024);
+                        const writeLen = buffer.length - keep;
+                        if (writeLen > 0)
+                        {
+                            const toWrite = buffer.slice(0, writeLen);
+                            if (current.writeStream)
+                            {
+                                current.collectedSize += toWrite.length;
+                                totalFileSize += toWrite.length;
+                                if (maxFileSize && current.collectedSize > maxFileSize)
+                                {
+                                    abortFileTooLarge();
+                                    return;
+                                }
+                                if (maxTotalSize && totalFileSize > maxTotalSize)
+                                {
+                                    abortFileTooLarge();
+                                    return;
+                                }
+                                current.writeStream.write(toWrite);
+                            } else
+                            {
+                                if (maxFieldSize && current.value.length + toWrite.length > maxFieldSize)
+                                {
+                                    if (!req._multipartErrorHandled)
+                                    {
+                                        req._multipartErrorHandled = true;
+                                        sendError(res, 413, 'field value too large');
+                                        req.raw.pause && req.raw.pause();
+                                    }
+                                    return;
+                                }
+                                current.value += toWrite.toString('utf8');
+                            }
+                            buffer = buffer.slice(writeLen);
+                        }
+                        break;
+                    }
+                    // boundary found at idx; data before idx is body chunk (without the leading CRLF)
+                    const bodyChunk = buffer.slice(0, idx);
+                    // if bodyChunk starts with CRLF, strip it
+                    const toWrite = (bodyChunk.slice(0, 2).toString() === '\r\n') ? bodyChunk.slice(2) : bodyChunk;
+                    if (toWrite.length)
+                    {
+                        if (current.writeStream)
+                        {
+                            current.collectedSize += toWrite.length;
+                            totalFileSize += toWrite.length;
+                            if (maxFileSize && current.collectedSize > maxFileSize)
+                            {
+                                abortFileTooLarge();
+                                return;
+                            }
+                            if (maxTotalSize && totalFileSize > maxTotalSize)
+                            {
+                                abortFileTooLarge();
+                                return;
+                            }
+                            current.writeStream.write(toWrite);
+                        } else
+                        {
+                            if (maxFieldSize && current.value.length + toWrite.length > maxFieldSize)
+                            {
+                                if (!req._multipartErrorHandled)
+                                {
+                                    req._multipartErrorHandled = true;
+                                    sendError(res, 413, 'field value too large');
+                                    req.raw.pause && req.raw.pause();
+                                }
+                                return;
+                            }
+                            current.value += toWrite.toString('utf8');
+                        }
+                    }
+                    // consume boundary marker
+                    buffer = buffer.slice(idx + dashBoundaryBuf.length);
+                    // check for final boundary '--'
+                    if (buffer.slice(0, 2).toString() === '--')
+                    {
+                        // final
+                        closeCurrent();
+                        // wait for any pending file flushes then continue
+                        req.raw.pause && req.raw.pause();
+                        Promise.all(pendingWrites).then(() =>
+                        {
+                            req.body = { fields, files };
+                            req._multipart = true;
+                            return next();
+                        }).catch(() =>
+                        {
+                            req.body = { fields, files };
+                            req._multipart = true;
+                            return next();
+                        });
+                        return;
+                    }
+                    // trim leading CRLF if present
+                    if (buffer.slice(0, 2).toString() === '\r\n') buffer = buffer.slice(2);
+                    // close current and continue to next headers
+                    closeCurrent();
+                    state = 'headers';
+                }
+            }
+        });
+
+        req.raw.on('end', () =>
+        {
+            // finish any current
+            if (current) closeCurrent();
+            req.body = { fields, files };
+            req._multipart = true;
+            next();
+        });
+
+        req.raw.on('error', (err) =>
+        {
+            next();
+        });
+    };
+}
+
+module.exports = multipart;

package/lib/body/raw.js

@@ -0,0 +1,71 @@
+/**
+ * @module body/raw
+ * @description Raw-buffer body-parsing middleware.
+ *              Stores the full request body as a Buffer on `req.body`.
+ *              Also sets `req.rawBody` for signature verification workflows.
+ */
+const rawBuffer = require('./rawBuffer');
+const isTypeMatch = require('./typeMatch');
+const sendError = require('./sendError');
+
+/**
+ * Create a raw-buffer body-parsing middleware.
+ *
+ * @param {object}          [options] - Configuration options.
+ * @param {string|number}   [options.limit]                           - Max body size. Default `'1mb'`.
+ * @param {string|string[]|Function} [options.type='application/octet-stream'] - Content-Type(s) to match.
+ * @param {boolean}         [options.requireSecure=false]             - When true, reject non-HTTPS requests with 403.
+ * @param {Function}        [options.verify]   - `verify(req, res, buf)` — called before setting body. Throw to reject with 403.
+ * @param {boolean}         [options.inflate=true] - Decompress gzip/deflate/br bodies. When false, compressed bodies return 415.
+ * @returns {Function} Async middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   const { raw } = require('@zero-server/sdk');
+ *
+ *   app.use(raw({ type: 'application/octet-stream', limit: '5mb' }));
+ *
+ *   app.post('/upload', (req, res) => {
+ *       console.log(req.body); // Buffer
+ *       res.send('received ' + req.body.length + ' bytes');
+ *   });
+ */
+function raw(options = {})
+{
+    const opts = options || {};
+    const limit = opts.limit !== undefined ? opts.limit : '1mb';
+    const typeOpt = opts.type || 'application/octet-stream';
+    const requireSecure = !!opts.requireSecure;
+    const verify = opts.verify;
+    const inflate = opts.inflate !== undefined ? opts.inflate : true;
+
+    return async (req, res, next) =>
+    {
+        if (requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
+        const ct = (req.headers['content-type'] || '');
+        if (!isTypeMatch(ct, typeOpt)) return next();
+        try
+        {
+            const buf = await rawBuffer(req, { limit, inflate });
+
+            // Store raw body for signature verification
+            req.rawBody = buf;
+
+            // Optional verification callback
+            if (verify)
+            {
+                try { verify(req, res, buf); }
+                catch (e) { return sendError(res, 403, e.message || 'verification failed'); }
+            }
+
+            req.body = buf;
+        } catch (err)
+        {
+            if (err && err.status === 413) return sendError(res, 413, 'payload too large');
+            if (err && err.status === 415) return sendError(res, 415, err.message || 'unsupported encoding');
+            req.body = Buffer.alloc(0);
+        }
+        next();
+    };
+}
+
+module.exports = raw;

package/lib/body/rawBuffer.js

@@ -0,0 +1,161 @@
+/**
+ * @module body/rawBuffer
+ * @description Low-level helper that collects the raw request body into a
+ *              single Buffer, enforcing an optional byte-size limit.
+ *              Supports Content-Encoding decompression (gzip, deflate, br)
+ *              and Content-Length pre-checking for early rejection.
+ */
+const zlib = require('zlib');
+
+/**
+ * Parse a human-readable size string (e.g. `'10kb'`, `'2mb'`) into bytes.
+ *
+ * @private
+ * @param {string|number|null} limit - Size limit value.
+ * @returns {number|null} Byte limit, or `null` for unlimited.
+ */
+function parseLimit(limit)
+{
+    if (!limit && limit !== 0) return null;
+    if (typeof limit === 'number') return limit;
+    if (typeof limit === 'string')
+    {
+        const v = limit.trim().toLowerCase();
+        const num = Number(v.replace(/[^0-9.]/g, ''));
+        if (v.endsWith('kb')) return Math.floor(num * 1024);
+        if (v.endsWith('mb')) return Math.floor(num * 1024 * 1024);
+        if (v.endsWith('gb')) return Math.floor(num * 1024 * 1024 * 1024);
+        return Math.floor(num);
+    }
+    return null;
+}
+
+/**
+ * Extract and normalise the charset from a Content-Type header value
+ * into a Node.js-compatible `BufferEncoding` name.
+ *
+ * @param {string} contentType - Full Content-Type header value.
+ * @returns {string|null} Normalised encoding or `null` when not specified.
+ */
+function charsetFromContentType(contentType)
+{
+    if (!contentType) return null;
+    const m = contentType.match(/charset=["']?([^\s;"']+)/i);
+    if (!m) return null;
+    const raw = m[1].toLowerCase().replace(/[^a-z0-9]/g, '');
+    if (raw === 'utf8') return 'utf8';
+    if (raw === 'utf16le' || raw === 'utf16' || raw === 'ucs2') return 'utf16le';
+    if (raw === 'latin1' || raw === 'iso88591') return 'latin1';
+    if (raw === 'ascii' || raw === 'usascii') return 'ascii';
+    return 'utf8'; // safe fallback for unknown charsets
+}
+
+/**
+ * Collect the raw request body into a Buffer.
+ *
+ * - Rejects with `{ status: 413 }` when `opts.limit` is exceeded.
+ * - Rejects with `{ status: 415 }` for unsupported Content-Encoding or
+ *   when `opts.inflate` is `false` and the body is compressed.
+ * - Automatically decompresses gzip / deflate / br when `opts.inflate`
+ *   is `true` (the default).
+ *
+ * @param {import('../http/request')} req        - Wrapped request (`.raw` stream, `.headers`).
+ * @param {object}                    [opts] - Configuration options.
+ * @param {string|number|null}        [opts.limit]         - Max body size (post-decompression).
+ * @param {boolean}                   [opts.inflate=true]  - Decompress gzip/deflate/br bodies.
+ * @returns {Promise<Buffer>} Resolved with the full body buffer.
+ */
+function rawBuffer(req, opts = {})
+{
+    const limit = parseLimit(opts.limit);
+    const inflate = opts.inflate !== false;
+
+    return new Promise((resolve, reject) =>
+    {
+        const headers = req.headers || (req.raw && req.raw.headers) || {};
+
+        // Content-Encoding handling
+        const encoding = (headers['content-encoding'] || '').toLowerCase().trim();
+        const isCompressed = encoding && encoding !== 'identity';
+
+        // Content-Length pre-check (skip for compressed bodies — CL is the compressed size)
+        if (!isCompressed)
+        {
+            const cl = parseInt(headers['content-length'], 10);
+            if (limit && cl && cl > limit)
+            {
+                const err = new Error('payload too large');
+                err.status = 413;
+                return reject(err);
+            }
+        }
+
+        // Select stream source (possibly a decompression transform)
+        let stream = req.raw;
+        if (isCompressed)
+        {
+            if (!inflate)
+            {
+                const err = new Error('compressed bodies not accepted');
+                err.status = 415;
+                return reject(err);
+            }
+            if (encoding === 'gzip' || encoding === 'x-gzip')
+            {
+                stream = req.raw.pipe(zlib.createGunzip());
+            }
+            else if (encoding === 'deflate')
+            {
+                stream = req.raw.pipe(zlib.createInflate());
+            }
+            else if (encoding === 'br')
+            {
+                stream = req.raw.pipe(zlib.createBrotliDecompress());
+            }
+            else
+            {
+                const err = new Error('unsupported Content-Encoding: ' + encoding);
+                err.status = 415;
+                return reject(err);
+            }
+        }
+
+        const chunks = [];
+        let total = 0;
+
+        function cleanup()
+        {
+            stream.removeListener('data', onData);
+            stream.removeListener('end', onEnd);
+            stream.removeListener('error', onError);
+        }
+        function onData(c)
+        {
+            total += c.length;
+            if (limit && total > limit)
+            {
+                cleanup();
+                const err = new Error('payload too large');
+                err.status = 413;
+                return reject(err);
+            }
+            chunks.push(c);
+        }
+        function onEnd()
+        {
+            cleanup();
+            resolve(Buffer.concat(chunks));
+        }
+        function onError(e)
+        {
+            cleanup();
+            reject(e);
+        }
+        stream.on('data', onData);
+        stream.on('end', onEnd);
+        stream.on('error', onError);
+    });
+}
+
+module.exports = rawBuffer;
+module.exports.charsetFromContentType = charsetFromContentType;

package/lib/body/sendError.js

@@ -0,0 +1,25 @@
+/**
+ * @module body/sendError
+ * @private
+ * @description Shared helper for sending HTTP error responses from body parsers.
+ *              Centralizes the pattern used across all parsers so changes only happen in one place.
+ */
+
+/**
+ * Send an HTTP error response.
+ *
+ * @private
+ * @param {object} res    - The response wrapper (or raw response).
+ * @param {number} status - HTTP status code.
+ * @param {string} message - Error message string for the JSON body.
+ */
+function sendError(res, status, message)
+{
+    const raw = res.raw || res;
+    if (raw.headersSent) return;
+    raw.statusCode = status;
+    raw.setHeader('Content-Type', 'application/json');
+    raw.end(JSON.stringify({ error: message }));
+}
+
+module.exports = sendError;

package/lib/body/text.js

@@ -0,0 +1,75 @@
+/**
+ * @module body/text
+ * @description Plain-text body-parsing middleware.
+ *              Reads the request body as a string and sets `req.body`.
+ *              Stores the raw buffer on `req.rawBody` for signature verification.
+ */
+const rawBuffer = require('./rawBuffer');
+const { charsetFromContentType } = require('./rawBuffer');
+const isTypeMatch = require('./typeMatch');
+const sendError = require('./sendError');
+
+/**
+ * Create a plain-text body-parsing middleware.
+ *
+ * @param {object}          [options] - Configuration options.
+ * @param {string|number}   [options.limit]              - Max body size. Default `'1mb'`.
+ * @param {string}          [options.encoding='utf8']    - Fallback character encoding when Content-Type has no charset.
+ * @param {string|string[]|Function} [options.type='text/*'] - Content-Type(s) to match.
+ * @param {boolean}         [options.requireSecure=false] - When true, reject non-HTTPS requests with 403.
+ * @param {Function}        [options.verify]   - `verify(req, res, buf, encoding)` — called before decoding. Throw to reject with 403.
+ * @param {boolean}         [options.inflate=true] - Decompress gzip/deflate/br bodies. When false, compressed bodies return 415.
+ * @returns {Function} Async middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   const { text } = require('@zero-server/sdk');
+ *
+ *   app.use(text({ type: 'text/plain', limit: '256kb' }));
+ *
+ *   app.post('/log', (req, res) => {
+ *       console.log(req.body); // raw string
+ *       res.send('ok');
+ *   });
+ */
+function text(options = {})
+{
+  const opts = options || {};
+  const limit = opts.limit !== undefined ? opts.limit : '1mb';
+  const defaultEncoding = opts.encoding || 'utf8';
+  const typeOpt = opts.type || 'text/*';
+  const requireSecure = !!opts.requireSecure;
+  const verify = opts.verify;
+  const inflate = opts.inflate !== undefined ? opts.inflate : true;
+
+  return async (req, res, next) =>
+  {
+    if (requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
+    const ct = (req.headers['content-type'] || '');
+    if (!isTypeMatch(ct, typeOpt)) return next();
+    try
+    {
+      const buf = await rawBuffer(req, { limit, inflate });
+      const encoding = charsetFromContentType(ct) || defaultEncoding;
+
+      // Store raw body for signature verification
+      req.rawBody = buf;
+
+      // Optional verification callback
+      if (verify)
+      {
+        try { verify(req, res, buf, encoding); }
+        catch (e) { return sendError(res, 403, e.message || 'verification failed'); }
+      }
+
+      req.body = buf.toString(encoding);
+    } catch (err)
+    {
+      if (err && err.status === 413) return sendError(res, 413, 'payload too large');
+      if (err && err.status === 415) return sendError(res, 415, err.message || 'unsupported encoding');
+      req.body = '';
+    }
+    next();
+  };
+}
+
+module.exports = text;

package/lib/body/typeMatch.js

@@ -0,0 +1,42 @@
+/**
+ * @module body/typeMatch
+ * @private
+ * @description Shared Content-Type matching utility for body parsers.
+ */
+
+/**
+ * Check whether a Content-Type header matches the configured type filter.
+ *
+ * @private
+ * @param {string}                        contentType  - The request Content-Type header value.
+ * @param {string|string[]|function}      typeOpt      - MIME pattern to match against (e.g. 'application/json', 'text/*', '*\/*'),
+ *                                                       an array of patterns, or a custom predicate `(ct) => boolean`.
+ * @returns {boolean} Boolean result.
+ */
+function isTypeMatch(contentType, typeOpt)
+{
+    if (!typeOpt) return true;
+    if (typeof typeOpt === 'function') return !!typeOpt(contentType);
+    if (Array.isArray(typeOpt)) return typeOpt.some(t => isTypeMatch(contentType, t));
+    if (!contentType) return false;
+    if (typeOpt === '*/*') return true;
+    // Strip charset/parameters from content-type for proper matching
+    const semiIdx = contentType.indexOf(';');
+    const baseType = semiIdx !== -1 ? contentType.substring(0, semiIdx).trim() : contentType;
+    if (typeOpt.endsWith('/*'))
+    {
+        return baseType.startsWith(typeOpt.slice(0, -1));
+    }
+    // Suffix pattern: application/*+json matches application/vnd.api+json
+    const starIdx = typeOpt.indexOf('/*+');
+    if (starIdx !== -1)
+    {
+        const prefix = typeOpt.slice(0, starIdx + 1); // 'application/'
+        const suffix = typeOpt.slice(starIdx + 2);     // '+json'
+        return baseType.startsWith(prefix) && baseType.endsWith(suffix);
+    }
+    // Exact or substring match against the base type only
+    return baseType.indexOf(typeOpt) !== -1;
+}
+
+module.exports = isTypeMatch;

package/lib/body/urlencoded.js

@@ -0,0 +1,235 @@
+/**
+ * @module body/urlencoded
+ * @description URL-encoded body-parsing middleware.
+ *              Supports both flat (`URLSearchParams`) and extended
+ *              (nested bracket syntax) parsing modes.
+ *              Stores the raw buffer on `req.rawBody` for signature verification.
+ */
+const rawBuffer = require('./rawBuffer');
+const isTypeMatch = require('./typeMatch');
+const sendError = require('./sendError');
+
+/**
+ * Append a value to an existing key, converting to an array when needed.
+ *
+ * @private
+ * @param {*}      prev - Previous value for the key (or `undefined`).
+ * @param {string} val  - New value to append.
+ * @returns {string|string[]} Merged value.
+ */
+function appendValue(prev, val)
+{
+    if (prev === undefined) return val;
+    if (Array.isArray(prev)) { prev.push(val); return prev; }
+    // convert existing scalar or object into array to hold multiple values
+    return [prev, val];
+}
+
+/**
+ * Create a URL-encoded body-parsing middleware.
+ *
+ * @param {object}          [options] - Configuration options.
+ * @param {string|number}   [options.limit]     - Max body size (e.g. `'10kb'`). Default `'1mb'`.
+ * @param {string|string[]|Function} [options.type='application/x-www-form-urlencoded'] - Content-Type(s) to match.
+ * @param {boolean}         [options.extended=false] - Use nested bracket parsing (e.g. `a[b][c]=1`).
+ * @param {boolean}         [options.requireSecure=false] - When true, reject non-HTTPS requests with 403.
+ * @param {number}          [options.parameterLimit=1000] - Max number of parameters. Prevents DoS via huge payloads.
+ * @param {number}          [options.depth=32]  - Max nesting depth for bracket syntax. Prevents deep-nesting DoS.
+ * @param {Function}        [options.verify]    - `verify(req, res, buf, encoding)` — called before parsing. Throw to reject with 403.
+ * @param {boolean}         [options.inflate=true] - Decompress gzip/deflate/br bodies.
+ * @returns {Function} Async middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   const { urlencoded } = require('@zero-server/sdk');
+ *
+ *   // Flat parsing (default)
+ *   app.use(urlencoded({ limit: '100kb' }));
+ *
+ *   // Nested bracket syntax
+ *   app.use(urlencoded({ extended: true }));
+ *
+ *   app.post('/form', (req, res) => {
+ *       console.log(req.body); // { name: 'Tony', age: '30' }
+ *       res.json(req.body);
+ *   });
+ */
+function urlencoded(options = {})
+{
+    const opts = options || {};
+    const limit = opts.limit !== undefined ? opts.limit : '1mb';
+    const typeOpt = opts.type || 'application/x-www-form-urlencoded';
+    const extended = !!opts.extended;
+    const requireSecure = !!opts.requireSecure;
+    const parameterLimit = opts.parameterLimit !== undefined ? opts.parameterLimit : 1000;
+    const maxDepth = opts.depth !== undefined ? opts.depth : 32;
+    const verify = opts.verify;
+    const inflate = opts.inflate !== undefined ? opts.inflate : true;
+
+    return async (req, res, next) =>
+    {
+        if (requireSecure && !req.secure) return sendError(res, 403, 'HTTPS required');
+        const ct = (req.headers['content-type'] || '');
+        if (!isTypeMatch(ct, typeOpt)) return next();
+        try
+        {
+            const buf = await rawBuffer(req, { limit, inflate });
+
+            // Store raw body for signature verification
+            req.rawBody = buf;
+
+            // Optional verification callback
+            if (verify)
+            {
+                try { verify(req, res, buf, 'utf8'); }
+                catch (e) { return sendError(res, 403, e.message || 'verification failed'); }
+            }
+
+            const txt = buf.toString('utf8');
+            if (!extended)
+            {
+                const params = new URLSearchParams(txt);
+                // Enforce parameter limit
+                if (parameterLimit)
+                {
+                    let count = 0;
+                    for (const _ of params) { if (++count > parameterLimit) return sendError(res, 413, 'too many parameters'); }
+                }
+                req.body = Object.fromEntries(params);
+            }
+            else
+            {
+                // extended parsing: support nested bracket syntax like a[b][c]=1 and arrays a[]=1
+                const out = {};
+                if (txt.trim() === '') { req.body = out; return next(); }
+                const pairs = txt.split('&');
+                // Enforce parameter limit
+                if (parameterLimit && pairs.length > parameterLimit)
+                {
+                    return sendError(res, 413, 'too many parameters');
+                }
+                for (const p of pairs)
+                {
+                    if (!p) continue;
+                    const eq = p.indexOf('=');
+                    let k, v;
+                    if (eq === -1) { k = decodeURIComponent(p.replace(/\+/g, ' ')); v = ''; }
+                    else { k = decodeURIComponent(p.slice(0, eq).replace(/\+/g, ' ')); v = decodeURIComponent(p.slice(eq + 1).replace(/\+/g, ' ')); }
+                    // parse key into parts
+                    const parts = [];
+                    const re = /([^\[\]]+)|\[(.*?)\]/g;
+                    let m;
+                    while ((m = re.exec(k)) !== null)
+                    {
+                        const part = m[1] || m[2];
+                        // Prevent prototype pollution
+                        if (part === '__proto__' || part === 'constructor' || part === 'prototype') continue;
+                        parts.push(part);
+                    }
+
+                    // Enforce depth limit
+                    if (maxDepth && parts.length > maxDepth)
+                    {
+                        return sendError(res, 400, 'nesting depth exceeded');
+                    }
+
+                    // set value into out following parts
+                    // _parent/_parentKey track the container holding `cur` so we can
+                    // convert it from object → array when the `[]` push syntax is used.
+                    let cur = out;
+                    let _parent = null;
+                    let _parentKey = null;
+                    for (let i = 0; i < parts.length; i++)
+                    {
+                        const part = parts[i];
+                        const isLast = (i === parts.length - 1);
+
+                        if (part === '')
+                        {
+                            // Empty-bracket array-push syntax: a[]=val  /  a[][key]=val
+                            if (isLast)
+                            {
+                                // Ensure cur is an array before pushing, converting parent ref if needed
+                                if (!Array.isArray(cur))
+                                {
+                                    const arr = [];
+                                    if (_parent !== null) _parent[_parentKey] = arr;
+                                    cur = arr;
+                                }
+                                cur.push(v);
+                                break;
+                            }
+                            // Intermediate empty bracket — navigate into next element of the array
+                            if (!Array.isArray(cur))
+                            {
+                                const arr = [];
+                                if (_parent !== null) _parent[_parentKey] = arr;
+                                cur = arr;
+                            }
+                            if (cur.length === 0 || typeof cur[cur.length - 1] !== 'object') cur.push({});
+                            _parent = cur;
+                            _parentKey = cur.length - 1;
+                            cur = cur[cur.length - 1];
+                            continue;
+                        }
+
+                        // normal key
+                        if (isLast)
+                        {
+                            if (Array.isArray(cur))
+                            {
+                                // numeric key may indicate index
+                                const idx = Number(part);
+                                if (!Number.isNaN(idx)) cur[idx] = appendValue(cur[idx], v);
+                                else cur[part] = appendValue(cur[part], v);
+                            }
+                            else
+                            {
+                                cur[part] = appendValue(cur[part], v);
+                            }
+                        }
+                        else
+                        {
+                            if (Array.isArray(cur))
+                            {
+                                const idx = Number(part);
+                                if (!Number.isNaN(idx))
+                                {
+                                    if (!cur[idx]) cur[idx] = {};
+                                    _parent = cur;
+                                    _parentKey = idx;
+                                    cur = cur[idx];
+                                } else
+                                {
+                                    // Non-numeric key on array — navigate into last pushed object
+                                    if (cur.length === 0) cur.push({});
+                                    if (typeof cur[cur.length - 1] !== 'object') cur.push({});
+                                    const obj = cur[cur.length - 1];
+                                    if (!obj[part]) obj[part] = {};
+                                    _parent = obj;
+                                    _parentKey = part;
+                                    cur = obj[part];
+                                }
+                            }
+                            else
+                            {
+                                if (!cur[part]) cur[part] = {};
+                                _parent = cur;
+                                _parentKey = part;
+                                cur = cur[part];
+                            }
+                        }
+                    }
+                }
+                req.body = out;
+            }
+        } catch (err)
+        {
+            if (err && err.status === 413) return sendError(res, 413, 'payload too large');
+            if (err && err.status === 415) return sendError(res, 415, err.message || 'unsupported encoding');
+            req.body = {};
+        }
+        next();
+    };
+}
+
+module.exports = urlencoded;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-server/body",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "json, urlencoded, text, raw, multipart parsers.",
   "keywords": [
     "zero-server",
@@ -20,6 +20,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "lib",
     "index.js",
     "index.d.ts",
     "README.md",
@@ -42,7 +43,12 @@
     "access": "public"
   },
   "sideEffects": false,
-  "dependencies": {
-    "@zero-server/sdk": "0.9.1"
+  "peerDependencies": {
+    "@zero-server/sdk": ">=0.9.2"
+  },
+  "peerDependenciesMeta": {
+    "@zero-server/sdk": {
+      "optional": true
+    }
   }
 }