@parmanasystems/crypto 1.56.0 → 1.59.0

package/README.md

@@ -1,84 +1,425 @@
 # @parmanasystems/crypto
 
-Ed25519 key management, signing, and verification primitives for the parmanasystems governance runtime.
+Cryptographic signing and verification infrastructure for deterministic governance artifacts and execution attestations.
 
 [![npm](https://img.shields.io/npm/v/@parmanasystems/crypto)](https://www.npmjs.com/package/@parmanasystems/crypto)
 
-## Overview
+---
 
-`@parmanasystems/crypto` provides the low-level cryptographic primitives used throughout parmanasystems:
+# Overview
 
-- Loading Ed25519 keys from disk or environment variables
-- Signing canonical payloads (returns base64)
-- Verifying Ed25519 signatures
-- Signing and verifying bundle manifests
+`@parmanasystems/crypto` provides the cryptographic trust infrastructure for the Parmana Systems governance ecosystem.
 
-All operations use Node.js's built-in `crypto` module — no external cryptographic dependencies.
+It is responsible for:
 
-## Installation
+- Ed25519 signing
+- deterministic signature verification
+- governance trust roots
+- bundle signature validation
+- execution attestation signing
+- runtime provenance verification
+- cryptographic governance authority
 
-```bash
+All governance trust in Parmana derives from deterministic cryptographic verification.
+
+Governance decisions are trusted because deterministic artifacts are cryptographically signed and independently verifiable.
+
+---
+
+# Mental Model
+
+```txt id="3e9qsu"
+Governance Artifact
+        ↓
+Canonical Serialization
+        ↓
+SHA-256 Hash
+        ↓
+Ed25519 Signature
+        ↓
+Portable Verification
+
+The crypto layer establishes deterministic governance trust boundaries.
+
+What this package does
+
+The crypto package provides:
+
+Ed25519 key management
+governance signing infrastructure
+deterministic signature verification
+governance manifest signing
+portable trust validation
+cryptographic provenance enforcement
+canonical payload signing
+
+This package is the trust foundation for:
+
+execution attestations
+governance bundles
+runtime manifests
+deterministic provenance
+When to use this package
+
+Use this package when:
+
+signing governance artifacts
+verifying execution attestations
+implementing deterministic trust roots
+verifying governance provenance
+managing Ed25519 governance keys
+building custom signing workflows
+validating governance signatures
+
+Do NOT use this package when:
+
+executing governed decisions
+generating governance manifests
+deploying HTTP runtimes
+performing policy evaluation
+
+In those cases use:
+
+Package	Responsibility
+@parmanasystems/execution	governed execution
+@parmanasystems/bundle	canonical artifacts
+@parmanasystems/server	deployable runtime
+@parmanasystems/core	unified governance SDK
+Features
+Ed25519 signing and verification
+Deterministic governance signatures
+Canonical payload signing
+Governance trust-root infrastructure
+Bundle manifest signing
+Portable cryptographic verification
+Runtime provenance validation
+Zero external crypto dependencies
+Installation
 npm install @parmanasystems/crypto
-```
+Quick Start
+import {
+  loadPrivateKey,
+  loadPublicKey,
+  signPayload,
+  verifyPayloadSignature,
+} from "@parmanasystems/crypto";
+
+const privateKey =
+  loadPrivateKey();
+
+const publicKey =
+  loadPublicKey();
+
+const payload = {
+  policy_id:
+    "claims-approval",
+
+  policy_version:
+    "v1",
+};
+
+const signature =
+  signPayload(
+    payload,
+    privateKey
+  );
+
+const valid =
+  verifyPayloadSignature(
+    payload,
+    signature,
+    publicKey
+  );
+
+console.log(valid);
+Core Concepts
+Canonical Signing
+
+Governance signatures are generated over canonical bytes.
+
+This is critical.
+
+The same governance payload must always produce identical serialized bytes before signing.
+
+Example:
+
+same payload
+      ↓
+same canonical bytes
+      ↓
+same deterministic hash
+
+Canonicalization guarantees:
+
+stable signatures
+reproducible provenance
+independent verification
+deterministic trust validation
+
+Canonical serialization is provided by:
+
+@parmanasystems/bundle
+Trust Roots
+
+Governance trust derives from cryptographic trust roots.
+
+Trust roots include:
+
+Ed25519 private keys
+Ed25519 public keys
+immutable verification authority
+
+Public keys establish portable governance verification authority.
+
+Independent Verification
+
+Governance signatures are independently verifiable.
+
+Any verifier can:
+
+reconstruct canonical bytes
+validate signatures
+verify provenance
+confirm runtime identity
+
+Verification does not depend on:
+
+runtime assumptions
+deployment infrastructure
+trusted servers
+mutable state
+
+Trust derives from deterministic cryptographic verification, not runtime assumptions.
+
+Deterministic Provenance
+
+Signatures bind:
+
+governance lineage
+execution identity
+runtime provenance
+governance artifacts
+
+This creates portable deterministic provenance.
+
+Portable Governance Validation
+
+Governance artifacts remain verifiable:
+
+across environments
+across deployments
+across organizations
+across runtime implementations
+
+This enables:
+
+independent audits
+reproducible verification
+portable governance trust
+Signing Flow
+Governance Artifact
+      ↓
+Canonical Serialization
+      ↓
+SHA-256 Hash
+      ↓
+Ed25519 Signature
+      ↓
+Portable Verification
+Key Loading
+loadPrivateKey
+
+Loads Ed25519 private keys.
+
+import {
+  loadPrivateKey
+} from "@parmanasystems/crypto";
+
+const privateKey =
+  loadPrivateKey();
+
+Default path:
+
+./dev-keys/bundle_signing_key
+loadPublicKey
+
+Loads Ed25519 public keys.
+
+import {
+  loadPublicKey
+} from "@parmanasystems/crypto";
+
+const publicKey =
+  loadPublicKey();
+
+Default path:
+
+./dev-keys/bundle_signing_key.pub
+Signing APIs
+signPayload
+
+Signs canonical governance payloads.
+
+import {
+  signPayload
+} from "@parmanasystems/crypto";
+
+const signature =
+  signPayload(
+    payload,
+    privateKey
+  );
+
+Returns:
+
+base64-encoded Ed25519 signature
+signManifest
+
+Signs governance manifests.
+
+import {
+  signManifest
+} from "@parmanasystems/crypto";
+
+const signature =
+  await signManifest(
+    "./policies/claims-approval/v1/bundle.manifest.json"
+  );
+
+Manifest signatures protect:
+
+governance lineage
+artifact integrity
+reproducibility provenance
+Verification APIs
+verifyPayloadSignature
+
+Verifies governance payload signatures.
+
+import {
+  verifyPayloadSignature
+} from "@parmanasystems/crypto";
+
+const valid =
+  verifyPayloadSignature(
+    payload,
+    signature,
+    publicKey
+  );
+
+Returns:
+
+boolean verification result
+verifySignature
+
+Verifies governance manifest signatures.
+
+import {
+  verifySignature
+} from "@parmanasystems/crypto";
+
+const valid =
+  await verifySignature(
+    manifestPath,
+    signature
+  );
+
+Verification checks:
+
+canonical integrity
+signature authenticity
+provenance validity
+Key Persistence
+persistKeys
+
+Persists governance trust-root keys.
 
-## API
+import {
+  persistKeys
+} from "@parmanasystems/crypto";
 
-### Key loading
+await persistKeys(
+  privateKey,
+  publicKey,
+  "./dev-keys"
+);
 
-```typescript
-import { loadPrivateKey, loadPublicKey } from "@parmanasystems/crypto";
+Generated files:
 
-// Load from file (relative path or absolute)
-const privateKey = loadPrivateKey();  // reads ./dev-keys/bundle_signing_key
-const publicKey  = loadPublicKey();   // reads ./dev-keys/bundle_signing_key.pub
-```
+bundle_signing_key
+bundle_signing_key.pub
+Algorithms
 
-### Signing
+The package uses:
 
-```typescript
-import { signManifest } from "@parmanasystems/crypto";
+Ed25519
 
-// Sign a bundle.manifest.json file
-const signature = await signManifest("./policies/claims-approval/v1/bundle.manifest.json");
-// Returns base64-encoded Ed25519 signature
-```
+via Node.js native crypto APIs.
 
-### Verification
+Formats:
 
-```typescript
-import { verifySignature, verifyPayloadSignature } from "@parmanasystems/crypto";
+Component	Format
+private keys	PKCS8 DER
+public keys	SPKI DER
+signatures	base64
 
-// Verify a manifest signature
-const ok = await verifySignature(manifestPath, signature);
+No external cryptographic dependencies are required.
 
-// Verify an arbitrary payload
-const ok = verifyPayloadSignature(payload, signature, publicKey);
-// Returns boolean
-```
+AWS KMS Support
 
-### Key persistence
+For HSM-backed signing use:
 
-```typescript
-import { persistKeys } from "@parmanasystems/crypto";
+AwsKmsSigner
 
-await persistKeys(privateKey, publicKey, "./dev-keys");
-// Writes bundle_signing_key and bundle_signing_key.pub
-```
+from:
 
-## Algorithm
+@parmanasystems/execution
 
-All signatures use **Ed25519** via Node.js `crypto.sign` / `crypto.verify`.
+This enables:
 
-- Private keys: PKCS8 DER format
-- Public keys: SPKI DER format
-- Signatures: base64-encoded
+managed signing keys
+cloud HSM integration
+enterprise key governance
+Example Signature Object
+{
+  "signature": "base64-signature",
+  "algorithm": "Ed25519",
+  "signed_at": "2026-05-13T10:00:00Z",
+  "key_id": "runtime-signing-key-v1"
+}
+Recommended Architecture
+Governance Artifact
+        ↓
+Canonical Serialization
+        ↓
+Deterministic Signature
+        ↓
+Portable Verification
+        ↓
+Independent Trust Validation
+Relationship to Other Parmana Packages
+Package	Responsibility
+@parmanasystems/bundle	canonical bytes
+@parmanasystems/crypto	signatures and trust
+@parmanasystems/execution	execution attestations
+@parmanasystems/verifier	proof validation
+@parmanasystems/governance	governance lifecycle
+Security Model
 
-For AWS KMS HSM-backed signing, use `AwsKmsSigner` in `@parmanasystems/execution`.
+The crypto layer guarantees:
 
-## Dev key location
+deterministic signatures
+immutable provenance binding
+portable verification
+independent trust validation
+governance authenticity
+runtime trust integrity
 
-The default dev key path is `./dev-keys/bundle_signing_key{,.pub}` relative to the current working directory. The server and CI scripts fall back to environment variables `Parmana_PRIVATE_KEY` / `Parmana_PUBLIC_KEY` (base64 DER) if these files are absent.
+The package is designed so that:
 
-## License
+trust derives from deterministic cryptographic verification, not runtime assumptions
+Most Important Principle
+Governance decisions are trusted because deterministic artifacts are cryptographically signed and independently verifiable.
+License
 
-Apache-2.0
+Apache-2.0

package/package.json

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