Stage 0-2 server spine: db, scheduler, REST, auth, economy, map

Built: SQLite (node:sqlite) via server/db.js with checksummed migrations, injectable clock, persistent event
scheduler with catch-up, tiny REST router (error envelope, idempotency keys, rate limits, bearer tokens with scrypt
passwords), lazy-resource economy in public/js/rules.js + data.js, build/cancel/rename commands, seeded map +
spawn ring, generated docs/openapi.json. NETWALL net.js/static.js reused.
Tested: manual smoke run only (signup, town view, build, map). No unit tests or e2e yet.
NOT done: military, expansion, social, client, push, deploy docs, bots/admin.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
This commit is contained in:
jvanvik 2026-10-11 18:07:42 +02:00
parent 9fa76d53a8
commit b56b13880e
39 changed files with 4450 additions and 0 deletions

274
server/net.js Normal file
View file

@ -0,0 +1,274 @@
'use strict';
/*
* Networking helpers: client IP / reverse-proxy awareness, Origin check, token bucket,
* dual-stack listen and the "what URLs can I open" list for the start-up banner.
* No dependencies beyond Node core.
*/
const net = require('net');
const os = require('os');
const { performance } = require('perf_hooks');
// ---------------------------------------------------------------- addresses
// "::ffff:1.2.3.4" -> "1.2.3.4"; strips an IPv6 zone ("fe80::1%eth0"); lower-cases.
function normalizeIp(addr) {
if (typeof addr !== 'string') return '';
let a = addr.trim().toLowerCase();
const z = a.indexOf('%');
if (z >= 0) a = a.slice(0, z);
if (a.startsWith('::ffff:') && net.isIPv4(a.slice(7))) a = a.slice(7);
return a;
}
// Loopback, RFC1918, link-local, unique-local (fc00::/7) and the unspecified address.
function isPrivateIp(addr) {
const ip = normalizeIp(addr);
if (net.isIPv4(ip)) {
const [a, b] = ip.split('.').map(Number);
return a === 127 || a === 10 || a === 0 ||
(a === 172 && b >= 16 && b <= 31) ||
(a === 192 && b === 168) ||
(a === 169 && b === 254);
}
if (net.isIPv6(ip)) {
if (ip === '::1' || ip === '::') return true;
const first = ip.startsWith('::') ? 0 : parseInt(ip.split(':')[0], 16);
if ((first & 0xfe00) === 0xfc00) return true; // fc00::/7
if ((first & 0xffc0) === 0xfe80) return true; // fe80::/10
}
return false;
}
// 'auto' | true | false, also from env-style strings ('1', '0', 'true', 'off' ...).
function parseTrustProxy(v) {
if (v === undefined || v === null || v === '') return 'auto';
if (v === true || v === false) return v;
if (typeof v === 'number') return v !== 0;
const s = String(v).trim().toLowerCase();
if (s === 'auto') return 'auto';
if (['1', 'true', 'yes', 'on'].includes(s)) return true;
if (['0', 'false', 'no', 'off'].includes(s)) return false;
throw new Error('invalid trustProxy value: ' + JSON.stringify(v) + " (use 'auto', '1' or '0')");
}
function peerIp(req) {
return normalizeIp(req.socket && req.socket.remoteAddress) || 'unknown';
}
// TRUSTED_PROXIES: extra proxy addresses believed under TRUST_PROXY=auto, on top of the private ranges. The built-in
// "private" list misses a proxy that reaches the game over a global IPv6 address, Tailscale / CGNAT (100.64.0.0/10) or
// any other routable address. Accepts an array or a comma separated string of IPs and CIDRs, IPv4 or IPv6
// ("100.64.0.0/10, 2001:db8::6, 2001:db8:1::/48"). Returns null for an empty list, throws on a malformed entry (a
// typo must stop the start-up, not silently leave the proxy untrusted). The result has .has(ip) and .list.
function parseTrustedProxies(v) {
const items = Array.isArray(v) ? v : String(v === undefined || v === null ? '' : v).split(',');
const list = items.map((s) => String(s).trim()).filter(Boolean);
if (!list.length) return null;
const bl = new net.BlockList();
for (const item of list) {
const slash = item.indexOf('/');
const addr = normalizeIp(slash < 0 ? item : item.slice(0, slash));
const type = net.isIPv4(addr) ? 'ipv4' : net.isIPv6(addr) ? 'ipv6' : null;
const max = type === 'ipv4' ? 32 : 128;
const prefixText = slash < 0 ? null : item.slice(slash + 1);
const prefix = prefixText === null ? max : (/^\d{1,3}$/.test(prefixText) ? Number(prefixText) : NaN);
if (!type || !(prefix >= 0 && prefix <= max) ||
(item.startsWith('::ffff:') && slash >= 0)) { // a v4-mapped prefix would need its own arithmetic: write the IPv4 form
throw new Error('invalid TRUSTED_PROXIES entry ' + JSON.stringify(item) + ' (use an IP or CIDR such as 100.64.0.0/10 or 2001:db8::6)');
}
if (prefixText === null) bl.addAddress(addr, type); else bl.addSubnet(addr, prefix, type);
}
return {
list,
has(ip) {
const a = normalizeIp(ip);
return net.isIPv4(a) ? bl.check(a, 'ipv4') : net.isIPv6(a) ? bl.check(a, 'ipv6') : false;
},
};
}
// Does this request come from a proxy whose X-Forwarded-* headers we believe? `trusted` = parseTrustedProxies() result.
function isTrustedPeer(req, trustProxy, trusted) {
if (trustProxy === true) return true;
if (trustProxy === false) return false;
const ip = peerIp(req);
return isPrivateIp(ip) || !!(trusted && trusted.has(ip));
}
// One entry of a forwarding header ("203.0.113.9", "[2001:db8::5]:443", "1.2.3.4:5555") -> bare IP or null.
function parseForwardedEntry(raw) {
let a = String(raw).trim();
if (!a) return null;
if (a[0] === '[') { const e = a.indexOf(']'); if (e < 0) return null; a = a.slice(1, e); }
else if (/^\d+\.\d+\.\d+\.\d+:\d+$/.test(a)) a = a.slice(0, a.lastIndexOf(':'));
a = normalizeIp(a);
return net.isIP(a) ? a : null;
}
// First address of a header value like "203.0.113.9, 10.0.0.2" (used for X-Real-IP, which holds one address).
function firstForwardedIp(value) {
return typeof value === 'string' ? parseForwardedEntry(value.split(',')[0]) : null;
}
// The client address in an X-Forwarded-For built by proxies that APPEND (nginx $proxy_add_x_forwarded_for, which is
// what nginx Proxy Manager does): everything left of the proxy's own entry is whatever the client chose to send, so
// the first entry is forgeable (it lets a client dodge the per-IP cap or use up somebody else's). Walk from the
// right instead, skip the private addresses of our own proxy hops and take the first public one. A chain that is
// private all the way (LAN clients) yields its rightmost entry, i.e. what the nearest proxy saw; junk -> null.
function forwardedClientIp(value) {
if (typeof value !== 'string') return null;
const parts = value.split(',');
let nearest = null;
for (let i = parts.length - 1; i >= 0; i--) {
const ip = parseForwardedEntry(parts[i]);
if (!ip) return nearest;
if (!isPrivateIp(ip)) return ip;
if (!nearest) nearest = ip;
}
return nearest;
}
// The address used for logging and the per-IP socket cap.
function clientIp(req, trustProxy, trusted) {
const peer = peerIp(req);
if (!isTrustedPeer(req, trustProxy, trusted)) return peer;
return forwardedClientIp(req.headers['x-forwarded-for']) ||
firstForwardedIp(req.headers['x-real-ip']) || peer;
}
// ---------------------------------------------------------------- Origin check
// Scheme-less, lower-case host name and port of a bare host ("Game.Example.com:443"), a Host header or a full origin
// ("https://x.example"): { name, port }, with port '' for none or for the default ports 80 / 443. null if unusable.
function hostParts(s) {
if (typeof s !== 'string') return null;
let v = s.trim();
if (!v) return null;
if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(v)) {
if (!/^[a-z0-9._:\[\]-]+$/i.test(v)) return null; // a bare host[:port], nothing else
v = 'http://' + v;
}
let u;
try { u = new URL(v); } catch (e) { return null; }
if (!u.hostname) return null;
const port = u.port; // '' for the scheme's own default
return { name: u.hostname.toLowerCase(), port: port && port !== '80' && port !== '443' ? port : '' }; // IPv6 keeps its brackets
}
// "host[:port]" form of hostParts().
function normalizeHost(s) {
const p = hostParts(s);
return p ? (p.port ? p.name + ':' + p.port : p.name) : null;
}
// Returns true when a WebSocket upgrade with this Origin may proceed.
// no Origin header -> true (non-browser clients)
// Origin host == Host -> true
// Origin host == X-Forwarded-Host (first) -> true, only when the peer is a trusted proxy
// Origin host name == Host name, Host without a port -> true, only when the peer is a trusted proxy (see below)
// Origin host in allowedOrigins -> true
// opts: { trustProxy, trustedProxies (parseTrustedProxies() result), allowedOrigins }.
function originAllowed(req, opts) {
const origin = req.headers.origin;
if (origin === undefined) return true;
const o = (typeof origin === 'string' && origin.toLowerCase() !== 'null' && /^[a-z][a-z0-9+.-]*:\/\//i.test(origin))
? hostParts(origin) : null;
if (!o) return false;
const h = hostParts(req.headers.host);
if (h && o.name === h.name && o.port === h.port) return true;
if (isTrustedPeer(req, opts.trustProxy, opts.trustedProxies)) {
const xfh = req.headers['x-forwarded-host'];
if (typeof xfh === 'string' && normalizeHost(xfh.split(',')[0]) === normalizeHost(origin)) return true;
// Published on a port other than 80/443 (https://game.example.com:8443) behind nginx / nginx Proxy Manager: their
// "proxy_set_header Host $host" drops the port, so Host is "game.example.com" while the browser's Origin keeps
// ":8443", and neither the X-Forwarded-Host nor an ALLOWED_ORIGINS entry written without the port helps. A browser that
// talks to this server directly on its port (8080 by default, never 80/443 unless you chose that) puts the port in
// Host, so a Host WITHOUT one from a trusted proxy is what a stripped port looks like: accept the same host name on
// any port. Another name still fails.
if (h && !h.port && o.name === h.name) return true;
}
const on = normalizeHost(origin);
for (const a of opts.allowedOrigins || []) if (on === normalizeHost(a)) return true;
return false;
}
// ---------------------------------------------------------------- token bucket
class TokenBucket {
constructor(ratePerSec, burst) {
this.rate = ratePerSec; this.burst = burst;
this.tokens = burst; this.last = performance.now();
}
// true when the event is allowed. `now` (ms) defaults to a monotonic clock: with Date.now() a wall-clock step
// backwards (NTP, a VM resume) would stop the refill for as long as the step is large and get sockets closed 4429.
take(now) {
now = now === undefined ? performance.now() : now;
const dt = now - this.last;
if (dt > 0) { this.tokens = Math.min(this.burst, this.tokens + dt * this.rate / 1000); this.last = now; }
if (this.tokens < 1) return false;
this.tokens -= 1;
return true;
}
}
// ---------------------------------------------------------------- listen
const V6_FALLBACK_CODES = new Set(['EAFNOSUPPORT', 'EADDRNOTAVAIL', 'EPROTONOSUPPORT', 'ENOTSUP', 'EINVAL', 'ENOPROTOOPT', 'EPFNOSUPPORT']);
function listenOnce(server, opts) {
return new Promise((resolve, reject) => {
const onError = (err) => { server.removeListener('listening', onListening); reject(err); };
const onListening = () => { server.removeListener('error', onError); resolve(); };
server.once('error', onError);
server.once('listening', onListening);
try { server.listen(opts); } catch (err) { onError(err); }
});
}
// Binds `host`. The default '::' is bound dual-stack (ipv6Only:false: one socket for IPv4 and IPv6);
// if IPv6 is unavailable (EAFNOSUPPORT, EADDRNOTAVAIL, ...) it falls back to 0.0.0.0. Any other host is
// used as given, and any other failure (EADDRINUSE, EACCES) is rejected, never papered over.
// Resolves to the host that ended up bound.
async function listenDual(server, port, host, log) {
if (host !== '::') { await listenOnce(server, { port, host }); return host; }
try {
await listenOnce(server, { port, host: '::', ipv6Only: false });
return '::';
} catch (err) {
if (!err || !V6_FALLBACK_CODES.has(err.code)) throw err;
if (log) log('IPv6 is not available (' + err.code + '); falling back to 0.0.0.0 (IPv4 only)');
await listenOnce(server, { port, host: '0.0.0.0' });
return '0.0.0.0';
}
}
// ---------------------------------------------------------------- start-up banner
function fmtUrl(host, port) {
return 'http://' + (host.includes(':') ? '[' + host + ']' : host) + ':' + port + '/';
}
// os.networkInterfaces() throws in some sandboxes (seccomp / RestrictAddressFamilies without AF_NETLINK, certain
// containers). The banner is cosmetic, so that must never stop a server that is already listening.
function interfaces() {
try { return os.networkInterfaces(); } catch (e) { return {}; }
}
// URLs worth printing for a server bound to `bound` on `port`.
function listUrls(bound, port, ifaces) {
const out = ['http://localhost:' + port + '/'];
if (bound !== '::' && bound !== '0.0.0.0') {
if (bound !== '127.0.0.1' && bound !== '::1') out.push(fmtUrl(bound, port));
return out;
}
ifaces = ifaces || interfaces();
for (const name of Object.keys(ifaces)) {
for (const a of ifaces[name] || []) {
if (a.internal) continue;
const v4 = a.family === 'IPv4' || a.family === 4;
if (v4) out.push(fmtUrl(a.address, port));
else if (bound === '::' && !/^fe80:/i.test(a.address)) out.push(fmtUrl(a.address.split('%')[0], port));
}
}
return out;
}
module.exports = {
normalizeIp, isPrivateIp, parseTrustProxy, parseTrustedProxies, peerIp, isTrustedPeer, firstForwardedIp, forwardedClientIp, clientIp,
hostParts, normalizeHost, originAllowed, TokenBucket, listenDual, listUrls, fmtUrl,
};