IF Commons GitHub

logical/credentials

Written to: 6 requirements: 6 proved, 0 partly, 0 failing, 0 with no test recorded. 0011-credential-prompt FR-001, 0011-credential-prompt FR-002, 0011-credential-prompt FR-003, 0011-credential-prompt FR-004, 0011-credential-prompt FR-005, 0011-credential-prompt FR-006

The credential prompt, as a port (commons headless 0011-credential-prompt): how a command asks a person for a passphrase, a password, a PIN or a yes without the program ever keeping it. A command asks its Credentials (get), which is one session for one command: it asks the port at most once for each credential, holds the answer in memory only until the command ends (close), refuses where there is no person to ask (a typed reason, never a guess), stops asking after a hard time limit, and tells the redactor every value it handed out so that no output of the run can carry one. What draws the prompt is a surface's (@intellectual-frontiers/headless/askpass).

A value is a Secret: an object whose text, JSON and inspected forms are [redacted], and whose value is read only by reveal(). The port is a record of functions, so that a terminal, a helper that SSH_ASKPASS runs, a window or a test each give their own. The session logs the fact of a prompt and how it ended through onEvent, never a value. The redactor of a run does not replace a value shorter than MIN_SECRET (commons headless 0008-exit-style-consent FR-003), so a credential of fewer characters is refused as too-short.

import { secretOf } from "./credentials.ts";
String(secretOf("hunter2!")); // "[redacted]"
JSON.stringify({ k: secretOf("hunter2!") }); // '{"k":"[redacted]"}'

Source: commons/headless/src/logical/credentials.ts

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

logical.CredentialKindtypeno test imports it
type CredentialKind = "passphrase" | "password" | "pin" | "confirm";

What is asked for: a passphrase of a key, a password, a PIN of a token, or a yes (which is not secret, and is still asked once).

logical.CREDENTIAL_KINDSconstno test imports it
const CREDENTIAL_KINDS: readonly CredentialKind[]

Every kind, for a program that walks them.

logical.CredentialIdtypeno test imports it
type CredentialId = Brand<string, "credential id">;

The identity of a credential within one command, the key of its one prompt (ssh-key:~/.ssh/id_ed25519): made only by parseCredentialId.

logical.parseCredentialIdfunctionno test imports it
function parseCredentialId(text: string): Result<CredentialId, string>

A credential id from text, or why the text is not one: the one way a CredentialId is made.

logical.CredentialRequesttypeno test imports it
type CredentialRequest = { readonly kind: CredentialKind; readonly id: CredentialId; readonly prompt: string };

What a command asks: the kind, the id and the words shown to the person (which never hold the value).

logical.Secrettypeno test imports it
type Secret = {
  readonly reveal: () => string;
  readonly toString: () => string;
  readonly toJSON: () => string;
  readonly [inspect: symbol]: () => string;
};

A value that is never written: its text, its JSON and its inspected form are [redacted]; only reveal() gives it.

logical.secretOffunctionno test imports it
function secretOf(value: string): Secret

A secret over a value: the value is held in a closure and is on no property.

logical.CredentialRefusaltypeno test imports it
type CredentialRefusal =
  | { readonly kind: "non-interactive" }
  | { readonly kind: "timeout"; readonly afterMs: number }
  | { readonly kind: "cancelled" }
  | { readonly kind: "unavailable"; readonly why: string }
  | { readonly kind: "empty" }
  | { readonly kind: "too-short"; readonly minimum: number }
  | { readonly kind: "closed" };

Why a credential was not given.

logical.CREDENTIAL_REFUSALSconstno test imports it
const CREDENTIAL_REFUSALS: readonly ("cancelled" | "closed" | "empty" | "non-interactive" | "timeout" | "too-short" | "unavailable")[]

Every reason by name.

logical.refusalMessagefunctionno test imports it
function refusalMessage(r: CredentialRefusal, id: string): string

One sentence for a refusal, with no value in it.

logical.refusalCodefunctionno test imports it
function refusalCode(r: CredentialRefusal): string

The stable code of a refusal, for the problem a command reports.

logical.refusalProblemfunctionno test imports it
function refusalProblem(r: CredentialRefusal, id: string): Problem

The failure a command reports for a refusal.

logical.AskLimitstypeno test imports it
type AskLimits = { readonly timeoutMs: number; readonly signal: AbortSignal };

What a port is given to ask with: the time it has and a signal that is aborted when it has none left or the run is stopped.

logical.CredentialPorttypeno test imports it
type CredentialPort = {
  readonly ask: (request: CredentialRequest, limits: AskLimits) => Promise<Result<Secret, CredentialRefusal>>;
};

The port: asks a person, and gives the secret or why not. A record of functions.

logical.Clocktypeno test imports it
type Clock = { readonly after: (ms: number, fn: () => void) => () => void };

A timer as a port: calls fn once after ms and gives the function that cancels it.

logical.CredentialEventtypeno test imports it
type CredentialEvent =
  | { readonly kind: "asked"; readonly id: string; readonly credential: CredentialKind }
  | { readonly kind: "given"; readonly id: string }
  | { readonly kind: "refused"; readonly id: string; readonly refusal: CredentialRefusal["kind"] };

What a session tells its watcher (the run log): that a prompt happened and how it ended, never a value.

logical.Credentialstypeno test imports it
type Credentials = { /** The credential, asked once per command for each id (concurrent asks for one id share the one … (510 characters)
type Credentials = {
  /** The credential, asked once per command for each id (concurrent asks for one id share the one prompt, a refusal is held as well); prompts of different ids go one at a time. */
  readonly get: (request: CredentialRequest) => Promise<Result<Secret, CredentialRefusal>>;
  /** The values handed out so far, for the redactor. */
  readonly values: () => readonly string[];
  /** Drops every answer and every value; a later `get` is refused as `closed`. */
  readonly close: () => void;
};

The one session a command asks through.

logical.MAX_TIMEOUT_MSconstno test imports it
const MAX_TIMEOUT_MS: 600000

The longest a prompt may wait, whatever is asked for: ten minutes.

logical.DEFAULT_TIMEOUT_MSconstno test imports it
const DEFAULT_TIMEOUT_MS: 120000

How long a prompt waits where nothing is said: two minutes.

logical.limitOffunctionno test imports it
function limitOf(ms: number | undefined): number

The time a prompt may take: what was asked for, held to between a second and MAX_TIMEOUT_MS; DEFAULT_TIMEOUT_MS where nothing was asked or the number is not one.

logical.SessionOptionstypeno test imports it
type SessionOptions = { /** What asks the person; none where there is none (every ask is then `unavailable`). */ rea… (508 characters)
type SessionOptions = {
  /** What asks the person; none where there is none (every ask is then `unavailable`). */
  readonly port?: CredentialPort;
  /** Whether a person can be asked at all (a terminal on both ends, not `--non-interactive`). */
  readonly interactive: boolean;
  readonly clock: Clock;
  readonly timeoutMs?: number;
  /** Aborted when the run is stopped: the prompt in hand ends as `cancelled`. */
  readonly signal?: AbortSignal;
  readonly onEvent?: (event: CredentialEvent) => void;
};

What a session is given.

logical.NO_CREDENTIALSconstno test imports it
const NO_CREDENTIALS: Credentials

A session that gives nothing: every ask is unavailable.

logical.credentialSessionfunctionno test imports it
function credentialSession(o: SessionOptions): Credentials

The session of one command.

CredentialKindtypeno test imports it
type CredentialKind = "passphrase" | "password" | "pin" | "confirm";

What is asked for: a passphrase of a key, a password, a PIN of a token, or a yes (which is not secret, and is still asked once).

CREDENTIAL_KINDSconstno test imports it
const CREDENTIAL_KINDS: readonly CredentialKind[]

Every kind, for a program that walks them.

CredentialIdtypeno test imports it
type CredentialId = Brand<string, "credential id">;

The identity of a credential within one command, the key of its one prompt (ssh-key:~/.ssh/id_ed25519): made only by parseCredentialId.

parseCredentialIdfunction
function parseCredentialId(text: string): Result<CredentialId, string>

A credential id from text, or why the text is not one: the one way a CredentialId is made.

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

CredentialRequesttype
type CredentialRequest = { readonly kind: CredentialKind; readonly id: CredentialId; readonly prompt: string };

What a command asks: the kind, the id and the words shown to the person (which never hold the value).

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

Secrettype
type Secret = {
  readonly reveal: () => string;
  readonly toString: () => string;
  readonly toJSON: () => string;
  readonly [inspect: symbol]: () => string;
};

A value that is never written: its text, its JSON and its inspected form are [redacted]; only reveal() gives it.

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

secretOffunction
function secretOf(value: string): Secret

A secret over a value: the value is held in a closure and is on no property.

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

CredentialRefusaltype
type CredentialRefusal =
  | { readonly kind: "non-interactive" }
  | { readonly kind: "timeout"; readonly afterMs: number }
  | { readonly kind: "cancelled" }
  | { readonly kind: "unavailable"; readonly why: string }
  | { readonly kind: "empty" }
  | { readonly kind: "too-short"; readonly minimum: number }
  | { readonly kind: "closed" };

Why a credential was not given.

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

CREDENTIAL_REFUSALSconst
const CREDENTIAL_REFUSALS: readonly ("cancelled" | "closed" | "empty" | "non-interactive" | "timeout" | "too-short" | "unavailable")[]

Every reason by name.

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

refusalMessagefunction
function refusalMessage(r: CredentialRefusal, id: string): string

One sentence for a refusal, with no value in it.

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

refusalCodefunction
function refusalCode(r: CredentialRefusal): string

The stable code of a refusal, for the problem a command reports.

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

refusalProblemfunctionno test imports it
function refusalProblem(r: CredentialRefusal, id: string): Problem

The failure a command reports for a refusal.

AskLimitstypeno test imports it
type AskLimits = { readonly timeoutMs: number; readonly signal: AbortSignal };

What a port is given to ask with: the time it has and a signal that is aborted when it has none left or the run is stopped.

CredentialPorttype
type CredentialPort = {
  readonly ask: (request: CredentialRequest, limits: AskLimits) => Promise<Result<Secret, CredentialRefusal>>;
};

The port: asks a person, and gives the secret or why not. A record of functions.

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

Clocktype
type Clock = { readonly after: (ms: number, fn: () => void) => () => void };

A timer as a port: calls fn once after ms and gives the function that cancels it.

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

CredentialEventtype
type CredentialEvent =
  | { readonly kind: "asked"; readonly id: string; readonly credential: CredentialKind }
  | { readonly kind: "given"; readonly id: string }
  | { readonly kind: "refused"; readonly id: string; readonly refusal: CredentialRefusal["kind"] };

What a session tells its watcher (the run log): that a prompt happened and how it ended, never a value.

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

Credentialstypeno test imports it
type Credentials = { /** The credential, asked once per command for each id (concurrent asks for one id share the one … (510 characters)
type Credentials = {
  /** The credential, asked once per command for each id (concurrent asks for one id share the one prompt, a refusal is held as well); prompts of different ids go one at a time. */
  readonly get: (request: CredentialRequest) => Promise<Result<Secret, CredentialRefusal>>;
  /** The values handed out so far, for the redactor. */
  readonly values: () => readonly string[];
  /** Drops every answer and every value; a later `get` is refused as `closed`. */
  readonly close: () => void;
};

The one session a command asks through.

MAX_TIMEOUT_MSconst
const MAX_TIMEOUT_MS: 600000

The longest a prompt may wait, whatever is asked for: ten minutes.

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

DEFAULT_TIMEOUT_MSconst
const DEFAULT_TIMEOUT_MS: 120000

How long a prompt waits where nothing is said: two minutes.

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

limitOffunction
function limitOf(ms: number | undefined): number

The time a prompt may take: what was asked for, held to between a second and MAX_TIMEOUT_MS; DEFAULT_TIMEOUT_MS where nothing was asked or the number is not one.

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

SessionOptionstypeno test imports it
type SessionOptions = { /** What asks the person; none where there is none (every ask is then `unavailable`). */ rea… (508 characters)
type SessionOptions = {
  /** What asks the person; none where there is none (every ask is then `unavailable`). */
  readonly port?: CredentialPort;
  /** Whether a person can be asked at all (a terminal on both ends, not `--non-interactive`). */
  readonly interactive: boolean;
  readonly clock: Clock;
  readonly timeoutMs?: number;
  /** Aborted when the run is stopped: the prompt in hand ends as `cancelled`. */
  readonly signal?: AbortSignal;
  readonly onEvent?: (event: CredentialEvent) => void;
};

What a session is given.

NO_CREDENTIALSconst
const NO_CREDENTIALS: Credentials

A session that gives nothing: every ask is unavailable.

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

credentialSessionfunction
function credentialSession(o: SessionOptions): Credentials

The session of one command.

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

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