Revamp doc (#823)

.cspell.jsonc

@@ -35,6 +35,7 @@
     ".gitignore",
     ".cspell.jsonc",
     "LICENSE",
-    "package.json"
+    "package.json",
+    "pnpm-lock.yaml"
   ]
 }

README.md

@@ -3,7 +3,7 @@
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/47784cde956642b1b9e8e33cb8551674)](https://app.codacy.com/app/ecies/js)
 [![License](https://img.shields.io/github/license/ecies/js.svg)](https://github.com/ecies/js)
 [![NPM Package](https://img.shields.io/npm/v/eciesjs.svg)](https://www.npmjs.com/package/eciesjs)
-![NPM Downloads](https://img.shields.io/npm/dm/eciesjs)
+[![NPM Downloads](https://img.shields.io/npm/dm/eciesjs)](https://npm-stat.link/eciesjs)
 [![Bundle size](https://badgen.net/bundlephobia/minzip/eciesjs)](https://bundlephobia.com/package/eciesjs@latest)
 [![CI](https://img.shields.io/github/actions/workflow/status/ecies/js/ci.yml)](https://github.com/ecies/js/actions)
 [![Codecov](https://img.shields.io/codecov/c/github/ecies/js.svg)](https://codecov.io/gh/ecies/js)
@@ -54,7 +54,7 @@ If you want a WASM version to run directly in modern browsers or on some blockch
 
 For bun/deno, see [`example/runtime`](./example/runtime). There are some limitations currently, mentioned in [`@ecies/ciphers`](https://github.com/ecies/js-ciphers#known-limitations):
 
-- `node:crypto`'s `xchacha20` does not work on bun (pure JS implementation is used instead)
+- `node:crypto`'s `chacha20-poly1305` does not work on bun (pure JS implementation is used instead)
 - `aes-256-gcm` only works with 12 bytes nonce on deno (deno is not handling package exports correctly)
 
 ### React Native
@@ -63,21 +63,21 @@ See the [React Native demo](https://github.com/ecies/js-rn-demo).
 
 ## API
 
-### `encrypt(receiverRawPK: string | Uint8Array, msg: Uint8Array): Buffer`
+### `encrypt(receiverRawPK: string | Uint8Array, data: Uint8Array): Buffer`
 
 Parameters:
 
 - **receiverRawPK** - Receiver's public key, hex string or Uint8Array
-- **msg** - Data to encrypt
+- **data** - Data to encrypt
 
 Returns: **Buffer**
 
-### `decrypt(receiverRawSK: string | Uint8Array, msg: Uint8Array): Buffer`
+### `decrypt(receiverRawSK: string | Uint8Array, data: Uint8Array): Buffer`
 
 Parameters:
 
 - **receiverRawSK** - Receiver's private key, hex string or Uint8Array
-- **msg** - Data to decrypt
+- **data** - Data to decrypt
 
 Returns: **Buffer**
 

example/runtime/main.js

@@ -1,8 +1,6 @@
 import { ECIES_CONFIG, PrivateKey, decrypt, encrypt } from "eciesjs";
 import { Buffer } from "node:buffer";
 
-globalThis.Buffer = Buffer;
-
 // because deno does not support indirect conditional exports
 // it falls to node:crypto's implementation
 // despite that @ecies/ciphers exports @noble/ciphers implementation to deno

package.json

@@ -62,10 +62,10 @@
     "@noble/hashes": "^1.5.0"
   },
   "devDependencies": {
-    "@types/node": "^22.10.1",
+    "@types/node": "^22.10.2",
     "@vitest/coverage-v8": "^2.1.8",
     "typescript": "^5.7.2",
-    "undici": "^7.1.0",
+    "undici": "^7.1.1",
     "vitest": "^2.1.8"
   },
   "packageManager": "[email protected]+sha512.c8180b3fbe4e4bca02c94234717896b5529740a6cbadf19fa78254270403ea2f27d4e1d46a08a0f56c89b63dc8ebfd3ee53326da720273794e6200fcf0d184ab"

src/index.ts

@@ -17,15 +17,19 @@ import {
 } from "./utils";
 
 /**
- * Encrypts a message.
+ * Encrypts data with a receiver's public key.
  * @description From version 0.5.0, `Uint8Array` will be returned instead of `Buffer`.
  * To keep the same behavior, use `Buffer.from(encrypt(...))`.
  *
  * @param receiverRawPK - Raw public key of the receiver, either as a hex string or a Uint8Array.
- * @param msg - Message to encrypt.
+ * @param data - Data to encrypt.
  * @returns Encrypted payload, format: `public key || encrypted`.
  */
-export function encrypt(receiverRawPK: string | Uint8Array, msg: Uint8Array): Buffer {
+export function encrypt(receiverRawPK: string | Uint8Array, data: Uint8Array): Buffer {
+  return Buffer.from(_encrypt(receiverRawPK, data));
+}
+
+function _encrypt(receiverRawPK: string | Uint8Array, data: Uint8Array): Uint8Array {
   const ephemeralSK = new PrivateKey();
 
   const receiverPK =
@@ -36,30 +40,34 @@ export function encrypt(receiverRawPK: string | Uint8Array, msg: Uint8Array): Bu
   const sharedKey = ephemeralSK.encapsulate(receiverPK, isHkdfKeyCompressed());
   const ephemeralPK = ephemeralSK.publicKey.toBytes(isEphemeralKeyCompressed());
 
-  const encrypted = symEncrypt(sharedKey, msg);
-  return Buffer.from(concatBytes(ephemeralPK, encrypted));
+  const encrypted = symEncrypt(sharedKey, data);
+  return concatBytes(ephemeralPK, encrypted);
 }
 
 /**
- * Decrypts a message.
+ * Decrypts data with a receiver's private key.
  * @description From version 0.5.0, `Uint8Array` will be returned instead of `Buffer`.
  * To keep the same behavior, use `Buffer.from(decrypt(...))`.
  *
  * @param receiverRawSK - Raw private key of the receiver, either as a hex string or a Uint8Array.
- * @param msg - Message to decrypt.
+ * @param data - Data to decrypt.
  * @returns Decrypted plain text.
  */
-export function decrypt(receiverRawSK: string | Uint8Array, msg: Uint8Array): Buffer {
+export function decrypt(receiverRawSK: string | Uint8Array, data: Uint8Array): Buffer {
+  return Buffer.from(_decrypt(receiverRawSK, data));
+}
+
+function _decrypt(receiverRawSK: string | Uint8Array, data: Uint8Array): Uint8Array {
   const receiverSK =
     receiverRawSK instanceof Uint8Array
       ? new PrivateKey(receiverRawSK)
       : PrivateKey.fromHex(receiverRawSK);
 
   const keySize = ephemeralKeySize();
-  const ephemeralPK = new PublicKey(msg.subarray(0, keySize));
-  const encrypted = msg.subarray(keySize);
+  const ephemeralPK = new PublicKey(data.subarray(0, keySize));
+  const encrypted = data.subarray(keySize);
   const sharedKey = ephemeralPK.decapsulate(receiverSK, isHkdfKeyCompressed());
-  return Buffer.from(symDecrypt(sharedKey, encrypted));
+  return symDecrypt(sharedKey, encrypted);
 }
 
 export { ECIES_CONFIG } from "./config";

tests/crypt/known.test.ts

@@ -7,21 +7,21 @@ const TEXT = "helloworld🌍";
 const encoder = new TextEncoder();
 
 describe("test known encrypt and decrypt", () => {
-  function testDecrypt(sk: string, msg: string, data: Uint8Array) {
-    expect(decrypt(sk, data).toString()).toBe(msg);
+  function testDecrypt(sk: string, data: string, expected: Uint8Array) {
+    expect(decrypt(sk, expected).toString()).toBe(data);
   }
 
-  function testEncrypt(sk: string, pk: string, msg: string) {
-    testDecrypt(sk, msg, encrypt(pk, encoder.encode(msg)));
+  function testEncrypt(sk: string, pk: string, data: string) {
+    testDecrypt(sk, data, encrypt(pk, encoder.encode(data)));
   }
 
-  function testKnown(sk: string, pk: string, msg: string, enc?: Uint8Array) {
+  function testKnown(sk: string, pk: string, data: string, enc?: Uint8Array) {
     if (enc === undefined) {
-      testEncrypt(sk, pk, msg);
+      testEncrypt(sk, pk, data);
     } else {
       // it should not be equal due to ephemeral key
-      expect(enc).not.toStrictEqual(encrypt(pk, encoder.encode(msg)));
-      testDecrypt(sk, msg, enc);
+      expect(enc).not.toStrictEqual(encrypt(pk, encoder.encode(data)));
+      testDecrypt(sk, data, enc);
     }
   }
 

tests/crypt/random.test.ts

@@ -12,10 +12,10 @@ import { EllipticCurve } from "../../src/config";
 
 const encoder = new TextEncoder();
 const TEXT = encoder.encode("hello world🌍");
-const decrypt = (sk: Buffer | string, msg: Uint8Array) =>
-  Uint8Array.from(_decrypt(sk, msg));
-const encrypt = (pk: Uint8Array | string, msg: Uint8Array) =>
-  Uint8Array.from(_encrypt(pk, msg));
+const decrypt = (sk: Buffer | string, data: Uint8Array) =>
+  Uint8Array.from(_decrypt(sk, data));
+const encrypt = (pk: Uint8Array | string, data: Uint8Array) =>
+  Uint8Array.from(_encrypt(pk, data));
 
 interface TestParameter {
   curve: EllipticCurve;