Add Canonical JSON serialization library with tests and documentation
- Implemented CanonJson class for deterministic JSON serialization and hashing. - Added unit tests for CanonJson functionality, covering various scenarios including key sorting, handling of nested objects, arrays, and special characters. - Created project files for the Canonical JSON library and its tests, including necessary package references. - Added README.md for library usage and API reference. - Introduced RabbitMqIntegrationFactAttribute for conditional RabbitMQ integration tests.
This commit is contained in:
95
src/__Libraries/StellaOps.Canonical.Json/README.md
Normal file
95
src/__Libraries/StellaOps.Canonical.Json/README.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# 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
|
||||
|
||||
```csharp
|
||||
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
|
||||
|
||||
```csharp
|
||||
// Hash object directly
|
||||
string hash = CanonJson.Hash(obj);
|
||||
|
||||
// With sha256: prefix
|
||||
string prefixed = CanonJson.HashPrefixed(obj);
|
||||
// Result: "sha256:a1b2c3..."
|
||||
```
|
||||
|
||||
### Canonicalizing Existing JSON
|
||||
|
||||
```csharp
|
||||
// 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
|
||||
|
||||
```csharp
|
||||
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
|
||||
Reference in New Issue
Block a user