nostr-nsec-seedphrase

A focused TypeScript library for Nostr key management and seedphrase functionality, with seamless integration with nostr-crypto-utils. This package specializes in converting between nsec keys and seed phrases, managing delegations, and handling various key formats.

Core Features

🌱 Seedphrase Management
- Generate and validate BIP39 seed phrases
- Convert between seed phrases and Nostr keys
- Secure entropy generation
- Multiple language support
🔑 Key Operations
- Convert between formats (hex, nsec, npub)
- Validate key pairs
- Generate new key pairs
- Public key derivation
📝 Delegation Support (NIP-26)
- Create delegation tokens
- Time-based conditions
- Event kind filtering
- Token validation and verification
- Expiry management
🔄 Format Conversions
- Hex ↔ nsec
- Hex ↔ npub
- Seed phrase ↔ key pair
- Comprehensive validation

NIPs Support Status

🟢 Fully implemented 🟡 Partially implemented 🔴 Not implemented

NIP	Status	Description
01	🟢	Basic protocol flow & event signing
06	🟢	Basic key derivation from seed phrase
19	🟢	bech32-encoded entities
26	🟢	Delegated event signing

Installation

npm install nostr-nsec-seedphrase

Quick Start

Generate a New Key Pair with Seed Phrase

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

const keyPair = generateKeyPairWithSeed();
console.log({
  seedPhrase: keyPair.seedPhrase,
  nsec: keyPair.nsec,
  npub: keyPair.npub
});

Convert Seed Phrase to Key Pair

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

const keyPair = await seedPhraseToKeyPair('your twelve word seed phrase here');
console.log({
  privateKey: keyPair.privateKey, // hex format
  publicKey: keyPair.publicKey,   // hex format
  nsec: keyPair.nsec,            // bech32 format
  npub: keyPair.npub             // bech32 format
});

Create and Verify Delegations

import { createDelegation, verifyDelegation } from 'nostr-nsec-seedphrase';

// Create a delegation token
const delegation = await createDelegation(
  delegateePublicKey,
  {
    kinds: [1, 2], // allowed event kinds
    since: Math.floor(Date.now() / 1000),
    until: Math.floor(Date.now() / 1000) + 86400 // 24 hours
  },
  delegatorPrivateKey
);

// Verify a delegation
const isValid = await verifyDelegation(
  delegation,
  Math.floor(Date.now() / 1000), // current timestamp
  1 // event kind to verify
);

Key Features in Detail

1. Seedphrase Management

The library provides comprehensive seedphrase functionality:

import { 
  generateSeedPhrase,
  validateSeedPhrase,
  seedPhraseToKeyPair
} from 'nostr-nsec-seedphrase';

// Generate a new seed phrase
const seedPhrase = generateSeedPhrase();

// Validate an existing seed phrase
const isValid = validateSeedPhrase(seedPhrase);

// Convert seed phrase to key pair
const keyPair = await seedPhraseToKeyPair(seedPhrase);

2. Key Format Conversions

Easy conversion between different key formats:

import {
  hexToNsec,
  hexToNpub,
  nsecToHex,
  npubToHex
} from 'nostr-nsec-seedphrase';

// Convert hex to bech32 formats
const nsec = hexToNsec(privateKeyHex);
const npub = hexToNpub(publicKeyHex);

// Convert bech32 to hex formats
const privateKeyHex = nsecToHex(nsec);
const publicKeyHex = npubToHex(npub);

3. Delegation Management

Comprehensive NIP-26 delegation support:

import {
  createDelegation,
  verifyDelegation,
  isDelegationValid,
  getDelegationExpiry
} from 'nostr-nsec-seedphrase';

// Create a delegation with conditions
const delegation = await createDelegation(delegatee, {
  kinds: [1], // only text notes
  since: Math.floor(Date.now() / 1000),
  until: Math.floor(Date.now() / 1000) + 86400
}, delegatorPrivateKey);

// Check delegation validity
const isValid = await isDelegationValid(delegation);

// Get delegation expiry
const expiry = getDelegationExpiry(delegation);

Module Support

This package supports both ESM and CommonJS usage:

ESM (recommended)

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

CommonJS

const { generateKeyPairWithSeed } = require('nostr-nsec-seedphrase');

Webpack Usage

The package is fully compatible with webpack for client-side applications. Add to your webpack config:

module.exports = {
  resolve: {
    fallback: {
      "crypto": require.resolve("crypto-browserify"),
      "stream": require.resolve("stream-browserify"),
      "buffer": require.resolve("buffer/")
    }
  }
};

Documentation

The library includes comprehensive TypeScript types and JSDoc documentation. You can:

View the documentation in your IDE through TypeScript and JSDoc annotations
Generate HTML documentation using:
```
npm run docs
```
View the generated documentation locally:
```
npm run docs:serve
```
Access the generated documentation in the docs directory

Key Format Utilities

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

// Encode/decode public keys
const npub = nip19.npubEncode(hexPublicKey);
const hexPubkey = nip19.npubDecode(npub);

// Encode/decode private keys
const nsec = nip19.nsecEncode(hexPrivateKey);
const hexPrivkey = nip19.nsecDecode(nsec);

// Encode/decode event IDs
const note = nip19.noteEncode(eventId);
const hexEventId = nip19.noteDecode(note);

Integration with nostr-crypto-utils

This package is designed to work seamlessly with nostr-crypto-utils:

Uses compatible key formats and types
Leverages nostr-crypto-utils for cryptographic operations
Maintains consistent error handling and validation

Security Considerations

Never share or expose private keys or seed phrases
Always validate input seed phrases and keys
Use secure entropy sources for key generation
Implement proper key storage practices
Regularly rotate delegation tokens
Set appropriate expiry times for delegations

Contributing

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

License

MIT License - see the LICENSE file for details.

Version 0.6.5

Fixed TypeScript errors related to unknown type assignments across multiple files.
Improved error handling by converting error objects to strings before logging.
Updated logger imports to use default imports where necessary.
Ensured consistent logging practices throughout the codebase.
Added a checklist for future reference.

Package detail