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:

1. View the documentation in your IDE through TypeScript and JSDoc annotations
2. Generate HTML documentation using:

   npm run docs

3. View the generated documentation locally:

   npm run docs:serve

4. 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

Dependency Vulnerability Status

We actively monitor and address security vulnerabilities in this codebase. npm audit --omit=dev reports zero vulnerabilities for this package — there are no known security issues in production dependencies.

Any remaining npm audit findings are in development-only tooling (eslint, typescript-eslint, vitest, typedoc, etc.) and stem from transitive dependencies with no upstream fix available. These are devDependencies that are never included in the published package and pose no risk to consumers of this library. We monitor upstream fixes and update promptly when they become available.

Contributing

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

License

MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a detailed history of changes.