@byokit/seal

Portable box, secretbox and Ed25519 signatures.
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).

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

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';

const recipient = boxKeyPairFromSeed(recipientSeed); // 32-byte seed; same as libsodium crypto_box_seed_keypair
const bundle = sealBox(plaintext, recipient.publicKey);
const opened = openBox(bundle, recipient.secretKey); // Uint8Array | null
const sealed = sealSecretBox(plaintext, secretboxKey); // 32-byte key
const unsealed = openSecretBox(sealed, secretboxKey); // Uint8Array | null
const stored = sealJson({ machines: [] }, secretboxKey);
const catalog = openJson(stored, secretboxKey); // unknown | null
const signing = signingKeyPairFromSeed(signingSeed); // 32-byte seed
const signature = signDetached(plaintext, signing.secretKey); // 64-byte signature
verifyDetached(plaintext, signature, signing.publicKey); // boolean

Raw keys, authenticated boxes and notices

const sender = boxKeyPair();
const device = boxKeyPair();
const authenticated = box(text, device.publicKey, sender.secretKey);
const opened = openAuthBox(authenticated, sender.publicKey, device.secretKey);
const notice = sealNotice({ kind: 'completed', job: 'build' }, device.publicKey);
const event = openNotice(notice, device.secretKey);

openBox now takes a raw X25519 secret. For stored seeds, keep boxKeyPairFromSeed(seed) and pass its secretKey, or replace the old openBox(bundle, seed) call with openBoxFromSeed(bundle, seed). Stored ciphertext and seed derivation are unchanged. A raw secret and a seed are different inputs.

A known-sender box requires a trusted public key for the peer; both peers can produce its ciphertext, so it is not a signature. Anonymous boxes and notices do not identify the sender. Validate decrypted notice values in the app before acting on them. JSON null is indistinguishable from an opening failure; undefined values, cyclic objects and BigInts cannot be sealed as JSON.

Opening a notice in an iOS Notification Service Extension

No JavaScript runs in an iOS Notification Service Extension, so the package also ships a Swift opener, ios/Sources/ByokitSeal/ByokitSeal.swift (CryptoKit only, iOS 13+). Add that file to the extension target. With @byokit/relay's mutableContent: true, iOS runs the extension before the alert shows, even when the app is not running, and the extension can replace the generic text with the notice:

import UserNotifications

final class NotificationService: UNNotificationServiceExtension {
  override func didReceive(_ request: UNNotificationRequest, withContentHandler done: @escaping (UNNotificationContent) -> Void) {
    let content = request.content.mutableCopy() as! UNMutableNotificationContent
    if let secret = ByokitSeal.keychainSecret(service: "app:no-auth", account: "notice-secret", accessGroup: "TEAMID.com.example.shared"),
       let notice = ByokitSeal.openNotice(userInfo: request.content.userInfo, secret: secret) as? [String: Any],
       let title = notice["title"] as? String, let body = notice["body"] as? String {
      content.title = title // validate before showing; the notice's sender is not authenticated
      content.body = body
    }
    done(content) // on any failure the generic alert shows unchanged
  }
}

The app owns the notice key: it makes it with boxKeyPair(), gives the public key to its host, and saves only the 32-byte secret as an unpadded base64url string in a keychain access group shared with its extension, readable after first unlock (with expo-secure-store: setItemAsync('notice-secret', secret, { accessGroup, keychainAccessible: AFTER_FIRST_UNLOCK }), which stores service app:no-auth). keychainSecret reads exactly that one item; the extension never reads other keychain items and never logs the secret or the notice. openNotice(envelope, secret:) opens an envelope from anywhere else. Its byte-for-byte parity with the TypeScript opener is checked by ios/Tests/ByokitSealTests against vectors this package's tests make and libsodium opens (swift test in this directory). One difference cannot be avoided: a Swift string cannot hold an unpaired UTF-16 surrogate, so a notice whose JSON contains one (for example text cut with slice through an emoji) opens in TypeScript but is nil in Swift, and the generic alert shows. Seal well-formed text (String.prototype.toWellFormed).

Formats

• sealBox emits ephemeral X25519 public key (32) | nonce (24) | crypto_box_easy ciphertext (16-byte MAC first).
• box emits nonce (24) | crypto_box_easy ciphertext (16-byte MAC first).
• sealNotice emits { v: 1, sealed }, where sealed is unpadded base64url of sealBox UTF-8 JSON bytes.
• sealSecretBox emits nonce (24) | crypto_secretbox_easy ciphertext.
• sealJson uses JSON.stringify then UTF-8; openJson parses UTF-8 and returns null on failure.
• openBox, openAuthBox and openSecretBox return null for short, tampered, or wrong-key bundles.
• Invalid key lengths passed to seal/sign throw.

Randomness and keys

Each seal accepts an optional final (length: number) => Uint8Array RNG for deterministic tests; in production the default is crypto.getRandomValues.

import { sealSecretBox, type RandomBytes } from '@byokit/seal';

// Tests only: a fixed RNG makes the output repeatable. Never in production.
const fixed: RandomBytes = (length) => new Uint8Array(length).fill(7);
const key = new Uint8Array(32).fill(1);
const a = sealSecretBox(new Uint8Array([1, 2, 3]), key, fixed);

Never reuse a secretbox nonce with the same key or substitute deterministic RNG in production. Keep secrets in a platform secure store; this library does not manage storage or keys.

Dependencies

Uses pinned @noble/curves, @noble/ciphers and @noble/hashes. No native modules or Node runtime imports.

Tests

The suite checks fixed libsodium/tweetnacl vectors and both directions of interoperability with sodium-native, including tamper and wrong-key cases. Run npm run build && npm run check && npm test at the repository root.

Links

• byokit, the repository root
• CHANGELOG.md
• SECURITY.md
• examples/expo: box, secretbox and signatures on iOS and Android, with the crypto.getRandomValues polyfill (expo-crypto) in polyfills.ts

License

Apache-2.0. See LICENSE and NOTICE.