> This page is for Applications Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# Installation

## Prerequisites

The HUMAN Edgio Enforcer uses Node.js and Edgio's [Edge Functions](https://docs.edg.io/guides/v7/edge-functions). See the prerequisites for using Edge Functions [here](https://docs.edg.io/guides/v7/edge-functions#prerequisites).

> **Note**
>
> 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](/applications/support).

0. Create an Edgio property and router (if you haven't already) by [following the instructions here](https://docs.edg.io/guides/v7/edge-functions#defining-edge-functions).
1. Install the HUMAN Enforcer NPM package into your Edgio project.

```sh
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](https://docs.edg.io/guides/v7/performance/cdn_as_code/edgio_config).

```javascript
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' }],
        },
    ],
};
```

> **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.

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.

```javascript
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.

```javascript
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;
}
```

> **Using Fetch**
>
> See [here](https://docs.edg.io/guides/v7/edge-functions#origin-requests-using-fetch) 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](https://docs.edg.io/guides/v7/edge-functions#limitations) when developing your edge function!

4. Use the Edgio CLI to [test your edge function locally](https://docs.edg.io/guides/v7/edge-functions#testing-locally) and [deploy the Edgio property](https://docs.edg.io/guides/v7/edge-functions#deploying-your-property).

```bash
# test locally
edgio dev

# deploy to edgio
edgio deploy
```