logical.CredentialKindtypeno test imports ittype 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).
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]"}'logical.CredentialKindtypeno test imports ittype 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 itconst CREDENTIAL_KINDS: readonly CredentialKind[]Every kind, for a program that walks them.
logical.CredentialIdtypeno test imports ittype 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 itfunction 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 ittype 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 ittype 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 itfunction secretOf(value: string): SecretA secret over a value: the value is held in a closure and is on no property.
logical.CredentialRefusaltypeno test imports ittype 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 itconst CREDENTIAL_REFUSALS: readonly ("cancelled" | "closed" | "empty" | "non-interactive" | "timeout" | "too-short" | "unavailable")[]Every reason by name.
logical.refusalMessagefunctionno test imports itfunction refusalMessage(r: CredentialRefusal, id: string): stringOne sentence for a refusal, with no value in it.
logical.refusalCodefunctionno test imports itfunction refusalCode(r: CredentialRefusal): stringThe stable code of a refusal, for the problem a command reports.
logical.refusalProblemfunctionno test imports itfunction refusalProblem(r: CredentialRefusal, id: string): ProblemThe failure a command reports for a refusal.
logical.AskLimitstypeno test imports ittype 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 ittype 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 ittype 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 ittype 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 ittype 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 itconst MAX_TIMEOUT_MS: 600000The longest a prompt may wait, whatever is asked for: ten minutes.
logical.DEFAULT_TIMEOUT_MSconstno test imports itconst DEFAULT_TIMEOUT_MS: 120000How long a prompt waits where nothing is said: two minutes.
logical.limitOffunctionno test imports itfunction limitOf(ms: number | undefined): numberThe 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 ittype 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 itconst NO_CREDENTIALS: CredentialsA session that gives nothing: every ask is unavailable.
logical.credentialSessionfunctionno test imports itfunction credentialSession(o: SessionOptions): CredentialsThe session of one command.
CredentialKindtypeno test imports ittype 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 itconst CREDENTIAL_KINDS: readonly CredentialKind[]Every kind, for a program that walks them.
CredentialIdtypeno test imports ittype 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.
parseCredentialIdfunctionfunction 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.
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).
Secrettypetype 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.
secretOffunctionfunction secretOf(value: string): SecretA secret over a value: the value is held in a closure and is on no property.
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.
CREDENTIAL_REFUSALSconstconst CREDENTIAL_REFUSALS: readonly ("cancelled" | "closed" | "empty" | "non-interactive" | "timeout" | "too-short" | "unavailable")[]Every reason by name.
refusalMessagefunctionfunction refusalMessage(r: CredentialRefusal, id: string): stringOne sentence for a refusal, with no value in it.
refusalCodefunctionfunction refusalCode(r: CredentialRefusal): stringThe stable code of a refusal, for the problem a command reports.
refusalProblemfunctionno test imports itfunction refusalProblem(r: CredentialRefusal, id: string): ProblemThe failure a command reports for a refusal.
AskLimitstypeno test imports ittype 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.
CredentialPorttypetype 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.
Clocktypetype 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.
CredentialEventtypetype 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.
Credentialstypeno test imports ittype 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_MSconstconst MAX_TIMEOUT_MS: 600000The longest a prompt may wait, whatever is asked for: ten minutes.
DEFAULT_TIMEOUT_MSconstconst DEFAULT_TIMEOUT_MS: 120000How long a prompt waits where nothing is said: two minutes.
limitOffunctionfunction limitOf(ms: number | undefined): numberThe 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.
SessionOptionstypeno test imports ittype 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_CREDENTIALSconstconst NO_CREDENTIALS: CredentialsA session that gives nothing: every ask is unavailable.
credentialSessionfunctionfunction credentialSession(o: SessionOptions): CredentialsThe session of one command.