physical.BundleFiletypeno test imports ittype BundleFile = "manifest.json" | "ledger.json" | "evidence.json" | "signature.json";The files of a bundle that hold a document.
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"physical.BundleFiletypeno test imports ittype BundleFile = "manifest.json" | "ledger.json" | "evidence.json" | "signature.json";The files of a bundle that hold a document.
physical.MANIFEST_PAYLOAD_TYPEconstno test imports itconst 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 ittype 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 ittype 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 ittype 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 ittype 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 ittype FindingKind = BundleFinding["kind"];The kind of a finding.
physical.FINDING_KINDSconstno test imports itconst 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"); // truephysical.codeOfFindingfunctionno test imports itfunction codeOfFinding(f: BundleFinding): stringThe stable problem code of a finding: E-BUNDLE- and its kind in upper case.
physical.codeOfKindfunctionno test imports itfunction 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"): stringThe stable problem code of a kind of finding.
codeOfKind("chain-broken"); // "E-BUNDLE-CHAIN-BROKEN"physical.concernOffunctionno test imports itfunction concernOf(f: BundleFinding): stringWhat 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 itfunction describeFinding(f: BundleFinding): stringOne sentence for a finding.
describeFinding({ kind: "signature-absent" }); // "the bundle has no signature"physical.BundleReporttypeno test imports ittype 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 itfunction 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.findingsphysical.bundleOkfunctionno test imports itfunction bundleOk(report: BundleReport): booleanWhether a report has no finding.
// bundleOk(report); // true where there is no findingphysical.signedBytesfunctionno test imports itfunction 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 coversBundleFiletypeno test imports ittype BundleFile = "manifest.json" | "ledger.json" | "evidence.json" | "signature.json";The files of a bundle that hold a document.
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"BundleContentstypetype 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.
TrustedKeytypeno test imports ittype 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.
Trusttypetype 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.
BundleFindingtypetype 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.
FindingKindtypeno test imports ittype FindingKind = BundleFinding["kind"];The kind of a finding.
FINDING_KINDSconstconst 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"); // truecodeOfFindingfunctionfunction codeOfFinding(f: BundleFinding): stringThe stable problem code of a finding: E-BUNDLE- and its kind in upper case.
codeOfKindfunctionno test imports itfunction 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"): stringThe stable problem code of a kind of finding.
codeOfKind("chain-broken"); // "E-BUNDLE-CHAIN-BROKEN"concernOffunctionfunction concernOf(f: BundleFinding): stringWhat 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"describeFindingfunctionfunction describeFinding(f: BundleFinding): stringOne sentence for a finding.
describeFinding({ kind: "signature-absent" }); // "the bundle has no signature"BundleReporttypeno test imports ittype 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.
verifyBundlefunctionfunction 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.findingsbundleOkfunctionfunction bundleOk(report: BundleReport): booleanWhether a report has no finding.
// bundleOk(report); // true where there is no findingsignedBytesfunctionno test imports itfunction 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