@polkadot-apps/crypto

Cryptographic primitives for Polkadot apps -- symmetric encryption, key derivation, and NaCl operations.

Install

pnpm add @polkadot-apps/crypto
Copy

No peer dependencies. This package bundles @noble/ciphers, @noble/hashes, and tweetnacl.

Quick start

import {
  xchachaEncrypt,
  xchachaDecrypt,
  randomBytes,
} from "@polkadot-apps/crypto";

const key = randomBytes(32);
const { ciphertext, nonce } = xchachaEncrypt(data, key);
const plaintext = xchachaDecrypt(ciphertext, key, nonce);
Copy

Symmetric encryption

All symmetric functions accept a 32-byte key and return { ciphertext: Uint8Array, nonce: Uint8Array } on encrypt. Text variants accept a string and return one on decrypt. Packed variants concatenate nonce || ciphertext into a single Uint8Array.

Algorithm comparison

AES-256-GCM

import {
  aesGcmEncrypt,
  aesGcmDecrypt,
  aesGcmEncryptText,
  aesGcmDecryptText,
  aesGcmEncryptPacked,
  aesGcmDecryptPacked,
  randomBytes,
} from "@polkadot-apps/crypto";

const key = randomBytes(32);

// Binary
const { ciphertext, nonce } = aesGcmEncrypt(data, key);
const plain = aesGcmDecrypt(ciphertext, key, nonce);

// Text
const { ciphertext: ct, nonce: n } = aesGcmEncryptText("hello", key);
const str = aesGcmDecryptText(ct, key, n);

// Packed (nonce || ciphertext in one buffer)
const packed = aesGcmEncryptPacked(data, key);
const unpacked = aesGcmDecryptPacked(packed, key);
Copy

ChaCha20-Poly1305

import {
  chachaEncrypt,
  chachaDecrypt,
  chachaEncryptText,
  chachaDecryptText,
  randomBytes,
} from "@polkadot-apps/crypto";

const key = randomBytes(32);

const { ciphertext, nonce } = chachaEncrypt(data, key);
const plain = chachaDecrypt(ciphertext, key, nonce);

const { ciphertext: ct, nonce: n } = chachaEncryptText("hello", key);
const str = chachaDecryptText(ct, key, n);
Copy

XChaCha20-Poly1305 (recommended)

The 24-byte nonce makes random nonce generation safe for virtually unlimited encryptions under the same key.

import {
  xchachaEncrypt,
  xchachaDecrypt,
  xchachaEncryptText,
  xchachaDecryptText,
  xchachaEncryptPacked,
  xchachaDecryptPacked,
  randomBytes,
} from "@polkadot-apps/crypto";

const key = randomBytes(32);

// Binary
const { ciphertext, nonce } = xchachaEncrypt(data, key);
const plain = xchachaDecrypt(ciphertext, key, nonce);

// Text
const { ciphertext: ct, nonce: n } = xchachaEncryptText("hello", key);
const str = xchachaDecryptText(ct, key, n);

// Packed (nonce || ciphertext in one buffer)
const packed = xchachaEncryptPacked(data, key);
const unpacked = xchachaDecryptPacked(packed, key);
Copy

Asymmetric encryption (NaCl)

Sealed box (anonymous sender)

Uses an ephemeral keypair so the recipient cannot identify the sender. Output format: ephemeralPubKey(32) || nonce(24) || ciphertext.

import { sealedBoxEncrypt, sealedBoxDecrypt, nacl } from "@polkadot-apps/crypto";

const recipient = nacl.box.keyPair();
const sealed = sealedBoxEncrypt(message, recipient.publicKey);
const plaintext = sealedBoxDecrypt(sealed, recipient.secretKey);
Copy

Box (authenticated, both parties known)

Uses X25519 key agreement and XSalsa20-Poly1305 encryption. Output format: nonce(24) || ciphertext.

import { boxEncrypt, boxDecrypt, nacl } from "@polkadot-apps/crypto";

const alice = nacl.box.keyPair();
const bob = nacl.box.keyPair();

const packed = boxEncrypt(message, bob.publicKey, alice.secretKey);
const plaintext = boxDecrypt(packed, alice.publicKey, bob.secretKey);
Copy

Key derivation

HKDF-SHA256 (RFC 5869). deriveKey is a convenience wrapper that outputs 32 bytes. For custom output lengths or hash functions, use the re-exported hkdf, extract, and expand primitives directly.

import { deriveKey, randomBytes } from "@polkadot-apps/crypto";

const masterKey = randomBytes(32);
const encryptionKey = deriveKey(masterKey, "myapp-v1", "document-encryption");
Copy

Utilities

import { randomBytes } from "@polkadot-apps/crypto";

const bytes = randomBytes(32);
Copy

Migration note: bytesToHex, hexToBytes, utf8ToBytes, and concatBytes have moved to @polkadot-apps/utils. Import them from there instead.

API

AES-256-GCM

ChaCha20-Poly1305

XChaCha20-Poly1305

NaCl asymmetric

Key derivation

Utilities

Types

type SymmetricAlgorithm =
  | "aes-256-gcm"
  | "chacha20-poly1305"
  | "xchacha20-poly1305";

type KemAlgorithm =
  | "x25519"
  | "ml-kem-768"         // post-quantum, future
  | "x25519-ml-kem-768"; // hybrid, future

interface EncryptedPayload {
  algorithm: SymmetricAlgorithm;
  ciphertext: Uint8Array;
  nonce: Uint8Array;
  kem?: KemAlgorithm;
}
Copy

License

Apache-2.0