331 lines
12 KiB
C#
331 lines
12 KiB
C#
using System.Security.Cryptography;
|
|
using System.Text;
|
|
using System.Text.Encodings.Web;
|
|
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
|
|
{
|
|
private static readonly JsonSerializerOptions DefaultSerializerOptions = new()
|
|
{
|
|
WriteIndented = false,
|
|
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
|
|
Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
|
|
};
|
|
|
|
private static readonly JsonWriterOptions DefaultWriterOptions = new()
|
|
{
|
|
Indented = false,
|
|
Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
|
|
};
|
|
|
|
/// <summary>
|
|
/// Serializes an object to a canonical JSON string.
|
|
/// Object keys are recursively sorted using Ordinal comparison.
|
|
/// </summary>
|
|
/// <typeparam name="T">The type to serialize.</typeparam>
|
|
/// <param name="obj">The object to serialize.</param>
|
|
/// <returns>Canonical JSON string.</returns>
|
|
public static string Serialize<T>(T obj)
|
|
{
|
|
var bytes = Canonicalize(obj);
|
|
return Encoding.UTF8.GetString(bytes);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Serializes an object to a canonical JSON string 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 serialize.</param>
|
|
/// <param name="options">JSON serializer options to use for initial serialization.</param>
|
|
/// <returns>Canonical JSON string.</returns>
|
|
public static string Serialize<T>(T obj, JsonSerializerOptions options)
|
|
{
|
|
var bytes = Canonicalize(obj, options);
|
|
return Encoding.UTF8.GetString(bytes);
|
|
}
|
|
|
|
/// <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, DefaultSerializerOptions);
|
|
|
|
using var doc = JsonDocument.Parse(json);
|
|
using var ms = new MemoryStream();
|
|
using var writer = new Utf8JsonWriter(ms, DefaultWriterOptions);
|
|
|
|
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, CreateWriterOptions(options));
|
|
|
|
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)
|
|
{
|
|
var reader = new Utf8JsonReader(jsonBytes, isFinalBlock: true, state: default);
|
|
using var doc = JsonDocument.ParseValue(ref reader);
|
|
using var ms = new MemoryStream();
|
|
using var writer = new Utf8JsonWriter(ms, DefaultWriterOptions);
|
|
|
|
WriteElementSorted(doc.RootElement, writer);
|
|
writer.Flush();
|
|
return ms.ToArray();
|
|
}
|
|
|
|
/// <summary>
|
|
/// Canonicalizes raw JSON bytes using a custom encoder for output.
|
|
/// </summary>
|
|
/// <param name="jsonBytes">UTF-8 encoded JSON bytes.</param>
|
|
/// <param name="encoder">Encoder to use for output escaping.</param>
|
|
/// <returns>UTF-8 encoded canonical JSON bytes.</returns>
|
|
public static byte[] CanonicalizeParsedJson(ReadOnlySpan<byte> jsonBytes, JavaScriptEncoder encoder)
|
|
{
|
|
ArgumentNullException.ThrowIfNull(encoder);
|
|
|
|
var reader = new Utf8JsonReader(jsonBytes, isFinalBlock: true, state: default);
|
|
using var doc = JsonDocument.ParseValue(ref reader);
|
|
using var ms = new MemoryStream();
|
|
using var writer = new Utf8JsonWriter(ms, new JsonWriterOptions
|
|
{
|
|
Indented = false,
|
|
Encoder = encoder
|
|
});
|
|
|
|
WriteElementSorted(doc.RootElement, writer);
|
|
writer.Flush();
|
|
return ms.ToArray();
|
|
}
|
|
|
|
private static JsonWriterOptions CreateWriterOptions(JsonSerializerOptions? options)
|
|
{
|
|
var encoder = options?.Encoder ?? DefaultWriterOptions.Encoder;
|
|
return new JsonWriterOptions
|
|
{
|
|
Indented = false,
|
|
Encoder = encoder
|
|
};
|
|
}
|
|
|
|
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);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Canonicalizes an object with version marker for content-addressed hashing.
|
|
/// The version marker is embedded as the first field in the canonical JSON,
|
|
/// ensuring stable hashes even if canonicalization logic evolves.
|
|
/// </summary>
|
|
/// <typeparam name="T">The type to serialize.</typeparam>
|
|
/// <param name="obj">The object to canonicalize.</param>
|
|
/// <param name="version">Canonicalization version (default: Current).</param>
|
|
/// <returns>UTF-8 encoded canonical JSON bytes with version marker.</returns>
|
|
public static byte[] CanonicalizeVersioned<T>(T obj, string version = CanonVersion.Current)
|
|
{
|
|
ArgumentException.ThrowIfNullOrWhiteSpace(version);
|
|
|
|
var json = JsonSerializer.SerializeToUtf8Bytes(obj, DefaultSerializerOptions);
|
|
|
|
using var doc = JsonDocument.Parse(json);
|
|
using var ms = new MemoryStream();
|
|
using var writer = new Utf8JsonWriter(ms, DefaultWriterOptions);
|
|
|
|
WriteElementVersioned(doc.RootElement, writer, version);
|
|
writer.Flush();
|
|
return ms.ToArray();
|
|
}
|
|
|
|
/// <summary>
|
|
/// Canonicalizes an object with version marker using custom serializer options.
|
|
/// </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>
|
|
/// <param name="version">Canonicalization version (default: Current).</param>
|
|
/// <returns>UTF-8 encoded canonical JSON bytes with version marker.</returns>
|
|
public static byte[] CanonicalizeVersioned<T>(T obj, JsonSerializerOptions options, string version = CanonVersion.Current)
|
|
{
|
|
ArgumentException.ThrowIfNullOrWhiteSpace(version);
|
|
|
|
var json = JsonSerializer.SerializeToUtf8Bytes(obj, options);
|
|
|
|
using var doc = JsonDocument.Parse(json);
|
|
using var ms = new MemoryStream();
|
|
using var writer = new Utf8JsonWriter(ms, CreateWriterOptions(options));
|
|
|
|
WriteElementVersioned(doc.RootElement, writer, version);
|
|
writer.Flush();
|
|
return ms.ToArray();
|
|
}
|
|
|
|
private static void WriteElementVersioned(JsonElement el, Utf8JsonWriter w, string version)
|
|
{
|
|
if (el.ValueKind == JsonValueKind.Object)
|
|
{
|
|
w.WriteStartObject();
|
|
|
|
// Write version marker first (underscore prefix ensures lexicographic first position)
|
|
w.WriteString(CanonVersion.VersionFieldName, version);
|
|
|
|
// Write remaining properties sorted
|
|
foreach (var prop in el.EnumerateObject().OrderBy(p => p.Name, StringComparer.Ordinal))
|
|
{
|
|
if (string.Equals(prop.Name, CanonVersion.VersionFieldName, StringComparison.Ordinal))
|
|
{
|
|
continue;
|
|
}
|
|
|
|
w.WritePropertyName(prop.Name);
|
|
WriteElementSorted(prop.Value, w);
|
|
}
|
|
w.WriteEndObject();
|
|
}
|
|
else
|
|
{
|
|
// Non-object root: wrap in object with version marker
|
|
w.WriteStartObject();
|
|
w.WriteString(CanonVersion.VersionFieldName, version);
|
|
w.WritePropertyName("_value");
|
|
WriteElementSorted(el, w);
|
|
w.WriteEndObject();
|
|
}
|
|
}
|
|
|
|
/// <summary>
|
|
/// Computes SHA-256 hash of versioned canonical representation.
|
|
/// </summary>
|
|
/// <typeparam name="T">The type to serialize.</typeparam>
|
|
/// <param name="obj">The object to hash.</param>
|
|
/// <param name="version">Canonicalization version (default: Current).</param>
|
|
/// <returns>64-character lowercase hex string.</returns>
|
|
public static string HashVersioned<T>(T obj, string version = CanonVersion.Current)
|
|
{
|
|
var canonical = CanonicalizeVersioned(obj, version);
|
|
return Sha256Hex(canonical);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Computes prefixed SHA-256 hash of versioned canonical representation.
|
|
/// </summary>
|
|
/// <typeparam name="T">The type to serialize.</typeparam>
|
|
/// <param name="obj">The object to hash.</param>
|
|
/// <param name="version">Canonicalization version (default: Current).</param>
|
|
/// <returns>Hash string with "sha256:" prefix.</returns>
|
|
public static string HashVersionedPrefixed<T>(T obj, string version = CanonVersion.Current)
|
|
{
|
|
var canonical = CanonicalizeVersioned(obj, version);
|
|
return Sha256Prefixed(canonical);
|
|
}
|
|
}
|