Cloudflare Workers

Overview

This quickstart outlines the minimal console workflow for installing the Centinel Worker. Allow 2-3 minutes for the worker to deploy globally across Cloudflare's edge network.

Prerequisites

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

Step 1 · Prepare the Script

1. Download or copy the contents of centinel-worker.js.
2. Keep your CENTINEL_SECRET_KEY ready (you'll add it as an environment variable in Step 4).

Step 2 · Create the Worker

1. Log into your Cloudflare dashboard.
2. Go to Workers & Pages → Create application → Create Worker.
3. Name your worker (for example centinel-protection).
4. Click Deploy to create the worker with default code.

Step 3 · Upload the Script

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

Step 4 · Configure Environment Variables

1. Go to Settings → Variables.
2. Under Environment Variables, add:
   • Variable name: CENTINEL_SECRET_KEY
     • Value: your-secret-key
     • Type: Encrypt (recommended)
3. (Optional) Add CENTINEL_VALIDATOR_URL if using a custom validator endpoint.
4. Click Save and Deploy.

Step 5 · Add Route to Your Domain

1. Go to Triggers → Add route.
2. Enter your route pattern (for example example.com/* or *.example.com/*).
3. Select your zone/domain from the dropdown.
4. Click Add route.

Step 6 · Verify Deployment

• Visit your website to confirm normal traffic flow.
• Test that requests to protected paths are validated by the Centinel API.
• Monitor worker logs by clicking Logs → Begin log stream in your worker dashboard.
• Review logs for entries with "service": "CentinelAnalytica" to verify the worker is processing requests.

Advanced Configuration

Option 1: Configure via activateCentinel() options (Recommended)

Edit the activateCentinel() call at the bottom of the script (around line 580):

export default {
    async fetch(request, env, ctx) {
        const handler = activateCentinel(undefined, {
            // Protect only specific paths (optional)
            protectedPathsInclusion: /\/(api|admin|checkout)\//,

            // Exclude static assets (already excluded by default)
            protectedPathsExclusion: /\.(js|css|png|jpg|svg)$/,

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

            // Increase API timeout in milliseconds (default: 300ms)
            timeout: 500,

            // Enable debug logging (default: false)
            enableDebugging: false,
        });
        return handler.fetch(request, env, ctx);
    },
};

Option 2: Edit default path patterns directly

For more permanent changes, edit the variables at the top of the script (lines 26-27):

/**
 * Path regex patterns for protection
 */
let CENTINEL_PROTECTED_PATHS_INCLUSION = null;  // null = protect all paths
let CENTINEL_PROTECTED_PATHS_EXCLUSION = /\.(avi|avif|bmp|css|eot|flac|flv|gif|gz|ico|jpeg|jpg|js|json|less|map|mka|mkv|mov|mp3|mp4|mpeg|mpg|ogg|ogm|opus|otf|png|svg|svgz|swf|ttf|wav|webm|webp|woff|woff2|xml|zip)$/i;

Example customizations:

// Protect only API and admin paths
let CENTINEL_PROTECTED_PATHS_INCLUSION = /\/(api|admin)\//;

// Add more file extensions to exclusion
let CENTINEL_PROTECTED_PATHS_EXCLUSION = /\.(js|css|png|jpg|svg|ico|woff|woff2|ttf)$/i;

After making changes, click Save and Deploy to update your worker.

Using Wrangler CLI (Alternative)

For developers who prefer command-line deployment:

# Install Wrangler
npm install -g wrangler

# Authenticate
wrangler login

# Set secret
wrangler secret put CENTINEL_SECRET_KEY

# Deploy
wrangler deploy centinel-worker.js --name centinel-protection

# Add route
wrangler route add "example.com/*" centinel-protection

Monitoring & Logs

• Real-time logs: Workers dashboard → Your worker → Logs → Begin log stream
• Analytics: Workers dashboard → Your worker → Analytics
• Debugging: Set enableDebugging: true in configuration options for detailed logging

Troubleshooting

Validation not working:

• Verify CENTINEL_SECRET_KEY is set correctly in environment variables
• Check that your route covers the paths you're testing
• Review worker logs for validation attempts and API responses
• Confirm validator API is responding (check for timeout logs)

Requests blocked unexpectedly:

• Review Cloudflare logs for Centinel entries with "service": "CentinelAnalytica"
• Check path exclusion patterns aren't too broad
• Verify the validator API is returning the expected decision values
• Enable debug logging (enableDebugging: true) to see detailed flow

Worker not activating:

• Confirm the route pattern matches your domain
• Check that the worker is deployed (status should be "Active")
• Verify you're testing on the correct domain/subdomain
• Ensure the worker code has no syntax errors

API timeouts or failures:

• The worker has exponential backoff enabled - after failures, it will skip validation temporarily
• Check if the validator API endpoint is accessible
• Increase timeout if needed (default is 300ms)
• Review logs for backoff messages indicating repeated failures

Changelog

• 1.2 - Improved timeout handling.
• 1.1 - Improved error handling.
• 1.0 - Initial release.