Canonical

Deterministic canonicalization and serialization for reproducible hashing and verification.

@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

Package	Responsibility
@parmanasystems/canonical	Deterministic serialization
@parmanasystems/signing	Signature generation
@parmanasystems/execution	Fingerprint generation
@parmanasystems/verifier	Verification
@parmanasystems/core	End-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