IF Commons GitHub

GRC evidence bundles

0011Active

0011-grc-bundles · owner if · domain grc

The bundle

FR-001checkpassing

A bundle MUST be a folder of manifest.json (a grc.evidence-manifest), ledger.json (an array of grc.ledger-entry), evidence.json (an array of grc.evidence), signature.json (a DSSE envelope over the canonical manifest, of payload type application/vnd.grc.evidence-manifest+json) and items/<digest>, the bytes of each item; the trust (the signing keys and their roles) and the evidence policy MUST NOT be read from the bundle but given by the verifier.

Enforced (check): .github: cd commons/grc && bun run verify — suite/bundles.test.ts

Proved by: grc/suite/bundles.test.ts

Written in: grc/src/physical/bundle.ts

Tests: passed: suite/bundles.test.ts a bundle is a folder of its documents and items; the trust is the verifier's and never rea

FR-002checkpassing

verifyBundle(input, trust, at) MUST be a pure core over the contents (text and bytes) of a bundle, with no file, network or clock, giving a report of findings in a fixed order; the file adapter readBundle MUST only read a folder into those contents.

Enforced (check): .github: cd commons/grc && bun run verify — suite/bundles.test.ts

Proved by: grc/suite/bundles.test.ts

Written in: grc/src/physical/bundle-files.ts, grc/src/physical/bundle.ts

Tests: passed: suite/bundles.test.ts the core is pure over contents: the same contents and trust give the same report, and noth

Cited by: GRC, physical/bundle-files

The findings

FR-003checkpassing

A finding MUST be of the closed union item-missing, item-hash-mismatch, item-size-mismatch, item-extra, chain-broken, not-canonical, signature-absent, signature-bad, signer-unallowed, evidence-expired, kind-unknown, schema-unknown and document-invalid, and each MUST name what it concerns: an item by digest, a ledger entry by sequence number, a signature by key id, or a file of the bundle.

Enforced (check): .github: cd commons/grc && bun run verify — suite/bundles.test.ts

Proved by: grc/suite/bundles.test.ts

Written in: grc/src/physical/bundle.ts

Tests: passed: suite/bundles.test.ts every finding is of the closed union and names what it concerns, with one sentence and a s

FR-004checkpassing

Each item of the manifest MUST be found missing where items/<digest> is absent, a hash mismatch where the SHA-256 of its bytes is not its digest, a size mismatch where its length is not its size, and each item the folder holds that the manifest does not list MUST be extra.

Enforced (check): .github: cd commons/grc && bun run verify — suite/bundles.test.ts

Proved by: grc/suite/bundles.test.ts

Written in: grc/src/physical/bundle.ts

Tests: passed: suite/bundles.test.ts an item is missing, has the wrong hash or size, or is extra

FR-005checkpassing

The ledger MUST be verified with verifyLedger against the head the manifest names, and a fault MUST be chain-broken naming the first entry at fault.

Enforced (check): .github: cd commons/grc && bun run verify — suite/bundles.test.ts

Proved by: grc/suite/bundles.test.ts

Written in: grc/src/physical/bundle.ts

Tests: passed: suite/bundles.test.ts the ledger is verified against the head the manifest names and the first entry at fault is

FR-006checkpassing

The manifest, the ledger and the evidence list MUST be in their canonical form (RFC 8785, with no white space), and a file that is not MUST be not-canonical.

Enforced (check): .github: cd commons/grc && bun run verify — suite/bundles.test.ts

Proved by: grc/suite/bundles.test.ts

Written in: grc/src/physical/bundle.ts

Tests: passed: suite/bundles.test.ts a manifest, ledger or evidence list that is not in canonical form is found

FR-007checkpassing

The signature MUST verify with the signer and the keys the verifier gives, over the canonical bytes of the manifest; an absent envelope MUST be signature-absent, a signature that does not verify (or a payload that is not the manifest) signature-bad, and a signature by a key the verifier does not trust, by a role the evidence policy does not allow to attest, or with a signer whose custody is weaker than the policy's MUST be signer-unallowed; a bundle MUST hold at least one signature, and every signature it holds MUST be valid and allowed.

Enforced (check): .github: cd commons/grc && bun run verify — suite/bundles.test.ts

Proved by: grc/suite/bundles.test.ts

Written in: grc/src/physical/bundle.ts

Tests: passed: suite/bundles.test.ts the signature verifies over the canonical manifest with the verifier's keys, and an absent

FR-008checkpassing

An item of evidence whose retention has passed at the instant MUST be evidence-expired, by retained.

Enforced (check): .github: cd commons/grc && bun run verify — suite/bundles.test.ts

Proved by: grc/suite/bundles.test.ts

Written in: grc/src/physical/bundle.ts

Tests: passed: suite/bundles.test.ts evidence past its retention at the instant is found

FR-009checkpassing

A file that is not valid JSON, is absent or does not decode MUST be document-invalid, a document of a kind no reader knows MUST be kind-unknown, and a document of a schema this release does not read MUST be schema-unknown, each naming the file.

Enforced (check): .github: cd commons/grc && bun run verify — suite/bundles.test.ts

Proved by: grc/suite/bundles.test.ts

Written in: grc/src/physical/bundle.ts

Tests: passed: suite/bundles.test.ts a file that is absent, not JSON or does not decode is invalid; a kind or a schema no reade

The verb

FR-010checkpassing

The verb MUST be grc bundle verify <folder> --keys <file> --policy <file> [--at <instant>], a read-only report with the reach of the existing reports; grc evidence verify MUST stay the verification of the objects of the store, because a bundle is a set of files and not a store.

Enforced (check): .github: cd commons/grc && bun run verify — suite/bundles.test.ts

Proved by: grc/suite/bundles.test.ts

Written in: grc/src/physical/bundle-files.ts

Tests: passed: suite/bundles.test.ts the verb is grc bundle verify, a read-only report with a reach, and grc evidence verify st

FR-011checkpassing

The exit MUST be ok (0) where there is no finding, findings (1) where there is any, usage (2) for a wrong command line (no folder, an instant that is not one), and environment (3) for a folder, keys file or policy file that cannot be read; each finding MUST carry the code E-BUNDLE- and its kind in upper case, which grc explain <code> MUST explain with what happened, the likely cause and the fix.

Enforced (check): .github: cd commons/grc && bun run verify — suite/bundles.test.ts

Proved by: grc/suite/bundles.test.ts

Tests: passed: suite/bundles.test.ts the exit is ok, findings, usage or environment, and each finding's code is explained

FR-012checkpassing

The verification MUST use no network and MUST write nothing.

Enforced (check): .github: cd commons/grc && bun run verify — suite/bundles.test.ts

Proved by: grc/suite/bundles.test.ts

Written in: grc/src/physical/bundle-files.ts, grc/src/physical/bundle.ts

Tests: passed: suite/bundles.test.ts verifying uses no network and writes nothing

Scenarios

  • Given an item whose bytes were edited, When the bundle is verified, Then an item-hash-mismatch names its digest and the exit is 1, per FR-004, FR-011.
  • Given a bundle with no signature.json, When it is verified, Then signature-absent, per FR-007.
  • Given a folder that does not exist, When it is verified, Then the exit is 3, per FR-011.

Out of scope

  • Making a bundle, and the archive that carries one; a transparency log.

Edge cases

  • A bundle of no items: valid where the ledger and signature are, per FR-004.

Assumptions

  • The verifier holds the keys it trusts: a bundle never vouches for its own signer.

Open questions

OQ-1open question

Whether a bundle may carry several manifests.

Key entities

  • Bundle, Finding, Trust.

Success criteria

SC-001success criterion

Every way a bundle can be wrong is a finding that names the item or entry.

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

Cited by

GRC, physical/bundle-files, physical/bundle, surfaces/headless/mod, bundle, GRC headless verbs, Kanon

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