Node SDK

SDK Overview

The WebDecoy Node SDK provides server-side bot detection and threat intelligence for Node.js applications. It enables deep integration with Express, Next.js, Fastify, and other Node.js frameworks.

Note: The Node SDK is currently in development. This documentation reflects the planned API and features.

SDK Capabilities

Feature	Description
Bot Detection	Analyze requests for automation signals
Threat Scoring	Calculate unified threat scores
IP Intelligence	Access reputation and geolocation data
TLS Fingerprinting	JA3/JA4 fingerprint analysis
Detection Submission	Send detections to WebDecoy
Framework Middleware	Express, Next.js, Fastify integration

When to Use the SDK

Use Case	SDK Benefit
Custom Node.js apps	Full control over detection logic
API protection	Server-side request analysis
High-traffic sites	Efficient server-side processing
Sensitive endpoints	Deep request inspection
Custom integrations	Programmatic access to detections

---

Installation

Core Package

npm install webdecoy
# or
yarn add webdecoy

Framework-Specific Packages

# Express
npm install @webdecoy/express

# Next.js
npm install @webdecoy/nextjs

# Fastify
npm install @webdecoy/fastify

Requirements

• Node.js 16.x or later
• npm 7.x or later
• WebDecoy API key

---

Basic Usage

Client Initialization

const { WebDecoyClient } = require('webdecoy');

const client = new WebDecoyClient({
  apiKey: process.env.WEBDECOY_API_KEY,
  // Optional settings
  baseUrl: 'https://api.webdecoy.com',
  timeout: 10000,
  retries: 3
});

Environment Variables

.env

WEBDECOY_API_KEY=sk_live_your_api_key_here
WEBDECOY_ORGANIZATION_ID=org_optional_override

Basic Detection Analysis

const { WebDecoyClient, BotDetector } = require('webdecoy');

const client = new WebDecoyClient({
  apiKey: process.env.WEBDECOY_API_KEY
});

const detector = new BotDetector({
  sensitivity: 'medium',
  allowSearchEngines: true
});

// In your request handler
async function handleRequest(req, res) {
  // Analyze the request
  const result = await detector.analyze({
    ip: req.ip,
    userAgent: req.headers['user-agent'],
    headers: req.headers,
    url: req.url,
    method: req.method
  });

  // Check if should block
  if (result.shouldBlock(75)) {
    return res.status(403).json({ error: 'Access denied' });
  }

  // Continue with request
  // ...
}

Detection Result Object

const result = await detector.analyze(request);

// Properties
result.score          // 0-100 unified threat score
result.threatLevel    // 'MINIMAL', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL'
result.botScore       // 0-100 bot likelihood score
result.flags          // Array of detection flags
result.isBot          // Boolean: likely a bot
result.isGoodBot      // Boolean: known legitimate bot
result.botName        // Name if identified (e.g., 'Googlebot')
result.botCategory    // Category (e.g., 'search_engine')
result.confidence     // 0.0-1.0 confidence level

// Methods
result.shouldBlock(threshold)    // true if score >= threshold
result.shouldChallenge(threshold)// true if score in challenge range
result.shouldLog()               // true if score warrants logging
result.isLegitimate()            // true if score < 20

Submitting Detections

// Submit a detection to WebDecoy
await client.submitDetection({
  source: 'sdk',
  ipAddress: req.ip,
  userAgent: req.headers['user-agent'],
  url: req.url,
  method: req.method,
  threatScore: result.score,
  flags: result.flags,
  metadata: {
    customField: 'value'
  }
});

---

Framework Integration

Express Middleware

const express = require('express');
const { webDecoyMiddleware } = require('@webdecoy/express');

const app = express();

// Apply globally
app.use(webDecoyMiddleware({
  apiKey: process.env.WEBDECOY_API_KEY,
  sensitivity: 'medium',
  blockThreshold: 75,
  allowSearchEngines: true,
  excludePaths: ['/health', '/metrics']
}));

// Or apply to specific routes
app.post('/api/login',
  webDecoyMiddleware({ blockThreshold: 60 }),
  loginHandler
);

app.listen(3000);

Express Middleware Options

Option	Default	Description
apiKey	Required	Your WebDecoy API key
sensitivity	’medium’	Detection sensitivity
blockThreshold	75	Score threshold to block
challengeThreshold	50	Score threshold to challenge
allowSearchEngines	true	Bypass for search bots
allowSocialBots	true	Bypass for social bots
excludePaths	[]	Paths to skip
excludeMethods	[‘OPTIONS’]	HTTP methods to skip
onDetection	null	Custom detection handler
onBlock	null	Custom block handler

Next.js Middleware

middleware.js

import { withWebDecoy } from '@webdecoy/nextjs';

export default withWebDecoy({
  apiKey: process.env.WEBDECOY_API_KEY,
  blockThreshold: 75,
  matcher: ['/api/:path*', '/login']
});

export const config = {
  matcher: ['/api/:path*', '/login']
};

Next.js API Route Protection

pages/api/protected.js

import { withBotProtection } from '@webdecoy/nextjs';

async function handler(req, res) {
  res.json({ message: 'Protected content' });
}

export default withBotProtection(handler, {
  blockThreshold: 70
});

Fastify Plugin

const fastify = require('fastify')();
const webDecoyPlugin = require('@webdecoy/fastify');

fastify.register(webDecoyPlugin, {
  apiKey: process.env.WEBDECOY_API_KEY,
  sensitivity: 'medium',
  blockThreshold: 75
});

fastify.get('/protected', async (request, reply) => {
  // Detection info available on request
  const botScore = request.webDecoy.score;
  return { score: botScore };
});

fastify.listen({ port: 3000 });

---

Advanced Features

Custom Signal Collection

const { SignalCollector } = require('webdecoy');

const collector = new SignalCollector();

// Collect signals from request
const signals = collector.collect({
  ip: req.ip,
  userAgent: req.headers['user-agent'],
  headers: req.headers,
  // Optional additional signals
  tlsFingerprint: req.socket.ja3,
  cookies: req.cookies,
  bodySize: req.body ? Buffer.byteLength(JSON.stringify(req.body)) : 0
});

// Use with detector
const result = await detector.analyze(signals);

IP Intelligence

const { IPIntelligence } = require('webdecoy');

const intel = new IPIntelligence(client);

const info = await intel.lookup('192.168.1.100');

// Returns
{
  ip: '192.168.1.100',
  country: 'US',
  city: 'New York',
  asn: 12345,
  isp: 'Example ISP',
  isProxy: false,
  isVPN: true,
  isTor: false,
  isHosting: false,
  abuseScore: 25,
  riskLevel: 'low'
}

TLS Fingerprinting

const { TLSFingerprinter } = require('webdecoy');

// In your HTTPS server
const server = https.createServer(options, app);

server.on('secureConnection', (tlsSocket) => {
  const fingerprint = TLSFingerprinter.fromSocket(tlsSocket);
  // Store fingerprint for later use
  tlsSocket.ja3 = fingerprint.ja3;
  tlsSocket.ja4 = fingerprint.ja4;
});

Rate Limiting Integration

const { RateLimiter } = require('webdecoy');

const limiter = new RateLimiter({
  windowMs: 60000,  // 1 minute
  maxRequests: 100,
  keyGenerator: (req) => req.ip,
  onRateLimit: async (req, key) => {
    // Submit as detection
    await client.submitDetection({
      source: 'sdk',
      ipAddress: key,
      flags: ['rate_limit_exceeded'],
      threatScore: 60
    });
  }
});

app.use(limiter.middleware());

---

API Reference

WebDecoyClient

const client = new WebDecoyClient(options);

// Methods
client.testConnection()           // Verify API key
client.submitDetection(detection) // Submit detection
client.getDetections(filters)     // Query detections
client.blockIP(ip, hours, reason) // Manual IP block
client.unblockIP(ip)              // Remove IP block

BotDetector

const detector = new BotDetector(options);

// Methods
detector.analyze(request)         // Analyze request
detector.setConfig(options)       // Update configuration
detector.getSignalCollector()     // Get signal collector

Detection Object

const detection = {
  source: 'sdk',
  ipAddress: '192.168.1.100',
  userAgent: 'Mozilla/5.0...',
  url: '/api/endpoint',
  method: 'POST',
  threatScore: 75,
  botScore: 80,
  flags: ['headless_browser', 'missing_headers'],
  mitreTactic: {
    id: 'TA0043',
    name: 'Reconnaissance'
  },
  metadata: {
    // Custom fields
  }
};

---

Error Handling

const { WebDecoyError, RateLimitError, AuthError } = require('webdecoy');

try {
  await client.submitDetection(detection);
} catch (error) {
  if (error instanceof AuthError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited, retry after:', error.retryAfter);
  } else if (error instanceof WebDecoyError) {
    console.error('API error:', error.message);
  } else {
    throw error;
  }
}

---

Best Practices

Performance

• Initialize client once, reuse across requests
• Use async/await for non-blocking detection
• Cache IP intelligence lookups
• Use exclude patterns for static assets

Security

• Store API key in environment variables
• Validate detection results before blocking
• Log detection decisions for audit
• Set appropriate timeout values

Integration

• Start with logging mode before blocking
• Monitor false positive rates
• Adjust thresholds based on traffic
• Combine with client-side bot scanner

---

Example: Complete Express App

const express = require('express');
const { WebDecoyClient, BotDetector } = require('webdecoy');
const { webDecoyMiddleware } = require('@webdecoy/express');

const app = express();

// Initialize client
const client = new WebDecoyClient({
  apiKey: process.env.WEBDECOY_API_KEY
});

// Global protection (logging mode)
app.use(webDecoyMiddleware({
  apiKey: process.env.WEBDECOY_API_KEY,
  blockThreshold: 90,  // Only block very high scores
  onDetection: (req, result) => {
    console.log(`Detection: ${req.ip} - Score: ${result.score}`);
  }
}));

// Stricter protection for sensitive endpoints
app.post('/api/login',
  webDecoyMiddleware({
    apiKey: process.env.WEBDECOY_API_KEY,
    blockThreshold: 60,
    sensitivity: 'high'
  }),
  async (req, res) => {
    // Login logic
  }
);

// Custom detection logic
app.post('/api/checkout', async (req, res) => {
  const detector = new BotDetector({ sensitivity: 'high' });

  const result = await detector.analyze({
    ip: req.ip,
    userAgent: req.headers['user-agent'],
    headers: req.headers
  });

  if (result.shouldBlock(70)) {
    await client.submitDetection({
      source: 'sdk',
      ipAddress: req.ip,
      url: '/api/checkout',
      threatScore: result.score,
      flags: result.flags
    });
    return res.status(403).json({ error: 'Request blocked' });
  }

  // Process checkout
});

app.listen(3000);