mirror of
https://github.com/wekan/wekan.git
synced 2026-11-20 14:45:01 -05:00
252 lines
13 KiB
JavaScript
252 lines
13 KiB
JavaScript
'use strict';
|
|
|
|
// Admin Panel → Problems → API: who called which endpoint, how often.
|
|
// Run: node tests/apiUsageReport.test.cjs
|
|
//
|
|
// The naming and the accumulator are a pure module, so the two things that could
|
|
// make this report worthless are testable as arithmetic, with no server and no
|
|
// database:
|
|
//
|
|
// 1. NAMING BY PATH instead of by route pattern. `/api/boards/abc123` and ten
|
|
// thousand of its siblings are one endpoint being used, not ten thousand
|
|
// endpoints - and a row per board id is exactly the one-row-per-event cost
|
|
// the whole Problems design exists to remove. Worse, an unauthenticated
|
|
// 404 sweep would let an attacker choose the names and fill the collection.
|
|
//
|
|
// 2. A WRITE PER REQUEST. Every other stream here records something rare; API
|
|
// traffic is the traffic. Counting in memory and folding on a timer is what
|
|
// makes this affordable, so the accumulator has to actually accumulate.
|
|
//
|
|
// The rest is wiring, checked by reading: the middleware counts on `finish` (so
|
|
// the route pattern and the account both exist by then), the identity carries
|
|
// the endpoint and the account id, and nothing about the API stream leaks into
|
|
// the "new problems" badge - it is usage, not a problem.
|
|
|
|
const assert = require('assert');
|
|
const fs = require('fs');
|
|
const path = require('path');
|
|
|
|
const ROOT = path.join(__dirname, '..');
|
|
const read = rel => fs.readFileSync(path.join(ROOT, rel), 'utf8');
|
|
const {
|
|
apiName, isApiRequest, UsageAccumulator, MAX_TRACKED, UNMATCHED,
|
|
} = require('../models/lib/apiUsage');
|
|
|
|
let passed = 0;
|
|
function test(name, fn) { fn(); passed += 1; console.log(' ok -', name); }
|
|
|
|
console.log('apiUsageReport:');
|
|
|
|
// ── naming ─────────────────────────────────────────────────────────────────
|
|
|
|
test('an endpoint is named by its route PATTERN', () => {
|
|
assert.strictEqual(apiName('get', '/api/boards/:boardId'), 'GET /api/boards/:boardId');
|
|
assert.strictEqual(apiName('POST', '/api/boards'), 'POST /api/boards');
|
|
// The method is part of the name: POST /api/boards creates a board and GET
|
|
// /api/boards lists them, and an admin reading "42 calls to /api/boards"
|
|
// cannot tell which happened.
|
|
assert.notStrictEqual(apiName('GET', '/api/boards'), apiName('POST', '/api/boards'));
|
|
});
|
|
|
|
test('a request that matched no route gets ONE name, not its path (negative)', () => {
|
|
// This is the difference between a bounded report and a collection an
|
|
// attacker can fill: a wordlist sweep is thousands of distinct paths, and
|
|
// naming rows after them would write a row per guess.
|
|
const sweep = ['/api/admin', '/api/../etc/passwd', '/api/v2/secret', '/api/wp-login.php']
|
|
.map(() => apiName('GET', null));
|
|
assert.strictEqual(new Set(sweep).size, 1, 'every unmatched request shares one name');
|
|
assert.ok(sweep[0].includes(UNMATCHED), 'and that name says it matched nothing');
|
|
for (const guessed of ['wp-login', 'passwd', 'secret']) {
|
|
assert.ok(!sweep.join(' ').includes(guessed),
|
|
`the name must not carry the attacker's path (${guessed})`);
|
|
}
|
|
});
|
|
|
|
test('only /api requests are counted', () => {
|
|
for (const url of ['/api', '/api/boards', '/api/boards?x=1']) {
|
|
assert.ok(isApiRequest(url), `${url} is API use`);
|
|
}
|
|
// The client's own traffic, the assets and the health check are not API use,
|
|
// and counting them would bury what this report is for.
|
|
for (const url of ['/', '/sockjs/info', '/apidocs', '/api-docs', '/healthz', '']) {
|
|
assert.ok(!isApiRequest(url), `${url} is not API use`);
|
|
}
|
|
});
|
|
|
|
// ── the accumulator ────────────────────────────────────────────────────────
|
|
|
|
test('a thousand calls are one row, with the window they fall in', () => {
|
|
const acc = new UsageAccumulator();
|
|
const first = new Date('2026-02-02T09:14:03Z');
|
|
for (let i = 0; i < 1000; i += 1) {
|
|
acc.add({
|
|
name: 'POST /api/boards', userId: 'alice', ip: '100.100.100.100',
|
|
at: new Date(first.getTime() + i * 1000),
|
|
});
|
|
}
|
|
assert.strictEqual(acc.size, 1, 'one endpoint, one account, one row');
|
|
const [row] = acc.drain();
|
|
assert.strictEqual(row.count, 1000);
|
|
assert.strictEqual(row.firstAt.toISOString(), first.toISOString());
|
|
assert.strictEqual(row.at.toISOString(), new Date(first.getTime() + 999000).toISOString(),
|
|
'the window ends at the LAST call, not the first');
|
|
});
|
|
|
|
test('and two accounts on one endpoint are two rows', () => {
|
|
// The account is part of the identity here - the deliberate exception - so
|
|
// "who called what" is answerable. Two endpoints for one account likewise.
|
|
const acc = new UsageAccumulator();
|
|
const at = new Date('2026-05-05T00:00:00Z');
|
|
acc.add({ name: 'POST /api/boards', userId: 'alice', at });
|
|
acc.add({ name: 'POST /api/boards', userId: 'bob', at });
|
|
acc.add({ name: 'GET /api/boards', userId: 'alice', at });
|
|
assert.strictEqual(acc.size, 3);
|
|
});
|
|
|
|
test('an unauthenticated caller is a row, not a mistake', () => {
|
|
const acc = new UsageAccumulator();
|
|
const at = new Date('2026-05-05T00:00:00Z');
|
|
for (let i = 0; i < 812; i += 1) acc.add({ name: 'POST /api/users', userId: '', ip: '2001:db8::1', at });
|
|
const [row] = acc.drain();
|
|
assert.strictEqual(row.count, 812);
|
|
assert.strictEqual(row.userId, '');
|
|
assert.strictEqual(row.ip, '2001:db8::1',
|
|
'with no account, the address is what identifies the caller');
|
|
});
|
|
|
|
test('the tracked pairs are CAPPED, and the rest are counted (negative)', () => {
|
|
// Without this an attacker who can vary the account or the endpoint grows the
|
|
// map with the attack - the same bug one level down that MAX_ACTORS closes in
|
|
// the summaries.
|
|
const acc = new UsageAccumulator({ maxTracked: 3 });
|
|
const at = new Date('2026-05-05T00:00:00Z');
|
|
for (let i = 0; i < 50; i += 1) acc.add({ name: `GET /api/x${i}`, userId: 'a', at });
|
|
assert.strictEqual(acc.size, 3, 'the map stops growing at the cap');
|
|
const rows = acc.drain();
|
|
const overflow = rows.find(r => r.name.includes('over 3 tracked'));
|
|
assert.ok(overflow, 'the ones past the cap are counted in an overflow row');
|
|
assert.strictEqual(overflow.count, 47, 'and nothing is silently dropped');
|
|
assert.ok(MAX_TRACKED >= 100, 'the real cap is far above ordinary use');
|
|
});
|
|
|
|
test('drain empties it, so a flush never writes the same calls twice', () => {
|
|
const acc = new UsageAccumulator();
|
|
acc.add({ name: 'GET /api/boards', userId: 'a', at: new Date() });
|
|
assert.strictEqual(acc.drain().length, 1);
|
|
assert.strictEqual(acc.drain().length, 0);
|
|
assert.strictEqual(acc.size, 0);
|
|
});
|
|
|
|
// ── the wiring ─────────────────────────────────────────────────────────────
|
|
|
|
test('it counts on `finish`, which is where the route pattern exists', () => {
|
|
const log = read('server/lib/apiUsageLog.js');
|
|
assert.ok(/res\.on\('finish'/.test(log),
|
|
'counting on the way IN would have no req.route and no authenticated user');
|
|
assert.ok(/req\.route && req\.route\.path/.test(log),
|
|
'the name comes from the matched route');
|
|
assert.ok(/HTTP_FORWARDED_COUNT/.test(log),
|
|
'and the address is resolved the same spoofing-safe way as the login throttle');
|
|
});
|
|
|
|
test('and it is installed in front of the routes, not per route', () => {
|
|
// A route added tomorrow has to be counted without anybody remembering to
|
|
// count it - that is the whole reason this is middleware.
|
|
const mw = read('server/apiMiddleware.js');
|
|
assert.ok(/apiUsageMiddleware/.test(mw), 'apiMiddleware.js must install it');
|
|
const routeFiles = ['server/models/boards.js', 'models/export.js'];
|
|
for (const file of routeFiles) {
|
|
assert.ok(!/apiUsage/.test(read(file)),
|
|
`${file} must not have to count its own routes`);
|
|
}
|
|
});
|
|
|
|
test('the summary identity carries the endpoint and the ACCOUNT ID', () => {
|
|
const summary = read('models/lib/eventLogSummary.js');
|
|
const identity = /const IDENTITY_FIELDS = \[([\s\S]*?)\];/.exec(summary);
|
|
assert.ok(identity, 'IDENTITY_FIELDS must exist');
|
|
assert.ok(/'api'/.test(identity[1]), 'the endpoint is part of the identity');
|
|
assert.ok(/'apiUserId'/.test(identity[1]),
|
|
'and the account, by ID - a rename must not split one account into two rows');
|
|
assert.ok(!/'apiUsername'/.test(identity[1]),
|
|
'the NAME must not be the identity, or a rename splits the history');
|
|
});
|
|
|
|
test('every API fold field is accepted by the EventLog schema', () => {
|
|
// Collection2 validates both the upsert selector and update. Missing `api`
|
|
// caused every timed flush to fail before one usage row could be recorded;
|
|
// the shared fold also adds the address-family fields to the update.
|
|
const eventLog = read('models/eventLog.js');
|
|
const schema = eventLog.slice(eventLog.indexOf('new SimpleSchema({'),
|
|
eventLog.indexOf('}),\n);'));
|
|
for (const field of ['api', 'apiUserId', 'ipv4', 'ipv6']) {
|
|
assert.ok(new RegExp(`\\n\\s*${field}:\\s*\\{ type: String`).test(schema),
|
|
`EventLog schema must accept ${field}`);
|
|
}
|
|
});
|
|
|
|
test('API use is not a "problem", so it stays out of the badge (negative)', () => {
|
|
// EVENT_STREAMS drives the red Problems button and the Summary counts. An
|
|
// instance serving its API would otherwise report thousands of new problems.
|
|
const eventLog = read('models/eventLog.js');
|
|
const streams = /export const EVENT_STREAMS = \[([^\]]*)\]/.exec(eventLog);
|
|
assert.ok(streams, 'EVENT_STREAMS must exist');
|
|
assert.ok(!/'api'/.test(streams[1]),
|
|
'the api stream must NOT be in EVENT_STREAMS - it is usage, not a problem');
|
|
});
|
|
|
|
test('the pane reuses the shared report, with its own columns only', () => {
|
|
// "Combine templates where possible": the API pane is the event-stream report
|
|
// with a different column list, not a second table page.
|
|
const jade = read('client/components/settings/adminProblems.jade');
|
|
assert.ok(/isPane 'report-api'\s*\n\s*\+eventStreamReport\(stream="api"\)/.test(jade),
|
|
'the API pane must render the shared event-stream report');
|
|
const js = read('client/components/settings/adminProblems.js');
|
|
assert.ok(/const API_COLUMNS = \[/.test(js), 'with its own columns');
|
|
assert.ok(/stream === 'api' \? API_COLUMNS : EVENT_STREAM_COLUMNS/.test(js),
|
|
'chosen by stream, in one place');
|
|
// The columns the request asked for: username, API name, count, the window,
|
|
// and the two address families in their own columns.
|
|
const cols = /const API_COLUMNS = \[([\s\S]*?)\n\];/.exec(js)[1];
|
|
for (const key of ['username', 'api-endpoint', 'api-calls',
|
|
'api-first-called', 'api-last-called']) {
|
|
assert.ok(cols.includes(`'${key}'`), `the table must have a ${key} column`);
|
|
}
|
|
// The four address/location columns are the group every report uses, not a third copy of
|
|
// them - that is what makes "IPv4 and IPv6 wherever the address is known"
|
|
// true of the whole page rather than of whichever report was edited last.
|
|
assert.ok(/\.\.\.addressReportColumns\(\)/.test(cols), 'the shared address and location columns');
|
|
const shared = read('models/lib/addressReportColumns.js');
|
|
for (const key of ['event-ipv4', 'event-ipv6']) {
|
|
assert.ok(shared.includes(`'${key}'`), `it must have a ${key} column`);
|
|
}
|
|
assert.ok(/classifyAddress\(row\.ip\)/.test(shared),
|
|
'and fall back to classifying `ip`, so rows written before the split still display');
|
|
});
|
|
|
|
test('and it sorts by how much, not by how recently', () => {
|
|
const eventLog = read('models/eventLog.js');
|
|
assert.ok(/stream === 'api' \? \{ count: -1, at: -1 \}/.test(eventLog),
|
|
'a usage report answers "what is used most"; a problem report answers "what happened last"');
|
|
});
|
|
|
|
test('every language has the keys, in en.i18n.json\'s order', () => {
|
|
// A key added to en and nowhere else shows the raw key name to everybody who
|
|
// does not read English.
|
|
const en = JSON.parse(read('imports/i18n/data/en.i18n.json'));
|
|
const keys = ['apiReportTitle', 'api-endpoint', 'api-calls',
|
|
'api-first-called', 'api-last-called', 'api-no-calls', 'api-report-desc'];
|
|
for (const key of keys) assert.ok(en[key], `en.i18n.json needs ${key}`);
|
|
const dir = path.join(ROOT, 'imports/i18n/data');
|
|
const missing = [];
|
|
for (const file of fs.readdirSync(dir)) {
|
|
if (!file.endsWith('.i18n.json')) continue;
|
|
if (fs.lstatSync(path.join(dir, file)).isSymbolicLink()) continue;
|
|
const data = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
|
|
for (const key of keys) if (!(key in data)) missing.push(`${file}:${key}`);
|
|
}
|
|
assert.deepStrictEqual(missing.slice(0, 5), [], `these languages lack the keys: ${missing.length}`);
|
|
});
|
|
|
|
console.log(`\napiUsageReport: ${passed} tests passed`);
|