IF Commons GitHub

surfaces/askpass/helper

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0011-credential-prompt FR-008, 0011-credential-prompt FR-009

The helper contract of an SSH_ASKPASS program (commons headless 0011-credential-prompt FR-008): the program that ssh runs to ask for a passphrase or a password, given as data and pure functions. ssh runs the helper with the prompt as its one argument and the environment SSH_ASKPASS_PROMPT (confirm for a yes or no, none for a message that needs no answer, absent for a secret), reads the answer from its standard output, and takes a non-zero status as a refusal. runAskpass is the whole helper over a credential port: it reads the request from the arguments, asks once through a session of the library (so the time limit and the typed refusals are the library's), and gives what to write and the status; launcherOf gives the file a system needs so that ssh can run the helper, which on Windows is a .cmd shim and not a script.

The helper writes the answer to its standard output and nothing else there, writes nothing of the answer to its standard error, and keeps nothing: each run of the helper is one command, so a second attempt of ssh is a second prompt (nothing is cached between processes). The prompt text of ssh is not secret and is the credential's id.

import { requestOf } from "./helper.ts";
const r = requestOf(["Enter passphrase for key '/home/u/.ssh/id_ed25519': "], () => undefined);
r.kind === "ask" && r.request.kind; // "passphrase"

Source: commons/headless/src/surfaces/askpass/helper.ts

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

AskpassRequesttypeno test imports it
type AskpassRequest =
  | { readonly kind: "ask"; readonly request: CredentialRequest }
  /** A message that needs no answer (`SSH_ASKPASS_PROMPT=none`): shown, and answered with nothing. */
  | { readonly kind: "inform"; readonly text: string };

What the helper is asked to do.

AskpassUsagetypeno test imports it
type AskpassUsage = { readonly kind: "usage"; readonly why: string };

Why the arguments are not a request.

kindOfPromptfunction
function kindOfPrompt(text: string, promptKind: string | undefined): CredentialKind

The kind of credential a prompt of ssh asks for, from its words.

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

idTextOffunction
function idTextOf(text: string): string

The id of a prompt: the key a passphrase is for, the user and host a password is for, or the words themselves.

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

requestOffunction
function requestOf(args: readonly string[], env: (name: string) => string | undefined): Result<AskpassRequest, AskpassUsage>

The request from the helper's arguments (the program's own name first, then ssh's prompt) and its environment.

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

AskpassEndtypeno test imports it
type AskpassEnd = { readonly stdout: string; readonly stderr: string; readonly code: 0 | 1 | 2 };

What the helper does: the text for its standard output, the text for its standard error, and its status.

AskpassOptionstypeno test imports it
type AskpassOptions = {
  readonly port: CredentialPort;
  readonly clock: Clock;
  readonly timeoutMs?: number;
  readonly signal?: AbortSignal;
};

What the helper runs with.

runAskpassfunction
function runAskpass(args: readonly string[], env: (name: string) => string | undefined, o: AskpassOptions): Promise<AskpassEnd>

The helper: reads its request, asks once, and gives the answer for ssh to read (a line on the standard output) with status 0, or nothing and status 1 where there was no answer (the reason, with no value in it, on the standard error), or status 2 where its arguments are not a request. A message that needs no answer is shown on the standard error and answered with nothing.

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

LauncherOstypeno test imports it
type LauncherOs = "linux" | "darwin" | "windows";

The system a launcher is for.

Launchertypeno test imports it
type Launcher = { readonly fileName: string; readonly text: string; readonly mode: number };

The file ssh runs as its askpass program: its name, its text and the mode it is written with.

launcherOffunction
function launcherOf(os: LauncherOs, runtime: string, entry: string): Result<Launcher, string>

The file that lets ssh run the helper: on Linux and macOS a script that runs the runtime on the helper's entry and passes the arguments on, on Windows a .cmd file that does (ssh there starts the program it is given and does not run a .ts file). The paths are written between quotes, so one that holds a quote, a line break or (on Windows) a percent sign is refused.

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

askpassEnvfunction
function askpassEnv(launcherPath: string): Readonly<Record<string, string>>

The variables ssh needs to run the helper where it has no display and no terminal of its own: force makes it use the helper even with a terminal, so the one prompt is the library's.

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

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