Installation

Prerequisites

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

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

Installation

Cookie V2

The Edgio Edge Function Enforcer uses Bot Defender Cookie V2. If you are unable to validate this by navigating to Bot Defender > Product Settings > Security Policy > Risk Cookie Key (Advanced Settings), please reach out to our support team.

Create an Edgio property and router (if you haven’t already) by following the instructions here.
Install the HUMAN Enforcer NPM package into your Edgio project.

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

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.

1 module.exports = {
2     name: 'example-edgio-site-name',
3     // ...
4     origins: [
5         // after including your origins...
6         {
7             name: 'hs-sapi-origin',
8             override_host_header: 'sapi-<PX_APP_ID>.perimeterx.net',
9             hosts: [{ location: 'sapi-<PX_APP_ID>.perimeterx.net' }],
10         },
11         {
12             name: 'hs-collector-origin',
13             override_host_header: 'collector-<PX_APP_ID>.perimeterx.net',
14             hosts: [{ location: 'collector-<PX_APP_ID>.perimeterx.net' }],
15         },
16         {
17             name: 'hs-client-origin',
18             override_host_header: 'client.perimeterx.net',
19             hosts: [{ location: 'client.perimeterx.net' }],
20         },
21         {
22             name: 'hs-captcha-origin',
23             override_host_header: 'captcha.px-cdn.net',
24             hosts: [{ location: 'captcha.px-cdn.net' }],
25         },
26     ],
27 };

Origin Names

The default names of these origins are hs-sapi-origin, hs-collector-origin, hs-client-origin, and hs-captcha-origin. If the default hs-*-origin origin names are changed, the new origin names must be explicitly indicated in the Enforcer configuration using the px_backend_origin_name, px_backend_collector_origin_name, px_backend_client_origin_name, and px_backend_captcha_origin_name configurations, respectively.

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.

1 import { createEnforcedRequestHandler } from '@humansecurity/edgio-enforcer';
2 
3 // define human security configuration
4 const config = {
5     px_app_id: '<APP_ID>',
6     px_auth_token: '<AUTH_TOKEN>',
7     px_cookie_secret: '<COOKIE_SECRET>',
8     // any other configs...
9 };
10 
11 // define what to do when requests pass HUMAN enforcement
12 const onPass = (request) => {
13     console.log('handling HUMAN-validated request')
14     return fetch(request.url, { edgio: { origin: '<ORIGIN_NAME>' } });
15 };
16 
17 // define what to do for block responses (optional)
18 const onResponse = (response) => {
19     console.log('handling response from HUMAN enforcer');
20     return response;
21 };
22 
23 // create and export request handler
24 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.

1 import { HumanSecurity } from '@humansecurity/edgio-edge-function-enforcer';
2 
3 // define human security configuration
4 const config = {
5     px_app_id: '<APP_ID>',
6     px_auth_token: '<AUTH_TOKEN>',
7     px_cookie_secret: '<COOKIE_SECRET>',
8     // any other configs...
9 };
10 
11 export async function handleHttpRequest(request, context) {
12     // create enforcer with configuration params
13     const enforcer = new HumanSecurity(config).createEnforcer();
14 
15     // await enforcement
16     let response = await enforcer.enforce(request, context);
17 
18     // return enforcer response (first party or block) if it exists
19     if (response) {
20         // if any block response modifications are needed, perform them here
21         return response;
22     }
23 
24     // perform logic to fetch desired response, for example:
25     response = await fetch(request.url, { edgio: { origin: '<ORIGIN_NAME>' } });
26 
27     // await any necessary post-processing
28     await enforcer.postEnforce(response);
29 
30     // return response
31     return response;
32 }

Using Fetch

See here for details on how to use Edgio’s built-in fetch function to make requests to your origin server.

Edge Function Limitations

Be aware of Edgio’s Edge Function limitations when developing your edge function!

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

$ # test locally
$ edgio dev
$ 
$ # deploy to edgio
$ edgio deploy

Prerequisites

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

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

Installation

Cookie V2

Create an Edgio property and router (if you haven’t already) by following the instructions here.
Install the HUMAN Enforcer NPM package into your Edgio project.

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

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.

1 module.exports = {
2     name: 'example-edgio-site-name',
3     // ...
4     origins: [
5         // after including your origins...
6         {
7             name: 'hs-sapi-origin',
8             override_host_header: 'sapi-<PX_APP_ID>.perimeterx.net',
9             hosts: [{ location: 'sapi-<PX_APP_ID>.perimeterx.net' }],
10         },
11         {
12             name: 'hs-collector-origin',
13             override_host_header: 'collector-<PX_APP_ID>.perimeterx.net',
14             hosts: [{ location: 'collector-<PX_APP_ID>.perimeterx.net' }],
15         },
16         {
17             name: 'hs-client-origin',
18             override_host_header: 'client.perimeterx.net',
19             hosts: [{ location: 'client.perimeterx.net' }],
20         },
21         {
22             name: 'hs-captcha-origin',
23             override_host_header: 'captcha.px-cdn.net',
24             hosts: [{ location: 'captcha.px-cdn.net' }],
25         },
26     ],
27 };

Origin Names

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.

1 import { createEnforcedRequestHandler } from '@humansecurity/edgio-enforcer';
2 
3 // define human security configuration
4 const config = {
5     px_app_id: '<APP_ID>',
6     px_auth_token: '<AUTH_TOKEN>',
7     px_cookie_secret: '<COOKIE_SECRET>',
8     // any other configs...
9 };
10 
11 // define what to do when requests pass HUMAN enforcement
12 const onPass = (request) => {
13     console.log('handling HUMAN-validated request')
14     return fetch(request.url, { edgio: { origin: '<ORIGIN_NAME>' } });
15 };
16 
17 // define what to do for block responses (optional)
18 const onResponse = (response) => {
19     console.log('handling response from HUMAN enforcer');
20     return response;
21 };
22 
23 // create and export request handler
24 export const handleHttpRequest = createEnforcedRequestHandler(config, onPass, onResponse);

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.

1 import { HumanSecurity } from '@humansecurity/edgio-edge-function-enforcer';
2 
3 // define human security configuration
4 const config = {
5     px_app_id: '<APP_ID>',
6     px_auth_token: '<AUTH_TOKEN>',
7     px_cookie_secret: '<COOKIE_SECRET>',
8     // any other configs...
9 };
10 
11 export async function handleHttpRequest(request, context) {
12     // create enforcer with configuration params
13     const enforcer = new HumanSecurity(config).createEnforcer();
14 
15     // await enforcement
16     let response = await enforcer.enforce(request, context);
17 
18     // return enforcer response (first party or block) if it exists
19     if (response) {
20         // if any block response modifications are needed, perform them here
21         return response;
22     }
23 
24     // perform logic to fetch desired response, for example:
25     response = await fetch(request.url, { edgio: { origin: '<ORIGIN_NAME>' } });
26 
27     // await any necessary post-processing
28     await enforcer.postEnforce(response);
29 
30     // return response
31     return response;
32 }

Using Fetch

See here for details on how to use Edgio’s built-in fetch function to make requests to your origin server.

Edge Function Limitations

Be aware of Edgio’s Edge Function limitations when developing your edge function!

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

$ # test locally
$ edgio dev
$ 
$ # deploy to edgio
$ edgio deploy

1	module.exports = {
2	name: 'example-edgio-site-name',
3	// ...
4	origins: [
5	// after including your origins...
6	{
7	name: 'hs-sapi-origin',
8	override_host_header: 'sapi-<PX_APP_ID>.perimeterx.net',
9	hosts: [{ location: 'sapi-<PX_APP_ID>.perimeterx.net' }],
10	},
11	{
12	name: 'hs-collector-origin',
13	override_host_header: 'collector-<PX_APP_ID>.perimeterx.net',
14	hosts: [{ location: 'collector-<PX_APP_ID>.perimeterx.net' }],
15	},
16	{
17	name: 'hs-client-origin',
18	override_host_header: 'client.perimeterx.net',
19	hosts: [{ location: 'client.perimeterx.net' }],
20	},
21	{
22	name: 'hs-captcha-origin',
23	override_host_header: 'captcha.px-cdn.net',
24	hosts: [{ location: 'captcha.px-cdn.net' }],
25	},
26	],
27	};

1	import { createEnforcedRequestHandler } from '@humansecurity/edgio-enforcer';
2
3	// define human security configuration
4	const config = {
5	px_app_id: '<APP_ID>',
6	px_auth_token: '<AUTH_TOKEN>',
7	px_cookie_secret: '<COOKIE_SECRET>',
8	// any other configs...
9	};
10
11	// define what to do when requests pass HUMAN enforcement
12	const onPass = (request) => {
13	console.log('handling HUMAN-validated request')
14	return fetch(request.url, { edgio: { origin: '<ORIGIN_NAME>' } });
15	};
16
17	// define what to do for block responses (optional)
18	const onResponse = (response) => {
19	console.log('handling response from HUMAN enforcer');
20	return response;
21	};
22
23	// create and export request handler
24	export const handleHttpRequest = createEnforcedRequestHandler(config, onPass, onResponse);

1	import { HumanSecurity } from '@humansecurity/edgio-edge-function-enforcer';
2
3	// define human security configuration
4	const config = {
5	px_app_id: '<APP_ID>',
6	px_auth_token: '<AUTH_TOKEN>',
7	px_cookie_secret: '<COOKIE_SECRET>',
8	// any other configs...
9	};
10
11	export async function handleHttpRequest(request, context) {
12	// create enforcer with configuration params
13	const enforcer = new HumanSecurity(config).createEnforcer();
14
15	// await enforcement
16	let response = await enforcer.enforce(request, context);
17
18	// return enforcer response (first party or block) if it exists
19	if (response) {
20	// if any block response modifications are needed, perform them here
21	return response;
22	}
23
24	// perform logic to fetch desired response, for example:
25	response = await fetch(request.url, { edgio: { origin: '<ORIGIN_NAME>' } });
26
27	// await any necessary post-processing
28	await enforcer.postEnforce(response);
29
30	// return response
31	return response;
32	}