@parmanasystems/crypto 1.69.0 → 1.71.2

package/README.md

@@ -1,425 +1,84 @@
 # @parmanasystems/crypto
 
-Cryptographic signing and verification infrastructure for deterministic governance artifacts and execution attestations.
+Ed25519 signing and verification primitives for governance artifacts.
 
 [![npm](https://img.shields.io/npm/v/@parmanasystems/crypto)](https://www.npmjs.com/package/@parmanasystems/crypto)
 
 ---
 
-# Overview
+## Overview
 
-`@parmanasystems/crypto` provides the cryptographic trust infrastructure for the Parmana Systems governance ecosystem.
+`@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.
 
-It is responsible for:
-
-- Ed25519 signing
-- deterministic signature verification
-- governance trust roots
-- bundle signature validation
-- execution attestation signing
-- runtime provenance verification
-- cryptographic governance authority
-
-All governance trust in Parmana derives from deterministic cryptographic verification.
-
-Governance decisions are trusted because deterministic artifacts are cryptographically signed and independently verifiable.
+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.
 
 ---
 
-# 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:
+## Install
 
-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
+```bash
 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.
-
-import {
-  persistKeys
-} from "@parmanasystems/crypto";
-
-await persistKeys(
-  privateKey,
-  publicKey,
-  "./dev-keys"
-);
+---
 
-Generated files:
+## Usage
 
-bundle_signing_key
-bundle_signing_key.pub
-Algorithms
+```typescript
+import { signBundle, loadPublicKey } from "@parmanasystems/crypto";
+import { LocalSigner } from "@parmanasystems/execution";
+import crypto from "crypto";
 
-The package uses:
+const { privateKey } = crypto.generateKeyPairSync("ed25519", {
+  privateKeyEncoding: { type: "pkcs8", format: "pem" },
+  publicKeyEncoding:  { type: "spki",  format: "pem" },
+});
 
-Ed25519
+const signer = new LocalSigner(privateKey);
 
-via Node.js native crypto APIs.
+// Sign a built bundle directory — writes bundle.sig next to bundle.manifest.json
+await signBundle({
+  bundlePath: "./dist/bundles/loan-approval",
+  signer,
+});
+```
 
-Formats:
+### Sign a manifest file directly
 
-Component	Format
-private keys	PKCS8 DER
-public keys	SPKI DER
-signatures	base64
+```typescript
+import { signManifest } from "@parmanasystems/crypto";
 
-No external cryptographic dependencies are required.
+// Reads bundle.manifest.json, canonicalizes, signs with trust root key from disk
+const signature = signManifest("./dist/bundles/loan-approval/bundle.manifest.json");
+console.log(signature); // base64-encoded Ed25519 signature
+```
 
-AWS KMS Support
+---
 
-For HSM-backed signing use:
+## Exports
 
-AwsKmsSigner
+| 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` |
 
-from:
+---
 
-@parmanasystems/execution
+## Trust root key location
 
-This enables:
+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.
 
-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
+---
 
-The crypto layer guarantees:
+## Documentation
 
-deterministic signatures
-immutable provenance binding
-portable verification
-independent trust validation
-governance authenticity
-runtime trust integrity
+Full docs: [parmanasystems.mintlify.app](https://parmanasystems.mintlify.app)
+Package page: [parmanasystems.mintlify.app/packages/crypto](https://parmanasystems.mintlify.app/packages/crypto)
 
-The package is designed so that:
+---
 
-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
+## License
 
-Apache-2.0
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parmanasystems/crypto",
-  "version": "1.69.0",
+  "version": "1.71.2",
   "private": false,
   "type": "module",
   "scripts": {
@@ -18,7 +18,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@parmanasystems/bundle": "^1.69.0"
+    "@parmanasystems/bundle": "^1.71.2"
   },
   "description": "Signing and verification primitives for deterministic governance infrastructure.",
   "license": "Apache-2.0",
@@ -26,7 +26,7 @@
     "type": "git",
     "url": "https://github.com/pavancharak/parmanasystems-core.git"
   },
-  "homepage": "https://github.com/pavancharak/parmanasystems-core",
+  "homepage": "https://parmanasystems.mintlify.app",
   "bugs": {
     "url": "https://github.com/pavancharak/parmanasystems-core/issues"
   },