libsodium-wrappers

libsodium-wrappers is the npm distribution of libsodium.js, which compiles the C libsodium cryptographic library to WebAssembly (with a pure-JS asm.js fallback) and layers on JavaScript-friendly wrappers around the raw C API. Instead of manually managing buffer lengths and memory addresses, callers pass and receive Uint8Array objects (or plain strings, auto-converted to UTF-8 bytes), and the library exposes the same function surface as libsodium itself: secret-key and public-key encryption, digital signatures, password hashing, key derivation, generic hashing, and streaming AEAD constructions.

The wrapper functions themselves are not hand-written. They are generated from a set of ~256 JSON symbol definitions (one per libsodium function) that declare each function’s inputs, outputs, and the low-level WASM call to make, which a build script (build-wrappers.ts) turns into the final wrap-template.js output. This same symbol data also drives the generated TypeScript definitions and API docs, keeping the JS surface, type signatures, and documentation in lock-step with the underlying C library as it evolves.

Because the package ships both a dist/modules (CommonJS) and dist/modules-esm (ESM) build, along with browser bundles in dist/browsers, it works the same way in Node.js, Bun, and directly in a <script> tag. A .ready promise gates access to the cryptographic functions, since the underlying WebAssembly module has to finish instantiating asynchronously before any crypto_* calls or constants become available.

What You Get

• The full high-level libsodium API surface (secretbox, box, sign, generichash, pwhash, kdf, kx, secretstream, AEAD ciphers) exposed as plain async-ready JS functions
• Automatic conversion between UTF-8 strings and Uint8Array buffers, so callers rarely need manual encoding
• Both CommonJS (dist/modules) and ESM (dist/modules-esm) builds, plus standalone browser bundles, from one package
• A WebAssembly implementation with an automatic asm.js fallback for environments where WASM fails to load
• A sumo variant (published separately as libsodium-wrappers-sumo) exposing the complete, less-common symbol set including crypto_pwhash_*
• Generated TypeScript type definitions kept in sync with the underlying symbol definitions used to build the wrappers

Common Use Cases

• End-to-end encrypting messages or files in a web or Node.js app using crypto_secretbox_easy/crypto_box_easy without needing a native crypto addon
• Signing and verifying data (e.g. license tokens, update manifests) with Ed25519 via crypto_sign_*
• Deriving and stretching keys from user passwords with crypto_pwhash for local encryption or key-wrapping
• Building streaming encrypted transports with crypto_secretstream_xchacha20poly1305_* for chunked message encryption with a single header
• Running the same cryptographic code path in the browser, Node.js, and Bun by sharing one wrapper import across platforms

Under The Hood

Architecture The project separates a thin runtime shim from a much larger code-generation layer. At runtime, wrap-template.js wraps an already-instantiated Emscripten WebAssembly module (libsodium), converts JS-friendly arguments into WASM heap writes, calls into the compiled C functions, and converts the results back into Uint8Array outputs. A .ready promise gates function availability until the WASM module (or its asm.js fallback, triggered automatically if a self-test using crypto_secretbox_easy fails) has finished loading. Every one of the ~256 exposed functions is described declaratively in wrapper/symbols/*.json (name, typed inputs/outputs, buffer lengths as libsodium C-call expressions, the WASM call itself, and return-value assertions), and wrapper/build-wrappers.ts reads these definitions plus a library of small JS “macro” snippets (wrapper/macros/) to generate the actual wrapper source injected into wrap-template.js/wrap-esm-template.js at build time. This keeps the hand-maintained surface small (build scripts and templates) while the large, error-prone buffer-marshaling code is generated rather than written by hand, and TypeScript defs and API docs are generated from the same symbol data so they cannot drift from the runtime implementation.

Tech Stack The published libsodium-wrappers package is a thin wrapper around the libsodium npm package (its only runtime dependency, pinned to ^0.8.0), which contains the actual Emscripten-compiled WebAssembly/asm.js binary produced from the upstream C libsodium library (included as a git submodule). Building from source uses Bun as the JS runtime/test runner, Make to orchestrate the multi-step build (compile via Emscripten/binaryen, generate wrappers, generate docs, generate TypeScript defs, minify with Terser), and Biome for linting/formatting (tabs, double quotes, import-organizing) in place of ESLint/Prettier. There is no bundler involved in the published artifact itself — dist/ ships pre-built CJS, ESM, and browser bundles directly.

Code Quality The repository has an extensive test/ directory (nearly 5,000 lines across ~28 files) using Bun’s built-in test runner, with one file per primitive family (secretbox.test.ts, sign.test.ts, pwhash.test.ts, secretstream.test.ts, kx.test.ts, etc.) plus dedicated files for cross-cutting concerns like ESM interop, symbol enumeration, TypeScript type shapes, and state-address handling. Tests exercise both success paths and expected-failure/edge-case behavior (e.g. asserting result.cipher/result.mac shapes and exact byte lengths on detached encryption). Return-value assertions in the generated wrappers (assert_retval in each symbol JSON) surface native libsodium failures as thrown JS errors rather than silently returning invalid data. Biome enforces consistent formatting and import order, and the wrapper/build scripts are themselves TypeScript, giving the code-generation layer type coverage even though the generated runtime output is plain JS.

What Makes It Unique Rather than hand-writing ~256 wrapper functions around a C API, the project generates them from declarative JSON symbol definitions that describe each function’s buffer semantics (fixed-length vs. unsized, computed output lengths, state-address handling for streaming APIs) — the same generation pass produces the runtime wrapper, the TypeScript definitions, and the API documentation from one source of truth, so the JS-facing API can never drift from what the underlying WASM module actually exposes. It also gets the full breadth of libsodium (AEAD ciphers, key exchange, secret streaming, password hashing, all in one library) into any JS runtime, browser included, via a WASM build with an automatic asm.js compatibility fallback, rather than relying on native Node.js addons that don’t work in the browser.