@parmanasystems/crypto

Ed25519 signing and verification primitives for governance artifacts.

Overview

@parmanasystems/crypto provides the low-level cryptographic operations used across the Parmana Systems governance pipeline: signing and verifying bundle manifests, loading trust root keys from disk, and packaging bundles with Ed25519 signatures.

Most applications should use @parmanasystems/core or @parmanasystems/governance. Use this package directly only when building tooling that needs the raw signing primitives - for example, a CI step that signs a bundle before deployment.

Install

npm install @parmanasystems/crypto

Key Management

Generate an Ed25519 keypair and store the PEM files on disk:

import crypto from "crypto";
import fs from "fs";

const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519", {
  privateKeyEncoding: { type: "pkcs8", format: "pem" },
  publicKeyEncoding:  { type: "spki",  format: "pem" },
});

// Store keys - in production use a secrets manager, not plain files
fs.mkdirSync("trust", { recursive: true });
fs.writeFileSync("trust/root.key", privateKey, { mode: 0o600 });
fs.writeFileSync("trust/root.pub", publicKey);

Pass paths explicitly to all signing and verification functions - there is no implicit key discovery.

Usage

Load keys from disk

import { loadPrivateKey, loadPublicKey } from "@parmanasystems/crypto";

// Both functions require an explicit path - there is no default path fallback
const privateKeyPem = loadPrivateKey("./trust/root.key");
const publicKeyPem  = loadPublicKey("./trust/root.pub");

Sign a manifest file

import { signManifest } from "@parmanasystems/crypto";

// Both arguments are required
const signature = signManifest(
  "./policies/loan-approval/1.0.0/bundle.manifest.json",  // path to manifest
  "./trust/root.key"                                    // path to Ed25519 private key PEM
);
console.log(signature); // base64-encoded Ed25519 signature

Verify a manifest signature

import { verifySignature } from "@parmanasystems/crypto";

// All three arguments are required
const ok = verifySignature(
  "./policies/loan-approval/1.0.0/bundle.manifest.json",  // path to manifest
  signature,                                            // base64 signature string
  "./trust/root.pub"                                   // path to Ed25519 public key PEM
);
console.log(ok); // true

Sign a bundle directory

import { signBundle } from "@parmanasystems/crypto";

// Signs bundle.manifest.json in the directory and writes bundle.sig
await signBundle({
  bundlePath:     "./policies/loan-approval/1.0.0",
  privateKeyPath: "./trust/root.key",
});

Exports

Export	Description
`loadPrivateKey`	Load Ed25519 private key PEM from an explicit file path
`loadPublicKey`	Load Ed25519 public key PEM from an explicit file path
`signManifest`	Sign a `bundle.manifest.json` file; returns base64 Ed25519 signature
`verifySignature`	Verify a base64 signature over a manifest file using a public key path
`verifyPayloadSignature`	Verify a base64 signature over an arbitrary UTF-8 payload string
`verifyManifestSignature`	Verify a `bundle.sig` file against a manifest on disk
`signBundle`	Sign a bundle directory - reads manifest, writes `bundle.sig`
`writeSignature`	Write a base64 signature string to `bundle.sig` in a directory
`readSignature`	Read a `bundle.sig` file and return the base64 signature string

Documentation

Full docs: parmanasystems.mintlify.app Package page: parmanasystems.mintlify.app/packages/crypto

License

Apache-2.0