IF Commons GitHub

targets/ssh/argv

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0005-reach-and-targets FR-005, 0005-reach-and-targets FR-006

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'"

Source: commons/headless/src/targets/ssh/argv.ts

8 of 10 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

shQuotefunction
function shQuote(word: string): string

A 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 '\''.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

remoteCommandfunction
function 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.

Imported by 18 tests of the run (18 passed, 0 failed): the library's results

SshFamilytypeno test imports it
type 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).

SshConfigtype
type 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.

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

configForReachfunction
function 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.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

sshArgvfunction
function 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.

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

safeRemotePathfunction
function safeRemotePath(path: string): boolean

A remote path that a remote shell cannot expand or split: letters, digits and _@%+=:,./-; no space, quote, glob, $, backtick, ;, &, |, <, >, parenthesis, brace, ~ or backslash.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

localForScpfunction
function localForScp(path: string): string

A 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 ./.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

Transfertypeno test imports it
type 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.

scpArgvfunction
function 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).

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.