@parmanasystems/bundle

Deterministic artifact canonicalization, hashing, and bundle I/O for the parmanasystems governance runtime.

Overview

@parmanasystems/bundle provides the canonical serialization foundation that makes parmanasystems governance decisions independently verifiable.

Every signed governance artifact — execution results, runtime manifests, policy bundles — is signed over the canonical JSON form produced by this package. This ensures:

• The same object always serializes to the same byte sequence regardless of property insertion order
• Signatures can be independently reproduced and verified by any party
• Artifact hashes are stable across platforms and runtimes

Installation

npm install @parmanasystems/bundle

API

canonicalize(value: unknown): string

Produces a deterministic JSON string with recursively sorted keys and stable formatting (INV-001). Enforced as a sealed-VM function — no Date.now or Math.random allowed inside.

import { canonicalize } from "@parmanasystems/bundle";

canonicalize({ b: 2, a: 1 });
// '{\n  "a": 1,\n  "b": 2\n}'

sha256(content: string): string

Returns a SHA-256 hex digest of the given string.

import { sha256 } from "@parmanasystems/bundle";

sha256('{"a":1}');
// "e3b0c44..." (hex)

generateManifest(policyId, version, directory): Promise<BundleManifest>

Hashes all files in a policy directory and produces a BundleManifest with a self-verifying bundle_hash.

import { generateManifest } from "@parmanasystems/bundle";

const manifest = await generateManifest("claims-approval", "v1", "./policies/claims-approval/v1");

readManifest(directory): Promise<BundleManifest>

Reads bundle.manifest.json from a directory.

verifyManifest(manifest, directory): Promise<VerifyResult>

Re-hashes all artifacts and compares against the stored manifest.

const result = await verifyManifest(manifest, directory);
console.log(result.valid);  // true

traverseBundle(dir: string): Promise<string[]>

Returns sorted POSIX-relative file paths within a bundle directory, enabling deterministic hash computation.

Types

BundleManifest

interface BundleManifest {
  manifest_version: "1";
  policy_id: string;
  policy_version: string;
  artifacts: BundleArtifact[];
  runtime_requirements: RuntimeRequirements;
  bundle_hash: string;  // self-verifying SHA-256
}

interface BundleArtifact {
  path: string;    // POSIX-relative
  hash: string;    // SHA-256 hex
}

VerifyResult

interface VerifyResult {
  valid: boolean;
  expected_bundle_hash: string;
  actual_bundle_hash: string;
}

Role in the pipeline

Governance artifact (object)
        │
   canonicalize()   ← this package
        │
   canonical JSON string
        │
   sha256() / Ed25519 sign / verify

canonicalize() is called by signExecutionToken(), stageSign(), and every other signing path in @parmanasystems/execution. You only need to call it directly for custom signing or verification flows.

License

Apache-2.0