@ecies/ciphers

Node/Pure JavaScript symmetric ciphers adapter.

If native implementations are available on some platforms (e.g. node, deno, bun), it'll use node:crypto for efficiency.

Otherwise (e.g. browser, react native), it'll use @noble/ciphers for compatibility.

[!NOTE] You may need to polyfill crypto.getRandomValues for React Native.

There are some limitations, see Known limitations below.

This library is tree-shakeable, unused code will be excluded by bundlers.

Check the example folder for more usages.

Quick start

// example/quick-start.js
import { aes256gcm } from "@ecies/ciphers/aes";
import { randomBytes } from "@noble/ciphers/webcrypto";

const TEXT = "hello world🌍!";
const encoder = new TextEncoder();
const decoder = new TextDecoder();
const msg = encoder.encode(TEXT);

const key = randomBytes();
const nonce = randomBytes(16);
const cipher = aes256gcm(key, nonce);
console.log("decrypted:", decoder.decode(cipher.decrypt(cipher.encrypt(msg))));

The API follows @noble/ciphers's API for ease of use, you can check their examples as well.

Supported ciphers

• aes-256-gcm
  • Both 16 bytes and 12 bytes nonce are supported.
• aes-256-cbc
  • Only for legacy applications. You should use xchacha20-poly1305 or aes-256-gcm as possible.
  • Nonce is always 16 bytes.
• chacha20-poly1305
  • Nonce is always 12 bytes.
• xchacha20-poly1305
  • Nonce is always 24 bytes.

If key is fixed and nonce is less than 16 bytes, avoid randomly generated nonce.

Known limitations

• xchacha20-poly1305 is implemented with pure JS hchacha20 function and node:crypto's chacha20-poly1305 on node/deno.
• Currently (Apr 2026), node:crypto's chacha20-poly1305 is not supported on bun, @noble/ciphers's implementation is used instead. From deno 2.7.10, node:crypto's chacha20-poly1305 is supported. Please upgrade deno to use native implementation for better performance.
• Some old versions of deno did not support indirect conditional exports. For example, if a library uses @ecies/ciphers, client code of that library might fall back to the node:crypto implementation and would not work properly, specifically aes-256-gcm and chacha20-poly1305. If you found such a problem, upgrade deno and run with --conditions deno (>=2.4.0) or --unstable-node-conditions deno(>=2.3.6,<2.4.0).