Nostr Crypto Utils

Overview

Core Features

Cryptographic Operations

Encoding Utilities

Protocol Support

Project Structure

├── src/
│ ├── crypto.ts # Core cryptographic operations
│ ├── encoding/ # Encoding utilities
│ │ ├── base64.ts
│ │ ├── hex.ts
│ │ └── index.ts
│ ├── types/ # Type definitions
│ │ ├── base.ts
│ │ ├── messages.ts
│ │ ├── protocol.ts
│ │ └── guards.ts
│ ├── nips/ # NIP implementations
│ └── utils/ # Utility functions

Technical Requirements

Security Notice

Why Choose nostr-crypto-utils?

Features

Supported NIPs

NIP-01 Features

NIP-04 Features

NIP-19 Features

NIP-19 Usage Examples

import { 
 npubEncode, 
 nsecEncode, 
 noteEncode, 
 nprofileEncode,
 neventEncode,
 naddrEncode,
 nrelayEncode,
 decode 
} from '@humanjavaenterprises/nostr-crypto-utils';
// Encode a public key
const npub = npubEncode('7f3b6c2444c526fc7b3a48b0a1e38fb6a5a4062d4a097c9e96feb3c1df2f36d0');
// npub1xtscya34g58tk0z6v2g0r6w5gpqrxdgkz9xeav
// Encode a private key
const nsec = nsecEncode('7f3b6c2444c526fc7b3a48b0a1e38fb6a5a4062d4a097c9e96feb3c1df2f36d0');
// nsec1xtscya34g58tk0z6v2g0r6w5gpqrxdgkz9xeav
// Encode a note ID
const note = noteEncode('7f3b6c2444c526fc7b3a48b0a1e38fb6a5a4062d4a097c9e96feb3c1df2f36d0');
// note1xtscya34g58tk0z6v2g0r6w5gpqrxdgkz9xeav
// Encode a profile with multiple relays
const nprofile = nprofileEncode(
 '7f3b6c2444c526fc7b3a48b0a1e38fb6a5a4062d4a097c9e96feb3c1df2f36d0',
 ['wss://relay1.example.com', 'wss://relay2.example.com']
);
// Encode an event with author and kind
const nevent = neventEncode(
 '7f3b6c2444c526fc7b3a48b0a1e38fb6a5a4062d4a097c9e96feb3c1df2f36d0',
 ['wss://relay.example.com'],
 '7f3b6c2444c526fc7b3a48b0a1e38fb6a5a4062d4a097c9e96feb3c1df2f36d0',
 1
);
// Encode an addressable entity (NIP-33)
const naddr = naddrEncode(
 '7f3b6c2444c526fc7b3a48b0a1e38fb6a5a4062d4a097c9e96feb3c1df2f36d0',
 30023,
 'my-article',
 ['wss://relay.example.com']
);
// Encode a relay URL
const nrelay = nrelayEncode('wss://relay.example.com');
// Decode any bech32-encoded entity
const decoded = decode(nprofile);
console.log(decoded);
// {
// type: 'nprofile',
// data: '7f3b6c2444c526fc7b3a48b0a1e38fb6a5a4062d4a097c9e96feb3c1df2f36d0',
// relays: ['wss://relay1.example.com', 'wss://relay2.example.com']
// }
// All functions include validation
try {
 const invalidNpub = npubEncode('invalid-hex');
} catch (error) {
 console.error(error); // Error: Invalid hex string
}
### Type System
#### Event Types
The library provides a comprehensive type system for Nostr events:
```typescript
// Create an unsigned event
const unsignedEvent: UnsignedNostrEvent = {
 kind: NostrEventKind.TEXT_NOTE,
 content: "Hello Nostr!",
 tags: [],
 created_at: Math.floor(Date.now() / 1000)
};
// Sign the event
const signedEvent = await signEvent(unsignedEvent, privateKey);

Authentication (NIP-42)

// Create an auth event
const authEvent: UnsignedNostrEvent = {
 kind: NostrEventKind.AUTH,
 content: "challenge-response",
 tags: [["challenge", challenge]],
 created_at: Math.floor(Date.now() / 1000)
};
// Sign and send the auth event
const signedAuthEvent = await signEvent(authEvent, privateKey);

Custom Tags (NIP-12)

// Create a filter with custom tags
const filter: NostrFilter = {
 kinds: [NostrEventKind.TEXT_NOTE],
 "#t": ["nostr", "crypto"], // Filter by custom tag
 limit: 10
};

Quick Start

Installation

npm install nostr-crypto-utils

Basic Usage

NIP-19 Encoding (Human-Readable Formats)

import { npubEncode, nsecEncode, noteEncode } from 'nostr-crypto-utils';
// Convert a hex public key to npub format
const hexPubkey = '12xyl6w6aacmqa3gmmzwrr9m3u0ldx3dwqhczuascswvew9am9q4sfg99cx';
const npub = npubEncode(hexPubkey);
console.log(npub); // npub1...
// Convert a hex private key to nsec format
const hexPrivkey = 'your-hex-private-key';
const nsec = nsecEncode(hexPrivkey);
console.log(nsec); // nsec1...
// Convert an event ID to note format
const eventId = 'your-event-id';
const note = noteEncode(eventId);
console.log(note); // note1...

Key Generation and Event Signing

import { generateKeyPair, createEvent, signEvent } from 'nostr-crypto-utils';
// Generate a new key pair
const keyPair = generateKeyPair();
console.log(keyPair.publicKey, keyPair.privateKey);
// Create and sign an event
const event = createEvent({
 pubkey: keyPair.publicKey,
 kind: 1,
 content: 'Hello Nostr!'
});
const signedEvent = signEvent(event, keyPair.privateKey);

Schnorr Signature Examples

Basic Message Signing

import { schnorrSign, schnorrVerify } from 'nostr-crypto-utils';
// Sign a message
const message = 'Hello Nostr!';
const privateKey = 'your-private-key';
const signature = await schnorrSign(message, privateKey);
// Verify the signature
const publicKey = 'corresponding-public-key';
const isValid = await schnorrVerify(signature, message, publicKey);
console.log('Signature valid:', isValid); // true

Delegation Token Example (NIP-26)

import { schnorrSign } from 'nostr-crypto-utils';
// Create a delegation token
const delegateePubkey = 'delegatee-public-key';
const delegatorPrivkey = 'delegator-private-key';
const conditions = {
 kind: 1, // Only allow text notes
 until: Math.floor(Date.now() / 1000) + 86400 // 24 hours from now
};
// Format conditions string
const conditionsString = Object.entries(conditions)
 .map(([key, value]) => `${key}=${value}`)
 .sort()
 .join('&');
// Create and sign the delegation message
const message = `nostr:delegation:${delegateePubkey}:${conditionsString}`;
const token = await schnorrSign(message, delegatorPrivkey);

Encrypted Direct Messages (NIP-04)

import { encryptMessage, decryptMessage } from 'nostr-crypto-utils';
// Encrypting a direct message
async function createEncryptedDM(
 content: string,
 recipientPubkey: string,
 senderPrivkey: string
) {
 try {
 const encryptedContent = await encryptMessage(
 content, 
 recipientPubkey, 
 senderPrivkey
 );
 
 return {
 kind: 4, // NIP-04 Encrypted Direct Message
 content: encryptedContent,
 tags: [['p', recipientPubkey]]
 };
 } catch (error) {
 throw new Error(`Failed to create encrypted DM: ${error}`);
 }
}
// Decrypting a received message
async function decryptDM(
 encryptedContent: string,
 senderPubkey: string,
 recipientPrivkey: string
) {
 try {
 const decryptedContent = await decryptMessage(
 encryptedContent,
 senderPubkey,
 recipientPrivkey
 );
 return decryptedContent;
 } catch (error) {
 throw new Error(`Failed to decrypt DM: ${error}`);
 }
}

Event Validation and Signature Verification

import { validateEvent, verifySignature } from 'nostr-crypto-utils';
import type { NostrEvent, SignedNostrEvent } from './types';
async function validateSignedMessage(event: NostrEvent): Promise<boolean> {
 try {
 // First validate the event structure
 if (!validateEvent(event)) {
 console.debug('Invalid event format');
 return false;
 }
 // Then verify the signature
 const isValid = await verifySignature(event as SignedNostrEvent);
 if (!isValid) {
 console.debug('Invalid signature');
 return false;
 }
 return true;
 } catch (error) {
 console.error('Error validating signed message:', error);
 return false;
 }
}

NIP-26 Features

Features and Capabilities

Integration with nostr-nsec-seedphrase

import { generateSeedPhrase } from '@humanjavaenterprises/nostr-nsec-seedphrase';
import { createTextNoteEvent, signEvent } from '@humanjavaenterprises/nostr-crypto-utils';
// Generate keys using nostr-nsec-seedphrase
const seedPhrase = generateSeedPhrase();
const keyPair = seedPhraseToKeyPair(seedPhrase);
// Use nostr-crypto-utils for event creation and signing
const event = createTextNoteEvent({
 content: 'Hello Nostr!',
 pubkey: keyPair.publicKey,
 created_at: Math.floor(Date.now() / 1000)
});
const signedEvent = signEvent(event, keyPair.privateKey);

Delegate Token Creation (NIP-26)

Basic Delegation Example

import { createDelegation, validateDelegation } from '@humanjavaenterprises/nostr-crypto-utils';
// Create a delegation token (delegator's perspective)
const delegatorKeyPair = await generateKeyPair();
const delegateePubkey = 'npub1...'; // The public key you're delegating to
const delegation = await createDelegation({
 delegatorPrivkey: delegatorKeyPair.privateKey,
 delegateePubkey,
 conditions: {
 kind: 1, // Only allow text notes
 until: Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60 // 30 days
 }
});
// Validate a delegation token (delegatee's perspective)
const isValid = await validateDelegation({
 token: delegation.token,
 delegatorPubkey: delegatorKeyPair.publicKey,
 delegateePubkey,
 kind: 1
});

Web Server Example

import { createEvent, signEventWithDelegation } from '@humanjavaenterprises/nostr-crypto-utils';
// On your server, store these securely
const DELEGATE_PRIVKEY = 'nsec1...'; // Your server's private key
const DELEGATION_TOKEN = 'nostr:delegation:...'; // Token from the delegator
const DELEGATOR_PUBKEY = 'npub1...'; // Delegator's public key
// Create and sign an event on behalf of the delegator
const event = await createEvent({
 kind: 1,
 content: 'Posted via delegation!',
 pubkey: DELEGATOR_PUBKEY, // Original delegator's pubkey
 created_at: Math.floor(Date.now() / 1000)
});
const signedEvent = await signEventWithDelegation({
 event,
 delegatePrivkey: DELEGATE_PRIVKEY,
 delegation: {
 token: DELEGATION_TOKEN,
 conditions: {
 kind: 1,
 until: Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60
 }
 }
});

Conditional Delegation

// Create a delegation with multiple conditions
const delegation = await createDelegation({
 delegatorPrivkey: delegatorKeyPair.privateKey,
 delegateePubkey,
 conditions: {
 kinds: [1, 6], // Allow only text notes and reposts
 until: Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60, // 1 week
 since: Math.floor(Date.now() / 1000), // Starting from now
 tags: [
 ['t', 'nostr'], // Only allow posts with tag 't' = 'nostr'
 ['p', delegateePubkey] // Only allow mentions of the delegatee
 ]
 }
});

Security Considerations

Type System Improvements

Enhanced Type System

Improved Type Documentation

Debug Mode

import { setDebugLevel } from '@humanjavaenterprises/nostr-crypto-utils';
// Enable debug logging
setDebugLevel('debug');
// Or for even more detail
setDebugLevel('trace');

Common Error Messages

Validation Checks

Key Formats

Time Constraints

Permission Scope

Network Issues

Testing Tools

// Test delegation validity
const testDelegation = async (delegation) => {
 const result = await validateDelegation({
 token: delegation.token,
 delegatorPubkey: delegation.delegator,
 delegateePubkey: delegation.delegatee,
 kind: 1
 });
 
 console.log('Delegation valid:', result.isValid);
 if (!result.isValid) {
 console.error('Validation error:', result.error);
 }
 
 return result;
};
// Test event signing
const testEventSigning = async (event, delegation) => {
 try {
 const signed = await signEventWithDelegation({
 event,
 delegatePrivkey: delegation.privateKey,
 delegation: delegation.token
 });
 console.log('Event signed successfully:', signed.id);
 return true;
 } catch (error) {
 console.error('Signing failed:', error);
 return false;
 }
};

Installation

npm install @humanjavaenterprises/nostr-crypto-utils

Quick Start

import { createKeyPair, createTextNoteEvent, signEvent } from '@humanjavaenterprises/nostr-crypto-utils';
// Generate a new key pair
const keyPair = createKeyPair();
// Create a text note event
const event = createTextNoteEvent({
 content: 'Hello Nostr!',
 pubkey: keyPair.publicKey,
 created_at: Math.floor(Date.now() / 1000)
});
// Sign the event
const signedEvent = signEvent(event, keyPair.privateKey);

Documentation

Type Safety

import { NostrEvent, NostrFilter, ValidationResult } from '@humanjavaenterprises/nostr-crypto-utils';
// All types are properly defined
const filter: NostrFilter = {
 kinds: [NostrEventKind.TEXT_NOTE],
 "#t": ["nostr", "crypto"], // Filter by custom tag
 limit: 10
};
// Validation results include type information
const result: ValidationResult = validateEvent(event);

Contributing

License

Changelog

v0.3.0 (2024年12月28日)

v0.2.0 (2024年12月26日)

Support

Related Projects