Installation

HUMAN's Cloudflare enforcer is an enforcer module for use in Cloudflare Workers. The enforcer is provided as a Node.js NPM package that can be integrated into an existing Cloudflare worker or used to create a brand new worker.

Prerequisites

None, other than Cloudflare's prerequisites.

Installation

0. Get started by creating a new worker project, downloading the Wrangler CLI (if you haven't already).

1. Install the HUMAN Cloudflare enforcer NPM package into your worker project.

npm i --save @humansecurity/cloudflare-enforcer

2. Integrate the HUMAN enforcer into your project. 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.

The Cloudflare enforcer supports TypeScript as well as both ES Modules and Service Worker syntaxes.

ES Modules Syntax

import { HumanSecurityEnforcer, HumanSecurityConfiguration } from '@humansecurity/cloudflare-enforcer';

const config: HumanSecurityConfiguration = {
    px_app_id: '<APP_ID>',
    px_auth_token: '<AUTH_TOKEN>',
    px_cookie_secret: '<COOKIE_SECRET>',
    // ...
};

interface Env {
    // If using Human Security features that require the PXKV Namespace
    PXKV: KVNamespace;
}

export default {
    async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
        // create a new enforcer
        const enforcer = await HumanSecurityEnforcer.initialize(config, env);

        // call enforce
        const retVal = await enforcer.enforce(ctx, request);

        // if enforce returned a response, return that response
        if (retVal instanceof Response) {
            return retVal;
        }

        // retrieve the resource from the cache or origin server
        // make sure to use the value returned from enforce
        const response = await fetch(retVal);

        // call postEnforce and return the resulting response
        return await enforcer.postEnforce(ctx, response);
    },
};

Service Worker Syntax

import { HumanSecurityEnforcer, HumanSecurityConfiguration } from "@humansecurity/cloudflare-enforcer";

const config: HumanSecurityConfiguration = {
    px_app_id: '<APP_ID>',
    px_auth_token: '<AUTH_TOKEN>',
    px_cookie_secret: '<COOKIE_SECRET>',
    // ...
};

async function handleEvent(event: FetchEvent): Promise<Response> {
    // create a new enforcer
    const enforcer = await HumanSecurityEnforcer.initialize(config);

    // call enforce
    const retVal = await enforcer.enforce(event);

    // if enforce returned a response, return that response
    if (retVal instanceof Response) {
        return retVal;
    }

    // retrieve the resource from the cache or origin server
    // make sure to use the value returned from enforce
    const response = await fetch(retVal);

    // call postEnforce and return the resulting response
    return await enforcer.postEnforce(event, response);
}

addEventListener('fetch', (event) => {
    event.respondWith(handleEvent(event));
});

3. Set up your wrangler configuration file. No modifications are necessary to any existing wrangler.toml unless utilizing Remote Configuration features. If these features are used, you must create a KV namespace named PXKV and include this namespace binding in your wrangler.toml file.

# wrangler.toml
name = "example-worker"
main = "./index.js"
compatibility_date = "2023-11-21"

kv_namespaces = [
    { binding = "PXKV", id = "<PXKV_ID>" }
]

5. Build, test, and deploy the worker to Cloudflare using Wrangler or the deploy tool of your choice.

# test your worker locally
npx wrangler dev

# deploy your worker to Cloudflare
npx wrangler deploy