node-sops 🔐

A robust, easy-to-use secrets management solution for Node.js projects, inspired by Mozilla SOPS but purpose-built for JavaScript/TypeScript environments.

🌟 Features

• Military-Grade Encryption: AES-256-GCM authenticated encryption for your sensitive data
• Multiple Format Support: Works seamlessly with YAML and JSON files
• Easy Key Management: Simple key generation and secure sharing capabilities
• Developer-Friendly API: Clean programmatic interface for integration
• Powerful CLI: Comprehensive command-line tools for manual operations
• TypeScript Support: Built with type safety for modern development
• Zero External Crypto Dependencies: Uses Node.js built-in crypto module
• Minimal Dependencies: Lightweight with few production dependencies

📋 Table of Contents

• Installation
• Quick Start
• CLI Usage
• Programmatic Usage
• File Formats
• Security Best Practices
• Advanced Usage
• Migration Guide
• Contributing
• License

🚀 Installation

npm install node-sops

Or with Yarn:

yarn add node-sops

🏃‍♂️ Quick Start

1. Initialize a new encryption key:

   npx node-sops init

2. Create a YAML or JSON file with your secrets:

   # secrets.yaml
   data:
     api:
       key: "your-api-key"
       secret: "your-api-secret"

3. Encrypt your secrets:

   npx node-sops encrypt -i secrets.yaml -o secrets.enc.json

4. Add .sops-key to your .gitignore file and commit only the encrypted file.

🖥️ CLI Usage

Initialize a new encryption key

npx node-sops init

Encrypt a secrets file

npx node-sops encrypt -i secrets.yaml -o secrets.enc.json

Decrypt a secrets file

npx node-sops decrypt -i secrets.enc.json -o secrets.yaml

View decrypted content without writing to a file

npx node-sops view -i secrets.enc.json

Get a specific value using dot notation

npx node-sops get -i secrets.enc.json -k data.api.key

Rotate encryption key

npx node-sops rotate -i secrets.enc.json -o secrets.enc.json

💻 Programmatic Usage

const { Sops } = require('node-sops');

// Create a new instance
const sops = new Sops();

// Initialize a new key (if not already created)
try {
  sops.initialize();
} catch (error) {
  // Key already exists
}

// Encrypt a file
sops.encrypt('secrets.yaml', 'secrets.enc.json');

// Decrypt a file
sops.decrypt('secrets.enc.json', 'secrets.yaml');

// View decrypted content
const data = sops.view('secrets.enc.json');
console.log(data);

// Get a specific value using dot notation
const apiKey = sops.get('secrets.enc.json', 'data.api.key');
console.log(apiKey);

For TypeScript users:

import { Sops } from 'node-sops';

// Same API as above, with full type safety
const sops = new Sops();
const config = sops.view('secrets.enc.json');
// config is properly typed!

📄 File Formats

node-sops supports both YAML and JSON files for plaintext secrets, with the encrypted output always in JSON format.

Example YAML input:

data:
  # API credentials
  api:
    key: your_api_key
    secret: your_api_secret
  
  # Database credentials
  database:
    username: db_user
    password: db_password

After encryption (JSON format):

{
  "iv": "base64_encoded_initialization_vector",
  "content": "base64_encoded_encrypted_content",
  "metadata": {
    "encryptedAt": "2023-04-25T12:00:00.000Z",
    "version": "1.0"
  }
}

🔒 Security Features and Best Practices

Security Features

• Authenticated Encryption: Uses AES-256-GCM to protect against tampering and ensure data integrity
• Secure Key Storage: Keys are stored with 0o600 permissions (user read/write only)
• Key Permission Verification: Warns when key files have insecure permissions
• Secure Temporary Files: Uses random names and secure deletion for sensitive temporary files
• Version-Aware Encryption: Format includes version markers for future algorithm upgrades

Best Practices

1. Never commit the key file (.sops-key) to git
2. Add .sops-key to your .gitignore file
3. Share the key securely with team members who need access
4. Only commit the encrypted files to version control
5. Consider using environment variables for production deployments
6. Rotate keys periodically for enhanced security
7. Use role-based access control for key management in team settings
8. Check the SECURITY.md file for detailed security information

🧩 Advanced Usage

Environment Variable Integration

const { Sops } = require('node-sops');

function loadSecrets() {
  const sops = new Sops();
  const secrets = sops.view('secrets.enc.json');
  
  // Add secrets to process.env
  Object.entries(secrets.data).forEach(([key, value]) => {
    if (typeof value === 'string') {
      process.env[key.toUpperCase()] = value;
    }
  });
}

// Call early in your application bootstrap
loadSecrets();

Custom Key Path

const sops = new Sops({ keyPath: '/custom/path/to/.custom-key' });

In-Memory Operations

// Encrypt content directly
const plainContent = { api: { key: 'secret_value' } };
const encrypted = sops.encryptContent(plainContent);

// Decrypt content directly
const decrypted = sops.decryptContent(encrypted);

👥 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with watch mode
npm run test:watch

# Build the project
npm run build

# Lint the codebase
npm run lint

📜 License

MIT