@parmanasystems/crypto 1.0.19

package/README.md

@@ -0,0 +1,84 @@
+# @parmanasystems/crypto
+
+Ed25519 key management, signing, and verification primitives for the parmanasystems governance runtime.
+
+[![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:
+
+- Loading Ed25519 keys from disk or environment variables
+- Signing canonical payloads (returns base64)
+- Verifying Ed25519 signatures
+- Signing and verifying bundle manifests
+
+All operations use Node.js's built-in `crypto` module — no external cryptographic dependencies.
+
+## Installation
+
+```bash
+npm install @parmanasystems/crypto
+```
+
+## API
+
+### Key loading
+
+```typescript
+import { loadPrivateKey, loadPublicKey } from "@parmanasystems/crypto";
+
+// 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
+```
+
+### Signing
+
+```typescript
+import { signManifest } from "@parmanasystems/crypto";
+
+// Sign a bundle.manifest.json file
+const signature = await signManifest("./policies/claims-approval/v1/bundle.manifest.json");
+// Returns base64-encoded Ed25519 signature
+```
+
+### Verification
+
+```typescript
+import { verifySignature, verifyPayloadSignature } from "@parmanasystems/crypto";
+
+// Verify a manifest signature
+const ok = await verifySignature(manifestPath, signature);
+
+// Verify an arbitrary payload
+const ok = verifyPayloadSignature(payload, signature, publicKey);
+// Returns boolean
+```
+
+### Key persistence
+
+```typescript
+import { persistKeys } from "@parmanasystems/crypto";
+
+await persistKeys(privateKey, publicKey, "./dev-keys");
+// Writes bundle_signing_key and bundle_signing_key.pub
+```
+
+## Algorithm
+
+All signatures use **Ed25519** via Node.js `crypto.sign` / `crypto.verify`.
+
+- Private keys: PKCS8 DER format
+- Public keys: SPKI DER format
+- Signatures: base64-encoded
+
+For AWS KMS HSM-backed signing, use `AwsKmsSigner` in `@parmanasystems/execution`.
+
+## Dev key location
+
+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.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Reads the root trust private key PEM.
+ *
+ * Production deployments should inject this
+ * via secure secret management.
+ */
+declare function loadPrivateKey(): string;
+/**
+ * Reads the root trust public key PEM.
+ */
+declare function loadPublicKey(): string;
+
+/**
+ * Writes a base64 signature string to `<directory>/bundle.sig`.
+ * Overwrites any existing file at that path.
+ */
+declare function writeSignature(signature: string, directory: string): void;
+/** Reads and returns the raw base64 signature from `<directory>/bundle.sig`. */
+declare function readSignature(directory: string): string;
+
+/**
+ * Reads the manifest JSON at `manifestPath`, canonicalizes it, and returns a
+ * base64-encoded Ed25519 signature produced with the dev private key.
+ *
+ * @param manifestPath - Absolute or CWD-relative path to a `bundle.manifest.json` file.
+ * @returns Base64-encoded Ed25519 signature over the canonical manifest bytes.
+ */
+declare function signManifest(manifestPath: string): string;
+
+/**
+ * Reads the manifest JSON at `manifestPath`, canonicalizes it, and verifies
+ * `signature` (base64 Ed25519) against the dev public key.
+ *
+ * @param manifestPath - Path to the `bundle.manifest.json` file.
+ * @param signature    - Base64-encoded Ed25519 signature to verify.
+ */
+declare function verifySignature(manifestPath: string, signature: string): boolean;
+/**
+ * Verifies a base64-encoded Ed25519 `signature` over an arbitrary UTF-8
+ * `payload` using the provided `publicKey` PEM.  Unlike `verifySignature`,
+ * this function accepts any payload string rather than reading a manifest
+ * file from disk.
+ *
+ * @param payload   - The original signed UTF-8 string.
+ * @param signature - Base64-encoded Ed25519 signature.
+ * @param publicKey - PEM-encoded Ed25519 public key.
+ */
+declare function verifyPayloadSignature(payload: string, signature: string, publicKey: string): boolean;
+
+/**
+ * Verifies `signature` (base64 Ed25519) over the already-serialized canonical
+ * `manifest` string against the dev public key.
+ *
+ * Unlike `verifySignature`, this function accepts the manifest bytes directly
+ * rather than reading them from disk — suited for in-memory verification flows.
+ *
+ * @param manifest  - Canonical manifest bytes (UTF-8 string).
+ * @param signature - Base64-encoded Ed25519 signature.
+ */
+declare function verifyManifestSignature(manifest: string, signature: string): boolean;
+
+export { loadPrivateKey, loadPublicKey, readSignature, signManifest, verifyManifestSignature, verifyPayloadSignature, verifySignature, writeSignature };

package/dist/index.js

@@ -0,0 +1,149 @@
+// src/keys.ts
+import fs from "fs";
+import path from "path";
+var PRIVATE_KEY_PATH = path.resolve(
+  "./trust/root.key"
+);
+var PUBLIC_KEY_PATH = path.resolve(
+  "./trust/root.pub"
+);
+function loadPrivateKey() {
+  return fs.readFileSync(
+    PRIVATE_KEY_PATH,
+    "utf8"
+  );
+}
+function loadPublicKey() {
+  return fs.readFileSync(
+    PUBLIC_KEY_PATH,
+    "utf8"
+  );
+}
+
+// src/persist.ts
+import fs2 from "fs";
+import path2 from "path";
+function writeSignature(signature, directory) {
+  const signaturePath = path2.join(
+    directory,
+    "bundle.sig"
+  );
+  fs2.writeFileSync(
+    signaturePath,
+    signature,
+    "utf8"
+  );
+}
+function readSignature(directory) {
+  const signaturePath = path2.join(
+    directory,
+    "bundle.sig"
+  );
+  return fs2.readFileSync(
+    signaturePath,
+    "utf8"
+  );
+}
+
+// src/sign.ts
+import fs3 from "fs";
+import crypto from "crypto";
+import {
+  canonicalize
+} from "@parmanasystems/bundle";
+function signManifest(manifestPath) {
+  const manifest = JSON.parse(
+    fs3.readFileSync(
+      manifestPath,
+      "utf8"
+    )
+  );
+  const canonical = canonicalize(
+    manifest
+  );
+  const privateKey = loadPrivateKey();
+  const signature = crypto.sign(
+    null,
+    Buffer.from(
+      canonical,
+      "utf8"
+    ),
+    privateKey
+  );
+  return signature.toString(
+    "base64"
+  );
+}
+
+// src/verify.ts
+import fs4 from "fs";
+import crypto2 from "crypto";
+import {
+  canonicalize as canonicalize2
+} from "@parmanasystems/bundle";
+function verifySignature(manifestPath, signature) {
+  const manifest = JSON.parse(
+    fs4.readFileSync(
+      manifestPath,
+      "utf8"
+    )
+  );
+  const canonical = canonicalize2(
+    manifest
+  );
+  const publicKey = loadPublicKey();
+  return crypto2.verify(
+    null,
+    Buffer.from(
+      canonical,
+      "utf8"
+    ),
+    publicKey,
+    Buffer.from(
+      signature,
+      "base64"
+    )
+  );
+}
+function verifyPayloadSignature(payload, signature, publicKey) {
+  return crypto2.verify(
+    null,
+    Buffer.from(
+      payload,
+      "utf8"
+    ),
+    publicKey,
+    Buffer.from(
+      signature,
+      "base64"
+    )
+  );
+}
+
+// src/verify-manifest-signature.ts
+import crypto3 from "crypto";
+function verifyManifestSignature(manifest, signature) {
+  const publicKey = loadPublicKey();
+  return crypto3.verify(
+    null,
+    Buffer.from(
+      manifest
+    ),
+    publicKey,
+    Buffer.from(
+      signature,
+      "base64"
+    )
+  );
+}
+export {
+  loadPrivateKey,
+  loadPublicKey,
+  readSignature,
+  signManifest,
+  verifyManifestSignature,
+  verifyPayloadSignature,
+  verifySignature,
+  writeSignature
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/keys.ts","../src/persist.ts","../src/sign.ts","../src/verify.ts","../src/verify-manifest-signature.ts"],"sourcesContent":["import fs from \"fs\";\n\nimport path from \"path\";\n\nconst PRIVATE_KEY_PATH =\n  path.resolve(\n    \"./trust/root.key\"\n  );\n\nconst PUBLIC_KEY_PATH =\n  path.resolve(\n    \"./trust/root.pub\"\n  );\n\n/**\n * Reads the root trust private key PEM.\n *\n * Production deployments should inject this\n * via secure secret management.\n */\nexport function loadPrivateKey(): string {\n\n  return fs.readFileSync(\n    PRIVATE_KEY_PATH,\n    \"utf8\"\n  );\n}\n\n/**\n * Reads the root trust public key PEM.\n */\nexport function loadPublicKey(): string {\n\n  return fs.readFileSync(\n    PUBLIC_KEY_PATH,\n    \"utf8\"\n  );\n}","import fs from \"fs\";\nimport path from \"path\";\n\n/**\n * Writes a base64 signature string to `<directory>/bundle.sig`.\n * Overwrites any existing file at that path.\n */\nexport function writeSignature(\n  signature: string,\n  directory: string\n): void {\n  const signaturePath = path.join(\n    directory,\n    \"bundle.sig\"\n  );\n\n  fs.writeFileSync(\n    signaturePath,\n    signature,\n    \"utf8\"\n  );\n}\n\n/** Reads and returns the raw base64 signature from `<directory>/bundle.sig`. */\nexport function readSignature(\n  directory: string\n): string {\n  const signaturePath = path.join(\n    directory,\n    \"bundle.sig\"\n  );\n\n  return fs.readFileSync(\n    signaturePath,\n    \"utf8\"\n  );\n}\n\n\n\n\n","import fs from \"fs\";\n\nimport crypto from \"crypto\";\n\nimport {\n  canonicalize,\n} from \"@parmanasystems/bundle\";\n\nimport {\n  loadPrivateKey,\n} from \"./keys\";\n\n/**\n * Reads the manifest JSON at `manifestPath`, canonicalizes it, and returns a\n * base64-encoded Ed25519 signature produced with the dev private key.\n *\n * @param manifestPath - Absolute or CWD-relative path to a `bundle.manifest.json` file.\n * @returns Base64-encoded Ed25519 signature over the canonical manifest bytes.\n */\nexport function signManifest(\n  manifestPath: string\n): string {\n\n  const manifest =\n    JSON.parse(\n      fs.readFileSync(\n        manifestPath,\n        \"utf8\"\n      )\n    );\n\n  const canonical =\n    canonicalize(\n      manifest\n    );\n\n  const privateKey =\n    loadPrivateKey();\n\n  const signature =\n    crypto.sign(\n      null,\n\n      Buffer.from(\n        canonical,\n        \"utf8\"\n      ),\n\n      privateKey\n    );\n\n  return signature.toString(\n    \"base64\"\n  );\n}\n\n\n\n\n","import fs from \"fs\";\n\nimport crypto from \"crypto\";\n\nimport {\n  canonicalize,\n} from \"@parmanasystems/bundle\";\n\nimport {\n  loadPublicKey,\n} from \"./keys\";\n\n/**\n * Reads the manifest JSON at `manifestPath`, canonicalizes it, and verifies\n * `signature` (base64 Ed25519) against the dev public key.\n *\n * @param manifestPath - Path to the `bundle.manifest.json` file.\n * @param signature    - Base64-encoded Ed25519 signature to verify.\n */\nexport function verifySignature(\n  manifestPath: string,\n  signature: string\n): boolean {\n\n  const manifest =\n    JSON.parse(\n      fs.readFileSync(\n        manifestPath,\n        \"utf8\"\n      )\n    );\n\n  const canonical =\n    canonicalize(\n      manifest\n    );\n\n  const publicKey =\n    loadPublicKey();\n\n  return crypto.verify(\n    null,\n\n    Buffer.from(\n      canonical,\n      \"utf8\"\n    ),\n\n    publicKey,\n\n    Buffer.from(\n      signature,\n      \"base64\"\n    )\n  );\n}\n\n/**\n * Verifies a base64-encoded Ed25519 `signature` over an arbitrary UTF-8\n * `payload` using the provided `publicKey` PEM.  Unlike `verifySignature`,\n * this function accepts any payload string rather than reading a manifest\n * file from disk.\n *\n * @param payload   - The original signed UTF-8 string.\n * @param signature - Base64-encoded Ed25519 signature.\n * @param publicKey - PEM-encoded Ed25519 public key.\n */\nexport function verifyPayloadSignature(\n  payload: string,\n  signature: string,\n  publicKey: string\n): boolean {\n\n  return crypto.verify(\n    null,\n\n    Buffer.from(\n      payload,\n      \"utf8\"\n    ),\n\n    publicKey,\n\n    Buffer.from(\n      signature,\n      \"base64\"\n    )\n  );\n}\n\n\n\n\n","import crypto from \"crypto\";\n\nimport {\n  loadPublicKey,\n} from \"./keys\";\n\n/**\n * Verifies `signature` (base64 Ed25519) over the already-serialized canonical\n * `manifest` string against the dev public key.\n *\n * Unlike `verifySignature`, this function accepts the manifest bytes directly\n * rather than reading them from disk — suited for in-memory verification flows.\n *\n * @param manifest  - Canonical manifest bytes (UTF-8 string).\n * @param signature - Base64-encoded Ed25519 signature.\n */\nexport function verifyManifestSignature(\n  manifest: string,\n  signature: string\n): boolean {\n\n  const publicKey =\n    loadPublicKey();\n\n  return crypto.verify(\n    null,\n\n    Buffer.from(\n      manifest\n    ),\n\n    publicKey,\n\n    Buffer.from(\n      signature,\n      \"base64\"\n    )\n  );\n}\n\n\n\n\n"],"mappings":";AAAA,OAAO,QAAQ;AAEf,OAAO,UAAU;AAEjB,IAAM,mBACJ,KAAK;AAAA,EACH;AACF;AAEF,IAAM,kBACJ,KAAK;AAAA,EACH;AACF;AAQK,SAAS,iBAAyB;AAEvC,SAAO,GAAG;AAAA,IACR;AAAA,IACA;AAAA,EACF;AACF;AAKO,SAAS,gBAAwB;AAEtC,SAAO,GAAG;AAAA,IACR;AAAA,IACA;AAAA,EACF;AACF;;;ACrCA,OAAOA,SAAQ;AACf,OAAOC,WAAU;AAMV,SAAS,eACd,WACA,WACM;AACN,QAAM,gBAAgBA,MAAK;AAAA,IACzB;AAAA,IACA;AAAA,EACF;AAEA,EAAAD,IAAG;AAAA,IACD;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAGO,SAAS,cACd,WACQ;AACR,QAAM,gBAAgBC,MAAK;AAAA,IACzB;AAAA,IACA;AAAA,EACF;AAEA,SAAOD,IAAG;AAAA,IACR;AAAA,IACA;AAAA,EACF;AACF;;;ACpCA,OAAOE,SAAQ;AAEf,OAAO,YAAY;AAEnB;AAAA,EACE;AAAA,OACK;AAaA,SAAS,aACd,cACQ;AAER,QAAM,WACJ,KAAK;AAAA,IACHC,IAAG;AAAA,MACD;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEF,QAAM,YACJ;AAAA,IACE;AAAA,EACF;AAEF,QAAM,aACJ,eAAe;AAEjB,QAAM,YACJ,OAAO;AAAA,IACL;AAAA,IAEA,OAAO;AAAA,MACL;AAAA,MACA;AAAA,IACF;AAAA,IAEA;AAAA,EACF;AAEF,SAAO,UAAU;AAAA,IACf;AAAA,EACF;AACF;;;ACtDA,OAAOC,SAAQ;AAEf,OAAOC,aAAY;AAEnB;AAAA,EACE,gBAAAC;AAAA,OACK;AAaA,SAAS,gBACd,cACA,WACS;AAET,QAAM,WACJ,KAAK;AAAA,IACHC,IAAG;AAAA,MACD;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEF,QAAM,YACJC;AAAA,IACE;AAAA,EACF;AAEF,QAAM,YACJ,cAAc;AAEhB,SAAOC,QAAO;AAAA,IACZ;AAAA,IAEA,OAAO;AAAA,MACL;AAAA,MACA;AAAA,IACF;AAAA,IAEA;AAAA,IAEA,OAAO;AAAA,MACL;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;AAYO,SAAS,uBACd,SACA,WACA,WACS;AAET,SAAOA,QAAO;AAAA,IACZ;AAAA,IAEA,OAAO;AAAA,MACL;AAAA,MACA;AAAA,IACF;AAAA,IAEA;AAAA,IAEA,OAAO;AAAA,MACL;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;;;ACxFA,OAAOC,aAAY;AAgBZ,SAAS,wBACd,UACA,WACS;AAET,QAAM,YACJ,cAAc;AAEhB,SAAOC,QAAO;AAAA,IACZ;AAAA,IAEA,OAAO;AAAA,MACL;AAAA,IACF;AAAA,IAEA;AAAA,IAEA,OAAO;AAAA,MACL;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;","names":["fs","path","fs","fs","fs","crypto","canonicalize","fs","canonicalize","crypto","crypto","crypto"]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@parmanasystems/crypto",
+  "version": "1.0.19",
+  "private": false,
+  "type": "module",
+  "scripts": {
+    "build": "tsup"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@parmanasystems/bundle": "^1.0.19"
+  },
+  "description": "Signing and verification primitives for deterministic governance infrastructure.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pavancharak/parmanasystems-core.git"
+  },
+  "homepage": "https://github.com/pavancharak/parmanasystems-core",
+  "bugs": {
+    "url": "https://github.com/pavancharak/parmanasystems-core/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "crypto",
+    "signing",
+    "verification",
+    "ed25519",
+    "attestation",
+    "governance"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}