Zipherly

Simplified secure encryption for Node.js web applications.

Overview

Zipherly is a user-friendly encryption library designed to simplify data security in Node.js applications. By abstracting away the complexities of cryptography, Zipherly enables developers to implement strong encryption with minimal effort through a JSON-based configuration system.

Key Features

• Simple Configuration - JSON-based config system with sensible defaults
• Strong Encryption - AES-256-GCM, AES-256-CBC, and ChaCha20-Poly1305 support
• Data Integrity - HMAC signatures for tamper protection
• Express Integration - Middleware for automatic API payload encryption
• Key Management - Tools for key generation, rotation, and secure storage
• Type Definitions - Full TypeScript support

Installation

npm install zipherly

Quick Start

1. Create a configuration file

Create a zipherly.config.json file in your project root:

{
  "encryption": {
    "symmetric": {
      "algorithm": "aes-256-gcm",
      "keySource": "ENV_ZIPHERLY_KEY"
    }
  },
  "hashing": {
    "algorithm": "sha256",
    "hmac": {
      "enabled": true,
      "secretSource": "ENV_ZIPHERLY_HMAC_SECRET"
    }
  },
  "security": {
    "disallowWeakAlgorithms": ["md5", "sha1", "des"]
  }
}

2. Set environment variables

# Generate a secure random key (base64 encoded)
export ZIPHERLY_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('base64'))")
export ZIPHERLY_HMAC_SECRET=$(node -e "console.log(require('crypto').randomBytes(64).toString('base64'))")

3. Use Zipherly in your application

const Zipherly = require('zipherly');
const zipherly = new Zipherly();

// Encrypt data
const encrypted = zipherly.encrypt({ username: 'johndoe', role: 'admin' });
console.log('Encrypted:', encrypted);

// Decrypt data
const decrypted = zipherly.decrypt(encrypted);
console.log('Decrypted:', decrypted);

// Sign data
const signed = zipherly.sign({ orderId: '12345', total: 99.99 });
console.log('Signed:', signed);

// Verify signature
const isValid = zipherly.verify(signed);
console.log('Signature valid:', isValid);

4. Use with Express.js

const express = require('express');
const Zipherly = require('zipherly');

const app = express();
app.use(express.json());

const zipherly = new Zipherly();

// Apply encryption middleware to all /api routes
app.use('/api', zipherly.expressMiddleware({
  encryptResponse: true,
  decryptRequest: true
}));

app.post('/api/data', (req, res) => {
  // Request body is automatically decrypted
  console.log('Received:', req.body);
  
  // Response will be automatically encrypted
  res.json({ status: 'success', message: 'Data received' });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Configuration Options

Zipherly uses a JSON schema for configuration. Here are the main options:

Encryption

"encryption": {
  "symmetric": {
    "algorithm": "aes-256-gcm",
    "keySource": "ENV_ZIPHERLY_KEY",
    "ivGeneration": "randomBytes"
  }
}

| Option | Description | Default | |--------|-------------|---------| | algorithm | Encryption algorithm | aes-256-gcm | | keySource | Source of encryption key (env variable or file path) | ENV_ZIPHERLY_KEY | | ivGeneration | Method to generate initialization vector | randomBytes |

Hashing

"hashing": {
  "algorithm": "sha256",
  "hmac": {
    "enabled": true,
    "secretSource": "ENV_ZIPHERLY_HMAC_SECRET"
  }
}

| Option | Description | Default | |--------|-------------|---------| | algorithm | Hashing algorithm | sha256 | | hmac.enabled | Enable HMAC signatures | true | | hmac.secretSource | Source of HMAC secret | ENV_ZIPHERLY_HMAC_SECRET |

Security

"security": {
  "disallowWeakAlgorithms": ["md5", "sha1", "des"],
  "enforceIvUniqueness": true,
  "keyRotationDays": 90
}

| Option | Description | Default | |--------|-------------|---------| | disallowWeakAlgorithms | Algorithms not allowed | ["md5", "sha1", "des"] | | enforceIvUniqueness | Enforce IV uniqueness | true | | keyRotationDays | Days before key rotation is recommended | 90 |

For more configuration options, see the configuration guide.

API Reference

Core Methods

• encrypt(data, options) - Encrypt data
• decrypt(encryptedData, options) - Decrypt data
• sign(data, options) - Sign data for integrity verification
• verify(signedData, options) - Verify signed data
• hash(data, options) - Create a hash of data
• deriveKey(password, options) - Derive a key from a password
• generateKey(length) - Generate a cryptographically secure random key

Middleware

• expressMiddleware(options) - Create Express.js middleware

Key Management

• isKeyRotationNeeded(keyPath) - Check if a key needs rotation
• rotateKey(keyPath, length) - Rotate a key

Examples

See the examples/ directory for more examples:

• express-basic.js - Basic Express.js integration
• api-security.js - Different approaches to API payload security
• key-rotation.js - Key rotation and management

Security Best Practices

1. Use GCM Mode - Prefer aes-256-gcm over CBC mode for authenticated encryption
2. Strong Keys - Use cryptographically secure random keys
3. Secure Storage - Store keys in environment variables or secure key management systems
4. Regular Rotation - Rotate keys regularly (90 days recommended)
5. Defense in Depth - Use Zipherly alongside TLS/HTTPS, not as a replacement

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Roadmap

See our roadmap for upcoming features:

• Asymmetric encryption (RSA, ECC)
• Additional KDF methods (Argon2id)
• Support for more frameworks (NestJS, Fastify)
• Plugin system for custom algorithms