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.

Release note — v0.8.0 (staged, pending publish). Part of the coordinated 2026-07 correctness pass across the Nostr library family. This release makes seed-phrase derivation NIP-06 compliant (BIP-32 m/44'/1237'/0'/0/0) and public keys 32-byte x-only per BIP-340, verified against a shared known-answer vector set (including the official NIP-06 spec vectors). Both are breaking — see CHANGELOG.md. The family dogfoods only its own libraries — no upstream nostr-tools dependency.

Core Features

• 🌱 Seedphrase Management

  • Generate and validate BIP39 seed phrases
  • Convert between seed phrases and Nostr keys — standard NIP-06 derivation (BIP-32 path m/44'/1237'/0'/0/0), interoperable with Alby, nos2x, nak, and other NIP-06 tooling
  • Secure entropy generation
  • Multiple language support

• 🔑 Key Operations

  • Convert between formats (hex, nsec, npub)
  • Validate key pairs
  • Generate new key pairs
  • Public key derivation — 32-byte x-only keys per BIP-340 (Nostr identity)

• 📝 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, // 32-byte private key (hex)
  publicKey: keyPair.publicKey,   // 32-byte x-only public key (hex, BIP-340)
  nsec: keyPair.nsec,            // bech32 format
  npub: keyPair.npub             // bech32 format
});

Public keys are 32-byte x-only keys (BIP-340), as required by Nostr. getPublicKey, seedPhraseToKeyPair, fromHex, and privateKeyToNpub all return the 64-hex-char x-only key. If you specifically need the 33-byte SEC1 compressed key (for ECDH / non-Nostr interop), use getCompressedPublicKey. This changed in v0.8.0 (previously 33-byte compressed) — see CHANGELOG.

Seed-phrase derivation is NIP-06 compliant as of v0.8.0. The private key is derived via the BIP-32 path m/44'/1237'/0'/0/0 from the BIP39 seed, so the same mnemonic yields the same key in Alby, nos2x, nak, and any other NIP-06 tool (verified against the official NIP-06 spec test vectors). Versions before 0.8.0 used a non-standard sha256(entropy) derivation; if you created an identity with an older version, recover it with seedPhraseToPrivateKeyLegacy / seedPhraseToKeyPairLegacy:

import { seedPhraseToKeyPairLegacy } from 'nostr-nsec-seedphrase';
const oldIdentity = seedPhraseToKeyPairLegacy('your pre-0.8.0 seed phrase');

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.