Skip to main content

​
@parmanasystems/canonical

The Canonical package provides deterministic serialization and canonicalization used throughout Parmana. It ensures that identical data always produces identical hashes, signatures, execution fingerprints, and verification results regardless of platform, runtime, or language implementation.

​
Installation

npm install @parmanasystems/canonical

​
Responsibilities

The canonical layer provides:
  • Deterministic serialization
  • Canonical JSON generation
  • Stable hashing inputs
  • Signature consistency
  • Cross-platform reproducibility
  • Verification compatibility

​
Why it exists

Cryptographic systems depend on exact byte-for-byte consistency. Without canonicalization: 
{"a":1,"b":2}
and 
{"b":2,"a":1}
could produce different hashes even though they represent the same data. Canonicalization eliminates this ambiguity.

​
Core concepts

​
Canonical Form

Before hashing or signing, data is transformed into a deterministic representation. 
Input
   ↓
Canonicalization
   ↓
Canonical Form
   ↓
Hashing / Signing
This guarantees reproducibility.

​
Execution Fingerprints

Execution fingerprints are derived from canonicalized inputs. 
sha256(
  canonical(
    policyId,
    policyVersion,
    signals
  )
)
Because canonicalization is deterministic:
  • identical inputs produce identical fingerprints
  • replay protection remains stable
  • verification is reproducible

​
Signature Consistency

Attestation signatures operate on canonical payloads. This ensures:
  • deterministic signing inputs
  • reproducible verification
  • language-independent validation

​
Relationship to other packages

PackageResponsibility
@parmanasystems/canonicalDeterministic serialization
@parmanasystems/signingSignature generation
@parmanasystems/executionFingerprint generation
@parmanasystems/verifierVerification
@parmanasystems/coreEnd-to-end SDK

​
Why canonicalization matters

Without canonicalization: 
Same data
     ↓
Different serialization
     ↓
Different hashes
     ↓
Broken verification
With canonicalization: 
Same data
     ↓
Same canonical form
     ↓
Same hash
     ↓
Same verification result

​
Design principles

​
Deterministic

The same input always produces the same canonical form.

​
Portable

Different runtimes produce identical results.

​
Verifiable

Hashes and signatures remain reproducible.

​
Long-term stable

Historical attestations remain verifiable years later.

​
Typical usage

Most developers use canonicalization indirectly through:
  • @parmanasystems/core
  • @parmanasystems/execution
  • @parmanasystems/signing
Advanced integrations may use canonicalization directly when generating hashes or custom trust artifacts.

​
Security benefits

​
Stable Hashes

Hashes are independent of serialization order.

​
Stable Signatures

Signatures are generated from reproducible payloads.

​
Independent Verification

Third parties can reproduce hashes exactly.

​
Audit Reproducibility

Historical authority verification outcomes remain verifiable.

​
See also

  • /packages/signing
  • /packages/execution
  • /packages/verifier
  • /verification/attestations
  • /architecture/trust-portability