feat: manage bad requests with 'allow request methods' package

Current behaviour: a DDoS can use an unexpected HTTP method to bypass the Fastly cache and cause
interruption to service. For example, making a request to the homepage as a POST rather than a GET.
Express will return a 404 for this error.

Ideal future work: If we can transform this 404 error into a 405 Method Not Allowed, we may be able
to use Signal Sciences to block this kind of attack very quickly. This is because it’s highly
unlikely that a genuine user will accidentally make a POST request.

Definition of done for this ticket: Build and release a package containing an Express middleware
that applications can consume which will cause unexpected request methods to error with a 405 rather
than a 404.

See Also: [CPREL-1276]

Author: CyntiBinti

.release-please-manifest.json

@@ -1,14 +1,15 @@
 {
-  "packages/app-info": "4.0.0",
-  "packages/crash-handler": "5.0.0",
-  "packages/errors": "4.0.0",
-  "packages/eslint-config": "4.0.0",
-  "packages/fetch-error-handler": "1.0.0",
-  "packages/log-error": "5.0.0",
-  "packages/logger": "4.0.0",
-  "packages/middleware-log-errors": "5.0.0",
-  "packages/middleware-render-error-info": "6.0.0",
-  "packages/serialize-error": "4.0.0",
-  "packages/serialize-request": "4.0.0",
-  "packages/opentelemetry": "3.0.0"
+	"packages/app-info": "4.0.0",
+	"packages/crash-handler": "5.0.0",
+	"packages/errors": "4.0.0",
+	"packages/eslint-config": "4.0.0",
+	"packages/fetch-error-handler": "1.0.0",
+	"packages/log-error": "5.0.0",
+	"packages/logger": "4.0.0",
+	"packages/middleware-log-errors": "5.0.0",
+	"packages/middleware-render-error-info": "6.0.0",
+	"packages/serialize-error": "4.0.0",
+	"packages/serialize-request": "4.0.0",
+	"packages/opentelemetry": "3.0.0",
+	"packages/middleware-allow-request-methods": "0.0.0"
 }

README.md

@@ -34,6 +34,9 @@ We maintain documentation in this repo:
     * **[@dotcom-reliability-kit/logger](./packages/logger/#readme):**<br/>
       A simple and fast logger based on [Pino](https://getpino.io/), with FT preferences baked in
 
+    * **[@dotcom-reliability-kit/middleware-allow-request-methods](./packages/middleware-allow-request-methods/README.md):**<br/>
+      Express middleware that returns 405 (rather than 404) for disallowed request methods
+
     * **[@dotcom-reliability-kit/middleware-log-errors](./packages/middleware-log-errors/#readme):**<br/>
       Express middleware to consistently log errors
 

package-lock.json

@@ -0,0 +1,3 @@
+CHANGELOG.md
+docs
+test

packages/middleware-allow-request-methods/.npmignore

@@ -0,0 +1,101 @@
+
+# @dotcom-reliability-kit/middleware-allow-request-methods
+
+Express middleware that returns 405 (rather than 404) for disallowed request methods. This module is part of [FT.com Reliability Kit](https://github.com/Financial-Times/dotcom-reliability-kit#readme).
+
+  * [Usage](#usage)
+    * [Configuration options](#configuration-options)
+      * [`options.allowedMethods`](#optionsallowedmethods)
+      * [`options.message`](#optionsmessage)
+      * [`options.logger`](#optionslogger)
+  * [Migrating](#migrating)
+  * [Contributing](#contributing)
+  * [License](#license)
+
+
+## Usage
+
+Install `@dotcom-reliability-kit/middleware-allow-request-methods` as a dependency:
+
+```bash
+npm install --save @dotcom-reliability-kit/middleware-allow-request-methods
+```
+
+Include in your code:
+
+```js
+import allowRequestMethods from '@dotcom-reliability-kit/middleware-allow-request-methods';
+// or
+const allowRequestMethods = require('@dotcom-reliability-kit/middleware-allow-request-methods');
+```
+
+Example usage:
+
+```js
+const express = require('express');
+const allowRequestMethods = require('@dotcom-reliability-kit/middleware-allow-request-methods');
+
+const app = express();
+
+// Apply the middleware to specific routes, for example:
+app.use('/', allowRequestMethods(['GET'])); // Allow only GET requests on '/'
+app.use('/submit', allowRequestMethods(['POST'])); // Allow only POST requests on '/submit'
+
+// Define your routes
+app.get('/', (req, res) => {
+  res.send('Homepage');
+});
+
+app.post('/submit', (req, res) => {
+  res.send('Form submitted');
+});
+
+app.listen(3000, () => console.log('Server running on port 3000'));
+```
+
+### Configuration options
+
+Config options can be passed into the `allowRequestMethods` function as an object with any of the keys below.
+
+```js
+app.use(allowRequestMethods({
+    // Config options go here
+}));
+```
+
+#### `options.allowedMethods`
+
+An array of HTTP methods that are allowed for the route. This must be an `Array` of `String`s, with each string being an HTTP method. It's important that you do not include methods which are not supported by the route.
+
+This option defaults to `[]`.
+
+#### `options.message`
+
+A string to be used as the response body when a request is made with an unsupported method.
+
+This option defaults to `'Method Not Allowed'`.
+
+#### `options.logger`
+
+A logger object which implements two methods, `error` and `warn`, which have the following permissive signature:
+
+```ts
+type LogMethod = (...logData: any) => any;
+```
+
+This is passed directly onto the relevant log-error method, [see the documentation for that package for more details](../log-error/README.md#optionslogger).
+
+## Migrating
+
+Consult the [Migration Guide](./docs/migration.md) if you're trying to migrate to a later major version of this package.
+
+
+## Contributing
+
+See the [central contributing guide for Reliability Kit](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/docs/contributing.md).
+
+
+## License
+
+Licensed under the [MIT](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/LICENSE) license.<br/>
+Copyright &copy; 2025, The Financial Times Ltd.

packages/middleware-allow-request-methods/README.md

@@ -0,0 +1,112 @@
+const { logRecoverableError } = require('@dotcom-reliability-kit/log-error');
+
+/**
+ * @typedef {object} RequestMethodOptions
+ * @property {string[]} [allowedMethods] The HTTP methods that are allowed i.e. will not throw 405 errors.
+ * @property {string} [message] The error message text to use if a disallowed method is used.
+ * @property {import('@dotcom-reliability-kit/log-error').Logger} [logger] The logger to use for logging errors.
+ */
+
+/**
+ * @typedef {import('express').ErrorRequestHandler} ExpressErrorHandler
+ */
+
+/**
+ * Create a middleware function to return 405 (rather than 404) for disallowed request methods.
+ *
+ * @param {RequestMethodOptions} [options]
+ * @returns {ExpressErrorHandler}
+ */
+function allowRequestMethods(
+	options = { allowedMethods: [], message: 'Method Not Allowed' }
+) {
+	const normalisedAllowedRequestMethods = normaliseAllowedRequestMethods(
+		options.allowedMethods || []
+	);
+
+	return function allowRequestMethodsMiddleware(
+		error,
+		request,
+		response,
+		next
+	) {
+		// If headers are already sent, pass the error to the default Express error handler
+		if (response.headersSent) {
+			return next(error);
+		}
+
+		try {
+			// If the allowed methods array is empty, you can either allow all methods or reject everything
+			if (normalisedAllowedRequestMethods.length === 0) {
+				// TODO: Option 1: Allow all methods (no restriction) i.e. request proceeds as normal
+				return next();
+
+				// TODO: or Option 2: Reject all methods (405 for every request) i.e. block all requests when no methods are explicitly stated
+				// response.header('Allow', normalisedAllowedRequestMethods.join(', '));
+				// response.status(405).send(options.message);
+				// return next(new MethodNotAllowedError(options.message));
+			}
+
+			// If the incoming request method is not in the allowed methods array, then send a 405 error
+			if (
+				!normalisedAllowedRequestMethods.includes(request.method.toUpperCase())
+			) {
+				response.header('Allow', normalisedAllowedRequestMethods.join(', '));
+				response.status(405).send(options.message);
+				return next(new MethodNotAllowedError(options.message));
+			} else {
+				// Else if it is, then pass the request to the next() middleware
+				next();
+			}
+		} catch (/** @type {any} */ error) {
+			if (options.logger) {
+				logRecoverableError({
+					error,
+					logger: options.logger,
+					request
+				});
+			}
+			next(error);
+		}
+	};
+}
+
+/**
+ * Normalise an array of HTTP methods.
+ *
+ * @param {string[]} methods - The HTTP methods to normalise.
+ * @returns {string[]} - Returns an array of capitalised HTTP methods.
+ */
+function normaliseAllowedRequestMethods(methods) {
+	if (!Array.isArray(methods) || methods.length === 0) {
+		return [];
+	}
+	return methods
+		.filter((method) => typeof method === 'string')
+		.map((method) => method.toUpperCase());
+}
+
+/**
+ * Error class for 405 Method Not Allowed errors.
+ *
+ * @augments Error
+ * @property {string} name
+ * @property {number} status
+ * @property {number} statusCode
+ */
+class MethodNotAllowedError extends Error {
+	/**
+	 * @override
+	 * @type {string}
+	 */
+	name = 'MethodNotAllowedError';
+
+	/** @type {number} */
+	status = 405;
+
+	/** @type {number} */
+	statusCode = 405;
+}
+
+module.exports = allowRequestMethods;
+module.exports.default = module.exports;

packages/middleware-allow-request-methods/lib/index.js

@@ -0,0 +1,18 @@
+{
+  "name": "@dotcom-reliability-kit/middleware-allow-request-methods",
+  "version": "0.0.0",
+  "description": "Express middleware that returns 405 (rather than 404) for disallowed request methods",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Financial-Times/dotcom-reliability-kit.git",
+    "directory": "packages/middleware-allow-request-methods"
+  },
+  "homepage": "https://github.com/Financial-Times/dotcom-reliability-kit/tree/main/packages/middleware-allow-request-methods#readme",
+  "bugs": "https://github.com/Financial-Times/dotcom-reliability-kit/issues?q=label:\"package: middleware-allow-request-methods\"",
+  "license": "MIT",
+  "engines": {
+    "node": "20.x || 22.x"
+  },
+  "main": "lib/index.js",
+  "types": "types/index.d.ts"
+}

packages/middleware-allow-request-methods/package.json

@@ -0,0 +1,5 @@
+describe('@dotcom-reliability-kit/middleware-allow-request-methods', () => {
+	it('has some tests', () => {
+		throw new Error('Please write some tests');
+	});
+});

packages/middleware-allow-request-methods/test/unit/lib/index.spec.js

@@ -0,0 +1 @@
+declare module '@dotcom-reliability-kit/middleware-allow-request-methods' {}

packages/middleware-allow-request-methods/types/index.d.ts

@@ -41,6 +41,7 @@
 		"packages/middleware-render-error-info": {},
 		"packages/serialize-error": {},
 		"packages/serialize-request": {},
-		"packages/opentelemetry": {}
+		"packages/opentelemetry": {},
+		"packages/middleware-allow-request-methods": {}
 	}
 }