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 nostr-nsec-seedphrase

Usage

Basic Key Generation

import { NostrSeedPhrase } from 'nostr-nsec-seedphrase';

// Generate new keys with mnemonic
const keys = await NostrSeedPhrase.generateNew();
console.log(keys);
// {
//   mnemonic: "your twelve word mnemonic phrase here",
//   nsec: "nsec1...",
//   npub: "npub1...",
//   privateKeyHex: "hex...",
//   publicKeyHex: "hex..."
// }

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

generateNew()

Generates a new Nostr key pair with mnemonic phrase.

Returns:

{
  mnemonic: string;
  nsec: string;
  npub: string;
  privateKeyHex: string;
  publicKeyHex: string;
}

nsecToSeed(nsec: string)

Converts a Nostr private key to a BIP39 seed phrase.

Parameters:

• nsec: The nsec format private key

Returns: Promise<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: Promise<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 Mnemonics: Safely store your mnemonic 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