paratix 0.9.0 → 0.12.2

package/dist/{user-B9lkXr0X.d.ts → index-udpAybq3.d.ts}

@@ -1,4 +1,319 @@
-import { M as Module } from './types-Cl2Muw1x.js';
+/**
+ * A scalar env value, or a lazy function that returns one.
+ * Functions may be async, allowing secrets to be fetched on demand.
+ */
+type EnvironmentValue = (() => boolean | number | string) | (() => Promise<boolean | number | string>) | boolean | number | string;
+/** A key-value map of environment values available to modules and templates. */
+type Environment = Record<string, EnvironmentValue>;
+/** Environment values that can be emitted through the typed meta system. */
+type MetaEnvironmentValue = EnvironmentValue;
+/** Generic meta entry that propagates a value into the downstream environment. */
+type EnvironmentMetaEntry = {
+    kind: "env";
+    name: string;
+    resolve: () => Promise<boolean | number | string>;
+    valueType: "boolean" | "number" | "string";
+    valueTypeExplicit?: boolean;
+};
+/** Runner control-plane meta entry emitted when sshd changed its listen port. */
+type SshdPortMetaEntry = {
+    kind: "sshd.port";
+    port: number;
+};
+/** Runner control-plane meta entry emitted when the target host changed. */
+type SystemHostMetaEntry = {
+    host: string;
+    kind: "system.host";
+};
+/** Runner control-plane meta entry emitted when a reboot should trigger reconnect logic. */
+type SystemRebootMetaEntry = {
+    kind: "system.reboot";
+};
+/** Any meta entry that modules may emit. */
+type ModuleMetaEntry = EnvironmentMetaEntry | SshdPortMetaEntry | SystemHostMetaEntry | SystemRebootMetaEntry;
+/** Check result indicating the module's desired state is not yet present. */
+declare const NEEDS_APPLY: "needs-apply";
+/** Execution status emitted by a module apply step. */
+type ModuleStatus = "changed" | "failed" | "ok" | "skipped";
+/** The outcome of a module's apply step. */
+type ModuleResult = {
+    /**
+     * Optional internal dry-run detail shown instead of the generic `(dry-run)`
+     * suffix when a module performed custom dry-run verification.
+     * @internal
+     */
+    _dryRunDetail?: string;
+    /**
+     * Optional internal control-plane marker that tells the current scope to
+     * execute all pending signals immediately at this point in the run.
+     * @internal
+     */
+    _flushSignals?: true;
+    /**
+     * Optional internal control-plane marker that tells the runner to stop the
+     * current run successfully after this module completed.
+     * @internal
+     */
+    _stopRun?: true;
+    /** Optional short detail appended to the printed module status line. */
+    detail?: string;
+    /**
+     * Optional multi-line unified-diff string rendered below the module status
+     * line when the runner was started with the `--diff` CLI flag (or with
+     * the runner option `diff`). Modules that participate in diff output produce
+     * the string in their `_applyDryRun` hook and mark themselves with
+     * `_dryRunDiffProducer: true`. The runner never modifies the string; the
+     * output layer applies registered-secret masking and terminal sanitizing
+     * before printing each line.
+     *
+     * Renders independently of `_dryRunDetail` — both fields may be set at the
+     * same time, and the runner shows both (detail inline next to the status,
+     * diff in a block beneath it).
+     */
+    diff?: string;
+    /** Optional error details consumed by the runner for centralized CLI output. */
+    error?: Error;
+    /** Optional typed meta entries for env propagation and runner control-plane updates. */
+    meta?: ModuleMetaEntry[];
+    /** Execution status of the module. */
+    status: ModuleStatus;
+};
+/**
+ * Internal orchestration step shape shared between runner and recipe execution.
+ * Contains the merged downstream environment after a single apply step.
+ * @internal
+ */
+type OrchestrationStep = {
+    /** @internal */
+    _flushSignals?: true;
+    /** @internal */
+    _stopRun?: true;
+    env: Environment;
+    meta?: ModuleMetaEntry[];
+    status: ModuleStatus;
+};
+/**
+ * Optional internal apply hooks used by composite modules to expose child
+ * orchestration steps to their surrounding runner scope.
+ * @internal
+ */
+type ModuleApplyOptions = {
+    onChildStep?: (step: OrchestrationStep) => Promise<void>;
+    shutdownSignal?: () => null | ShutdownSignal;
+};
+/**
+ * Shutdown signal names observed by Paratix orchestration hooks.
+ *
+ * This intentionally mirrors Node's process signal strings without referencing
+ * the ambient `NodeJS` namespace, so published declarations remain usable in
+ * consumers that do not install `@types/node`.
+ */
+type ShutdownSignal = "SIGABRT" | "SIGALRM" | "SIGBREAK" | "SIGBUS" | "SIGCHLD" | "SIGCONT" | "SIGFPE" | "SIGHUP" | "SIGILL" | "SIGINFO" | "SIGINT" | "SIGIO" | "SIGIOT" | "SIGKILL" | "SIGLOST" | "SIGPIPE" | "SIGPOLL" | "SIGPROF" | "SIGPWR" | "SIGQUIT" | "SIGSEGV" | "SIGSTKFLT" | "SIGSTOP" | "SIGSYS" | "SIGTERM" | "SIGTRAP" | "SIGTSTP" | "SIGTTIN" | "SIGTTOU" | "SIGUNUSED" | "SIGURG" | "SIGUSR1" | "SIGUSR2" | "SIGVTALRM" | "SIGWINCH" | "SIGXCPU" | "SIGXFSZ";
+/**
+ * A single idempotent unit of work that can be checked and applied.
+ * Modules form the building blocks of a server recipe.
+ */
+type Module = {
+    /**
+     * Optional internal dry-run apply hook for modules that need custom dry-run
+     * execution semantics beyond the generic blocker/meta-producer markers.
+     * @internal
+     */
+    _applyDryRun?: (ssh: null | SshConnection, environment: Environment, options?: ModuleApplyOptions) => Promise<ModuleResult>;
+    /**
+     * Internal marker for modules that must still execute their apply step in dry-run mode
+     * because they act as run blockers rather than mutating state.
+     * @internal
+     */
+    _dryRunBlocker?: true;
+    /**
+     * Internal marker for modules that can produce a {@link ModuleResult.diff}
+     * during dry-run by running their `_applyDryRun` hook. The runner only
+     * dispatches `_applyDryRun` for diff production when the user passed the
+     * `--diff` CLI flag (i.e. the runner option `diff` is `true`); otherwise the
+     * generic `(dry-run)` suffix is shown without any extra remote round-trips.
+     * @internal
+     */
+    _dryRunDiffProducer?: true;
+    /**
+     * Internal marker for non-mutating modules whose apply step emits meta that must
+     * still be materialized during dry-run so downstream modules see the same environment.
+     * @internal
+     */
+    _dryRunMetaProducer?: true;
+    /**
+     * Internal marker for composite modules that can expose child orchestration
+     * steps to the surrounding runner scope.
+     * @internal
+     */
+    _supportsChildStepHook?: true;
+    /**
+     * Enforce the desired state.
+     * @returns A {@link ModuleResult} describing what happened.
+     */
+    apply: (ssh: null | SshConnection, environment: Environment, options?: ModuleApplyOptions) => Promise<ModuleResult>;
+    /**
+     * Determine whether the module needs to run.
+     * @returns `"ok"` if the desired state is already present, `"needs-apply"` otherwise.
+     */
+    check: (ssh: null | SshConnection, environment: Environment) => Promise<"needs-apply" | "ok">;
+    /**
+     * When true the module runs locally instead of over SSH.
+     * The `ssh` parameter will be `null` in check/apply.
+     */
+    local?: boolean;
+    /** Human-readable name shown in the run output. */
+    name: string;
+};
+/** Raw output from a remote or local command execution. */
+type ExecResult = {
+    /** Exit code of the process. */
+    code: number;
+    /** Captured standard error. */
+    stderr: string;
+    /** Captured standard output. */
+    stdout: string;
+};
+/** Options that control how a command is executed. */
+type ExecOptions = {
+    /** Additional environment variables to inject into the process. */
+    env?: Record<string, string>;
+    /** Return a result even when the exit code is non-zero instead of throwing. */
+    ignoreExitCode?: boolean;
+    /**
+     * Optional payload written to the remote command's stdin before EOF is
+     * signalled. Used to pass secret material (password hashes, signed URLs,
+     * Authorization headers) to a remote tool without exposing it on the
+     * command line, where it would otherwise leak into `/var/log/auth.log`,
+     * `ps -ef`, or `/proc/<pid>/cmdline`.
+     */
+    input?: string;
+    /**
+     * Maximum number of UTF-8 bytes captured per output stream for `stdout` and
+     * `stderr`. Live output still streams fully; only the stored ExecResult and
+     * CommandError output are capped.
+     */
+    maxOutputBytes?: number;
+    /** Strings to mask in error messages (e.g. tokens, passwords). */
+    secrets?: string[];
+    /** Suppress stdout/stderr from the console while running. */
+    silent?: boolean;
+    /** Abort the command after this many milliseconds. */
+    timeout?: number;
+};
+/**
+ * Abstraction over an active SSH session.
+ * All methods that accept a `command` string run it on the remote host.
+ */
+type SshConnection = {
+    /** Register an additional port that was opened on the remote host. Returns `true` when added. */
+    addPort: (port: number) => boolean;
+    /** Close the SSH connection and free resources. */
+    disconnect: () => void;
+    /** Download a remote file to the local filesystem. */
+    downloadFile: (remotePath: string, localPath: string) => Promise<void>;
+    /** Run a command and return the full result including exit code and output. */
+    exec: (command: string, options?: ExecOptions) => Promise<ExecResult>;
+    /** Return `true` if the remote path exists. */
+    exists: (remotePath: string) => Promise<boolean>;
+    /**
+     * Return the low-level connection parameters for this session.
+     * `privateKeyPath` and `agentSocket` reflect the authentication method that
+     * was actually used for the current session. `privateKeyPath` is returned as
+     * an expanded filesystem path.
+     */
+    getConnectionInfo: () => {
+        agentSocket?: string;
+        authMethod?: "agent" | "password" | "privateKey";
+        configuredPorts: number[];
+        host: string;
+        port: number;
+        privateKeyPath?: string;
+        user: string;
+        verifiedHostPublicKey?: string;
+    };
+    /** Run a command and return stdout split into lines. */
+    lines: (command: string) => Promise<string[]>;
+    /** Run a command and return trimmed stdout. */
+    output: (command: string) => Promise<string>;
+    /** Probe whether passwordless sudo works; prompt interactively if not and cache the password. */
+    probeSudo: () => Promise<void>;
+    /** Read the full contents of a remote file as a string. */
+    readFile: (remotePath: string) => Promise<string>;
+    /** Reconnect the SSH session using the current host and registered port candidates. */
+    reconnect: () => Promise<void>;
+    /** Remove a previously registered port from the reconnect candidate list. */
+    removePort: (port: number) => void;
+    /** Return the SHA-256 hex digest of a remote file, or `null` if not found. */
+    sha256: (remotePath: string) => Promise<null | string>;
+    /** Run a command and return `true` if the exit code is zero. */
+    test: (command: string) => Promise<boolean>;
+    /** Update the target host address (e.g. after a reboot with new IP). */
+    updateHost: (host: string) => void;
+    /** Upload a local file to the remote host via SFTP. */
+    uploadFile: (localPath: string, remotePath: string, options?: {
+        mode?: string;
+    }) => Promise<void>;
+    /** Write a string to a remote file, creating or overwriting it. */
+    writeFile: (remotePath: string, content: string, options: {
+        mode: string;
+    }) => Promise<void>;
+};
+/** SSH connection parameters for a server. */
+type SshConfig = {
+    /** Forward the local SSH agent to the remote host. */
+    agentForward?: boolean;
+    /** Expected SHA256 host fingerprint used as a pinned trust anchor. */
+    expectedHostFingerprint?: string;
+    /** Expected OpenSSH public key (`"<algorithm> <base64>"`) used as a pinned trust anchor. */
+    expectedHostPublicKey?: string;
+    /** Maximum number of reconnection attempts before giving up. */
+    maxReconnectAttempts?: number;
+    /** Fall back to password authentication if key auth fails. */
+    passwordFallback?: boolean;
+    /** Ordered list of candidate ports -- the runner tries each until one connects. */
+    ports: number[];
+    /**
+     * Absolute path to the private key file used for authentication.
+     * When omitted, the SSH agent referenced by `SSH_AUTH_SOCK` is used instead.
+     * Exactly one of `privateKey` or a running SSH agent must be available.
+     */
+    privateKey?: string;
+    /** Maximum time in milliseconds to spend attempting reconnection before giving up. */
+    reconnectTimeout?: number;
+    /**
+     * Host key verification strategy.
+     * - `"accept-new"` — explicit TOFU opt-in: accept unknown keys and append them to `~/.ssh/known_hosts`.
+     * - `"yes"` — reject unknown keys; only connect when the key is already in `known_hosts`.
+     * - `"no"` — skip host key verification entirely.
+     *
+     * When omitted, Paratix now defaults to `"yes"`. To connect to a new host
+     * safely without TOFU, set `expectedHostFingerprint` or `expectedHostPublicKey`.
+     */
+    strictHostKeyChecking?: "accept-new" | "no" | "yes";
+    /** Password used for `sudo` escalation on the remote host. */
+    sudoPassword?: string;
+    /** Username to authenticate as. */
+    user: string;
+};
+/** Top-level definition of a server and the modules to run on it. */
+type ServerDefinition = {
+    /** Server-level env values merged with global env before running modules. */
+    env?: Environment;
+    /** Hostname or IP address. */
+    host: string;
+    /** Display name for the server. */
+    name: string;
+    /** Ordered list of modules (or recipes) to apply. */
+    run: Module[];
+    /**
+     * Modules triggered as signals after the run completes with status `"changed"`.
+     * Typically used for service reloads or notifications.
+     */
+    signals?: Module[];
+    /** SSH connection parameters. */
+    ssh: SshConfig;
+};
 
 /** Per-call overrides for package operations that can take a long time. */
 type UpgradeOptions = {
@@ -217,7 +532,7 @@ declare const archive: {
      * @param source - Path to the archive (remote path, or local path when upload is true).
      * @param destination - The destination directory on the remote host.
      * @param options - Optional settings.
-     * @param options.owner - Run chown -R after extraction.
+     * @param options.owner - Set ownership on extracted archive members after extraction.
      * @param options.upload - Upload a local file to the remote host before extracting.
      * @returns A Module that manages the archive extraction.
      */
@@ -238,6 +553,11 @@ declare const command: {
      * with a shell expression that exits `0` when the desired state is already
      * present -- in that case the command is skipped.
      *
+     * Security: `cmd` and `options.check` are executed verbatim by the remote shell.
+     * Never interpolate untrusted input into these strings. NUL, CR, and LF are
+     * rejected up front because they can split or corrupt the line-based protocol
+     * between the orchestrator and the remote shell.
+     *
      * @param cmd - The shell command to execute.
      * @param options - Optional configuration for the command.
      * @param options.check - An optional shell expression used as the idempotency guard.
@@ -369,6 +689,16 @@ declare const compose: {
 
 /** Options for `cron.job`. */
 type CronJobOptions = {
+    /**
+     * R-0000697: opt-in to splicing the marker in front of an existing
+     * crontab line that exactly matches `job` when no marker is present.
+     * Without this flag, `state="present"` appends a fresh marker + job
+     * and never silently adopts an identical user-authored line. Set this
+     * to `true` only when knowingly recovering from a `cron.absent` on a
+     * legacy marker that left the original job line as an orphan
+     * (R-0000567/R-0000676). Defaults to `false`.
+     */
+    adoptOrphans?: boolean;
     /** The crontab line to manage (e.g. `"0 * * * * /usr/bin/backup"`). */
     job: string;
     /** Whether the job should be `"present"` or `"absent"`. Defaults to `"present"`. */
@@ -382,6 +712,22 @@ type CronJobOptions = {
  * idempotent and safely repeatable.
  */
 declare const cron: {
+    /**
+     * Ensure a cron job is absent from a user's crontab.
+     *
+     * Removes the `# paratix: <name>` marker comment and the crontab line
+     * directly below it. If the marker is not found, the module reports `ok`
+     * without writing the crontab. When the crontab becomes empty after the
+     * removal, it is deleted entirely via `crontab -r`.
+     *
+     * Equivalent to `cron.job(user, name, { job: "<unused>", state: "absent" })`,
+     * but does not require a placeholder `job` argument.
+     *
+     * @param user - The target user whose crontab is managed.
+     * @param name - Unique identifier of the cron job marker to remove.
+     * @returns A Module that ensures the cron job entry is absent.
+     */
+    absent(user: string, name: string): Module;
     /**
      * Ensure a cron job is present in (or absent from) a user's crontab.
      *
@@ -395,6 +741,27 @@ declare const cron: {
      * @param options - Job content and desired state.
      * @param options.job - The crontab line to manage (e.g. `"0 * * * * /usr/bin/backup"`).
      * @param options.state - Whether the job should be `"present"` or `"absent"`. Defaults to `"present"`.
+     * @param options.adoptOrphans - R-0000697: opt-in to splicing the marker
+     *   in front of an existing crontab line that exactly matches `job` when
+     *   no marker is present. Defaults to `false`. Set to `true` only when
+     *   knowingly recovering from a `cron.absent` on a legacy marker.
+     *
+     * R-0000804: concurrency semantics.
+     *
+     * Each `cron.job` / `cron.absent` apply is serialised by the per-user
+     * mutex `crontab-<user>` (see `crontabMutexLockName`). All cron modules
+     * targeting the same user therefore share the same flag-lock directory:
+     * only one apply can hold the mutex at a time and writers never
+     * interleave their `crontab -u <user> -` calls.
+     *
+     * `check` does NOT take the mutex — it issues a plain `crontab -u <user>
+     * -l` and inspects the output, which is safe because cron's own crontab
+     * file is read atomically. As a result, `check` may briefly observe a
+     * snapshot that does not yet reflect a concurrent apply on the same
+     * user. The verdict in that case is `NEEDS_APPLY`, and the subsequent
+     * apply re-runs under the mutex against the current crontab state, so a
+     * stale `check` cannot cause a divergent write.
+     *
      * @returns A Module that manages the cron job entry.
      */
     job(user: string, name: string, options: CronJobOptions): Module;
@@ -408,6 +775,8 @@ type BaseDownloadOptions = {
     allowInsecureHttp?: boolean;
     /** Explicitly opt out of integrity verification for trusted sources. */
     allowUnverifiedDownload?: boolean;
+    /** Maximum time to establish the curl connection, in milliseconds. */
+    connectTimeout?: number;
     /** Group owner to set on the downloaded file via `chown`. */
     group?: string;
     /** File mode to set via `chmod` (e.g. `"0755"`). */
@@ -416,6 +785,8 @@ type BaseDownloadOptions = {
     owner?: string;
     /** Expected SHA-256 hex digest for integrity verification. */
     sha256?: string;
+    /** Maximum time for the full curl transfer, in milliseconds. */
+    timeout?: number;
 };
 /**
  * Modules for downloading files to remote servers via `curl`.
@@ -431,6 +802,13 @@ declare const download: {
      * Idempotency follows the same rules as {@link download.url}: SHA-256
      * comparison when a digest is given, otherwise file-existence check.
      *
+     * R-0000805: same caveat as `download.url` — `allowUnverifiedDownload`
+     * stores the post-download sha256 in a read-only sibling marker
+     * (`<destination>.sha256`, mode 0o444) to detect later tampering, but a
+     * root-equivalent attacker can replace both the payload and the marker
+     * together. Prefer providing an explicit `sha256` from the GitHub
+     * release notes whenever it is available.
+     *
      * @param destination - Absolute path on the remote server where the asset is saved.
      * @param options - Repository coordinates and optional download settings.
      * @param options.repo - GitHub repository in `owner/repo` format (e.g. `"hashicorp/terraform"`).
@@ -466,10 +844,13 @@ declare const download: {
      * @param url - The URL to download from.
      * @param options - Optional settings for ownership, permissions, and headers.
      * @param options.allowInsecureHttp - Allow unencrypted `http://` downloads explicitly.
+     * @param options.allowInsecureHttpHeaders - Allow sending sensitive headers over unencrypted `http://` explicitly.
+     * @param options.connectTimeout - Maximum time to establish the curl connection, in milliseconds.
      * @param options.group - Group owner to set on the downloaded file via `chown`.
      * @param options.mode - File mode to set via `chmod` (e.g. `"0755"`).
      * @param options.owner - User owner to set on the downloaded file via `chown`.
      * @param options.sha256 - Expected SHA-256 hex digest for integrity verification.
+     * @param options.timeout - Maximum time for the full curl transfer, in milliseconds.
      * @param options.allowUnverifiedDownload - Explicitly opt out of integrity verification.
      * @param options.headers - Additional HTTP headers sent with the curl request.
      * @returns A Module that manages the large file download.
@@ -477,8 +858,12 @@ declare const download: {
     large(destination: string, url: string, options?: {
         /** Allow unencrypted `http://` downloads explicitly. */
         allowInsecureHttp?: boolean;
+        /** Allow sending sensitive headers over unencrypted `http://` explicitly. */
+        allowInsecureHttpHeaders?: boolean;
         /** Explicitly opt out of integrity verification for trusted sources. */
         allowUnverifiedDownload?: boolean;
+        /** Maximum time to establish the curl connection, in milliseconds. */
+        connectTimeout?: number;
         /** Group owner to set on the downloaded file via `chown`. */
         group?: string;
         /** Additional HTTP headers sent with the curl request. */
@@ -489,6 +874,8 @@ declare const download: {
         owner?: string;
         /** Expected SHA-256 hex digest for integrity verification. */
         sha256?: string;
+        /** Maximum time for the full curl transfer, in milliseconds. */
+        timeout?: number;
     }): Module;
     /**
      * Download a file from a URL to the remote server via `curl -fsSL`.
@@ -497,15 +884,31 @@ declare const download: {
      * provided), file existence (when no digest is given), or skipped entirely
      * when `force` is `true`.
      *
+     * R-0000805: when `allowUnverifiedDownload: true` is set, paratix stores
+     * the sha256 of the downloaded payload in a sibling marker file
+     * `<destination>.sha256` (mode 0o444) and re-verifies the destination
+     * against the marker on subsequent runs. The marker is a tampering
+     * detector, not a tampering preventer: an attacker with write access to
+     * the destination directory and root privileges can swap both the
+     * payload and the marker simultaneously, and the next `check` will then
+     * conclude the file is "in sync". The read-only mode raises the bar for
+     * an unprivileged attacker but does not substitute for a verified
+     * `sha256` digest. Provide `sha256` whenever an authoritative digest is
+     * known.
+     *
      * @param destination - Absolute path on the remote server where the file is saved.
      * @param url - The URL to download from.
      * @param options - Optional settings for integrity, ownership, and headers.
+     * @param options.allowInsecureHttp - Allow unencrypted `http://` downloads explicitly.
+     * @param options.allowInsecureHttpHeaders - Allow sending sensitive headers over unencrypted `http://` explicitly.
      * @param options.allowUnverifiedDownload - Explicitly opt out of integrity verification.
      * @returns A Module that manages the file download.
      */
     url(destination: string, url: string, options?: {
         /** Allow unencrypted `http://` downloads explicitly. */
         allowInsecureHttp?: boolean;
+        /** Allow sending sensitive headers over unencrypted `http://` explicitly. */
+        allowInsecureHttpHeaders?: boolean;
         /** Explicitly opt out of integrity verification for trusted sources. */
         allowUnverifiedDownload?: boolean;
         /** Force re-download even if the file already exists. */
@@ -555,9 +958,19 @@ declare function assemble(remotePath: string, fragments: string[], options?: {
  * @returns A Module that ensures the block is present with the correct content.
  */
 declare function block(remotePath: string, options: BlockOptions): Module;
+/** Desired settings passed by the caller. */
+type PropertiesOptions = {
+    group?: string;
+    mode?: string;
+    owner?: string;
+};
 /**
  * Set file or directory ownership and permissions on the remote host.
- * Only the attributes specified in `options` are checked and applied.
+ * Only the attributes specified in `options` are checked and applied. Drift
+ * is detected via `stat -c '%a %U %G'` so `apply` only invokes the relevant
+ * `chmod`/`chown`/`chgrp` for fields that actually differ from the desired
+ * state. When all desired fields already match, `apply` returns `status: "ok"`
+ * instead of falsely reporting a change.
  *
  * @param remotePath - Path to the file or directory on the remote host.
  * @param options - Attributes to enforce.
@@ -566,14 +979,14 @@ declare function block(remotePath: string, options: BlockOptions): Module;
  * @param options.owner - Optional owner name.
  * @returns A Module that ensures the properties match.
  */
-declare function properties(remotePath: string, options: {
-    group?: string;
-    mode?: string;
-    owner?: string;
-}): Module;
+declare function properties(remotePath: string, options: PropertiesOptions): Module;
 /**
  * Replace all occurrences of a regex pattern in a remote file.
- * `check` uses `grep -E` to detect whether the pattern still exists in the file.
+ * `check` reads the file, applies the same replacement that `apply` would
+ * perform, and reports `needs-apply` only when the resulting content differs
+ * from the current content. This makes the module idempotent for cases where
+ * the replacement string still matches the pattern (e.g. pattern `"foo"` and
+ * replacement `"foobar"`).
  * `apply` reads the file, performs the replacement in TypeScript and writes it back.
  *
  * @param remotePath - Path to the file on the remote host.
@@ -623,7 +1036,10 @@ declare const file: {
      * @param remotePath - Destination path on the remote host.
      * @param localPath - Source path on the local filesystem.
      * @param options - Optional file attributes.
-     * @param options.mode - Optional chmod mode string (e.g. `"0644"`).
+     * @param options.mode - Optional chmod mode string (e.g. `"0644"`). When omitted,
+     *   the file is created with the documented default `"0644"`
+     *   (`"0644"`) instead of inheriting whatever default `ssh.uploadFile` happens
+     *   to choose for its temp file.
      * @param options.owner - Optional chown owner string (e.g. `"www-data:www-data"`).
      * @returns A Module that copies the file to the remote host.
      */
@@ -650,7 +1066,7 @@ declare const file: {
      * with the new `line` value instead of appending.
      *
      * @param remotePath - Path to the file on the remote host.
-     * @param line - The exact line content to ensure is present.
+     * @param line - The exact single-line content to ensure is present.
      * @param options - Optional match configuration.
      * @param options.match - A regex pattern; when matched, the line is replaced rather than appended.
      * @returns A Module that ensures the line is present.
@@ -690,8 +1106,8 @@ declare const git: {
      *
      * If the destination directory does not yet contain a `.git` folder, the
      * repository is cloned from scratch. If it already exists, the repository is
-     * updated instead (fetch + checkout + reset). When no `ref` is specified, a
-     * plain `git pull` is performed on an existing clone.
+     * updated instead (fetch + checkout + reset). When no `ref` is specified,
+     * the existing clone is reset to the current remote default branch HEAD.
      *
      * @param repo - The repository URL to clone.
      * @param destination - The destination path on the remote host.
@@ -716,7 +1132,9 @@ declare const group: {
      */
     absent(name: string): Module;
     /**
-     * Ensure a group exists. Creates it via `groupadd` if absent.
+     * Ensure a group exists. Creates it via `groupadd` if absent. When the
+     * group already exists but its GID differs from `options.gid`, the GID
+     * is healed via `groupmod -g <gid>` so the drift becomes recoverable.
      *
      * @param name - The group name.
      * @param options - Optional group configuration.
@@ -767,11 +1185,10 @@ declare const mount: {
      * Ensure a filesystem is mounted at the given path. Creates the mountpoint
      * directory if it does not exist. Optionally persists the mount in `/etc/fstab`.
      *
-     * The check phase verifies that the mountpoint is active (via `findmnt`) and,
-     * when `persist` is `true`, that the fstab entry matches the desired line
-     * exactly. It does **not** compare the currently mounted source, filesystem
-     * type, or options against the desired values — a remount is only triggered
-     * when the mountpoint is absent entirely.
+     * The check phase verifies that the mountpoint is active (via `findmnt`), that
+     * its live source / filesystem type / normalized options match the desired
+     * values, and, when `persist` is `true`, that the fstab entry matches the
+     * desired line exactly.
      *
      * @param options - Configuration for the mount.
      * @param options.fstype - The filesystem type (e.g. `"ext4"`, `"tmpfs"`, `"nfs"`).
@@ -842,17 +1259,23 @@ declare const net: {
      *
      * @param url - The URL to request.
      * @param options - Optional request settings.
+     * @param options.allowInsecureHttpHeaders - When `true`, allow sending sensitive headers (e.g. `Authorization`, `Cookie`) over plaintext `http://`. Default `false` rejects such combinations to prevent credential leakage.
      * @param options.body - Expected string in the response body.
+     * @param options.connectTimeout - Maximum time to establish the curl connection, in milliseconds.
      * @param options.headers - Additional HTTP headers.
      * @param options.method - HTTP method (default: `"GET"`).
      * @param options.status - Expected HTTP status code (default: `200`).
+     * @param options.timeout - Maximum time for the full curl request, in milliseconds.
      * @returns A Module that checks the HTTP endpoint.
      */
     request(url: string, options?: {
+        allowInsecureHttpHeaders?: boolean;
         body?: string;
+        connectTimeout?: number;
         headers?: Record<string, string>;
         method?: string;
         status?: number;
+        timeout?: number;
     }): Module;
     /**
      * Manage /etc/resolv.conf (nameservers and search domains).
@@ -896,7 +1319,7 @@ declare const op: {
     /**
      * Resolve 1Password secret references into environment values.
      *
-     * Regular references are resolved in bulk via `op inject`.
+     * Regular references are resolved via `op read`.
      * References ending in `/one-time-password` or `/otp` are resolved individually
      * via `op read` and returned as lazy functions that compute a fresh TOTP code
      * on each call.
@@ -1024,6 +1447,28 @@ declare const quadlet: {
     updateImage(options: QuadletImageUpdateOptions): Module;
 };
 
+/**
+ * Shared helper for the `resolveHost` callback used by reboot-style modules
+ * (`system.reboot`, `releaseUpgrade.upgrade`). Wraps the caller-supplied
+ * resolver in a wall-clock timeout so a hanging DNS/cloud lookup cannot
+ * stall the entire playbook indefinitely.
+ *
+ * R-0000243: previously the resolver was awaited unconditionally — a stuck
+ * cloud-metadata or DNS request would keep the module pending forever
+ * because the runner has no inherent timeout for module callbacks.
+ */
+
+/**
+ * R-0000575: callable shape for `resolveHost`. The optional `AbortSignal`
+ * argument lets callers like `resolveHostWithTimeout` signal cancellation
+ * when the wall-clock timeout elapses, so a long-running DNS/cloud lookup
+ * can drop its in-flight work instead of running to completion in the
+ * background. The argument is optional to keep existing zero-arg callbacks
+ * source-compatible — callers that don't care can keep their current
+ * signature.
+ */
+type ResolveHostCallback = (signal?: AbortSignal) => Promise<string>;
+
 /**
  * Options for the {@link releaseUpgrade.upgrade} module.
  */
@@ -1038,8 +1483,20 @@ type ReleaseUpgradeOptions = {
      * post-upgrade reboot. Useful when the server's IP address may change
      * (e.g. DHCP or cloud environments). The resolved value is emitted as
      * `system.host` meta so the runner can reconnect to the correct address.
+     *
+     * R-0000575: the callback receives an `AbortSignal` that fires when the
+     * configured timeout elapses. Honoring the signal lets DNS/cloud lookups
+     * abort their in-flight work promptly.
+     */
+    resolveHost?: ResolveHostCallback;
+    /**
+     * Wall-clock timeout (ms) applied to {@link ReleaseUpgradeOptions.resolveHost}.
+     * Defaults to 30 seconds (R-0000243) so a hanging DNS/cloud lookup cannot
+     * stall the playbook indefinitely.
      */
-    resolveHost?: () => Promise<string>;
+    resolveHostTimeoutMs?: number;
+    /** Override the per-step command timeout (ms). Default: 30 minutes. */
+    timeout?: number;
 };
 /**
  * Modules for upgrading the operating system to the next major release.
@@ -1114,6 +1571,8 @@ type SyncOptions = {
      * (not recommended for production).
      */
     strictHostKeyChecking?: "accept-new" | "no" | "off" | "yes";
+    /** Maximum runtime for a single rsync process in milliseconds. */
+    timeout?: number;
 };
 /**
  * Modules for synchronizing files to a remote host using rsync.
@@ -1230,7 +1689,12 @@ type KnownHostsOptions = {
     expectedFingerprint?: string;
     port?: number;
     publicKey?: string;
-    state?: "absent" | "present";
+    state?: KnownHostsState;
+};
+type KnownHostsState = "absent" | "present";
+type AuthorizedKeysState = "absent" | "present";
+type AuthorizedKeysOptions = {
+    state?: AuthorizedKeysState;
 };
 /**
  * Modules for managing SSH client-side resources such as known hosts
@@ -1250,14 +1714,12 @@ declare const ssh: {
      * @param options.state - Whether the key should be `"present"` or `"absent"`. Defaults to `"present"`.
      * @returns A Module that manages the authorized key entry.
      */
-    authorizedKeys(user: string, key: string, options?: {
-        state?: "absent" | "present";
-    }): Module;
+    authorizedKeys(user: string, key: string, options?: AuthorizedKeysOptions): Module;
     /**
      * Ensure a host is present in (or absent from) the connecting user's `~/.ssh/known_hosts`.
      *
      * When `state` is `"present"` (the default), the host's public keys are fetched
-     * via `ssh-keyscan` and appended to `~/.ssh/known_hosts`. When `state` is
+     * via `ssh-keyscan` and written to `~/.ssh/known_hosts`. When `state` is
      * `"absent"`, the host entry is removed via `ssh-keygen -R`.
      *
      * @param host - The hostname or IP address to manage.
@@ -1294,6 +1756,61 @@ declare const sshd: {
     port(targetPort: number): Module;
 };
 
+/**
+ * Modules for managing swap files and common swap-related kernel tuning.
+ */
+declare const swap: {
+    /**
+     * Ensure a file-backed swap area exists, is activated, and is persisted in `/etc/fstab`.
+     *
+     * @param options - Configuration for the swap file.
+     * @param options.mode - File mode applied to the swap file. Defaults to `0600`.
+     * @param options.path - Absolute path to the swap file, e.g. `/swapfile`.
+     * @param options.priority - Optional swap priority written into the fstab entry.
+     * @param options.size - Desired file size as bytes or a shell-friendly size string such as `2G`.
+     * @param options.state - Whether the swap file should be `present` (default) or `absent`.
+     * @returns A Module that manages the swap file lifecycle.
+     */
+    file(options: {
+        mode?: string;
+        path: string;
+        priority?: number;
+        size: number | string;
+        state?: "absent" | "present";
+    }): Module;
+    /**
+     * Persist `vm.swappiness`.
+     *
+     * @param value - Desired swappiness value.
+     * @returns A Module that manages `vm.swappiness`.
+     */
+    swappiness(value: number): Module;
+    /**
+     * Persist `vm.vfs_cache_pressure`.
+     *
+     * @param value - Desired VFS cache pressure value.
+     * @returns A Module that manages `vm.vfs_cache_pressure`.
+     */
+    vfsCachePressure(value: number): Module;
+};
+
+/**
+ * Options for {@link sysctl.set}.
+ */
+type SysctlSetOptions = {
+    /**
+     * When `state` is `"absent"`, optionally restore this live runtime value
+     * after removing the persistence file. Without `resetValue`, only the
+     * persistence file is removed and the live kernel value remains unchanged
+     * until the next reboot.
+     *
+     * Use this for security-relevant parameters (e.g. resetting
+     * `net.ipv4.ip_forward` to `"0"`) where leaving the live value in place
+     * would silently violate the desired absent state.
+     */
+    resetValue?: string;
+    state?: "absent" | "present";
+};
 /**
  * Modules for managing kernel parameters via sysctl on the remote host.
  */
@@ -1302,21 +1819,24 @@ declare const sysctl: {
      * Set a sysctl kernel parameter and persist it across reboots.
      *
      * The live value is applied immediately via `sysctl -w` and a configuration
-     * file is written to `/etc/sysctl.d/99-paratix-<sanitized-key>.conf` for
-     * persistence.
+     * file is written to `/etc/sysctl.d/99-paratix-<sanitized-key>-<hash>.conf`
+     * for persistence.
      *
-     * When `state` is `"absent"`, the persistence file is removed but the live
-     * value is not reverted (a reboot will restore the default).
+     * When `state` is `"absent"`, the persistence file is removed. By default
+     * the live value is not reverted (a reboot will restore the default). Pass
+     * `resetValue` to additionally write the desired runtime value back to the
+     * kernel via `sysctl -w` so the absent state converges on the live system
+     * as well.
      *
      * @param key - The sysctl key (e.g. "net.ipv4.ip_forward").
      * @param value - The desired value (e.g. "1").
      * @param options - Optional settings.
      * @param options.state - Whether the parameter should be "present" (default) or "absent".
+     * @param options.resetValue - Live runtime value to restore when `state` is `"absent"`.
+     *   Ignored when `state` is `"present"`.
      * @returns A Module that manages the sysctl parameter.
      */
-    set(key: string, value: string, options?: {
-        state?: "absent" | "present";
-    }): Module;
+    set(key: string, value: string, options?: SysctlSetOptions): Module;
 };
 
 /**
@@ -1326,8 +1846,19 @@ type RebootOptions = {
     /**
      * Optional async function to resolve the new host address after a reboot.
      * Useful when the server's IP address may change (e.g. DHCP or cloud environments).
+     *
+     * R-0000575: the callback receives an `AbortSignal` that fires when the
+     * configured timeout elapses. Honoring the signal lets DNS/cloud lookups
+     * abort their in-flight work promptly.
+     */
+    resolveHost?: ResolveHostCallback;
+    /**
+     * Wall-clock timeout (ms) applied to {@link RebootOptions.resolveHost}.
+     * Defaults to 30 seconds. Mirrors R-0000243 in
+     * {@link import("./releaseUpgrade.js")} so a stuck resolver cannot stall
+     * the runner indefinitely.
      */
-    resolveHost?: () => Promise<string>;
+    resolveHostTimeoutMs?: number;
 };
 /**
  * Modules for managing system-level operations.
@@ -1405,6 +1936,74 @@ declare const systemd: {
     unmasked(name: string): Module;
 };
 
+/** Options for `timer.scheduled`. */
+type TimerScheduledOptions = {
+    /** Optional `AccuracySec=` for the `[Timer]` section. */
+    accuracySec?: number | string;
+    /** Description used in both unit `[Unit]` sections. Defaults to `Paratix scheduled task: <name>`. */
+    description?: string;
+    /** Extra environment variables rendered as `Environment=KEY=VAL` lines in `[Service]`. */
+    environment?: Record<string, string>;
+    /** The single command line written as `ExecStart=` in the generated `.service`. */
+    exec: string;
+    /** Optional `Group=` for the `[Service]` section. */
+    group?: string;
+    /** Calendar specification(s) written as one or more `OnCalendar=` lines. */
+    onCalendar: string | string[];
+    /** Whether `Persistent=true` is written into the `[Timer]` section. Defaults to `true`. */
+    persistent?: boolean;
+    /** Optional `RandomizedDelaySec=` for the `[Timer]` section. */
+    randomizedDelaySec?: number | string;
+    /** Whether the timer should be `"present"` or `"absent"`. Defaults to `"present"`. */
+    state?: "absent" | "present";
+    /** Optional `User=` for the `[Service]` section. */
+    user?: string;
+    /** Optional `WorkingDirectory=` for the `[Service]` section. */
+    workingDirectory?: string;
+};
+
+declare const timer: {
+    /**
+     * Ensure a systemd timer-driven scheduled task does not exist.
+     *
+     * Disables and stops `<name>.timer`, removes both `<name>.service` and
+     * `<name>.timer` from `/etc/systemd/system/`, and reloads systemd. The
+     * `disable --now` step also removes the timer's `wants/` symlink. Failure
+     * to disable a unit that does not exist is ignored, so this method is
+     * safe to apply repeatedly.
+     *
+     * Behaves like `timer.scheduled(name, { exec: "<unused>", onCalendar: "<unused>", state: "absent" })`,
+     * but does not require placeholder values for `exec` or `onCalendar` and
+     * reports failures with a `timer.absent` prefix instead of `timer.scheduled`.
+     *
+     * @param name - Base unit name without extension. Must match
+     *   `^[A-Za-z0-9_\-]+$`.
+     * @returns A Module that ensures the timer-driven scheduled task is absent.
+     */
+    absent(name: string): Module;
+    /**
+     * Ensure a systemd timer-driven scheduled task is present (or absent).
+     *
+     * Generates `<name>.service` (`Type=oneshot`, no `[Install]` section since
+     * it is triggered exclusively by the timer) and `<name>.timer` under
+     * `/etc/systemd/system/`, reloads systemd, and runs
+     * `systemctl enable --now <name>.timer`. When the timer unit content
+     * changed, the timer is restarted so a new `OnCalendar=` schedule is picked
+     * up immediately. With `state: "absent"`, the timer is disabled and
+     * stopped, both unit files are removed, and systemd is reloaded.
+     *
+     * Validation of `exec`, `description`, `user`, `group`, `workingDirectory`,
+     * `environment` and `onCalendar` only runs when `state` is `"present"`,
+     * so callers can pass placeholder values when removing a timer.
+     *
+     * @param name - Base unit name without extension. Used as `<name>.service`
+     *   and `<name>.timer`. Must match `^[A-Za-z0-9_\-]+$`.
+     * @param options - Schedule, command, optional service hardening, and state.
+     * @returns A Module that manages the timer-driven scheduled task.
+     */
+    scheduled(name: string, options: TimerScheduledOptions): Module;
+};
+
 /**
  * Modules for managing the UFW (Uncomplicated Firewall) on Debian/Ubuntu hosts.
  */
@@ -1435,6 +2034,7 @@ declare const ufw: {
 type UserOptions = {
     groups?: string[];
     home?: string;
+    homeMode?: string;
     password?: string;
     shell?: string;
     uid?: number;
@@ -1458,16 +2058,33 @@ declare const user: {
      * Ensure a user account exists. Creates the account if absent, or runs
      * `usermod` to update attributes if the user already exists.
      *
+     * Supplementary group membership is additive: when `options.groups` is set
+     * and the user already exists, `usermod --append --groups <list>` is used so
+     * preexisting memberships not managed by Paratix (e.g. `sudo`, `docker`,
+     * manually added groups) are preserved across re-applies. The `groups`
+     * option therefore expresses "ensure the user is a member of these groups",
+     * not "the user must be a member of exactly these supplementary groups".
+     *
+     * When `home` is provided, `usermod --move-home` migrates the existing
+     * contents to the new path (instead of leaving the user pointing at an
+     * empty directory with the old contents stranded on disk). The home
+     * directory's permission bits are then enforced via `chmod`; the default
+     * mode is `0700` so dot-files in a freshly created home cannot be read
+     * by other local accounts even on hosts where `/etc/login.defs` sets
+     * `HOME_MODE=0755`.
+     *
      * @param name - The username.
      * @param options - Optional user account configuration.
      * @param options.uid - Desired numeric UID.
      * @param options.shell - Login shell path (e.g. `"/bin/bash"`).
      * @param options.home - Home directory path.
-     * @param options.groups - Supplementary groups to add the user to.
+     * @param options.homeMode - Octal permission bits for the home directory
+     *   (e.g. `"0700"`, `"750"`). Requires `home`. Defaults to `"0700"`.
+     * @param options.groups - Supplementary groups to add the user to (additive).
      * @param options.password - Pre-hashed password (e.g. SHA-512 `$6$...`) set via `chpasswd -e`.
      * @returns A Module that ensures the user account is present.
      */
     present(name: string, options?: UserOptions): Module;
 };
 
-export { type UpgradeOptions as U, apt as a, archive as b, command as c, compose as d, cron as e, download as f, file as g, git as h, group as i, hostname as j, rsync as k, service as l, mount as m, net as n, op as o, pkg as p, quadlet as q, releaseUpgrade as r, script as s, ssh as t, sshd as u, sysctl as v, system as w, systemd as x, ufw as y, user as z };
+export { op as A, pkg as B, quadlet as C, releaseUpgrade as D, type Environment as E, rsync as F, script as G, service as H, ssh as I, sshd as J, swap as K, sysctl as L, type Module as M, NEEDS_APPLY as N, type OrchestrationStep as O, system as P, systemd as Q, timer as R, type SshdPortMetaEntry as S, ufw as T, user as U, type UpgradeOptions as V, type ModuleMetaEntry as a, type MetaEnvironmentValue as b, type EnvironmentMetaEntry as c, type SystemHostMetaEntry as d, type SystemRebootMetaEntry as e, type ModuleResult as f, type ExecResult as g, type ModuleStatus as h, type SshConnection as i, type ShutdownSignal as j, type ServerDefinition as k, type EnvironmentValue as l, type ExecOptions as m, type SshConfig as n, apt as o, archive as p, command as q, compose as r, cron as s, download as t, file as u, git as v, group as w, hostname as x, mount as y, net as z };