Fastify Plugin

@webdecoy/fastify registers the Node SDK as a Fastify plugin. Detection runs on every request, blocked requests get a 403 by default, and the result is attached to req.webdecoy.

Installation

npm install @webdecoy/fastify @webdecoy/node

Quick Start

import Fastify from 'fastify';
import webdecoyPlugin from '@webdecoy/fastify';

const fastify = Fastify();

await fastify.register(webdecoyPlugin, {
  threshold: 70,
  skipPaths: ['/health']
});

fastify.post('/api/checkout', async (req, reply) => {
  const { decision, confidence, bot_detected } = req.webdecoy;

  if (decision === 'block') {
    return reply.code(403).send({ error: 'Request blocked' });
  }
  if (decision === 'challenge') {
    return reply.code(429).send({ error: 'Verification required' });
  }

  // Process checkout...
});

Options

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

Option	Default	Description
getIP	request.ip (set Fastify’s trustProxy for 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
rules	—	Local rules such as tripwire()

Captcha Endpoints

webdecoyCaptchaPlugin mounts the self-hosted captcha endpoints for the Browser Client widget:

import { webdecoyCaptchaPlugin } from '@webdecoy/fastify';

await fastify.register(webdecoyCaptchaPlugin, {
  secret: process.env.WEBDECOY_SECRET
});

---

Next Steps

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