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

# API

## createEnforcedRequestHandler

A function that creates a default request handler with built-in HUMAN enforcement. Useful if there is little request/response manipulation in your Fastly JS service.

```ts
createEnforcedRequestHandler(
    config: HumanSecurityConfiguration,
    onPass: (event: FetchEvent) => Response | Promise<Response>,
    onResponse?: (response: Response) => Response | Promise<Response>,
) => ((event: FetchEvent) => Promise<Response>)
```

* Parameters
  * config: HumanSecurityConfiguration
  * onPass: (event: [FetchEvent](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent/FetchEvent)) => [Response](https://js-compute-reference-docs.edgecompute.app/docs/globals/Response/) | [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) | [Response](https://js-compute-reference-docs.edgecompute.app/docs/globals/Response/) | [Response](https://js-compute-reference-docs.edgecompute.app/docs/globals/Response/)
  * onResponse?: (response: [Response](https://js-compute-reference-docs.edgecompute.app/docs/globals/Response/)) => [Response](https://js-compute-reference-docs.edgecompute.app/docs/globals/Response/) | [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) | [Response](https://js-compute-reference-docs.edgecompute.app/docs/globals/Response/) | [Response](https://js-compute-reference-docs.edgecompute.app/docs/globals/Response/)
* Returns a handler function that accepts a [FetchEvent](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent/FetchEvent) and returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) resolving to a [Response](https://js-compute-reference-docs.edgecompute.app/docs/globals/Response/).

Sample usage:

```ts
// index.ts
import { HumanSecurityConfiguration, createEnforcedRequestHandler } from "perimeterx-fastly-js-edge";

// define HUMAN configuration
const configs: HumanSecurityConfiguration = {
    px_app_id: '<APP_ID>',
    px_cookie_secret: '<COOKIE_SECRET>',
    px_auth_token: '<AUTH_TOKEN>',
};

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

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

// create request handler
const handleRequest = createEnforcedRequestHandler(configs, onPass, onResponse);

// invoke request handler on incoming fetch events
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
```

## HumanSecurityEnforcer

The entity responsible for performing HUMAN enforcement.

### HumanSecurityEnforcer.initialize()

A static function that creates a new instance of the HumanSecurityEnforcer class from a HumanSecurityConfiguration object.

```ts
HumanSecurityEnforcer.initialize(params: HumanSecurityConfiguration) => Promise<HumanSecurityEnforcer>
```

* Parameters
  * params: HumanSecurityConfiguration
* Returns a Promise resolving to a new instance of the HumanSecurityEnforcer class

### enforce()

Executes the enforcement functionality, returning a request or response depending on which action should be taken by the worker.

```ts
enforce(event: FetchEvent) => Promise<Response | null>
```

* Parameters
  * event: [FetchEvent](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent/FetchEvent)
* Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) resolving to a [Response](https://js-compute-reference-docs.edgecompute.app/docs/globals/Response/) or null

**The function returns null when...**

1. The request should not be blocked.
2. The request should be blocked, but the enforcer has been configured to let these requests pass.

> **Note**
>
> The function may add headers to the original [Request](https://js-compute-reference-docs.edgecompute.app/docs/globals/Request/) object present on the incoming [FetchEvent](https://js-compute-reference-docs.edgecompute.app/docs/globals/FetchEvent/#instance-properties).

**The function returns a Response when...**

1. The request should be blocked, and the response is a block page generated by the enforcer.
2. The request was a first-party request, and the response is the first-party resource requested.

> **Note**
>
> Modifications can be made to this response as needed prior to returning it from the main function.

### postEnforce()

Performs any post-enforcement processing actions and final modifications to (i.e., setting cookies or headers on) the response if needed.

```ts
postEnforce(response: Response) => Promise<void>
```

* Parameters
  * response: [Response](https://js-compute-reference-docs.edgecompute.app/docs/globals/Response/)
* Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) resolving to void.