@webjsdev/cli 0.10.54 → 0.10.55

package/lib/api-gallery.js

@@ -69,9 +69,33 @@ export async function writeApiGallery(appDir) {
     "// Per-segment middleware: it sits beside this route, so it rate-limits ONLY",
     "// /api/features/rate-limit. rateLimit() is backed by the pluggable cache store",
     "// (in-memory by default; point it at Redis to share the window across nodes).",
+    "//",
+    "// `trustProxy: true` decides WHAT gets counted. Without it the bucket key is",
+    "// the socket peer, which is the visitor only when the browser connects to you",
+    "// directly. Behind a CDN or a platform router the peer is that proxy, so a",
+    "// proxy POOL hands out one bucket per proxy and multiplies your real limit by",
+    "// the pool size. With it the key is the forwarded client address instead.",
+    "//",
+    "// It has a precondition: the proxy in front MUST strip an inbound",
+    "// X-Forwarded-For before adding its own, or a client can forge the header and",
+    "// pick its own bucket. Serving with nothing in front? Drop the option, since",
+    "// then the socket peer IS the visitor. WEBJS_NO_TRUST_PROXY=1 outranks it either",
+    "// way. https://webjs.dev/docs/rate-limiting has the full threat model.",
+    "//",
+    "// Behind a CDN, add `clientIpHeader` to name the header carrying the visitor,",
+    "// e.g. `clientIpHeader: 'cf-connecting-ip'` behind Cloudflare. The default",
+    "// chain reads the leftmost X-Forwarded-For entry, which behind a CDN is the",
+    "// CDN's egress address; those are pinned per connection, so the limiter ends up",
+    "// handing out a bucket per connection and refusing nobody. It is left unset",
+    "// here because the right header depends on what you deploy behind.",
     "import { rateLimit } from '@webjsdev/server';",
     "",
-    "export default rateLimit({ window: '10s', max: 5, message: 'Slow down: five requests per ten seconds.' });",
+    "export default rateLimit({",
+    "  window: '10s',",
+    "  max: 5,",
+    "  trustProxy: true,",
+    "  message: 'Slow down: five requests per ten seconds.',",
+    "});",
     "",
   ].join('\n'));
   await writeFile(feat('rate-limit', 'route.ts'), [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.54",
+  "version": "0.10.55",
   "type": "module",
   "description": "The CLI for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Runs the dev and production servers, scaffolds apps, validates conventions, and drives the database. Node 24+ or Bun.",
   "bin": {

package/templates/.agents/skills/webjs/references/built-ins.md

@@ -109,7 +109,11 @@ import { rateLimit } from '@webjsdev/server';
 export default rateLimit({ window: '1m', max: 60 });
 ```
 
-Options: `window` (ms or a string like `'1m'`), `max`, `key` (a string prefix or a `(req) => string` function, defaults to the client IP), `message`, `store`, `trustProxy` (honour the forwarded-IP headers; inert while `WEBJS_NO_TRUST_PROXY=1` is set, which outranks it and keeps the limiter on the framework-stamped peer). Over-limit responds `429` with `Retry-After` and `X-RateLimit-*` headers; an allowed response carries the remaining-quota headers too. For multi-instance scaling, set the global store to Redis once at startup.
+Options: `window` (ms or a string like `'1m'`), `max`, `key` (a string prefix or a `(req) => string` function, defaults to the framework-stamped socket peer), `message`, `store`, `trustProxy` (honour the forwarded-IP headers; inert while `WEBJS_NO_TRUST_PROXY=1` is set, which outranks it and keeps the limiter on the framework-stamped peer). Over-limit responds `429` with `Retry-After` and `X-RateLimit-*` headers; an allowed response carries the remaining-quota headers too. For multi-instance scaling, set the global store to Redis once at startup.
+
+**The default key is the socket PEER, which is the visitor only when the browser connects to you directly.** Deploy behind a CDN or a platform router and the peer is that proxy, so `trustProxy: true` is what a deployed limiter almost always wants. Get it wrong and nothing looks broken: a single shared proxy buckets every visitor together, and a proxy POOL (the common case) hands out one full allowance PER proxy, so the effective limit is multiplied by the pool size while `X-RateLimit-Remaining` still counts down convincingly inside each bucket. Diagnose it by sending the requests over ONE keep-alive connection, which pins them to one peer: counts that descend there but reset on a fresh connection mean you are bucketing proxies. `trustProxy: true` has one precondition, that the proxy in front strips an inbound `X-Forwarded-For` before adding its own (Cloudflare, Railway, Fly, Render, and Vercel do; nginx and Caddy only if configured), or a client can forge the header and choose its own bucket.
+
+**Behind a CDN, `trustProxy: true` alone is usually still wrong, so name the header: `rateLimit({ trustProxy: true, clientIpHeader: 'cf-connecting-ip' })`.** The default chain starts at the leftmost `X-Forwarded-For` entry, which behind Cloudflare is Cloudflare's EGRESS address rather than the visitor. Cloudflare pins one egress IP per connection, so the symptom is a limiter that counts down correctly for a button that pings on one connection and never refuses anyone who opens a new one. When `clientIpHeader` is set it is the only wire header read (falling back to the peer, then `_anon_`), a blank value falls through rather than becoming a key every visitor shares, and a comma chain is split so an appending proxy cannot mint a bucket per hop. The framework will NOT prefer `CF-Connecting-IP` on its own, because Cloudflare overwrites it, which makes it unforgeable behind Cloudflare and forgeable anywhere else: on an nginx or bare-platform deploy a client could then send it and outrank the header the real proxy set. Name the header YOUR edge sets and overwrites.
 
 ## Broadcast
 

package/templates/gallery/app/features/rate-limit/ping/middleware.ts

@@ -1,8 +1,40 @@
 // Per-segment middleware. It sits in the ping/ folder, so it applies ONLY to
 // /features/rate-limit/ping (its route.ts), not to the demo page one level up.
-// rateLimit() returns a standard webjs middleware: return a Response to
-// short-circuit (the 429), or call next() to continue. Keyed by client IP by
-// default; pass `key` to key by user id, API key, etc.
+// rateLimit() returns a standard WebJs middleware: return a Response to
+// short-circuit (the 429), or call next() to continue. Pass `key` to bucket by
+// user id, API key, or anything else instead of by IP.
+//
+// `trustProxy: true` is the load-bearing option here, and it is why this demo
+// works on the deployed site. WITHOUT it the bucket key is the socket peer,
+// which is correct only when the visitor's browser is the thing connecting.
+// Behind a CDN or a platform router the peer is that proxy, so every visitor
+// sharing one proxy shares one bucket, and (worse for a limiter) a proxy POOL
+// hands out one bucket per proxy, which multiplies the real limit by the pool
+// size. WITH it the key comes from the forwarded client address instead.
+//
+// `clientIpHeader` then says WHICH forwarded header carries the visitor, and on
+// this deployment it is load-bearing too. Without it the default chain takes the
+// leftmost X-Forwarded-For entry, which behind Cloudflare is Cloudflare's EGRESS
+// address rather than yours. Cloudflare pins an egress IP per connection, so the
+// limiter hands out one bucket per connection: the count descends convincingly
+// while you hold one connection open and resets the moment a new one opens,
+// which is a limiter that limits nobody. Your address is in CF-Connecting-IP, so
+// that is the header this app names.
+//
+// Copying this into your own app? Name the header YOUR proxy sets, and only
+// after checking it cannot be forged past that proxy. Cloudflare overwrites
+// CF-Connecting-IP, which is what makes it safe HERE and unsafe on a deploy that
+// Cloudflare is not in front of. The same precondition applies to the default
+// chain: the proxy MUST strip an inbound X-Forwarded-For before adding its own.
+// Serving with nothing in front? Drop both options, since then the socket peer
+// IS the visitor. WEBJS_NO_TRUST_PROXY=1 outranks all of it.
+// /docs/rate-limiting has the full threat model.
 import { rateLimit } from '@webjsdev/server';
 
-export default rateLimit({ window: '10s', max: 5, message: 'Slow down: five requests per ten seconds.' });
+export default rateLimit({
+  window: '10s',
+  max: 5,
+  trustProxy: true,
+  clientIpHeader: 'cf-connecting-ip',
+  message: 'Slow down: five requests per ten seconds.',
+});

package/templates/gallery/app/features/route-handler/data/route.ts

@@ -16,7 +16,15 @@ export async function GET(req: Request) {
   return json({
     ok: true,
     at: new Date(), // a real Date; richFetch decodes it back to a Date, not a string
+    // Two addresses, because behind a proxy they are NOT the same and the
+    // difference is invisible until something depends on it (a rate limiter
+    // did, and bucketed proxies instead of visitors). `ip` is the socket peer,
+    // which is the visitor only when the browser connects to you directly.
+    // `forwardedIp` is what the visitor's own CDN header says, which is what a
+    // limiter or an audit log wants. Deployed behind Cloudflare and Railway,
+    // `ip` is a rotating 100.64.x.x router address while `forwardedIp` is you.
     ip: clientIp(req),
+    forwardedIp: clientIp(req, { trustProxy: true, header: 'cf-connecting-ip' }),
     requestId: requestId(),
     userAgent: headers().get('user-agent') ?? 'unknown',
     // cookies() reads the REQUEST cookies. Report how many are present (a

package/templates/gallery/test/rate-limit/rate-limit.test.ts

@@ -0,0 +1,91 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+import { createRequestHandler } from '@webjsdev/server';
+import { testRequest } from '@webjsdev/server/testing';
+
+const appDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+const PING = '/features/rate-limit/ping';
+
+// The demo's own numbers, so a change to the middleware that these tests do not
+// notice is a change that made them stale rather than one they tolerated.
+const MAX = 5;
+
+// Each test picks its own visitor addresses. The limiter counts into the global
+// in-memory cache store, which outlives a handler instance, so two tests sharing
+// an address would share a bucket and the second would start already exhausted.
+// The demo names CF-Connecting-IP, because that is the header carrying the
+// visitor on the deployment it runs on. Every request here also carries an
+// X-Forwarded-For that DISAGREES, standing in for the CDN egress address the
+// real deploy puts there, so a test that passes only because the two agree
+// cannot exist.
+function ping(handle: (req: Request) => Promise<Response>, visitor: string, cdnEgress = '172.68.1.9') {
+  return testRequest(handle, PING, {
+    headers: { 'cf-connecting-ip': visitor, 'x-forwarded-for': cdnEgress },
+  });
+}
+
+test('the demo limits one visitor to five requests per window', async () => {
+  const app = await createRequestHandler({ appDir, dev: true });
+  const visitor = '203.0.113.10';
+
+  for (let i = 1; i <= MAX; i += 1) {
+    const res = await ping(app.handle, visitor);
+    assert.equal(res.status, 200, `request ${i} is inside the window`);
+    assert.equal(res.headers.get('x-ratelimit-remaining'), String(MAX - i));
+  }
+
+  const limited = await ping(app.handle, visitor);
+  assert.equal(limited.status, 429, 'the sixth request is refused');
+  assert.equal(limited.headers.get('retry-after'), '10');
+});
+
+// This is the assertion the deployed bug would have failed. Both visitors reach
+// the app through the same proxy, so the socket peer is identical for both and a
+// peer-keyed limiter would count them into ONE bucket: exhausting the first
+// would refuse the second. Keying on the forwarded address keeps them apart.
+//
+// Counterfactual, proven at this commit: removing `trustProxy: true` from
+// gallery/app/features/rate-limit/ping/middleware.ts fails this test on the last
+// assertion (the second visitor gets a 429), while the single-visitor test above
+// still passes. That asymmetry is the point, since the single-visitor test is
+// what a peer-keyed limiter satisfies too.
+test('one visitor exhausting the window does not refuse another behind the same proxy', async () => {
+  const app = await createRequestHandler({ appDir, dev: true });
+  const noisy = '203.0.113.20';
+  const bystander = '203.0.113.21';
+
+  for (let i = 0; i < MAX; i += 1) await ping(app.handle, noisy);
+  assert.equal((await ping(app.handle, noisy)).status, 429, 'the noisy visitor is limited');
+
+  const other = await ping(app.handle, bystander);
+  assert.equal(other.status, 200, 'a different visitor keeps their own window');
+  assert.equal(other.headers.get('x-ratelimit-remaining'), String(MAX - 1));
+});
+
+// The half `trustProxy: true` alone did not deliver, and the one the live site
+// disproved (#1389). A CDN gives each connection a different egress address, so
+// one visitor opening several connections arrives with several X-Forwarded-For
+// values and ONE CF-Connecting-IP. Keyed on XFF that visitor gets a fresh bucket
+// per connection and is never refused, which is what shipped and read as working.
+//
+// Counterfactual, proven at this commit: removing `clientIpHeader` from the
+// middleware fails this test at the sixth request AND the two-visitor test
+// above, while the single-visitor test still passes. The one that survives is
+// the one whose requests all carry the same CDN address, which is exactly the
+// blind spot that let the first fix look complete on a real deployment.
+test('one visitor is limited across connections, whatever CDN address they arrive on', async () => {
+  const app = await createRequestHandler({ appDir, dev: true });
+  const visitor = '203.0.113.30';
+
+  for (let i = 1; i <= MAX; i += 1) {
+    const res = await ping(app.handle, visitor, `172.68.9.${i}`);
+    assert.equal(res.status, 200, `request ${i} arrives on its own CDN egress address`);
+  }
+
+  const limited = await ping(app.handle, visitor, '172.68.9.99');
+  assert.equal(limited.status, 429, 'a new CDN egress address does not buy a new window');
+});

package/templates/scripts/clear-gallery.mjs

@@ -53,10 +53,13 @@ if (!existsSync(join(root, 'app/features'))) {
 
 // 1) Gallery route trees + example metadata routes. `app/api/auth` is the auth
 // card's createAuth handler (it lives at the app root, not under app/features/,
-// because createAuth hardcodes /api/auth/*), and `test/auth` is the auth card's
-// request-pipeline test, so both are removed here alongside the card.
+// because createAuth hardcodes /api/auth/*), and `test/auth` + `test/rate-limit`
+// are card-owned request-pipeline tests, so they are removed alongside their
+// cards. A card that ships a test under test/ MUST be listed here: the prune
+// below only removes test/ once it is EMPTY, so a missed entry silently leaves
+// the reset app with a test suite for a card it no longer has.
 const galleryPaths = [
-  'app/features', 'app/examples', 'app/sitemaps', 'app/api/auth', 'test/auth',
+  'app/features', 'app/examples', 'app/sitemaps', 'app/api/auth', 'test/auth', 'test/rate-limit',
   'app/icon.ts', 'app/apple-icon.ts', 'app/manifest.ts', 'app/opengraph-image.ts',
   'app/twitter-image.ts', 'app/robots.ts', 'app/sitemap.ts',
   'app/global-error.ts', 'app/global-not-found.ts',