Local App Vaults CLI

A CLI tool for managing beeswax-compatible encrypted vault files using AWS KMS and the AWS Encryption SDK. This tool allows you to securely encrypt and decrypt configuration files and sensitive data using the same format as beeswax.

Features

• Beeswax Compatibility: Creates and reads vault files in the same format as beeswax
• AWS Encryption SDK: Uses envelope encryption with the AWS Encryption SDK
• AWS KMS Integration: Supports KMS key aliases and ARNs
• CLI Interface: Easy-to-use command-line tool
• TypeScript: Fully typed for better development experience
• Error Handling: Proper error handling and user feedback

Installation

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. (Optional) Link the CLI globally:

npm link

Usage

CLI Commands

Encrypt a file to create a beeswax vault file

vault encrypt <input-file> <output-file> <kms-key-id> <application> <stack> <component>

Example:

vault encrypt config.env app.vault alias/local-app-vault-configuration access-control-service local app

Decrypt a beeswax vault file

vault decrypt <input-file> <output-file>

Example:

vault decrypt app.vault config.env

Options

• --region <region>: AWS region (default: us-east-1 or AWS_REGION env var)
• --profile <profile>: AWS profile to use
• -h, --help: Show help

Quiet Mode

Set the QUIET environment variable to suppress verbose output:

# Suppress CLI verbose output
QUIET=true vault encrypt
QUIET=1 vault encrypt

# Normal verbose output
vault encrypt

Note: Errors and warnings will always be displayed, even in quiet mode.

Development Usage

You can also use the CLI in development mode:

npm run dev encrypt config.env app.vault alias/my-kms-key myapp prod api
npm run dev decrypt app.vault config.env

Programmatic Usage

import { VaultManager } from 'local-app-vaults-cli';

async function example() {
    const vault = new VaultManager({ region: 'us-east-1' });

    // Encrypt a file to beeswax vault format
    await vault.encryptToVaultFile(
        'config.env', 
        'app.vault', 
        'alias/my-kms-key',
        { 
            application: 'myapp', 
            stack: 'prod', 
            component: 'api' 
        }
    );

    // Decrypt a beeswax vault file
    const decryptedContent = await vault.decryptVaultFile('app.vault');
    console.log(decryptedContent);
}

AWS Configuration

The CLI uses the AWS SDK, which will automatically use your AWS credentials from:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
2. AWS credentials file (~/.aws/credentials)
3. IAM roles (if running on EC2/ECS/Lambda)

Required IAM Permissions

Your AWS credentials need the following KMS permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:GenerateDataKey"
            ],
            "Resource": "arn:aws:kms:region:account:key/key-id"
        }
    ]
}

Environment Variables

• AWS_REGION: Default AWS region
• AWS_PROFILE: Default AWS profile
• AWS_ACCESS_KEY_ID: AWS access key
• AWS_SECRET_ACCESS_KEY: AWS secret key

Scripts

• npm run build: Build the TypeScript project
• npm run start: Run the built CLI
• npm run dev: Run the CLI in development mode with ts-node
• npm run test: Run tests
• npm run lint: Run ESLint
• npm run clean: Clean the dist directory

Directory Structure

local-app-vaults/
├── src/
│   ├── cli.ts              # CLI implementation
│   ├── vault-manager.ts    # Core VaultManager class
│   └── index.ts           # Main exports
├── dist/                  # Built JavaScript files
├── package.json
├── tsconfig.json
└── README.md

License

MIT