nostr-websocket-utils 0.2.4 → 0.3.0

package/dist/nips/nip-01.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file NIP-01: Basic protocol flow implementation
+ * @module nips/nip-01
+ */
+import type { NostrWSMessage } from '../types/messages';
+interface NostrEventValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validates a message according to NIP-01 specifications
+ */
+export declare function validateMessage(message: NostrWSMessage): boolean;
+/**
+ * Creates an EVENT message
+ */
+export declare function createEventMessage(event: Record<string, unknown>): NostrWSMessage;
+/**
+ * Creates a REQ message
+ */
+export declare function createReqMessage(subscriptionId: string, filters: Array<Record<string, unknown>>): NostrWSMessage;
+/**
+ * Creates a CLOSE message
+ */
+export declare function createCloseMessage(subscriptionId: string): NostrWSMessage;
+/**
+ * Creates a NOTICE message
+ */
+export declare function createNoticeMessage(message: string): NostrWSMessage;
+/**
+ * Validates a Nostr event according to NIP-01
+ */
+export declare function validateEvent(event: unknown): NostrEventValidationResult;
+export {};

package/dist/nips/nip-01.js

@@ -0,0 +1,145 @@
+/**
+ * @file NIP-01: Basic protocol flow implementation
+ * @module nips/nip-01
+ */
+import { getLogger } from '../utils/logger';
+import { MESSAGE_TYPES } from '../types/messages';
+const logger = getLogger('NIP-01');
+/**
+ * Validates a message according to NIP-01 specifications
+ */
+export function validateMessage(message) {
+    if (!message || typeof message !== 'object') {
+        logger.debug('Invalid message format');
+        return false;
+    }
+    if (!message.type || !Object.values(MESSAGE_TYPES).includes(message.type)) {
+        logger.debug(`Invalid message type: ${message.type}`);
+        return false;
+    }
+    if (!message.data || typeof message.data !== 'object') {
+        logger.debug('Invalid message data');
+        return false;
+    }
+    // Message type specific validation
+    if (message.type === MESSAGE_TYPES.EVENT) {
+        if (!validateEvent(message.data).valid) {
+            return false;
+        }
+    }
+    if (message.type === MESSAGE_TYPES.REQ) {
+        if (!validateReqMessage(message)) {
+            return false;
+        }
+    }
+    if (message.type === MESSAGE_TYPES.CLOSE) {
+        if (!validateCloseMessage(message)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Creates an EVENT message
+ */
+export function createEventMessage(event) {
+    return {
+        type: MESSAGE_TYPES.EVENT,
+        data: event
+    };
+}
+/**
+ * Creates a REQ message
+ */
+export function createReqMessage(subscriptionId, filters) {
+    return {
+        type: MESSAGE_TYPES.REQ,
+        data: {
+            subscription_id: subscriptionId,
+            filters
+        }
+    };
+}
+/**
+ * Creates a CLOSE message
+ */
+export function createCloseMessage(subscriptionId) {
+    return {
+        type: MESSAGE_TYPES.CLOSE,
+        data: {
+            subscription_id: subscriptionId
+        }
+    };
+}
+/**
+ * Creates a NOTICE message
+ */
+export function createNoticeMessage(message) {
+    return {
+        type: MESSAGE_TYPES.NOTICE,
+        data: {
+            message
+        }
+    };
+}
+/**
+ * Validates a Nostr event according to NIP-01
+ */
+export function validateEvent(event) {
+    if (typeof event !== 'object' || !event) {
+        return { valid: false, error: 'Event must be an object' };
+    }
+    const typedEvent = event;
+    if (!typedEvent.id || typeof typedEvent.id !== 'string') {
+        return { valid: false, error: 'Event must have a string id' };
+    }
+    if (!typedEvent.pubkey || typeof typedEvent.pubkey !== 'string') {
+        return { valid: false, error: 'Event must have a string pubkey' };
+    }
+    if (!typedEvent.created_at || typeof typedEvent.created_at !== 'number') {
+        return { valid: false, error: 'Event must have a number created_at' };
+    }
+    if (!typedEvent.kind || typeof typedEvent.kind !== 'number') {
+        return { valid: false, error: 'Event must have a number kind' };
+    }
+    if (!Array.isArray(typedEvent.tags)) {
+        return { valid: false, error: 'Event must have an array of tags' };
+    }
+    if (!typedEvent.content || typeof typedEvent.content !== 'string') {
+        return { valid: false, error: 'Event must have a string content' };
+    }
+    if (!typedEvent.sig || typeof typedEvent.sig !== 'string') {
+        return { valid: false, error: 'Event must have a string sig' };
+    }
+    // Validate tag structure
+    for (const tag of typedEvent.tags) {
+        if (!Array.isArray(tag) || tag.length === 0) {
+            return { valid: false, error: 'Each tag must be a non-empty array' };
+        }
+        if (typeof tag[0] !== 'string') {
+            return { valid: false, error: 'Tag identifier must be a string' };
+        }
+    }
+    return { valid: true };
+}
+// Private helper functions
+function validateReqMessage(message) {
+    const { subscription_id, filters } = message.data;
+    if (!subscription_id || typeof subscription_id !== 'string') {
+        logger.debug('Invalid subscription_id');
+        return false;
+    }
+    if (!Array.isArray(filters)) {
+        logger.debug('Invalid filters format');
+        return false;
+    }
+    return true;
+}
+function validateCloseMessage(message) {
+    const { subscription_id } = message.data;
+    if (!subscription_id || typeof subscription_id !== 'string') {
+        logger.debug('Invalid subscription_id');
+        return false;
+    }
+    return true;
+}

package/dist/nips/nip-02.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @file NIP-02: Contact List and Petnames
+ * @module nips/nip-02
+ * @see https://github.com/nostr-protocol/nips/blob/master/02.md
+ */
+import type { NostrWSMessage } from '../types/messages';
+import type { Logger } from '../types/logger';
+/**
+ * Contact list event kind
+ */
+export declare const CONTACT_LIST_KIND = 3;
+/**
+ * Contact entry structure
+ */
+export interface Contact {
+    pubkey: string;
+    relay?: string;
+    petname?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Creates a contact list event
+ * @param contacts - List of contacts
+ * @param metadata - Optional metadata for the contact list
+ * @returns {NostrWSMessage} Contact list event
+ */
+export declare function createContactListEvent(contacts: Contact[], metadata?: Record<string, unknown>): NostrWSMessage;
+/**
+ * Extracts contacts from a contact list event
+ * @param message - Contact list message
+ * @param _logger - Logger instance
+ * @returns {Contact[]} Array of contacts
+ */
+export declare function extractContacts(message: NostrWSMessage, _logger: Logger): Contact[];
+/**
+ * Creates a contact list subscription message
+ * @param pubkey - Public key to subscribe to
+ * @returns {NostrWSMessage} Subscription message
+ */
+export declare function createContactListSubscription(pubkey: string): NostrWSMessage;
+/**
+ * Contact list manager interface
+ */
+export interface ContactListManager {
+    /**
+     * Adds or updates a contact
+     * @param contact - Contact to add/update
+     */
+    addContact(contact: Contact): void;
+    /**
+     * Removes a contact
+     * @param pubkey - Public key of contact to remove
+     */
+    removeContact(pubkey: string): void;
+    /**
+     * Gets a contact by public key
+     * @param pubkey - Public key to look up
+     * @returns {Contact | undefined} Contact if found
+     */
+    getContact(pubkey: string): Contact | undefined;
+    /**
+     * Gets all contacts
+     * @returns {Contact[]} Array of all contacts
+     */
+    getAllContacts(): Contact[];
+    /**
+     * Updates contact metadata
+     * @param pubkey - Public key of contact
+     * @param metadata - New metadata
+     */
+    updateContactMetadata(pubkey: string, metadata: Record<string, unknown>): void;
+    /**
+     * Creates a contact list event
+     * @returns {NostrWSMessage} Contact list event
+     */
+    createEvent(): NostrWSMessage;
+}
+/**
+ * Creates a contact list manager
+ * @param _logger - Logger instance
+ * @returns {ContactListManager} Contact list manager
+ */
+export declare function createContactListManager(_logger: Logger): ContactListManager;

package/dist/nips/nip-02.js

@@ -0,0 +1,123 @@
+/**
+ * @file NIP-02: Contact List and Petnames
+ * @module nips/nip-02
+ * @see https://github.com/nostr-protocol/nips/blob/master/02.md
+ */
+/**
+ * Contact list event kind
+ */
+export const CONTACT_LIST_KIND = 3;
+/**
+ * Creates a contact list event
+ * @param contacts - List of contacts
+ * @param metadata - Optional metadata for the contact list
+ * @returns {NostrWSMessage} Contact list event
+ */
+export function createContactListEvent(contacts, metadata = {}) {
+    const tags = contacts.map(contact => {
+        const tag = ['p', contact.pubkey];
+        if (contact.relay)
+            tag.push(contact.relay);
+        if (contact.petname)
+            tag.push(contact.petname);
+        return tag;
+    });
+    return {
+        type: 'EVENT',
+        data: {
+            kind: CONTACT_LIST_KIND,
+            tags,
+            content: JSON.stringify(metadata)
+        }
+    };
+}
+/**
+ * Extracts contacts from a contact list event
+ * @param message - Contact list message
+ * @param _logger - Logger instance
+ * @returns {Contact[]} Array of contacts
+ */
+export function extractContacts(message, _logger) {
+    try {
+        if (message.type !== 'EVENT' || !message.data) {
+            return [];
+        }
+        const event = message.data;
+        if (event.kind !== CONTACT_LIST_KIND || !Array.isArray(event.tags)) {
+            return [];
+        }
+        let metadata = {};
+        try {
+            metadata = JSON.parse(event.content);
+        }
+        catch (error) {
+            _logger.debug('Failed to parse contact list metadata');
+        }
+        return event.tags
+            .filter(tag => Array.isArray(tag) && tag[0] === 'p' && tag[1])
+            .map(tag => ({
+            pubkey: tag[1],
+            relay: tag[2],
+            petname: tag[3],
+            metadata
+        }));
+    }
+    catch (error) {
+        _logger.error('Error extracting contacts:', error);
+        return [];
+    }
+}
+/**
+ * Creates a contact list subscription message
+ * @param pubkey - Public key to subscribe to
+ * @returns {NostrWSMessage} Subscription message
+ */
+export function createContactListSubscription(pubkey) {
+    return {
+        type: 'REQ',
+        data: {
+            filter: {
+                authors: [pubkey],
+                kinds: [CONTACT_LIST_KIND],
+                limit: 1
+            }
+        }
+    };
+}
+/**
+ * Creates a contact list manager
+ * @param _logger - Logger instance
+ * @returns {ContactListManager} Contact list manager
+ */
+export function createContactListManager(_logger) {
+    const contacts = new Map();
+    return {
+        addContact(contact) {
+            contacts.set(contact.pubkey, contact);
+        },
+        removeContact(pubkey) {
+            contacts.delete(pubkey);
+        },
+        getContact(pubkey) {
+            return contacts.get(pubkey);
+        },
+        getAllContacts() {
+            return Array.from(contacts.values());
+        },
+        updateContactMetadata(pubkey, metadata) {
+            const contact = contacts.get(pubkey);
+            if (contact) {
+                contacts.set(pubkey, {
+                    ...contact,
+                    metadata: {
+                        ...contact.metadata,
+                        ...metadata
+                    }
+                });
+            }
+        },
+        createEvent() {
+            return createContactListEvent(Array.from(contacts.values()));
+        }
+    };
+}

package/dist/nips/nip-04.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file NIP-04: Encrypted Direct Message Support
+ * @module nips/nip-04
+ * @see https://github.com/nostr-protocol/nips/blob/master/04.md
+ */
+import type { NostrWSMessage } from '../types/messages';
+import type { Logger } from '../types/logger';
+/**
+ * Kind value for encrypted direct messages
+ */
+export declare const ENCRYPTED_DM_KIND = 4;
+/**
+ * Creates an encrypted direct message event
+ * @param content - Message content to encrypt
+ * @param recipientPubkey - Recipient's public key
+ * @param senderPrivkey - Sender's private key
+ * @param tags - Additional tags for the event
+ * @returns {Promise<NostrWSMessage>} Encrypted message event
+ */
+export declare function createEncryptedDM(content: string, recipientPubkey: string, senderPrivkey: string, tags?: string[][]): Promise<NostrWSMessage>;
+/**
+ * Decrypts a received direct message event
+ * @param message - Received message
+ * @param recipientPrivkey - Recipient's private key
+ * @param senderPubkey - Sender's public key
+ * @param logger - Logger instance
+ * @returns {Promise<string>} Decrypted message content
+ */
+export declare function decryptDM(message: NostrWSMessage, recipientPrivkey: string, senderPubkey: string, logger: Logger): Promise<string>;
+/**
+ * Validates an encrypted DM event format
+ * @param message - Message to validate
+ * @param logger - Logger instance
+ * @returns {boolean} True if message follows NIP-04 format
+ */
+export declare function validateEncryptedDM(message: NostrWSMessage, logger: Logger): boolean;

package/dist/nips/nip-04.js

@@ -0,0 +1,105 @@
+/**
+ * @file NIP-04: Encrypted Direct Message Support
+ * @module nips/nip-04
+ * @see https://github.com/nostr-protocol/nips/blob/master/04.md
+ */
+import { encryptMessage, decryptMessage } from 'nostr-crypto-utils';
+/**
+ * Kind value for encrypted direct messages
+ */
+export const ENCRYPTED_DM_KIND = 4;
+/**
+ * Creates an encrypted direct message event
+ * @param content - Message content to encrypt
+ * @param recipientPubkey - Recipient's public key
+ * @param senderPrivkey - Sender's private key
+ * @param tags - Additional tags for the event
+ * @returns {Promise<NostrWSMessage>} Encrypted message event
+ */
+export async function createEncryptedDM(content, recipientPubkey, senderPrivkey, tags = []) {
+    try {
+        const encryptedContent = await encryptMessage(content, recipientPubkey, senderPrivkey);
+        return {
+            type: 'EVENT',
+            data: {
+                kind: ENCRYPTED_DM_KIND,
+                content: encryptedContent,
+                tags: [
+                    ['p', recipientPubkey],
+                    ...tags
+                ]
+            }
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        throw new Error(`Failed to create encrypted DM: ${errorMessage}`);
+    }
+}
+/**
+ * Decrypts a received direct message event
+ * @param message - Received message
+ * @param recipientPrivkey - Recipient's private key
+ * @param senderPubkey - Sender's public key
+ * @param logger - Logger instance
+ * @returns {Promise<string>} Decrypted message content
+ */
+export async function decryptDM(message, recipientPrivkey, senderPubkey, logger) {
+    try {
+        if (message.type !== 'EVENT' || !message.data) {
+            throw new Error('Invalid message format');
+        }
+        const event = message.data;
+        if (event.kind !== ENCRYPTED_DM_KIND) {
+            throw new Error('Not an encrypted DM event');
+        }
+        const content = event.content;
+        if (!content) {
+            throw new Error('No encrypted content found');
+        }
+        return await decryptMessage(content, senderPubkey, recipientPrivkey);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Failed to decrypt DM: ${errorMessage}`);
+        throw new Error(errorMessage);
+    }
+}
+/**
+ * Validates an encrypted DM event format
+ * @param message - Message to validate
+ * @param logger - Logger instance
+ * @returns {boolean} True if message follows NIP-04 format
+ */
+export function validateEncryptedDM(message, logger) {
+    try {
+        if (message.type !== 'EVENT' || !message.data) {
+            logger.debug('Not an event message');
+            return false;
+        }
+        const event = message.data;
+        if (event.kind !== ENCRYPTED_DM_KIND) {
+            logger.debug('Not an encrypted DM event');
+            return false;
+        }
+        if (!event.content || typeof event.content !== 'string') {
+            logger.debug('Invalid or missing content');
+            return false;
+        }
+        if (!Array.isArray(event.tags)) {
+            logger.debug('Missing tags array');
+            return false;
+        }
+        const pTag = event.tags.find(tag => Array.isArray(tag) && tag[0] === 'p' && tag[1]);
+        if (!pTag) {
+            logger.debug('Missing recipient pubkey tag');
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Error validating encrypted DM: ${errorMessage}`);
+        return false;
+    }
+}

package/dist/nips/nip-05.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @file NIP-05: DNS-Based Verification
+ * @module nips/nip-05
+ * @see https://github.com/nostr-protocol/nips/blob/master/05.md
+ */
+/**
+ * NIP-05 verification result
+ */
+export interface NIP05VerificationResult {
+    valid: boolean;
+    pubkey?: string;
+    relays?: string[];
+    error?: string;
+}
+/**
+ * Verifies a NIP-05 identifier
+ * @param identifier - Internet identifier (user@domain.com)
+ * @param pubkey - Public key to verify
+ * @param logger - Logger instance
+ * @returns {Promise<NIP05VerificationResult>} Verification result
+ */
+export declare function verifyNIP05Identifier(identifier: string, pubkey: string, logger: any): Promise<NIP05VerificationResult>;
+/**
+ * Creates metadata event with NIP-05 identifier
+ * @param identifier - Internet identifier
+ * @param metadata - Additional metadata
+ * @returns {Record<string, unknown>} Metadata event content
+ */
+export declare function createNIP05Metadata(identifier: string, metadata?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * NIP-05 verification cache interface
+ */
+export interface NIP05VerificationCache {
+    /**
+     * Gets cached verification result
+     * @param identifier - Internet identifier
+     * @param pubkey - Public key
+     * @returns {NIP05VerificationResult | undefined} Cached result
+     */
+    get(identifier: string, pubkey: string): NIP05VerificationResult | undefined;
+    /**
+     * Sets verification result in cache
+     * @param identifier - Internet identifier
+     * @param pubkey - Public key
+     * @param result - Verification result
+     * @param ttl - Time to live in seconds
+     */
+    set(identifier: string, pubkey: string, result: NIP05VerificationResult, ttl: number): void;
+    /**
+     * Clears expired entries
+     */
+    cleanup(): void;
+}
+/**
+ * Creates a NIP-05 verification cache
+ * @param defaultTTL - Default TTL in seconds
+ * @returns {NIP05VerificationCache} Verification cache
+ */
+export declare function createNIP05VerificationCache(defaultTTL?: number): NIP05VerificationCache;
+/**
+ * Batch verification interface for multiple identifiers
+ */
+export interface NIP05BatchVerifier {
+    /**
+     * Adds identifier to verification queue
+     * @param identifier - Internet identifier
+     * @param pubkey - Public key
+     */
+    addToQueue(identifier: string, pubkey: string): void;
+    /**
+     * Verifies all queued identifiers
+     * @returns {Promise<Map<string, NIP05VerificationResult>>} Verification results
+     */
+    verifyAll(): Promise<Map<string, NIP05VerificationResult>>;
+    /**
+     * Clears verification queue
+     */
+    clearQueue(): void;
+}
+/**
+ * Creates a NIP-05 batch verifier
+ * @param logger - Logger instance
+ * @param cache - Optional verification cache
+ * @returns {NIP05BatchVerifier} Batch verifier
+ */
+export declare function createNIP05BatchVerifier(logger: any, cache?: NIP05VerificationCache): NIP05BatchVerifier;