Registry / type-stubs / sodium-javascript

sodium-javascript

library0.8.0jsnpmunverified

sodium-javascript is a pure JavaScript implementation of the libsodium cryptographic library's API, leveraging `tweetnacl` as its foundation. It was developed to provide a browser-compatible alternative to `sodium-native`, which is a Node.js native addon binding to the C libsodium library. The package's current stable version is 0.8.0, but it explicitly states 'WIP - Work In Progress' in its README and was last published over four years ago (January 2022). This suggests the project is largely unmaintained or abandoned. Its key differentiator was offering a pure JavaScript fallback for environments where native bindings are not feasible (e.g., browsers). For modern cross-platform libsodium usage, alternatives like `libsodium-wrappers` (which utilizes WebAssembly for better performance and broader API coverage) are generally recommended.

type-stubs auth-security

npm install sodium-javascript

github ↗package ↗

INSTALL

IMPORT

SIG · SODIUM-JAVASCRIPT

sodium-javascript

type-stubsjavascriptv0.8.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.

sodium

✓ const sodium = require('sodium-javascript')

✗ import sodium from 'sodium-javascript'

The library is primarily CommonJS. While ES modules can technically import CommonJS modules via a default import, the library's unmaintained state means explicit ESM support or a `package.json` `exports` field is unlikely. Use `require()` for Node.js.

crypto_secretbox_easy

✓ const sodium = require('sodium-javascript'); sodium.crypto_secretbox_easy(...)

✗ import { crypto_secretbox_easy } from 'sodium-javascript'

Functions are exposed as properties on the main `sodium` object. There are no named exports for individual functions, as it is a CommonJS module.

submodule

✓ const sub = require('sodium-javascript/submodule-name')

✗ import { submoduleName } from 'sodium-javascript/submodule-name'

The library supports requiring individual submodules for smaller browser bundles. These are also CommonJS modules, so use `require()`.

This quickstart demonstrates basic authenticated encryption and decryption using the `crypto_secretbox_easy` and `crypto_secretbox_open_easy` functions, including key and nonce generation.

const sodium = require('sodium-javascript') const key = Buffer.alloc(sodium.crypto_secretbox_KEYBYTES) const nonce = Buffer.alloc(sodium.crypto_secretbox_NONCEBYTES) sodium.randombytes_buf(key) sodium.randombytes_buf(nonce) const message = Buffer.from('Hello, World!') const cipher = Buffer.alloc(message.length + sodium.crypto_secretbox_MACBYTES) sodium.crypto_secretbox_easy(cipher, message, nonce, key) console.log('Encrypted:', cipher.toString('hex')) const plainText = Buffer.alloc(cipher.length - sodium.crypto_secretbox_MACBYTES) sodium.crypto_secretbox_open_easy(plainText, cipher, nonce, key) console.log('Plaintext:', plainText.toString())

Debug

Known issues

breakingThe package is labeled 'WIP - Work In Progress' in its README and has not been updated in over four years (last published January 2022). It should be considered abandoned and unsuitable for new production applications requiring robust security or active maintenance.

fix

Migrate to actively maintained alternatives like `libsodium-wrappers` (for Node.js and browser with WebAssembly) or `sodium-native` (for Node.js with native bindings) for production use.

affects: >=0.8.0

gotchaNot all functions from the comprehensive libsodium API are implemented in `sodium-javascript`. The API documentation points to `sodium-native`, which is more feature-complete.

fix

Always check for function availability before relying on it. For full libsodium feature parity, consider `libsodium-wrappers` or `sodium-native`.

affects: >=0.1.0

breakingBeing a pure JavaScript cryptographic library that is unmaintained, `sodium-javascript` might not incorporate the latest security patches or best practices for cryptographic primitives. Using unmaintained crypto libraries poses significant security risks.

fix

Transition to actively maintained cryptographic libraries that receive regular security audits and updates.

affects: >=0.1.0

gotchaThe API style, mimicking the low-level C libsodium, often requires manual buffer allocation for output and precise buffer sizing, which is error-prone and can lead to memory issues or incorrect results if not handled carefully. This contrasts with higher-level wrappers that manage buffers automatically.

fix

Refer strictly to the `sodium-native` documentation for correct buffer sizes and usage patterns. Consider using `sodium-universal` for a more ergonomic API or `libsodium-wrappers` which often handles buffer management automatically.

affects: >=0.1.0

gotchaAs a pure JavaScript implementation, `sodium-javascript` is generally slower than native C bindings (`sodium-native`) or WebAssembly-compiled versions (`libsodium-wrappers`), especially for intensive cryptographic operations.

fix

For performance-critical applications in Node.js, `sodium-native` is the preferred choice. For cross-platform (browser/Node.js) applications needing better performance, `libsodium-wrappers` offers WebAssembly execution.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: sodium.crypto_some_unimplemented_function is not a function

The specific libsodium function you are trying to use is not implemented in `sodium-javascript`, or the installed version is too old to include it.

fix

Verify the function exists in the `sodium-javascript` API by checking its source or `sodium-native` documentation (which it aims to mimic). If not implemented, you must use an alternative library or find another way to achieve the cryptographic goal.

ReferenceError: Buffer is not defined

`Buffer` is a Node.js global. This error occurs when `sodium-javascript` is used directly in a browser environment without a `Buffer` polyfill or appropriate bundling.

fix

Ensure your browser environment has a `Buffer` polyfill (e.g., `buffer` npm package) if using a bundler like Webpack, or prefer `libsodium-wrappers` for browser-native execution.

Error: bad secretbox message

This error typically indicates that the ciphertext, nonce, or key used for decryption is incorrect, corrupted, or does not match the parameters used during encryption. It's a common cryptographic integrity check failure.

fix

Double-check that the `cipher`, `nonce`, and `key` buffers are exactly the same as those used for encryption. Ensure no data corruption occurred during storage or transmission. Also verify buffer lengths and types.

Error: Module not found: Error: Can't resolve 'sodium-javascript' (or similar bundler/ESM import errors)

`sodium-javascript` is a CommonJS module. Direct `import ... from 'sodium-javascript'` syntax in an ES Module context might not be resolved correctly by some bundlers or Node.js versions without explicit configuration or a `package.json` `exports` map.

fix

In Node.js ESM files, use `const sodium = require('sodium-javascript')` or dynamic import `const sodium = await import('sodium-javascript')`. In bundlers, ensure your configuration correctly handles CJS module imports into an ESM project.

Upgrade

Version history

0.8.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

35 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sodium-friends/sodium-javascript ↗

packagehttps://www.npmjs.com/package/sodium-javascript ↗