@parmanasystems/bundle

Policy bundle manifest generation, verification, and persistence. A bundle packages a compiled policy with a cryptographically signed bundle.manifest.json that records the content hash of every artifact in the bundle directory. The manifest is the trust anchor: loadPolicyBundle() in @parmanasystems/governance verifies it at runtime before the policy is evaluated.

Public API

/**
 * Generate a bundle manifest for the directory at `bundlePath`.
 * Traverses all files, computes SHA-256 per artifact, and writes
 * `bundle.manifest.json`. If a signer is provided, also writes `bundle.sig`.
 */
function generateManifest(
  bundlePath: string,
  options?: { signer?: (payload: string) => Promise<string> }
): Promise<BundleManifest>

/** Read and parse `bundle.manifest.json` from `bundlePath`. */
function readManifest(bundlePath: string): BundleManifest

/**
 * Verify manifest integrity: recompute artifact hashes and compare.
 * Returns a VerifyResult with `valid: boolean` and per-artifact details.
 */
function verifyManifest(bundlePath: string, manifest: BundleManifest): Promise<VerifyResult>

/** Write a `BundleManifest` object to `bundle.manifest.json` at `bundlePath`. */
function writeManifest(bundlePath: string, manifest: BundleManifest): void

/** Recursively list files under `dirPath`, returning relative paths. */
function traverseDirectory(dirPath: string): string[]

/** SHA-256 hash of a UTF-8 string, hex-encoded. */
function sha256(value: string): string

// ── Types ──────────────────────────────────────────────────────────────────

interface BundleArtifact {
  path: string;   // relative path within bundle directory
  hash: string;   // SHA-256 hex of file contents
}

interface BundleManifest {
  bundle_hash: string;       // deterministic hash of all artifacts
  artifacts: BundleArtifact[];
  [key: string]: unknown;    // additional provenance fields
}

interface VerifyResult {
  valid: boolean;
  artifacts: Array<{
    path: string;
    expected: string;
    actual: string;
    match: boolean;
  }>;
}

interface RuntimeRequirements {
  supportedRuntimeVersions: string[];
  supportedSchemaVersions: string[];
}

Environment variables

None.

Package wiring

@parmanasystems/bundle depends on @parmanasystems/canonical for deterministic manifest serialization. It is used by @parmanasystems/governance (generateBundle() calls into this package to create and sign the manifest), and by @parmanasystems/verifier to verify bundle integrity. The release pipeline uses it via scripts/governance/build-policies.ts.