fix(overpass): keyless gate, loopback admission headroom and per-phase arrival budgets

Address gekh's review of 69a87fe2:

- P1: /api/overpass now uses admitSameSiteKeyless, like /api/terrain/heights,
  so an instance behind the README's reverse proxy keeps its Overpass-backed
  layers; cross-site shapes are still refused and forwarding headers no
  longer launder them. SECURITY.md, the gate header and CURRENT-STATE say so.
- P2: admission keys IPv6 peers by /64 and folds IPv4-mapped peers
  (clientNetworkKey), and loopback has its own 300/min window outside the
  900/min global, so a few LAN peers cannot lock the owner's browser out.
- P2 (track): the settle and reveal frames each get their own 500 ms budget,
  measured from moveEnd and from the settle frame respectively, so a ~300 ms
  SwiftShader frame no longer trips the reveal deadline while both stay
  inside the 1 s idle refresh.
- Smaller: drop the dead settings-block check and stale probe comment in
  query.js, clamp whitespace-tolerant [ timeout : N ], and add tests for the
  global window, the /64 keying, loopback headroom, proxied admission and
  cache hits spending admission but not upstream budget.

Co-Authored-By: Claude Fable 5.1 <[email protected]>

server/providers/common/rate-limit.js

@@ -1,3 +1,4 @@
+import { isIPv6 } from 'node:net';
 import { makeRateLimiter } from '../../../src/sources/rateLimit.js';
 export { makeRateLimiter } from '../../../src/sources/rateLimit.js';
 
@@ -60,3 +61,46 @@ export function makeCostRateLimiter(envValue, defaultPerMin) {
 export function clientKey(req) {
   return String(req.socket?.remoteAddress || 'local');
 }
+
+const IPV4_MAPPED_RE = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i;
+
+/**
+ * Whether a socket peer address is this machine: IPv4 loopback in any of its
+ * forms (`127.0.0.0/8`, including the IPv4-mapped `::ffff:127.x` a dual-stack
+ * listener reports) or the IPv6 loopback. Non-address keys are not loopback.
+ * @param {string} address - A `clientKey` value.
+ * @returns {boolean}
+ */
+export function isLoopbackPeer(address) {
+  const raw = String(address || '');
+  const v4 = IPV4_MAPPED_RE.exec(raw)?.[1] ?? raw;
+  return v4.startsWith('127.') || raw === '::1';
+}
+
+/**
+ * Rate-limit key that survives address rotation, for limiters whose global
+ * backstop everyone shares. IPv6 privacy extensions hand one host a fresh
+ * address at will inside its /64, so keying by the full address lets a single
+ * host mint per-peer quota until the global window closes for everyone else.
+ * IPv6 peers are keyed by their /64 prefix instead, and an IPv4-mapped
+ * address folds to its IPv4 form so one host cannot hold two buckets. Any
+ * other value (IPv4, or the `local` fallback) passes through unchanged.
+ * @param {import('node:http').IncomingMessage} req
+ * @returns {string}
+ */
+export function clientNetworkKey(req) {
+  const address = clientKey(req);
+  const mapped = IPV4_MAPPED_RE.exec(address);
+  if (mapped) return mapped[1];
+  const bare = address.replace(/%.*$/, ''); // link-local zone id
+  if (!isIPv6(bare)) return address;
+  const [head, tail = ''] = bare.split('::');
+  const headParts = head ? head.split(':') : [];
+  const tailParts = tail ? tail.split(':') : [];
+  const missing = Math.max(0, 8 - headParts.length - tailParts.length);
+  const hextets = [...headParts, ...Array(missing).fill('0'), ...tailParts];
+  return `${hextets
+    .slice(0, 4)
+    .map((h) => h.toLowerCase().replace(/^0+(?=.)/, ''))
+    .join(':')}::/64`;
+}

server/providers/common/rateLimitKeys.test.mjs

@@ -0,0 +1,37 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { clientNetworkKey, isLoopbackPeer } from './rate-limit.js';
+
+const req = (remoteAddress) => ({ socket: { remoteAddress } });
+
+test('clientNetworkKey keys IPv6 peers by /64 and folds IPv4-mapped peers', () => {
+  assert.equal(clientNetworkKey(req('2001:db8:1:2::1')), '2001:db8:1:2::/64');
+  assert.equal(
+    clientNetworkKey(req('2001:0db8:0001:0002:abcd:ef01:2345:6789')),
+    '2001:db8:1:2::/64',
+  );
+  assert.equal(clientNetworkKey(req('2001:DB8::1')), '2001:db8:0:0::/64');
+  assert.equal(clientNetworkKey(req('fe80::1%en0')), 'fe80:0:0:0::/64');
+  assert.equal(clientNetworkKey(req('::1')), '0:0:0:0::/64');
+  assert.equal(clientNetworkKey(req('::ffff:10.0.0.5')), '10.0.0.5');
+  assert.equal(clientNetworkKey(req('10.0.0.5')), '10.0.0.5');
+  assert.equal(clientNetworkKey(req(undefined)), 'local');
+  assert.equal(clientNetworkKey(req('not-an-address')), 'not-an-address');
+});
+
+test('isLoopbackPeer recognizes every loopback form and nothing else', () => {
+  for (const address of ['127.0.0.1', '127.9.9.9', '::1', '::ffff:127.0.0.1']) {
+    assert.equal(isLoopbackPeer(address), true, address);
+  }
+  for (const address of [
+    '10.0.0.1',
+    '::ffff:10.0.0.1',
+    '2001:db8::1',
+    '::2',
+    'local',
+    '',
+    undefined,
+  ]) {
+    assert.equal(isLoopbackPeer(address), false, String(address));
+  }
+});

server/providers/common/same-site.js

@@ -58,7 +58,7 @@ function forwardedProtocol(req) {
 
 /**
  * Cross-site gate for keyless routes the map needs in order to render
- * (`/api/terrain/heights`). It refuses the same cross-site browser shapes as
+ * (`/api/terrain/heights`, `/api/overpass`). It refuses the same cross-site browser shapes as
  * `admitSameSite` (a `Sec-Fetch-Site` other than same-origin/none, a foreign
  * or opaque `Origin`) but does not refuse reverse-proxy forwarding headers:
  * those protect credentials and spend, which a keyless route has neither of,

server/providers/overpass.js

@@ -1,6 +1,11 @@
-import { makeRateLimiter, clientKey } from './common/rate-limit.js';
+import {
+  makeRateLimiter,
+  clientKey,
+  clientNetworkKey,
+  isLoopbackPeer,
+} from './common/rate-limit.js';
 import { readRequestBodyCapped } from './common/request.js';
-import { admitSameSite } from './common/same-site.js';
+import { admitSameSiteKeyless } from './common/same-site.js';
 import {
   OVERPASS_MAX_BODY_BYTES,
   OVERPASS_MAX_CONCURRENT,
@@ -29,10 +34,16 @@ const _overpassInFlight = new Map();
 let _overpassConcurrent = 0;
 
 // Bound body-reading and validation work, including malformed requests and
-// cache hits. Keep the tighter upstream budget below independent of this gate.
-const _overpassRequestLimiter = makeRateLimiter({
-  windowMs: 60_000,
-  max: 300,
+// cache hits, before a byte is read. Non-loopback peers share one global
+// window so address rotation cannot mint admission without bound (IPv6 peers
+// are keyed by /64 for the same reason); loopback — the owner's own browser
+// and the repo QA harnesses — has its own per-peer window outside that global,
+// so a few busy LAN peers cannot lock the owner out of the map. Keep the
+// tighter upstream budget below independent of this gate.
+const OVERPASS_ADMISSION_WINDOW = { windowMs: 60_000, max: 300 };
+const _overpassLoopbackAdmission = makeRateLimiter(OVERPASS_ADMISSION_WINDOW);
+const _overpassPeerAdmission = makeRateLimiter({
+  ...OVERPASS_ADMISSION_WINDOW,
   globalMax: 900,
 });
 
@@ -42,6 +53,20 @@ const _overpassRateLimiter = makeRateLimiter({
   globalMax: 300,
 });
 
+/**
+ * Spend one admission slot for this request's peer; false when it is over its
+ * window (or, for a non-loopback peer, when the shared global window is full).
+ * @param {import('http').IncomingMessage} req
+ * @param {string} peer - `clientNetworkKey(req)`.
+ * @returns {boolean}
+ */
+function admitOverpassRequest(req, peer) {
+  const admit = isLoopbackPeer(clientKey(req))
+    ? _overpassLoopbackAdmission
+    : _overpassPeerAdmission;
+  return admit(peer);
+}
+
 /**
  * Write a completed Overpass payload to the HTTP response.
  *
@@ -103,8 +128,13 @@ function overpassProxy({ routing = {} } = {}) {
           return;
         }
 
-        if (admitSameSite(req, res)) return;
-        if (!_overpassRequestLimiter(clientKey(req))) {
+        // Keyless gate: refuses cross-site browser requests but, unlike the
+        // cost-bearing routes, admits the forwarding headers a reverse proxy
+        // adds — the layers that depend on Overpass must keep working for an
+        // instance deployed the way the README documents.
+        if (admitSameSiteKeyless(req, res)) return;
+        const peer = clientNetworkKey(req);
+        if (!admitOverpassRequest(req, peer)) {
           res.writeHead(429, {
             'Content-Type': 'application/json',
             'Cache-Control': 'no-store',
@@ -163,7 +193,7 @@ function overpassProxy({ routing = {} } = {}) {
           // requests; boundary-class queries keep their month-long TTL.
           readDisk: () =>
             readOverpassDisk(cacheKey, overpassDiskTtlMs(cacheKey)),
-          allowUpstream: () => _overpassRateLimiter(clientKey(req)),
+          allowUpstream: () => _overpassRateLimiter(peer),
         });
         if (preflight.source === 'RATE_LIMITED') {
           res.writeHead(429, {

server/providers/overpass/query.js

@@ -122,12 +122,14 @@ function sanitizeOverpassBody(rawBody) {
   const boundedSets = new Set();
   for (let stmt of withoutTags.split(';')) {
     stmt = stmt.trim();
-    if (!stmt || stmt.startsWith('[') || /^out\b/.test(stmt)) continue;
+    // The settings block (`[out:json][timeout:25]`) was blanked together with
+    // the tag filters, so it arrives here as an empty statement.
+    if (!stmt || /^out\b/.test(stmt)) continue;
 
-    // Strip output-set assignments (NOT input bounds). Bracket tag filters were
-    // removed above so a tag KEY/value (e.g. `way[is_in]`, `node[around]`) cannot be
-    // misread as a spatial bound. Bounds live in (...) / function calls / set
-    // refs, never inside [...], so the probe loses nothing real.
+    // Strip output-set assignments (NOT input bounds). With the tag filters
+    // already gone, a tag KEY/value (e.g. `way[is_in]`, `node[around]`) cannot
+    // be misread as a spatial bound; bounds live in (...) / function calls /
+    // set refs, never inside [...], so nothing real was lost.
     const outSets = [];
     const probe = stmt.replace(/->\s*\.(\w+)/g, (_, name) => {
       outSets.push(name);
@@ -166,8 +168,10 @@ function sanitizeOverpassBody(rawBody) {
     if (bounded) for (const name of outSets) boundedSets.add(name);
   }
 
+  // Tolerate whitespace around the directive so `[ timeout : N ]` is clamped
+  // rather than passed through as written.
   const clamped = data.replace(
-    /\[timeout:\s*(\d+)\s*\]/gi,
+    /\[\s*timeout\s*:\s*(\d+)\s*\]/gi,
     (_, n) =>
       `[timeout:${Math.min(Number(n) || OVERPASS_MAX_QL_TIMEOUT, OVERPASS_MAX_QL_TIMEOUT)}]`,
   );

server/providers/overpass/requestAdmission.test.mjs

@@ -3,6 +3,7 @@ import assert from 'node:assert/strict';
 import { Readable } from 'node:stream';
 import { spawnSync } from 'node:child_process';
 import { overpassProxy } from '../overpass.js';
+import { _overpassCache } from './cache.js';
 import { sanitizeOverpassBody } from './query.js';
 
 const form = (query) => `data=${encodeURIComponent(query)}`;
@@ -37,6 +38,15 @@ test('bounded queries preserve quoted brackets, comments, multiple tags and time
       query.replace('[timeout:999]', '[timeout:30]'),
     );
   }
+  // Whitespace inside the directive is clamped too, not passed through.
+  const spaced = sanitizeOverpassBody(
+    form('[out:json][ timeout : 999 ];node(around:20,1,1);out;'),
+  );
+  assert.equal(spaced.ok, true);
+  assert.equal(
+    new URLSearchParams(spaced.body).get('data'),
+    '[out:json][timeout:30];node(around:20,1,1);out;',
+  );
 });
 
 test('a burst of maximum-size unterminated filters completes within a bounded process deadline', () => {
@@ -126,7 +136,13 @@ for (const hook of ['configureServer', 'configurePreviewServer']) {
       { 'sec-fetch-site': 'cross-site' },
       { 'sec-fetch-site': 'same-site' },
       { origin: 'null' },
-      { 'x-forwarded-for': '127.0.0.1' },
+      // Forwarding headers do not launder a cross-site request.
+      { 'x-forwarded-for': '10.0.0.9', 'sec-fetch-site': 'cross-site' },
+      {
+        'x-forwarded-proto': 'https',
+        origin: 'http://localhost:4173',
+        'sec-fetch-site': 'same-origin',
+      },
     ]) {
       const response = await call(route, { headers, forbidRead: true });
       assert.equal(response.statusCode, 403);
@@ -136,12 +152,23 @@ for (const hook of ['configureServer', 'configurePreviewServer']) {
   });
 }
 
-test('same-origin, LAN and non-browser requests still reach validation; GET status stays available', async () => {
+test('same-origin, LAN, proxied and non-browser requests still reach validation; GET status stays available', async () => {
   const route = handler();
   for (const headers of [
     {},
     { origin: 'http://localhost:4173', 'sec-fetch-site': 'same-origin' },
     { host: '192.168.1.10:4173', origin: 'http://192.168.1.10:4173' },
+    // The README's reverse-proxy deployment: Overpass is keyless, so the
+    // forwarding headers the proxy adds are admitted (as for terrain heights).
+    {
+      host: 'globe.example.lan',
+      origin: 'https://globe.example.lan',
+      'sec-fetch-site': 'same-origin',
+      'x-forwarded-for': '203.0.113.7',
+      'x-forwarded-proto': 'https',
+      'x-forwarded-host': 'globe.example.lan',
+    },
+    { 'x-forwarded-for': '127.0.0.1' },
   ]) {
     const response = await call(route, { headers });
     assert.equal(response.statusCode, 400);
@@ -176,3 +203,117 @@ test('invalid requests spend admission quota before parsing, including on an unc
   now += 60001;
   assert.equal((await call(route, { peer })).statusCode, 400);
 });
+
+// Each limiter test mocks Date.now well past the previous test's window so the
+// module-level limiters start from an empty window.
+
+test('the 900/min global window spans non-loopback peers only; loopback keeps its own window', async (t) => {
+  let now = Date.now() + 3_600_000;
+  t.mock.method(Date, 'now', () => now);
+  t.mock.method(globalThis, 'fetch', () =>
+    assert.fail('unexpected upstream fetch'),
+  );
+  const route = handler();
+  for (const peer of ['10.0.0.1', '10.0.0.2', '10.0.0.3']) {
+    for (let i = 0; i < 300; i++) {
+      assert.equal((await call(route, { peer })).statusCode, 400, peer);
+    }
+  }
+  const starved = await call(route, { peer: '10.0.0.4', forbidRead: true });
+  assert.equal(starved.statusCode, 429, 'global window is full for LAN peers');
+  assert.equal(starved.reads, 0);
+  for (const peer of ['127.0.0.1', '::1', '::ffff:127.0.0.1']) {
+    const owner = await call(route, { peer });
+    assert.equal(owner.statusCode, 400, `${peer} is admitted past the global`);
+    assert.equal(owner.reads, 1);
+  }
+  now += 60_001;
+  assert.equal((await call(route, { peer: '10.0.0.4' })).statusCode, 400);
+});
+
+test('IPv6 peers share a /64 admission bucket and IPv4-mapped peers fold to IPv4', async (t) => {
+  let now = Date.now() + 7_200_000;
+  t.mock.method(Date, 'now', () => now);
+  t.mock.method(globalThis, 'fetch', () =>
+    assert.fail('unexpected upstream fetch'),
+  );
+  const route = handler();
+  for (let i = 0; i < 300; i++) {
+    assert.equal(
+      (await call(route, { peer: `2001:db8:1:2::${(i % 200) + 1}` }))
+        .statusCode,
+      400,
+    );
+  }
+  const rotated = await call(route, {
+    peer: '2001:db8:1:2:ffff:ffff:ffff:9',
+    forbidRead: true,
+  });
+  assert.equal(rotated.statusCode, 429, 'a rotating host stays in one bucket');
+  assert.equal((await call(route, { peer: '2001:db8:1:3::1' })).statusCode, 400);
+  for (let i = 0; i < 300; i++) {
+    assert.equal(
+      (await call(route, { peer: '::ffff:10.1.1.1' })).statusCode,
+      400,
+    );
+  }
+  const unmapped = await call(route, { peer: '10.1.1.1', forbidRead: true });
+  assert.equal(unmapped.statusCode, 429, 'mapped and bare IPv4 share a bucket');
+  now += 60_001;
+  assert.equal((await call(route, { peer: '10.1.1.1' })).statusCode, 400);
+});
+
+test('cache hits spend admission budget but not the 90/min upstream budget', async (t) => {
+  let now = Date.now() + 10_800_000;
+  t.mock.method(Date, 'now', () => now);
+  const prior = process.env.OVERPASS_UPSTREAMS;
+  process.env.OVERPASS_UPSTREAMS = 'https://overpass.example/api/interpreter';
+  t.after(() => {
+    if (prior === undefined) delete process.env.OVERPASS_UPSTREAMS;
+    else process.env.OVERPASS_UPSTREAMS = prior;
+    _overpassCache.delete(hitKey);
+  });
+  let fetches = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    fetches++;
+    // Not data: nothing is cached or written to disk by this test.
+    return new Response('upstream unavailable', { status: 503 });
+  });
+  const hit = 'node(around:20,1,1);out;';
+  const hitKey = `data=${encodeURIComponent(hit)}`;
+  _overpassCache.set(hitKey, {
+    status: 200,
+    body: '{"elements":[]}',
+    contentType: 'application/json',
+    endpoint: 'https://overpass.example/api/interpreter',
+    cachedAt: now,
+  });
+  const route = handler();
+  const peer = '10.7.7.7';
+  // More cache hits than the upstream limiter would allow per peer.
+  for (let i = 0; i < 100; i++) {
+    const response = await call(route, { peer, body: form(hit) });
+    assert.equal(response.statusCode, 200);
+    assert.equal(response.headers['x-overpass-cache'], 'HIT');
+  }
+  assert.equal(fetches, 0);
+  const miss = await call(route, {
+    peer,
+    body: form('node(around:20,2,2);out;'),
+  });
+  assert.equal(fetches, 1, 'the first miss still reaches upstream');
+  assert.notEqual(miss.statusCode, 429);
+  for (let i = 0; i < 199; i++) {
+    assert.equal(
+      (await call(route, { peer, body: form(hit) })).statusCode,
+      200,
+    );
+  }
+  const exhausted = await call(route, {
+    peer,
+    body: form(hit),
+    forbidRead: true,
+  });
+  assert.equal(exhausted.statusCode, 429, 'hits spent the admission window');
+  assert.equal(exhausted.reads, 0);
+});