A simple way to encrypt/decrypt fields to/from a string bundle, using AES256-GCM with a randomly generated IV.
npm i aes256gcm-bundle
Encrypt / Decrypt
import CipherBundle from 'aes256gcm-bundle' const cb = new CipherBundle(base64urlEncodedKey) const bundle = cb.encrypt('Hello world') // e.g.: "0.YFG9joOntVvgLLYQ.QL7k4BFI8ot8PJeqTXOyXQ.fQGNGGwvoKEQXg0" const plainText = cb.decrypt(bundle) // e.g.: "Hello world"
Creating a CipherBundle
use a randomly generated base64url-encoded key (very secure)
import crypto from 'node:crypto' const key = crypto.randomBytes(32).toString('base64url') // example key: Bi-zMjDdm8ZuqbJQ5WstSwFUCLwVwsPcBQvah-pprSY let cb = new CipherBundle(key)
or provide a key in another encoding (utf8, base64, hex, ...)
cb = new CipherBundle(veryStrongPassword, 'utf8')
Text passed to
encrypt() creates a bundle in this dot-separated format:
keyNameis just a moniker that is set to
0by default, but you can override it to denote (to you) which key was used to encrypt the bundle. It can be set to a meaningful value (e.g.
prod0) and should be changed when rotating keys.
authTagcomponents are opaque base64url-encoded values that are needed to successfully decrypt the bundle.
cipherTextcomponent of the bundle is the AES256-GCM encryption of the plain text (with a random IV), encoded to a base64url string. The key used for encryption is the SHA-256 of the key that you provide when creating a
Key rotation / identification
To support key rotation/identification, you can pass an optional
keyName parameter to
encrypt(text, keyName). The default prefix is
keyName is not specified. The
keyName parameter changes the prefix on your bundle to a tag that allows you to later identify which key was used to encrypt the bundle, under your own naming conventions. The name should be short but meaningful (example
prod1), cannot include the
. character, and should be changed alongside a key rotation (e.g. to
It is up to you to determine an appropriate key rotation schedule - after a billion encryptions with the same key, it is probably time to choose a new key! Since the IV is randomly generated, there is a very small chance of a duplicate IV after many encryptions - this is significant known risk for AES256-GCM, but it can be mitigated by periodic key rotations.
Here is an example of setting a custom prefix for the bundle to identify the use of a new key:
cb = new CipherBundle(prod1Key) const bundle = cb.encrypt('Hello world', "prod1") // example bundle: prod1.VqUyV8dr33MRITD5.7LiH24gOXaoGHw9sfJMNKA.r00A78iuZWNd748 const plainText = cb.decrypt(bundle) // example plainText: Hello world