ts-env

A TypeScript utility for securely managing environment variables through file encryption and runtime loading.

Overview

ts-env provides two main functionalities:

1. CLI Tool: Encrypt and decrypt environment files using AES-128-CBC encryption
2. Runtime Library: Load encrypted environment files as Node.js environment variables

Installation

npm install @j2blasco/ts-env

CLI Usage

The ts-env command-line tool allows you to encrypt and decrypt environment files.

Prerequisites

Before using the CLI, you need to set an environment variable containing your encryption key:

# For environment type "alpha"
export ENV_ALPHA_KEY="your-128-bit-hex-key"

# For environment type "production"  
export ENV_PRODUCTION_KEY="your-128-bit-hex-key"

Note: The key must be a 32-character hexadecimal string (128-bit). You can generate one at https://generate-random.org/encryption-key-generator.

File Naming Convention

Environment files must follow the naming pattern: env.{environment-type}.json

Examples:

• env.alpha.json
• env.beta.json
• env.production.json

Encrypting Files

# Encrypt an environment file
ts-env encrypt path/to/env.alpha.json

# The file will be encrypted in-place

Decrypting Files

# Decrypt an environment file
ts-env decrypt path/to/env.alpha.json

# The file will be decrypted in-place

Runtime Usage

Use the setEnvironment function to load encrypted environment files into process.env at runtime.

Basic Example

import { setEnvironment } from '@j2blasco/ts-env';

async function initializeApp() {
  try {
    await setEnvironment({
      envPath: './config',
      envType: 'alpha'
    });
    
    // Environment variables are now available in process.env
    console.log(process.env.DATABASE_URL);
    console.log(process.env.API_KEY);
  } catch (error) {
    console.error('Failed to load environment:', error);
  }
}

initializeApp();

Function Parameters

• envPath: Directory containing the environment file
• envType: Environment type (used to construct filename and find encryption key)

How It Works

1. Constructs filename as env.{envType}.json in the specified path
2. Looks for encryption key in environment variable ENV_{ENVTYPE}_KEY
3. Decrypts the file to a temporary location
4. Parses the JSON content
5. Sets all key-value pairs as environment variables in process.env
6. Cleans up temporary files

Environment File Format

Environment files should be valid JSON with string key-value pairs:

{
  "DATABASE_URL": "postgresql://localhost:5432/mydb",
  "API_KEY": "secret-api-key",
  "NODE_ENV": "production",
  "PORT": "3000"
}

Security Features

• AES-128-CBC Encryption: Industry-standard encryption algorithm
• Random IV: Each encryption uses a fresh initialization vector
• File Markers: Encrypted files are marked to prevent double-encryption
• Key Validation: Ensures encryption keys are the correct length
• Temporary Decryption: Files are decrypted to temporary locations only

Error Handling

The library provides detailed error messages for common issues:

• Missing encryption keys
• Invalid key lengths
• File not found
• Invalid JSON format
• Decryption failures

Development Scripts

# Encrypt environment file (development)
npm run env:encrypt

# Decrypt environment file (development)  
npm run env:decrypt

# Use built CLI tool
npm run env:bin:encrypt
npm run env:bin:decrypt

License

MIT

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.