api-turnstile 0.1.7 → 0.1.9

package/README.md

@@ -1,35 +1,52 @@
-# API Turnstile — CAPTCHA-Free API Bot Protection & Abuse Prevention
+# API Turnstile (Sentinel) — Turnstile for APIs
 
 <div align="center">
   <img src="https://sentinel.risksignal.name.ng/sentinel-logo.png" alt="Sentinel Logo" width="120" />
-  <h3>Turnstile for API</h3>
+  <h3>Your APIs are being abused. You just don't see it yet.</h3>
   <p>Cloudflare Turnstile protects browsers. <b>Sentinel protects APIs.</b></p>
   <p>
     <a href="https://www.npmjs.com/package/api-turnstile"><img src="https://img.shields.io/npm/v/api-turnstile?color=orange&style=flat-square" alt="NPM Version" /></a>
-    <a href="https://github.com/00xf5/sentinelapinpm/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/api-turnstile?style=flat-square" alt="MIT License" /></a>
     <a href="https://sentinel.risksignal.name.ng"><img src="https://img.shields.io/badge/latency-<50ms-green?style=flat-square" alt="Latency" /></a>
   </p>
 </div>
 
 ---
 
-> **The first line of defense for modern APIs.**  
-> **Block bots, scripts, credential stuffing, and automation attacks — without rate limits or CAPTCHAs.**  
-> **API Turnstile is a high-velocity decision engine built specifically to protect API endpoints at the network edge.**
+**Sentinel** is a high-velocity deterministic trust layer for modern APIs. It stops automated abuse, credential stuffing, and fake signups by analyzing **Infrastructure DNA** and enforcing **Behavioral Work Tokens** without ever showing a CAPTCHA to a human.
 
-## What Is API Turnstile?
+## 🚫 Problems We Stop
+- **Signup Flooding**: Thousands of fake accounts hitting your database.
+- **Credential Stuffing**: Automated login attempts using leaked passwords.
+- **API Scraping**: Competitors or AI agents draining your proprietary data.
+- **Ghost Traffic Tax**: Unnecessary AWS/Cloud compute costs from non-human traffic.
 
-API Turnstile (Sentinel) is a deterministic trust layer for APIs. Unlike traditional WAFs that rely on static IP blocklists or user-hostile CAPTCHAs, Sentinel uses **Infrastructure Forensics** and **Behavioral Work Tokens (BWT)** to differentiate between legitimate users and automated scripts in real-time.
+## ⚡ Global Edge Enforcement
+Sentinel is built for the internet's edge. Deploy as a standard Node.js middleware or a **Global Edge Guard** on Cloudflare Workers / Vercel Edge.
 
-It allows you to maintain a frictionless user experience while effectively blocking 99.9% of automated threats, including sophisticated headless browsers and residential proxy rotation.
+- **Fast-Path Matrix**: Instant identification of hosting/proxy infrastructure.
+- **Edge Cache Support**: Sub-2ms rejection using Cloudflare KV or Vercel Edge Config.
+- **Agentic Governance**: Specific profiles to identify and throttle AI Agents vs Humans.
 
-## Architecture
+### Example: Cloudflare Worker Edge Enforcement
+```typescript
+import { sentinelEdge } from 'api-turnstile';
 
-Sentinel operates on a three-tier defense matrix:
+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
+    });
 
-1.  **Fast-Path Matrix (< 20ms)**: Instant vetting against a global ASN/IP reputation matrix (OVH, Hetzner, DigitalOcean, etc.).
-2.  **Behavioral Work Tokens (BWT)**: A cryptographic challenge-response system that escalatesPoW difficulty for suspicious IPs.
-3.  **Infrastructure Forensics**: Deep analysis of request signatures to detect Puppeteer, Playwright, curl, and VPN/Proxy masking.
+    const blockResponse = await shield(request, ctx);
+    if (blockResponse) return blockResponse;
+
+    return await fetch(request);
+  }
+};
+```
 
 ---
 
@@ -128,6 +145,18 @@ Sentinel profiles tune the engine's heuristics based on the endpoint's value:
 | **`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. |
+
+### Using the Agentic Profile
+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'
+}));
+```
 
 ---
 
@@ -188,6 +217,11 @@ BWT is our proprietary adaptive PoW system. When Sentinel identifies an "Unstabl
 - **Cloud Runtime**: Vercel Edge, Cloudflare Workers, AWS Lambda.
 - **Database**: Zero external DB dependencies (Decision Engine is managed).
 
+## Related
+
+- [Sentinel API Security Platform](https://sentinel.risksignal.name.ng) — Managed API bot protection
+- [Why CAPTCHAs Fail for APIs](https://sentinel.risksignal.name.ng/blog/captchas-fail-for-apis)
+
 ## License
 
 MIT © [Sentinel Security](https://sentinel.risksignal.name.ng)

package/dist/edge/adapter.d.ts

@@ -0,0 +1,25 @@
+import { SentinelConfig } from '../types';
+/**
+ * Cloudflare Worker / Vercel Edge Adapter Options
+ */
+export interface EdgeAdapterOptions extends SentinelConfig {
+    /**
+     * KV Namespace (for Cloudflare) or reference to Edge Config (for Vercel)
+     */
+    cache?: {
+        get: (key: string) => Promise<string | null>;
+        put: (key: string, value: string, options?: {
+            expirationTtl: number;
+        }) => Promise<void>;
+    };
+    /**
+     * Cache TTL in seconds (default: 300 / 5 minutes)
+     */
+    cacheTtl?: number;
+}
+/**
+ * Sentinel Edge Adapter (Cloudflare Workers / Vercel Edge Runtime)
+ * Optimized for sub-5ms local enforcement using KV/Edge caches.
+ */
+export declare const sentinelEdge: (options: EdgeAdapterOptions) => (request: Request, context?: any) => Promise<import("undici-types").Response | null>;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/edge/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/edge/adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAoB,MAAM,UAAU,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACtD;;OAEG;IACH,KAAK,CAAC,EAAE;QACJ,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QAC7C,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;YAAE,aAAa,EAAE,MAAM,CAAA;SAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC3F,CAAC;IACF;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,kBAAkB,MAUtC,SAAS,OAAO,EAAE,UAAU,GAAG,oDAkFhD,CAAC"}

package/dist/edge/adapter.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sentinelEdge = void 0;
+const sentinel_1 = require("../client/sentinel");
+/**
+ * Sentinel Edge Adapter (Cloudflare Workers / Vercel Edge Runtime)
+ * Optimized for sub-5ms local enforcement using KV/Edge caches.
+ */
+const sentinelEdge = (options) => {
+    const client = new sentinel_1.SentinelClient(options.apiKey, options.endpoint, options.timeout, options.debug);
+    const ttl = options.cacheTtl || 300;
+    return async (request, context) => {
+        const url = new URL(request.url);
+        const path = url.pathname;
+        // Path checking logic (simplified for edge)
+        const isProtected = (p) => {
+            if (Array.isArray(options.protect)) {
+                return options.protect.some(pattern => {
+                    if (pattern === p)
+                        return true;
+                    if (pattern.endsWith('*'))
+                        return p.startsWith(pattern.slice(0, -1));
+                    return false;
+                });
+            }
+            return !!options.protect[p];
+        };
+        if (!isProtected(path))
+            return null;
+        // Resolve IP
+        const ip = request.headers.get('cf-connecting-ip') ||
+            request.headers.get('x-real-ip') ||
+            request.headers.get('x-forwarded-for')?.split(',')[0].trim() ||
+            '127.0.0.1';
+        // 1. FAST PATH: Check Edge Cache
+        if (options.cache) {
+            try {
+                const cached = await options.cache.get(`sentinel:verdict:${ip}`);
+                if (cached === 'BLOCK') {
+                    return new Response(JSON.stringify({ error: 'Access Denied', code: 'EDGE_BLOCK' }), {
+                        status: 403,
+                        headers: { 'Content-Type': 'application/json' }
+                    });
+                }
+                if (cached === 'ALLOW')
+                    return null;
+            }
+            catch (err) {
+                if (options.debug)
+                    console.error('[Sentinel Edge] Cache Read Error:', err);
+            }
+        }
+        // 2. PRIMARY CHECK
+        try {
+            const decision = await client.check({
+                target: ip,
+                profile: options.profile || 'api',
+                trustToken: request.headers.get('x-sentinel-trust') || undefined
+            });
+            // Update Cache Asynchronously
+            if (options.cache && context?.waitUntil) {
+                context.waitUntil(options.cache.put(`sentinel:verdict:${ip}`, decision.allow ? 'ALLOW' : 'BLOCK', { expirationTtl: ttl }).catch(() => { }));
+            }
+            if (!decision.allow) {
+                return new Response(JSON.stringify({
+                    error: 'Access Denied',
+                    reason: decision.reason,
+                    remediation: decision.remediation
+                }), {
+                    status: 403,
+                    headers: { 'Content-Type': 'application/json' }
+                });
+            }
+        }
+        catch (error) {
+            if (options.debug)
+                console.error('[Sentinel Edge] Decision Error:', error);
+            if (options.fail === 'closed') {
+                return new Response(JSON.stringify({ error: 'Security System Unavailable' }), {
+                    status: 403,
+                    headers: { 'Content-Type': 'application/json' }
+                });
+            }
+        }
+        return null;
+    };
+};
+exports.sentinelEdge = sentinelEdge;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { sentinel } from './middleware/express';
 export { sentinelFastify } from './middleware/fastify';
-export { sentinelEdge } from './middleware/next';
+export { sentinelEdge } from './edge/adapter';
 export { sentinelHono } from './middleware/hono';
 export { SentinelClient } from './client/sentinel';
 export type { SentinelConfig, SentinelDecision, SecurityProfile, ProtectionMode, FailStrategy, PathProtection, CheckParams, Verdict } from './types';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGnD,YAAY,EACR,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,cAAc,EACd,WAAW,EACX,OAAO,EACV,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGnD,YAAY,EACR,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,cAAc,EACd,WAAW,EACX,OAAO,EACV,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -6,8 +6,8 @@ var express_1 = require("./middleware/express");
 Object.defineProperty(exports, "sentinel", { enumerable: true, get: function () { return express_1.sentinel; } });
 var fastify_1 = require("./middleware/fastify");
 Object.defineProperty(exports, "sentinelFastify", { enumerable: true, get: function () { return fastify_1.sentinelFastify; } });
-var next_1 = require("./middleware/next");
-Object.defineProperty(exports, "sentinelEdge", { enumerable: true, get: function () { return next_1.sentinelEdge; } });
+var adapter_1 = require("./edge/adapter");
+Object.defineProperty(exports, "sentinelEdge", { enumerable: true, get: function () { return adapter_1.sentinelEdge; } });
 var hono_1 = require("./middleware/hono");
 Object.defineProperty(exports, "sentinelHono", { enumerable: true, get: function () { return hono_1.sentinelHono; } });
 // Export client

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "api-turnstile",
-    "version": "0.1.7",
+    "version": "0.1.9",
     "description": "CAPTCHA-free API bot protection and abuse prevention middleware for Node.js, Express, Next.js, and serverless APIs.",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -16,17 +16,17 @@
     "keywords": [
         "api security",
         "api bot protection",
-        "api abuse prevention",
         "anti bot",
-        "bot protection",
         "captcha free",
         "cloudflare turnstile alternative",
+        "api abuse prevention",
         "credential stuffing",
-        "signup fraud",
-        "rate limiting alternative",
-        "express middleware",
-        "nextjs api",
-        "serverless security"
+        "anti bot middleware",
+        "nodejs security",
+        "waf alternative",
+        "bot detection",
+        "signup protection",
+        "scraping prevention"
     ],
     "author": "Sentinel Security",
     "license": "MIT",
@@ -64,4 +64,4 @@
     "engines": {
         "node": ">=18.0.0"
     }
-}
+}