@andrian.yablonskyy/thub-coordinator 1.0.39 → 1.0.41

package/src/security.js

@@ -0,0 +1,106 @@
+/**
+ * @file        packages/coordinator/src/security.js
+ * @description HTTP security headers for every response, and the same-origin check on the dashboard's state-changing requests (README §12)
+ *
+ * @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';
+
+// Everything the dashboard loads: its own files, plus Bootstrap and its
+// icon font from jsDelivr (layout.pug). No inline script at all — the
+// templates use data-* attributes (public/js/actions.js) — while inline
+// style="" attributes, used throughout the templates, stay allowed.
+const CDN = 'https://cdn.jsdelivr.net',
+  CONTENT_SECURITY_POLICY = [
+    'default-src \'self\'',
+    `script-src 'self' ${CDN}`,
+    `style-src 'self' ${CDN} 'unsafe-inline'`,
+    `font-src 'self' ${CDN}`,
+    // data: — Bootstrap's CSS draws some icons (select arrow, close button)
+    // as inline SVG images.
+    'img-src \'self\' data:',
+    // The CDN too: browser DevTools fetch Bootstrap's source maps (*.map)
+    // from it — a connection, not a script or style.
+    `connect-src 'self' ${CDN}`,
+    'object-src \'none\'',
+    'base-uri \'self\'',
+    'form-action \'self\'',
+    'frame-ancestors \'none\''
+  ].join('; '),
+  // 180 days, this host only: HTTPS is how a TLS-fronted Coordinator is
+  // reached; other hosts under the same domain are none of its business.
+  HSTS = 'max-age=15552000',
+  UNSAFE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+// Sent on every response (dashboard, API, static files).
+function securityHeaders(req, res, next){
+  res.set({
+    'Content-Security-Policy': CONTENT_SECURITY_POLICY,
+    // Also frame-ancestors above; this one for browsers that predate it.
+    'X-Frame-Options': 'DENY',
+    'X-Content-Type-Options': 'nosniff',
+    // Full URLs (job ids, searches) only within the dashboard itself.
+    'Referrer-Policy': 'same-origin',
+    'Cross-Origin-Opener-Policy': 'same-origin'
+  });
+  // Only on HTTPS (behind a TLS proxy: X-Forwarded-Proto from a trusted
+  // proxy, trustProxy) — over plain HTTP a browser ignores it anyway.
+  if (req.secure){
+    res.set('Strict-Transport-Security', HSTS);
+  }
+  next();
+}
+
+function originOf(url){
+  try {
+    return new URL(url).origin;
+  }
+  catch {
+    return null;
+  }
+}
+
+// CSRF defence for the session-authenticated routes (the dashboard, and
+// /api/v1/admin), on top of the session cookie's SameSite=Lax: a request
+// that changes something must come from this dashboard's own pages. The
+// browser says where from in Origin (every modern browser sends it on a
+// POST), else Referer; a request carrying neither isn't from a browser page
+// (curl, a script) and couldn't have been forged by one, so it passes. The
+// Agent/Client APIs use bearer tokens, which a browser never attaches by
+// itself, and don't go through here.
+function sameOriginOnly(config){
+  return (req, res, next) => {
+    if (!UNSAFE_METHODS.has(req.method)){
+      return next();
+    }
+    const origin = req.get('origin'),
+      from = origin !== undefined ? origin : req.get('referer') !== undefined ? originOf(req.get('referer')) : undefined;
+    if (from === undefined){
+      return next();
+    }
+    // The address the browser used (Host, as the reverse proxy passes it),
+    // or the configured publicUrl (a proxy that rewrites Host) — read on
+    // every request, since the dashboard can change it (§13.2).
+    const configured = originOf(config.publicUrl),
+      allowed = [configured, `${req.protocol}://${req.get('host')}`];
+    if (from && allowed.includes(from)){
+      return next();
+    }
+    const text = `Blocked: this request came from ${from || 'an unknown page'}, not from this dashboard (${configured}). ` +
+      'Changes can only be made from the dashboard\'s own pages. If you opened the dashboard at a different address, ' +
+      'set publicUrl to that address.';
+    if (req.originalUrl.startsWith('/api/')){ // req.path is relative to the router's mount point
+      return res.status(403).json({ error: text });
+    }
+    res.status(403).type('text/plain').send(text);
+  };
+}
+
+module.exports = { securityHeaders, sameOriginOnly, CONTENT_SECURITY_POLICY };

package/src/server.js

@@ -39,6 +39,9 @@ const fs = require('node:fs'),
   { createUpdatesService } = require('./services/updates'),
   { createLiveService } = require('./services/live'),
   { SqliteSessionStore } = require('./services/session-store'),
+  { securityHeaders, sameOriginOnly } = require('./security'),
+  { createSettingsService } = require('./services/settings'),
+  { createRateLimiter } = require('./rate-limit'),
 
   { createAgentRouter } = require('./api/agent'),
   { createResourceRouter } = require('./api/resource'),
@@ -58,6 +61,9 @@ function removeLegacyArtifacts(config){
 function buildServices(config){
   removeLegacyArtifacts(config);
   const db = openDb(config.dbPath),
+    // First: dashboard settings (README §13.2) go into `config` before any
+    // service reads it — some read theirs only once, at creation.
+    settings = createSettingsService(db, { config }).applyAtStartup(),
     events = createEventsService(db),
     registry = createRegistryService(db, { bus, events }),
     agents = createAgentsService(db, { events }),
@@ -101,7 +107,8 @@ function buildServices(config){
     cleanup,
     updates,
     live,
-    sessionStore
+    sessionStore,
+    settings
   };
 }
 
@@ -130,6 +137,9 @@ function createApp(config, services){
   app.set('view engine', 'pug');
   app.set('views', path.join(__dirname, '..', 'views'));
   app.set('trust proxy', config.trustProxy);
+  app.disable('x-powered-by');
+  // CSP, framing, nosniff, Referrer-Policy, HSTS on HTTPS (security.js, §12).
+  app.use(securityHeaders);
   app.locals.services = services;
   // Shown in every dashboard page's footer (layout.pug).
   app.locals.coordinatorVersion = require('../package.json').version;
@@ -174,12 +184,16 @@ function createApp(config, services){
   });
   app.use(express.static(path.join(__dirname, '..', 'public')));
   app.use('/avatars', express.static(config.avatarsDir));
+  // Everything below (API, dashboard, sign-in) — static files above aren't
+  // counted. Per credential, else per IP (rate-limit.js, §12).
+  app.use(createRateLimiter(config, services));
 
   app.use('/api/v1', createAgentRouter({ services, config }));
   app.use('/api/v1', createResourceRouter({ services, config }));
-  app.use('/api/v1/admin', createAdminRouter({ services }));
+  // Session-authenticated, like the dashboard: same-origin requests only.
+  app.use('/api/v1/admin', sameOriginOnly(config), createAdminRouter({ services }));
 
-  app.use('/', createWebRouter({ services, config }));
+  app.use('/', sameOriginOnly(config), createWebRouter({ services, config }));
 
   app.use((err, req, res, next) => {
     const status = err.status || 500;

package/src/services/admin-users.js

@@ -14,25 +14,42 @@
 'use strict';
 
 const crypto = require('node:crypto'),
+  { promisify } = require('node:util'),
   { v4: uuid } = require('uuid'),
   { normalize: normalizeListPrefs } = require('./list-prefs');
 
+// Stored as "<salt hex>:<scrypt hex>". The synchronous one is only for the
+// CLI and startup (thub-admin create-admin, the bootstrap password); every
+// request uses the async versions, which run scrypt on libuv's thread pool —
+// scryptSync would stall every request for each sign-in attempt.
+const scrypt = promisify(crypto.scrypt);
+
 function hashPassword(password){
   const salt = crypto.randomBytes(16).toString('hex'),
     derived = crypto.scryptSync(password, salt, 64).toString('hex');
   return `${salt}:${derived}`;
 }
 
-function verifyPassword(password, stored){
+async function hashPasswordAsync(password){
+  const salt = crypto.randomBytes(16).toString('hex');
+  return `${salt}:${(await scrypt(password, salt, 64)).toString('hex')}`;
+}
+
+async function verifyPassword(password, stored){
   const [salt, derived] = stored.split(':'),
-    check = crypto.scryptSync(password, salt, 64).toString('hex');
-  return crypto.timingSafeEqual(Buffer.from(check, 'hex'), Buffer.from(derived, 'hex'));
+    check = await scrypt(String(password ?? ''), salt, 64);
+  return crypto.timingSafeEqual(check, Buffer.from(derived, 'hex'));
 }
 
-// Presets offered on the profile page (§10.1) — a fixed list rather than a
-// free-text field, so a user can't accidentally set a 3-second or 10-year
-// idle timeout.
-const SESSION_TIMEOUT_OPTIONS_MIN = [15, 30, 60, 120, 240, 480, 1440],
+// Checked instead of a real hash when the username doesn't exist, so that
+// answer takes as long as a wrong password and doesn't reveal which
+// usernames exist.
+const DUMMY_HASH = hashPassword(crypto.randomBytes(16).toString('hex')),
+
+  // Presets offered on the profile page (§10.1) — a fixed list rather than a
+  // free-text field, so a user can't accidentally set a 3-second or 10-year
+  // idle timeout.
+  SESSION_TIMEOUT_OPTIONS_MIN = [15, 30, 60, 120, 240, 480, 1440],
   THEMES = ['auto', 'light', 'dark'];
 
 function toProfile(row){
@@ -105,26 +122,22 @@ function createAdminUsersService(db){
   // Self-service password change (§10.1) — requires knowing the *current*
   // password, unlike resetPassword() above (that's the admin/operator
   // break-glass path, which deliberately doesn't need it).
-  function changePassword(id, currentPassword, newPassword){
+  async function changePassword(id, currentPassword, newPassword){
     const row = db.prepare('SELECT * FROM admin_users WHERE id = ?').get(id);
-    if (!row || !verifyPassword(currentPassword, row.password_hash)){
+    if (!row || !(await verifyPassword(currentPassword, row.password_hash))){
       throw Object.assign(new Error('Current password is incorrect'), { status: 401 });
     }
     if (!newPassword){
       throw Object.assign(new Error('New password must not be empty'), { status: 400 });
     }
-    db.prepare('UPDATE admin_users SET password_hash = ? WHERE id = ?').run(hashPassword(newPassword), id);
+    db.prepare('UPDATE admin_users SET password_hash = ? WHERE id = ?').run(await hashPasswordAsync(newPassword), id);
   }
 
-  function verify(username, password){
-    const user = getByUsername(username);
-    if (!user){
-      return null;
-    }
-    if (!verifyPassword(password, user.password_hash)){
-      return null;
-    }
-    return toProfile(user);
+  // Async (thread pool); the same work whether or not the user exists.
+  async function verify(username, password){
+    const user = getByUsername(String(username ?? '')),
+      ok = await verifyPassword(password, user ? user.password_hash : DUMMY_HASH);
+    return user && ok ? toProfile(user) : null;
   }
 
   // Partial update — only the fields present in `fields` are touched, so a

package/src/services/heartbeat.js

@@ -18,9 +18,29 @@ const { RESOURCE_STATES, ACTIVE_JOB_STATES } = require('@andrian.yablonskyy/thub
 // §5.1 sweeper: runs every sweepIntervalSec, marks resources OUT_OF_SERVICE
 // after missedLimit missed heartbeats and moves any active job to LOST.
 function createHeartbeatMonitor(db, { bus, events, registry, jobs, config }){
-  function sweepOnce(){
-    const { intervalSec, missedLimit } = config.heartbeat,
-      cutoff = new Date(Date.now() - missedLimit * intervalSec * 1000).toISOString(),
+  // heartbeat.intervalSec can change while running (dashboard Settings,
+  // §13.2). Clients learn the new one from their next heartbeat reply, so
+  // right after it's *lowered* they're still on the old, longer one: keep
+  // judging by that until every Client has had time to switch over.
+  let seenInterval = config.heartbeat.intervalSec,
+    graceInterval = 0,
+    graceUntil = 0;
+  function effectiveInterval(now){
+    const current = config.heartbeat.intervalSec;
+    if (current !== seenInterval){
+      if (current < seenInterval){
+        graceInterval = seenInterval;
+        graceUntil = now + (config.heartbeat.missedLimit + 1) * seenInterval * 1000;
+      }
+      seenInterval = current;
+    }
+    return now < graceUntil ? Math.max(current, graceInterval) : current;
+  }
+
+  function sweepOnce(now = Date.now()){
+    const { missedLimit } = config.heartbeat,
+      intervalSec = effectiveInterval(now),
+      cutoff = new Date(now - missedLimit * intervalSec * 1000).toISOString(),
 
       stale = db
         .prepare(

package/src/services/job-artifacts.js

@@ -0,0 +1,91 @@
+/**
+ * @file        packages/coordinator/src/services/job-artifacts.js
+ * @description Artifacts a finished job reports (metadata only): validation, normalization and size formatting
+ *
+ * @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 §7.3. The job's command publishes its files wherever it likes and
+// lists them in $THUB_ARTIFACTS_FILE; the Client sends that list with the
+// result, and the job keeps only this metadata:
+//   { name, size, link, timestamp }
+// It comes from the job's own command, so it's treated as untrusted: only
+// http(s) links (a `javascript:` one would run in the dashboard when
+// clicked), bounded sizes, and entries that don't fit are dropped, not fatal.
+const MAX_ARTIFACTS = 500,
+  MAX_NAME = 255,
+  MAX_LINK = 2048;
+
+// Unix seconds, Unix milliseconds or an ISO date -> ISO string (or null).
+function normalizeTimestamp(value){
+  let ms = NaN;
+  if (typeof value === 'number' && Number.isFinite(value)){
+    ms = value < 1e11 ? value * 1000 : value; // 1e11 s is the year 5138: smaller means seconds
+  }
+  else if (typeof value === 'string' && value.trim()){
+    ms = /^\d+(\.\d+)?$/.test(value.trim()) ? normalizeTimestampMs(Number(value)) : Date.parse(value);
+  }
+  return Number.isFinite(ms) && ms >= 0 && ms < 8.64e15 ? new Date(ms).toISOString() : null;
+}
+
+function normalizeTimestampMs(n){
+  return n < 1e11 ? n * 1000 : n;
+}
+
+function normalizeLink(value){
+  if (typeof value !== 'string' || value.length > MAX_LINK){
+    return null;
+  }
+  try {
+    const url = new URL(value.trim());
+    return url.protocol === 'http:' || url.protocol === 'https:' ? url.href : null;
+  }
+  catch {
+    return null;
+  }
+}
+
+// -> { artifacts: [...valid, normalized], dropped: <count> }
+function sanitizeArtifacts(raw){
+  if (!Array.isArray(raw)){
+    return { artifacts: [], dropped: raw === undefined || raw === null ? 0 : 1 };
+  }
+  const artifacts = [];
+  let dropped = Math.max(0, raw.length - MAX_ARTIFACTS);
+  for (const item of raw.slice(0, MAX_ARTIFACTS)){
+    const name = typeof item?.name === 'string' ? item.name.trim().slice(0, MAX_NAME) : '',
+      link = normalizeLink(item?.link),
+      size = Number.isSafeInteger(item?.size) && item.size >= 0 ? item.size : null;
+    if (!name || !link){
+      dropped += 1;
+      continue;
+    }
+    artifacts.push({ name, size, link, timestamp: normalizeTimestamp(item.timestamp) });
+  }
+  return { artifacts, dropped };
+}
+
+// 1233 -> "1.2 KB" (1024-based, as file managers show it).
+const UNITS = ['B', 'KB', 'MB', 'GB', 'TB', 'PB'];
+function formatBytes(bytes){
+  if (!Number.isFinite(bytes) || bytes < 0){
+    return '—';
+  }
+  let value = bytes,
+    unit = 0;
+  while (value >= 1024 && unit < UNITS.length - 1){
+    value /= 1024;
+    unit += 1;
+  }
+  return unit === 0 ? `${value} B` : `${value < 10 ? value.toFixed(1) : Math.round(value)} ${UNITS[unit]}`;
+}
+
+module.exports = { sanitizeArtifacts, normalizeTimestamp, formatBytes, MAX_ARTIFACTS };

package/src/services/jobs.js

@@ -16,6 +16,7 @@
 const { validateJobSpec, maskEnv, JOB_STATES, ACTIVE_JOB_STATES, TERMINAL_JOB_STATES, RESOURCE_STATES } = require('@andrian.yablonskyy/thub-common'),
   { paginate } = require('./list-prefs'),
   { parseTerms, likeClause } = require('./search'),
+  { sanitizeArtifacts } = require('./job-artifacts'),
   // Named in spec errors: a field the Agent sends but this thub-common
   // doesn't know means the Coordinator needs an update.
   VERSIONS = `Coordinator v${require('../../package.json').version}, ` +
@@ -28,7 +29,8 @@ function rowToJob(row){
   return {
     ...row,
     spec: JSON.parse(row.spec),
-    summary: row.summary ? JSON.parse(row.summary) : null
+    summary: row.summary ? JSON.parse(row.summary) : null,
+    artifacts: row.artifacts ? JSON.parse(row.artifacts) : []
   };
 }
 
@@ -365,7 +367,9 @@ function createJobsService(db, { bus, events, registry, config }){
   }
 
   // Resource: POST /jobs/:id/result — final verdict from the test runner.
-  function applyResult(id, resourceId, { state, exitCode, summary }){
+  // `artifacts`: what the job published elsewhere (job-artifacts.js) — kept
+  // as metadata, stored before the job turns final so its page shows them.
+  function applyResult(id, resourceId, { state, exitCode, summary, artifacts }){
     const job = get(id);
     if (!job || job.resource_id !== resourceId){
       throw Object.assign(new Error('Job not assigned to this resource'), { status: 403 });
@@ -373,6 +377,13 @@ function createJobsService(db, { bus, events, registry, config }){
     if (![JOB_STATES.PASSED, JOB_STATES.FAILED, JOB_STATES.ERROR].includes(state)){
       throw Object.assign(new Error('Invalid result state'), { status: 400 });
     }
+    if (artifacts !== undefined){
+      const { artifacts: list, dropped } = sanitizeArtifacts(artifacts);
+      db.prepare('UPDATE jobs SET artifacts = ? WHERE id = ?').run(list.length ? JSON.stringify(list) : null, id);
+      if (dropped){
+        events.record('job', id, 'job.artifacts_dropped', { dropped });
+      }
+    }
     return setState(id, state, { exitCode, summary });
   }
 

package/src/services/registry.js

@@ -696,6 +696,39 @@ function createRegistryService(db, { bus, events }){
     return { resource: get(resourceId), ignored };
   }
 
+  // Groups tab (resource card): the Client's group membership. It belongs to
+  // the Client's config file (`groups`, which every registration reports),
+  // so it goes out as the next config revision — like an Import's top-level
+  // fields — for the Client to write there and restart with. The Coordinator
+  // applies it at once too, so scheduling follows without waiting for that.
+  // Fields of an Import not applied yet are carried along, not lost.
+  function setClientGroups(resourceId, groupIds, { by, knownGroupIds } = {}){
+    const r = get(resourceId);
+    if (!r){
+      throw Object.assign(new Error('Unknown resource'), { status: 404 });
+    }
+    const ids = [...new Set(groupIds)],
+      unknown = knownGroupIds ? ids.filter((id) => !knownGroupIds.includes(id) && !r.group_ids.includes(id)) : [];
+    if (unknown.length){
+      throw Object.assign(new Error(`Unknown group: ${unknown.join(', ')}`), { status: 400 });
+    }
+    // Writing top-level fields needs a Client that reports its config file
+    // (the same that Import needs); an older one would drop them.
+    const desired = r.config_desired || r.client_config;
+    if (!desired || !r.client_config_file){
+      throw Object.assign(new Error(`${r.name} is too old to take its groups from the dashboard — update its Client first`), { status: 409 });
+    }
+    const revision = r.config_revision + 1,
+      fields = { ...(pendingImport(r) || {}), groups: ids };
+    db.transaction(() => {
+      db.prepare(`UPDATE resources SET config_desired = ?, config_revision = ?, config_error = NULL, config_import = ?
+                  WHERE id = ?`).run(JSON.stringify(desired), revision, JSON.stringify({ revision, fields }), resourceId);
+      setGroups(resourceId, ids);
+    })();
+    events.record('resource', resourceId, 'resource.groups_set', { by, revision, groups: ids });
+    return get(resourceId);
+  }
+
   // Export (resource card): the Client's config file as it last reported it
   // (secrets excluded), with what's saved for it but not applied yet — so
   // exporting right after an edit or import gives what the Client will run.
@@ -796,6 +829,7 @@ function createRegistryService(db, { bus, events }){
     setRebootSchedule,
     pendingRebootSchedule,
     setClientConfig,
+    setClientGroups,
     pendingConfig,
     importClientConfig,
     exportClientConfig,