evalhub_core/canonical.rs
1//! RFC 8785 canonical JSON and the content hash.
2//!
3//! The hub needs one answer to "are these two records the same?" that does
4//! not depend on how the client serialised them. RFC 8785 (JSON
5//! Canonicalization Scheme) gives it: object keys sorted by UTF-16 code
6//! units, no insignificant whitespace, numbers printed the way ECMAScript
7//! prints them (`1` not `1.0`, `1e21` not `1000000000000000000000`), strings
8//! escaped minimally. Two records that differ only in key order or
9//! formatting produce identical bytes.
10//!
11//! `content_hash = sha256(canonical_bytes)`, hex-encoded. It is stored on
12//! every version and used for two things only:
13//!
14//! - **Idempotency.** A `POST` whose hash equals the latest version's hash
15//! returns that version with `200` instead of creating a duplicate.
16//! - **Integrity.** `GET` responses carry the hash so a client can verify
17//! the body it received is the body that was stored.
18//!
19//! It is deliberately *not* an address. Versions are addressed by `@{seq}`
20//! or `@{label}`; a hash-addressed API would let two names share a version
21//! and make tombstoning ambiguous.
22//!
23//! # Numbers
24//!
25//! Canonicalisation requires parsing every number as an IEEE 754 double.
26//! An integer outside ±2^53 would lose precision silently, so validation
27//! rejects it first (`number_too_large`) and the producer sends it as a
28//! string. Non-finite values cannot appear in JSON and are not a case.
29//!
30//! # Why `serde_json_canonicalizer`
31//!
32//! It implements RFC 8785 including the ECMAScript number formatting (via
33//! `ryu-js`), which the simpler "sort keys and strip whitespace" crates do
34//! not. Canonical form is a contract with every client that computes the
35//! hash locally, so the number formatting has to be exactly the RFC's.
36//!
37//! # Tests
38//!
39//! Fixtures in `fixtures/canonical/` pair an input JSON with its expected
40//! canonical bytes and hash, including the RFC's own test vectors. A
41//! property test asserts that canonicalising a value, re-parsing it, and
42//! canonicalising again is a fixed point.
43
44use std::fmt;
45use std::str::FromStr;
46
47use serde_json::Value;
48use sha2::{Digest, Sha256};
49
50/// Failure to produce canonical bytes.
51///
52/// The only way RFC 8785 serialisation of a `serde_json::Value` fails is
53/// through the underlying serialiser (a map with a non-string key cannot
54/// occur in a `Value`, so in practice this is unreachable for values parsed
55/// from JSON text). It is surfaced rather than unwrapped because the hash of
56/// a partially written buffer must never be stored.
57#[derive(Debug, thiserror::Error)]
58pub enum CanonicalError {
59 /// The serialiser refused the value.
60 #[error("canonical serialisation failed: {0}")]
61 Serialize(#[source] serde_json::Error),
62}
63
64/// The sha256 of a record's canonical bytes.
65///
66/// Thirty-two bytes, shown as sixty-four lower-case hex characters. Used
67/// for idempotency and integrity only; never as an address (see the module
68/// doc).
69#[derive(Clone, Copy, PartialEq, Eq, Hash)]
70pub struct ContentHash([u8; 32]);
71
72impl ContentHash {
73 /// The raw digest, for the `bytea` column.
74 pub fn as_bytes(&self) -> &[u8; 32] {
75 &self.0
76 }
77
78 /// Lower-case hex, sixty-four characters, as carried in API responses.
79 pub fn as_hex(&self) -> String {
80 hex::encode(self.0)
81 }
82
83 /// Wrap a digest already computed (for example, read back from the
84 /// database). No validation beyond the length the type enforces.
85 pub fn from_bytes(bytes: [u8; 32]) -> Self {
86 Self(bytes)
87 }
88}
89
90impl fmt::Display for ContentHash {
91 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
92 f.write_str(&self.as_hex())
93 }
94}
95
96impl fmt::Debug for ContentHash {
97 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
98 write!(f, "ContentHash({})", self.as_hex())
99 }
100}
101
102/// A hex string that is not a sha256 digest.
103#[derive(Debug, thiserror::Error)]
104#[error("not a sha256 hex digest: {0}")]
105pub struct ParseContentHashError(String);
106
107impl FromStr for ContentHash {
108 type Err = ParseContentHashError;
109
110 /// Parses sixty-four hex characters, either case.
111 fn from_str(s: &str) -> Result<Self, Self::Err> {
112 let bytes = hex::decode(s).map_err(|e| ParseContentHashError(e.to_string()))?;
113 let arr: [u8; 32] = bytes.try_into().map_err(|_| {
114 ParseContentHashError(format!("expected 32 bytes, got {}", s.len() / 2))
115 })?;
116 Ok(Self(arr))
117 }
118}
119
120/// Serialise `value` as RFC 8785 canonical JSON.
121///
122/// Deterministic: the same value in any key order yields the same bytes.
123/// Cost is one pass over the value plus a sort of each object's keys.
124/// Numbers are printed as ECMAScript prints them (`1` not `1.0`); the
125/// caller is responsible for having rejected integers outside ±2^53
126/// beforehand (`validate`, M2), because past that point the double they
127/// become is not the integer the client sent.
128///
129/// # Errors
130///
131/// [`CanonicalError::Serialize`] if the serialiser fails; not expected for
132/// a `Value` built from JSON text.
133pub fn canonicalize(value: &Value) -> Result<Vec<u8>, CanonicalError> {
134 serde_json_canonicalizer::to_vec(value).map_err(CanonicalError::Serialize)
135}
136
137/// sha256 over canonical bytes. Infallible; O(n) in the input.
138pub fn content_hash(canonical: &[u8]) -> ContentHash {
139 let digest = Sha256::digest(canonical);
140 ContentHash(digest.into())
141}
142
143/// [`canonicalize`] then [`content_hash`], returning both, since every
144/// caller that wants the hash also stores the bytes.
145///
146/// # Errors
147///
148/// Same as [`canonicalize`].
149pub fn hash_value(value: &Value) -> Result<(Vec<u8>, ContentHash), CanonicalError> {
150 let bytes = canonicalize(value)?;
151 let hash = content_hash(&bytes);
152 Ok((bytes, hash))
153}