Env

Orion Env is a robust utility for securely managing environment variables directly in your source control. Unlike traditional .env files that must be excluded from repositories, Orion Env allows you to safely commit your configuration to your codebase using public key, elliptic curve cryptography.

This package works as a standalone package. It does not depend on any other Orion.js packages.

​

Key Features

• Secure Storage: Encrypt sensitive data with strong cryptography
• Source Control Integration: Store all configurations directly in your repository
• TypeScript Support: Automatically generate TypeScript definitions for your environment variables
• Secret Manager Integration: Read variables from JSON-formatted environment variables populated by secret managers
• Flexible Usage: Access environment variables directly or load them into process.env

​

Installation

pnpm add @orion-js/env

​

Getting Started

​

Creating a new Env configuration file

Run the following command in your project. You’ll receive a password that you’ll need to keep secure - it’s required to decrypt your environment variables.

pnpm orion-env init --path=<path>

This will create a new configuration file at the specified path with an initial setup.

​

Adding environment variables

To add a new environment variable to your configuration:

pnpm orion-env add --path=<path>

This interactive command will prompt you for:

• The variable name
• The variable value

​

Reading variables in your application

There are two main approaches to using your environment variables:

​

1. Direct access via the env object

import { env } from '@orion-js/env'

// Access variables directly
const databaseUrl = env.DATABASE_URL
const apiKey = env.API_KEY

​

2. Loading into process.env

import { loadEnv } from '@orion-js/env'

// Load all variables into process.env
loadEnv()

// Now use process.env as usual
const databaseUrl = process.env.DATABASE_URL

​

Configuration Options

​

Environment Setup

For either approach, you’ll need to configure these environment variables:

• ORION_ENV_FILE_PATH: Path to your Orion Env configuration file
• ORION_ENV_SECRET_KEY: The password to decrypt encrypted variables

You can set these using traditional methods (environment variables, .env files, etc.)

​

loadEnv Options

The loadEnv() function accepts the following options:

loadEnv({
  // Secret password used to decrypt the encrypted env file
  // Default: process.env.ORION_ENV_SECRET_KEY
  secretKey: 'your-secret-key',

  // Location of the file to read
  // Default: process.env.ORION_ENV_FILE_PATH
  envFilePath: './config/env.yml',

  // Whether to override existing process.env variables
  // Default: process.env.ORION_ENV_OVERRIDE === truthy
  override: true
})

​

TypeScript Integration

Orion Env can automatically generate TypeScript definition files for your environment variables, providing autocomplete and type checking.

import { writeDtsFileFromConfigFile } from '@orion-js/env'

// Generate types file from your config
writeDtsFileFromConfigFile('./config/env.yml', './types/env.d.ts')

This will create a declaration file that defines the types for all your environment variables, enabling full TypeScript support.

​

Secret Manager Integration

You can configure Orion Env to read variables from JSON-formatted environment variables, which can be populated from secret managers like AWS Secrets Manager, HashiCorp Vault, or similar services.

​

Configuration

In your Orion Env configuration file, add a readFromSecret section that maps environment variable names to arrays of variable keys:

version: '1'
publicKey: '...'
cleanKeys:
  PUBLIC_URL: 'https://example.com'
encryptedKeys:
  DATABASE_PASSWORD: '...'
readFromSecret:
  AWS_SECRETS:
    - DATABASE_URL
    - API_KEY
  GCP_SECRETS:
    - SERVICE_ACCOUNT_KEY
    - STORAGE_BUCKET

​

How it works

1. Orion Env looks for environment variables specified in the readFromSecret object (e.g., AWS_SECRETS).
2. If found, it parses the value as JSON.
3. For each variable name in the array (e.g., DATABASE_URL), it looks for corresponding properties in the parsed JSON.
4. These values become available in the env object alongside your other variables.

​

Secret Key Discovery

If the JSON content contains an ORION_ENV_SECRET_KEY property, Orion Env will use that value as the secret key for decrypting your encrypted variables. This allows you to store your decryption password in the secret manager as well.

Example JSON in process.env.AWS_SECRETS:

{
  "DATABASE_URL": "postgresql://user:pass@localhost:5432/db",
  "API_KEY": "xyz123",
  "ORION_ENV_SECRET_KEY": "my-decryption-password"
}

​

Best Practices

1. Rotate Keys Regularly: Periodically update your encryption keys and regenerate your configuration.
2. Use CI/CD Variables: For production environments, consider storing your secret key in CI/CD variables.
3. Clean vs. Encrypted: Only store sensitive data (API keys, passwords) as encrypted; public URLs and non-sensitive configs can use cleanKeys.
4. Version Control: Always include your env configuration file in version control - that’s the whole point!

​

CLI Reference

​

init

pnpm orion-env init --path=<path>

Creates a new Orion Env configuration file with auto-generated encryption keys.

​

add

pnpm orion-env add --path=<path>

Interactively add a new environment variable to your configuration.

​

read

pnpm orion-env read --path=<path> --key=<key>

Decrypt and display the value of a specific environment variable.

​

File Format

The Orion Env configuration file uses YAML format with the following structure:

version: '1'
publicKey: '...'
cleanKeys:
  # Non-sensitive variables stored as plaintext
  PUBLIC_URL: 'https://example.com'
  NODE_ENV: 'development'
encryptedKeys:
  # Sensitive variables stored encrypted
  DATABASE_PASSWORD: '...'
  API_SECRET: '...'
readFromSecret:
  # Variables to read from JSON environment variables
  AWS_SECRETS:
    - DATABASE_URL
    - API_KEY