@andrian.yablonskyy/thub-coordinator 1.0.39 → 1.0.41

package/bin/thub-admin.js

@@ -33,6 +33,7 @@ const { loadConfig } = require('../src/config'),
   { createJobsService } = require('../src/services/jobs'),
   { createCleanupService } = require('../src/services/cleanup'),
   { generateToken } = require('../src/services/tokens'),
+  { createSettingsService } = require('../src/services/settings'),
   { PACKAGES, fetchLatestVersion, isNewer, isValidVersion, npmBin, formatDateTime, parseDateTime } = require('@andrian.yablonskyy/thub-common'),
   { spawnSync } = require('node:child_process'),
   { version: installedVersion } = require('../package.json');
@@ -51,6 +52,11 @@ function usage(){
   thub-admin group add <name> [--comment <text>]
   thub-admin group list
   thub-admin group remove <groupId>
+  thub-admin settings list        Settings changed from the dashboard (Settings page)
+  thub-admin settings reset [<key>...]
+                                  Drop them (all, or the named ones) — back to the config
+                                  file's values at the next restart; the way back if a
+                                  setting locked you out of the dashboard
   thub-admin check-update         Compare this Coordinator with the latest published version
   thub-admin self-update [--to X.Y.Z]
                                   Update this Coordinator (sudo npm i -g; restarts the service)
@@ -136,6 +142,23 @@ function main(){
     jobs = createJobsService(db, { bus, events, registry, config }),
     groups = createGroupsService(db, { events, registry });
 
+  if (cmd === 'settings' && (sub === 'list' || sub === 'reset')){
+    const settings = createSettingsService(db, { config });
+    if (sub === 'reset'){
+      const n = settings.reset(rest);
+      console.log(`Removed ${n} dashboard setting(s). Restart the Coordinator to use the config file's values: sudo systemctl restart thub-coordinator`);
+      return;
+    }
+    const changed = settings.list().filter((s) => s.source === 'dashboard');
+    if (!changed.length){
+      console.log('No settings changed from the dashboard — everything comes from the config file (or the environment).');
+    }
+    for (const s of changed){
+      console.log(`${s.key} = ${s.type === 'secret' ? '(secret)' : JSON.stringify(s.value)}   (${s.updatedBy || '?'}, ${s.updatedAt})`);
+    }
+    return;
+  }
+
   if (cmd === 'create-admin'){
     const { positional, flags } = parseFlags([sub, ...rest].filter(Boolean)),
       [username, password] = positional;

package/config.json

@@ -19,6 +19,10 @@
     "defaultTimeoutSec": 1800,
     "maxTimeoutSec": 14400
   },
+  "rateLimit": {
+    "requestsPerMinute": 500,
+    "loginPerMinute": 10
+  },
   "retention": {
     "jobRetention": "forever"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.0.39",
+  "version": "1.0.41",
   "description": "TestHub Coordinator — job queue, resource registry, scheduler, heartbeat monitor, log/artifact store and web dashboard",
   "main": "src/server.js",
   "engines": {
@@ -19,7 +19,7 @@
     "lint:fix": "eslint . --fix"
   },
   "dependencies": {
-    "@andrian.yablonskyy/thub-common": "^1.0.32",
+    "@andrian.yablonskyy/thub-common": "^1.0.33",
     "better-sqlite3": "^12.4.1",
     "express": "^5.1.0",
     "express-session": "^1.18.2",

package/public/js/actions.js

@@ -0,0 +1,58 @@
+/**
+ * @file        packages/coordinator/public/js/actions.js
+ * @description Dashboard: small declarative behaviours (data-* attributes) that used to be inline on*= handlers
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+// The Content-Security-Policy (server.js) allows no inline script, so no
+// onclick=/onchange=/onsubmit= in the templates: they declare what they
+// want with these attributes instead. Delegated, so it also works for
+// content swapped in by live updates (live.js).
+(function (){
+  // <select data-navigate>: its option values are URLs to go to.
+  // <select data-autosubmit>: submit its form on change.
+  document.addEventListener('change', (e) => {
+    const el = e.target;
+    if (el.matches?.('select[data-navigate]')){
+      window.location.href = el.value;
+    }
+    else if (el.matches?.('[data-autosubmit]') && el.form){
+      el.form.submit();
+    }
+  });
+
+  // <button data-fill="#field" data-value="…">: put the value into #field.
+  document.addEventListener('click', (e) => {
+    const btn = e.target.closest('[data-fill]'),
+      target = btn && document.querySelector(btn.dataset.fill);
+    if (target){
+      target.value = btn.dataset.value;
+    }
+  });
+
+  // <form data-submit-busy>: disable its button and show a spinner while
+  // the request runs (e.g. the navbar's check for updates).
+  document.addEventListener('submit', (e) => {
+    const form = e.target;
+    if (!form.matches?.('form[data-submit-busy]') || e.defaultPrevented){
+      return;
+    }
+    const button = form.querySelector('button'),
+      icon = button?.querySelector('i');
+    if (button){
+      button.disabled = true;
+    }
+    if (icon){
+      icon.className = 'spinner-border spinner-border-sm';
+    }
+  });
+})();

package/public/js/settings.js

@@ -0,0 +1,66 @@
+/**
+ * @file        packages/coordinator/public/js/settings.js
+ * @description Dashboard Settings page: generate/show the join key, and wait out a restart
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+(function (){
+  // Generate: a random key, shown so it can be copied into the Clients'
+  // configs (joinKey) before saving.
+  document.querySelectorAll('[data-secret-generate]').forEach((btn) => {
+    btn.addEventListener('click', () => {
+      const input = document.querySelector(btn.dataset.secretGenerate),
+        bytes = crypto.getRandomValues(new Uint8Array(32)),
+        b64 = btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+      input.value = `jk_${b64}`;
+      input.type = 'text';
+      input.select();
+    });
+  });
+  document.querySelectorAll('[data-secret-show]').forEach((btn) => {
+    btn.addEventListener('click', () => {
+      const input = document.querySelector(btn.dataset.secretShow);
+      input.type = input.type === 'password' ? 'text' : 'password';
+    });
+  });
+
+  // Restarting: poll until a process with a different start time answers,
+  // then reload (riding out the seconds it's down).
+  const banner = document.querySelector('[data-restarting]');
+  if (banner){
+    const before = banner.dataset.restarting,
+      started = Date.now(),
+      poll = async () => {
+        try {
+          const res = await fetch('/admin/settings/status', { cache: 'no-store', redirect: 'manual' });
+          if (res.type === 'opaqueredirect'){
+            window.location.href = '/login'; // the session didn't survive? sign in again
+            return;
+          }
+          if (res.ok && (await res.json()).startedAt !== before){
+            window.location.href = '/admin/settings';
+            return;
+          }
+        }
+        catch {
+          // down for now
+        }
+        if (Date.now() - started > 120_000){
+          banner.lastElementChild.textContent = 'The Coordinator hasn\'t come back after 2 minutes — check journalctl -u thub-coordinator on its host.';
+          banner.querySelector('.spinner-border')?.remove();
+          return;
+        }
+        setTimeout(poll, 1500);
+      };
+    setTimeout(poll, 1500);
+  }
+})();

package/src/api/agent.js

@@ -24,7 +24,21 @@ function createAgentRouter({ services, config }){
     // the /api/v1 prefix with the resource and admin routers — a blanket
     // router-level middleware would run for their paths too, before route
     // matching even happens, and reject them for lacking an agent token.
-    auth = requireRole('agent');
+    auth = requireRole('agent'),
+
+    // Which jobs an agent may see (README §12): a `ci` token (pipelines) all
+    // of them; a `cli` token (a person's own `thub`) only the jobs it
+    // submitted. Anyone else's job is answered exactly like a job that
+    // doesn't exist (404), so a cli token can't tell which ids are in use.
+    canSee = (agent, job) => agent.kind === 'ci' || job.agent_id === agent.id,
+    visibleJob = (req, res, next) => {
+      const job = services.jobs.get(req.params.id);
+      if (!job || !canSee(req.agent, job)){
+        return res.status(404).json({ error: 'Unknown job' });
+      }
+      req.job = job;
+      next();
+    };
 
   router.post('/jobs', auth, (req, res, next) => {
     try {
@@ -40,12 +54,9 @@ function createAgentRouter({ services, config }){
     }
   });
 
-  router.get('/jobs/:id', auth, (req, res) => {
-    const job = services.jobs.get(req.params.id);
-    if (!job){
-      return res.status(404).json({ error: 'Unknown job' });
-    }
-    const resource = job.resource_id ? services.registry.get(job.resource_id) : null;
+  router.get('/jobs/:id', auth, visibleJob, (req, res) => {
+    const { job } = req,
+      resource = job.resource_id ? services.registry.get(job.resource_id) : null;
     res.json({
       ...services.jobs.publicJob(job),
       resource: resource ? { id: resource.id, name: resource.name } : job.resource_name ? { id: null, name: job.resource_name } : null
@@ -57,13 +68,14 @@ function createAgentRouter({ services, config }){
       state: req.query.state,
       source: req.query.source,
       agentId: req.agent.id,
-      mine: req.query.mine === 'true' || req.query.mine === '1',
+      // A cli token's list is always its own jobs (canSee above).
+      mine: req.agent.kind !== 'ci' || req.query.mine === 'true' || req.query.mine === '1',
       limit: req.query.limit ? Number(req.query.limit) : undefined
     });
     res.json({ jobs: jobs.map(services.jobs.publicJob) });
   });
 
-  router.post('/jobs/:id/cancel', auth, (req, res, next) => {
+  router.post('/jobs/:id/cancel', auth, visibleJob, (req, res, next) => {
     try {
       const job = services.jobs.cancel(req.params.id, { agentId: req.agent.id, isAdmin: false });
       res.json(services.jobs.publicJob(job));
@@ -73,20 +85,20 @@ function createAgentRouter({ services, config }){
     }
   });
 
-  router.get('/jobs/:id/logs', auth, (req, res) => {
+  router.get('/jobs/:id/logs', auth, visibleJob, (req, res) => {
     const after = Number(req.query.after || 0),
       limit = req.query.limit ? Number(req.query.limit) : undefined;
     res.json({ lines: services.logs.listSince(req.params.id, after, limit) });
   });
 
-  router.get('/jobs/:id/logs/stream', auth, (req, res) => {
+  router.get('/jobs/:id/logs/stream', auth, visibleJob, (req, res) => {
     attachJobStream(req, res, { jobId: req.params.id, services });
   });
 
-  // No artifacts are stored any more (README §9); an Agent older than that
-  // still asks after a finished job's `thub status`, so answer "none".
-  router.get('/jobs/:id/artifacts', auth, (req, res) => {
-    res.json({ artifacts: [] });
+  // What the job reported (README §7.3): metadata and links only. `url` is
+  // `link` again, for Agents from before, which print `url`.
+  router.get('/jobs/:id/artifacts', auth, visibleJob, (req, res) => {
+    res.json({ artifacts: req.job.artifacts.map((a) => ({ ...a, url: a.link })) });
   });
 
   router.get('/resources', auth, (req, res) => {

package/src/api/resource.js

@@ -127,7 +127,9 @@ function createResourceRouter({ services, config }){
       if (req.resource.remove_requested_at && !activeJobId){
         services.jobs.completeRemoval(req.params.id, { by: 'removal-confirmed' });
       }
-      res.json({ serverTime: new Date().toISOString(), commands });
+      // The current interval in every reply, not only at registration, so a
+      // change from the dashboard (§13.2) reaches running Clients at once.
+      res.json({ serverTime: new Date().toISOString(), commands, heartbeatIntervalSec: config.heartbeat.intervalSec });
     }
     catch (err){
       next(err);
@@ -218,8 +220,8 @@ function createResourceRouter({ services, config }){
 
   router.post('/jobs/:id/result', auth, requireOwnJob(services), (req, res, next) => {
     try {
-      const { state, exitCode, summary } = req.body,
-        job = services.jobs.applyResult(req.params.id, req.resource.id, { state, exitCode, summary });
+      const { state, exitCode, summary, artifacts } = req.body,
+        job = services.jobs.applyResult(req.params.id, req.resource.id, { state, exitCode, summary, artifacts });
       res.json(job);
     }
     catch (err){

package/src/config.js

@@ -52,6 +52,13 @@ const DEFAULTS = {
     defaultTimeoutSec: 1800,
     maxTimeoutSec: 14400
   },
+  // Requests per minute per caller (rate-limit.js, README §12): an agent or
+  // resource token or a dashboard user, else the client IP; sign-in attempts
+  // per IP on top. 0 turns a limit off.
+  rateLimit: {
+    requestsPerMinute: 500,
+    loginPerMinute: 10
+  },
   // logRetentionDays, artifactRetentionDays and the `artifacts` section of
   // older configs are no longer read: a job's log lines live as long as the
   // job, and the Coordinator stores no artifacts (README §9).
@@ -106,7 +113,9 @@ function loadConfig(configPath = process.env.THUB_COORDINATOR_CONFIG){
       (p) => p && fs.existsSync(p)
     ),
     fileConfig = candidate ? JSON.parse(fs.readFileSync(candidate, 'utf8')) || {} : {},
-    config = deepMerge(DEFAULTS, fileConfig);
+    // A copy: the dashboard's settings change the loaded config in place
+    // (services/settings.js), which must never reach DEFAULTS itself.
+    config = deepMerge(structuredClone(DEFAULTS), fileConfig);
 
   // Environment overrides for the bits you don't want in a committed file.
   if (process.env.THUB_LISTEN){
@@ -125,6 +134,13 @@ function loadConfig(configPath = process.env.THUB_COORDINATOR_CONFIG){
     config.clientJoinKey = process.env.THUB_CLIENT_JOIN_KEY;
   }
 
+  for (const key of ['requestsPerMinute', 'loginPerMinute']){
+    const v = config.rateLimit[key];
+    if (!Number.isInteger(v) || v < 0){
+      throw new Error(`rateLimit.${key} must be a whole number, 0 or more (0 = no limit; got ${JSON.stringify(v)}) in ${candidate || 'the config'}`);
+    }
+  }
+
   if (![true, false, 'auto'].includes(config.session.secureCookie)){
     throw new Error(
       `session.secureCookie must be "auto", true or false (got ${JSON.stringify(config.session.secureCookie)}) in ${candidate || 'the config'}`

package/src/db/migrations/024_add_settings.sql

@@ -0,0 +1,10 @@
+-- Coordinator settings changed from the dashboard (services/settings.js,
+-- /admin/settings). They override the config file — which the sandboxed
+-- service can't write — and are overridden by environment variables.
+-- `value` is JSON.
+CREATE TABLE settings (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  updated_by TEXT
+);

package/src/db/migrations/025_add_job_artifacts.sql

@@ -0,0 +1,4 @@
+-- Artifacts a finished job reports (services/job-artifacts.js): metadata
+-- only — name, size, a download link elsewhere, a time — as a JSON array.
+-- The files themselves never reach the Coordinator (README §7.3, §9).
+ALTER TABLE jobs ADD COLUMN artifacts TEXT;

package/src/dev/virtual.js

@@ -173,7 +173,6 @@ function seedHistory(services, agentId, resourceIds){
 // services the Client API uses, so SSE and durations all work.
 function startVirtualClients(services, config){
   const { registry, jobs, logs, bus } = services,
-    intervalMs = config.heartbeat.intervalSec * 1000,
     clients = new Map(); // resourceId -> { def, activity, running }
 
   for (const def of VIRTUAL_CLIENTS){
@@ -232,9 +231,14 @@ function startVirtualClients(services, config){
         }
       }
     },
-    timer = setInterval(beat, intervalMs);
-  timer.unref?.();
-  beat();
+    // Like a real Client, follow heartbeat.intervalSec as it changes (§13.2).
+    tick = () => {
+      beat();
+      timer = setTimeout(tick, config.heartbeat.intervalSec * 1000);
+      timer.unref?.();
+    };
+  let timer = null;
+  tick();
 
   const sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
     stillActive = (jobId) => ACTIVE_JOB_STATES.has(jobs.get(jobId)?.state);
@@ -287,7 +291,7 @@ function startVirtualClients(services, config){
 
   return {
     resourceIds: Object.fromEntries([...clients].map(([id, c]) => [c.def.type, id])),
-    stop: () => clearInterval(timer)
+    stop: () => clearTimeout(timer)
   };
 }
 

package/src/login-guard.js

@@ -0,0 +1,111 @@
+/**
+ * @file        packages/coordinator/src/login-guard.js
+ * @description Sign-in protection: exponential backoff after failed attempts, per IP and per username, and a cap on concurrent password checks
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+// README §12. On top of the per-IP budget for sign-in attempts
+// (rate-limit.js): after a few failures in a row, each further failure
+// doubles the wait before the next attempt is even considered — checked
+// before any password hashing, so a locked-out guesser costs nothing.
+//
+//  - per IP: from the 5th failure, 1 s, 2 s, 4 s … up to 15 min.
+//  - per username: from the 10th, up to 5 min — milder, since anyone can
+//    trigger it for a name they know; it still slows guessing one account
+//    from many addresses to a crawl, without locking its owner out for long.
+//    Applied to any name typed, existing or not, so it reveals nothing.
+//
+// A success clears both. A record without a failure for an hour is dropped.
+const POLICIES = {
+    ip: { after: 5, maxSec: 15 * 60 },
+    user: { after: 10, maxSec: 5 * 60 }
+  },
+  FORGET_MS = 60 * 60 * 1000,
+  MAX_RECORDS = 50_000,
+  // Password checks running at once (scrypt on libuv's 4-thread pool, which
+  // file serving shares): beyond this, "busy, retry" instead of queueing.
+  MAX_CONCURRENT = 8;
+
+function createLoginGuard({ now = Date.now, maxConcurrent = MAX_CONCURRENT } = {}){
+  const records = new Map();
+  let inFlight = 0;
+
+  const keysOf = (ip, username) => [
+    ['ip', `ip:${ip}`],
+    ['user', `user:${String(username ?? '').trim().toLowerCase().slice(0, 128)}`]
+  ];
+
+  function record(key){
+    const r = records.get(key);
+    if (r && now() - r.lastFailure > FORGET_MS){
+      records.delete(key);
+      return null;
+    }
+    return r || null;
+  }
+
+  // Before checking a password: { ok } or { ok: false, retryAfterSec, reason }.
+  function check(ip, username){
+    let wait = 0;
+    for (const [, key]of keysOf(ip, username)){
+      const r = record(key);
+      if (r && r.lockedUntil > now()){
+        wait = Math.max(wait, r.lockedUntil - now());
+      }
+    }
+    if (wait){
+      return { ok: false, reason: 'backoff', retryAfterSec: Math.ceil(wait / 1000) };
+    }
+    if (inFlight >= maxConcurrent){
+      return { ok: false, reason: 'busy', retryAfterSec: 1 };
+    }
+    return { ok: true };
+  }
+
+  // Wraps the password check itself, for the concurrency cap.
+  async function run(fn){
+    inFlight += 1;
+    try {
+      return await fn();
+    }
+    finally {
+      inFlight -= 1;
+    }
+  }
+
+  function failure(ip, username){
+    for (const [kind, key]of keysOf(ip, username)){
+      const { after, maxSec } = POLICIES[kind],
+        r = record(key) || { failures: 0, lockedUntil: 0, lastFailure: 0 };
+      r.failures += 1;
+      r.lastFailure = now();
+      if (r.failures >= after){
+        r.lockedUntil = now() + Math.min(maxSec, 2 ** (r.failures - after)) * 1000;
+      }
+      records.delete(key);
+      if (records.size >= MAX_RECORDS){
+        records.delete(records.keys().next().value); // the longest-idle one
+      }
+      records.set(key, r);
+    }
+  }
+
+  function success(ip, username){
+    for (const [, key]of keysOf(ip, username)){
+      records.delete(key);
+    }
+  }
+
+  return { check, run, failure, success, size: () => records.size };
+}
+
+module.exports = { createLoginGuard, POLICIES };

package/src/rate-limit.js

@@ -0,0 +1,137 @@
+/**
+ * @file        packages/coordinator/src/rate-limit.js
+ * @description Request rate limiting: token buckets per credential (agent/resource token, dashboard user), per IP without one; a stricter one for sign-in
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const { hashToken } = require('./services/tokens');
+
+// README §12. A token bucket per caller: it holds up to `perMinute` tokens,
+// refills at `perMinute` a minute, and every request takes one — so a short
+// burst (a Client flushing logs, a page loading) goes through while the
+// sustained rate stays capped. Kept in memory: the Coordinator is a single
+// process by design.
+//
+// Who the caller is: the credential when the request carries a valid one
+// (agent token, resource token, dashboard session), else the client IP —
+// unauthenticated calls (sign-in, Client registration), and requests with
+// a token that doesn't exist, so a random token per request can't dodge the
+// limit. Keying by credential means a whole lab behind one NAT address
+// doesn't share a single budget.
+const MAX_BUCKETS = 50_000,
+  PRUNE_MS = 60_000;
+
+function createBuckets(){
+  const buckets = new Map();
+
+  // Takes one token from `key`'s bucket of `capacity`, refilled at
+  // `capacity` per minute. Returns { ok, remaining, retryAfterSec }.
+  function take(key, capacity, now = Date.now()){
+    const ratePerMs = capacity / 60_000;
+    let b = buckets.get(key);
+    if (!b){
+      if (buckets.size >= MAX_BUCKETS){
+        buckets.delete(buckets.keys().next().value); // oldest first
+      }
+      b = { tokens: capacity, at: now };
+    }
+    else {
+      buckets.delete(key); // re-insert below: Map order = least recently used first
+      b.tokens = Math.min(capacity, b.tokens + (now - b.at) * ratePerMs);
+      b.at = now;
+    }
+    buckets.set(key, b);
+    if (b.tokens >= 1){
+      b.tokens -= 1;
+      return { ok: true, remaining: Math.floor(b.tokens), retryAfterSec: 0 };
+    }
+    return { ok: false, remaining: 0, retryAfterSec: Math.max(1, Math.ceil((1 - b.tokens) / ratePerMs / 1000)) };
+  }
+
+  // A bucket that has refilled completely is the same as no bucket.
+  function prune(capacityOf, now = Date.now()){
+    for (const [key, b]of buckets){
+      const capacity = capacityOf(key);
+      if (b.tokens + (now - b.at) * (capacity / 60_000) >= capacity){
+        buckets.delete(key);
+      }
+    }
+  }
+
+  return { take, prune, size: () => buckets.size };
+}
+
+// The credential a request carries, if it's a real one: "agent:<id>",
+// "resource:<id>" or "user:<id>"; otherwise null (counted by IP).
+function credentialOf(req, services){
+  const [scheme, token] = (req.get('authorization') || '').split(' ');
+  if (scheme === 'Bearer' && token){
+    const hash = hashToken(token),
+      agent = services.agents.getByTokenHash(hash);
+    if (agent){
+      return `agent:${agent.id}`;
+    }
+    const resource = services.registry.getByTokenHash(hash);
+    return resource ? `resource:${resource.id}` : null;
+  }
+  const user = req.session?.user;
+  return user ? `user:${user.id}` : null;
+}
+
+function tooMany(req, res, retryAfterSec, what){
+  const text = `Too many ${what}: try again in ${retryAfterSec} s.`;
+  res.set('Retry-After', String(retryAfterSec));
+  if (req.originalUrl.startsWith('/api/') || !req.accepts('html')){
+    return res.status(429).json({ error: text, retryAfterSec });
+  }
+  res.status(429).type('text/plain').send(text);
+}
+
+// `config.rateLimit` is read on every request, so a change from the
+// dashboard (Settings, §13.2) applies at once. 0 turns a limit off.
+function createRateLimiter(config, services){
+  const buckets = createBuckets(),
+    capacityOf = (key) => (key.startsWith('login:') ? config.rateLimit.loginPerMinute : config.rateLimit.requestsPerMinute) || 1,
+    pruneTimer = setInterval(() => buckets.prune(capacityOf), PRUNE_MS);
+  pruneTimer.unref?.();
+
+  function limit(req, res, next){
+    const perMinute = config.rateLimit.requestsPerMinute,
+      loginPerMinute = config.rateLimit.loginPerMinute;
+
+    // Sign-in attempts: their own, much smaller budget per IP (password
+    // guessing), on top of the general one.
+    if (loginPerMinute > 0 && req.method === 'POST' && req.path === '/login'){
+      const login = buckets.take(`login:${req.ip}`, loginPerMinute);
+      if (!login.ok){
+        return tooMany(req, res, login.retryAfterSec, 'sign-in attempts');
+      }
+    }
+
+    if (!(perMinute > 0)){
+      return next();
+    }
+    const key = credentialOf(req, services) || `ip:${req.ip}`,
+      result = buckets.take(key, perMinute);
+    res.set({ 'RateLimit-Limit': String(perMinute), 'RateLimit-Remaining': String(result.remaining) });
+    if (!result.ok){
+      return tooMany(req, res, result.retryAfterSec, 'requests');
+    }
+    next();
+  }
+
+  limit.buckets = buckets;
+  limit.stop = () => clearInterval(pruneTimer);
+  return limit;
+}
+
+module.exports = { createRateLimiter, createBuckets };