test(sdk): pin the invariants a reviewer cannot see

packages/nextjs/src/captcha.ts

@@ -15,7 +15,6 @@
 import {
   createCaptchaEndpoints,
   resolveClientIp,
-  normalizeIp,
   type CaptchaEndpointsOptions,
   type TrustedProxies,
 } from '@webdecoy/node';
@@ -28,13 +27,7 @@ import {
  * back on.
  */
 function getIP(headers: Headers, trustProxy: TrustedProxies | undefined): string {
-  const fromChain = resolveClientIp({ headers, trustProxy: trustProxy ?? 1 });
-  if (fromChain) return fromChain;
-  return (
-    normalizeIp(headers.get('x-real-ip')) ??
-    normalizeIp(headers.get('x-vercel-forwarded-for')?.split(',').pop()) ??
-    '127.0.0.1'
-  );
+  return resolveClientIp({ headers, trustProxy: trustProxy ?? 1 }) ?? '127.0.0.1';
 }
 
 export interface NextCaptchaOptions extends CaptchaEndpointsOptions {

packages/nextjs/src/middleware.ts

@@ -99,17 +99,10 @@
  * `X-Forwarded-For`, never an override of one.
  */
 function resolveIP(req: NextRequest, trustProxy: TrustedProxies | undefined): string {
-  const fromChain = resolveClientIp({
-    headers: req.headers,
-    trustProxy: trustProxy ?? 1,
-  });
-  if (fromChain) return fromChain;
-
-  return (
-    normalizeIp(req.headers.get('x-real-ip')) ??
-    normalizeIp(req.headers.get('x-vercel-forwarded-for')?.split(',').pop()) ??
-    '127.0.0.1'
-  );
+  // One resolver. `x-real-ip` and the platform header used to be read here as a
+  // fallback; they now live inside resolveClientIp, so this adapter reads no
+  // forwarding header of its own and cannot drift from the others.
+  return resolveClientIp({ headers: req.headers, trustProxy: trustProxy ?? 1 }) ?? '127.0.0.1';
 }
 
 /**
@@ -327,7 +320,7 @@
  * });
  * ```
  */
 export function withBotProtection<T extends (...args: any[]) => any>(
   handler: T,
   config: WebDecoyConfig & WithBotProtectionOptions
 ): T {

packages/webdecoy/src/client-ip.test.ts

@@ -302,3 +302,42 @@ describe('resolveClientIp', () => {
     });
   });
 });
+
+describe('the single-header fallback', () => {
+  it('uses X-Real-IP when a proxy is declared but sends no chain', () => {
+    // nginx's default: X-Real-IP and no X-Forwarded-For.
+    const ip = resolveClientIp({
+      headers: h({ 'x-real-ip': '203.0.113.9' }),
+      peer: '10.0.0.1',
+      trustProxy: 1,
+    });
+    expect(ip).toBe('203.0.113.9');
+  });
+
+  it('takes the last value of the platform header, not the first', () => {
+    const ip = resolveClientIp({
+      headers: h({ 'x-vercel-forwarded-for': '1.2.3.4, 203.0.113.9' }),
+      trustProxy: 1,
+    });
+    expect(ip).toBe('203.0.113.9');
+  });
+
+  it('prefers a real forwarding chain over either', () => {
+    const ip = resolveClientIp({
+      headers: h({ 'x-forwarded-for': '198.51.100.7', 'x-real-ip': '203.0.113.9' }),
+      peer: '10.0.0.1',
+      trustProxy: 1,
+    });
+    expect(ip).toBe('198.51.100.7');
+  });
+
+  it('ignores both when no proxy is declared', () => {
+    // Under trustProxy: false we read no forwarding header at all. X-Real-IP is
+    // exactly as forgeable as the rest of them.
+    const ip = resolveClientIp({
+      headers: h({ 'x-real-ip': '1.2.3.4' }),
+      peer: '198.51.100.7',
+    });
+    expect(ip).toBe('198.51.100.7');
+  });
+});

packages/webdecoy/src/client-ip.ts

@@ -262,14 +262,27 @@ export function resolveClientIp(options: ResolveClientIpOptions): string | undef
 
   const chain = forwardedChain(headers);
 
+  // A proxy that sets only `X-Real-IP` (nginx's default) or the platform's own
+  // header, with no forwarding chain to walk. Consulted here rather than in each
+  // adapter so there is one place that decides what counts as the client — the
+  // adapters reading these themselves is how the leftmost-XFF bug came to live
+  // in three copies.
+  //
+  // Only when the caller has said a proxy exists. Under `false` we read no
+  // forwarding header at all, and these are as forgeable as the rest.
+  const singleHeaderFallback = (): string | undefined =>
+    normalizeIp(readHeader(headers, 'x-real-ip')) ??
+    normalizeIp(readHeader(headers, 'x-vercel-forwarded-for')?.split(',').pop()) ??
+    undefined;
+
   if (typeof trustProxy === 'number') {
     if (!Number.isInteger(trustProxy) || trustProxy < 0) return peer;
     // The client is the Nth entry from the right. A chain shorter than the
     // configured depth means the request did not arrive the way the operator
     // described it, so we believe none of it.
     const index = chain.length - trustProxy;
-    if (index < 0 || index >= chain.length) return peer;
-    return chain[index] ?? peer;
+    if (index < 0 || index >= chain.length) return singleHeaderFallback() ?? peer;
+    return chain[index] ?? singleHeaderFallback() ?? peer;
   }
 
   // CIDR list: walk right to left, past addresses that belong to us. `peer`
@@ -284,5 +297,5 @@ export function resolveClientIp(options: ResolveClientIpOptions): string | undef
   }
   // Every hop was trusted, which means the outermost one is as far as the chain
   // goes — that address is the client.
-  return (full[0] ?? undefined) ?? peer;
+  return (full[0] ?? undefined) ?? singleHeaderFallback() ?? peer;
 }

packages/webdecoy/src/invariants.test.ts

@@ -0,0 +1,151 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+/**
+ * Invariants a reviewer cannot see.
+ *
+ * Every finding in the 0.12.0 / 0.13.0 batch was the same shape: two places
+ * answering one question, and the surface picking the more flattering answer.
+ * The spoofable client IP survived in two adapters after the WordPress plugin
+ * had already fixed the same class of bug, because each call site read perfectly
+ * reasonably on its own and nothing connected them.
+ *
+ * These tests connect them. They read source rather than behaviour on purpose:
+ * the defect is never "this function is wrong", it is "there are two of these
+ * and they disagree", which no unit test of either one can catch.
+ */
+
+const PACKAGES = join(__dirname, '..', '..');
+
+/** Every shipped .ts file across the workspace, tests and builds excluded. */
+function sourceFiles(): string[] {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir)) {
+      if (entry === 'node_modules' || entry === 'dist' || entry === '.turbo') continue;
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.endsWith('.ts')) continue;
+      if (entry.endsWith('.test.ts') || entry.endsWith('.spec.ts')) continue;
+      if (entry.endsWith('.generated.ts')) continue;
+      out.push(full);
+    }
+  };
+  walk(PACKAGES);
+  return out;
+}
+
+/** Lines of `file` that contain `needle`, ignoring comments. */
+function hits(file: string, needle: RegExp): string[] {
+  const found: string[] = [];
+  readFileSync(file, 'utf8')
+    .split('\n')
+    .forEach((line, i) => {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) return;
+      if (needle.test(line)) found.push(`${relative(PACKAGES, file)}:${i + 1}`);
+    });
+  return found;
+}
+
+describe('one answer to "who is the client"', () => {
+  it('resolves the client IP only in client-ip.ts', () => {
+    // Reading a forwarding header anywhere else is how the leftmost-XFF bug
+    // lived in Express and Next.js after the same bug had been fixed elsewhere:
+    // three adapters, three copies, and no one place to correct.
+    const offenders = sourceFiles()
+      .filter((f) => !f.endsWith(join('webdecoy', 'src', 'client-ip.ts')))
+      // Matches *reading* the header to derive an address —
+      // `headers['x-forwarded-for']` or `.get('x-forwarded-for')` — not merely
+      // naming it. The detection engine legitimately lists these among the
+      // headers it inspects for suspicious shapes, and that is not IP
+      // resolution.
+      .flatMap((f) =>
+        hits(
+          f,
+          /(?:\.get\(|\[)\s*['"](?:x-forwarded-for|x-real-ip|cf-connecting-ip)['"]/i,
+        ),
+      );
+
+    if (offenders.length > 0) {
+      throw new Error(
+        'These read a forwarding header directly instead of calling resolveClientIp().\n' +
+          'The leftmost value of X-Forwarded-For is written by the client, so trusting\n' +
+          'it hands an attacker the rate-limit key and the address on every detection.\n' +
+          'Use resolveClientIp({ headers, peer, trustProxy }).\n\n  ' +
+          offenders.join('\n  '),
+      );
+    }
+  });
+});
+
+describe('one answer to "what did we decide"', () => {
+  it('builds decisions only through the Decision class', () => {
+    // protect() returning a plain object literal is how `allowed` and
+    // `conclusion` drift apart, and how a spread silently strips the narrowing
+    // helpers off the result.
+    const sdk = join(PACKAGES, 'webdecoy', 'src', 'sdk.ts');
+    const source = readFileSync(sdk, 'utf8');
+
+    if (/return\s*\{\s*\n?\s*allowed:/.test(source)) {
+      throw new Error(
+        'sdk.ts returns a bare object with an `allowed` key. Every decision must be\n' +
+          'a `new Decision({...})`, or the conclusion and the boolean can disagree\n' +
+          'and the narrowing helpers are lost on the way out.',
+      );
+    }
+  });
+
+  it('never spreads a decision, which would drop its methods', () => {
+    const sdk = readFileSync(join(PACKAGES, 'webdecoy', 'src', 'sdk.ts'), 'utf8');
+
+    if (/\{\s*\.\.\.(result|decision)\s*,/.test(sdk)) {
+      throw new Error(
+        'Spreading a Decision produces a plain object: `isDenied()` and `deniedBy()`\n' +
+          'vanish and the adapter silently loses them. Use decision.withEdge(...) or\n' +
+          'another method that returns a Decision.',
+      );
+    }
+  });
+});
+
+describe('one answer to "is this rule running"', () => {
+  it('every rule that can be starved reports NOT_RUN rather than ALLOW', () => {
+    // A rule that cannot evaluate must say so. Reporting ALLOW makes "checked
+    // and fine" indistinguishable from "never checked", which is how a filter
+    // rule with no enrichment looked like a passing IP reputation check.
+    const starvable = ['filter-rule.ts', 'web-bot-auth-rule.ts', 'rate-limit-rule.ts'];
+
+    for (const name of starvable) {
+      const source = readFileSync(join(PACKAGES, 'webdecoy', 'src', 'rules', name), 'utf8');
+      if (!source.includes("state: 'NOT_RUN'")) {
+        throw new Error(
+          `${name} has no NOT_RUN path. A rule that silently allows when its input ` +
+            `is missing is indistinguishable from one that ran and passed.`,
+        );
+      }
+    }
+  });
+});
+
+describe('the edge build stays edge-compatible', () => {
+  it('no node: import reaches a package that ships to Workers', () => {
+    // check:edge catches this at build time, but only for the entry points it
+    // is pointed at. This catches it in review, with the file named.
+    const edgePackages = ['webdecoy', 'nextjs', 'hono'];
+    const offenders = sourceFiles()
+      .filter((f) => edgePackages.some((p) => f.includes(join(PACKAGES, p, 'src'))))
+      .flatMap((f) => hits(f, /from ['"]node:/));
+
+    if (offenders.length > 0) {
+      throw new Error(
+        'A `node:` import anywhere in these graphs breaks the bundle for Cloudflare\n' +
+          'Workers and Vercel Edge, where most of this SDK is meant to run.\n\n  ' +
+          offenders.join('\n  '),
+      );
+    }
+  });
+});