@andrian.yablonskyy/thub-coordinator 1.0.42 → 1.1.0

package/bin/thub-admin.js

@@ -34,14 +34,24 @@ const { loadConfig } = require('../src/config'),
   { createCleanupService } = require('../src/services/cleanup'),
   { generateToken } = require('../src/services/tokens'),
   { createSettingsService } = require('../src/services/settings'),
+  { roleLabel, normalizeRole } = require('../src/services/admin-users'),
   { PACKAGES, fetchLatestVersion, isNewer, isValidVersion, npmBin, formatDateTime, parseDateTime } = require('@andrian.yablonskyy/thub-common'),
   { spawnSync } = require('node:child_process'),
   { version: installedVersion } = require('../package.json');
 
 function usage(){
   console.log(`Usage:
-  thub-admin create-admin <username> <password> [--role admin|viewer]
-  thub-admin agent add <name> --kind ci|cli
+  thub-admin user add <username> --email <email> [--role user|maintainer|admin] [--password <p>] [--key]
+                                  New user (§10.3). Maintainers/admins without --password get a
+                                  temporary one (printed once); --key also creates their access key
+  thub-admin user list
+  thub-admin user block|unblock <username>
+  thub-admin user role <username> user|maintainer|admin
+  thub-admin user password <username> <password>    Set a password (no change required)
+  thub-admin user key <username>  New access key for them (printed once; the old one stops)
+  thub-admin user delete <username>
+  thub-admin create-admin <username> <password> [--role admin|maintainer]   (= user add, no email)
+  thub-admin agent add <name>      A CI token (pipelines; people get their key with: user key)
   thub-admin join-key generate
   thub-admin resource maintenance <resourceId> --on|--off
   thub-admin jobs reset --yes     Cancel every queued/assigned/preparing/running job
@@ -138,7 +148,7 @@ function main(){
     events = createEventsService(db),
     registry = createRegistryService(db, { bus, events }),
     agents = createAgentsService(db, { events }),
-    adminUsers = createAdminUsersService(db),
+    adminUsers = createAdminUsersService(db, { events }),
     jobs = createJobsService(db, { bus, events, registry, config }),
     groups = createGroupsService(db, { events, registry });
 
@@ -159,6 +169,83 @@ function main(){
     return;
   }
 
+  // Users (§10.3) — also the way back in when nobody can sign in: unblock or
+  // re-role an admin, set a password. Run as the Coordinator's user.
+  if (cmd === 'user'){
+    const { positional, flags } = parseFlags(rest),
+      [username, arg] = positional,
+      by = 'thub-admin',
+      need = (u) => {
+        const row = adminUsers.getByUsername(u || '');
+        if (!row){
+          console.error(`No user "${u}"`);
+          process.exit(4);
+        }
+        return row;
+      };
+    try {
+      if (sub === 'list'){
+        for (const u of adminUsers.list()){
+          const key = u.key ? `…${u.key.hint || '????'}` : 'none';
+          console.log(`${u.username.padEnd(24)} ${roleLabel(u.role).padEnd(11)} ${u.blocked ? 'blocked' : 'active '}  ${u.email || '(no email)'}  key: ${key}`);
+        }
+        return;
+      }
+      if (sub === 'add'){
+        if (!username || !flags.email){
+          return usage(), process.exit(4);
+        }
+        const created = adminUsers.create({ username, email: flags.email, role: flags.role || 'user', password: flags.password, requireEmail: true }, { by });
+        console.log(`Created ${roleLabel(created.role)} "${created.username}"`);
+        if (created.tempPassword){
+          console.log(`Temporary password (shown once; to change at the first sign-in): ${created.tempPassword}`);
+        }
+        if (rest.includes('--key')){
+          console.log(`Access key (shown once): ${adminUsers.issueKey(created.id, { by })}`);
+        }
+        return;
+      }
+      const target = need(username);
+      if (sub === 'block' || sub === 'unblock'){
+        adminUsers.setBlocked(target.id, sub === 'block', { by });
+        console.log(`${sub === 'block' ? 'Blocked' : 'Unblocked'} "${target.username}"`);
+      }
+      else if (sub === 'role'){
+        const { tempPassword } = adminUsers.update(target.id, { role: arg }, { by });
+        console.log(`"${target.username}" is now ${roleLabel(normalizeRole(arg))}`);
+        if (tempPassword){
+          console.log(`Temporary password (shown once): ${tempPassword}`);
+        }
+      }
+      else if (sub === 'password'){
+        if (!arg){
+          return usage(), process.exit(4);
+        }
+        adminUsers.resetPassword({ username: target.username, password: arg });
+        console.log(`Password of "${target.username}" set`);
+      }
+      else if (sub === 'key'){
+        console.log(`Access key for "${target.username}" (shown once; any previous one has stopped working): ${adminUsers.issueKey(target.id, { by })}`);
+      }
+      else if (sub === 'delete'){
+        if (!flags.yes){
+          console.error(`This deletes "${target.username}" for good (their jobs stay). Re-run with --yes to confirm.`);
+          process.exit(4);
+        }
+        adminUsers.remove(target.id, { by });
+        console.log(`Deleted "${target.username}"`);
+      }
+      else {
+        return usage(), process.exit(4);
+      }
+    }
+    catch (err){
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
   if (cmd === 'create-admin'){
     const { positional, flags } = parseFlags([sub, ...rest].filter(Boolean)),
       [username, password] = positional;
@@ -166,18 +253,22 @@ function main(){
       return usage(), process.exit(4);
     }
     adminUsers.create({ username, password, role: flags.role || 'admin' });
-    console.log(`Created ${flags.role || 'admin'} user "${username}"`);
+    console.log(`Created ${roleLabel(normalizeRole(flags.role || 'admin'))} user "${username}"`);
     return;
   }
 
   if (cmd === 'agent' && sub === 'add'){
     const { positional, flags } = parseFlags(rest),
       [name] = positional;
-    if (!name || !flags.kind){
+    if (!name){
       return usage(), process.exit(4);
     }
-    const { agent, token } = agents.create({ name, kind: flags.kind });
-    console.log(`Agent ${agent.id} created. Token (shown once): ${token}`);
+    if (flags.kind && flags.kind !== 'ci'){
+      console.error('Agent tokens are for CI only now; a person gets their access key with: thub-admin user key <username>');
+      process.exit(4);
+    }
+    const { agent, token } = agents.create({ name, kind: 'ci' });
+    console.log(`CI token ${agent.id} created. Token (shown once): ${token}`);
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrian.yablonskyy/thub-coordinator",
-  "version": "1.0.42",
+  "version": "1.1.0",
   "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.33",
+    "@andrian.yablonskyy/thub-common": "^1.1.0",
     "better-sqlite3": "^12.4.1",
     "express": "^5.1.0",
     "express-session": "^1.18.2",

package/public/css/thub.css

@@ -227,3 +227,111 @@
     animation: none;
   }
 }
+
+/* Mobile / tablet menu (below lg, where the navbar collapses; layout.pug).
+   It drops down over the page instead of pushing it down, scrolls inside
+   itself on short screens, and is laid out for thumbs: pages as a two-column
+   grid, the tools in one row, the account in the next. public/js/actions.js
+   closes it on a tap outside, Esc, or choosing a page. */
+.thub-nav-break {
+  display: none;
+}
+
+@media (max-width: 991.98px) {
+  .navbar .thub-nav {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    right: 0;
+    z-index: 1035;
+    max-height: calc(100dvh - 4rem);
+    overflow-y: auto;
+    padding: 0.75rem 1rem 1rem;
+    background: var(--bs-tertiary-bg);
+    border-bottom: 1px solid var(--bs-border-color);
+    box-shadow: 0 0.75rem 1.5rem rgba(0, 0, 0, 0.15);
+  }
+
+  .thub-nav-pages {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 0.375rem;
+    padding-bottom: 0.75rem;
+    border-bottom: 1px solid var(--bs-border-color);
+  }
+
+  .thub-nav-pages .nav-link {
+    display: flex;
+    align-items: center;
+    min-height: 2.75rem;
+    padding: 0.5rem 0.75rem;
+    border-radius: var(--bs-border-radius);
+    background: var(--bs-body-bg);
+    border: 1px solid var(--bs-border-color-translucent);
+  }
+
+  .thub-nav-pages .nav-link.active {
+    background: var(--bs-primary-bg-subtle);
+    border-color: var(--bs-primary-border-subtle);
+    color: var(--bs-primary-text-emphasis);
+    font-weight: 500;
+  }
+
+  .thub-nav-tools {
+    flex-direction: row;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.5rem 0.75rem;
+    padding-top: 0.75rem;
+  }
+
+  .thub-nav-tools > li {
+    margin: 0 !important;
+  }
+
+  /* Bigger tap targets for the icon buttons. */
+  .thub-nav-tools .btn-sm {
+    min-width: 2.5rem;
+    min-height: 2.5rem;
+  }
+
+  /* The account row: the profile link takes the line, sign-out at its end. */
+  .thub-nav-break {
+    display: block;
+    flex-basis: 100%;
+    height: 0;
+  }
+
+  .thub-nav-account {
+    flex: 1 1 auto;
+    min-height: 2.5rem;
+  }
+}
+
+/* Phones: wide tables scroll sideways inside their own box instead of
+   running off the page, with one-line headers (wrapped headers of squeezed
+   columns used to make the header row very tall). The resource card's tab
+   row scrolls sideways too rather than wrapping onto several lines. */
+@media (max-width: 767.98px) {
+  main .table:not(.table-responsive .table) {
+    display: block;
+    max-width: 100%;
+    overflow-x: auto;
+    -webkit-overflow-scrolling: touch;
+  }
+
+  main .table th {
+    white-space: nowrap;
+  }
+
+  .thub-resource-card .nav-tabs {
+    flex-wrap: nowrap;
+    overflow-x: auto;
+    overflow-y: hidden;
+    scrollbar-width: thin;
+  }
+
+  .thub-resource-card .nav-tabs .nav-link {
+    white-space: nowrap;
+  }
+}

package/public/js/actions.js

@@ -30,6 +30,16 @@
     }
   });
 
+  // <select data-describe="#hint">: show the chosen option's data-help in
+  // #hint (e.g. what a role allows, under the role picker).
+  document.addEventListener('change', (e) => {
+    const select = e.target.closest?.('select[data-describe]'),
+      hint = select && document.querySelector(select.dataset.describe);
+    if (hint){
+      hint.textContent = select.selectedOptions[0]?.dataset.help || '';
+    }
+  });
+
   // <button data-fill="#field" data-value="…">: put the value into #field.
   document.addEventListener('click', (e) => {
     const btn = e.target.closest('[data-fill]'),
@@ -39,6 +49,29 @@
     }
   });
 
+  // The collapsed (mobile) menu drops down over the page (thub.css
+  // .thub-nav): close it on a tap outside, on Esc, and once a page in it is
+  // chosen — over the content, it shouldn't stay open in the way.
+  const nav = document.getElementById('nav'),
+    closeNav = () => {
+      if (nav?.classList.contains('show')){
+        window.bootstrap?.Collapse.getOrCreateInstance(nav, { toggle: false }).hide();
+      }
+    };
+  document.addEventListener('click', (e) => {
+    if (!nav?.classList.contains('show')){
+      return;
+    }
+    if (!e.target.closest('#nav, .navbar-toggler') || e.target.closest('#nav a[href]')){
+      closeNav();
+    }
+  });
+  document.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape'){
+      closeNav();
+    }
+  });
+
   // <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) => {

package/public/js/tooltips.js

@@ -16,5 +16,10 @@
 // Delegated (one instance per element, created on first hover/focus), so
 // content swapped in by live updates (public/js/live.js) gets tooltips too.
 (function (){
+  // On touch screens a tap would open a tooltip and leave it stuck there
+  // (no hover to end it) — over the mobile menu, too: no tooltips there.
+  if (!window.matchMedia('(hover: hover)').matches){
+    return;
+  }
   new bootstrap.Tooltip(document.body, { selector: '[data-bs-toggle="tooltip"]' });
 })();

package/src/api/agent.js

@@ -26,14 +26,17 @@ function createAgentRouter({ services, config }){
     // matching even happens, and reject them for lacking an agent token.
     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,
+    // Which jobs a key may see (README §12, §10.3): a CI token all of them;
+    // a user's key all of them for maintainers and admins, only their own
+    // for the `user` role. Anyone else's job is answered exactly like a job
+    // that doesn't exist (404), so a user can't tell which ids are in use.
+    seesAll = (req) => req.agent.kind === 'ci' || ['maintainer', 'admin'].includes(req.user?.role),
+    canSee = (req, job) => seesAll(req) || job.agent_id === req.agent.id,
+    // Cancelling: maintainers and admins any job; anyone else their own.
+    cancelsAll = (req) => ['maintainer', 'admin'].includes(req.user?.role),
     visibleJob = (req, res, next) => {
       const job = services.jobs.get(req.params.id);
-      if (!job || !canSee(req.agent, job)){
+      if (!job || !canSee(req, job)){
         return res.status(404).json({ error: 'Unknown job' });
       }
       req.job = job;
@@ -68,8 +71,8 @@ function createAgentRouter({ services, config }){
       state: req.query.state,
       source: req.query.source,
       agentId: req.agent.id,
-      // 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',
+      // A `user`'s list is always their own jobs (canSee above).
+      mine: !seesAll(req) || 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) });
@@ -77,7 +80,7 @@ function createAgentRouter({ services, config }){
 
   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 });
+      const job = services.jobs.cancel(req.params.id, { agentId: req.agent.id, isAdmin: cancelsAll(req) });
       res.json(services.jobs.publicJob(job));
     }
     catch (err){
@@ -101,6 +104,30 @@ function createAgentRouter({ services, config }){
     res.json({ artifacts: req.job.artifacts.map((a) => ({ ...a, url: a.link })) });
   });
 
+  // `thub whoami` / `thub key show` (§10.3): who this key belongs to.
+  router.get('/me', auth, (req, res) => {
+    if (!req.user){
+      return res.json({ kind: req.agent.kind, name: req.agent.name });
+    }
+    const { username, email, role } = req.user,
+      key = services.adminUsers.keyOf(req.user.id);
+    res.json({
+      kind: req.agent.kind,
+      user: { username, email, role },
+      key: { hint: key.token_hint, createdAt: key.token_created_at || key.created_at, lastUsedAt: key.last_used_at }
+    });
+  });
+
+  // `thub key rotate`: a user replaces their own key — the one sending this
+  // stops working at once, the new one is in the answer (only there).
+  // A CI token is replaced by an admin, on the dashboard.
+  router.post('/me/key/rotate', auth, (req, res) => {
+    if (!req.user){
+      return res.status(403).json({ error: 'A CI token is replaced by an admin on the dashboard (CI tokens)' });
+    }
+    res.json({ key: services.adminUsers.issueKey(req.user.id, { by: req.user.username }), username: req.user.username });
+  });
+
   router.get('/resources', auth, (req, res) => {
     res.json({ resources: services.registry.list().map(publicResource) });
   });

package/src/auth.js

@@ -36,11 +36,20 @@ function requireRole(role){
     const tokenHash = hashToken(token);
 
     if (role === 'agent'){
-      const agent = req.app.locals.services.agents.getByTokenHash(tokenHash);
+      const { agents, adminUsers } = req.app.locals.services,
+        agent = agents.getByTokenHash(tokenHash);
       if (!agent){
-        return res.status(401).json({ error: 'Invalid or revoked agent token' });
+        return res.status(401).json({ error: 'Invalid or revoked access key' });
       }
-      req.app.locals.services.agents.touchLastUsed(agent.id, appVersion(req, 'agent'));
+      // A user's access key (§10.3) works only while its user may use it.
+      if (agent.user_id){
+        const user = adminUsers.getById(agent.user_id);
+        if (!user || user.blocked){
+          return res.status(401).json({ error: user ? `User ${user.username} is blocked — ask an admin` : 'Invalid or revoked access key' });
+        }
+        req.user = user;
+      }
+      agents.touchLastUsed(agent.id, appVersion(req, 'agent'));
       req.agent = agent;
       return next();
     }
@@ -81,19 +90,43 @@ function requireJoinKey(config){
   };
 }
 
+// Dashboard session (§10.3): the user is read again on every request, so
+// blocking, deleting or demoting someone to `user` ends their session at
+// their next click, and a role change applies at once. A temporary password
+// must be changed (on the profile page) before anything else.
+const MUST_CHANGE_ALLOWED = ['/profile', '/profile/password', '/logout', '/live'];
 function requireAdminSession(req, res, next){
-  if (!req.session?.user){
+  const fresh = req.session?.user && req.app.locals.services.adminUsers.getById(req.session.user.id);
+  if (!fresh || fresh.blocked || !fresh.canUseDashboard){
+    const reason = !req.session?.user ? null
+      : !fresh ? 'Your account no longer exists.'
+        : fresh.blocked ? 'Your account is blocked — ask an admin.' : 'Your account has no dashboard access — use the Agent with your access key.';
+    if (req.session?.user){
+      req.session.user = null;
+      if (reason){
+        req.session.flash = [{ type: 'danger', text: reason }];
+      }
+    }
     if (req.accepts('html')){
       return res.redirect('/login');
     }
-    return res.status(401).json({ error: 'Login required' });
+    return res.status(401).json({ error: reason || 'Login required' });
+  }
+  req.session.user = fresh;
+  res.locals.user = fresh;
+  if (fresh.mustChangePassword && !MUST_CHANGE_ALLOWED.includes(req.path) && req.method === 'GET'){
+    return res.redirect('/profile');
   }
   next();
 }
 
+// The dashboard's security features (§10.3): Users, Settings, CI tokens…
 function requireAdminRole(req, res, next){
   if (req.session?.user?.role !== 'admin'){
-    return res.status(403).json({ error: 'Admin role required' });
+    const text = 'Only admins can open this — it\'s one of the Coordinator\'s security features.';
+    return req.originalUrl.startsWith('/api/') || !req.accepts('html')
+      ? res.status(403).json({ error: text })
+      : res.status(403).type('text/plain').send(text);
   }
   next();
 }

package/src/db/migrations/026_users.sql

@@ -0,0 +1,74 @@
+-- User management (README §10.3): one account table for everyone. Roles:
+--   user        submits jobs with the Agent and reads its results; no dashboard
+--   maintainer  user + the dashboard, without its security features
+--   admin       everything
+-- Each user may hold one access key: an `agents` row linked by user_id
+-- (jobs already reference agents, so a user's job history stays attached
+-- across key rotations). CI tokens stay agents rows without a user.
+--
+-- admin_users becomes users: SQLite can't change its role CHECK in place.
+CREATE TABLE users (
+  id TEXT PRIMARY KEY,
+  username TEXT NOT NULL UNIQUE,
+  email TEXT NOT NULL DEFAULT '',
+  -- NULL: no dashboard sign-in (role user, or a converted agent token).
+  password_hash TEXT,
+  role TEXT NOT NULL CHECK (role IN ('user', 'maintainer', 'admin')),
+  first_name TEXT,
+  last_name TEXT,
+  avatar_path TEXT,
+  timezone TEXT NOT NULL DEFAULT 'UTC',
+  theme TEXT NOT NULL DEFAULT 'auto' CHECK (theme IN ('auto', 'light', 'dark')),
+  session_timeout_min INTEGER NOT NULL DEFAULT 60,
+  list_prefs TEXT,
+  must_change_password INTEGER NOT NULL DEFAULT 0,
+  blocked_at TEXT,
+  created_at TEXT NOT NULL
+);
+
+-- Dashboard accounts: admin stays admin; viewer becomes maintainer.
+INSERT INTO users (id, username, email, password_hash, role, first_name, last_name, avatar_path, timezone, theme,
+                   session_timeout_min, list_prefs, created_at)
+  SELECT id, username, '', password_hash, CASE role WHEN 'viewer' THEN 'maintainer' ELSE role END,
+         first_name, last_name, avatar_path, timezone, theme, session_timeout_min, list_prefs, created_at
+  FROM admin_users;
+
+DROP TABLE admin_users;
+
+-- Every developer (cli) agent token becomes a user that owns it, so each
+-- existing key keeps working. Its name becomes the username — suffixed
+-- where that's taken (a dashboard account, an earlier token of the same
+-- name). A revoked token becomes a blocked user, kept for its job history.
+INSERT INTO users (id, username, email, password_hash, role, blocked_at, created_at)
+  SELECT 'usr_' || substr(a.id, 5),
+         a.name || CASE
+           WHEN EXISTS (SELECT 1 FROM users u WHERE u.username = a.name)
+             OR EXISTS (SELECT 1 FROM agents b WHERE b.kind = 'cli' AND b.name = a.name AND (b.created_at < a.created_at OR (b.created_at = a.created_at AND b.id < a.id)))
+           THEN '-' || substr(a.id, 5, 6) ELSE '' END,
+         '', NULL, 'user', a.revoked_at, a.created_at
+  FROM agents a
+  WHERE a.kind = 'cli';
+
+ALTER TABLE agents ADD COLUMN user_id TEXT REFERENCES users(id);
+-- The last characters of the key, to recognize it by (keys are stored hashed).
+ALTER TABLE agents ADD COLUMN token_hint TEXT;
+ALTER TABLE agents ADD COLUMN token_created_at TEXT;
+UPDATE agents SET user_id = 'usr_' || substr(id, 5) WHERE kind = 'cli';
+
+CREATE UNIQUE INDEX idx_agents_user ON agents(user_id) WHERE user_id IS NOT NULL;
+CREATE UNIQUE INDEX idx_users_email ON users(lower(email)) WHERE email <> '';
+
+-- The audit log gets user events (created, blocked, role changed, key
+-- rotated…). Same rebuild as 006: nothing has a foreign key into events.
+CREATE TABLE events_new (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts TEXT NOT NULL,
+  entity TEXT NOT NULL CHECK (entity IN ('job', 'resource', 'agent', 'group', 'user')),
+  entity_id TEXT NOT NULL,
+  type TEXT NOT NULL,
+  data TEXT
+);
+INSERT INTO events_new (id, ts, entity, entity_id, type, data) SELECT id, ts, entity, entity_id, type, data FROM events;
+DROP TABLE events;
+ALTER TABLE events_new RENAME TO events;
+CREATE INDEX idx_events_entity ON events(entity, entity_id);

package/src/server.js

@@ -68,7 +68,7 @@ function buildServices(config){
     registry = createRegistryService(db, { bus, events }),
     agents = createAgentsService(db, { events }),
     groups = createGroupsService(db, { events, registry }),
-    adminUsers = createAdminUsersService(db),
+    adminUsers = createAdminUsersService(db, { events }),
     commands = createCommandsService({ bus }),
     logs = createLogsService(db, { bus }),
     jobs = createJobsService(db, { bus, events, registry, config }),