IF Commons GitHub

Archon governance

0002Active

0002-archon-governance · owner if · domain commons

Requirements

FR-001checkpassing

The library MUST make a requirement id, a resource kind id, a subject name and a secret reference only by functions that validate them (a requirement id is lower case words joined by dots or hyphens, at most 100 characters; a subject name is a host name; a secret reference is secret:<store>/<name>), and a text that is none of them MUST be refused with the rule it broke.

Enforced (check): .github: cd commons/archon && bun run verify — suite/governance.test.ts: names are made only by their functions

Proved by: archon/suite/governance.test.ts

Written in: archon/src/governance/ids.ts

Tests: passed: suite/governance.test.ts names are made only by their functions, and a text that is none is refused with the rule

FR-002checkpassing

The library MUST give the catalogue of resource kinds as data, each with its id, a sentence, the classes of subject it applies to (machine, device, workstation, cloud-account) and whether it can destroy, and the catalogue MUST include kinds for the packages, users, files, services, firewall rules and SSH keys of a machine, the tools a computer needs at a pinned version, the DNS records of a zone and the resources of a cloud account.

Enforced (check): .github: cd commons/archon && bun run verify — suite/governance.test.ts: the catalogue has kinds for machines, zones and cloud accounts

Proved by: archon/suite/governance.test.ts

Written in: archon/src/governance/kinds.ts

Tests: passed: suite/governance.test.ts the catalogue has kinds for machines, zones and cloud accounts, each with its classes and

FR-003checkpassing

defineRequirement MUST return a requirement or every reason it is not one: it MUST refuse a requirement with no reason (why), a kind that is not in the catalogue, a subject class the kind does not apply to, a desired state that is not data, a destructive requirement that does not say how it can be rolled back, and a requirement that asks for a resource to be absent unless its change class is destructive.

Enforced (check): .github: cd commons/archon && bun run verify — suite/governance.test.ts: a requirement is defined or refused with every reason

Proved by: archon/suite/governance.test.ts

Written in: archon/src/governance/json.ts, archon/src/governance/requirement.ts

Tests: passed: suite/governance.test.ts a requirement is defined, or refused with every reason

FR-004checkpassing

findSecretLike MUST find, in a desired state, every text that looks like a secret (a private key block, an access key of a cloud, a token of a code host, or any text under a key named for a password, a passphrase, a secret, a token or a private key that is not a secret reference), by the path where it was found, and defineRequirement MUST refuse a desired state in which it finds one.

Enforced (check): .github: cd commons/archon && bun run verify — suite/governance.test.ts: text that looks like a secret is found by its path

Proved by: archon/suite/governance.test.ts

Written in: archon/src/governance/requirement.ts, archon/src/governance/secret.ts

Tests: passed: suite/governance.test.ts text that looks like a secret is found by its path, and a requirement that holds one is re

FR-005checkpassing

The library MUST give the controls of each assurance profile as data: how a change is approved (an authenticated push, a signed commit, or a signed commit with a second approver), how a key is held, what a machine accepts as a tip, how recovery works, what is audited, how remote access is exposed, whether a second approver is needed for a change of tier or a destructive change, whether the hash of the plan is required, and how strictly tools are pinned (any current version, a release line, or one exact version with the hash of its artifact); and the profiles MUST be ordered from the least to the most strict, each control value having a rank.

Enforced (check): .github: cd commons/archon && bun run verify — suite/governance.test.ts: each profile gives every control and the profiles are ranked

Proved by: archon/suite/governance.test.ts

Written in: archon/src/governance/assurance.ts

Tests: passed: suite/governance.test.ts each profile gives every control, and the profiles are ranked from the least strict to the

FR-006checkpassing

A fleet MUST be able to override one control of its profile with a value, a reason and a date, and the library MUST refuse an override with no reason, a control it does not have, and a value that is not one of the control's values, and MUST keep every override in the resolved assurance so that a report can say it.

Enforced (check): .github: cd commons/archon && bun run verify — suite/governance.test.ts: an override has a reason and a date and is kept

Proved by: archon/suite/governance.test.ts

Written in: archon/src/governance/assurance.ts

Tests: passed: suite/governance.test.ts an override has a reason and a date, names a control it has and a value it has, and is kep

FR-007checkpassing

The library MUST state, as data, the floor that holds whatever the profile and whatever the overrides: no secret in a model, a specification, a commit, a log or a report; no library stores or sees a passphrase; an agent proposes and a person approves; a destructive action needs the marker of its requirement and a confirmation typed by a person.

Enforced (check): .github: cd commons/archon && bun run verify — suite/governance.test.ts: the floor is data and no control or override lowers it

Proved by: archon/suite/governance.test.ts

Written in: archon/src/governance/assurance.ts

Tests: passed: suite/governance.test.ts the floor is stated as data and no control or override can lower it

FR-008checkpassing

judgeAssuranceChange MUST decide whether a tip that proposes an assurance is accepted, by the assurance in force and not by the one proposed: it MUST name each control of the assurance in force that the evidence of the approval does not meet and refuse the change where there is one, it MUST accept a change that the evidence meets, and it MUST record, for an accepted change that lowers a control, which controls it lowers, so that a commit cannot lower its own bar.

Enforced (check): .github: cd commons/archon && bun run verify — suite/governance.test.ts: a change of assurance is judged by the assurance in force

Proved by: archon/suite/governance.test.ts

Written in: archon/src/governance/assurance.ts

Tests: passed: suite/governance.test.ts a change of assurance is judged by the assurance in force, and an accepted change records

Acceptance scenarios

  1. Given the text web-01.example.test, When it is made a subject name, Then it is one, and Web 01 is refused with the rule, per FR-001.
  2. Given a requirement for a package with no why, When it is defined, Then it is refused with that reason, per FR-003.
  3. Given a desired state with a private key block under content, When the requirement is defined, Then it is refused and the path content is named, per FR-004.
  4. Given the profile solo and the profile regulated, When their controls are read, Then every control of solo has a rank lower than or equal to that of regulated, per FR-005.
  5. Given an override of keyCustody with no reason, When the assurance is resolved, Then it is refused, per FR-006.
  6. Given the profile in force team and a proposed solo with evidence of an authenticated push only, When the change is judged, Then it is refused and the controls that are not met are named, per FR-008.
  7. Given the profile in force team and a proposed solo with evidence of a signed commit by a listed signer with a hardware key, When the change is judged, Then it is accepted and the lowered controls are recorded, per FR-008.

Out of scope

  • Keys, signatures and the verification of a tip: the library of signing.
  • The resolution of a subject selector by tags: the library of tags (the selector here names subjects, all subjects or a class).

Edge cases

  • A requirement for a kind that does not apply to the subject class it names: refused, per FR-003.
  • An override that raises a control: accepted with its reason, per FR-006.
  • A change that lowers nothing: accepted when the evidence meets the profile in force, with an empty record of lowered controls, per FR-008.

Assumptions

  • A secret-looking text is a reason to refuse and never a proof that no secret is present: the check is a guard, and the rule is that the model holds only references, per FR-004.

Open questions

  • None.

Key entities

  • Requirement - what a subject must be, with its why, its change class and its verification.
  • Assurance - a profile and its overrides, resolved to controls.
  • Floor - what holds whatever the profile.

Success criteria

SC-001success criterion

A requirement that holds a secret, has no reason or asks for a kind its subject cannot have is never made.

SC-002success criterion

A commit cannot lower the assurance of the fleet that follows it.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

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