Simple HMAC Authentication Express Middleware

Common errors

• TypeError: secretForKey must be a function that returns a promise

  cause The `secretForKey` function was implemented using a Node.js-style callback instead of returning a Promise, which is required since v1.3.0.
  fix Refactor `secretForKey` to be an `async` function that returns the secret directly or a `Promise.resolve(secret)`. Example: `secretForKey: async (apiKey) => { /* ... */ return 'mysecret'; }`.

• Error: Can't set headers after they are sent to the client.

  cause The `onRejected` handler or another middleware tried to send a response or modify headers after `simple-hmac-auth-express` (or another middleware) had already finalized the response. This often happens if `onRejected` doesn't explicitly send a response or call `next(error)`.
  fix Verify that your `onRejected` function explicitly sends a response (e.g., `response.status(401).json(...)`) or calls `next(error)` to propagate the error. Also, check for other middleware inadvertently sending responses.

• Signature mismatch error / 401 Unauthorized for valid requests

  cause This typically indicates that the HMAC signature calculated by the client does not match the one calculated by the server. Common causes include: incorrect `secretForKey` implementation, differences in how the request body is parsed/hashed, incorrect headers included in the signature, or clock skew between client and server.
  fix Double-check the `secretForKey` implementation to ensure it returns the correct secret. Verify that client and server are hashing the *exact* same request components (method, path, headers, raw body). Ensure consistent body parsing, especially if the `body` option is used. Check for significant time differences between client and server.

Warnings

• breaking The `secretForKey` callback signature changed from a Node.js-style `(apiKey, callback)` to an `async (apiKey)` function that returns a Promise. Direct callback usage will no longer work and must be migrated to a Promise-returning asynchronous function.
  Fix: Update your `secretForKey` implementation to be an `async` function that directly `return`s the secret (or `null`/`undefined`) or a Promise that resolves with it, rather than using a callback. Example: `secretForKey: async (apiKey) => { /* ... */ return 'SECRET'; }`
• breaking Version 1.3.0 of `simple-hmac-auth-express` bumps its core dependency `simple-hmac-auth` to v4.0.0. Any breaking changes introduced in `simple-hmac-auth` v4.0.0 will implicitly affect users of `simple-hmac-auth-express` v1.3.0 and later. Developers should consult the `simple-hmac-auth` changelog for further details.
  Fix: Review the changelog for `simple-hmac-auth` v4.0.0 for any specific breaking changes that might impact your HMAC signature generation or verification logic. Adjust client-side or server-side implementations as necessary.
• gotcha This middleware includes its own body parsing capabilities. If you use other body parsing middleware (like `express.json()` or `body-parser`) before `simple-hmac-auth-express`, the request body may already be consumed, leading to signature verification failures as the raw body required for HMAC calculation will be unavailable.
  Fix: Ensure `simple-hmac-auth-express` middleware is placed *before* any other body parsing middleware in your Express application chain. If you need custom body parsing, configure it via the `body` option within the `simple-hmac-auth-express` middleware configuration.
• gotcha The `onRejected` handler is crucial for responding to unauthenticated requests. If it does not explicitly terminate the request-response cycle (e.g., by sending a response or calling `next(error)` for an error handler), the request may hang or proceed unexpectedly, potentially causing 'Can't set headers after they are sent' errors.
  Fix: Always ensure your `onRejected` function sends a response (e.g., `res.status(401).json(...)`) or passes an error to the next middleware (`next(error)`) to properly terminate or handle the request. Do not leave the response open.

Install

• npm install simple-hmac-auth-express npm
• yarn add simple-hmac-auth-express yarn
• pnpm add simple-hmac-auth-express pnpm

Imports

• auth
  wrong:

  import { auth } from 'simple-hmac-auth-express';

  correct:

  import auth from 'simple-hmac-auth-express';

  The package exports the middleware factory function as its default export. For TypeScript projects, this is the preferred ESM import.
• auth

  const auth = require('simple-hmac-auth-express');

  CommonJS `require` syntax for Node.js environments. The exported value is a function that, when called with options, returns the Express middleware.
• HmacAuthMiddlewareOptions

  import type { HmacAuthMiddlewareOptions } from 'simple-hmac-auth-express';

  Imports the TypeScript type definition for the middleware's configuration options.

Quickstart

This quickstart demonstrates how to set up `simple-hmac-auth-express` middleware in an Express application. It shows the basic configuration with `secretForKey` and `onRejected` functions, including optional body parsing settings. It provides an example of a protected route and how to access authenticated requests.

import express from 'express';
import auth from 'simple-hmac-auth-express';

const app = express();

app.use(auth({
  // Required: Return a promise that resolves with the secret for the specified API key.
  // This function is async since v1.3.0 and core library v4.0.0.
  secretForKey: async (apiKey) => {
    // In a real application, you would fetch the secret from a database or secure store
    // based on the provided apiKey. For example purposes, we return a hardcoded secret.
    if (apiKey === 'MY_API_KEY') {
      return process.env.HMAC_SECRET_KEY ?? 'my-super-secret-key';
    }
    return null; // API key not found
  },

  // Required: Handle requests that have failed authentication.
  onRejected: (error, request, response, next) => {
    console.error(`Authentication failed for "${request.apiKey}": ${error.message} on ${request.method} ${request.url}`);
    response.status(401).json({
      error: {
        message: error.message || 'Authentication Failed'
      }
    });
  },
  
  // Optional: Handle requests that have passed authentication.
  onAccepted: (request, response) => {
    console.log(`"${request.apiKey}" authenticated request to ${request.method} ${request.url}`);
  },

  // Optional: Body-parser options. The middleware parses the body itself for signature verification.
  // It should be placed before other body parsing middleware.
  body: {
    json: { strict: false, limit: '1mb' },
    urlencoded: { extended: true, limit: '5mb' },
    text: { type: 'application/octet-stream' }
  }
}));

app.get('/protected', (req, res) => {
  res.send(`Hello, authenticated user with API Key: ${req.apiKey}!`);
});

app.post('/protected-data', (req, res) => {
  // Access parsed body if configured in 'body' options
  res.json({ message: 'Data received and authenticated!', data: req.body });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
  console.log('Use MY_API_KEY and hmac signature for /protected and /protected-data');
});