BRASS protocol verifier SDK for rate limiting and abuse prevention
npm install @brassproof/verifierOfficial BRASS protocol verifier SDK for Node.js and edge runtimes. Verify blinded tokens, enforce rate limits, and prevent abuse with privacy-preserving cryptography.
- ✅ 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 BRASS Proof" widget builds user trust
``bash`
npm install @brassproof/verifier
`typescript
import { createBrassVerifier } from '@brassproof/verifier'
const verifier = createBrassVerifier({
secretKey: process.env.BRASS_SECRET_KEY!,
issuerPublicKey: process.env.BRASS_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, // BRASS spend payload from client
{
origin: 'https://example.com',
scope: 'comment-submission',
clientIp: req.ip,
}
)
if (result.success) {
console.log('✅ Token verified!', result.remaining, 'requests remaining')
// Process the request...
} else {
console.error('❌ Verification failed:', result.error)
// Reject the request
}
`
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| secretKey | string | ✅ | Your BRASS API secret key |issuerPublicKey
| | string | ✅ | Public key from your BRASS issuer |issuerUrl
| | string | ❌ | Issuer endpoint URL (for future features) |kvNamespace
| | KVNamespace | ❌ | Key-value store for rate limiting and replay protection |rateLimits
| | Record | ❌ | Custom rate limits per scope |replayWindowSeconds
| | number | ❌ | How long to track used tokens (default: 3600) |
`typescript`
{
'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
}
`typescript
import express from 'express'
import { createBrassVerifier } from '@brassproof/verifier'
const app = express()
const verifier = createBrassVerifier({
secretKey: process.env.BRASS_SECRET_KEY!,
issuerPublicKey: process.env.BRASS_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 })
})
`
`typescript
import { createBrassVerifier } from '@brassproof/verifier'
export default {
async fetch(request: Request, env: Env) {
const verifier = createBrassVerifier({
secretKey: env.BRASS_SECRET_KEY,
issuerPublicKey: env.BRASS_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 }))
}
}
`
`typescript
import { NextRequest, NextResponse } from 'next/server'
import { createBrassVerifier } from '@brassproof/verifier'
const verifier = createBrassVerifier({
secretKey: process.env.BRASS_SECRET_KEY!,
issuerPublicKey: process.env.BRASS_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 })
}
`
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
BRASS includes opt-in telemetry that powers managed service features like analytics dashboards and auto-calibrated rate limits.
- ✅ 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
Telemetry is disabled by default for privacy. Enable it to access managed service features:
Option 1: Environment Variables
`bash`
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
`typescript
import { createBrassVerifier } from '@brassproof/verifier'
const verifier = createBrassVerifier({
secretKey: process.env.BRASS_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.
},
},
})
No action needed - telemetry is off unless you explicitly enable it. If you've enabled it and want to disable:
`bash`Remove or set to false
BRASS_TELEMETRY_ENABLED=false
`typescript`
// Or explicitly disable in code
const verifier = createBrassVerifier({
secretKey: process.env.BRASS_SECRET_KEY!,
telemetry: { enabled: false },
})
`typescript
import { createBrassVerifier } from '@brassproof/verifier'
const verifier = createBrassVerifier({
secretKey: process.env.BRASS_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!,`
}),
})
},
},
})
Skip the trial-and-error! Use battle-tested security profiles for common use cases.
| 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 |
`typescript
import { createBrassVerifier } from '@brassproof/verifier'
// Instantly configure for your use case
const verifier = createBrassVerifier({
secretKey: process.env.BRASS_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
`typescript`
const verifier = createBrassVerifier({
secretKey: process.env.BRASS_SECRET_KEY!,
calibrationProfile: 'comments',
profileOverrides: {
rateLimit: { maxRequests: 5 }, // Allow 5 comments/day instead of 3
tokens: { maxAgeSeconds: 600 } // Extend token lifetime to 10min
}
})
`typescript
import { listProfiles } from '@brassproof/verifier'
const profiles = listProfiles()
profiles.forEach(p => {
console.log(${p.name}: ${p.description}) Tested with: ${p.metadata.testedWith}
console.log() Warnings: ${p.metadata.warnings?.join(', ')}
console.log()`
})
`typescript
import { recommendProfile } from '@brassproof/verifier'
const profile = recommendProfile('user comments on blog posts')
// Returns: 'comments'
const verifier = createBrassVerifier({
secretKey: process.env.BRASS_SECRET_KEY!,
calibrationProfile: profile,
})
`
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 sales@brassproof.com for private beta access.
---
Get notified when critical events occur. Perfect for DDoS detection, rate limit monitoring, and security incident response.
`typescript
import { createBrassVerifier } from '@brassproof/verifier'
const verifier = createBrassVerifier({
secretKey: process.env.BRASS_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)
}
}
})
`
| 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)
Alerts are sent as POST requests with HMAC SHA-256 signatures:
`json`
{
"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=
`typescript
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)
)
}
`typescript`
const verifier = createBrassVerifier({
secretKey: process.env.BRASS_SECRET_KEY!,
telemetry: {
enabled: true,
alerts: {
slack: {
webhookUrl: process.env.SLACK_WEBHOOK_URL!
},
severities: ['critical', 'warning'],
maxAlertsPerDay: 10
}
}
})
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
`typescript`
const verifier = createBrassVerifier({
secretKey: process.env.BRASS_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
}
}
})
`typescript
import { Telemetrist } from '@brassproof/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 }
})
`
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 sales@brassproof.com for private beta access.
---
Show your users you're using privacy-first abuse prevention with an embeddable badge (similar to reCAPTCHA).
Note: Badge is exported separately to avoid forcing React as a dependency for server-side users.
`tsx
import { BrassBadge } from '@brassproof/verifier/badge'
function App() {
return (
$3
`tsx
position="bottom-left"
variant="compact"
theme="dark"
linkUrl="https://brassproof.com"
/>{/ Disable badge /}
`$3
`html
`$3
| 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
`bash
Required
BRASS_SECRET_KEY=your_secret_key_here
BRASS_ISSUER_PUBKEY=issuer_public_key_hexOptional - Telemetry
BRASS_TELEMETRY_ENABLED=true
BRASS_TELEMETRY_ENDPOINT=https://telemetry.brassproof.com/ingest
BRASS_TENANT_ID=your-project-idOptional - Verifier
BRASS_ISSUER_URL=https://brass-issuer.your-domain.workers.dev
`API Reference
$3
Creates a new BRASS verifier instance.
$3
Verifies a BRASS token and enforces rate limits.
Parameters:
-
payload: The BRASS spend payload from the client
- context: Verification context including origin and scopeReturns:
`typescript
{
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
}
``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
- BRASS Documentation
- Self-Hosting Guide
- Cloudflare Worker Example
- Security Whitepaper
- GitHub Issues: Report bugs
- Documentation: docs.brassproof.com
- Email: support@brassproof.com
MIT - see LICENSE for details.