Encryption

A thin convenience layer over crypto-js. One consistent encrypt(value, key) / decrypt(cipher, key) pair so callers don’t each re-invent the JSON wrapping, UTF-8 decoding, and “what does a wrong key look like” handling. Plus fast hex hashes (md5/sha1/sha256/sha512) for content fingerprinting.

Read this before reaching for it. Symmetric obfuscation + content fingerprinting only. Not for passwords, session tokens, PII at rest, or anything regulated. See Security boundaries below.

Highlighted features

Symmetric encrypt/decrypt

One encrypt(value, key) / decrypt(cipher, key) pair. JSON wrapping + UTF-8 + base64 cipher handled for you. AES by default; pluggable driver.

Four hex hashes

md5, sha1, sha256, sha512 — stable lowercase hex digests. Great for cache keys, content fingerprints, ETags.

Module-level config

setEncryptionConfigurations({ key, driver }) once at boot — never thread key through every call site again.

Browser + Node

Same API in both — crypto-js is the only transitive dep, no separate install needed. Pairs with @mongez/cache’s encrypted drivers.

Install

npm install @mongez/encryption

yarn add @mongez/encryption

pnpm add @mongez/encryption

crypto-js ships as a transitive dep — no separate install needed.

Quick peek

import { encrypt, decrypt, sha256 } from "@mongez/encryption";

const cipher = encrypt({ userId: 42 }, "my-key");      // AES by default
const value  = decrypt(cipher, "my-key");              // { userId: 42 }
const tag    = sha256(JSON.stringify({ q: "phones" })); // stable cache key

Symmetric encrypt/decrypt of any JSON-encodable value, plus stable hex digests for cache keys or content fingerprints.

Security boundaries — read this before reaching for the helpers

Pick the right tool for the threat. The table below is the package’s actual capability surface, not a marketing claim.

Concern	This package
Authenticated encryption (AEAD / tamper detection)	No. `crypto-js` `AES.encrypt(text, passphrase)` is AES-CBC + OpenSSL-style MD5 KDF + random salt. Ciphertext can be tampered with undetectably.
Modern key derivation	No. OpenSSL-style KDF is one round of MD5.
Salts / IVs	crypto-js picks a fresh salt per call → cipher is non-deterministic. No IV exposed to caller.
Constant-time digest comparison	No. Outputs are hex strings; `===` is not timing-safe.
`md5` / `sha1` collision resistance	Broken. Suitable for fingerprinting / ETags only.
FIPS / regulated compliance	No. Pure-JS, not validated.

Reach for it when: opaquing query-string params, masking values in logs, signing-free local-storage payloads, non-sensitive round-trips through string form. Threat model: “casual reader,” not “motivated attacker.”

Do NOT reach for it when: passwords, session tokens, PII at rest, payment data, secrets in transit, anything under a compliance regime, anywhere you need integrity. Use Node crypto AES-GCM, libsodium, or a managed KMS.

Mental model

Concept	Type	Mental model
`encrypt(value, ...)`	`(any, string?, driver?) => string`	JSON-stringify the value in `{ data: value }`, hand to `driver.encrypt`, return base64 cipher.
`decrypt(cipher, ...)`	`(string, string?, driver?) => any \| null`	Driver-decrypt, UTF-8-decode, JSON-parse, return `.data`. Returns `null` on any failure.
`driver`	a `crypto-js` cipher module	Anything with `.encrypt(text, key)` / `.decrypt(cipher, key)`. Default `AES`.
Hash function	`(string) => string`	Stateless, no config. Returns lowercase hex.
Module config	`{ key?, driver? }`	Module-level globals via `setEncryptionConfigurations`.

Where to go next

Configuration — setEncryptionConfigurations, swapping driver/key
Encrypt / decrypt — full signatures, failure modes, driver swapping
Hashes — md5 / sha1 / sha256 / sha512
Recipes — cache-key fingerprinting, query-string opaqueness