OWASP ESAPI Encoder for Node.js

Common errors

• ReferenceError: ESAPI is not defined

  cause Attempting to use the `ESAPI` object before it has been properly `require`d or attempting to use it in an ES Module context without conversion.
  fix Ensure `const ESAPI = require('node-esapi');` is at the top of your file. If using ES Modules, consider using a CommonJS-to-ESM wrapper or finding an alternative, actively maintained library.

• TypeError: ESAPI.encoder is not a function

  cause The `ESAPI` object itself is not callable as a function. The `encoder()` method must be called on the main `ESAPI` object to get an encoder instance.
  fix Correct usage is `const encoder = ESAPI.encoder();` then use `encoder.encodeForHTML(...)`.

Warnings

• breaking This package is at version 0.0.1 and has not been updated since approximately 2014. It is not considered stable or production-ready, and its APIs are subject to change without notice if development were to resume.
  Fix: Avoid using this package for production systems. Consider actively maintained security libraries or framework-provided encoding utilities.
• gotcha The OWASP ESAPI project, while historically significant, has evolved. This `node-esapi` port is based on an older version of ESAPI4JS and is no longer maintained. Relying on an unmaintained security library can introduce vulnerabilities rather than prevent them.
  Fix: Modern web security relies on contextual encoding specific to the output destination (e.g., using safe templating engines or framework-provided sanitization). Do not use this package for new development.
• gotcha This package is CommonJS-only (`require`). Attempting to import it using ES Modules syntax (`import ESAPI from 'node-esapi'`) will result in a runtime error because it does not provide an `exports` field or an ES Module entry point.
  Fix: Use `const ESAPI = require('node-esapi');` for all imports.
• gotcha The middleware function `ESAPI.middleware()` is designed for Express.js and serves client-side ESAPI scripts. If not explicitly protected, exposing client-side security scripts via a simple middleware could introduce information disclosure risks or be misused in certain contexts.
  Fix: If using the middleware, ensure its endpoint (`/esapi/*`) is properly secured, rate-limited, and its use case carefully evaluated. Consider if serving static files directly is more appropriate or if these client-side scripts are even necessary.

Install

• npm install node-esapi npm
• yarn add node-esapi yarn
• pnpm add node-esapi pnpm

Imports

• ESAPI
  wrong:

  import ESAPI from 'node-esapi';

  correct:

  const ESAPI = require('node-esapi');

  This package is CommonJS-only and does not support ES Modules syntax like `import`.
• encoder
  wrong:

  const encoder = require('node-esapi').encoder();

  correct:

  const encoder = ESAPI.encoder();

  The `encoder()` function is a method on the main ESAPI object, not a direct export.
• middleware
  wrong:

  app.use(require('node-esapi').middleware());

  correct:

  app.use(ESAPI.middleware());

  The middleware function is designed for Express.js and is a method of the main ESAPI object.

Quickstart

Demonstrates basic usage of the ESAPI encoder to mitigate common injection vulnerabilities by encoding input for different contexts like HTML, JavaScript, and URLs.

const ESAPI = require('node-esapi');

// Get an encoder instance
const encoder = ESAPI.encoder();

// Example of HTML encoding
const userInput = '<script>alert("XSS!")</script>';
const encodedHTML = encoder.encodeForHTML(userInput);
console.log('Encoded for HTML:', encodedHTML);

// Example of JavaScript encoding
const jsInput = "hello' + world";
const encodedJS = encoder.encodeForJS(jsInput);
console.log('Encoded for JavaScript:', encodedJS);

// Example of URL encoding
const urlInput = 'http://example.com?param=value with spaces';
const encodedURL = encoder.encodeForURL(urlInput);
console.log('Encoded for URL:', encodedURL);