@underpostnet/cyberia 3.2.80

package/src/server/cron.js

@@ -0,0 +1,476 @@
+/**
+ * UnderpostCron server module
+ * @module src/server/cron.js
+ * @namespace UnderpostCron
+ */
+
+import { loggerFactory } from './logger.js';
+import { shellExec } from './process.js';
+import fs from 'fs-extra';
+import Underpost from '../index.js';
+import { getUnderpostRootPath, loadCronDeployEnv } from './conf.js';
+
+const logger = loggerFactory(import.meta);
+
+const volumeHostPath = '/home/dd';
+const enginePath = '/home/dd/engine';
+const cronVolumeName = 'underpost-cron-container-volume';
+const shareEnvVolumeName = 'underpost-share-env';
+const underpostContainerEnvDir = '/usr/lib/node_modules/underpost';
+
+/**
+ * Generates a Kubernetes CronJob YAML manifest string.
+ *
+ * @param {Object} params - CronJob parameters
+ * @param {string} params.name - CronJob name (max 52 chars, sanitized to DNS subdomain)
+ * @param {string} params.expression - Cron schedule expression (e.g., '0 0 * * *')
+ * @param {string} params.deployList - Comma-separated deploy IDs for the cron CLI
+ * @param {string} params.jobList - Comma-separated job IDs (e.g., 'dns', 'backup')
+ * @param {string} [params.image] - Container image (defaults to underpost/underpost-engine:<version>)
+ * @param {string} [params.namespace='default'] - Kubernetes namespace
+ * @param {boolean} [params.git=false] - Pass --git flag to cron CLI
+ * @param {boolean} [params.dev=false] - Use local ./ base path instead of global underpost installation
+ * @param {string} [params.cmd] - Optional pre-script commands to run before cron execution
+ * @param {boolean} [params.suspend=false] - Whether the CronJob is suspended
+ * @param {boolean} [params.dryRun=false] - Pass --dry-run flag to the cron command inside the container
+ * @param {boolean} [params.k3s=false] - Pass --k3s flag to the cron command inside the container
+ * @param {boolean} [params.kind=false] - Pass --kind flag to the cron command inside the container
+ * @param {boolean} [params.kubeadm=false] - Pass --kubeadm flag to the cron command inside the container
+ * @returns {string} Kubernetes CronJob YAML manifest
+ * @memberof UnderpostCron
+ */
+const cronJobYamlFactory = ({
+  name,
+  expression,
+  deployList,
+  jobList,
+  image,
+  namespace = 'default',
+  git = false,
+  dev = false,
+  cmd,
+  suspend = false,
+  dryRun = false,
+  k3s = false,
+  kind = false,
+  kubeadm = false,
+}) => {
+  const containerImage = image || `underpost/underpost-engine:${Underpost.version}`;
+
+  const sanitizedName = name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/--+/g, '-')
+    .replace(/^-|-$/g, '')
+    .substring(0, 52);
+
+  const cronBin = 'node bin'; // dev ? 'node bin' : 'underpost';
+  const flags = `${git ? '--git ' : ''}${dev ? '--dev ' : ''}${dryRun ? '--dry-run ' : ''}${k3s ? '--k3s ' : ''}${kind ? '--kind ' : ''}${kubeadm ? '--kubeadm ' : ''}`;
+  const commands = [`cd ${enginePath}`]; // `node bin run secret`
+  if (cmd) commands.push(cmd);
+  commands.push(`${cronBin} cron ${deployList} ${jobList} ${flags}`);
+  const fullCommand = commands.join(' &&\n                  ');
+
+  return `apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: ${sanitizedName}
+  namespace: ${namespace}
+  labels:
+    app: ${sanitizedName}
+    managed-by: underpost
+spec:
+  schedule: "${expression}"
+  concurrencyPolicy: Forbid
+  startingDeadlineSeconds: 200
+  successfulJobsHistoryLimit: 3
+  failedJobsHistoryLimit: 1
+  suspend: ${suspend}
+  jobTemplate:
+    spec:
+      template:
+        metadata:
+          labels:
+            app: ${sanitizedName}
+            managed-by: underpost
+        spec:
+          containers:
+            - name: ${sanitizedName}
+              image: ${containerImage}
+              command:
+                - /bin/sh
+                - -c
+                - >
+                  ${fullCommand}
+              volumeMounts:
+                - mountPath: ${enginePath}
+                  name: ${cronVolumeName}
+                - mountPath: ${underpostContainerEnvDir}
+                  name: ${shareEnvVolumeName}
+          volumes:
+            - hostPath:
+                path: ${enginePath}
+                type: Directory
+              name: ${cronVolumeName}
+            - hostPath:
+                path: ${getUnderpostRootPath()}
+                type: DirectoryOrCreate
+              name: ${shareEnvVolumeName}
+          restartPolicy: OnFailure
+`;
+};
+
+/**
+ * Syncs the engine directory into the kind-worker container node.
+ * Required for kind clusters where worker nodes don't share the host filesystem.
+ *
+ * @memberof UnderpostCron
+ */
+const syncEngineToKindWorker = () => {
+  logger.info('Syncing engine volume to kind-worker node');
+  shellExec(`docker exec -i kind-worker bash -c "rm -rf ${volumeHostPath}"`);
+  shellExec(`docker exec -i kind-worker bash -c "mkdir -p ${volumeHostPath}"`);
+  shellExec(`docker cp ${volumeHostPath}/engine kind-worker:${volumeHostPath}/engine`);
+  shellExec(
+    `docker exec -i kind-worker bash -c "chown -R 1000:1000 ${volumeHostPath}; chmod -R 755 ${volumeHostPath}"`,
+  );
+};
+
+/**
+ * Resolves the deploy-id to use for cron job generation.
+ * When deployId is provided directly, uses it. Otherwise reads from dd.cron file.
+ *
+ * @param {string} [deployId] - Explicit deploy-id override
+ * @memberof UnderpostCron
+ * @returns {string|null} Resolved deploy-id or null if not found
+ */
+const resolveDeployId = (deployId) => {
+  if (deployId) return deployId;
+
+  const cronDeployFilePath = './engine-private/deploy/dd.cron';
+  if (!fs.existsSync(cronDeployFilePath)) {
+    return null;
+  }
+  return fs.readFileSync(cronDeployFilePath, 'utf8').trim();
+};
+
+/**
+ * UnderpostCron main module methods
+ * @class UnderpostCron
+ * @memberof UnderpostCron
+ */
+class UnderpostCron {
+  /** @returns {Object} Available cron job handlers */
+  static get JOB() {
+    return {
+      dns: Underpost.dns,
+      backup: Underpost.backup,
+    };
+  }
+
+  static API = {
+    /**
+     * CLI entry point for the `underpost cron` command.
+     *
+     * @param {string} deployList - Comma-separated deploy IDs
+     * @param {string} jobList - Comma-separated job IDs
+     * @param {Object} options - CLI flags
+     * @param {boolean} [options.generateK8sCronjobs] - Generate K8s CronJob YAML manifests
+     * @param {boolean} [options.apply] - Apply manifests to the cluster
+     * @param {boolean} [options.git] - Pass --git to job execution
+     * @param {boolean} [options.dev] - Use local ./ base path instead of global underpost installation
+     * @param {string}  [options.cmd] - Optional pre-script commands to run before cron execution
+     * @param {string}  [options.namespace] - Kubernetes namespace
+     * @param {string}  [options.image] - Custom container image
+     * @param {string}  [options.setupStart] - Deploy-id to setup: updates its package.json start and generates+applies cron jobs
+     * @param {boolean} [options.k3s] - Use k3s cluster context (apply directly on host)
+     * @param {boolean} [options.kind] - Use kind cluster context (apply via kind-worker container)
+     * @param {boolean} [options.kubeadm] - Use kubeadm cluster context (apply directly on host)
+     * @param {boolean} [options.dryRun] - Preview cron jobs without executing them
+     * @param {boolean} [options.createJobNow] - After applying, immediately create a Job from each CronJob (requires --apply)
+     * @memberof UnderpostCron
+     */
+    callback: async function (
+      deployList = 'default',
+      jobList = Object.keys(Underpost.cron.JOB).join(','),
+      options = {},
+    ) {
+      loadCronDeployEnv();
+      if (options.setupStart) return await Underpost.cron.setupDeployStart(options.setupStart, options);
+
+      if (options.generateK8sCronjobs) return await Underpost.cron.generateK8sCronJobs(options);
+
+      for (const _jobId of jobList.split(',')) {
+        const jobId = _jobId.trim();
+        if (Underpost.cron.JOB[jobId]) {
+          if (options.dryRun) {
+            logger.info(`[dry-run] Would execute cron job`, { jobId, deployList, options });
+          } else {
+            logger.info(`Executing cron job`, { jobId, deployList, options });
+            await Underpost.cron.JOB[jobId].callback(deployList, options);
+          }
+        } else {
+          logger.warn(`Unknown cron job: ${jobId}`);
+        }
+      }
+    },
+
+    /**
+     * Update the package.json start script for the given deploy-id and generate+apply its K8s CronJob manifests.
+     *
+     * @param {string} deployId - The deploy-id whose package.json will be updated
+     * @param {Object} [options] - Additional options forwarded to generateK8sCronJobs
+     * @param {boolean} [options.createJobNow] - After applying, immediately create a Job from each CronJob
+     * @param {boolean} [options.dryRun] - Pass --dry-run=client to kubectl commands
+     * @param {boolean} [options.apply] - Whether to apply generated manifests to the cluster
+     * @param {boolean} [options.git] - Pass --git flag to cron CLI commands
+     * @param {boolean} [options.dev] - Use local ./ base path instead of global underpost installation
+     * @param {string}  [options.cmd] - Optional pre-script commands to run before cron execution
+     * @param {string}  [options.namespace] - Kubernetes namespace for the CronJobs
+     * @param {string}  [options.image] - Custom container image override for the CronJobs
+     * @param {boolean} [options.k3s] - k3s cluster context (apply directly on host)
+     * @param {boolean} [options.kind] - kind cluster context (apply via kind-worker container)
+     * @param {boolean} [options.kubeadm] - kubeadm cluster context (apply directly on host)
+     * @memberof UnderpostCron
+     */
+    setupDeployStart: async function (deployId, options = {}) {
+      if (!deployId || deployId === true) deployId = resolveDeployId();
+      const confDir = `./engine-private/conf/${deployId}`;
+      const packageJsonPath = `${confDir}/package.json`;
+      const confCronPath = `${confDir}/conf.cron.json`;
+
+      if (!fs.existsSync(confCronPath)) {
+        logger.warn(`conf.cron.json not found for deploy-id: ${deployId}`, { path: confCronPath });
+        return;
+      }
+
+      const confCron = JSON.parse(fs.readFileSync(confCronPath, 'utf8'));
+
+      if (!confCron.jobs || Object.keys(confCron.jobs).length === 0) {
+        logger.warn(`No cron jobs configured for deploy-id: ${deployId}`);
+        return;
+      }
+
+      const hasEnabledJobs = Object.values(confCron.jobs).some((job) => job.enabled !== false);
+      if (!hasEnabledJobs) {
+        logger.warn(`No enabled cron jobs for deploy-id: ${deployId}`);
+        return;
+      }
+
+      // Update package.json start script
+      if (fs.existsSync(packageJsonPath)) {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        let startCommand = 'echo "Starting cron jobs..."';
+        for (const job of Object.keys(confCron.jobs))
+          startCommand += ` && kubectl apply -f ./manifests/cronjobs/${deployId}/${deployId}-${job}.yaml`;
+        if (!packageJson.scripts) packageJson.scripts = {};
+        packageJson.scripts.start = startCommand;
+
+        fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 4) + '\n', 'utf8');
+        logger.info(`Updated package.json start script for ${deployId}`, { path: packageJsonPath });
+      } else {
+        logger.warn(`package.json not found for deploy-id: ${deployId}`, { path: packageJsonPath });
+      }
+
+      await Underpost.cron.generateK8sCronJobs({
+        deployId,
+        namespace: options.namespace,
+        image: options.image,
+        apply: options.apply,
+        createJobNow: options.createJobNow,
+        git: !!options.git,
+        dev: !!options.dev,
+        kubeadm: !!options.kubeadm,
+        cmd: options.cmd || `node bin env ${deployId} production`,
+        k3s: !!options.k3s,
+        kind: !!options.kind,
+        dryRun: !!options.dryRun,
+      });
+    },
+
+    /**
+     * Generate Kubernetes CronJob YAML manifests from conf.cron.json configuration.
+     * Each enabled job produces one CronJob YAML file under manifests/cronjobs/<deployId>/.
+     * With --apply the manifests are also applied to the cluster via kubectl.
+     *
+     * @param {Object} options
+     * @param {string}  [options.deployId] - Explicit deploy-id (overrides dd.cron file lookup)
+     * @param {boolean} [options.git=false] - Pass --git flag to cron CLI commands
+     * @param {boolean} [options.dev=false] - Use local ./ base path instead of global underpost
+     * @param {string}  [options.cmd] - Optional pre-script commands
+     * @param {boolean} [options.apply=false] - kubectl apply generated manifests
+     * @param {string}  [options.namespace='default'] - Target Kubernetes namespace
+     * @param {string}  [options.image] - Custom container image override
+     * @param {boolean} [options.k3s=false] - k3s cluster context (apply directly on host)
+     * @param {boolean} [options.kind=false] - kind cluster context (apply via kind-worker container)
+     * @param {boolean} [options.kubeadm=false] - kubeadm cluster context (apply directly on host)
+     * @param {boolean} [options.createJobNow=false] - After applying, create a Job from each CronJob immediately
+     * @param {boolean} [options.dryRun=false] - Pass --dry-run=client to kubectl commands
+     * @memberof UnderpostCron
+     */
+    generateK8sCronJobs: async function (options = {}) {
+      const namespace = options.namespace || 'default';
+      const jobDeployId = resolveDeployId(options.deployId);
+
+      if (!jobDeployId) {
+        logger.warn(
+          'Could not resolve deploy-id. Provide --setup-start <deploy-id> or create engine-private/deploy/dd.cron',
+        );
+        return;
+      }
+
+      const confCronPath = `./engine-private/conf/${jobDeployId}/conf.cron.json`;
+
+      if (!fs.existsSync(confCronPath)) {
+        logger.warn(`Cron configuration not found: ${confCronPath}`);
+        return;
+      }
+
+      const confCronConfig = JSON.parse(fs.readFileSync(confCronPath, 'utf8'));
+
+      if (!confCronConfig.jobs || Object.keys(confCronConfig.jobs).length === 0) {
+        logger.info('No cron jobs configured');
+        return;
+      }
+
+      const outputDir = `./manifests/cronjobs/${jobDeployId}`;
+      fs.mkdirSync(outputDir, { recursive: true });
+
+      const generatedFiles = [];
+
+      for (const job of Object.keys(confCronConfig.jobs)) {
+        const jobConfig = confCronConfig.jobs[job];
+
+        if (jobConfig.enabled === false) {
+          logger.info(`Skipping disabled job: ${job}`);
+          continue;
+        }
+
+        const deployIdList = Underpost.cron.getRelatedDeployIdList(job);
+        const expression = jobConfig.expression || '0 0 * * *';
+        const cronJobName = `${jobDeployId}-${job}`;
+
+        const yamlContent = cronJobYamlFactory({
+          name: cronJobName,
+          expression,
+          deployList: deployIdList,
+          jobList: job,
+          image: options.image,
+          namespace,
+          git: !!options.git,
+          dev: !!options.dev,
+          cmd: options.cmd,
+          suspend: false,
+          dryRun: !!options.dryRun,
+          k3s: !!options.k3s,
+          kind: !!options.kind,
+          kubeadm: !!options.kubeadm,
+        });
+
+        const yamlFilePath = `${outputDir}/${cronJobName}.yaml`;
+        fs.writeFileSync(yamlFilePath, yamlContent, 'utf8');
+        generatedFiles.push(yamlFilePath);
+
+        logger.info(`Generated CronJob manifest: ${yamlFilePath}`, { job, expression, namespace });
+      }
+
+      if (options.apply) {
+        // Delete existing CronJobs before applying new ones
+        for (const job of Object.keys(confCronConfig.jobs)) {
+          const cronJobName = `${jobDeployId}-${job}`;
+          shellExec(`kubectl delete cronjob ${cronJobName} --namespace=${namespace} --ignore-not-found`);
+        }
+
+        // Ensure default dockerhub image is loaded on the cluster when no custom image is provided
+        if (!options.image) {
+          logger.info('Ensuring default image is loaded on cluster');
+          Underpost.image.pullDockerHubImage({
+            dockerhubImage: 'underpost',
+            kind: !!options.kind,
+            k3s: !!options.k3s,
+            kubeadm: !!options.kubeadm,
+            dev: !!options.dev,
+          });
+        }
+
+        // Sync engine volume to kind-worker node if using kind cluster
+        if (options.kind) {
+          syncEngineToKindWorker();
+        }
+
+        for (const yamlFile of generatedFiles) {
+          logger.info(`Applying: ${yamlFile}`);
+          shellExec(`kubectl apply -f ${yamlFile}`);
+        }
+        logger.info('All CronJob manifests applied');
+      } else {
+        logger.info(`Manifests generated in ${outputDir}. Use --apply to deploy to the cluster.`);
+      }
+      // Create an immediate Job from each CronJob if requested
+      if (options.createJobNow) {
+        for (const job of Object.keys(confCronConfig.jobs)) {
+          const jobConfig = confCronConfig.jobs[job];
+          if (jobConfig.enabled === false) continue;
+
+          const cronJobName = `${jobDeployId}-${job}`
+            .toLowerCase()
+            .replace(/[^a-z0-9-]/g, '-')
+            .replace(/--+/g, '-')
+            .replace(/^-|-$/g, '')
+            .substring(0, 52);
+
+          const immediateJobName = `${cronJobName}-now-${Date.now()}`.substring(0, 63);
+          logger.info(`Creating immediate Job from CronJob: ${cronJobName}`, { jobName: immediateJobName });
+          shellExec(`kubectl create job ${immediateJobName} --from=cronjob/${cronJobName} -n ${namespace}`);
+        }
+        logger.info('All immediate Jobs created');
+      }
+    },
+
+    /**
+     * Resolve the deploy-id list associated with a given job.
+     * Backup jobs read from dd.router (multiple deploy-ids); others from dd.cron.
+     *
+     * @param {string} jobId - Job identifier (e.g., 'dns', 'backup')
+     * @returns {string} Comma-separated deploy IDs
+     * @memberof UnderpostCron
+     */
+    getRelatedDeployIdList(jobId) {
+      const deployFilePath =
+        jobId === 'backup' ? './engine-private/deploy/dd.router' : './engine-private/deploy/dd.cron';
+
+      if (!fs.existsSync(deployFilePath)) {
+        logger.warn(`Deploy file not found: ${deployFilePath}, using default`);
+        return fs.existsSync('./engine-private/deploy/dd.cron')
+          ? fs.readFileSync('./engine-private/deploy/dd.cron', 'utf8').trim()
+          : 'dd-cron';
+      }
+
+      return fs.readFileSync(deployFilePath, 'utf8').trim();
+    },
+
+    /**
+     * Get the available cron job handlers.
+     * Each handler should have a callback function that executes the job logic.
+     * @memberof UnderpostCron
+     * @returns {Object} Available cron job handlers
+     */
+    get JOB() {
+      return UnderpostCron.JOB;
+    },
+
+    /**
+     * Get the list of available job IDs.
+     * This is derived from the keys of the JOB object.
+     * @memberof UnderpostCron
+     * @returns {string[]} List of available job IDs
+     */
+    getJobsIDs() {
+      return Object.keys(UnderpostCron.JOB);
+    },
+  };
+}
+
+export default UnderpostCron;
+
+export { cronJobYamlFactory, resolveDeployId };

package/src/server/crypto.js

@@ -0,0 +1,210 @@
+/**
+ * Module for managing crypto operations
+ * @module src/server/crypto.js
+ * @namespace Crypto
+ */
+
+import crypto from 'crypto';
+
+/* ----------------------------- SymmetricCrypto ----------------------------- */
+
+class SymmetricCrypto {
+  #encryptionKey;
+
+  /**
+   * @param {object} [options]
+   * @param {Buffer | string} [options.encryptionKey] - 32-byte key as Buffer or hex string. If not provided, a new random key is generated.
+   */
+  /** @memberof Crypto */
+  constructor(options = {}) {
+    const { encryptionKey } = options;
+
+    if (encryptionKey) {
+      this.#encryptionKey = typeof encryptionKey === 'string' ? Buffer.from(encryptionKey, 'hex') : encryptionKey;
+    } else {
+      this.#encryptionKey = crypto.randomBytes(32);
+    }
+
+    if (!Buffer.isBuffer(this.#encryptionKey) || this.#encryptionKey.length !== 32) {
+      throw new Error('Encryption key must be a 32-byte Buffer or 64-length hex string.');
+    }
+
+    // Provide a compatibility IV property expected by some test suites / legacy code.
+    // This IV is not reused for each encryption operation (encryptData will generate its own IV).
+    // It exists so tests that expect an ivHex on the instance (16 bytes) continue to work.
+    this.ivHex = crypto.randomBytes(16).toString('hex'); // 16 bytes -> 32 hex chars
+  }
+
+  /** Returns encryption key as hex. */
+  /** @memberof Crypto */
+  get encryptionKeyHex() {
+    return this.#encryptionKey.toString('hex');
+  }
+
+  /**
+   * Encrypts plaintext using AES-256-GCM and returns `iv_hex:ciphertext_hex:authTag_hex`.
+   *
+   * @param {string} [plaintext='']
+   * @returns {string}
+   * @memberof Crypto
+   */
+  encryptData(plaintext = '') {
+    // GCM recommended IV size is 12 bytes
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', this.#encryptionKey, iv);
+
+    const encryptedPart = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+
+    return `${iv.toString('hex')}:${encryptedPart.toString('hex')}:${authTag.toString('hex')}`;
+  }
+
+  /**
+   * Decrypts data. Supports two formats:
+   *  - AES-256-GCM: `iv_hex:ciphertext_hex:authTag_hex` (preferred)
+   *  - Legacy AES-256-CBC: `iv_hex:ciphertext_hex` (fallback for backward compatibility)
+   *
+   * @param {string} [ciphertext='']
+   * @returns {string} plaintext
+   * @throws {Error} Generic error on failure (to avoid leaking details).
+   * @memberof Crypto
+   */
+  decryptData(ciphertext = '') {
+    try {
+      const parts = ciphertext.split(':');
+
+      if (parts.length === 3) {
+        // AES-256-GCM
+        const [ivHex, encryptedHex, tagHex] = parts;
+        const iv = Buffer.from(ivHex, 'hex');
+        const encrypted = Buffer.from(encryptedHex, 'hex');
+        const authTag = Buffer.from(tagHex, 'hex');
+
+        const decipher = crypto.createDecipheriv('aes-256-gcm', this.#encryptionKey, iv);
+        decipher.setAuthTag(authTag);
+
+        const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+        return decrypted.toString('utf8');
+      }
+
+      if (parts.length === 2) {
+        // Legacy: AES-256-CBC (no authentication). Provided for compatibility only.
+        const [ivHex, encryptedHex] = parts;
+        const iv = Buffer.from(ivHex, 'hex');
+        const encrypted = encryptedHex;
+
+        const decipher = crypto.createDecipheriv('aes-256-cbc', this.#encryptionKey, iv);
+        let decrypted = decipher.update(encrypted, 'hex', 'utf8');
+        decrypted += decipher.final('utf8');
+        return decrypted;
+      }
+
+      throw new Error('Invalid ciphertext format.');
+    } catch (err) {
+      // Do not leak internal error details (stack, key material, etc.).
+      // Optional: instrument monitoring/logging but avoid logging sensitive inputs.
+      throw new Error('Decryption failed. Check key, IV, or ciphertext integrity.');
+    }
+  }
+}
+
+/* ---------------------------- AsymmetricCrypto ---------------------------- */
+
+class AsymmetricCrypto {
+  #publicKey;
+  #privateKey;
+  #modulusLength;
+
+  /**
+   * @param {object} [options]
+   * @param {string|Buffer} [options.publicKey] - PEM-formatted public key
+   * @param {string|Buffer} [options.privateKey] - PEM-formatted private key
+   * @param {number} [options.modulusLength=2048] - If keys are not provided, generates a new key pair of this size (bits). Consider 3072 for long-lived keys.
+   */
+  /** @memberof Crypto */
+  constructor(options = {}) {
+    const { publicKey, privateKey } = options;
+    this.#modulusLength = options.modulusLength || 2048;
+
+    if (!publicKey || !privateKey) {
+      // Generate an in-memory key pair. No file I/O; keys remain in process memory only.
+      const { publicKey: pub, privateKey: priv } = crypto.generateKeyPairSync('rsa', {
+        modulusLength: this.#modulusLength,
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+      });
+      this.#publicKey = pub;
+      this.#privateKey = priv;
+    } else {
+      // Accept provided keys (string or Buffer)
+      this.#publicKey = typeof publicKey === 'string' || Buffer.isBuffer(publicKey) ? publicKey : String(publicKey);
+      this.#privateKey =
+        typeof privateKey === 'string' || Buffer.isBuffer(privateKey) ? privateKey : String(privateKey);
+
+      // Basic validation: ensure PEM headers exist. This is intentionally lightweight.
+      const pubStr = String(this.#publicKey);
+      const privStr = String(this.#privateKey);
+      if (!pubStr.includes('BEGIN PUBLIC KEY') || !privStr.includes('BEGIN')) {
+        throw new Error('Provided keys do not appear to be valid PEM-formatted keys.');
+      }
+    }
+  }
+
+  /** @memberof Crypto */
+  get publicKey() {
+    return this.#publicKey;
+  }
+
+  /** @memberof Crypto */
+  get privateKey() {
+    return this.#privateKey;
+  }
+
+  /**
+   * Encrypts plaintext using RSA-OAEP with SHA-256. Returns hex-encoded ciphertext.
+   * Note: RSA encryption is intended for small payloads. For larger data use hybrid encryption (encrypt a symmetric key and then use AES-GCM).
+   * @param {string} plaintext
+   * @returns {string} hex ciphertext
+   * @memberof Crypto
+   */
+  encryptData(plaintext) {
+    const buffer = Buffer.from(plaintext, 'utf8');
+    const encrypted = crypto.publicEncrypt(
+      {
+        key: this.#publicKey,
+        padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
+        oaepHash: 'sha256',
+      },
+      buffer,
+    );
+
+    return encrypted.toString('hex');
+  }
+
+  /**
+   * Decrypts RSA-OAEP hex ciphertext and returns utf8 plaintext.
+   * @param {string} ciphertextHex
+   * @returns {string}
+   * @memberof Crypto
+   */
+  decryptData(ciphertextHex) {
+    try {
+      const buffer = Buffer.from(ciphertextHex, 'hex');
+      const decrypted = crypto.privateDecrypt(
+        {
+          key: this.#privateKey,
+          padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
+          oaepHash: 'sha256',
+        },
+        buffer,
+      );
+
+      return decrypted.toString('utf8');
+    } catch (err) {
+      // Avoid leaking details about keys or ciphertext
+      throw new Error('Decryption failed. Check private key or ciphertext integrity.');
+    }
+  }
+}
+
+export { SymmetricCrypto, AsymmetricCrypto };