@goguard/node

API security for Node.js. One line of code blocks fake signups, bot traffic, credential stuffing, and phone fraud.

Install

npm install @goguard/node

Setup

const express = require('express')
const { goguard } = require('@goguard/node')

const app = express()
app.use(express.json())
app.use(goguard({ apiKey: process.env.GOGUARD_API_KEY }))

app.post('/signup', (req, res) => {
  // only legitimate requests reach here
  res.json({ ok: true })
})

app.listen(3000)

No other code changes needed. Your existing routes work as before — abusive requests are blocked before they reach your handlers.

What it blocks

| Category | Attacks stopped | |----------|----------------| | Email fraud | Disposable domains, plus-tag tricks, Gmail dot tricks, fake domains (no MX) | | Phone fraud | VoIP/virtual numbers, suspicious country codes, phone-country mismatch | | Credential stuffing | Automated login attempts across multiple IPs | | Bots & scrapers | Sequential crawling, timing-based detection, high GET ratio | | Rate abuse | Per-IP and per-fingerprint sliding window limits | | Known threats | IP blocklists, watchlists, threat intelligence feeds | | Anomalies | ML-based anomaly scoring per customer baseline | | Custom rules | Your own block/challenge rules via the dashboard |

Configuration

app.use(goguard({
  apiKey: process.env.GOGUARD_API_KEY,  // required

  mode: 'block',            // 'block' | 'monitor' (default: 'block')
  excludePaths: ['/health'], // skip these paths
  timeout: 1500,             // ms before fail-open (default: 1500)
  failOpen: true,            // never break your app (default: true)

  // toggle auto-protection (all on by default)
  protect: {
    email: true,
    phone: true,
    login: true,
  },

  onBlock: (req, reason) => console.log('Blocked:', reason),
  onError: (err) => console.error('GoGuard:', err.message),
}))

Enrichment data (optional)

If you want access to the analysis results, they're on req.goguard:

app.post('/signup', (req, res) => {
  const email = req.goguard?.email?.normalized ?? req.body.email
  // "[email protected]" → "[email protected]"
})

| Field | Type | Description | |-------|------|-------------| | req.goguard.requestId | string | Unique request ID | | req.goguard.fingerprint | string | Device fingerprint | | req.goguard.verdict | Verdict | { action, reason, confidence } | | req.goguard.email | EmailAnalysis | Present if email detected in body | | req.goguard.phone | PhoneAnalysis | Present if phone detected in body | | req.goguard.stuffing | StuffingAnalysis | Present on login paths |

Advanced: analysis methods

For deeper fraud investigation (audit scripts, admin tools), use GoGuardClient directly:

const { GoGuardClient } = require('@goguard/node')
const client = new GoGuardClient({ apiKey: process.env.GOGUARD_API_KEY })

Find fake account clusters in your database:

const result = await client.detectEmailAbuse([
  '[email protected]', '[email protected]', '[email protected]'
])
// { is_abuse: true, total_fake_accounts: 2, clusters: [...] }

Detect phone number cycling:

const result = await client.detectPhoneCycling([
  { phone: '+14155551111', timestamp: 1711600000000 },
  { phone: '+447911123456', timestamp: 1711600060000 },
])
// { is_cycling: true, unique_phones: 2, unique_countries: 2 }

Single email/phone analysis:

const email = await client.analyzeEmail('[email protected]')
// { is_disposable: true, normalized: '[email protected]', risk_score: 0.7 }

const phone = await client.analyzePhone('+37255001234')
// { is_suspicious_country: true, country_name: 'Estonia', risk_score: 0.3 }

Next.js (Edge Runtime)

The Express middleware uses node:crypto which isn't available in Edge Runtime. Use GoGuardClient directly:

import { GoGuardClient } from '@goguard/node/dist/client.js'
import { NextRequest, NextResponse } from 'next/server'

const client = new GoGuardClient({ apiKey: process.env.GOGUARD_API_KEY! })

export async function middleware(req: NextRequest) {
  const verdict = await client.decide({
    requestId: crypto.randomUUID(),
    timestamp: Date.now(),
    ip: req.headers.get('x-forwarded-for')?.split(',')[0] || '0.0.0.0',
    fingerprint: '',
    userAgent: req.headers.get('user-agent') || '',
    path: req.nextUrl.pathname,
    method: req.method,
    headers: Object.fromEntries(req.headers.entries()),
    bodySize: 0,
  })

  if (verdict.action === 'block') {
    return NextResponse.json({ error: 'Blocked' }, { status: 403 })
  }
  return NextResponse.next()
}

Response headers

| Header | Value | |--------|-------| | X-Shield-Request-Id | Unique request ID | | X-Shield-Action | allow, block, or challenge |

Requirements

• Node.js 20+
• Express 4+ or any (req, res, next) middleware stack

Links

• Dashboard
• Go SDK
• Python SDK

License

MIT