nkeys.js

What is nkeys.js?

The nkeys.js package is a JavaScript library for handling NATS keys. It provides functionalities for creating, managing, and verifying NATS keys, which are used for secure communication in NATS (a high-performance messaging system).

What are nkeys.js's main functionalities?

Generate a new NATS key pair

This feature allows you to generate a new NATS key pair, which includes a public key and a private key. The public key can be shared, while the private key should be kept secure.

const nkeys = require('nkeys.js');
const kp = nkeys.createAccount();
console.log('Public Key:', kp.getPublicKey());
console.log('Private Key:', kp.getPrivateKey());

Sign a message

This feature allows you to sign a message using the private key of a NATS key pair. The signature can be used to verify the authenticity of the message.

const nkeys = require('nkeys.js');
const kp = nkeys.createAccount();
const message = Buffer.from('Hello, NATS!');
const signature = kp.sign(message);
console.log('Signature:', signature.toString('hex'));

Verify a message signature

This feature allows you to verify the signature of a message using the public key of a NATS key pair. It ensures that the message was signed by the corresponding private key.

const nkeys = require('nkeys.js');
const kp = nkeys.createAccount();
const message = Buffer.from('Hello, NATS!');
const signature = kp.sign(message);
const publicKey = kp.getPublicKey();
const isValid = nkeys.fromPublic(publicKey).verify(message, signature);
console.log('Is the signature valid?', isValid);

Other packages similar to nkeys.js

tweetnacl

TweetNaCl is a cryptographic library that provides similar functionalities for key generation, signing, and verification. It is a port of the Networking and Cryptography library (NaCl) to JavaScript. Compared to nkeys.js, TweetNaCl is more general-purpose and not specifically tailored for NATS.

node-forge

Node-forge is a comprehensive cryptographic library for Node.js that includes support for key generation, signing, and verification, among other cryptographic operations. It is more feature-rich and versatile compared to nkeys.js, which is specifically designed for NATS key management.

crypto

The built-in 'crypto' module in Node.js provides cryptographic functionalities, including key generation, signing, and verification. While it is not as specialized as nkeys.js for NATS, it is a powerful and widely-used library for general cryptographic operations in Node.js applications.

README

nkeys.js

A public-key signature system based on Ed25519 for the NATS ecosystem system for JavaScript.

The nkeys.js library works in Deno, Node.js, and the browser!

Installation

For your Deno projects:

import { createUser, fromPublic, fromSeed } from "https://deno.land/x/nkeys.js/modules/esm/mod.ts";

On node, and browsers you can get a build from npm:

npm install nkeys.js

In your node projects:

  const {createUser, fromSeed, fromPublic} = require("nkeys.js");

On your browser projects, make available the node/nkeys.js/nkeys.mjs, and then

import {
  createUser,
  fromPublic,
  fromSeed,
} from "https://host/path/nkeys.mjs";

Basic Usage

The documentation is here

// create an user nkey KeyPair (can also create accounts, operators, etc).
const user = createUser();

// A seed is the public and private keys together.
const seed: Uint8Array = user.getSeed();

// Seeds are encoded into Uint8Array, and start with
// the letter 'S'. Seeds need to be kept safe and never shared
console.log(`seeds start with s: ${seed[0] === "S".charCodeAt(0)}`);

// A seed's second letter encodes it's type:
// `U` for user,
// `A` for account,
// `O` for operators
console.log(`nkey is for a user? ${seed[1] === "U".charCodeAt(0)}`);

// To view a seed, simply decode it:
console.log(new TextDecoder().decode(seed));

// you can recreate the keypair with its seed:
const priv = fromSeed(seed);

// Using the KeyPair, you can cryptographically sign content:
const data = new TextEncoder().encode("Hello World!");
const sig = priv.sign(data);

// and verify a signature:
const valid = user.verify(data, sig);
if (!valid) {
  console.error("couldn't validate the data/signature against my key");
} else {
  console.error("data was verified by my key");
}

// others can validate using your public key:
const publicKey = user.getPublicKey();
const pub = fromPublic(publicKey);
if (!pub.verify(data, sig)) {
  console.error(`couldn't validate the data/signature with ${publicKey}`);
} else {
  console.info(`data was verified by ${publicKey}`);
}

// when extracting with seeds or private keys
// you should clear them when done:
seed.fill(0);

// you should also clear the keypairs:
user.clear();
priv.clear();

Supported Node Versions

Our support policy for Nodejs versions follows Nodejs release support. We will support and build nkeys.js on even-numbered Nodejs versions that are current or in LTS.

License

Unless otherwise noted, the NATS source files are distributed under the Apache Version 2.0 license found in the LICENSE file.