api-turnstile 0.1.3 β†’ 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +90 -34
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,58 +1,114 @@
1
- # api-turnstile
1
+ # api-turnstile (Sentinel)
2
2
 
3
- Cloudflare Turnstile protects browsers. Sentinel protects APIs.
4
- Block bots, scrapers, and automated attacks in under 50ms using infrastructure and behavioral signals. No CAPTCHAs required.
3
+ <div align="center">
4
+ <img src="https://sentinel.risksignal.name.ng/sentinel-logo.png" alt="Sentinel Logo" width="120" />
5
+ <h3>The Deterministic Trust Layer for Modern APIs</h3>
6
+ <p>Cloudflare Turnstile protects browsers. <b>Sentinel protects APIs.</b></p>
7
+ <p>
8
+ <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>
9
+ <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>
10
+ <a href="https://sentinel.risksignal.name.ng"><img src="https://img.shields.io/badge/latency-<50ms-green?style=flat-square" alt="Latency" /></a>
11
+ </p>
12
+ </div>
5
13
 
6
- ## Installation
14
+ ---
15
+
16
+ **api-turnstile** is the official Node.js adapter for [Sentinel](https://sentinel.risksignal.name.ng). It provides transparent, high-performance protection for Express, Fastify, Next.js, and Hono APIs.
17
+
18
+ Unlike traditional WAFs or Rate Limiters, Sentinel uses **infrastructure forensics** and **Behavioral Work Tokens (BWT)** to differentiate between legitimate users and automated scripts in real-timeβ€”without ever showing a CAPTCHA.
19
+
20
+ ## πŸš€ Key Features
21
+
22
+ - **⚑ Sub-50ms Latency**: Built on a globally distributed decision engine.
23
+ - **πŸ›‘οΈ Adaptive Defenses**: Automatically escalates cryptographic challenges (BWT) for suspicious IPs.
24
+ - **πŸ”Œ Multi-Framework**: First-class support for Node.js (Express/Fastify) and Edge Runtimes (Next.js/Bun).
25
+ - **πŸ•ΉοΈ CLI Intelligence**: Stream live traffic decisions directly to your terminal with `sentinel tail`.
26
+ - **🎯 Outcome-Based**: Focuses on business results (e.g., bot reduction, capital saved) rather than just "block counts".
27
+
28
+ ## πŸ“¦ Installation
7
29
 
8
30
  ```bash
9
31
  npm install api-turnstile
10
32
  ```
11
33
 
12
- ## Quick Start (Express)
34
+ ## πŸ› οΈ Quick Start
13
35
 
36
+ ### Express / Node.js
14
37
  ```javascript
15
38
  import { sentinel } from 'api-turnstile';
39
+ import express from 'express';
40
+
41
+ const app = express();
16
42
 
17
43
  app.use(sentinel({
18
- apiKey: process.env.SENTINEL_KEY,
19
- protect: ['/login', '/api/*']
44
+ apiKey: 'your_api_key',
45
+ protect: ['/api/v1/auth/*', '/v1/payments'],
46
+ profile: 'api'
20
47
  }));
21
48
  ```
22
49
 
23
- ## Features
50
+ ### Next.js Edge Middleware
51
+ ```javascript
52
+ // middleware.ts
53
+ import { sentinelEdge } from 'api-turnstile/middleware/next';
54
+
55
+ export default sentinelEdge({
56
+ apiKey: process.env.SENTINEL_KEY,
57
+ protect: {
58
+ '/api/auth/*': 'strict',
59
+ '/api/public/*': 'monitor'
60
+ }
61
+ });
62
+ ```
63
+
64
+ ## βš™οΈ Configuration Deep Dive
65
+
66
+ | Option | Type | Default | Description |
67
+ | :--- | :--- | :--- | :--- |
68
+ | `apiKey` | `string` | **Required** | Your Sentinel API key. |
69
+ | `protect` | `string[] \| Object` | `[]` | Paths to protect. Supports wildcards (`*`) and per-path modes. |
70
+ | `profile` | `string` | `'api'` | Protection profile: `api`, `signup`, `payments`, `crypto`. |
71
+ | `fail` | `'open' \| 'closed'` | `'closed'` | Strategy if the Sentinel API is unreachable. |
72
+ | `bwt.enabled` | `boolean` | `true` | Enable Behavioral Work Tokens (Adaptive PoW). |
73
+ | `onBlock` | `function` | Default 403 response | Custom handler for blocked requests. |
74
+
75
+ ### Protection Modes
76
+ - **`monitor`**: Logs activity but never blocks. Ideal for initial onboarding.
77
+ - **`balanced`**: Blocks obvious bots and high-risk signals.
78
+ - **`strict`**: Enforces zero-tolerance for automation and proxy traffic.
79
+
80
+ ## πŸ’» Sentinel CLI
24
81
 
25
- - **Multi-Framework**: Native support for Express, Fastify, Hono, and Bun.
26
- - **Edge Native**: Specialized middleware for Next.js Edge Runtime and Vercel.
27
- - **Sentinel CLI**: Terminal-based monitoring (`sentinel tail`) and forensics.
28
- - **Economic Defenses**: Behavioral Work Tokens (BWT) to increase bot costs.
29
- - **Real-time Alerts**: Webhook notifications for blocked incidents.
82
+ The package includes a powerful CLI for real-time forensics and monitoring.
30
83
 
31
- ## Supported Adapters
84
+ ```bash
85
+ # Install globally
86
+ npm install -g api-turnstile
87
+
88
+ # Stream live decisions in real-time
89
+ sentinel tail --key YOUR_API_KEY
90
+
91
+ # Perform an immediate forensic check on an IP
92
+ sentinel check 1.2.3.4
93
+
94
+ # View security outcomes and ROI stats
95
+ sentinel stats
96
+ ```
32
97
 
33
- | Framework | Middleware |
34
- |-----------|------------|
35
- | Express / Node | `sentinel(config)` |
36
- | Fastify | `sentinelFastify(config)` |
37
- | Hono / Bun | `sentinelHono(config)` |
38
- | Next.js Edge | `sentinelEdge(config)` |
98
+ ## 🧠 Behavioral Work Tokens (BWT)
39
99
 
40
- ## Configuration
100
+ BWT is Sentinel's secret weapon. When an IP is deemed "unstable" (not yet high-risk enough to block), Sentinel issues a cryptographic challenge.
41
101
 
42
- | Option | Description |
43
- |--------|-------------|
44
- | `apiKey` | Your API key from the dashboard |
45
- | `protect` | Array of paths or path-to-mode mapping |
46
- | `profile` | Security profile (`api`, `signup`, `payments`, `crypto`) |
47
- | `webhooks` | Optional URL for block notifications |
48
- | `fail` | Strategy if API is down (`open`, `closed`) |
102
+ 1. Legitimate clients (using this SDK) solve the challenge in the background (~5ms overhead).
103
+ 2. Bot scripts (Headless Chrome, curl, python-requests) fail to solve the token.
104
+ 3. Your server rejects the request before it ever hits your business logic.
49
105
 
50
- ## Links
106
+ ## πŸ”— Links
51
107
 
52
- - [Dashboard & API Keys](https://sentinel.risksignal.name.ng)
53
- - [Full Documentation](https://sentinel.risksignal.name.ng/docs)
54
- - [GitHub Repository](https://github.com/00xf5/sentinelapinpm)
108
+ - **[Dashboard & API Management](https://sentinel.risksignal.name.ng)**
109
+ - **[Documentation](https://sentinel.risksignal.name.ng/docs)**
110
+ - **[GitHub Repository](https://github.com/00xf5/sentinelapinpm)**
55
111
 
56
- ## License
112
+ ## πŸ“„ License
57
113
 
58
- MIT
114
+ MIT Β© [Sentinel Security](https://sentinel.risksignal.name.ng)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "api-turnstile",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
4
  "description": "Cloudflare Turnstile protects browsers β€” not APIs. Sentinel is a Turnstile for APIs. Block bots, scripts, and automation without CAPTCHAs.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",