@parmanasystems/crypto 1.71.12 → 1.71.14

package/README.md

@@ -10,7 +10,7 @@ Ed25519 signing and verification primitives for governance artifacts.
 
 `@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`. 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.
+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.
 
 ---
 
@@ -22,53 +22,95 @@ npm install @parmanasystems/crypto
 
 ---
 
-## Usage
+## Key Management
+
+Generate an Ed25519 keypair and store the PEM files on disk:
 
 ```typescript
-import { signBundle, loadPublicKey } from "@parmanasystems/crypto";
-import { LocalSigner } from "@parmanasystems/execution";
 import crypto from "crypto";
+import fs from "fs";
 
-const { privateKey } = crypto.generateKeyPairSync("ed25519", {
+const { privateKey, publicKey } = crypto.generateKeyPairSync("ed25519", {
   privateKeyEncoding: { type: "pkcs8", format: "pem" },
   publicKeyEncoding:  { type: "spki",  format: "pem" },
 });
 
-const signer = new LocalSigner(privateKey);
+// 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);
+```
 
-// Sign a built bundle directory — writes bundle.sig next to bundle.manifest.json
-await signBundle({
-  bundlePath: "./dist/bundles/loan-approval",
-  signer,
-});
+Pass paths **explicitly** to all signing and verification functions — there is no implicit key discovery.
+
+---
+
+## Usage
+
+### Load keys from disk
+
+```typescript
+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 directly
+### Sign a manifest file
 
 ```typescript
 import { signManifest } from "@parmanasystems/crypto";
 
-// Reads bundle.manifest.json, canonicalizes, signs with trust root key from disk
-const signature = signManifest("./dist/bundles/loan-approval/bundle.manifest.json");
+// Both arguments are required
+const signature = signManifest(
+  "./policies/loan-approval/v1/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
 
-## Exports
+```typescript
+import { verifySignature } from "@parmanasystems/crypto";
+
+// All three arguments are required
+const ok = verifySignature(
+  "./policies/loan-approval/v1/bundle.manifest.json",  // path to manifest
+  signature,                                            // base64 signature string
+  "./trust/root.pub"                                   // path to Ed25519 public key PEM
+);
+console.log(ok); // true
+```
 
-| Export | Description |
-|---|---|
-| `signBundle` | Sign a bundle directory — reads `bundle.manifest.json`, writes `bundle.sig` |
-| `signManifest` | Sign a manifest file using the trust root private key from disk |
-| `loadPrivateKey` | Load the trust root Ed25519 private key PEM from `trust/root.key` |
-| `loadPublicKey` | Load the trust root Ed25519 public key PEM from `trust/root.pub` |
+### Sign a bundle directory
+
+```typescript
+import { signBundle } from "@parmanasystems/crypto";
+
+// Signs bundle.manifest.json in the directory and writes bundle.sig
+await signBundle({
+  bundlePath:     "./policies/loan-approval/v1",
+  privateKeyPath: "./trust/root.key",
+});
+```
 
 ---
 
-## Trust root key location
+## Exports
 
-By default `loadPrivateKey` and `loadPublicKey` read from `trust/root.key` and `trust/root.pub` relative to `process.cwd()`. In production, inject key material via a secrets manager rather than files on disk.
+| 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 |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parmanasystems/crypto",
-  "version": "1.71.12",
+  "version": "1.71.14",
   "private": false,
   "type": "module",
   "scripts": {
@@ -18,7 +18,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@parmanasystems/bundle": "^1.71.12"
+    "@parmanasystems/bundle": "^1.71.14"
   },
   "description": "Signing and verification primitives for deterministic governance infrastructure.",
   "license": "Apache-2.0",