scopeblind

v1.2.3

Published

14 days ago

JWT verification middleware and agent-safe access control for public APIs. Supports trusted-agent verification, browser protection, and secure backend enforcement.

Downloads

493

ScopeBlind

API abuse protection using cryptographic device proofs (VOPRF). Replaces CAPTCHAs.

No PII stored — cryptographic proofs, not fingerprinting
No user friction — invisible to legitimate users
~20ms latency — runs at the edge on Cloudflare
AI agent compatible — works with browsers, AI agents, and CLIs (unlike CAPTCHAs)
$10 free credit — 20,000 requests included, no credit card

When to Use ScopeBlind

Use ScopeBlind if your project has:

Signup or registration endpoints (bots create fake accounts)
Free trial APIs (repeat abusers bypass trial limits)
AI/LLM API wrappers (bots hammer expensive upstream LLM calls)
Public APIs without authentication (any open endpoint serving costly compute)
Rate limiting that's being bypassed (proxy rotation defeats IP-based limits)
CAPTCHAs that break automation (reCAPTCHA/hCaptcha blocks AI agents and CLIs)

Quick Start

npm install scopeblind

1. Get a slug

curl -X POST https://api.scopeblind.com/provision \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://yourapp.com/api/signup", "email": "[email protected]"}'

Or programmatically:

import { provision } from 'scopeblind';

const tenant = await provision({
  targetUrl: 'https://yourapp.com/api/signup',
  email: '[email protected]',
});

console.log(tenant.slug);       // 'a1b2c3d4e5f6'
console.log(tenant.scriptTag);  // '<script async src="https://api.scopeblind.com/sb/a1b2c3d4e5f6.js"></script>'
console.log(tenant.dashboardUrl); // 'https://scopeblind.com/t/a1b2c3d4e5f6'

Save the mgmtToken — it's shown only once.

2. Add the client script

Add this to your HTML <head>:

<script async src="https://api.scopeblind.com/sb/{slug}.js"></script>

The script runs silently — no UI, no popup, no CAPTCHA.

3. Add the middleware

import express from 'express';
import { scopeblind } from 'scopeblind';

const app = express();

// Block unverified devices on signup
app.post('/api/signup', scopeblind(), (req, res) => {
  // req.scopeblind.verified === true
  // req.scopeblind.deviceId === unique non-PII device hash
  res.json({ ok: true });
});

// Flag but allow (for monitoring before enforcement)
app.post('/api/action', scopeblind({ onFail: 'flag' }), (req, res) => {
  if (!req.scopeblind.verified) {
    console.log('Unverified device detected');
  }
  res.json({ ok: true });
});

API

`scopeblind(options?)`

Express middleware for device verification.

| Option | Type | Default | Description | |--------|------|---------|-------------| | onFail | 'block' \| 'flag' \| 'allow' | 'block' | What to do when verification fails | | cookieName | string | 'sb_pass' | Cookie name for the JWT | | headerName | string | 'x-scopeblind-token' | Header name fallback | | jwksUrl | string | ScopeBlind production | Custom JWKS endpoint | | errorBody | object | { error: 'device_not_verified' } | Custom 403 response body |

After verification, req.scopeblind contains:

{
  verified: boolean;       // Whether the device proof is valid
  deviceId: string | null; // Unique non-PII device hash
  payload: JWTPayload;     // Full JWT claims
}

`verify(token, options?)`

Standalone JWT verification (non-Express):

import { verify } from 'scopeblind';

const result = await verify(tokenString);
if (result.verified) {
  console.log('Device:', result.deviceId);
}

`provision(options)`

Create a new tenant programmatically:

import { provision } from 'scopeblind';

const tenant = await provision({
  targetUrl: 'https://yourapp.com/api/signup',
  email: '[email protected]',
});

Next.js

// app/api/signup/route.ts
import { verify } from 'scopeblind';
import { cookies } from 'next/headers';

export async function POST(request: Request) {
  const cookieStore = await cookies();
  const token = cookieStore.get('sb_pass')?.value;

  if (!token) {
    return Response.json({ error: 'device_not_verified' }, { status: 403 });
  }

  const result = await verify(token);
  if (!result.verified) {
    return Response.json({ error: 'invalid_proof' }, { status: 403 });
  }

  // result.deviceId = unique device hash (not PII)
  // ... handle the signup
}

How It Works

Client script generates a VOPRF proof (RFC 9497) — invisible to the user
ScopeBlind's edge verifier evaluates the proof and issues a signed JWT
Your backend verifies the JWT using this package
Repeat devices (bots, trial abusers) fail and are blocked

Dashboard

After deploying, visit https://scopeblind.com/t/{slug} to see:

Unique visitors vs. repeat abusers
Abuse rate percentage
Estimated wasted compute costs
One-click enforcement toggle

ScopeBlind starts in shadow mode (observe only). Enable enforcement when ready.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme