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

# Akamai EdgeWorker Enforcer v4 API

The Akamai EdgeWorker Enforcer library includes two subpackages that can be imported and used. The first is the `worker` subpackage,\
which contains the enforcer logic that should be executed within the Akamai EdgeWorker. The second is the `propertymanager` subpackage,\
which provides utility functions to help generate the Akamai Property Manager rules and variables required for the enforcer.

## Worker Subpackage

The HUMAN Akamai EdgeWorker subpackage exports three functions with names in the format of `createHumanSecurity<EventName>` that generate out-of-the box\
handlers for each of the three `onClientRequest`, `onClientResponse`, and `responseProvider` events. The handlers returned by these functions provide the simplest\
possible implementation of the enforcer logic for each event and should be used if no other edgeworker logic is required.

The subpackage exports `OnClientRequestEnforcer`, `OnClientResponseEnforcer`, and `ResponseProviderEnforcer` classes, which can be used to create\
handlers that require additional logic for each Akamai EdgeWorker event as needed. The subpackage also exports a `HumanSecurityUtils` namespace as well as\
`HumanSecurityFunctionsConfiguration` and `HumanSecurityConfiguration` types for configuring the enforcer.

See the documentation below for more information on the functions and classes exported by the subpackage. See the configuration documentation for more information on the configuration types.

### createHumanSecurityOnClientRequest

Creates a handler for the `onClientRequest` event that includes all logic necessary for HUMAN enforcement.

Both function parameters are optional. The first parameter, `HumanSecurityFunctionsConfiguration`, is necessary for configuring any\
custom function behavior. The second parameter is the `EdgeKV` client for enabling the Remote Configuration feature.

```ts
createHumanSecurityOnClientRequest(
    customFunctions?: HumanSecurityFunctionsConfiguration,
    edgeKVClient?: EdgeKV
): (request: EW.IngressClientRequest) => Promise<void>
```

* Parameters
  * customFunctions?: HumanSecurityFunctionsConfiguration
  * edgeKVClient?: [EdgeKV](https://techdocs.akamai.com/edgekv/docs/library-helper-methods)
* Returns an `onClientRequest` Akamai event handler

Sample Usage:

```ts
import {
    createHumanSecurityOnClientRequest,
    // ...
} from '@humansecurity/akamai-edgeworker-enforcer/worker';

export const onClientRequest = createHumanSecurityOnClientRequest();
// ...
```

### OnClientRequestEnforcer

The entity responsible for performing HUMAN enforcement in the `onClientRequest` event.

Sample Usage:

```ts
import {
    OnClientRequestEnforcer,
    HumanSecurityUtils,
} from '@humansecurity/akamai-edgeworker-enforcer/worker';

export async function onClientRequest(request: EW.IngressClientRequest): Promise<void> {
    const config = HumanSecurityUtils.getConfiguration(request);
    const enforcer = new OnClientRequestEnforcer(config);
    const resp = await enforcer.enforce(request);
    if (resp) {
        return request.respondWith(resp.status, resp.headers, resp.body.substring(0, 2048));
    }
}
```

#### constructor

Creates a new instance of the `OnClientRequestEnforcer` class. Requires the full HUMAN security configuration and an optional EdgeKV client for Remote Configuration.

```ts
new OnClientRequestEnforcer(
    config: HumanSecurityConfiguration,
    edgeKVClient?: EdgeKV,
): OnClientRequestEnforcer
```

* Parameters
  * config: HumanSecurityConfiguration
  * edgeKVClient?: [EdgeKV](https://techdocs.akamai.com/edgekv/docs/library-helper-methods)
* Returns a new instance of the `OnClientRequestEnforcer` class

#### enforce

Performs HUMAN enforcement on the incoming request. The enforcer will return either `null` when the request should be passed through to the origin server,\
or an object representing the block response when the request should be blocked.

```ts
enforce(request: EW.IngressClientRequest): Promise<{ status: number, headers: Record<string, string[]>, body: string } | null>
```

* Parameters
  * request: [EW.IngressClientRequest](https://techdocs.akamai.com/edgeworkers/docs/request-object)
* Returns a Promise resolving to either null or an object representing the block response

> **Note**
>
> The block response object includes the status code, headers, and body, and can be used in conjunction with the Request object's
> [respondWith](https://techdocs.akamai.com/edgeworkers/docs/request-object#respondwith) function to block the request.
>
> ```ts
> // in onClientRequest event handler
> const res = await enforcer.enforce(request);
> if (res) {
> request.respondWith(res.status, res.headers, res.body);
> }
> ```

### createHumanSecurityOnClientResponse

Creates a handler for the `onClientResponse` event that includes all logic necessary for HUMAN enforcement.

The function parameter, `HumanSecurityFunctionsConfiguration`, is optional and should be used to configure any custom function behavior.

```ts
createHumanSecurityOnClientResponse(
    customFunctions?: HumanSecurityFunctionsConfiguration
): (request: EW.EgressClientRequest, response: EW.EgressClientResponse) => Promise<void>
```

* Parameters
  * customFunctions?: HumanSecurityFunctionsConfiguration
* Returns an `onClientResponse` Akamai event handler

Sample Usage:

```ts
import {
    createHumanSecurityOnClientResponse,
    // ...
} from '@humansecurity/akamai-edgeworker-enforcer/worker';

export const onClientResponse = createHumanSecurityOnClientResponse();
// ...
```

### OnClientResponseEnforcer

The entity responsible for performing HUMAN post-enforcement functionality in the `onClientResponse` event.

Sample Usage:

```ts
import {
    OnClientResponseEnforcer,
    HumanSecurityUtils,
} from '@humansecurity/akamai-edgeworker-enforcer/worker';

export async function onClientResponse(request: EW.EgressClientRequest, response: EW.EgressClientResponse) {
  const config = HumanSecurityUtils.getConfiguration(request);
  const enforcer = new OnClientResponseEnforcer(config, request);
  await enforcer.postEnforce(request, response);
};
```

#### constructor

Creates a new instance of the `OnClientResponseEnforcer` class. Requires the full HUMAN security configuration.

```ts
new OnClientResponseEnforcer(
    config: HumanSecurityConfiguration,
    request: EW.EgressClientRequest,
): OnClientResponseEnforcer
```

* Parameters
  * config: HumanSecurityConfiguration
  * request: [EW.EgressClientRequest](https://techdocs.akamai.com/edgeworkers/docs/request-object)
* Returns a new instance of the `OnClientResponseEnforcer` class

#### postEnforce

Performs post-enforcement actions required for HUMAN enforcement.

```ts
postEnforce(request: EW.EgressClientRequest, response: EW.EgressClientResponse): Promise<void> 
```

* Parameters
  * request: [EW.EgressClientRequest](https://techdocs.akamai.com/edgeworkers/docs/request-object)
  * response: [EW.EgressClientResponse](https://techdocs.akamai.com/edgeworkers/docs/response-object)
* Returns a Promise resolving to void

### createHumanSecurityResponseProvider

Creates a handler for the `responseProvider` event that includes all logic necessary for HUMAN enforcement.

Both function parameters are optional. The first parameter, `HumanSecurityFunctionsConfiguration`, is necessary for configuring any\
custom function behavior. The second parameter is the `EdgeKV` client for enabling the Remote Configuration feature.

```ts
createHumanSecurityResponseProvider(
    customFunctions?: HumanSecurityFunctionsConfiguration,
    edgeKV?: EdgeKV,
): (request: EW.ResponseProviderRequest) => Promise<object>
```

* Parameters
  * customFunctions?: HumanSecurityFunctionsConfiguration
  * edgeKVClient?: [EdgeKV](https://techdocs.akamai.com/edgekv/docs/library-helper-methods)
* Returns a `responseProvider` Akamai event handler

Sample Usage:

```ts
import {
    createHumanSecurityResponseProvider,
    // ...
} from '@humansecurity/akamai-edgeworker-enforcer/worker';

export const responseProvider = createHumanSecurityResponseProvider();
// ...
```

### ResponseProviderEnforcer

The entity responsible for performing HUMAN enforcement in the `responseProvider` event.

Sample Usage:

```ts
import {
  ResponseProviderEnforcer,
  HumanSecurityUtils,
} from '@humansecurity/akamai-edgeworker-enforcer/worker';

export async function responseProvider(request: EW.ResponseProviderRequest): Promise<object> {
  const config = HumanSecurityUtils.getConfiguration(request);
  const enforcer = new ResponseProviderEnforcer(config);
  const resp = await enforcer.enforce(request);
  if (resp) {
    return resp;
  }

  const proxyResp = await ResponseProviderEnforcer.proxyRequestToOrigin(request);

  return await enforcer.postEnforce(request, proxyResp);
};
```

#### constructor

Creates a new instance of the `ResponseProviderEnforcer` class. Requires the full HUMAN security configuration and an optional EdgeKV client for Remote Configuration.

```ts
new ResponseProviderEnforcer(
    config: HumanSecurityConfiguration,
    edgeKVClient?: EdgeKV,
): ResponseProviderEnforcer
```

* Parameters:
  * config: HumanSecurityConfiguration
  * edgeKVClient?: [EdgeKV](https://techdocs.akamai.com/edgekv/docs/library-helper-methods)
* Returns a new instance of the `ResponseProviderEnforcer` class

#### ResponseProviderEnforcer.proxyRequestToOrigin

Proxies the request to the origin server and returns the response. The function prepares the request body, removes [problematic headers](https://techdocs.akamai.com/edgeworkers/docs/edgeworkers-javascript-code#can-i-re-use-request-and-response-headers),\
and uses the [httpRequest](https://techdocs.akamai.com/edgeworkers/docs/http-request#httprequest) function to send the request.

```ts
proxyRequestToOrigin(
    request: EW.ResponseProviderRequest,
    timeoutMs?: number,
): Promise<HttpResponse>
```

* Parameters:
  * request: [EW.ResponseProviderRequest](https://techdocs.akamai.com/edgeworkers/docs/request-object),
  * timeoutMs?: number
* Returns a Promise resolving to an [HttpResponse](https://techdocs.akamai.com/edgeworkers/docs/http-request#httpresponse-object) object

#### enforce

Performs HUMAN enforcement on the incoming Response Provider request. The enforcer will return either `null` when the request should be passed through to the origin server,\
or an object representing the block response when the request should be blocked.

```ts
enforce(request: EW.ResponseProviderRequest): Promise<object | null>
```

* Parameters
  * request: [EW.ResponseProviderRequest](https://techdocs.akamai.com/edgeworkers/docs/request-object)
* Returns a Promise resolving to either null or an object created from [createResponse](https://techdocs.akamai.com/edgeworkers/docs/create-response)

#### postEnforce

Performs post-enforcement actions required for HUMAN enforcement.

```ts
postEnforce(request: EW.ResponseProviderRequest, response: HttpResponse): Promise<object>
```

* Parameters
  * request: [EW.ResponseProviderRequest](https://techdocs.akamai.com/edgeworkers/docs/request-object)
  * response: [HttpResponse](https://techdocs.akamai.com/edgeworkers/docs/http-request#httpresponse-object)
* Returns a Promise resolving to an object created from [createResponse](https://techdocs.akamai.com/edgeworkers/docs/create-response)

### HumanSecurityUtils

#### getConfiguration

Generates the full HUMAN Security configuration required for the enforcer. The function requires the Akamai EdgeWorker request object and an optional custom function configuration.

```ts
getConfiguration(
    request: EW.ResponseProviderRequest | EW.IngressClientRequest | EW.EgressClientRequest,
    customFunctions?: HumanSecurityFunctionsConfiguration,
): HumanSecurityConfiguration
```

* Parameters
  * request: [Request](https://techdocs.akamai.com/edgeworkers/docs/request-object)
  * customFunctions?: HumanSecurityFunctionsConfiguration
* Returns a complete HumanSecurityConfiguration object

#### getRequestBody

Retrieves the request body from the Akamai EdgeWorker request object. Note that the request body can only be accessed in the `responseProvider` event.\
Since the request body can only be read once, the HUMAN Akamai EdgeWorker enforcer will store the request body when read. If the body has already\
been read, this function will return the stored value. If the body has not yet been read, this function will read the body and store it for future use.

```ts
getRequestBody(request: EW.ResponseProviderEvent): Promise<string | undefined>
```

* Parameters
  * request: [EW.ResponseProviderEvent](https://techdocs.akamai.com/edgeworkers/docs/request-object)
* Returns a Promise resolving to a string or undefined

#### getResponseBody

Retrieves the response body from the parameter passed to the `login_successful_callback`. Note that the response body can only be accessed in the `responseProvider` event.\
Since the response body can only be read once, the HUMAN Akamai EdgeWorker enforcer will store the response body when read. If the body has already\
been read, this function will return the stored value. If the body has not yet been read, this function will read the body and store it for future use.

```ts
getResponseBody(response: { status: number; headers: Record<string, string[]>; body: any }): Promise<string>
```

* Parameters
  * response: `{ status: number; headers: Record<string, string[]>; body: any }`
* Returns a Promise resolving to a string

## Property Manager Subpackage

The HUMAN Akamai EdgeWorker Property Manager subpackage exports two functions for generating the Property Manager rules and variables required for the enforcer.

### buildHumanSecurityPropertyManagerRules

Generates an object representing the PXEnforcerRule and its child rules required for integrating the enforcer with the given configuration into your Property Manager.

```ts
buildHumanSecurityPropertyManagerRules(
    config: HumanSecurityConfiguration,
    edgeWorkerId: number,
    netStorageCpCode: number,
    netStorageDomain: string,
): object
```

* Parameters:
  * config: HumanSecurityConfiguration
  * edgeWorkerId: number (e.g., `12345`, [see here](https://techdocs.akamai.com/edgeworkers/docs/create-an-edgeworker-id-2))
  * netStorageCpCode: number (e.g., `1234567`, [see here](https://techdocs.akamai.com/netstorage/reference/get-started))
  * netStorageDomain: string (e.g., `<prefix>.download.akamai.com`, [see here](https://techdocs.akamai.com/netstorage/docs/downloads-with-netstorage#use-netstorage-as-an-origin-server))
* Returns an object representing the Property Manager rules required for the enforcer

### buildHumanSecurityPropertyManagerVariables

Generates a list of Property Manager variables required for configuring the enforcer with the given configuration.

```ts
buildHumanSecurityPropertyManagerVariables(config: HumanSecurityConfiguration): Variable[]
```

* Parameters:
  * config: HumanSecurityConfiguration
* Returns a list of Property Manager variables required for the enforcer