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.

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

• Parameters
  • customFunctions?: HumanSecurityFunctionsConfiguration
  • edgeKVClient?: EdgeKV
• Returns an onClientRequest Akamai event handler

Sample Usage:

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:

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.

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

• Parameters
  • config: HumanSecurityConfiguration
  • edgeKVClient?: EdgeKV
• 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.

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

• Parameters
  • request: EW.IngressClientRequest
• 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 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.

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

• Parameters
  • customFunctions?: HumanSecurityFunctionsConfiguration
• Returns an onClientResponse Akamai event handler

Sample Usage:

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:

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.

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

• Parameters
  • config: HumanSecurityConfiguration
  • request: EW.EgressClientRequest
• Returns a new instance of the OnClientResponseEnforcer class

postEnforce

Performs post-enforcement actions required for HUMAN enforcement.

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

• Parameters
  • request: EW.EgressClientRequest
  • response: EW.EgressClientResponse
• 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.

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

• Parameters
  • customFunctions?: HumanSecurityFunctionsConfiguration
  • edgeKVClient?: EdgeKV
• Returns a responseProvider Akamai event handler

Sample Usage:

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:

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.

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

• Parameters:
  • config: HumanSecurityConfiguration
  • edgeKVClient?: EdgeKV
• 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,
and uses the httpRequest function to send the request.

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

• Parameters:
  • request: EW.ResponseProviderRequest,
  • timeoutMs?: number
• Returns a Promise resolving to an HttpResponse 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.

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

• Parameters
  • request: EW.ResponseProviderRequest
• Returns a Promise resolving to either null or an object created from createResponse

postEnforce

Performs post-enforcement actions required for HUMAN enforcement.

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

• Parameters
  • request: EW.ResponseProviderRequest
  • response: HttpResponse
• Returns a Promise resolving to an object created from createResponse

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.

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

• Parameters
  • request: Request
  • 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.

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

• Parameters
  • request: EW.ResponseProviderEvent
• 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.

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.

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

• Parameters:
  • config: HumanSecurityConfiguration
  • edgeWorkerId: number (e.g., 12345, see here)
  • netStorageCpCode: number (e.g., 1234567, see here)
  • netStorageDomain: string (e.g., <prefix>.download.akamai.com, see here)
• 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.

buildHumanSecurityPropertyManagerVariables(config: HumanSecurityConfiguration): Variable[]

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