@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.

| | aes | chacha |
| ------------ | ---------------- | ---------------- |
| Node | node:crypto ⚡ | node:crypto ⚡ |
| Bun | node:crypto ⚡ | @noble/ciphers |
| Deno | node:crypto ⚡ | @noble/ciphers |
| Browser | @noble/ciphers | @noble/ciphers |
| React Native | @noble/ciphers | @noble/ciphers |

> [!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

``js
// 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.
- Currently (Nov 2025), node:crypto's chacha20-poly1305 is neither supported on deno nor bun, @noble/ciphers's implementation is used on both platforms instead.
- Some old versions of deno did not support indirect conditional exports. If you used this library to build another library, client code of your library might have fell back to the node:crypto implementation and would not work properly, specifically aes-256-gcm (16 bytes nonce) 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).