@tetherto/wdk-secret-manager

Note: This package is currently in beta. Please test thoroughly in development environments before using in production.

A small, security-focused utility for generating, encrypting, and managing wallet secrets. It provides:

• Versioned, self-describing payloads
• PBKDF2-SHA256 key derivation
• Authenticated encryption using libsodium crypto_secretbox
• BIP-39 mnemonic/seed helpers
• Memory zeroization utilities

🔍 About WDK

This module is part of the WDK (Wallet Development Kit) project, which empowers developers to build secure, non-custodial wallets with unified blockchain access, stateless architecture, and full user control.

For detailed documentation about the complete WDK ecosystem, visit https://docs.wallet.tether.io.

🌟 Features

• PBKDF2-SHA256 KDF: Derives strong keys from user passkeys and a 16-byte salt
• Versioned Payloads: Header includes version, KDF algorithm, iterations, salt, and nonce
• Authenticated Encryption: Uses libsodium crypto_secretbox (XSalsa20-Poly1305)
• BIP-39 Support: Convert entropy ↔ mnemonic and derive the standard 64-byte seed
• Master-Key Override: Optionally provide a 32-byte key to skip PBKDF2
• Secure Memory Handling: Zeroizes sensitive buffers and supports dispose()
• Bare Runtime Support: Ships a bare build for bare-wdk-runtime

⬇️ Installation

Install with npm:

npm install @tetherto/wdk-secret-manager

🚀 Quick Start

Importing

import WdkSecretManager from "@tetherto/wdk-secret-manager";

If you are using the bare runtime, import as usual; the bare export is provided for compatible bundlers/environments.

Creating a Secret Manager

import WdkSecretManager from "@tetherto/wdk-secret-manager";

const passkey = "correct horse battery staple"; // minimum 12 characters
const salt = WdkSecretManager.generateSalt(); // 16-byte Buffer

// Optional: tune PBKDF2 iterations
const sm = new WdkSecretManager(passkey, salt, { iterations: 100_000 });

Generating and Encrypting Entropy + Seed

// Generates 16-byte entropy, converts to BIP-39 mnemonic, derives 64-byte seed,
// and encrypts both with the manager's settings
const { encryptedEntropy, encryptedSeed } = await sm.generateAndEncrypt();

// Decrypt later
const entropy = sm.decrypt(encryptedEntropy); // 16 bytes
const seed = sm.decrypt(encryptedSeed); // 64 bytes

Encrypting and Decrypting Arbitrary Data

// Accepts payloads between 16 and 64 bytes
const data = crypto.getRandomValues(new Uint8Array(32));
const payload = sm.encrypt(Buffer.from(data));
const out = sm.decrypt(payload);

Using a Pre-Derived Master Key (Skip PBKDF2)

import { pbkdf2Sync } from "crypto";
import b4a from "b4a";

const masterKey = b4a.from(
  pbkdf2Sync(b4a.from(passkey), b4a.from(salt), 100_000, 32, "sha256")
);

const cipher = sm.encrypt(
  Buffer.from("0123456789abcdef0123456789abcdef"),
  masterKey
);
const plain = sm.decrypt(cipher, masterKey);

Mnemonic Helpers

const entropy16 = sm.generateRandomBuffer(); // 16 bytes
const mnemonic = sm.entropyToMnemonic(entropy16); // 12 words
const entropyRoundTrip = sm.mnemonicToEntropy(mnemonic); // back to 16 bytes

Memory Management

// Wipes internal passkey/salt/iteration state from memory
sm.dispose();

📚 API Reference

Table of Contents

| Class | Description | Methods | | ------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | WdkSecretManager | High-level manager for secret generation, encryption, and decryption. | constructor, generateSalt, generateAndEncrypt, encrypt, decrypt, entropyToMnemonic, mnemonicToEntropy, generateRandomBuffer, dispose |

WdkSecretManager

The main class for generating and managing encrypted secrets.

Constructor

new WdkSecretManager(passKey, salt, kdfParams?)

Parameters:

• passKey (string | Buffer | Uint8Array): User passkey (min 12 characters/bytes)
• salt (Buffer): 16-byte salt used for key derivation
• kdfParams (object, optional):
  • iterations (number, optional): PBKDF2 iterations (default: 100_000)

Static Methods

• generateSalt(): Buffer
  • Returns a new 16-byte random salt.

Methods

| Method | Description | Returns | | ------------------------------------------------ | -------------------------------------------------------------------------- | ----------------------------------------------------- | | generateAndEncrypt(entropyOpt?, masterKeyOpt?) | Generates 16-byte entropy, derives mnemonic + 64-byte seed, encrypts both. | { encryptedSeed: Buffer, encryptedEntropy: Buffer } | | encrypt(data, masterKeyOpt?) | Encrypts 16–64 byte payload with header and MAC. | Buffer (payload) | | decrypt(payload, masterKeyOpt?) | Decrypts a payload produced by this manager. | Buffer (plaintext) | | generateRandomBuffer() | Returns 16 random bytes. | Buffer | | entropyToMnemonic(entropy) | Converts 16-byte entropy to 12-word mnemonic. | string | | mnemonicToEntropy(mnemonic) | Converts 12-word mnemonic to 16-byte entropy. | Buffer | | dispose() | Zeroizes internal state; instance becomes unusable. | void |

Payload Format

Header [version(1), kdf_alg(1), iterations(u32le), reserved(u32le=0), salt(16), nonce(24)] followed by cipher = secretbox( [len(1) | data(16..64)], nonce, key).

generateAndEncrypt(entropyOpt?, masterKeyOpt?)

Generates 16-byte entropy, converts it to a BIP-39 12-word mnemonic, derives the 64-byte BIP-39 seed, and encrypts both values.

Parameters:

• entropyOpt (Buffer | null, optional): If provided, must be exactly 16 bytes. When not provided, secure random entropy is generated.
• masterKeyOpt (Buffer | null, optional): A 32-byte key. If provided, PBKDF2 derivation is skipped and this key is used for encryption.

Returns: { encryptedSeed: Buffer, encryptedEntropy: Buffer }

Example:

const { encryptedSeed, encryptedEntropy } = await sm.generateAndEncrypt();
const seed = sm.decrypt(encryptedSeed); // 64 bytes
const entropy = sm.decrypt(encryptedEntropy); // 16 bytes

encrypt(data, masterKeyOpt?)

Encrypts a 16–64 byte payload using a versioned header and crypto_secretbox. The plaintext is prefixed with a single-byte length before encryption.

Parameters:

• data (Buffer): Plaintext data. Must be between 16 and 64 bytes inclusive.
• masterKeyOpt (Buffer | null, optional): 32-byte master key. If omitted, a key is derived via PBKDF2-SHA256 from the manager's passkey + salt.

Returns: Buffer - Encrypted payload with header and MAC.

Throws: on invalid input length, missing/invalid passkey or salt, or other validation errors.

Example:

const data = Buffer.from("0123456789abcdef0123456789abcdef"); // 32 bytes
const payload = sm.encrypt(data);

decrypt(payload, masterKeyOpt?)

Decrypts a payload produced by this manager, validates the header, and returns the original plaintext.

Parameters:

• payload (Buffer): Encrypted payload produced by encrypt.
• masterKeyOpt (Buffer | null, optional): 32-byte master key. If omitted, a key is derived via PBKDF2-SHA256 using the header's salt and iteration count.

Returns: Buffer - Decrypted plaintext.

Throws: when authentication fails, payload is malformed, length prefix is out of bounds, or inputs are invalid.

Example:

const plain = sm.decrypt(payload);

generateRandomBuffer()

Generates 16 bytes of cryptographically secure random data using libsodium.

Returns: Buffer

Example:

const entropy16 = sm.generateRandomBuffer();

entropyToMnemonic(entropy)

Converts 16-byte entropy into a 12-word BIP-39 mnemonic.

Parameters:

• entropy (Buffer): Exactly 16 bytes.

Returns: string - 12-word mnemonic.

Throws: on invalid type or length.

Example:

const mnemonic = sm.entropyToMnemonic(entropy16);

mnemonicToEntropy(mnemonic)

Converts a 12-word mnemonic into its original 16-byte entropy buffer.

Parameters:

• mnemonic (string): Non-empty 12-word BIP-39 mnemonic.

Returns: Buffer - 16-byte entropy.

Throws: on invalid/empty string or non-12-word mnemonics.

Example:

const entropy = sm.mnemonicToEntropy(mnemonic);

dispose()

Securely wipes internal state (passkey, salt, iterations) from memory. The instance should not be used after calling this.

Returns: void

Example:

sm.dispose();

🌐 Supported Runtimes

• Node.js: Uses sodium-native and Node crypto for PBKDF2
• Bare Runtime: Ships a bare build; PBKDF2 provided by bare-crypto

🔒 Security Considerations

• Passkey Strength: Enforce long, high-entropy user passkeys (min 12 characters)
• Salt Handling: Use a unique 16-byte salt per user/passkey, store it with the payload
• KDF Parameters: Tune PBKDF2 iterations to balance security and performance
• Integrity & Confidentiality: crypto_secretbox provides authenticated encryption
• Master Key: Only use a 32-byte master key if you securely derive/transport it
• Memory Hygiene: Call dispose() after use to wipe sensitive state

🛠️ Development

Building

# Install dependencies
npm install

# Build TypeScript definitions
npm run build:types

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

Testing

# Run bare runtime tests
npm run test:bare

📜 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🆘 Support

For support, please open an issue on the repository.