dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/host/infra/transport/ssh/alias-transport.d.ts

@@ -0,0 +1,206 @@
+/**
+ * The `alias` transport: the system OpenSSH client in ControlMaster mode.
+ *
+ * Why the system client: it inherits everything the user already configured — `~/.ssh/config`
+ * aliases, identity files, `ProxyJump`, `known_hosts`, ssh-agent — which is exactly the
+ * "import type { MultiplexingCache } from '../transport.ts';
+
+import my ssh config and it just works" requirement. Password authentication is not offered
+ * here (a non-interactive `ssh` must not block on a prompt); the `ssh2` transport covers that.
+ *
+ * Remote file bytes travel as base64 over the multiplexed connection, so the plugin needs
+ * nothing installed on the remote host beyond POSIX `sh`, `base64` and (for version tokens)
+ * `stat` or `wc`.
+ *
+ * @module dsh-over-ssh/infra/transport/alias-transport
+ */
+import { type RemoteCapabilities } from '../../../domain/capability.ts';
+import type { HostKeyPolicy } from '../../../domain/roots/connection.ts';
+import { type ExecRequest, type ExecResult, type ReadFileRangeRequest, type ReadFileRequest, type RemoteFileChunk, type RemoteWriteOutcome, type RemoveRequest, type RenameRequest, type Transport, type TransportState, type WriteFileRangeRequest, type WriteFileRequest } from '../transport.ts';
+import type { MultiplexingCache } from '../transport.ts';
+export type { MultiplexingCache } from '../transport.ts';
+/** One spawned process result as reported by the injected spawner. */
+export interface SpawnResult {
+    readonly code: number;
+    readonly signal: string | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** Whether the spawner cut stdout at the requested cap. */
+    readonly truncated?: boolean;
+    /**
+     * Whether the spawner dropped stderr bytes.
+     *
+     * Optional because a spawner is free not to track it; absent means "this spawner cannot say", and the
+     * transport then reports `false` rather than guessing. `createNodeSpawner` keeps only the first 64 stderr
+     * chunks, so it **does** drop bytes and must set this.
+     */
+    readonly stderrTruncated?: boolean;
+    /**
+     * Whether the spawner's **own deadline** ended the process.
+     *
+     * Optional because a spawner that has no deadline cannot report it; absent means "this spawner cannot
+     * say", and the transport then reports `false` rather than blaming a timeout it never observed.
+     * `createNodeSpawner` kills the child on `timeoutMs` and **does** know, so it sets this.
+     */
+    readonly timedOut?: boolean;
+}
+/** Spawn options honoured by the injected spawner. */
+export interface SpawnOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly stdin?: string;
+    readonly maxBytes?: number;
+    /**
+     * Environment entries merged over the parent's environment for this child only.
+     *
+     * Exists for the `SSH_ASKPASS` wiring (`askpass.ts`): a password must reach the `ssh` child without being
+     * written to a file or interpolated into a command line. Absent means "inherit unchanged", which is what
+     * every other caller wants.
+     */
+    readonly env?: Record<string, string>;
+}
+/** Injected process spawner (real: `node:child_process`; tests: a scripted fake). */
+export type SpawnFn = (argv: readonly string[], options: SpawnOptions) => Promise<SpawnResult>;
+/** How connection reuse is behaving for one transport. */
+export type MultiplexingMode = 'unknown' | 'master' | 'unsupported' | 'off';
+/**
+ * Remembers hosts whose `ssh` client cannot multiplex.
+ *
+ * The measurement that motivates this: the OpenSSH client shipped with Windows fails
+ * ControlMaster with `getsockname failed: Not a socket`, so retrying the master on every connect
+ * would cost a failed process per command sequence. See `doc/03-decisions/0006-…`.
+ */
+/** Create an in-memory multiplexing cache (one per process by default). */
+export declare function createMultiplexingCache(): MultiplexingCache;
+/** Process-wide cache shared by every alias transport. */
+export declare const sharedMultiplexingCache: MultiplexingCache;
+/**
+ * Whether a failed `ssh` run failed *because multiplexing is unavailable*, as opposed to a real
+ * connection problem.
+ *
+ * Deliberately narrow: a vanished control socket also mentions "control socket", but that is a
+ * connection loss (retryable), not "this client cannot multiplex" (permanent for this client).
+ *
+ * @param stderr - the failed client's stderr.
+ * @returns whether the failure indicates missing multiplexing support.
+ */
+export declare function isMultiplexingFailure(stderr: string): boolean;
+/** Construction options for the alias transport. */
+export interface AliasTransportOptions {
+    /** Connection id (also the pool key). */
+    readonly connectionId: string;
+    /** OpenSSH alias that carries user/port/identity/jump configuration. */
+    readonly alias: string;
+    /** Directory holding this plugin's ControlMaster sockets. */
+    readonly controlDir: string;
+    /** `ssh` executable; defaults to `ssh` on PATH. */
+    readonly sshBinary?: string;
+    /**
+     * Identity file to pass as `-i`.
+     *
+     * The alias transport inherits `~/.ssh/config`, but when the connection **itself** names a key
+     * (`auth.kind === 'key'`) that key must win: silently ignoring it means the user's explicit choice only
+     * works if their config happens to agree (found by the agent-path e2e).
+     */
+    readonly identityFile?: string;
+    /** Known-hosts file to pass as `-o UserKnownHostsFile`; omitted means ssh's own default. */
+    readonly knownHostsFile?: string;
+    /**
+     * Remote user to pass as `-l`.
+     *
+     * Same reasoning as {@link identityFile}: when the connection names a user, that user must win. Without
+     * this, `ssh <bare-host>` silently used the **local** username (found by the agent-path e2e: the ladder
+     * failed with `yerier@host: Permission denied` even though the profile said `root`).
+     */
+    readonly user?: string;
+    readonly hostKeyPolicy?: HostKeyPolicy;
+    readonly connectTimeoutMs?: number;
+    readonly commandTimeoutMs?: number;
+    readonly keepAliveSeconds?: number;
+    /** When true (default) authentication never prompts. */
+    readonly batchMode?: boolean;
+    /**
+     * Extra environment for every `ssh` child this transport spawns.
+     *
+     * The askpass wiring lives here (`askpass.ts`): with a password connection the transport must both stop
+     * forbidding prompts ({@link batchMode} false) and hand ssh the helper that answers them. Passing it at
+     * construction means master, command and shutdown invocations all authenticate the same way — the drift
+     * that a per-call override would reintroduce.
+     */
+    readonly env?: Record<string, string>;
+    /** `auto` (default) probes multiplexing and degrades; `off` never opens a master. */
+    readonly multiplexing?: 'auto' | 'off';
+    /** Injected cache so tests stay isolated; defaults to the process-wide cache. */
+    readonly multiplexingCache?: MultiplexingCache;
+    /** Injected spawner; the transport never touches `node:child_process` itself. */
+    readonly spawn: SpawnFn;
+    /** Injectable clock for diagnostics. */
+    readonly now?: () => number;
+}
+interface ParsedReadHeaders {
+    readonly size: number;
+    readonly mtime: number;
+    readonly bodyStart: number;
+}
+/** System-ssh transport with ControlMaster session reuse. */
+export declare class AliasTransport implements Transport {
+    #private;
+    readonly id: string;
+    constructor(options: AliasTransportOptions);
+    get state(): TransportState;
+    get capabilities(): RemoteCapabilities;
+    /** Whether commands share one master connection, and why not when they do not. */
+    get multiplexing(): MultiplexingMode;
+    /** Human-readable reason when {@link multiplexing} is `unsupported`. */
+    multiplexingReason(): string | undefined;
+    /** Path of this connection's ControlMaster socket. */
+    controlPath(): string;
+    /** The argv that establishes (and persists) the multiplexed master connection. */
+    buildMasterArgv(): readonly string[];
+    /**
+     * The argv for one command.
+     *
+     * `-S` is only attached when a master connection actually exists: on a client without
+     * multiplexing it would make every command fail with a socket error.
+     */
+    buildCommandArgv(command: string): readonly string[];
+    /** Establish the connection; concurrent calls share one attempt. */
+    connect(signal?: AbortSignal): Promise<void>;
+    /** Close the master connection when one exists. Idempotent. */
+    dispose(): Promise<void>;
+    /** Run one remote command. */
+    exec(request: ExecRequest, signal?: AbortSignal): Promise<ExecResult>;
+    /** Read a remote file with a version token from the same round trip. */
+    readFile(request: ReadFileRequest, signal?: AbortSignal): Promise<RemoteFileChunk>;
+    /** Write a remote file, optionally guarded by the digest of the current content. */
+    writeFile(request: WriteFileRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
+    /**
+     * Read `[offset, offset+maxBytes)` in one round trip.
+     *
+     * The command comes from `fs-commands.ts`, the same module the agent transport uses, so a shell offset read
+     * cannot drift between the two.
+     */
+    readFileRange(request: ReadFileRangeRequest, signal?: AbortSignal): Promise<RemoteFileChunk>;
+    /** Write at `offset`, leaving the earlier bytes untouched (`dd conv=notrunc`). */
+    writeFileRange(request: WriteFileRangeRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
+    /** Move a path; a cross-device move fails instead of silently copying. */
+    rename(request: RenameRequest, signal?: AbortSignal): Promise<void>;
+    /** Remove a file or (with `recursive`) a directory tree. */
+    remove(request: RemoveRequest, signal?: AbortSignal): Promise<void>;
+    /**
+     * Probe the remote host once and remember the result.
+     *
+     * @param signal - cancellation.
+     * @param maxAgeMs - reuse a previous probe inside this window (default 5 minutes).
+     * @returns the discovered capabilities.
+     */
+    probeCapabilities(signal?: AbortSignal, maxAgeMs?: number): Promise<RemoteCapabilities>;
+}
+/**
+ * Parse the header lines emitted by {@link AliasTransport.readFile}.
+ *
+ * @param stdout - raw stdout of the read script.
+ * @returns size, mtime and the base64 body, or `undefined` when the headers are missing.
+ */
+export declare function parseReadHeaders(stdout: string): ParsedReadHeaders | undefined;
+//# sourceMappingURL=alias-transport.d.ts.map

package/lib/types/src/host/infra/transport/ssh/askpass-fs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The real filesystem behind {@link AskpassIo}.
+ *
+ * Deliberately tiny and separate, for the same reason `node-spawn.ts` is: the askpass logic is pure and
+ * testable, and this is the only module that touches a disk. Nothing here ever writes a secret — the
+ * helper it materialises reads the secret from the environment at run time.
+ *
+ * @module dsh-over-ssh/infra/transport/askpass-fs
+ */
+import type { AskpassIo } from './askpass.ts';
+/**
+ * Build the production {@link AskpassIo}.
+ *
+ * The helper lives in a fresh private directory under the OS temp root, named with the plugin's prefix so a
+ * leftover is recognisable. Files are created `0o600`/`0o700` where the platform supports modes.
+ *
+ * @returns a filesystem adapter for {@link createAskpass}.
+ */
+export declare function createAskpassFs(): AskpassIo;
+//# sourceMappingURL=askpass-fs.d.ts.map

package/lib/types/src/host/infra/transport/ssh/askpass.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Non-interactive **password** authentication for the system `ssh` client, via `SSH_ASKPASS`.
+ *
+ * Why this module exists: the Tier 2 agent is launched by spawning `ssh` (`ssh <alias> <agent> --stdio`),
+ * and the alias transport runs every command the same way. System `ssh` cannot read a password from a pipe,
+ * so a password-only connection used to be impossible on any transport that goes through `ssh` — which made
+ * "default to Tier 2" silently false for password connections (they were downgraded to `ssh2`). That was
+ * never a property of SSH: OpenSSH ≥ 8.4 supports `SSH_ASKPASS_REQUIRE=force`, which runs a helper program
+ * to obtain the secret **even with no tty**, exactly the situation a background plugin is in.
+ *
+ * Two rules make this safe:
+ *
+ *  1. **The secret never touches the disk.** The helper program carries no secret; it forwards the value of
+ *     an environment variable (`DSH_OVER_SSH_ASKPASS_SECRET`) that the ssh child process inherits. A leftover
+ *     helper file therefore leaks nothing: with the variable absent it prints an empty line and ssh fails
+ *     the authentication instead of succeeding with a stale credential.
+ *  2. **The secret is never interpolated into a shell or command line.** It travels only as an environment
+ *     value, so characters like `&`, `|`, `%`, `^` and quotes need no escaping (a `cmd`-based helper that
+ *     echoed the secret would break on those, and its argv would be visible in the process list).
+ *
+ * Verified on the real host (Windows, OpenSSH_for_Windows_9.5p1): password auth succeeds through a spawned
+ * `ssh` whose stdio are pipes, and a **wrong** secret fails — so the helper is genuinely what authenticates.
+ *
+ * @module dsh-over-ssh/infra/transport/askpass
+ */
+/** The interpreter that runs the helper script. */
+export interface AskpassInterpreter {
+    /** Absolute path of the executable (`node`/Electron). */
+    readonly execPath: string;
+    /** `'win32'` or a POSIX platform id; decides which shim shape is written. */
+    readonly platform: string;
+}
+/** The two files a helper is made of, and the exact text written to each. */
+export interface AskpassFiles {
+    /** The program `SSH_ASKPASS` points at. */
+    readonly helperPath: string;
+    /** The script the helper delegates to. */
+    readonly scriptPath: string;
+    /** Contents of {@link scriptPath}; carries no secret. */
+    readonly script: string;
+    /** Contents of {@link helperPath}; carries no secret. */
+    readonly helper: string;
+    /** Mode to create the files with (POSIX needs the helper executable). */
+    readonly mode: number;
+}
+/**
+ * The helper script: print the secret from the environment, then a newline.
+ *
+ * A trailing newline is required — an ssh askpass program whose output lacks one is rejected
+ * (measured: `<nul set /p =` without a newline failed while `echo` succeeded).
+ */
+export declare function askpassScript(): string;
+/**
+ * The program `SSH_ASKPASS` names.
+ *
+ * Windows: a `cmd` shim, because ssh executes the path directly and a `.mjs` is not executable there.
+ * POSIX: a `sh` script. Both only *launch* the interpreter with the script path, so the secret is never
+ * quoted into a command line.
+ *
+ * @param interpreter - interpreter and platform.
+ * @param scriptPath - absolute path of {@link askpassScript}'s file.
+ * @returns the shim text.
+ */
+export declare function askpassHelper(interpreter: AskpassInterpreter, scriptPath: string): string;
+/**
+ * Build the files for one helper directory.
+ *
+ * @param dir - directory to place the helper in.
+ * @param interpreter - interpreter and platform.
+ * @returns the file plan (paths plus contents).
+ */
+export declare function planAskpassFiles(dir: string, interpreter: AskpassInterpreter): AskpassFiles;
+/**
+ * The environment that makes the system `ssh` ask {@link AskpassFiles.helperPath} for the password.
+ *
+ * `ELECTRON_RUN_AS_NODE=1` is set unconditionally: this plugin normally runs inside the Electron desktop
+ * app, where `process.execPath` is the Electron binary and would otherwise open a GUI instead of running
+ * the script. Real `node` ignores the variable, so one code path covers both hosts.
+ *
+ * `DISPLAY` is set because pre-8.4 OpenSSH only consults `SSH_ASKPASS` when it is non-empty, and
+ * `SSH_ASKPASS_REQUIRE=force` because ≥ 8.4 additionally requires it when a tty might exist. Setting both
+ * makes the helper work on either generation.
+ *
+ * @param files - the helper plan.
+ * @param secret - the password; only ever passed here, never written to a file.
+ * @returns environment entries to merge into the `ssh` child's environment.
+ */
+export declare function askpassEnvironment(files: AskpassFiles, secret: string): Record<string, string>;
+/** Filesystem surface this module needs; injected so tests never touch a real disk. */
+export interface AskpassIo {
+    /** Create `dir` (and parents). */
+    mkdir(dir: string): Promise<void>;
+    /** Write `content` to `path`, optionally with a POSIX mode. */
+    writeFile(path: string, content: string, mode: number): Promise<void>;
+    /** Remove `dir` recursively; never throws when it is already gone. */
+    remove(dir: string): Promise<void>;
+    /** Create a private directory to hold one helper. */
+    makeTempDir(): Promise<string>;
+}
+/** A live helper: the environment to hand `ssh`, plus a way to take it away again. */
+export interface AskpassHandle {
+    /** Environment entries for the `ssh` child process. */
+    readonly env: Record<string, string>;
+    /** Delete the helper directory. Safe to call more than once. */
+    dispose(): Promise<void>;
+}
+/** Options for {@link createAskpass}. */
+export interface AskpassOptions {
+    /** The password. Held in memory only. */
+    readonly secret: string;
+    /** Interpreter facts; defaults to this process. */
+    readonly interpreter?: AskpassInterpreter;
+    /** Injected filesystem. */
+    readonly io: AskpassIo;
+}
+/**
+ * Create a password helper and the environment that uses it.
+ *
+ * @param options - secret, interpreter and injected filesystem.
+ * @returns the handle; call {@link AskpassHandle.dispose} when the connection goes away.
+ */
+export declare function createAskpass(options: AskpassOptions): Promise<AskpassHandle>;
+/**
+ * Whether a connection's password can be handed to the system `ssh` at all.
+ *
+ * Only `authKind: 'password'` needs the helper: key and agent connections never prompt, and forcing
+ * `BatchMode=no` for them would let a misconfigured host block on an interactive prompt forever.
+ *
+ * @param authKind - the connection's authentication mode.
+ * @returns true when the askpass helper must be wired in.
+ */
+export declare function needsAskpass(authKind: 'agent' | 'key' | 'password'): boolean;
+//# sourceMappingURL=askpass.d.ts.map

package/lib/types/src/host/infra/transport/ssh/shell-quote.d.ts

@@ -0,0 +1,62 @@
+/**
+ * POSIX shell quoting for remote command construction.
+ *
+ * Remote commands are the plugin's one injection surface: `ssh <alias> <command>` runs the
+ * command through the remote login shell, so every interpolated value must be quoted. The
+ * `argv`-first design keeps quoting to the places that genuinely need a shell.
+ *
+ * @module dsh-over-ssh/infra/transport/shell-quote
+ */
+/**
+ * Quote one value for a POSIX shell so it cannot be interpreted.
+ *
+ * Thin alias over {@link quote} in the domain: the implementation lives there because `domain` must not
+ * depend on `infra` (red line #2), and the terminal wrapper + tool-request builders need the same function.
+ * Keeping this name means the 41 ssh-transport call sites do not have to change.
+ *
+ * @param value - raw value.
+ * @returns a shell-safe literal.
+ * @throws SshDevError when the value contains a NUL byte.
+ */
+export declare function shellQuote(value: string): string;
+/** Quote several values and join them with spaces. */
+export declare function shellQuoteAll(values: readonly string[]): string;
+/** How a remote command is assembled. */
+export interface RemoteCommandOptions {
+    /** Directory to `cd` into before running; omitted leaves the remote default. */
+    readonly cwd?: string;
+    /** Environment assignments applied to the command only. */
+    readonly env?: Readonly<Record<string, string>>;
+}
+/**
+ * Build a remote command string from an argv vector.
+ *
+ * @param argv - executable followed by arguments; never shell-interpreted as a whole.
+ * @param options - optional `cwd` and environment.
+ * @returns a command string safe to pass as the single `ssh` command argument.
+ * @throws SshDevError when `argv` is empty or a value carries a NUL.
+ */
+export declare function buildRemoteCommand(argv: readonly string[], options?: RemoteCommandOptions): string;
+/**
+ * Prefix lines that make a **script** honour `cwd` and `env`.
+ *
+ * The argv path builds these into one command; the script path must apply them too, because dropping them
+ * silently is the worst outcome — a real-host run showed `remote_exec { cwd: 'src' }` running in `$HOME` and
+ * reporting success. Shared by every shell transport so the two paths cannot drift apart again.
+ *
+ * @param request - requested `cwd` and environment.
+ * @returns prefix lines, `cd` first; empty when neither was requested.
+ * @throws SshDevError when an environment name is not a shell identifier.
+ */
+export declare function scriptPrefixes(request: RemoteCommandOptions): readonly string[];
+/**
+ * Build a remote command from a raw script body.
+ *
+ * The caller owns the script text; values interpolated into it must already be quoted with
+ * {@link shellQuote}.
+ *
+ * @param script - POSIX shell script body.
+ * @returns the command string.
+ */
+export declare function buildRemoteScript(script: string): string;
+//# sourceMappingURL=shell-quote.d.ts.map

package/lib/types/src/host/infra/transport/ssh/ssh-argv.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The one place that decides which `ssh` arguments a connection's credentials turn into.
+ *
+ * Two call sites need exactly the same answer — the alias transport (which builds master and per-command
+ * argv) and the Tier 2 agent launcher (which spawns `ssh <alias> <agent> --stdio`) — and the agent-path e2e
+ * caught both of them drifting: the transport ignored `keyPath`, then the launcher ignored `user`, so the
+ * ladder authenticated and the agent session did not. Duplicating this list is what allowed that.
+ *
+ * Honesty rule: a value is only emitted when the connection actually set it. Emitting `-l`/`-i`
+ * unconditionally would override the user's own `~/.ssh/config`, which is the alias transport's whole point.
+ *
+ * @module dsh-over-ssh/infra/transport/ssh-argv
+ */
+import type { HostKeyPolicy } from '../../../domain/roots/connection.ts';
+/** Credential-ish options shared by every `ssh` invocation this plugin makes. */
+export interface SshArgvOptions {
+    /** Destination: an `~/.ssh/config` alias or a bare `user@host`-less host. */
+    readonly alias: string;
+    /** Remote user; omitted or empty means "let ssh decide". */
+    readonly user?: string;
+    /** `-i` identity file. */
+    readonly identityFile?: string;
+    /** `-o UserKnownHostsFile=…`. */
+    readonly knownHostsFile?: string;
+    readonly hostKeyPolicy?: HostKeyPolicy;
+    readonly connectTimeoutMs?: number;
+    /** `-o BatchMode=yes` (never prompt). Defaults to true: this plugin never has a human at the tty. */
+    readonly batchMode?: boolean;
+    /** Extra `-o` options appended verbatim, in order. */
+    readonly extraOptions?: readonly string[];
+}
+/** `-i`, `-o UserKnownHostsFile`, `-l` — only what the connection configured. */
+export declare function credentialArgv(options: SshArgvOptions): readonly string[];
+/** Common `-o` options (policy, timeout, batch mode) plus {@link credentialArgv}. */
+export declare function commonSshOptions(options: SshArgvOptions): readonly string[];
+/**
+ * A complete `ssh` prefix ending at the destination: `ssh -T <options…> <alias>`.
+ *
+ * The Tier 2 launcher appends the remote command to this; the alias transport appends its own control
+ * sockets and the command.
+ */
+export declare function sshPrefix(sshBinary: string, options: SshArgvOptions): readonly string[];
+//# sourceMappingURL=ssh-argv.d.ts.map