geniejars 0.2.7

package/script/setup-geniejars.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+// One-time system setup — must be run as root (sudo node script/setup-geniejars.mjs)
+//
+// Creates geniejars, groups, ACLs, sudoers rule, and socket directory.
+// Idempotent — safe to run again after changing pool size.
+
+import { execFile as _execFile } from 'child_process'
+import { promisify } from 'util'
+import fs from 'fs/promises'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { loadConfig, allNames } from '../src/pool.mjs'
+
+const execFile = promisify(_execFile)
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const agentScript = path.resolve(__dirname, '../src/agent.mjs')
+
+// Assert running as root
+if (process.getuid() !== 0) {
+  console.error('Error: setup must be run as root. Use: sudo node script/setup-geniejars.mjs')
+  process.exit(1)
+}
+
+const config = await loadConfig()
+const { managerUser, managerGroup, homeBase, socketDir, nodePath } = config
+const commonUser = config.commonUser ?? 'subcommon'
+const commonDir = config.commonDir ?? path.join(homeBase, commonUser)
+const names = allNames(config)
+
+async function run(cmd, args) {
+  try {
+    await execFile(cmd, args)
+  } catch (err) {
+    // surface stderr but let caller decide if it's fatal
+    throw new Error(`${cmd} ${args.join(' ')}: ${err.stderr?.trim() ?? err.message}`)
+  }
+}
+
+async function groupExists(group) {
+  try { await execFile('getent', ['group', group]); return true } catch { return false }
+}
+
+async function userExists(user) {
+  try { await execFile('id', [user]); return true } catch { return false }
+}
+
+async function userInGroup(user, group) {
+  try {
+    const { stdout } = await execFile('id', ['-Gn', user])
+    return stdout.trim().split(/\s+/).includes(group)
+  } catch { return false }
+}
+
+console.log('=== geniejars system setup ===\n')
+
+// 1. Create manager group
+if (await groupExists(managerGroup)) {
+  console.log(`group ${managerGroup}: already exists`)
+} else {
+  await run('groupadd', [managerGroup])
+  console.log(`group ${managerGroup}: created`)
+}
+
+// 2. Add manager user to manager group
+if (await userInGroup(managerUser, managerGroup)) {
+  console.log(`${managerUser} in ${managerGroup}: already set`)
+} else {
+  await run('usermod', ['-aG', managerGroup, managerUser])
+  console.log(`${managerUser} in ${managerGroup}: added`)
+}
+
+// 3. Create each geniejars
+for (const name of names) {
+  const home = path.join(homeBase, name)
+
+  // Create group for this geniejars
+  if (await groupExists(name)) {
+    console.log(`group ${name}: already exists`)
+  } else {
+    await run('groupadd', ['--system', name])
+    console.log(`group ${name}: created`)
+  }
+
+  // Create user
+  if (await userExists(name)) {
+    console.log(`user ${name}: already exists`)
+  } else {
+    await run('useradd', [
+      '--system',
+      '--create-home',
+      '--home-dir', home,
+      '--shell', '/usr/bin/nologin',
+      '--gid', name,
+      name,
+    ])
+    console.log(`user ${name}: created`)
+  }
+
+  // Add manager user to this geniejars's group (so manager can read/write home)
+  if (await userInGroup(managerUser, name)) {
+    console.log(`${managerUser} in group ${name}: already set`)
+  } else {
+    await run('usermod', ['-aG', name, managerUser])
+    console.log(`${managerUser} in group ${name}: added`)
+  }
+
+  // Set home dir: owned by geniejars:geniejars, setgid (2770)
+  await run('chown', [`${name}:${name}`, home])
+  await run('chmod', ['2770', home])
+  console.log(`${name} home permissions: set`)
+
+  // Default ACLs so manager-written files are accessible by geniejars and vice versa
+  await run('setfacl', ['-d', '-m', `u:${managerUser}:rwX`, home])
+  await run('setfacl', ['-d', '-m', `u:${name}:rwX`, home])
+  console.log(`${name} default ACLs: set`)
+
+  // Apply ACLs recursively to any files already in the home dir (e.g. created by system at useradd time)
+  await run('setfacl', ['-R', '-m', `u:${managerUser}:rwX`, home])
+  console.log(`${name} recursive ACLs: set`)
+}
+
+// 4. Create common user and shared directory
+//    commonDir is owned by the manager (write access) with group=subcommon (read access).
+//    All geniejars are added to the subcommon group so they can traverse and read it.
+
+if (await groupExists(commonUser)) {
+  console.log(`group ${commonUser}: already exists`)
+} else {
+  await run('groupadd', ['--system', commonUser])
+  console.log(`group ${commonUser}: created`)
+}
+
+if (await userExists(commonUser)) {
+  console.log(`user ${commonUser}: already exists`)
+} else {
+  await run('useradd', [
+    '--system',
+    '--create-home',
+    '--home-dir', commonDir,
+    '--shell', '/usr/bin/nologin',
+    '--gid', commonUser,
+    commonUser,
+  ])
+  console.log(`user ${commonUser}: created`)
+}
+
+// Manager owns commonDir so they can install tools freely.
+// subcommon group (sub* users) gets r-x only. Others get nothing.
+// setgid ensures new files/dirs created by manager inherit the subcommon group.
+// Default ACLs enforce correct permissions on new content automatically.
+await fs.mkdir(commonDir, { recursive: true })
+await run('chown', [`${managerUser}:${commonUser}`, commonDir])
+await run('chmod', ['2750', commonDir])
+await run('setfacl', ['-d', '-m', `u:${managerUser}:rwX`, commonDir])
+await run('setfacl', ['-d', '-m', `g:${commonUser}:rX`, commonDir])
+await run('setfacl', ['-d', '-m', 'o::---', commonDir])
+console.log(`${commonUser} home ${commonDir}: permissions set`)
+
+// Add manager to subcommon group so chgrp works without sudo after re-login.
+if (await userInGroup(managerUser, commonUser)) {
+  console.log(`${managerUser} in ${commonUser}: already set`)
+} else {
+  await run('usermod', ['-aG', commonUser, managerUser])
+  console.log(`${managerUser} in ${commonUser}: added`)
+}
+
+// Add each geniejars to the subcommon group so they can access commonDir.
+for (const name of names) {
+  if (await userInGroup(name, commonUser)) {
+    console.log(`${name} in ${commonUser}: already set`)
+  } else {
+    await run('usermod', ['-aG', commonUser, name])
+    console.log(`${name} in ${commonUser}: added`)
+  }
+}
+
+// 5. Write sudoers rule — restrict to running the agent script only
+const userList = names.join(', ')
+const sudoersEntry = [
+  '# geniejars agent — allows manager to start agents as geniejars',
+  `${managerUser} ALL = (${userList}) NOPASSWD: ${nodePath} ${agentScript} *`,
+  '',
+].join('\n')
+
+const sudoersFile = '/etc/sudoers.d/geniejars'
+await fs.writeFile(sudoersFile, sudoersEntry, { mode: 0o440 })
+console.log(`sudoers rule: written to ${sudoersFile}`)
+
+// 6. Create socket directory: sticky + world-writable (like /tmp) so each geniejars
+// can create their own socket. Socket files are 0660 owned by the geniejars, and the
+// manager is in each geniejars's group — so only the manager can connect to each socket.
+// Other geniejars cannot connect to each other's sockets (not in each other's groups).
+await fs.mkdir(socketDir, { recursive: true })
+await run('chown', ['root:root', socketDir])
+await run('chmod', ['1777', socketDir])
+console.log(`socket dir ${socketDir}: ready`)
+
+const tmpfilesConf = `/etc/tmpfiles.d/geniejars.conf`
+await fs.writeFile(tmpfilesConf, `d ${socketDir} 1777 root root -\n`)
+console.log(`tmpfiles.d: written to ${tmpfilesConf}`)
+
+console.log('\n=== setup complete ===')
+console.log(`\nIMPORTANT: group membership changes require a new login session to take effect.`)
+console.log(`Please log out and log back in, or run: su ${managerUser}`)
+console.log(`Note: 'su' is a temporary workaround — a full re-login is recommended.`)
+console.log(`After that, no more sudo or su required.`)
+console.log(`Then: geniejars sys up`)
+console.log(`\n🧙 GenieJars ready! Happy summoning your agents!`)

package/script/uninstall-geniejars.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// Uninstall — must be run as root (sudo geniejars uninstall)
+//
+// Removes all geniejars, groups, home dirs, sudoers rule, and tmp state.
+// Does NOT remove the manager user or the manager's own home directory.
+
+import { execFile as _execFile } from 'child_process'
+import { promisify } from 'util'
+import fs from 'fs/promises'
+import path from 'path'
+import { loadConfig, allNames } from '../src/pool.mjs'
+
+const execFile = promisify(_execFile)
+
+if (process.getuid() !== 0) {
+  console.error('Error: uninstall must be run as root. Use: sudo geniejars uninstall')
+  process.exit(1)
+}
+
+const config = await loadConfig()
+const { managerUser, managerGroup, homeBase, socketDir } = config
+const commonUser = config.commonUser ?? 'subcommon'
+const commonDir = config.commonDir ?? path.join(homeBase, commonUser)
+const names = allNames(config)
+
+async function run(cmd, args, { silent = false } = {}) {
+  try {
+    await execFile(cmd, args)
+  } catch (err) {
+    if (!silent) console.warn(`  warning: ${cmd} ${args.join(' ')}: ${err.stderr?.trim() ?? err.message}`)
+  }
+}
+
+async function userExists(user) {
+  try { await execFile('id', [user]); return true } catch { return false }
+}
+
+async function groupExists(group) {
+  try { await execFile('getent', ['group', group]); return true } catch { return false }
+}
+
+console.log('=== geniejars uninstall ===\n')
+
+// 1. Stop the shell server gracefully if running
+const pidFile = path.join(socketDir, 'server.pid')
+try {
+  const pid = parseInt(await fs.readFile(pidFile, 'utf8'), 10)
+  if (!isNaN(pid)) {
+    try { process.kill(pid, 'SIGTERM') } catch {}
+    // Wait up to 3s for it to exit
+    for (let i = 0; i < 15; i++) {
+      await new Promise(r => setTimeout(r, 200))
+      try { process.kill(pid, 0) } catch { break }
+    }
+    try { process.kill(pid, 'SIGKILL') } catch {}
+    console.log('shell server: stopped')
+  }
+} catch { console.log('shell server: not running') }
+
+// 2. Remove each geniejars and their home directory
+for (const name of names) {
+  const home = path.join(homeBase, name)
+  if (await userExists(name)) {
+    await run('userdel', [name])
+    console.log(`user ${name}: removed`)
+  } else {
+    console.log(`user ${name}: not found`)
+  }
+  await fs.rm(home, { recursive: true, force: true })
+  console.log(`home ${home}: removed`)
+  if (await groupExists(name)) {
+    await run('groupdel', [name])
+    console.log(`group ${name}: removed`)
+  }
+}
+
+// 3. Remove common user and directory
+if (await userExists(commonUser)) {
+  await run('userdel', [commonUser])
+  console.log(`user ${commonUser}: removed`)
+} else {
+  console.log(`user ${commonUser}: not found`)
+}
+await fs.rm(commonDir, { recursive: true, force: true })
+console.log(`commonDir ${commonDir}: removed`)
+if (await groupExists(commonUser)) {
+  await run('groupdel', [commonUser])
+  console.log(`group ${commonUser}: removed`)
+}
+
+// 4. Remove manager group
+if (await groupExists(managerGroup)) {
+  await run('groupdel', [managerGroup])
+  console.log(`group ${managerGroup}: removed`)
+} else {
+  console.log(`group ${managerGroup}: not found`)
+}
+
+// 5. Remove sudoers rule
+await fs.unlink('/etc/sudoers.d/geniejars').catch(() => {})
+console.log('sudoers rule: removed')
+
+// 6. Remove tmpfiles.d config
+await fs.unlink('/etc/tmpfiles.d/geniejars.conf').catch(() => {})
+console.log('tmpfiles.d config: removed')
+
+// 7. Clean up /tmp state
+const toRemove = [
+  socketDir,
+  config.stateFile,
+  config.lockFile,
+  config.logDir,
+]
+for (const p of toRemove) {
+  if (!p) continue
+  await fs.rm(p, { recursive: true, force: true })
+  console.log(`${p}: removed`)
+}
+
+console.log('\n=== uninstall complete ===')
+console.log(`\nNOTE: ${managerUser} may still have residual group memberships in this session.`)
+console.log(`Run:  su - ${managerUser}   to get a clean login.`)

package/src/agent.mjs

@@ -0,0 +1,194 @@
+// Geniejars agent — runs as the geniejars, listens on a Unix socket.
+// Started at boot via systemd with an absolute path to node:
+//   /usr/bin/node /path/to/src/agent.mjs <geniejars-name>
+//
+// Handles requests from the manager over a newline-delimited JSON protocol:
+//   run    — execute a command, stream stdout/stderr, report exit
+//   start  — start the one long-running main process, stream output
+//   stop   — kill the main process
+//   status — report whether main process is running
+
+import net from 'net'
+import { spawn } from 'child_process'
+import fs from 'fs/promises'
+import path from 'path'
+import { loadConfig } from './pool.mjs'
+
+const name = process.argv[2]
+if (!name) {
+  console.error('Usage: agent <geniejars-name>')
+  process.exit(1)
+}
+
+const config = await loadConfig()
+const sockPath = path.join(config.socketDir, `${name}.sock`)
+
+await fs.mkdir(config.socketDir, { recursive: true })
+await fs.unlink(sockPath).catch(() => {})
+
+let mainProc = null  // the one long-running process
+
+// --- Idle timeout ---
+const idleTimeoutMs = (config.agentIdleTimeout ?? 300) * 1000
+let idleTimer = null
+
+function scheduleIdleShutdown() {
+  if (idleTimeoutMs === 0 || mainProc) return
+  if (idleTimer) clearTimeout(idleTimer)
+  idleTimer = setTimeout(async () => {
+    if (mainProc) return  // became busy — skip
+    server.close()
+    await fs.unlink(sockPath).catch(() => {})
+    process.exit(0)
+  }, idleTimeoutMs)
+}
+
+function resetIdleTimer() {
+  if (idleTimer) { clearTimeout(idleTimer); idleTimer = null }
+  scheduleIdleShutdown()
+}
+
+function send(socket, obj) {
+  if (!socket.destroyed) socket.write(JSON.stringify(obj) + '\n')
+}
+
+function handleConnection(socket) {
+  let buf = ''
+
+  socket.on('data', chunk => {
+    buf += chunk.toString()
+    let nl
+    while ((nl = buf.indexOf('\n')) !== -1) {
+      const line = buf.slice(0, nl).trim()
+      buf = buf.slice(nl + 1)
+      if (!line) continue
+      let req
+      try { req = JSON.parse(line) } catch {
+        send(socket, { type: 'error', message: 'Invalid JSON' })
+        socket.destroy()
+        return
+      }
+      handleRequest(req, socket)
+    }
+  })
+
+  socket.on('error', () => {})
+}
+
+function handleRequest(req, socket) {
+  switch (req.type) {
+
+    case 'run': {
+      resetIdleTimer()
+      let child
+      try {
+        child = spawn(req.cmd, req.args ?? [], {
+          cwd: req.cwd ?? process.env.HOME,
+          env: { ...process.env, ...(req.env ?? {}) },
+          stdio: ['ignore', 'pipe', 'pipe'],
+        })
+      } catch (err) {
+        send(socket, { type: 'error', message: err.message })
+        socket.end()
+        return
+      }
+      child.stdout.on('data', d => send(socket, { type: 'stdout', data: d.toString() }))
+      child.stderr.on('data', d => send(socket, { type: 'stderr', data: d.toString() }))
+      child.on('error', err => { send(socket, { type: 'error', message: err.message }); socket.end() })
+      child.on('close', code => { send(socket, { type: 'exit', code: code ?? 1 }); socket.end(); resetIdleTimer() })
+      break
+    }
+
+    case 'start': {
+      if (mainProc) {
+        send(socket, { type: 'error', message: 'Process already running' })
+        socket.end()
+        return
+      }
+      resetIdleTimer()
+      let child
+      try {
+        child = spawn(req.cmd, req.args ?? [], {
+          cwd: req.cwd ?? process.env.HOME,
+          env: { ...process.env, ...(req.env ?? {}) },
+          stdio: ['ignore', 'pipe', 'pipe'],
+        })
+      } catch (err) {
+        send(socket, { type: 'error', message: err.message })
+        socket.end()
+        return
+      }
+      mainProc = child
+      send(socket, { type: 'started', pid: child.pid })
+
+      child.stdout.on('data', d => send(socket, { type: 'stdout', data: d.toString() }))
+      child.stderr.on('data', d => send(socket, { type: 'stderr', data: d.toString() }))
+      child.on('error', err => {
+        send(socket, { type: 'error', message: err.message })
+        mainProc = null
+        resetIdleTimer()
+        socket.end()
+      })
+      child.on('close', code => {
+        send(socket, { type: 'exit', code: code ?? 1 })
+        mainProc = null
+        resetIdleTimer()
+        socket.end()
+      })
+
+      // If manager disconnects, process keeps running — detach listeners
+      socket.on('close', () => {
+        if (mainProc) {
+          mainProc.stdout.removeAllListeners('data')
+          mainProc.stderr.removeAllListeners('data')
+        }
+      })
+      break
+    }
+
+    case 'stop': {
+      if (!mainProc) {
+        send(socket, { type: 'error', message: 'No process running' })
+      } else {
+        mainProc.kill('SIGTERM')
+        send(socket, { type: 'stopped' })
+      }
+      socket.end()
+      break
+    }
+
+    case 'status': {
+      send(socket, { type: 'status', running: mainProc !== null, pid: mainProc?.pid ?? null })
+      socket.end()
+      break
+    }
+
+    default: {
+      send(socket, { type: 'error', message: `Unknown request type: ${req.type}` })
+      socket.end()
+    }
+  }
+}
+
+const server = net.createServer(handleConnection)
+
+server.listen(sockPath, async () => {
+  // Override any setgid inheritance from the directory — socket must be owned by
+  // this process's own uid:gid so the manager (in the geniejars's group) can connect.
+  await fs.chown(sockPath, process.getuid(), process.getgid())
+  await fs.chmod(sockPath, 0o660)
+  console.log(`[geniejars-agent] ${name} listening on ${sockPath}`)
+  scheduleIdleShutdown()
+})
+
+server.on('error', err => {
+  console.error('[geniejars-agent] Error:', err.message)
+  process.exit(1)
+})
+
+process.on('SIGTERM', async () => {
+  if (mainProc) mainProc.kill('SIGTERM')
+  server.close()
+  await fs.unlink(sockPath).catch(() => {})
+  process.exit(0)
+})

package/src/allocate.mjs

@@ -0,0 +1,96 @@
+import fs from 'fs/promises'
+import path from 'path'
+import { execFile } from 'child_process'
+import { promisify } from 'util'
+import { acquireLock, readState, writeState, freeNames, homeDir } from './pool.mjs'
+
+const execFileAsync = promisify(execFile)
+
+// Allocate a free geniejars. Returns the geniejars name.
+// Options:
+//   backup: boolean (default false) - tar home before clearing
+//   clear:  boolean (default true)  - clear home dir contents
+//   tag:    string  (default null)  - label stored in state
+export async function allocate(config, options = {}) {
+  const { backup = false, clear = true, tag = null } = options
+
+  const release = await acquireLock(config)
+  try {
+    const state = await readState(config)
+    const free = freeNames(state)
+    if (free.length === 0) {
+      const total = Object.keys(state.pool).length
+      throw new Error(`No free geniejars available (pool size: ${total})`)
+    }
+
+    const name = free[0]
+
+    if (backup) await backupHome(config, name)
+    if (clear) await clearHome(config, name)
+
+    // Allocate ports
+    const freePorts = Object.entries(state.ports)
+      .filter(([, v]) => v === 'free')
+      .map(([k]) => Number(k))
+      .sort((a, b) => a - b)
+    if (freePorts.length < config.portsPerGeniejars) {
+      throw new Error(`Not enough free ports (need ${config.portsPerGeniejars}, have ${freePorts.length})`)
+    }
+    const assignedPorts = freePorts.slice(0, config.portsPerGeniejars)
+    for (const port of assignedPorts) state.ports[port] = name
+
+    state.pool[name] = {
+      status: 'occupied',
+      allocatedAt: new Date().toISOString(),
+      allocatedBy: config.managerUser,
+      tag: tag ?? null,
+      ports: assignedPorts,
+      prepared: null,
+    }
+    await writeState(config, state)
+    return name
+  } finally {
+    await release()
+  }
+}
+
+// Release a geniejars back to the free pool.
+export async function deallocate(config, name) {
+  const release = await acquireLock(config)
+  try {
+    const state = await readState(config)
+    if (!(name in state.pool)) {
+      throw new Error(`Unknown geniejars: ${name}`)
+    }
+    if (state.pool[name].status !== 'occupied') {
+      throw new Error(`Geniejars ${name} is not currently occupied`)
+    }
+    // Free ports
+    const ports = state.pool[name].ports ?? []
+    for (const port of ports) state.ports[port] = 'free'
+
+    state.pool[name] = { status: 'free', allocatedAt: null, allocatedBy: null, tag: null, ports: null, prepared: null }
+    await writeState(config, state)
+  } finally {
+    await release()
+  }
+}
+
+// Remove all contents inside a geniejars's home dir (not the dir itself).
+// Runs as the manager directly — manager has group write access via default ACLs.
+export async function clearHome(config, name) {
+  const home = homeDir(config, name)
+  const entries = await fs.readdir(home).catch(() => [])
+  await Promise.all(entries.map(e => fs.rm(path.join(home, e), { recursive: true, force: true })))
+}
+
+// Create a tar.gz snapshot of the geniejars's home into backupDir.
+// Returns the path to the archive.
+export async function backupHome(config, name) {
+  const home = homeDir(config, name)
+  await fs.mkdir(config.backupDir, { recursive: true })
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const archive = path.join(config.backupDir, `${name}-${timestamp}.tar.gz`)
+  await execFileAsync('tar', ['-czf', archive, '-C', path.dirname(home), path.basename(home)])
+  return archive
+}

package/src/index.mjs

@@ -0,0 +1,5 @@
+export { loadConfig, poolName, allNames, homeDir, freeNames, occupiedNames, readState, writeState, initialState, resolveName, acquireLock } from './pool.mjs'
+export { allocate, deallocate, clearHome, backupHome } from './allocate.mjs'
+export { parseJFile, readJFile, applyJFile, prepare } from './prepare.mjs'
+export { runAs, runShellAs, startAs, stopProcess, agentStatus, logFilePath, ensureAgent } from './run.mjs'
+export { normalize, applyAcl } from './normalize.mjs'

package/src/normalize.mjs

@@ -0,0 +1,26 @@
+import { execFile } from 'child_process'
+import { promisify } from 'util'
+import { homeDir } from './pool.mjs'
+
+const execFileAsync = promisify(execFile)
+
+// Re-apply ACLs to all manager-owned files in a geniejars's home.
+// Grants the geniejars rw(X) on any file currently owned by the manager.
+// Runs without sudo because the manager is in the geniejars's group (set up in Phase 1).
+export async function normalize(config, name) {
+  const home = homeDir(config, name)
+  const manager = config.managerUser
+  const aclEntry = `u:${name}:rwX`
+
+  // find all files/dirs owned by the manager, then setfacl on them in batch
+  await execFileAsync('find', [
+    home,
+    '-user', manager,
+    '-exec', 'setfacl', '-m', aclEntry, '{}', '+'
+  ])
+}
+
+// Apply a single ACL entry to a specific path.
+export async function applyAcl(config, name, filePath) {
+  await execFileAsync('setfacl', ['-m', `u:${name}:rwX`, filePath])
+}