IF Commons GitHub

Headless credential prompt

0011Draft

0011-credential-prompt · owner if · domain commons

The port and the session

FR-001checkpassing

A credential MUST be asked for with a CredentialRequest (a kind of passphrase, password, pin or confirm, an id made only by parseCredentialId, and the words shown to the person), and answered with a Secret: an object whose text, JSON and inspected forms are [redacted] and whose value only reveal() gives. The port (CredentialPort, a record of functions) MUST be the only way a prompt is drawn, so that a terminal, a helper, a window and a test each give their own.

Enforced (check): .github: cd commons/headless && bun run verify — suite/credential-prompt.test.ts: a secret is never written: its text, JSON and inspected forms are redacted and only reveal() gives it, and an id is parsed

Proved by: headless/suite/credential-prompt.test.ts

Written in: headless/src/logical/credentials.ts

Tests: passed: suite/credential-prompt.test.ts a secret is never written: its text, JSON and inspected forms are redacted and only reveal

FR-002checkpassing

A command MUST ask through one Credentials session (credentialSession) that asks the port at most once for each credential id: a second ask for the same id MUST give the answer (or the refusal) of the first without asking again, asks for one id at the same time MUST share the one prompt, and prompts for different ids MUST go one at a time. The answers MUST be held in memory only until close, which MUST drop every answer and every value and refuse a later ask as closed.

Enforced (check): .github: cd commons/headless && bun run verify — suite/credential-prompt.test.ts: a credential is asked once for each command, shared by asks at the same time, in turn for different ids, and dropped at close

Proved by: headless/suite/credential-prompt.test.ts

Written in: headless/src/logical/credentials.ts

Tests: passed: suite/credential-prompt.test.ts a credential is asked once for each command, shared by asks at the same time, in turn for

FR-003checkpassing

Where no person can be asked (interactive false: no terminal on both ends, or --non-interactive) the session MUST refuse as non-interactive and MUST NOT call the port; where there is no port it MUST refuse as unavailable. Every refusal MUST be a value of a closed union (non-interactive, timeout, cancelled, unavailable, empty, too-short, closed) with one sentence (refusalMessage) and one stable code (refusalCode) that hold no value.

Enforced (check): .github: cd commons/headless && bun run verify — suite/credential-prompt.test.ts: where no person can be asked the refusal is a typed value and the port is not called, and every refusal has a sentence and a code with no value in it

Proved by: headless/suite/credential-prompt.test.ts

Written in: headless/src/logical/credentials.ts

Tests: passed: suite/credential-prompt.test.ts where no person can be asked the refusal is a typed value and the port is not called, and

FR-004checkpassing

A prompt MUST have a hard time limit: the time asked for held to between one second and MAX_TIMEOUT_MS (ten minutes), DEFAULT_TIMEOUT_MS where none is asked, after which the session MUST refuse as timeout and abort the signal the port was given, even where the port does not return; a stopped run (an aborted signal) MUST end the prompt in hand as cancelled. An empty answer MUST be empty, and an answer to a secret shorter than the redactor replaces (MIN_SECRET) MUST be too-short.

Enforced (check): .github: cd commons/headless && bun run verify — suite/credential-prompt.test.ts: a prompt has a hard time limit that aborts the port, a stopped run cancels it, and an empty or short answer is refused

Proved by: headless/suite/credential-prompt.test.ts

Written in: headless/src/logical/credentials.ts

Tests: passed: suite/credential-prompt.test.ts a prompt has a hard time limit that aborts the port, a stopped run cancels it, and an empt

What never happens to a value

FR-005checkpassing

A command MUST be given its session as Context.credentials, the session MUST be closed when the command ends whatever way it ends, and the redaction of the run MUST cover every value the session handed out as well as the program's own secrets, so that no outcome, problem, progress line, JSON document or log line of the run carries one.

Enforced (check): .github: cd commons/headless && bun run verify — suite/credential-prompt.test.ts: a command is given its session, the redaction of the run covers the values it handed out, the log records the prompt and never the value, and the session ends with the command

Proved by: headless/suite/credential-prompt.test.ts

Written in: headless/src/logical/credentials.ts

Tests: passed: suite/credential-prompt.test.ts a command is given its session, the redaction of the run covers the values it handed out,

Cited by: Headless executor check mode

FR-006checkpassing

The run log MUST record that a prompt was made and how it ended (asked, given, refused with the reason) and MUST NOT record a value; nothing in this library MUST write a value to a stream, a file or a message, and the adapter MUST NOT echo it.

Enforced (check): .github: cd commons/headless && bun run verify — suite/credential-prompt.test.ts: a command is given its session, the redaction of the run covers the values it handed out, the log records the prompt and never the value, and the session ends with the command

Proved by: headless/suite/credential-prompt.test.ts

Written in: headless/src/logical/credentials.ts

Tests: passed: suite/credential-prompt.test.ts a command is given its session, the redaction of the run covers the values it handed out,

The terminal and the helper

FR-007checkpassing

The terminal adapter (terminalCredentials over a TtyPort) MUST draw the prompt on the terminal, read the answer with no echo for a secret, and give it as a Secret; an input ended by the person (Ctrl-C, Ctrl-D, the end of the stream) and an aborted signal MUST be cancelled, and a terminal that cannot be had MUST be unavailable with the reason. The reader of the bytes (readerStep) MUST be pure: a character adds, backspace takes one away, enter ends the line, Ctrl-C and Ctrl-D end the input. What differs between systems MUST be a row of data (ttyDevicesOf: /dev/tty and stty on Linux and macOS, CONIN$ and the console's input mode on Windows), not a branch of the adapter.

Enforced (check): .github: cd commons/headless && bun run verify — suite/credential-prompt.test.ts: the terminal adapter draws the prompt, reads with no echo for a secret and with echo for a yes, never writes the value, and cancels on an ended input; the reader is pure and the devices are rows by system

Proved by: headless/suite/credential-prompt.test.ts

Written in: headless/src/surfaces/askpass/mod.ts, headless/src/surfaces/askpass/system-tty.ts, headless/src/surfaces/askpass/terminal.ts

Tests: passed: suite/credential-prompt.test.ts the terminal adapter draws the prompt, reads with no echo for a secret and with echo for a

Cited by: Headless, surfaces/askpass/system-tty, surfaces/askpass/terminal

FR-008checkpassing

The helper contract of an SSH_ASKPASS program MUST be runAskpass: the prompt of ssh is its one argument, SSH_ASKPASS_PROMPT of confirm makes the request a confirm and of none a message that needs no answer; it MUST ask once through a session of the library, write the answer as one line on its standard output and end with status 0, end with status 1 and write only the reason (never a value) on its standard error where there is no answer, and end with status 2 where its arguments are not a request; the kind (passphrase, password, pin) and the id (the key, or the user and host) MUST come from the words of the prompt.

Enforced (check): .github: cd commons/headless && bun run verify — suite/credential-prompt.test.ts: the helper ssh runs reads the request from its argument, asks once, writes the answer as one line and ends 0, ends 1 with only a reason where there is none, and ends 2 for arguments that are no request

Proved by: headless/suite/credential-prompt.test.ts

Written in: headless/src/surfaces/askpass/helper.ts, headless/src/surfaces/askpass/mod.ts, headless/src/surfaces/askpass/system-tty.ts, headless/src/surfaces/askpass/terminal.ts

Tests: passed: suite/credential-prompt.test.ts the helper ssh runs reads the request from its argument, asks once, writes the answer as o

Cited by: Headless, surfaces/askpass/helper

FR-009checkpassing

launcherOf(os, runtime, entry) MUST give the file ssh runs as its askpass program: a script with mode 0700 on Linux and macOS, a .cmd file on Windows (where ssh starts a program and does not run a script), MUST refuse a path that cannot be quoted in it, and askpassEnv MUST give SSH_ASKPASS and SSH_ASKPASS_REQUIRE=force, so that the one prompt of a command is the library's even where ssh has a terminal of its own. Nothing is cached between processes: each run of the helper is one command.

Enforced (check): .github: cd commons/headless && bun run verify — suite/credential-prompt.test.ts: the launcher is a script on Linux and macOS and a .cmd file on Windows, a path that cannot be quoted is refused, and ssh is told to use it even with a terminal

Proved by: headless/suite/credential-prompt.test.ts

Written in: headless/src/surfaces/askpass/helper.ts

Tests: passed: suite/credential-prompt.test.ts the launcher is a script on Linux and macOS and a .cmd file on Windows, a path that cannot

Acceptance scenarios

  1. Given a command that asks twice for one credential, When it runs with a port that counts, Then the port was asked once, per FR-002.
  2. Given a run with no terminal, When a command asks, Then it is non-interactive and the port is not called, per FR-003.
  3. Given a port that never answers, When the limit passes, Then the ask is timeout and the port's signal is aborted, per FR-004.
  4. Given a command that writes the passphrase into its own message, When the run ends, Then neither the output, the JSON nor the log holds it, per FR-005 and FR-006.
  5. Given ssh's prompt Enter passphrase for key '/k':, When the helper runs against a port that answers, Then its standard output is the answer and one line, per FR-008.
  6. Given Windows, When the launcher is made, Then it is a .cmd file that runs the runtime on the entry with the arguments, per FR-009.

Out of scope

  • Reading the controlling terminal when the standard input is not a terminal (/dev/tty, CONIN$): it needs a read of a file with no position, which the system's FsFile does not have; Planned. Until then the system terminal is the standard input where it is a terminal, and the helper is run by ssh with the standard input inherited.
  • Where a key is kept and how a token or an agent is used: the program's (signing, secrets).

Edge cases

  • A confirm is asked once like a secret and is not handed to the redactor, per FR-002 and FR-005.
  • Two commands (two processes) each ask: nothing is shared between them, per FR-009.
  • A port that throws: the ask is unavailable, with the name of the error and never its message, per FR-003.

Assumptions

  • A passphrase of an SSH key is five characters or more, so the redactor's minimum does not refuse a real one.

Open questions

  • None.

Key entities

  • Secret - a value that is never written.
  • Credentials - the session of one command.
  • Askpass helper - the program ssh runs to ask, over the same port.

Success criteria

SC-001success criterion

A command signs or connects with a passphrase a person typed once, and nothing of it is in a file, a log or a message afterwards.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Headless, logical/credentials, surfaces/askpass/helper, surfaces/askpass/system-tty, surfaces/askpass/terminal, Headless executor check mode

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