tweetnacl

library1.0.3jsnpmunverified

TweetNaCl.js is a JavaScript port of the TweetNaCl/NaCl cryptographic library, designed for modern browsers and Node.js. It provides a thin layer of idiomatic high-level API over a faithful translation of the original C implementation, prioritizing security and correctness. The library ships with two versions: `nacl.js` (a direct port) and `nacl-fast.js` (which includes faster, optimized functions and is used by default when installed via npm). Currently at version 1.0.3, it maintains a stable release cadence with updates typically addressing security fixes or minor improvements. A key differentiator is its public domain license and a comprehensive audit by Cure53 in 2017, which found no security problems, cementing its reputation as a robust and secure cryptographic tool. All API functions operate on `Uint8Array` for byte handling.

auth-security

npm install tweetnacl

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TWEETNACL

tweetnacl

auth-securityjavascriptv1.0.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.

nacl

✓ import nacl from 'tweetnacl';

✗ import { nacl } from 'tweetnacl';

The library exports the main 'nacl' object as a default export for ESM compatibility, aligning with its CommonJS `module.exports` structure.

nacl

✓ const nacl = require('tweetnacl');

CommonJS import; `require('tweetnacl')` directly returns the 'nacl' object (specifically `nacl-fast.js` by default).

BoxKeyPair

✓ import type { BoxKeyPair } from 'tweetnacl';

For TypeScript users, specific types like `BoxKeyPair` are available for explicit type annotations.

This quickstart demonstrates public-key authenticated encryption using `nacl.box`. It covers key pair generation, message encryption, and decryption, highlighting the use of `Uint8Array` for all data operations and the importance of a unique nonce.

import nacl from 'tweetnacl'; // Utility for converting strings to Uint8Array and vice-versa (not part of tweetnacl itself) const encoder = new TextEncoder(); const decoder = new TextDecoder(); function utf8ToUint8Array(str) { return encoder.encode(str); } function uint8ArrayToUtf8(arr) { return decoder.decode(arr); } // Generate a key pair for the sender and receiver const senderKeyPair = nacl.box.keyPair(); const receiverKeyPair = nacl.box.keyPair(); // A message to encrypt const message = 'Hello, secure world! This is a secret message.'; const messageUint8 = utf8ToUint8Array(message); // Generate a random nonce for the encryption const nonce = nacl.randomBytes(nacl.box.nonceLength); // Encrypt the message const encryptedMessage = nacl.box( messageUint8, nonce, receiverKeyPair.publicKey, senderKeyPair.secretKey ); console.log('Original message:', message); console.log('Encrypted message (Uint8Array):', encryptedMessage); // Decrypt the message const decryptedMessageUint8 = nacl.box.open( encryptedMessage, nonce, senderKeyPair.publicKey, receiverKeyPair.secretKey ); if (decryptedMessageUint8) { const decryptedMessage = uint8ArrayToUtf8(decryptedMessageUint8); console.log('Decrypted message:', decryptedMessage); } else { console.error('Decryption failed!'); }

Debug

Known issues

breakingIn versions 1.0.0 and later, functions like `nacl.secretbox.open`, `nacl.box.open`, and `nacl.box.after` now return `null` instead of `false` when decryption fails (e.g., due to incorrect key, nonce, or tampered input). While `if (!result)` checks generally remain compatible, direct comparison `if (result == false)` will behave differently.

fix

Ensure your code checks for `null` or uses a general falsy check (`!result`) for failed decryption operations instead of strict `=== false`.

affects: >=1.0.0

breakingVersion 1.0.3 includes an important security fix. A bug in the modulo reduction calculation for integers larger than 32 bits could lead to `nacl.sign` or `nacl.sign.detached` creating *incorrect signatures*. This issue specifically affected signature generation, not verification. Users of previous versions are strongly urged to upgrade.

fix

Upgrade immediately to `tweetnacl@1.0.3` or newer to ensure correct signature generation. Re-sign any critical data signed with affected versions.

affects: <1.0.3

breakingVersions 0.14.2 through 0.14.3 experienced a critical bug in the 'fast' version of Poly1305. This bug could occasionally produce incorrect results, potentially affecting the authenticity of `secretbox`, `secretbox.open`, `box`, and `box.open` functions. Although the chance of real-world impact was considered low, it was a significant vulnerability.

fix

Ensure you are using `tweetnacl@0.14.3` or any later version (including current 1.x releases). Version 0.14.3 fixed this issue by reverting to the original, slower Poly1305 implementation until a corrected fast version was available, and subsequent versions resolved it completely.

affects: 0.14.2

Errors

Common errors & fixes

Error: Argument 1 must be of type Uint8Array

TweetNaCl.js functions strictly expect `Uint8Array` instances for all byte operations. Passing strings, Arrays, or Node.js Buffers incorrectly will lead to type errors.

fix

Always convert input data to `Uint8Array` before passing it to TweetNaCl.js functions. For Node.js Buffers, use `Buffer.from(myBuffer)` for copying, or `Buffer.isBuffer(myVar) ? Uint8Array.from(myVar) : myVar` for robust handling. For strings, use `new TextEncoder().encode(myString)` or `tweetnacl-util-js`.

TypeError: nacl.box is not a function

This usually indicates that the `nacl` object was not imported correctly, or the import resulted in an undefined or partial object.

fix

Ensure you are using the correct import statement: `import nacl from 'tweetnacl';` for ESM, or `const nacl = require('tweetnacl');` for CommonJS. Verify that your environment correctly handles module resolution, especially in bundler configurations.

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

tweetnacl-util-jsoptionalRecommended for encoding/decoding strings to/from Uint8Array, as TweetNaCl.js functions exclusively operate on Uint8Array.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dchest/tweetnacl-js ↗

packagehttps://www.npmjs.com/package/tweetnacl ↗

homepagehttps://tweetnacl.js.org ↗