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

$3

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

``bash


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

$3

#### Installation
`bash


Remove old version

npm uninstall aws-lockbox

Install new version

npm install aws-lockbox@3
`

#### Code Changes Required

Old code (v2):
`javascript
const Lockbox = require('aws-lockbox');
const lb = new Lockbox.Lockbox(maxTries);
lb.exec();
lb.wait(maxWaits, waitMS); // Synchronous wait
`

New code (v3):
`javascript
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
`javascript
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:
`typescript
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

$3

`bash
npm install aws-lockbox
`

$3

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
`

$3

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

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

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

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

$3

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

$3


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

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

$3


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

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

$3

First, make the script executable (one-time setup):
`bash
chmod +x publish.sh
`

Then run the automated publish script:
`bash
./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

$3

Follow these steps to publish manually:

1. Ensure correct Node.js version:
`bash


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


Remove existing dependencies

rm -rf node_modules package-lock.json

Fresh install

npm install
`

3. Update version:
`bash


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


Rebuild the package

npm run rebuild

Run tests

npm test
`

5. Preview package contents:
`bash


Create tarball without publishing

npm pack

Review the contents

tar -tf aws-lockbox-*.tgz
`

6. Publish to npm:
`bash


Login to npm (if not already logged in)

npm login

Publish the package

npm publish

Push git tags

git push origin main --tags
``

$3

- [ ] 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