{"id":14923,"library":"sodium-javascript","title":"Sodium JavaScript Cryptography Library","description":"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.","status":"abandoned","version":"0.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/sodium-friends/sodium-javascript","tags":["javascript"],"install":[{"cmd":"npm install sodium-javascript","lang":"bash","label":"npm"},{"cmd":"yarn add sodium-javascript","lang":"bash","label":"yarn"},{"cmd":"pnpm add sodium-javascript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import sodium from 'sodium-javascript'","symbol":"sodium","correct":"const sodium = require('sodium-javascript')"},{"note":"Functions are exposed as properties on the main `sodium` object. There are no named exports for individual functions, as it is a CommonJS module.","wrong":"import { crypto_secretbox_easy } from 'sodium-javascript'","symbol":"crypto_secretbox_easy","correct":"const sodium = require('sodium-javascript'); sodium.crypto_secretbox_easy(...)"},{"note":"The library supports requiring individual submodules for smaller browser bundles. These are also CommonJS modules, so use `require()`.","wrong":"import { submoduleName } from 'sodium-javascript/submodule-name'","symbol":"submodule","correct":"const sub = require('sodium-javascript/submodule-name')"}],"quickstart":{"code":"const sodium = require('sodium-javascript')\n\nconst key = Buffer.alloc(sodium.crypto_secretbox_KEYBYTES)\nconst nonce = Buffer.alloc(sodium.crypto_secretbox_NONCEBYTES)\n\nsodium.randombytes_buf(key)\nsodium.randombytes_buf(nonce)\n\nconst message = Buffer.from('Hello, World!')\nconst cipher = Buffer.alloc(message.length + sodium.crypto_secretbox_MACBYTES)\n\nsodium.crypto_secretbox_easy(cipher, message, nonce, key)\n\nconsole.log('Encrypted:', cipher.toString('hex'))\n\nconst plainText = Buffer.alloc(cipher.length - sodium.crypto_secretbox_MACBYTES)\n\nsodium.crypto_secretbox_open_easy(plainText, cipher, nonce, key)\n\nconsole.log('Plaintext:', plainText.toString())","lang":"javascript","description":"This quickstart demonstrates basic authenticated encryption and decryption using the `crypto_secretbox_easy` and `crypto_secretbox_open_easy` functions, including key and nonce generation."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Always check for function availability before relying on it. For full libsodium feature parity, consider `libsodium-wrappers` or `sodium-native`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Transition to actively maintained cryptographic libraries that receive regular security audits and updates.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: sodium.crypto_some_unimplemented_function is not a function"},{"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.","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.","error":"ReferenceError: Buffer is not defined"},{"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.","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.","error":"Error: bad secretbox message"},{"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.","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.","error":"Error: Module not found: Error: Can't resolve 'sodium-javascript' (or similar bundler/ESM import errors)"}],"ecosystem":"npm"}