Express Middleware

@webdecoy/express wraps the Node SDK as Express middleware: every request is analyzed, blocked requests get a 403 by default, and the detection result rides on req.webdecoy.

Installation

npm install @webdecoy/express @webdecoy/node

Quick Start

import express from 'express';
import { webdecoy } from '@webdecoy/express';

const app = express();

app.use(webdecoy({
  threshold: 70,
  skipPaths: ['/health', '/static'],
  onBlocked: (req, res, detection) => {
    res.status(403).json({ error: 'Blocked' });
  }
}));

app.post('/api/login', (req, res) => {
  const { decision, confidence, threat_level } = req.webdecoy;

  if (decision === 'challenge') {
    return res.status(429).json({ error: 'Please complete verification' });
  }

  // Process login...
});

Options

Extends the core ProtectOptions (threshold, skipLocalAnalysis, metadata) with:

Option	Default	Description
`getIP`	`req.ip` / `x-forwarded-for`	Custom IP extraction
`onBlocked`	403 Forbidden	Custom handler for blocked requests
`onError`	Log and allow (fail open)	Custom error handler
`skipPaths`	—	Paths to skip (health checks, static assets)
`extractTLS`	`false`	Capture JA3/JA4 TLS fingerprints from the socket
`rules`	—	Local rules such as `tripwire()`

Set a Scraper Trap

Tripwires run locally — no API key, no network call. And under session clearance, a tripwire hit from a tokened session feeds the clearance deny-list: the SDK forwards the session’s token with the violation, and the client gets the same durable, rotation-proof lockout as a hosted decoy hit.

import { webdecoy } from '@webdecoy/express';
import { tripwire, honeytoken } from '@webdecoy/node';

const trap = honeytoken();

app.use(webdecoy({
  rules: [tripwire({ paths: [trap.path] })],
  skipPaths: ['/health', '/static']
}));

// Inject the invisible link so scrapers find it
app.get('/', (req, res) => {
  res.send('<!doctype html><html><body>' + trap.linkHtml + '</body></html>');
});

Captcha Endpoints

webdecoyCaptcha mounts the self-hosted captcha’s challenge and verify endpoints, which the Browser Client widget talks to:

import { webdecoyCaptcha } from '@webdecoy/express';

app.use(express.json());
app.use(webdecoyCaptcha({ secret: process.env.WEBDECOY_SECRET }));

Next Steps

Node SDK — the core API, configuration, and detection response
Browser Client — the widget for the captcha endpoints