@zswarm/core 0.1.7 → 0.1.8

package/dist/ops/serve-tunnel.d.ts

@@ -0,0 +1,109 @@
+import { type ChildProcess } from "node:child_process";
+import { type ProbeServeOptions, type ServeHelloData } from "./serve.js";
+import type { OpsResult } from "./types.js";
+export declare const DEFAULT_SSH_SERVE_PORT: number;
+/** Ordinary OpenSSH default when neither the URI nor ssh_config supplies Port. */
+export declare const DEFAULT_SSH_PORT = 22;
+export declare const SSH_SERVE_REMOTE_HOST = "127.0.0.1";
+export declare const SSH_TUNNEL_KEEPALIVE_INTERVAL_S = 15;
+export declare const SSH_TUNNEL_KEEPALIVE_COUNT = 3;
+export declare const SSH_TUNNEL_PORT_RETRIES = 8;
+export type ParsedSshServeTarget = {
+    user: string | undefined;
+    host: string;
+    /** Explicit URI authority port. `undefined` leaves Port to ssh_config / ssh. */
+    sshPort: number | undefined;
+    servePort: number;
+    destination: string;
+};
+export type SshTunnelArgv = {
+    bin: string;
+    args: string[];
+};
+export type SshTunnelSpawn = (bin: string, args: string[], options: {
+    env?: NodeJS.ProcessEnv;
+    stdio: ["ignore", "ignore", "pipe"];
+    windowsHide: true;
+    detached: false;
+}) => ChildProcess;
+export type AcquireServeTunnelOptions = {
+    env?: NodeJS.ProcessEnv;
+    token?: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+};
+export type ServeTunnelHandle = {
+    localTarget: string;
+    identity: string;
+    hello: ServeHelloData;
+    release: () => Promise<void>;
+    invalidate: () => Promise<void>;
+};
+export type ServeTunnelAcquireSuccess = {
+    ok: true;
+    handle: ServeTunnelHandle;
+    localTarget: string;
+    hello: ServeHelloData;
+};
+export type ServeTunnelManager = {
+    acquire: (raw: string, options: AcquireServeTunnelOptions) => Promise<ServeTunnelAcquireSuccess | OpsResult>;
+    /**
+     * Terminal disposal: cancels pending acquires, reaps every owned child
+     * (including in-flight startups), and rejects later acquires.
+     */
+    closeAll: () => Promise<void>;
+    ownedCount: () => number;
+};
+export type ServeTunnelManagerOptions = {
+    /** MCP keeps idle owned tunnels; CLI tears them down when the last op releases. */
+    persistIdle?: boolean;
+    spawnSsh?: SshTunnelSpawn;
+    allocatePort?: () => Promise<number>;
+    probe?: (target: string, options?: ProbeServeOptions) => Promise<OpsResult>;
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+};
+export declare function isSshServeTarget(raw: string): boolean;
+/**
+ * Safe label for logs/errors. Successful parses use the canonical URI.
+ * Failed parses omit userinfo, query, path, and fragment so secrets cannot
+ * echo through diagnostics.
+ */
+export declare function describeServeTarget(raw: string): string;
+/** @deprecated Use describeServeTarget; kept for callers that redacted userinfo only. */
+export declare function redactSshUserinfo(raw: string): string;
+export declare function formatSshServeTarget(target: ParsedSshServeTarget): string;
+/**
+ * ssh:// is not host:port. Authority port is the SSH port when present; omitting
+ * it leaves Port to OpenSSH (alias ssh_config, then ssh's own default).
+ * `servePort` is the already-running loopback serve on the remote (default 9419).
+ */
+export declare function parseSshServeTarget(raw: string): ParsedSshServeTarget;
+/**
+ * Reject ControlMaster/daemonize/fork/extra forwards/remote commands that would
+ * outlive or escape the tracked foreground child. Combined clusters (`-fn`) and
+ * whitespace `-o Keyword Value` forms are parsed, not only `-o Keyword=value`.
+ */
+export declare function assertSafeSshTunnelOpts(opts: string[]): void;
+/**
+ * Required `-o` keywords come first so OpenSSH's first-obtained-value rule
+ * cannot be overridden by later user `-o` or ssh_config. `-S none` is last so
+ * a last-assignment ControlPath flag still loses. Explicit URI `-p` is emitted
+ * only when the URI supplied a port; omitted port leaves alias Port intact.
+ */
+export declare function buildSshTunnelArgv(target: ParsedSshServeTarget, localPort: number, env?: NodeJS.ProcessEnv): SshTunnelArgv;
+/** Isolated identity for an owned tunnel. Never includes the serve token or raw secrets. */
+export declare function serveTunnelCacheKey(target: ParsedSshServeTarget, env?: NodeJS.ProcessEnv): string;
+export declare function allocateLoopbackPort(): Promise<number>;
+export declare function stripControllerRouting(args: Record<string, unknown>): Record<string, unknown>;
+export declare function createServeTunnelManager(options?: ServeTunnelManagerOptions): ServeTunnelManager;
+export declare function forwardServe(input: {
+    target: string;
+    args: Record<string, unknown>;
+    timeoutMs: number;
+    token?: string;
+    signal?: AbortSignal;
+    env?: NodeJS.ProcessEnv;
+    manager?: ServeTunnelManager;
+    now?: () => number;
+}): Promise<OpsResult>;