@centinel/cloudflare-worker

Bot detection middleware for Cloudflare Workers. Checks requests against the Centinel validator API and blocks or redirects bots. Allowed requests pass through to your existing worker.

Install

npm install @centinel/cloudflare-worker

Usage

Wrap your existing worker with activateCentinel:

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

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

export default activateCentinel(myWorker);

Set CENTINEL_SECRET_KEY as an environment variable in your wrangler.toml or via the dashboard:

[vars]
CENTINEL_SECRET_KEY = "sk_live_..."

Options

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

    // Skip these paths (default: static asset extensions)
    protectedPathsExclusion: /\.(css|js|png|jpg)$/i,

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

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

All options can be overridden per-request via environment variables:

| Env var | Overrides | |---|---| | CENTINEL_SECRET_KEY | secretKey | | CENTINEL_VALIDATOR_URL | validatorURL | | CENTINEL_TIMEOUT | timeout | | CENTINEL_ENABLE_DEBUGGING | enableDebugging |

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;

Or paste example/standalone/centinel-worker.js directly into the Cloudflare dashboard. See example/standalone/README.md for step-by-step instructions.

How it works

1. Request comes in
2. Path checked against inclusion/exclusion patterns
3. If protected, POSTs request metadata to the Centinel validator API
4. Validator returns allow, block, redirect, or not_matched
5. allow / not_matched: request forwarded to your worker
6. block: returns HTML error page with status code
7. redirect: returns base64-decoded challenge page

Fails open on every error path. If the validator is down or slow, requests go through to your worker. Exponential backoff stops hammering the validator after repeated failures.

Examples

• example/standalone/ - single-file for CF dashboard paste
• example/npm-integration/ - wrapping an existing worker

License

MIT