The Deterministic Trust Layer

Cloudflare Turnstile is for browsers. Sentinel is for APIs.

npm install api-turnstile

import { sentinel } from 'api-turnstile';

app.use(sentinel({
  apiKey: 'sz_live_...',
  protect: ['/auth/*', '/payments'],
  profile: 'strict'
}));

Sentinel is a high-velocity decision engine designed to render sub-50ms trust decisions for API traffic at the network edge. It replaces user-hostile CAPTCHAs with infrastructure forensics and cryptographic Proof-of-Work, blocking automated attacks without ever interrupting a legitimate user.

Core Architecture

Sentinel operates on a Zero-Friction, Zero-Trust philosophy using three distinct layers of defense:

Agentic Security & AI Governance

Traditional "Human-only" filters are too binary. Sentinel's agentic profile allows you to categorize traffic into three tiers:

• Verified Human: Full access to high-compute resources.
• Verified Agent: Limited access (cached content, text-only responses, zero-DB access).
• Malicious Bot: Hard rejection.

Global Edge Enforcement

For high-traffic applications, Sentinel offers a specialized Edge Adapter that moves enforcement to the CDN layer. This reduces decision latency from >50ms to **under 5ms** by using local Key-Value caches.

import { sentinelEdge } from 'api-turnstile';

export default {
  async fetch(request, env, ctx) {
    const shield = sentinelEdge({
      apiKey: env.SENTINEL_KEY,
      cache: env.SENTINEL_KV, // Cloudflare KV Namespace
      protect: ['/v1/*'],
      cacheTtl: 300 // 5-minute local cache
    });

    const blockResponse = await shield(request, ctx);
    if (blockResponse) return blockResponse;

    return await fetch(request);
  }
};

Quick Start

Integrate Sentinel in minutes using our official adapter for Express, Fastify, or Next.js.

npm install api-turnstile

Initialize the middleware with your Vector API key and specify the routes you want to protect.

import { sentinel } from 'api-turnstile';
import express from 'express';

const app = express();

app.use(sentinel({
  apiKey: process.env.SENTINEL_KEY,
  protect: ['/api/auth/*', '/v1/payments'],
  profile: 'api'
}));

Framework Integration

Sentinel provides first-class support for popular Node.js frameworks.

Configuration Deep Dive

The SentinelConfig object allows for granular control over enforcement and fallback strategies.

Protection Modes

Each protected path can run in one of three modes:

• monitor: Passively logs traffic. Useful for profiling before enforcement.
• balanced: Standard protection. Blocks high-confidence automated threats.
• strict: Zero tolerance. Blocks any suspicious signal including VPNs and datacenters.

Behavioral Work Tokens (BWT)

BWT is our proprietary extension of Proof-of-Work (PoW) that couples cryptographic difficulty with physical human interaction. This ensures that even "smart" bots with GPU clusters cannot scale their attacks because the cost of simulation exceeds the value of the target.

Verification Lifecycle

Implementing Sentinel's behavioral gate follows a deterministic three-stage lifecycle. This is standard for all high-security integrations.

POST /v1/challenge/issue
{ "target": "client_ip", "duration": 2.0 }

POST /v1/challenge/verify
{ "target": "client_ip", "nonce": "SOLVED_NONCE" }

// RESPONSE
{ "success": true, "trust_token": "..." }

Security Profiles

Profiles allow you to tune the engine sensitivity based on the business value of the endpoint.

CLI & Forensics

Analyze your traffic and investigate suspicious IPs directly from your terminal.

# Install the CLI
npm install -g api-turnstile

# Tail live traffic decisions
sentinel tail --key YOUR_API_KEY

# Forensic audit of an IP
sentinel check 1.2.3.4

Frontend Widget

For high-risk interactions like signups or payments, you can add an interactive behavioral challenge to your frontend. The Sentinel Widget requires users to demonstrate "Proof of Intent" through a controlled interaction that bots cannot easily replicate.

1. Implementation

Include the Sentinel client script and add the target element where you want the widget to appear.

<!-- 1. Add the target element -->
<div id="sentinel-widget" data-sitekey="YOUR_PROJECT_KEY"></div>

<!-- 2. Include the widget script -->
<script src="https://sentinel.risksignal.name.ng/widget.js" async defer></script>

2. Handling Verification

When the user successfully completes the challenge, the widget fires a sentinelSuccess event and automatically injects a hidden input named sentinel-token if it resides within a form.

document.addEventListener('sentinelSuccess', (event) => {
  const { trust_token } = event.detail;
  console.log('Verified!', trust_token);
  
  // Optional: Manually submit or enable your submit button
  document.getElementById('submit-btn').disabled = false;
});

app.use(sentinel({
  apiKey: process.env.SENTINEL_KEY,
  verifyToken: true,             // Enable automatic widget token detection
  trustTokenField: 'sentinel-token', // Custom field name (Optional)
  onBlock: (req, res, decision) => {
    return res.status(403).json({ error: "High-risk session. Please complete verification." });
  }
}));

# Example: Python / Flask
import requests

def verify_sentinel(token, ip):
    res = requests.post(
        "https://sentinel.risksignal.name.ng/v1/challenge/verify",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"target": ip, "nonce": token} # Use 'nonce' for token check
    )
    return res.json().get("success")

API Reference

{
  "target": "185.123.45.6",    // Target IP
  "profile": "signup",         // Security profile
  "privacy_mode": "full"       // strict | full
}

{
  "allow": false,
  "action": "block",
  "risk": "untrusted",
  "reason": "vpn_detection_confirmed",
  "confidence": 0.99,
  "latency_ms": 14,
  "remediation": {
     "widget_required": true
  }
}

Challenge API Reference

The Challenge API powers the interactive behavioral verification system.

// Node.js Example
const sentinelToken = req.headers['x-sentinel-trust'];

// The middleware handles this automatically, but for manual validation:
const isValid = await sentinel.verifyToken(sentinelToken, clientIp);
if (!isValid) return res.status(403).send("Behavioral Proof Required");