koa-escher-auth is a Koa middleware designed to integrate Escher authentication into Node.js applications. It restricts access to routes by verifying incoming HTTP requests using Escher signatures and a configurable key pool. The package is currently stable at version 4.0.0, released in January 2023, with updates occurring on an irregular basis, typically for dependency upgrades or minor feature enhancements. Key differentiators include its tight integration with the Koa framework and its reliance on the `escher-keypool` for managing authentication credentials, ensuring secure, signed request processing. It is explicitly designed to work downstream of a body-parser middleware to correctly process request bodies for authentication. Escher itself is a stateless API authentication protocol based on AWS Signature Version 4.
npm install koa-escher-authVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to set up a Koa application with Escher authentication, including the necessary body parser middleware and how to access the authenticated user's access key ID from the Koa context.
Review your logging configurations and ensure compatibility with `@emartech/json-logger` if you were previously relying on `logentries-logformat` output. No direct changes to `koa-escher-auth` integration are typically needed, but downstream logging consumers might be affected.
Ensure `app.use(bodyParser());` is called *before* `app.use(escherAuth.authenticator(escherConfig));` in your Koa application setup.
Always use `JSON.stringify()` when defining the `keyPool` object in your configuration. If using environment variables, ensure the variable's value is a properly escaped JSON string.
Ensure your project's Node.js environment adheres to the specified engine requirements (`>=10.13.0 <19`). Consider using a Node Version Manager (NVM) to manage different Node.js versions.
Upgrade to version 3.4.0 or newer to ensure correct handling of empty POST requests and robust body validation based on `request.body`.
Ensure `app.use(bodyParser())` is placed before `app.use(escherAuth.authenticator())` in your Koa middleware chain.
Verify that your `escherConfig.keyPool` (or `SUITE_ESCHER_KEY_POOL` environment variable) contains a valid JSON string, using `JSON.stringify()` if constructing it from an object.
Double-check that the `credentialScope`, `keyId`, and `secret` in your `escherConfig` on the server match the client-side configuration. Ensure server and client clocks are synchronized. Validate that the client is signing the request body and headers exactly as expected by the server.