zeyra 1.0.1 → 1.1.0

package/README.md

@@ -1,69 +1,113 @@
-# Zeyra
-
-WebCrypto helpers for zero-knowledge–friendly flows: generate AES-GCM + ECDSA keysets as JWKs and wrap them with tiny agent classes for encrypt, decrypt, sign, and verify.
-
-## Features
-- AES-GCM 256 encryption/decryption via `CipherAgent`
-- ECDSA P-256 signing/verification via `SigningAgent` and `VerificationAgent`
-- `generateKeyset()` produces an exportable JWK bundle you can store or transport
-- Pure WebCrypto, no native add-ons; ships as ESM
-- Plays nicely with `bytecodec` for UTF-8 and base64url conversions
-
-## Requirements
-- Node.js 18+ (global `crypto.subtle`)
-- ESM environment (`"type": "module"` in `package.json`)
-
-## Installation
-```bash
-npm install zeyra
-```
-
-## Quickstart
-```js
-import { Bytes } from "bytecodec";
-import {
-  generateKeyset,
-  CipherAgent,
-  SigningAgent,
-  VerificationAgent,
-} from "zeyra";
-
-// One-time key material for a resource
-const { symmetricJwk, privateJwk, publicJwk } = await generateKeyset();
-
-// Writers: encrypt + sign
-const cipher = new CipherAgent(symmetricJwk);
-const signer = new SigningAgent(privateJwk);
-const payload = await cipher.encrypt(Bytes.fromString("hello world"));
-const signature = await signer.sign(payload.ciphertext);
-
-// Readers / servers: verify ownership + decrypt
-const verifier = new VerificationAgent(publicJwk);
-const authorized = await verifier.verify(payload.ciphertext, signature);
-const plaintext = Bytes.toString(await cipher.decrypt(payload));
-```
-
-## API
-- `generateKeyset()` -> `{ symmetricJwk, publicJwk, privateJwk }` (all exportable JWKs)
-- `new CipherAgent(symmetricJwk)`  
-  - `.encrypt(Uint8Array)` -> `{ iv: Uint8Array, ciphertext: ArrayBuffer }`  
-  - `.decrypt({ iv, ciphertext })` -> `Uint8Array`
-- `new SigningAgent(privateJwk)`  
-  - `.sign(Uint8Array | ArrayBuffer)` -> `ArrayBuffer` (ECDSA P-256 / SHA-256)
-- `new VerificationAgent(publicJwk)`  
-  - `.verify(Uint8Array | ArrayBuffer, ArrayBuffer)` -> `boolean`
-
-See the implementations in `src/index.js` and friends for details.
-
-## Testing and benchmarks
-- Run tests: `npm test` (uses Node’s built-in `node:test` runner against `test.js`)
-- Run microbenchmarks (skipped by default): `npm run bench`  
-  - Pass iterations: `npm run bench -- --iterations=500`
-  - Reports ops/sec for encryption and the full encrypt/sign/verify/decrypt pipeline.
-
-## Notes
-- Keys are intentionally exportable to move them between client/storage; encrypt them at rest according to your threat model.
-- AES-GCM already authenticates ciphertext/IV; ECDSA signatures add an explicit ownership check for multi-party flows.
-
-## License
-MIT
+# Zeyra
+
+Managed WebCrypto helpers for storage-ready AES-GCM + ECDSA keysets, with lightweight agents and weakly cached clusters.
+
+## Features
+
+- AES-GCM 256 encryption/decryption via `CipherAgent`
+- ECDSA P-256 signing/verification via `SigningAgent` and `VerificationAgent`
+- Managed clusters (`CipherCluster`, `SigningCluster`, `VerificationCluster`) cache agents with WeakRef for large keysets
+- `generateKeyset()` produces an exportable JWK bundle you can store or transport
+- Storage/transport-ready artifacts with base64url payloads and SHA-256 digests
+- Pure WebCrypto, no native add-ons; ships as ESM
+- Works with `bytecodec` for UTF-8, compression, and base64url conversions
+
+## Requirements
+
+- Node.js 18+ (global `crypto.subtle`)
+- ESM environment (`"type": "module"` in `package.json`)
+
+## Installation
+
+```bash
+npm install zeyra
+```
+
+## Quickstart (agents)
+
+```js
+import { Bytes } from "bytecodec";
+import {
+  generateKeyset,
+  CipherAgent,
+  SigningAgent,
+  VerificationAgent,
+} from "zeyra";
+
+// One-time key material for a resource
+const { symmetricJwk, privateJwk, publicJwk } = await generateKeyset();
+
+// Writers: encrypt + sign
+const cipher = new CipherAgent(symmetricJwk);
+const signer = new SigningAgent(privateJwk);
+const payload = await cipher.encrypt(Bytes.fromString("hello world"));
+const signature = await signer.sign(payload.ciphertext);
+
+// Readers / servers: verify ownership + decrypt
+const verifier = new VerificationAgent(publicJwk);
+const authorized = await verifier.verify(payload.ciphertext, signature);
+const plaintext = Bytes.toString(await cipher.decrypt(payload));
+```
+
+## Managed cluster flow
+
+```js
+import {
+  generateKeyset,
+  CipherCluster,
+  SigningCluster,
+  VerificationCluster,
+} from "zeyra";
+
+const { symmetricJwk, privateJwk, publicJwk } = await generateKeyset();
+
+const resource = { id: "file-123", body: "hello world" };
+const artifact = await CipherCluster.encrypt(symmetricJwk, resource);
+const signature = await SigningCluster.sign(privateJwk, resource.id);
+
+// VerificationCluster is designed to run on a per-resource server node.
+const authorized = await VerificationCluster.verify(
+  publicJwk,
+  resource.id,
+  signature
+);
+
+const decrypted = await CipherCluster.decrypt(symmetricJwk, artifact);
+```
+
+## API
+
+- `generateKeyset()` -> `{ symmetricJwk, publicJwk, privateJwk }` (all exportable JWKs)
+- `new CipherAgent(symmetricJwk)`
+  - `.encrypt(Uint8Array)` -> `{ iv: Uint8Array, ciphertext: ArrayBuffer }`
+  - `.decrypt({ iv, ciphertext })` -> `Uint8Array`
+- `new SigningAgent(privateJwk)`
+  - `.sign(Uint8Array | ArrayBuffer)` -> `ArrayBuffer` (ECDSA P-256 / SHA-256)
+- `new VerificationAgent(publicJwk)`
+  - `.verify(Uint8Array | ArrayBuffer, ArrayBuffer)` -> `boolean`
+- `CipherCluster.encrypt(symmetricJwk, resource)`
+  - -> `{ digest, ciphertext, iv }` (all base64url strings; digest is SHA-256 of JSON bytes, pre-encryption, useful for version checks)
+- `CipherCluster.decrypt(symmetricJwk, artifact)`
+  - -> `{ digest, ...resource }` (resource object restored from compressed JSON)
+- `SigningCluster.sign(privateJwk, value)` -> `Base64URLString`
+- `VerificationCluster.verify(publicJwk, value, signature)` -> `boolean`
+
+See the implementations in `src/index.js` and friends for details.
+
+## Testing and benchmarks
+
+- Run tests: `npm test` (uses Node's built-in `node:test` runner against `test.js`)
+- Run microbenchmarks (skipped by default): `npm run bench`
+  - Pass iterations: `npm run bench -- --iterations=500`
+  - Reports ops/sec for encryption and the full encrypt/sign/verify/decrypt pipeline.
+
+## Notes
+
+- CipherCluster assumes one unique random key per resource (no derivations or shared usage).
+- Cluster classes are intended for client-side usage; `VerificationCluster`/`VerificationAgent` can be hosted per-resource to pre-verify access before downstream identity or ACL checks.
+- Cluster serialization uses JSON and adds a `digest` field; avoid using `digest` in resource objects.
+- WeakRef caching keeps memory usage loose and GC-friendly by design.
+
+## License
+
+MIT

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "zeyra",
-  "version": "1.0.1",
-  "description": "WebCrypto helper for generating JWK keysets plus AES-GCM encryption and ECDSA signing agents.",
+  "version": "1.1.0",
+  "description": "Managed WebCrypto helpers for AES-GCM + ECDSA JWK keysets with storage-ready cluster APIs.",
   "keywords": [
     "webcrypto",
     "aes-gcm",
     "ecdsa",
     "jwk",
     "encryption",
-    "signature"
+    "signature",
+    "cluster",
+    "keyset",
+    "base64url",
+    "compression",
+    "storage",
+    "transport"
   ],
   "license": "MIT",
   "type": "module",
@@ -27,7 +33,7 @@
   },
   "homepage": "https://github.com/jortsupetterson/zeyra#readme",
   "dependencies": {
-    "bytecodec": "^1.2.1"
+    "bytecodec": "^1.3.0"
   },
   "engines": {
     "node": ">=18"

package/src/CipherCluster/class.js

@@ -0,0 +1,57 @@
+import { Bytes } from "bytecodec";
+import { CipherAgent } from "../CipherAgent/class.js";
+
+export class CipherCluster {
+  /** @type {WeakMap<JsonWebKey, WeakRef<CipherAgent>>} */
+  static #agents = new WeakMap();
+
+  /**
+   * @param {JsonWebKey} symmetricJwk
+   * @returns {CipherAgent}
+   */
+  static #loadAgent(symmetricJwk) {
+    const weakRef = CipherCluster.#agents.get(symmetricJwk);
+    /** @type {CipherAgent | undefined} */
+    let agent = weakRef?.deref();
+    if (!agent) {
+      agent = new CipherAgent(symmetricJwk);
+      CipherCluster.#agents.set(symmetricJwk, new WeakRef(agent));
+    }
+    return agent;
+  }
+
+  /**
+   * @param {JsonWebKey} symmetricJwk
+   * @param {any} resource
+   * @returns {Promise<{ digest: Base64URLString, ciphertext: Base64URLString, iv: Base64URLString }>}
+   */
+  static async encrypt(symmetricJwk, resource) {
+    const agent = CipherCluster.#loadAgent(symmetricJwk);
+    const bytes = Bytes.fromJSON(resource);
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    const compressed = await Bytes.toCompressed(bytes);
+    const envelope = await agent.encrypt(compressed);
+    return {
+      digest: Bytes.toBase64UrlString(digest),
+      ciphertext: Bytes.toBase64UrlString(envelope.ciphertext),
+      iv: Bytes.toBase64UrlString(envelope.iv),
+    };
+  }
+
+  /**
+   * @param {JsonWebKey} symmetricJwk
+   * @param {{ digest: Base64URLString, ciphertext: Base64URLString, iv: Base64URLString }} artifact
+   * @returns {Promise<any>}
+   */
+  static async decrypt(symmetricJwk, artifact) {
+    const envelope = {
+      ciphertext: Bytes.fromBase64UrlString(artifact.ciphertext),
+      iv: Bytes.fromBase64UrlString(artifact.iv),
+    };
+    const agent = CipherCluster.#loadAgent(symmetricJwk);
+    const bytes = await agent.decrypt(envelope);
+    const decompressed = await Bytes.fromCompressed(bytes);
+    const resource = Bytes.toJSON(decompressed);
+    return { digest: artifact.digest, ...resource };
+  }
+}

package/src/SigningCluster/class.js

@@ -0,0 +1,34 @@
+import { Bytes } from "bytecodec";
+import { SigningAgent } from "../SigningAgent/class.js";
+
+export class SigningCluster {
+  /** @type {WeakMap<JsonWebKey, WeakRef<SigningAgent>>} */
+  static #agents = new WeakMap();
+
+  /**
+   * @param {JsonWebKey} privateJwk
+   * @returns {SigningAgent}
+   */
+  static #loadAgent(privateJwk) {
+    const weakRef = SigningCluster.#agents.get(privateJwk);
+    /** @type {SigningAgent | undefined} */
+    let agent = weakRef?.deref();
+    if (!agent) {
+      agent = new SigningAgent(privateJwk);
+      SigningCluster.#agents.set(privateJwk, new WeakRef(agent));
+    }
+    return agent;
+  }
+
+  /**
+   * @param {JsonWebKey} privateJwk
+   * @param {any} value
+   * @returns {Promise<Base64URLString>}
+   */
+  static async sign(privateJwk, value) {
+    const agent = SigningCluster.#loadAgent(privateJwk);
+    const bytes = Bytes.fromJSON(value);
+    const signature = await agent.sign(bytes);
+    return Bytes.toBase64UrlString(signature);
+  }
+}

package/src/VerificationCluster/class.js

@@ -0,0 +1,35 @@
+import { Bytes } from "bytecodec";
+import { VerificationAgent } from "../VerificationAgent/class.js";
+
+export class VerificationCluster {
+  /** @type {WeakMap<JsonWebKey, WeakRef<VerificationAgent>>} */
+  static #agents = new WeakMap();
+
+  /**
+   * @param {JsonWebKey} publicJwk
+   * @returns {VerificationAgent}
+   */
+  static #loadAgent(publicJwk) {
+    const weakRef = VerificationCluster.#agents.get(publicJwk);
+    /** @type {VerificationAgent | undefined} */
+    let agent = weakRef?.deref();
+    if (!agent) {
+      agent = new VerificationAgent(publicJwk);
+      VerificationCluster.#agents.set(publicJwk, new WeakRef(agent));
+    }
+    return agent;
+  }
+
+  /**
+   * @param {JsonWebKey} publicJwk
+   * @param {any} value
+   * @param {Base64URLString} signature
+   * @returns {Promise<boolean>}
+   */
+  static async verify(publicJwk, value, signature) {
+    const agent = VerificationCluster.#loadAgent(publicJwk);
+    const valueBytes = Bytes.fromJSON(value);
+    const signatureBytes = Bytes.fromBase64UrlString(signature);
+    return await agent.verify(valueBytes, signatureBytes);
+  }
+}

package/src/index.js

@@ -2,4 +2,15 @@ import { generateKeyset } from "./generateKeyset/index.js";
 import { CipherAgent } from "./CipherAgent/class.js";
 import { SigningAgent } from "./SigningAgent/class.js";
 import { VerificationAgent } from "./VerificationAgent/class.js";
-export { generateKeyset, CipherAgent, SigningAgent, VerificationAgent };
+import { CipherCluster } from "./CipherCluster/class.js";
+import { SigningCluster } from "./SigningCluster/class.js";
+import { VerificationCluster } from "./VerificationCluster/class.js";
+export {
+  generateKeyset,
+  CipherAgent,
+  SigningAgent,
+  VerificationAgent,
+  CipherCluster,
+  SigningCluster,
+  VerificationCluster,
+};