@push.rocks/smartdaemon 2.2.0 → 2.4.0

package/ts/classes.systemdunit.ts

@@ -0,0 +1,173 @@
+import * as plugins from './smartdaemon.plugins.js';
+
+export interface ISystemdUnitOptions {
+  unitName: string;
+  /** Absolute executable path supplied by trusted owning code. */
+  systemctlPath?: string;
+  /** Bounds the systemctl client, not the server-side job. Defaults to 120 seconds. */
+  commandTimeoutMs?: number;
+}
+
+export interface ISystemdUnitState {
+  readonly unitName: string;
+  readonly loadState: string;
+  readonly activeState: string;
+  readonly subState: string;
+  readonly unitFileState: string;
+  readonly mainPid: number;
+  readonly controlPid: number;
+  readonly controlGroup: string;
+  readonly killMode: string;
+  /** Empty when no systemd job is pending; otherwise systemctl's job description. */
+  readonly job: string;
+}
+
+export interface ISystemdUnitConfigurationState {
+  readonly unitName: string;
+  readonly fragmentPath: string;
+  /** Opaque systemctl path list. An empty value proves no effective drop-ins. */
+  readonly dropInPaths: string;
+  readonly needsReload: boolean;
+}
+
+export class SystemdUnitError extends Error {
+  constructor(public readonly code: 'invalid_options' | 'command_failed' | 'invalid_state') {
+    super(`Systemd unit operation failed: ${code}.`);
+    this.name = 'SystemdUnitError';
+  }
+}
+
+const properties = [
+  'Id',
+  'LoadState',
+  'ActiveState',
+  'SubState',
+  'UnitFileState',
+  'MainPID',
+  'ControlPID',
+  'ControlGroup',
+  'KillMode',
+  'Job',
+] as const;
+
+/** Controls an existing system unit without creating files, changing enablement or escalating privileges. */
+export class SystemdUnit {
+  private readonly unitName: string;
+  private readonly executable: string;
+  private readonly timeout: number;
+
+  constructor(optionsArg: ISystemdUnitOptions) {
+    this.unitName = optionsArg?.unitName;
+    this.executable = optionsArg?.systemctlPath ?? '/usr/bin/systemctl';
+    this.timeout = optionsArg?.commandTimeoutMs ?? 120000;
+    if (
+      typeof this.unitName !== 'string' ||
+      !/^[a-zA-Z0-9][a-zA-Z0-9_.:@-]{0,230}\.service$/.test(this.unitName) ||
+      typeof this.executable !== 'string' || !plugins.path.isAbsolute(this.executable) ||
+      this.executable.includes('\0') || !Number.isSafeInteger(this.timeout) ||
+      this.timeout < 1 || this.timeout > 600000
+    ) throw new SystemdUnitError('invalid_options');
+  }
+
+  /** Snapshot only. Callers own application-specific admission and restart policy. */
+  public async inspect(): Promise<ISystemdUnitState> {
+    const stdout = await this.command([
+      'show',
+      this.unitName,
+      `--property=${properties.join(',')}`,
+      '--all',
+    ]);
+    const fields = new Map<string, string>();
+    for (const line of stdout.trimEnd().split('\n')) {
+      const separator = line.indexOf('=');
+      const key = line.slice(0, separator);
+      if (separator < 1 || !(properties as readonly string[]).includes(key) || fields.has(key)) {
+        throw new SystemdUnitError('invalid_state');
+      }
+      fields.set(key, line.slice(separator + 1));
+    }
+    if (
+      fields.size !== properties.length || fields.get('Id') !== this.unitName ||
+      ['LoadState', 'ActiveState', 'SubState'].some((key) => !fields.get(key)) ||
+      ['MainPID', 'ControlPID'].some((key) =>
+        !/^(0|[1-9]\d*)$/.test(fields.get(key)!) || !Number.isSafeInteger(Number(fields.get(key)))
+      )
+    ) throw new SystemdUnitError('invalid_state');
+    return Object.freeze({
+      unitName: this.unitName,
+      loadState: fields.get('LoadState')!,
+      activeState: fields.get('ActiveState')!,
+      subState: fields.get('SubState')!,
+      unitFileState: fields.get('UnitFileState')!,
+      mainPid: Number(fields.get('MainPID')),
+      controlPid: Number(fields.get('ControlPID')),
+      controlGroup: fields.get('ControlGroup')!,
+      killMode: fields.get('KillMode')!,
+      job: fields.get('Job')!,
+    });
+  }
+
+  /** Await the systemd job, then inspect. This does not enable or unmask the unit. */
+  public async start(): Promise<ISystemdUnitState> {
+    await this.command(['start', this.unitName]);
+    return this.inspect();
+  }
+
+  /** Await the systemd job, then inspect. The snapshot alone is not an application data-drain proof. */
+  public async stop(): Promise<ISystemdUnitState> {
+    await this.command(['stop', this.unitName]);
+    return this.inspect();
+  }
+
+  /** Reports the manager's selected definition without reading or changing its contents. */
+  public async inspectConfiguration(): Promise<ISystemdUnitConfigurationState> {
+    const keys = ['Id', 'FragmentPath', 'DropInPaths', 'NeedDaemonReload'];
+    const stdout = await this.command(['show', this.unitName, `--property=${keys.join(',')}`, '--all']);
+    const fields = new Map<string, string>();
+    for (const line of stdout.trimEnd().split('\n')) {
+      const separator = line.indexOf('='), key = line.slice(0, separator);
+      if (separator < 1 || !keys.includes(key) || fields.has(key)) {
+        throw new SystemdUnitError('invalid_state');
+      }
+      fields.set(key, line.slice(separator + 1));
+    }
+    if (fields.size !== keys.length || fields.get('Id') !== this.unitName ||
+      !['yes', 'no'].includes(fields.get('NeedDaemonReload')!)) {
+      throw new SystemdUnitError('invalid_state');
+    }
+    return Object.freeze({
+      unitName: this.unitName,
+      fragmentPath: fields.get('FragmentPath')!,
+      dropInPaths: fields.get('DropInPaths')!,
+      needsReload: fields.get('NeedDaemonReload') === 'yes',
+    });
+  }
+
+  /** Reloads unit definitions globally; does not enable, unmask, start or stop a unit. */
+  public async reloadConfiguration(): Promise<ISystemdUnitConfigurationState> {
+    await this.command(['daemon-reload']);
+    return this.inspectConfiguration();
+  }
+
+  private command(argsArg: string[]): Promise<string> {
+    return new Promise((resolve, reject) => {
+      plugins.childProcess.execFile(
+        this.executable,
+        ['--system', '--no-ask-password', '--no-pager', ...argsArg],
+        {
+          encoding: 'utf8',
+          timeout: this.timeout,
+          killSignal: 'SIGKILL',
+          maxBuffer: 16384,
+          windowsHide: true,
+          env: { PATH: '/usr/bin:/bin', LANG: 'C', LC_ALL: 'C' },
+        },
+        (error, stdout) => {
+          // execFile settles after the client closes. A timed-out client's remote job may continue.
+          if (error) reject(new SystemdUnitError('command_failed'));
+          else resolve(stdout);
+        },
+      );
+    });
+  }
+}

package/ts/classes.systemdunitfile.ts

@@ -0,0 +1,311 @@
+import * as plugins from './smartdaemon.plugins.js';
+import { SystemdServiceDefinition } from './classes.systemdservicedefinition.js';
+import {
+  type ISystemdUnitOptions,
+  type ISystemdUnitState,
+  SystemdUnit,
+} from './classes.systemdunit.js';
+
+export interface ISystemdUnitFileOptions extends ISystemdUnitOptions {
+  /** Local vendor definitions can be installed without removing an administrator's mask. */
+  unitDirectory?: string;
+  /** Trusted owning-code qualification only. Defaults to root. */
+  expectedUid?: number;
+}
+export interface ISystemdUnitFileRecord {
+  readonly path: string;
+  readonly sha256: string;
+}
+export class SystemdUnitFileError extends Error {
+  constructor(
+    public readonly code:
+      | 'invalid_options'
+      | 'unsafe_path'
+      | 'busy'
+      | 'changed'
+      | 'unsafe_unit'
+      | 'write_failed'
+      | 'reload_failed',
+  ) {
+    super(`Systemd unit definition installation failed: ${code}.`);
+    this.name = 'SystemdUnitFileError';
+  }
+}
+const requireValue = (value: unknown, code: SystemdUnitFileError['code']): void => {
+  if (!value) throw new SystemdUnitFileError(code);
+};
+const digest = (bytes: Uint8Array) =>
+  plugins.crypto.createHash('sha256').update(bytes).digest('hex');
+const quiet = (state: ISystemdUnitState) =>
+  state.mainPid === 0 && state.controlPid === 0 &&
+  state.controlGroup === '' && state.job === '' &&
+  (state.activeState === 'inactive' && state.subState === 'dead' ||
+    state.activeState === 'failed' && state.subState === 'failed');
+const masked = (state: ISystemdUnitState) =>
+  state.loadState === 'masked' &&
+  ['masked', 'masked-runtime'].includes(state.unitFileState);
+const sameFile = (left: { dev: number; ino: number }, right: { dev: number; ino: number }) =>
+  left.dev === right.dev && left.ino === right.ino;
+
+/**
+ * Protected code/config installation, inside the caller's cross-process installation ownership scope.
+ * Other privileged writers must be serialized by that owner. Never changes enablement or masks.
+ */
+export class SystemdUnitFile {
+  public readonly path: string;
+  private readonly directory: string;
+  private readonly uid: number;
+  private readonly unit: SystemdUnit;
+  private readonly name: string;
+  private busy = false;
+
+  constructor(options: ISystemdUnitFileOptions) {
+    this.unit = new SystemdUnit(options);
+    this.name = options.unitName;
+    this.directory = options.unitDirectory ?? '/usr/local/lib/systemd/system';
+    this.uid = options.expectedUid ?? 0;
+    requireValue(
+      typeof this.directory === 'string' && this.directory !== '/' &&
+        plugins.path.isAbsolute(this.directory) &&
+        plugins.path.normalize(this.directory) === this.directory &&
+        !this.directory.endsWith('/') && !/[\x00-\x1f\x7f]/.test(this.directory) &&
+        this.directory.length <= 4000 && Number.isSafeInteger(this.uid) && this.uid >= 0,
+      'invalid_options',
+    );
+    this.path = plugins.path.join(this.directory, this.name);
+  }
+
+  /** Reads only the exact protected definition; no systemd or filesystem mutation. */
+  public async inspect(): Promise<ISystemdUnitFileRecord | null> {
+    if (!await this.directories(false)) return null;
+    const file = await this.read(this.path);
+    return file ? Object.freeze({ path: this.path, sha256: digest(file.bytes) }) : null;
+  }
+
+  /**
+   * Expected previous digest is mandatory; null admits an absent file. Exact desired bytes are idempotent.
+   * Retains changed definitions beside the unit before replacement. A failed reload never rolls code back.
+   */
+  public async install(
+    definition: SystemdServiceDefinition,
+    expectedSha256: string | null,
+  ): Promise<Readonly<{ changed: boolean; record: ISystemdUnitFileRecord; masked: boolean }>> {
+    requireValue(
+      definition instanceof SystemdServiceDefinition && definition.unitName === this.name &&
+        (expectedSha256 === null ||
+          typeof expectedSha256 === 'string' && /^[a-f0-9]{64}$/.test(expectedSha256)),
+      'invalid_options',
+    );
+    requireValue(!this.busy, 'busy');
+    this.busy = true;
+    let temporary: string | undefined;
+    let temporaryInfo: plugins.Stats | undefined;
+    try {
+      const before = await this.unit.inspect();
+      await this.admit(before);
+      await this.directories(true);
+      const parent = await plugins.fs.lstat(this.directory);
+      const previous = await this.read(this.path);
+      const previousSha = previous ? digest(previous.bytes) : null;
+      const changed = previousSha !== definition.sha256;
+      requireValue(!changed || previousSha === expectedSha256, 'changed');
+      if (changed) {
+        if (previous) {
+          const backup = `${this.path}.previous-${previousSha}`;
+          try {
+            await this.create(backup, previous.bytes);
+          } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+            requireValue(digest((await this.read(backup))!.bytes) === previousSha, 'changed');
+          }
+          await this.flushDirectory(parent);
+        }
+        temporary = plugins.path.join(
+          this.directory,
+          `.${this.name}.${plugins.crypto.randomUUID()}.tmp`,
+        );
+        await this.create(temporary, Buffer.from(definition.content));
+        temporaryInfo = await plugins.fs.lstat(temporary);
+        const current = await this.read(this.path);
+        requireValue(
+          (current ? digest(current.bytes) : null) === previousSha &&
+            (!current || previous && sameFile(current.info, previous.info)),
+          'changed',
+        );
+        requireValue(sameFile(parent, await plugins.fs.lstat(this.directory)), 'unsafe_path');
+        const rechecked = await this.unit.inspect();
+        requireValue(JSON.stringify(rechecked) === JSON.stringify(before), 'changed');
+        await this.admit(rechecked);
+        await plugins.fs.rename(temporary, this.path);
+        temporary = undefined;
+        await this.flushDirectory(parent);
+      }
+      try {
+        await this.unit.reloadConfiguration();
+        const after = await this.unit.inspect();
+        requireValue(
+          quiet(after) &&
+            (before.loadState === 'not-found'
+              ? after.loadState === 'loaded' && after.unitFileState === 'disabled'
+              : after.loadState === before.loadState &&
+                after.unitFileState === before.unitFileState),
+          'changed',
+        );
+        const configuration = await this.unit.inspectConfiguration();
+        requireValue(
+          !configuration.needsReload && configuration.dropInPaths === '' &&
+            configuration.fragmentPath === (masked(after) ? '/dev/null' : this.path),
+          'unsafe_unit',
+        );
+        const installed = await this.inspect();
+        requireValue(installed?.sha256 === definition.sha256, 'changed');
+        return Object.freeze({ changed, record: installed!, masked: masked(after) });
+      } catch {
+        throw new SystemdUnitFileError('reload_failed');
+      }
+    } catch (error) {
+      if (error instanceof SystemdUnitFileError) throw error;
+      throw new SystemdUnitFileError('write_failed');
+    } finally {
+      try {
+        if (temporary && temporaryInfo) {
+          const named = await plugins.fs.lstat(temporary);
+          requireValue(sameFile(temporaryInfo, named), 'unsafe_path');
+          await plugins.fs.unlink(temporary);
+        }
+      } finally {
+        this.busy = false;
+      }
+    }
+  }
+
+  private async admit(state: ISystemdUnitState): Promise<void> {
+    requireValue(
+      quiet(state) && (masked(state) ||
+        state.loadState === 'loaded' &&
+          ['enabled', 'enabled-runtime', 'disabled'].includes(state.unitFileState) ||
+        state.loadState === 'not-found' && state.unitFileState === ''),
+      'unsafe_unit',
+    );
+    const configuration = await this.unit.inspectConfiguration();
+    requireValue(
+      configuration.dropInPaths === '' && configuration.fragmentPath ===
+          (masked(state) ? '/dev/null' : state.loadState === 'not-found' ? '' : this.path),
+      'unsafe_unit',
+    );
+  }
+
+  private async directories(create: boolean): Promise<boolean> {
+    requireValue(process.platform === 'linux' && process.getuid?.() === this.uid, 'unsafe_path');
+    let directory = '/';
+    for (const part of this.directory.split('/').filter(Boolean)) {
+      directory = plugins.path.join(directory, part);
+      let info: plugins.Stats;
+      try {
+        info = await plugins.fs.lstat(directory);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+        if (!create) return false;
+        await plugins.fs.mkdir(directory, { mode: 0o755 });
+        const parent = await plugins.fs.open(
+          plugins.path.dirname(directory),
+          plugins.fsConstants.O_RDONLY | plugins.fsConstants.O_DIRECTORY |
+            plugins.fsConstants.O_NOFOLLOW,
+        );
+        try {
+          await parent.sync();
+        } finally {
+          await parent.close();
+        }
+        info = await plugins.fs.lstat(directory);
+      }
+      requireValue(
+        info.isDirectory() && !info.isSymbolicLink() && [0, this.uid].includes(info.uid) &&
+          ((info.mode & 0o022) === 0 || directory === '/tmp' && info.uid === 0 &&
+              (info.mode & 0o7777) === 0o1777),
+        'unsafe_path',
+      );
+    }
+    return true;
+  }
+
+  private async read(path: string): Promise<{ bytes: Buffer; info: plugins.Stats } | null> {
+    let file: Awaited<ReturnType<typeof plugins.fs.open>>;
+    try {
+      file = await plugins.fs.open(
+        path,
+        plugins.fsConstants.O_RDONLY | plugins.fsConstants.O_NOFOLLOW |
+          plugins.fsConstants.O_NONBLOCK,
+      );
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+      throw new SystemdUnitFileError('unsafe_path');
+    }
+    try {
+      const info = await file.stat();
+      requireValue(
+        info.isFile() && info.uid === this.uid && info.nlink === 1 &&
+          (info.mode & 0o7777) === 0o644 && info.size <= 16384,
+        'unsafe_path',
+      );
+      const bytes = Buffer.alloc(16385);
+      let size = 0;
+      for (;;) {
+        const result = await file.read(bytes, size, bytes.length - size, size);
+        if (result.bytesRead === 0) break;
+        size += result.bytesRead;
+        requireValue(size <= 16384, 'unsafe_path');
+      }
+      const after = await file.stat(), named = await plugins.fs.lstat(path);
+      requireValue(
+        sameFile(info, named) && !named.isSymbolicLink() && after.size === size &&
+          info.size === after.size && info.mtimeMs === after.mtimeMs &&
+          info.ctimeMs === after.ctimeMs,
+        'changed',
+      );
+      return { bytes: bytes.subarray(0, size), info };
+    } finally {
+      await file.close();
+    }
+  }
+
+  private async create(path: string, bytes: Uint8Array): Promise<void> {
+    const file = await plugins.fs.open(
+      path,
+      plugins.fsConstants.O_CREAT | plugins.fsConstants.O_EXCL |
+        plugins.fsConstants.O_WRONLY | plugins.fsConstants.O_NOFOLLOW,
+      0o644,
+    );
+    let created: plugins.Stats | undefined;
+    try {
+      try {
+        created = await file.stat();
+        await file.chmod(0o644);
+        await file.writeFile(bytes);
+        await file.sync();
+      } finally {
+        await file.close();
+      }
+    } catch (error) {
+      if (created) {
+        requireValue(sameFile(created, await plugins.fs.lstat(path)), 'unsafe_path');
+        await plugins.fs.unlink(path);
+      }
+      throw error;
+    }
+  }
+
+  private async flushDirectory(expected: plugins.Stats): Promise<void> {
+    const directory = await plugins.fs.open(
+      this.directory,
+      plugins.fsConstants.O_RDONLY |
+        plugins.fsConstants.O_DIRECTORY | plugins.fsConstants.O_NOFOLLOW,
+    );
+    try {
+      requireValue(sameFile(expected, await directory.stat()), 'unsafe_path');
+      await directory.sync();
+    } finally {
+      await directory.close();
+    }
+  }
+}

package/ts/index.ts

@@ -1,2 +1,5 @@
 export * from './smartdaemon.classes.smartdaemon.js';
 export * from './smartdaemon.classes.service.js';
+export * from './classes.systemdunit.js';
+export * from './classes.systemdservicedefinition.js';
+export * from './classes.systemdunitfile.js';

package/ts/smartdaemon.plugins.ts

@@ -1,7 +1,12 @@
 // node native scope
 import * as path from 'path';
+import * as childProcess from 'node:child_process';
+import * as fs from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import * as crypto from 'node:crypto';
+export type { Stats } from 'node:fs';
 
-export { path };
+export { path, childProcess, fs, fsConstants, crypto };
 
 // @pushrocks scope
 import * as lik from '@push.rocks/lik';

package/readme.hints.md

@@ -1 +0,0 @@
-