@push.rocks/smartdaemon 2.12.0 → 2.14.0

package/ts/classes.systemdservicedefinition.ts

@@ -1,8 +1,11 @@
 import * as plugins from './smartdaemon.plugins.js';
-import { environmentByteLimit, environmentVariableLimit, isCleanText, renderServiceRelations, type TSystemdServiceStartup,
-  type ISystemdServiceDependencies, type ISystemdServiceInstallTargets } from './systemd.definition.js';
+import { environmentByteLimit, environmentVariableLimit, isCleanText, renderServiceRelations, systemdAddressFamilies,
+  systemdCapabilities, type TSystemdServiceStartup, type ISystemdServiceDependencies, type ISystemdServiceInstallTargets,
+  type ISystemdServiceCredential, type TSystemdCapability, type TSystemdAddressFamily } from './systemd.definition.js';
 export type { ISystemdServiceStartup, ISystemdServiceNotifyStartup, TSystemdServiceStartup,
-  ISystemdServiceDependencies, ISystemdServiceInstallTargets } from './systemd.definition.js';
+  ISystemdServiceDependencies, ISystemdServiceInstallTargets, ISystemdServiceCredential, TSystemdCapability,
+  TSystemdAddressFamily } from './systemd.definition.js';
+export { systemdCapabilities, systemdAddressFamilies } from './systemd.definition.js';
 
 interface ISystemdServiceDefinitionBaseOptions {
   unitName: string;
@@ -33,6 +36,53 @@ interface ISystemdServiceDefinitionBaseOptions {
    * 64 variables and 8192 UTF-8 bytes of `NAME=value` in total. They are taken literally: `%` is escaped, and `Environment=` never expands `$`.
    */
   environment?: Readonly<Record<string, string>>;
+  /**
+   * System scope only. Runs the service as a transient user and group allocated at start
+   * (`DynamicUser=`), named by `user` and `group`, which then must not be `root` and have at most
+   * 31 characters. Systemd enforces `ProtectSystem=strict`, `PrivateTmp=`, `NoNewPrivileges=` and
+   * `RestrictSUIDSGID=` for such a service, so a definition that weakens any of them is refused.
+   */
+  dynamicUser?: boolean;
+  /** System scope only. Credentials read in plaintext, one `LoadCredential=` line each, ordered by name. */
+  loadCredentials?: readonly ISystemdServiceCredential[];
+  /** System scope only. Credentials sealed with `systemd-creds encrypt`, one `LoadCredentialEncrypted=` line each, ordered by name. */
+  loadCredentialsEncrypted?: readonly ISystemdServiceCredential[];
+  /** System scope only (`NoNewPrivileges=`). */
+  noNewPrivileges?: boolean;
+  /** System scope only (`ProtectSystem=`): `true` mounts `/usr` and the boot loader read-only, `'full'` also `/etc`, `'strict'` the whole file system but the API file systems. */
+  protectSystem?: boolean | 'full' | 'strict';
+  /** System scope only (`ProtectHome=`). */
+  protectHome?: boolean | 'read-only' | 'tmpfs';
+  /** System scope only (`PrivateTmp=`). */
+  privateTmp?: boolean;
+  /** System scope only (`PrivateDevices=`). */
+  privateDevices?: boolean;
+  /** System scope only (`ProtectKernelTunables=`). */
+  protectKernelTunables?: boolean;
+  /** System scope only (`ProtectKernelModules=`). */
+  protectKernelModules?: boolean;
+  /** System scope only (`ProtectKernelLogs=`). */
+  protectKernelLogs?: boolean;
+  /** System scope only (`ProtectControlGroups=`). */
+  protectControlGroups?: boolean;
+  /** System scope only (`ProtectClock=`). */
+  protectClock?: boolean;
+  /** System scope only (`ProtectHostname=`). */
+  protectHostname?: boolean;
+  /** System scope only (`RestrictNamespaces=`): `true` forbids creating every kind of namespace. */
+  restrictNamespaces?: boolean;
+  /** System scope only (`RestrictRealtime=`). */
+  restrictRealtime?: boolean;
+  /** System scope only (`RestrictSUIDSGID=`). */
+  restrictSUIDSGID?: boolean;
+  /** System scope only (`LockPersonality=`). */
+  lockPersonality?: boolean;
+  /** System scope only. The only capabilities the service's processes can ever hold (`CapabilityBoundingSet=`); empty drops all. */
+  capabilityBoundingSet?: readonly TSystemdCapability[];
+  /** System scope only. Capabilities a non-root service's processes receive (`AmbientCapabilities=`); within `capabilityBoundingSet` when both are given. */
+  ambientCapabilities?: readonly TSystemdCapability[];
+  /** System scope only. The only socket families the service may create (`RestrictAddressFamilies=`); at least one, and `AF_UNIX` for a notify service. */
+  restrictAddressFamilies?: readonly TSystemdAddressFamily[];
 }
 
 export type ISystemdServiceDefinitionOptions = ISystemdServiceDefinitionBaseOptions & (
@@ -40,13 +90,43 @@ export type ISystemdServiceDefinitionOptions = ISystemdServiceDefinitionBaseOpti
   { scope: 'user'; user?: never; group?: never }
 );
 
+/**
+ * The option a refusal names: a key of the definition, or `'options'` for the definition object
+ * itself (not a plain object, an unknown or accessor key, or a unit over 16384 bytes).
+ */
+export type TSystemdServiceDefinitionOption = keyof ISystemdServiceDefinitionOptions | 'options';
+
 export class SystemdServiceDefinitionError extends Error {
-  constructor() {
-    super('Invalid direct systemd service definition.');
+  public readonly option: TSystemdServiceDefinitionOption;
+
+  constructor(option: TSystemdServiceDefinitionOption) {
+    super(`Invalid direct systemd service definition: ${option}.`);
     this.name = 'SystemdServiceDefinitionError';
+    this.option = option;
   }
 }
 
+/** Sandboxing switches in their rendering order, each with its directive. */
+const sandboxSwitches = [
+  ['privateTmp', 'PrivateTmp'],
+  ['privateDevices', 'PrivateDevices'],
+  ['protectKernelTunables', 'ProtectKernelTunables'],
+  ['protectKernelModules', 'ProtectKernelModules'],
+  ['protectKernelLogs', 'ProtectKernelLogs'],
+  ['protectControlGroups', 'ProtectControlGroups'],
+  ['protectClock', 'ProtectClock'],
+  ['protectHostname', 'ProtectHostname'],
+  ['restrictNamespaces', 'RestrictNamespaces'],
+  ['restrictRealtime', 'RestrictRealtime'],
+  ['restrictSUIDSGID', 'RestrictSUIDSGID'],
+  ['lockPersonality', 'LockPersonality'],
+] as const;
+
+/** Options a user manager's service cannot carry: they need the system manager's privileges. */
+const systemOnlyOptions = ['dynamicUser', 'loadCredentials', 'loadCredentialsEncrypted', 'noNewPrivileges',
+  'protectSystem', 'protectHome', ...sandboxSwitches.map(([option]) => option), 'capabilityBoundingSet',
+  'ambientCapabilities', 'restrictAddressFamilies'] as const;
+
 /** Literal direct-execution definition; never introduces a shell or environment expansion. */
 export class SystemdServiceDefinition {
   public readonly unitName: string;
@@ -55,26 +135,27 @@ export class SystemdServiceDefinition {
   public readonly sha256: string;
 
   constructor(options: ISystemdServiceDefinitionOptions) {
-    const requireValue = (value: unknown): void => {
-      if (!value) throw new SystemdServiceDefinitionError();
+    const fail = (option: TSystemdServiceDefinitionOption): never => {
+      throw new SystemdServiceDefinitionError(option);
+    };
+    const requireValue = (value: unknown, option: TSystemdServiceDefinitionOption): void => {
+      if (!value) fail(option);
     };
     requireValue(options && !plugins.util.types.isProxy(options) &&
-      Object.getPrototypeOf(options) === Object.prototype);
+      Object.getPrototypeOf(options) === Object.prototype, 'options');
     const scopeDescriptor = Object.getOwnPropertyDescriptor(options, 'scope');
     requireValue(scopeDescriptor === undefined ||
-      scopeDescriptor.enumerable && 'value' in scopeDescriptor);
+      scopeDescriptor.enumerable && 'value' in scopeDescriptor, 'scope');
     const scopeValue: unknown = scopeDescriptor?.value ?? 'system';
-    if (scopeValue !== 'system' && scopeValue !== 'user') {
-      throw new SystemdServiceDefinitionError();
-    }
-    const scope = scopeValue;
+    if (scopeValue !== 'system' && scopeValue !== 'user') fail('scope');
+    const scope = scopeValue as 'system' | 'user';
     // Systemd ignores an assignment whose text is not clean UTF-8, leaving the unit unloadable.
     const text = (value: unknown, maximum = 4096): value is string =>
       typeof value === 'string' && value.length <= maximum && isCleanText(value);
-    const absolute = (value: unknown) =>
+    const absolute = (value: unknown): value is string =>
       text(value) && plugins.path.isAbsolute(value) &&
       plugins.path.normalize(value) === value;
-    const keys = [
+    const keys: TSystemdServiceDefinitionOption[] = [
       'unitName',
       'description',
       'executable',
@@ -83,31 +164,40 @@ export class SystemdServiceDefinition {
       'restart',
       'killMode',
       'timeoutStopSeconds',
-      ...(scope === 'system' ? ['user', 'group'] : []),
+      ...(scope === 'system' ? ['user', 'group'] as const : []),
     ];
-    const optionalKeys = ['scope', 'startup', 'dependencies', 'install', 'restartSeconds', 'delegate',
-      'limitNoFile', 'tasksMax', 'oomScoreAdjust', 'environment'];
-    requireValue(
-      Reflect.ownKeys(options).every(key => typeof key === 'string' && [...keys, ...optionalKeys].includes(key)
-          && Object.getOwnPropertyDescriptor(options, key)?.enumerable && 'value' in Object.getOwnPropertyDescriptor(options, key)!) && keys.every((key) => {
-          const descriptor = Object.getOwnPropertyDescriptor(options, key);
-          return descriptor && 'value' in descriptor;
-        }),
-    );
+    const optionalKeys: TSystemdServiceDefinitionOption[] = ['scope', 'startup', 'dependencies', 'install',
+      'restartSeconds', 'delegate', 'limitNoFile', 'tasksMax', 'oomScoreAdjust', 'environment',
+      ...systemOnlyOptions];
+    // Every own key is a known option held by an enumerable data property, so no accessor or trap runs.
+    for (const key of Reflect.ownKeys(options)) {
+      requireValue(typeof key === 'string' && [...keys, ...optionalKeys, 'user', 'group'].includes(key as never), 'options');
+      const option = key as TSystemdServiceDefinitionOption;
+      const descriptor = Object.getOwnPropertyDescriptor(options, key);
+      requireValue(keys.includes(option) || optionalKeys.includes(option), option);
+      requireValue(descriptor?.enumerable && 'value' in descriptor, option);
+    }
+    for (const key of keys) requireValue(Object.getOwnPropertyDescriptor(options, key), key);
     requireValue(
       typeof options.unitName === 'string' &&
         /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,230}\.service$/.test(options.unitName),
+      'unitName',
     );
     requireValue(
       text(options.description, 1024) && options.description.length > 0 &&
         options.description.trim() === options.description && !options.description.includes('\\'),
+      'description',
     );
     requireValue(
       absolute(options.executable) && options.executable !== '/' &&
-        !/[\\"']/.test(options.executable) && !options.executable.endsWith('/') &&
-        absolute(options.workingDirectory) &&
+        !/[\\"']/.test(options.executable) && !options.executable.endsWith('/'),
+      'executable',
+    );
+    requireValue(
+      absolute(options.workingDirectory) &&
         options.workingDirectory.trim() === options.workingDirectory &&
         !options.workingDirectory.includes('\\'),
+      'workingDirectory',
     );
     requireValue(
       Array.isArray(options.args) && !plugins.util.types.isProxy(options.args) && Object.getPrototypeOf(options.args) === Array.prototype &&
@@ -118,43 +208,44 @@ export class SystemdServiceDefinition {
           (_, index) => Object.getOwnPropertyDescriptor(options.args, String(index)),
         )
           .every((descriptor) => descriptor && 'value' in descriptor && text(descriptor.value)),
+      'args',
     );
     if (scope === 'system') {
-      requireValue(
-        [options.user, options.group].every((value) =>
-          typeof value === 'string' && /^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$/.test(value)
-        ),
-      );
+      for (const key of ['user', 'group'] as const) {
+        requireValue(typeof options[key] === 'string' && /^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$/.test(options[key]), key);
+      }
     }
+    requireValue(['no', 'on-failure', 'always'].includes(options.restart), 'restart');
+    requireValue(['mixed', 'control-group', 'process'].includes(options.killMode), 'killMode');
     requireValue(
-      ['no', 'on-failure', 'always'].includes(options.restart) &&
-        ['mixed', 'control-group', 'process'].includes(options.killMode) &&
-        Number.isSafeInteger(options.timeoutStopSeconds) &&
+      Number.isSafeInteger(options.timeoutStopSeconds) &&
         options.timeoutStopSeconds >= 1 && options.timeoutStopSeconds <= 600,
+      'timeoutStopSeconds',
     );
     const integer = (value: unknown, minimum: number, maximum: number): value is number =>
       Number.isSafeInteger(value) && (value as number) >= minimum && (value as number) <= maximum;
     const limit = (value: unknown): value is number | 'infinity' =>
       value === 'infinity' || integer(value, 1, Number.MAX_SAFE_INTEGER);
+    const yesNo = (value: boolean) => value ? 'yes' : 'no';
     // Each optional directive is absent unless supplied, so existing definitions keep their bytes.
     const service: string[] = [];
     if (options.restartSeconds !== undefined) {
-      requireValue(integer(options.restartSeconds, 1, 600) && options.restart !== 'no');
+      requireValue(integer(options.restartSeconds, 1, 600) && options.restart !== 'no', 'restartSeconds');
     }
     if (options.delegate !== undefined) {
-      requireValue(typeof options.delegate === 'boolean');
-      service.push(`Delegate=${options.delegate ? 'yes' : 'no'}`);
+      requireValue(typeof options.delegate === 'boolean', 'delegate');
+      service.push(`Delegate=${yesNo(options.delegate)}`);
     }
     if (options.limitNoFile !== undefined) {
-      requireValue(limit(options.limitNoFile));
+      requireValue(limit(options.limitNoFile), 'limitNoFile');
       service.push(`LimitNOFILE=${options.limitNoFile}`);
     }
     if (options.tasksMax !== undefined) {
-      requireValue(limit(options.tasksMax));
+      requireValue(limit(options.tasksMax), 'tasksMax');
       service.push(`TasksMax=${options.tasksMax}`);
     }
     if (options.oomScoreAdjust !== undefined) {
-      requireValue(integer(options.oomScoreAdjust, -1000, 1000));
+      requireValue(integer(options.oomScoreAdjust, -1000, 1000), 'oomScoreAdjust');
       service.push(`OOMScoreAdjust=${options.oomScoreAdjust}`);
     }
     // Quoting and percent/dollar escaping follow systemd.syntax and systemd.service.
@@ -163,26 +254,135 @@ export class SystemdServiceDefinition {
         .replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%')
         .replaceAll('$', () => command ? '$$' : '$') +
       '"';
+    const plainObject = (value: unknown, option: TSystemdServiceDefinitionOption) =>
+      requireValue(value !== null && typeof value === 'object' && !plugins.util.types.isProxy(value) &&
+        Object.getPrototypeOf(value) === Object.prototype, option);
     if (options.environment !== undefined) {
       // Read each variable once through its own data descriptor, so no accessor or trap runs.
       const variables: unknown = options.environment;
-      requireValue(variables !== null && typeof variables === 'object' &&
-        !plugins.util.types.isProxy(variables) && Object.getPrototypeOf(variables) === Object.prototype);
+      plainObject(variables, 'environment');
       const names = Reflect.ownKeys(variables as object);
-      requireValue(names.length <= environmentVariableLimit);
+      requireValue(names.length <= environmentVariableLimit, 'environment');
       const assignments = new Map<string, string>();
       for (const name of names) {
         const descriptor = Object.getOwnPropertyDescriptor(variables, name);
         requireValue(typeof name === 'string' && /^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(name) &&
-          descriptor?.enumerable && 'value' in descriptor && text(descriptor.value));
+          descriptor?.enumerable && 'value' in descriptor && text(descriptor.value), 'environment');
         assignments.set(name as string, `${name as string}=${descriptor!.value as string}`);
       }
-      requireValue(Buffer.byteLength([...assignments.values()].join('')) <= environmentByteLimit);
+      requireValue(Buffer.byteLength([...assignments.values()].join('')) <= environmentByteLimit, 'environment');
       // Environment= unquotes and unescapes each word and expands `%` specifiers, never `$`.
       service.push(...[...assignments.keys()].sort()
         .map((name) => `Environment=${quote(assignments.get(name)!)}`));
     }
-    const relations = renderServiceRelations(options, options.unitName, options.restart, scope, () => { throw new SystemdServiceDefinitionError(); });
+    // Every system-only option is refused by name in a user manager's service.
+    for (const option of systemOnlyOptions) {
+      requireValue(scope === 'system' || options[option] === undefined, option);
+    }
+    /** Reads a plain array once through its data descriptors: distinct items, sorted. */
+    const list = <T>(value: unknown, option: TSystemdServiceDefinitionOption, maximum: number,
+      item: (entry: unknown) => T, identity: (entry: T) => string): T[] => {
+      requireValue(Array.isArray(value) && !plugins.util.types.isProxy(value) &&
+        Object.getPrototypeOf(value) === Array.prototype && value.length <= maximum &&
+        Reflect.ownKeys(value).length === value.length + 1, option);
+      const result = Array.from({ length: (value as unknown[]).length }, (_, index) => {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        requireValue(descriptor?.enumerable && 'value' in descriptor, option);
+        return item(descriptor!.value);
+      });
+      const identities = result.map(identity);
+      requireValue(new Set(identities).size === identities.length, option);
+      return result.sort((left, right) => identity(left) < identity(right) ? -1 : 1);
+    };
+    // Credential names and sources hold no `%`, quote, backslash, whitespace or `:`, so systemd's
+    // `NAME[:SOURCE]` parser and its specifier expansion read them exactly as written.
+    const credentialName = (value: unknown): value is string =>
+      typeof value === 'string' && /^[A-Za-z0-9_@-][A-Za-z0-9_.@-]{0,254}$/.test(value);
+    const credentials = (value: unknown, option: 'loadCredentials' | 'loadCredentialsEncrypted') =>
+      list(value, option, 64, (entry): ISystemdServiceCredential => {
+        plainObject(entry, option);
+        const entryKeys = Reflect.ownKeys(entry as object);
+        requireValue(entryKeys.includes('name') && entryKeys.every((key) => (key === 'name' || key === 'source') &&
+          Object.getOwnPropertyDescriptor(entry, key)?.enumerable &&
+          'value' in Object.getOwnPropertyDescriptor(entry, key)!), option);
+        const { name, source } = entry as Record<'name' | 'source', unknown>;
+        requireValue(credentialName(name), option);
+        if (entryKeys.includes('source')) {
+          requireValue(source !== name && (credentialName(source) || absolute(source) && !source.endsWith('/') &&
+            /^[A-Za-z0-9_.@/+-]+$/.test(source)), option);
+        }
+        return entryKeys.includes('source') ? { name: name as string, source: source as string } : { name: name as string };
+      }, (entry) => entry.name);
+    const plainCredentials = options.loadCredentials === undefined ? [] : credentials(options.loadCredentials, 'loadCredentials');
+    const encryptedCredentials = options.loadCredentialsEncrypted === undefined
+      ? [] : credentials(options.loadCredentialsEncrypted, 'loadCredentialsEncrypted');
+    // Systemd keeps both kinds in one table by name, so a name loads from exactly one of them.
+    requireValue(encryptedCredentials.every((entry) => !plainCredentials.some(({ name }) => name === entry.name)),
+      'loadCredentialsEncrypted');
+    const credential = ({ name, source }: ISystemdServiceCredential) => source === undefined ? name : `${name}:${source}`;
+    service.push(...plainCredentials.map((entry) => `LoadCredential=${credential(entry)}`));
+    service.push(...encryptedCredentials.map((entry) => `LoadCredentialEncrypted=${credential(entry)}`));
+    const dynamicUser = options.dynamicUser;
+    if (dynamicUser !== undefined) {
+      requireValue(typeof dynamicUser === 'boolean', 'dynamicUser');
+      // A static account of the same name would be used instead, so the name must not be root's,
+      // and systemd allocates only names that fit utmp.
+      requireValue(!dynamicUser || [options.user, options.group].every((name) =>
+        name !== 'root' && typeof name === 'string' && name.length <= 31), 'dynamicUser');
+    }
+    // Settings systemd forces on for a dynamic user, so the unit never states a weaker one.
+    const forced = (option: TSystemdServiceDefinitionOption, weakened: boolean) =>
+      requireValue(!(dynamicUser === true && weakened), option);
+    if (options.noNewPrivileges !== undefined) {
+      requireValue(typeof options.noNewPrivileges === 'boolean', 'noNewPrivileges');
+      forced('noNewPrivileges', !options.noNewPrivileges);
+      service.push(`NoNewPrivileges=${yesNo(options.noNewPrivileges)}`);
+    }
+    if (options.protectSystem !== undefined) {
+      requireValue([true, false, 'full', 'strict'].includes(options.protectSystem), 'protectSystem');
+      forced('protectSystem', options.protectSystem !== 'strict');
+      service.push(`ProtectSystem=${typeof options.protectSystem === 'boolean'
+        ? yesNo(options.protectSystem) : options.protectSystem}`);
+    }
+    if (options.protectHome !== undefined) {
+      requireValue([true, false, 'read-only', 'tmpfs'].includes(options.protectHome), 'protectHome');
+      forced('protectHome', options.protectHome === false);
+      service.push(`ProtectHome=${typeof options.protectHome === 'boolean'
+        ? yesNo(options.protectHome) : options.protectHome}`);
+    }
+    for (const [option, directive] of sandboxSwitches) {
+      const value = options[option];
+      if (value === undefined) continue;
+      requireValue(typeof value === 'boolean', option);
+      forced(option, (option === 'privateTmp' || option === 'restrictSUIDSGID') && !value);
+      service.push(`${directive}=${yesNo(value)}`);
+    }
+    const capabilities = (value: unknown, option: 'capabilityBoundingSet' | 'ambientCapabilities') =>
+      list(value, option, systemdCapabilities.length, (entry) => {
+        requireValue((systemdCapabilities as readonly unknown[]).includes(entry), option);
+        return entry as TSystemdCapability;
+      }, (entry) => entry);
+    const bounding = options.capabilityBoundingSet === undefined
+      ? undefined : capabilities(options.capabilityBoundingSet, 'capabilityBoundingSet');
+    const ambient = options.ambientCapabilities === undefined
+      ? undefined : capabilities(options.ambientCapabilities, 'ambientCapabilities');
+    // An ambient capability outside the bounding set would fail every start of the service.
+    requireValue(!bounding || !ambient || ambient.every((entry) => bounding.includes(entry)), 'ambientCapabilities');
+    // An empty CapabilityBoundingSet= empties the bounding set; an empty AmbientCapabilities= grants none.
+    if (bounding) service.push(`CapabilityBoundingSet=${bounding.join(' ')}`);
+    if (ambient) service.push(`AmbientCapabilities=${ambient.join(' ')}`);
+    const families = options.restrictAddressFamilies === undefined ? undefined
+      : list(options.restrictAddressFamilies, 'restrictAddressFamilies', systemdAddressFamilies.length, (entry) => {
+        requireValue((systemdAddressFamilies as readonly unknown[]).includes(entry), 'restrictAddressFamilies');
+        return entry as TSystemdAddressFamily;
+      }, (entry) => entry);
+    // An empty RestrictAddressFamilies= would lift the restriction instead of denying every family.
+    requireValue(!families || families.length > 0, 'restrictAddressFamilies');
+    if (families) service.push(`RestrictAddressFamilies=${families.join(' ')}`);
+    const relations = renderServiceRelations(options, options.unitName, options.restart, scope, fail);
+    // A notify service sends READY=1 over an AF_UNIX socket it creates itself.
+    requireValue(!families || !relations.service.includes('Type=notify') || families.includes('AF_UNIX'),
+      'restrictAddressFamilies');
     this.unitName = options.unitName;
     this.scope = scope;
     this.content = [
@@ -193,6 +393,7 @@ export class SystemdServiceDefinition {
       '[Service]',
       ...relations.service,
       ...(scope === 'system' ? [`User=${options.user}`, `Group=${options.group}`] : []),
+      ...(dynamicUser !== undefined ? [`DynamicUser=${yesNo(dynamicUser)}`] : []),
       `ExecStart=${
         [quote(options.executable), ...options.args.map((value) => quote(value, true))].join(' ')
       }`,
@@ -215,7 +416,7 @@ export class SystemdServiceDefinition {
       ...relations.install,
       '',
     ].join('\n');
-    requireValue(Buffer.byteLength(this.content) <= 16384);
+    requireValue(Buffer.byteLength(this.content) <= 16384, 'options');
     this.sha256 = plugins.crypto.createHash('sha256').update(this.content).digest('hex');
     Object.freeze(this);
   }

package/ts/classes.systemdunit.ts

@@ -35,8 +35,28 @@ export interface ISystemdUnitState {
   readonly controlPid: number;
   readonly controlGroup: string;
   readonly killMode: string;
-  /** Empty when no systemd job is pending; otherwise systemctl's job description. */
+  /** Empty when no systemd job is pending; otherwise the pending job's id as systemctl prints it. */
   readonly job: string;
+  /**
+   * The service's last `STATUS=` notification (`StatusText`), verbatim; empty when it sent none or
+   * cleared it. Text the service chose: UTF-8 without a line break, at most 16 KiB.
+   */
+  readonly statusText: string;
+  /**
+   * The service's `Result`, in systemd's own words: `success`, or why it last failed: `resources`,
+   * `protocol`, `timeout`, `exit-code`, `signal`, `core-dump`, `watchdog`, `start-limit-hit`,
+   * `oom-kill` or `exec-condition` (systemd 255). A newer manager's word is still reported.
+   */
+  readonly result: string;
+}
+
+/** Lifecycle call options. */
+export interface ISystemdUnitJobOptions {
+  /**
+   * Defaults to true: wait for the job to finish. False passes `--no-block`: systemd verifies and
+   * enqueues the job, and the returned snapshot is read while it may still be pending.
+   */
+  wait?: boolean;
 }
 
 export interface ISystemdUnitConfigurationState {
@@ -72,6 +92,8 @@ export interface ISystemdServiceSettings {
   readonly restartMicroseconds: number | 'infinity';
   readonly killMode: string;
   readonly timeoutStopMicroseconds: number | 'infinity';
+  /** `TimeoutStartUSec`. Extensions a service requests with `EXTEND_TIMEOUT_USEC=` are not included. */
+  readonly timeoutStartMicroseconds: number | 'infinity';
   readonly delegate: boolean;
   /** Hard open-file limit (`LimitNOFILE`). */
   readonly limitNoFile: number | 'infinity';
@@ -155,7 +177,8 @@ const parseEnvironment = (text: string): Readonly<Record<string, string>> | unde
  * through shell_maybe_quote(), which backslash-escapes `"`, `\\`, `` ` `` and `$`, so each of the at
  * most environmentByteLimit `NAME=value` bytes prints as at most two and each of the at most
  * environmentVariableLimit words gains two quotes and a separator. The property names and every
- * other requested property, a 239-character unit name included, print in under 1024 bytes.
+ * other requested property, a 239-character unit name included, print in under 1024 bytes. The
+ * next largest is inspect(): systemd keeps a StatusText of at most 16384 bytes, printed verbatim.
  */
 const outputLimit = 2 * environmentByteLimit + 3 * environmentVariableLimit + 1024;
 
@@ -170,8 +193,21 @@ const properties = [
   'ControlGroup',
   'KillMode',
   'Job',
+  'StatusText',
+  'Result',
 ] as const;
 
+/** Arguments preceding the verb; refuses anything but an absent or boolean `wait`. */
+const jobArguments = (optionsArg: ISystemdUnitJobOptions | undefined): string[] => {
+  if (optionsArg === undefined) return [];
+  if (
+    typeof optionsArg !== 'object' || optionsArg === null ||
+    Object.keys(optionsArg).some((key) => key !== 'wait') ||
+    (optionsArg.wait !== undefined && typeof optionsArg.wait !== 'boolean')
+  ) throw new SystemdUnitError('invalid_options');
+  return optionsArg.wait === false ? ['--no-block'] : [];
+};
+
 /** Controls an existing system unit without rewriting its definition or escalating privileges. */
 export class SystemdUnit {
   private readonly unitName: string;
@@ -215,7 +251,8 @@ export class SystemdUnit {
       '--all',
     ]);
     const fields = new Map<string, string>();
-    for (const line of stdout.trimEnd().split('\n')) {
+    // StatusText is printed verbatim, so only the final line break is systemctl's own.
+    for (const line of (stdout.endsWith('\n') ? stdout.slice(0, -1) : stdout).split('\n')) {
       const separator = line.indexOf('=');
       const key = line.slice(0, separator);
       if (separator < 1 || !(properties as readonly string[]).includes(key) || fields.has(key)) {
@@ -226,6 +263,7 @@ export class SystemdUnit {
     if (
       fields.size !== properties.length || fields.get('Id') !== this.unitName ||
       ['LoadState', 'ActiveState', 'SubState'].some((key) => !fields.get(key)) ||
+      !/^[a-z][a-z-]{0,31}$/.test(fields.get('Result')!) ||
       ['MainPID', 'ControlPID'].some((key) =>
         !/^(0|[1-9]\d*)$/.test(fields.get(key)!) || !Number.isSafeInteger(Number(fields.get(key)))
       )
@@ -241,12 +279,17 @@ export class SystemdUnit {
       controlGroup: fields.get('ControlGroup')!,
       killMode: fields.get('KillMode')!,
       job: fields.get('Job')!,
+      statusText: fields.get('StatusText')!,
+      result: fields.get('Result')!,
     });
   }
 
-  /** 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]);
+  /**
+   * Await the systemd job, or with `wait: false` only its enqueueing, then inspect. This does not
+   * enable or unmask the unit.
+   */
+  public async start(optionsArg?: ISystemdUnitJobOptions): Promise<ISystemdUnitState> {
+    await this.command([...jobArguments(optionsArg), 'start', this.unitName]);
     return this.inspect();
   }
 
@@ -283,9 +326,12 @@ export class SystemdUnit {
       requiredBy: units('RequiredBy'), wantedBy: units('WantedBy') });
   }
 
-  /** 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]);
+  /**
+   * Await the systemd job, or with `wait: false` only its enqueueing, then inspect. The snapshot
+   * alone is not an application data-drain proof.
+   */
+  public async stop(optionsArg?: ISystemdUnitJobOptions): Promise<ISystemdUnitState> {
+    await this.command([...jobArguments(optionsArg), 'stop', this.unitName]);
     return this.inspect();
   }
 
@@ -294,7 +340,7 @@ export class SystemdUnit {
     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')) {
+    for (const line of (stdout.endsWith('\n') ? stdout.slice(0, -1) : stdout).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');
@@ -319,7 +365,7 @@ export class SystemdUnit {
    */
   public async inspectServiceSettings(): Promise<ISystemdServiceSettings> {
     const keys = ['Id', 'Type', 'NotifyAccess', 'Restart', 'RestartUSec', 'KillMode', 'TimeoutStopUSec',
-      'Delegate', 'LimitNOFILE', 'LimitNOFILESoft', 'TasksMax', 'OOMScoreAdjust', 'Environment'];
+      'TimeoutStartUSec', 'Delegate', 'LimitNOFILE', 'LimitNOFILESoft', 'TasksMax', 'OOMScoreAdjust', 'Environment'];
     const stdout = await this.command(['show', this.unitName, `--property=${keys.join(',')}`, '--all']);
     const fields = new Map<string, string>();
     for (const line of (stdout.endsWith('\n') ? stdout.slice(0, -1) : stdout).split('\n')) {
@@ -349,6 +395,7 @@ export class SystemdUnit {
       restartMicroseconds: parsed('RestartUSec', parseTimespan),
       killMode: mode('KillMode'),
       timeoutStopMicroseconds: parsed('TimeoutStopUSec', parseTimespan),
+      timeoutStartMicroseconds: parsed('TimeoutStartUSec', parseTimespan),
       delegate: parsed('Delegate', (text) => text === 'yes' ? true : text === 'no' ? false : undefined),
       limitNoFile: parsed('LimitNOFILE', parseLimit),
       limitNoFileSoft: parsed('LimitNOFILESoft', parseLimit),

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);