fastify 6.0.0-alpha.1 → 6.0.0-alpha.3

package/docs/Guides/Ecosystem.md

@@ -226,6 +226,8 @@ section.
 - [`@pompelmi/fastify-plugin`](https://github.com/pompelmi/pompelmi/tree/main/packages/fastify-plugin)
   In-process file upload scanning for Fastify with MIME/magic-byte
   validation, ZIP bomb protection, size limits, and optional YARA.
+- [`@punkish/fastify-better-sqlite3`](https://github.com/punkish/fastify-better-sqlite3)
+  Plugin for better-sqlite3.
 - [`@pybot/fastify-autoload`](https://github.com/kunal097/fastify-autoload)
   Plugin to generate routes automatically with valid json content
 - [`@scalar/fastify-api-reference`](https://github.com/scalar/scalar/tree/main/integrations/fastify)
@@ -309,8 +311,6 @@ section.
   development servers that require Babel transformations of JavaScript sources.
 - [`fastify-bcrypt`](https://github.com/beliven-it/fastify-bcrypt) A Bcrypt hash
   generator & checker.
-- [`fastify-better-sqlite3`](https://github.com/punkish/fastify-better-sqlite3)
-  Plugin for better-sqlite3.
 - [`fastify-blipp`](https://github.com/PavelPolyakov/fastify-blipp) Prints your
   routes to the console, so you definitely know which endpoints are available.
 - [`fastify-bookshelf`](https://github.com/butlerx/fastify-bookshelfjs) Fastify
@@ -698,9 +698,6 @@ middlewares into Fastify plugins
   [uws](https://github.com/uNetworking/uWebSockets).
 - [`fastify-xml-body-parser`](https://github.com/NaturalIntelligence/fastify-xml-body-parser)
   Parse XML payload / request body into JS / JSON object.
-- [`http-wizard`](https://github.com/flodlc/http-wizard)
-  Exports a typescript API client for your Fastify API and ensures fullstack type
-  safety for your project.
 - [`i18next-http-middleware`](https://github.com/i18next/i18next-http-middleware#fastify-usage)
   An [i18next](https://www.i18next.com) based i18n (internationalization)
   middleware to be used with Node.js web frameworks like Express or Fastify and

package/docs/Guides/Style-Guide.md

@@ -13,7 +13,8 @@ This guide is for anyone who loves to build with Fastify or wants to contribute
 to our documentation. You do not need to be an expert in writing technical
 documentation. This guide is here to help you.
 
-Visit the [contribute](https://fastify.dev/contribute/) page on our website or
+Visit the [contribute](https://fastify.dev/docs/latest/Guides/Contributing/)
+page on our website or
 read the
 [CONTRIBUTING.md](https://github.com/fastify/fastify/blob/main/CONTRIBUTING.md)
 file on GitHub to join our Open Source folks.
@@ -224,18 +225,18 @@ hyperlink should look:
 <!-- More like this -->
 
 // Add clear & brief description
-[Fastify Plugins] (https://fastify.dev/docs/latest/Plugins/)
+[Fastify Plugins] (https://fastify.dev/docs/latest/Reference/Plugins/)
 
 <!--Less like this -->
 
 // incomplete description
-[Fastify] (https://fastify.dev/docs/latest/Plugins/)
+[Fastify] (https://fastify.dev/docs/latest/Reference/Plugins/)
 
 // Adding title in link brackets
-[](https://fastify.dev/docs/latest/Plugins/ "fastify plugin")
+[](https://fastify.dev/docs/latest/Reference/Plugins/ "fastify plugin")
 
 // Empty title
-[](https://fastify.dev/docs/latest/Plugins/)
+[](https://fastify.dev/docs/latest/Reference/Plugins/)
 
 // Adding links localhost URLs instead of using code strings (``)
 [http://localhost:3000/](http://localhost:3000/)

package/docs/Reference/ContentTypeParser.md

@@ -5,7 +5,10 @@ Fastify natively supports `'application/json'` and `'text/plain'` content types
 with a default charset of `utf-8`. These default parsers can be changed or
 removed.
 
-Unsupported content types will throw an `FST_ERR_CTP_INVALID_MEDIA_TYPE` error.
+Unsupported or [syntactically invalid](https://httpwg.org/specs/rfc9110.html#media.type)
+content types result in a `415 Unsupported Media Type` response with an
+[`FST_ERR_CTP_INVALID_MEDIA_TYPE`](./Errors.md#fst_err_ctp_invalid_media_type)
+error.
 
 To support other content types, use the `addContentTypeParser` API or an
 existing [plugin](https://fastify.dev/ecosystem/).
@@ -45,6 +48,25 @@ parsed.
 > by the regex has a corresponding entry in the schema's `content` map. See
 > [Validation and Serialization](./Validation-and-Serialization.md) for details.
 
+> ℹ️ Note:
+> Fastify validates the request's `Content-Type` header before selecting a body
+> parser. String, `RegExp`, and [catch-all](#catch-all) parsers therefore will
+> never handle an invalid header. An `onRequest` hook can rewrite a malformed
+> header prior to validation:
+>
+> ```js
+> fastify.addHook('onRequest', async function rewriteContentType (request) {
+>   if (request.headers['content-type'] === 'application/json,application/json') {
+>     request.headers['content-type'] = 'application/json'
+>   }
+> })
+> ```
+>
+> Apply only unambiguous rewrites and reject other malformed values. An invalid
+> media type can select a different body parser or `schema.body.content`
+> validation schema. Rewrite the header before accessing `request.mediaType`,
+> which parses and caches the current value.
+
 ### Usage
 ```js
 fastify.addContentTypeParser('application/jsoff', function (request, payload, done) {
@@ -167,10 +189,6 @@ fastify.addContentTypeParser('text/xml', function (request, payload, done) {
 })
 ```
 
-> ℹ️ Note:
-> `function(req, done)` and `async function(req)` are
-> still supported but deprecated.
-
 #### Body Parser
 The request body can be parsed in two ways. First, add a custom content type
 parser and handle the request stream. Or second, use the `parseAs` option in the

package/docs/Reference/Reply.md

@@ -638,9 +638,6 @@ invocation of `reply.send()` once the handler promise resolve should be skipped.
 By calling `reply.hijack()`, an application claims full responsibility for the
 low-level request and response. Moreover, hooks will not be invoked.
 
-*Modifying the `.sent` property directly is deprecated. Please use the
-aforementioned `.hijack()` method to achieve the same effect.*
-
 ### .hijack()
 <a name="hijack"></a>
 

package/docs/Reference/Request.md

@@ -72,10 +72,6 @@ Request is a core Fastify object containing the following fields:
   for cooperative cancellation. On timeout, `signal.reason` is the
   `FST_ERR_HANDLER_TIMEOUT` error; on client disconnect it is a generic
   `AbortError`. Check `signal.reason.code` to distinguish the two cases.
-- `context` - Deprecated, use `request.routeOptions.config` instead. A Fastify
-  internal object. Do not use or modify it directly. It is useful to access one
-  special key:
-  - `context.config` - The route [`config`](./Routes.md#routes-config) object.
 - `routeOptions` - The route [`option`](./Routes.md#routes-options) object.
   - `bodyLimit` - Either server limit or route limit.
   - `handlerTimeout` - The handler timeout configured for this route.

package/docs/Reference/Server.md

@@ -560,11 +560,14 @@ const fastify = require('fastify')({
 + `string`: Trust only given IP/CIDR (e.g. `'127.0.0.1'`). May be a list of
   comma separated values (e.g. `'127.0.0.1,192.168.1.1/24'`).
 + `Array<string>`: Trust only given IP/CIDR list (e.g. `['127.0.0.1']`).
-+ `number`: Trust the nth hop from the front-facing proxy server as the client.
++ `number`: Hop-count-only trust is disabled because it cannot validate the
+  immediate peer and lets direct clients spoof `X-Forwarded-*` values. Use an
+  IP/CIDR string, array, or custom function that validates the proxy address
+  instead.
 + `Function`: Custom trust function that takes `address` as first argument
     ```js
     function myTrustFn(address, hop) {
-      return address === '1.2.3.4' || hop === 1
+      return address === '1.2.3.4' && hop === 0
     }
     ```
 
@@ -586,7 +589,9 @@ You may access the `ip`, `ips`, `host` and `protocol` values on the
 > These values are derived from socket/forwarding metadata and must be treated
 > as untrusted input unless your proxy chain is explicitly trusted and
 > validated. Do not use them directly for authorization or other
-> security-sensitive decisions without explicit validation.
+> security-sensitive decisions without explicit validation. Custom trust
+> functions must validate the `address` argument; hop-count-only checks such as
+> `hop < 1` are unsafe when the Fastify origin can be reached directly.
 
 ```js
 fastify.get('/', (request, reply) => {

package/docs/Reference/Validation-and-Serialization.md

@@ -628,6 +628,17 @@ This pattern ensures validators work correctly with both sync and async
 `preValidation` hooks, preventing unhandled promise rejections that can crash
 an application.
 
+> [!IMPORTANT]
+> The `{ value, error }` result convention applies to **synchronous** validator
+> compilers only. An **asynchronous** validator (a compiler that returns a
+> promise, including an [`$async` Ajv schema](https://ajv.js.org/guide/async-validation.html))
+> is treated as pass/fail only: its resolved value is not unwrapped as
+> `{ value, error }`. An async schema resolves with the validated data itself, so
+> unwrapping it would let a payload that carries `value` or `error` keys replace
+> the request part or inject a validation error. An async validator must signal
+> failure by rejecting (throwing), and it cannot coerce the request part through
+> a resolved `value`.
+
 ##### .statusCode property
 
 All validation errors have a `.statusCode` property set to `400`, ensuring the

package/docs/Reference/Warnings.md

@@ -7,6 +7,9 @@
   - [Fastify Warning Codes](#fastify-warning-codes)
     - [FSTWRN001](#FSTWRN001)
     - [FSTWRN003](#FSTWRN003)
+  - [Fastify Security Codes](#fastify-security-codes)
+    - [FSTSEC001](#FSTSEC001)
+    - [FSTSEC002](#FSTSEC002)
   - [Fastify Deprecation Codes](#fastify-deprecation-codes)
 
 ## Warnings
@@ -42,6 +45,13 @@ Disabling warnings is not recommended and may cause unexpected behavior.
 | <a id="FSTWRN001">FSTWRN001</a> | The specified schema for a route is missing. This may indicate the schema is not well specified. | Check the schema for the route. | [#4647](https://github.com/fastify/fastify/pull/4647) |
 | <a id="FSTWRN003">FSTWRN003</a> | The `%s` plugin mixes async and callback styles, which may lead to unhandled rejections. | Do not mix async and callback style. | [#6011](https://github.com/fastify/fastify/pull/6011) |
 
+### Fastify Security Codes
+
+| Code | Description | How to solve | Discussion |
+| ---- | ----------- | ------------ | ---------- |
+| <a id="FSTSEC001">FSTSEC001</a> | A `RegExp` Content-Type is used that may be vulnerable to a CORS bypass, because it does not anchor the essence MIME type. | Start the `RegExp` with `^` or include `;?` so the essence MIME type is detected correctly. | [#4450](https://github.com/fastify/fastify/pull/4450) |
+| <a id="FSTSEC002">FSTSEC002</a> | A headers schema references an external `$ref` (a schema registered with `addSchema`) that is not reached by header case normalization. Header names in the referenced schema keep their original case and do not match the lowercased request headers, so case-insensitive assertions such as `required` and `dependencies` may not apply. | Inline the header schema instead of referencing it with an external `$ref`. | - |
+
 ### Fastify Deprecation Codes
 
 Deprecation codes are supported by the Node.js CLI options:

package/fastify.d.ts

@@ -144,7 +144,7 @@ declare namespace fastify {
     serverFactory?: FastifyServerFactory<RawServer>,
     requestIdHeader?: string | false,
     genReqId?: (req: RawRequestDefaultExpression<RawServer>) => string,
-    trustProxy?: boolean | string | string[] | number | TrustProxyFunction,
+    trustProxy?: boolean | string | string[] | TrustProxyFunction,
     schemaController?: {
       bucket?: (parentSchemas?: unknown) => {
         add(schema: unknown): FastifyInstance;

package/fastify.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const VERSION = '6.0.0-alpha.1'
+const VERSION = '6.0.0-alpha.3'
 
 const Avvio = require('avvio')
 const http = require('node:http')
@@ -600,7 +600,7 @@ function fastify (serverOptions) {
 
     if (name === 'onClose') {
       this.onClose(fn.bind(this))
-    } else if (name === 'onReady' || name === 'onListen' || name === 'onRoute') {
+    } else if (name === 'onReady' || name === 'onListen' || name === 'onRoute' || name === 'preClose') {
       this[kHooks].add(name, fn)
     } else {
       this.after((err, done) => {

package/lib/four-oh-four.js

@@ -34,11 +34,10 @@ function fourOhFour (options) {
 
   // 404 router, used for handling encapsulated 404 handlers
   const router = FindMyWay({
-    onBadUrl: createRouteEventHandler(),
-    onMaxParamLength: createRouteEventHandler(),
+    onBadUrl: options.routerOptions.onBadUrl,
+    onMaxParamLength: options.routerOptions.onMaxParamLength,
     defaultRoute: fourOhFourFallBack
   })
-  let _routeEventHandler = null
 
   return { router, setNotFoundHandler, setContext, arrange404 }
 
@@ -47,8 +46,6 @@ function fourOhFour (options) {
     instance[kFourOhFourLevelInstance] = instance
     instance[kCanSetNotFoundHandler] = true
     // we need to bind instance for the context
-    router.onBadUrl = router.onBadUrl.bind(instance)
-    router.onMaxParamLength = router.onMaxParamLength.bind(instance)
     router.defaultRoute = router.defaultRoute.bind(instance)
   }
 
@@ -62,20 +59,15 @@ function fourOhFour (options) {
     })
   }
 
-  function createRouteEventHandler () {
-    return function onRouteEvent (path, req, res) {
-      const fourOhFourContext = this[kFourOhFourLevelInstance][kFourOhFourContext]
-      const id = getGenReqId(fourOhFourContext.server, req)
-      const childLogger = createChildLogger(fourOhFourContext, logger, req, id)
-      const request = new Request(id, null, req, null, childLogger, fourOhFourContext)
-      const reply = new Reply(res, request, childLogger)
-
-      _routeEventHandler(request, reply)
-    }
-  }
-
   function setContext (instance, context) {
-    const _404Context = Object.assign({}, instance[kFourOhFourContext])
+    // Use the selected not-found context as the prototype rather than taking a
+    // detached shallow snapshot. The selected context's lifecycle hooks are
+    // populated during preReady (potentially after this snapshot is taken when
+    // the route is registered first), and prototype lookup keeps the
+    // route-specific 404 context linked to the live one so hooks like
+    // preHandler are not lost. The route's own onSend is preserved as an own
+    // property.
+    const _404Context = Object.create(instance[kFourOhFourContext])
     _404Context.onSend = context.onSend
     context[kFourOhFourContext] = _404Context
   }
@@ -123,12 +115,8 @@ function fourOhFour (options) {
     if (handler) {
       this[kFourOhFourLevelInstance][kCanSetNotFoundHandler] = false
       handler = handler.bind(this)
-      // update route event handler
-      _routeEventHandler = handler
     } else {
       handler = basic404
-      // update route event handler
-      _routeEventHandler = basic404
     }
 
     this.after((notHandledErr, done) => {

package/lib/request.js

@@ -49,8 +49,9 @@ function getTrustProxyFn (tp) {
     return function () { return true }
   }
   if (typeof tp === 'number') {
-    // Support trusting hop count
-    return function (a, i) { return i < tp }
+    // Hop-count-only trust cannot validate the immediate peer. Fail closed so
+    // direct clients cannot spoof X-Forwarded-* values by supplying enough hops.
+    return function () { return false }
   }
   if (typeof tp === 'string') {
     // Support comma-separated tps

package/lib/route.js

@@ -289,6 +289,7 @@ function buildRouting (options) {
         opts.attachValidation = false
       }
 
+      const routeConfigUrl = prefixing ? prefix : url
       if (prefixing === false) {
         // run 'onRoute' hooks
         for (const hook of this[kHooks].onRoute) {
@@ -327,7 +328,7 @@ function buildRouting (options) {
       const constraints = opts.constraints || {}
       const config = {
         ...opts.config,
-        url,
+        url: routeConfigUrl,
         method: opts.method
       }
 
@@ -409,10 +410,13 @@ function buildRouting (options) {
             context.schema = normalizeSchema(context.schema, this.initialConfig)
 
             const schemaController = this[kSchemaController]
-            const hasValidationSchema = opts.schema.body ||
-              opts.schema.headers ||
-              opts.schema.querystring ||
-              opts.schema.params
+            // A JSON Schema boolean (`false` or `true`) is a valid schema and
+            // must still trigger the validator compiler setup, so presence is
+            // determined from an explicit `undefined` check rather than truthiness.
+            const hasValidationSchema = opts.schema.body !== undefined ||
+              opts.schema.headers !== undefined ||
+              opts.schema.querystring !== undefined ||
+              opts.schema.params !== undefined
             if (!opts.validatorCompiler && hasValidationSchema) {
               schemaController.setupValidator(this[kOptions])
             }

package/lib/schemas.js

@@ -61,9 +61,12 @@ function normalizeSchema (routeSchemas, serverOptions) {
   }
 
   // alias query to querystring schema
-  if (routeSchemas.query) {
+  // A JSON Schema boolean (`false` or `true`) is a valid schema and must still
+  // be aliased, so presence is determined from an explicit `undefined` check
+  // rather than truthiness.
+  if (routeSchemas.query !== undefined) {
     // check if our schema has both querystring and query
-    if (routeSchemas.querystring) {
+    if (routeSchemas.querystring !== undefined) {
       throw new FST_ERR_SCH_DUPLICATE('querystring')
     }
     routeSchemas.querystring = routeSchemas.query

package/lib/validation.js

@@ -13,7 +13,7 @@ const {
   FST_ERR_SCH_RESPONSE_SCHEMA_NOT_NESTED_2XX
 } = require('./errors')
 
-const { FSTWRN001 } = require('./warnings')
+const { FSTWRN001, FSTSEC002 } = require('./warnings')
 
 function compileSchemasForSerialization (context, compile) {
   if (!context.schema || !context.schema.response) {
@@ -54,6 +54,169 @@ function compileSchemasForSerialization (context, compile) {
     }, {})
 }
 
+// Header names are case insensitive (RFC 9110 §5.1), and Node.js stores every
+// received header name in lowercase in `request.headers` (see the Node.js
+// `message.headers` docs). The header schema must be normalized the same way
+// before compilation, otherwise schema keywords that reference header names by
+// their canonical or mixed case — `properties`, `required`, and the Draft 7
+// `dependencies` keyword (triggers and array-form dependent names) — never
+// match the lowercased request object, silently skipping assertions.
+//
+// JSON Schema is recursive, so the transformation walks the whole schema and
+// lowercases every position where a property name (i.e. a header name) appears,
+// while recursing into subschemas. This covers `properties` and `required` in
+// every nested subschema, `dependencies` trigger keys, array-form dependent
+// property names and subschemas used as dependency values, and subschemas
+// reachable through `allOf`, `anyOf`, `oneOf`, `not`, `if`/`then`/`else`, local
+// `$ref` definitions (`definitions`/`$defs`), and the other standard subschema
+// containers. The input schema is never mutated: a new schema tree is returned.
+function lowerCaseHeadersSchema (schema) {
+  if (Array.isArray(schema)) {
+    return schema.map(lowerCaseHeadersSchema)
+  }
+  if (schema === null || typeof schema !== 'object') {
+    return schema
+  }
+
+  const result = {}
+
+  for (const key of Object.keys(schema)) {
+    const value = schema[key]
+
+    switch (key) {
+      case 'properties': {
+        if (value === null || typeof value !== 'object') {
+          result.properties = value
+          break
+        }
+        const normalized = {}
+        for (const prop of Object.keys(value)) {
+          normalized[prop.toLowerCase()] = lowerCaseHeadersSchema(value[prop])
+        }
+        result.properties = normalized
+        break
+      }
+      case 'required':
+        result.required = Array.isArray(value)
+          ? value.map(name => name.toLowerCase())
+          : value
+        break
+      case 'dependencies': {
+        if (value === null || typeof value !== 'object') {
+          result.dependencies = value
+          break
+        }
+        const normalized = {}
+        for (const dep of Object.keys(value)) {
+          const depValue = value[dep]
+          if (Array.isArray(depValue)) {
+            normalized[dep.toLowerCase()] = depValue.map(name => name.toLowerCase())
+          } else {
+            normalized[dep.toLowerCase()] = lowerCaseHeadersSchema(depValue)
+          }
+        }
+        result.dependencies = normalized
+        break
+      }
+      case 'dependentSchemas': {
+        if (value === null || typeof value !== 'object') {
+          result.dependentSchemas = value
+          break
+        }
+        const normalized = {}
+        for (const dep of Object.keys(value)) {
+          normalized[dep.toLowerCase()] = lowerCaseHeadersSchema(value[dep])
+        }
+        result.dependentSchemas = normalized
+        break
+      }
+      case 'dependentRequired': {
+        if (value === null || typeof value !== 'object') {
+          result.dependentRequired = value
+          break
+        }
+        const normalized = {}
+        for (const dep of Object.keys(value)) {
+          normalized[dep.toLowerCase()] = value[dep].map(name => name.toLowerCase())
+        }
+        result.dependentRequired = normalized
+        break
+      }
+      // Arrays of subschemas (`allOf`/`anyOf`/`oneOf`) or a single subschema
+      // (`not`/`if`/`then`/`else`/`items`/`additionalItems`/...). `lowerCaseHeadersSchema`
+      // handles arrays, objects and booleans, so recursing here covers them all.
+      case 'allOf':
+      case 'anyOf':
+      case 'oneOf':
+      case 'not':
+      case 'if':
+      case 'then':
+      case 'else':
+      case 'items':
+      case 'additionalItems':
+      case 'additionalProperties':
+      case 'unevaluatedItems':
+      case 'unevaluatedProperties':
+      case 'contains':
+      case 'propertyNames':
+      case 'contentSchema':
+        result[key] = lowerCaseHeadersSchema(value)
+        break
+      // Maps of subschemas whose keys are not header names (definition names,
+      // regex patterns): keep the keys, normalize the subschema values.
+      case 'definitions':
+      case '$defs':
+      case 'patternProperties': {
+        if (value === null || typeof value !== 'object') {
+          result[key] = value
+          break
+        }
+        const normalized = {}
+        for (const k of Object.keys(value)) {
+          normalized[k] = lowerCaseHeadersSchema(value[k])
+        }
+        result[key] = normalized
+        break
+      }
+      default:
+        result[key] = value
+    }
+  }
+
+  return result
+}
+
+// `lowerCaseHeadersSchema` only normalizes the inline schema tree. A header
+// schema can also pull in a schema registered with `addSchema()` through an
+// external `$ref` (any ref that does not start with `#`, i.e. not a same
+// document fragment). Those referenced schemas are resolved by the validator
+// after normalization and keep their original header-name case, so
+// case-insensitive assertions in them never match the lowercased request
+// headers. We cannot safely normalize them here because the same registered
+// schema is shared with body, querystring and params validation, so we detect
+// the external reference and warn the developer instead. Returns the first
+// external `$ref` found, or undefined.
+function findExternalHeaderRef (schema) {
+  if (Array.isArray(schema)) {
+    for (const item of schema) {
+      const ref = findExternalHeaderRef(item)
+      if (ref !== undefined) return ref
+    }
+    return undefined
+  }
+  if (schema === null || typeof schema !== 'object') {
+    return undefined
+  }
+  if (typeof schema.$ref === 'string' && schema.$ref[0] !== '#') {
+    return schema.$ref
+  }
+  for (const key of Object.keys(schema)) {
+    const ref = findExternalHeaderRef(schema[key])
+    if (ref !== undefined) return ref
+  }
+  return undefined
+}
+
 function compileSchemasForValidation (context, compile, isCustom) {
   const { schema } = context
   if (!schema) {
@@ -62,32 +225,37 @@ function compileSchemasForValidation (context, compile, isCustom) {
 
   const { method, url } = context.config || {}
 
+  // JSON Schema Draft 7 defines the boolean `false` (and `true`) as a valid
+  // schema. A present boolean must be passed to the compiler unchanged, so
+  // every request-part schema is selected by an explicit `undefined` check
+  // rather than truthiness. FSTWRN001 is preserved only for schemas that are
+  // explicitly set to `undefined`.
+
   const headers = schema.headers
   // the or part is used for backward compatibility
-  if (headers && (isCustom || Object.getPrototypeOf(headers) !== Object.prototype)) {
-    // do not mess with schema when custom validator applied, e.g. Joi, Typebox
-    context[headersSchema] = compile({ schema: headers, method, url, httpPart: 'headers' })
-  } else if (headers) {
-    // The header keys are case insensitive
-    //  https://datatracker.ietf.org/doc/html/rfc2616#section-4.2
-    const headersSchemaLowerCase = {}
-    Object.keys(headers).forEach(k => { headersSchemaLowerCase[k] = headers[k] })
-    if (headersSchemaLowerCase.required instanceof Array) {
-      headersSchemaLowerCase.required = headersSchemaLowerCase.required.map(h => h.toLowerCase())
-    }
-    if (headers.properties) {
-      headersSchemaLowerCase.properties = {}
-      Object.keys(headers.properties).forEach(k => {
-        headersSchemaLowerCase.properties[k.toLowerCase()] = headers.properties[k]
-      })
+  if (headers !== undefined) {
+    if (isCustom || typeof headers !== 'object' || headers === null || Object.getPrototypeOf(headers) !== Object.prototype) {
+      // do not mess with schema when custom validator applied, e.g. Joi, Typebox
+      // boolean schemas (true/false) and invalid values are compiled directly
+      context[headersSchema] = compile({ schema: headers, method, url, httpPart: 'headers' })
+    } else {
+      // The header keys are case insensitive
+      //  https://datatracker.ietf.org/doc/html/rfc2616#section-4.2
+      const headersSchemaLowerCase = lowerCaseHeadersSchema(headers)
+      const externalRef = findExternalHeaderRef(headers)
+      if (externalRef !== undefined) {
+        FSTSEC002(method, url, externalRef)
+      }
+      context[headersSchema] = compile({ schema: headersSchemaLowerCase, method, url, httpPart: 'headers' })
     }
-    context[headersSchema] = compile({ schema: headersSchemaLowerCase, method, url, httpPart: 'headers' })
   } else if (Object.hasOwn(schema, 'headers')) {
     FSTWRN001('headers', method, url)
   }
 
-  if (schema.body) {
-    const contentProperty = schema.body.content
+  if (schema.body !== undefined) {
+    const contentProperty = schema.body !== null && typeof schema.body === 'object'
+      ? schema.body.content
+      : undefined
     if (contentProperty) {
       const contentTypeSchemas = {}
       for (const contentType of Object.keys(contentProperty)) {
@@ -102,13 +270,13 @@ function compileSchemasForValidation (context, compile, isCustom) {
     FSTWRN001('body', method, url)
   }
 
-  if (schema.querystring) {
+  if (schema.querystring !== undefined) {
     context[querystringSchema] = compile({ schema: schema.querystring, method, url, httpPart: 'querystring' })
   } else if (Object.hasOwn(schema, 'querystring')) {
     FSTWRN001('querystring', method, url)
   }
 
-  if (schema.params) {
+  if (schema.params !== undefined) {
     context[paramsSchema] = compile({ schema: schema.params, method, url, httpPart: 'params' })
   } else if (Object.hasOwn(schema, 'params')) {
     FSTWRN001('params', method, url)
@@ -120,7 +288,16 @@ function validateParam (validatorFunction, request, paramName) {
   let ret
 
   try {
-    ret = validatorFunction?.(isUndefined ? null : request[paramName])
+    const data = isUndefined ? null : request[paramName]
+    // Ajv can only mutate a root value when its parent is provided.
+    if (validatorFunction?.schemaEnv) {
+      ret = validatorFunction(data, {
+        parentData: request,
+        parentDataProperty: paramName
+      })
+    } else {
+      ret = validatorFunction?.(data)
+    }
   } catch (err) {
     // If validator throws synchronously, ensure it propagates as an internal error
     err.statusCode = 500
@@ -128,8 +305,13 @@ function validateParam (validatorFunction, request, paramName) {
   }
 
   if (ret && typeof ret.then === 'function') {
+    // An async validator (for example an `$async` Ajv schema) resolves with the
+    // validated data itself, not a `{ value, error }` result. Its properties must
+    // not be unwrapped the way a synchronous custom compiler result is, otherwise
+    // a payload carrying an `error` or `value` key could inject a validation error
+    // or replace the whole request part. Treat the async result as pass/fail only.
     return ret
-      .then((res) => { return answer(res) })
+      .then((res) => { return res === false ? validatorFunction.errors : false })
       .catch(err => { return err }) // return as simple error (not throw)
   }