88 lines
3.3 KiB
C#
88 lines
3.3 KiB
C#
namespace StellaOps.Canonical.Json;
|
|
|
|
/// <summary>
|
|
/// Canonicalization version identifiers for content-addressed hashing.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Version markers are embedded in canonical JSON to ensure hash stability across
|
|
/// algorithm evolution. When canonicalization logic changes (bug fixes, spec updates,
|
|
/// optimizations), a new version constant is introduced, allowing:
|
|
/// <list type="bullet">
|
|
/// <item>Verifiers to select the correct canonicalization algorithm</item>
|
|
/// <item>Graceful migration without invalidating existing hashes</item>
|
|
/// <item>Clear audit trail of which algorithm produced each hash</item>
|
|
/// </list>
|
|
/// </remarks>
|
|
public static class CanonVersion
|
|
{
|
|
/// <summary>
|
|
/// Version 1: RFC 8785 JSON Canonicalization Scheme (JCS) with:
|
|
/// <list type="bullet">
|
|
/// <item>Ordinal key sorting (case-sensitive, lexicographic)</item>
|
|
/// <item>No whitespace or formatting variations</item>
|
|
/// <item>UTF-8 encoding without BOM</item>
|
|
/// <item>IEEE 754 number formatting</item>
|
|
/// <item>Minimal escape sequences in strings</item>
|
|
/// </list>
|
|
/// </summary>
|
|
public const string V1 = "stella:canon:v1";
|
|
|
|
/// <summary>
|
|
/// Field name for version marker in canonical JSON.
|
|
/// Underscore prefix ensures it sorts first lexicographically,
|
|
/// making version detection a simple prefix check.
|
|
/// </summary>
|
|
public const string VersionFieldName = "_canonVersion";
|
|
|
|
/// <summary>
|
|
/// Current default version for new hashes.
|
|
/// All new content-addressed IDs use this version.
|
|
/// </summary>
|
|
public const string Current = V1;
|
|
|
|
/// <summary>
|
|
/// Prefix bytes for detecting versioned canonical JSON.
|
|
/// Versioned JSON starts with: {"_canonVersion":"
|
|
/// </summary>
|
|
internal static ReadOnlySpan<byte> VersionedPrefixBytes => "{\"_canonVersion\":\""u8;
|
|
|
|
/// <summary>
|
|
/// Checks if canonical JSON bytes are versioned (contain version marker).
|
|
/// </summary>
|
|
/// <param name="canonicalJson">UTF-8 encoded canonical JSON bytes.</param>
|
|
/// <returns>True if the JSON contains a version marker at the expected position.</returns>
|
|
public static bool IsVersioned(ReadOnlySpan<byte> canonicalJson)
|
|
{
|
|
// Versioned canonical JSON always starts with: {"_canonVersion":"stella:canon:v
|
|
// Minimum length: {"_canonVersion":"stella:canon:v1"} = 35 bytes
|
|
return canonicalJson.Length >= 35 &&
|
|
canonicalJson.StartsWith(VersionedPrefixBytes);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Extracts the version string from versioned canonical JSON.
|
|
/// </summary>
|
|
/// <param name="canonicalJson">UTF-8 encoded canonical JSON bytes.</param>
|
|
/// <returns>The version string, or null if not versioned or invalid format.</returns>
|
|
public static string? ExtractVersion(ReadOnlySpan<byte> canonicalJson)
|
|
{
|
|
if (!IsVersioned(canonicalJson))
|
|
{
|
|
return null;
|
|
}
|
|
|
|
// Find the closing quote after the version value
|
|
var prefixLength = VersionedPrefixBytes.Length;
|
|
var remaining = canonicalJson[prefixLength..];
|
|
|
|
var quoteIndex = remaining.IndexOf((byte)'"');
|
|
if (quoteIndex <= 0)
|
|
{
|
|
return null;
|
|
}
|
|
|
|
var versionBytes = remaining[..quoteIndex];
|
|
return System.Text.Encoding.UTF8.GetString(versionBytes);
|
|
}
|
|
}
|