@allsecurex-quantum/crypto-shim

Drop-in quantum-safe upgrade for Node.js applications - zero code changes required.

This package transparently upgrades your Node.js application's cryptographic operations to quantum-safe alternatives. Simply install and configure at application startup - all existing crypto code continues to work while being protected against quantum computer attacks.

Features

• Zero Code Changes: Works with existing crypto module usage
• Automatic Upgrades: RSA/ECDSA signatures upgraded to ML-DSA hybrids
• Multiple Modes: Monitor, hybrid, or pure post-quantum
• Analytics: Track all crypto operations via QuantumVault dashboard
• Gradual Rollout: Start in monitor mode, then progressively upgrade
• Fallback Safety: Automatic fallback to classical crypto on errors

Installation

npm install @allsecurex-quantum/crypto-shim

Quick Start

Add this at the very top of your application entry point (before any other imports):

// Must be the FIRST line of your application
require('@allsecurex-quantum/crypto-shim').install({
  apiKey: process.env.QUANTUMVAULT_API_KEY,
  mode: 'hybrid' // Start with 'monitor' to observe without changes
});

// Now all your existing code is quantum-safe!
const crypto = require('crypto');

// This RSA signature is automatically upgraded to ML-DSA-65 hybrid
const sign = crypto.createSign('RSA-SHA256');
sign.update('data to sign');
const signature = sign.sign(privateKey);

Configuration

require('@allsecurex-quantum/crypto-shim').install({
  // Required: Your QuantumVault API key
  apiKey: 'qvp_...',

  // Optional: Plugin ID for analytics (get from QuantumVault dashboard)
  pluginId: 'plugin_abc123',

  // Optional: API endpoint (defaults to production)
  endpoint: 'https://api.quantumvault.io',

  // Mode: 'monitor' | 'hybrid' | 'pq_only' | 'intercept'
  // - monitor: Log only, no changes (safe to start with)
  // - hybrid: Use classical + quantum-safe combined (recommended)
  // - pq_only: Pure post-quantum (future-proof but may have compatibility issues)
  // - intercept: Upgrade classical to PQ transparently
  mode: 'hybrid',

  // Fallback behavior on errors
  fallback: {
    onError: 'use_classical', // 'use_classical' | 'fail'
    timeout_ms: 5000
  },

  // Logging
  logging: {
    enabled: true,
    level: 'info' // 'debug' | 'info' | 'warn' | 'error'
  }
});

Algorithm Mappings

| Classical Algorithm | Quantum-Safe Upgrade | Hybrid Option | |---------------------|----------------------|---------------| | RSA-SHA256 | ML-DSA-65 | RSA-SHA256 + ML-DSA-65 | | RSA-SHA384 | ML-DSA-65 | RSA-SHA384 + ML-DSA-65 | | RSA-SHA512 | ML-DSA-87 | RSA-SHA512 + ML-DSA-87 | | ECDSA-P256 | ML-DSA-44 | ECDSA-P256 + ML-DSA-44 | | ECDSA-P384 | ML-DSA-65 | ECDSA-P384 + ML-DSA-65 | | Ed25519 | ML-DSA-44 | Ed25519 + ML-DSA-44 | | RSA (keygen) | ML-KEM-768 | RSA-2048 + ML-KEM-768 | | ECDH-P256 | ML-KEM-768 | ECDH-P256 + ML-KEM-768 | | X25519 | ML-KEM-768 | X25519 + ML-KEM-768 |

API Reference

install(config)

Install the crypto shim. Must be called before any crypto operations.

uninstall()

Remove the shim and restore original crypto functions.

isActive()

Returns true if the shim is currently installed.

status()

Get current shim status and statistics:

const { status } = require('@allsecurex-quantum/crypto-shim');

console.log(status());
// {
//   installed: true,
//   mode: 'hybrid',
//   stats: {
//     totalOperations: 150,
//     upgradedOperations: 142,
//     classicalOperations: 8,
//     failedOperations: 0,
//     byAlgorithm: Map { 'RSA-SHA256' => { upgraded: 100, classical: 0 }, ... }
//   }
// }

getMappings()

Get all algorithm mappings.

addMapping(mapping)

Add a custom algorithm mapping:

const { addMapping } = require('@allsecurex-quantum/crypto-shim');

addMapping({
  classical: 'CUSTOM-ALGO',
  quantum_safe: 'ML-DSA-87',
  hybrid_option: 'CUSTOM-ALGO + ML-DSA-87'
});

Migration Guide

Step 1: Monitor Mode (Week 1)

Start with monitor mode to understand your crypto usage:

require('@allsecurex-quantum/crypto-shim').install({
  apiKey: process.env.QUANTUMVAULT_API_KEY,
  mode: 'monitor',
  logging: { enabled: true, level: 'info' }
});

Step 2: Review Analytics

Check your QuantumVault dashboard to see:

• Which algorithms are being used
• Operation frequency and latency
• Potential compatibility issues

Step 3: Enable Hybrid Mode (Week 2+)

Once confident, switch to hybrid mode:

require('@allsecurex-quantum/crypto-shim').install({
  apiKey: process.env.QUANTUMVAULT_API_KEY,
  mode: 'hybrid'
});

Step 4: Pure Post-Quantum (Optional)

For maximum future-proofing:

require('@allsecurex-quantum/crypto-shim').install({
  apiKey: process.env.QUANTUMVAULT_API_KEY,
  mode: 'pq_only'
});

Supported Operations

| Operation | Supported | Notes | |-----------|-----------|-------| | createSign() | Yes | Signature algorithms upgraded | | createVerify() | Yes | Verification algorithms upgraded | | generateKeyPair() | Yes | Key types upgraded | | generateKeyPairSync() | Yes | Key types upgraded | | publicEncrypt() | Coming soon | Key encapsulation | | privateDecrypt() | Coming soon | Key decapsulation | | createCipheriv() | N/A | AES-256 already quantum-safe | | createDecipheriv() | N/A | AES-256 already quantum-safe | | createHash() | N/A | SHA-256+ already quantum-safe |

TypeScript Support

Full TypeScript support with type definitions included:

import { install, status, ShimConfig } from '@allsecurex-quantum/crypto-shim';

const config: ShimConfig = {
  apiKey: process.env.QUANTUMVAULT_API_KEY!,
  mode: 'hybrid'
};

install(config);

Troubleshooting

"Crypto shim is already installed"

The shim can only be installed once. If you need to reconfigure, call uninstall() first.

Operations not being upgraded

1. Check that install() is called before any crypto imports
2. Verify the algorithm is in the mappings list
3. Check that mode is set to 'hybrid' or 'pq_only'

Performance concerns

The shim adds minimal overhead (~1-2ms per operation). For high-throughput applications, consider:

• Using 'monitor' mode initially
• Batching operations where possible
• Caching signatures for repeated data

License

MIT

Support

• Documentation: https://docs.quantumvault.io
• Issues: https://github.com/AllSecureX-Quantum/crypto-shim-nodejs/issues
• Email: [email protected]

About AllSecureX

AllSecureX provides enterprise-grade post-quantum cryptography solutions. QuantumVault is our flagship product for NIST-standardized quantum-resistant algorithms (FIPS 203, 204, 205).

• Website: https://allsecurex.com
• GitHub: https://github.com/AllSecureX-Quantum