Documentation
¶
Overview ¶
Package canonicalize provides RFC 8785 (JSON Canonicalization Scheme) compliant serialization for deterministic hashing of HELM artifacts. quantum_posture: canonical bytes bind hashes and signatures; this encoder does not itself choose a classical, hybrid, or post-quantum signing profile.
Index ¶
- Constants
- Variables
- func CanonicalHash(v interface{}) (string, error)
- func Canonicalize(schemaID string, raw interface{}) (*interfaces.Artifact, error)
- func CheckInteroperableNumbers(v interface{}) error
- func ComputeArtifactHash(data []byte) string
- func HashBytes(data []byte) string
- func InteroperableJCS(v interface{}) ([]byte, error)
- func JCS(v interface{}) ([]byte, error)
- func JCSString(v interface{}) (string, error)
Constants ¶
const MaxSafeInteger = 9007199254740991
MaxSafeInteger is 2^53-1, the largest integer an IEEE 754 double represents exactly. RFC 8785 Appendix B recommends confining true integers to ±MaxSafeInteger for maximum compliance with the ECMAScript JSON object.
Variables ¶
var ErrNonInteroperableNumber = errors.New("canonicalize: number outside the interoperable subset")
ErrNonInteroperableNumber is returned by CheckInteroperableNumbers for a value whose JSON number literal is not guaranteed to be byte-identical between HELM canonical JSON and a strict RFC 8785 implementation.
Functions ¶
func CanonicalHash ¶
CanonicalHash returns the SHA-256 hex digest of the canonical JSON representation of v.
func Canonicalize ¶
func Canonicalize(schemaID string, raw interface{}) (*interfaces.Artifact, error)
Canonicalize converts a raw value into a canonical Artifact. It detects the content type and applies the appropriate canonicalization logic.
func CheckInteroperableNumbers ¶
func CheckInteroperableNumbers(v interface{}) error
CheckInteroperableNumbers reports whether every number reachable from v is inside the subset on which HELM canonical JSON and RFC 8785 produce identical bytes: an integer in [-MaxSafeInteger, MaxSafeInteger] written without a sign on zero, without leading zeros, without a fraction and without an exponent.
Numbers outside that subset are not rejected by JCS — JCS preserves the literal — so this is the gate every signed artifact and every published test vector MUST pass before its bytes are frozen. Without it, "1e2", "1.0", "-0" and 9007199254740993 canonicalize to literals a conformant RFC 8785 implementation will not reproduce.
The returned error names the JSON path of the first offending value.
func ComputeArtifactHash ¶
ComputeArtifactHash returns the SHA-256 multihash of the canonical bytes.
func InteroperableJCS ¶
InteroperableJCS is JCS gated on CheckInteroperableNumbers. Use it to mint canonical bytes that a third-party RFC 8785 implementation reproduces.
func JCS ¶
JCS returns the RFC 8785 canonical JSON representation of v.
Conformance and the one deviation, stated precisely (see protocols/specs/rfc/canonical-json-v1.md):
- Object keys are sorted by UTF-16 code unit, per RFC 8785 Section 3.2.3.
- Strings use the RFC 8785 Section 3.2.2.2 escape set: only U+0000..U+001F, '"' and '\' are escaped. HTML escaping is DISABLED; U+2028/U+2029 and U+007F are emitted as literal UTF-8.
- DEVIATION from RFC 8785 Section 3.2.2.3: numbers are emitted as the JSON literal produced by encoding/json for v (or, for a value decoded with json.Number, the literal from the source document) rather than by the ECMAScript Number-to-String algorithm. Over the interoperable subset enforced by CheckInteroperableNumbers the two agree byte for byte; outside it they do not. Signed HELM artifacts are confined to that subset.
JCS is lossy on invalid UTF-8: the encoding/json pre-marshal replaces ill-formed byte sequences with U+FFFD before this function sees them, so invalid input canonicalizes rather than failing. Callers that must reject ill-formed input have to validate before calling.
Types ¶
This section is empty.
Source Files