Registry / auth-security / libsodium-wrappers

libsodium-wrappers

library0.8.3jsnpmunverified

libsodium-wrappers provides a JavaScript/TypeScript binding for the highly regarded Sodium cryptographic library, compiled to WebAssembly with a pure JavaScript fallback. It is currently stable at version 0.8.3, wrapping libsodium 1.0.22. The package offers comprehensive, high-performance cryptographic operations for both web browsers (Chrome, Firefox, Edge, Safari, Mobile Safari) and server-side environments like Node.js and Bun. It comes in two variants: a standard version with commonly used functions and a 'sumo' version that includes the full, exhaustive libsodium API. Since version 0.8.1, the library automatically includes TypeScript definitions, simplifying development in typed environments. Users must `await sodium.ready` to ensure the underlying cryptographic engine is fully initialized before using any functions or constants. The library maintains a regular release cadence to incorporate upstream libsodium updates and address issues.

auth-security serialization

npm install libsodium-wrappers

github ↗package ↗

INSTALL

IMPORT

SIG · LIBSODIUM-WRAPPERS

libsodium-wrappers

auth-securityjavascriptv0.8.3

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.

sodium

✓ import sodium from 'libsodium-wrappers';

✗ import { sodium } from 'libsodium-wrappers';

The primary `sodium` object is a default export and must be awaited via `sodium.ready` before use. Cryptographic functions and constants are dynamically added to this object after `ready` resolves, so they cannot be destructured directly at the import statement.

ready

✓ import { ready, from_string, to_string } from 'libsodium-wrappers';

✗ import { ready } from 'libsodium-wrappers'; console.log(sodium.crypto_secretbox_keygen());

Helper functions like `from_string`, `to_string`, `from_hex`, and the `ready` promise itself can be imported as named exports from ESM modules. However, cryptographic functions (e.g., `crypto_secretbox_keygen`) are *not* named exports and must be accessed via the default `sodium` object after `await sodium.ready`.

sodium

✓ const sodium = require('libsodium-wrappers'); (async () => { await sodium.ready; /* use sodium */ })();

✗ const sodium = require('libsodium-wrappers'); const key = sodium.crypto_secretbox_keygen();

For CommonJS environments, `require` provides the `sodium` object. Similar to ESM, `sodium.ready` is a promise that *must* be awaited before any cryptographic operations are called. Attempting to use functions before `ready` resolves will result in `TypeError`s.

This example demonstrates end-to-end secret stream encryption and decryption using libsodium-wrappers, showcasing key generation, message pushing with tags, and message pulling.

import sodium from 'libsodium-wrappers'; async function encryptDecryptStream() { await sodium.ready; // Generate a key for secret stream encryption const key = sodium.crypto_secretstream_xchacha20poly1305_keygen(); // Initialize a push state and get the header const { state: state_out, header } = sodium.crypto_secretstream_xchacha20poly1305_init_push(key); // Push messages with different tags const message1 = sodium.from_string('This is the first secret message.'); const c1 = sodium.crypto_secretstream_xchacha20poly1305_push( state_out, message1, null, sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE ); const message2 = sodium.from_string('And this is the final message.'); const c2 = sodium.crypto_secretstream_xchacha20poly1305_push( state_out, message2, null, sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL ); console.log('Encrypted message 1 (hex):', sodium.to_hex(c1)); console.log('Encrypted message 2 (hex):', sodium.to_hex(c2)); // Initialize a pull state with the header and key const state_in = sodium.crypto_secretstream_xchacha20poly1305_init_pull(header, key); // Pull and decrypt the first message const r1 = sodium.crypto_secretstream_xchacha20poly1305_pull(state_in, c1); const { message: m1_bytes, tag: tag1 } = r1; const m1 = sodium.to_string(m1_bytes); console.log('Decrypted message 1:', m1, '(Tag:', tag1, ')'); // Pull and decrypt the second (final) message const r2 = sodium.crypto_secretstream_xchacha20poly1305_pull(state_in, c2); const { message: m2_bytes, tag: tag2 } = r2; const m2 = sodium.to_string(m2_bytes); console.log('Decrypted message 2:', m2, '(Tag:', tag2, ')'); // Ensure the tags are correct if (tag1 === sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE && tag2 === sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL) { console.log('Stream messages successfully encrypted and decrypted with correct tags.'); } else { console.error('Tag mismatch!'); } } encryptDecryptStream();

Debug

Known issues

breakingAll cryptographic functions and constants are only available after the `sodium.ready` promise has resolved. Attempting to call them before initialization will result in a `TypeError`.

fix

Always `await sodium.ready;` before using any cryptographic functions or constants from the default `sodium` export.

affects: >=0.7.0

gotchaCryptographic functions (e.g., `crypto_secretbox_easy`) and constants (e.g., `crypto_secretbox_KEYBYTES`) are not available as named exports in ESM modules. They must be accessed via the default `sodium` object after it has initialized.

fix

Always use `import sodium from 'libsodium-wrappers'; await sodium.ready;` and then access functions as `sodium.crypto_...`. Only helper utilities like `from_string`, `to_hex`, and `ready` itself can be named imports.

affects: >=0.7.16

gotchaOlder versions of Mobile Safari on iOS (< 8.0) and Safari (< 6) are noted to produce incorrect cryptographic results. Developers targeting these environments should exercise extreme caution or use alternative libraries.

fix

Ensure target environments meet the minimum compatibility requirements (Mobile Safari >= 8.0, Safari >= 6, Chrome >= 16, Firefox >= 21, Edge >= 0.11, NodeJS, Bun, Opera >= 15).

affects: <0.8.0

gotchaThe `libsodium-wrappers` package (standard) includes commonly used high-level functions, while `libsodium-wrappers-sumo` provides the full, often low-level and undocumented, libsodium API, including functions like `crypto_pwhash_*`. Using the `sumo` version increases bundle size and exposes potentially misuse-prone functions.

fix

For most projects, `libsodium-wrappers` is recommended. Only use `libsodium-wrappers-sumo` if you explicitly require functions not present in the standard version, and understand the implications of using advanced/low-level primitives.

affects: >=0.7.0

breakingESM (ECMAScript Module) support was added in version 0.7.16. Older versions may not correctly resolve `import` statements or use `.mjs` extensions, leading to module resolution errors in modern JavaScript environments.

fix

Upgrade to `libsodium-wrappers` version 0.7.16 or newer for full ESM compatibility. Ensure your build system is configured to handle `.mjs` extensions if direct file paths are being used.

affects: <0.7.16

Errors

Common errors & fixes

TypeError: sodium.crypto_secretstream_xchacha20poly1305_keygen is not a function

Attempting to use a cryptographic function before the `sodium.ready` promise has resolved.

fix

Ensure `await sodium.ready;` is executed before any calls to `sodium`'s cryptographic methods.

ERR_MODULE_NOT_FOUND: Cannot find package 'libsodium-wrappers'

Incorrect import path, package not installed, or module resolution issues in the build system (e.g., webpack, Turbopack, or Jest).

fix

Verify the package is installed (`npm install libsodium-wrappers`). Check import paths, especially when mixing CommonJS and ESM. For bundler issues, review configuration (e.g., Next.js with Turbopack might need specific handling for WASM modules).

TypeError: Cannot read properties of undefined (reading 'sodium')

This error can occur in testing environments (like Jest) where the global `window` object or module loading context is not fully emulated as expected by libsodium-wrappers' internal initialization logic.

fix

When testing, ensure Jest (or similar) is correctly configured for ESM and/or browser-like environments. You might need to mock the library or configure Jest's `moduleNameMapper` or `transformIgnorePatterns` to handle it correctly. Some users have found solutions by ensuring proper WebAssembly loading in their test runner.

Upgrade

Version history

0.8.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jedisct1/libsodium.js ↗

packagehttps://www.npmjs.com/package/libsodium-wrappers ↗