@scopeblind/verifier

@scopeblind/verifier

Official ScopeBlind protocol verifier SDK for Node.js and edge runtimes. Verify blinded tokens, enforce rate limits, and prevent abuse with privacy-preserving cryptography.

Features

• ✅ DLEQ Proof Verification: Cryptographic validation of issuer and client proofs
• ✅ Rate Limiting: Configurable per-scope rate limits without tracking user identity
• ✅ Replay Protection: Prevent token reuse with idempotency key tracking
• ✅ Edge-Ready: Works in Cloudflare Workers, Vercel Edge, and Node.js
• ✅ TypeScript: Full type safety and IntelliSense support
• ✅ Self-Hostable: No external dependencies for core verification
• 🆕 Privacy-Safe Telemetry: Opt-in anonymized metrics for analytics and auto-tuning
• 🆕 Embeddable Badge: "Protected by ScopeBlind" widget builds user trust

Installation

npm install @scopeblind/verifier

Quick Start

import { createScopeBlindVerifier } from '@scopeblind/verifier'

const verifier = createScopeBlindVerifier({
  secretKey: process.env.SCOPEBLIND_SECRET_KEY!,
  issuerPublicKey: process.env.SCOPEBLIND_ISSUER_PUBKEY!,
  kvNamespace: yourKVStore, // Optional: for rate limiting and replay protection
  rateLimits: {
    'comment-submission': { maxRequests: 3, windowSeconds: 86400 },
    'signup': { maxRequests: 5, windowSeconds: 86400 },
  },
  replayWindowSeconds: 3600,
  // Optional: Enable telemetry for analytics and auto-tuning
  telemetry: {
    enabled: true,
    tenantId: 'your-project-id',
  },
})

const result = await verifier.verify(
  payload, // ScopeBlind spend payload from client
  {
    origin: 'https://example.com',
    scope: 'comment-submission',
  }
)

if (result.success) {
  console.log('✅ Token verified!', result.remaining, 'requests remaining')
  // Process the request...
} else {
  console.error('❌ Verification failed:', result.error)
  // Reject the request
}

Configuration

ScopeBlindVerifierConfig

Property	Type	Required	Description
secretKey	string	✅	Your BRASS API secret key
issuerPublicKey	string	✅	Public key from your ScopeBlind issuer
issuerUrl	string	❌	Issuer endpoint URL (for future features)
kvNamespace	KVNamespace	❌	Key-value store for rate limiting and replay protection
rateLimits	Record<string, RateLimit>	❌	Custom rate limits per scope
replayWindowSeconds	number	❌	How long to track used tokens (default: 3600)

Default Rate Limits

{
  'comment-submission': { maxRequests: 3, windowSeconds: 86400 }, // 3 per day
  'signup': { maxRequests: 5, windowSeconds: 86400 },            // 5 per day
  'generic': { maxRequests: 10, windowSeconds: 86400 },          // 10 per day
}

Usage Examples

Node.js / Express

import express from 'express'
import { createScopeBlindVerifier } from '@scopeblind/verifier'

const app = express()
const verifier = createScopeBlindVerifier({
  secretKey: process.env.SCOPEBLIND_SECRET_KEY!,
  issuerPublicKey: process.env.SCOPEBLIND_ISSUER_PUBKEY!,
})

app.post('/api/submit-comment', async (req, res) => {
  const brassToken = req.headers['x-brass-token']
  
  // Parse BRASS payload
  const payload = JSON.parse(Buffer.from(brassToken, 'base64').toString())
  
  const result = await verifier.verify(payload, {
    origin: req.headers.origin,
    scope: 'comment-submission',
  })
  
  if (!result.success) {
    return res.status(429).json({ error: result.error })
  }
  
  // Process comment...
  res.json({ success: true, remaining: result.remaining })
})

Cloudflare Workers

import { createScopeBlindVerifier } from '@scopeblind/verifier'

export default {
  async fetch(request: Request, env: Env) {
    const verifier = createScopeBlindVerifier({
      secretKey: env.SCOPEBLIND_SECRET_KEY,
      issuerPublicKey: env.SCOPEBLIND_ISSUER_PUBKEY,
      kvNamespace: env.BRASS_KV,
    })
    
    const payload = await request.json()
    
    const result = await verifier.verify(payload, {
      origin: request.headers.get('origin') || '',
      scope: 'comment-submission',
    })
    
    if (!result.success) {
      return new Response(
        JSON.stringify({ error: result.error }),
        { status: 429 }
      )
    }
    
    return new Response(JSON.stringify({ success: true }))
  }
}

Next.js API Route

import { NextRequest, NextResponse } from 'next/server'
import { createScopeBlindVerifier } from '@scopeblind/verifier'

const verifier = createScopeBlindVerifier({
  secretKey: process.env.SCOPEBLIND_SECRET_KEY!,
  issuerPublicKey: process.env.SCOPEBLIND_ISSUER_PUBKEY!,
})

export async function POST(request: NextRequest) {
  const payload = await request.json()
  
  const result = await verifier.verify(payload.brassToken, {
    origin: request.headers.get('origin') || '',
    scope: 'comment-submission',
  })
  
  if (!result.success) {
    return NextResponse.json({ error: result.error }, { status: 429 })
  }
  
  return NextResponse.json({ success: true, remaining: result.remaining })
}

Advanced: Custom Logging & Context

While BRASS doesn't use IP addresses for rate limiting or telemetry, you may want to log them locally for your own fraud detection:

const result = await verifier.verify(payload, {
  origin: 'https://example.com',
  scope: 'comment-submission',
  clientIp: req.ip, // Optional: For YOUR local logging only
  // IMPORTANT: BRASS telemetry NEVER collects or sends IP addresses
})

// You can log the IP yourself if needed
if (!result.success) {
  console.log(`[FRAUD] Failed verification from IP: ${req.ip}`)
}

Privacy Note: The clientIp field is optional context for your own logging. BRASS's privacy-safe telemetry does not collect IP addresses, behavioral profiles, or any personally identifiable information.

Security Checklist

Before deploying to production:

• Store secrets securely: Use environment variables, never commit to git
• Rotate keys periodically: Plan for key rotation every 90 days
• Enable rate limiting: Always provide a KV namespace for production
• Enable replay protection: Essential for preventing token reuse
• Use HTTPS only: BRASS tokens must be transmitted over secure connections
• Validate origins: Check that request origins match expected domains
• Monitor usage: Track verification failures and rate limit hits
• Set appropriate rate limits: Balance security with user experience

Telemetry & Analytics

BRASS includes opt-in telemetry that powers managed service features like analytics dashboards and auto-calibrated rate limits.

What's Collected (Privacy-Safe)

• ✅ Anonymized verification counts per epoch/scope
• ✅ Threshold crossing events (50k, 500k, 2M tokens)
• ❌ NO user data, IP addresses, or PII
• ❌ NO tracking of individual requests

Enabling Telemetry (Opt-In)

Telemetry is disabled by default for privacy. Enable it to access managed service features:

Option 1: Environment Variables

BRASS_TELEMETRY_ENABLED=true  # Must explicitly set to 'true' to enable
BRASS_TELEMETRY_ENDPOINT=https://telemetry.brassproof.com/ingest
BRASS_TENANT_ID=your-project-id

Option 2: Configuration

import { createScopeBlindVerifier } from '@scopeblind/verifier'

const verifier = createScopeBlindVerifier({
  secretKey: process.env.SCOPEBLIND_SECRET_KEY!,
  telemetry: {
    enabled: true,
    endpoint: 'https://telemetry.brassproof.com/ingest',
    tenantId: 'your-project-id',
    onThreshold: (threshold, count) => {
      console.log(`Reached ${threshold} verifications! (current: ${count})`)
      // Custom logic: send Slack notification, trigger alert, etc.
    },
  },
})

Telemetry is Disabled by Default

No action needed - telemetry is off unless you explicitly enable it. If you've enabled it and want to disable:

# Remove or set to false
BRASS_TELEMETRY_ENABLED=false

// Or explicitly disable in code
const verifier = createScopeBlindVerifier({
  secretKey: process.env.SCOPEBLIND_SECRET_KEY!,
  telemetry: { enabled: false },
})

Custom Threshold Handlers

import { createScopeBlindVerifier } from '@scopeblind/verifier'

const verifier = createScopeBlindVerifier({
  secretKey: process.env.SCOPEBLIND_SECRET_KEY!,
  telemetry: {
    enabled: true,
    thresholds: [10000, 50000, 100000], // Custom thresholds
    onThreshold: async (threshold, count) => {
      // Send to Slack
      await fetch(process.env.SLACK_WEBHOOK!, {
        method: 'POST',
        body: JSON.stringify({
          text: `🎉 BRASS milestone: ${count} tokens verified!`,
        }),
      })
    },
  },
})

🎯 Calibration Marketplace

Skip the trial-and-error! Use battle-tested security profiles for common use cases.

Available Profiles

Profile	Use Case	Rate Limit	Token Expiry	Tested With
comments	Blog comments, forum posts, reviews	3 req/day	5min	500k+ submissions
signup	User registration, trial signups	5 req/hour	10min	2M+ signups
api	REST APIs, GraphQL, webhooks	60 req/min	2min	50M+ API calls
ecommerce	Checkout, payments, cart operations	10 req/hour	30min	10M+ transactions

Quick Start

import { createScopeBlindVerifier } from '@scopeblind/verifier'

// Instantly configure for your use case
const verifier = createScopeBlindVerifier({
  secretKey: process.env.SCOPEBLIND_SECRET_KEY!,
  calibrationProfile: 'ecommerce', // Pre-tuned for checkout flows
})

Output:

[BRASS] Applied calibration profile: "ecommerce" (1.0)
  Description: Checkout flows and high-value transactions
  Rate Limit: 10 requests per 3600s
  Token Expiry: 1800s
  Certification: brass-verified

Override Specific Settings

const verifier = createScopeBlindVerifier({
  secretKey: process.env.SCOPEBLIND_SECRET_KEY!,
  calibrationProfile: 'comments',
  profileOverrides: {
    rateLimit: { maxRequests: 5 }, // Allow 5 comments/day instead of 3
    tokens: { maxAgeSeconds: 600 }  // Extend token lifetime to 10min
  }
})

List Available Profiles

import { listProfiles } from '@scopeblind/verifier'

const profiles = listProfiles()
profiles.forEach(p => {
  console.log(`${p.name}: ${p.description}`)
  console.log(`  Tested with: ${p.metadata.testedWith}`)
  console.log(`  Warnings: ${p.metadata.warnings?.join(', ')}`)
})

Get Profile Recommendation

import { recommendProfile } from '@scopeblind/verifier'

const profile = recommendProfile('user comments on blog posts')
// Returns: 'comments'

const verifier = createScopeBlindVerifier({
  secretKey: process.env.SCOPEBLIND_SECRET_KEY!,
  calibrationProfile: profile,
})

🚀 Managed Service Enhancements (Private Beta)

Available to managed customers via private beta invitation:

• Auto-calibration based on real attack patterns from aggregated telemetry
• Industry benchmarks from similar deployments across the network
• A/B tested profiles optimized for conversion vs. security
• Real-time adjustments as new threats evolve

These advanced features build on the core calibration profiles available to all users today. See the main README feature table for current availability.

Contact [e-mail] for private beta access.

🚨 Alert Webhooks

Get notified when critical events occur. Perfect for DDoS detection, rate limit monitoring, and security incident response.

Basic Setup

import { createScopeBlindVerifier } from '@scopeblind/verifier'

const verifier = createScopeBlindVerifier({
  secretKey: process.env.SCOPEBLIND_SECRET_KEY!,
  telemetry: {
    enabled: true,
    alerts: {
      webhooks: [{
        url: 'https://your-alerting-service.com/hook',
        secret: process.env.WEBHOOK_SECRET // For HMAC signature verification
      }],
      severities: ['critical'], // Only send critical alerts (DDoS, massive abuse)
      maxAlertsPerDay: 5,       // Prevent alert spam
      dryRun: true              // Test config without sending (RECOMMENDED for testing)
    }
  }
})

Alert Severities

Severity	When to Use	Examples
critical	Infrastructure threats, massive abuse	DDoS attack, 10x traffic spike, complete service outage
warning	Elevated activity, potential issues	2-5x traffic increase, sustained high rate limit hits
info	Milestone events, normal operations	Threshold reached (50k tokens), new deployment

Default: critical only (prevents alert fatigue)

Webhook Payload

Alerts are sent as POST requests with HMAC SHA-256 signatures:

{
  "alert": {
    "severity": "critical",
    "title": "DDoS Attack Detected",
    "message": "Traffic spike: 10x normal rate detected on /api/submit",
    "timestamp": 1699123456789,
    "metadata": {
      "scope": "api",
      "currentRate": 1000,
      "normalRate": 100
    }
  },
  "tenantId": "your-project-id",
  "timestamp": 1699123456789
}

Headers:

Content-Type: application/json
X-BRASS-Event: alert
X-Brass-Signature: sha256=<hmac_sha256_hex>

Verify Webhook Signatures

import crypto from 'crypto'

function verifyWebhook(req: Request, secret: string): boolean {
  const signature = req.headers['x-brass-signature']
  const payload = JSON.stringify(req.body)
  
  const hmac = crypto.createHmac('sha256', secret)
  hmac.update(payload)
  const expected = `sha256=${hmac.digest('hex')}`
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Slack Integration

const verifier = createScopeBlindVerifier({
  secretKey: process.env.SCOPEBLIND_SECRET_KEY!,
  telemetry: {
    enabled: true,
    alerts: {
      slack: {
        webhookUrl: process.env.SLACK_WEBHOOK_URL!
      },
      severities: ['critical', 'warning'],
      maxAlertsPerDay: 10
    }
  }
})

Alert Rate Limiting

Alerts include built-in protections against spam:

• Daily cap: Default 5 alerts/day (configurable)
• Debouncing: 60-minute window prevents duplicate alerts
• Severity filtering: Only send configured severity levels
• Dry run mode: Test without actually sending webhooks

const verifier = createScopeBlindVerifier({
  secretKey: process.env.SCOPEBLIND_SECRET_KEY!,
  telemetry: {
    enabled: true,
    alerts: {
      webhooks: [{ url: '...' }],
      maxAlertsPerDay: 10,      // Raise limit for high-volume apps
      debounceMinutes: 30,      // Reduce debounce for faster alerts
      dryRun: true,             // Test mode: logs alerts without sending
      severities: ['critical']  // Only the most important events
    }
  }
})

Manual Alert Triggering

import { Telemetrist } from '@scopeblind/verifier'

const telemetrist = new Telemetrist({
  enabled: true,
  alerts: {
    webhooks: [{ url: '...' }],
    severities: ['critical'],
    dryRun: false
  }
})

// Trigger custom alert
await telemetrist.emitAlert({
  severity: 'critical',
  title: 'Database Connection Lost',
  message: 'Primary database unreachable for 30 seconds',
  timestamp: Date.now(),
  metadata: { database: 'postgres-primary', downtime: 30 }
})

🚀 Managed Service Integrations (Private Beta)

Available to managed customers via invitation-only beta:

• Zero-config Slack/PagerDuty integrations
• SMS alerts via managed Twilio integration
• Anomaly detection powered by machine learning
• Smart alerting that learns your patterns to reduce noise
• Guaranteed delivery with automatic retry and fallback

Core webhook support (shown above) is available to all users today. See the main README feature table for current availability.

Contact [e-mail] for private beta access.

"Protected by ScopeBlind" Badge

Show your users you're using privacy-first abuse prevention with an embeddable badge (similar to reCAPTCHA).

React Component

Note: Badge is exported separately to avoid forcing React as a dependency for server-side users.

import { BrassBadge } from '@scopeblind/verifier/badge'

function App() {
  return (
    <div>
      <h1>Your App</h1>
      {/* Badge appears in bottom-right by default */}
      <BrassBadge />
    </div>
  )
}

Customization

<BrassBadge
  position="bottom-left"
  variant="compact"
  theme="dark"
  linkUrl="https://brassproof.com"
/>

{/* Disable badge */}
<BrassBadge enabled={false} />

Vanilla JavaScript

<script src="https://cdn.brassproof.com/badge.js"></script>
<script>
  BRASSBadge.init({
    position: 'bottom-right',
    variant: 'default',
    theme: 'auto', // Follows system dark mode preference
  })
</script>

<!-- Disable badge -->
<script>
  BRASSBadge.init({ enabled: false })
</script>

Badge Configuration

Property	Type	Default	Description
enabled	boolean	true	Show/hide badge
position	'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'	'bottom-right'	Badge position
variant	'default' | 'minimal' | 'compact'	'default'	Badge size/style
theme	'light' | 'dark' | 'auto'	'auto'	Color scheme
linkUrl	string	'https://brassproof.com'	Where badge links to

Environment Variables

# Required
SCOPEBLIND_SECRET_KEY=your_secret_key_here
SCOPEBLIND_ISSUER_PUBKEY=issuer_public_key_hex

# Optional - Telemetry
BRASS_TELEMETRY_ENABLED=true
BRASS_TELEMETRY_ENDPOINT=https://telemetry.brassproof.com/ingest
BRASS_TENANT_ID=your-project-id

# Optional - Verifier
BRASS_ISSUER_URL=https://brass-issuer.your-domain.workers.dev

API Reference

createScopeBlindVerifier(config: ScopeBlindVerifierConfig): BrassVerifier

Creates a new BRASS verifier instance.

verifier.verify(payload: BrassSpendPayload, context: VerificationContext): Promise<VerificationResult>

Verifies a BRASS token and enforces rate limits.

Parameters:

• payload: The ScopeBlind spend payload from the client
• context: Verification context including origin and scope

Returns:

{
  success: boolean
  error?: string           // Error message if verification failed
  remaining?: number       // Remaining requests in current window
  resetAt?: number        // Timestamp when rate limit resets
  metadata?: object       // Additional verification metadata
}

Self-Hosting

See docs/verifier.md for complete self-hosting instructions including:

• Cloudflare Worker deployment
• Durable Objects setup for distributed counters
• KV namespace configuration
• Key generation and rotation

Learn More

• BRASS Documentation
• Self-Hosting Guide
• Cloudflare Worker Example
• Security Whitepaper

Support

• GitHub Issues: Report bugs
• Documentation: docs.brassproof.com
• Email: [e-mail]

License

MIT - see LICENSE for details.