@byokit/seal weekly downloads statistics

<h1 align="center">@byokit/seal</h1> <p align="center"> <a href="https://www.npmjs.com/package/@byokit/seal"><img alt="npm" src="https://img.shields.io/npm/v/@byokit/seal?style=flat&label=npm" /></a> <a href="https://github.com/umeranjum17/byokit/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/umeranjum17/byokit/ci.yml?style=flat&branch=main" /></a> <a href="LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-666?style=flat" /></a> <img alt="Node 22+ | browsers | React Native" src="https://img.shields.io/badge/platform-Node%2022%2B%20%7C%20browsers%20%7C%20React%20Native-666?style=flat" /> </p> <p align="center"><strong>Portable box, secretbox and Ed25519 signatures.</strong><br/> Box, secretbox and Ed25519 signatures for Node 22+, browsers/PWAs and React Native, with no native modules and no Node runtime imports. For apps that store or send small secrets and need byte-identical sealed boxes everywhere (see the API table and Tests for the compatibility vectors).</p>

Install

npm install @byokit/seal

· Latest release · All releases

Quickstart

npm install @byokit/seal

On React Native, install a crypto.getRandomValues polyfill before using it (for example react-native-get-random-values).

Seal and open a box, keep a JSON value in a secretbox, and sign and verify a message:

import {
  boxKeyPair, boxPublicKey, boxKeyPairFromSeed, sealBox, openBox, openBoxFromSeed,
  box, openAuthBox, sealNotice, openNotice,
  sealJson, openJson,
  signingKeyPairFromSeed, signDetached, verifyDetached,
} from '@byokit/seal';

const text = new TextEncoder().encode('hello from the phone');

// Box: anyone with the recipient's public key can seal; only the secret opens.
const recipientSeed = crypto.getRandomValues(new Uint8Array(32));
const recipient = boxKeyPairFromSeed(recipientSeed);
const bundle = sealBox(text, recipient.publicKey);
console.log('box bytes:', bundle.length);
console.log('opened:', new TextDecoder().decode(openBox(bundle, recipient.secretKey)!));
console.log('wrong key:', openBox(bundle, crypto.getRandomValues(new Uint8Array(32))));

// Secretbox JSON: one 32-byte key seals and opens data at rest.
const key = crypto.getRandomValues(new Uint8Array(32));
const stored = sealJson({ machines: ['desk'] }, key);
console.log('json:', openJson(stored, key));
stored[stored.length - 1] ^= 1;
console.log('tampered json:', openJson(stored, key));

// Ed25519 detached signatures.
const signing = signingKeyPairFromSeed(crypto.getRandomValues(new Uint8Array(32)));
const signature = signDetached(text, signing.secretKey);
console.log('signature bytes:', signature.length, 'secret key bytes:', signing.secretKey.length);
console.log('verified:', verifyDetached(text, signature, signing.publicKey));
console.log('other message:', verifyDetached(new TextEncoder().encode('changed'), signature, signing.publicKey));

Output of running the TypeScript file with node (Node 22.18+):

box bytes: 92
opened: hello from the phone
wrong key: null
json: { machines: [ 'desk' ] }
tampered json: null
signature bytes: 64 secret key bytes: 64
verified: true
other message: false

The 92-byte box is 32 (ephemeral public key) + 24 (nonce) + 16 (MAC) + 20 (the message).

API at a glance

Export	What it does
boxKeyPair(rng?)	Fresh raw 32-byte X25519 secret and its public key
boxPublicKey(secret)	X25519 public key from a raw 32-byte secret
boxKeyPairFromSeed(seed)	X25519 key pair from a 32-byte seed; same as libsodium crypto_box_seed_keypair
sealBox(bytes, recipientPublicKey, rng?)	Seals bytes to a public key with a fresh ephemeral key
openBox(bundle, recipientSecret)	Opens with a raw secret; Uint8Array or null
openBoxFromSeed(bundle, recipientSeed)	Opens with a seed, as in the original API
box(bytes, theirPublic, mySecret, rng?)	Known-sender authenticated box
openAuthBox(bundle, theirPublic, mySecret)	Opens a known-sender box; Uint8Array or null
sealNotice(value, boxPublicKey, rng?)	JSON in an anonymous box; { v: 1, sealed: string }
openNotice(data, secret)	Opens a notice with a raw secret; unknown or null
sealSecretBox(bytes, key, rng?)	Seals bytes with a 32-byte secret key
openSecretBox(bundle, key)	Opens a secretbox; Uint8Array or null
sealJson(value, key, rng?)	JSON.stringify, UTF-8, then secretbox
openJson(bundle, key)	Opens and parses; the value or null
signingKeyPairFromSeed(seed)	Ed25519 key pair from a 32-byte seed; tweetnacl-style 64-byte secret key
signDetached(bytes, secretKey)	64-byte detached signature
verifyDetached(bytes, signature, publicKey)	true or false
RandomBytes (type)	(length: number) => Uint8Array, the optional RNG the seal functions take

Every call in one place:

import {
  boxKeyPair, boxPublicKey, boxKeyPairFromSeed, sealBox, openBox, openBoxFromSeed,
  box, openAuthBox, sealNotice, openNotice,
  sealSecretBox, openSecretBox, sealJson, openJson,
  signingKeyPairFromSeed, signDetached, verifyDetached,
} from '@byokit/seal';…