Cloudflare Workers (npm)

Install

npm install @centinel/cloudflare-worker

Setup

[vars]
CENTINEL_SECRET_KEY = "sk_live_..."

wrangler secret put CENTINEL_SECRET_KEY

import { activateCentinel } from '@centinel/cloudflare-worker';

const myWorker = {
    async fetch(request, env, ctx) {
        // Your existing worker code
        return new Response('Hello from my app');
    },
};

export default activateCentinel(myWorker);

wrangler deploy

Options

Pass a second argument to activateCentinel:

export default activateCentinel(myWorker, {
    // Only validate paths matching this pattern (tested against full URL)
    protectedPathsInclusion: /\/api(\/|$)/,

    // Skip paths matching this pattern (default: static assets like .css, .js, .png)
    protectedPathsExclusion: /\.(css|js|png|jpg|woff2)$/i,

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

    // Structured JSON debug logging (default: false)
    enableDebugging: true,
});

Environment variables

Options can be overridden per-request via environment variables. Set in wrangler.toml, the dashboard, or .dev.vars:

Env vars take precedence over options passed to activateCentinel(), so you can use different settings per environment without changing code.

How requests flow

1. Request arrives at your Cloudflare Worker
2. activateCentinel checks the path against inclusion/exclusion patterns
3. If protected, it POSTs request metadata (URL, method, IP, headers, _centinel cookie) to the validator API
4. The validator returns a decision:

Client → Centinel → Validator (allow) → Your Worker → Client

Client → Centinel → Validator (block) → 403 HTML page

Client → Centinel → Validator (redirect) → Challenge page

Client → Centinel → Validator (not_matched) → Your Worker → Client

Fail-open behavior

If the validator is down, slow, or returns an error, the request is forwarded to your worker. Your site stays up even if the validator has problems.

After repeated failures, the worker backs off exponentially (1s, 2s, 4s, ... up to 5 minutes) to stop hammering a broken endpoint. It retries once the backoff expires.

Standalone mode

If you don't have an existing worker, the default export works on its own:

import centinelWorker from '@centinel/cloudflare-worker';
export default centinelWorker;

TypeScript

Type definitions are included:

import { activateCentinel, CentinelOptions, CentinelHandler } from '@centinel/cloudflare-worker';

const options: CentinelOptions = {
    protectedPathsInclusion: /\/api\//,
    timeout: 5000,
};

export default activateCentinel(myWorker, options);

Monitoring

• Real-time logs: Workers dashboard → Your worker → Logs → Begin log stream
• Debug mode: Set CENTINEL_ENABLE_DEBUGGING = "true" in your env vars for detailed JSON logs at each step
• Server-Timing header: Every response from a protected path includes Server-Timing: validator;dur=<ms> showing how long the validator call took

Changelog

v1.1.2

• Response headers from /validate are now applied to all outgoing responses (block, redirect, and allow). Headers like Content-Type are no longer hardcoded — they come from the validator.
• Validator API requests now include a User-Agent header identifying the integration name and version.