IF Commons GitHub

governance/redact

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-headless-governance FR-011

Keeps a secret out of what a program prints, logs or returns (commons headless 0002-headless-governance FR-011, 0008-exit-style-consent FR-003). It redacts only what is a secret and never what merely looks like a line about one: the secret values the program holds, the password of a URL and a password= assignment, the shapes of the tokens that have a known form (GitHub, GitLab, Slack, AWS, npm, sk-, bearer and JWT tokens, private-key blocks), and the value of a key that the program declared secret (KEY=value, or "KEY": "value"). A sentence that names a variable (ERGONEX_GITHUB_TOKEN: the token is not set) is prose and is left as it is.

import { redactor } from "./redact.ts";
const redact = redactor(["hunter22"], { keys: ["APP_TOKEN"] });
redact("connect postgres://app:hunter22@db/x failed"); // "connect postgres://app:***@db/x failed"
redact("APP_TOKEN: the token is not set"); // unchanged: it is prose
redact("APP_TOKEN=abc123"); // "APP_TOKEN=***"

Source: commons/headless/src/governance/redact.ts

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

governance.MASKconstno test imports it
const MASK: "***"

What replaces a secret.

governance.MIN_SECRETconstno test imports it
const MIN_SECRET: 4

The shortest secret value that is replaced wherever it appears: a shorter one would mask ordinary words.

governance.RedactOptionstypeno test imports it
type RedactOptions = {
  /** The names of the keys that are secret in this program (`APP_TOKEN`): the value of `KEY=value` or `"KEY": "value"` is replaced. */
  readonly keys?: readonly string[];
  /** Whether the tokens of a known shape are replaced wherever they appear (true by default). */
  readonly shapes?: boolean;
};

What a redactor is told besides the secret values.

governance.redactfunctionno test imports it
function redact(text: string, secrets?: readonly string[], options?: RedactOptions): string

The text with the password of every URL, a password= assignment, every token of a known shape, the value of every declared key and every given secret replaced by ***.

governance.Redactortypeno test imports it
type Redactor = (text: string) => string;

A function that redacts with the secrets it was made with.

governance.redactorfunctionno test imports it
function redactor(secrets?: readonly string[], options?: RedactOptions): Redactor

A redactor for the secrets given (a program passes the values it holds: a token, a passphrase, the password of its URL) and the keys it declares secret.

governance.passwordOffunctionno test imports it
function passwordOf(url: string | undefined): string | undefined

The password of a URL, where it has one, so that it can be redacted wherever it turns up.

MASKconst
const MASK: "***"

What replaces a secret.

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

MIN_SECRETconstno test imports it
const MIN_SECRET: 4

The shortest secret value that is replaced wherever it appears: a shorter one would mask ordinary words.

RedactOptionstypeno test imports it
type RedactOptions = {
  /** The names of the keys that are secret in this program (`APP_TOKEN`): the value of `KEY=value` or `"KEY": "value"` is replaced. */
  readonly keys?: readonly string[];
  /** Whether the tokens of a known shape are replaced wherever they appear (true by default). */
  readonly shapes?: boolean;
};

What a redactor is told besides the secret values.

redactfunction
function redact(text: string, secrets?: readonly string[], options?: RedactOptions): string

The text with the password of every URL, a password= assignment, every token of a known shape, the value of every declared key and every given secret replaced by ***.

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

Redactortypeno test imports it
type Redactor = (text: string) => string;

A function that redacts with the secrets it was made with.

redactorfunction
function redactor(secrets?: readonly string[], options?: RedactOptions): Redactor

A redactor for the secrets given (a program passes the values it holds: a token, a passphrase, the password of its URL) and the keys it declares secret.

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

passwordOffunction
function passwordOf(url: string | undefined): string | undefined

The password of a URL, where it has one, so that it can be redacted wherever it turns up.

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

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