@push.rocks/smartdaemon 2.11.0 → 2.13.0

package/ts/classes.systemdtransientscope.ts

@@ -0,0 +1,272 @@
+import * as plugins from './smartdaemon.plugins.js';
+import { isCleanText } from './systemd.definition.js';
+import { captureUserEnvironment, inspectRuntimeDirectory, isSafeDirectory } from './systemd.userenvironment.js';
+
+export interface ISystemdTransientScopeOptions {
+  /** The calling user's manager; the only manager a transient scope is started in. */
+  scope: 'user';
+  /** Absolute, normalized program path, executed directly: no shell, no PATH search. */
+  executable: string;
+  /** Literal arguments, at most 128 of at most 32768 characters each, without NUL. */
+  args: readonly string[];
+  /** Absolute, normalized directory the program starts in. */
+  workingDirectory: string;
+  /**
+   * The program's complete environment. Nothing of the calling process is inherited: the program
+   * receives exactly these variables, the manager's `XDG_RUNTIME_DIR` and systemd's
+   * `INVOCATION_ID`. Names match `[A-Za-z_][A-Za-z0-9_]*` (at most 128 characters); values are
+   * strings of at most 32768 characters without NUL; at most 256 variables. `XDG_RUNTIME_DIR`,
+   * `INVOCATION_ID` and names starting with `SYSTEMD_` or `DBUS_`, which configure systemd-run
+   * itself, are refused.
+   */
+  environment: Readonly<Record<string, string>>;
+  /** Literal unit description: clean text of 1 to 1024 characters, trimmed, without `\`. */
+  description: string;
+  /** A `.scope` unit name; defaults to a unique `smartdaemon-<32 hex digits>.scope`. */
+  unitName?: string;
+  /** User-manager socket directory. Defaults to a non-empty XDG_RUNTIME_DIR. */
+  runtimeDirectory?: string;
+  /** Absolute executable path supplied by trusted owning code. Defaults to `/usr/bin/systemd-run`. */
+  systemdRunPath?: string;
+  /** Absolute executable path supplied by trusted owning code. Defaults to `/usr/bin/systemctl`. */
+  systemctlPath?: string;
+  /** Bounds the manager probe and the program's direct process, each. Defaults to 120 seconds. */
+  commandTimeoutMs?: number;
+}
+
+export interface ISystemdTransientScopeResult {
+  /** The scope unit. It stays active while any process the program started runs in it. */
+  readonly unitName: string;
+  /** Exit status of the program's direct process; null when a signal ended it. */
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+  /** UTF-8 decoded output of the program and every process that shared its stdout. */
+  readonly stdout: string;
+  /** As `stdout`, without the line systemd-run prints on starting the scope. */
+  readonly stderr: string;
+}
+
+export type TSystemdTransientScopeErrorCode =
+  /** The options are malformed, or the runtime directory is not a private directory of the caller. */
+  | 'invalid_options'
+  /** The process is not running on Linux. */
+  | 'unsupported_platform'
+  /** No runtime directory is set or it does not exist, or the manager does not answer systemctl. */
+  | 'user_manager_unavailable'
+  /** systemd-run exited without reporting the scope running; the program has not run. */
+  | 'scope_start_failed'
+  /** The manager probe or the program did not finish, and close its output, in time. */
+  | 'timed_out'
+  /** The program's stdout or stderr exceeded 1 MiB. */
+  | 'output_limit';
+
+export class SystemdTransientScopeError extends Error {
+  constructor(
+    public readonly code: TSystemdTransientScopeErrorCode,
+    /** The scope the call used; null when the options were refused. */
+    public readonly unitName: string | null,
+    /** The probe's or systemd-run's stderr as far as it was read; empty when none ran. */
+    public readonly stderr: string,
+    options?: ErrorOptions,
+  ) {
+    super(`Systemd transient scope failed: ${code}${unitName === null ? '' : ` (${unitName})`}.`, options);
+    this.name = 'SystemdTransientScopeError';
+  }
+}
+
+const outputLimit = 1048576;
+const reservedName = (name: string) =>
+  name === 'XDG_RUNTIME_DIR' || name === 'INVOCATION_ID' || name.startsWith('SYSTEMD_') || name.startsWith('DBUS_');
+
+interface IValidatedOptions {
+  readonly executable: string;
+  readonly args: readonly string[];
+  readonly workingDirectory: string;
+  readonly environment: ReadonlyMap<string, string>;
+  readonly description: string;
+  readonly unitName: string;
+  readonly runtimeDirectory?: string;
+  readonly systemdRunPath: string;
+  readonly systemctlPath: string;
+  readonly timeoutMs: number;
+}
+
+/** Reads every option once through its own data descriptor, so no accessor or proxy trap runs. */
+const validate = (options: unknown): IValidatedOptions | undefined => {
+  const plain = (value: unknown, prototype: object): value is object => value !== null &&
+    typeof value === 'object' && !plugins.util.types.isProxy(value) && Object.getPrototypeOf(value) === prototype;
+  if (!plain(options, Object.prototype)) return undefined;
+  const required = ['scope', 'executable', 'args', 'workingDirectory', 'environment', 'description'];
+  const optional = ['unitName', 'runtimeDirectory', 'systemdRunPath', 'systemctlPath', 'commandTimeoutMs'];
+  const values = new Map<string, unknown>();
+  for (const key of Reflect.ownKeys(options)) {
+    const descriptor = Object.getOwnPropertyDescriptor(options, key);
+    if (typeof key !== 'string' || ![...required, ...optional].includes(key) || !descriptor?.enumerable ||
+      !('value' in descriptor)) return undefined;
+    if (descriptor.value !== undefined) values.set(key, descriptor.value);
+  }
+  if (!required.every((key) => values.has(key)) || values.get('scope') !== 'user') return undefined;
+  const path = (value: unknown): value is string => isSafeDirectory(value);
+  const bounded = (value: unknown): value is string =>
+    typeof value === 'string' && value.length <= 32768 && !value.includes('\0');
+
+  const executable = values.get('executable');
+  const workingDirectory = values.get('workingDirectory');
+  const description = values.get('description');
+  if (!path(executable) || !(workingDirectory === '/' || path(workingDirectory)) ||
+    typeof description !== 'string' || description.length < 1 || description.length > 1024 ||
+    description.trim() !== description || description.includes('\\') || !isCleanText(description)) return undefined;
+
+  const argsValue = values.get('args');
+  if (!plain(argsValue, Array.prototype) || !Array.isArray(argsValue) || argsValue.length > 128 ||
+    Reflect.ownKeys(argsValue).length !== argsValue.length + 1) return undefined;
+  const args: string[] = [];
+  for (let index = 0; index < argsValue.length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(argsValue, String(index));
+    if (!descriptor || !('value' in descriptor) || !bounded(descriptor.value)) return undefined;
+    args.push(descriptor.value);
+  }
+
+  const variables = values.get('environment');
+  if (!plain(variables, Object.prototype)) return undefined;
+  const names = Reflect.ownKeys(variables);
+  if (names.length > 256) return undefined;
+  const environment = new Map<string, string>();
+  for (const name of names) {
+    const descriptor = Object.getOwnPropertyDescriptor(variables, name);
+    if (typeof name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(name) || reservedName(name) ||
+      !descriptor?.enumerable || !('value' in descriptor) || !bounded(descriptor.value)) return undefined;
+    environment.set(name, descriptor.value);
+  }
+
+  const unitName = values.get('unitName') ?? `smartdaemon-${plugins.crypto.randomUUID().replaceAll('-', '')}.scope`;
+  const runtimeDirectory = values.get('runtimeDirectory');
+  const systemdRunPath = values.get('systemdRunPath') ?? '/usr/bin/systemd-run';
+  const systemctlPath = values.get('systemctlPath') ?? '/usr/bin/systemctl';
+  const timeoutMs = values.get('commandTimeoutMs') ?? 120000;
+  if (typeof unitName !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,230}\.scope$/.test(unitName) ||
+    (runtimeDirectory !== undefined && !path(runtimeDirectory)) || !path(systemdRunPath) || !path(systemctlPath) ||
+    !Number.isSafeInteger(timeoutMs) || (timeoutMs as number) < 1 || (timeoutMs as number) > 600000) return undefined;
+  return {
+    executable, args, workingDirectory, environment, description, unitName, runtimeDirectory, systemdRunPath,
+    systemctlPath, timeoutMs: timeoutMs as number,
+  };
+};
+
+type TProcessOutcome =
+  | { readonly kind: 'exited'; readonly code: number | null; readonly signal: NodeJS.Signals | null;
+    readonly stdout: string; readonly stderr: string }
+  | { readonly kind: 'spawn_failed'; readonly error: Error }
+  | { readonly kind: 'timed_out' | 'output_limit'; readonly stderr: string };
+
+/**
+ * Runs a program with stdin on /dev/null and bounded output. It settles once the process has exited
+ * and its stdout and stderr have closed; on the deadline or an output overflow it kills the process
+ * if it still runs and releases both pipes, so a descendant holding them keeps no handle open here.
+ */
+const runProcess = (file: string, args: readonly string[], env: Record<string, string>, timeoutMs: number) =>
+  new Promise<TProcessOutcome>((resolve) => {
+    const child = plugins.childProcess.spawn(file, args, {
+      cwd: '/', env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true,
+    });
+    const output = { stdout: [] as Buffer[], stderr: [] as Buffer[] };
+    const sizes = { stdout: 0, stderr: 0 };
+    let settled = false;
+    const text = (chunks: Buffer[]) => Buffer.concat(chunks).toString('utf8');
+    const abandon = (kind: 'timed_out' | 'output_limit') => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+      child.stdout.destroy();
+      child.stderr.destroy();
+      resolve({ kind, stderr: text(output.stderr) });
+    };
+    const timer = setTimeout(() => abandon('timed_out'), timeoutMs);
+    for (const stream of ['stdout', 'stderr'] as const) {
+      child[stream].on('data', (chunk: Buffer) => {
+        sizes[stream] += chunk.length;
+        if (sizes[stream] > outputLimit) abandon('output_limit');
+        else output[stream].push(chunk);
+      });
+    }
+    child.on('error', (error) => {
+      if (settled || child.pid !== undefined) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ kind: 'spawn_failed', error });
+    });
+    child.on('close', (code, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ kind: 'exited', code, signal, stdout: text(output.stdout), stderr: text(output.stderr) });
+    });
+  });
+
+/**
+ * The first stderr line systemd-run prints once the scope runs, before it executes the program:
+ * systemd 255 and later print `Running as unit: NAME` with an optional `; invocation ID: ID`,
+ * systemd 254 prints `Running scope as unit: NAME`. Returns the rest of stderr, or undefined.
+ */
+const programStderr = (stderr: string, unitName: string): string | undefined => {
+  const newline = stderr.indexOf('\n');
+  if (newline < 0) return undefined;
+  const line = stderr.slice(0, newline);
+  const started = line === `Running as unit: ${unitName}` || line === `Running scope as unit: ${unitName}` ||
+    (line.startsWith(`Running as unit: ${unitName}; invocation ID: `) &&
+      /^[0-9a-f]{32}$/.test(line.slice(`Running as unit: ${unitName}; invocation ID: `.length)));
+  return started ? stderr.slice(newline + 1) : undefined;
+};
+
+/**
+ * Starts a program in a new transient scope unit of the calling user's systemd manager, so it and
+ * every process it starts run outside the caller's own unit and survive that unit's stop, and
+ * waits for the program's direct process. A program that daemonizes and exits returns its result
+ * while its daemon keeps the scope active; the scope ends when its last process exits. The daemon
+ * must not keep the program's stdout or stderr open, or the call runs into its timeout.
+ *
+ * On `timed_out` and `output_limit` the direct process is killed; processes it started stay in
+ * the scope. A program that exits with a failure status is a result, not an error.
+ */
+export const runInTransientScope = async (
+  options: ISystemdTransientScopeOptions,
+): Promise<ISystemdTransientScopeResult> => {
+  const validated = validate(options);
+  if (validated === undefined) throw new SystemdTransientScopeError('invalid_options', null, '');
+  const { unitName } = validated;
+  const fail = (code: TSystemdTransientScopeErrorCode, stderr = '', cause?: unknown): never => {
+    throw new SystemdTransientScopeError(code, unitName, stderr, cause === undefined ? undefined : { cause });
+  };
+  if (process.platform !== 'linux') fail('unsupported_platform');
+  const runtimeDirectory = validated.runtimeDirectory ?? captureUserEnvironment(undefined).runtimeDirectory;
+  if (runtimeDirectory === undefined) fail('user_manager_unavailable');
+  if (!isSafeDirectory(runtimeDirectory)) fail('invalid_options');
+  const admission = await inspectRuntimeDirectory(runtimeDirectory!);
+  if (admission === 'absent') fail('user_manager_unavailable');
+  if (admission !== 'private') fail('invalid_options');
+
+  const probe = await runProcess(validated.systemctlPath,
+    ['--user', '--no-ask-password', '--no-pager', 'show', '--property=Version'],
+    { PATH: '/usr/bin:/bin', LANG: 'C', LC_ALL: 'C', XDG_RUNTIME_DIR: runtimeDirectory! }, validated.timeoutMs);
+  if (probe.kind === 'timed_out') fail('timed_out', probe.stderr);
+  if (probe.kind !== 'exited' || probe.code !== 0 || !probe.stdout.startsWith('Version=')) {
+    fail('user_manager_unavailable', probe.kind === 'spawn_failed' ? '' : probe.stderr,
+      probe.kind === 'spawn_failed' ? probe.error : undefined);
+  }
+
+  // systemd-run registers its own process as the scope, then executes the program in place with
+  // its environment, so that environment is the program's own plus INVOCATION_ID.
+  const outcome = await runProcess(validated.systemdRunPath, [
+    '--user', '--scope', '--collect', '--no-ask-password', '--expand-environment=no',
+    `--unit=${unitName}`, `--description=${validated.description}`,
+    `--working-directory=${validated.workingDirectory}`, '--', validated.executable, ...validated.args,
+  ], { ...Object.fromEntries(validated.environment), XDG_RUNTIME_DIR: runtimeDirectory! }, validated.timeoutMs);
+  if (outcome.kind === 'spawn_failed') return fail('scope_start_failed', '', outcome.error);
+  if (outcome.kind !== 'exited') return fail(outcome.kind, outcome.stderr);
+  const stderr = programStderr(outcome.stderr, unitName);
+  if (stderr === undefined) return fail('scope_start_failed', outcome.stderr);
+  return Object.freeze({
+    unitName, exitCode: outcome.code, signal: outcome.signal, stdout: outcome.stdout, stderr,
+  });
+};

package/ts/classes.systemdunit.ts

@@ -3,6 +3,7 @@ import {
   type ISystemdUserEnvironment,
   type TSystemdUserManagerEnvironment,
   captureUserEnvironment,
+  inspectRuntimeDirectory,
   isSafeDirectory,
   isUserManagerEnvironment,
 } from './systemd.userenvironment.js';
@@ -371,17 +372,7 @@ export class SystemdUnit {
     const environment = this.userEnvironment;
     if (environment === undefined) return undefined;
     if (!isUserManagerEnvironment(environment)) throw new SystemdUnitError('invalid_options');
-    const runtimeDirectory = environment.runtimeDirectory;
-    try {
-      const uid = process.getuid?.();
-      if (process.platform !== 'linux' || uid === undefined || process.geteuid?.() !== uid ||
-        await plugins.fs.realpath(runtimeDirectory) !== runtimeDirectory) {
-        throw new SystemdUnitError('invalid_options');
-      }
-      const info = await plugins.fs.lstat(runtimeDirectory);
-      if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== uid ||
-        (info.mode & 0o077) !== 0) throw new SystemdUnitError('invalid_options');
-    } catch {
+    if (await inspectRuntimeDirectory(environment.runtimeDirectory) !== 'private') {
       throw new SystemdUnitError('invalid_options');
     }
     return environment;

package/ts/index.ts

@@ -3,3 +3,4 @@ export * from './smartdaemon.classes.service.js';
 export * from './classes.systemdunit.js';
 export * from './classes.systemdservicedefinition.js';
 export * from './classes.systemdunitfile.js';
+export * from './classes.systemdtransientscope.js';

package/ts/systemd.definition.ts

@@ -34,6 +34,41 @@ export interface ISystemdServiceInstallTargets {
   requiredBy: readonly string[];
 }
 
+/**
+ * One credential a system service reads from `$CREDENTIALS_DIRECTORY/<name>` (`LoadCredential=` or
+ * `LoadCredentialEncrypted=`). The value never appears in the unit, its environment or
+ * `systemctl show`; it is readable by the service's user only.
+ */
+export interface ISystemdServiceCredential {
+  /** The credential's name inside the service: printable ASCII from `[A-Za-z0-9_.@-]`, 1–255 characters, not starting with `.`. */
+  name: string;
+  /**
+   * Where systemd reads it: an absolute normalized path (a file, a directory of files or an
+   * `AF_UNIX` socket), or a credential name that systemd searches among its own credentials and
+   * in the credstore directories (`/etc/credstore/`, `/run/credstore/`, `/usr/lib/credstore/`, and
+   * for encrypted credentials also their `.encrypted` counterparts). Omitted, systemd searches
+   * under `name` itself.
+   */
+  source?: string;
+}
+
+/** Linux capabilities systemd 255 knows by name, for `capabilityBoundingSet` and `ambientCapabilities`. */
+export const systemdCapabilities = [
+  'CAP_AUDIT_CONTROL', 'CAP_AUDIT_READ', 'CAP_AUDIT_WRITE', 'CAP_BLOCK_SUSPEND', 'CAP_BPF',
+  'CAP_CHECKPOINT_RESTORE', 'CAP_CHOWN', 'CAP_DAC_OVERRIDE', 'CAP_DAC_READ_SEARCH', 'CAP_FOWNER',
+  'CAP_FSETID', 'CAP_IPC_LOCK', 'CAP_IPC_OWNER', 'CAP_KILL', 'CAP_LEASE', 'CAP_LINUX_IMMUTABLE',
+  'CAP_MAC_ADMIN', 'CAP_MAC_OVERRIDE', 'CAP_MKNOD', 'CAP_NET_ADMIN', 'CAP_NET_BIND_SERVICE',
+  'CAP_NET_BROADCAST', 'CAP_NET_RAW', 'CAP_PERFMON', 'CAP_SETFCAP', 'CAP_SETGID', 'CAP_SETPCAP',
+  'CAP_SETUID', 'CAP_SYSLOG', 'CAP_SYS_ADMIN', 'CAP_SYS_BOOT', 'CAP_SYS_CHROOT', 'CAP_SYS_MODULE',
+  'CAP_SYS_NICE', 'CAP_SYS_PACCT', 'CAP_SYS_PTRACE', 'CAP_SYS_RAWIO', 'CAP_SYS_RESOURCE',
+  'CAP_SYS_TIME', 'CAP_SYS_TTY_CONFIG', 'CAP_WAKE_ALARM',
+] as const;
+export type TSystemdCapability = typeof systemdCapabilities[number];
+
+/** Socket address families a definition may allow with `restrictAddressFamilies`. */
+export const systemdAddressFamilies = ['AF_INET', 'AF_INET6', 'AF_NETLINK', 'AF_PACKET', 'AF_UNIX', 'AF_VSOCK'] as const;
+export type TSystemdAddressFamily = typeof systemdAddressFamilies[number];
+
 /**
  * Internal bounds of a definition's `environment`: variables, and UTF-8 bytes of `NAME=value` in
  * total. SystemdUnit sizes its systemctl output limit from them, so every accepted definition reads back.
@@ -59,10 +94,13 @@ export const renderServiceRelations = (options: {
   startup?: TSystemdServiceStartup;
   dependencies?: ISystemdServiceDependencies;
   install?: ISystemdServiceInstallTargets;
-}, unitName: string, restart: string, scope: 'system' | 'user', fail: () => never): {
+}, unitName: string, restart: string, scope: 'system' | 'user',
+fail: (option: 'startup' | 'dependencies' | 'install') => never): {
   unit: string[]; service: string[]; install: string[];
 } => {
-  const requireValue = (value: unknown): void => { if (!value) fail(); };
+  // Every check names the option it belongs to; `option` is set before each option is read.
+  let option: 'startup' | 'dependencies' | 'install' = 'startup';
+  const requireValue = (value: unknown): void => { if (!value) fail(option); };
   const plain = (value: unknown): void => requireValue(value !== null && typeof value === 'object'
     && !plugins.util.types.isProxy(value) && Object.getPrototypeOf(value) === Object.prototype);
   const record = (value: unknown, keys: readonly string[]): void => {
@@ -110,6 +148,7 @@ export const renderServiceRelations = (options: {
     }
   }
   if (options.dependencies !== undefined) {
+    option = 'dependencies';
     const value = options.dependencies;
     record(value, ['defaultDependencies', 'after', 'before', 'requires', 'wants', 'conflicts']);
     requireValue(typeof value.defaultDependencies === 'boolean');
@@ -120,6 +159,7 @@ export const renderServiceRelations = (options: {
       ...line('Before', before), ...line('Requires', requires), ...line('Wants', wants), ...line('Conflicts', conflicts)];
   }
   if (options.install !== undefined) {
+    option = 'install';
     const value = options.install;
     record(value, ['wantedBy', 'requiredBy']);
     const wanted = units(value.wantedBy), required = units(value.requiredBy);

package/ts/systemd.userenvironment.ts

@@ -61,3 +61,23 @@ export const isUserManagerEnvironment = (
   isSafeDirectory(environment.runtimeDirectory) && isSafeDirectory(environment.homeDirectory) &&
   (environment.configDirectory === undefined || isSafeDirectory(environment.configDirectory)) &&
   (environment.dataDirectory === undefined || isSafeDirectory(environment.dataDirectory));
+
+/**
+ * Admits a user-manager runtime directory: on Linux, for a process whose uid is its effective uid,
+ * the path must be its own real path and a directory owned by that uid without group or other
+ * permissions. `absent` is a directory that does not exist; every other refusal is `unsafe`.
+ */
+export const inspectRuntimeDirectory = async (
+  runtimeDirectory: string,
+): Promise<'private' | 'absent' | 'unsafe'> => {
+  const uid = process.getuid?.();
+  if (process.platform !== 'linux' || uid === undefined || process.geteuid?.() !== uid) return 'unsafe';
+  try {
+    if (await plugins.fs.realpath(runtimeDirectory) !== runtimeDirectory) return 'unsafe';
+    const info = await plugins.fs.lstat(runtimeDirectory);
+    return info.isDirectory() && !info.isSymbolicLink() && info.uid === uid && (info.mode & 0o077) === 0
+      ? 'private' : 'unsafe';
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'absent' : 'unsafe';
+  }
+};