@parmanasystems/crypto

Ed25519 signing and verification utilities for Parmana governance artifacts. Provides key loading from PEM files, signature persistence, manifest signing, and bundle signing. All payloads are first canonicalized via @parmanasystems/canonical before signing so signatures are byte-stable across platforms.

Public API

/**
 * Load an Ed25519 private key from a PEM file path (PKCS8 format).
 * Returns a Node.js KeyObject.
 */
function loadPrivateKey(path: string): crypto.KeyObject

/**
 * Load an Ed25519 public key from a PEM file path (SPKI format).
 * Returns a Node.js KeyObject.
 */
function loadPublicKey(path: string): crypto.KeyObject

/**
 * Sign a governance manifest object. The manifest is canonicalized before signing.
 * Returns the base64-encoded Ed25519 signature string.
 */
function signManifest(manifest: unknown, privateKey: crypto.KeyObject): string

/**
 * Verify a base64-encoded Ed25519 signature against a payload string.
 * Returns true if valid, false otherwise.
 */
function verifySignature(payload: string, signature: string, publicKey: crypto.KeyObject | string): boolean

/**
 * Verify the signature of a governance manifest object.
 * Canonicalizes the manifest, then calls verifySignature.
 */
function verifyManifestSignature(
  manifest: unknown,
  signature: string,
  publicKey: crypto.KeyObject | string
): boolean

/**
 * Sign a policy bundle. Canonicalizes the bundle manifest and writes a .sig file.
 */
function signBundle(bundlePath: string, privateKey: crypto.KeyObject): Promise<void>

/** Write a base64 signature string to a file. */
function writeSignature(path: string, signature: string): void

/** Read a base64 signature string from a file. */
function readSignature(path: string): string

Environment variables

None. Key material is loaded by callers (e.g. @parmanasystems/signing) who pass key objects to these functions.

Package wiring

@parmanasystems/crypto depends on @parmanasystems/canonical for deterministic serialization before signing. It is used by the release pipeline scripts (scripts/release/sign-release-manifest.ts), @parmanasystems/core (which re-exports signBundle), and the build tooling. The server runtime uses @parmanasystems/signing for runtime key management, which wraps the lower-level crypto operations.