FuseCore Express Encrypted Package

FuseCore Express version - Provides the exact same API as the standard version, but with AES-256-GCM + RSA encryption for code protection.

🚀 Quick Start

Installation

npm install fuse-core-express

Basic Usage

The FuseCore uses a two-stage initialization pattern:

import FuseCore from 'fuse-core-express';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

// Stage 1: Initialize decryption
const privateKeyPath = path.join(__dirname, 'keys/recipient-keys-1.0.3.json');
await FuseCore.initDecryption(privateKeyPath);

// Stage 2: Initialize FuseCore (same as standard version)
await FuseCore.init({
    log: {
        level: 'info',
        format: 'json'
    },
    cache: {
        type: 'memory',
        maxSize: '100MB'
    },
    monitor: {
        enabled: true,
        interval: 5000
    }
});

// Use FuseCore API normally
// ... Your business logic ...

// Shutdown FuseCore
await FuseCore.shutdown();

📋 Detailed API Documentation

FuseCore.initDecryption(privateKeyPath)

Initialize the decryption process, this is the necessary first step for using FuseCore.

Parameters

• privateKeyPath (string): Path to the recipient private key file
  • Must be a JSON file containing the privateKey field
  • Typically named recipient-keys-{version}.json
  • Example path: ./keys/recipient-keys-1.0.3.json

Return Value

• Returns FuseCore instance (for method chaining)

Examples

// Use bundled key files (recommended for development/testing)
const privateKeyPath = path.join(__dirname, 'keys/recipient-keys-1.0.3.json');
await FuseCore.initDecryption(privateKeyPath);

// Use custom path key files
await FuseCore.initDecryption('/path/to/your/private-key.json');

Key File Format

The private key file should be in JSON format, containing the following fields:

{
  "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\n",
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIB...\n-----END PUBLIC KEY-----\n",
  "owner": "recipient",
  "timestamp": "2025-08-01T15:58:34.531Z"
}

FuseCore.init(options)

Initialize FuseCore instance, exactly the same API as the standard version.

Prerequisites

• ⚠️ Must call initDecryption() first

Parameters

• options (object): FuseCore configuration options
  • log: Logging configuration
  • cache: Cache configuration
  • monitor: Monitoring configuration
  • etc... (same as standard version)

Examples

await FuseCore.init({
    log: {
        level: 'debug',
        format: 'pretty',
        output: './logs'
    },
    cache: {
        type: 'redis',
        host: 'localhost',
        port: 6379
    },
    monitor: {
        enabled: true,
        interval: 3000,
        metrics: ['cpu', 'memory', 'requests']
    }
});

FuseCore.shutdown()

Shutdown FuseCore instance and clean up resources.

await FuseCore.shutdown();

🔐 Key Management

Method 1: Use Bundled Keys (Development/Testing)

The package includes ready-to-use key files:

const privateKeyPath = path.join(__dirname, 'keys/recipient-keys-1.0.3.json');
await FuseCore.initDecryption(privateKeyPath);

Method 2: Environment Variables (Production Recommended)

export FUSECORE_RECIPIENT_PRIVATE_KEY="$(cat /secure/path/recipient-private-key.pem)"
export FUSECORE_SIGNER_PUBLIC_KEY="$(cat /secure/path/signer-public-key.pem)"

// When environment variables exist, no parameters need to be passed
await FuseCore.initDecryption();

Method 3: Custom Key Files

await FuseCore.initDecryption('/custom/path/to/private-key.json');

📁 Package File Structure

node_modules/fuse-core-express/
├── index.js                    # Main entry file
├── secure-package.vxz          # Encrypted code package
├── decryptor.js               # Standalone decryptor
├── keys/                      # Key files directory
│   ├── build-version.json
│   ├── recipient-keys-1.0.3.json  # Recipient keys (contains private key)
│   ├── signer-keys-1.0.3.json     # Signer public key
│   └── README.md
├── example-usage.js           # Usage examples
└── package.json

🔄 Complete Usage Workflow

1. CommonJS Environment

const FuseCore = require('fuse-core-express');
const path = require('path');

async function initializeFuseCore() {
    try {
        // Decryption initialization
        const privateKeyPath = path.join(__dirname, 'keys/recipient-keys-1.0.3.json');
        await FuseCore.initDecryption(privateKeyPath);
        
        // FuseCore initialization
        await FuseCore.init({
            log: { level: 'info' },
            cache: { type: 'memory' }
        });
        
        // Use FuseCore...
        console.log('FuseCore initialized successfully');
        
    } catch (error) {
        console.error('Failed to initialize FuseCore:', error.message);
        process.exit(1);
    }
}

initializeFuseCore();

2. ES Module Environment

import FuseCore from 'fuse-core-express';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

async function initializeFuseCore() {
    try {
        // Decryption initialization
        const privateKeyPath = path.join(__dirname, 'keys/recipient-keys-1.0.3.json');
        await FuseCore.initDecryption(privateKeyPath);
        
        // FuseCore initialization
        await FuseCore.init({
            log: { level: 'info' },
            cache: { type: 'memory' }
        });
        
        // Use FuseCore...
        console.log('FuseCore initialized successfully');
        
    } catch (error) {
        console.error('Failed to initialize FuseCore:', error.message);
        process.exit(1);
    }
}

initializeFuseCore();

⚠️ Security Considerations

Development Environment

• ✅ Can use bundled key files for rapid development
• ✅ Key files are already included in the npm package, ready to use

Production Environment

• 🔐 Do not expose private keys on the client side
• 🔐 Use environment variables or key management services
• 🔐 Rotate keys regularly
• 🔐 Monitor key usage
• 🔐 Restrict access permissions to key files

Recommended Production Configuration

// Production environment recommended to use environment variables
if (process.env.NODE_ENV === 'production') {
    // Ensure environment variables are set
    if (!process.env.FUSECORE_RECIPIENT_PRIVATE_KEY) {
        throw new Error('FUSECORE_RECIPIENT_PRIVATE_KEY environment variable is required in production');
    }
    await FuseCore.initDecryption(); // Automatically use environment variables
} else {
    // Development environment use bundled keys
    const privateKeyPath = path.join(__dirname, 'keys/recipient-keys-1.0.3.json');
    await FuseCore.initDecryption(privateKeyPath);
}

🛠️ Troubleshooting

Common Errors

1. "FuseCore not decrypted. Call initDecryption(privateKeyPath) first."

Cause: Used FuseCore methods without calling initDecryption() first

Solution: Ensure to call await FuseCore.initDecryption(privateKeyPath) first

2. "Private key not found: /path/to/key.json"

Cause: Private key file path is incorrect or file doesn't exist

Solution:

• Check if the file path is correct
• Ensure the file exists and is readable
• Use absolute path or correct relative path

3. "Signature verification failed"

Cause: Private key doesn't match the encrypted package, or package is corrupted

Solution:

• Ensure using the correct version of key files
• Re-download the package or regenerate keys

4. "Key files not found in either ./keys/ or ../keys/ directories"

Cause: Cannot find the corresponding signer public key file

Solution: Ensure the signer-keys-{version}.json file exists in the keys directory

📚 More Examples

Check the example-usage.js file for complete usage examples.

🔗 Related Links

• FuseCore Standard Version Documentation
• Key Management Best Practices

📞 Support

If you encounter issues during use, please:

1. Check the troubleshooting section of this documentation
2. Review the example-usage.js examples
3. Submit an Issue to the project repository

Version: 1.0.3
Last Updated: 2025-08-02
Encryption Algorithm: AES-256-GCM + RSA-OAEP + RSA-PSS-SHA256