Koa Escher Authentication Middleware

Common errors

• TypeError: Cannot read properties of undefined (reading 'rawBody')

  cause The `koa-bodyparser` middleware was not applied or was applied after `koa-escher-auth.authenticator`.
  fix Ensure `app.use(bodyParser())` is placed before `app.use(escherAuth.authenticator())` in your Koa middleware chain.

• Error: Invalid Escher key pool

  cause The `keyPool` configuration provided to the authenticator is not a valid JSON string or is malformed.
  fix 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.

• Authentication Failed: Signature mismatch

  cause The Escher signature generated by the client does not match the signature computed by the server. This is commonly caused by incorrect `credentialScope`, `keyId`, `secret`, client-server clock skew, or discrepancies in how the request is signed (e.g., included headers, body content).
  fix 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.

Warnings

• breaking Version 4.0.0 introduced a breaking change where its internal dependency, `escher-keypool`, now uses `@emartech/json-logger` instead of `logentries-logformat` for logging. This change may require adjustments if your logging infrastructure or tests directly interacted with or expected the format of the previous logger.
  Fix: 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.
• gotcha The `koa-escher-auth` middleware *must* be used downstream of a body-parser middleware (e.g., `koa-bodyparser`) that defines `request.rawBody`. Incorrect ordering will lead to authentication failures, especially for requests with bodies.
  Fix: Ensure `app.use(bodyParser());` is called *before* `app.use(escherAuth.authenticator(escherConfig));` in your Koa application setup.
• gotcha The `keyPool` configuration parameter (whether passed directly or via environment variable `SUITE_ESCHER_KEY_POOL`) must always be a valid JSON *string*. Providing an object directly or an invalid JSON string will result in configuration errors.
  Fix: 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.
• gotcha Node.js engine support was updated in v3.5.0 to `Node.js >=10.13.0 <19`. Using the package with Node.js versions outside this range (e.g., Node.js 19+) may lead to unexpected behavior or runtime errors due to dependency incompatibilities or changes in Node.js APIs.
  Fix: 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.
• gotcha Prior to version 3.4.0, handling of empty POST requests and body validation was based on `request.rawBody`. This could cause issues with certain request types or body parser configurations. Version 3.4.0 updated this to validate the body based on `request.body`.
  Fix: Upgrade to version 3.4.0 or newer to ensure correct handling of empty POST requests and robust body validation based on `request.body`.

Install

• npm install koa-escher-auth npm
• yarn add koa-escher-auth yarn
• pnpm add koa-escher-auth pnpm

Imports

• authenticator
  wrong:

  const escherAuth = require('koa-escher-auth'); app.use(escherAuth);

  correct:

  import { authenticator } from 'koa-escher-auth';

  The primary export is a function `authenticator` which expects configuration. Direct `app.use(escherAuth)` would not work as `escherAuth` itself is the module, not the middleware function. The `require` pattern is common in older Koa apps, but ESM is preferred in modern Node.js environments.
• authenticator
  wrong:

  import escherAuth from 'koa-escher-auth';

  correct:

  const escherAuth = require('koa-escher-auth'); app.use(escherAuth.authenticator(escherConfig));

  The module exports an object with a named export `authenticator`, not a default export. The CommonJS `require` syntax as shown in the README is the most robust import pattern for this library's typical usage.
• ctx.escherAccessKeyId

  app.use(function(ctx) { console.log(ctx.escherAccessKeyId); });

  After successful authentication, the access key ID used for the request is attached to the Koa context for downstream middleware access. This is a property on the context object, not a direct import.

Quickstart

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.

import Koa from 'koa';
import bodyParser from 'koa-bodyparser';
import { authenticator } from 'koa-escher-auth';

// Load Escher configuration from environment variables or provide directly
const escherConfig = {
  credentialScope: process.env.SUITE_ESCHER_CREDENTIAL_SCOPE ?? 'eu/app-id/ems_request',
  keyPool: process.env.SUITE_ESCHER_KEY_POOL ?? JSON.stringify([
    { 'keyId': 'app-id_suite_v1', 'secret': 'app-id-secret', 'acceptOnly': 0 }
  ])
};

const app = new Koa();

// IMPORTANT: koa-bodyparser must be used before koa-escher-auth
app.use(bodyParser());

// Apply the Escher authenticator middleware
app.use(authenticator(escherConfig));

// Define a protected route handler
app.use(async (ctx) => {
  // If authentication passes, the access key ID is available on ctx.escherAccessKeyId
  ctx.body = `Hello world, ${ctx.escherAccessKeyId}! Request authenticated successfully.`;
});

const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Server listening on http://localhost:${port}`);
});