Installation

Prerequisites

The HUMAN Fastly JavaScript Compute@Edge enforcer requires access to:

Installation

  1. Get started by creating a Fastly C@E Service and downloading the Fastly CLI (if you haven’t already).
  2. Use the HUMAN Fastly JavaScript Compute@Edge starter kit or install the HUMAN Enforcer NPM package into your existing Fastly project.
1# if you want to start a brand new project
2fastly compute init --from=https://github.com/PerimeterX/perimeterx-fastly-js-edge-template --language=javascript
3
4# if you have an existing project
5npm i --save perimeterx-fastly-js-edge
  1. Integrate the HUMAN Enforcer into your project.

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

1import { createEnforcedRequestHandler } from "perimeterx-fastly-js-edge";
2
3// define HUMAN configuration
4const config = {
5 px_app_id: '<APP_ID>',
6 px_cookie_secret: '<COOKIE_SECRET>',
7 px_auth_token: '<AUTH_TOKEN>',
8};
9
10// define what to do when requests pass HUMAN enforcement
11const onPass = (event) => {
12 console.log('handling HUMAN-validated request')
13 return fetch(event.request, { backend: '<ORIGIN_NAME>' })
14};
15
16// define what to do for block responses (optional)
17const onResponse = (response) => {
18 console.log('handling response from HUMAN enforcer');
19 return response;
20};
21
22// create request handler
23const handleRequest = createEnforcedRequestHandler(config, onPass, onResponse);
24
25// invoke handleRequest on incoming fetch event
26addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));

The example below shows what the createEnforcedRequestHandler() function does behind the scenes. For a more customized solution, create a new HumanSecurityEnforcer instance and use it in your request handler as desired.

The recommended usage is to:

  • initialize the HumanSecurityEnforcer, 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.
1import { HumanSecurityEnforcer } from 'perimeterx-fastly-js-edge';
2
3// define HUMAN configuration
4const config = {
5 px_app_id: '<APP_ID>',
6 px_cookie_secret: '<COOKIE_SECRET>',
7 px_auth_token: '<AUTH_TOKEN>',
8};
9
10async function handleRequest(event) {
11 // create enforcer with configuration params
12 const enforcer = await HumanSecurityEnforcer.initialize(config);
13
14 // await enforcement
15 let response = await enforcer.enforce(event);
16
17 // return enforcer response (first party or block) if it exists
18 if (response) {
19
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(event.request, { backend: '<ORIGIN_NAME>' });
26
27 // await any necessary post-processing
28 await enforcer.postEnforce(response);
29
30 // return response
31 return response;
32}
33
34// invoke handleRequest on incoming fetch event
35addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
  1. Add or modify the required HUMAN backends in your fastly.toml file (see here for more info) and/or directly to your Fastly service, replacing the application ID placholder with your application ID.
1[setup.backends.human_sapi]
2 address = "sapi-PX12345678.perimeterx.net"
3 description = "The Human Score API backend"
4
5[setup.backends.human_collector]
6 address = "collector-PX12345678.perimeterx.net"
7 description = "The Human Collector backend"
8
9[setup.backends.human_client]
10 address = "client.perimeterx.net"
11 description = "The Human backend that serves the client sensor"
12
13[setup.backends.human_captcha]
14 address = "captcha.px-cdn.net"
15 description = "The Human backend that serves the captcha script"
Backend Names

The default names of these backends are human_sapi, human_collector, human_client, and human_captcha. If the default human_* backend names are changed, the new backend names must be explicitly indicated in the Enforcer configuration using the px_backend_score_name, px_backend_collector_name, px_backend_client_name, and px_backend_captcha_name configurations, respectively.

  1. Build, test, and deploy the worker using the Fastly CLI.
1# builds and packages the worker
2fastly compute build
3
4# test the worker locally
5fastly compute serve
6
7# deploy the worker to Fastly
8fastly compute deploy
9
10# update an existing service
11fastly compute update -p ./path/to/packaged_worker.tar.gz --version=latest --autoclone