IF Commons GitHub

physical/bundle

Written to: 10 requirements: 10 proved, 0 partly, 0 failing, 0 with no test recorded. 0011-grc-bundles FR-002, 0011-grc-bundles FR-012, 0011-grc-bundles FR-001, 0011-grc-bundles FR-003, 0011-grc-bundles FR-004, 0011-grc-bundles FR-005 and 4 more

Verifying a whole evidence bundle offline (0011-grc-bundles): the manifest's items by hash and size, the ledger's hash chain against the head the manifest names, the canonical form of the documents, the signature of the manifest (the signer and the keys are the verifier's, never the bundle's), and the retention of the evidence. The core is pure over the contents of a bundle and names each fault as a typed finding of a closed union that says the item, entry, signature or file it concerns.

It uses no network, no file and no clock: readBundle (in bundle-files.ts) is the adapter that reads a folder into BundleContents.

import { codeOfFinding } from "./bundle.ts";
codeOfFinding({ kind: "item-missing", digest: "ab".repeat(32) }); // "E-BUNDLE-ITEM-MISSING"

Source: commons/grc/src/physical/bundle.ts

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

physical.BundleFiletypeno test imports it
type BundleFile = "manifest.json" | "ledger.json" | "evidence.json" | "signature.json";

The files of a bundle that hold a document.

physical.MANIFEST_PAYLOAD_TYPEconstno test imports it
const MANIFEST_PAYLOAD_TYPE: "application/vnd.grc.evidence-manifest+json"

The payload type of the signature of a manifest.

MANIFEST_PAYLOAD_TYPE; // "application/vnd.grc.evidence-manifest+json"
physical.BundleContentstypeno test imports it
type BundleContents = {
  readonly manifest: string | undefined;
  readonly ledger: string | undefined;
  readonly evidence: string | undefined;
  readonly signature: string | undefined;
  readonly items: ReadonlyMap<string, Uint8Array>;
};

What a bundle holds, read: the text of its documents (absent where the file is) and the bytes of its items by digest.

physical.TrustedKeytypeno test imports it
type TrustedKey = { readonly keyid: string; readonly role: string; readonly key: unknown };

A key the verifier trusts, the role it may attest in, and the key as its signer takes it.

physical.Trusttypeno test imports it
type Trust = { readonly policy: EvidencePolicy; readonly signer: Signer; readonly keys: readonly TrustedKey[] };

What the verifier gives: the evidence policy, the signer and the keys it trusts.

physical.BundleFindingtypeno test imports it
type BundleFinding = | { readonly kind: "item-missing"; readonly digest: string } | { readonly kind: "item-hash-mism… (1175 characters)
type BundleFinding =
  | { readonly kind: "item-missing"; readonly digest: string }
  | { readonly kind: "item-hash-mismatch"; readonly digest: string; readonly actual: string }
  | { readonly kind: "item-size-mismatch"; readonly digest: string; readonly expected: number; readonly actual: number }
  | { readonly kind: "item-extra"; readonly digest: string }
  | { readonly kind: "chain-broken"; readonly seq: number; readonly reason: string }
  | { readonly kind: "not-canonical"; readonly file: BundleFile }
  | { readonly kind: "signature-absent" }
  | { readonly kind: "signature-bad"; readonly keyid: string | undefined; readonly reason: string }
  | { readonly kind: "signer-unallowed"; readonly keyid: string | undefined; readonly why: "unknown-key" | "role" | "custody"; readonly detail: string }
  | { readonly kind: "evidence-expired"; readonly digest: string }
  | { readonly kind: "kind-unknown"; readonly file: BundleFile; readonly found: string }
  | { readonly kind: "schema-unknown"; readonly file: BundleFile; readonly found: string; readonly expected: string }
  | { readonly kind: "document-invalid"; readonly file: BundleFile; readonly message: string };

Every fault of a bundle, each with what it concerns.

physical.FindingKindtypeno test imports it
type FindingKind = BundleFinding["kind"];

The kind of a finding.

physical.FINDING_KINDSconstno test imports it
const FINDING_KINDS: readonly ["document-invalid", "kind-unknown", "schema-unknown", "not-canonical", "item-missing", "item-hash-mismatch", "item-size-mismatch", "item-extra", "chain-broken", "evidence-expired", "signature-absent", "signature-bad", "signer-unallowed"]

Every kind of finding, in the order a report gives them.

FINDING_KINDS.includes("item-missing"); // true
physical.codeOfFindingfunctionno test imports it
function codeOfFinding(f: BundleFinding): string

The stable problem code of a finding: E-BUNDLE- and its kind in upper case.

physical.codeOfKindfunctionno test imports it
function codeOfKind(kind: "chain-broken" | "document-invalid" | "evidence-expired" | "item-extra" | "item-hash-mismatch" | "item-missing" | "item-size-mismatch" | "kind-unknown" | "not-canonical" | "schema-unknown" | "signature-absent" | "signature-bad" | "signer-unallowed"): string

The stable problem code of a kind of finding.

codeOfKind("chain-broken"); // "E-BUNDLE-CHAIN-BROKEN"
physical.concernOffunctionno test imports it
function concernOf(f: BundleFinding): string

What a finding concerns, as one short name: an item, an entry, a signature, or a file.

concernOf({ kind: "chain-broken", seq: 3, reason: "entry 3 was changed" }); // "entry 3"
physical.describeFindingfunctionno test imports it
function describeFinding(f: BundleFinding): string

One sentence for a finding.

describeFinding({ kind: "signature-absent" }); // "the bundle has no signature"
physical.BundleReporttypeno test imports it
type BundleReport = { readonly at: string; readonly items: number; readonly entries: number; readonly findings: readonly BundleFinding[] };

What verification gave: the instant, the findings in the order of FINDING_KINDS, and how much was checked.

physical.verifyBundlefunctionno test imports it
function verifyBundle(contents: BundleContents, trust: Trust, at: string): Promise<BundleReport>

Verifies the whole bundle at the instant at with the trust the verifier gives; every fault is a finding, in the order of FINDING_KINDS and then of what it concerns. Pure: no file, network or clock.

// const report = await verifyBundle(contents, { policy, signer, keys }, "2026-06-01T00:00:00Z"); // report.findings
physical.bundleOkfunctionno test imports it
function bundleOk(report: BundleReport): boolean

Whether a report has no finding.

// bundleOk(report); // true where there is no finding
physical.signedBytesfunctionno test imports it
function signedBytes(manifest: Document & { readonly items: readonly ObjectOf<{ digest: Decoder<string>; size: Decoder<number>; mediaType: Decoder<string>; }, Record<never, never>>[]; readonly ledgerHead: string; } & {}): Uint8Array<ArrayBufferLike>

The canonical bytes the signature of a manifest covers (the same function the signer of a bundle uses).

// signedBytes(manifest); // the canonical bytes a signature covers
BundleFiletypeno test imports it
type BundleFile = "manifest.json" | "ledger.json" | "evidence.json" | "signature.json";

The files of a bundle that hold a document.

MANIFEST_PAYLOAD_TYPEconst
const MANIFEST_PAYLOAD_TYPE: "application/vnd.grc.evidence-manifest+json"

The payload type of the signature of a manifest.

MANIFEST_PAYLOAD_TYPE; // "application/vnd.grc.evidence-manifest+json"

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

BundleContentstype
type BundleContents = {
  readonly manifest: string | undefined;
  readonly ledger: string | undefined;
  readonly evidence: string | undefined;
  readonly signature: string | undefined;
  readonly items: ReadonlyMap<string, Uint8Array>;
};

What a bundle holds, read: the text of its documents (absent where the file is) and the bytes of its items by digest.

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

TrustedKeytypeno test imports it
type TrustedKey = { readonly keyid: string; readonly role: string; readonly key: unknown };

A key the verifier trusts, the role it may attest in, and the key as its signer takes it.

Trusttype
type Trust = { readonly policy: EvidencePolicy; readonly signer: Signer; readonly keys: readonly TrustedKey[] };

What the verifier gives: the evidence policy, the signer and the keys it trusts.

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

BundleFindingtype
type BundleFinding = | { readonly kind: "item-missing"; readonly digest: string } | { readonly kind: "item-hash-mism… (1175 characters)
type BundleFinding =
  | { readonly kind: "item-missing"; readonly digest: string }
  | { readonly kind: "item-hash-mismatch"; readonly digest: string; readonly actual: string }
  | { readonly kind: "item-size-mismatch"; readonly digest: string; readonly expected: number; readonly actual: number }
  | { readonly kind: "item-extra"; readonly digest: string }
  | { readonly kind: "chain-broken"; readonly seq: number; readonly reason: string }
  | { readonly kind: "not-canonical"; readonly file: BundleFile }
  | { readonly kind: "signature-absent" }
  | { readonly kind: "signature-bad"; readonly keyid: string | undefined; readonly reason: string }
  | { readonly kind: "signer-unallowed"; readonly keyid: string | undefined; readonly why: "unknown-key" | "role" | "custody"; readonly detail: string }
  | { readonly kind: "evidence-expired"; readonly digest: string }
  | { readonly kind: "kind-unknown"; readonly file: BundleFile; readonly found: string }
  | { readonly kind: "schema-unknown"; readonly file: BundleFile; readonly found: string; readonly expected: string }
  | { readonly kind: "document-invalid"; readonly file: BundleFile; readonly message: string };

Every fault of a bundle, each with what it concerns.

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

FindingKindtypeno test imports it
type FindingKind = BundleFinding["kind"];

The kind of a finding.

FINDING_KINDSconst
const FINDING_KINDS: readonly ["document-invalid", "kind-unknown", "schema-unknown", "not-canonical", "item-missing", "item-hash-mismatch", "item-size-mismatch", "item-extra", "chain-broken", "evidence-expired", "signature-absent", "signature-bad", "signer-unallowed"]

Every kind of finding, in the order a report gives them.

FINDING_KINDS.includes("item-missing"); // true

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

codeOfFindingfunction
function codeOfFinding(f: BundleFinding): string

The stable problem code of a finding: E-BUNDLE- and its kind in upper case.

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

codeOfKindfunctionno test imports it
function codeOfKind(kind: "chain-broken" | "document-invalid" | "evidence-expired" | "item-extra" | "item-hash-mismatch" | "item-missing" | "item-size-mismatch" | "kind-unknown" | "not-canonical" | "schema-unknown" | "signature-absent" | "signature-bad" | "signer-unallowed"): string

The stable problem code of a kind of finding.

codeOfKind("chain-broken"); // "E-BUNDLE-CHAIN-BROKEN"
concernOffunction
function concernOf(f: BundleFinding): string

What a finding concerns, as one short name: an item, an entry, a signature, or a file.

concernOf({ kind: "chain-broken", seq: 3, reason: "entry 3 was changed" }); // "entry 3"

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

describeFindingfunction
function describeFinding(f: BundleFinding): string

One sentence for a finding.

describeFinding({ kind: "signature-absent" }); // "the bundle has no signature"

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

BundleReporttypeno test imports it
type BundleReport = { readonly at: string; readonly items: number; readonly entries: number; readonly findings: readonly BundleFinding[] };

What verification gave: the instant, the findings in the order of FINDING_KINDS, and how much was checked.

verifyBundlefunction
function verifyBundle(contents: BundleContents, trust: Trust, at: string): Promise<BundleReport>

Verifies the whole bundle at the instant at with the trust the verifier gives; every fault is a finding, in the order of FINDING_KINDS and then of what it concerns. Pure: no file, network or clock.

// const report = await verifyBundle(contents, { policy, signer, keys }, "2026-06-01T00:00:00Z"); // report.findings

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

bundleOkfunction
function bundleOk(report: BundleReport): boolean

Whether a report has no finding.

// bundleOk(report); // true where there is no finding

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

signedBytesfunctionno test imports it
function signedBytes(manifest: Document & { readonly items: readonly ObjectOf<{ digest: Decoder<string>; size: Decoder<number>; mediaType: Decoder<string>; }, Record<never, never>>[]; readonly ledgerHead: string; } & {}): Uint8Array<ArrayBufferLike>

The canonical bytes the signature of a manifest covers (the same function the signer of a bundle uses).

// signedBytes(manifest); // the canonical bytes a signature covers

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