nostr-websocket-utils 0.2.4 → 0.3.0

package/dist/nips/nip-05.js

@@ -0,0 +1,151 @@
+/**
+ * @file NIP-05: DNS-Based Verification
+ * @module nips/nip-05
+ * @see https://github.com/nostr-protocol/nips/blob/master/05.md
+ */
+import { fetchJson } from '../utils/http';
+/**
+ * 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 async function verifyNIP05Identifier(identifier, pubkey, logger) {
+    try {
+        // Parse identifier
+        const [name, domain] = identifier.split('@');
+        if (!name || !domain) {
+            return {
+                valid: false,
+                error: 'Invalid identifier format'
+            };
+        }
+        // Fetch well-known URL
+        const url = `https://${domain}/.well-known/nostr.json?name=${name}`;
+        const response = await fetchJson(url);
+        if (!response || !response.names || !response.names[name]) {
+            return {
+                valid: false,
+                error: 'Name not found in well-known file'
+            };
+        }
+        // Verify name matches pubkey
+        const verifiedPubkey = response.names[name];
+        if (!verifiedPubkey) {
+            return {
+                valid: false,
+                error: 'Name not found'
+            };
+        }
+        if (verifiedPubkey !== pubkey) {
+            return {
+                valid: false,
+                error: 'Public key mismatch'
+            };
+        }
+        // Get associated relays if available
+        const relays = response.relays?.[verifiedPubkey];
+        return {
+            valid: true,
+            pubkey: verifiedPubkey,
+            relays
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`NIP-05 verification failed: ${errorMessage}`);
+        return {
+            valid: false,
+            error: errorMessage
+        };
+    }
+}
+/**
+ * Creates metadata event with NIP-05 identifier
+ * @param identifier - Internet identifier
+ * @param metadata - Additional metadata
+ * @returns {Record<string, unknown>} Metadata event content
+ */
+export function createNIP05Metadata(identifier, metadata = {}) {
+    return {
+        ...metadata,
+        nip05: identifier
+    };
+}
+/**
+ * Creates a NIP-05 verification cache
+ * @param defaultTTL - Default TTL in seconds
+ * @returns {NIP05VerificationCache} Verification cache
+ */
+export function createNIP05VerificationCache(defaultTTL = 3600) {
+    const cache = new Map();
+    function getCacheKey(identifier, pubkey) {
+        return `${identifier}:${pubkey}`;
+    }
+    return {
+        get(identifier, pubkey) {
+            const key = getCacheKey(identifier, pubkey);
+            const entry = cache.get(key);
+            if (!entry)
+                return undefined;
+            if (Date.now() > entry.expiresAt) {
+                cache.delete(key);
+                return undefined;
+            }
+            return entry.result;
+        },
+        set(identifier, pubkey, result, ttl = defaultTTL) {
+            const key = getCacheKey(identifier, pubkey);
+            cache.set(key, {
+                result,
+                expiresAt: Date.now() + (ttl * 1000)
+            });
+        },
+        cleanup() {
+            const now = Date.now();
+            for (const [key, entry] of cache.entries()) {
+                if (now > entry.expiresAt) {
+                    cache.delete(key);
+                }
+            }
+        }
+    };
+}
+/**
+ * Creates a NIP-05 batch verifier
+ * @param logger - Logger instance
+ * @param cache - Optional verification cache
+ * @returns {NIP05BatchVerifier} Batch verifier
+ */
+export function createNIP05BatchVerifier(logger, cache) {
+    const queue = new Map();
+    return {
+        addToQueue(identifier, pubkey) {
+            queue.set(identifier, pubkey);
+        },
+        async verifyAll() {
+            const results = new Map();
+            for (const [identifier, pubkey] of queue.entries()) {
+                // Check cache first
+                if (cache) {
+                    const cached = cache.get(identifier, pubkey);
+                    if (cached) {
+                        results.set(identifier, cached);
+                        continue;
+                    }
+                }
+                // Verify and cache result
+                const result = await verifyNIP05Identifier(identifier, pubkey, logger);
+                results.set(identifier, result);
+                if (cache) {
+                    cache.set(identifier, pubkey, result, 3600);
+                }
+            }
+            return results;
+        },
+        clearQueue() {
+            queue.clear();
+        }
+    };
+}

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

@@ -0,0 +1,92 @@
+/**
+ * @file NIP-09: Event Deletion
+ * @module nips/nip-09
+ * @see https://github.com/nostr-protocol/nips/blob/master/09.md
+ */
+import type { NostrEvent, NostrSubscriptionEvent } from '../types/events';
+/**
+ * Represents the result of a deletion operation
+ * @interface DeletionResult
+ * @property {boolean} success - Whether the deletion operation was successful
+ * @property {string} [error] - Error message if the operation failed
+ * @property {string[]} [deletedIds] - Array of successfully deleted event IDs
+ */
+interface DeletionResult {
+    success: boolean;
+    error?: string;
+    deletedIds?: string[];
+}
+/**
+ * Event deletion kind
+ */
+export declare const EVENT_DELETION_KIND = 5;
+/**
+ * Creates a deletion event
+ */
+export declare function createDeletionEvent(eventIds: string[], reason?: string): Omit<NostrEvent, 'id' | 'sig'>;
+/**
+ * Validates a deletion event
+ */
+export declare function validateDeletionEvent(event: NostrEvent): boolean;
+/**
+ * Processes a deletion event
+ */
+export declare function processDeletionEvent(event: NostrEvent, _logger: any, deleteEvent: (id: string) => Promise<boolean>): Promise<DeletionResult>;
+/**
+ * Event deletion manager interface
+ */
+export interface EventDeletionManager {
+    /**
+     * Processes a deletion event
+     * @param message - Deletion message
+     * @returns {Promise<string[]>} Deleted event IDs
+     */
+    processDeletion(message: NostrEvent): Promise<string[]>;
+    /**
+     * Checks if an event has been deleted
+     * @param eventId - Event ID to check
+     * @returns {boolean} True if event is deleted
+     */
+    isDeleted(eventId: string): boolean;
+    /**
+     * Gets deletion reason for an event
+     * @param eventId - Event ID
+     * @returns {string | undefined} Deletion reason if available
+     */
+    getDeletionReason(eventId: string): string | undefined;
+    /**
+     * Gets all deleted events
+     * @returns {Map<string, string>} Map of event IDs to deletion reasons
+     */
+    getDeletedEvents(): Map<string, string>;
+}
+/**
+ * Creates an event deletion manager
+ * @param _logger - Logger instance
+ * @returns {EventDeletionManager} Deletion manager
+ */
+export declare function createEventDeletionManager(_logger: any): EventDeletionManager;
+/**
+ * Event deletion subscription manager interface
+ */
+export interface DeletionSubscriptionManager {
+    /**
+     * Creates a subscription for deletion events
+     * @param eventIds - Event IDs to monitor
+     * @returns {NostrSubscriptionEvent} Subscription message
+     */
+    subscribeToDeletions(eventIds: string[]): NostrSubscriptionEvent;
+    /**
+     * Creates a subscription for all deletions by a user
+     * @param pubkey - Public key of user
+     * @returns {NostrSubscriptionEvent} Subscription message
+     */
+    subscribeToUserDeletions(pubkey: string): NostrSubscriptionEvent;
+}
+/**
+ * Creates a deletion subscription manager
+ * @param _logger - Logger instance
+ * @returns {DeletionSubscriptionManager} Subscription manager
+ */
+export declare function createDeletionSubscriptionManager(_logger: any): DeletionSubscriptionManager;
+export {};

package/dist/nips/nip-09.js

@@ -0,0 +1,190 @@
+/**
+ * @file NIP-09: Event Deletion
+ * @module nips/nip-09
+ * @see https://github.com/nostr-protocol/nips/blob/master/09.md
+ */
+import { getLogger } from '../utils/logger';
+const logger = getLogger('NIP-09');
+/**
+ * Event deletion kind
+ */
+export const EVENT_DELETION_KIND = 5;
+/**
+ * Creates a deletion event
+ */
+export function createDeletionEvent(eventIds, reason) {
+    return {
+        kind: EVENT_DELETION_KIND,
+        created_at: Math.floor(Date.now() / 1000),
+        tags: eventIds.map(id => ['e', id]),
+        content: reason || '',
+        pubkey: '', // To be filled by the caller
+    };
+}
+/**
+ * Validates a deletion event
+ */
+export function validateDeletionEvent(event) {
+    try {
+        // Must be kind 5
+        if (event.kind !== EVENT_DELETION_KIND) {
+            logger.debug('Invalid event kind for deletion');
+            return false;
+        }
+        // Must have at least one e tag
+        const eventIds = event.tags
+            .filter((tag) => Array.isArray(tag) && tag[0] === 'e' && typeof tag[1] === 'string')
+            .map(tag => tag[1]);
+        if (eventIds.length === 0) {
+            logger.debug('No event IDs to delete');
+            return false;
+        }
+        // Validate each event ID format
+        const validHexString = /^[0-9a-f]{64}$/;
+        const invalidIds = eventIds.filter(id => !validHexString.test(id));
+        if (invalidIds.length > 0) {
+            logger.debug(`Invalid event IDs: ${invalidIds.join(', ')}`);
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Error validating deletion event: ${errorMessage}`);
+        return false;
+    }
+}
+/**
+ * Processes a deletion event
+ */
+export async function processDeletionEvent(event, _logger, deleteEvent) {
+    try {
+        if (!validateDeletionEvent(event)) {
+            return {
+                success: false,
+                error: 'Invalid deletion event'
+            };
+        }
+        const eventIds = event.tags
+            .filter((tag) => tag[0] === 'e')
+            .map(tag => tag[1]);
+        const deletedIds = [];
+        const failedIds = [];
+        for (const eventId of eventIds) {
+            try {
+                const success = await deleteEvent(eventId);
+                if (success) {
+                    deletedIds.push(eventId);
+                }
+                else {
+                    failedIds.push(eventId);
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                logger.error(`Failed to delete event ${eventId}: ${errorMessage}`);
+                failedIds.push(eventId);
+            }
+        }
+        if (failedIds.length > 0) {
+            return {
+                success: false,
+                error: `Failed to delete events: ${failedIds.join(', ')}`,
+                deletedIds
+            };
+        }
+        return {
+            success: true,
+            deletedIds
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Error processing deletion event: ${errorMessage}`);
+        return {
+            success: false,
+            error: errorMessage
+        };
+    }
+}
+/**
+ * Creates an event deletion manager
+ * @param _logger - Logger instance
+ * @returns {EventDeletionManager} Deletion manager
+ */
+export function createEventDeletionManager(_logger) {
+    // Map of deleted event IDs to deletion reasons
+    const deletedEvents = new Map();
+    // Map of deleted event IDs to deletion event IDs
+    const deletionEvents = new Map();
+    return {
+        async processDeletion(message) {
+            try {
+                if (!validateDeletionEvent(message)) {
+                    throw new Error('Invalid deletion event');
+                }
+                const event = message;
+                const eventIds = event.tags
+                    .filter(tag => tag[0] === 'e')
+                    .map(tag => tag[1]);
+                const reason = event.content;
+                const deletionId = event.id;
+                // Process each event ID
+                eventIds.forEach(eventId => {
+                    // Only delete if not already deleted or if this deletion is newer
+                    const existingDeletionId = deletionEvents.get(eventId);
+                    if (!existingDeletionId || deletionId > existingDeletionId) {
+                        deletedEvents.set(eventId, reason);
+                        deletionEvents.set(eventId, deletionId);
+                    }
+                });
+                logger.debug('Processed deletion event', {
+                    deletionId,
+                    eventIds,
+                    reason
+                });
+                return eventIds;
+            }
+            catch (error) {
+                logger.error('Error processing deletion event:', error);
+                return [];
+            }
+        },
+        isDeleted(eventId) {
+            return deletedEvents.has(eventId);
+        },
+        getDeletionReason(eventId) {
+            return deletedEvents.get(eventId);
+        },
+        getDeletedEvents() {
+            return new Map(deletedEvents);
+        }
+    };
+}
+/**
+ * Creates a deletion subscription manager
+ * @param _logger - Logger instance
+ * @returns {DeletionSubscriptionManager} Subscription manager
+ */
+export function createDeletionSubscriptionManager(_logger) {
+    return {
+        subscribeToDeletions(eventIds) {
+            return {
+                subscriptionId: `deletion_${eventIds.join('_')}`,
+                filters: [{
+                        kinds: [EVENT_DELETION_KIND],
+                        '#e': eventIds
+                    }]
+            };
+        },
+        subscribeToUserDeletions(pubkey) {
+            return {
+                subscriptionId: `user_deletion_${pubkey}`,
+                filters: [{
+                        kinds: [EVENT_DELETION_KIND],
+                        authors: [pubkey]
+                    }]
+            };
+        }
+    };
+}

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

@@ -0,0 +1,64 @@
+/**
+ * @file NIP-11: Relay Information Document
+ * @module nips/nip-11
+ * @see https://github.com/nostr-protocol/nips/blob/master/11.md
+ */
+/**
+ * Relay information document structure
+ */
+export interface RelayInformation {
+    name?: string;
+    description?: string;
+    pubkey?: string;
+    contact?: string;
+    supported_nips?: number[];
+    software?: string;
+    version?: string;
+    limitation?: {
+        max_message_length?: number;
+        max_subscriptions?: number;
+        max_filters?: number;
+        max_limit?: number;
+        max_subid_length?: number;
+        min_prefix?: number;
+        max_event_tags?: number;
+        max_content_length?: number;
+        min_pow_difficulty?: number;
+        auth_required?: boolean;
+        payment_required?: boolean;
+    };
+}
+/**
+ * Fetches relay information document
+ * @param url - Relay URL (ws:// or wss://)
+ * @returns {Promise<RelayInformation>} Relay information
+ */
+export declare function getRelayInformation(url: string): Promise<RelayInformation>;
+/**
+ * Checks if relay meets requirements
+ * @param relay - Relay information
+ * @param requirements - Required relay features
+ * @returns {boolean} True if relay meets all requirements
+ */
+export declare function checkRelayRequirements(relay: RelayInformation, requirements: Partial<RelayInformation>): boolean;
+/**
+ * Validates relay capabilities against required features
+ * @param info - Relay information
+ * @param requiredNips - Required NIPs
+ * @param requiredFeatures - Required relay features
+ * @returns {boolean} True if relay supports all required features
+ */
+export declare function validateRelayCapabilities(info: RelayInformation, requiredNips?: number[], requiredFeatures?: Partial<RelayInformation['limitation']>): boolean;
+/**
+ * Creates a relay selection score based on capabilities
+ * @param info - Relay information
+ * @param preferences - Scoring preferences
+ * @returns {number} Relay score (higher is better)
+ */
+export declare function scoreRelayCapabilities(info: RelayInformation, preferences?: {
+    preferredNips?: number[];
+    minMessageLength?: number;
+    minSubscriptions?: number;
+    requireAuth?: boolean;
+    requirePayment?: boolean;
+}): number;

package/dist/nips/nip-11.js

@@ -0,0 +1,154 @@
+/**
+ * @file NIP-11: Relay Information Document
+ * @module nips/nip-11
+ * @see https://github.com/nostr-protocol/nips/blob/master/11.md
+ */
+import { getLogger } from '../utils/logger';
+import { fetchJson } from '../utils/http';
+const logger = getLogger('NIP-11');
+/**
+ * Fetches relay information document
+ * @param url - Relay URL (ws:// or wss://)
+ * @returns {Promise<RelayInformation>} Relay information
+ */
+export async function getRelayInformation(url) {
+    try {
+        const relayUrl = url.replace('ws://', 'http://').replace('wss://', 'https://');
+        const response = await fetchJson(`${relayUrl}/.well-known/nostr.json`);
+        return response;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Failed to fetch relay information: ${errorMessage}`);
+        throw new Error(`Failed to fetch relay information: ${errorMessage}`);
+    }
+}
+/**
+ * Checks if relay meets requirements
+ * @param relay - Relay information
+ * @param requirements - Required relay features
+ * @returns {boolean} True if relay meets all requirements
+ */
+export function checkRelayRequirements(relay, requirements) {
+    try {
+        // Check supported NIPs
+        if (requirements.supported_nips && relay.supported_nips) {
+            const missingNips = requirements.supported_nips.filter(nip => !relay.supported_nips?.includes(nip));
+            if (missingNips.length > 0) {
+                logger.debug(`Missing required NIPs: ${missingNips.join(', ')}`);
+                return false;
+            }
+        }
+        // Check limitations
+        if (requirements.limitation && relay.limitation) {
+            for (const [key, value] of Object.entries(requirements.limitation)) {
+                const relayValue = relay.limitation[key];
+                // Skip if relay doesn't specify this limitation
+                if (relayValue === undefined)
+                    continue;
+                // For maximum values, relay should support at least the required value
+                if (key.startsWith('max_') && typeof relayValue === 'number' && typeof value === 'number') {
+                    if (relayValue < value) {
+                        logger.debug(`Relay ${key} too low: ${relayValue} < ${value}`);
+                        return false;
+                    }
+                }
+                // For minimum values, relay should not require more than specified
+                if (key.startsWith('min_') && typeof relayValue === 'number' && typeof value === 'number') {
+                    if (relayValue > value) {
+                        logger.debug(`Relay ${key} too high: ${relayValue} > ${value}`);
+                        return false;
+                    }
+                }
+                // For boolean flags, values must match if specified
+                if (typeof relayValue === 'boolean' && typeof value === 'boolean') {
+                    if (relayValue !== value) {
+                        logger.debug(`Relay ${key} mismatch: ${relayValue} !== ${value}`);
+                        return false;
+                    }
+                }
+            }
+        }
+        return true;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Error checking relay requirements: ${errorMessage}`);
+        return false;
+    }
+}
+/**
+ * Validates relay capabilities against required features
+ * @param info - Relay information
+ * @param requiredNips - Required NIPs
+ * @param requiredFeatures - Required relay features
+ * @returns {boolean} True if relay supports all required features
+ */
+export function validateRelayCapabilities(info, requiredNips = [], requiredFeatures = {}) {
+    // Check NIP support
+    if (requiredNips.length > 0) {
+        if (!info.supported_nips)
+            return false;
+        if (!requiredNips.every(nip => info.supported_nips?.includes(nip))) {
+            return false;
+        }
+    }
+    // Check limitations
+    if (info.limitation) {
+        for (const [key, value] of Object.entries(requiredFeatures)) {
+            const relayValue = info.limitation[key];
+            if (relayValue === undefined)
+                return false;
+            // For maximum values, relay limit should be higher
+            if (key.startsWith('max_') && typeof relayValue === 'number' && typeof value === 'number') {
+                if (relayValue < value)
+                    return false;
+            }
+            // For minimum values, relay limit should be lower
+            if (key.startsWith('min_') && typeof relayValue === 'number' && typeof value === 'number') {
+                if (relayValue > value)
+                    return false;
+            }
+            // For boolean flags, must match exactly
+            if (typeof relayValue === 'boolean' && typeof value === 'boolean') {
+                if (relayValue !== value)
+                    return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Creates a relay selection score based on capabilities
+ * @param info - Relay information
+ * @param preferences - Scoring preferences
+ * @returns {number} Relay score (higher is better)
+ */
+export function scoreRelayCapabilities(info, preferences = {}) {
+    let score = 0;
+    // Score NIP support
+    if (info.supported_nips && preferences.preferredNips) {
+        score += preferences.preferredNips.filter(nip => info.supported_nips?.includes(nip)).length * 10;
+    }
+    // Score limitations
+    if (info.limitation) {
+        const limits = info.limitation;
+        // Message length
+        if (limits.max_message_length && preferences.minMessageLength) {
+            score += limits.max_message_length >= preferences.minMessageLength ? 5 : -5;
+        }
+        // Subscriptions
+        if (limits.max_subscriptions && preferences.minSubscriptions) {
+            score += limits.max_subscriptions >= preferences.minSubscriptions ? 5 : -5;
+        }
+        // Auth requirements
+        if (preferences.requireAuth !== undefined) {
+            score += (limits.auth_required === preferences.requireAuth) ? 5 : -10;
+        }
+        // Payment requirements
+        if (preferences.requirePayment !== undefined) {
+            score += (limits.payment_required === preferences.requirePayment) ? 5 : -10;
+        }
+    }
+    return score;
+}