did stuff

server/config.example.yaml

@@ -0,0 +1,9 @@
+admins:
+  - username: admin
+    password_hash: "$2b$10$ZW4Jy7ctIt7k9V1AogFky.v4wedLF92t4/ZlT9kWPlIiCmdQNzJ.C" # password: adminpass
+    discord_id: "1234567890"
+    lockdown: false
+  - username: lockdown
+    password_hash: "$2b$10$n0L0oe1ZQy7IgM.FvVAzb.aXz43uaZWFiT0wr.05uNoVIDLawmrCG" # password: lockdownpass
+    discord_id: "0987654321"
+    lockdown: true

server/index.js

@@ -9,6 +9,7 @@ require('./src/helpers/sensorDecoder');
 require('./src/services/alertService');
 require('./src/services/authService');
 require('./src/services/modeManager');
+require('./src/services/lockdownGuard');
 require('./src/services/roverManager');
 require('./src/services/commandService');
 require('./src/services/roverConnectionService');

server/package-lock.json

@@ -8,7 +8,9 @@
       "name": "multiroombarover-server",
       "version": "0.1.0",
       "dependencies": {
+        "bcrypt": "^6.0.0",
         "express": "^4.19.2",
+        "js-yaml": "^4.1.1",
         "morgan": "^1.10.0",
         "socket.io": "^4.7.5",
         "uuid": "^9.0.1",
@@ -69,6 +71,12 @@
         "node": ">= 8"
       }
     },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "license": "Python-2.0"
+    },
     "node_modules/array-flatten": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/array-flatten/-/array-flatten-1.1.1.tgz",
@@ -109,6 +117,20 @@
       "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
       "license": "MIT"
     },
+    "node_modules/bcrypt": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/bcrypt/-/bcrypt-6.0.0.tgz",
+      "integrity": "sha512-cU8v/EGSrnH+HnxV2z0J7/blxH8gq7Xh2JFT6Aroax7UohdmiJJlxApMxtKfuI7z68NvvVcmR78k2LbT6efhRg==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "dependencies": {
+        "node-addon-api": "^8.3.0",
+        "node-gyp-build": "^4.8.4"
+      },
+      "engines": {
+        "node": ">= 18"
+      }
+    },
     "node_modules/binary-extensions": {
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz",
@@ -769,6 +791,18 @@
         "node": ">=0.12.0"
       }
     },
+    "node_modules/js-yaml": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
+      "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
     "node_modules/math-intrinsics": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -894,6 +928,26 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/node-addon-api": {
+      "version": "8.5.0",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-8.5.0.tgz",
+      "integrity": "sha512-/bRZty2mXUIFY/xU5HLvveNHlswNJej+RnxBjOMkidWfwZzgTbPG1E3K5TOxRLOR+5hX7bSofy8yf1hZevMS8A==",
+      "license": "MIT",
+      "engines": {
+        "node": "^18 || ^20 || >= 21"
+      }
+    },
+    "node_modules/node-gyp-build": {
+      "version": "4.8.4",
+      "resolved": "https://registry.npmjs.org/node-gyp-build/-/node-gyp-build-4.8.4.tgz",
+      "integrity": "sha512-LA4ZjwlnUblHVgq0oBF3Jl/6h/Nvs5fzBLwdEF4nuxnFdsfajde4WfxtJr3CaiH+F6ewcIB/q4jQ4UzPyid+CQ==",
+      "license": "MIT",
+      "bin": {
+        "node-gyp-build": "bin.js",
+        "node-gyp-build-optional": "optional.js",
+        "node-gyp-build-test": "build-test.js"
+      }
+    },
     "node_modules/nodemon": {
       "version": "3.1.10",
       "resolved": "https://registry.npmjs.org/nodemon/-/nodemon-3.1.10.tgz",

server/package.json

@@ -7,7 +7,9 @@
     "dev": "nodemon index.js"
   },
   "dependencies": {
+    "bcrypt": "^6.0.0",
     "express": "^4.19.2",
+    "js-yaml": "^4.1.1",
     "morgan": "^1.10.0",
     "socket.io": "^4.7.5",
     "uuid": "^9.0.1",

server/public/index.html

@@ -12,11 +12,21 @@
       .row { margin-bottom: 8px; }
       #alerts { margin-top: 12px; max-width: 600px; }
       .alert { background: #fff1d2; border: 1px solid #f0b651; padding: 6px 8px; margin-bottom: 6px; font-size: 0.9rem; }
+      #authPanel { margin: 12px 0; display: flex; gap: 8px; align-items: center; }
+      #authPanel input { padding: 4px; }
+      #activeDriver { margin-bottom: 8px; font-weight: bold; }
     </style>
   </head>
   <body>
     <h1>Multi Roomba Rover</h1>
     <div id="status">Connecting…</div>
+    <div id="authPanel">
+      <input id="username" placeholder="Username" />
+      <input id="password" type="password" placeholder="Password" />
+      <button id="loginBtn">Admin Login</button>
+      <button id="spectatorBtn">Spectate</button>
+      <span id="roleStatus">Role: user</span>
+    </div>
     <div id="layout">
       <div id="roverList">
         <label for="roverSelect">Rovers</label>
@@ -41,6 +51,7 @@
       </div>
       <div style="flex: 1">
         <h3>Sensor Frames</h3>
+        <div id="activeDriver">Active driver: --</div>
         <pre id="sensorOutput"></pre>
         <p>Use WASD keys to drive the selected rover. Shift increases speed.</p>
         <div id="alerts"></div>
@@ -52,6 +63,7 @@
     <script src="src/helpers/formatters.js"></script>
     <script src="src/services/state.js"></script>
     <script src="src/services/alertFeed.js"></script>
+    <script src="src/services/authControls.js"></script>
     <script src="src/services/roverUI.js"></script>
     <script src="src/services/driveControls.js"></script>
     <script src="src/main.js"></script>

server/public/src/main.js

@@ -2,5 +2,6 @@ requireModule('globals/socket');
 requireModule('helpers/formatters');
 requireModule('services/state');
 requireModule('services/alertFeed');
+requireModule('services/authControls');
 requireModule('services/roverUI');
 requireModule('services/driveControls');

server/public/src/services/authControls.js

@@ -0,0 +1,41 @@
+registerModule('services/authControls', (require, exports) => {
+  const { socket } = require('globals/socket');
+  const state = require('services/state');
+
+  const usernameInput = document.getElementById('username');
+  const passwordInput = document.getElementById('password');
+  const loginBtn = document.getElementById('loginBtn');
+  const roleStatus = document.getElementById('roleStatus');
+  const spectatorBtn = document.getElementById('spectatorBtn');
+
+  function updateRole(role) {
+    if (roleStatus) {
+      roleStatus.textContent = `Role: ${role}`;
+    }
+    state.setRole(role);
+  }
+
+  loginBtn?.addEventListener('click', () => {
+    const username = usernameInput.value.trim();
+    const password = passwordInput.value;
+    socket.emit('auth:login', { username, password }, (resp = {}) => {
+      if (!resp.success) {
+        alert(resp.error || 'Login failed');
+      } else {
+        updateRole(resp.role);
+      }
+      passwordInput.value = '';
+    });
+  });
+
+  socket.on('auth:role', ({ role }) => {
+    updateRole(role);
+  });
+  // initialize from default role
+  updateRole(state.getRole());
+
+  spectatorBtn?.addEventListener('click', () => {
+    socket.emit('role:set', { role: 'spectator' });
+    updateRole('spectator');
+  });
+});

server/public/src/services/roverUI.js

@@ -8,9 +8,16 @@ registerModule('services/roverUI', (require, exports) => {
   const sensorOutput = document.getElementById('sensorOutput');
   const requestBtn = document.getElementById('requestControl');
   const lockBtn = document.getElementById('lockToggle');
+  const activeDriverEl = document.getElementById('activeDriver');
 
   let roster = [];
 
+  state.onRoleChange((role) => {
+    const isAdmin = role === 'admin' || role === 'lockdown';
+    if (requestBtn) requestBtn.disabled = !isAdmin;
+    if (lockBtn) lockBtn.disabled = !isAdmin;
+  });
+
   socket.on('rovers', (list) => {
     roster = list;
     roverSelect.innerHTML = '';
@@ -48,6 +55,13 @@ registerModule('services/roverUI', (require, exports) => {
     sensorOutput.textContent = lines.join('\n');
   });
 
+  socket.on('activeDriver', ({ roverId, socketId }) => {
+    if (roverId !== state.getSelected()) return;
+    if (activeDriverEl) {
+      activeDriverEl.textContent = `Active driver: ${socketId || 'none'}`;
+    }
+  });
+
   requestBtn?.addEventListener('click', () => {
     socket.emit('requestControl', { roverId: state.getSelected() });
   });

server/public/src/services/state.js

@@ -1,5 +1,7 @@
 registerModule('services/state', (require, exports) => {
   let selectedRover = null;
+  let role = 'user';
+  const roleListeners = new Set();
 
   function setSelected(roverId) {
     selectedRover = roverId;
@@ -9,6 +11,24 @@ registerModule('services/state', (require, exports) => {
     return selectedRover;
   }
 
+  function setRole(nextRole) {
+    role = nextRole;
+    roleListeners.forEach((cb) => cb(role));
+  }
+
+  function getRole() {
+    return role;
+  }
+
+  function onRoleChange(cb) {
+    roleListeners.add(cb);
+    cb(role);
+    return () => roleListeners.delete(cb);
+  }
+
   exports.setSelected = setSelected;
   exports.getSelected = getSelected;
+  exports.setRole = setRole;
+  exports.getRole = getRole;
+  exports.onRoleChange = onRoleChange;
 });

server/scripts/hashPassword.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+const bcrypt = require('bcrypt');
+const readline = require('readline');
+
+const passwordFromArg = process.argv[2];
+
+async function hashPassword(password) {
+  try {
+    const hash = await bcrypt.hash(password, 10);
+    console.log(`Password: ${password}`);
+    console.log(`Hash: ${hash}`);
+    process.exit(0);
+  } catch (err) {
+    console.error('Error hashing password:', err.message);
+    process.exit(1);
+  }
+}
+
+if (passwordFromArg) {
+  hashPassword(passwordFromArg);
+} else {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.question('Password to hash: ', (answer) => {
+    rl.close();
+    hashPassword(answer);
+  });
+}

server/src/helpers/configLoader.js

@@ -0,0 +1,20 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const CONFIG_PATH = process.env.SERVER_CONFIG || path.join(__dirname, '..', '..', 'config.yaml');
+
+let cachedConfig;
+
+function loadConfig() {
+  if (cachedConfig) {
+    return cachedConfig;
+  }
+  const file = fs.readFileSync(CONFIG_PATH, 'utf8');
+  cachedConfig = yaml.load(file);
+  return cachedConfig;
+}
+
+module.exports = {
+  loadConfig,
+};

server/src/services/authService.js

@@ -1,12 +1,63 @@
-function isAdmin(/* socket */) {
-  return false;
+const bcrypt = require('bcrypt');
+const io = require('../globals/io');
+const { loadConfig } = require('../helpers/configLoader');
+const { clearLockdownTimer } = require('./lockdownGuard');
+const { setRole, roleEvents } = require('./roleService');
+
+const config = loadConfig();
+const admins = config.admins || [];
+
+function findAdmin(username) {
+  return admins.find((admin) => admin.username === username);
 }
 
-function isLockdownAdmin(/* socket */) {
-  return false;
+async function authenticate(username, password) {
+  const admin = findAdmin(username);
+  if (!admin) {
+    throw new Error('Invalid credentials');
+  }
+  const ok = await bcrypt.compare(password, admin.password_hash);
+  if (!ok) {
+    throw new Error('Invalid credentials');
+  }
+  return admin;
 }
 
+function isAdmin(socket) {
+  return socket?.data?.role === 'admin' || socket?.data?.role === 'lockdown';
+}
+
+function isLockdownAdmin(socket) {
+  return socket?.data?.role === 'lockdown';
+}
+
+io.on('connection', (socket) => {
+  setRole(socket, 'user');
+  socket.emit('auth:role', { role: 'user' });
+  socket.on('auth:login', async ({ username, password }, cb = () => {}) => {
+    try {
+      const admin = await authenticate(username, password);
+      const role = admin.lockdown ? 'lockdown' : 'admin';
+      socket.data.user = { username: admin.username, discordId: admin.discord_id };
+      setRole(socket, role);
+      socket.emit('auth:role', { role });
+      clearLockdownTimer(socket);
+      cb({ success: true, role: socket.data.role });
+    } catch (err) {
+      cb({ success: false, error: err.message });
+    }
+  });
+
+  socket.on('role:set', ({ role }) => {
+    if (role === 'spectator' || role === 'user') {
+      setRole(socket, role);
+      socket.emit('auth:role', { role });
+    }
+  });
+});
+
 module.exports = {
   isAdmin,
   isLockdownAdmin,
+  authenticate,
 };

server/src/services/commandService.js

@@ -1,7 +1,6 @@
 const { v4: uuidv4 } = require('uuid');
 const io = require('../globals/io');
 const roverManager = require('./roverManager');
-const { isAdmin } = require('./authService');
 
 const pendingCommands = new Map(); // id -> { roverId }
 
@@ -40,8 +39,8 @@ io.on('connection', (socket) => {
       if (!roverId) {
         throw new Error('roverId required');
       }
-      if (!roverManager.isDriver(roverId, socket) && !isAdmin(socket)) {
-        throw new Error('Not controlling this rover');
+      if (!roverManager.canDrive(roverId, socket)) {
+        throw new Error('Not your turn or no control');
       }
       const payload = data ? { ...data } : {};
       const id = issueCommand(roverId, { type, ...payload });

server/src/services/lockdownGuard.js

@@ -0,0 +1,46 @@
+const io = require('../globals/io');
+const { MODES, getMode, modeEvents } = require('./modeManager');
+const { isLockdownAdmin } = require('./roleService');
+
+function disconnectForLockdown(socket) {
+  socket.emit('lockdown', { message: 'Server is in lockdown mode' });
+  socket.disconnect(true);
+}
+
+function clearLockdownTimer(socket) {
+  if (socket?.data?.lockdownTimer) {
+    clearTimeout(socket.data.lockdownTimer);
+    socket.data.lockdownTimer = null;
+  }
+}
+
+function enforceLockdown() {
+  for (const socket of io.sockets.sockets.values()) {
+    if (!isLockdownAdmin(socket)) {
+      disconnectForLockdown(socket);
+    }
+  }
+}
+
+io.on('connection', (socket) => {
+  if (getMode() === MODES.LOCKDOWN && !isLockdownAdmin(socket)) {
+    socket.data.lockdownTimer = setTimeout(() => {
+      if (!isLockdownAdmin(socket)) {
+        disconnectForLockdown(socket);
+      }
+    }, 10000);
+    socket.once('disconnect', () => clearLockdownTimer(socket));
+  }
+});
+
+module.exports = {
+  enforceLockdown,
+  disconnectForLockdown,
+  clearLockdownTimer,
+};
+
+modeEvents.on('change', (mode) => {
+  if (mode === MODES.LOCKDOWN) {
+    enforceLockdown();
+  }
+});

server/src/services/modeManager.js

@@ -1,6 +1,7 @@
+const EventEmitter = require('events');
 const io = require('../globals/io');
 const { sendAlert, COLORS } = require('./alertService');
-const { isAdmin, isLockdownAdmin } = require('./authService');
+const { isAdmin, isLockdownAdmin } = require('./roleService');
 
 const MODES = {
   OPEN: 'open',
@@ -10,6 +11,7 @@ const MODES = {
 };
 
 let currentMode = MODES.OPEN;
+const modeEvents = new EventEmitter();
 
 function canChangeMode(socket, nextMode) {
   if (nextMode === MODES.LOCKDOWN) {
@@ -34,6 +36,7 @@ function setMode(nextMode, socket) {
     title: 'Mode Changed',
     message: `Server mode set to ${nextMode}`,
   });
+  modeEvents.emit('change', currentMode);
   return currentMode;
 }
 
@@ -45,6 +48,7 @@ module.exports = {
   MODES,
   getMode,
   setMode,
+  modeEvents,
 };
 
 io.on('connection', (socket) => {

server/src/services/roleService.js

@@ -0,0 +1,33 @@
+const EventEmitter = require('events');
+
+const roleEvents = new EventEmitter();
+
+function getRole(socket) {
+  return socket?.data?.role || 'user';
+}
+
+function setRole(socket, role) {
+  socket.data = socket.data || {};
+  if (socket.data.role === role) {
+    return;
+  }
+  socket.data.role = role;
+  roleEvents.emit('change', { socket, role });
+}
+
+function isAdmin(socket) {
+  const role = getRole(socket);
+  return role === 'admin' || role === 'lockdown';
+}
+
+function isLockdownAdmin(socket) {
+  return getRole(socket) === 'lockdown';
+}
+
+module.exports = {
+  getRole,
+  setRole,
+  isAdmin,
+  isLockdownAdmin,
+  roleEvents,
+};

server/src/services/roverManager.js

@@ -3,10 +3,12 @@ const logger = require('../globals/logger');
 const { sendAlert, COLORS } = require('./alertService');
 const { parseSensorFrame } = require('../helpers/sensorDecoder');
 const { MODES, getMode } = require('./modeManager');
-const { isAdmin } = require('./authService');
+const { isAdmin, roleEvents } = require('./roleService');
 
 const rovers = new Map(); // roverId -> record
 const socketToRovers = new Map(); // socketId -> Set(roverId)
+const spectatorSockets = new Set();
+const turnService = require('./turnService');
 
 function ensureRecord(id) {
   if (!rovers.has(id)) {
@@ -31,6 +33,10 @@ function upsertRover(meta, ws) {
   record.ws = ws;
   record.lastSeen = Date.now();
   rovers.set(id, record);
+  spectatorSockets.forEach((socketId) => {
+    const sock = io.sockets.sockets.get(socketId);
+    sock?.join(record.room);
+  });
   broadcastRoster();
   return record;
 }
@@ -39,6 +45,11 @@ function removeRover(id) {
   const record = rovers.get(id);
   if (!record) return;
   rovers.delete(id);
+  turnService.cleanupRover(id);
+  spectatorSockets.forEach((socketId) => {
+    const sock = io.sockets.sockets.get(socketId);
+    sock?.leave(record.room);
+  });
   broadcastRoster();
 }
 
@@ -89,14 +100,19 @@ function handleSensorFrame(roverId, frame) {
 
 function removeSocket(socket) {
   const joined = socketToRovers.get(socket.id);
-  if (!joined) return;
+  if (!joined) {
+    disableSpectator(socket);
+    return;
+  }
   for (const roverId of joined) {
     const record = rovers.get(roverId);
     if (record) {
       record.drivers.delete(socket.id);
     }
+    turnService.driverRemoved(roverId, socket.id);
   }
   socketToRovers.delete(socket.id);
+  disableSpectator(socket);
 }
 
 function requestControl(roverId, socket) {
@@ -104,6 +120,9 @@ function requestControl(roverId, socket) {
   if (!record) {
     throw new Error('Unknown rover');
   }
+  if (!isAdmin(socket)) {
+    throw new Error('Only admins can request control');
+  }
   if (record.locked && !isAdmin(socket)) {
     throw new Error('Rover locked');
   }
@@ -114,13 +133,13 @@ function requestControl(roverId, socket) {
   if (mode === MODES.LOCKDOWN && !isAdmin(socket)) {
     throw new Error('Server in lockdown');
   }
-  // TODO: future turns logic
   record.drivers.add(socket.id);
   if (!socketToRovers.has(socket.id)) {
     socketToRovers.set(socket.id, new Set());
   }
   socketToRovers.get(socket.id).add(roverId);
   socket.join(record.room);
+  turnService.driverAdded(roverId, socket.id);
   sendAlert({
     color: COLORS.success,
     title: 'Control Granted',
@@ -141,6 +160,7 @@ function releaseControl(roverId, socket) {
     }
   }
   socket.leave(record.room);
+  turnService.driverRemoved(roverId, socket.id);
 }
 
 function isDriver(roverId, socket) {
@@ -149,6 +169,10 @@ function isDriver(roverId, socket) {
   return record.drivers.has(socket.id);
 }
 
+function canDrive(roverId, socket) {
+  return turnService.canDrive(roverId, socket) || isAdmin(socket);
+}
+
 module.exports = {
   upsertRover,
   removeRover,
@@ -160,10 +184,26 @@ module.exports = {
   releaseControl,
   removeSocket,
   isDriver,
+  canDrive,
+  enableSpectator,
+  disableSpectator,
   rovers,
 };
 
+roleEvents.on('change', ({ socket, role }) => {
+  if (role === 'spectator') {
+    enableSpectator(socket);
+  } else {
+    disableSpectator(socket);
+  }
+});
+
 io.on('connection', (socket) => {
+  socket.emit('rovers', getRoster());
+  if (socket.data?.role === 'spectator') {
+    enableSpectator(socket);
+  }
+
   socket.on('requestControl', ({ roverId } = {}) => {
     try {
       const targetId = roverId || Array.from(rovers.keys())[0];
@@ -192,6 +232,9 @@ io.on('connection', (socket) => {
   });
 
   socket.on('subscribeAll', () => {
+    if (socket.data?.role !== 'spectator') {
+      return;
+    }
     for (const record of rovers.values()) {
       socket.join(record.room);
     }
@@ -201,3 +244,19 @@ io.on('connection', (socket) => {
     removeSocket(socket);
   });
 });
+
+function enableSpectator(socket) {
+  if (!socket?.id || spectatorSockets.has(socket.id)) return;
+  spectatorSockets.add(socket.id);
+  for (const record of rovers.values()) {
+    socket.join(record.room);
+  }
+}
+
+function disableSpectator(socket) {
+  if (!socket?.id || !spectatorSockets.has(socket.id)) return;
+  spectatorSockets.delete(socket.id);
+  for (const record of rovers.values()) {
+    socket.leave(record.room);
+  }
+}

server/src/services/turnService.js

@@ -0,0 +1,129 @@
+const io = require('../globals/io');
+const { sendAlert, COLORS } = require('./alertService');
+const { MODES, getMode, modeEvents } = require('./modeManager');
+
+const driverQueues = new Map(); // roverId -> { queue: [], current: socketId, timer: Timeout | null }
+const activeDrivers = new Map();
+const TURN_DURATION_MS = 60 * 1000;
+
+function driverAdded(roverId, socketId) {
+  const queue = ensureQueue(roverId);
+  if (!queue.queue.includes(socketId)) {
+    queue.queue.push(socketId);
+  }
+  if (!queue.current) {
+    queue.current = socketId;
+  }
+  syncState(roverId);
+}
+
+function driverRemoved(roverId, socketId) {
+  const queue = driverQueues.get(roverId);
+  if (!queue) return;
+  queue.queue = queue.queue.filter((id) => id !== socketId);
+  if (queue.current === socketId) {
+    advanceTurn(roverId);
+  }
+}
+
+function cleanupRover(roverId) {
+  const queue = driverQueues.get(roverId);
+  if (queue) {
+    clearTimeout(queue.timer);
+  }
+  driverQueues.delete(roverId);
+  activeDrivers.delete(roverId);
+}
+
+function canDrive(roverId, socket) {
+  if (!socket) return false;
+  const queue = driverQueues.get(roverId);
+  if (!queue || getMode() !== MODES.TURNS || queue.queue.length <= 1) {
+    return true;
+  }
+  return activeDrivers.get(roverId) === socket.id;
+}
+
+function ensureQueue(roverId) {
+  if (!driverQueues.has(roverId)) {
+    driverQueues.set(roverId, { queue: [], current: null, timer: null });
+  }
+  return driverQueues.get(roverId);
+}
+
+function syncState(roverId) {
+  const mode = getMode();
+  const queue = ensureQueue(roverId);
+  if (mode !== MODES.TURNS || queue.queue.length <= 1) {
+    queue.current = queue.queue[0] || null;
+    setActiveDriver(roverId, queue.current);
+    clearTimeout(queue.timer);
+    return;
+  }
+  if (!queue.current) {
+    queue.current = queue.queue[0];
+  }
+  setActiveDriver(roverId, queue.current);
+  scheduleNextTurn(roverId);
+}
+
+function scheduleNextTurn(roverId) {
+  const queue = driverQueues.get(roverId);
+  if (!queue) return;
+  clearTimeout(queue.timer);
+  queue.timer = setTimeout(() => advanceTurn(roverId), TURN_DURATION_MS);
+}
+
+function advanceTurn(roverId) {
+  const queue = driverQueues.get(roverId);
+  if (!queue) return;
+  if (queue.queue.length === 0) {
+    clearTimeout(queue.timer);
+    setActiveDriver(roverId, null);
+    return;
+  }
+  const mode = getMode();
+  if (mode !== MODES.TURNS || queue.queue.length <= 1) {
+    queue.current = queue.queue[0] || null;
+    setActiveDriver(roverId, queue.current);
+    clearTimeout(queue.timer);
+    return;
+  }
+  const idx = queue.queue.findIndex((id) => id === queue.current);
+  const nextIdx = idx === -1 ? 0 : (idx + 1) % queue.queue.length;
+  queue.current = queue.queue[nextIdx];
+  setActiveDriver(roverId, queue.current);
+  sendAlert({ color: COLORS.info, title: 'Turn switch', message: `${queue.current} now controls ${roverId}` });
+  stopRover(roverId);
+  scheduleNextTurn(roverId);
+}
+
+function setActiveDriver(roverId, socketId) {
+  if (!socketId) {
+    activeDrivers.delete(roverId);
+  } else {
+    activeDrivers.set(roverId, socketId);
+  }
+  io.emit('activeDriver', { roverId, socketId });
+}
+
+function stopRover(roverId) {
+  try {
+    const { issueCommand } = require('./commandService');
+    issueCommand(roverId, { type: 'drive', driveDirect: { left: 0, right: 0 } });
+    issueCommand(roverId, { type: 'motors', motorPwm: { main: 0, side: 0, vacuum: 0 } });
+  } catch (err) {
+    // best effort; log elsewhere if needed
+  }
+}
+
+modeEvents.on('change', (mode) => {
+  driverQueues.forEach((_, roverId) => syncState(roverId));
+});
+
+module.exports = {
+  driverAdded,
+  driverRemoved,
+  cleanupRover,
+  canDrive,
+};