@parmanasystems/canonical

Deterministic canonicalization and signing-domain infrastructure for independently verifiable governance systems.

Canonicalization is the deterministic substrate beneath:

• governance execution
• replay protection
• provenance verification
• cryptographic attestations
• release verification
• trust-root continuity

The same semantic input always produces:

• the same canonical bytes
• the same hashes
• the same signatures
• the same execution identity

Installation

npm install @parmanasystems/canonical

Requirements

• Node.js >= 20
• ESM-only runtime

Why Canonicalization Matters

Without deterministic canonicalization:

• signatures drift
• replay identity breaks
• provenance cannot be reconstructed
• governance verification becomes non-portable
• independent verification becomes unreliable

Canonicalization guarantees that semantically equivalent inputs produce identical serialized output across runtimes and environments.

Canonicalization Guarantees

Parmana canonicalization guarantees:

• deterministic UTF-8 serialization
• lexicographically sorted object keys
• preserved array ordering
• deterministic primitive serialization
• deterministic nested serialization
• whitespace-independent output
• stable signing payload generation

The same semantic structure always produces identical canonical bytes.

Canonicalization Rules

Object Keys

Object keys are sorted lexicographically.

Example:

{
  z: true,
  a: true
}

Canonicalizes to:

{"a":true,"z":true}

Arrays

Arrays preserve original ordering.

Example:

[
  "a",
  "b",
  "c"
]

remains:

["a","b","c"]

Array order is considered semantically significant.

UTF-8 Output

Canonicalized payloads are emitted as deterministic UTF-8 strings.

Nested Structures

Nested objects and arrays are recursively canonicalized using identical deterministic rules.

Quickstart

Canonicalize Deterministic Payloads

import {

  canonicalize,

  canonicalHash,

} from "@parmanasystems/canonical";

const payload = {

  z: true,

  nested: {

    b: 2,

    a: 1,
  },

  a: true,

  items: [
    "x",
    "y",
    "z"
  ],
};

const canonical =
  canonicalize(
    payload
  );

console.log(
  canonical
);

const hash =
  canonicalHash(
    payload
  );

console.log(
  hash
);

Expected Output

{"a":true,"items":["x","y","z"],"nested":{"a":1,"b":2},"z":true}

4d4e2cb4f54f0a2f0b5a0e7f1a8f3c7f74d6d6e3a1f5f6d4f91f9e1f1f1d2a3

The same semantic payload always produces the same:

• canonical bytes
• canonical hash
• signing payload
• replay identity

Stable Signing Payloads

Canonical signing payloads prevent cross-runtime signature drift.

Example

import {

  buildSigningPayload,

  SIGNING_DOMAINS,

} from "@parmanasystems/canonical";

const payload =
  buildSigningPayload(

    SIGNING_DOMAINS.release,

    {
      version: "1.0.0",
      artifact: "openapi.json",
    }
  );

console.log(
  payload
);

Expected Signing Payload

PARMANA_RELEASE_V1
{"artifact":"openapi.json","version":"1.0.0"}

Signing payloads are deterministic and domain-separated.

Signing Domains

Parmana uses explicit signing domains to prevent cross-domain signature confusion.

Supported domains:

PARMANA_BUNDLE_V1
PARMANA_ATTESTATION_V1
PARMANA_RELEASE_V1
PARMANA_AUDIT_V1
PARMANA_TOKEN_V1
PARMANA_OVERRIDE_V1

Each signing domain creates isolated cryptographic intent boundaries.

A signature created for:

PARMANA_RELEASE_V1

cannot be reused as a valid:

PARMANA_BUNDLE_V1

signature.

This prevents:

• cross-domain replay
• signature confusion
• provenance ambiguity
• governance escalation through signature reuse

Determinism Invariants

Parmana governance execution forbids nondeterministic operational metadata from influencing execution identity.

Core invariants include:

forbiddenDeterministicFields
assertNoOperationalMetadata

These protections prevent:

• timestamps
• process-local identifiers
• runtime-local metadata
• transient infrastructure state
• nondeterministic operational fields

from affecting:

• execution fingerprints
• replay identity
• signatures
• provenance reconstruction

Example — Stable Canonical Hashes

import {

  canonicalHash,

} from "@parmanasystems/canonical";

const a = {

  z: true,

  a: true,
};

const b = {

  a: true,

  z: true,
};

console.log(
  canonicalHash(a)
);

console.log(
  canonicalHash(b)
);

Expected Output

true

Both structures produce identical canonical hashes despite differing source ordering.

Governance Architecture Role

Canonicalization forms the deterministic foundation beneath:

• replay-safe execution
• cryptographic attestations
• bundle verification
• release verification
• runtime provenance
• independent auditability
• portable governance verification

Deterministic governance is impossible without deterministic serialization semantics.

API Surface

canonicalize

canonicalize(
  value: unknown
): string

Produces deterministic canonical UTF-8 serialization.

canonicalHash

canonicalHash(
  value: unknown
): string

Produces deterministic SHA-256 canonical hashes.

buildSigningPayload

buildSigningPayload(
  domain: string,
  payload: unknown
): string

Constructs deterministic signing payloads with explicit signing-domain separation.

SIGNING_DOMAINS

SIGNING_DOMAINS.bundle
SIGNING_DOMAINS.attestation
SIGNING_DOMAINS.release
SIGNING_DOMAINS.audit
SIGNING_DOMAINS.token
SIGNING_DOMAINS.override

Deterministic Governance Model

Parmana separates:

AI Evaluation

AI systems may:

• classify inputs
• summarize content
• generate signals
• recommend actions

Governance Enforcement

Canonicalization guarantees that governed execution identity remains:

• deterministic
• portable
• independently reproducible
• cryptographically stable

License

Apache-2.0