Shogun Derive

A lightweight cryptographic key derivation library for the Shogun SDK ecosystem. This library provides deterministic key derivation from passwords or seed data, supporting multiple cryptographic standards.

Features

• P-256 Key Derivation: Default ECDSA key pairs for signing and encryption
• Bitcoin P2PKH Support: secp256k1 keys with Bitcoin address generation
• Ethereum Support: secp256k1 keys with Ethereum address generation
• PBKDF2 Key Stretching: 300,000 iterations for security
• Unicode Support: Proper handling of international characters
• TypeScript Support: Full type definitions included

Installation

npm install shogun-derive

Usage

Basic Usage (P-256 keys only)

import { derive } from 'shogun-derive';

const keys = await derive('my-password', 'extra-entropy');
console.log(keys.pub);  // Public key for signing
console.log(keys.priv); // Private key for signing
console.log(keys.epub); // Public key for encryption
console.log(keys.epriv); // Private key for encryption

Bitcoin Keys

import { derive } from 'shogun-derive';

const keys = await derive('my-password', 'extra-entropy', {
  includeSecp256k1Bitcoin: true
});

if (keys.secp256k1Bitcoin) {
  console.log(keys.secp256k1Bitcoin.privateKey); // Hex private key
  console.log(keys.secp256k1Bitcoin.publicKey);  // Hex public key
  console.log(keys.secp256k1Bitcoin.address);    // Bitcoin P2PKH address
}

Ethereum Keys

import { derive } from 'shogun-derive';

const keys = await derive('my-password', 'extra-entropy', {
  includeSecp256k1Ethereum: true
});

if (keys.secp256k1Ethereum) {
  console.log(keys.secp256k1Ethereum.privateKey); // 0x-prefixed hex private key
  console.log(keys.secp256k1Ethereum.publicKey);  // 0x-prefixed hex public key
  console.log(keys.secp256k1Ethereum.address);    // Ethereum address
}

All Key Types

import { derive } from 'shogun-derive';

const keys = await derive('my-password', 'extra-entropy', {
  includeP256: true,
  includeSecp256k1Bitcoin: true,
  includeSecp256k1Ethereum: true
});

// All key types will be available

Random Key Generation

import { derive } from 'shogun-derive';

// Generate keys from random entropy
const keys = await derive(undefined, undefined);

API Reference

derive(pwd, extra, options?)

Derives cryptographic keys from input data.

Parameters

• pwd (string | Uint8Array | undefined): Password or seed data
• extra (string | string[] | undefined): Additional entropy
• options (DeriveOptions): Configuration options

Options

interface DeriveOptions {
  includeP256?: boolean;              // Default: true
  includeSecp256k1Bitcoin?: boolean;  // Default: false
  includeSecp256k1Ethereum?: boolean; // Default: false
}

Returns

interface DeriveResult {
  pub?: string;                       // P-256 signing public key
  priv?: string;                      // P-256 signing private key
  epub?: string;                      // P-256 encryption public key
  epriv?: string;                     // P-256 encryption private key
  secp256k1Bitcoin?: {
    privateKey: string;               // Hex private key
    publicKey: string;                // Hex public key
    address: string;                  // Bitcoin P2PKH address
  };
  secp256k1Ethereum?: {
    privateKey: string;               // 0x-prefixed hex private key
    publicKey: string;                // 0x-prefixed hex public key
    address: string;                  // Ethereum address
  };
}

Security Features

• PBKDF2 Key Stretching: 300,000 iterations with SHA-256
• Deterministic Output: Same input always produces same keys
• Salt Separation: Different salts for different key types
• Input Validation: Proper validation of input parameters
• Unicode Normalization: NFC normalization for consistent results

Recent Fixes (v1.0.0)

Bug Fixes

• Fixed salt type casting: Resolved issue with Uint8Array to BufferSource conversion in PBKDF2
• Improved Unicode support: Fixed btoa() compatibility with Unicode characters
• Added input validation: Proper validation for empty strings and arrays
• Enhanced error handling: Better error messages for invalid inputs

Improvements

• Type safety: Improved TypeScript type definitions
• Documentation: Enhanced JSDoc comments
• Test coverage: Added comprehensive test suite
• Browser compatibility: Better cross-browser support

Development

Building

npm run build

Testing

npm test

Formatting

npm run format

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

Changelog

v1.0.0

• Initial release
• P-256, Bitcoin, and Ethereum key derivation
• PBKDF2 key stretching
• TypeScript support
• Comprehensive test suite