@push.rocks/smartdaemon 2.11.0 → 2.13.0

package/readme.md

@@ -464,6 +464,93 @@ and `%` doubled, so systemd applies no specifier; `Environment=` never expands `
 taken literally. An empty object renders nothing. Systemd merges these variables over its own
 (`HOME`, `USER`, `INVOCATION_ID`, …), so a name such as `NOTIFY_SOCKET` overrides the manager's value.
 
+#### Credentials, a dynamic user and the sandbox
+
+A system service can receive secrets as systemd credentials instead of variables, run as a
+transient account and be confined. Each option below renders nothing when omitted, so existing
+definitions keep their exact bytes; `false` renders the directive as `no`. A user service refuses
+all of them, since a user manager cannot grant them. `DynamicUser=` follows `Group=`; the others
+follow the `environment` lines in this order:
+
+| Option | Directive | Accepted values |
+| --- | --- | --- |
+| `dynamicUser` | `DynamicUser=` | boolean; with `true`, `user` and `group` name the allocated account |
+| `loadCredentials` | one `LoadCredential=` line per credential, ordered by name | array of `{ name, source? }` |
+| `loadCredentialsEncrypted` | one `LoadCredentialEncrypted=` line per credential, ordered by name | array of `{ name, source? }` |
+| `noNewPrivileges` | `NoNewPrivileges=` | boolean |
+| `protectSystem` | `ProtectSystem=` | boolean, `'full'` or `'strict'` |
+| `protectHome` | `ProtectHome=` | boolean, `'read-only'` or `'tmpfs'` |
+| `privateTmp`, `privateDevices`, `protectKernelTunables`, `protectKernelModules`, `protectKernelLogs`, `protectControlGroups`, `protectClock`, `protectHostname`, `restrictNamespaces`, `restrictRealtime`, `restrictSUIDSGID`, `lockPersonality` | the directive of the same name, in this order | boolean |
+| `capabilityBoundingSet` | `CapabilityBoundingSet=` | distinct capabilities from `systemdCapabilities`, sorted; empty drops every capability |
+| `ambientCapabilities` | `AmbientCapabilities=` | distinct capabilities, sorted; within `capabilityBoundingSet` when both are given |
+| `restrictAddressFamilies` | `RestrictAddressFamilies=` | at least one distinct family of `AF_INET`, `AF_INET6`, `AF_NETLINK`, `AF_PACKET`, `AF_UNIX`, `AF_VSOCK`, sorted; includes `AF_UNIX` for a notify service |
+
+```typescript
+const relay = new SystemdServiceDefinition({
+  unitName: 'relay.service',
+  description: 'Cluster relay',
+  executable: '/opt/relay/current/relay',
+  args: [],
+  workingDirectory: '/opt/relay/current',
+  user: 'relay',
+  group: 'relay',
+  dynamicUser: true,
+  restart: 'always',
+  restartSeconds: 2,
+  killMode: 'mixed',
+  timeoutStopSeconds: 60,
+  dependencies: {
+    defaultDependencies: true,
+    after: ['network-online.target'],
+    before: ['node.service'],
+    requires: [],
+    wants: ['network-online.target'],
+    conflicts: [],
+  },
+  environment: { RELAY_BIND_PORT: '8443' },
+  loadCredentials: [{ name: 'RELAY_AUTHORIZATION' }],
+  noNewPrivileges: true,
+  protectSystem: 'strict',
+  protectHome: true,
+  privateTmp: true,
+  privateDevices: true,
+  capabilityBoundingSet: [],
+  restrictAddressFamilies: ['AF_INET', 'AF_INET6', 'AF_UNIX'],
+});
+// DynamicUser=yes
+// LoadCredential=RELAY_AUTHORIZATION
+// CapabilityBoundingSet=
+// RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+```
+
+A credential's value never appears in the unit, in the service's environment (so child processes
+do not inherit it) or in `systemctl show`: the service reads it from
+`$CREDENTIALS_DIRECTORY/<name>`, readable by the service's user only. `name` is 1–255 characters of
+`[A-Za-z0-9_.@-]`, not starting with `.`. `source` is either an absolute normalized path of
+`[A-Za-z0-9_.@/+-]` characters without a trailing `/` (a file, a directory of files or an `AF_UNIX`
+socket), or a credential name that systemd looks up among its own credentials and then in
+`/etc/credstore/`, `/run/credstore/` and `/usr/lib/credstore/` (for encrypted credentials also the
+`credstore.encrypted` directories). Without `source`, systemd looks up `name` itself, so
+`{ name: 'RELAY_AUTHORIZATION' }` reads `/etc/credstore/RELAY_AUTHORIZATION`; a `source` equal to
+`name` is refused, as it only spells the same lookup twice. These characters need no quoting and
+hold no `%` specifier, `:` separator or escape, so systemd reads each line exactly as written.
+Encrypted credentials are sealed with `systemd-creds encrypt` (host key or TPM2). Systemd keeps both
+kinds in one table by name, so a name appears in at most one list; at most 64 per list. The
+directory search needs systemd 250 or later; an absolute `source` works from systemd 247.
+
+`dynamicUser: true` allocates the account when the service starts. Systemd would use a static
+account of the same name instead, so `user` and `group` must not be `root`, and they have at most
+31 characters, the longest name systemd allocates. For such a service systemd enforces
+`ProtectSystem=strict`, `PrivateTmp=yes`, `NoNewPrivileges=yes`, `RestrictSUIDSGID=yes` and at least
+`ProtectHome=read-only`; a definition that states any of them weaker is refused, so the unit never
+reads as less confined than it is.
+
+Each refusal throws `SystemdServiceDefinitionError`, whose `option` names the offending option (for
+every option of a definition, not only these) and whose message is
+`Invalid direct systemd service definition: <option>.`. `option` is `'options'` for the definition
+object itself: not a plain object, an unknown or accessor key, or a unit over 16384 bytes. No
+refusal carries the offending value.
+
 Optional `dependencies` describes the complete literal runtime relationships:
 
 ```typescript
@@ -605,6 +692,77 @@ other process in the unit survives, so the main process must own their shutdown
 deliberate retention (as with `Delegate=yes` workloads). A successful systemd start still requires application readiness
 verification, and a completed stop alone does not prove database drain.
 
+### Starting a program in its own transient scope
+
+A service that launches a long-lived program keeps that program in its own
+control group, so stopping the service ends the program too, even when the
+program detached itself with `setsid`. `runInTransientScope()` starts a program in
+a new transient scope unit of the calling user's systemd manager instead
+(`systemd-run --user --scope`): the program and every process it starts run in
+that scope and outlive the caller's unit. The call waits for the program's direct
+process and returns its result; a program that daemonizes and exits returns while
+its daemon keeps the scope active, and the scope ends when its last process exits.
+
+```typescript
+import { runInTransientScope, SystemdTransientScopeError } from '@push.rocks/smartdaemon';
+
+try {
+  const result = await runInTransientScope({
+    scope: 'user',
+    description: 'Codex app-server daemon',
+    executable: '/home/owner/.local/bin/codex',
+    args: ['app-server', 'daemon', 'start'],
+    workingDirectory: '/home/owner',
+    environment: { HOME: '/home/owner', CODEX_HOME: '/home/owner/.codex', PATH: '/usr/bin:/bin' },
+  });
+  console.log(result.unitName, result.exitCode, result.stdout);
+} catch (error) {
+  if (error instanceof SystemdTransientScopeError && error.code === 'user_manager_unavailable') {
+    // No user manager: the caller decides how to run the program without one.
+  }
+  throw error;
+}
+```
+
+The result holds the scope's `unitName`, the direct process's `exitCode` (or the
+`signal` that ended it), and its `stdout` and `stderr`, UTF-8 decoded. A failure
+status is a result, not an error. The program is executed directly from an
+absolute `executable` with literal `args`, with no shell, PATH search or `$`
+expansion (systemd 258 expands `$` in a scope's command line unless told not to,
+and the call always passes `--expand-environment=no`), in the absolute
+`workingDirectory`, with stdin on `/dev/null`. Its
+environment is exactly `environment` plus the manager's `XDG_RUNTIME_DIR` and
+systemd's `INVOCATION_ID`: nothing of the calling process is inherited, so pass
+every variable the program needs. `XDG_RUNTIME_DIR`, `INVOCATION_ID` and names
+starting with `SYSTEMD_` or `DBUS_`, which would configure systemd-run itself, are
+refused. `unitName` names the scope (a `.scope` name) and defaults to a unique
+`smartdaemon-<32 hex digits>.scope`; a scope of that name that is still active
+refuses a second start. The literal `description` is the unit's description.
+
+Failures throw `SystemdTransientScopeError` with the scope's `unitName` (null for
+refused options), the `stderr` read so far and one of these codes:
+
+| Code | Meaning |
+| --- | --- |
+| `invalid_options` | Malformed options, or a runtime directory that is not a private directory of the caller |
+| `unsupported_platform` | The process is not running on Linux |
+| `user_manager_unavailable` | No `XDG_RUNTIME_DIR` (or `runtimeDirectory`), a runtime directory that does not exist, or a manager that does not answer `systemctl --user` |
+| `scope_start_failed` | systemd-run exited without reporting the scope running; the program has not run |
+| `timed_out` | The manager probe or the program did not finish and close its output within `commandTimeoutMs` |
+| `output_limit` | The program's stdout or stderr exceeded 1 MiB |
+
+The call completes once the direct process has exited and its stdout and stderr
+have closed, so a daemon must not keep them open (Codex, for example, redirects
+its daemon's output); otherwise the call runs into its timeout. On `timed_out` and
+`output_limit` the direct process is killed and the processes it started stay in
+the scope. `commandTimeoutMs` (default 120000, maximum 600000) bounds the probe
+and the program each. Trusted owning code can set `runtimeDirectory` and the
+absolute `systemdRunPath` and `systemctlPath`. systemd-run reports the started
+scope as its first stderr line, which systemd 254 and later print; an older
+systemd-run, which lacks `--expand-environment`, fails with `scope_start_failed`.
+If the program cannot be executed after the scope started, systemd-run reports
+that as the program's exit status 1.
+
 ### SmartDaemonService Class
 
 ```typescript

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartdaemon',
-  version: '2.11.0',
+  version: '2.13.0',
   description: 'Start scripts as long running daemons and manage them.'
 }

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