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.
🟢 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 |
npm install nostr-nsec-seedphrase
import { generateKeyPairWithSeed } from 'nostr-nsec-seedphrase';
const keyPair = generateKeyPairWithSeed();
console.log({
seedPhrase: keyPair.seedPhrase,
nsec: keyPair.nsec,
npub: keyPair.npub
});
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
});
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
);
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);
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);
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);
This package supports both ESM and CommonJS usage:
import { generateKeyPairWithSeed } from 'nostr-nsec-seedphrase';
const { generateKeyPairWithSeed } = require('nostr-nsec-seedphrase');
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/")
}
}
};
The library includes comprehensive TypeScript types and JSDoc documentation. You can:
npm run docs
npm run docs:serve
docs directoryimport { 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);
This package is designed to work seamlessly with nostr-crypto-utils:
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.
We welcome contributions! Please see our Contributing Guide for details.
MIT License - see the LICENSE file for details.
See CHANGELOG.md for a detailed history of changes.