Upgrading to Version 8

Upgrade Process

Updating the Configuration

If you're upgrading from version 7.x or below of the Node Express, many of the configuration fields have remained the same.

The following configuration fields have been modified:

• px_additional_activity_handler has been changed. The function signature has been modified from (pxCtx, config) => void to (config, context, request) => Promise<void> | void.
• px_enrich_custom_parameters has been changed. The function signature has been modified from (customParams, request) => CustomParameters to (config, request) => Promise<CustomParameters>.
• px_cors_custom_preflight_handler has been changed. The function signature has been modified from (request) => Response to (request) => Promise<{ body: string, headers: Record<string, string[]>, status: number }>.
• The function px_cors_create_custom_block_response_headers has been changed. The function signature modified from (request) => Promise<Record<string, string>> to (request) => Promise<Record<string, string[]>>.

The following configuration fields have been removed:

• px_custom_request_handler
• px_extract_user_ip
• px_send_async_activities_enabled
• px_dynamic_configuration_enabled
• px_cd_first_party_enabled
• px_testing_mode_enabled
• px_custom_template_root
• px_pxhd_secure_enabled
• px_proxy_url
• px_modify_context

Updating the Node Express Enforcer Integration

In prior versions of the Node Express Enforcer:

• the module was imported from the perimeterx-node-express package
• the middleware function was initialized by calling perimeterx.init()
• the middleware function was accessible via the perimeterx.middleware property

See the code sample below for the v7.x integration.

import express from 'express';
// the entire module is imported
import perimeterx from 'perimeterx-node-express';

const config = {
    px_app_id: 'PX_APP_ID',
    px_cookie_secret: 'PX_COOKIE_SECRET',
    px_auth_token: 'PX_AUTH_TOKEN'
};

// middleware function is initialized without a return value
perimeterx.init(config);

const app = express();
app.use(express.urlencoded());
app.use(express.json());

// middleware function is accessed (via perimeterx.middleware)
app.use(perimeterx.middleware);

app.get('/helloWorld', (req, res) => {
    res.send('Hello from PX');
});

app.listen(8081, () => {
    console.log('server started');
});

While the same basic principles of importing, initializing, and accessing the middleware still hold true in the new version of the enforcer, they are done in a slightly different way.

• The module is imported via the @humansecurity/node-express-enforcer package. Note that the perimeterx-node-express package is considered deprecated.
• The middleware function is initialized by calling createHumanSecurityHandler()
• The middleware function is accessible via the return value of createHumanSecurityHandler()

import express from 'express';
// the middleware creation function is imported from the module
import { createHumanSecurityHandler } from '@humansecurity/node-express-enforcer'

const config = {
    px_app_id: '<APP_ID>',
    px_auth_token: '<AUTH_TOKEN>',
    px_cookie_secret: '<COOKIE_SECRET>'
};

// the middleware is initialized and returned
const humanSecurityMiddleware = createHumanSecurityHandler(config);

const app = express();
app.use(express.urlencoded());
app.use(express.json());

// the middleware is accessed (via the previously defined constant)
app.use(humanSecurityMiddleware);

app.get('/helloWorld', (req, res) => {
    res.send('Hello from HUMAN Security');
});

app.listen(8081, () => {
    console.log('server started');
});