opticore-asymmetric-cryption

RSA asymmetric encryption/decryption module for the OpticoreJS framework. Provides sign, verify, encrypt, and decrypt operations using RSA key pairs, with an interactive CLI to generate your keys.

Table of contents

• Installation
• Generate RSA keys
• Quick start
• API reference
  • loaderTranslationFile
  • SAsymmetricCryptionDataWithPublicRSAKey
  • SAsymmetricCryptionDataWithPrivateRSAKey
  • RSAKeyEncryption
  • RSAKeyDecryption
  • Constants
• Security
• License

Installation

npm install opticore-asymmetric-cryption

After installation, a welcome message appears automatically with the command to run to generate your RSA keys.

Generate RSA keys

The package ships an interactive CLI that guides you through generating a key pair:

npx opticore-gen-keys

Or, if npx is not available:

node node_modules/opticore-asymmetric-cryption/scripts/generate-rsa-keys.mjs

The script lets you:

• Choose the generation method: Node.js crypto (built-in, no dependency) or OpenSSL (system tool)
• Choose the key size: 2048 bits (recommended) or 4096 bits (maximum security)
• Choose the output directory (default: keys/)
• Automatically creates a .gitignore in the output folder to protect private.pem

The package does not store your keys. They are generated in the directory you choose and are your responsibility to secure.

Generated files

| File | Description | |---|---| | keys/private.pem | Private key — keep it secret | | keys/public.pem | Public key — can be shared | | keys/.gitignore | Prevents private.pem from being committed |

Quick start

import fs from "fs";
import {
  loaderTranslationFile,
  SAsymmetricCryptionDataWithPublicRSAKey,
  SAsymmetricCryptionDataWithPrivateRSAKey,
} from "opticore-asymmetric-cryption";

// 1. Load translations (call once at application startup)
loaderTranslationFile("en"); // "en" or "fr"

// 2. Read your RSA keys
const privateKey = fs.readFileSync("keys/private.pem", "utf8");
const publicKey  = fs.readFileSync("keys/public.pem",  "utf8");

// 3. Encrypt with the public key, decrypt with the private key
const servicePublic = new SAsymmetricCryptionDataWithPublicRSAKey("en", ".env");
const result = servicePublic.verifyPublicRSAKey(privateKey, publicKey, "my secret payload");
console.log(result); // "my secret payload"

// 4. Encrypt with the private key, decrypt with the public key
const servicePrivate = new SAsymmetricCryptionDataWithPrivateRSAKey("en", ".env");
const result2 = servicePrivate.verifyRSAKey(privateKey, publicKey, "my secret payload");
console.log(result2); // "my secret payload"

API reference

loaderTranslationFile

Loads the package translation files for the given locale. Must be called once before using any service.

import { loaderTranslationFile } from "opticore-asymmetric-cryption";

loaderTranslationFile("en"); // English
loaderTranslationFile("fr"); // French

The locale can also be set via the OPTICORE_LOCALE environment variable.

SAsymmetricCryptionDataWithPublicRSAKey

Handles the public-key-first flow: signs and verifies with the public key, encrypts with the public key, and decrypts with the private key.

Constructor

new SAsymmetricCryptionDataWithPublicRSAKey(localeLanguage: string, environmentPath: string)

| Parameter | Type | Description | |---|---|---| | localeLanguage | string | Locale for error messages ("en" or "fr") | | environmentPath | string | Path to your .env file (e.g. ".env") |

verifyPublicRSAKey(privateKey, publicKey, payload)

Signs the payload with the public key (SHA-256), verifies the signature, then encrypts with the public key and decrypts with the private key.

verifyPublicRSAKey(
  privateKey: string,
  publicKey:  string,
  payload:    any
): string | StackTraceError

const service = new SAsymmetricCryptionDataWithPublicRSAKey("en", ".env");
const decrypted = service.verifyPublicRSAKey(privateKey, publicKey, "payload");
// returns "payload" if signature is verified, StackTraceError otherwise

SAsymmetricCryptionDataWithPrivateRSAKey

Handles the private-key-first flow: signs with the private key, verifies with the public key, encrypts with the private key, and decrypts with the public key.

Constructor

new SAsymmetricCryptionDataWithPrivateRSAKey(localeLanguage: string, environmentPath: string)

| Parameter | Type | Description | |---|---|---| | localeLanguage | string | Locale for error messages ("en" or "fr") | | environmentPath | string | Path to your .env file (e.g. ".env") |

verifyRSAKey(privateKey, publicKey, payload)

Signs the payload with the private key (SHA-256), verifies the signature with the public key, then encrypts with the private key and decrypts with the public key.

verifyRSAKey(
  privateKey: string,
  publicKey:  string,
  payload:    any
): string | Error

const service = new SAsymmetricCryptionDataWithPrivateRSAKey("en", ".env");
const decrypted = service.verifyRSAKey(privateKey, publicKey, "payload");
// returns "payload" if signature is verified, Error otherwise

RSAKeyEncryption

Low-level static class for raw RSA encryption. Use the service classes above for a higher-level interface.

import { RSAKeyEncryption } from "opticore-asymmetric-cryption";

// Encrypt with private key
const encrypted = RSAKeyEncryption.privateEncrypt(privateKey, Buffer.from("data"));

// Encrypt with public key
const encrypted = RSAKeyEncryption.publicEncrypt(publicKey, Buffer.from("data"));

| Method | Parameters | Returns | |---|---|---| | privateEncrypt(key, data) | key: string, data: Buffer | Buffer | | publicEncrypt(key, data) | key: string, data: Buffer | Buffer |

RSAKeyDecryption

Low-level static class for raw RSA decryption.

import { RSAKeyDecryption } from "opticore-asymmetric-cryption";

// Decrypt with private key
const decrypted = RSAKeyDecryption.privateDecrypt(privateKey, encryptedBuffer);

// Decrypt with public key
const decrypted = RSAKeyDecryption.publicDecrypt(publicKey, encryptedBuffer);

| Method | Parameters | Returns | |---|---|---| | privateDecrypt(key, data) | key: string, data: Buffer | Buffer | | publicDecrypt(key, data) | key: string, data: Buffer | Buffer |

Constants

All constants are re-exported from CSignRSAKeyComponent or individually.

CAlgorithm

Supported signing algorithms.

import { CAlgorithm } from "opticore-asymmetric-cryption";

CAlgorithm.sha256          // "SHA256"
CAlgorithm.RSA_SHA256      // "RSA-SHA256"
CAlgorithm.RSA_SHA512      // "RSA-SHA512"
CAlgorithm.sha512          // "sha512"
// ... and many more (RSA-MD5, RSA-SHA384, SHA3 variants, BLAKE2, etc.)

CKeyType

import { CKeyType } from "opticore-asymmetric-cryption";

CKeyType.private  // "Private"
CKeyType.public   // "Public"

COutputFormat

import { COutputFormat } from "opticore-asymmetric-cryption";

COutputFormat.base64     // "base64"
COutputFormat.base64url  // "base64url"
COutputFormat.hex        // "hex"
COutputFormat.binary     // "binary"

CEncodingFormat

import { CEncodingFormat } from "opticore-asymmetric-cryption";

CEncodingFormat.utf8     // "utf8"
CEncodingFormat.utf_8    // "utf-8"
CEncodingFormat.ascii    // "ascii"
CEncodingFormat.base64   // "base64"
CEncodingFormat.hex      // "hex"
// ... and more (utf16le, ucs2, latin1, binary, etc.)

CSignRSAKeyComponent

Aggregates all four constants under a single object:

import { CSignRSAKeyComponent } from "opticore-asymmetric-cryption";

CSignRSAKeyComponent.algorithm      // → CAlgorithm
CSignRSAKeyComponent.keyType        // → CKeyType
CSignRSAKeyComponent.outputFormat   // → COutputFormat
CSignRSAKeyComponent.encodingFormat // → CEncodingFormat

Security

• NEVER commit private.pem to your Git repository. The key generation script creates a .gitignore automatically.
• In production, store the private key in an environment variable or a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler, etc.).
• Use 4096-bit keys for maximum security, or 2048-bit for a balance between security and performance.
• The private key must remain confidential at all times. The public key can be distributed freely.

License

MIT — Guy-Serge Kouacou