Sodium JavaScript Cryptography Library

Common errors

• TypeError: sodium.crypto_some_unimplemented_function is not a function

  cause 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

  cause `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

  cause 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)

  cause `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.

Warnings

• breaking The 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.
• gotcha Not 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`.
• breaking Being 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.
• gotcha The 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.
• gotcha As 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.

Install

• npm install sodium-javascript npm
• yarn add sodium-javascript yarn
• pnpm add sodium-javascript pnpm

Imports

• sodium
  wrong:

  import sodium from 'sodium-javascript'

  correct:

  const sodium = require('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
  wrong:

  import { crypto_secretbox_easy } from 'sodium-javascript'

  correct:

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

  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
  wrong:

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

  correct:

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

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

Quickstart

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())