@andrian.yablonskyy/thub-coordinator 1.0.39 → 1.0.41

package/test/security.test.js

@@ -0,0 +1,108 @@
+/**
+ * @file        packages/coordinator/test/security.test.js
+ * @description Tests: security headers on every response, and the same-origin (CSRF) check on the dashboard's POSTs
+ *
+ * @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 test = require('node:test'),
+  assert = require('node:assert/strict'),
+  fs = require('node:fs'),
+  os = require('node:os'),
+  path = require('node:path'),
+  { loadConfig } = require('../src/config'),
+  { buildServices, createApp } = require('../src/server');
+
+async function start(t, extra = {}){
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'thub-sec-')),
+    file = path.join(dir, 'coordinator.json');
+  fs.writeFileSync(file, JSON.stringify({
+    dataDir: path.join(dir, 'data'), sessionSecret: 'test-secret-test-secret', updates: { checkIntervalMin: 0 }, ...extra
+  }));
+  const config = loadConfig(file),
+    services = buildServices(config),
+    server = createApp(config, services).listen(0, '127.0.0.1');
+  t.after(() => new Promise((r) => {
+    server.closeAllConnections?.();
+    server.close(r);
+  }));
+  await new Promise((r) => server.on('listening', r));
+  services.adminUsers.create({ username: 'admin', password: 'pw', role: 'admin' });
+  return { base: `http://127.0.0.1:${server.address().port}`, services };
+}
+
+test('security headers on pages, the API and static files; HSTS only over HTTPS', async (t) => {
+  const { base } = await start(t);
+  for (const url of ['/login', '/api/v1/resources', '/css/thub.css']){
+    const res = await fetch(`${base}${url}`),
+      csp = res.headers.get('content-security-policy');
+    assert.equal(res.headers.get('x-frame-options'), 'DENY', url);
+    assert.equal(res.headers.get('x-content-type-options'), 'nosniff', url);
+    assert.equal(res.headers.get('referrer-policy'), 'same-origin', url);
+    assert.equal(res.headers.get('x-powered-by'), null, url);
+    assert.equal(res.headers.get('strict-transport-security'), null, url); // plain HTTP
+    assert.match(csp, /default-src 'self'/);
+    assert.match(csp, /script-src 'self' https:\/\/cdn\.jsdelivr\.net(;|$)/); // no 'unsafe-inline' for scripts
+    assert.match(csp, /frame-ancestors 'none'/);
+    assert.match(csp, /connect-src 'self' https:\/\/cdn\.jsdelivr\.net(;|$)/); // DevTools: Bootstrap's source maps
+    assert.match(csp, /object-src 'none'/);
+  }
+  // Behind the (loopback, trusted) TLS proxy.
+  const tls = await fetch(`${base}/login`, { headers: { 'X-Forwarded-Proto': 'https' } });
+  assert.match(tls.headers.get('strict-transport-security'), /^max-age=\d+$/);
+});
+
+test('same-origin check: POSTs from other sites are refused; own pages, publicUrl and non-browser clients pass', async (t) => {
+  const { base, services } = await start(t, { publicUrl: 'http://thub.lab.example' }),
+    post = (url, headers = {}) => fetch(`${base}${url}`, {
+      method: 'POST', headers, body: new URLSearchParams({ username: 'admin', password: 'pw' }), redirect: 'manual'
+    }),
+
+    // A forged cross-site form post (login CSRF here; any dashboard action alike).
+    evil = await post('/login', { Origin: 'https://evil.example' });
+  assert.equal(evil.status, 403);
+  assert.match(await evil.text(), /came from https:\/\/evil\.example, not from this dashboard \(http:\/\/thub\.lab\.example\)/);
+  assert.equal((await post('/login', { Origin: 'null' })).status, 403); // sandboxed iframe, data: URL
+  assert.equal((await post('/login', { Referer: 'https://evil.example/page' })).status, 403); // no Origin: Referer decides
+  assert.equal((await post('/login', { Origin: 'http://thub.lab.example:8443' })).status, 403); // another port is another origin
+
+  // The dashboard's own pages: the address it was opened at, or publicUrl
+  // (a reverse proxy that rewrites Host).
+  assert.equal((await post('/login', { Origin: base })).status, 302);
+  assert.equal((await post('/login', { Origin: 'http://thub.lab.example' })).status, 302);
+  assert.equal((await post('/login', { Referer: `${base}/login` })).status, 302);
+  // Neither header: not a browser page (curl, a script) — nothing to forge.
+  assert.equal((await post('/login')).status, 302);
+
+  // Reading is never blocked.
+  assert.equal((await fetch(`${base}/login`, { headers: { Origin: 'https://evil.example' } })).status, 200);
+
+  // The session-authenticated admin API is covered too (JSON answer)…
+  const admin = await fetch(`${base}/api/v1/admin/jobs/reset-queue`, { method: 'POST', headers: { Origin: 'https://evil.example' } });
+  assert.equal(admin.status, 403);
+  assert.match((await admin.json()).error, /Blocked/);
+  // …the bearer-token Agent API isn't: a browser never attaches that token by itself.
+  const { token } = services.agents.create({ name: 'ci', kind: 'ci' }),
+    agent = await fetch(`${base}/api/v1/jobs`, {
+      method: 'POST',
+      headers: { Origin: 'https://evil.example', authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body: JSON.stringify({})
+    });
+  assert.notEqual(agent.status, 403); // 400 invalid spec — got past the check
+});
+
+test('templates carry no inline event handlers (the CSP would block them)', () => {
+  const views = path.join(__dirname, '..', 'views'),
+    files = fs.readdirSync(views, { recursive: true }).filter((f) => f.endsWith('.pug'));
+  for (const f of files){
+    assert.doesNotMatch(fs.readFileSync(path.join(views, f), 'utf8'), /\bon[a-z]+="/, f);
+  }
+});

package/test/settings.test.js

@@ -0,0 +1,206 @@
+/**
+ * @file        packages/coordinator/test/settings.test.js
+ * @description Tests: Coordinator settings from the dashboard — precedence, validation, applying now vs after a restart, the page, thub-admin reset
+ *
+ * @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 test = require('node:test'),
+  assert = require('node:assert/strict'),
+  fs = require('node:fs'),
+  os = require('node:os'),
+  path = require('node:path'),
+  { spawnSync } = require('node:child_process'),
+  { loadConfig } = require('../src/config'),
+  { buildServices, createApp } = require('../src/server');
+
+function configFile(extra = {}){
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'thub-settings-')),
+    file = path.join(dir, 'coordinator.json');
+  fs.writeFileSync(file, JSON.stringify({
+    dataDir: path.join(dir, 'data'), sessionSecret: 'test-secret-test-secret', updates: { checkIntervalMin: 0 },
+    publicUrl: 'http://thub.lab', jobs: { defaultTimeoutSec: 1800, maxTimeoutSec: 14400 }, ...extra
+  }));
+  return file;
+}
+
+const byKey = (list) => Object.fromEntries(list.map((s) => [s.key, s]));
+
+test('settings: dashboard values override the file, "now" ones apply at once, "restart" ones at the next start', () => {
+  const file = configFile(),
+    config = loadConfig(file),
+    { settings } = buildServices(config);
+
+  assert.equal(byKey(settings.list())['jobs.maxTimeoutSec'].source, 'file');
+  const result = settings.save(
+    { changes: { 'jobs.maxTimeoutSec': '3600', 'scheduler.tickIntervalSec': '30', 'scheduler.requeueOnLost': 'false' } },
+    { by: 'alice' }
+  );
+  assert.deepEqual(result.now.sort(), ['jobs.maxTimeoutSec', 'scheduler.requeueOnLost']);
+  assert.deepEqual(result.restart, ['scheduler.tickIntervalSec']);
+
+  // Applied now: every service reads the same config object.
+  assert.equal(config.jobs.maxTimeoutSec, 3600);
+  assert.equal(config.scheduler.requeueOnLost, false);
+  // Not yet: shown as pending.
+  assert.equal(config.scheduler.tickIntervalSec, 10);
+  const list = byKey(settings.list());
+  assert.equal(list['scheduler.tickIntervalSec'].pendingRestart, true);
+  assert.equal(list['jobs.maxTimeoutSec'].source, 'dashboard');
+  assert.equal(list['jobs.maxTimeoutSec'].updatedBy, 'alice');
+
+  // The next start (same database) runs with them all.
+  const config2 = loadConfig(file),
+    { settings: settings2 } = buildServices(config2);
+  assert.equal(config2.scheduler.tickIntervalSec, 30);
+  assert.equal(config2.jobs.maxTimeoutSec, 3600);
+  assert.equal(byKey(settings2.list())['scheduler.tickIntervalSec'].pendingRestart, false);
+
+  // Reset: back to the config file's value.
+  settings2.save({ reset: ['jobs.maxTimeoutSec'] });
+  assert.equal(config2.jobs.maxTimeoutSec, 14400);
+  assert.equal(byKey(settings2.list())['jobs.maxTimeoutSec'].source, 'file');
+});
+
+test('settings: validated all-or-nothing; env-locked ones can\'t change; bad stored values are skipped at startup', (t) => {
+  const file = configFile(),
+    config = loadConfig(file),
+    { settings, db } = buildServices(config);
+
+  assert.throws(() => settings.save({ changes: { 'jobs.maxTimeoutSec': '600', publicUrl: 'not a url' } }), /Public URL: must be a URL/);
+  assert.equal(config.jobs.maxTimeoutSec, 14400); // nothing saved
+  assert.throws(() => settings.save({ changes: { 'jobs.defaultTimeoutSec': '7200', 'jobs.maxTimeoutSec': '3600' } }), /longer than the maximum/);
+  assert.throws(() => settings.save({ changes: { clientJoinKey: 'short' } }), /at least 16 characters/);
+  assert.throws(() => settings.save({ changes: { 'retention.jobRetention': '5y' } }), /must be one of/);
+  settings.save({ changes: { publicUrl: 'https://thub.example.com/', clientJoinKey: 'jk_0123456789abcdef' } });
+  assert.equal(config.publicUrl, 'https://thub.example.com'); // trailing slash dropped
+  assert.equal(config.clientJoinKey, 'jk_0123456789abcdef');
+  settings.save({ changes: { clientJoinKey: '' } }); // cleared: registration off
+  assert.equal(config.clientJoinKey, null);
+
+  // A value an older version stored that this one rejects: ignored, warned.
+  db.prepare('INSERT OR REPLACE INTO settings (key, value, updated_at) VALUES (?, ?, ?)').run('retention.jobRetention', '"5y"', 'x');
+  const warn = t.mock.method(console, 'warn', () => {}),
+    config2 = loadConfig(file);
+  buildServices(config2);
+  assert.equal(config2.retention.jobRetention, 'forever');
+  assert.match(warn.mock.calls[0].arguments[0], /Ignoring dashboard setting retention\.jobRetention/);
+
+  // The environment wins, and the dashboard can't override it.
+  const prev = process.env.THUB_PUBLIC_URL;
+  process.env.THUB_PUBLIC_URL = 'https://from-env.example';
+  t.after(() => (prev === undefined ? delete process.env.THUB_PUBLIC_URL : (process.env.THUB_PUBLIC_URL = prev)));
+  const config3 = loadConfig(file),
+    { settings: settings3 } = buildServices(config3);
+  assert.equal(config3.publicUrl, 'https://from-env.example');
+  assert.equal(byKey(settings3.list()).publicUrl.source, 'env');
+  assert.deepEqual(settings3.save({ changes: { publicUrl: 'https://other.example' } }).changed, []);
+  assert.equal(config3.publicUrl, 'https://from-env.example');
+});
+
+test('settings page: admins only; saves; refuses a setting that would lock everyone out', async (t) => {
+  const config = loadConfig(configFile()),
+    services = buildServices(config),
+    server = createApp(config, services).listen(0, '127.0.0.1');
+  t.after(() => new Promise((r) => {
+    server.closeAllConnections?.();
+    server.close(r);
+  }));
+  await new Promise((r) => server.on('listening', r));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  services.adminUsers.create({ username: 'admin', password: 'pw', role: 'admin' });
+  services.adminUsers.create({ username: 'view', password: 'pw', role: 'viewer' });
+  const login = async (u) => (await fetch(`${base}/login`, {
+      method: 'POST', body: new URLSearchParams({ username: u, password: 'pw' }), redirect: 'manual'
+    })).headers.get('set-cookie').split(';')[0],
+    admin = await login('admin'),
+    viewer = await login('view'),
+    post = (body) => fetch(`${base}/admin/settings`, { method: 'POST', headers: { cookie: admin }, body: new URLSearchParams(body), redirect: 'manual' }),
+    page = async () => (await fetch(`${base}/admin/settings`, { headers: { cookie: admin } })).text();
+
+  assert.equal((await fetch(`${base}/admin/settings`, { headers: { cookie: viewer } })).status, 403);
+  const html = await page();
+  assert.match(html, /name="s\[jobs\.maxTimeoutSec\]"/);
+  assert.match(html, /href="\/admin\/settings"/); // navbar link
+  assert.doesNotMatch(html, /test-secret-test-secret/); // secrets never in the page
+
+  // A checkbox posts "false" then (checked) "true"; the last one wins.
+  await post([['s[jobs.maxTimeoutSec]', '7200'], ['s[scheduler.requeueOnLost]', 'false']]);
+  assert.equal(config.jobs.maxTimeoutSec, 7200);
+  assert.equal(config.scheduler.requeueOnLost, false);
+  assert.match(await page(), /Saved and applied: Maximum job timeout \(s\), Retry lost jobs\./);
+
+  // An empty secret field leaves the key alone; "clear" removes it.
+  await post({ 's[clientJoinKey]': 'jk_0123456789abcdef' });
+  await post({ 's[clientJoinKey]': '' });
+  assert.equal(config.clientJoinKey, 'jk_0123456789abcdef');
+  await post({ 'clear[clientJoinKey]': '1' });
+  assert.equal(config.clientJoinKey, null);
+
+  // Over plain HTTP, an HTTPS-only cookie would lock everyone out: refused.
+  await post({ 's[session.secureCookie]': 'true' });
+  assert.match(await page(), /you're connected over plain HTTP|you're connected over plain HTTP/);
+  assert.equal(services.settings.list().find((s) => s.key === 'session.secureCookie').source, 'file');
+
+  // Not under systemd: no restart.
+  assert.equal((await fetch(`${base}/admin/settings/restart`, { method: 'POST', headers: { cookie: admin }, redirect: 'manual' })).status, 302);
+  assert.match(await page(), /isn't running under systemd|isn't running under systemd/);
+});
+
+test('thub-admin settings reset: the way back from a bad setting', () => {
+  const file = configFile(),
+    config = loadConfig(file),
+    { settings } = buildServices(config);
+  settings.save({ changes: { 'jobs.maxTimeoutSec': '3600', 'scheduler.maxQueuedPerAgent': '5' } });
+  const run = (...args) => spawnSync(process.execPath, [path.join(__dirname, '..', 'bin', 'thub-admin.js'), 'settings', ...args], {
+    env: { ...process.env, THUB_COORDINATOR_CONFIG: file }, encoding: 'utf8'
+  });
+  assert.match(run('list').stdout, /jobs\.maxTimeoutSec = 3600/);
+  assert.match(run('reset', 'jobs.maxTimeoutSec').stdout, /Removed 1 dashboard setting/);
+  assert.match(run('reset').stdout, /Removed 1 dashboard setting/);
+  assert.match(run('list').stdout, /No settings changed from the dashboard/);
+});
+
+test('heartbeat interval from Settings: sent in every reply; lowering it gives Clients time to switch', async (t) => {
+  const config = loadConfig(configFile()),
+    services = buildServices(config),
+    { settings, registry, heartbeatMonitor, db } = services,
+    server = createApp(config, services).listen(0, '127.0.0.1');
+  t.after(() => new Promise((r) => {
+    server.closeAllConnections?.();
+    server.close(r);
+  }));
+  await new Promise((r) => server.on('listening', r));
+  const { resourceId, resourceToken } = registry.registerAuto({ clientId: 'c1', name: 'lab-1', type: 'sw', labels: [] }),
+    beat = () => fetch(`http://127.0.0.1:${server.address().port}/api/v1/resources/${resourceId}/heartbeat`, {
+      method: 'POST', headers: { authorization: `Bearer ${resourceToken}`, 'content-type': 'application/json' }, body: JSON.stringify({ state: 'idle' })
+    }).then((r) => r.json()),
+    status = () => registry.get(resourceId).status;
+
+  assert.equal((await beat()).heartbeatIntervalSec, 10);
+  settings.save({ changes: { 'heartbeat.intervalSec': '5' } });
+  assert.equal((await beat()).heartbeatIntervalSec, 5); // the next reply carries it
+
+  // Last heard from 25 s ago, still on the old 10 s interval: within 3 × 10 s.
+  const now = Date.now(),
+    lastBeat = (ageSec) => db.prepare('UPDATE resources SET last_heartbeat_at = ? WHERE id = ?').run(new Date(now - ageSec * 1000).toISOString(), resourceId);
+  lastBeat(25);
+  heartbeatMonitor.sweepOnce(now); // 3 × 5 s alone would call it gone
+  assert.notEqual(status(), 'OUT_OF_SERVICE');
+  // Once every Client has had (missedLimit + 1) old intervals to switch, the new one counts.
+  heartbeatMonitor.sweepOnce(now + 41_000);
+  assert.equal(status(), 'OUT_OF_SERVICE');
+
+  // missedLimit applies at once, too.
+  settings.save({ changes: { 'heartbeat.missedLimit': '6', 'heartbeat.sweepIntervalSec': '2' } });
+  assert.equal(config.heartbeat.missedLimit, 6);
+  assert.equal(config.heartbeat.sweepIntervalSec, 5); // a timer: after a restart
+});

package/views/admin/settings.pug

@@ -0,0 +1,133 @@
+extends ../layout
+
+//- One setting's input (services/settings.js SETTINGS: type text | number
+//- | checkbox | select | secret). Names: s[<key>]; reset[] / clear[<key>].
+mixin settingInput(s, locked)
+  - const id = `setting-${s.key.replace(/\./g, '-')}`
+  if s.type === 'checkbox'
+    .form-check.form-switch
+      input(type="hidden" name=`s[${s.key}]` value="false" disabled=locked)
+      input.form-check-input(id=id type="checkbox" name=`s[${s.key}]` value="true" checked=s.value === true disabled=locked)
+      label.form-check-label.visually-hidden(for=id)= s.label
+  else if s.type === 'select'
+    select.form-select.form-select-sm(id=id name=`s[${s.key}]` disabled=locked)
+      each o in s.options
+        option(value=o selected=String(s.value) === String(o))= s.labels && s.labels[o] ? `${o} — ${s.labels[o]}` : o
+  else if s.type === 'secret'
+    .input-group.input-group-sm
+      input.form-control(
+        id=id
+        type="password"
+        name=`s[${s.key}]`
+        autocomplete="new-password"
+        placeholder=s.value ? `set (…${String(s.value).slice(-4)}) — type to replace` : 'not set — registration is off'
+        disabled=locked
+        data-secret-input
+      )
+      button.btn.btn-outline-secondary(type="button" data-secret-generate=`#${id}` disabled=locked) Generate
+      button.btn.btn-outline-secondary(type="button" data-secret-show=`#${id}` disabled=locked aria-label="Show")
+        i.bi.bi-eye
+    if s.value && !locked
+      .form-check.mt-1
+        input.form-check-input(id=`${id}-clear` type="checkbox" name=`clear[${s.key}]` value="1")
+        label.form-check-label.small(for=`${id}-clear`) Clear it (turns self-registration off)
+  else
+    input.form-control.form-control-sm(
+      id=id
+      type=s.type === 'number' ? 'number' : 'text'
+      name=`s[${s.key}]`
+      value=s.value === null || s.value === undefined ? '' : String(s.value)
+      disabled=locked
+    )
+
+block content
+  .d-flex.justify-content-between.align-items-center.mb-2
+    h1.h4.mb-0 Settings
+  p.text-body-secondary.small.
+    Coordinator options, saved in its database on top of the config file (#[code= readOnly.configPath]).
+    An environment variable still wins over both. Options marked #[span.badge.text-bg-secondary after restart]
+    are read only at startup.
+
+  if restarting
+    .alert.alert-info.d-flex.align-items-center.gap-2(data-restarting=restarting role="status")
+      span.spinner-border.spinner-border-sm(aria-hidden="true")
+      span Restarting the Coordinator… this page reloads by itself once it's back.
+  else if pendingRestart.length
+    .alert.alert-warning.d-flex.flex-wrap.align-items-center.gap-2
+      i.bi.bi-arrow-clockwise
+      span.me-auto
+        | Saved but not active until a restart: #{pendingRestart.map((s) => s.label).join(', ')}.
+      if canRestart
+        form(
+          method="post"
+          action="/admin/settings/restart"
+          data-confirm="Restart the Coordinator now? The dashboard and API are unavailable for a few seconds; Clients and Agents reconnect by themselves and running jobs carry on."
+          data-confirm-title="Restart the Coordinator?"
+          data-confirm-ok="Restart now"
+          data-confirm-tone="warning"
+        )
+          button.btn.btn-sm.btn-warning(type="submit") Restart now
+      else
+        span.small Restart it by hand: #[code sudo systemctl restart thub-coordinator].
+
+  form(method="post" action="/admin/settings")
+    each group in groups
+      .card.mb-3
+        .card-header.fw-semibold= group.name
+        ul.list-group.list-group-flush
+          each s in group.items
+            - const locked = s.source === 'env'
+            li.list-group-item
+              .row.g-2.align-items-start
+                .col-md-4
+                  label.form-label.mb-0.fw-medium(for=`setting-${s.key.replace(/\./g, '-')}`)= s.label
+                  .small.text-body-secondary
+                    code.small= s.key
+                  .d-flex.flex-wrap.gap-1.mt-1
+                    if s.applies === 'now'
+                      span.badge.text-bg-success applies now
+                    else
+                      span.badge.text-bg-secondary after restart
+                    if s.pendingRestart
+                      span.badge.text-bg-warning restart pending
+                    if s.source === 'env'
+                      span.badge.text-bg-dark(data-bs-toggle="tooltip" data-bs-title=`Set by the environment variable ${s.env}; unset it to change this here`)= `from ${s.env}`
+                    else if s.source === 'dashboard'
+                      span.badge.text-bg-info(data-bs-toggle="tooltip" data-bs-title=`Changed ${fmtDate(s.updatedAt)}${s.updatedBy ? ` by ${s.updatedBy}` : ''}`) from dashboard
+                    else
+                      span.badge.text-bg-light.border config file / default
+                .col-md-5
+                  +settingInput(s, locked)
+                  .form-text= s.help
+                .col-md-3
+                  if s.source === 'dashboard'
+                    .form-check.small
+                      input.form-check-input(id=`reset-${s.key}` type="checkbox" name="reset" value=s.key)
+                      label.form-check-label(for=`reset-${s.key}`)
+                        | Back to the config file's value
+                        if s.type !== 'secret'
+                          |  (
+                          code= s.fileValue === null || s.fileValue === undefined ? 'unset' : String(s.fileValue)
+                          | )
+    .d-flex.justify-content-end.gap-2.mb-4
+      a.btn.btn-outline-secondary(href="/admin/settings") Discard changes
+      button.btn.btn-primary(type="submit") Save settings
+
+  .card.mb-4
+    .card-header.fw-semibold Config file only
+    .card-body.small
+      p.text-body-secondary.
+        These change the address, storage or session signing the dashboard itself runs on, so they're set in the
+        config file (then #[code sudo systemctl restart thub-coordinator]).
+      dl.row.mb-0
+        dt.col-sm-3 listen
+        dd.col-sm-9: code= readOnly.listen
+        dt.col-sm-3 dataDir
+        dd.col-sm-9: code= readOnly.dataDir
+        dt.col-sm-3 sessionSecret
+        dd.col-sm-9 set (never shown)
+      p.small.text-body-secondary.mt-3.mb-0
+        | Locked out by a setting? On the Coordinator host: #[code thub-admin settings reset], then restart it.
+
+block scripts
+  script(src="/js/settings.js")

package/views/groups/list.pug

@@ -9,7 +9,7 @@ block content
 
   p.text-body-secondary.small: i.
     A job can be constrained to run only on resources in a group with `thub run --group <id>` (§13.1).
-    A resource joins a group by listing its id under `groups` in the Client's own config — membership isn't set here.
+    Which groups a Client is in is set on its resource card (Groups tab, admins), or as `groups` in the Client's own config — the tab writes it there.
 
   if totalCount
     .d-flex.flex-wrap.align-items-center.gap-2.mb-2

package/views/help/_agent-cli.pug

@@ -5,7 +5,7 @@
     thub status   <jobId> [--json]          Status; follow the log if running, verdict and test counts if done
     thub cancel   <jobId>                   Cancel a job
     thub resources [--json]                 Clients and their status
-    thub jobs     [--mine] [--state <s>] [--json]   Recent jobs
+    thub jobs     [--mine] [--state <s>] [--json]   Recent jobs (a cli token: only its own)
     thub config   set <url|token|group|user> <value>
     thub check-update                       Compare with the latest published Agent
     thub self-update [--to <x.y.z>]         Update with npm i -g

package/views/help/_agent-setup.pug

@@ -13,7 +13,7 @@
   h3.h6 Get a token
   p.small.
     An admin registers an agent on #[a(href="/admin/agents") Agents] (or with #[code thub-admin agent add]) and passes you
-    its token, which is shown only once. The agent's #[strong kind] decides the job id prefix and the default priority:
+    its token, which is shown only once. The agent's #[strong kind] decides the job id prefix, the default priority and which jobs it can see:
   table.table.table-sm.small.w-auto
     thead
       tr
@@ -21,17 +21,20 @@
         th For
         th Job ids
         th Default priority
+        th Can see
     tbody
       tr
         td: code ci
         td Pipelines
         td: code A-00001…
         td 50
+        td every job (details, log)
       tr
         td: code cli
         td Developers
         td: code M-00001…
         td 60 (so a busy pipeline doesn't starve them)
+        td only the jobs it submitted
 
   h3.h6 Configure
   +code('Save the settings once').

package/views/help/_client-setup.pug

@@ -83,7 +83,7 @@
         tr
           td: code groups
           td No
-          td Group ids (from #[a(href="/groups") Groups]) this Client belongs to, for #[code thub run --group].
+          td Group ids (from #[a(href="/groups") Groups]) this Client belongs to, for #[code thub run --group]. Admins can also set them on the resource card (Groups tab), which writes them here.
         tr
           td: code varDir
           td No

package/views/help/_coordinator.pug

@@ -30,6 +30,7 @@
       "heartbeat": { "intervalSec": 10, "missedLimit": 3, "sweepIntervalSec": 5 },
       "scheduler": { "assignAckTimeoutSec": 15, "requeueOnLost": true, "maxQueuedPerAgent": 20, "tickIntervalSec": 10 },
       "jobs": { "defaultTimeoutSec": 1800, "maxTimeoutSec": 14400 },
+      "rateLimit": { "requestsPerMinute": 500, "loginPerMinute": 10 },
       "retention": { "jobRetention": "forever" },
       "updates": { "checkIntervalMin": 15, "registry": null }
     }
@@ -60,10 +61,13 @@
           td The shared secret Clients self-register with. Unset or #[code null] turns registration off (#[code 503]).
         tr
           td: code heartbeat.*
-          td Clients heartbeat every #[code intervalSec]. After #[code missedLimit] misses a resource goes #[code OUT_OF_SERVICE] and its job becomes #[code LOST].
+          td Clients heartbeat every #[code intervalSec] — the Coordinator tells them, so it's set here only (and on Settings). After #[code missedLimit] misses a resource goes #[code OUT_OF_SERVICE] and its job becomes #[code LOST]; #[code sweepIntervalSec] is how often that's checked.
         tr
           td: code scheduler.*
           td #[code assignAckTimeoutSec]: how long an assignment waits for the Client to accept. #[code requeueOnLost]: retry a #[code LOST] job once. #[code maxQueuedPerAgent]: queue limit per agent.
+        tr
+          td: code rateLimit.*
+          td Requests per minute per caller (agent/resource token, dashboard user, else IP; default 500), and sign-in attempts per IP (default 10). Past it: #[code 429] with #[code Retry-After]. #[code 0] turns a limit off.
         tr
           td: code jobs.*
           td Default and maximum job timeout, in seconds.
@@ -73,6 +77,10 @@
         tr
           td: code updates.*
           td How often to check npm for new versions (#[code 0] turns the periodic check off), and an optional private registry.
+  +note('info').
+    Most of these can also be changed by admins on the dashboard's #[a(href="/admin/settings") Settings] page — stored in the
+    database on top of this file; some apply at once, the rest after a restart (#[strong Restart now] under systemd). An environment
+    variable still wins. Locked out by a setting? #[code thub-admin settings reset] on the Coordinator host, then restart.
   p.small.
     Resolution order: #[code THUB_COORDINATOR_CONFIG] (a path) → #[code ~/.config/thub/coordinator.json] → the bundled
     default. These environment variables override the file: #[code THUB_LISTEN], #[code THUB_PUBLIC_URL],

package/views/help/_env.pug

@@ -9,6 +9,7 @@
   -
     const thubVars = [
       ['THUB_JOB_ID', 'The job id, e.g. M-00125'],
+      ['THUB_ARTIFACTS_FILE', 'Where the command may list the artifacts it published elsewhere: a JSON array of {"name", "size", "link", "timestamp"}, shown on the job page'],
       ['THUB_WORK_DIR', 'The directory the command runs in: the --git-repo checkout, else empty. JUnit XML in results/ or artifacts/ gives the test counts; deleted when the job ends'],
       ['THUB_SUITE', '--suite (default: default)'],
       ['THUB_GIT_COMMIT', 'The exact commit checked out for --git-repo'],

package/views/help/_troubleshooting.pug

@@ -17,7 +17,9 @@
       ['Finding a job, resource, group or agent', 'Use the search box on its list page (press `/` to jump to it). Every word must match, e.g. `lab-hw-01 FAILED` or a git ref. Job search covers ids, users, resources, agents, commands, repos and `--meta`, but not `--env` values (secrets). On a job page, search the log above the log viewer: `Enter`/`Shift+Enter` step through matches.'],
       ['Lists don\'t update by themselves (navbar shows Offline or Paused)', '`Paused`: you\'re editing something on the page (a field, the inline rename, a dialog); it resumes when you\'re done. `Offline`: the browser can\'t hold the `/live` stream open, often a proxy buffering it (nginx: `proxy_buffering off;`); reloading the page always shows current data. `Session ended`: sign in again. Background updates never extend the session\'s idle timeout.'],
       ['Sign-in says it needs HTTPS', 'The session cookie is HTTPS-only because `publicUrl` is `https://`, but the request arrived as plain HTTP. Open the dashboard through its https:// address; behind a reverse proxy, make it send `X-Forwarded-Proto: https` (nginx: `proxy_set_header X-Forwarded-Proto $scheme;`) and check `trustProxy`. To allow plain HTTP, set `session.secureCookie` to `false`.'],
-      ['Where are a job\'s test reports and output files?', 'The Coordinator keeps only the log and the result (verdict, exit code, JUnit test counts). Files the job creates stay in its workspace on the Client and are deleted when the job ends. To keep them, publish them from `--command`, e.g. `curl -fsS -H "Authorization: Bearer $ART_TOKEN" -T results/report.xml "https://artifactory.example.com/qa/$THUB_JOB_ID/report.xml"` with `--env ART_TOKEN`. The full log is always available from the job page\'s Raw button.'],
+      ['Where are a job\'s test reports and output files?', 'The Coordinator keeps only the log and the result (verdict, exit code, JUnit test counts). Files the job creates stay in its workspace on the Client and are deleted when the job ends. To keep them, publish them from `--command`, e.g. `curl -fsS -H "Authorization: Bearer $ART_TOKEN" -T results/report.xml "https://artifactory.example.com/qa/$THUB_JOB_ID/report.xml"` with `--env ART_TOKEN`. To show them on the job page and in `thub status`, list them in `$THUB_ARTIFACTS_FILE` as `[{"name", "size", "link", "timestamp"}]` — only that metadata is kept. The full log is always available from the job page\'s Raw button.'],
+      ['429 Too Many Requests', 'A caller went over `rateLimit.requestsPerMinute` (per agent or resource token, per dashboard user, else per IP; default 500). The Agent and Client wait for `Retry-After` and retry by themselves; a script calling the API should do the same. Raise the limit in the config file or on Settings if your normal traffic needs more (a Client streaming logs makes up to ~240 requests a minute). Too many sign-in attempts from one address: wait a minute (`rateLimit.loginPerMinute`).'],
+      ['Sign-in says “Too many failed sign-ins”', 'After repeated wrong passwords the Coordinator makes each further attempt wait, doubling each time: per address from the 5th failure (up to 15 min), per username from the 10th from any address (up to 5 min). Wait the time shown, or sign in from another address; a successful sign-in clears it, and an hour without failures forgets it. The Coordinator never tells whether a username exists.'],
       ['Locked out of the dashboard', 'Restart the Coordinator once with `THUB_BOOTSTRAP_ADMIN_PASSWORD=<new>` (resets the `admin` user), then unset it.']
     ]
     const withCode = (text) => text

package/views/jobs/list.pug

@@ -15,12 +15,12 @@ block content
     .col-12.col-md-5.col-lg-4
       +searchBox(filters.q, 'Search jobs: id, user, resource, command, repo…', list.urlFor({ q: '' }))
     .col-auto
-      select.form-select.form-select-sm(name="state" onchange="this.form.submit()")
+      select.form-select.form-select-sm(name="state" data-autosubmit)
         option(value="") any state
         each s in ['QUEUED','ASSIGNED','PREPARING','RUNNING','PASSED','FAILED','ERROR','TIMEOUT','CANCELED','LOST']
           option(value=s selected=filters.state === s)= s
     .col-auto
-      select.form-select.form-select-sm(name="source" onchange="this.form.submit()")
+      select.form-select.form-select-sm(name="source" data-autosubmit)
         option(value="") any source
         option(value="ci" selected=filters.source === 'ci') ci
         option(value="cli" selected=filters.source === 'cli') cli
@@ -128,8 +128,8 @@ block content
         each preset in cleanupInfo.presets
           button.btn.btn-sm.btn-outline-secondary(
             type="button"
+            data-fill="#cleanup-before"
             data-value=preset.value
-            onclick="document.getElementById('cleanup-before').value = this.dataset.value"
           )= preset.label
       p
         | Deletes finished jobs that ended before then, with their logs, and the resource, agent and group history logged before then — then compacts the database file.

package/views/jobs/show.pug

@@ -49,5 +49,41 @@ block content
       dt.col-sm-2 Message
       dd.col-sm-10= job.message
 
+  //- What the job published elsewhere and listed in $THUB_ARTIFACTS_FILE
+  //- (README §7.3): metadata only; the links go to wherever the files are.
+  h2.h6.mt-4#artifacts Artifacts
+  if job.artifacts.length
+    .table-responsive
+      table.table.table-sm.align-middle.mb-0
+        thead
+          tr
+            th Name
+            th.text-end Size
+            th Time
+            th
+        tbody
+          each a in job.artifacts
+            tr
+              td
+                a(href=a.link target="_blank" rel="noopener noreferrer")= a.name
+              td.text-end.text-nowrap(title=a.size != null ? `${a.size} bytes` : null)= a.size != null ? fmtBytes(a.size) : '—'
+              td.text-nowrap= a.timestamp ? fmtDate(a.timestamp) : '—'
+              td.text-end
+                a.btn.btn-sm.btn-outline-secondary(
+                  href=a.link
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  aria-label=`Download ${a.name}`
+                  data-bs-toggle="tooltip"
+                  data-bs-title=a.link
+                )
+                  i.bi.bi-download
+  else if jobActive
+    p.small.text-body-secondary.mb-0 Listed here when the job finishes, if it reports any.
+  else
+    p.small.text-body-secondary.mb-0.
+      None reported. A job lists the files it published (to Artifactory, S3, a file server…) in
+      #[code $THUB_ARTIFACTS_FILE] as #[code [{"name", "size", "link", "timestamp"}]].
+
   h2.h6.mt-4 Log
   +logViewer(job.id, jobActive)