@zero-transfer/sdk 0.4.7 → 0.4.8

package/dist/index.d.ts

@@ -400,6 +400,10 @@ interface TlsProfile {
      * trust via `rejectUnauthorized`. Pinning is **recommended for production** when you control
      * the server and want defence-in-depth against rogue certificates issued by trusted CAs.
      *
+     * Cannot be combined with `rejectUnauthorized: false`: pin verification runs after the TLS
+     * handshake is accepted, so chain validation must stay enabled. Use `ca` for self-signed
+     * certificates.
+     *
      * @example "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
      */
     pinnedFingerprint256?: string | readonly string[];
@@ -677,10 +681,42 @@ interface TransferBandwidthLimit {
     /** Optional burst allowance in bytes for token-bucket-style implementations. */
     burstBytes?: number;
 }
-/** Timeout policy applied by the transfer engine. */
+/**
+ * Timeout policy applied by the transfer engine.
+ *
+ * Two timeout scopes exist with deliberately different failure semantics:
+ *
+ * - **Job scope** ({@link timeoutMs}): covers the full engine execution
+ *   including retries. When it fires, the engine rethrows the
+ *   {@link TimeoutError} immediately - the retry policy is never consulted.
+ * - **Attempt scope** ({@link attemptTimeoutMs} and {@link stallTimeoutMs}):
+ *   covers a single attempt. When either fires, the per-attempt abort
+ *   controller cancels the attempt and the resulting {@link TimeoutError}
+ *   flows into the retry policy like any other attempt failure, so retryable
+ *   timeouts are retried (with backoff) instead of failing the job.
+ *
+ * @example Retry stalled attempts, but never run longer than 10 minutes total
+ * ```ts
+ * await engine.execute(job, executor, {
+ *   retry: createDefaultRetryPolicy(),
+ *   timeout: { timeoutMs: 600_000, attemptTimeoutMs: 120_000, stallTimeoutMs: 30_000 },
+ * });
+ * ```
+ */
 interface TransferTimeoutPolicy {
     /** Maximum duration for the full engine execution, including retries, in milliseconds. */
     timeoutMs?: number;
+    /**
+     * Maximum duration for a single attempt in milliseconds. Expiry aborts only
+     * the active attempt; the failure flows into the retry policy.
+     */
+    attemptTimeoutMs?: number;
+    /**
+     * Maximum time without progress before an attempt is considered stalled, in
+     * milliseconds. The watchdog resets on every progress report; expiry aborts
+     * only the active attempt and the failure flows into the retry policy.
+     */
+    stallTimeoutMs?: number;
     /** Whether timeout failures are retryable. Defaults to `true`. */
     retryable?: boolean;
 }
@@ -805,15 +841,31 @@ interface TransferRetryDecisionInput {
     error: unknown;
     /** One-based attempt number that failed. */
     attempt: number;
+    /** Milliseconds elapsed since the engine execution started, including prior attempts and delays. */
+    elapsedMs: number;
     /** Job being executed. */
     job: TransferJob;
 }
-/** Retry policy for transfer execution. */
+/**
+ * Retry policy for transfer execution.
+ *
+ * Use {@link createDefaultRetryPolicy} for a production-ready policy with
+ * exponential backoff, full jitter, and `Retry-After` support, or implement
+ * the hooks directly for full control.
+ */
 interface TransferRetryPolicy {
     /** Maximum total attempts, including the first attempt. Defaults to `1`. */
     maxAttempts?: number;
     /** Decides whether a failed attempt should be retried. Defaults to SDK retryability metadata. */
     shouldRetry?(input: TransferRetryDecisionInput): boolean;
+    /**
+     * Computes the delay before the next attempt in milliseconds.
+     *
+     * The engine sleeps for the returned duration with an abort-aware timer:
+     * cancelling the job during the delay rejects immediately instead of
+     * waiting out the backoff. Non-positive or missing values retry at once.
+     */
+    getDelayMs?(input: TransferRetryDecisionInput): number;
     /** Observes retry decisions before the next attempt starts. */
     onRetry?(input: TransferRetryDecisionInput): void;
 }
@@ -847,7 +899,12 @@ interface TransferEngineOptions {
  *
  * @example Execute a single job with a custom executor
  * ```ts
- * import { TransferEngine, type TransferExecutor, type TransferJob } from "@zero-transfer/sdk";
+ * import {
+ *   TransferEngine,
+ *   createDefaultRetryPolicy,
+ *   type TransferExecutor,
+ *   type TransferJob,
+ * } from "@zero-transfer/sdk";
  *
  * const engine = new TransferEngine();
  *
@@ -865,7 +922,8 @@ interface TransferEngineOptions {
  * };
  *
  * const receipt = await engine.execute(job, executor, {
- *   retry: { maxAttempts: 3, baseDelayMs: 250 },
+ *   retry: createDefaultRetryPolicy(),
+ *   timeout: { stallTimeoutMs: 30_000 },
  * });
  * console.log(receipt.attempts.length); // 1 on success
  * ```
@@ -1087,6 +1145,40 @@ declare class ProviderRegistry {
     listCapabilities(): CapabilitySet[];
 }
 
+/**
+ * Client-level execution defaults applied when a call site does not supply
+ * its own value.
+ *
+ * Defaults are consumed by {@link runRoute}, the one-shot helpers
+ * ({@link uploadFile}, {@link downloadFile}, {@link copyBetween}),
+ * {@link TransferQueue} (via its `client` option), and scheduled routes fired
+ * through {@link MftScheduler}. The {@link TransferEngine} primitive stays
+ * fully explicit: defaults never reach `engine.execute()` directly.
+ *
+ * Per-call options always win over client defaults.
+ *
+ * Additional default slots (`verify`, `resume`, `compression`, `policy`) land
+ * here as their features ship in later releases; the shape is additive.
+ *
+ * @example Resilient defaults for every transfer in an application
+ * ```ts
+ * import { createDefaultRetryPolicy, createTransferClient } from "@zero-transfer/sdk";
+ *
+ * const client = createTransferClient({
+ *   providers: [createSftpProviderFactory(), createS3ProviderFactory()],
+ *   defaults: {
+ *     retry: createDefaultRetryPolicy(),
+ *     timeout: { stallTimeoutMs: 30_000 },
+ *   },
+ * });
+ * ```
+ */
+interface TransferClientDefaults {
+    /** Default retry policy for transfers executed through this client. */
+    retry?: TransferRetryPolicy;
+    /** Default timeout policy for transfers executed through this client. */
+    timeout?: TransferTimeoutPolicy;
+}
 /** Options used to create a provider-neutral transfer client. */
 interface TransferClientOptions {
     /** Existing registry to reuse. When omitted, a fresh empty registry is created. */
@@ -1095,16 +1187,20 @@ interface TransferClientOptions {
     providers?: ProviderFactory[];
     /** Structured logger used for client lifecycle records. */
     logger?: ZeroTransferLogger;
+    /** Execution defaults applied when call sites omit their own values. */
+    defaults?: TransferClientDefaults;
 }
 /** Small provider-neutral client that owns provider lookup and connection setup. */
 declare class TransferClient {
     /** Provider registry used by this client. */
     readonly registry: ProviderRegistry;
+    /** Execution defaults applied when call sites omit their own values. */
+    readonly defaults?: TransferClientDefaults;
     private readonly logger;
     /**
      * Creates a transfer client without opening any provider connections.
      *
-     * @param options - Optional registry, provider factories, and logger.
+     * @param options - Optional registry, provider factories, logger, and execution defaults.
      */
     constructor(options?: TransferClientOptions);
     /**
@@ -1438,11 +1534,11 @@ interface RunRouteOptions {
     now?: () => Date;
     /** Abort signal used to cancel the route execution. */
     signal?: AbortSignal;
-    /** Retry policy forwarded to the engine. */
+    /** Retry policy forwarded to the engine. Falls back to `client.defaults.retry`. */
     retry?: TransferRetryPolicy;
     /** Progress observer forwarded to the engine. */
     onProgress?: (event: TransferProgressEvent) => void;
-    /** Timeout policy forwarded to the engine. */
+    /** Timeout policy forwarded to the engine. Falls back to `client.defaults.timeout`. */
     timeout?: TransferTimeoutPolicy;
     /** Optional bandwidth limit forwarded to the engine. */
     bandwidthLimit?: TransferBandwidthLimit;
@@ -1464,7 +1560,12 @@ interface RunRouteOptions {
  *
  * @example Run a pre-built route with progress + retry
  * ```ts
- * import { createTransferClient, runRoute, type MftRoute } from "@zero-transfer/sdk";
+ * import {
+ *   createDefaultRetryPolicy,
+ *   createTransferClient,
+ *   runRoute,
+ *   type MftRoute,
+ * } from "@zero-transfer/sdk";
  *
  * const route: MftRoute = {
  *   id: "nightly-export",
@@ -1483,7 +1584,7 @@ interface RunRouteOptions {
  *   client,
  *   route,
  *   onProgress: (e) => console.log(`${e.bytesTransferred}/${e.totalBytes ?? "?"}`),
- *   retry: { maxAttempts: 3, baseDelayMs: 500 },
+ *   retry: createDefaultRetryPolicy({ maxAttempts: 3 }),
  * });
  * console.log(`Job ${receipt.jobId} moved ${receipt.bytesTransferred} bytes…`);
  * ```
@@ -2271,6 +2372,12 @@ interface HttpProviderOptions {
     fetch?: HttpFetch;
     /** Default headers applied to every request. */
     defaultHeaders?: Record<string, string>;
+    /**
+     * Rejects factory creation when the transport is cleartext `http`. Defaults
+     * to `false`, where connecting with credentials over cleartext emits a
+     * process `SecurityWarning` instead of failing.
+     */
+    enforceHttps?: boolean;
 }
 /**
  * Creates a provider factory backed by HTTP(S) GET/HEAD.
@@ -2329,20 +2436,26 @@ interface WebDavProviderOptions {
     fetch?: HttpFetch;
     /** Default headers applied to every request. */
     defaultHeaders?: Record<string, string>;
+    /**
+     * Rejects factory creation when the transport is cleartext `http`. Defaults
+     * to `false`, where connecting with credentials over cleartext emits a
+     * process `SecurityWarning` instead of failing.
+     */
+    enforceHttps?: boolean;
     /**
      * Streaming policy for `PUT` request bodies.
      *
-     * - `"when-known-size"` (default) - stream when the caller declares
-     *   `request.totalBytes` (an explicit `Content-Length` is sent so all
-     *   WebDAV servers accept the upload); otherwise buffer the entire body in
-     *   memory before sending. This is the safe default that does not require
-     *   the server to accept HTTP/1.1 chunked transfer-encoding.
-     * - `"always"` - always stream the body, even when the size is unknown
-     *   (the runtime will use chunked transfer-encoding). Some legacy WebDAV
-     *   servers reject `Transfer-Encoding: chunked` and will respond `411
-     *   Length Required` or `501 Not Implemented`; only enable this for
-     *   servers known to accept chunked uploads (modern Apache/nginx, IIS
-     *   with chunked transfer enabled, Nextcloud, ownCloud, sabre/dav).
+     * - `"always"` (default since 0.5) - always stream the body so memory use
+     *   stays bounded regardless of payload size. When the caller declares
+     *   `request.totalBytes` an explicit `Content-Length` is still sent (no
+     *   chunked encoding); only unknown-size uploads fall back to HTTP/1.1
+     *   chunked transfer-encoding. Some legacy WebDAV servers reject
+     *   `Transfer-Encoding: chunked` and respond `411 Length Required` or
+     *   `501 Not Implemented`; point those at `"when-known-size"`.
+     * - `"when-known-size"` (default before 0.5) - stream only when
+     *   `request.totalBytes` is known; unknown-size bodies are buffered
+     *   entirely in memory so a `Content-Length` can always be sent. Use for
+     *   servers that require a declared length on every upload.
      * - `"never"` - always buffer (legacy behaviour pre-0.4.0). Use for
      *   maximum compatibility at the cost of memory.
      */
@@ -2407,7 +2520,7 @@ interface S3ProviderOptions {
     defaultHeaders?: Record<string, string>;
     /** Optional STS session token applied to every request. */
     sessionToken?: SecretSource;
-    /** Multipart upload tuning. Disabled by default; enable for objects above ~5 GiB or when streaming. */
+    /** Multipart upload tuning. Enabled by default; see {@link S3MultipartOptions.enabled}. */
     multipart?: S3MultipartOptions;
 }
 /** Multipart upload tuning for the S3 provider. */
@@ -2417,8 +2530,11 @@ interface S3MultipartOptions {
      * in fixed-size parts instead of being buffered in memory before a single
      * `PUT`. Payloads at or below {@link S3MultipartOptions.thresholdBytes}
      * still fall back to a single-shot `PUT` automatically. Set to `false` to
-     * force the legacy single-shot behaviour (e.g. when targeting an
-     * S3-compatible endpoint that does not support `CreateMultipartUpload`).
+     * force single-shot behaviour (e.g. when targeting an S3-compatible
+     * endpoint that does not support `CreateMultipartUpload`). Single-shot
+     * uploads stream with `UNSIGNED-PAYLOAD` signing when the total size is
+     * known; S3 requires a `Content-Length` up front, so unknown-size payloads
+     * are buffered entirely in memory on this path.
      */
     enabled?: boolean;
     /** Object size threshold in bytes above which multipart is used. Defaults to 8 MiB. */
@@ -2774,8 +2890,13 @@ interface FileZillaSite {
     folder: readonly string[];
     /** Generated connection profile. */
     profile: ConnectionProfile;
-    /** Encoded password value retained from the file, if any. */
-    password?: string;
+    /**
+     * Whether the FileZilla entry stored a password. The importer never decodes
+     * or returns stored passwords; supply the credential via a
+     * {@link ConnectionProfile.password | SecretSource} (for example
+     * `{ env: "SITE_PASSWORD" }` or `{ path: "./secret" }`) before connecting.
+     */
+    hasStoredPassword: boolean;
     /** Logon type code preserved from the file (`0`=anonymous, `1`=normal, etc.). */
     logonType?: number;
 }
@@ -2832,16 +2953,6 @@ interface ImportWinScpSessionsResult {
  */
 declare function importWinScpSessions(ini: string): ImportWinScpSessionsResult;
 
-/**
- * Structured ZeroTransfer error hierarchy.
- *
- * The classes in this module preserve protocol details, retryability, command/path
- * context, and machine-readable codes so application code does not need to parse
- * human error messages.
- *
- * @module errors/ZeroTransferError
- */
-
 /**
  * Complete set of fields required to create a ZeroTransfer error.
  */
@@ -2907,6 +3018,11 @@ declare class ZeroTransferError extends Error {
     /**
      * Serializes the error into a plain object suitable for logs or API responses.
      *
+     * `details` and `command` are passed through secret redaction so serialized
+     * errors never leak credentials, signed URLs, or raw protocol commands. The
+     * live {@link ZeroTransferError.details | details} property stays unredacted
+     * for programmatic consumers.
+     *
      * @returns A JSON-safe object containing public structured error fields.
      */
     toJSON(): Record<string, unknown>;
@@ -3110,6 +3226,32 @@ declare function redactValue(value: unknown): unknown;
  * @returns A shallow object copy with sensitive fields and nested secrets redacted.
  */
 declare function redactObject(input: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Strips credentials and query/fragment content from a URL before logging.
+ *
+ * Query strings routinely carry bearer material - SigV4 `X-Amz-Signature`
+ * values, SAS tokens, signed-URL parameters - so the entire search and hash
+ * segments are replaced rather than filtered key-by-key. Embedded
+ * `user:password@` userinfo is removed. Origin and pathname are preserved
+ * because they are what operators need to correlate a failing request.
+ *
+ * @param url - Absolute URL string or `URL` instance to sanitize.
+ * @returns A loggable URL string, or {@link REDACTED} when the value cannot be
+ * parsed as a URL (an unparsable value may still embed credentials).
+ */
+declare function redactUrlForLogging(url: string | URL): string;
+/**
+ * Converts an arbitrary thrown value into a JSON-safe, secret-free record.
+ *
+ * Structured SDK errors are serialized through their `toJSON()` (which already
+ * redacts details); plain errors contribute name/message/stack-free context;
+ * other values are stringified. Use this at every internal log site that
+ * records a caught error.
+ *
+ * @param error - Caught value of unknown shape.
+ * @returns A redacted, JSON-safe object describing the error.
+ */
+declare function redactErrorForLogging(error: unknown): Record<string, unknown>;
 
 /** Algorithm lists exchanged during SSH KEXINIT negotiation. */
 interface SshAlgorithmPreferences {
@@ -3710,7 +3852,7 @@ interface RunSshCommandResult {
  * stdout, and disconnects. The TCP socket, transport, auth session, and
  * channel are all owned by this helper and torn down before it returns.
  *
- * @example Run `uname -a` with a password credential
+ * @example Run uname -a with a password credential
  * ```ts
  * import { runSshCommand } from "@zero-transfer/ssh";
  *
@@ -4329,6 +4471,73 @@ declare function createBandwidthThrottle(limit: TransferBandwidthLimit | undefin
  */
 declare function throttleByteIterable(source: AsyncIterable<Uint8Array>, throttle: BandwidthThrottle | undefined, signal?: AbortSignal): AsyncIterable<Uint8Array>;
 
+/** Options for {@link createDefaultRetryPolicy}. */
+interface DefaultRetryPolicyOptions {
+    /** Maximum total attempts, including the first attempt. Defaults to `4`. */
+    maxAttempts?: number;
+    /** Base backoff delay before jitter in milliseconds. Defaults to `250`. */
+    baseDelayMs?: number;
+    /** Upper bound for a single computed backoff delay in milliseconds. Defaults to `30_000`. */
+    maxDelayMs?: number;
+    /**
+     * Total elapsed-time budget across all attempts and delays in milliseconds.
+     * Once exceeded, no further retries are attempted. Defaults to `300_000` (5 minutes).
+     */
+    maxElapsedMs?: number;
+    /**
+     * Random source in `[0, 1)` used for jitter. Defaults to `Math.random`.
+     * Inject a deterministic source in tests.
+     */
+    random?: () => number;
+}
+/**
+ * Creates the SDK's recommended retry policy for transfer execution.
+ *
+ * The policy retries only failures the SDK has marked as safe to retry
+ * (`error.retryable === true` on a {@link ZeroTransferError}), backing off
+ * exponentially with full jitter: each delay is drawn uniformly from
+ * `[0, min(maxDelayMs, baseDelayMs * 2^(attempt - 1)))`, the schedule that
+ * minimizes contention when many clients retry against the same server.
+ *
+ * Server pacing hints are honored: when the failed attempt carries
+ * `details.retryAfterMs` (parsed from an HTTP `Retry-After` header on 429/503
+ * responses by the web-family providers), the next delay is exactly that
+ * value rather than the jittered backoff. A hint that does not fit in the
+ * remaining `maxElapsedMs` budget stops retrying instead of retrying early.
+ *
+ * Retries also stop once `maxElapsedMs` has elapsed since execution started,
+ * regardless of how many attempts remain.
+ *
+ * @param options - Optional overrides for attempts, delays, and the elapsed budget.
+ * @returns A {@link TransferRetryPolicy} for {@link TransferEngine.execute},
+ *   {@link runRoute}, {@link TransferQueue}, or client-level defaults.
+ *
+ * @example Default policy on a one-shot helper
+ * ```ts
+ * import { createDefaultRetryPolicy, uploadFile } from "@zero-transfer/sdk";
+ *
+ * await uploadFile({
+ *   client,
+ *   destination: { path: "/uploads/report.csv", profile },
+ *   localPath: "./out/report.csv",
+ *   retry: createDefaultRetryPolicy(),
+ * });
+ * ```
+ *
+ * @example Tighter schedule for latency-sensitive work
+ * ```ts
+ * const retry = createDefaultRetryPolicy({
+ *   maxAttempts: 3,
+ *   baseDelayMs: 100,
+ *   maxDelayMs: 2_000,
+ *   maxElapsedMs: 15_000,
+ * });
+ * ```
+ *
+ * @see {@link TransferRetryPolicy} for the underlying hook contract.
+ */
+declare function createDefaultRetryPolicy(options?: DefaultRetryPolicyOptions): TransferRetryPolicy;
+
 /**
  * Transfer executor bridge for provider-backed read/write sessions.
  *
@@ -4484,6 +4693,12 @@ declare function summarizeTransferPlan(plan: TransferPlan): TransferPlanSummary;
 /** Converts executable plan steps into transfer jobs while preserving order. */
 declare function createTransferJobsFromPlan(plan: TransferPlan): TransferJob[];
 
+/**
+ * Transfer queue primitives built on top of {@link TransferEngine}.
+ *
+ * @module transfers/TransferQueue
+ */
+
 /** Queue item lifecycle state. */
 type TransferQueueItemStatus = "queued" | "running" | "completed" | "failed" | "canceled";
 /** Resolver used when jobs do not provide an executor at enqueue time. */
@@ -4492,15 +4707,20 @@ type TransferQueueExecutorResolver = (job: TransferJob) => TransferExecutor;
 interface TransferQueueOptions {
     /** Transfer engine used to execute queued jobs. Defaults to a new engine. */
     engine?: TransferEngine;
+    /**
+     * Transfer client whose {@link TransferClientDefaults | defaults} seed the
+     * queue's retry and timeout policies when not set here or per drain.
+     */
+    client?: TransferClient;
     /** Maximum jobs to execute at the same time. Defaults to `1`. */
     concurrency?: number;
     /** Default executor used for jobs that do not provide one directly. */
     executor?: TransferExecutor;
     /** Dynamic executor resolver used when no per-job executor or default executor exists. */
     resolveExecutor?: TransferQueueExecutorResolver;
-    /** Retry policy passed to engine executions. */
+    /** Retry policy passed to engine executions. Falls back to `client.defaults.retry`. */
     retry?: TransferRetryPolicy;
-    /** Timeout policy passed to engine executions. */
+    /** Timeout policy passed to engine executions. Falls back to `client.defaults.timeout`. */
     timeout?: TransferTimeoutPolicy;
     /** Optional throughput limit shape passed to transfer executors. */
     bandwidthLimit?: TransferBandwidthLimit;
@@ -5547,7 +5767,7 @@ declare function summarizeError(error: unknown): {
 
 /** Webhook destination. */
 interface WebhookTarget {
-    /** Absolute HTTP(S) URL that receives `POST` deliveries. */
+    /** Absolute `https:` URL that receives `POST` deliveries. */
     url: string;
     /** Additional headers merged into every request. */
     headers?: Record<string, string>;
@@ -5555,6 +5775,12 @@ interface WebhookTarget {
     secret?: string;
     /** Audit entry types to deliver. Defaults to all types. */
     types?: readonly MftAuditEntry["type"][];
+    /**
+     * Permits plain `http:` delivery. Defaults to `false`, which rejects
+     * cleartext URLs because audit payloads (and the HMAC timestamp/signature
+     * headers) would cross the network unencrypted.
+     */
+    allowInsecureUrl?: boolean;
 }
 /** Retry policy for webhook deliveries. */
 interface WebhookRetryPolicy {
@@ -5610,6 +5836,8 @@ declare function signWebhookPayload(payload: string, secret: string, timestamp?:
  *
  * @param options - Target, payload, fetch impl, retry policy, abort signal.
  * @returns The delivery outcome.
+ * @throws {@link ConfigurationError} When the target URL is not absolute or
+ * uses cleartext `http:` without `allowInsecureUrl: true`.
  */
 declare function dispatchWebhook(options: DispatchWebhookOptions): Promise<DispatchWebhookResult>;
 /** Options accepted by {@link createWebhookAuditLog}. */
@@ -5927,6 +6155,17 @@ declare class ApprovalRejectedError extends ZeroTransferError {
      */
     constructor(request: ApprovalRequest);
 }
+/** Error raised when an approval request is not resolved within its timeout window. */
+declare class ApprovalTimeoutError extends ZeroTransferError {
+    readonly request: ApprovalRequest;
+    /**
+     * Creates an approval timeout error.
+     *
+     * @param request - The approval request that timed out while pending.
+     * @param timeoutMs - Configured timeout window in milliseconds.
+     */
+    constructor(request: ApprovalRequest, timeoutMs: number);
+}
 /** In-memory approval registry. */
 declare class ApprovalRegistry {
     private readonly requests;
@@ -5993,17 +6232,27 @@ interface CreateApprovalGateOptions {
     now?: () => Date;
     /** Observer fired when a new approval request is created. */
     onRequested?: (request: ApprovalRequest) => void;
+    /**
+     * Maximum time in milliseconds an approval may stay pending. When the window
+     * elapses the request is rejected with reason `"timeout"` and the gated run
+     * fails with a typed {@link ApprovalTimeoutError}. Unset means wait forever.
+     */
+    timeoutMs?: number;
 }
 /**
  * Wraps a route runner with an approval gate.
  *
  * The returned runner creates an approval request, waits for resolution, and
  * dispatches the underlying runner only when the request is approved. Rejection
- * surfaces an {@link ApprovalRejectedError}. Pair with {@link MftScheduler} to
- * implement two-person rules and human-in-the-loop release flows.
+ * surfaces an {@link ApprovalRejectedError}; an unresolved request that exceeds
+ * `timeoutMs` surfaces an {@link ApprovalTimeoutError}. Pair with
+ * {@link MftScheduler} to implement two-person rules and human-in-the-loop
+ * release flows.
  *
  * @param options - Registry, downstream runner, approval-id derivation, hooks.
  * @returns A {@link ScheduleRouteRunner} that gates execution behind approval.
+ * @throws {@link ApprovalTimeoutError} From the returned runner when the
+ * request stays pending longer than `timeoutMs`.
  *
  * @example Two-person rule on a release route
  * ```ts
@@ -6069,10 +6318,14 @@ declare function nextCronFireAt(expression: CronExpression, from: Date, timezone
 /**
  * Validates that an FTP command argument cannot inject additional command lines.
  *
+ * NUL bytes are rejected alongside CR/LF: C-string-based servers and filesystem
+ * APIs truncate at the first NUL, which lets a crafted path smuggle a different
+ * effective target past validation.
+ *
  * @param value - Argument value to validate.
  * @param label - Human-readable argument label used in error messages.
  * @returns The original value when it is safe.
- * @throws {@link ConfigurationError} When the value contains CR or LF characters.
+ * @throws {@link ConfigurationError} When the value contains CR, LF, or NUL characters.
  */
 declare function assertSafeFtpArgument(value: string, label?: string): string;
 /**
@@ -6080,7 +6333,7 @@ declare function assertSafeFtpArgument(value: string, label?: string): string;
  *
  * @param input - Remote path that may contain duplicate separators or dot segments.
  * @returns A normalized remote path, `/` for absolute root, or `.` for an empty relative path.
- * @throws {@link ConfigurationError} When the input contains unsafe CR or LF characters.
+ * @throws {@link ConfigurationError} When the input contains unsafe CR, LF, or NUL characters.
  */
 declare function normalizeRemotePath(input: string): string;
 /**
@@ -6106,4 +6359,4 @@ declare function basenameRemotePath(input: string): string;
  */
 declare function isMainModule(importMetaUrl: string): boolean;
 
-export { AbortError, type AgeRetentionPolicy, ApprovalRegistry, ApprovalRejectedError, type ApprovalRequest, type ApprovalStatus, type AtomicDeployActivateOperation, type AtomicDeployActivateStep, type AtomicDeployPlan, type AtomicDeployPruneStep, type AtomicDeployStrategy, type AuthenticationCapability, AuthenticationError, AuthorizationError, type AzureBlobMultipartOptions, type AzureBlobProviderOptions, type BandwidthSleep, type BandwidthThrottle, type BandwidthThrottleOptions, type Base64EnvSecretSource, type BuiltInProviderId, type BuiltinCapabilityMatrixEntry, type BuiltinProviderMatrixId, CLASSIC_PROVIDER_IDS, type CapabilitySet, type ChecksumCapability, type ClassicProviderId, type ClientDiagnostics, type CompareRemoteManifestsOptions, ConfigurationError, type ConnectionDiagnosticTimings, type ConnectionDiagnosticsResult, ConnectionError, type ConnectionPoolOptions, type ConnectionProfile, type ConventionEndpoint, type CopyBetweenOptions, type CountRetentionPolicy, type CreateApprovalGateOptions, type CreateAtomicDeployPlanOptions, type CreateInboxRouteOptions, type CreateOutboxRouteOptions, type CreateRemoteBrowserOptions, type CreateRemoteManifestOptions, type CreateSyncPlanOptions, type CreateWebhookAuditLogOptions, type CronExpression, type CronField, type CronScheduleTrigger, DEFAULT_FAILED_SUBDIR, DEFAULT_PROCESSED_SUBDIR, DEFAULT_SSH_ALGORITHM_PREFERENCES, type DiffRemoteTreesOptions, type DispatchWebhookOptions, type DispatchWebhookResult, type DownloadFileOptions, type DropboxProviderOptions, type EnvSecretSource, type EvaluateRetentionOptions, type FileSecretSource, type FileSystemS3MultipartResumeStoreOptions, type FileZillaSite, type FriendlyTransferOptions, type FtpFeatures, type FtpPassiveHostStrategy, type FtpProviderOptions, type FtpReplyErrorInput, type FtpResponse, FtpResponseParser, type FtpResponseStatus, type FtpsDataProtection, type FtpsMode, type FtpsProviderOptions, type GcsMultipartOptions, type GcsProviderOptions, type GoogleDriveProviderOptions, type HttpFetch, type HttpProviderOptions, type ImportFileZillaSitesResult, type ImportOpenSshConfigOptions, type ImportOpenSshConfigResult, type ImportWinScpSessionsResult, InMemoryAuditLog, type IntervalScheduleTrigger, type JsonlWriter, type KnownHostsEntry, type KnownHostsMarker, type ListOptions, type LocalProviderOptions, type LogLevel, type LogRecord, type LogRecordInput, type LoggerMethod, type MemoryProviderEntry, type MemoryProviderOptions, type MetadataCapability, type MftAuditEntry, type MftAuditEntryType, type MftAuditLog, type MftInboxConvention, type MftOutboxConvention, type MftRoute, type MftRouteEndpoint, type MftRouteFilter, type MftRouteOperation, type MftSchedule, type MftScheduleTrigger, MftScheduler, type MftSchedulerOptions, type MkdirOptions, type NegotiatedSshAlgorithms, type OAuthAccessToken, type OAuthRefreshCallback, type OAuthTokenSecretSourceOptions, type OneDriveMultipartOptions, type OneDriveProviderOptions, type OpenSshConfigEntry, ParseError, PathAlreadyExistsError, PathNotFoundError, PermissionDeniedError, type PooledTransferClient, type ProgressEventInput, ProtocolError, type ProviderFactory, type ProviderId, ProviderRegistry, type ProviderSelection, type ProviderTransferEndpointRole, type ProviderTransferExecutorOptions, type ProviderTransferOperations, type ProviderTransferReadRequest, type ProviderTransferReadResult, type ProviderTransferRequest, type ProviderTransferSessionResolver, type ProviderTransferSessionResolverInput, type ProviderTransferWriteRequest, type ProviderTransferWriteResult, REDACTED, REMOTE_MANIFEST_FORMAT_VERSION, type RemoteBreadcrumb, type RemoteBrowser, type RemoteBrowserFilter, type RemoteBrowserSnapshot, type RemoteEntry, type RemoteEntrySortKey, type RemoteEntrySortOrder, type RemoteEntryType, type RemoteFileAdapter, type RemoteFileEndpoint, type RemoteFileSystem, type RemoteManifest, type RemoteManifestEntry, type RemotePermissions, type RemoteProtocol, type RemoteStat, type RemoteTreeDiff, type RemoteTreeDiffEntry, type RemoteTreeDiffReason, type RemoteTreeDiffStatus, type RemoteTreeDiffSummary, type RemoteTreeEntry, type RemoteTreeFilter, type RemoveOptions, type RenameOptions, type ResolveSecretOptions, type ResolvedConnectionProfile, type ResolvedOpenSshHost, type ResolvedSshProfile, type ResolvedTlsProfile, type RetentionEvaluation, type RetentionPolicy, type RmdirOptions, RouteRegistry, type RunConnectionDiagnosticsOptions, type RunRouteOptions, type RunSshCommandOptions, type RunSshCommandResult, type S3MultipartCheckpoint, type S3MultipartOptions, type S3MultipartPart, type S3MultipartResumeKey, type S3MultipartResumeStore, type S3ProviderOptions, ScheduleRegistry, type ScheduleRouteRunner, type ScheduleTimerHooks, type SecretProvider, type SecretSource, type SecretValue, type SftpProviderOptions, type SftpRawSession, type SpecializedErrorDetails, type SshAgentSource, type SshAlgorithmPreferences, type SshAlgorithms, SshAuthSession, SshConnectionManager, SshDataReader, SshDataWriter, SshDisconnectReason, type SshKeyboardInteractiveChallenge, type SshKeyboardInteractiveCredential, type SshKeyboardInteractiveHandler, type SshKeyboardInteractivePrompt, type SshKnownHostsSource, type SshPasswordCredential, type SshProfile, type SshPublickeyCredential, SshSessionChannel, type SshSocketFactory, type SshSocketFactoryContext, SshTransportConnection, type SshTransportConnectionOptions, SshTransportHandshake, type SshTransportHandshakeResult, type StatOptions, type SyncConflictPolicy, type SyncDeletePolicy, type SyncDirection, type SyncEndpointInput, TimeoutError, type TlsProfile, type TlsSecretSource, type TransferAttempt, type TransferAttemptError, type TransferBandwidthLimit, type TransferByteRange, TransferClient, type TransferClientOptions, type TransferDataChunk, type TransferDataSource, type TransferEndpoint, TransferEngine, type TransferEngineExecuteOptions, type TransferEngineOptions, TransferError, type TransferExecutionContext, type TransferExecutionResult, type TransferExecutor, type TransferJob, type TransferOperation, type TransferPlan, type TransferPlanAction, type TransferPlanInput, type TransferPlanStep, type TransferPlanSummary, type TransferProgressEvent, type TransferProvider, TransferQueue, type TransferQueueExecutorResolver, type TransferQueueItem, type TransferQueueItemStatus, type TransferQueueOptions, type TransferQueueRunOptions, type TransferQueueSummary, type TransferReceipt, type TransferResult, type TransferResultInput, type TransferRetryDecisionInput, type TransferRetryPolicy, type TransferSession, type TransferTimeoutPolicy, type TransferVerificationResult, UnsupportedFeatureError, type UploadFileOptions, type ValueSecretSource, VerificationError, type WalkRemoteTreeOptions, type WebDavProviderOptions, type WebhookRetryPolicy, type WebhookSignature, type WebhookTarget, type WinScpSession, ZeroTransfer, type ZeroTransferCapabilities, ZeroTransferError, type ZeroTransferErrorDetails, type ZeroTransferLogger, type ZeroTransferOptions, assertSafeFtpArgument, basenameRemotePath, buildPublickeyCredential, buildRemoteBreadcrumbs, compareRemoteManifests, composeAuditLogs, copyBetween, createApprovalGate, createAtomicDeployPlan, createAzureBlobProviderFactory, createBandwidthThrottle, createDropboxProviderFactory, createFileSystemS3MultipartResumeStore, createFtpProviderFactory, createFtpsProviderFactory, createGcsProviderFactory, createGoogleDriveProviderFactory, createHttpProviderFactory, createInboxRoute, createJsonlAuditLog, createLocalProviderFactory, createMemoryProviderFactory, createMemoryS3MultipartResumeStore, createOAuthTokenSecretSource, createOneDriveProviderFactory, createOutboxRoute, createPooledTransferClient, createProgressEvent, createProviderTransferExecutor, createRemoteBrowser, createRemoteManifest, createS3ProviderFactory, createSftpProviderFactory, createSyncPlan, createTransferClient, createTransferJobsFromPlan, createTransferPlan, createTransferResult, createWebDavProviderFactory, createWebhookAuditLog, diffRemoteTrees, dispatchWebhook, downloadFile, emitLog, errorFromFtpReply, evaluateRetention, filterRemoteEntries, formatCapabilityMatrixMarkdown, freezeReceipt, getBuiltinCapabilityMatrix, importFileZillaSites, importOpenSshConfig, importWinScpSessions, inboxFailedPath, inboxProcessedPath, isClassicProviderId, isMainModule, isSensitiveKey, joinRemotePath, matchKnownHosts, matchKnownHostsEntry, negotiateSshAlgorithms, nextCronFireAt, nextScheduleFireAt, noopLogger, normalizeRemotePath, parentRemotePath, parseCronExpression, parseFtpFeatures, parseFtpResponseLines, parseKnownHosts, parseMlsdLine, parseMlsdList, parseMlstTimestamp, parseOpenSshConfig, parseRemoteManifest, parseUnixList, parseUnixListLine, redactCommand, redactConnectionProfile, redactObject, redactSecretSource, redactValue, resolveConnectionProfileSecrets, resolveOpenSshHost, resolveProviderId, resolveSecret, runConnectionDiagnostics, runRoute, runSshCommand, serializeRemoteManifest, signWebhookPayload, sortRemoteEntries, summarizeClientDiagnostics, summarizeError, summarizeTransferPlan, throttleByteIterable, uploadFile, validateConnectionProfile, validateSchedule, walkRemoteTree };
+export { AbortError, type AgeRetentionPolicy, ApprovalRegistry, ApprovalRejectedError, type ApprovalRequest, type ApprovalStatus, ApprovalTimeoutError, type AtomicDeployActivateOperation, type AtomicDeployActivateStep, type AtomicDeployPlan, type AtomicDeployPruneStep, type AtomicDeployStrategy, type AuthenticationCapability, AuthenticationError, AuthorizationError, type AzureBlobMultipartOptions, type AzureBlobProviderOptions, type BandwidthSleep, type BandwidthThrottle, type BandwidthThrottleOptions, type Base64EnvSecretSource, type BuiltInProviderId, type BuiltinCapabilityMatrixEntry, type BuiltinProviderMatrixId, CLASSIC_PROVIDER_IDS, type CapabilitySet, type ChecksumCapability, type ClassicProviderId, type ClientDiagnostics, type CompareRemoteManifestsOptions, ConfigurationError, type ConnectionDiagnosticTimings, type ConnectionDiagnosticsResult, ConnectionError, type ConnectionPoolOptions, type ConnectionProfile, type ConventionEndpoint, type CopyBetweenOptions, type CountRetentionPolicy, type CreateApprovalGateOptions, type CreateAtomicDeployPlanOptions, type CreateInboxRouteOptions, type CreateOutboxRouteOptions, type CreateRemoteBrowserOptions, type CreateRemoteManifestOptions, type CreateSyncPlanOptions, type CreateWebhookAuditLogOptions, type CronExpression, type CronField, type CronScheduleTrigger, DEFAULT_FAILED_SUBDIR, DEFAULT_PROCESSED_SUBDIR, DEFAULT_SSH_ALGORITHM_PREFERENCES, type DefaultRetryPolicyOptions, type DiffRemoteTreesOptions, type DispatchWebhookOptions, type DispatchWebhookResult, type DownloadFileOptions, type DropboxProviderOptions, type EnvSecretSource, type EvaluateRetentionOptions, type FileSecretSource, type FileSystemS3MultipartResumeStoreOptions, type FileZillaSite, type FriendlyTransferOptions, type FtpFeatures, type FtpPassiveHostStrategy, type FtpProviderOptions, type FtpReplyErrorInput, type FtpResponse, FtpResponseParser, type FtpResponseStatus, type FtpsDataProtection, type FtpsMode, type FtpsProviderOptions, type GcsMultipartOptions, type GcsProviderOptions, type GoogleDriveProviderOptions, type HttpFetch, type HttpProviderOptions, type ImportFileZillaSitesResult, type ImportOpenSshConfigOptions, type ImportOpenSshConfigResult, type ImportWinScpSessionsResult, InMemoryAuditLog, type IntervalScheduleTrigger, type JsonlWriter, type KnownHostsEntry, type KnownHostsMarker, type ListOptions, type LocalProviderOptions, type LogLevel, type LogRecord, type LogRecordInput, type LoggerMethod, type MemoryProviderEntry, type MemoryProviderOptions, type MetadataCapability, type MftAuditEntry, type MftAuditEntryType, type MftAuditLog, type MftInboxConvention, type MftOutboxConvention, type MftRoute, type MftRouteEndpoint, type MftRouteFilter, type MftRouteOperation, type MftSchedule, type MftScheduleTrigger, MftScheduler, type MftSchedulerOptions, type MkdirOptions, type NegotiatedSshAlgorithms, type OAuthAccessToken, type OAuthRefreshCallback, type OAuthTokenSecretSourceOptions, type OneDriveMultipartOptions, type OneDriveProviderOptions, type OpenSshConfigEntry, ParseError, PathAlreadyExistsError, PathNotFoundError, PermissionDeniedError, type PooledTransferClient, type ProgressEventInput, ProtocolError, type ProviderFactory, type ProviderId, ProviderRegistry, type ProviderSelection, type ProviderTransferEndpointRole, type ProviderTransferExecutorOptions, type ProviderTransferOperations, type ProviderTransferReadRequest, type ProviderTransferReadResult, type ProviderTransferRequest, type ProviderTransferSessionResolver, type ProviderTransferSessionResolverInput, type ProviderTransferWriteRequest, type ProviderTransferWriteResult, REDACTED, REMOTE_MANIFEST_FORMAT_VERSION, type RemoteBreadcrumb, type RemoteBrowser, type RemoteBrowserFilter, type RemoteBrowserSnapshot, type RemoteEntry, type RemoteEntrySortKey, type RemoteEntrySortOrder, type RemoteEntryType, type RemoteFileAdapter, type RemoteFileEndpoint, type RemoteFileSystem, type RemoteManifest, type RemoteManifestEntry, type RemotePermissions, type RemoteProtocol, type RemoteStat, type RemoteTreeDiff, type RemoteTreeDiffEntry, type RemoteTreeDiffReason, type RemoteTreeDiffStatus, type RemoteTreeDiffSummary, type RemoteTreeEntry, type RemoteTreeFilter, type RemoveOptions, type RenameOptions, type ResolveSecretOptions, type ResolvedConnectionProfile, type ResolvedOpenSshHost, type ResolvedSshProfile, type ResolvedTlsProfile, type RetentionEvaluation, type RetentionPolicy, type RmdirOptions, RouteRegistry, type RunConnectionDiagnosticsOptions, type RunRouteOptions, type RunSshCommandOptions, type RunSshCommandResult, type S3MultipartCheckpoint, type S3MultipartOptions, type S3MultipartPart, type S3MultipartResumeKey, type S3MultipartResumeStore, type S3ProviderOptions, ScheduleRegistry, type ScheduleRouteRunner, type ScheduleTimerHooks, type SecretProvider, type SecretSource, type SecretValue, type SftpProviderOptions, type SftpRawSession, type SpecializedErrorDetails, type SshAgentSource, type SshAlgorithmPreferences, type SshAlgorithms, SshAuthSession, SshConnectionManager, SshDataReader, SshDataWriter, SshDisconnectReason, type SshKeyboardInteractiveChallenge, type SshKeyboardInteractiveCredential, type SshKeyboardInteractiveHandler, type SshKeyboardInteractivePrompt, type SshKnownHostsSource, type SshPasswordCredential, type SshProfile, type SshPublickeyCredential, SshSessionChannel, type SshSocketFactory, type SshSocketFactoryContext, SshTransportConnection, type SshTransportConnectionOptions, SshTransportHandshake, type SshTransportHandshakeResult, type StatOptions, type SyncConflictPolicy, type SyncDeletePolicy, type SyncDirection, type SyncEndpointInput, TimeoutError, type TlsProfile, type TlsSecretSource, type TransferAttempt, type TransferAttemptError, type TransferBandwidthLimit, type TransferByteRange, TransferClient, type TransferClientDefaults, type TransferClientOptions, type TransferDataChunk, type TransferDataSource, type TransferEndpoint, TransferEngine, type TransferEngineExecuteOptions, type TransferEngineOptions, TransferError, type TransferExecutionContext, type TransferExecutionResult, type TransferExecutor, type TransferJob, type TransferOperation, type TransferPlan, type TransferPlanAction, type TransferPlanInput, type TransferPlanStep, type TransferPlanSummary, type TransferProgressEvent, type TransferProvider, TransferQueue, type TransferQueueExecutorResolver, type TransferQueueItem, type TransferQueueItemStatus, type TransferQueueOptions, type TransferQueueRunOptions, type TransferQueueSummary, type TransferReceipt, type TransferResult, type TransferResultInput, type TransferRetryDecisionInput, type TransferRetryPolicy, type TransferSession, type TransferTimeoutPolicy, type TransferVerificationResult, UnsupportedFeatureError, type UploadFileOptions, type ValueSecretSource, VerificationError, type WalkRemoteTreeOptions, type WebDavProviderOptions, type WebhookRetryPolicy, type WebhookSignature, type WebhookTarget, type WinScpSession, ZeroTransfer, type ZeroTransferCapabilities, ZeroTransferError, type ZeroTransferErrorDetails, type ZeroTransferLogger, type ZeroTransferOptions, assertSafeFtpArgument, basenameRemotePath, buildPublickeyCredential, buildRemoteBreadcrumbs, compareRemoteManifests, composeAuditLogs, copyBetween, createApprovalGate, createAtomicDeployPlan, createAzureBlobProviderFactory, createBandwidthThrottle, createDefaultRetryPolicy, createDropboxProviderFactory, createFileSystemS3MultipartResumeStore, createFtpProviderFactory, createFtpsProviderFactory, createGcsProviderFactory, createGoogleDriveProviderFactory, createHttpProviderFactory, createInboxRoute, createJsonlAuditLog, createLocalProviderFactory, createMemoryProviderFactory, createMemoryS3MultipartResumeStore, createOAuthTokenSecretSource, createOneDriveProviderFactory, createOutboxRoute, createPooledTransferClient, createProgressEvent, createProviderTransferExecutor, createRemoteBrowser, createRemoteManifest, createS3ProviderFactory, createSftpProviderFactory, createSyncPlan, createTransferClient, createTransferJobsFromPlan, createTransferPlan, createTransferResult, createWebDavProviderFactory, createWebhookAuditLog, diffRemoteTrees, dispatchWebhook, downloadFile, emitLog, errorFromFtpReply, evaluateRetention, filterRemoteEntries, formatCapabilityMatrixMarkdown, freezeReceipt, getBuiltinCapabilityMatrix, importFileZillaSites, importOpenSshConfig, importWinScpSessions, inboxFailedPath, inboxProcessedPath, isClassicProviderId, isMainModule, isSensitiveKey, joinRemotePath, matchKnownHosts, matchKnownHostsEntry, negotiateSshAlgorithms, nextCronFireAt, nextScheduleFireAt, noopLogger, normalizeRemotePath, parentRemotePath, parseCronExpression, parseFtpFeatures, parseFtpResponseLines, parseKnownHosts, parseMlsdLine, parseMlsdList, parseMlstTimestamp, parseOpenSshConfig, parseRemoteManifest, parseUnixList, parseUnixListLine, redactCommand, redactConnectionProfile, redactErrorForLogging, redactObject, redactSecretSource, redactUrlForLogging, redactValue, resolveConnectionProfileSecrets, resolveOpenSshHost, resolveProviderId, resolveSecret, runConnectionDiagnostics, runRoute, runSshCommand, serializeRemoteManifest, signWebhookPayload, sortRemoteEntries, summarizeClientDiagnostics, summarizeError, summarizeTransferPlan, throttleByteIterable, uploadFile, validateConnectionProfile, validateSchedule, walkRemoteTree };