@push.rocks/smartdaemon 2.21.0 → 3.0.0

package/readme.md

@@ -21,7 +21,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 - 🔄 **Systemd Integration**: Full Linux systemd support for production-grade service management
 - 🛡️ **Auto-Recovery**: Built-in service restart on failure
 - 📝 **Declarative Service Definitions**: Simple, clear service configuration
-- 🔌 **Interactive & Non-Interactive Modes**: Support for both passwordless sudo and interactive authentication
+- 🔌 **Passwordless or Password-Based Sudo**: Works with passwordless sudo, or hands a configured sudo password to sudo on standard input (no terminal or PTY needed)
 - 🎛️ **Complete Lifecycle Management**: Start, stop, enable, disable, and reload services with ease
 
 ## 📦 Installation
@@ -115,6 +115,20 @@ const service = await daemon.addService({
 await service.enable(); // Automatically uses sudo with password
 ```
 
+Each privileged command runs as `sudo -k -S -p '' -- <command>`: sudo reads the password from
+standard input, which is closed right after the password line, so a rejected password fails at
+once instead of waiting for a retry. The password is never placed in argv, the environment or the
+output, and no PTY (`node-pty`) is involved. `-k` makes sudo ask for the password every time and
+leaves no cached credentials behind. If a sudoers rule lets the command run without a password
+(`NOPASSWD`), sudo does not read standard input and the password line reaches the command's
+standard input instead (`systemctl`, `mv`, `chmod` and `rm` never read it); leave `sudoPassword`
+unset when sudo is passwordless.
+
+A command that does not exit 0 rejects with `SmartDaemonCommandError` (`command`, `exitCode`,
+`signal`, `stderr`), with or without a sudo password: a rejected password, a missing `sudo`
+(exit code 127) or a failing `systemctl` call all surface this way. Besides `systemctl`, saving
+and deleting a unit file as a non-root user runs `mv`, `chmod` and `rm` through sudo.
+
 ### Passwordless Sudo (Recommended for Production)
 
 For production environments, configure passwordless sudo for specific systemctl commands:
@@ -998,6 +1012,106 @@ 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.
 
+### The service side: notifications and passed descriptors (`/systemd-runtime`, Node.js 26)
+
+The definitions above tell the manager what to expect; a Node.js main process answers it through
+the `@push.rocks/smartdaemon/systemd-runtime` subpath: `sd_notify(3)` messages (with descriptors
+for the store) and the descriptors the manager passes (`LISTEN_FDS`). Node.js has no `AF_UNIX`
+datagram socket and no `fcntl(2)`, so the subpath calls glibc through `node:ffi`:
+
+- It requires **Node.js 26 or later**. Importing it on an older Node.js throws
+  `SystemdRuntimeError` with code `runtime_unsupported`; the main entry is unaffected and keeps
+  its Node.js range. The package is ES modules: CommonJS can `require()` either entry only on a
+  Node.js that loads ES modules through `require()` by default (20.19+, 22.12+, 23+), where the
+  subpath throws the same `runtime_unsupported` below 26; an older Node.js throws `ERR_REQUIRE_ESM`.
+- It runs on Linux x64 and arm64 with glibc (`libc.so.6`). Elsewhere, and with `node:ffi`
+  unavailable (`--no-experimental-ffi`) or denied by the permission model, the first call that
+  needs libc throws `runtime_unsupported`. Under the permission model pass `--allow-ffi`.
+- `node:ffi` is experimental: loading it prints one `ExperimentalWarning`. A single executable
+  application suppresses it through its `execArgv` (`--disable-warning=ExperimentalWarning`).
+- libc is opened on first use. Outside systemd nothing is loaded: without `NOTIFY_SOCKET`
+  `SystemdNotifier.fromEnvironment()` returns null, and without `LISTEN_*` variables
+  `takeSystemdListenDescriptors()` returns an empty list.
+
+```typescript
+import {
+  SystemdNotifier,
+  takeSystemdListenDescriptors,
+  watchdogIntervalUsec,
+} from '@push.rocks/smartdaemon/systemd-runtime';
+
+// Descriptors passed for this process, numbered from 3, already close-on-exec.
+const passed = takeSystemdListenDescriptors(); // [{ descriptor: 3, name: 'pallet-router' }]
+const namespaceDescriptor = passed.find(({ name }) => name === 'pallet-router')?.descriptor ?? createNamespace();
+
+// null when no service manager listens; the caller decides what that means.
+const notifier = SystemdNotifier.fromEnvironment({ take: true });
+if (notifier) {
+  notifier.extendTimeout(60_000_000, 'replaying journal');
+  notifier.replaceDescriptors('pallet-router', [namespaceDescriptor], { poll: false });
+  notifier.ready('serving');
+  const interval = watchdogIntervalUsec();
+  if (interval !== null) setInterval(() => notifier.watchdog(), interval / 2000);
+}
+```
+
+| Call | Sends or does |
+| --- | --- |
+| `ready(status?)` | `READY=1` (and `STATUS=`) |
+| `status(text)` | `STATUS=` |
+| `stopping(status?)` | `STOPPING=1` |
+| `reloading(status?)` | `RELOADING=1` with `MONOTONIC_USEC=` (`CLOCK_MONOTONIC`); send `ready()` when done |
+| `watchdog()` | `WATCHDOG=1` |
+| `extendTimeout(usec, status?)` | `EXTEND_TIMEOUT_USEC=` |
+| `storeDescriptors(name, fds, { poll? })` | `FDSTORE=1`, `FDNAME=`, `FDPOLL=0` for `poll: false`; descriptors as `SCM_RIGHTS` |
+| `removeDescriptors(name)` | `FDSTOREREMOVE=1`, `FDNAME=` |
+| `replaceDescriptors(name, fds, { poll? })` | remove, then store: two messages, handled in order |
+| `send(fields, fds?)` | any `NAME=value` fields in insertion order |
+| `takeSystemdNotifySocket()` | removes `NOTIFY_SOCKET` from the environment and returns it validated, or null |
+| `takeSystemdListenDescriptors()` | removes `LISTEN_PID`/`LISTEN_FDS`/`LISTEN_FDNAMES`; for this process marks every passed descriptor close-on-exec and returns it with its name (`unknown` without names) |
+| `setCloseOnExec(fd)` | `fcntl(F_SETFD, FD_CLOEXEC)`, verified |
+| `watchdogIntervalUsec()` | `WATCHDOG_USEC` for this process (`WATCHDOG_PID`), or null |
+
+Every call is synchronous and either completes or throws `SystemdRuntimeError` (`code`, and
+`errno` when a libc call failed); nothing is dropped silently. systemd ignores a message it cannot
+parse without telling the sender, so the notifier refuses it first: field names are upper-case,
+values carry no newline or NUL, a message is at most 4096 bytes (`notify_field_invalid`); a
+descriptor name is 1–255 printable ASCII characters without `:` (`descriptor_name_invalid`); one
+message carries 1–253 descriptors (`descriptor_invalid`). `NOTIFY_SOCKET` must be an absolute
+path or an abstract name (`@name`) of at most 107 bytes; anything else, `vsock:` addresses
+included, is `notify_socket_invalid`. A send the kernel refuses is `notify_failed` with its errno
+(`ENOENT` for a missing path, `ECONNREFUSED` for an abstract name nobody holds). `LISTEN_*`
+variables naming another process are removed and nothing else is touched; a partial or malformed
+set (`LISTEN_FDS` not a positive integer, a names list of another length) is
+`listen_environment_invalid` before any descriptor is touched, and a passed descriptor that is not
+open is `close_on_exec_failed`.
+
+`LISTEN_FDS` is also bounded by the process's hard `RLIMIT_NOFILE` before any descriptor is touched:
+a count whose last descriptor (`2 + count`) is at or above that limit is
+`listen_environment_invalid`. No descriptor systemd passed can lie at or above the hard limit,
+because it moves them into place with `fcntl(F_DUPFD)` (which refuses a number at or above the soft
+limit) after applying the unit's limits; a wrapper that lowers its hard limit below a passed
+descriptor before starting Node.js is refused. The hard limit can be as large as `fs.nr_open`
+(`LimitNOFILE=infinity`), so nothing is allocated per counted descriptor up front: like
+`sd_listen_fds(3)`, the descriptors are marked one by one from 3, the first that is not open throws
+`close_on_exec_failed` (the ones before it keep the flag), and the list grows only with open
+descriptors.
+
+Sends are blocking `sendmsg(2)` calls on a fresh `AF_UNIX` datagram socket, the same as
+`sd_notify(3)`: when the manager's receive queue is full, the call waits for room and the event loop
+stalls for that time.
+
+`node:ffi` has no errno API: the subpath reads glibc's thread-local `errno` through
+`__errno_location()` immediately after the failed call. Node.js itself calls libuv's
+`uv_disable_stdio_inheritance()` at startup (`InitializeNodeWithArgsInternal()` in `src/node.cc`;
+`deps/uv/src/unix/core.c`, Node.js 25.9.0 and 26.11.1), which marks descriptors 0–15 close-on-exec
+and continues past 15 until the first descriptor that is not open. The subpath still sets and
+verifies the flag on every passed descriptor, as `sd_listen_fds(3)` does.
+
+`test/test.systemdruntimeunit.node.ts` proves the subpath under a real `Type=notify` unit of the
+caller's user manager (`systemd-run --user`), and skips with the reason without Node.js 26 or a
+user manager.
+
 ### Starting a program in its own transient scope
 
 A service that launches a long-lived program keeps that program in its own
@@ -1254,6 +1368,8 @@ console.log(template); // View generated systemd unit file
 - **systemd 240 or later** for installing a definition with an `append` output (`standardOutput` or
   `standardError`), refused the same way
 - **Node.js**: Version 14.x or higher
+- **Node.js 26 or later** for the `@push.rocks/smartdaemon/systemd-runtime` subpath (`node:ffi`), on Linux
+  x64 or arm64 with glibc
 - **Permissions**: Either root access or properly configured sudo
 
 ## ⚙️ Generated Systemd Service Files
@@ -1296,7 +1412,8 @@ WantedBy=multi-user.target
 
 ### Permission Denied Errors
 
-If you encounter "Interactive authentication required" errors:
+If an operation rejects with a `SmartDaemonCommandError` whose `stderr` reports that sudo needs a
+password or a terminal (for example "a terminal is required to read the password"):
 
 1. **Option 1**: Run your application with sudo
    ```bash

package/ts/00_commitinfo_data.ts

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

package/ts/index.ts

@@ -4,3 +4,4 @@ export * from './classes.systemdunit.js';
 export * from './classes.systemdservicedefinition.js';
 export * from './classes.systemdunitfile.js';
 export * from './classes.systemdtransientscope.js';
+export * from './smartdaemon.classes.commanderror.js';

package/ts/smartdaemon.classes.commanderror.ts

@@ -0,0 +1,23 @@
+/**
+ * A privileged command run by `SmartDaemon` (through `systemdManager.execute()`) did not exit 0.
+ * The exit status alone decides failure; `stderr` carries what the command or sudo reported.
+ */
+export class SmartDaemonCommandError extends Error {
+  constructor(
+    /** The command as run, including any `sudo` prefix. It never contains the sudo password. */
+    public readonly command: string,
+    /** The exit code; `1` when a signal ended the command. */
+    public readonly exitCode: number,
+    /** The signal that ended the command, if one did. */
+    public readonly signal: NodeJS.Signals | undefined,
+    /** The command's standard error, as captured. */
+    public readonly stderr: string,
+    /** `cause`: the stdin write error when sudo exited before reading the password. */
+    options?: ErrorOptions,
+  ) {
+    const reason = signal ? `was terminated by signal ${signal}` : `exited with code ${exitCode}`;
+    const detail = stderr.trim();
+    super(`Command "${command}" ${reason}${detail ? `: ${detail}` : '.'}`, options);
+    this.name = 'SmartDaemonCommandError';
+  }
+}

package/ts/smartdaemon.classes.systemdmanager.ts

@@ -1,6 +1,7 @@
 import * as plugins from './smartdaemon.plugins.js';
 import * as paths from './smartdaemon.paths.js';
 import { SmartDaemon } from './smartdaemon.classes.smartdaemon.js';
+import { SmartDaemonCommandError } from './smartdaemon.classes.commanderror.js';
 import {
   type ISmartDaemonServiceConstructorOptions,
   SmartDaemonService,
@@ -31,8 +32,10 @@ export class SmartDaemonSystemdManager {
   public smartFs: plugins.smartfs.SmartFs;
 
   public shouldExecute: boolean = false;
+  /** Whether this process runs as root; set by the first privileged operation's check. */
   public isRoot: boolean = false;
   public sudoPassword?: string;
+  private rootStatus?: Promise<void>;
 
   constructor(smartdaemonRefArg: SmartDaemon, sudoPasswordArg?: string) {
     this.smartdaemonRef = smartdaemonRefArg;
@@ -41,14 +44,6 @@ export class SmartDaemonSystemdManager {
     });
     this.smartFs = new plugins.smartfs.SmartFs(new plugins.smartfs.SmartFsProviderNode());
     this.sudoPassword = sudoPasswordArg;
-    
-    // Check if we're running as root
-    this.checkIsRoot().then(isRoot => {
-      this.isRoot = isRoot;
-      if (!isRoot) {
-        console.log('Not running as root. Sudo will be used for privileged operations.');
-      }
-    });
   }
 
   private async checkIsRoot(): Promise<boolean> {
@@ -56,6 +51,23 @@ export class SmartDaemonSystemdManager {
     return result.stdout.trim() === '0';
   }
 
+  /** Checks once whether this process runs as root and sets `isRoot`; later calls reuse that check. */
+  private ensureRootStatus(): Promise<void> {
+    if (!this.rootStatus) {
+      this.rootStatus = this.checkIsRoot().then((isRoot) => {
+        this.isRoot = isRoot;
+        if (!isRoot) {
+          console.log('Not running as root. Sudo will be used for privileged operations.');
+        }
+      });
+      // A failed check is not memoized, so the next privileged operation asks again.
+      this.rootStatus.catch(() => {
+        this.rootStatus = undefined;
+      });
+    }
+    return this.rootStatus;
+  }
+
   public async checkElegibility() {
     if (plugins.os.platform() === 'linux') {
       this.shouldExecute = true;
@@ -66,31 +78,61 @@ export class SmartDaemonSystemdManager {
     return this.shouldExecute;
   }
 
-  public async execute(commandArg: string) {
-    if (await this.checkElegibility()) {
-      // Only use sudo if we're not root and command doesn't already have sudo
-      if (!this.isRoot && !commandArg.startsWith('sudo')) {
-        commandArg = `sudo ${commandArg}`;
-        
-        if (this.sudoPassword) {
-          // Use interactive PTY mode for password input
-          const interactiveExec = await this.smartshellInstance.execInteractiveControlPty(commandArg);
-          await interactiveExec.sendLine(this.sudoPassword);
-          const result = await interactiveExec.finalPromise;
-          return result;
-        }
-      }
-      
-      // Execute command (with or without sudo)
-      try {
-        await this.smartshellInstance.exec(commandArg);
-      } catch (error) {
-        if (!this.isRoot && error instanceof Error && error.message.includes('authentication')) {
-          throw new Error('Sudo authentication failed. Please configure passwordless sudo or provide a sudo password.');
-        }
-        throw error;
-      }
+  /**
+   * Runs a command, through sudo when this process is not root and the command does not start with
+   * `sudo` already. With a `sudoPassword`, sudo reads it from standard input (`sudo -k -S -p ''`):
+   * it never reaches argv, the environment or a terminal. Rejects with `SmartDaemonCommandError`
+   * when the command does not exit 0.
+   */
+  public async execute(commandArg: string): Promise<plugins.smartshell.IExecResult | undefined> {
+    if (!(await this.checkElegibility())) {
+      return undefined;
+    }
+    await this.ensureRootStatus();
+    if (this.isRoot || commandArg.startsWith('sudo')) {
+      return await this.runChecked(commandArg);
+    }
+    if (!this.sudoPassword) {
+      return await this.runChecked(`sudo ${commandArg}`);
+    }
+    // -k ignores cached credentials, so sudo reads the password line whenever its policy asks for
+    // one; ending stdin right after it makes a rejected password fail instead of waiting for a retry.
+    const sudoCommand = `sudo -k -S -p '' -- ${commandArg}`;
+    const interactiveExec = await this.smartshellInstance.execInteractiveControl(sudoCommand);
+    let writeError: unknown;
+    try {
+      await interactiveExec.sendLine(this.sudoPassword);
+    } catch (error) {
+      // sudo can exit before reading stdin (EPIPE); its exit status below decides the outcome.
+      writeError = error;
+    }
+    interactiveExec.endInput();
+    const result = await interactiveExec.finalPromise;
+    this.assertSucceeded(sudoCommand, result, writeError);
+    return result;
+  }
+
+  private async runChecked(commandArg: string): Promise<plugins.smartshell.IExecResult> {
+    const result = await this.smartshellInstance.exec(commandArg);
+    this.assertSucceeded(commandArg, result);
+    return result;
+  }
+
+  private assertSucceeded(
+    commandArg: string,
+    resultArg: plugins.smartshell.IExecResult,
+    causeArg?: unknown,
+  ): void {
+    if (resultArg.exitCode === 0 && !resultArg.signal) {
+      return;
     }
+    throw new SmartDaemonCommandError(
+      commandArg,
+      resultArg.exitCode,
+      resultArg.signal,
+      resultArg.stderr,
+      causeArg === undefined ? undefined : { cause: causeArg },
+    );
   }
 
   /**
@@ -136,7 +178,8 @@ export class SmartDaemonSystemdManager {
     if (await this.checkElegibility()) {
       const content = this.smartdaemonRef.templateManager.generateUnitFileForService(serviceArg);
       const targetPath = SmartDaemonSystemdManager.createFilePathFromServiceName(serviceArg.name);
-      
+
+      await this.ensureRootStatus();
       if (this.isRoot) {
         // Direct write when running as root
         await this.smartFs.file(targetPath).encoding('utf8').mode(0o644).write(content);
@@ -153,7 +196,8 @@ export class SmartDaemonSystemdManager {
   public async deleteService(serviceArg: SmartDaemonService) {
     if (await this.checkElegibility()) {
       const filePath = SmartDaemonSystemdManager.createFilePathFromServiceName(serviceArg.name);
-      
+
+      await this.ensureRootStatus();
       if (this.isRoot) {
         await this.smartFs.file(filePath).delete();
       } else {

package/ts/smartdaemon.plugins.ts

@@ -13,8 +13,6 @@ export { path, childProcess, fs, fsConstants, crypto, util, os };
 // @pushrocks scope
 import * as lik from '@push.rocks/lik';
 import * as smartfs from '@push.rocks/smartfs';
-import * as smartlog from '@push.rocks/smartlog';
-import * as smartlogDestinationLocal from '@push.rocks/smartlog/destination-local';
 import * as smartmarkdown from '@push.rocks/smartmarkdown/iso';
 import * as smartpath from '@push.rocks/smartpath';
 import * as smartshell from '@push.rocks/smartshell';
@@ -22,8 +20,6 @@ import * as smartshell from '@push.rocks/smartshell';
 export {
   lik,
   smartfs,
-  smartlog,
-  smartlogDestinationLocal,
   smartmarkdown,
   smartpath,
   smartshell,

package/ts_systemdruntime/classes.systemdnotifier.ts

@@ -0,0 +1,287 @@
+import { SystemdRuntimeError } from './classes.systemdruntimeerror.js';
+import {
+  controlSpace,
+  descriptorsPerMessageMaximum,
+  libcConstants,
+  socketAddressLength,
+  systemdLibc,
+  writeSocketAddress,
+} from './systemdruntime.libc.js';
+import {
+  assertSystemdDescriptor,
+  assertSystemdNotifySocketAddress,
+  isSystemdDescriptorName,
+} from './systemdruntime.validation.js';
+
+/** `NOTIFY_BUFFER_MAX` (`PIPE_BUF`): systemd ignores a longer notification message. */
+export const notifyMessageMaximumBytes = 4096;
+
+export interface ISystemdEnvironmentOptions {
+  /** The environment to read; `process.env` by default. */
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+export interface ISystemdNotifierEnvironmentOptions extends ISystemdEnvironmentOptions {
+  /** Remove `NOTIFY_SOCKET` from the environment, so no child inherits it. Default `false`. */
+  readonly take?: boolean;
+}
+
+export interface ISystemdStoreDescriptorsOptions {
+  /**
+   * Whether the manager watches the stored descriptors and drops one that reports `POLLHUP` or
+   * `POLLERR` (`FDPOLL=`). Default `true`, as in systemd; `false` sends `FDPOLL=0`, for descriptors
+   * that are not pollable or always report hang-up, such as namespace descriptors.
+   */
+  readonly poll?: boolean;
+}
+
+/**
+ * Takes `NOTIFY_SOCKET` out of the environment: the validated address, or null when it is unset or
+ * empty. An address that is set but invalid is removed as well and then refused
+ * (`notify_socket_invalid`).
+ */
+export const takeSystemdNotifySocket = (optionsArg: ISystemdEnvironmentOptions = {}): string | null => {
+  const env = optionsArg.env ?? process.env;
+  const address = env.NOTIFY_SOCKET;
+  delete env.NOTIFY_SOCKET;
+  if (address === undefined || address === '') return null;
+  assertSystemdNotifySocketAddress(address);
+  return address;
+};
+
+const fieldNamePattern = /^[A-Z][A-Z0-9_]*$/;
+
+/**
+ * Sends `sd_notify(3)` messages to a service manager's notification socket: one `AF_UNIX`
+ * `SOCK_DGRAM` datagram per message, descriptors attached as `SCM_RIGHTS`. Every call is synchronous
+ * and either delivers the whole message to the socket or throws a `SystemdRuntimeError`; whether
+ * the manager acts on it depends on the unit's `NotifyAccess=`. Fields and descriptor names are
+ * validated before sending, because systemd ignores a message it cannot parse without telling the
+ * sender.
+ */
+export class SystemdNotifier {
+  /**
+   * The notifier for the unit that started this process, or null when `NOTIFY_SOCKET` is unset or
+   * empty — the process was not started by a service manager that listens. The caller decides what
+   * that means; nothing is sent silently nowhere. An invalid `NOTIFY_SOCKET` throws
+   * `notify_socket_invalid`.
+   */
+  public static fromEnvironment(optionsArg: ISystemdNotifierEnvironmentOptions = {}): SystemdNotifier | null {
+    const env = optionsArg.env ?? process.env;
+    const address = optionsArg.take === true ? takeSystemdNotifySocket({ env }) : env.NOTIFY_SOCKET;
+    if (address === undefined || address === null || address === '') return null;
+    return new SystemdNotifier(address);
+  }
+
+  /** The notification socket: an absolute path, or an abstract name written `@name`. */
+  public readonly socketAddress: string;
+
+  constructor(socketAddressArg: string) {
+    assertSystemdNotifySocketAddress(socketAddressArg);
+    this.socketAddress = socketAddressArg;
+  }
+
+  /** `READY=1`, with an optional `STATUS=`. */
+  public ready(statusArg?: string): void {
+    this.send({ READY: '1', ...(statusArg === undefined ? {} : { STATUS: statusArg }) });
+  }
+
+  /** `STATUS=`: free-form text the manager shows as the unit's status. */
+  public status(textArg: string): void {
+    this.send({ STATUS: textArg });
+  }
+
+  /** `STOPPING=1`, with an optional `STATUS=`. */
+  public stopping(statusArg?: string): void {
+    this.send({ STOPPING: '1', ...(statusArg === undefined ? {} : { STATUS: statusArg }) });
+  }
+
+  /**
+   * `RELOADING=1` with `MONOTONIC_USEC=` (`CLOCK_MONOTONIC` now), with an optional `STATUS=`. The
+   * service sends `ready()` once the reload finished.
+   */
+  public reloading(statusArg?: string): void {
+    this.send({
+      RELOADING: '1',
+      MONOTONIC_USEC: String(monotonicMicroseconds()),
+      ...(statusArg === undefined ? {} : { STATUS: statusArg }),
+    });
+  }
+
+  /** `WATCHDOG=1`: keeps a `WatchdogSec=` unit alive. */
+  public watchdog(): void {
+    this.send({ WATCHDOG: '1' });
+  }
+
+  /**
+   * `EXTEND_TIMEOUT_USEC=`: asks the manager to wait `microsecondsArg` longer for the current start,
+   * runtime-start, stop or watchdog deadline, with an optional `STATUS=`.
+   */
+  public extendTimeout(microsecondsArg: number, statusArg?: string): void {
+    if (!Number.isSafeInteger(microsecondsArg) || microsecondsArg <= 0) {
+      throw new SystemdRuntimeError('notify_field_invalid', 'EXTEND_TIMEOUT_USEC must be a positive integer.');
+    }
+    this.send({
+      EXTEND_TIMEOUT_USEC: String(microsecondsArg),
+      ...(statusArg === undefined ? {} : { STATUS: statusArg }),
+    });
+  }
+
+  /**
+   * `FDSTORE=1` with `FDNAME=`: the manager keeps duplicates of `descriptorsArg` (1–253) under
+   * `nameArg` in the unit's descriptor store (`FileDescriptorStoreMax=`) and passes them to the
+   * next main process through `LISTEN_FDS`. Storing does not replace descriptors already stored
+   * under the name; `replaceDescriptors()` does.
+   */
+  public storeDescriptors(
+    nameArg: string,
+    descriptorsArg: readonly number[],
+    optionsArg: ISystemdStoreDescriptorsOptions = {},
+  ): void {
+    assertDescriptorName(nameArg);
+    assertStoredDescriptors(descriptorsArg);
+    this.send(
+      { FDSTORE: '1', FDNAME: nameArg, ...(optionsArg.poll === false ? { FDPOLL: '0' } : {}) },
+      descriptorsArg,
+    );
+  }
+
+  /** `FDSTOREREMOVE=1` with `FDNAME=`: the manager closes every descriptor stored under `nameArg`. */
+  public removeDescriptors(nameArg: string): void {
+    assertDescriptorName(nameArg);
+    this.send({ FDSTOREREMOVE: '1', FDNAME: nameArg });
+  }
+
+  /**
+   * Removes the descriptors stored under `nameArg`, then stores `descriptorsArg` under it: two
+   * messages, handled by the manager in order. Between them the store holds nothing under the name.
+   */
+  public replaceDescriptors(
+    nameArg: string,
+    descriptorsArg: readonly number[],
+    optionsArg: ISystemdStoreDescriptorsOptions = {},
+  ): void {
+    assertDescriptorName(nameArg);
+    assertStoredDescriptors(descriptorsArg);
+    this.removeDescriptors(nameArg);
+    this.storeDescriptors(nameArg, descriptorsArg, optionsArg);
+  }
+
+  /**
+   * Sends one message: `NAME=value` fields in insertion order, joined by newlines, and up to 253
+   * descriptors. Names are upper-case (`A–Z`, digits, `_`); values carry no newline or NUL; the
+   * message is at most 4096 bytes.
+   */
+  public send(fieldsArg: Readonly<Record<string, string>>, descriptorsArg: readonly number[] = []): void {
+    const entries = Object.entries(fieldsArg);
+    if (entries.length === 0) {
+      throw new SystemdRuntimeError('notify_field_invalid', 'A notification needs at least one field.');
+    }
+    for (const [name, value] of entries) {
+      if (!fieldNamePattern.test(name)) {
+        throw new SystemdRuntimeError('notify_field_invalid', `${JSON.stringify(name)} is not a notification field name.`);
+      }
+      if (typeof value !== 'string' || /[\n\0]/.test(value)) {
+        throw new SystemdRuntimeError('notify_field_invalid', `The ${name} value must be a string without newline or NUL.`);
+      }
+    }
+    assertDescriptorList(descriptorsArg);
+    const payload = Buffer.from(entries.map(([name, value]) => `${name}=${value}`).join('\n'), 'utf8');
+    if (payload.length > notifyMessageMaximumBytes) {
+      throw new SystemdRuntimeError(
+        'notify_field_invalid',
+        `The message is ${payload.length} bytes; systemd reads at most ${notifyMessageMaximumBytes}.`,
+      );
+    }
+    sendDatagram(this.socketAddress, payload, descriptorsArg);
+  }
+}
+
+const assertDescriptorName = (nameArg: string): void => {
+  if (!isSystemdDescriptorName(nameArg, true)) {
+    throw new SystemdRuntimeError(
+      'descriptor_name_invalid',
+      'A descriptor name is 1–255 printable ASCII characters without ":".',
+    );
+  }
+};
+
+/** At most 253 valid descriptor numbers. */
+const assertDescriptorList = (descriptorsArg: readonly number[]): void => {
+  if (descriptorsArg.length > descriptorsPerMessageMaximum) {
+    throw new SystemdRuntimeError(
+      'descriptor_invalid',
+      `One message carries at most ${descriptorsPerMessageMaximum} descriptors.`,
+    );
+  }
+  descriptorsArg.forEach(assertSystemdDescriptor);
+};
+
+/** 1–253 valid descriptor numbers, as `FDSTORE=1` needs. */
+const assertStoredDescriptors = (descriptorsArg: readonly number[]): void => {
+  if (descriptorsArg.length === 0) {
+    throw new SystemdRuntimeError('descriptor_invalid', 'FDSTORE=1 needs at least one descriptor.');
+  }
+  assertDescriptorList(descriptorsArg);
+};
+
+/** `CLOCK_MONOTONIC` in microseconds, as `MONOTONIC_USEC=` expects. */
+const monotonicMicroseconds = (): bigint => {
+  const libc = systemdLibc();
+  const timespec = Buffer.alloc(16);
+  if (libc.functions.clock_gettime(libcConstants.CLOCK_MONOTONIC, timespec) !== 0) {
+    throw new SystemdRuntimeError('notify_failed', 'clock_gettime(CLOCK_MONOTONIC) failed.', { errno: libc.errno() });
+  }
+  return timespec.readBigInt64LE(0) * 1_000_000n + timespec.readBigInt64LE(8) / 1_000n;
+};
+
+// One block holds the whole message, so every pointer inside it stays valid while the block is
+// borrowed by the call: msghdr, iovec, sockaddr_un, control data, payload.
+const iovecOffset = 56;
+const addressOffset = 72;
+const controlOffset = 184;
+
+const sendDatagram = (addressArg: string, payloadArg: Buffer, descriptorsArg: readonly number[]): void => {
+  const libc = systemdLibc();
+  const space = descriptorsArg.length === 0 ? 0 : controlSpace(descriptorsArg.length);
+  const payloadOffset = controlOffset + space;
+  const block = Buffer.alloc(payloadOffset + payloadArg.length);
+  const base = libc.ffi.getRawPointer(block);
+  writeSocketAddress(block, addressOffset, addressArg);
+  payloadArg.copy(block, payloadOffset);
+  block.writeBigUInt64LE(base + BigInt(addressOffset), 0);
+  block.writeUInt32LE(socketAddressLength(addressArg), 8);
+  block.writeBigUInt64LE(base + BigInt(iovecOffset), 16);
+  block.writeBigUInt64LE(1n, 24);
+  block.writeBigUInt64LE(base + BigInt(payloadOffset), iovecOffset);
+  block.writeBigUInt64LE(BigInt(payloadArg.length), iovecOffset + 8);
+  if (space > 0) {
+    block.writeBigUInt64LE(base + BigInt(controlOffset), 32);
+    block.writeBigUInt64LE(BigInt(space), 40);
+    block.writeBigUInt64LE(BigInt(16 + 4 * descriptorsArg.length), controlOffset);
+    block.writeInt32LE(libcConstants.SOL_SOCKET, controlOffset + 8);
+    block.writeInt32LE(libcConstants.SCM_RIGHTS, controlOffset + 12);
+    descriptorsArg.forEach((descriptor, index) => block.writeInt32LE(descriptor, controlOffset + 16 + 4 * index));
+  }
+  const socket = libc.functions.socket(libcConstants.AF_UNIX, libcConstants.SOCK_DGRAM | libcConstants.SOCK_CLOEXEC, 0);
+  if (socket < 0) {
+    throw new SystemdRuntimeError('notify_failed', 'socket(AF_UNIX, SOCK_DGRAM) failed.', { errno: libc.errno() });
+  }
+  try {
+    let sent = libc.functions.sendmsg(socket, block, libcConstants.MSG_NOSIGNAL);
+    let errno = sent < 0n ? libc.errno() : 0;
+    while (sent < 0n && errno === libcConstants.EINTR) {
+      sent = libc.functions.sendmsg(socket, block, libcConstants.MSG_NOSIGNAL);
+      errno = sent < 0n ? libc.errno() : 0;
+    }
+    if (sent < 0n) {
+      throw new SystemdRuntimeError('notify_failed', `sendmsg to ${addressArg} failed.`, { errno });
+    }
+    if (sent !== BigInt(payloadArg.length)) {
+      throw new SystemdRuntimeError('notify_failed', `sendmsg to ${addressArg} sent ${sent} of ${payloadArg.length} bytes.`);
+    }
+  } finally {
+    // Linux releases the descriptor whatever close(2) reports; the socket is this call's alone.
+    libc.functions.close(socket);
+  }
+};