@push.rocks/smartdaemon 2.7.2 → 2.9.0

package/ts/classes.systemdunitfile.ts

@@ -37,14 +37,65 @@ export class SystemdUnitFileError extends Error {
       | 'unsafe_unit'
       | 'write_failed'
       | 'reload_failed',
+    options?: ErrorOptions,
   ) {
-    super(`Systemd unit definition installation failed: ${code}.`);
+    super(`Systemd unit definition installation failed: ${code}.`, options);
     this.name = 'SystemdUnitFileError';
   }
 }
-const requireValue = (value: unknown, code: SystemdUnitFileError['code']): void => {
+/** Why a path was refused with `unsafe_path`. */
+export type TSystemdUnitFileUnsafePathReason =
+  /** The process is not running on Linux. */
+  | 'unsupported_platform'
+  /** The process does not run as the uid that must own the unit directory and file. */
+  | 'foreign_process'
+  /** The unit directory or one of its ancestors is a symbolic link, or the unit file is one. */
+  | 'symlink'
+  /** The unit directory or one of its ancestors exists but is not a directory. */
+  | 'not_directory'
+  /** A directory is owned by neither root nor the expected uid, or the unit file not by the expected uid. */
+  | 'foreign_owner'
+  /** A directory is group- or world-writable; only a root-owned sticky mode-1777 `/tmp` is admitted. */
+  | 'group_or_world_writable'
+  /** The unit file exists but cannot be opened for reading. */
+  | 'unreadable'
+  /** The unit file is not a regular file. */
+  | 'not_regular_file'
+  /** The unit file has more than one hard link. */
+  | 'hard_linked'
+  /** The unit file's mode is not exactly 0644. */
+  | 'wrong_mode'
+  /** The unit file is larger than 16384 bytes. */
+  | 'too_large'
+  /** A checked directory or file was replaced by another between two of its own checks. */
+  | 'replaced';
+/** Every `unsafe_path` refusal: names the offending path and why it was refused. */
+export class SystemdUnitFileUnsafePathError extends SystemdUnitFileError {
+  declare public readonly code: 'unsafe_path';
+
+  constructor(
+    public readonly path: string,
+    public readonly reason: TSystemdUnitFileUnsafePathReason,
+    options?: ErrorOptions,
+  ) {
+    super('unsafe_path', options);
+    this.message = `Systemd unit definition installation failed: unsafe_path (${reason}: ${path}).`;
+    this.name = 'SystemdUnitFileUnsafePathError';
+  }
+}
+const requireValue = (
+  value: unknown,
+  code: Exclude<SystemdUnitFileError['code'], 'unsafe_path'>,
+): void => {
   if (!value) throw new SystemdUnitFileError(code);
 };
+const requireSafePath = (
+  value: unknown,
+  path: string,
+  reason: TSystemdUnitFileUnsafePathReason,
+): void => {
+  if (!value) throw new SystemdUnitFileUnsafePathError(path, reason);
+};
 const digest = (bytes: Uint8Array) =>
   plugins.crypto.createHash('sha256').update(bytes).digest('hex');
 const quiet = (state: ISystemdUnitState) =>
@@ -195,7 +246,9 @@ export class SystemdUnitFile {
             (!current || previous && sameFile(current.info, previous.info)),
           'changed',
         );
-        requireValue(sameFile(parent, await plugins.fs.lstat(this.directory)), 'unsafe_path');
+        requireSafePath(
+          sameFile(parent, await plugins.fs.lstat(this.directory)), this.directory, 'replaced',
+        );
         const rechecked = await this.unit.inspect();
         requireValue(JSON.stringify(rechecked) === JSON.stringify(before), 'changed');
         const recheckedConfiguration = await this.admit(rechecked, maskDirectories);
@@ -240,7 +293,7 @@ export class SystemdUnitFile {
       try {
         if (temporary && temporaryInfo) {
           const named = await plugins.fs.lstat(temporary);
-          requireValue(sameFile(temporaryInfo, named), 'unsafe_path');
+          requireSafePath(sameFile(temporaryInfo, named), temporary, 'replaced');
           await plugins.fs.unlink(temporary);
         }
       } finally {
@@ -276,7 +329,8 @@ export class SystemdUnitFile {
   }
 
   private async directories(create: boolean): Promise<boolean> {
-    requireValue(process.platform === 'linux' && process.getuid?.() === this.uid, 'unsafe_path');
+    requireSafePath(process.platform === 'linux', this.directory, 'unsupported_platform');
+    requireSafePath(process.getuid?.() === this.uid, this.directory, 'foreign_process');
     let directory = '/';
     for (const part of this.directory.split('/').filter(Boolean)) {
       directory = plugins.path.join(directory, part);
@@ -299,11 +353,14 @@ export class SystemdUnitFile {
         }
         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',
+      requireSafePath(!info.isSymbolicLink(), directory, 'symlink');
+      requireSafePath(info.isDirectory(), directory, 'not_directory');
+      requireSafePath([0, this.uid].includes(info.uid), directory, 'foreign_owner');
+      requireSafePath(
+        (info.mode & 0o022) === 0 ||
+          directory === '/tmp' && info.uid === 0 && (info.mode & 0o7777) === 0o1777,
+        directory,
+        'group_or_world_writable',
       );
     }
     return true;
@@ -318,23 +375,27 @@ export class SystemdUnitFile {
           plugins.fsConstants.O_NONBLOCK,
       );
     } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
-      throw new SystemdUnitFileError('unsafe_path');
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT') return null;
+      // O_NOFOLLOW refuses a symbolic link as the final component with ELOOP.
+      throw new SystemdUnitFileUnsafePathError(
+        path, code === 'ELOOP' ? 'symlink' : 'unreadable', { cause: error },
+      );
     }
     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',
-      );
+      requireSafePath(info.isFile(), path, 'not_regular_file');
+      requireSafePath(info.uid === this.uid, path, 'foreign_owner');
+      requireSafePath(info.nlink === 1, path, 'hard_linked');
+      requireSafePath((info.mode & 0o7777) === 0o644, path, 'wrong_mode');
+      requireSafePath(info.size <= 16384, path, 'too_large');
       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');
+        requireSafePath(size <= 16384, path, 'too_large');
       }
       const after = await file.stat(), named = await plugins.fs.lstat(path);
       requireValue(
@@ -368,7 +429,7 @@ export class SystemdUnitFile {
       }
     } catch (error) {
       if (created) {
-        requireValue(sameFile(created, await plugins.fs.lstat(path)), 'unsafe_path');
+        requireSafePath(sameFile(created, await plugins.fs.lstat(path)), path, 'replaced');
         await plugins.fs.unlink(path);
       }
       throw error;
@@ -382,7 +443,7 @@ export class SystemdUnitFile {
         plugins.fsConstants.O_DIRECTORY | plugins.fsConstants.O_NOFOLLOW,
     );
     try {
-      requireValue(sameFile(expected, await directory.stat()), 'unsafe_path');
+      requireSafePath(sameFile(expected, await directory.stat()), this.directory, 'replaced');
       await directory.sync();
     } finally {
       await directory.close();

package/ts/systemd.definition.ts

@@ -6,6 +6,18 @@ export interface ISystemdServiceStartup {
   timeoutStartSeconds: number;
 }
 
+/**
+ * Ready when a process admitted by `notifyAccess` sends `READY=1`. `NotifyAccess=none` is not
+ * offered: systemd would discard every notification and the start could only time out.
+ */
+export interface ISystemdServiceNotifyStartup {
+  type: 'notify';
+  notifyAccess: 'main' | 'exec' | 'all';
+  timeoutStartSeconds: number;
+}
+
+export type TSystemdServiceStartup = ISystemdServiceStartup | ISystemdServiceNotifyStartup;
+
 /** Complete literal relations. System services always retain After=local-fs.target. */
 export interface ISystemdServiceDependencies {
   defaultDependencies: boolean;
@@ -24,16 +36,17 @@ export interface ISystemdServiceInstallTargets {
 
 /** Internal validated renderer; no systemd/process/filesystem effects. */
 export const renderServiceRelations = (options: {
-  startup?: ISystemdServiceStartup;
+  startup?: TSystemdServiceStartup;
   dependencies?: ISystemdServiceDependencies;
   install?: ISystemdServiceInstallTargets;
 }, unitName: string, restart: string, scope: 'system' | 'user', fail: () => never): {
   unit: string[]; service: string[]; install: string[];
 } => {
   const requireValue = (value: unknown): void => { if (!value) fail(); };
+  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 => {
-    requireValue(value !== null && typeof value === 'object' && !plugins.util.types.isProxy(value)
-      && Object.getPrototypeOf(value) === Object.prototype);
+    plain(value);
     const actual = Reflect.ownKeys(value as object);
     requireValue(actual.length === keys.length && actual.every(key => typeof key === 'string' && keys.includes(key)
       && Object.getOwnPropertyDescriptor(value, key)?.enumerable && 'value' in Object.getOwnPropertyDescriptor(value, key)!));
@@ -62,10 +75,19 @@ export const renderServiceRelations = (options: {
   };
   if (options.startup !== undefined) {
     const value = options.startup;
-    record(value, ['type', 'remainAfterExit', 'timeoutStartSeconds']);
-    requireValue(value.type === 'oneshot' && typeof value.remainAfterExit === 'boolean' && restart !== 'always'
-      && Number.isSafeInteger(value.timeoutStartSeconds) && value.timeoutStartSeconds >= 1 && value.timeoutStartSeconds <= 600);
-    result.service = ['Type=oneshot', `RemainAfterExit=${value.remainAfterExit ? 'yes' : 'no'}`, `TimeoutStartSec=${value.timeoutStartSeconds}s`];
+    plain(value);
+    // Select the shape from the data descriptor so no accessor runs before record() refuses it.
+    const kind = Object.getOwnPropertyDescriptor(value, 'type');
+    record(value, kind !== undefined && 'value' in kind && kind.value === 'notify'
+      ? ['type', 'notifyAccess', 'timeoutStartSeconds'] : ['type', 'remainAfterExit', 'timeoutStartSeconds']);
+    requireValue(Number.isSafeInteger(value.timeoutStartSeconds) && value.timeoutStartSeconds >= 1 && value.timeoutStartSeconds <= 600);
+    if (value.type === 'notify') {
+      requireValue(['main', 'exec', 'all'].includes(value.notifyAccess));
+      result.service = ['Type=notify', `NotifyAccess=${value.notifyAccess}`, `TimeoutStartSec=${value.timeoutStartSeconds}s`];
+    } else {
+      requireValue(value.type === 'oneshot' && typeof value.remainAfterExit === 'boolean' && restart !== 'always');
+      result.service = ['Type=oneshot', `RemainAfterExit=${value.remainAfterExit ? 'yes' : 'no'}`, `TimeoutStartSec=${value.timeoutStartSeconds}s`];
+    }
   }
   if (options.dependencies !== undefined) {
     const value = options.dependencies;