Cloudflare Workers

Overview

This guide covers the console workflow for installing the Centinel Worker as a standalone file. The worker deploys globally in 2-3 minutes.

Have an existing worker?

If you already have a Cloudflare Worker and want to add Centinel to it, use the npm package instead.

Prerequisites

Centinel secret key (for validator API)
Cloudflare account with a website added
Access to the Cloudflare dashboard

Install

Prepare the script

Download or copy centinel-worker.js.
Keep your CENTINEL_SECRET_KEY ready (you'll add it as an environment variable later).

Create the worker

Log into your Cloudflare dashboard.
Go to Workers & Pages → Create application → Create Worker.
Name your worker (e.g. centinel-protection).
Click Deploy to create the worker with default code.

Upload the script

In the worker overview, click Quick Edit (or go to Edit code).
Delete all the default code.
Paste the entire contents of centinel-worker.js.
Click Save and Deploy.

Configure

Configure environment variables

Go to Settings → Variables and Secrets.
Click Add variable and enter:
- Variable name: CENTINEL_SECRET_KEY
- Value: your-secret-key
- Type: Secret. Do not use a plaintext variable for this.
Optionally add CENTINEL_VALIDATOR_URL, CENTINEL_TIMEOUT, or CENTINEL_ENABLE_DEBUGGING.
Click Save and Deploy.

Variable	Type	Default	Purpose
`CENTINEL_SECRET_KEY`	secret	—	Required. Without it the worker forwards all traffic unvalidated.
`CENTINEL_VALIDATOR_URL`	text	`https://validator.centinelanalytica.com/validate`	Alternate validator endpoint.
`CENTINEL_TIMEOUT`	text	`10000`	Validator timeout in ms.
`CENTINEL_ENABLE_DEBUGGING`	text	`false`	Set to `true` for verbose logs.

Use a Worker secret, not a Secrets Store binding

The worker reads this value as a plain string. A Secrets Store binding arrives as an object, which fails silently and leaves traffic unvalidated.

Add a route to your domain

Go to Settings → Domains & Routes and click Add.
Choose Route, then enter your pattern (e.g. example.com/* or *.example.com/*). A Custom Domain works too if the worker owns the hostname.
Select your zone/domain from the dropdown.
Click Add route.

Advanced configuration

Edit the activateCentinel() call at the bottom of the script. Keep it at the top level of the module, exactly as shipped.

export default activateCentinel(undefined, {
    // Protect only specific paths (optional; default is every path)
    protectedPathsInclusion: /\/(api|admin|checkout)\//,

    // Exclude static assets (a default exclusion list is already applied)
    protectedPathsExclusion: /\.(js|css|png|jpg|svg)$/,

    // Alternate validator endpoint (optional)
    validatorURL: 'https://custom-validator.example.com/validate',

    // Validator timeout in milliseconds (default: 10000)
    timeout: 10000,

    // Verbose logging (default: false)
    enableDebugging: false,
});

Call activateCentinel() once, at the top level

The handler holds the failure-backoff state. Calling activateCentinel() inside fetch resets that state for each request. The worker still calls the validator, but repeated failures can cause more validator traffic.

Path matching uses url.pathname, not the full URL. A query string cannot bypass an exclusion. Use the options above for supported configuration. Editing a bundled constant can change the worker behavior, but the change does not update the integration source or a later download.

# Install Wrangler 4 (needs Node.js 20+)
npm install -D wrangler@4

# Authenticate
npx wrangler login

# Set secret
npx wrangler secret put CENTINEL_SECRET_KEY

# Deploy
npx wrangler deploy

Routes are declarative in Wrangler 4. Add them to wrangler.toml rather than on the command line, then deploy:

name = "centinel-protection"
main = "centinel-worker.js"
compatibility_date = "2025-03-25"

routes = [
  { pattern = "example.com/*", zone_name = "example.com" }
]

Verify

Visit your site to confirm traffic flows normally.
Test that requests to protected paths are validated by the Centinel API.
Confirm a protected response carries a Server-Timing: validator;dur=... header. That is the zero-config signal that the validator was actually called.
For log output, set CENTINEL_ENABLE_DEBUGGING to true, then open Logs → Begin log stream and reload a protected path. Entries carry "service": "CentinelAnalytics". Unset it when you are done.
A healthy worker logs nothing by default, so silence in the log stream does not mean it is working. Watch instead for CENTINEL_SECRET_KEY not set or a 401 from the validator: either one means traffic is passing through unvalidated.

Monitoring and logs

Real-time logs: Workers dashboard → Your worker → Logs → Begin log stream
Analytics: Workers dashboard → Your worker → Analytics
Debugging: set CENTINEL_ENABLE_DEBUGGING to true, or pass enableDebugging: true in the options

Changelog

v1.2.1 — Edge case fixes
v1.2.0 — Security and edge fixes
v1.1.3 — Timeout handling
v1.1.0 — Error handling

On this page