@push.rocks/smartdaemon 2.7.1 → 2.8.0

package/ts/systemd.userenvironment.ts

@@ -0,0 +1,63 @@
+import * as plugins from './smartdaemon.plugins.js';
+
+/**
+ * The calling process's user-manager environment, captured once at construction so a unit file
+ * and the unit it drives read the same values. Nothing here is validated at capture: each value
+ * is checked by the operation that reads it, so a malformed variable that an operation never
+ * reads cannot stop that operation.
+ */
+export interface ISystemdUserEnvironment {
+  /** The account's home directory; absent when the calling uid has no passwd entry. */
+  readonly homeDirectory?: string;
+  /** A non-empty XDG_CONFIG_HOME. */
+  readonly configDirectory?: string;
+  /** A non-empty XDG_DATA_HOME. */
+  readonly dataDirectory?: string;
+  /** The explicit option, otherwise a non-empty XDG_RUNTIME_DIR. */
+  readonly runtimeDirectory?: string;
+}
+
+/** The environment every user-manager call passes to systemctl, once it has been admitted. */
+export type TSystemdUserManagerEnvironment = ISystemdUserEnvironment & {
+  readonly homeDirectory: string;
+  readonly runtimeDirectory: string;
+};
+
+/** Absolute, normalized, bounded and printable; never the root itself or a trailing slash. */
+export const isSafeDirectory = (value: unknown): value is string =>
+  typeof value === 'string' && value !== '/' && plugins.path.isAbsolute(value) &&
+  plugins.path.normalize(value) === value && !value.endsWith('/') &&
+  value.length <= 4000 && !/[\x00-\x1f\x7f]/.test(value);
+
+/**
+ * An empty XDG variable counts as unset, as the XDG base directory specification defines. An
+ * explicit runtime directory option is never reinterpreted, so an empty option stays malformed.
+ */
+export const captureUserEnvironment = (
+  runtimeDirectoryOption: string | undefined,
+): ISystemdUserEnvironment => {
+  let homeDirectory: string | undefined;
+  try {
+    homeDirectory = plugins.os.userInfo().homedir;
+  } catch {
+    // os.userInfo() throws for a uid without a passwd entry. The home directory is then absent,
+    // and every operation that reads it refuses with its own invalid_options code.
+  }
+  return Object.freeze({
+    homeDirectory,
+    configDirectory: process.env.XDG_CONFIG_HOME || undefined,
+    dataDirectory: process.env.XDG_DATA_HOME || undefined,
+    runtimeDirectory: runtimeDirectoryOption ?? (process.env.XDG_RUNTIME_DIR || undefined),
+  });
+};
+
+/**
+ * Every call that reaches the user manager passes the runtime and home directories and any set
+ * XDG config/data roots to systemctl, so all of them must be well formed before the first call.
+ */
+export const isUserManagerEnvironment = (
+  environment: ISystemdUserEnvironment,
+): environment is TSystemdUserManagerEnvironment =>
+  isSafeDirectory(environment.runtimeDirectory) && isSafeDirectory(environment.homeDirectory) &&
+  (environment.configDirectory === undefined || isSafeDirectory(environment.configDirectory)) &&
+  (environment.dataDirectory === undefined || isSafeDirectory(environment.dataDirectory));