IF Commons GitHub

governance/reach

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0005-reach-and-targets FR-001, 0005-reach-and-targets FR-002, 0005-reach-and-targets FR-003

Where an action may be reached from and run, as governance (commons headless 0005-reach-and-targets): a reach policy for each action (the channels it may come through, whether it is read-only and idempotent, whether it needs a terminal, whom it runs as, how it is confirmed), the classes of target there are, and the trust policy for them. The action is defined once; where it runs, here or on a target, is a separate choice that these facts bound.

Nothing here names a secret value: the trust policy says how a host is known and what is done when it is not, and a credential is only ever a reference.

import { defineReach, reachProblems } from "./reach.ts";
import { defineAction } from "./action.ts";
const status = defineAction({ id: "status", summary: "Status.", kind: "report" });
reachProblems(status, defineReach({ channels: ["local", "ssh", "mcp"], readOnly: true })); // []

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

8 of 38 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.Channeltypeno test imports it
type Channel = "local" | "ssh" | "mcp" | "rest";

A way an action can be reached: here (local), on a target through the system's ssh client (ssh), through a tool server (mcp) or a REST interface (rest).

governance.CHANNELSconstno test imports it
const CHANNELS: readonly Channel[]

Every channel.

governance.RunsAstypeno test imports it
type RunsAs = "caller" | "service";

Whom an action runs as on the machine it runs on: the person or program that called it, or a service account of the program.

governance.ConfirmationClasstypeno test imports it
type ConfirmationClass = "none" | "flag" | "person" | "consent";

How an action is confirmed where it is confirmed at all: not at all, by a flag of the invocation, by a person, or by a prior consent (0008-exit-style-consent FR-004): an identifier of an approval a person gave earlier, passed as --consent <id>, which lets a run that changes something go on with no terminal, and is recorded in the run's log.

governance.ReachPolicytypeno test imports it
type ReachPolicy = { /** The channels it may come through; never empty. */ readonly channels: readonly Channel[]; … (622 characters)
type ReachPolicy = {
  /** The channels it may come through; never empty. */
  readonly channels: readonly Channel[];
  /** Whether it only reads, so that a key that may only read may run it. */
  readonly readOnly: boolean;
  /** Whether repeating it is safe: the same fact as the action's, held here so that a reach decision needs no more than this. */
  readonly idempotent: boolean;
  /** Whether it needs a terminal; false by default, and an action that needs one MUST NOT come through a channel that has none. */
  readonly needsTty: boolean;
  readonly runsAs: RunsAs;
  readonly confirmation: ConfirmationClass;
};

The reach policy of one action.

governance.ReachDefinitiontypeno test imports it
type ReachDefinition = {
  readonly channels: readonly Channel[];
  readonly readOnly?: boolean;
  readonly idempotent?: boolean;
  readonly needsTty?: boolean;
  readonly runsAs?: RunsAs;
  readonly confirmation?: ConfirmationClass;
};

What defineReach takes: the channels, and any fact that is not the safe default.

governance.defineReachfunctionno test imports it
function defineReach(d: ReachDefinition): ReachPolicy

A reach policy with the safe defaults: it changes something, is not assumed idempotent, needs no terminal, runs as the caller, and is not confirmed.

governance.TargetClasstypeno test imports it
type TargetClass = "server" | "workstation" | "device" | "network-gear";

What a target is, for what may be done with it and how it is reached.

governance.TARGET_CLASSESconstno test imports it
const TARGET_CLASSES: readonly TargetClass[]

Every class of target.

governance.TrustPolicytypeno test imports it
type TrustPolicy = {
  readonly hostKey: "verify";
  readonly knownHosts: readonly ["repository", "user"];
  readonly onMismatch: "refuse";
  readonly firstContact: "explicit-verb";
  readonly credentials: "reference-only";
};

How a host is known and what is done when it is not: its key is checked against the known-hosts of the repository first and the user's file after, a key that does not match is refused and never accepted for the person, the first contact with a host is a verb of its own that a person runs and confirms by the fingerprint, and a credential is a reference, never a value. Each field has the one value the policy allows, so a policy cannot be loosened by data.

governance.TRUSTconstno test imports it
const TRUST: TrustPolicy

The trust policy: there is one.

governance.ReachRuletypeno test imports it
type ReachRule =
  | "reach/missing"
  | "reach/no-channel"
  | "reach/duplicate-channel"
  | "reach/read-only-mismatch"
  | "reach/idempotent-mismatch"
  | "reach/tty-without-terminal"
  | "reach/destructive-unconfirmed"
  | "reach/human-only-remote"
  | "reach/consent-on-read";

The ways a reach policy can contradict the action it is of.

governance.ReachProblemtypeno test imports it
type ReachProblem = { readonly rule: ReachRule; readonly message: string };

A contradiction between an action and its reach policy.

governance.reachProblemsfunctionno test imports it
function reachProblems(a: ActionFacts, r: ReachPolicy): readonly ReachProblem[]

Every contradiction between an action and its reach policy: a policy with no channel or one twice; readOnly that is not whether the action only reads; idempotent that is not the action's; a need for a terminal on a channel that has none; a destructive action that is not confirmed; an action for a person that comes through a channel that is a machine's.

governance.interactiveAllowedfunctionno test imports it
function interactiveAllowed(r: ReachPolicy): boolean

Whether a call may be interactive (the client may ask, a terminal may be given): only where the action's reach policy says it needs a terminal, which is explicit and never the default.

governance.Reachedtypeno test imports it
type Reached = { readonly facts: ActionFacts; readonly reach: ReachPolicy | undefined };

An action with its reach policy, or without one.

governance.reachConformancefunctionno test imports it
function reachConformance(actions: readonly Reached[]): readonly ReachProblem[]

The conformance rule: every action MUST have a reach policy (reach/missing), and each policy MUST fit its action.

governance.ReachDecisiontypeno test imports it
type ReachDecision = { readonly kind: "allowed" } | { readonly kind: "refused"; readonly reason: "channel" | "read-only-key"; readonly message: string };

What a channel of the policy and a key's role let through.

governance.reachDecisionfunctionno test imports it
function reachDecision(a: ActionFacts, r: ReachPolicy, channel: Channel, caller: { readonly mayOnlyRead: boolean; }): ReachDecision

Whether an action may be reached through a channel, by a caller that may only read (a probe key) or may do more.

Channeltypeno test imports it
type Channel = "local" | "ssh" | "mcp" | "rest";

A way an action can be reached: here (local), on a target through the system's ssh client (ssh), through a tool server (mcp) or a REST interface (rest).

CHANNELSconstno test imports it
const CHANNELS: readonly Channel[]

Every channel.

RunsAstypeno test imports it
type RunsAs = "caller" | "service";

Whom an action runs as on the machine it runs on: the person or program that called it, or a service account of the program.

ConfirmationClasstypeno test imports it
type ConfirmationClass = "none" | "flag" | "person" | "consent";

How an action is confirmed where it is confirmed at all: not at all, by a flag of the invocation, by a person, or by a prior consent (0008-exit-style-consent FR-004): an identifier of an approval a person gave earlier, passed as --consent <id>, which lets a run that changes something go on with no terminal, and is recorded in the run's log.

ReachPolicytypeno test imports it
type ReachPolicy = { /** The channels it may come through; never empty. */ readonly channels: readonly Channel[]; … (622 characters)
type ReachPolicy = {
  /** The channels it may come through; never empty. */
  readonly channels: readonly Channel[];
  /** Whether it only reads, so that a key that may only read may run it. */
  readonly readOnly: boolean;
  /** Whether repeating it is safe: the same fact as the action's, held here so that a reach decision needs no more than this. */
  readonly idempotent: boolean;
  /** Whether it needs a terminal; false by default, and an action that needs one MUST NOT come through a channel that has none. */
  readonly needsTty: boolean;
  readonly runsAs: RunsAs;
  readonly confirmation: ConfirmationClass;
};

The reach policy of one action.

ReachDefinitiontypeno test imports it
type ReachDefinition = {
  readonly channels: readonly Channel[];
  readonly readOnly?: boolean;
  readonly idempotent?: boolean;
  readonly needsTty?: boolean;
  readonly runsAs?: RunsAs;
  readonly confirmation?: ConfirmationClass;
};

What defineReach takes: the channels, and any fact that is not the safe default.

defineReachfunction
function defineReach(d: ReachDefinition): ReachPolicy

A reach policy with the safe defaults: it changes something, is not assumed idempotent, needs no terminal, runs as the caller, and is not confirmed.

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

TargetClasstypeno test imports it
type TargetClass = "server" | "workstation" | "device" | "network-gear";

What a target is, for what may be done with it and how it is reached.

TARGET_CLASSESconst
const TARGET_CLASSES: readonly TargetClass[]

Every class of target.

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

TrustPolicytypeno test imports it
type TrustPolicy = {
  readonly hostKey: "verify";
  readonly knownHosts: readonly ["repository", "user"];
  readonly onMismatch: "refuse";
  readonly firstContact: "explicit-verb";
  readonly credentials: "reference-only";
};

How a host is known and what is done when it is not: its key is checked against the known-hosts of the repository first and the user's file after, a key that does not match is refused and never accepted for the person, the first contact with a host is a verb of its own that a person runs and confirms by the fingerprint, and a credential is a reference, never a value. Each field has the one value the policy allows, so a policy cannot be loosened by data.

TRUSTconst
const TRUST: TrustPolicy

The trust policy: there is one.

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

ReachRuletypeno test imports it
type ReachRule =
  | "reach/missing"
  | "reach/no-channel"
  | "reach/duplicate-channel"
  | "reach/read-only-mismatch"
  | "reach/idempotent-mismatch"
  | "reach/tty-without-terminal"
  | "reach/destructive-unconfirmed"
  | "reach/human-only-remote"
  | "reach/consent-on-read";

The ways a reach policy can contradict the action it is of.

ReachProblemtypeno test imports it
type ReachProblem = { readonly rule: ReachRule; readonly message: string };

A contradiction between an action and its reach policy.

reachProblemsfunction
function reachProblems(a: ActionFacts, r: ReachPolicy): readonly ReachProblem[]

Every contradiction between an action and its reach policy: a policy with no channel or one twice; readOnly that is not whether the action only reads; idempotent that is not the action's; a need for a terminal on a channel that has none; a destructive action that is not confirmed; an action for a person that comes through a channel that is a machine's.

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

interactiveAllowedfunction
function interactiveAllowed(r: ReachPolicy): boolean

Whether a call may be interactive (the client may ask, a terminal may be given): only where the action's reach policy says it needs a terminal, which is explicit and never the default.

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

Reachedtype
type Reached = { readonly facts: ActionFacts; readonly reach: ReachPolicy | undefined };

An action with its reach policy, or without one.

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

reachConformancefunction
function reachConformance(actions: readonly Reached[]): readonly ReachProblem[]

The conformance rule: every action MUST have a reach policy (reach/missing), and each policy MUST fit its action.

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

ReachDecisiontypeno test imports it
type ReachDecision = { readonly kind: "allowed" } | { readonly kind: "refused"; readonly reason: "channel" | "read-only-key"; readonly message: string };

What a channel of the policy and a key's role let through.

reachDecisionfunction
function reachDecision(a: ActionFacts, r: ReachPolicy, channel: Channel, caller: { readonly mayOnlyRead: boolean; }): ReachDecision

Whether an action may be reached through a channel, by a caller that may only read (a probe key) or may do more.

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

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