@nats-io/nkeys
v2.0.0-3
Published
A public-key signature system based on Ed25519 for the NATS ecosystem in javascript
Downloads
22,216
Readme
nkeys.js
A public-key signature system based on Ed25519 for the NATS ecosystem system for JavaScript.
[!IMPORTANT]
With the 2.0.0 release, the library changed module name from
nkeys.js
to@nats-io/nkeys
.
The nkeys.js library works in Deno, Node.js, Bun, and the browser!
Installation
The nkeys library is available on both npm and jsr.io
deno add jsr:@nats-io/nkeys
import { createUser, fromPublic, fromSeed } from "@nats-io/nkeys";
In Node:
npm install @nats-io/nkeys
const { createUser, fromSeed, fromPublic } = require("nkeys.js");
// or
import { createUser, fromPublic, fromSeed } from "nkeys.js";
On your browser use the jsr or npn registry that is compatible with your build workflow
import { createUser, fromPublic, fromSeed } from "https://host/path/nkeys.mjs";
Basic Usage
// 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.
Note that this library no longer shims atob
, btoa
, TextEncoder
, nor
TextDecoder
. These should be available in fairly old node builds going as far
back as Node 16. If you need to run on an older environment, use one of the
older versions on npm.
License
Unless otherwise noted, the NATS source files are distributed under the Apache Version 2.0 license found in the LICENSE file.