js-nacl

library1.4.0jsnpmunverified

js-nacl is a JavaScript library offering a high-level API for libsodium, a well-regarded cryptographic library based on NaCl. It operates by wrapping an Emscripten-compiled version of libsodium, providing robust cryptographic primitives for both Node.js and browser environments. The current stable version, 1.4.0, was released in late 2018 and is based on libsodium 1.0.18-stable. Key differentiators include its adherence to the security-focused libsodium API, cross-platform compatibility, and the use of WebAssembly (WASM) for performance since version 1.3.0. It aims to simplify complex cryptographic tasks, offering functions for encryption, decryption, hashing, and digital signatures. Browser usage requires support for the `window.crypto.getRandomValues` API. The project's release cadence historically followed libsodium updates, with a focus on stability and API consistency, though it has not seen recent updates since 2018.

auth-security serialization

npm install js-nacl

github ↗package ↗

INSTALL

IMPORT

SIG · JS-NACL

js-nacl

auth-securityjavascriptv1.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

nacl_factory

✓ const nacl_factory = require('js-nacl/lib/nacl_factory.js');

✗ import { nacl_factory } from 'js-nacl';

For Node.js, the module path must point directly to `lib/nacl_factory.js`. It exposes a factory, not the `nacl` instance directly.

nacl

✓ nacl_factory.instantiate((nacl) => { /* use nacl API */ });

✗ const nacl = require('js-nacl');

The core `nacl` API object is provided asynchronously via a callback to `nacl_factory.instantiate()` in both Node.js and browser environments. It's not a direct export or global.

Browser Global

✓ <script src="node_modules/js-nacl/lib/nacl_factory.js"></script> <script> nacl_factory.instantiate((nacl) => { /* use nacl */ }); </script>

✗ import * as nacl from 'js-nacl';

In a browser, the library creates a global `nacl_factory` object. ESM imports are not supported for this package.

This quickstart demonstrates how to instantiate the js-nacl library in Node.js, generate cryptographic keys, nonces, and compute a SHA512 hash using the libsodium API.

const nacl_factory = require('js-nacl/lib/nacl_factory.js'); nacl_factory.instantiate((nacl) => { if (!nacl) { console.error('Failed to instantiate nacl library.'); return; } // Generate a random 32-byte key const key = nacl.random_bytes(nacl.crypto_box_SECRETKEYBYTES); console.log('Generated key (hex):', nacl.to_hex(key)); // Example: Generate a random nonce const nonce = nacl.random_bytes(nacl.crypto_box_NONCEBYTES); console.log('Generated nonce (hex):', nacl.to_hex(nonce)); // Example: Hash a message const message = nacl.from_string('Hello, js-nacl!'); const hash = nacl.crypto_hash(message); console.log('Hashed message (hex):', nacl.to_hex(hash)); });

Debug

Known issues

breakingThe `nacl_factory.instantiate` function's API changed to expect a callback as its first argument, which receives the `nacl` instance.

fix

Update calls from `nacl_factory.instantiate()` returning a value to `nacl_factory.instantiate((nacl_instance) => { /* use nacl_instance */ })`.

affects: >=1.1.0

breakingThe library API was changed from directly providing a `nacl` module to providing `nacl_factory` with an `instantiate` function that returns the `nacl` instance.

fix

Migrate code to use `nacl_factory.instantiate()` to obtain the functional `nacl` object instead of importing/accessing `nacl` directly.

affects: >=0.5.0

deprecatedFunctions `crypto_sign_keypair_from_seed` and `crypto_box_keypair_from_seed` were renamed to `crypto_sign_seed_keypair` and `crypto_box_seed_keypair` respectively to align with libsodium naming conventions.

fix

Update calls to the new names: `crypto_sign_seed_keypair` and `crypto_box_seed_keypair`. The old names are deprecated aliases and may be removed in future versions.

affects: >=1.2.0

gotchajs-nacl is known to have issues and potential data corruption when running on Safari version 5.1.x, especially with Javascript debug mode disabled.

fix

Upgrade to Safari 7.0 or a newer version. The library runs correctly on modern versions of Chrome, Firefox, and Safari.

affects: <7.0 (Safari)

gotchaBrowser usage of js-nacl requires support for the `window.crypto.getRandomValues` API for secure random number generation.

fix

Ensure that the target browser environment supports `window.crypto.getRandomValues`. Most modern browsers provide this API.

affects: All

gotchaAs of version 1.3.2, the Emscripten-compiled code no longer adds a listener to the `uncaughtException` event in Node.js.

fix

Applications using `js-nacl` in Node.js should implement their own `uncaughtException` handling if required, as the library no longer provides this default behavior.

affects: >=1.3.2

Errors

Common errors & fixes

TypeError: nacl is not defined

Attempting to use the `nacl` API object directly without first instantiating it through `nacl_factory.instantiate()`.

fix

Always call `nacl_factory.instantiate((naclInstance) => { /* use naclInstance */ })` to get the `nacl` object. The instantiation is asynchronous.

TypeError: nacl_factory.instantiate is not a function

The `nacl_factory` object was not correctly loaded or required. In Node.js, often caused by an incorrect `require` path or trying to use ES Modules `import`.

fix

For Node.js, use `const nacl_factory = require('js-nacl/lib/nacl_factory.js');`. For browsers, ensure `<script src="lib/nacl_factory.js">` is correctly placed before your script.

SecurityError: The operation is not supported.

This error typically occurs in a browser environment when `window.crypto.getRandomValues` is not available or accessible, which is required by `js-nacl`.

fix

Ensure the browser is modern enough to support `window.crypto.getRandomValues` and that the script is running in a secure context (e.g., HTTPS) if the browser enforces it.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tonyg/js-nacl ↗

packagehttps://www.npmjs.com/package/js-nacl ↗