fastify 5.12.0 → 5.12.2

package/docs/Reference/Server.md

@@ -638,11 +638,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
     }
     ```
 
@@ -664,7 +667,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

@@ -8,6 +8,9 @@
     - [FSTWRN001](#FSTWRN001)
     - [FSTWRN003](#FSTWRN003)
     - [FSTWRN004](#FSTWRN004)
+  - [Fastify Security Codes](#fastify-security-codes)
+    - [FSTSEC001](#FSTSEC001)
+    - [FSTSEC002](#FSTSEC002)
   - [Fastify Deprecation Codes](#fastify-deprecation-codes)
     - [FSTDEP022](#FSTDEP022)
     - [FSTDEP023](#FSTDEP023)
@@ -47,6 +50,14 @@ 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) |
 | <a id="FSTWRN004">FSTWRN004</a> | An `errorHandler` is being overridden in the same scope, which can lead to subtle bugs. | Avoid calling `setErrorHandler` more than once in the same scope. For more information, see [Server documentation](https://fastify.dev/docs/latest/Reference/Server/#allowerrorhandleroverride). | [#6104](https://github.com/fastify/fastify/pull/6104) |
+
+### 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

@@ -149,7 +149,7 @@ declare namespace fastify {
     requestIdLogLabel?: string;
     useSemicolonDelimiter?: boolean,
     genReqId?: (req: RawRequestDefaultExpression<RawServer>) => string,
-    trustProxy?: boolean | string | string[] | number | TrustProxyFunction,
+    trustProxy?: boolean | string | string[] | TrustProxyFunction,
     querystringParser?: (str: string) => { [key: string]: unknown },
     constraints?: {
       [name: string]: ConstraintStrategy<FindMyWayVersion<RawServer>, unknown>,

package/fastify.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const VERSION = '5.12.0'
+const VERSION = '5.12.1'
 
 const Avvio = require('avvio')
 const http = require('node:http')
@@ -601,7 +601,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

@@ -290,6 +290,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) {
@@ -328,7 +329,7 @@ function buildRouting (options) {
       const constraints = opts.constraints || {}
       const config = {
         ...opts.config,
-        url,
+        url: routeConfigUrl,
         method: opts.method
       }
 
@@ -410,10 +411,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)
   }
 

package/lib/warnings.js

@@ -3,9 +3,10 @@
 const { createWarning } = require('process-warning')
 
 /**
- * Deprecation codes:
+ * Warning codes:
  *   - FSTWRN001
  *   - FSTSEC001
+ *   - FSTSEC002
  *   - FSTDEP022
  *   - FSTDEP023
  *   - FSTDEP024
@@ -44,6 +45,13 @@ const FSTSEC001 = createWarning({
   unlimited: true
 })
 
+const FSTSEC002 = createWarning({
+  name: 'FastifySecurity',
+  code: 'FSTSEC002',
+  message: 'The headers schema for %s: %s references an external $ref (%s) that is not case-normalized. Header names in the referenced schema keep their original case and will 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.',
+  unlimited: true
+})
+
 const FSTDEP022 = createWarning({
   name: 'FastifyWarning',
   code: 'FSTDEP022',
@@ -77,6 +85,7 @@ module.exports = {
   FSTWRN003,
   FSTWRN004,
   FSTSEC001,
+  FSTSEC002,
   FSTDEP022,
   FSTDEP023,
   FSTDEP024,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify",
-  "version": "5.12.0",
+  "version": "5.12.2",
   "description": "Fast and low overhead web framework, for Node.js",
   "main": "fastify.js",
   "type": "commonjs",