IF Commons GitHub

governance/assurance

Written to: 4 requirements: 4 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-archon-governance FR-005, 0002-archon-governance FR-006, 0002-archon-governance FR-007, 0002-archon-governance FR-008

The assurance of a fleet: how strictly it approves a change to its machines. A profile (solo, team or regulated) is a table of controls, each control a value with a rank from the least strict to the most; a fleet can override one control with a reason and a date; and a floor that no profile and no override lowers is stated beside them. judgeAssuranceChange decides whether a tip that proposes another assurance is accepted by the assurance in force, so that a commit cannot lower its own bar.

import { PROFILES } from "./assurance.ts";
PROFILES.solo.approval; // "authenticated-push"
PROFILES.regulated.keyCustody; // "hardware-required"

Source: commons/archon/src/governance/assurance.ts

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

ProfileNametypeno test imports it
type ProfileName = "solo" | "team" | "regulated";

A named level of strictness.

PROFILE_NAMESconst
const PROFILE_NAMES: readonly ProfileName[]

Every profile, from the least strict to the most.

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

Controlstypeno test imports it
type Controls = { /** How a change is approved. */ readonly approval: "authenticated-push" | "signed-commit" | "sign… (1252 characters)
type Controls = {
  /** How a change is approved. */
  readonly approval: "authenticated-push" | "signed-commit" | "signed-commit-second-approver";
  /** How the key that approves is held. */
  readonly keyCustody: "optional" | "passphrase-or-hardware" | "hardware-required";
  /** What a machine accepts as the tip to follow. */
  readonly tipAccept: "authenticated-remote" | "signed-by-listed-signer" | "signed-with-plan-hash";
  /** How a fleet recovers when a key is lost. */
  readonly recovery: "owner-backup" | "recovery-key" | "recovery-key-escrow-break-glass";
  /** What is kept of what happened. */
  readonly audit: "run-log" | "mail-every-change" | "offbox-ledger";
  /** How remote access is exposed. */
  readonly exposure: "lan-only" | "passkeys" | "passkeys-mfa";
  /** Whether a change of tier or a destructive change needs a second approver. */
  readonly secondApprover: "never" | "tier-and-destructive";
  /** Whether an approval must name the hash of the plan. */
  readonly planHash: "optional" | "required";
  /** How strictly the tools of a computer are pinned: any current version, a release line, or one exact version with the hash of its artifact. */
  readonly toolIntegrity: "rolling" | "release-line" | "exact-hashed";
};

The controls of a profile.

ControlNametypeno test imports it
type ControlName = keyof Controls;

The name of a control.

CONTROL_NAMESconst
const CONTROL_NAMES: readonly (keyof Controls)[]

The names of the controls.

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

rankOffunction
function rankOf(control: keyof Controls, value: string): number

The rank of a value of a control (0 is the least strict), or -1 where it is not a value of it.

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

PROFILESconst
const PROFILES: Readonly<Record<ProfileName, Controls>>

The profiles.

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

FloorRuletypeno test imports it
type FloorRule = { readonly id: string; readonly rule: string };

One rule of the floor.

FLOORconst
const FLOOR: readonly FloorRule[]

What holds whatever the profile and whatever the overrides.

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

Overridetypeno test imports it
type Override = {
  readonly control: ControlName;
  readonly value: string;
  readonly reason: string;
  readonly decidedOn: string;
};

An override of one control of a profile, with the reason and the date it was decided.

Assurancetype
type Assurance = {
  readonly profile: ProfileName;
  readonly controls: Controls;
  readonly overrides: readonly Override[];
};

A profile with the overrides of a fleet, resolved to its controls.

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

parseOverridefunctionno test imports it
function parseOverride(input: unknown): Result<Override, string>

An override from untyped data, or why it is not one.

resolveAssurancefunction
function resolveAssurance(profile: ProfileName, overrides?: readonly unknown[]): Result<Assurance, readonly string[]>

The assurance of a profile with overrides, or every reason an override is refused.

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

ApprovalEvidencetype
type ApprovalEvidence = {
  readonly mechanism: Controls["approval"];
  readonly keyHeld: "none" | "passphrase" | "hardware";
  readonly tip: Controls["tipAccept"];
  readonly secondApproverPresent: boolean;
  readonly planHashNamed: boolean;
};

What the approval of a tip is shown to have been.

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

unmetByfunctionno test imports it
function unmetBy(controls: Controls, evidence: ApprovalEvidence): readonly (keyof Controls)[]

The controls of an assurance that the evidence of an approval does not meet. Recovery, audit and exposure are not shown by an approval and are not judged here.

loweredByfunctionno test imports it
function loweredBy(inForce: Assurance, proposed: Assurance): readonly (keyof Controls)[]

The controls that the proposed assurance holds less strictly than the one in force.

AssuranceJudgementtypeno test imports it
type AssuranceJudgement =
  | { readonly kind: "accepted"; readonly lowered: readonly ControlName[] }
  | { readonly kind: "refused"; readonly unmet: readonly ControlName[] };

The judgement of a tip that proposes an assurance.

judgeAssuranceChangefunction
function judgeAssuranceChange(input: { readonly inForce: Assurance; readonly proposed: Assurance; readonly evidence: ApprovalEvidence; }): AssuranceJudgement

Whether a tip that proposes proposed is accepted: by the assurance in force, never by the one proposed, so that a commit cannot lower its own bar. An accepted change records the controls it lowers.

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

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