@vvlad1973/crypto 2.1.1

package/.hintrc

@@ -0,0 +1,15 @@
+{
+  "extends": [
+    "development"
+  ],
+  "hints": {
+    "typescript-config/consistent-casing": "off",
+    "axe/structure": [
+      "default",
+      {
+        "definition-list": "off"
+      }
+    ],
+    "disown-opener": "off"
+  }
+}

package/.vscode/launch.json

@@ -0,0 +1,20 @@
+{
+    // Используйте IntelliSense, чтобы узнать о возможных атрибутах.
+    // Наведите указатель мыши, чтобы просмотреть описания существующих атрибутов.
+    // Для получения дополнительной информации посетите: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "env": {
+                "NODE_OPTIONS": "--experimental-vm-modules"
+            },
+            "name": "Запустить программу",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "program": "${workspaceFolder}\\index.js"
+        }
+    ]
+}

package/CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Common requirements
+
+- отвечай на русском языке. Используй английский только если на то есть особые указания
+- комментарии в коде, в JSDoc - используй английский язык
+- отчеты - используй русский язык
+- при создании документов и commit messages НИКОГДА НЕ ДОБАВЛЯЙ в нихх никакой информации о том, что этот текст сгенерирован тобой, либо при твоем участии/соавторстве
+- при формировании и редактировании файлов *.md соблюдай синтаксис MarkDown. Все Markdown-файлы (*.md) ДОЛЖНЫ проходить проверку линтером без ошибок и предупреждений
+- Не вноси изменений в CHANGELOG.md, этот файл формируется автоматически
+- **НИКОГДА НЕ ИСПОЛЬЗУЙ EMOJI** в файлах .md - это строгое требование проекта без исключений
+- при подготовке файлов документации соблюдай структуру каталога docs, правила, изложенные в C:\Repositories\botApp\bot-app-service\docs\CONTRIBUTING.md
+
+## Project Overview
+
+TypeScript library providing AES-256-CTR encryption/decryption functionality. Wrapper around Node.js native `crypto` module, replacing the previous `aes-js` dependency.
+
+## Development Commands
+
+### Build
+```bash
+npm run build
+```
+Compiles TypeScript to JavaScript using `tsc`. Output: `dist/` directory with `.js` and `.d.ts` files.
+
+### Testing
+```bash
+npm test
+```
+Runs build followed by Node.js native test runner with ts-node loader.
+
+To run a specific test file:
+```bash
+npm run build && node --loader ts-node/esm --test src/__tests__/crypto.test.ts
+```
+
+### Documentation Generation
+```bash
+npm run doc
+```
+Generates JSDoc documentation using better-docs template. Output: `docs/` directory.
+
+## Architecture
+
+### Core Module Structure
+- [src/crypto.ts](src/crypto.ts) - Main `Crypto` class implementation
+- [src/index.ts](src/index.ts) - Module exports
+- [src/__tests__/crypto.test.ts](src/__tests__/crypto.test.ts) - Test suite
+
+### Crypto Class Design
+
+The `Crypto` class uses Node.js native crypto APIs:
+- **Key derivation**: `pbkdf2Sync` with configurable algorithm (default SHA512), iterations (1000), and key length (32 bytes)
+- **Encryption**: AES-256-CTR mode via `createCipheriv`
+- **Initialization Vector (IV)**: Accepts either Buffer or number (converted to 16-byte Buffer)
+
+Constructor supports two signatures:
+1. Individual parameters: `new Crypto(password, salt, algorithm?, iterations?, keyLength?, iv?)`
+2. Options object: `new Crypto({ password, salt, algorithm?, iterations?, keyLength?, iv? })`
+
+### Key Implementation Details
+
+- IV conversion from number: Uses `Buffer.alloc(16)` with `writeUInt32BE` at offset 12
+- Encryption output: Hex-encoded string
+- Type guard: `isCrypto(object)` function checks for `encrypt` and `decrypt` methods
+- Static method: `Crypto.getUUID()` returns UUIDv4 string using `crypto.randomUUID()`
+
+### Module System
+- ES modules (`"type": "module"` in package.json)
+- TypeScript target: ES2022
+- File extensions: Import paths must use `.js` extension (not `.ts`) due to ES module resolution
+
+## TypeScript Configuration
+
+Strict mode enabled with full type checking. Output includes declaration files for TypeScript consumers.
+
+## Testing Approach
+
+Tests use Node.js native test runner (`node:test`) with:
+- Encryption/decryption round-trip verification
+- Both constructor signatures
+- Default parameter handling
+- Type guard validation
+- Backward compatibility with previous library version (validates specific encrypted output)
+
+## JSDoc Requirements
+
+Per user instructions: All modules must include complete JSDoc with module definitions. Comments and JSDoc must be in English.

package/LICENSE

@@ -0,0 +1,19 @@
+# MIT License with Commercial Use
+
+Copyright (c) 2022 Vladislav Vnukovskiy
+
+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.
+
+Commercial Use:
+
+The user is allowed to use the Software for commercial purposes, subject to the following conditions:
+
+The user must agree to share a portion of their revenue with the author of the Software.
+
+The author of the Software reserves the right to verify the accuracy and size of the revenue earned by the user through the use of the Software. This provision is a mandatory condition for the commercial use of the Software.
+
+If the user does not agree to these conditions, they may not use the Software for commercial purposes.
+
+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,253 @@
+# @vvlad1973/crypto
+
+A TypeScript library for encrypting and decrypting text using AES-256-CTR encryption with PBKDF2 key derivation.
+
+This library uses Node.js native `crypto` module for secure encryption operations.
+
+## Features
+
+- AES-256-CTR encryption
+- PBKDF2 key derivation with configurable parameters
+- Support for both number and Buffer initialization vectors
+- TypeScript support with full type definitions
+- Dual API: constructor with options object or separate parameters
+- UUID v4 generation utility
+- Zero external dependencies (uses native Node.js crypto)
+
+## Installation
+
+```bash
+npm install @vvlad1973/crypto
+```
+
+## Usage
+
+### Importing
+
+```typescript
+import Crypto, { CryptoOptions, isCrypto } from '@vvlad1973/crypto';
+```
+
+### Basic Usage
+
+```typescript
+import Crypto from '@vvlad1973/crypto';
+
+const password = 'your-password';
+const salt = 'your-salt';
+
+// Create an instance using separate parameters
+const crypto = new Crypto(password, salt);
+
+// Encrypt a text
+const plainText = 'Hello, World!';
+const encryptedText = crypto.encrypt(plainText);
+console.log('Encrypted:', encryptedText);
+
+// Decrypt the text
+const decryptedText = crypto.decrypt(encryptedText);
+console.log('Decrypted:', decryptedText);
+```
+
+### Using Options Object
+
+```typescript
+import Crypto, { CryptoOptions } from '@vvlad1973/crypto';
+
+const options: CryptoOptions = {
+  password: 'your-password',
+  salt: 'your-salt',
+  algorithm: 'SHA512',
+  iterations: 1000,
+  keyLength: 32,
+  iv: 5
+};
+
+const crypto = new Crypto(options);
+const encrypted = crypto.encrypt('Secret message');
+const decrypted = crypto.decrypt(encrypted);
+```
+
+### Using Buffer IV
+
+```typescript
+import Crypto from '@vvlad1973/crypto';
+import { randomBytes } from 'crypto';
+
+// Generate a random 16-byte initialization vector
+const ivBuffer = randomBytes(16);
+
+const crypto = new Crypto({
+  password: 'your-password',
+  salt: 'your-salt',
+  iv: ivBuffer
+});
+
+const encrypted = crypto.encrypt('Secret message');
+```
+
+### Generating UUIDs
+
+```typescript
+import Crypto from '@vvlad1973/crypto';
+
+// Generate a UUID v4
+const uuid = Crypto.getUUID();
+console.log(uuid); // e.g., '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
+```
+
+### Type Guard
+
+```typescript
+import Crypto, { isCrypto } from '@vvlad1973/crypto';
+
+const crypto = new Crypto('password', 'salt');
+
+if (isCrypto(crypto)) {
+  // TypeScript knows crypto has encrypt/decrypt methods
+  const encrypted = crypto.encrypt('text');
+}
+```
+
+## API
+
+### Constructor
+
+#### Using separate parameters
+
+```typescript
+new Crypto(
+  password: string,
+  salt: string,
+  algorithm?: string,
+  iterations?: number,
+  keyLength?: number,
+  iv?: number | Buffer
+)
+```
+
+#### Using options object
+
+```typescript
+new Crypto(options: CryptoOptions)
+```
+
+**CryptoOptions interface:**
+
+```typescript
+interface CryptoOptions {
+  password: string;      // Password for key derivation
+  salt: string;          // Salt for key derivation
+  algorithm?: string;    // Hash algorithm (default: 'SHA512')
+  iterations?: number;   // PBKDF2 iterations (default: 1000)
+  keyLength?: number;    // Key length in bytes (default: 32)
+  iv?: number | Buffer;  // Initialization vector (default: random 16 bytes)
+}
+```
+
+**Parameters:**
+
+- `password` - The password used for PBKDF2 key derivation
+- `salt` - The salt used for PBKDF2 key derivation
+- `algorithm` - Hash algorithm for PBKDF2 (default: `'SHA512'`)
+- `iterations` - Number of PBKDF2 iterations (default: `1000`)
+- `keyLength` - Derived key length in bytes (default: `32` for AES-256)
+- `iv` - Initialization vector: either a number (converted to 16-byte Buffer) or a Buffer directly (default: random 16 bytes)
+
+### Instance Methods
+
+#### encrypt(text: string): string
+
+Encrypts the given text using AES-256-CTR encryption.
+
+- `text` - The plain text to encrypt
+- **Returns:** The encrypted text as a hexadecimal string
+
+#### decrypt(text: string): string
+
+Decrypts the given encrypted text using AES-256-CTR decryption.
+
+- `text` - The encrypted text as a hexadecimal string
+- **Returns:** The decrypted plain text
+
+### Static Methods
+
+#### Crypto.getUUID(): string
+
+Generates a random UUID v4 string using Node.js native crypto.
+
+- **Returns:** A UUID v4 string (e.g., `'9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'`)
+
+### Utility Functions
+
+#### isCrypto(object: any): object is Crypto
+
+Type guard function to check if an object is an instance of Crypto.
+
+- `object` - The object to check
+- **Returns:** `true` if the object is a Crypto instance, `false` otherwise
+
+## Testing
+
+This library uses Vitest for testing with comprehensive coverage requirements.
+
+### Run all tests
+
+```bash
+npm test
+```
+
+### Run tests in watch mode
+
+```bash
+npm run test:watch
+```
+
+### Run tests with UI
+
+```bash
+npm run test:ui
+```
+
+### Generate coverage report
+
+```bash
+npm run test:coverage
+```
+
+### Coverage Requirements
+
+- Lines: 90%
+- Functions: 85%
+- Branches: 90%
+- Statements: 90%
+
+Current coverage: **100%** across all metrics
+
+## Building
+
+To build the TypeScript project:
+
+```bash
+npm run build
+```
+
+This will compile TypeScript files to the `dist` directory with type definitions.
+
+## Documentation
+
+To generate TypeDoc documentation:
+
+```bash
+npm run doc
+```
+
+Documentation will be generated in the `docs` directory.
+
+## License
+
+This project is licensed under the MIT License with Commercial Use - see the LICENSE file for details.
+
+## Author
+
+Vladislav Vnukovskiy <vvlad1973@gmail.com>

package/dist/__tests__/crypto.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/crypto.test.js

@@ -0,0 +1,181 @@
+import { describe, it, beforeEach, expect } from 'vitest';
+import { randomBytes } from 'crypto';
+import Crypto, { isCrypto } from '../crypto.js';
+describe('Crypto', () => {
+    const plainText = 'Hello, World!';
+    let options;
+    let password;
+    let salt;
+    let algorithm;
+    let iterations;
+    let keyLength;
+    let iv;
+    beforeEach(() => {
+        options = {
+            password: 'testPassword',
+            salt: 'testSalt',
+            algorithm: 'SHA512',
+            iterations: 1000,
+            keyLength: 32,
+            iv: 5,
+        };
+        password = 'testPassword';
+        salt = 'testSalt';
+        algorithm = 'SHA512';
+        iterations = 1000;
+        keyLength = 32;
+        iv = 5;
+    });
+    it('should initialize with CryptoOptions object', () => {
+        const crypto = new Crypto(options);
+        expect(crypto).toBeDefined();
+    });
+    it('should initialize with separate parameters', () => {
+        const crypto = new Crypto(password, salt, algorithm, iterations, keyLength, iv);
+        expect(crypto).toBeDefined();
+    });
+    it('should return UUIDv4', () => {
+        const crypto = new Crypto(options);
+        const uuid = Crypto.getUUID();
+        const uuidv4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+        expect(uuid).toMatch(uuidv4Regex);
+    });
+    it('should encrypt and decrypt text correctly using ICryptoOptions', () => {
+        const crypto = new Crypto(options);
+        const encryptedText = crypto.encrypt(plainText);
+        const decryptedText = crypto.decrypt(encryptedText);
+        expect(decryptedText).toBe(plainText);
+    });
+    it('should encrypt and decrypt text correctly using separate parameters', () => {
+        const crypto = new Crypto(password, salt, algorithm, iterations, keyLength, iv);
+        const encryptedText = crypto.encrypt(plainText);
+        const decryptedText = crypto.decrypt(encryptedText);
+        expect(decryptedText).toBe(plainText);
+    });
+    it('should handle default values for optional parameters', () => {
+        const cryptoWithDefaults = new Crypto(password, salt);
+        const encryptedText = cryptoWithDefaults.encrypt(plainText);
+        const decryptedText = cryptoWithDefaults.decrypt(encryptedText);
+        expect(decryptedText).toBe(plainText);
+    });
+    it('should initialize with Buffer IV using options object', () => {
+        const ivBuffer = randomBytes(16);
+        const crypto = new Crypto({
+            password,
+            salt,
+            algorithm,
+            iterations,
+            keyLength,
+            iv: ivBuffer,
+        });
+        const encryptedText = crypto.encrypt(plainText);
+        const decryptedText = crypto.decrypt(encryptedText);
+        expect(decryptedText).toBe(plainText);
+    });
+    it('should initialize with Buffer IV using separate parameters', () => {
+        const ivBuffer = randomBytes(16);
+        const crypto = new Crypto(password, salt, algorithm, iterations, keyLength, ivBuffer);
+        const encryptedText = crypto.encrypt(plainText);
+        const decryptedText = crypto.decrypt(encryptedText);
+        expect(decryptedText).toBe(plainText);
+    });
+    it('should initialize without IV (random generation via options)', () => {
+        const crypto1 = new Crypto({ password, salt });
+        const crypto2 = new Crypto({ password, salt });
+        const encrypted1 = crypto1.encrypt(plainText);
+        const encrypted2 = crypto2.encrypt(plainText);
+        // Should produce different encrypted results due to different random IVs
+        expect(encrypted1).not.toBe(encrypted2);
+    });
+    it('should handle empty string encryption and decryption', () => {
+        const crypto = new Crypto(options);
+        const emptyText = '';
+        const encryptedText = crypto.encrypt(emptyText);
+        const decryptedText = crypto.decrypt(encryptedText);
+        expect(decryptedText).toBe(emptyText);
+    });
+    it('should handle Unicode characters', () => {
+        const crypto = new Crypto(options);
+        const unicodeText = '🔐 Encryption test 中文 العربية';
+        const encryptedText = crypto.encrypt(unicodeText);
+        const decryptedText = crypto.decrypt(encryptedText);
+        expect(decryptedText).toBe(unicodeText);
+    });
+    it('should handle different hash algorithms', () => {
+        const crypto256 = new Crypto(password, salt, 'sha256', iterations, keyLength, iv);
+        const encryptedText = crypto256.encrypt(plainText);
+        const decryptedText = crypto256.decrypt(encryptedText);
+        expect(decryptedText).toBe(plainText);
+    });
+    it('should handle different key lengths', () => {
+        // AES-256-CTR requires 32 bytes key, testing with valid 32 bytes
+        const crypto32 = new Crypto(password, salt, algorithm, iterations, 32, iv);
+        const encryptedText = crypto32.encrypt(plainText);
+        const decryptedText = crypto32.decrypt(encryptedText);
+        expect(decryptedText).toBe(plainText);
+    });
+    it('should handle different iteration counts', () => {
+        const crypto = new Crypto(password, salt, algorithm, 5000, keyLength, iv);
+        const encryptedText = crypto.encrypt(plainText);
+        const decryptedText = crypto.decrypt(encryptedText);
+        expect(decryptedText).toBe(plainText);
+    });
+});
+describe('isCrypto', () => {
+    const validCryptoOptions = {
+        password: 'testPassword',
+        salt: 'testSalt',
+        algorithm: 'SHA512',
+        iterations: 1000,
+        keyLength: 32,
+        iv: 5,
+    };
+    it('should return true for a valid Crypto instance created with ICryptoOptions', () => {
+        const crypto = new Crypto(validCryptoOptions);
+        expect(isCrypto(crypto)).toBe(true);
+    });
+    it('should return true for a valid Crypto instance created with separate parameters', () => {
+        const crypto = new Crypto(validCryptoOptions.password, validCryptoOptions.salt, validCryptoOptions.algorithm, validCryptoOptions.iterations, validCryptoOptions.keyLength, validCryptoOptions.iv);
+        expect(isCrypto(crypto)).toBe(true);
+    });
+    it('should return false for null', () => {
+        const nullObject = null;
+        expect(isCrypto(nullObject)).toBe(false);
+    });
+    it('should return false for undefined', () => {
+        const undefinedObject = undefined;
+        expect(isCrypto(undefinedObject)).toBe(false);
+    });
+    it('should return false for a plain object without encrypt and decrypt methods', () => {
+        const plainObject = {
+            someMethod: () => { },
+        };
+        expect(isCrypto(plainObject)).toBe(false);
+    });
+});
+describe('Compatibility with previous version', () => {
+    const plainText = 'Проверка связи';
+    let options;
+    let encText = 'a4661cb701751a895f65418ed488faad33da3090d05ad661f0a7a9';
+    beforeEach(() => {
+        options = {
+            algorithm: 'SHA512',
+            iv: 5,
+            keyLength: 32,
+            iterations: 1000,
+            password: 'password',
+            salt: 'saltsaltsalt',
+        };
+    });
+    it('should return correct string', () => {
+        const crypto = new Crypto(options);
+        const decryptedText = crypto.decrypt(encText);
+        expect(decryptedText).toBe(plainText);
+    });
+    it('should return correct encrypt-decrypt', () => {
+        const crypto = new Crypto(options);
+        const encryptedText = crypto.encrypt(plainText);
+        const decryptedText = crypto.decrypt(encryptedText);
+        expect(decryptedText).toBe(plainText);
+    });
+});

package/dist/crypto.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Checks if an object is an instance of Crypto.
+ * @param {any} object - The object to check.
+ * @returns {boolean} Returns true if the object is an instance of Crypto, false otherwise.
+ */
+export declare function isCrypto(object: any): object is Crypto;
+/**
+ * Interface representing the set of parameters to create an instance of the Crypto class.
+ * @interface CryptoOptions
+ * @property {string} password - The password used for key derivation.
+ * @property {string} salt - The salt used for key derivation.
+ * @property {string} [algorithm='sha512'] - The hash algorithm to use for key derivation.
+ * @property {number} [iterations=1000] - The number of iterations to use for key derivation.
+ * @property {number} [keyLength=32] - The length of the derived key in bytes.
+ * @property {number|Buffer} [iv] - The initialization vector for the AES encryption.
+ */
+export interface CryptoOptions {
+    password: string;
+    salt: string;
+    algorithm?: string;
+    iterations?: number;
+    keyLength?: number;
+    iv?: number | Buffer;
+}
+/**
+ * Class representing a cryptographic utility for encrypting and decrypting text.
+ * @class
+ * @param {string|CryptoOptions} passwordOrOptions - The password used for key derivation or an options object.
+ * @param {string} salt - The salt used for key derivation.
+ * @param {string} [algorithm='sha512'] - The hash algorithm to use for key derivation.
+ * @param {number} [iterations=1000] - The number of iterations to use for key derivation.
+ * @param {number} [keyLength=32] - The length of the derived key in bytes.
+ * @param {number|Buffer} [iv] - The initialization vector for the AES encryption.
+ */
+export declare class Crypto {
+    private iv;
+    private key;
+    constructor(password: string, salt: string, algorithm?: string, iterations?: number, keyLength?: number, iv?: number | Buffer);
+    constructor(options: CryptoOptions);
+    private convertNumberToIV;
+    /**
+     * Encrypt a text string.
+     * @param {string} text - The plain text to encrypt.
+     * @returns {string} The encrypted text as a hex string.
+     */
+    encrypt(text: string): string;
+    /**
+     * Decrypt an encrypted text string.
+     * @param {string} text - The encrypted text as a hex string.
+     * @returns {string} The decrypted plain text.
+     */
+    decrypt(text: string): string;
+    /**
+     * Returns a UUID ver.4 string.
+     * @returns {string} UUID ver.4 string.
+     */
+    static getUUID(): string;
+}
+export default Crypto;