shQuotefunctionfunction shQuote(word: string): stringA word as one word of a POSIX shell: as it is where it needs no quoting, else in single quotes with each single quote written '\''.
The one place the arguments of the system's OpenSSH client are made (commons headless 0005-reach-and-targets FR-005, FR-006; 0007-ssh-coverage FR-001, FR-003, FR-006). ssh joins what it is given after the host into one string for the remote shell; proc.run does not, so the remote command is quoted here word by word and sent as ONE argument. The options every call needs are here and nowhere else, in three families: batch (never a question: BatchMode, a connect time out, keep-alive, no terminal, a host key that does not match is refused, the repository's known hosts then the user's), pinned (the same with only the one file of the keys pinned for this host) and interactive (the client may ask, for a password or a passphrase, and only where the action's reach policy says it needs a terminal). The files are copied by scp with the same care: argv only, no shell expansion.
import { shQuote } from "./argv.ts";
shQuote("it's here"); // "'it'\\''s here'"shQuotefunctionfunction shQuote(word: string): stringA word as one word of a POSIX shell: as it is where it needs no quoting, else in single quotes with each single quote written '\''.
remoteCommandfunctionfunction remoteCommand(argv: readonly string[]): Result<string, string>An argument vector as the one string the remote shell reads back as that vector; a word with a NUL (which no shell can hold) is refused.
SshFamilytypeno test imports ittype SshFamily = "batch" | "pinned" | "interactive";The families of options: batch never asks, pinned trusts only the keys pinned for the host, interactive may ask (for a password or a passphrase).
SshConfigtypetype SshConfig = {
/** The program, `ssh` by default. */
readonly program?: string;
/** The program that copies fi… (1073 characters)type SshConfig = {
/** The program, `ssh` by default. */
readonly program?: string;
/** The program that copies files, `scp` by default. */
readonly scpProgram?: string;
/** The repository's known hosts (from Git), consulted first; for the family `pinned`, the one file of the keys pinned for the host (often a temporary file). */
readonly knownHostsRepository: string;
/** The user's known hosts, consulted after; not consulted in the family `pinned`. */
readonly knownHostsUser: string;
/** The folder the control sockets are in; with none, the connection is not shared. */
readonly controlDir?: string;
readonly connectTimeoutSec?: number;
readonly serverAliveSec?: number;
/** `batch` by default. */
readonly family?: SshFamily;
/** Whether a terminal is asked of the remote (`-t`); only in the family `interactive`. */
readonly pty?: boolean;
/** The path of the key file a credential reference names (never a key's value); a reference it does not know is an error. */
readonly identityFor?: (name: string) => string | undefined;
};What the client's calls are configured with: the files of known hosts, where the shared connections live, the times, the family, and how a credential reference becomes a key file.
configForReachfunctionfunction configForReach(config: SshConfig, reach: ReachPolicy, family: SshFamily, pty?: boolean): Result<SshConfig, string>The configuration for an action: the family interactive and a terminal are allowed only where the action's reach policy says it needs a terminal (needsTty), which no channel but a person's own terminal has; anything else keeps the family it was given, batch by default.
sshArgvfunctionfunction sshArgv(t: Target, all: readonly Target[], config: SshConfig, remote: string): Result<readonly string[], string>The argument vector that runs remote (already one string, see remoteCommand) on a target: -T (no terminal; -t only where the interactive family is given a terminal), the options of the family, the port, then -- and the destination so that nothing after it can be read as an option. Nothing here accepts a host key: there is no accept-new and no no.
safeRemotePathfunctionfunction safeRemotePath(path: string): booleanA remote path that a remote shell cannot expand or split: letters, digits and _@%+=:,./-; no space, quote, glob, $, backtick, ;, &, |, <, >, parenthesis, brace, ~ or backslash.
localForScpfunctionfunction localForScp(path: string): stringA local path as an argument of scp: one that begins with a dash, or that holds a colon (which scp reads as host:path), is made relative with ./.
Transfertypeno test imports ittype Transfer = { readonly kind: "put"; readonly files: readonly string[]; readonly remoteDir: string } | { readonly kind: "get"; readonly remote: string; readonly local: string };What to copy: the files to put in a remote folder, or a remote file to get to a local path.
scpArgvfunctionfunction scpArgv(t: Target, all: readonly Target[], config: SshConfig, transfer: Transfer): Result<readonly string[], string>The argument vector of scp for a transfer: -q, the options of the family, the port as -P, --, then the files and the remote place as user@host:path. Every word is its own argument, nothing goes through a shell here, and a remote path that a remote shell could expand or split is refused (the legacy protocol reads it with a shell).