Module format 

The attestation format: the payload’s fields, the note’s blocks, and the names every producer and verifier shares (SPEC.md, “The note”).

Structs

Block

One signed statement out of a note: the exact bytes that were signed (trailing newline included) and the armored signature over them.

Names

One complete set of the names a signed attestation lives under: its header, the two notes refs, the SSH namespace, the two fingerprint domains and the payload’s producer-line word. A note is read WHOLE under one set (SPEC.md, “Names”): its header says which, and the namespace, the domains and the inputs ref follow, so the two sets never mix inside one note.

Constants

FORMAT

First token of every payload (the LEGACY name until Phase 4 of ADR-0068’s plan; see WRITE). A verifier that does not recognise this string must treat the note as absent: an unknown version may mean anything, and “run the tests” is the only safe reading of anything.

GREEN

The names notes are signed under from Phase 4. Verifiers read them first and fall back to LEGACY (SPEC.md, “Names”).

INPUTS_REF

The second notes ref, keyed by input fingerprint rather than by object. Every key there is a synthetic oid that is not an object, which is why it is a separate ref: git notes prune on it would drop everything, and the main ref keeps its 1.x invariant that every key is real.

LEGACY

The names notes have been written under since 1.0, and still are until WRITE becomes GREEN in Phase 4. Removed at the census.

LOCAL_PREFIX

Where sign.sh --no-push keeps blocks that never reached origin, under refs/notes/, prefixed to either ref name above. Origin cannot revoke them, so a verifier reads them only when asked (--include-local).

MAX_BLOCKS

How many blocks of one note are read. Every block costs two ssh-keygen runs, and the notes ref is writable by anyone with push access.

NAMESPACE

The ssh-keygen -Y namespace. Namespaces exist so a signature minted for one purpose cannot be replayed for another; an allowed_signers entry pinned to this namespace accepts nothing else.

NOTES_REF

The notes ref, as git notes --ref wants it.

WRITE

The ONE owner of what is written: FORMAT, NOTES_REF, INPUTS_REF, NAMESPACE, the producer word of payload and the set-less functions (fingerprint::key, canon_key, their preimages, notes::sync_mirrors) all derive from it. LEGACY until Phase 4, which changes this line to GREEN, together with the four name assignments in sign/sign.sh (held equal to these by tests/sign.sh): a dependent signing with the constants (greengate, through a caret pin) cannot write the new names earlier.

Functions

block

A signed block as a note holds it: the payload without its trailing newline, a blank line, the armored signature without its own.

bound_platform

The platform a signer principal is bound to: the text after its last @ when that is <arch>-<os> over the closed sets below, else None. A principal that names no platform (ci@relais, an email address) is unbound, and so is one whose suffix has any other shape (x@x86_64-linux-gnu, x@riscv64-linux).

canon_claim

The canonical fingerprint a block claims: a canon <oid> line of exactly two blank-separated fields, first occurrence wins. A malformed oid is not a claim.

field

Read a payload field BY PREFIX, never by line position: the payload has grown a line once already (v1 -> v2 added platform), and a positional reader silently mis-assigns every field after an insertion rather than failing. First match wins, so a second gates line cannot smuggle a value past the caller.

input_fp

The fingerprint a block claims for gate: an input <gate> <fp> line of exactly three blank-separated fields, first occurrence wins. Byte-strict like field; a fourth field or a malformed oid is not a claim.

is_oid

A 40- or 64-hex object id, as hash-object prints one.

payload

The payload of an attestation, in the exact shape SPEC.md gives: tree, gates, platform, the input lines in spec order, canon, then the producer line, each followed by LF. The same inputs give the same bytes, so a re-run recognises its own block.

platform

Where a suite ran, as <arch>-<os>. Coarser than a target triple on purpose: the libc flavour is not something std can answer, and the question a CI matrix actually asks is “did this run on MY leg”.

platform_matches

Does an attestation minted on ran_on satisfy what the caller asked for?

split_blocks

A note into its blocks. Since 1.2.0 a note may hold several — a laptop’s and a CI job’s, each on its own platform — separated by blank lines, which is exactly what git notes append produces.

split_note

The first block of a note, as payload and signature.