io.github.tomjwxf/scopeblind-mcp
Scan, protect, and monitor APIs from AI coding tools. Device-level rate limiting.
Ask AI about io.github.tomjwxf/scopeblind-mcp
Powered by Claude Β· Grounded in docs
I know everything about io.github.tomjwxf/scopeblind-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
ScopeBlind Gateway
Source-available under the Functional Source License (FSL-1.1-MIT). You may use, modify, and self-host this freely for your own projects or internal company use. You may not offer ScopeBlind (or a substantially similar service) as a hosted/managed product to third parties. After 2 years, each version automatically converts to the MIT license. For zero-ops managed hosting with real-time abuse intelligence, use scopeblind.com.
Drop-in gateway protection for public APIs using ScopeBlind pass-token verification.
ScopeBlind helps public APIs let trusted agents through, challenge unknown traffic privately, and stop repeat abuse without CAPTCHA friction or invasive tracking. This gateway is the secure-mode deployment path.
The browser script starts observation and access decisions. The gateway is the real security boundary for protected APIs.
When to Use This Gateway
Use this repo when:
- you want stricter protection than client-side observe mode alone
- your API can be called directly (bots can skip the browser)
- you want edge enforcement before requests hit your origin
- you want to verify ScopeBlind pass tokens without adding SDK code to every service
Quick Start
# 1. Clone and install
git clone https://github.com/tomjwxf/scopeblind-gateway.git
cd scopeblind-gateway
npm install
# 2. Edit wrangler.toml:
# - ORIGIN_URL = "https://your-api.com"
# - SCOPEBLIND_AUDIENCE = "YOUR_SLUG"
# - SCOPEBLIND_JWKS_URL = "https://api.scopeblind.com/.well-known/jwks.json"
# (get your slug by scanning your endpoint at scopeblind.com)
# 3. Deploy
npx wrangler deploy
Your gateway is now live at scopeblind-gateway.<your-account>.workers.dev.
Point protected API traffic at the gateway URL instead of your origin. Requests with valid ScopeBlind pass tokens are forwarded. Requests without valid tokens are either logged (observe mode) or blocked (enforce mode).
What Observe Mode Does
Observe mode is the default. It never blocks anything β it measures what would happen if secure enforcement were enabled.
Every protected request (POST, PUT, DELETE, PATCH by default) is checked for a ScopeBlind pass token:
- browser traffic usually sends it via the
sb_passcookie - API-only or agent traffic can send it via the
X-ScopeBlind-Tokenheader
| Scenario | Observe Mode | Enforce Mode |
|---|---|---|
| No token | β
Forward + log would-block | β 403 Rejected |
| Invalid / expired token | β
Forward + log would-block | β 403 Rejected |
| Valid token | β
Forward + log verified | β Forward |
| JWKS verification unavailable | β
Forward + log fallback-allow | Depends on FALLBACK_MODE |
GET requests pass through by default.
Reading Observe Mode Logs
npx wrangler tail --format json | jq 'select(.logs[]?.message | contains("_scopeblind"))'
Every log entry includes:
action:missing_token,invalid_token, orverifiedmethod: HTTP methodpath: request pathts: ISO timestamp
After a few days, you will know exactly how much direct API traffic would fail secure-mode verification.
Health Check
curl https://scopeblind-gateway.<you>.workers.dev/_scopeblind/health
Returns:
{
"ok": true,
"mode": "observe",
"origin": "https://your-api.com",
"audience": "your-slug",
"jwks": "https://api.scopeblind.com/.well-known/jwks.json"
}
Configuration
All config lives in wrangler.toml:
| Variable | Description |
|---|---|
ORIGIN_URL | Your backend API URL |
SCOPEBLIND_AUDIENCE | Your tenant slug (expected JWT aud) |
SCOPEBLIND_JWKS_URL | JWKS endpoint for EdDSA pass-token verification |
OBSERVE_MODE | "true" = log only, "false" = enforce |
PROTECTED_METHODS | Comma-separated methods to protect |
FALLBACK_MODE | "open" = allow if verification infra is down, "closed" = reject |
Legacy SHADOW_MODE is still supported for older deployments, but new installs should use OBSERVE_MODE.
How It Works
Client -> ScopeBlind decision flow -> pass token issued
|
v
Client -> Cloudflare Edge -> [ScopeBlind Gateway] -> Your API
- ScopeBlind decides whether to allow, challenge, pay, or deny
- Allowed requests receive a signed pass token (
sb_passcookie orX-ScopeBlind-Tokenheader) - This gateway verifies the token against the public JWKS endpoint
- Valid requests are forwarded to your origin with
X-ScopeBlind-*metadata headers - Missing or invalid tokens are logged in observe mode or rejected in enforce mode
Headers forwarded to your origin:
X-ScopeBlind-Mode:observeorenforceX-ScopeBlind-Verified:true,missing,invalid,error, orskippedX-ScopeBlind-Subject: tenant-scoped device hash from the JWTX-ScopeBlind-Agent:trueif token came from the agent fast-laneX-ScopeBlind-Expires: JWT expiry timestampX-ScopeBlind-JTI: JWT ID (for replay-sensitive origin logic if needed)
The gateway strips sb_pass and X-ScopeBlind-Token before forwarding so your origin does not need to handle raw ScopeBlind credentials.
Switching to Enforcement
When your observe-mode data confirms the pattern, switch to strict enforcement:
OBSERVE_MODE = "false"
npx wrangler deploy
Now protected requests without a valid ScopeBlind pass token are blocked at the edge before they hit your backend.
What This Repo Does Not Do
This gateway does not issue tokens or run the challenge flow itself. That still happens in ScopeBlind's browser/agent path. This repo is the enforcement layer for APIs that need a clean edge boundary.
It also does not implement the future payment-required branch yet. When ScopeBlind later returns machine-readable payment options for over-quota traffic, that logic belongs on the protected resource path above this gateway.
License
FSL-1.1-MIT β source-available now, converts to MIT after 2 years. See LICENSE.
