@pulkitsinha007/hybrid-crypto-js 1.2.0 → 1.2.2

package/README.md

@@ -1,32 +1,203 @@
-# Hybrid Crypto dummy set-up
+# @pulkitsinha007/hybrid-crypto-js
 
-This example demonstrates how to use the `hybrid-crypto-js` library in a full-stack Node.js application.
+A robust hybrid encryption library for high-security applications, implementing industry-standard **RSA-OAEP** and **AES-GCM** algorithms. This package is designed to facilitate secure, two-way communication by combining the performance of symmetric encryption with the security of asymmetric key exchange, ensuring the symmetric key is never exposed in its unwrapped form during transit.
 
-## Structure
+## Installation
 
-- **Backend**: A Node.js HTTP server that manages its own RSA key pair, exposes its Public Key, and handles decryption of client messages and encryption of secret messages for clients.
-- **Frontend**: A simple HTML/JS page that generates a client-side RSA key pair, fetches the server's Public Key, and demonstrates secure 2-way communication.
+```bash
+npm install @pulkitsinha007/hybrid-crypto-js
+```
 
-## Running the Example
+## Overview
 
-1. Ensure you are in the root of the repository.
-2. Run the server:
-   ```bash
-   node examples/full-stack/backend/server.js
-   ```
-3. Open your browser and navigate to:
-   [http://localhost:3000](http://localhost:3000)
+This package is ideal for scenarios requiring end-to-end encryption where:
+- **High Security** is paramount (e.g., financial data, personal identifiable information).
+- **Industry Standards** must be met (utilizing native Web Crypto API and Node.js Crypto).
+- **Two-way Communication** is needed, allowing the server to respond securely using the same session key established by the client.
 
-## How it works
+## API Documentation
 
-1. **Client -> Server Encryption**:
-   - The Client fetches the Server's Public Key.
-   - The Client encrypts a message using `encrypt(message, serverPublicKey)`.
-   - The Client sends the encrypted package to the Server.
-   - The Server decrypts it using its Private Key.
+### `generateKeyPair()`
+Generates a new RSA-OAEP key pair (2048-bit).
+- **Returns**: `Promise<{publicKey: string, privateKey: string}>` (Base64 encoded)
 
-2. **Server -> Client Encryption**:
-   - The Client sends its Public Key to the Server.
-   - The Server encrypts a message using `encrypt(message, clientPublicKey)`.
-   - The Server sends the encrypted package to the Client.
-   - The Client decrypts it using its Private Key.
+```javascript
+import { generateKeyPair } from '@pulkitsinha007/hybrid-crypto-js';
+
+const { publicKey, privateKey } = await generateKeyPair();
+console.log('Public Key:', publicKey);
+```
+
+### `createSymmetricKey()`
+Generates a random AES-GCM symmetric key (256-bit).
+- **Returns**: `Promise<CryptoKey>`
+
+```javascript
+import { createSymmetricKey } from '@pulkitsinha007/hybrid-crypto-js';
+
+const sessionKey = await createSymmetricKey();
+```
+
+### `wrapKey(key, publicKey)`
+Encrypts (wraps) a symmetric key using an RSA public key.
+- **Parameters**:
+  - `key`: `CryptoKey` - The symmetric key to wrap.
+  - `publicKey`: `string` - The RSA public key (Base64).
+- **Returns**: `Promise<string>` (Base64 encoded wrapped key)
+
+```javascript
+import { wrapKey } from '@pulkitsinha007/hybrid-crypto-js';
+
+const wrappedKey = await wrapKey(sessionKey, serverPublicKey);
+```
+
+### `unwrapKey(wrappedKey, privateKey)`
+Decrypts (unwraps) a symmetric key using an RSA private key.
+- **Parameters**:
+  - `wrappedKey`: `string` - The wrapped key (Base64).
+  - `privateKey`: `string` - The RSA private key (Base64).
+- **Returns**: `Promise<CryptoKey>`
+
+```javascript
+import { unwrapKey } from '@pulkitsinha007/hybrid-crypto-js';
+
+const sessionKey = await unwrapKey(wrappedKey, serverPrivateKey);
+```
+
+### `encryptWithSymmetricKey(data, key)`
+Encrypts data using an AES symmetric key.
+- **Parameters**:
+  - `data`: `string | object` - The payload to encrypt.
+  - `key`: `CryptoKey` - The AES key.
+- **Returns**: `Promise<{encryptedData: string, iv: string}>`
+
+```javascript
+import { encryptWithSymmetricKey } from '@pulkitsinha007/hybrid-crypto-js';
+
+const { encryptedData, iv } = await encryptWithSymmetricKey({ msg: "Hello" }, sessionKey);
+```
+
+### `decryptWithSymmetricKey(encryptedPackage, key)`
+Decrypts data using an AES symmetric key.
+- **Parameters**:
+  - `encryptedPackage`: `{encryptedData: string, iv: string}`.
+  - `key`: `CryptoKey`.
+- **Returns**: `Promise<string | object>`
+
+```javascript
+import { decryptWithSymmetricKey } from '@pulkitsinha007/hybrid-crypto-js';
+
+const data = await decryptWithSymmetricKey({ encryptedData, iv }, sessionKey);
+```
+
+---
+
+## Backend Setup (Dummy Application)
+
+This section demonstrates how to set up a simple backend (e.g., using Node.js/Express) that generates an RSA key pair on startup and handles secure requests.
+
+```javascript
+import http from 'http';
+import {
+    generateKeyPair,
+    unwrapKey,
+    decryptWithSymmetricKey,
+    encryptWithSymmetricKey
+} from '@pulkitsinha007/hybrid-crypto-js';
+
+let publicKey, privateKey;
+
+// 1. Generate RSA Keys on Startup
+(async () => {
+    const keys = await generateKeyPair();
+    publicKey = keys.publicKey;
+    privateKey = keys.privateKey;
+    console.log('Server keys ready.');
+})();
+
+const server = http.createServer(async (req, res) => {
+    // 2. Expose Public Key Endpoint
+    if (req.url === '/api/public-key' && req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ publicKey }));
+        return;
+    }
+
+    // 3. Handle Secure Submission
+    if (req.url === '/api/submit' && req.method === 'POST') {
+        let body = '';
+        req.on('data', chunk => body += chunk);
+        req.on('end', async () => {
+            try {
+                const { wrappedKey, encryptedPackage } = JSON.parse(body);
+
+                // A. Unwrap the session key using Server Private Key
+                const sessionKey = await unwrapKey(wrappedKey, privateKey);
+
+                // B. Decrypt the client's message
+                const decryptedData = await decryptWithSymmetricKey(encryptedPackage, sessionKey);
+                console.log('Received:', decryptedData);
+
+                // C. Process data and prepare response
+                const responseData = { status: 'received', timestamp: Date.now() };
+
+                // D. Encrypt response using the SAME session key
+                const encryptedResponse = await encryptWithSymmetricKey(responseData, sessionKey);
+
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ encryptedResponse }));
+            } catch (err) {
+                res.writeHead(500);
+                res.end(JSON.stringify({ error: err.message }));
+            }
+        });
+    }
+});
+
+server.listen(3000, () => console.log('Server running on port 3000'));
+```
+
+## Frontend Setup
+
+This section demonstrates the client-side logic to establish a secure session.
+
+```javascript
+import {
+    createSymmetricKey,
+    wrapKey,
+    encryptWithSymmetricKey,
+    decryptWithSymmetricKey
+} from '@pulkitsinha007/hybrid-crypto-js';
+
+async function sendSecureMessage(message) {
+    // 1. Fetch Server Public Key
+    const res = await fetch('http://localhost:3000/api/public-key');
+    const { publicKey } = await res.json();
+
+    // 2. Create a fresh Session Key (AES)
+    const sessionKey = await createSymmetricKey();
+
+    // 3. Wrap (Encrypt) the Session Key with Server's Public Key
+    const wrappedKey = await wrapKey(sessionKey, publicKey);
+
+    // 4. Encrypt the payload with the Session Key
+    const encryptedPackage = await encryptWithSymmetricKey(message, sessionKey);
+
+    // 5. Send both to the server
+    const postRes = await fetch('http://localhost:3000/api/submit', {
+        method: 'POST',
+        body: JSON.stringify({
+            wrappedKey,
+            encryptedPackage
+        })
+    });
+
+    // 6. Receive and Decrypt Response (using the same Session Key)
+    const { encryptedResponse } = await postRes.json();
+    const responseData = await decryptWithSymmetricKey(encryptedResponse, sessionKey);
+
+    console.log('Server Response:', responseData);
+}
+
+sendSecureMessage({ hello: "world" });
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulkitsinha007/hybrid-crypto-js",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Hybrid encryption package using native crypto modules for Node and Browser",
   "type": "module",
   "main": "src/index.js",

package/src/crypto.js

@@ -176,36 +176,4 @@ export async function unwrapKey(wrappedKey, privateKey) {
   );
 
   return key;
-}
-
-/**
- * Encrypts data using hybrid encryption (Generates new AES key).
- * @param {string|object} data - The payload to encrypt.
- * @param {string} publicKey - The backend's public RSA key (Base64).
- * @returns {Promise<{encryptedData: string, encryptedKey: string, iv: string}>}
- */
-export async function encrypt(data, publicKey) {
-  const aesKey = await createSymmetricKey();
-  const { encryptedData, iv } = await encryptWithSymmetricKey(data, aesKey);
-  const encryptedKey = await wrapKey(aesKey, publicKey); // Reusing wrapKey
-
-  return {
-    encryptedData,
-    encryptedKey,
-    iv
-  };
-}
-
-/**
- * Decrypts data using hybrid encryption.
- * @param {object} encryptedPackage - The encrypted package { encryptedData, encryptedKey, iv }.
- * @param {string} privateKey - The backend's private RSA key (Base64).
- * @returns {Promise<string|object>} The decrypted payload.
- */
-export async function decrypt(encryptedPackage, privateKey) {
-  const { encryptedData, encryptedKey, iv } = encryptedPackage;
-
-  const aesKey = await unwrapKey(encryptedKey, privateKey); // Reusing unwrapKey
-
-  return await decryptWithSymmetricKey({ encryptedData, iv }, aesKey);
-}
+}

package/src/index.d.ts

@@ -91,27 +91,4 @@ export function wrapKey(key: CryptoKey, publicKey: string): Promise<string>;
  * @param privateKey - The RSA private key (Base64).
  * @returns The unwrapped AES key.
  */
-export function unwrapKey(wrappedKey: string, privateKey: string): Promise<CryptoKey>;
-
-/**
- * Encrypts data using hybrid encryption (Generates new AES key).
- * @param data - The payload to encrypt.
- * @param publicKey - The backend's public RSA key (Base64).
- */
-export function encrypt(data: string | object, publicKey: string): Promise<{
-    encryptedData: string;
-    encryptedKey: string;
-    iv: string;
-}>;
-
-/**
- * Decrypts data using hybrid encryption.
- * @param encryptedPackage - The encrypted package { encryptedData, encryptedKey, iv }.
- * @param privateKey - The backend's private RSA key (Base64).
- * @returns The decrypted payload.
- */
-export function decrypt<T = any>(encryptedPackage: {
-    encryptedData: string;
-    encryptedKey: string;
-    iv: string;
-}, privateKey: string): Promise<T>;
+export function unwrapKey(wrappedKey: string, privateKey: string): Promise<CryptoKey>;

package/src/index.js

@@ -1,7 +1,5 @@
 export {
   generateKeyPair,
-  encrypt,
-  decrypt,
   createSymmetricKey,
   encryptWithSymmetricKey,
   decryptWithSymmetricKey,

package/src/utils.js

@@ -1,77 +1,77 @@
-// Utility functions for Hybrid Crypto Package
-
-/**
- * Converts a string to an ArrayBuffer using TextEncoder.
- * @param {string} str - The string to convert.
- * @returns {ArrayBuffer} The resulting ArrayBuffer.
- */
-export function str2ab(str) {
-  return new TextEncoder().encode(str);
-}
-
-/**
- * Converts an ArrayBuffer to a string using TextDecoder.
- * @param {ArrayBuffer} buf - The buffer to convert.
- * @returns {string} The resulting string.
- */
-export function ab2str(buf) {
-  return new TextDecoder().decode(buf);
-}
-
-/**
- * Converts an ArrayBuffer to a Base64 string.
- * @param {ArrayBuffer} buf - The buffer to convert.
- * @returns {string} Base64 string.
- */
-export function arrayBufferToBase64(buf) {
-  let binary = '';
-  const bytes = new Uint8Array(buf);
-  const len = bytes.byteLength;
-  for (let i = 0; i < len; i++) {
-    binary += String.fromCharCode(bytes[i]);
-  }
-  return btoa(binary);
-}
-
-/**
- * Converts a Base64 string to an ArrayBuffer.
- * @param {string} base64 - The Base64 string.
- * @returns {ArrayBuffer} The resulting ArrayBuffer.
- */
-export function base64ToArrayBuffer(base64) {
-  const binaryString = atob(base64);
-  const len = binaryString.length;
-  const bytes = new Uint8Array(len);
-  for (let i = 0; i < len; i++) {
-    bytes[i] = binaryString.charCodeAt(i);
-  }
-  return bytes.buffer;
-}
-
-/**
- * Converts a PEM formatted string to an ArrayBuffer.
- * @param {string} pem - The PEM string.
- * @returns {ArrayBuffer} The raw key data.
- */
-export function pemToArrayBuffer(pem) {
-  // Remove headers, footers, and newlines
-  const b64 = pem
-    .replace(/-----BEGIN [^-]+-----/, '')
-    .replace(/-----END [^-]+-----/, '')
-    .replace(/\s/g, ''); // Removes all whitespace including newlines
-  return base64ToArrayBuffer(b64);
-}
-
-/**
- * Converts an ArrayBuffer to a PEM formatted string.
- * @param {ArrayBuffer} buf - The raw key data.
- * @param {string} type - The key type (e.g., 'PUBLIC KEY', 'PRIVATE KEY').
- * @returns {string} The PEM string.
- */
-export function arrayBufferToPem(buf, type) {
-  const b64 = arrayBufferToBase64(buf);
-  const pemString = `-----BEGIN ${type}-----\n` +
-    b64.match(/.{1,64}/g).join('\n') +
-    `\n-----END ${type}-----\n`;
-  return pemString;
-}
+// Utility functions for Hybrid Crypto Package
+
+/**
+ * Converts a string to an ArrayBuffer using TextEncoder.
+ * @param {string} str - The string to convert.
+ * @returns {ArrayBuffer} The resulting ArrayBuffer.
+ */
+export function str2ab(str) {
+  return new TextEncoder().encode(str);
+}
+
+/**
+ * Converts an ArrayBuffer to a string using TextDecoder.
+ * @param {ArrayBuffer} buf - The buffer to convert.
+ * @returns {string} The resulting string.
+ */
+export function ab2str(buf) {
+  return new TextDecoder().decode(buf);
+}
+
+/**
+ * Converts an ArrayBuffer to a Base64 string.
+ * @param {ArrayBuffer} buf - The buffer to convert.
+ * @returns {string} Base64 string.
+ */
+export function arrayBufferToBase64(buf) {
+  let binary = '';
+  const bytes = new Uint8Array(buf);
+  const len = bytes.byteLength;
+  for (let i = 0; i < len; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Converts a Base64 string to an ArrayBuffer.
+ * @param {string} base64 - The Base64 string.
+ * @returns {ArrayBuffer} The resulting ArrayBuffer.
+ */
+export function base64ToArrayBuffer(base64) {
+  const binaryString = atob(base64);
+  const len = binaryString.length;
+  const bytes = new Uint8Array(len);
+  for (let i = 0; i < len; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+
+/**
+ * Converts a PEM formatted string to an ArrayBuffer.
+ * @param {string} pem - The PEM string.
+ * @returns {ArrayBuffer} The raw key data.
+ */
+export function pemToArrayBuffer(pem) {
+  // Remove headers, footers, and newlines
+  const b64 = pem
+    .replace(/-----BEGIN [^-]+-----/, '')
+    .replace(/-----END [^-]+-----/, '')
+    .replace(/\s/g, ''); // Removes all whitespace including newlines
+  return base64ToArrayBuffer(b64);
+}
+
+/**
+ * Converts an ArrayBuffer to a PEM formatted string.
+ * @param {ArrayBuffer} buf - The raw key data.
+ * @param {string} type - The key type (e.g., 'PUBLIC KEY', 'PRIVATE KEY').
+ * @returns {string} The PEM string.
+ */
+export function arrayBufferToPem(buf, type) {
+  const b64 = arrayBufferToBase64(buf);
+  const pemString = `-----BEGIN ${type}-----\n` +
+    b64.match(/.{1,64}/g).join('\n') +
+    `\n-----END ${type}-----\n`;
+  return pemString;
+}