EscherJS

4.0.2 verified Sat Apr 25 auth: no javascript

EscherJS is a JavaScript implementation of the Escher HTTP request signing algorithm, based on Amazon's AWS Signature Version 4 but generalized and extended. Version 4.0.2 (stable, released 2023) supports Node >=16 and is ESM-only. It provides both client and server-side signing and validation of HTTP requests. Key differentiators: it's the reference JS library for the Escher auth protocol, used in production by multiple companies. The library has a history of breaking changes (v2, v3, v4) with updated minimum Node versions and URL encoding fixes.

Common errors

error const Escher = require('escher-auth'); TypeError: Escher is not a constructor ↓

cause ESM-only module, require returns module namespace object.

fix

Use import { Escher } from 'escher-auth' or const { Escher } = await import('escher-auth').

error Error: Cannot find module 'escher-auth' ↓

cause Package not installed or wrong import path.

fix

Run npm install escher-auth and ensure correct import.

error Escher: algorithm must be one of SHA256, SHA512 ↓

cause Invalid algo parameter passed to constructor.

fix

Set algo to 'SHA256' or 'SHA512'.

error Escher: credentialScope must be in format 'region/service' ↓

cause credentialScope missing or malformed.

fix

Provide credentialScope as string like 'us-east-1/api'.

Warnings

breaking Version 4.0.0 is ESM-only, no CommonJS support. ↓

fix Use import syntax or dynamic import in CJS projects.

breaking Version 2.0.0 properly escapes round parentheses in URLs. ↓

fix Upgrade to v2+ or manually encode parentheses in request URLs.

breaking Version 1.0.0 drops Node 0.x support and fixes date handling (date calculated at sign/validate time, not instantiation). ↓

fix Upgrade to v1+ and ensure Node >=6.14.4.

breaking Minimum Node version was raised to 16 in v4.0.0. ↓

fix Use Node >=16 or stick with v3 (supports older Node).

gotcha The default export changed; previously could be required as a function. ↓

fix Use named import { Escher } from 'escher-auth'.

Install

npm install escher-auth

yarn add escher-auth

pnpm add escher-auth

Imports

Escher

wrong

const Escher = require('escher-auth')

correct

import { Escher } from 'escher-auth'

ESM-only since v4. Use dynamic import if needed in CJS.

Escher

const { Escher } = await import('escher-auth')

For CJS projects, use dynamic import.

AuthError

wrong

import AuthError from 'escher-auth'

correct

import { AuthError } from 'escher-auth'

AuthError is a named export, not default.

createEscher

wrong

import createEscher from 'escher-auth'

correct

import { createEscher } from 'escher-auth'

Factory function, named export.

Quickstart

Shows how to create an Escher instance, sign a request, and validate it.

import { Escher } from 'escher-auth';

const escher = new Escher({
  algo: 'SHA256',
  credentialScope: 'us-east-1/api',
  accessKeyId: 'your-access-key',
  apiSecret: 'your-secret-key'
});

// Sign a request
const request = {
  method: 'POST',
  url: 'https://api.example.com/data',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ key: 'value' })
};

const signedRequest = escher.signRequest(request);
console.log(signedRequest.headers['X-Escher-Auth']);

// Validate a request
const isValid = escher.validateRequest(signedRequest);
console.log('Valid:', isValid);