git.stella-ops.org/src/__Libraries/StellaOps.Canonical.Json

StellaOps.Canonical.Json

Canonical JSON serialization with deterministic hashing for StellaOps proofs.

Overview

This library provides canonical JSON serialization that produces bit-identical output across different environments, enabling deterministic replay and cryptographic verification of score proofs.

Key Features

• Deterministic Output: Object keys are recursively sorted using Ordinal comparison
• No Whitespace: Compact output with no formatting variations
• Consistent Hashing: SHA-256 hashes are always lowercase hex
• Cross-Platform: Same output across Windows, Linux, containers

Usage

Basic Canonicalization

using StellaOps.Canonical.Json;

var obj = new { z = 3, a = 1, nested = new { b = 2, x = 1 } };

// Get canonical bytes
byte[] canonical = CanonJson.Canonicalize(obj);
// Result: {"a":1,"nested":{"b":2,"x":1},"z":3}

// Compute hash
string hash = CanonJson.Sha256Hex(canonical);
// Result: lowercase 64-char hex string

One-Step Hash

// Hash object directly
string hash = CanonJson.Hash(obj);

// With sha256: prefix
string prefixed = CanonJson.HashPrefixed(obj);
// Result: "sha256:a1b2c3..."

Canonicalizing Existing JSON

// Re-sort keys in existing JSON
byte[] rawJson = Encoding.UTF8.GetBytes(@"{""z"":1,""a"":2}");
byte[] canonical = CanonJson.CanonicalizeParsedJson(rawJson);
// Result: {"a":2,"z":1}

Custom Serialization Options

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower
};

byte[] canonical = CanonJson.Canonicalize(obj, options);

API Reference

Method	Description
Canonicalize<T>(obj)	Serialize and canonicalize an object
Canonicalize<T>(obj, options)	Serialize with custom options and canonicalize
CanonicalizeParsedJson(bytes)	Canonicalize existing JSON bytes
Sha256Hex(bytes)	Compute SHA-256, return lowercase hex
Sha256Prefixed(bytes)	Compute SHA-256 with "sha256:" prefix
Hash<T>(obj)	Canonicalize and hash in one step
HashPrefixed<T>(obj)	Canonicalize and hash with prefix

Guarantees

1. Key Ordering: Object keys are always sorted alphabetically (Ordinal)
2. No Environment Dependencies: No timestamps, random values, or environment variables
3. UTF-8 Without BOM: Output is always UTF-8 encoded without byte order mark
4. Array Order Preserved: Arrays maintain element order (only object keys are sorted)

Use Cases

• Scan Manifests: Hash all inputs affecting scan results
• DSSE Payloads: Sign canonical JSON for attestations
• Proof Replay: Verify scores are deterministic
• Content Addressing: Store proofs by their hash

Related Components

• StellaOps.Scanner.Core.Models.ScanManifest - Uses CanonJson for manifest hashing
• StellaOps.Attestor - Signs canonical JSON payloads
• StellaOps.Evidence.Bundle - Content-addressed proof storage