Installation

Installing the Node.JS Express Enforcer

The Node.js Express Enforcer is used as a middleware on between the client and your Node.js Express application.

Installation

1. Install the HUMAN Node Express Enforcer NPM package into your Express project.

npm install --save @humansecurity/node-express-enforcer

2. Integrate the HUMAN Enforcer into your Node Express project by setting the it as a middleware in your project.

📘

Middleware Order Matters!

Express applications execute middleware functions in the order they are added to the application. The ideal integration point for the HUMAN Security middleware is after general request processing middleware (e.g., body parsing), but before business logic middleware (e.g., authorization, routing). This way, the HUMAN Security middleware has access to the request data it needs while preventing unnecessary execution of business logic.

Using the Default HUMAN Security Handler

For an out-of-the box handler with the HUMAN Enforcer integrated into it already, simply import and use the createHumanSecurityHandler function.

import express from 'express';
import { createHumanSecurityHandler } from '@humansecurity/node-express-enforcer'

// define HUMAN Security configuration
const config = {
    px_app_id: '<APP_ID>',
    px_auth_token: '<AUTH_TOKEN>',
    px_cookie_secret: '<COOKIE_SECRET>',
    // any other configs...
};

// create Express app and apply parsing middleware
const app = express();
app.use(express.urlencoded());
app.use(express.json());

// use the HUMAN Security handler in the Express app
app.use(createHumanSecurityHandler(config));
// ...

Creating a Customized Handler

For a more customized solution, construct a new HumanSecurityEnforcer instance and use it in your custom middleware function.

The recommended usage is to:

• create the enforcer, call the enforce() function, and return any resulting response as early as possible in the request flow to minimize invocation of unnecessary logic.
• call the postEnforce() after returning the response to the client to ensure any HUMAN data is sent to the collector.

As an example, the code below shows what the createHumanSecurityHandler() function does behind the scenes.

import express from 'express';
import { HumanSecurityEnforcer } from '@humansecurity/node-express-enforcer';

// define HUMAN Security configuration
const config = {
    px_app_id: '<APP_ID>',
    px_auth_token: '<AUTH_TOKEN>',
    px_cookie_secret: '<COOKIE_SECRET>',
    // any other configs...
};

// create enforcer with HUMAN Security configuration
const enforcer = new HumanSecurityEnforcer(config);

// define custom middleware
const customMiddleware = (req, res, next) => {
    // await enforcement
    const enforcerResponse = await enforcer.enforce(request, response);

    // return enforcer response (first party or block) if it exists
    if (enforcerResponse) {
        return enforcerResponse;
    }

    // call the post enorcer after the response is returned to the client
    response.on('finish', async () => {
        await enforcer.postEnforce(request, response);
    });

    // pass the request to the next middleware
    next();
};

// create Express app and apply parsing middleware
const app = express();
app.use(express.urlencoded());
app.use(express.json());

// use the custom middleware in your Express application
app.use(customMiddleware);
// ...

📘

Note

In the examples above, the HUMAN Security enforcement handler function was passed into the app.use() function as the only argument. This is because we want to apply the HUMAN Security enforcement middleware to all routes and all HTTP methods in the application. This allows for comprehensive protection of your application and ensures that First Party functionality works properly.

While it is possible to apply the handler function to a subset of routes or methods, it is recommend to apply the handler function to all routes and methods, and specify which requests should be filtered (i.e., not enforced) using the HumanSecurityConfiguration. Filtering can be done based on route, HTTP method, file extension, and more.

3. Build, test, and deploy the Node Express application.