Installation

Prerequisites

The HUMAN Edgio Enforcer uses Node.js and Edgio's Edge Functions. See the prerequesites for using Edge Functions here.

Note: The Enforcer is supported for Edgio Core v7.x and Node.js 16.x.

Installation

0. Create an Edgio property and router (if you haven't already) by following the instructions here.

1. Install the HUMAN Enforcer NPM package into your Edgio project.

npm i --save @humansecurity/edgio-edge-function-enforcer

2. Modify the edgio.config.js file to include the following four origins, replacing <PX_APP_ID> with your application ID (e.g., PX12345678). For more information on the Edgio configuration file, see here.

module.exports = {
    name: 'example-edgio-site-name',
    // ...
    origins: [
        // after including your origins...
        {
            name: 'hs-sapi-origin',
            override_host_header: 'sapi-<PX_APP_ID>.perimeterx.net',
            hosts: [{ location: 'sapi-<PX_APP_ID>.perimeterx.net' }],
        },
        {
            name: 'hs-collector-origin',
            override_host_header: 'collector-<PX_APP_ID>.perimeterx.net',
            hosts: [{ location: 'collector-<PX_APP_ID>.perimeterx.net' }],
        },
        {
            name: 'hs-client-origin',
            override_host_header: 'client.perimeterx.net',
            hosts: [{ location: 'client.perimeterx.net' }],
        },
        {
            name: 'hs-captcha-origin',
            override_host_header: 'captcha.px-cdn.net',
            hosts: [{ location: 'captcha.px-cdn.net' }],
        },
    ],
};

3. Integrate the HUMAN Enforcer into your Edge Function's main file.

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

import { createEnforcedRequestHandler } from '@humansecurity/edgio-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...
};

// define what to do when requests pass HUMAN enforcement
const onPass = (request) => {
    console.log('handling HUMAN-validated request')
    return fetch(request.url, { edgio: { origin: '<ORIGIN_NAME>' } });
};

// define what to do for block responses (optional)
const onResponse = (response) => {
    console.log('handling response from HUMAN enforcer');
    return response;
};

// create and export request handler
export const handleHttpRequest = createEnforcedRequestHandler(config, onPass, onResponse);

The example below shows what the createEnforcedRequestHandler() function does behind the scenes. For a more customized solution, construct a new HumanSecurity instance, create an enforcer, and use it in the handleHttpRequest function.

The recommended usage is to:

• create the HUMAN 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() right before returning the response from the request handler to ensure any necessary response modifications are performed and HUMAN data is sent to the collector.

import { HumanSecurity } from '@humansecurity/edgio-edge-function-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...
};

export async function handleHttpRequest(request, context) {
    // create enforcer with configuration params
    const enforcer = new HumanSecurity(config).createEnforcer();
    
    // await enforcement
    let response = await enforcer.enforce(request, context);
    
    // return enforcer response (first party or block) if it exists
    if (response) {
        // if any block response modifications are needed, perform them here
        return response;
    }

    // perform logic to fetch desired response, for example:
    response = await fetch(request.url, { edgio: { origin: '<ORIGIN_NAME>' } });
    
    // await any necessary post-processing
    await enforcer.postEnforce(response);
    
    // return response
    return response;
}

4. Use the Edgio CLI to test your edge function locally and deploy the Edgio property.

# test locally
edgio dev

# deploy to edgio
edgio deploy