'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. 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) { if (this.m.size >= this.maxKeys) this.prune(); b = new TokenBucket(this.rate, this.burst); this.m.set(key, b); } return b.take(); } prune() { for (const [k, b] of this.m) if (b.tokens >= b.burst - 0.5) this.m.delete(k); if (this.m.size >= this.maxKeys) this.m.clear(); // under attack from >maxKeys distinct keys: forget, do not grow } } 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(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(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) { // 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); } return { router, handle, pruneIdempotency, CODES }; } module.exports = { createApi, Router, Reply, reply, Limiter };