Documentation
¶
Overview ¶
Package merkle implements the Merkle tree Readproof commits manifests with.
It exists so that exactly one implementation of the leaf/root rule is shipped: internal/evidence puts the root in a bundle's in-toto subject digest, and internal/run puts the same value on the readproof.run.commit span (readproof.manifest.merkle_root). Those two must agree byte for byte or the trace stops being a usable handle on the evidence, so neither package keeps its own copy of the algorithm.
The fixed vectors in internal/evidence/merkle_test.go are the contract: this package's output must never change for a given input.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Leaf ¶
Leaf returns the hex-encoded Merkle leaf for one manifest entry:
sha256(position_be_uint32 || 0x00 || uri || 0x00 || content_hash)
The position is length-prefixed as a fixed-width big-endian uint32 and the string fields are 0x00-separated so that no two distinct entries can serialize to the same byte string (a URI containing the separator would otherwise be able to impersonate a different position/hash pair). contentHash is hashed as the recorded string, "sha256:<hex>" prefix included, so the leaf commits to the exact value stored in the manifest.
Only position, uri and content_hash feed the leaf: descriptive metadata (snapshot id, ref, content type, provenance) must never move the root, or two exports of the same manifest would disagree.
func Root ¶
Root computes the hex-encoded root of a standard binary Merkle tree over the given hex-encoded leaves, in the order supplied (manifest entries are already in position order — order is a hard Readproof invariant, so it must be committed to, not sorted away).
Rules, fixed and mirrored by the TypeScript exporter:
- zero leaves -> sha256 of the empty input
- exactly one leaf -> the root is that leaf
- odd level -> the last node is duplicated and paired with itself (the Bitcoin rule), then parent = sha256(left || right)
The duplicate-last rule is known to admit CVE-2012-2459-style collisions between differently shaped trees; that is acceptable here because the evidence bundle also carries the full entry list, so a verifier recomputes the root from a known entry count rather than trusting the root alone.
Types ¶
This section is empty.
Source Files