Blockchain Commons Crypto Interfaces for TypeScript

Disclaimer: This package is under active development and APIs may change.

Introduction

@bcts/crypto exposes a uniform API for the cryptographic primitives used in higher-level Blockchain Commons projects such as Gordian Envelope.

Features

• Hash Functions: SHA-256, SHA-512, HMAC, PBKDF2, HKDF, CRC32
• Symmetric Encryption: ChaCha20-Poly1305 AEAD
• Public Key Cryptography:
  • X25519 (key agreement)
  • ECDSA (secp256k1 signing/verification)
  • Schnorr signatures (BIP-340)
  • Ed25519 (signing/verification)
• Key Derivation: Scrypt, Argon2id
• Memory Security: Best-effort memory zeroing utilities

Security Considerations

Memory Zeroing (memzero)

⚠️ IMPORTANT SECURITY LIMITATION

The memzero() function provides best-effort memory clearing in JavaScript/TypeScript, but cannot guarantee that sensitive data is fully erased from memory.

Why this limitation exists:

• JavaScript/TypeScript lacks volatile memory writes (unlike the Rust reference implementation which uses std::ptr::write_volatile())
• JavaScript engines and JIT compilers may optimize away zeroing operations
• The garbage collector may have made copies of sensitive data
• Swapped pages or memory dumps may contain copies

What memzero() does:

• ✅ Overwrites memory with zeros to reduce exposure time
• ✅ Makes a verification check to prevent some optimizations
• ❌ Cannot guarantee complete erasure from physical memory

Best practices for sensitive operations:

1. Use Web Crypto API when possible: For truly sensitive cryptographic operations, use crypto.subtle with non-extractable keys
2. Minimize exposure time: Call memzero() immediately after sensitive operations
3. Understand the limitations: This is defense-in-depth, not a security guarantee
4. Consider your threat model: Evaluate if JavaScript is appropriate for your security requirements

Example:

import { memzero } from '@bcts/crypto';

const sensitiveKey = new Uint8Array(32);
// ... use the key ...

// Clear from memory (best effort)
memzero(sensitiveKey);

For more details, see the implementation comments.

Rust Reference Implementation

This TypeScript implementation is based on bc-crypto-rust v0.14.0 (commit).