Canonicalization

Ensuring deterministic hashing of JSON structures

JSON is an unordered format. {"a": 1, "b": 2} and {"b": 2, "a": 1} are semantically identical but have different string bytes.

To ensure that signatures are stable, MCPTrust uses JCS (JSON Canonicalization Scheme - RFC 8785) before hashing or signing any artifact.

What JCS Does

  • Sorts object keys lexicographically.
  • Removes insignificant whitespace (minification).
  • Uses a consistent number formatting (e.g., no scientific notation for integers).

The Pipeline

  1. Scan: Receive raw JSON from MCP server.
  2. Canonicalize: Apply JCS.
  3. Hash: Compute SHA-256.
  4. Sign: Sign the canonical lockfile.

This ensures that mcptrust verify works across different operating systems and languages.

Versions (v1 vs v2)

MCPTrust supports two canonicalization versions:

  • v1 (Default): Sorts keys lexicographically. Sufficient for most use cases.
  • v2 (RFC 8785): Full JCS compliance. Handles edge cases like floating point representation and unicode escaping more strictly.

To use strict RFC compliance:

mcptrust lock --canonicalization v2
Docs — MCPTrust