Registry / auth-security / simple-hmac-auth-express

simple-hmac-auth-express

JSON →
library1.3.0jsnpmunverified

This package, `simple-hmac-auth-express`, provides an Express middleware designed for implementing HMAC-based authentication in API endpoints. It acts as a wrapper around the `simple-hmac-auth` core library, integrating its authentication logic seamlessly into the Express request-response cycle. The current stable version is v1.3.0, released in August 2022. Releases appear to be event-driven, primarily driven by updates to its core dependency or maintenance tasks. A key differentiator is its ability to handle request body parsing internally, which is crucial for HMAC signature verification that often requires access to the raw request body before other middleware might consume it. It requires `secretForKey` (a function returning a Promise for the secret) and `onRejected` handlers for failed authentication.

npm install simple-hmac-auth-express
INSTALL
IMPORT
SIG · SIMPLE-HMAC-AUTH-E
S
simple-hmac-auth-express
auth-securityjavascriptv1.3.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

auth
import auth from 'simple-hmac-auth-express';
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.

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'); });
Debug
Known issues
breakingThe `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'; }`
affects: >=1.3.0
breakingVersion 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.
affects: >=1.3.0
gotchaThis 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.
affects: >=1.0.0
gotchaThe `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.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: secretForKey must be a function that returns a promise
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.
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
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.
Upgrade
Version history
1.3.0latest on npm
Audit
Dependencies
simple-hmac-authrequiredProvides the core HMAC authentication logic and protocol specification.
expressrequiredRuntime peer dependency as this is an Express middleware.
Agent activity
16 hits · last 30 days
node
12
OpenAI (training)
3
Resources