envelope_encryption-notes.md

RE: envelope_encryption

Repository.

OSS items

A few notes. First, if we're planning to link the demo from a blog post, I'd be happy to check a couple of boxes on community-friendliness by:

• adding a LICENSE, README (with install/usage, a bit of background, and link back to blog post) and package.json with fixed versions of deps and a known-good engine.

• dropping the AWS REGION override for everyone testing via standard / us-east-1 and linking AWS SDK docs from README instead

• extracting tests to a separate module (maybe two--separate entrypoints for un/mocked KMS implementations).

Implementation

A few small, mostly stylistic items jumped out while I was reading.

First, consider leaving returned objects intact where there would otherwise be a prefixed variable. For instance,

// const { cipherText: tmkCipherText, plainText: tmkPlainText } = (await createTenantMasterKey(cmkId));
const tmk = await createTenantMasterKey(cmkId);

...tmk.cipherText is an extra character, but (IMO) a bit easier for a reader to parse.

Second, inline comments may clarify constants/design decisions that aren't immediately obvious:

// Return `base64` to avoid encoding issues in the DB / over the wire
return (Buffer.concat([decipher.update(cipherText, cipherTextEnc), decipher.final()])).toString('base64');

const { Plaintext } = await kms.generateRandom({
  NumberOfBytes: 32, // for 256 bit key
}).promise();

Finally, consider pulling metrics (i.e., start...elapsed in the {encrypt|decrypt}Envelope family) out to a separate wrapper to be composed on demand. Ideally we keep this code focused on the envelope flow; KMS benchmarking (e.g.) may make for an interesting follow-up post, though!