@parmanasystems/canonical

Deterministic JSON serialization for the Parmana stack. Given any value, canonicalize produces a compact JSON string with object keys sorted recursively, strings Unicode-NFC normalized, and line endings normalized to \n. The output is byte-stable across runtimes, so SHA-256 hashes and Ed25519 signatures computed from it are reproducible. All signing, hashing, and attestation in the stack pass through this package.

Public API

/**
 * Serialize `value` to stable, compact JSON.
 * Object keys are sorted recursively. Strings are NFC-normalized.
 * Throws coded errors for: BigInt ([CANONICAL-002]), Date ([CANONICAL-003]),
 * circular references ([CANONICAL-004]), non-finite numbers ([CANONICAL-001]).
 */
function canonicalize(value: unknown): string

/**
 * Serialize `value` and wrap it in a signing-domain envelope.
 * Used before Ed25519 signing and before computing attestation hashes.
 */
function canonicalizeForSigning(value: unknown, domain: SigningDomain): string

/**
 * Return the signing-domain envelope object without serializing to string.
 */
function applySigningDomain(value: unknown, domain: SigningDomain): Record<string, unknown>

/**
 * Pre-defined signing domains. Pass one of these to canonicalizeForSigning
 * to ensure cross-package domain separation.
 */
const SIGNING_DOMAINS: {
  token:       SigningDomain;
  attestation: SigningDomain;
  audit:       SigningDomain;
  bundle:      SigningDomain;
  manifest:    SigningDomain;
  provenance:  SigningDomain;
}

type SigningDomain = string

Environment variables

None. Pure computation — no I/O, no environment reads.

Package wiring

@parmanasystems/canonical has no internal @parmanasystems dependencies. It is a leaf package imported by every other package in the stack: execution, crypto, bundle, governance, provenance, verifier, and execution-runtime all import canonicalize and SIGNING_DOMAINS directly. Many of those packages re-export these symbols for consumer convenience.