Upstream/server/http.js
jvanvik d84b0c9d12 Fix review findings: proto smuggling, trade-leg recall, escrow cap, static headers, rate limits, rankings DoS
Fixed: validator rejects __proto__/constructor keys at any depth (transport capacity bypass); trade and site shipments
cannot be recalled; trade escrow refund capped by Rack hall; CSP/nosniff on static files and connect-src 'self';
IPv6 /64 limiter keys + LRU eviction + per-username login bucket + scrypt concurrency cap; 5 s footprint cache for
rankings; rename uses text.cleanText; 429s no longer pinned in the idempotency store; 30-day notification prune;
units_offline notification on first offline. Accepted items listed in docs/DECISIONS.md R1.
Tested: npm test 182/182 incl. test/review-fixes.test.js (regression tests). Not re-reviewed after the fixes.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
2026-10-11 19:06:51 +02:00

241 lines
12 KiB
JavaScript

'use strict';
/*
* Tiny REST layer on node:http: router, JSON in/out, error envelope, bearer auth, rate limits, Idempotency-Key.
*
* const api = createApi({ db, clock, log, opts, services });
* routes.register(api.router, services);
* server.on('request', (req, res) => url.startsWith('/api/') ? api.handle(req, res) : serveStatic(req, res));
*
* Route meta (also the source of docs/openapi.json, see tools/gen-openapi.js):
* { summary, tag, auth: true|false, query: schema, body: schema, response: schema, errors: [codes], limit: 'auth' }
* Every JSON response is an object carrying `serverTime`. Errors are { error: { code, message, details } }.
*/
const crypto = require('crypto');
const { GameError, CODES } = require('./errors');
const { validate } = require('./validate');
const { TokenBucket, clientIp } = require('./net');
const { applySecurityHeaders } = require('./static');
const MAX_BODY = 32 * 1024;
const INT_PARAMS = new Set(['id', 'townId', 'eventId', 'tokenId', 'inviteId', 'noteId', 'proposalId', 'otherId', 'operatorId', 'reportId']);
// Per-key token buckets (per IP, per token). Idle full buckets are pruned so the map cannot grow without bound.
// Rate-limit key for an address: IPv6 clients get a whole /64 each (they can mint 2^64 addresses), IPv4 is used as is.
function limitKey(ip) {
if (typeof ip !== 'string' || !ip.includes(':')) return ip;
const [head, tail = ''] = ip.split('::');
const h = head ? head.split(':') : [], t = tail ? tail.split(':') : [];
const full = ip.includes('::') ? h.concat(new Array(Math.max(0, 8 - h.length - t.length)).fill('0'), t) : h;
return full.slice(0, 4).map((x) => x.toLowerCase().replace(/^0+(?=.)/, '')).join(':') + '::/64';
}
class Limiter {
constructor(ratePerSec, burst, maxKeys) { this.rate = ratePerSec; this.burst = burst; this.maxKeys = maxKeys || 20000; this.m = new Map(); }
take(key) {
let b = this.m.get(key);
if (b) this.m.delete(key); // re-insert below: Map order = least recently used first
else {
if (this.m.size >= this.maxKeys) this.prune();
b = new TokenBucket(this.rate, this.burst);
}
this.m.set(key, b);
return b.take();
}
// Drop idle (full) buckets first; if everything is busy evict the least recently used. Never forget a throttled key
// just because many other keys showed up.
prune() {
for (const [k, b] of this.m) if (b.tokens >= b.burst - 0.5) this.m.delete(k);
for (const k of this.m.keys()) { if (this.m.size < this.maxKeys * 0.9) break; this.m.delete(k); }
}
}
class Router {
constructor() { this.routes = []; }
// path like '/towns/:id/build' (relative to /api/v1)
add(method, path, meta, handler) {
const names = [];
const re = new RegExp('^' + path.replace(/:([A-Za-z]+)/g, (m, n) => { names.push(n); return '([^/]+)'; }) + '$');
this.routes.push({ method, path, re, names, meta: meta || {}, handler });
}
get(path, meta, h) { this.add('GET', path, meta, h); }
post(path, meta, h) { this.add('POST', path, meta, h); }
del(path, meta, h) { this.add('DELETE', path, meta, h); }
// -> { route, params } | { methods: [...] } (path matches, method does not) | null
find(method, pathname) {
const allowed = [];
for (const r of this.routes) {
const m = r.re.exec(pathname);
if (!m) continue;
if (r.method !== method) { allowed.push(r.method); continue; }
const params = {};
for (let i = 0; i < r.names.length; i++) {
let v;
try { v = decodeURIComponent(m[i + 1]); } catch (e) { return null; }
if (INT_PARAMS.has(r.names[i])) {
if (!/^\d{1,12}$/.test(v)) return null;
v = Number(v);
}
params[r.names[i]] = v;
}
return { route: r, params };
}
return allowed.length ? { methods: allowed } : null;
}
}
// A handler returns a plain object (HTTP 200) or reply(status, object).
class Reply { constructor(status, body) { this.status = status; this.body = body; } }
const reply = (status, body) => new Reply(status, body);
function createApi({ db, clock, log, opts, auth }) {
const router = new Router();
const ipLimit = new Limiter(opts.ipRate || 30, opts.ipBurst || 90);
const tokenLimit = new Limiter(opts.tokenRate || 15, opts.tokenBurst || 45);
const authLimit = new Limiter(opts.authRate || 0.1, opts.authBurst || 8); // login / signup: ~1 per 10 s sustained
const inflight = new Set();
function send(res, status, body, extra) {
const text = JSON.stringify(body);
applySecurityHeaders(res);
res.writeHead(status, Object.assign({ 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(text), 'Cache-Control': 'no-store' }, extra));
res.end(text);
}
function fail(res, err, ctx) {
let ge = err;
if (!(err instanceof GameError)) {
log('internal error ' + (ctx || '') + ': ' + (err && err.stack || err));
ge = new GameError('internal_error');
}
const extra = ge.status === 429 && ge.details.retryAfter ? { 'Retry-After': String(ge.details.retryAfter) } : undefined;
send(res, ge.status, { serverTime: clock.now(), error: { code: ge.code, message: ge.message, details: ge.details } }, extra);
}
function readBody(req) {
return new Promise((resolve, reject) => {
const len = Number(req.headers['content-length'] || 0);
if (len > MAX_BODY) return reject(new GameError('payload_too_large'));
const chunks = []; let size = 0;
req.on('data', (c) => {
size += c.length;
if (size > MAX_BODY) { reject(new GameError('payload_too_large')); req.destroy(); return; }
chunks.push(c);
});
req.on('end', () => resolve(Buffer.concat(chunks)));
req.on('error', () => reject(new GameError('bad_request')));
});
}
async function handle(req, res) {
const ip = clientIp(req, opts.trustProxy, opts.trustedProxies);
const started = clock.now();
let pathname = '', routeKey = '';
try {
const u = new URL(req.url, 'http://x');
pathname = u.pathname;
if (!ipLimit.take(limitKey(ip))) { log('refused rate_limited(ip) ip=' + ip + ' path=' + pathname); throw new GameError('rate_limited', { retryAfter: 1 }); }
if (!pathname.startsWith('/api/v1/')) throw new GameError('not_found');
const found = router.find(req.method, pathname.slice('/api/v1'.length));
if (!found) throw new GameError('not_found');
if (found.methods) { const e = new GameError('method_not_allowed', { allowed: found.methods }); throw e; }
const { route, params } = found;
routeKey = route.method + ' ' + route.path;
const meta = route.meta;
if (meta.limit === 'auth' && !authLimit.take(limitKey(ip))) { log('refused rate_limited(auth) ip=' + ip + ' route=' + routeKey); throw new GameError('rate_limited', { retryAfter: 10 }); }
let user = null, tokenId = null;
if (meta.auth !== false) {
const a = auth.authenticate(req.headers.authorization, clock.now());
if (!a) { log('refused unauthorized ip=' + ip + ' route=' + routeKey); throw new GameError('unauthorized'); }
user = a.user; tokenId = a.tokenId;
if (!tokenLimit.take('t' + tokenId)) { log('refused rate_limited(token) token=' + tokenId + ' route=' + routeKey); throw new GameError('rate_limited', { retryAfter: 1 }); }
}
// query
const query = {};
for (const [k, v] of u.searchParams) query[k] = v;
let q = {};
if (meta.query) {
const v = validate(meta.query, query, { coerce: true });
if (!v.ok) throw new GameError('validation_failed', { errors: v.errors });
q = v.value;
}
// body
let body = {};
if (meta.body) {
const raw = await readBody(req);
let parsed = {};
if (raw.length) {
if (!/^application\/json\b/i.test(req.headers['content-type'] || '')) throw new GameError('bad_request', { reason: 'content-type must be application/json' });
try { parsed = JSON.parse(raw.toString('utf8')); } catch (e) { throw new GameError('bad_request', { reason: 'invalid JSON' }); }
}
const v = validate(meta.body, parsed);
if (!v.ok) throw new GameError('validation_failed', { errors: v.errors });
body = v.value;
} else if (req.method !== 'GET' && req.method !== 'HEAD') {
await readBody(req).catch(() => null); // drain
}
const ctx = { req, ip, user, tokenId, params, query: q, body, now: clock.now() };
// Idempotency-Key on mutating POSTs of authenticated users
const idem = req.method === 'POST' && user ? req.headers['idempotency-key'] : undefined;
let idemId = null;
if (idem !== undefined) {
if (typeof idem !== 'string' || !/^[A-Za-z0-9_.:-]{8,64}$/.test(idem)) throw new GameError('validation_failed', { errors: [{ path: 'Idempotency-Key', message: 'must be 8-64 of A-Za-z0-9_.:-' }] });
const sig = req.method + ' ' + pathname + ' ' + crypto.createHash('sha256').update(JSON.stringify(body)).digest('hex');
idemId = user.id + ':' + idem;
const row = db.get('SELECT request, status, body FROM idempotency WHERE user_id = ? AND key = ?', user.id, idem);
if (row) {
if (row.request !== sig) throw new GameError('idempotency_key_reuse');
return send(res, row.status, JSON.parse(row.body), { 'Idempotent-Replay': 'true' });
}
if (inflight.has(idemId)) throw new GameError('request_in_progress');
inflight.add(idemId);
ctx.idem = { key: idem, sig };
}
try {
let out;
let status = 200;
try {
out = await route.handler(ctx);
if (out instanceof Reply) { status = out.status; out = out.body; }
out = Object.assign({ serverTime: clock.now() }, out);
} catch (err) {
if (ctx.idem && err instanceof GameError && err.status < 500 && err.status !== 429 && err.code !== 'request_in_progress') {
// Replaying a rejected request must give the same rejection, not run it again.
const eb = { serverTime: clock.now(), error: { code: err.code, message: err.message, details: err.details } };
storeIdem(user.id, ctx.idem, err.status, eb);
}
throw err;
}
if (ctx.idem) storeIdem(user.id, ctx.idem, status, out);
send(res, status, out);
} finally { if (idemId) inflight.delete(idemId); }
} catch (err) {
if (!(err instanceof GameError)) log('request failed ' + routeKey + ' ' + pathname + ': ' + (err && err.stack || err));
else if (err.status >= 400 && err.code !== 'not_found' && err.code !== 'unauthorized' && err.status !== 429) {
// game-rule refusals are normal traffic; keep them out of the log except for the security-relevant codes
if (err.code === 'forbidden' || err.code === 'validation_failed' || err.code === 'bad_request') log('refused ' + err.code + ' ip=' + ip + ' route=' + routeKey);
}
if (!res.headersSent) fail(res, err, routeKey);
}
}
function storeIdem(userId, idem, status, body) {
try {
db.run('INSERT OR IGNORE INTO idempotency (user_id, key, request, status, body, created_at) VALUES (?, ?, ?, ?, ?, ?)', userId, idem.key, idem.sig, status, JSON.stringify(body), clock.now());
} catch (e) { log('could not store idempotency key: ' + e.message); }
}
function pruneIdempotency() {
db.run('DELETE FROM idempotency WHERE created_at < ?', clock.now() - 24 * 3600 * 1000);
db.run('DELETE FROM notifications WHERE created_at < ?', clock.now() - 30 * 24 * 3600 * 1000);
}
return { router, handle, pruneIdempotency, CODES };
}
module.exports = { createApi, Router, Reply, reply, Limiter, limitKey };