AWS Lockbox

A TypeScript library for managing AWS Parameter Store (SSM) secrets in Node.js applications. Automatically loads parameters into process.env on startup.

Note: Requires Node.js 16 or later.

Development

Node.js Version

This project uses Node.js 20.15.0. We recommend using nvm to manage Node.js versions.

# Install the correct version
nvm install

# Use the correct version
nvm use

⚠️ Breaking Changes in Version 3.0.0

This version includes several breaking changes:

1. AWS SDK v3 Migration

   • Upgraded from AWS SDK v2 to v3
   • New modular AWS SDK structure
   • Different error handling patterns

2. TypeScript Support

   • Package is now written in TypeScript
   • Includes type definitions
   • Better error handling and type safety

Migration Guide from v2 to v3

Installation

# Remove old version
npm uninstall aws-lockbox

# Install new version
npm install aws-lockbox@3

Code Changes Required

Old code (v2):

const Lockbox = require('aws-lockbox');
const lb = new Lockbox.Lockbox(maxTries);
lb.exec();
lb.wait(maxWaits, waitMS);  // Synchronous wait

New code (v3):

const { Lockbox } = require('aws-lockbox');  // or import { Lockbox } from 'aws-lockbox';

async function init() {
  try {
    const maxTries = 100;  // Max retries for fetching parameters
    const lb = new Lockbox(maxTries);
    
    // Execute and fetch parameters
    await lb.exec();  // Now returns a Promise
    
    // Wait for parameters to be set (optional)
    const maxWaits = 10;   // Maximum number of retries
    const waitMS = 100;    // Time between retries in milliseconds
    await lb.wait(maxWaits, waitMS);  // Now returns a Promise
    
    console.log('Parameters loaded successfully');
  } catch (err) {
    console.error('Failed to load parameters:', err);
  }
}

init();

Configuration Changes

Your existing lockbox directory structure will continue to work with v3. The main differences are:

1. Async/Await Support

   • All operations are now Promise-based
   • Need to use await with exec() and wait()

2. AWS SDK v3 Error Handling

   try {
     const lb = new Lockbox();
     await lb.exec();
   } catch (err) {
     // AWS SDK v3 error format is different
     console.error('Failed to load parameters:', err);
   }

3. TypeScript Support (Optional)

   • If using TypeScript, you can import types:

   import { Lockbox } from 'aws-lockbox';
   import type { LockboxConfig } from 'aws-lockbox';

Your existing configuration files in the lockbox directory will work without changes:

lockbox/
    - production.js
    - development.js
    - default.js

Getting Started

Installation

npm install aws-lockbox

Directory Structure

1. Your variables need to be available in AWS Parameter Store (SSM)
2. Create a lockbox directory in your project root with the following structure:

lockbox/
    - production.js
    - stage.js
    - development.js
    - local.js
    - default.js

Configuration Files

default.js

This is where you put the name of the keys that you wish to pull from Parameter Store:

module.exports = {
  parameters: [
    "/aws-lockbox/test/secret1",
    "/aws-lockbox/test/secret2",
    "/aws-lockbox/test/api-key"
  ],
  overrides: []
};

Environment-specific Files (e.g., development.js, production.js)

These files can extend the default configuration and provide environment-specific overrides:

const defaultConfig = require('./default.js');

module.exports = {
  parameters: defaultConfig.parameters,
  overrides: [
    {
      Name: "/aws-lockbox/test/secret1",
      Value: "local-development-value"
    }
  ]
};

Initialization

import { Lockbox } from 'aws-lockbox';

async function init() {
  // The max number of tries you want to attempt before throwing an error
  const maxTries = 100;
  const lb = new Lockbox(maxTries);
  
  // Execute and fetch parameters
  await lb.exec();
  
  // Optional: Wait for parameters to be set
  const waitMS = 100;    // Time between retries
  const maxWaits = 10;   // Maximum number of retries
  await lb.wait(maxWaits, waitMS);
}

Features

• Written in TypeScript for better type safety and development experience
• Uses AWS SDK v3 for better modularity and performance
• Automatic retries with exponential backoff for throttled requests
• Environment-specific configuration support
• Local parameter overrides for development
• Async/await based API
• Type definitions included

Configuration Details

Parameters Array

The parameters array in your configuration files defines what parameters to fetch from AWS SSM:

module.exports = {
  parameters: [
    "/my-app/database/url",
    "/my-app/api/key",
    "/my-app/secrets/token"
  ]
};

Overrides Array

The overrides array allows you to specify local values, particularly useful for development:

module.exports = {
  parameters: [...],
  overrides: [
    {
      Name: "/my-app/database/url",
      Value: "localhost:5432"
    }
  ]
};

Environment Selection

The library automatically selects the configuration file based on NODE_ENV:

• If NODE_ENV=production, it looks for lockbox/production.js
• If NODE_ENV=development, it looks for lockbox/development.js
• If no environment-specific file is found, it falls back to lockbox/default.js

AWS Configuration

The library uses AWS SDK v3's SSMClient. Make sure you have proper AWS credentials configured either through:

• Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
• AWS credentials file
• IAM role (if running on AWS infrastructure)

Your IAM role/user needs permissions to access the AWS Systems Manager Parameter Store:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameters"
      ],
      "Resource": "arn:aws:ssm:region:account-id:parameter/*"
    }
  ]
}

Error Handling

The library includes built-in error handling for common scenarios:

• Throttling: Automatically retries with exponential backoff
• Missing parameters: Returns clear error messages
• Timeout: Configurable timeout with maxTries and waitMS
• Configuration: Validates configuration format and provides clear error messages

Publishing to npm

For maintainers, there are two ways to publish a new version:

Option 1: Using the Publish Script (Recommended)

First, make the script executable (one-time setup):

chmod +x publish.sh

Then run the automated publish script:

./publish.sh

The script will:

1. Verify npm login status
2. Verify Node.js version using nvm
3. Clean install dependencies
4. Show current version and optionally update it
   • Choose to keep current version
   • Or update to patch/minor/major version
5. Build and test
6. Preview package contents
7. Confirm before publishing
8. Publish to npm
9. Show git tags that need to be pushed

After publishing, you'll need to manually:

1. Review the generated git tags
2. Push the tags when ready: git push origin main --tags

Option 2: Manual Publishing

Follow these steps to publish manually:

1. Ensure correct Node.js version:

# Verify and switch to the correct Node.js version
nvm use

# Verify @types/node matches Node.js version
npm run update-types

2. Clean install dependencies:

# Remove existing dependencies
rm -rf node_modules package-lock.json

# Fresh install
npm install

3. Update version:

# For patches (bug fixes)
npm version patch

# For minor releases (new features)
npm version minor

# For major releases (breaking changes)
npm version major

4. Build and test:

# Rebuild the package
npm run rebuild

# Run tests
npm test

5. Preview package contents:

# Create tarball without publishing
npm pack

# Review the contents
tar -tf aws-lockbox-*.tgz

6. Publish to npm:

# Login to npm (if not already logged in)
npm login

# Publish the package
npm publish

# Push git tags
git push origin main --tags

Publishing Checklist

• [ ] Correct Node.js version (check .nvmrc)
• [ ] Dependencies are clean installed
• [ ] Version updated in package.json
• [ ] CHANGELOG.md updated (if exists)
• [ ] All tests pass
• [ ] Build is clean (no warnings)
• [ ] Package contents reviewed
• [ ] Published to npm
• [ ] Git tags pushed
• [ ] TypeScript types verified (@types/node matches Node.js version)

License

ISC