Skip to content

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

5.5 KB
Raw Blame
import { execFile } from 'node:child_process';
import { chmod, mkdir, stat } from 'node:fs/promises';
import { homedir } from 'node:os';
import { isAbsolute, join, resolve } from 'node:path';
import { promisify } from 'node:util';
import { ConfigurationError } from './errors';

export const DATA_DIR_ENV = 'SWITCH_CONTROLLER_DATA_DIR';

/**
 * Where the controller keeps its state when nothing names a directory:
 * macOS `~/Library/Application Support/Switch/agent-controller`, Linux
 * `$XDG_STATE_HOME/switch/agent-controller` or
 * `~/.local/state/switch/agent-controller`.
 */
export function defaultDataDir(input: {
  platform: NodeJS.Platform;
  env: NodeJS.ProcessEnv;
  home: string;
}): string {
  if (input.platform === 'darwin')
    return join(input.home, 'Library', 'Application Support', 'Switch', 'agent-controller');
  if (input.platform === 'win32') {
    const local = input.env.LOCALAPPDATA;
    if (!local)
      throw new ConfigurationError(
        `LOCALAPPDATA is not set; pass --data-dir or set ${DATA_DIR_ENV}.`
      );
    return join(local, 'Switch', 'agent-controller');
  }
  const xdg = input.env.XDG_STATE_HOME;
  // The XDG spec ignores a relative value, so does this.
  const state = xdg && isAbsolute(xdg) ? xdg : join(input.home, '.local', 'state');
  return join(state, 'switch', 'agent-controller');
}

/** `--data-dir`, then `SWITCH_CONTROLLER_DATA_DIR`, then the OS default. */
export function resolveDataDir(flag: string | undefined): string {
  const named = flag ?? process.env[DATA_DIR_ENV];
  if (named) return resolve(named);
  return defaultDataDir({ platform: process.platform, env: process.env, home: homedir() });
}

/**
 * Creates the data directory owner-only (0700), and tightens one that already
 * exists with looser permissions: it holds the controller credential and every
 * agent's relay token. Windows has no mode bits, so there its access list is
 * replaced with one that lets in this user and the system alone, inherited by
 * everything written under it.
 */
export async function ensureDataDir(dir: string): Promise<void> {
  await mkdir(dir, { recursive: true, mode: 0o700 });
  if (process.platform === 'win32') {
    await restrictToCurrentUser(dir);
    return;
  }
  const mode = (await stat(dir)).mode & 0o777;
  if (mode !== 0o700) await chmod(dir, 0o700);
}

/** The well-known SID of the operating system's own account. */
const LOCAL_SYSTEM_SID = 'S-1-5-18';

/**
 * A Windows tool by its full path: a PATH with Git for Windows on it has GNU
 * tools of the same names ahead of the system's.
 */
function system32(tool: string): string {
  return join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', tool);
}

async function restrictToCurrentUser(dir: string): Promise<void> {
  const execute = promisify(execFile);
  try {
    const { stdout } = await execute(system32('whoami.exe'), ['/user', '/fo', 'csv', '/nh'], {
      timeout: 15_000,
      windowsHide: true,
    });
    const sid = stdout.trim().split(',').at(-1)?.replaceAll('"', '');
    if (!sid?.startsWith('S-1-')) throw new Error(`whoami printed no SID: ${stdout.trim()}`);
    await execute(
      system32('icacls.exe'),
      [
        dir,
        '/inheritance:r',
        '/grant:r',
        `*${sid}:(OI)(CI)F`,
        '/grant:r',
        `*${LOCAL_SYSTEM_SID}:(OI)(CI)F`,
      ],
      { timeout: 15_000, windowsHide: true }
    );
  } catch (error) {
    throw new ConfigurationError(
      `Could not make ${dir} readable by this user only, and it holds the controller's credentials: ${error instanceof Error ? error.message : String(error)}`
    );
  }
}

export type DataLayout = {
  root: string;
  database: string;
  secrets: string;
  agentDir: (agentId: string) => string;
  agentCredentials: (agentId: string) => string;
  watcherRoot: (agentId: string) => string;
};

/**
 * Where agents with no directory of their own work, for one server: a short
 * folder in the home directory named after the server's address, shared by
 * every controller on the machine that talks to it, rather than a path inside
 * a controller's data directory.
 */
export function serverWorkspacesDir(server: string): string {
  const { host } = new URL(server);
  const segment = host.replace(/[^A-Za-z0-9._-]+/g, '-');
  if (!isSafeSegment(segment))
    throw new ConfigurationError(`The server address '${server}' cannot name a folder.`);
  return join(homedir(), '.switch', 'agents', segment);
}

/** An agent's working directory under `workspaces`, when its definition names none. */
export function agentWorkspace(workspaces: string, name: string): string {
  return join(workspaces, safeSegment(name, 'agent name'));
}

export function dataLayout(root: string): DataLayout {
  return {
    root,
    database: join(root, 'controller.db'),
    secrets: join(root, 'secrets'),
    agentDir: (agentId) => join(root, 'agents', safeSegment(agentId, 'agent id')),
    agentCredentials: (agentId) =>
      join(root, 'agents', safeSegment(agentId, 'agent id'), 'credentials.json'),
    watcherRoot: (agentId) => join(root, 'watchers', safeSegment(agentId, 'agent id')),
  };
}

const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;

/** A server-supplied value about to become one path segment under the data directory. */
export function isSafeSegment(value: string): boolean {
  return SAFE_SEGMENT.test(value) && !value.includes('..');
}

function safeSegment(value: string, what: string): string {
  if (!isSafeSegment(value))
    throw new Error(`The ${what} '${value}' cannot be used as a directory name.`);
  return value;
}