zeyra 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 zeyra contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# 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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "zeyra",
+  "version": "1.0.0",
+  "description": "WebCrypto helper for generating JWK keysets plus AES-GCM encryption and ECDSA signing agents.",
+  "main": "src/index.js",
+  "keywords": [
+    "webcrypto",
+    "aes-gcm",
+    "ecdsa",
+    "jwk",
+    "encryption",
+    "signature"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "test": "node --test test.js",
+    "bench": "node test.js --bench",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "bytecodec": "^1.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false
+}

package/src/CipherAgent/class.js

@@ -0,0 +1,43 @@
+export class CipherAgent {
+  /**
+   * @param {JsonWebKey} symmetricJwk  // AES-GCM (kty:"oct", alg:"A256GCM")
+   */
+  constructor(symmetricJwk) {
+    this.keyPromise = crypto.subtle.importKey(
+      "jwk",
+      symmetricJwk,
+      { name: "AES-GCM" },
+      false,
+      ["encrypt", "decrypt"]
+    );
+  }
+
+  /**
+   * @param {Uint8Array} plaintext
+   * @returns {Promise<{ iv: Uint8Array, ciphertext: ArrayBuffer }>}
+   */
+  async encrypt(plaintext) {
+    const key = await this.keyPromise;
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ciphertext = await crypto.subtle.encrypt(
+      { name: "AES-GCM", iv },
+      key,
+      plaintext
+    );
+    return { iv, ciphertext };
+  }
+
+  /**
+   * @param {{ iv: Uint8Array, ciphertext: ArrayBuffer }} payload
+   * @returns {Promise<Uint8Array>}
+   */
+  async decrypt({ iv, ciphertext }) {
+    const key = await this.keyPromise;
+    const plaintext = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv },
+      key,
+      ciphertext
+    );
+    return new Uint8Array(plaintext);
+  }
+}

package/src/SigningAgent/class.js

@@ -0,0 +1,23 @@
+export class SigningAgent {
+  /**
+   * @param {JsonWebKey} privateJwk // ECDSA P-256 private key
+   */
+  constructor(privateJwk) {
+    this.keyPromise = crypto.subtle.importKey(
+      "jwk",
+      privateJwk,
+      { name: "ECDSA", namedCurve: "P-256" },
+      false,
+      ["sign"]
+    );
+  }
+
+  /**
+   * @param {Uint8Array} bytes
+   * @returns {Promise<ArrayBuffer>}
+   */
+  async sign(bytes) {
+    const key = await this.keyPromise;
+    return crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, key, bytes);
+  }
+}

package/src/VerificationAgent/class.js

@@ -0,0 +1,29 @@
+export class VerificationAgent {
+  /**
+   * @param {JsonWebKey} publicJwk // ECDSA P-256 public key
+   */
+  constructor(publicJwk) {
+    this.keyPromise = crypto.subtle.importKey(
+      "jwk",
+      publicJwk,
+      { name: "ECDSA", namedCurve: "P-256" },
+      false,
+      ["verify"]
+    );
+  }
+
+  /**
+   * @param {Uint8Array} bytes
+   * @param {ArrayBuffer} signature
+   * @returns {Promise<boolean>}
+   */
+  async verify(bytes, signature) {
+    const key = await this.keyPromise;
+    return crypto.subtle.verify(
+      { name: "ECDSA", hash: "SHA-256" },
+      key,
+      signature,
+      bytes
+    );
+  }
+}

package/src/generateKeyset/index.js

@@ -0,0 +1,36 @@
+/**
+ * Generates a cryptographic keyset for a single resource.
+ *
+ * Returned keys:
+ * - symmetricJwk: AES-GCM 256-bit key (JWK, kty:"oct") for encrypt/decrypt
+ * - publicJwk: ECDSA P-256 public key (JWK) for verify
+ * - privateJwk: ECDSA P-256 private key (JWK) for sign
+ *
+ * All keys are extractable and intended to be stored encrypted
+ * or transported as data. Type definitions are expected to live
+ * in a separate TypeScript types file.
+ *
+ * @returns {Promise<{
+ *   symmetricJwk: JsonWebKey,
+ *   publicJwk: JsonWebKey,
+ *   privateJwk: JsonWebKey
+ * }>}
+ */
+export async function generateKeyset() {
+  const aesKey = await crypto.subtle.generateKey(
+    { name: "AES-GCM", length: 256 },
+    true,
+    ["encrypt", "decrypt"]
+  );
+  const symmetricJwk = await crypto.subtle.exportKey("jwk", aesKey);
+
+  const keyPair = await crypto.subtle.generateKey(
+    { name: "ECDSA", namedCurve: "P-256" },
+    true,
+    ["sign", "verify"]
+  );
+  const publicJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
+  const privateJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
+
+  return { symmetricJwk, publicJwk, privateJwk };
+}

package/src/index.js

@@ -0,0 +1,5 @@
+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 };