@andrian.yablonskyy/thub-coordinator 1.0.0

package/src/config.js

@@ -0,0 +1,110 @@
+/**
+ * @file        packages/coordinator/src/config.js
+ * @description Coordinator config resolution: config file, env var overrides, and defaults (README §13)
+ *
+ * @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 fs = require('node:fs'),
+  path = require('node:path');
+
+// Defaults mirror README.md §13. Unlike the Client (config.js there), there
+// is no FHS-path fallback here — a real deployment must set
+// THUB_COORDINATOR_CONFIG explicitly to override the bundled default below.
+const DEFAULTS = {
+  listen: '127.0.0.1:8080',
+  publicUrl: 'http://localhost:8080',
+  dataDir: path.join(process.cwd(), '.data'),
+  sessionSecret: 'dev-only-change-me',
+  // Shared secret Clients present to self-register (see api/resource.js).
+  // null disables auto-registration entirely — set it explicitly to turn it on.
+  clientJoinKey: null,
+  heartbeat: {
+    intervalSec: 10,
+    missedLimit: 3,
+    sweepIntervalSec: 5
+  },
+  scheduler: {
+    assignAckTimeoutSec: 15,
+    requeueOnLost: true,
+    maxQueuedPerAgent: 20,
+    tickIntervalSec: 10
+  },
+  jobs: {
+    defaultTimeoutSec: 1800,
+    maxTimeoutSec: 14400
+  },
+  retention: {
+    logRetentionDays: 14,
+    artifactRetentionDays: 30
+  },
+  artifacts: {
+    maxUploadMb: 512,
+    linkTtlHours: 168
+  }
+};
+
+function deepMerge(base, override){
+  if (!override){
+    return base;
+  }
+  const out = { ...base };
+  for (const [k, v]of Object.entries(override)){
+    out[k] = v && typeof v === 'object' && !Array.isArray(v) ? deepMerge(base[k] || {}, v) : v;
+  }
+  return out;
+}
+
+// Bundled with the package so the Coordinator has something sane to run
+// with out of the box; a real deployment overrides it with
+// THUB_COORDINATOR_CONFIG or /srv/thub/coordinator.json (§13).
+const PACKAGE_DEFAULT_CONFIG_PATH = path.join(__dirname, '..', 'config.json');
+
+function loadConfig(configPath = process.env.THUB_COORDINATOR_CONFIG){
+  const candidate = [configPath, PACKAGE_DEFAULT_CONFIG_PATH].find(
+      (p) => p && fs.existsSync(p)
+    ),
+    fileConfig = candidate ? JSON.parse(fs.readFileSync(candidate, 'utf8')) || {} : {},
+    config = deepMerge(DEFAULTS, fileConfig);
+
+  // Environment overrides for the bits you don't want in a committed file.
+  if (process.env.THUB_LISTEN){
+    config.listen = process.env.THUB_LISTEN;
+  }
+  if (process.env.THUB_PUBLIC_URL){
+    config.publicUrl = process.env.THUB_PUBLIC_URL;
+  }
+  if (process.env.THUB_DATA_DIR){
+    config.dataDir = process.env.THUB_DATA_DIR;
+  }
+  if (process.env.THUB_SESSION_SECRET){
+    config.sessionSecret = process.env.THUB_SESSION_SECRET;
+  }
+  if (process.env.THUB_CLIENT_JOIN_KEY){
+    config.clientJoinKey = process.env.THUB_CLIENT_JOIN_KEY;
+  }
+
+  const [host, port] = config.listen.split(':');
+  config.host = host;
+  config.port = Number(port);
+  config.dbPath = path.join(config.dataDir, 'thub.db');
+  config.artifactsDir = path.join(config.dataDir, 'artifacts');
+  config.workDir = path.join(config.dataDir, 'work');
+  config.avatarsDir = path.join(config.dataDir, 'avatars');
+
+  fs.mkdirSync(config.dataDir, { recursive: true });
+  fs.mkdirSync(config.artifactsDir, { recursive: true });
+  fs.mkdirSync(config.avatarsDir, { recursive: true });
+
+  return config;
+}
+
+module.exports = { loadConfig, DEFAULTS };

package/src/db/index.js

@@ -0,0 +1,61 @@
+/**
+ * @file        packages/coordinator/src/db/index.js
+ * @description Opens the SQLite database and applies pending schema migrations on startup
+ *
+ * @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 fs = require('node:fs'),
+  path = require('node:path'),
+  Database = require('better-sqlite3');
+
+function openDb(dbPath){
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('synchronous = NORMAL');
+  db.pragma('foreign_keys = ON');
+  migrate(db);
+  return db;
+}
+
+function migrate(db){
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      id TEXT PRIMARY KEY,
+      applied_at TEXT NOT NULL
+    );
+  `);
+
+  const migrationsDir = path.join(__dirname, 'migrations'),
+    applied = new Set(db.prepare('SELECT id FROM schema_migrations').all().map((r) => r.id)),
+
+    files = fs
+      .readdirSync(migrationsDir)
+      .filter((f) => f.endsWith('.sql'))
+      .sort();
+
+  for (const file of files){
+    if (applied.has(file)){
+      continue;
+    }
+    const sql = fs.readFileSync(path.join(migrationsDir, file), 'utf8'),
+      runMigration = db.transaction(() => {
+        db.exec(sql);
+        db.prepare('INSERT INTO schema_migrations (id, applied_at) VALUES (?, ?)').run(
+          file,
+          new Date().toISOString()
+        );
+      });
+    runMigration();
+  }
+}
+
+module.exports = { openDb };

package/src/db/migrations/001_init.sql

@@ -0,0 +1,104 @@
+-- Schema mirrors README.md §9 (SQLite ER diagram).
+
+CREATE TABLE agents (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('ci', 'cli')),
+  token_hash TEXT NOT NULL UNIQUE,
+  created_at TEXT NOT NULL,
+  last_used_at TEXT,
+  revoked_at TEXT
+);
+
+CREATE TABLE resources (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  type TEXT NOT NULL CHECK (type IN ('hw', 'sw')),
+  status TEXT NOT NULL DEFAULT 'REGISTERED',
+  busy_source TEXT CHECK (busy_source IN ('ci', 'cli', 'local')),
+  busy_reason TEXT,
+  labels TEXT NOT NULL DEFAULT '[]',
+  host_info TEXT,
+  token_hash TEXT UNIQUE,
+  -- Unused: resources self-register via the shared clientJoinKey
+  -- (registry.registerAuto) rather than an admin-issued enrollment token.
+  -- Left in place because SQLite can't drop a UNIQUE column without a
+  -- full table rebuild, which isn't worth it for two dead columns.
+  enrollment_hash TEXT UNIQUE,
+  enrollment_expires_at TEXT,
+  last_heartbeat_at TEXT,
+  last_job_finished_at TEXT,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE jobs (
+  id TEXT PRIMARY KEY,
+  agent_id TEXT NOT NULL REFERENCES agents(id),
+  resource_id TEXT REFERENCES resources(id),
+  source TEXT NOT NULL CHECK (source IN ('ci', 'cli')),
+  state TEXT NOT NULL,
+  spec TEXT NOT NULL,
+  priority INTEGER NOT NULL DEFAULT 50,
+  attempt INTEGER NOT NULL DEFAULT 1,
+  exit_code INTEGER,
+  summary TEXT,
+  message TEXT,
+  created_at TEXT NOT NULL,
+  assigned_at TEXT,
+  started_at TEXT,
+  finished_at TEXT,
+  deadline_at TEXT
+);
+
+CREATE TABLE job_logs (
+  job_id TEXT NOT NULL REFERENCES jobs(id),
+  seq INTEGER NOT NULL,
+  ts TEXT NOT NULL,
+  stream TEXT NOT NULL,
+  line TEXT NOT NULL,
+  PRIMARY KEY (job_id, seq)
+);
+
+CREATE TABLE artifacts (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  job_id TEXT NOT NULL REFERENCES jobs(id),
+  name TEXT NOT NULL,
+  path TEXT NOT NULL,
+  size INTEGER NOT NULL,
+  sha256 TEXT,
+  content_type TEXT,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts TEXT NOT NULL,
+  entity TEXT NOT NULL CHECK (entity IN ('job', 'resource', 'agent')),
+  entity_id TEXT NOT NULL,
+  type TEXT NOT NULL,
+  data TEXT
+);
+
+-- Dashboard login (§10): separate from API tokens.
+CREATE TABLE admin_users (
+  id TEXT PRIMARY KEY,
+  username TEXT NOT NULL UNIQUE,
+  password_hash TEXT NOT NULL,
+  role TEXT NOT NULL CHECK (role IN ('admin', 'viewer')),
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE counters (
+  name TEXT PRIMARY KEY,
+  value INTEGER NOT NULL DEFAULT 0
+);
+-- Unused: job IDs are now A-00001../M-00001.. (see migration 003 and
+-- jobs.js's nextJobId), split by source rather than one shared sequence.
+INSERT INTO counters (name, value) VALUES ('job_id', 0);
+
+CREATE INDEX idx_jobs_scheduler ON jobs(state, priority DESC, created_at);
+CREATE INDEX idx_resources_status_type ON resources(status, type);
+CREATE INDEX idx_resources_heartbeat ON resources(last_heartbeat_at);
+CREATE INDEX idx_jobs_agent ON jobs(agent_id);
+CREATE INDEX idx_artifacts_job ON artifacts(job_id);
+CREATE INDEX idx_events_entity ON events(entity, entity_id);

package/src/db/migrations/003_split_job_id_counters.sql

@@ -0,0 +1,5 @@
+-- Job IDs split by source: A-00001.. for CI/CD, M-00001.. for manual
+-- `thub run` from a developer's own machine (jobs.js's nextJobId). The
+-- original 'job_id' counter is now unused — left in place, harmless.
+INSERT INTO counters (name, value) VALUES ('job_id_a', 0);
+INSERT INTO counters (name, value) VALUES ('job_id_m', 0);

package/src/db/migrations/004_add_client_id.sql

@@ -0,0 +1,8 @@
+-- Stable per-Client identity (a UUID a Client generates once and persists
+-- in its .client-id file, README §5.1/§8.6), separate from `name` so a
+-- Client can rename/retype itself on restart and still be recognized as
+-- the same resource (registry.registerAuto matches on this, not name).
+-- Nullable: resources created before this existed have no client_id and
+-- get adopted by name on that Client's next registration.
+ALTER TABLE resources ADD COLUMN client_id TEXT;
+CREATE UNIQUE INDEX idx_resources_client_id ON resources(client_id) WHERE client_id IS NOT NULL;

package/src/db/migrations/005_add_groups.sql

@@ -0,0 +1,14 @@
+-- Resource groups: an admin-managed way to partition the lab so a job can
+-- be constrained to run only on resources in a specific group (§13.1,
+-- `thub run --group <id>`). A resource declares which groups it belongs to
+-- (0 or more) in its own Client config, same JSON-array-column pattern as
+-- `labels` — not a join table, consistent with this schema's existing
+-- style and this system's scale (§3.1: tens of runners, not thousands).
+CREATE TABLE groups (
+  id TEXT PRIMARY KEY,  -- UUID
+  name TEXT NOT NULL,
+  comment TEXT,
+  created_at TEXT NOT NULL
+);
+
+ALTER TABLE resources ADD COLUMN group_ids TEXT NOT NULL DEFAULT '[]';

package/src/db/migrations/006_events_allow_group.sql

@@ -0,0 +1,20 @@
+-- events.entity's CHECK constraint didn't include 'group' (groups.js's
+-- audit calls). SQLite can't alter a CHECK constraint in place, so this
+-- rebuilds the table — safe here since nothing has a foreign key into
+-- events, unlike resources/jobs.
+CREATE TABLE events_new (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts TEXT NOT NULL,
+  entity TEXT NOT NULL CHECK (entity IN ('job', 'resource', 'agent', 'group')),
+  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/db/migrations/007_add_user_profile.sql

@@ -0,0 +1,10 @@
+-- Per-user dashboard profile settings (README §10.1): display name, avatar,
+-- timezone (used to render every dashboard timestamp), theme preference
+-- (synced across devices instead of living only in browser localStorage),
+-- and an idle session timeout the user picks for their own account.
+ALTER TABLE admin_users ADD COLUMN first_name TEXT;
+ALTER TABLE admin_users ADD COLUMN last_name TEXT;
+ALTER TABLE admin_users ADD COLUMN avatar_path TEXT;
+ALTER TABLE admin_users ADD COLUMN timezone TEXT NOT NULL DEFAULT 'UTC';
+ALTER TABLE admin_users ADD COLUMN theme TEXT NOT NULL DEFAULT 'auto' CHECK (theme IN ('auto', 'light', 'dark'));
+ALTER TABLE admin_users ADD COLUMN session_timeout_min INTEGER NOT NULL DEFAULT 60;

package/src/server.js

@@ -0,0 +1,179 @@
+/**
+ * @file        packages/coordinator/src/server.js
+ * @description Coordinator entry point: wires services, mounts routes, and starts the HTTP server
+ *
+ * @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 path = require('node:path'),
+  express = require('express'),
+  session = require('express-session'),
+
+  { loadConfig } = require('./config'),
+  { openDb } = require('./db'),
+  { bus } = require('./services/bus'),
+  { createEventsService } = require('./services/events'),
+  { createRegistryService } = require('./services/registry'),
+  { createAgentsService } = require('./services/agents'),
+  { createGroupsService } = require('./services/groups'),
+  { createAdminUsersService } = require('./services/admin-users'),
+  { createJobsService } = require('./services/jobs'),
+  { createScheduler } = require('./services/scheduler'),
+  { createHeartbeatMonitor } = require('./services/heartbeat'),
+  { createLogsService } = require('./services/logs'),
+  { createArtifactsService } = require('./services/artifacts'),
+  { createCommandsService } = require('./services/commands'),
+  { createRetentionService } = require('./services/retention'),
+
+  { createAgentRouter } = require('./api/agent'),
+  { createResourceRouter } = require('./api/resource'),
+  { createAdminRouter } = require('./api/admin'),
+  { createWebRouter } = require('./web/routes');
+
+function buildServices(config){
+  const db = openDb(config.dbPath),
+    events = createEventsService(db),
+    registry = createRegistryService(db, { bus, events }),
+    agents = createAgentsService(db, { events }),
+    groups = createGroupsService(db, { events, registry }),
+    adminUsers = createAdminUsersService(db),
+    commands = createCommandsService({ bus }),
+    logs = createLogsService(db, { bus }),
+    artifacts = createArtifactsService(db, { config }),
+    jobs = createJobsService(db, { bus, events, registry, artifacts, config }),
+    scheduler = createScheduler(db, { bus, events, registry, config }),
+    heartbeatMonitor = createHeartbeatMonitor(db, { bus, events, registry, jobs, config }),
+    retention = createRetentionService(db, { bus, logs, artifacts, config });
+
+  jobs.reconcileOnStartup();
+
+  const sweepInterval = setInterval(() => {
+    jobs.checkAssignAcks();
+    jobs.checkTimeouts();
+  }, config.heartbeat.sweepIntervalSec * 1000);
+  sweepInterval.unref?.();
+
+  return {
+    db,
+    bus,
+    events,
+    registry,
+    agents,
+    groups,
+    adminUsers,
+    commands,
+    jobs,
+    logs,
+    artifacts,
+    scheduler,
+    heartbeatMonitor,
+    retention
+  };
+}
+
+function createApp(config, services){
+  const app = express();
+  app.set('view engine', 'pug');
+  app.set('views', path.join(__dirname, '..', 'views'));
+  app.locals.services = services;
+
+  app.use(express.json({ limit: '2mb' }));
+  app.use(express.urlencoded({ extended: true }));
+  app.use(
+    session({
+      secret: config.sessionSecret,
+      resave: false,
+      saveUninitialized: false,
+      // Idle timeout, not a fixed one (§10.1): `rolling` re-sends a fresh
+      // Set-Cookie on every response, so the session survives as long as
+      // the user stays active and only actually expires `sessionTimeoutMin`
+      // (routes.js) after their *last* request. Each user's own preference
+      // is applied per-request in web/routes.js, since it isn't known here.
+      rolling: true,
+      cookie: { httpOnly: true, sameSite: 'lax' }
+    })
+  );
+  app.use(express.static(path.join(__dirname, '..', 'public')));
+  app.use('/avatars', express.static(config.avatarsDir));
+
+  app.use('/api/v1', createAgentRouter({ services, config }));
+  app.use('/api/v1', createResourceRouter({ services, config }));
+  app.use('/api/v1/admin', createAdminRouter({ services }));
+
+  // HMAC-signed artifact downloads (§3.1, §12) — no session or bearer token.
+  app.get('/artifacts/download/:token', (req, res, next) => {
+    try {
+      const artifact = services.artifacts.verify(req.params.token);
+      res.download(artifact.path, artifact.name);
+    }
+    catch (err){
+      next(err);
+    }
+  });
+
+  app.use('/', createWebRouter({ services, config }));
+
+  app.use((err, req, res, next) => {
+    const status = err.status || 500;
+    if (status >= 500){
+      console.error(err);
+    }
+    if (req.path.startsWith('/api/')){
+      return res.status(status).json({ error: err.message });
+    }
+    res.status(status).send(err.message);
+  });
+
+  return app;
+}
+
+function start(configPath){
+  const config = loadConfig(configPath),
+    services = buildServices(config),
+    app = createApp(config, services);
+
+  ensureBootstrapAdmin(services);
+
+  const server = app.listen(config.port, config.host, () => {
+    console.log(`TestHub Coordinator listening on http://${config.host}:${config.port}`);
+  });
+
+  return { app, server, services, config };
+}
+
+// THUB_BOOTSTRAP_ADMIN_PASSWORD is an exceptional password reset, not just
+// a first-run convenience (README §13.1): whenever it's set, it wins over
+// whatever's in the DB for THUB_BOOTSTRAP_ADMIN_USER (or "admin") — reset
+// that user's password if the account exists, or create it fresh as admin
+// if it doesn't — on *every* startup, not only when admin_users is empty.
+// Unset it again once you're back in; otherwise every restart re-applies
+// it. With it unset, login uses whatever's already in the DB, as normal.
+function ensureBootstrapAdmin(services){
+  const password = process.env.THUB_BOOTSTRAP_ADMIN_PASSWORD;
+  if (!password){
+    if (services.adminUsers.count() === 0){
+      console.warn(
+        'No admin_users exist and THUB_BOOTSTRAP_ADMIN_PASSWORD is not set — ' +
+          'create one with: node bin/thub-admin.js create-admin <user> <password>'
+      );
+    }
+    return;
+  }
+  const username = process.env.THUB_BOOTSTRAP_ADMIN_USER || 'admin';
+  services.adminUsers.resetPassword({ username, password });
+  console.log(`Reset password for admin user "${username}" from THUB_BOOTSTRAP_ADMIN_PASSWORD`);
+}
+
+if (require.main === module){
+  start();
+}
+
+module.exports = { start, buildServices, createApp };

package/src/services/admin-users.js

@@ -0,0 +1,174 @@
+/**
+ * @file        packages/coordinator/src/services/admin-users.js
+ * @description Admin user accounts: password hashing/verification and per-user profile settings (§10.1)
+ *
+ * @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 crypto = require('node:crypto'),
+  { v4: uuid } = require('uuid');
+
+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){
+  const [salt, derived] = stored.split(':'),
+    check = crypto.scryptSync(password, salt, 64).toString('hex');
+  return crypto.timingSafeEqual(Buffer.from(check, 'hex'), 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],
+  THEMES = ['auto', 'light', 'dark'];
+
+function toProfile(row){
+  return {
+    id: row.id,
+    username: row.username,
+    role: row.role,
+    firstName: row.first_name,
+    lastName: row.last_name,
+    avatarPath: row.avatar_path,
+    timezone: row.timezone,
+    theme: row.theme,
+    sessionTimeoutMin: row.session_timeout_min
+  };
+}
+
+// §10: dashboard login uses its own admin/viewer account table with
+// session cookies — deliberately separate from the API bearer tokens.
+function createAdminUsersService(db){
+  function getByUsername(username){
+    return db.prepare('SELECT * FROM admin_users WHERE username = ?').get(username);
+  }
+
+  function getById(id){
+    const row = db.prepare('SELECT * FROM admin_users WHERE id = ?').get(id);
+    return row ? toProfile(row) : null;
+  }
+
+  function count(){
+    return db.prepare('SELECT COUNT(*) AS n FROM admin_users').get().n;
+  }
+
+  function create({ username, password, role }){
+    const id = `usr_${uuid()}`;
+    db.prepare('INSERT INTO admin_users (id, username, password_hash, role, created_at) VALUES (?, ?, ?, ?, ?)').run(
+      id,
+      username,
+      hashPassword(password),
+      role,
+      new Date().toISOString()
+    );
+    return { id, username, role };
+  }
+
+  // Exceptional password reset (README §13.1): resets an *existing*
+  // user's password without touching their role (a reset shouldn't
+  // silently promote a viewer to admin), or creates one as admin if the
+  // named account doesn't exist yet — the original first-run bootstrap
+  // case, now handled by the same path.
+  function resetPassword({ username, password, role = 'admin' }){
+    const existing = getByUsername(username);
+    if (existing){
+      db.prepare('UPDATE admin_users SET password_hash = ? WHERE id = ?').run(hashPassword(password), existing.id);
+      return { id: existing.id, username, role: existing.role };
+    }
+    return create({ username, password, role });
+  }
+
+  // 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){
+    const row = db.prepare('SELECT * FROM admin_users WHERE id = ?').get(id);
+    if (!row || !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);
+  }
+
+  function verify(username, password){
+    const user = getByUsername(username);
+    if (!user){
+      return null;
+    }
+    if (!verifyPassword(password, user.password_hash)){
+      return null;
+    }
+    return toProfile(user);
+  }
+
+  // Partial update — only the fields present in `fields` are touched, so a
+  // theme-only PATCH (the navbar toggle, §10.1) doesn't require resending
+  // the whole profile. Username is unique like at creation time; changing
+  // it to one already held by a *different* account is a conflict, not a
+  // silent overwrite.
+  function updateProfile(id, fields){
+    if (fields.username !== undefined){
+      const owner = getByUsername(fields.username);
+      if (owner && owner.id !== id){
+        throw Object.assign(new Error(`Username "${fields.username}" is already taken`), { status: 409 });
+      }
+    }
+    if (fields.theme !== undefined && !THEMES.includes(fields.theme)){
+      throw Object.assign(new Error(`theme must be one of: ${THEMES.join(', ')}`), { status: 400 });
+    }
+    if (fields.sessionTimeoutMin !== undefined && !SESSION_TIMEOUT_OPTIONS_MIN.includes(fields.sessionTimeoutMin)){
+      throw Object.assign(new Error(`sessionTimeoutMin must be one of: ${SESSION_TIMEOUT_OPTIONS_MIN.join(', ')}`), {
+        status: 400
+      });
+    }
+
+    const columns = {
+        username: fields.username,
+        first_name: fields.firstName,
+        last_name: fields.lastName,
+        avatar_path: fields.avatarPath,
+        timezone: fields.timezone,
+        theme: fields.theme,
+        session_timeout_min: fields.sessionTimeoutMin
+      },
+      set = Object.entries(columns).filter(([, v]) => v !== undefined);
+    if (set.length === 0){
+      return getById(id);
+    }
+
+    db.prepare(`UPDATE admin_users SET ${set.map(([k]) => `${k} = ?`).join(', ')} WHERE id = ?`).run(
+      ...set.map(([, v]) => v),
+      id
+    );
+    return getById(id);
+  }
+
+  return {
+    getByUsername,
+    getById,
+    count,
+    create,
+    resetPassword,
+    changePassword,
+    verify,
+    updateProfile,
+    SESSION_TIMEOUT_OPTIONS_MIN,
+    THEMES
+  };
+}
+
+module.exports = { createAdminUsersService, SESSION_TIMEOUT_OPTIONS_MIN, THEMES };