# @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

```ts
/**
 * 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
```

<!-- VERIFY: confirm exact parameter and return types for signManifest, verifySignature, verifyManifestSignature, signBundle from packages/crypto/src/*.ts -->

---

## 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.