refactor: one adapter core, so a fifth copy cannot drift

Express, Fastify, Next.js (twice — the middleware and the Pages wrapper)
and the fetch guard each carried their own copy of the same decisions:
skip-path matching, the 429 payload, the 403 payload, honeytoken arming.
Five copies of one set of rules.

Not a tidiness complaint. The leftmost-X-Forwarded-For bug survived in two
adapters after the same class had been fixed elsewhere, precisely because
there was no one place to fix. Every copy is a place the next correction
can fail to land, and each reads sensibly on its own, which is why review
does not catch it.

adapter-core.ts holds the decisions. The adapters keep the I/O, which
differs genuinely: Express intercepts res.write/res.end, Fastify uses an
onSend hook, a fetch handler rebuilds a Response, and the detail in each
is hard-won.

Fastify keeps its awaited arming. It derives during plugin registration,
which is already an async boot phase, so it has no window where early
requests are served without the link -- forcing it onto the
fire-and-forget getter would have REGRESSED it. deriveAndArm() is the same
logic with the other timing, not a second implementation.

Every existing honeytoken-injection test passes unchanged, which was the
acceptance criterion: the response mechanics are untouched.

Three invariants stop the sixth copy, and writing them found a false
positive worth keeping: nextjs/honeytoken.ts derives a token without
arming, deliberately -- it is the render-side helper a layout calls, and
the developer arms in middleware from the same HMAC. A second caller, not
a second answer. Excluded with that reason rather than by loosening the
rule.

Closes WebDecoy/app#739

Author: cport1

packages/express/src/middleware.ts

@@ -6,18 +6,18 @@ import { Request, Response, NextFunction } from 'express';
 import { WebDecoy, WebDecoyConfig, RequestMetadata, ProtectOptions } from '@webdecoy/node';
 import type {
   EdgeVerdict,
-  SiteHoneytoken,
   TrustedProxies,
   ProtectResult,
   SDKDetectionResponse,
 } from '@webdecoy/node';
 import {
-  siteHoneytoken,
   injectHoneytokenLink,
   isInjectableHtml,
-  tripwire,
   resolveClientIp,
   normalizeIp,
+  shouldSkipPath,
+  ruleBlockResponse,
+  armSiteHoneytoken,
 } from '@webdecoy/node';
 
 export interface WebDecoyMiddlewareOptions extends ProtectOptions {
@@ -169,22 +169,6 @@ function defaultOnError(req: Request, res: Response, error: Error): void {
   // Fail open - allow the request to continue
 }
 
-/**
- * Check if path should be skipped
- */
-function shouldSkipPath(path: string, skipPaths?: string[] | RegExp[]): boolean {
-  if (!skipPaths || skipPaths.length === 0) {
-    return false;
-  }
-
-  return skipPaths.some((pattern) => {
-    if (typeof pattern === 'string') {
-      return path === pattern || path.startsWith(pattern);
-    }
-    return pattern.test(path);
-  });
-}
-
 /**
  * Create Express middleware for Web Decoy protection
  *
@@ -218,27 +202,13 @@ export function webdecoy(
   const onBlocked = config.onBlocked || defaultOnBlocked;
   const mode = config.mode ?? 'monitor';
 
-  // Honeytoken. Derived from the API key so every replica computes the
-  // same path without coordinating — a random per-process token would advertise
-  // a link whose tripwire only one replica had armed.
-  //
-  // Resolution is async (WebCrypto HMAC, so this still runs on edge runtimes),
-  // and requests served before it settles simply carry no link. That is a few
-  // milliseconds at boot against the alternative of blocking startup on crypto.
-  const honeytokenEnabled = (config.honeytoken ?? true) && Boolean(config.apiKey);
-  let token: SiteHoneytoken | null = null;
-  if (honeytokenEnabled) {
-    void siteHoneytoken({ secret: config.apiKey as string })
-      .then((t) => {
-        token = t;
-        // Arm the path we are about to advertise. Without this the link is bait
-        // with no trap behind it — a crawler follows it and nothing happens.
-        sdk.addRule(tripwire({ paths: t.activePaths, includeDefaults: false }));
-      })
-      .catch(() => {
-        // Deriving the token is not worth a failed boot. No token, no injection.
-      });
-  }
+  // Honeytoken arming lives in the shared core: every adapter derived the same
+  // token the same way, and a fourth copy is a fourth place the next change can
+  // fail to land.
+  const getToken = armSiteHoneytoken(sdk, {
+    apiKey: config.apiKey,
+    enabled: config.honeytoken,
+  });
   const onError = config.onError || defaultOnError;
   const skipPaths = config.skipPaths;
 
@@ -282,8 +252,10 @@ export function webdecoy(
       //   - a committed response is left alone, because headers are already sent
       //   - Content-Length is corrected, or the client truncates the body
       //   - anything thrown falls back to the original write
-      if (token) {
-        const ht = token;
+      // Read once: the getter can settle between calls, and an injected link
+      // whose tripwire was armed a moment later is bait with no trap.
+      const ht = getToken();
+      if (ht) {
         const originalWrite = res.write.bind(res);
         const originalEnd = res.end.bind(res);
         const chunks: Buffer[] = [];
@@ -358,29 +330,15 @@ export function webdecoy(
         return next();
       }
 
-      // Handle rule engine results for specific HTTP responses
-      if (!result.allowed && result.ruleResult) {
-        const rr = result.ruleResult;
-
-        if (rr.action === 'THROTTLE') {
-          const retryAfter = rr.metadata?.retryAfter ?? 60;
-          res.setHeader('Retry-After', String(retryAfter));
-          res.status(429).json({
-            error: 'Too Many Requests',
-            message: rr.reason || 'Rate limit exceeded',
-            retry_after: retryAfter,
-          });
-          return;
-        }
-
-        if (rr.action === 'DENY') {
-          res.status(403).json({
-            error: 'Forbidden',
-            message: rr.reason || 'Access denied by rule',
-            rule: rr.rule,
-          });
-          return;
+      // A rule refusal answers with the shape every adapter uses; only the
+      // writing of it is Express's business.
+      const block = ruleBlockResponse(result);
+      if (block) {
+        for (const [name, value] of Object.entries(block.headers)) {
+          res.setHeader(name, value);
         }
+        res.status(block.status).json(block.body);
+        return;
       }
 
       // Handle the result

packages/fastify/src/plugin.ts

@@ -9,12 +9,13 @@ import {
   WebDecoyConfig,
   RequestMetadata,
   ProtectOptions,
-  siteHoneytoken,
   injectHoneytokenLink,
   isInjectableHtml,
-  tripwire,
   resolveClientIp,
   normalizeIp,
+  shouldSkipPath,
+  ruleBlockResponse,
+  deriveAndArm,
 } from '@webdecoy/node';
 import type {
   EdgeVerdict,
@@ -153,22 +154,6 @@ function defaultOnError(req: FastifyRequest, reply: FastifyReply, error: Error):
   // Fail open - allow the request to continue
 }
 
-/**
- * Check if path should be skipped
- */
-function shouldSkipPath(path: string, skipPaths?: string[] | RegExp[]): boolean {
-  if (!skipPaths || skipPaths.length === 0) {
-    return false;
-  }
-
-  return skipPaths.some((pattern) => {
-    if (typeof pattern === 'string') {
-      return path === pattern || path.startsWith(pattern);
-    }
-    return pattern.test(path);
-  });
-}
-
 /**
  * Web Decoy detection info attached to requests
  */
@@ -235,19 +220,12 @@ async function webdecoyPluginImpl(
   // Fastify lets us await it here, because plugin registration is already an
   // async boot phase — so unlike Express there is no window where early requests
   // are served without the link.
-  const honeytokenEnabled = (options.honeytoken ?? true) && Boolean(options.apiKey);
-  let token: SiteHoneytoken | null = null;
-  if (honeytokenEnabled) {
-    try {
-      token = await siteHoneytoken({ secret: options.apiKey as string });
-      // Arm the path we are about to advertise. Without this the link is bait
-      // with no trap behind it — a crawler follows it and nothing happens.
-      sdk.addRule(tripwire({ paths: token.activePaths, includeDefaults: false }));
-    } catch {
-      // Deriving the token is not worth a failed boot. No token, no injection.
-      token = null;
-    }
-  }
+  // The awaited variant, because plugin registration is already an async boot
+  // phase. Same derive-and-arm as every other adapter; only the timing differs.
+  const token: SiteHoneytoken | null = await deriveAndArm(sdk, {
+    apiKey: options.apiKey,
+    enabled: options.honeytoken,
+  });
 
   // Add decorator for webdecoy property
   fastify.decorateRequest('webdecoy', null);
@@ -305,29 +283,15 @@ async function webdecoyPluginImpl(
         return;
       }
 
-      // Handle rule engine results for specific HTTP responses
-      if (!result.allowed && result.ruleResult) {
-        const rr = result.ruleResult;
-
-        if (rr.action === 'THROTTLE') {
-          const retryAfter = rr.metadata?.retryAfter ?? 60;
-          reply.header('Retry-After', String(retryAfter));
-          reply.status(429).send({
-            error: 'Too Many Requests',
-            message: rr.reason || 'Rate limit exceeded',
-            retry_after: retryAfter,
-          });
-          return;
-        }
-
-        if (rr.action === 'DENY') {
-          reply.status(403).send({
-            error: 'Forbidden',
-            message: rr.reason || 'Access denied by rule',
-            rule: rr.rule,
-          });
-          return;
+      // A rule refusal answers with the shape every adapter uses; only the
+      // writing of it is Fastify's business.
+      const block = ruleBlockResponse(result);
+      if (block) {
+        for (const [name, value] of Object.entries(block.headers)) {
+          reply.header(name, value);
         }
+        reply.status(block.status).send(block.body);
+        return;
       }
 
       // Handle the result

packages/nextjs/src/middleware.ts

@@ -10,6 +10,8 @@ import {
   ProtectOptions,
   resolveClientIp,
   normalizeIp,
+  shouldSkipPath,
+  ruleBlockResponse,
 } from '@webdecoy/node';
 import type { TrustedProxies, ProtectResult, SDKDetectionResponse } from '@webdecoy/node';
 
@@ -128,22 +130,6 @@ function defaultOnError(req: NextRequest, error: Error): NextResponse | null {
   return null;
 }
 
-/**
- * Check if path should be skipped
- */
-function shouldSkipPath(path: string, skipPaths?: string[] | RegExp[]): boolean {
-  if (!skipPaths || skipPaths.length === 0) {
-    return false;
-  }
-
-  return skipPaths.some((pattern) => {
-    if (typeof pattern === 'string') {
-      return path === pattern || path.startsWith(pattern);
-    }
-    return pattern.test(path);
-  });
-}
-
 /**
  * Create Next.js middleware for Web Decoy protection
  *
@@ -224,35 +210,14 @@ export function withWebDecoy(
         return NextResponse.next({ request: { headers: monitorHeaders } });
       }
 
-      // Handle rule engine results for specific HTTP responses
-      if (!result.allowed && result.ruleResult) {
-        const rr = result.ruleResult;
-
-        if (rr.action === 'THROTTLE') {
-          const retryAfter = rr.metadata?.retryAfter ?? 60;
-          return NextResponse.json(
-            {
-              error: 'Too Many Requests',
-              message: rr.reason || 'Rate limit exceeded',
-              retry_after: retryAfter,
-            },
-            {
-              status: 429,
-              headers: { 'Retry-After': String(retryAfter) },
-            }
-          );
-        }
-
-        if (rr.action === 'DENY') {
-          return NextResponse.json(
-            {
-              error: 'Forbidden',
-              message: rr.reason || 'Access denied by rule',
-              rule: rr.rule,
-            },
-            { status: 403 }
-          );
-        }
+      // A rule refusal answers with the shape every adapter uses; only the
+      // building of the NextResponse is this adapter's business.
+      const block = ruleBlockResponse(result);
+      if (block) {
+        return NextResponse.json(block.body, {
+          status: block.status,
+          headers: block.headers,
+        });
       }
 
       // Handle the result
@@ -359,17 +324,17 @@ export function withBotProtection<T extends (...args: any[]) => any>(
       });
 
       if (!result.allowed) {
-        // Handle rule engine specific responses
-        if (result.ruleResult?.action === 'THROTTLE') {
-          const retryAfter = result.ruleResult.metadata?.retryAfter ?? 60;
-          res.setHeader('Retry-After', String(retryAfter));
-          return res.status(429).json({
-            error: 'Too Many Requests',
-            message: result.ruleResult.reason || 'Rate limit exceeded',
-            retry_after: retryAfter,
-          });
+        // Same shared refusal shape as the middleware and every other adapter.
+        // This wrapper was the fourth copy of it.
+        const block = ruleBlockResponse(result);
+        if (block) {
+          for (const [name, value] of Object.entries(block.headers)) {
+            res.setHeader(name, value);
+          }
+          return res.status(block.status).json(block.body);
         }
 
+        // A server-score block names no rule, so it keeps its own shape.
         return res.status(403).json({
           error: 'Forbidden',
           message: 'Access denied by Web Decoy protection',