@nats-io/nkeys - npm Package Compare versions

Comparing version 2.0.0 to 2.0.1

lib/nkeys.d.ts

@@ -29,3 +29,6 @@ /**
 /**
- * @ignore
+ * Generates and returns a KeyPair object using the Curve prefix.
+ * Curve KeyPairs can seal/open (encrypt/decrypt) payloads.
+ *
+ * @return {KeyPair} The generated KeyPair object with Curve prefix.
  */
@@ -40,2 +43,9 @@ export declare function createCurve(): KeyPair;
 export declare function fromPublic(src: string): KeyPair;
+/**
+ * Creates a KeyPair from a Curve seed. Curve keys can encrypt and decrypt payloads.
+ *
+ * @param {Uint8Array} src - The seed representing the Curve key in encoded format.
+ * @return {KeyPair} The resulting KeyPair generated from the Curve seed.
+ * @throws {NKeysError} If the seed's prefix is not a Curve prefix or if the seed length is invalid.
+ */
 export declare function fromCurveSeed(src: Uint8Array): KeyPair;
@@ -70,6 +80,6 @@ /**
      * Returns the digital signature of signing the input with the
-     * the KeyPair's private key.
+     * the KeyPair's private key. Note that only non-curve keys can sign.
      * @param {Uint8Array} input
      * @returns Uint8Array
-     * @throws NKeysError
+     * @throws NKeysError if a curve key
      */
@@ -79,6 +89,8 @@ sign(input: Uint8Array): Uint8Array;
      * Returns true if the signature can be verified with the KeyPair
+     * Note that only non-curve keys can verify.
+     *
      * @param {Uint8Array} input
      * @param {Uint8Array} sig
      * @returns {boolean}
-     * @throws NKeysError
+     * @throws NKeysError if a curve key
      */
@@ -91,3 +103,22 @@ verify(input: Uint8Array, sig: Uint8Array): boolean;
     clear(): void;
+    /**
+     * Seals (encrypts) the provided input data with the recipient's public key
+     * and an optional nonce. Note that only curve keys can seal a payload.
+     *
+     * @param {Uint8Array} input - The data to be encrypted.
+     * @param {string} recipient - The recipient's identifier or public key.
+     * @param {Uint8Array} [nonce] - An optional nonce to use in the encryption process.
+     * @return {Uint8Array} The encrypted data.
+     * @throws {NKeysError} if not a curve key
+     */
     seal(input: Uint8Array, recipient: string, nonce?: Uint8Array): Uint8Array;
+    /**
+     * Opens (decrypts) and processes a given message from a specified sender.
+     * Note that only curve keys can open a payload.
+     *
+     * @param {Uint8Array} message - The message to be opened and processed.
+     * @param {string} sender - The sender of the message.
+     * @return {Uint8Array | null} Returns the processed message as a Uint8Array if successful, or null if the operation fails.
+     * @throws {NKeysError} if not a curve key
+     */
     open(message: Uint8Array, sender: string): Uint8Array | null;
@@ -94,0 +125,0 @@ }

lib/nkeys.js

@@ -81,3 +81,6 @@ "use strict";
 /**
- * @ignore
+ * Generates and returns a KeyPair object using the Curve prefix.
+ * Curve KeyPairs can seal/open (encrypt/decrypt) payloads.
+ *
+ * @return {KeyPair} The generated KeyPair object with Curve prefix.
  */
@@ -102,2 +105,9 @@ function createCurve() {
 }
+/**
+ * Creates a KeyPair from a Curve seed. Curve keys can encrypt and decrypt payloads.
+ *
+ * @param {Uint8Array} src - The seed representing the Curve key in encoded format.
+ * @return {KeyPair} The resulting KeyPair generated from the Curve seed.
+ * @throws {NKeysError} If the seed's prefix is not a Curve prefix or if the seed length is invalid.
+ */
 function fromCurveSeed(src) {
@@ -104,0 +114,0 @@ const sd = codec_1.Codec.decodeSeed(src);

lib/version.d.ts

@@ -1,1 +0,1 @@
-export declare const version = "2.0.0";
+export declare const version = "2.0.1";

lib/version.js

@@ -5,3 +5,3 @@ "use strict";
 // this file is autogenerated - do not edit
-exports.version = "2.0.0";
+exports.version = "2.0.1";
 //# sourceMappingURL=version.js.map

package.json

 {
   "name": "@nats-io/nkeys",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "A public-key signature system based on Ed25519 for the NATS ecosystem in javascript",
@@ -23,5 +23,5 @@ "main": "lib/mod.js",
     "prepare": "npm run clean && npm run stage",
-    "test-node": "node --test",
+    "test-node": "cd node_test; node --test",
     "test-deno": "deno test -A test",
-    "test": "npm run prepare && npm run check-package && npm run test-node && npm run test-deno",
+    "test": "npm run prepare && npm run check-package && npm run test-deno && npm run test-node",
     "doc": "rm -Rf docs && npm run stage && node_modules/.bin/typedoc --out docs/ && touch ./docs/.nojekyll",
@@ -50,6 +50,6 @@ "bump-qualifier": "npm version prerelease --no-commit-hooks --no-git-tag-version",
   "devDependencies": {
-    "@types/node": "^22.10.1",
-    "typedoc": "^0.27.3",
-    "typescript": "^5.7.2"
+    "@types/node": "^22.10.7",
+    "typedoc": "^0.27.6",
+    "typescript": "^5.7.3"
   }
 }

README.md

@@ -113,2 +113,64 @@ # nkeys.js
 
+## Curve Keys
+
+Curve keys seal/open (encrypt/decrypt) payloads only, but look like regular
+nkeys. The `getSeed()`, `getPrivate()`, `getPublic()`, `clear()` work have the
+same functionality as the normal nkeys. The APIs to `sign()`, `verify()` however
+will throw an error (regular nkeys will throw an error for `seal()` and
+`open()`)
+
+```javascript
+// let's create 3 different curve keys, as with other nkeys
+// private/seeds should be kept private, and public keys can be
+// shared.
+const a = createCurve();
+const b = createCurve();
+const c = createCurve();
+
+// encryption api works on bytes - so lets make a message
+const payload = new TextEncoder().encode("hello!");
+
+// let's encrypt the message so that "b" can read it
+const encrypted = a.seal(payload, b.getPublicKey());
+
+// "b" can then open the message, we need to know the sender
+let decrypted = b.open(encrypted, a.getPublicKey());
+if (decrypted === null) {
+  throw new Error("failed to decrypt");
+}
+console.log(new TextDecoder().decode(decrypted));
+
+// wrong recipient - will return `null`
+decrypted = c.open(encrypted, a.getPublicKey());
+if (decrypted !== null) {
+  throw new Error("this should have been null");
+}
+
+// wrong sender - will return `null`
+decrypted = b.open(encrypted, c.getPublicKey());
+if (decrypted !== null) {
+  throw new Error("shouldn't have decrypted");
+}
+
+// seal can take an user-specified nonce - the nonce will make
+// it so that 2 equal payloads encrypt to different values
+// when not specified seal uses a random nonce (a good thing).
+// for this example, we'll use the same nonce
+const nonce = new Uint8Array(24);
+
+// same payload, but with the specified nonce, different encrypted results
+// comparing the outputs you wouldn't be able to guess they are the
+// same exact unencrytped payload.
+const encrypted2 = a.seal(payload, b.getPublicKey(), nonce);
+console.log(encrypted, encrypted2);
+
+console.log("---------");
+
+// now re-encrypt with the same nonce, encrypted2 and encrypted3 are equal
+// which would provide a hint that the unencrypted payloads are
+// the same (not a good thing).
+const encrypted3 = a.seal(payload, b.getPublicKey(), nonce);
+console.log(encrypted2, encrypted3);
+```
+
 ## Supported Node Versions
@@ -115,0 +177,0 @@

No alert changes

Improved metrics

Total package byte prevSize

90414

increased by5.1%

Lines of code

1401

increased by3.01%

Number of lines in readme file

190

increased by48.44%

No dependency changes