@centralping/ergo 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0-beta.1] - 2026-05-20
+
+### Changed
+
+- **BREAKING**: Renamed package from `ergo` to `@centralping/ergo`.
+- Updated `content-type` dependency to v2.0.0 (string-only parse API).
+- Added TypeScript declaration files (`.d.ts`) generated from JSDoc.
+- Added `CHANGELOG.md` to published npm tarball.
+- Updated release workflow to support pre-release dist-tags.
+
+## [0.1.0] - 2026-03-20
+
+### Added
+
+- Initial development release as `ergo` (unscoped, never published to npm).
+- Composable Fast Fail middleware pipeline with four-stage architecture (Negotiation, Authorization, Validation, Execution).
+- RFC-compliant middleware: content negotiation, authorization (Basic/Bearer), body parsing (JSON/multipart/URL-encoded), cookie handling, CORS, CSRF protection, rate limiting, security headers, cache control, conditional requests, compression, and more.
+- Structured error responses via RFC 9457 Problem Details.
+- Prefer header support (RFC 7240).
+- Web Linking support (RFC 8288).
+- Pure ESM with Node.js >= 22.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-present Jason Cust
+
+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/README.md

@@ -0,0 +1,139 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-wordmark-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="assets/logo-wordmark-light.svg">
+    <img alt="ergo" src="assets/logo-wordmark-light.svg" width="240">
+  </picture>
+</p>
+
+[![CI](https://github.com/CentralPing/ergo/actions/workflows/ci.yml/badge.svg)](https://github.com/CentralPing/ergo/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/CentralPing/ergo/branch/main/graph/badge.svg)](https://codecov.io/gh/CentralPing/ergo)
+[![npm version](https://img.shields.io/npm/v/@centralping/ergo.svg)](https://www.npmjs.com/package/@centralping/ergo)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/CentralPing/ergo/badge)](https://scorecard.dev/viewer/?uri=github.com/CentralPing/ergo)
+[![Node.js >=22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A **Fast Fail** REST API toolkit for Node.js. _ergo_ (error or go) provides composable, stream-native middleware organized around the principle that a server should fail as early as possible -- before doing any expensive work -- through four ordered stages: **Negotiation, Authorization, Validation, and Execution**. Every behavior is backed by an IETF RFC or industry standard, not invented conventions.
+
+## Why ergo?
+
+- **Fail Fast by design** -- Errors are caught at the earliest possible stage. You never parse a request body for an unauthenticated user, and you never execute business logic on invalid input. This principle produces more robust software with fewer defects ([Shore, "Fail Fast", IEEE Software 2004](https://www.martinfowler.com/ieeeSoftware/failFast.pdf)) and is a core reliability pillar in the [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_mitigate_interaction_failure_limit_retries.html).
+- **RESTful-first via RFCs** -- Every middleware implements a specific RFC or standard. Content negotiation follows [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110), error responses use [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457), cookies follow [RFC 6265](https://www.rfc-editor.org/rfc/rfc6265). No proprietary patterns.
+- **Defense in depth** -- Input validation happens [as early as possible in the data flow](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html) per OWASP, and access control is enforced [at each API endpoint](https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html) before business logic. Authorization runs before body parsing, so unauthenticated requests never trigger expensive I/O.
+- **Secure by default** -- Security headers ship with conservative defaults (`Content-Security-Policy: default-src 'none'`, `X-Frame-Options: DENY`). All user-input objects use [null prototypes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create#object_with_null_prototype) to prevent prototype pollution. Input parsing is bounded out of the box (query length, pair count, body size, decompressed size). The pipeline's design maps directly to the [OWASP API Security Top 10](https://owasp.org/API-Security/) and [REST Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html).
+- **Zero-overhead composition** -- Synchronous middleware avoids microtask overhead entirely. Independent middleware within a stage run concurrently. The pipeline is a single function call with no framework runtime.
+
+## The Fast Fail Design
+
+Every API request passes through exactly four stages, in order:
+
+```
+Request
+  |
+  +- Stage 1: Negotiation      Parse and inspect the request.
+  |    logger() -> [ cors() | accepts() | cookie() | url() ]
+  |
+  +- Stage 2: Authorization    Authenticate user, verify request integrity.
+  |    [ authorization() | csrf() ]
+  |
+  +- Stage 3: Validation       Parse and validate the request body.
+  |    body() . validate()
+  |
+  +- Stage 4: Execution        Run the handler and send the response.
+       timeout() . compress() . [your route logic] . send()
+```
+
+Stages run serially. If any middleware throws, the pipeline stops immediately and the error handler runs. Independent middleware within a stage are parallelizable (shown with `|`).
+
+## Installation
+
+```bash
+npm install @centralping/ergo
+```
+
+Requires **Node.js >= 22**.
+
+## Quick Start
+
+```js
+import {createServer} from 'node:http';
+import {compose, handler, logger, cors, authorization, body, send} from '@centralping/ergo';
+
+const pipeline = compose(
+  [logger(), [], 'log'],
+  [cors(), [], 'cors'],
+  [authorization({strategies: [{type: 'Bearer', authorizer: (_, token) =>
+    token === 'my-token' ? {authorized: true, info: {uid: 1}} : {}
+  }]}), [], 'auth'],
+  [body(), [], 'body'],
+  (req, res, {auth, body}) => ({body: {user: auth, data: body.parsed}}),
+  send()
+);
+
+createServer(handler(pipeline, send())).listen(3000);
+```
+
+## Middleware Overview
+
+| Middleware | Description | Standard |
+|---|---|---|
+| `logger()` | Request ID + structured request/response logging | -- |
+| `cors()` | CORS preflight and simple request handling | [Fetch Standard](https://fetch.spec.whatwg.org/#http-cors-protocol) |
+| `accepts()` | Content negotiation (type, encoding, language) | [RFC 9110 &sect;12.5](https://www.rfc-editor.org/rfc/rfc9110#section-12.5) |
+| `cookie()` | Cookie parsing with Set-Cookie builder | [RFC 6265](https://www.rfc-editor.org/rfc/rfc6265) |
+| `url()` | URL and query string parsing | -- |
+| `authorization()` | Bearer / Basic auth with pluggable strategies | [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750), [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617) |
+| `csrf()` | Double-submit cookie CSRF protection | [OWASP CSRF Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html) |
+| `body()` | JSON, multipart/form-data, URL-encoded parsing | [RFC 7578](https://www.rfc-editor.org/rfc/rfc7578) |
+| `validate()` | JSON Schema validation via AJV | -- |
+| `timeout()` | Request timeout with automatic 408/504 | -- |
+| `compress()` | Content-Encoding negotiation (gzip, deflate, br) | [RFC 9110 &sect;12.5.3](https://www.rfc-editor.org/rfc/rfc9110#section-12.5.3) |
+| `send()` | Response serialization, ETag, conditional requests, Problem Details errors | [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110), [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) |
+| `prefer()` | Prefer header parsing and response | [RFC 7240](https://www.rfc-editor.org/rfc/rfc7240) |
+| `precondition()` | 428 Precondition Required enforcement | [RFC 6585 &sect;3](https://www.rfc-editor.org/rfc/rfc6585#section-3) |
+| `rateLimit()` | Sliding-window rate limiting with 429 responses | [RFC 6585 &sect;4](https://www.rfc-editor.org/rfc/rfc6585#section-4) |
+| `securityHeaders()` | HSTS, CSP, X-Content-Type-Options, etc. | [RFC 6797](https://www.rfc-editor.org/rfc/rfc6797) |
+| `cacheControl()` | Cache-Control header management | [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111) |
+| `jsonApiQuery()` | JSON:API query parameter validation | [JSON:API](https://jsonapi.org/) |
+
+See the [full API reference](https://centralping.github.io/api/ergo/) for detailed options and examples.
+
+## Standards Compliance
+
+| RFC / Standard | Description | ergo Feature |
+|---|---|---|
+| [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110) | HTTP Semantics | `send()` conditional requests, ETag, content negotiation |
+| [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) | Problem Details for HTTP APIs | `send()` error responses, `httpErrors` utility |
+| [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111) | HTTP Caching | `cacheControl()` |
+| [RFC 9205](https://www.rfc-editor.org/rfc/rfc9205) | Building Protocols with HTTP (BCP 56) | Overall API design philosophy |
+| [RFC 7240](https://www.rfc-editor.org/rfc/rfc7240) | Prefer Header for HTTP | `prefer()` |
+| [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) | Web Linking | `lib/link.js` pagination helpers |
+| [RFC 6585](https://www.rfc-editor.org/rfc/rfc6585) | Additional HTTP Status Codes (428, 429) | `precondition()`, `rateLimit()` |
+| [RFC 6265](https://www.rfc-editor.org/rfc/rfc6265) | HTTP State Management (Cookies) | `cookie()` |
+| [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750) | Bearer Token Usage | `authorization()` |
+| [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617) | Basic HTTP Authentication | `authorization()` |
+| [RFC 7578](https://www.rfc-editor.org/rfc/rfc7578) | multipart/form-data | `body()` |
+| [RFC 6797](https://www.rfc-editor.org/rfc/rfc6797) | HTTP Strict Transport Security | `securityHeaders()` |
+| [OWASP API Security Top 10](https://owasp.org/API-Security/) | Aligned with top API security risks | Pipeline stage ordering, `rateLimit()`, `securityHeaders()`, input bounding |
+| [OWASP REST Security](https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html) | Aligned with REST security best practices | Auth enforcement, input validation, security headers, error redaction |
+
+## Documentation
+
+- [Getting Started](https://centralping.github.io/getting-started/)
+- [API Reference](https://centralping.github.io/api/ergo/)
+- [Architecture & Design](https://centralping.github.io/architecture/)
+- [Benchmarks](https://centralping.github.io/benchmarks/)
+
+## Development
+
+```bash
+npm install
+npm test            # lint + format check + tests with coverage
+npm run test:watch  # watch mode
+npm run lint        # ESLint
+npm run format      # Prettier
+```
+
+## License
+
+[MIT](LICENSE) &copy; 2019-present Jason Cust

package/http/accepts.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview HTTP middleware factory for content negotiation.
+ *
+ * Wraps the `negotiator` library to inspect `Accept`, `Accept-Language`,
+ * `Accept-Charset`, and `Accept-Encoding` request headers and determine the best
+ * matching content type, language, charset, and encoding for the response.
+ *
+ * When `throwIfFail` is true, returns `{response: {statusCode: 406, detail}}` for any
+ * header that cannot be satisfied, enforcing strict content negotiation in the
+ * Fast Fail pipeline.
+ *
+ * @module http/accepts
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../lib/accepts.js
+ * @requires ../utils/http-errors.js
+ *
+ * @example
+ * import {compose, accepts} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [accepts({types: ['application/json']}), 'accepts'],
+ *   // acc.accepts => {type: 'application/json', language: 'en', charset: 'utf-8', encoding: 'identity'}
+ * );
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc9110#section-12.5 RFC 9110 Section 12.5 - Content Negotiation}
+ */
+import accepts from '../lib/accepts.js';
+
+const headerMap = {
+  type: 'Accept',
+  language: 'Accept-Language',
+  charset: 'Accept-Charset',
+  encoding: 'Accept-Encoding'
+};
+
+/**
+ * Creates a content negotiation middleware.
+ *
+ * @param {object} [options] - Negotiation configuration
+ * @param {boolean} [options.throwIfFail=false] - Return `{response: {statusCode: 406, detail}}` if any negotiation key is undefined
+ * @param {string[]} [options.types] - Acceptable media types
+ * @param {string[]} [options.languages] - Acceptable languages
+ * @param {string[]} [options.charsets] - Acceptable character sets
+ * @param {string[]} [options.encodings] - Acceptable content encodings
+ * @returns {function} - Middleware `(req) => {type, language, charset, encoding}` on success, or `{response: {statusCode: 406, detail: string}}` when `throwIfFail` is true and any negotiation value is undefined
+ */
+export default ({throwIfFail = false, ...options} = {}) => {
+  const acceptor = accepts(options);
+
+  return ({headers = {}} = {}) => {
+    const accepted = acceptor(headers);
+
+    if (throwIfFail) {
+      for (const [k, v] of Object.entries(accepted)) {
+        if (v === undefined) {
+          return {
+            response: {
+              statusCode: 406,
+              detail: `Failed to negotiate content for: [${headerMap[k]}].`
+            }
+          };
+        }
+      }
+    }
+
+    return accepted;
+  };
+};

package/http/authorization.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview HTTP middleware factory for request authorization header parsing.
+ *
+ * Parses the `Authorization` header using one or more configured strategies (e.g. Bearer,
+ * Basic, API key). Each strategy provides a `type`, optional `attributes` matcher, and an
+ * `authorizer` function that receives the parsed credentials and returns `{authorized, info}`.
+ *
+ * On authorization failure, returns `{response: {statusCode: 403}}` by default. Strategies may return a custom
+ * `statusCode` (e.g. `401`) and an `authenticate` challenge string for the `WWW-Authenticate`
+ * response header (RFC 7235).
+ *
+ * @module http/authorization
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires ../lib/authorization.js
+ * @requires ../utils/http-errors.js
+ *
+ * @example
+ * import {compose, authorization} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [authorization({
+ *     strategies: [{
+ *       type: 'Bearer',
+ *       authorizer: async (attributes, token) => {
+ *         const user = await verifyJwt(token);
+ *         return user
+ *           ? {authorized: true, info: {user}}
+ *           : {authorized: false, info: {statusCode: 401}};
+ *       }
+ *     }]
+ *   }), 'auth'],
+ *   // acc.auth => {user: {...}} on success
+ * );
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc6750 RFC 6750 - Bearer Token Usage}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7617 RFC 7617 - The 'Basic' HTTP Authentication Scheme}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7235 RFC 7235 - HTTP Authentication}
+ */
+import authorize from '../lib/authorization.js';
+
+/**
+ * Creates an authorization middleware that parses the Authorization header
+ * and dispatches to the matching strategy handler.
+ *
+ * @param {object} [options] - Authorization configuration
+ * @param {Array<{type: string, attributes?: object, authorizer: function}>} [options.strategies=[]] - Authentication strategy definitions
+ * @returns {function} - Async middleware `(req) => info` on success; on failure `{response: {statusCode: 401|403, headers?}}` with optional `WWW-Authenticate` header tuples from `authenticate`
+ */
+export default ({strategies = []} = {}) => {
+  const authorizer = authorize(strategies);
+
+  return async ({headers: {authorization = ''} = {}} = {}) => {
+    const {authorized, info} = await authorizer(authorization);
+
+    if (authorized === false) {
+      const {statusCode = 403, authenticate} = info;
+      const headers = authenticate ? [['WWW-Authenticate', authenticate]] : undefined;
+
+      return {response: {statusCode, headers}};
+    }
+
+    return info;
+  };
+};

package/http/body.js

@@ -0,0 +1,311 @@
+/**
+ * @fileoverview HTTP middleware factory for request body parsing.
+ *
+ * Reads and parses the request body according to the declared `Content-Type`. Supports:
+ * - `application/json` and `application/vnd.api+json` — parsed via `JSON.parse`
+ * - `application/x-www-form-urlencoded` — parsed via the query string parser
+ * - `multipart/form-data` — parsed via the RFC 7578 streaming multipart parser
+ *
+ * Handles both `Content-Length` and `Transfer-Encoding: chunked` requests. Enforces
+ * a configurable byte limit (default 1 MiB). Returns `{response: {statusCode, detail}}` for:
+ * - `411 Length Required` if neither Content-Length nor chunked encoding is present
+ * - `413 Payload Too Large` if the body exceeds the limit
+ * - `415 Unsupported Media Type` for unrecognized content types
+ * - `400 Bad Request` if Content-Length doesn't match received bytes or the body is malformed
+ *
+ * Contains a fast path for identity-encoded `application/json` that bypasses the
+ * 3-stream pipeline for reduced per-request overhead.
+ *
+ * @module http/body
+ * @version 0.1.0
+ * @since 0.1.0
+ * @requires node:stream
+ * @requires node:zlib
+ * @requires content-type
+ * @requires ../utils/streams/meter.js
+ * @requires ../lib/body/writer.js
+ * @requires ../lib/query.js
+ * @requires ../lib/body/multiparse.js
+ * @requires ../utils/http-errors.js
+ *
+ * @example
+ * import {compose, body} from 'ergo';
+ *
+ * const pipeline = compose(
+ *   [body({limit: 2 * 1024 * 1024}), 'body'],
+ *   // acc.body => {type, charset, encoding, length, received, raw, parsed}
+ *   // For JSON types, acc.body.parsed is the decoded object
+ * );
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7578 RFC 7578 - Returning Values from Forms: multipart/form-data}
+ */
+import zlib from 'node:zlib';
+import {PassThrough} from 'node:stream';
+import {pipeline} from 'node:stream/promises';
+import {parse} from 'content-type';
+
+import meter from '../utils/streams/meter.js';
+import writer from '../lib/body/writer.js';
+import formParse from '../lib/query.js';
+import multiParse from '../lib/body/multiparse.js';
+import httpErrors from '../utils/http-errors.js';
+
+const errors = {
+  TooLarge({limit, length} = {}) {
+    return httpErrors(413, {
+      message: `Body exceeded limit: [${limit}]; received: [${length}]`
+    });
+  },
+  NoLength({length} = {}) {
+    return httpErrors(411, {
+      message: `Content-Length is required: [${length}]`
+    });
+  },
+  InvalidLength({length, received} = {}) {
+    return httpErrors(400, {
+      message: `Invalid Content-Length: [${length}]; received [${received}]`
+    });
+  },
+  Unsupported({prop, value, err} = {}) {
+    return httpErrors(415, {
+      message: `Unsupported ${prop}: [${value}]`,
+      originalError: err
+    });
+  },
+  Malformed({type, err} = {}) {
+    return httpErrors(400, {
+      message: `Malformed ${type} body`,
+      originalError: err
+    });
+  }
+};
+
+const parsers = new Proxy(
+  {
+    'application/x-www-form-urlencoded': formParse,
+    'multipart/form-data': multiParse
+  },
+  {
+    get(o, p) {
+      return Object.hasOwn(o, p) ? o[p] : JSON.parse;
+    }
+  }
+);
+
+const decompressors = new Proxy(
+  {
+    gzip: zlib.createGunzip,
+    deflate: zlib.createInflate,
+    br: zlib.createBrotliDecompress,
+    identity: () => new PassThrough()
+  },
+  {
+    get(o, p) {
+      if (Object.hasOwn(o, p)) {
+        return o[p]();
+      } else {
+        throw errors.Unsupported({prop: 'Content-Encoding', value: p});
+      }
+    }
+  }
+);
+
+/**
+ * Creates a request body parsing middleware.
+ *
+ * @param {object} [options] - Body parser configuration
+ * @param {number} [options.limit=DEFAULT_LIMIT] - Maximum body size in bytes (default 1 MiB)
+ * @param {number} [options.decompressedLimit] - Maximum decompressed body size (default 10 * limit, capped at MAX_DECOMPRESSED)
+ * @param {string[]} [options.types] - Allowed Content-Type MIME types
+ * @param {string} [options.charset='utf-8'] - Default character encoding
+ * @returns {function} - Async middleware `(req) => {type, charset, encoding, length, received, boundary, raw, parsed}` on success; on error `{response: {statusCode: 400|411|413|415, detail: string}}`. Errors without `statusCode` are rethrown.
+ */
+const DEFAULT_LIMIT = 1 << 20; // 1 MiB
+const MAX_DECOMPRESSED = 10 * DEFAULT_LIMIT; // 10 MiB hard cap
+
+export default ({
+    limit = DEFAULT_LIMIT,
+    decompressedLimit = Math.min(10 * limit, MAX_DECOMPRESSED),
+    types = [
+      'application/vnd.api+json',
+      'application/json',
+      'application/x-www-form-urlencoded',
+      'multipart/form-data'
+    ],
+    charset = 'utf-8'
+  } = {}) =>
+  async req => {
+    try {
+      let type;
+      let boundary;
+      let charsetEncoding = charset;
+      const ctHeader = req.headers['content-type'] ?? '';
+
+      // Fast path: plain "application/json" with no parameters
+      if (ctHeader === 'application/json') {
+        type = 'application/json';
+      } else {
+        try {
+          ({
+            type,
+            parameters: {charset: charsetEncoding = charsetEncoding, boundary}
+          } = parse(ctHeader));
+        } catch (err) {
+          throw errors.Unsupported({prop: 'Content-Type', value: ctHeader, err});
+        }
+      }
+
+      if (!types.includes(type)) {
+        throw errors.Unsupported({prop: 'Content-Type', value: type});
+      }
+
+      const hasContentLength = 'content-length' in req.headers;
+      // Per RFC 9112 §6.3, Transfer-Encoding overrides Content-Length when both present.
+      // Node's HTTP parser decodes chunked framing before this middleware sees chunks.
+      // Keeping the Content-Length check provides an extra integrity validation:
+      // if the proxy forwarded both headers, a mismatch results in a 400 rather than
+      // silent acceptance of inconsistent framing.
+      const isChunked = /\bchunked\b/i.test(req.headers['transfer-encoding'] ?? '');
+
+      let length;
+
+      if (hasContentLength) {
+        length = Number(req.headers['content-length']);
+        if (Number.isNaN(length) || length < 0) {
+          throw errors.NoLength({length: req.headers['content-length']});
+        }
+        if (length > limit) {
+          throw errors.TooLarge({limit, length});
+        }
+      } else if (!isChunked) {
+        throw errors.NoLength({length: req.headers['content-length']});
+      }
+
+      const encoding = req.headers['content-encoding'];
+      const isIdentity = !encoding || encoding === 'identity';
+
+      const {data: raw, received} = isIdentity
+        ? await readBodyDirect(req, {limit, expected: length, encoding: charsetEncoding})
+        : await readReqStream(req, {
+            limit,
+            decompressedLimit,
+            expected: length,
+            type: encoding,
+            encoding: charsetEncoding
+          });
+
+      const result = {type, charset: charsetEncoding, encoding, length, received, boundary, raw};
+
+      // Fast path: for JSON types, parse immediately instead of a lazy getter
+      if (
+        isIdentity &&
+        type !== 'multipart/form-data' &&
+        type !== 'application/x-www-form-urlencoded'
+      ) {
+        try {
+          result.parsed = JSON.parse(raw);
+        } catch (err) {
+          throw errors.Malformed({type, err});
+        }
+        return result;
+      }
+
+      Object.defineProperty(result, 'parsed', {
+        get() {
+          try {
+            return (this.parsed = parsers[type](this.raw, this.boundary));
+          } catch (err) {
+            throw errors.Malformed({type, err});
+          }
+        },
+        set(v) {
+          delete this.parsed;
+          this.parsed = v;
+        },
+        configurable: true
+      });
+
+      return result;
+    } catch (err) {
+      if (err?.statusCode) {
+        return {response: {statusCode: err.statusCode, detail: err.message}};
+      }
+      throw err;
+    }
+  };
+
+/**
+ * Fast path: buffer the request body directly without creating intermediate
+ * stream objects. Used when Content-Encoding is identity (no compression).
+ *
+ * Replicates the same size guards as the stream pipeline (meter + writer).
+ *
+ * @param {import('node:stream').Readable} stream - Incoming request body stream
+ * @param {object} options - Size-guard and charset options
+ * @returns {Promise<{data: string, received: number}>} - Resolved body string and byte count
+ */
+async function readBodyDirect(stream, {limit = Infinity, expected, encoding} = {}) {
+  const chunks = [];
+  let bytesRead = 0;
+
+  for await (const chunk of stream) {
+    bytesRead += chunk.length;
+
+    if (bytesRead > limit) {
+      stream.destroy();
+      throw errors.TooLarge({limit, length: bytesRead});
+    }
+
+    if (expected !== undefined && bytesRead > expected) {
+      stream.destroy();
+      throw errors.InvalidLength({length: expected, received: bytesRead});
+    }
+
+    chunks.push(chunk);
+  }
+
+  if (expected !== undefined && bytesRead !== expected) {
+    throw errors.InvalidLength({length: expected, received: bytesRead});
+  }
+
+  try {
+    return {data: Buffer.concat(chunks, bytesRead).toString(encoding), received: bytesRead};
+  } catch (err) {
+    throw errors.Unsupported({prop: 'charset', value: encoding, err});
+  }
+}
+
+/**
+ * Reads and optionally decompresses a request body through a stream pipeline
+ * with byte metering and size enforcement. A wire-side meter enforces `limit`
+ * on the compressed bytes; a second meter after decompression enforces
+ * `decompressedLimit` to protect against decompression bombs.
+ *
+ * @param {import('node:stream').Readable} stream - Incoming request body stream
+ * @param {object} options - Size-guard and decompression options
+ * @returns {Promise<{data: string, received: number}>} - Resolved body string and byte count
+ */
+async function readReqStream(
+  stream,
+  {limit = Infinity, decompressedLimit = Infinity, expected, encoding, type = 'identity'} = {}
+) {
+  const wireMeter = meter({limit, expected});
+  const inflatedMeter = meter({limit: decompressedLimit});
+  const w = writer();
+  const decompressor = decompressors[type];
+
+  try {
+    await pipeline(stream, wireMeter, decompressor, inflatedMeter, w);
+  } catch (err) {
+    if (err?.type in errors) {
+      throw errors[err.type](err);
+    }
+    throw err;
+  }
+
+  try {
+    return {data: w.data.toString(encoding), received: wireMeter.bytesRead};
+  } catch (err) {
+    throw errors.Unsupported({prop: 'charset', value: encoding, err});
+  }
+}