libsodium 0.7.16 → 0.8.1

package/README.md

@@ -8,8 +8,9 @@ compiled to WebAssembly and pure JavaScript using
 automatically generated wrappers to make it easy to use in web
 applications.
 
-The complete library weighs 188 KB (minified, gzipped, includes pure JS +
-WebAssembly versions) and can run in a web browser as well as server-side.
+The standard version weighs about 290 KB and the sumo version about 375 KB
+(minified, gzipped, includes pure JS + WebAssembly versions). Both can run in
+a web browser as well as server-side.
 
 ### Compatibility
 
@@ -60,37 +61,56 @@ 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)
@@ -118,6 +138,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
@@ -188,7 +216,7 @@ Functions returning more than one output buffer are returning them as
 an object. For example, the `sodium.crypto_box_keypair()` function
 returns the following object:
 ```javascript
-{ keyType: 'curve25519', privateKey: (Uint8Array), publicKey: (Uint8Array) }
+{ publicKey: (Uint8Array), privateKey: (Uint8Array), keyType: 'x25519' }
 ```
 
 ### Standard vs Sumo version
@@ -223,6 +251,12 @@ Running `make` will install the dev dependencies, clone libsodium,
 build it, test it, build the wrapper, and create the modules and
 minified distribution files.
 
+### Benchmarks
+
+Run `make benchmark` to measure the performance of the cryptographic functions.
+You can also run specific benchmarks with `bun benchmark/index.ts --only <name>`
+(use `--list` to see available benchmarks).
+
 ## Related projects
 
 * [react-native-libsodium](https://github.com/serenity-kit/react-native-libsodium): React Native bindings to Libsodium matching the libsodium-wrappers package API