nostr-websocket-utils 0.2.4 → 0.3.0

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

@@ -0,0 +1,73 @@
+/**
+ * @file NIP-13: Proof of Work
+ * @module nips/nip-13
+ * @see https://github.com/nostr-protocol/nips/blob/master/13.md
+ */
+import type { NostrWSMessage } from '../types/messages';
+import type { Logger } from '../types/logger';
+/**
+ * Calculates the number of leading zero bits in a hex string
+ * @param hex - Hex string to check
+ * @returns {number} Number of leading zero bits
+ */
+export declare function countLeadingZeroBits(hex: string): number;
+/**
+ * Calculates event ID with proof of work
+ * @param event - Event object without ID
+ * @param targetDifficulty - Target number of leading zero bits
+ * @param maxAttempts - Maximum number of attempts
+ * @returns {Promise<string>} Event ID with sufficient proof of work
+ */
+export declare function calculatePowEventId(event: Record<string, unknown>, targetDifficulty: number, maxAttempts?: number): Promise<string>;
+/**
+ * Validates proof of work for an event
+ * @param message - Message containing event
+ * @param minDifficulty - Minimum required difficulty
+ * @param logger - Logger instance
+ * @returns {boolean} True if proof of work is valid
+ */
+export declare function validateEventPoW(message: NostrWSMessage, minDifficulty: number, logger: Logger): boolean;
+/**
+ * Dynamic difficulty calculator based on event type and content
+ */
+export interface DifficultyCalculator {
+    /**
+     * Calculates required difficulty for an event
+     * @param event - Event to check
+     * @returns {number} Required number of leading zero bits
+     */
+    calculateRequiredDifficulty(event: Record<string, unknown>): number;
+}
+/**
+ * Creates a default difficulty calculator
+ * @param baseDifficulty - Base difficulty for all events
+ * @param contentMultiplier - Multiplier based on content length
+ * @returns {DifficultyCalculator} Difficulty calculator
+ */
+export declare function createDifficultyCalculator(baseDifficulty?: number, contentMultiplier?: number): DifficultyCalculator;
+/**
+ * Rate limiter interface for proof of work
+ */
+export interface PowRateLimiter {
+    /**
+     * Checks if an event should be rate limited
+     * @param pubkey - Publisher's public key
+     * @param currentTime - Current timestamp
+     * @returns {boolean} True if should be rate limited
+     */
+    shouldRateLimit(pubkey: string, currentTime: number): boolean;
+    /**
+     * Records an event for rate limiting
+     * @param pubkey - Publisher's public key
+     * @param difficulty - Event difficulty
+     * @param currentTime - Current timestamp
+     */
+    recordEvent(pubkey: string, difficulty: number, currentTime: number): void;
+}
+/**
+ * Creates a default PoW rate limiter
+ * @param windowSeconds - Time window for rate limiting
+ * @param maxDifficulty - Maximum cumulative difficulty per window
+ * @returns {PowRateLimiter} Rate limiter
+ */
+export declare function createPowRateLimiter(windowSeconds?: number, maxDifficulty?: number): PowRateLimiter;

package/dist/nips/nip-13.js

@@ -0,0 +1,128 @@
+/**
+ * @file NIP-13: Proof of Work
+ * @module nips/nip-13
+ * @see https://github.com/nostr-protocol/nips/blob/master/13.md
+ */
+import { createHash } from 'crypto';
+/**
+ * Calculates the number of leading zero bits in a hex string
+ * @param hex - Hex string to check
+ * @returns {number} Number of leading zero bits
+ */
+export function countLeadingZeroBits(hex) {
+    let count = 0;
+    for (const char of hex) {
+        const nibble = parseInt(char, 16);
+        if (nibble === 0) {
+            count += 4;
+        }
+        else {
+            count += Math.clz32(nibble) - 28;
+            break;
+        }
+    }
+    return count;
+}
+/**
+ * Calculates event ID with proof of work
+ * @param event - Event object without ID
+ * @param targetDifficulty - Target number of leading zero bits
+ * @param maxAttempts - Maximum number of attempts
+ * @returns {Promise<string>} Event ID with sufficient proof of work
+ */
+export async function calculatePowEventId(event, targetDifficulty, maxAttempts = 1000000) {
+    let nonce = 0;
+    const eventCopy = { ...event };
+    while (nonce < maxAttempts) {
+        eventCopy.nonce = nonce.toString();
+        const serialized = JSON.stringify([
+            0,
+            eventCopy.pubkey,
+            eventCopy.created_at,
+            eventCopy.kind,
+            eventCopy.tags,
+            eventCopy.content,
+            eventCopy.nonce
+        ]);
+        const hash = createHash('sha256').update(serialized).digest('hex');
+        const difficulty = countLeadingZeroBits(hash);
+        if (difficulty >= targetDifficulty) {
+            return hash;
+        }
+        nonce++;
+    }
+    throw new Error('Failed to find proof of work within maximum attempts');
+}
+/**
+ * Validates proof of work for an event
+ * @param message - Message containing event
+ * @param minDifficulty - Minimum required difficulty
+ * @param logger - Logger instance
+ * @returns {boolean} True if proof of work is valid
+ */
+export function validateEventPoW(message, minDifficulty, logger) {
+    try {
+        if (message.type !== 'EVENT' || !message.data) {
+            return true; // Not an event message
+        }
+        const event = message.data;
+        if (!event.id || typeof event.id !== 'string') {
+            logger.debug('Missing event ID');
+            return false;
+        }
+        // Calculate difficulty
+        const difficulty = countLeadingZeroBits(event.id);
+        return difficulty >= minDifficulty;
+    }
+    catch (error) {
+        logger.error('Error validating proof of work:', error);
+        return false;
+    }
+}
+/**
+ * Creates a default difficulty calculator
+ * @param baseDifficulty - Base difficulty for all events
+ * @param contentMultiplier - Multiplier based on content length
+ * @returns {DifficultyCalculator} Difficulty calculator
+ */
+export function createDifficultyCalculator(baseDifficulty = 8, contentMultiplier = 0.001) {
+    return {
+        calculateRequiredDifficulty(event) {
+            let difficulty = baseDifficulty;
+            // Increase difficulty for larger content
+            if (typeof event.content === 'string') {
+                difficulty += Math.floor(event.content.length * contentMultiplier);
+            }
+            // Increase difficulty for certain event kinds
+            const kind = event.kind;
+            if (kind >= 1000) {
+                difficulty += 4; // Higher difficulty for application-specific events
+            }
+            return difficulty;
+        }
+    };
+}
+/**
+ * Creates a default PoW rate limiter
+ * @param windowSeconds - Time window for rate limiting
+ * @param maxDifficulty - Maximum cumulative difficulty per window
+ * @returns {PowRateLimiter} Rate limiter
+ */
+export function createPowRateLimiter(windowSeconds = 3600, maxDifficulty = 100) {
+    const difficulties = new Map();
+    return {
+        shouldRateLimit(pubkey, currentTime) {
+            const events = difficulties.get(pubkey) || [];
+            // Remove old events
+            const validEvents = events.filter(([time]) => currentTime - time < windowSeconds);
+            // Calculate cumulative difficulty
+            const totalDifficulty = validEvents.reduce((sum, [, diff]) => sum + diff, 0);
+            return totalDifficulty >= maxDifficulty;
+        },
+        recordEvent(pubkey, difficulty, currentTime) {
+            const events = difficulties.get(pubkey) || [];
+            events.push([currentTime, difficulty]);
+            difficulties.set(pubkey, events);
+        }
+    };
+}

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

@@ -0,0 +1,83 @@
+/**
+ * @file NIP-15: End of Stored Events Notice
+ * @module nips/nip-15
+ * @see https://github.com/nostr-protocol/nips/blob/master/15.md
+ */
+import type { NostrWSMessage } from '../types/messages';
+import type { Logger } from '../types/logger';
+/**
+ * Creates an EOSE (End of Stored Events) message
+ * @param subscriptionId - Subscription ID
+ * @returns {NostrWSMessage} EOSE message
+ */
+export declare function createEOSEMessage(subscriptionId: string): NostrWSMessage;
+/**
+ * Subscription state manager interface
+ */
+export interface SubscriptionStateManager {
+    /**
+     * Registers a new subscription
+     * @param subscriptionId - Subscription ID
+     * @param filter - Subscription filter
+     */
+    registerSubscription(subscriptionId: string, filter: Record<string, unknown>): void;
+    /**
+     * Marks a subscription as complete (EOSE sent)
+     * @param subscriptionId - Subscription ID
+     */
+    markComplete(subscriptionId: string): void;
+    /**
+     * Checks if a subscription is complete
+     * @param subscriptionId - Subscription ID
+     * @returns {boolean} True if EOSE has been sent
+     */
+    isComplete(subscriptionId: string): boolean;
+    /**
+     * Gets subscription filter
+     * @param subscriptionId - Subscription ID
+     * @returns {Record<string, unknown> | undefined} Subscription filter
+     */
+    getFilter(subscriptionId: string): Record<string, unknown> | undefined;
+    /**
+     * Removes a subscription
+     * @param subscriptionId - Subscription ID
+     */
+    removeSubscription(subscriptionId: string): void;
+}
+/**
+ * Creates a subscription state manager
+ * @param logger - Logger instance
+ * @returns {SubscriptionStateManager} Subscription state manager
+ */
+export declare function createSubscriptionStateManager(logger: Logger): SubscriptionStateManager;
+/**
+ * Pagination handler interface
+ */
+export interface PaginationHandler {
+    /**
+     * Gets next page of events
+     * @param subscriptionId - Subscription ID
+     * @param pageSize - Number of events per page
+     * @returns {Promise<NostrWSMessage[]>} Next page of events
+     */
+    getNextPage(subscriptionId: string, pageSize: number): Promise<NostrWSMessage[]>;
+    /**
+     * Checks if more events are available
+     * @param subscriptionId - Subscription ID
+     * @returns {boolean} True if more events exist
+     */
+    hasMoreEvents(subscriptionId: string): boolean;
+    /**
+     * Updates pagination state with new events
+     * @param subscriptionId - Subscription ID
+     * @param events - New events
+     */
+    updateState(subscriptionId: string, events: NostrWSMessage[]): void;
+}
+/**
+ * Creates a pagination handler
+ * @param stateManager - Subscription state manager
+ * @param logger - Logger instance
+ * @returns {PaginationHandler} Pagination handler
+ */
+export declare function createPaginationHandler(stateManager: SubscriptionStateManager, logger: Logger): PaginationHandler;

package/dist/nips/nip-15.js

@@ -0,0 +1,101 @@
+/**
+ * @file NIP-15: End of Stored Events Notice
+ * @module nips/nip-15
+ * @see https://github.com/nostr-protocol/nips/blob/master/15.md
+ */
+/**
+ * Creates an EOSE (End of Stored Events) message
+ * @param subscriptionId - Subscription ID
+ * @returns {NostrWSMessage} EOSE message
+ */
+export function createEOSEMessage(subscriptionId) {
+    return {
+        type: 'EOSE',
+        data: {
+            subscription_id: subscriptionId
+        }
+    };
+}
+/**
+ * Creates a subscription state manager
+ * @param logger - Logger instance
+ * @returns {SubscriptionStateManager} Subscription state manager
+ */
+export function createSubscriptionStateManager(logger) {
+    const subscriptions = new Map();
+    return {
+        registerSubscription(subscriptionId, filter) {
+            subscriptions.set(subscriptionId, {
+                filter,
+                complete: false,
+                timestamp: Date.now()
+            });
+        },
+        markComplete(subscriptionId) {
+            const state = subscriptions.get(subscriptionId);
+            if (state) {
+                state.complete = true;
+            }
+            else {
+                logger.debug(`Attempting to mark unknown subscription ${subscriptionId} as complete`);
+            }
+        },
+        isComplete(subscriptionId) {
+            return subscriptions.get(subscriptionId)?.complete || false;
+        },
+        getFilter(subscriptionId) {
+            return subscriptions.get(subscriptionId)?.filter;
+        },
+        removeSubscription(subscriptionId) {
+            subscriptions.delete(subscriptionId);
+        }
+    };
+}
+/**
+ * Creates a pagination handler
+ * @param stateManager - Subscription state manager
+ * @param logger - Logger instance
+ * @returns {PaginationHandler} Pagination handler
+ */
+export function createPaginationHandler(stateManager, logger) {
+    const paginationStates = new Map();
+    return {
+        async getNextPage(subscriptionId, pageSize) {
+            const state = paginationStates.get(subscriptionId);
+            if (!state) {
+                logger.debug(`No pagination state for subscription ${subscriptionId}`);
+                return [];
+            }
+            const start = state.currentIndex;
+            const end = Math.min(start + pageSize, state.events.length);
+            state.currentIndex = end;
+            state.hasMore = end < state.events.length;
+            // If this is the last page, send EOSE
+            if (!state.hasMore && !stateManager.isComplete(subscriptionId)) {
+                stateManager.markComplete(subscriptionId);
+                return [
+                    ...state.events.slice(start, end),
+                    createEOSEMessage(subscriptionId)
+                ];
+            }
+            return state.events.slice(start, end);
+        },
+        hasMoreEvents(subscriptionId) {
+            return paginationStates.get(subscriptionId)?.hasMore || false;
+        },
+        updateState(subscriptionId, events) {
+            const existing = paginationStates.get(subscriptionId);
+            if (existing) {
+                existing.events.push(...events);
+                existing.hasMore = true;
+            }
+            else {
+                paginationStates.set(subscriptionId, {
+                    events,
+                    currentIndex: 0,
+                    hasMore: true
+                });
+            }
+        }
+    };
+}

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

@@ -0,0 +1,88 @@
+/**
+ * @file NIP-16: Event Treatment
+ * @module nips/nip-16
+ * @see https://github.com/nostr-protocol/nips/blob/master/16.md
+ */
+import type { NostrWSMessage } from '../types/messages';
+import type { Logger } from '../types/logger';
+/**
+ * Event treatment types
+ */
+export declare const EventTreatment: {
+    readonly EPHEMERAL: "ephemeral";
+    readonly REPLACEABLE: "replaceable";
+    readonly PERSISTENT: "persistent";
+};
+export type EventTreatmentType = typeof EventTreatment[keyof typeof EventTreatment];
+/**
+ * Replaceable event kinds (10000-19999)
+ */
+export declare const REPLACEABLE_EVENT_KINDS: {
+    METADATA: number;
+    CONTACT_LIST: number;
+    CHANNEL_METADATA: number;
+    CHANNEL_MESSAGE: number;
+    USER_STATUS: number;
+    USER_PROFILE: number;
+    RELAY_LIST: number;
+    BOOKMARKS: number;
+    MUTE_LIST: number;
+    PIN_LIST: number;
+    RELAY_METADATA: number;
+    CLIENT_PREFERENCES: number;
+    CUSTOM_START: number;
+    CUSTOM_END: number;
+};
+/**
+ * Ephemeral event kinds (20000-29999)
+ */
+export declare const EPHEMERAL_EVENT_KINDS: {
+    TYPING_INDICATOR: number;
+    ONLINE_STATUS: number;
+    USER_PRESENCE: number;
+    CUSTOM_START: number;
+    CUSTOM_END: number;
+};
+/**
+ * Determines event treatment type
+ * @param eventKind - Event kind number
+ * @returns {EventTreatmentType} Event treatment type
+ */
+export declare function getEventTreatment(eventKind: number): EventTreatmentType;
+/**
+ * Validates event treatment rules
+ * @param message - Message to validate
+ * @param logger - Logger instance
+ * @returns {boolean} True if event follows treatment rules
+ */
+export declare function validateEventTreatment(message: NostrWSMessage, logger: Logger): boolean;
+/**
+ * Storage management interface for different event types
+ */
+export interface EventStorageManager {
+    /**
+     * Determines if an event should be stored
+     * @param event - Event to check
+     * @returns {boolean} True if event should be stored
+     */
+    shouldStore(event: Record<string, unknown>): boolean;
+    /**
+     * Gets storage duration for an event
+     * @param event - Event to check
+     * @returns {number} Storage duration in seconds (0 for permanent)
+     */
+    getStorageDuration(event: Record<string, unknown>): number;
+    /**
+     * Checks if an event should replace another
+     * @param newEvent - New event
+     * @param existingEvent - Existing event
+     * @returns {boolean} True if new event should replace existing
+     */
+    shouldReplace(newEvent: Record<string, unknown>, existingEvent: Record<string, unknown>): boolean;
+}
+/**
+ * Creates default event storage manager
+ * @param logger - Logger instance
+ * @returns {EventStorageManager} Storage manager
+ */
+export declare function createEventStorageManager(logger: Logger): EventStorageManager;

package/dist/nips/nip-16.js

@@ -0,0 +1,150 @@
+/**
+ * @file NIP-16: Event Treatment
+ * @module nips/nip-16
+ * @see https://github.com/nostr-protocol/nips/blob/master/16.md
+ */
+/**
+ * Event treatment types
+ */
+export const EventTreatment = {
+    EPHEMERAL: 'ephemeral',
+    REPLACEABLE: 'replaceable',
+    PERSISTENT: 'persistent'
+};
+/**
+ * Replaceable event kinds (10000-19999)
+ */
+export const REPLACEABLE_EVENT_KINDS = {
+    METADATA: 0,
+    CONTACT_LIST: 3,
+    CHANNEL_METADATA: 41,
+    CHANNEL_MESSAGE: 42,
+    USER_STATUS: 10000,
+    USER_PROFILE: 10001,
+    RELAY_LIST: 10002,
+    BOOKMARKS: 10003,
+    MUTE_LIST: 10004,
+    PIN_LIST: 10005,
+    RELAY_METADATA: 10010,
+    CLIENT_PREFERENCES: 10015,
+    CUSTOM_START: 11000,
+    CUSTOM_END: 19999
+};
+/**
+ * Ephemeral event kinds (20000-29999)
+ */
+export const EPHEMERAL_EVENT_KINDS = {
+    TYPING_INDICATOR: 20001,
+    ONLINE_STATUS: 20002,
+    USER_PRESENCE: 20003,
+    CUSTOM_START: 21000,
+    CUSTOM_END: 29999
+};
+/**
+ * Determines event treatment type
+ * @param eventKind - Event kind number
+ * @returns {EventTreatmentType} Event treatment type
+ */
+export function getEventTreatment(eventKind) {
+    if (eventKind >= 20000 && eventKind < 30000) {
+        return EventTreatment.EPHEMERAL;
+    }
+    if (eventKind >= 10000 && eventKind < 20000 || [0, 3, 41, 42].includes(eventKind)) {
+        return EventTreatment.REPLACEABLE;
+    }
+    return EventTreatment.PERSISTENT;
+}
+/**
+ * Validates event treatment rules
+ * @param message - Message to validate
+ * @param logger - Logger instance
+ * @returns {boolean} True if event follows treatment rules
+ */
+export function validateEventTreatment(message, logger) {
+    try {
+        if (message.type !== 'EVENT' || !message.data) {
+            return true; // Not an event message
+        }
+        const event = message.data;
+        const kind = event.kind;
+        const treatment = getEventTreatment(kind);
+        // Validate based on treatment type
+        switch (treatment) {
+            case EventTreatment.EPHEMERAL:
+                // Ephemeral events shouldn't have large content
+                if (typeof event.content === 'string' && event.content.length > 1000) {
+                    logger.debug('Ephemeral event content too large');
+                    return false;
+                }
+                break;
+            case EventTreatment.REPLACEABLE:
+                // Replaceable events must have proper 'd' tag for uniqueness
+                if (Array.isArray(event.tags)) {
+                    const dTags = event.tags.filter(tag => Array.isArray(tag) && tag[0] === 'd');
+                    if (dTags.length > 1) {
+                        logger.debug('Multiple d tags in replaceable event');
+                        return false;
+                    }
+                }
+                break;
+        }
+        return true;
+    }
+    catch (error) {
+        logger.error('Error validating event treatment:', error);
+        return false;
+    }
+}
+/**
+ * Creates default event storage manager
+ * @param logger - Logger instance
+ * @returns {EventStorageManager} Storage manager
+ */
+export function createEventStorageManager(logger) {
+    return {
+        shouldStore(event) {
+            const kind = event.kind;
+            const treatment = getEventTreatment(kind);
+            // Don't store ephemeral events by default
+            if (treatment === EventTreatment.EPHEMERAL) {
+                return false;
+            }
+            return true;
+        },
+        getStorageDuration(event) {
+            const kind = event.kind;
+            const treatment = getEventTreatment(kind);
+            switch (treatment) {
+                case EventTreatment.EPHEMERAL:
+                    return 300; // 5 minutes
+                case EventTreatment.REPLACEABLE:
+                    return 0; // Permanent until replaced
+                default:
+                    return 0; // Permanent
+            }
+        },
+        shouldReplace(newEvent, existingEvent) {
+            try {
+                const kind = newEvent.kind;
+                if (kind !== existingEvent.kind)
+                    return false;
+                const treatment = getEventTreatment(kind);
+                if (treatment !== EventTreatment.REPLACEABLE)
+                    return false;
+                // Check 'd' tag for parameterized replaceable events
+                if (Array.isArray(newEvent.tags) && Array.isArray(existingEvent.tags)) {
+                    const newDTag = newEvent.tags.find(tag => Array.isArray(tag) && tag[0] === 'd')?.[1];
+                    const existingDTag = existingEvent.tags.find(tag => Array.isArray(tag) && tag[0] === 'd')?.[1];
+                    if (newDTag !== existingDTag)
+                        return false;
+                }
+                // Replace if new event is newer
+                return newEvent.created_at > existingEvent.created_at;
+            }
+            catch (error) {
+                logger.error('Error checking event replacement:', error);
+                return false;
+            }
+        }
+    };
+}

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

@@ -0,0 +1,28 @@
+/**
+ * @file NIP-19: bech32-encoded entities
+ * @module nips/nip-19
+ */
+/**
+ * Encode a public key to bech32 npub format
+ */
+export declare function encodePubkey(pubkey: string): string;
+/**
+ * Encode a private key to bech32 nsec format
+ */
+export declare function encodePrivkey(privkey: string): string;
+/**
+ * Decode a bech32 npub to hex pubkey
+ */
+export declare function decodePubkey(npub: string): string;
+/**
+ * Decode a bech32 nsec to hex privkey
+ */
+export declare function decodePrivkey(nsec: string): string;
+/**
+ * Process tags containing bech32-encoded entities
+ */
+export declare function processBech32Tags(tags: string[][]): string[][];
+/**
+ * Encode tags containing hex pubkeys to bech32
+ */
+export declare function encodeBech32Tags(tags: string[][]): string[][];