CAPTCHA-free API bot protection and abuse prevention middleware for Node.js, Express, Next.js, and serverless APIs.
npm install api-turnstile
Cloudflare Turnstile protects browsers. Sentinel protects APIs.
typescript
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/*'],
profile: 'agentic' // Identify & throttle AI Agents
});
const blockResponse = await shield(request, ctx);
if (blockResponse) return blockResponse;
return await fetch(request);
}
};
`
---
Key Features
- Extreme Performance: Sub-50ms decision latency globally.
- Zero Friction: No CAPTCHAs, no puzzles, no interrupted user flows.
- Adaptive Defenses: Automatically scales security based on the risk-score of an incoming request.
- Framework Agnostic: Native middleware for Express, Fastify, Next.js, Hono, and Bun.
- CLI Forensics: Stream live traffic decisions and audit IPs directly from your terminal.
- Outcome-Focused: Designed for Registration Fraud, Account Takeover (ATO), and Scraping Prevention.
---
Installation
`bash
npm install api-turnstile
`
---
Basic Integration
$3
`javascript
import { sentinel } from 'api-turnstile';
import express from 'express';
const app = express();
app.use(sentinel({
apiKey: 'YOUR_SENTINEL_KEY',
protect: ['/api/auth/*', '/v1/payments'],
profile: 'api' // Default profile
}));
`
$3
`typescript
// middleware.ts
import { sentinelEdge } from 'api-turnstile';
export default sentinelEdge({
apiKey: process.env.SENTINEL_KEY,
protect: {
'/api/auth/*': 'strict',
'/api/public/*': 'monitor'
}
});
export const config = {
matcher: '/api/:path*',
};
`
---
Advanced Configuration
The sentinel middleware accepts a SentinelConfig object for granular control.
| Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| apiKey | string | Required | Your Sentinel API key. |
| protect | string[] \| Object | [] | List of paths to protect or a map of path patterns to ProtectionMode. |
| profile | string | 'api' | Sensitivity profile: api, signup, payments, crypto. |
| fail | 'open' \| 'closed' | 'closed' | Fail strategy if API is unreachable. closed blocks access. |
| onBlock | Function | 403 JSON | Custom block handler: (req, res, decision) => void. |
| bwt.enabled | boolean | true | Enable Behavioral Work Tokens (Adaptive PoW). |
| webhooks.onBlock| string | undefined | URL to POST to when an attack is blocked. |
$3
Control how strictly each path is enforced:
- monitor: Passive logging. Never blocks.
- balanced: Defensive mode. Blocks high-confidence automated threats.
- strict: Zero-tolerance. Blocks any suspicious signal including VPNs and Datacenters.
`javascript
protect: {
'/api/public': 'monitor',
'/api/user/*': 'balanced',
'/api/sensitive': 'strict'
}
`
---
Security Profiles
Sentinel profiles tune the engine's heuristics based on the endpoint's value:
| Profile | Focus | Use Case |
| :--- | :--- | :--- |
| api | Velocity | Standard API endpoints, data feeds. |
| signup | Identity | Registration, Login, Forget Password. |
| payments | Integrity | Checkout, Subscription, Payment Method Update. |
| crypto | Pure Trust | Wallets, Faucets, On-Chain interactions. |
| agentic | AI Governance | LLM Agents, Scrapers, Automated Crawlers. |
$3
The agentic profile is designed to differentiate between human users and AI Agents (like GPT-5, Perplexity, etc.). When enabled, Sentinel provides granular signals that allow you to serve "Lite" or "Cached" content to bots while saving expensive compute for humans.
`javascript
app.use(sentinel({
apiKey: '...',
protect: ['/data/*'],
profile: 'agentic'
}));
`
---
Response Formats
$3
Requests that pass Sentinel checks proceed seamlessly to your next middleware.
$3
If a request is blocked, Sentinel returns a detailed forensic response:
`json
{
"error": "Access denied",
"reason": "Headless browser signature detected (Puppeteer/Chrome)",
"remediation": {
"widget_required": false,
"trust_token_eligible": true
}
}
`
---
Sentinel CLI
The package includes a powerful command-line interface for real-time traffic analysis.
`bash
Install CLI globally
npm install -g api-turnstile
Stream live traffic forensic decisions
sentinel tail --key YOUR_API_KEY
Perform an immediate audit on an IP address
sentinel check 1.2.3.4
View security ROI and outcome metrics
sentinel stats
`
---
Behavioral Work Tokens (BWT)
BWT is our proprietary adaptive PoW system. When Sentinel identifies an "Unstable" IP, it scales a cryptographic challenge that must be solved by the client.
1. Legitimate Users: The api-turnstile client (or frontend widget) solves the challenge in ~10-40ms in the background.
2. Bot Scripts: Python, Go, and simple NodeJS scripts fail the challenge as they lack the cryptographic engine required to generate a valid BWT-Nonce`.