ProfileNametypeno test imports ittype ProfileName = "solo" | "team" | "regulated";A named level of strictness.
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"ProfileNametypeno test imports ittype ProfileName = "solo" | "team" | "regulated";A named level of strictness.
PROFILE_NAMESconstconst PROFILE_NAMES: readonly ProfileName[]Every profile, from the least strict to the most.
Controlstypeno test imports ittype 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 ittype ControlName = keyof Controls;The name of a control.
CONTROL_NAMESconstconst CONTROL_NAMES: readonly (keyof Controls)[]The names of the controls.
rankOffunctionfunction rankOf(control: keyof Controls, value: string): numberThe rank of a value of a control (0 is the least strict), or -1 where it is not a value of it.
PROFILESconstconst PROFILES: Readonly<Record<ProfileName, Controls>>The profiles.
FloorRuletypeno test imports ittype FloorRule = { readonly id: string; readonly rule: string };One rule of the floor.
FLOORconstconst FLOOR: readonly FloorRule[]What holds whatever the profile and whatever the overrides.
Overridetypeno test imports ittype 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.
Assurancetypetype Assurance = {
readonly profile: ProfileName;
readonly controls: Controls;
readonly overrides: readonly Override[];
};A profile with the overrides of a fleet, resolved to its controls.
parseOverridefunctionno test imports itfunction parseOverride(input: unknown): Result<Override, string>An override from untyped data, or why it is not one.
resolveAssurancefunctionfunction resolveAssurance(profile: ProfileName, overrides?: readonly unknown[]): Result<Assurance, readonly string[]>The assurance of a profile with overrides, or every reason an override is refused.
ApprovalEvidencetypetype 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.
unmetByfunctionno test imports itfunction 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 itfunction 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 ittype AssuranceJudgement =
| { readonly kind: "accepted"; readonly lowered: readonly ControlName[] }
| { readonly kind: "refused"; readonly unmet: readonly ControlName[] };The judgement of a tip that proposes an assurance.
judgeAssuranceChangefunctionfunction judgeAssuranceChange(input: { readonly inForce: Assurance; readonly proposed: Assurance; readonly evidence: ApprovalEvidence; }): AssuranceJudgementWhether 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.