libsodium 0.7.15 → 0.8.0

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2015-2023
+Copyright (c) 2015-2026
 Ahmad Ben Mrad <batikhsouri at gmail dot org>
 Frank Denis <j at pureftpd dot org>
 Ryan Lester <ryan at cyph dot com>

package/README.md

@@ -4,11 +4,11 @@
 
 The [sodium](https://github.com/jedisct1/libsodium) crypto library
 compiled to WebAssembly and pure JavaScript using
-[Emscripten](https://github.com/kripken/emscripten), with
+[Emscripten](https://github.com/emscripten-core/emscripten), with
 automatically generated wrappers to make it easy to use in web
 applications.
 
-The complete library weighs 188 KB (minified, gzipped, includes pure JS +
+The complete library weighs about 310 KB (minified, gzipped, includes pure JS +
 WebAssembly versions) and can run in a web browser as well as server-side.
 
 ### Compatibility
@@ -43,11 +43,15 @@ It contains code for commonly used functions.
 is a superset of the previous script, that contains all functions,
 including rarely used ones and undocumented ones.
 - [modules](https://github.com/jedisct1/libsodium.js/tree/master/dist/modules)
-includes commonly used functions, and is designed to be loaded as a module.
+includes commonly used functions, and is designed to be loaded as a CommonJS module.
 `libsodium-wrappers` is the module your application should load, which
 will in turn automatically load `libsodium` as a dependency.
 - [modules-sumo](https://github.com/jedisct1/libsodium.js/tree/master/dist/modules-sumo)
 contains sumo variants of the previous modules.
+- [modules-esm](https://github.com/jedisct1/libsodium.js/tree/master/dist/modules-esm)
+contains ESM (ES modules) versions with `.mjs` extensions.
+- [modules-sumo-esm](https://github.com/jedisct1/libsodium.js/tree/master/dist/modules-sumo-esm)
+contains sumo ESM variants.
 
 The modules are also available on npm:
 - [libsodium-wrappers](https://www.npmjs.com/package/libsodium-wrappers)
@@ -56,44 +60,63 @@ The modules are also available on npm:
 ### Usage (as a module)
 
 Load the `libsodium-wrappers` module. The returned object contains a `.ready`
-property: a promise that must be resolve before the sodium functions
+property: a promise that must be resolved before the sodium functions
 can be used.
 
 Example:
 
 ```js
-import _sodium from 'libsodium-wrappers';
-await (async() => {
-  await _sodium.ready;
-  const sodium = _sodium;
-
-  let key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
-
-  let res = sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
-  let [state_out, header] = [res.state, res.header];
-  let c1 = sodium.crypto_secretstream_xchacha20poly1305_push(state_out,
-    sodium.from_string('message 1'), null,
-    sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE);
-  let c2 = sodium.crypto_secretstream_xchacha20poly1305_push(state_out,
-    sodium.from_string('message 2'), null,
-    sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL);
-
-  let state_in = sodium.crypto_secretstream_xchacha20poly1305_init_pull(header, key);
-  let r1 = sodium.crypto_secretstream_xchacha20poly1305_pull(state_in, c1);
-  let [m1, tag1] = [sodium.to_string(r1.message), r1.tag];
-  let r2 = sodium.crypto_secretstream_xchacha20poly1305_pull(state_in, c2);
-  let [m2, tag2] = [sodium.to_string(r2.message), r2.tag];
-
-  console.log(m1);
-  console.log(m2);
-})();
+import sodium from 'libsodium-wrappers';
+
+await sodium.ready;
+
+let key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+
+let res = sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
+let [state_out, header] = [res.state, res.header];
+let c1 = sodium.crypto_secretstream_xchacha20poly1305_push(state_out,
+  sodium.from_string('message 1'), null,
+  sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE);
+let c2 = sodium.crypto_secretstream_xchacha20poly1305_push(state_out,
+  sodium.from_string('message 2'), null,
+  sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL);
+
+let state_in = sodium.crypto_secretstream_xchacha20poly1305_init_pull(header, key);
+let r1 = sodium.crypto_secretstream_xchacha20poly1305_pull(state_in, c1);
+let [m1, tag1] = [sodium.to_string(r1.message), r1.tag];
+let r2 = sodium.crypto_secretstream_xchacha20poly1305_pull(state_in, c2);
+let [m2, tag2] = [sodium.to_string(r2.message), r2.tag];
+
+console.log(m1);
+console.log(m2);
+```
+
+**Named exports:** The ESM modules also provide named exports for helper functions:
+
+```js
+import { ready, from_hex, to_hex, from_string, to_string } from 'libsodium-wrappers';
+
+await ready;
+const bytes = from_hex('deadbeef');
+console.log(to_hex(bytes));
+```
+
+**Note:** Cryptographic functions (like `crypto_secretbox_easy`) and constants (like `crypto_secretbox_KEYBYTES`) are dynamically added to the module at runtime after `ready` resolves. They cannot be imported as named exports and must be accessed via the default export:
+
+```js
+import sodium from 'libsodium-wrappers';
+
+await sodium.ready;
+// Now crypto functions and constants are available on the sodium object
+const key = sodium.crypto_secretbox_keygen();
+const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
 ```
 
 ### Usage (in a web browser, via a callback)
 
 The `sodium.js` file includes both the core libsodium functions, as
 well as the higher-level JavaScript wrappers. It can be loaded
-asynchronusly.
+asynchronously.
 
 A `sodium` object should be defined in the global namespace, with the
 following property:
@@ -114,6 +137,14 @@ Example:
 <script src="sodium.js" async></script>
 ```
 
+**Important:** If you inline the library directly into your HTML (rather than loading it from a separate file), make sure your page declares UTF-8 encoding:
+
+```html
+<meta charset="utf-8">
+```
+
+Without this, browsers may corrupt the embedded WebAssembly binary data during HTML parsing, leading to errors like "failed to match magic number" or "HEAPU8 is undefined". Also ensure your server sends the `charset=utf-8` header.
+
 ## Additional helpers
 
 * `from_base64()`, `to_base64()` with an optional second parameter
@@ -159,7 +190,11 @@ let key = sodium.from_hex('724b092810ec86d7e35c9d067702b31ef90bc43a7b59862674991
 
 function encrypt_and_prepend_nonce(message) {
     let nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
-    return nonce.concat(sodium.crypto_secretbox_easy(message, nonce, key));
+    let ciphertext = sodium.crypto_secretbox_easy(message, nonce, key);
+    let result = new Uint8Array(nonce.length + ciphertext.length);
+    result.set(nonce);
+    result.set(ciphertext, nonce.length);
+    return result;
 }
 
 function decrypt_after_extracting_nonce(nonce_and_ciphertext) {
@@ -185,13 +220,13 @@ returns the following object:
 
 ### Standard vs Sumo version
 
-The standard version (in the `dist/browsers` and `dist/modules`
-directories) contains the high-level functions, and is the recommended
-one for most projects.
+The standard version (in the `dist/browsers`, `dist/modules`, and
+`dist/modules-esm` directories) contains the high-level functions, and
+is the recommended one for most projects.
 
 Alternatively, the "sumo" version, available in the
-`dist/browsers-sumo` and `dist/modules-sumo` directories contains all
-the symbols from the original library. This includes undocumented,
+`dist/browsers-sumo`, `dist/modules-sumo`, and `dist/modules-sumo-esm`
+directories contains all the symbols from the original library. This includes undocumented,
 untested, deprecated, low-level and easy to misuse functions.
 
 The `crypto_pwhash_*` function set is only included in the sumo version.