Skip to content

Files

Latest commit

 

History

History

docs

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 

nostr-nsec-seedphrase v0.6.0


nostr-nsec-seedphrase

npm version npm downloads License TypeScript Test Status Code Style

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);

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.