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

using System.Security.Cryptography;
using System.Text.Json;

namespace StellaOps.Canonical.Json;

/// <summary>
/// Canonical JSON serialization with deterministic hashing.
/// Produces bit-identical output across environments for proof replay.
/// </summary>
/// <remarks>
/// Key guarantees:
/// <list type="bullet">
///   <item>Object keys are sorted alphabetically (Ordinal comparison)</item>
///   <item>No whitespace or formatting variations</item>
///   <item>Consistent number formatting</item>
///   <item>UTF-8 encoding without BOM</item>
/// </list>
/// </remarks>
public static class CanonJson
{
    /// <summary>
    /// Canonicalizes an object to a deterministic byte array.
    /// Object keys are recursively sorted using Ordinal comparison.
    /// </summary>
    /// <typeparam name="T">The type to serialize.</typeparam>
    /// <param name="obj">The object to canonicalize.</param>
    /// <returns>UTF-8 encoded canonical JSON bytes.</returns>
    public static byte[] Canonicalize<T>(T obj)
    {
        var json = JsonSerializer.SerializeToUtf8Bytes(obj, new JsonSerializerOptions
        {
            WriteIndented = false,
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
        });

        using var doc = JsonDocument.Parse(json);
        using var ms = new MemoryStream();
        using var writer = new Utf8JsonWriter(ms, new JsonWriterOptions { Indented = false });

        WriteElementSorted(doc.RootElement, writer);
        writer.Flush();
        return ms.ToArray();
    }

    /// <summary>
    /// Canonicalizes an object using custom serializer options.
    /// Object keys are recursively sorted using Ordinal comparison.
    /// </summary>
    /// <typeparam name="T">The type to serialize.</typeparam>
    /// <param name="obj">The object to canonicalize.</param>
    /// <param name="options">JSON serializer options to use for initial serialization.</param>
    /// <returns>UTF-8 encoded canonical JSON bytes.</returns>
    public static byte[] Canonicalize<T>(T obj, JsonSerializerOptions options)
    {
        var json = JsonSerializer.SerializeToUtf8Bytes(obj, options);

        using var doc = JsonDocument.Parse(json);
        using var ms = new MemoryStream();
        using var writer = new Utf8JsonWriter(ms, new JsonWriterOptions { Indented = false });

        WriteElementSorted(doc.RootElement, writer);
        writer.Flush();
        return ms.ToArray();
    }

    /// <summary>
    /// Canonicalizes raw JSON bytes by parsing and re-sorting keys.
    /// Use this when you have existing JSON that needs to be canonicalized.
    /// </summary>
    /// <param name="jsonBytes">UTF-8 encoded JSON bytes.</param>
    /// <returns>UTF-8 encoded canonical JSON bytes.</returns>
    public static byte[] CanonicalizeParsedJson(ReadOnlySpan<byte> jsonBytes)
    {
        using var doc = JsonDocument.Parse(jsonBytes.ToArray());
        using var ms = new MemoryStream();
        using var writer = new Utf8JsonWriter(ms, new JsonWriterOptions { Indented = false });

        WriteElementSorted(doc.RootElement, writer);
        writer.Flush();
        return ms.ToArray();
    }

    private static void WriteElementSorted(JsonElement el, Utf8JsonWriter w)
    {
        switch (el.ValueKind)
        {
            case JsonValueKind.Object:
                w.WriteStartObject();
                foreach (var prop in el.EnumerateObject().OrderBy(p => p.Name, StringComparer.Ordinal))
                {
                    w.WritePropertyName(prop.Name);
                    WriteElementSorted(prop.Value, w);
                }
                w.WriteEndObject();
                break;

            case JsonValueKind.Array:
                w.WriteStartArray();
                foreach (var item in el.EnumerateArray())
                {
                    WriteElementSorted(item, w);
                }
                w.WriteEndArray();
                break;

            default:
                el.WriteTo(w);
                break;
        }
    }

    /// <summary>
    /// Computes SHA-256 hash of bytes, returns lowercase hex string.
    /// </summary>
    /// <param name="bytes">The bytes to hash.</param>
    /// <returns>64-character lowercase hex string.</returns>
    public static string Sha256Hex(ReadOnlySpan<byte> bytes)
        => Convert.ToHexString(SHA256.HashData(bytes)).ToLowerInvariant();

    /// <summary>
    /// Computes SHA-256 hash of bytes, returns prefixed hash string.
    /// </summary>
    /// <param name="bytes">The bytes to hash.</param>
    /// <returns>Hash string with "sha256:" prefix.</returns>
    public static string Sha256Prefixed(ReadOnlySpan<byte> bytes)
        => "sha256:" + Sha256Hex(bytes);

    /// <summary>
    /// Canonicalizes an object and computes its SHA-256 hash.
    /// </summary>
    /// <typeparam name="T">The type to serialize.</typeparam>
    /// <param name="obj">The object to hash.</param>
    /// <returns>64-character lowercase hex string.</returns>
    public static string Hash<T>(T obj)
    {
        var canonical = Canonicalize(obj);
        return Sha256Hex(canonical);
    }

    /// <summary>
    /// Canonicalizes an object and computes its prefixed SHA-256 hash.
    /// </summary>
    /// <typeparam name="T">The type to serialize.</typeparam>
    /// <param name="obj">The object to hash.</param>
    /// <returns>Hash string with "sha256:" prefix.</returns>
    public static string HashPrefixed<T>(T obj)
    {
        var canonical = Canonicalize(obj);
        return Sha256Prefixed(canonical);
    }
}