aws4-express is an Express middleware library designed for validating AWS Signature Version 4 (SigV4) authenticated requests. It enables Express applications to act as SigV4-secured endpoints, mimicking AWS service behavior without requiring an actual AWS backend for authentication. The current stable version is 0.14.1, and the project demonstrates an active release cadence, frequently updating to support newer Node.js versions (currently >=20) and incorporating security enhancements. Its primary function is to abstract the complexities of SigV4 verification, providing an `awsVerify` middleware that integrates with Express's request lifecycle, notably requiring careful handling of the raw request body for accurate signature calculation. It is actively maintained with regular updates and security audits.
npm install aws4-expressVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to set up `aws4-express` middleware on an Express server to protect a route with AWS Signature V4, including a client-side example using `aws4` to sign and send a request. It highlights the crucial raw body parsing requirement and dynamic secret key lookup.
Upgrade your Node.js runtime to version 20 or later. For example, using `nvm install 20 && nvm use 20`.
Configure your Express body parser middleware with `verify: rawBodyFromVerify`. Example: `app.use(express.json({ verify: rawBodyFromVerify }));`Consult the `CHANGELOG.md` or GitHub release notes for specific breaking changes when upgrading minor versions. Pin exact versions for production use.
Upgrade to `v0.14.1` or newer to ensure correct package entrypoint resolution, especially in CommonJS environments.
Consult the `v0.4.0` release notes and examples for updated configuration parameter usage. This is mostly relevant for very early adopters.
Verify the `secretKey` callback is returning the correct secret for the `accessKey`. Ensure no middleware modifies the request body before `awsVerify` runs, and that `rawBodyFromVerify` is correctly used. Debug the client-side signing process to match server expectations.
If using `express.json()`, `express.raw()`, or `express.urlencoded()`, ensure you pass `{ verify: rawBodyFromVerify }` to its configuration. For custom body parsing, ensure `req.rawBody` is manually populated with the exact raw request payload.Switch to ES Module `import` syntax (`import { awsVerify } from 'aws4-express';`) and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`). If strictly using CommonJS, ensure you are on `v0.14.1` or later, which should have improved CJS compatibility due to the entrypoint fix.