underpost 2.8.878 → 2.8.882

package/src/server/valkey.js

@@ -1,3 +1,9 @@
+/**
+ * Module for managing Valkey
+ * @module src/server/valkey.js
+ * @namespace Valkey
+ */
+
 import Valkey from 'iovalkey';
 import mongoose from 'mongoose';
 import { hashPassword } from './auth.js';
@@ -10,11 +16,35 @@ const ValkeyInstances = {};
 const DummyStores = {}; // in-memory Maps per instance
 const ValkeyStatus = {}; // 'connected' | 'dummy' | 'error' | undefined
 
-// Backward-compatible overall flag: true if any instance is connected
+/**
+ * Checks if any Valkey instance is connected.
+ * This is a backward-compatible overall flag.
+ * @returns {boolean} True if any instance has a 'connected' status.
+ * @memberof Valkey
+ */
 const isValkeyEnable = () => Object.values(ValkeyStatus).some((s) => s === 'connected');
 
+/**
+ * Generates a unique key for a Valkey instance based on its host and path.
+ * @param {object} [opts={ host: '', path: '' }] - The instance options.
+ * @param {string} [opts.host=''] - The host of the instance.
+ * @param {string} [opts.path=''] - The path of the instance.
+ * @returns {string} The instance key.
+ * @private
+ * @memberof Valkey
+ */
 const _instanceKey = (opts = { host: '', path: '' }) => `${opts.host || ''}${opts.path || ''}`;
 
+/**
+ * Creates and manages a connection to a Valkey server for a given instance.
+ * It sets up a client, attaches event listeners for connection status, and implements a fallback to an in-memory dummy store if the connection fails.
+ * @param {object} [instance={ host: '', path: '' }] - The instance identifier.
+ * @param {string} [instance.host=''] - The host of the instance.
+ * @param {string} [instance.path=''] - The path of the instance.
+ * @param {object} [valkeyServerConnectionOptions={ host: '', path: '' }] - Connection options for the iovalkey client.
+ * @returns {Promise<Valkey|undefined>} A promise that resolves to the Valkey client instance, or undefined if creation fails.
+ * @memberof Valkey
+ */
 const createValkeyConnection = async (
   instance = { host: '', path: '' },
   valkeyServerConnectionOptions = { host: '', path: '' },
@@ -72,6 +102,14 @@ const createValkeyConnection = async (
   return ValkeyInstances[key];
 };
 
+/**
+ * Factory function to create a Data Transfer Object (DTO) from a payload.
+ * It filters the payload to include only the keys specified in the `select` object.
+ * @param {object} payload - The source object.
+ * @param {object} select - An object where keys are field names and values are 1 to include them.
+ * @returns {object} A new object containing only the selected fields from the payload.
+ * @memberof Valkey
+ */
 const selectDtoFactory = (payload, select) => {
   const result = {};
   for (const key of Object.keys(select)) {
@@ -80,6 +118,12 @@ const selectDtoFactory = (payload, select) => {
   return result;
 };
 
+/**
+ * Factory function to create a new Valkey client instance.
+ * @param {object} options - Connection options for the iovalkey client.
+ * @returns {Promise<Valkey>} A promise that resolves to a new Valkey client.
+ * @memberof Valkey
+ */
 const valkeyClientFactory = async (options) => {
   const valkey = new Valkey({
     port: options?.port ? options.port : undefined,
@@ -103,6 +147,15 @@ const valkeyClientFactory = async (options) => {
   return valkey;
 };
 
+/**
+ * Retrieves an object from Valkey by key for a specific instance.
+ * If the Valkey client is not connected or an error occurs, it falls back to the dummy in-memory store.
+ * It automatically parses JSON strings.
+ * @param {object} [options={ host: '', path: '' }] - The instance identifier.
+ * @param {string} [key=''] - The key of the object to retrieve.
+ * @returns {Promise<object|string|null>} A promise that resolves to the retrieved object, string, or null if not found.
+ * @memberof Valkey
+ */
 const getValkeyObject = async (options = { host: '', path: '' }, key = '') => {
   const k = _instanceKey(options);
   const status = ValkeyStatus[k];
@@ -124,6 +177,16 @@ const getValkeyObject = async (options = { host: '', path: '' }, key = '') => {
   return DummyStores[k]?.get(key) ?? null;
 };
 
+/**
+ * Sets an object or string in Valkey for a specific instance.
+ * If the Valkey client is not connected, it writes to the in-memory dummy store instead.
+ * Objects are automatically stringified.
+ * @param {object} [options={ host: '', path: '' }] - The instance identifier.
+ * @param {string} [key=''] - The key under which to store the payload.
+ * @param {object|string} [payload={}] - The data to store.
+ * @returns {Promise<string>} A promise that resolves to 'OK' on success.
+ * @memberof Valkey
+ */
 const setValkeyObject = async (options = { host: '', path: '' }, key = '', payload = {}) => {
   const k = _instanceKey(options);
   const isString = typeof payload === 'string';
@@ -141,6 +204,16 @@ const setValkeyObject = async (options = { host: '', path: '' }, key = '', paylo
   return 'OK';
 };
 
+/**
+ * Updates an existing object in Valkey by merging it with a new payload.
+ * It retrieves the current object, merges it with the new payload, and sets the updated object back.
+ * It also updates the `updatedAt` timestamp.
+ * @param {object} [options={ host: '', path: '' }] - The instance identifier.
+ * @param {string} [key=''] - The key of the object to update.
+ * @param {object} [payload={}] - The new data to merge into the object.
+ * @returns {Promise<string>} A promise that resolves to the result of the set operation.
+ * @memberof Valkey
+ */
 const updateValkeyObject = async (options = { host: '', path: '' }, key = '', payload = {}) => {
   let base = await getValkeyObject(options, key);
   if (typeof base !== 'object' || base === null) base = {};
@@ -148,6 +221,17 @@ const updateValkeyObject = async (options = { host: '', path: '' }, key = '', pa
   return await setValkeyObject(options, key, { ...base, ...payload });
 };
 
+/**
+ * Factory function to create a new object based on a model schema.
+ * It generates a new object with default properties like `_id`, `createdAt`, and `updatedAt`,
+ * and model-specific properties.
+ * @param {object} [options={ host: 'localhost', path: '', object: {} }] - Options for object creation.
+ * @param {string} [options.host='localhost'] - The host context for the object.
+ * @param {object} [options.object={}] - An initial object to extend.
+ * @param {string} [model=''] - The name of the model schema to use (e.g., 'user').
+ * @returns {Promise<object>} A promise that resolves to the newly created object.
+ * @memberof Valkey
+ */
 const valkeyObjectFactory = async (options = { host: 'localhost', path: '', object: {} }, model = '') => {
   const idoDate = new Date().toISOString();
   options.object = options.object || {};
@@ -181,6 +265,10 @@ const valkeyObjectFactory = async (options = { host: 'localhost', path: '', obje
   }
 };
 
+/**
+ * A collection of Valkey-related API functions.
+ * @type {object}
+ */
 const ValkeyAPI = {
   valkeyClientFactory,
   selectDtoFactory,

package/test/crypto.test.js

@@ -0,0 +1,117 @@
+/**
+ * @module crypto.test
+ * @description Unit tests for SymmetricCrypto and AsymmetricCrypto classes
+ * in the crypto module.
+ * * Uses 'chai' for assertions.
+ */
+
+// Import Chai's assertion library
+import { expect } from 'chai';
+
+// Import the cryptographic classes from the Canvas's refactored module
+import { SymmetricCrypto, AsymmetricCrypto } from '../src/server/crypto.js';
+
+// Define a common plaintext message for testing
+const plaintext = 'This is a secret message for testing cryptographic operations.';
+
+// --- Main Test Suite ---
+
+describe('Crypto Module Tests', () => {
+  // --- SymmetricCrypto Tests (AES-256-CBC) ---
+  describe('SymmetricCrypto (AES-256-CBC)', () => {
+    /**
+     * Test case: Verify that key and IV are automatically generated.
+     */
+    it('should generate new 32-byte key and 16-byte IV if none are provided', () => {
+      const symm = new SymmetricCrypto();
+      // Key should be 32 bytes (64 hex characters) and IV 16 bytes (32 hex characters)
+      expect(symm.encryptionKeyHex).to.be.a('string').and.have.lengthOf(64);
+      expect(symm.ivHex).to.be.a('string').and.have.lengthOf(32);
+    });
+
+    /**
+     * Test case: Encrypt data and ensure successful decryption back to the original plaintext.
+     */
+    it('should encrypt and successfully decrypt data', () => {
+      const symm = new SymmetricCrypto();
+      const ciphertext = symm.encryptData(plaintext);
+
+      // Ciphertext should contain IV and the encrypted data, separated by a colon
+      expect(ciphertext).to.include(':');
+
+      const decryptedText = symm.decryptData(ciphertext);
+      expect(decryptedText).to.equal(plaintext);
+    });
+
+    /**
+     * Test case: Verify that decryption fails gracefully if the ciphertext is tampered with (e.g., corrupting the encrypted payload).
+     *
+     * FIX: We now reliably tamper with the encrypted hex string by removing the last character.
+     * This ensures the underlying crypto operation fails due to invalid hex length or incomplete data,
+     * guaranteeing the try/catch block in the implementation is hit, and the expected error is thrown.
+     */
+    it('should fail decryption gracefully for tampered ciphertext (invalid payload)', () => {
+      const symm = new SymmetricCrypto();
+      const ciphertext = symm.encryptData(plaintext);
+
+      const [ivHex, encryptedHex] = ciphertext.split(':');
+
+      // Tamper with the encrypted content by cutting off the last character.
+      const tamperedEncryptedHex = encryptedHex.substring(0, encryptedHex.length - 1);
+
+      const tamperedCiphertext = `${ivHex}:${tamperedEncryptedHex}`;
+
+      // Expect the internal error handling to throw the generic error message
+      expect(() => symm.decryptData(tamperedCiphertext)).to.throw(
+        Error,
+        'Decryption failed. Check key, IV, or ciphertext integrity.',
+      );
+    });
+  });
+
+  // --- AsymmetricCrypto Tests (RSA 2048) ---
+  describe('AsymmetricCrypto (RSA 2048)', () => {
+    /**
+     * Test case: Verify that RSA key pair is automatically generated.
+     */
+    it('should generate a new RSA key pair if none are provided', () => {
+      const asymm = new AsymmetricCrypto();
+      // Public and Private keys should be PEM strings
+      expect(asymm.publicKey).to.be.a('string').and.include('BEGIN PUBLIC KEY');
+      expect(asymm.privateKey).to.be.a('string').and.include('BEGIN PRIVATE KEY');
+    });
+
+    /**
+     * Test case: Encrypt with public key and decrypt with the corresponding private key.
+     */
+    it('should encrypt data with public key and decrypt with private key', () => {
+      const asymm = new AsymmetricCrypto();
+      const ciphertext = asymm.encryptData(plaintext);
+
+      // Ciphertext is a hex string
+      expect(ciphertext).to.be.a('string');
+
+      const decryptedText = asymm.decryptData(ciphertext);
+      expect(decryptedText).to.equal(plaintext);
+    });
+
+    /**
+     * Test case: Verify that decryption fails gracefully when using a mismatched private key.
+     */
+    it('should fail decryption gracefully when using the wrong private key', () => {
+      // 1. Generate the key pair and encrypt the data
+      const asymm1 = new AsymmetricCrypto();
+      const ciphertext = asymm1.encryptData(plaintext);
+
+      // 2. Generate a completely different key pair (wrong key)
+      const asymm2 = new AsymmetricCrypto();
+
+      // 3. Try to decrypt ciphertext from asymm1 using the private key from asymm2
+      // The implementation will log the 'oaep decoding error' and re-throw the generic message.
+      expect(() => asymm2.decryptData(ciphertext)).to.throw(
+        Error,
+        'Decryption failed. Check private key or ciphertext integrity.',
+      );
+    });
+  });
+});