npm package: @industriousoffice/local-beeswax
Description: CLI tool for encrypting/decrypting beeswax-compatible vault files using AWS KMS and Encryption SDK
Author: IndustriousOfficeLLC
Latest version: 1.0.0

# 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:
```bash
npm install
```

2. Build the project:
```bash
npm run build
```

3. (Optional) Link the CLI globally:
```bash
npm link
```

## Usage

### CLI Commands

#### Encrypt a file to create a beeswax vault file
```bash
vault encrypt <input-file> <output-file> <kms-key-id> <application> <stack> <component>
```

Example:
```bash
vault encrypt config.env app.vault alias/local-app-vault-configuration access-control-service local app
```

#### Decrypt a beeswax vault file
```bash
vault decrypt <input-file> <output-file>
```

Example:
```bash
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:
```bash
# 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:

```bash
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

```typescript
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:

```json
{
    "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