Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

πŸ”‘πŸ’Œ keystash

Save secrets in AWS S3 with KMS envelope encryption

  • Save key/value pairs in an S3 Bucket with KMS envelope encryption
  • Additional serverside encryption with S3
  • Automatic S3 versioning for durability
  • Generate random key data
  • Use as a module
  • Bundles a simple CLI

Perfect for:

  • Centralized key management with minimalist command line interface
  • Environment variables in modules and npm scripts
  • Lightweight and secure personal key value store



  • AWS account credentials setup .aws/credentials
  • AWS_PROFILE and AWS_REGION environment variables

✨ Tip export default AWS_PROFILE and AWS_REGION env vars your in .bashrc or .bash_profile and override as neccessary on the command line or in package.json to make working with different stashes easy


npm i -g keystash

command line interface

keystash <bucket name> [options]


Setup an S3 bucket:

  • keystash my-bucket --create create an S3 bucket for storing secrets

Read secrets:

  • keystash my-bucket read encrypted secrets from S3 bucket
  • keystash my-bucket BIG_SEKRET to read a value to stdout

Write secrets:

  • keystash my-bucket BIG_SEKRET xxx-xxx save a secret BIG_SEKRET with value xxx-xxx
  • keystash my-bucket --rand BIG_SEKRET to generate (really!) random key data
  • keystash my-bucket --delete BIG_SEKRET remove BIG_SEKRET
  • keystash my-bucket --reset remove all secrets from latest version

Working with versions:

  • keystash my-bucket --versions list all versions
  • keystash my-bucket --versions some-version-id get secrets for a given version
  • keystash my-bucket --versions some-version-id some-key get the key for the given version
  • keystash my-bucket --nuke remove all versions

Run keystash --help to see short switches.

module install and usage

Use this module in npm scripts.

npm i keystash --save
// package.json
  "start": "DB_URL=${keystash some-bucket DB_URL} node index"

Or a bash script:

DB_URL=`keystash cred-bucket DB_URL`

node index

Or in module code itself:

var keystash = require('keystash'){ns: 's3-bucket-name'}, console.log)

See tests for more examples!


var keystash = require('keystash')
  • keystash.create({ns}, err=>) create a keystash S3 bucket
  • keystash.delete({ns, key}, (err, result)=>) remove a key
  • keystash.env({ns}, err=>) add secrets to process.env
  • keystash.nuke({ns}, err=>) remove all versions
  • keystash.rand({key}, (err, result)=>) generate a random key
  •{ns}, (err, result)=>) get all secrets
  •{ns, version}, (err, result)=>) get all secrets for given version
  • keystash.reset({ns}, (err, result)=>) remove all secrets from the current version
  • keystash.versions({ns}, (err, result)=>) get all versions
  • keystash.write({ns, key, value}, (err, result)=>) save a secret


This module is inspired by credstash. This module differs in that its JavaScript instead of Python and uses S3 to persist secrets instead of Dynamo. Read more about credstash here.

Also thx to Matt Weagle for encouraging KMS envelope encryption and Ben Kehoe for suggesting to use the S3 Object Metadata property to store the KMS cipher.


πŸ”‘πŸ’Œ Save secrets in S3 using KMS envelope encryption






No releases published


No packages published