HUMAN Decisioning Worker

The HUMAN Decisioning Worker is a library to quickly set up a BotGuard integration on pre-existing web applications using Cloudflare Workers.

Overview

HUMAN Decisioning Worker can be used to set up BotGuard's Active Mitigation or a Token Mitigation on sensitive endpoints. This worker handles injecting the required client-side logic to run BotGuard's Detection Tag and Block or Forward API calls to your server. Additionally, this solution is fully extendable to forward BotGuard's Decision about your user traffic upstream, allowing you to attach your own custom handlers.

Notes

• Active Mitigation:
  • Provides mitigation on your web applications in real time by fetching a Decision from BotGuard's Mitigation API.
  • Best suited for defending on individual interactive events (e.g. account creation, authentication, commenting or liking, checking out, etc.) and mission critical API access.
• Token Mitigation:
  • Provides broad mitigation by fetching a Decision and storing an encrypted token on the client that can be used to provide constant decisioning and protection.
  • Best suited as overall application protection such as scraping protection.

Actions

The HUMAN Worker provides bot mitigation through these core actions:

• deployTag:
  • Injects the HUMAN client-side logic on the web page to be protected.
  • This action should be set on routes that return HTML back.
• createToken:
  • Creates and extends expirations on Decisions nested in the HUMAN token as an encrypted cookie string.
  • This token represents the decision from the Mitigation API that can be used to pre-check a human/bot before allowing access to any sensitive endpoints.
  • There should be only be one route set for this action per domain.
• checkToken
  • Verifies the decision in the HUMAN token from the createToken action above.
  • If bot, it returns a configurable block response to the client. Otherwise, it forwards the request to the upstream server for the request.
• checkLive
  • Verifying a user directly with the Mitigation API
  • If bot, it returns a configurable block response to the client. Otherwise, it forwards the request to the upstream server for the request.
• formData
  • Verifying a user directly on events using the native form submit action
  • If bot, it returns a configurable block response to the client. Otherwise, it forwards the request to the upstream server for the request.

Features

• Handles turnkey mitigation from HUMAN.
• Extendable to add custom middleware.
• TypeScript Support.

Installation

A package of the library is available, please contact your HUMAN representative for access to the latest distribution. There are additional example use cases available as recipes. Please reach out if you need additional guidance on your integration.

Basic Example

You will need the human.js file from your HUMAN representative along with a Cloudflare account with a domain configured.

// In your index.js file
// PASTE the contents of the `human.js`file here (this exposes the library via the human var)

const config = {
  /* Your configuration object */
};

// handleRequest is the default version of the HUMAN Worker all inclusive of routing and handling all actions
const { handleRequest } = human.initialize(config);

addEventListener("fetch", (event) => {
  event.passThroughOnException();
  event.respondWith(handleRequest(event.request));
});

Set up the Environment

You must add your Mitigation API key to your worker's Environment variables. In your Cloudflare dashboard, please go to the settings for your HUMAN Worker service. You will see the section for adding Environment variables as depicted below:

Please enter the environment variable name MITIGATION_API_KEY and enter your API key where you read YOUR-VESPER-API-KEY and encrypt this value. You should see the value is set as below:

Configuration Object

Config

human.initialize(config)

Route

Advanced Usage

If you are using wrangler and/or miniflare which is out of scope for this example, you will need a worker directory configured to deploy your code. Once you have this, you can use the library by importing it as shown below. Otherwise, you must copy the contents as the preview example.

1. Initialize HUMAN Worker

import human from "./human.js";

const config = {
  /* Your configuration object*/
};

const humanWorker = human.initialize(config);

2. Setup Handler

const {
  findMatchingRoute,
  deployTag,
  checkToken,
  createToken,
  checkLive,
  getForwardRequest,
} = humanWorker;

// This is the same implementation as the handleRequest exported in the default humanWorker
const handleRequest = async (request) => {
  // Finds the matching route in the config
  const matchingRoute = findMatchingRoute(request);

  switch (matchingRoute?.type) {
    case "deployTag":
      return deployTag(request);
    case "checkToken":
      return checkToken(request);
    case "createToken":
      return createToken(request);
    case "checkLive":
      return checkLive(request, { eventType: matchingRoute.eventType });
  }

  // All routes that do not match should also use `getForwardRequest` to remove
  // any human cookies or update domains on forward requests
  return fetch(getForwardRequest(request));
};

addEventListener("fetch", (event) => {
  event.passThroughOnException();
  event.respondWith(handleRequest(event.request));
});

3. Setup Handler for a single action

If you want the worker to only handle a single action without routing, you can use the individual actions as shown here:

// Create Token Worker
const { createToken } = humanWorker;

addEventListener("fetch", (event) => {
  event.respondWith(createToken(event.request));
});

// Deploy Tag Worker
const { deployTag } = humanWorker;

addEventListener("fetch", (event) => {
  event.respondWith(deployTag(event.request));
});

// Check Token Worker
const { checkToken } = humanWorker;

addEventListener("fetch", (event) => {
  event.respondWith(checkToken(event.request));
});

// Check Live Worker
const { checkLive } = humanWorker;

addEventListener("fetch", (event) => {
  event.respondWith(checkLive(event.request, { eventType: "EVENT_TYPE" }));
});

Additional Functions

In addition to the base actions that come with the HUMAN Worker, the following provided functions allow more customization:

• injectHumanScript:
  • Used in deployTag handler.
  • Takes a Response object with a Content-Type of html, and appends the HUMAN client logic to that response.
  • This action should be set on routes that return HTML back.
• getCheckLiveResult:
  • Used in checkLive handler.
  • Creates and extends expirations on Decisions nested in the HUMAN token as an encrypted cookie string.
  • This token represents the decision from the Mitigation API that can be used to pre-check a human/bot before allowing access to any sensitive endpoints.
  • There should be only be one route set for this action per domain.
• getCheckTokenResult
  • Used in checkToken handler.
  • Verifies the decision in the HUMAN token from the createToken action above.
  • If bot, it returns a configurable block response to the client. Otherwise, it forwards the request to the upstream server for the request.
• getCreateTokenResult
  • Used in createToken handler.
  • Verifies a user directly with the Mitigation API.
  • If bot, it returns a configurable block response to the client. Otherwise, it forwards the request to the upstream server for the request.
• askHuman
  • Directly make a request to the Mitigation API.
• getMitigationParams
  • Retrieves the parameters for the Mitigation API from the request headers, returns '[EMPTY]' for each param if not found.
• getForwardRequest
  • Clones the request and updates the URL to the originDomain in config if there are any, and removes any HUMAN cookies & headers in the upstream request.
• findMatchingRoute
  • Returns a matching route for the request if any exists.
• removeUpstreamHUMANHeaders
  • Removes any HUMAN headers or cookies from the request.

These examples show how the base actions can be used to create your own handlers:

const {
  injectHumanScript,
  getCheckLiveResult,
  getCheckTokenResult,
  getCreateTokenResult,
} = humanWorker;

// If the response is html, then attach the HUMAN client logic
async function deployTag(request) {
  const serverResponse = await fetch(request)
  const contentType: string | null = serverResponse.headers.get('Content-Type')

  if (contentType?.startsWith('text/html')) {
    return injectHumanScript(serverResponse)
  }

  return serverResponse
}

// If the Active decision is allow, then forward the request
async function checkLive(request, { eventType }){
  const checkLiveResult = await getCheckLiveResult(request, , { eventType })
  if (checkLiveResult.result === 'allow') {
    return fetch(request)
  }

  return new Response("Forbidden", { status: 403 });
}

// If the Token decision is allow, then forward the request
async function checkToken(request) {
  const checkTokenResult = await getCheckTokenResult(request, , { eventType })
  if (checkTokenResult.result === 'allow') {
    return fetch(request)
  }

  return new Response("Forbidden", { status: 403 });
}

Middleware

Creating custom middleware with the HUMAN worker is very straightforward by wrapping the additional functions. The HUMAN Worker works well with the itty-router library.

Example 1: Middleware for attaching a HUMAN Decision on Token routes

import { Router } from "itty-router";
import human from "./human.js";

const config = {
  /* Your configuration object*/
};

const humanWorker = human.initialize(config);
const { getCheckTokenResult } = humanWorker;

// itty-router
const router = Router();

// Appends the human decision on the request
const withHumanTokenDecision = async (request) => {
  const checkTokenResult = await getCheckTokenResult(request);
  request.humanDecision = checkTokenResult;
};

Example 2: Middleware for Mitigating account creation routes

import { Router } from "itty-router";
import human from "./human.js";

const config = {
  /* Your configuration object*/
};

const humanWorker = human.initialize(config);
const { getCheckLiveResult } = humanWorker;

// For a live route for account creation
const withHumanActiveDecision = async (request) => {
  const checkLiveResult = await getCheckLiveResult(request, { eventType: "2" });
  request.humanDecision = checkLiveResult.decision;
};

// Middleware that only passes allow decision
const requireAllowAction = (request) => {
  if (!request.humanDecision?.action === "allow") {
    return new Response("Forbidden", { status: 403 });
  }
};

const createAccount = (request) => {
  return new Response("Account creation success", { status: 200 });
};

router.get(
  "/signup",
  withHumanActiveDecision,
  requireAllowAction,
  createAccount
);

TypeScript

The library is built with, and fully supports, TypeScript. In the folder of the library's distribution, you will see the definitions for the library in the file human.d.ts.