Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

31.0 KB
Raw Blame
import {
  access,
  chmod,
  chown,
  lstat,
  mkdir,
  readdir,
  readFile,
  rm,
  stat,
  writeFile,
} from 'node:fs/promises';
import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
import { z } from 'zod';
import { ConfigurationError } from './errors';
import { defaultDataDir } from './paths';
import { CURRENT, pointCurrent, readCurrent } from './releases';
import { CommandFailure, type CommandRunner } from './secrets';
import { installPrefix, isNewer } from './update';

/**
 * Running every agent as a Linux user of its own.
 *
 * Root sets it up once (`sudo switch-agent-controller install-service
 * --separate-users`): a pool of system users for one controller's agents, all
 * in a group of their own that the controller also gets; a systemd template
 * unit that runs an agent as one of them; a polkit rule that lets the
 * controller's user start, stop and restart those units and nothing else; and
 * the controller itself as a system service of that user. After that the
 * controller needs no root: each agent it is given claims a free user from the
 * pool, and runs as `switch-agent-<uid>@<NN>.service`, seeing only its own
 * directory.
 *
 * Everything is named after the controller user's uid, so several controllers
 * on one machine each get their own.
 */

export const SEPARATE_USERS_CONFIG_DIR = '/etc/switch-agent-controller';
const SYSTEMD_SYSTEM_DIR = '/etc/systemd/system';
const POLKIT_RULES_DIR = '/etc/polkit-1/rules.d';
const AGENTS_PARENT = '/var/lib/switch-agents';
const RELEASES_PARENT = '/var/lib';
export const MAX_AGENT_USERS = 99;
export const DEFAULT_AGENT_USERS = 16;
/** Where agents cannot reach, so nothing an agent runs may live there. */
const HOME_ROOTS = ['/home', '/root', '/run/user'];

const absolutePath = z.string().refine((value) => isAbsolute(value) && isUnitSafe(value), {
  message: 'must be an absolute path of letters, digits and ._/@+-',
});

export const separateUsersConfigSchema = z.strictObject({
  v: z.literal(1),
  user: z.string().regex(/^[a-z_][a-z0-9_.-]*\$?$/i),
  uid: z.number().int().positive(),
  gid: z.number().int().positive(),
  dataDir: absolutePath,
  agentsDir: absolutePath,
  agentUsers: z.number().int().min(1).max(MAX_AGENT_USERS),
  node: absolutePath,
  bundle: absolutePath,
  /**
   * The releases directory the controller installs the releases Switch names
   * into (`releases.ts`); null for a setup made before there was one, or from
   * a controller that is not an npm install.
   */
  releasesDir: absolutePath.nullable().default(null),
});
export type SeparateUsersConfig = z.infer<typeof separateUsersConfigSchema>;

/** The names one controller's agents run under, all derived from its user's uid. */
export function separateUserNames(uid: number) {
  return {
    group: `switch-agents-${uid}`,
    controllerUnit: `switch-agent-controller-${uid}.service`,
    agentTemplate: `switch-agent-${uid}@.service`,
    agentUnitPattern: `switch-agent-${uid}@*.service`,
    polkitRule: join(POLKIT_RULES_DIR, `50-switch-agent-controller-${uid}.rules`),
    config: separateUsersConfigPath(uid),
    agentUnit: (slot: number) => `switch-agent-${uid}@${slotName(slot)}.service`,
    agentUser: (slot: number) => `sa${uid}-${slotName(slot)}`,
  };
}

export function separateUsersConfigPath(uid: number): string {
  return join(SEPARATE_USERS_CONFIG_DIR, `separate-users-${uid}.json`);
}

/** `1` → `01`: the instance name of an agent's unit, and the suffix of its user. */
export function slotName(slot: number): string {
  if (!Number.isInteger(slot) || slot < 1 || slot > MAX_AGENT_USERS)
    throw new Error(`Agent user ${slot} is not one of 1–${MAX_AGENT_USERS}.`);
  return String(slot).padStart(2, '0');
}

/** Where agents' directories are when setup names none. */
export function defaultAgentsDir(uid: number): string {
  return join(AGENTS_PARENT, String(uid));
}

/** Where the controller's releases are when setup names no other place. */
export function defaultReleasesDir(uid: number): string {
  return join(RELEASES_PARENT, `switch-agent-controller-${uid}`, 'releases');
}

/** Where the directory of the agent agent user `slot` runs is, on the machine. */
export function agentRoot(config: SeparateUsersConfig, slot: number): string {
  return join(config.agentsDir, slotName(slot));
}

/**
 * Where an agent sees its own directory, whichever agent user it runs as: the
 * same path for every agent, each in its own mount namespace, so the paths
 * an agent records (its sessions' working directory, its provider's state)
 * stay valid when it later runs as another user.
 */
export function unitAgentRoot(config: SeparateUsersConfig): string {
  return join(config.agentsDir, 'agent');
}

/** Where the controller keeps what agent user `slot`'s unit loads: its relay credentials and environment. */
export function unitFilesDir(config: SeparateUsersConfig, slot: number): string {
  return join(config.dataDir, 'units', slotName(slot));
}

/** The path a unit's process reads its relay credentials from, as systemd hands them over. */
export function unitCredentialsPath(config: SeparateUsersConfig, slot: number): string {
  return join('/run/credentials', separateUserNames(config.uid).agentUnit(slot), 'relay');
}

/** The home directory `path` is under, where agents cannot reach; null when it is under none. */
export function homeRootOf(path: string, homes: string[]): string | null {
  for (const home of [...HOME_ROOTS, ...homes])
    if (path === home || isWithin(home, path)) return home;
  return null;
}

/** Characters a path may hold to be written into a unit file as is (no quoting, no `%`). */
function isUnitSafe(value: string): boolean {
  return /^[A-Za-z0-9._/@+-]+$/.test(value);
}

function isWithin(root: string, path: string): boolean {
  const rest = relative(resolve(root), resolve(path));
  return rest !== '' && rest !== '..' && !rest.startsWith(`..${sep}`) && !isAbsolute(rest);
}

/**
 * The template unit an agent runs as: one of the pool's users, in the
 * controller's agents' group, with only its own directory to see and write
 * (at `unitAgentRoot`),
 * no access to the controller's data, the home directories or the cloud
 * instance metadata, and systemd restarting it after a crash.
 *
 * Before it starts, root hands it back anything in its directory owned by
 * another agent user (its directory moves to whichever user it is given):
 * only files in the agents' group, never through a link, and never what the
 * controller wrote. Nothing of the agent runs then: its unit is stopped, so
 * nothing can swap a path mid-walk. A file outside the agents' group is never
 * touched, so not even a controller that pointed an agent's directory
 * elsewhere could have root hand it a file it does not already share.
 */
export function agentUnitTemplate(
  config: SeparateUsersConfig,
  tools: { sh: string; find: string; chown: string; path: string }
): string {
  const names = separateUserNames(config.uid);
  const onMachine = `${config.agentsDir}/%i`;
  const root = unitAgentRoot(config);
  const user = `sa${config.uid}-%i`;
  return [
    '# Written by switch-agent-controller install-service --separate-users;',
    '# run that again rather than editing this file.',
    '[Unit]',
    `Description=Switch agent %i of the agent controller run by ${config.user}`,
    'StartLimitIntervalSec=600',
    'StartLimitBurst=5',
    '',
    '[Service]',
    'Type=simple',
    `User=${user}`,
    `Group=${names.group}`,
    'UMask=0007',
    'Environment=SWITCH_HOST_SHARED_GROUP=1',
    `Environment=HOME=${root}/home`,
    `Environment=PATH=${tools.path}`,
    `EnvironmentFile=-${config.dataDir}/units/%i/environment`,
    `LoadCredential=relay:${config.dataDir}/units/%i/relay.json`,
    `WorkingDirectory=${root}`,
    // Some systemd versions run a `+` command inside the unit's mount
    // namespace, where the directory is at `root`; others outside it.
    `ExecStartPre=+${tools.sh} -c 'dir=${root}; [ -d "$$dir" ] || dir=${onMachine}; exec ${tools.find} "$$dir" -xdev -mindepth 1 -group ${names.group} ! -user ${user} ! -user ${config.uid} -exec ${tools.chown} --no-dereference ${user} {} +'`,
    `ExecStart=${config.node} ${config.bundle} ${root}/watcher ${root}/watcher/config.json --watch-worker`,
    'StandardInput=null',
    'StandardOutput=journal',
    'StandardError=journal',
    'Restart=on-failure',
    'RestartSec=3',
    `TemporaryFileSystem=${config.agentsDir}:ro`,
    `BindPaths=${onMachine}:${root}`,
    `InaccessiblePaths=-${config.dataDir}`,
    'ProtectSystem=strict',
    'ProtectHome=yes',
    'PrivateTmp=yes',
    'PrivateDevices=yes',
    'NoNewPrivileges=yes',
    'CapabilityBoundingSet=',
    'AmbientCapabilities=',
    'ProtectProc=invisible',
    'ProtectKernelTunables=yes',
    'ProtectKernelModules=yes',
    'ProtectKernelLogs=yes',
    'ProtectControlGroups=yes',
    'ProtectClock=yes',
    'ProtectHostname=yes',
    'RestrictRealtime=yes',
    'RestrictSUIDSGID=yes',
    'LockPersonality=yes',
    'RemoveIPC=yes',
    'RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK',
    'IPAddressDeny=169.254.169.254/32 fd00:ec2::254/128',
    '',
  ].join('\n');
}

/** The polkit rule: the controller's user may start, stop, restart and reset its agents' units, and nothing else. */
export function polkitRule(config: SeparateUsersConfig): string {
  return `// Written by switch-agent-controller install-service --separate-users.
// ${config.user} may start, stop, restart and reset its agents' units, and
// nothing else. Every other request falls through to the defaults.
polkit.addRule(function (action, subject) {
  if (action.id !== "org.freedesktop.systemd1.manage-units" || subject.user !== ${JSON.stringify(config.user)}) return;
  var unit = action.lookup("unit"), verb = action.lookup("verb");
  if (/^switch-agent-${config.uid}@[0-9]{2}\\.service$/.test(unit) &&
      ["start", "stop", "restart", "reset-failed"].indexOf(verb) >= 0) return polkit.Result.YES;
});
`;
}

/**
 * The controller as a system service of its user, with the agents' group as a
 * supplementary group, so it can read what its agents write. Restarted on exit
 * codes 1 and 7 (restarting into an update), as the user service is.
 */
export function controllerSystemUnit(
  config: SeparateUsersConfig,
  run: { cli: string; envFile: string | null; path: string }
): string {
  const quote = (value: string) => `"${value.replace(/(["\\])/g, '\\$1').replace(/%/g, '%%')}"`;
  const args = [
    config.node,
    run.cli,
    'run',
    '--data-dir',
    config.dataDir,
    '--agent-runtime',
    'separate-user',
    '--shared-host-bundle',
    config.bundle,
    ...(run.envFile ? ['--env-file', run.envFile] : []),
  ];
  return [
    '# Written by switch-agent-controller install-service --separate-users;',
    '# run that again rather than editing this file.',
    '[Unit]',
    `Description=Switch agent controller run by ${config.user}, each agent as a user of its own`,
    'After=network-online.target',
    'Wants=network-online.target',
    '',
    '[Service]',
    `User=${config.user}`,
    `SupplementaryGroups=${separateUserNames(config.uid).group}`,
    `ExecStart=${args.map(quote).join(' ')}`,
    `Environment=${quote(`PATH=${run.path}`)}`,
    'Restart=on-failure',
    'RestartSec=5',
    'RestartPreventExitStatus=2 3 4 5 6',
    '',
    '[Install]',
    'WantedBy=multi-user.target',
    '',
  ].join('\n');
}

/** `PATH` without the entries agents cannot reach. */
export function agentPath(path: string, homes: string[]): string {
  const kept = path
    .split(delimiter)
    .filter((entry) => isAbsolute(entry) && isUnitSafe(entry) && !homeRootOf(entry, homes));
  return [...new Set(kept)].join(delimiter) || '/usr/local/bin:/usr/bin:/bin';
}

/** One line of `getent passwd`. */
export type PasswdEntry = { name: string; uid: number; gid: number; home: string };

export function parsePasswd(line: string): PasswdEntry {
  const fields = line.trim().split(':');
  if (fields.length < 7) throw new Error(`Not a passwd entry: ${line.trim()}`);
  return {
    name: fields[0]!,
    uid: Number(fields[2]),
    gid: Number(fields[3]),
    home: fields[5]!,
  };
}

/** The setup made for the controller user `uid`, or null when there is none. */
async function readSetup(uid: number): Promise<SeparateUsersConfig | null> {
  const path = separateUsersConfigPath(uid);
  let text: string;
  try {
    text = await readFile(path, 'utf8');
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
    throw new ConfigurationError(`${path} cannot be read: ${(error as Error).message}`);
  }
  const parsed = separateUsersConfigSchema.safeParse(JSON.parse(text));
  if (!parsed.success)
    throw new ConfigurationError(
      `${path} is not a setup this controller can read (${parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ')}). Run the setup again.`
    );
  if (parsed.data.uid !== uid)
    throw new ConfigurationError(`${path} was set up for uid ${parsed.data.uid}, not ${uid}.`);
  return parsed.data;
}

/**
 * The setup for the controller running as `uid` on `dataDir`, or null when
 * agents are not set up to run as users of their own for it.
 */
export async function findSeparateUsersConfig(
  uid: number,
  dataDir: string
): Promise<SeparateUsersConfig | null> {
  const config = await readSetup(uid);
  return config && resolve(config.dataDir) === resolve(dataDir) ? config : null;
}

/** The setup for the controller running as `uid` on `dataDir`; a missing or different one is a configuration error. */
export async function loadSeparateUsersConfig(
  uid: number,
  dataDir: string
): Promise<SeparateUsersConfig> {
  const config = await readSetup(uid);
  const path = separateUsersConfigPath(uid);
  if (!config)
    throw new ConfigurationError(
      `Agents cannot run as users of their own here: ${path} does not exist. Set it up once as root: sudo switch-agent-controller install-service --separate-users --data-dir ${dataDir}`
    );
  if (resolve(config.dataDir) !== resolve(dataDir))
    throw new ConfigurationError(
      `${path} was set up for the data directory ${config.dataDir}, not ${dataDir}. Run the setup again with --data-dir ${dataDir}.`
    );
  return config;
}

/** What the agents' group and unit need from the running controller process. */
export function assertControllerCanRunSeparateUsers(config: SeparateUsersConfig): void {
  if (!process.getgroups?.().includes(config.gid))
    throw new ConfigurationError(
      `This controller is not in the agents' group ${separateUserNames(config.uid).group}, so it cannot read what its agents write. Run it as the service the setup installed: sudo systemctl start ${separateUserNames(config.uid).controllerUnit}`
    );
}

export type SetupInput = {
  user: string;
  /** The controller's data directory; the user's default one when null. */
  dataDir: string | null;
  agentsDir: string | null;
  agentUsers: number;
  node: string;
  cli: string;
  bundle: string;
  /** The version of the controller running the setup, which `cli` is. */
  version: string;
  /** Where the controller's releases go; `defaultReleasesDir` when null. */
  releasesDir: string | null;
  envFile: string | null;
  path: string;
  /**
   * Queue the controller's restart rather than wait for it: for a caller the
   * controller's unit is ordered after, such as a machine's boot service.
   */
  noBlock: boolean;
};

export type SetupReport = { notes: string[] };

/**
 * Sets everything up as root, and starts the controller as a system service.
 * Run again, it rewrites the files from what it is given and adds agent users
 * up to `agentUsers`; it never removes one.
 */
export async function installSeparateUsers(
  input: SetupInput,
  run: CommandRunner
): Promise<SetupReport> {
  await assertSetupHost();
  run = onSystemPath(run);
  const account = parsePasswd((await run('getent', ['passwd', input.user], null)).stdout);
  if (account.uid === 0)
    throw new ConfigurationError('The controller must run as a user other than root.');
  const homes = [account.home];
  const names = separateUserNames(account.uid);
  for (const [what, path] of [
    ['Node', input.node],
    ['The controller', input.cli],
    ['The shared-host bundle', input.bundle],
  ] as const) {
    const home = homeRootOf(path, homes);
    if (home)
      throw new ConfigurationError(
        `${what} is at ${path}, under ${home}, which agents running as users of their own cannot reach. Install Node and the controller system-wide (sudo npm install --global <the release's .tgz URL>) and run the setup again.`
      );
    if (!isUnitSafe(path))
      throw new ConfigurationError(
        `${what} is at ${path}; a path in a unit file must hold only letters, digits and ._/@+-.`
      );
  }
  if (input.envFile && !isAbsolute(input.envFile))
    throw new ConfigurationError(`--env-file must be an absolute path, not ${input.envFile}.`);
  const dataDir = resolve(
    input.dataDir ?? defaultDataDir({ platform: process.platform, env: {}, home: account.home })
  );
  await assertEnrolled(dataDir, account);
  await assertNoUserService(dataDir, account);

  const group = await ensureGroup(names.group, run);
  const agentsDir = input.agentsDir ?? defaultAgentsDir(account.uid);
  if (homeRootOf(agentsDir, homes))
    throw new ConfigurationError(
      `--agents-dir ${agentsDir} is under a home directory, which agents cannot reach.`
    );
  const releases = planReleases({
    cli: input.cli,
    bundle: input.bundle,
    releasesDir: input.releasesDir,
    uid: account.uid,
    dataDir,
    agentsDir: resolve(agentsDir),
    homes,
  });
  const config = separateUsersConfigSchema.parse({
    v: 1,
    user: account.name,
    uid: account.uid,
    gid: group,
    dataDir,
    agentsDir: resolve(agentsDir),
    agentUsers: input.agentUsers,
    node: input.node,
    bundle: releases?.bundle ?? input.bundle,
    releasesDir: releases?.dir ?? null,
  } satisfies SeparateUsersConfig);
  for (let slot = 1; slot <= config.agentUsers; slot++)
    await ensureAgentUser(names.agentUser(slot), names.group, run);

  await mkdir(dirname(config.agentsDir), { recursive: true, mode: 0o755 });
  await mkdir(config.agentsDir, { recursive: true, mode: 0o700 });
  await chown(config.agentsDir, account.uid, account.gid);
  await chmod(config.agentsDir, 0o700);
  const releasesNote = releases
    ? await ensureReleases({
        releasesDir: releases.dir,
        prefix: releases.prefix,
        version: input.version,
        owner: { uid: account.uid, gid: account.gid },
      })
    : 'The controller does not run from an npm install, so it cannot install the releases Switch names for itself.';

  const tools = {
    sh: await which('sh', SYSTEM_PATH),
    find: await which('find', SYSTEM_PATH),
    chown: await which('chown', SYSTEM_PATH),
    path: agentPath(input.path, homes),
  };
  await mkdir(SEPARATE_USERS_CONFIG_DIR, { recursive: true, mode: 0o755 });
  await writeFile(names.config, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o644 });
  await writeFile(join(SYSTEMD_SYSTEM_DIR, names.agentTemplate), agentUnitTemplate(config, tools), {
    mode: 0o644,
  });
  await writeFile(names.polkitRule, polkitRule(config), { mode: 0o644 });
  await writeFile(
    join(SYSTEMD_SYSTEM_DIR, names.controllerUnit),
    controllerSystemUnit(config, {
      cli: releases?.cli ?? input.cli,
      envFile: input.envFile,
      path: input.path,
    }),
    { mode: 0o644 }
  );
  await run('systemctl', ['daemon-reload'], null);
  await run('systemctl', ['enable', names.controllerUnit], null);
  await run(
    'systemctl',
    input.noBlock
      ? ['restart', '--no-block', names.controllerUnit]
      : ['restart', names.controllerUnit],
    null
  );
  return {
    notes: [
      `${config.agentUsers} agent users (${names.agentUser(1)}…), in the group ${names.group}.`,
      `Agents' directories: ${config.agentsDir}`,
      `Each agent runs as ${names.agentUnitPattern}; its log: journalctl -u ${names.agentUnit(1)}`,
      `The controller runs as ${names.controllerUnit}; its log: journalctl -u ${names.controllerUnit} -f`,
      releasesNote,
      'Agents see only their own directory: a definition naming a directory elsewhere is refused.',
      "Agents do not see this user's provider logins: give each provider an API key or token in --env-file.",
    ],
  };
}

/** Where the controller's units run it and its bundle from, through `<releases>/current`. */
export type ReleasesPlan = {
  dir: string;
  /** The npm prefix the controller running the setup was installed in. */
  prefix: string;
  cli: string;
  bundle: string;
};

/**
 * The releases directory for a setup run by the controller at `cli`, and the
 * paths of the CLI and the shared-host bundle through its `current` link; null
 * when that controller is not an npm install (a checkout), which cannot have
 * one. The directory must be where agents can read it and the controller
 * alone writes: not under a home, the data directory or the agents'
 * directories, which agents cannot reach.
 */
export function planReleases(input: {
  cli: string;
  bundle: string;
  releasesDir: string | null;
  uid: number;
  dataDir: string;
  agentsDir: string;
  homes: string[];
}): ReleasesPlan | null {
  const prefix = installPrefix(input.cli);
  if (!prefix) {
    if (input.releasesDir)
      throw new ConfigurationError(
        `--releases-dir needs the controller installed with npm (sudo npm install --global <the release's .tgz URL>), not run from ${input.cli}.`
      );
    return null;
  }
  const dir = resolve(input.releasesDir ?? defaultReleasesDir(input.uid));
  if (!isUnitSafe(dir))
    throw new ConfigurationError(
      `--releases-dir ${dir}: a path in a unit file must hold only letters, digits and ._/@+-.`
    );
  const home = homeRootOf(dir, input.homes);
  if (home)
    throw new ConfigurationError(
      `--releases-dir ${dir} is under ${home}, which agents running as users of their own cannot reach.`
    );
  for (const [what, root] of [
    ['the data directory', input.dataDir],
    ["the agents' directories", input.agentsDir],
  ] as const)
    if (dir === resolve(root) || isWithin(root, dir) || isWithin(dir, root))
      throw new ConfigurationError(
        `--releases-dir ${dir} overlaps ${what} (${root}), which agents cannot read; name a directory of its own.`
      );
  const current = join(dir, CURRENT);
  return {
    dir,
    prefix,
    cli: join(current, relative(prefix, input.cli)),
    bundle: isWithin(prefix, input.bundle)
      ? join(current, relative(prefix, input.bundle))
      : input.bundle,
  };
}

/**
 * Makes the releases directory (0755, the controller's), and points its
 * `current` link at `prefix`, the release running the setup, only when the
 * link is missing, names no readable release, or names one older than
 * `version`: a machine whose boot runs the setup with the release its image
 * carries keeps an update applied since, and a newer image still wins.
 */
export async function ensureReleases(input: {
  releasesDir: string;
  prefix: string;
  version: string;
  owner: { uid: number; gid: number } | null;
}): Promise<string> {
  const { releasesDir } = input;
  await mkdir(dirname(releasesDir), { recursive: true, mode: 0o755 });
  try {
    const found = await lstat(releasesDir);
    if (!found.isDirectory() || found.isSymbolicLink())
      throw new ConfigurationError(`${releasesDir} is not a directory; move it aside.`);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
    await mkdir(releasesDir, { mode: 0o755 });
  }
  if (input.owner) await chown(releasesDir, input.owner.uid, input.owner.gid);
  await chmod(releasesDir, 0o755);
  const current = await readCurrent(releasesDir);
  if (current.kind === 'not_a_link')
    throw new ConfigurationError(
      `${join(releasesDir, CURRENT)} is not a link; move it aside and run the setup again.`
    );
  if (
    current.kind === 'link' &&
    current.version !== null &&
    !isNewer(input.version, current.version)
  )
    return `The controller runs ${current.version} from ${current.target}, through ${join(releasesDir, CURRENT)}; it installs the releases Switch names there.`;
  await pointCurrent(releasesDir, input.prefix, input.owner);
  return `The controller runs ${input.version} from ${input.prefix}, through ${join(releasesDir, CURRENT)}; it installs the releases Switch names there.`;
}

/**
 * Stops the controller and every agent unit, and removes the units, the rule,
 * the setup, the agent users and their group. The agents' directories are
 * kept, and said so.
 */
export async function uninstallSeparateUsers(
  user: string,
  run: CommandRunner
): Promise<SetupReport> {
  assertRoot();
  run = onSystemPath(run);
  const account = parsePasswd((await run('getent', ['passwd', user], null)).stdout);
  const names = separateUserNames(account.uid);
  let agentsDir: string | null = null;
  let releasesDir: string | null = null;
  let agentUsers = MAX_AGENT_USERS;
  try {
    const config = separateUsersConfigSchema.parse(
      JSON.parse(await readFile(names.config, 'utf8'))
    );
    agentsDir = config.agentsDir;
    releasesDir = config.releasesDir;
    agentUsers = config.agentUsers;
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
  }
  await run('systemctl', ['disable', '--now', names.controllerUnit], null).catch(ignoreFailure);
  await run('systemctl', ['stop', names.agentUnitPattern], null).catch(ignoreFailure);
  await run('systemctl', ['reset-failed', names.agentUnitPattern], null).catch(ignoreFailure);
  await rm(join(SYSTEMD_SYSTEM_DIR, names.controllerUnit), { force: true });
  await rm(join(SYSTEMD_SYSTEM_DIR, names.agentTemplate), { force: true });
  await rm(names.polkitRule, { force: true });
  await rm(names.config, { force: true });
  await run('systemctl', ['daemon-reload'], null);
  for (let slot = 1; slot <= agentUsers; slot++)
    await run('userdel', [names.agentUser(slot)], null).catch(ignoreFailure);
  await run('groupdel', [names.group], null).catch(ignoreFailure);
  return {
    notes: [
      ...(agentsDir
        ? [
            `The agents' directories are kept in ${agentsDir}; remove them when nothing in them is needed.`,
          ]
        : []),
      ...(releasesDir
        ? [`The controller's releases are kept in ${releasesDir}; remove it when it is not needed.`]
        : []),
    ],
  };
}

function ignoreFailure(error: unknown): void {
  if (!(error instanceof CommandFailure)) throw error;
}

function assertRoot(): void {
  if (process.getuid?.() !== 0)
    throw new ConfigurationError(
      'Setting agents up as users of their own needs root, once: run this with sudo.'
    );
}

async function assertSetupHost(): Promise<void> {
  if (process.platform !== 'linux')
    throw new ConfigurationError(
      'Agents run as users of their own only on Linux with systemd. On this machine, run the controller as a service of your user: switch-agent-controller install-service'
    );
  assertRoot();
  try {
    await access('/run/systemd/system');
  } catch {
    throw new ConfigurationError(
      'systemd is not this machine’s init system, and agents run as users of their own through it.'
    );
  }
  try {
    await access(POLKIT_RULES_DIR);
  } catch {
    throw new ConfigurationError(
      `${POLKIT_RULES_DIR} does not exist: install polkit (polkitd), which lets the controller start its agents without root, and run the setup again.`
    );
  }
  for (const command of ['useradd', 'groupadd', 'getent', 'id', 'systemctl'])
    await which(command, SYSTEM_PATH);
}

async function assertEnrolled(dataDir: string, account: PasswdEntry): Promise<void> {
  const database = join(dataDir, 'controller.db');
  let owner: number;
  try {
    owner = (await stat(database)).uid;
  } catch {
    throw new ConfigurationError(
      `${dataDir} holds no enrolled controller. Enroll it first, as ${account.name}: switch-agent-controller enroll --server <url> --code <code> --data-dir ${dataDir}`
    );
  }
  if (owner !== account.uid)
    throw new ConfigurationError(
      `${database} belongs to uid ${owner}, not to ${account.name}, who would run the controller.`
    );
}

/** A user service on the same data directory would run a second controller with the same identity. */
async function assertNoUserService(dataDir: string, account: PasswdEntry): Promise<void> {
  const directory = join(account.home, '.config', 'systemd', 'user');
  let entries: string[];
  try {
    entries = await readdir(directory);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
    throw error;
  }
  for (const entry of entries) {
    if (!/^switch-agent-controller.*\.service$/.test(entry)) continue;
    const file = join(directory, entry);
    if ((await readFile(file, 'utf8')).includes(`"${dataDir}"`))
      throw new ConfigurationError(
        `${account.name} already runs this controller as a user service (${file}). Remove it first, as ${account.name}: switch-agent-controller uninstall-service --data-dir ${dataDir}`
      );
  }
}

async function ensureGroup(group: string, run: CommandRunner): Promise<number> {
  const existing = await run('getent', ['group', group], null).catch((error: unknown) => {
    ignoreFailure(error);
    return null;
  });
  if (!existing) await run('groupadd', ['--system', group], null);
  const line = existing ?? (await run('getent', ['group', group], null));
  const gid = Number(line.stdout.trim().split(':')[2]);
  if (!Number.isInteger(gid) || gid <= 0)
    throw new Error(`Could not read the gid of the group ${group}.`);
  return gid;
}

async function ensureAgentUser(user: string, group: string, run: CommandRunner): Promise<void> {
  const existing = await run('getent', ['passwd', user], null).catch((error: unknown) => {
    ignoreFailure(error);
    return null;
  });
  if (existing) {
    const groups = (await run('id', ['-gn', user], null)).stdout.trim();
    if (groups !== group)
      throw new ConfigurationError(
        `The user ${user} exists, but its group is ${groups}, not ${group}; it was not made by this setup.`
      );
    return;
  }
  await run(
    'useradd',
    [
      '--system',
      '--gid',
      group,
      '--no-create-home',
      '--home-dir',
      '/nonexistent',
      '--shell',
      '/usr/sbin/nologin',
      '--comment',
      'Switch agent',
      user,
    ],
    null
  );
}

/**
 * Where the setup finds the system's own commands (`useradd`, `systemctl`,
 * `find`…), whatever PATH it runs with: the PATH it is given is the one the
 * controller and its agents run with, which has no business holding `sbin`.
 */
const SYSTEM_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin';

/** `run`, with each command found on `SYSTEM_PATH` and run by its absolute path. */
function onSystemPath(run: CommandRunner): CommandRunner {
  return async (file, args, input) => run(await which(file, SYSTEM_PATH), args, input);
}

async function which(command: string, path: string): Promise<string> {
  for (const directory of path.split(delimiter)) {
    if (!isAbsolute(directory)) continue;
    const candidate = join(directory, command);
    try {
      await access(candidate);
      if (isUnitSafe(candidate)) return candidate;
    } catch {
      // not in this directory
    }
  }
  throw new ConfigurationError(
    `${command} is not installed in ${path.split(delimiter).join(', ')}, and the setup needs it.`
  );
}