jouleclaw: sign the tree head, and give the transparency log a consumer #167

Merged

dcharlot merged 1 commit from feat/transparency-log into main 2026-10-06 17:28:15 -04:00

Conversation 0 Commits 1 Files changed 6 +582 -17

2026-10-05

Transaction Science

jouleclaw: sign the tree head, and give the transparency log a consumer ...

Two problems, and they were the same problem seen from either end.

The crate's own promise is that "any party can prove a receipt was included in
the log without trusting the log operator". An inclusion proof delivers that
only against a root the operator is bound to, and `TreeHead` — documented as a
"Signed Tree Head" — had no signature, no key, and no verification. An unsigned
root can be minted per-auditor, so two parties shown different roots had nothing
to compare and nobody to attribute it to. The promise was false as written.

And nothing consumed the crate. The RFC 6962 proofs merged in #153 were inert:
no JouleClaw or JCP decision could be given an inclusion proof, so the
auditor-grade tier existed as an unreferenced library.

**Signed tree head.** `TreeHead::sign` / `SignedTreeHead::verify` over
`0x02 || size || root || timestamp`, every field fixed-width so no two heads
share a preimage, and `0x02` a third domain separator so a head cannot be
presented as an entry in its own log. `verify` returns the *root* rather than
`()`, so a caller cannot check a proof against an unverified head by accident.
`root_hex` is a `String`, so it is now parsed rather than assumed: a head whose
root is not 32 bytes of hex is refused at signing time and again at verify time,
because a signature over an unparseable root is a signature over nothing
checkable. Tests cover each field being load-bearing, the wrong key, malformed
signature bytes, and — the property an unsigned root cannot have — two signed
heads at one size as attributable equivocation.

**A consumer.** `JcpGate` already accumulated its sealed receipts in a private
`Vec`, which is only as trustworthy as the party holding it. Each receipt is now
appended to a Merkle log on the same path, and the gate publishes
`signed_tree_head`, `inclusion_proof` and `consistency_proof`. An auditor with
only the steward's public key can check that a specific decision — allow or deny
— is in the stream the operator published. Stream and log are appended in one
place so an index into one is an index into the other.

**Fail closed.** On that path, `if let Ok(receipt) = seal_chained(..)` swallowed
a seal failure and then returned the verdict, so an *allow* could proceed with
no receipt and no log entry — the one outcome the log exists to make impossible.
A seal failure now refuses the dispatch. The debit has already landed, so the
caller is charged for a call it does not get; that is the safe direction,
because the opposite is an unrecorded side effect.

**What this does not prove**, stated in the module docs and the spec rather than
left to be inferred: not completeness. An operator that never records a decision
logs nothing, and no proof about the entries that exist can speak for one never
written. What narrows the gap is where the append happens — before the verdict
returns, so a caller that observed a refusal can demand the entry that refused
it.

SPEC gains §22 (Transparency log, OPTIONAL): the tree, the signing preimage
byte-for-byte, the MUSTs on signing and on refusing an unparseable root, the
proven/not-proven split in plain terms, and conformance class C-TLOG. References
moves to §23; nothing cross-referenced it.

Co-Authored-By: Claude Opus 5 <[email protected]>

3b1b3ff235

• View at this point in history

2026-10-05 21:48:36 -04:00