IF Commons GitHub

assessor/verify-pack

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-quality-evidence FR-064

The offline verifier of an assessor pack (commons 0001-quality-evidence FR-064 to FR-066): small, typed TypeScript with no import and no dependency, run on Bun and on Node 26 with no network and no account, and shipped inside the pack (verify/verify-pack.ts) so that the pack checks itself. It is given the pack's files (path to bytes) and checks, in this order, and names the first thing that fails:

  1. manifest: the manifest reads and is a pack's manifest.
  2. files: every file the manifest lists is in the pack with the SHA-256 and size it says, and the pack holds no file the manifest does not list.
  3. evidence-chain: each evidence file names, as ifc.quality.previous.sha256, the digest of the file before it, from the manifest's anchor to the head it names.
  4. ledger-chain: the records of the ledger are numbered from 1 and each names the digest of the one before it.
  5. notes: each note names a file the pack holds, with the SHA-256 the note says.
  6. signature:<file>: each signed envelope verifies against the keys in the pack (an allowed-signers file of ssh-ed25519 keys), and its statement names files the pack holds, with their digests; every file the pack carries is named by one.
  7. figures: the figures of the manifest's summary equal the figures computed from the files.

A part that cannot be checked (a file the manifest lists and the pack lacks, a key the pack does not hold, no signature at all) is not_run with its reason, and a pack with any check not pass is not reported verified.

This file imports nothing, on purpose: it is copied into every pack byte for byte. It uses crypto.subtle (SHA-256 and Ed25519), atob, TextEncoder and JSON, which Bun and Node 26 both have. figuresOf is also what the generator uses for the figures of the page and of the pack's summary, so that the two cannot be computed two ways.

import { verifyPack } from "./verify-pack.ts";
// const report = await verifyPack(new Map([["manifest.json", bytes]]));
// report.verified; report.first?.detail

Source: commons/quality/src/assessor/verify-pack.ts

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

PackFilestype
type PackFiles = ReadonlyMap<string, Uint8Array>;

The files of a pack: path with / to bytes.

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

PackChecktypeno test imports it
type PackCheck = {
  readonly name: string;
  readonly status: "pass" | "fail" | "not_run";
  readonly detail: string;
  /** The file it is about, where it is about one. */
  readonly file?: string;
};

What one check found.

PackReporttypeno test imports it
type PackReport = {
  /** Whether every check passed. */
  readonly verified: boolean;
  readonly checks: readonly PackCheck[];
  /** The first check that failed, else the first that could not be run; none where all passed. */
  readonly first?: PackCheck;
};

The verification of a pack.

Figurestypeno test imports it
type Figures = {
  readonly evidenceFiles: number;
  readonly cases: number;
  readonly passed: number;
  readonly failed: number;
  readonly notRun: number;
  readonly otherCases: number;
  readonly ledgerRecords: number;
  readonly nonconformancesOpen: number;
  readonly nonconformancesClosed: number;
  readonly capasOpen: number;
  readonly capasClosed: number;
};

The figures of a pack, computed from its files and stated in its manifest's summary (0001-quality-evidence FR-062, FR-064).

GENESIS_DIGESTconstno test imports it
const GENESIS_DIGEST: string

The digest of 64 zeros: what the first file of a chain names as its predecessor.

PREVIOUS_ATTRIBUTEconstno test imports it
const PREVIOUS_ATTRIBUTE: "ifc.quality.previous.sha256"

The attribute that chains the evidence files.

digestOffunctionno test imports it
function digestOf(bytes: Uint8Array<ArrayBufferLike>): Promise<string>

The SHA-256 of bytes as lower-case hexadecimal.

PackEvidenceFactstypeno test imports it
type PackEvidenceFacts = {
  readonly previous: string | undefined;
  readonly traceId: string | undefined;
  readonly outcomes: readonly string[];
  readonly readable: boolean;
};

What an evidence file says of itself: its predecessor, the trace id of its spans and the outcome of each case.

evidenceFactsfunctionno test imports it
function evidenceFacts(bytes: Uint8Array<ArrayBufferLike> | undefined): PackEvidenceFacts

Reads an evidence file (an OTLP/JSON document of 0001-quality-evidence FR-018) for what the verifier needs of it.

figuresOffunction
function figuresOf(files: PackFiles): Figures

The figures of a pack computed from its files: the cases of the evidence files by outcome, and the nonconformances and CAPA the ledger's records open and close. The same function is what the generator states, so that a figure of the page equals the same figure of the pack.

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

TrustedKeytypeno test imports it
type TrustedKey = { readonly principal: string; readonly raw: Uint8Array };

A public key the pack trusts: the principal its allowed-signers line names and the raw Ed25519 key.

parseAllowedSignersfunction
function parseAllowedSigners(content: string): readonly TrustedKey[]

The ssh-ed25519 keys of an allowed-signers file (principal [options] ssh-ed25519 KEY [comment]); other lines are skipped.

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

allowedSignersLinefunction
function allowedSignersLine(principal: string, raw: Uint8Array<ArrayBufferLike>): string

The text of an allowed-signers line for an Ed25519 key: what a harness publishes beside its pack.

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

paefunctionno test imports it
function pae(payloadType: string, payload: Uint8Array<ArrayBufferLike>): Uint8Array<ArrayBufferLike>

The pre-authentication encoding of DSSE: what a signature of an envelope is over.

verifyPackfunction
function verifyPack(files: PackFiles): Promise<PackReport>

Verifies a pack (0001-quality-evidence FR-064, FR-065): see the module's account of the checks and their order.

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

showReportfunctionno test imports it
function showReport(r: PackReport): string

A report as lines of text: each check with its status, then the verdict.

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