Nostr Nsec Seedphrase Library

A comprehensive TypeScript library designed to make Nostr keys more human-readable and easier to manage. By converting nsec keys to mnemonic seed phrases, this library simplifies the process of storing and re-entering keys into Nostr applications.

⚠️ Important Security Notice

This library handles cryptographic keys and seed phrases that are critical for securing your Nostr identity and data. Just like Bitcoin, any seed phrase or private key (nsec) generated by this library must be stored with the utmost security and care.

Developers using this library must inform their users about the critical nature of managing seed phrases, nsec, and hex keys. It is the user's responsibility to securely store and manage these keys. The library and its authors disclaim any responsibility or liability for lost keys, seed phrases, or data resulting from mismanagement.

Features

• Generate secure BIP39 mnemonics for Nostr key pairs
• Create nsec private keys from hex format
• Convert between nsec/npub and hex representations
• TypeScript support with comprehensive type definitions
• Secure key management utilities
• Extensive testing and documentation

Installation

npm install @humanjavaenterprises/nostr-nsec-seedphrase

Usage

Basic Key Generation

import { 
  generateKeyPairWithSeed,
  nsecToHex,
  npubToHex,
  hexToNpub,
  hexToNsec,
  validateSeedPhrase,
  seedPhraseToKeyPair
} from '@humanjavaenterprises/nostr-nsec-seedphrase';

// Generate new keys with seed phrase
const keyPair = generateKeyPairWithSeed();
console.log(keyPair);
// {
//   seedPhrase: "your twelve word seed phrase here",
//   nsec: "nsec1...",
//   npub: "npub1...",
//   privateKey: "hex...",
//   publicKey: "hex..."
// }

// Validate the seed phrase
const isValid = validateSeedPhrase(keyPair.seedPhrase);
console.log(isValid); // true

Converting Between Formats

// Convert hex to nsec/npub
const nsec = hexToNsec('your-hex-private-key');
const npub = hexToNpub('your-hex-public-key');

// Convert nsec/npub to hex
const privateKeyHex = nsecToHex('nsec1...');
const publicKeyHex = npubToHex('npub1...');

// Convert seed phrase to key pair
const keyPair = seedPhraseToKeyPair('your twelve word seed phrase here');

Converting Nsec to Seedphrase

const seedPhrase = await NostrSeedPhrase.nsecToSeed('nsec1...');
console.log(seedPhrase); // "your twelve word mnemonic phrase here"

Converting Seedphrase to Nsec

const nsec = await NostrSeedPhrase.seedToNsec('your twelve word mnemonic phrase here');
console.log(nsec); // "nsec1..."

Converting Hex to Nsec

const nsec = await NostrSeedPhrase.hexToNsec('your-hex-private-key');
console.log(nsec); // "nsec1..."

Converting Nsec to Hex

const hex = await NostrSeedPhrase.nsecToHex('nsec1...');
console.log(hex); // "hex..."

Converting Npub to Hex

const hex = await NostrSeedPhrase.npubToHex('npub1...');
console.log(hex); // "hex..."

Converting Hex to Npub

const npub = await NostrSeedPhrase.hexToNpub('hex...');
console.log(npub); // "npub1..."

API Reference

generateKeyPairWithSeed()

Generates a new Nostr key pair with seed phrase. This is useful when you need to provide users with a recoverable key pair.

Returns:

{
  seedPhrase: string;  // BIP39 seed phrase for key recovery
  nsec: string;        // Private key in bech32 format
  npub: string;        // Public key in bech32 format
  privateKey: string;  // Private key in hex format
  publicKey: string;   // Public key in hex format
}

nsecToSeed(nsec: string)

Converts a Nostr private key to a BIP39 seed phrase.

Parameters:

• nsec: The nsec format private key

Returns: string - The BIP39 seed phrase

seedToNsec(seedPhrase: string)

Converts a BIP39 seed phrase back to a Nostr key pair.

Parameters:

• seedPhrase: The BIP39 seed phrase

Returns: string - The nsec format private key

hexToNsec(hexPrivateKey: string)

Converts a hex private key to nsec format.

Parameters:

• hexPrivateKey: Hex string of the private key

Returns: Promise<string> - The nsec format private key

nsecToHex(nsec: string)

Converts an nsec private key to hex format.

Parameters:

• nsec: The nsec format private key

Returns: Promise<string> - The hex format private key

npubToHex(npub: string)

Converts an npub public key to hex format.

Parameters:

• npub: The npub format public key

Returns: Promise<string> - The hex format public key

hexToNpub(hexPublicKey: string)

Converts a hex public key to npub format.

Parameters:

• hexPublicKey: Hex string of the public key

Returns: Promise<string> - The npub format public key

Security Best Practices

1. Never Share Private Keys: Keep your nsec and private key hex values secure and never share them.
2. Backup Seed Phrases: Safely store your seed phrase in a secure location.
3. Verify Keys: Always verify key pairs after generation or conversion.
4. Environment Variables: Use environment variables for storing sensitive keys in production.
5. Memory Management: Clear sensitive data from memory when no longer needed.

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Testing

Run the test suite:

npm test

License

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

Support

• Create an Issue
• Follow on Nostr
• Follow on X (Twitter)

Acknowledgments

• nostr-tools - For Nostr protocol utilities
• bip39 - For mnemonic generation