simple-secure-webcrypto
v2.0.1
Published
Simple and secure encrypt/decrypt functions using Web Crypto API and no dependencies
Downloads
658
Readme
simple-secure-webcrypto
This Simple Secure WebCrypto library was created to make it easy to do symmetric encryption and decryption of strings using the Web Crypto API, which provides the SubtleCrypto interface with low-level cryptographic functions.
Features
✅ Zero package dependencies - exclusively uses WebCrypto API.
✅ Works on browser platforms like Cloudflare Workers.
✅ Secure defaults; uses AES-GCM (authenticated encryption) with a 256 bit key.
✅ Written in TypeScript.
Who is this library for?
If you're a developer building on platforms such as Cloudflare Pages or Cloudflare Workers and want to easily encrypt and decrypt some data with just an secret from an environment variable, this library provides a simple interface to do so.
Usage
Install via your package manager:
bun install simple-secure-webcrypto
Then invoke the async encrypt
and decrypt
functions:
import { encrypt, decrypt } from "simple-secure-webcrypto";
const someData = "hello world";
try {
const encrypted = await encrypt(env.ENCRYPTION_SECRET, someData);
const decrypted = await decrypt(env.ENCRYPTION_SECRET, encrypted);
} catch (error) {
console.log(error);
}
Note: the decrypt
function will throw an error if the encrypted data is in an invalid format.
To generate a new random encryption secret key, we created the genkey.ts
helper:
import { generateKey } from "./src/index";
console.log(await generateKey());
which you can run from this repository root with:
bun run ./genkey.ts
How does it work?
Under the hood the SubtleCrypto interface provides encryption and decryption functions which support multiple algorithms.
The encrypted string returns from our encrypt
function will be encoded as iv.ciphertext
where:
IV is the base64 encoded Initialization Vector (IV) aka nonce, randomly generated on each
encrypt
function invocation.Ciphertext is the base64 encoded AES-GCM encrypted value.
The returned string can safely be stored in a database or cookie; AES-GCM uses authenticated encryption, which will fail if either the ciphertext or IV cannot be verified, per Appendix B: Authentication Assurance
in NIST SP 800-38D.
License
MIT
Credit
Thank you to Nadrama.com for sponsoring this work! Nadrama enables you to run a Kubernetes PaaS in your cloud account, in minutes.
References
Development
We're using TypeScript, Bun, Bun test, Prettier, and ESLint.
To install dev dependencies:
bun install
To run prettier and eslint:
bun run pretty
bun run lint
To run tests:
bun test
To build:
bun run build
Security
Please reach out to Nadrama or @ryan0x44 if you have any security related questions or concerns.