nostr-websocket-utils 0.2.4 → 0.3.0

package/dist/nips/nip-19.js

@@ -0,0 +1,103 @@
+/**
+ * @file NIP-19: bech32-encoded entities
+ * @module nips/nip-19
+ */
+import { getLogger } from '../utils/logger';
+import { encodeToBech32, decodeFromBech32 } from '../crypto/bech32';
+const logger = getLogger('NIP-19');
+/**
+ * Encode a public key to bech32 npub format
+ */
+export function encodePubkey(pubkey) {
+    try {
+        return encodeToBech32('npub', pubkey);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Failed to encode pubkey: ${errorMessage}`);
+        throw new Error(`Failed to encode pubkey: ${errorMessage}`);
+    }
+}
+/**
+ * Encode a private key to bech32 nsec format
+ */
+export function encodePrivkey(privkey) {
+    try {
+        return encodeToBech32('nsec', privkey);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Failed to encode private key: ${errorMessage}`);
+        throw new Error(`Failed to encode private key: ${errorMessage}`);
+    }
+}
+/**
+ * Decode a bech32 npub to hex pubkey
+ */
+export function decodePubkey(npub) {
+    try {
+        const { prefix, hex } = decodeFromBech32(npub);
+        if (prefix !== 'npub') {
+            throw new Error('Invalid prefix for public key');
+        }
+        return hex;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Failed to decode pubkey: ${errorMessage}`);
+        throw new Error(`Failed to decode pubkey: ${errorMessage}`);
+    }
+}
+/**
+ * Decode a bech32 nsec to hex privkey
+ */
+export function decodePrivkey(nsec) {
+    try {
+        const { prefix, hex } = decodeFromBech32(nsec);
+        if (prefix !== 'nsec') {
+            throw new Error('Invalid prefix for private key');
+        }
+        return hex;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Failed to decode private key: ${errorMessage}`);
+        throw new Error(`Failed to decode private key: ${errorMessage}`);
+    }
+}
+/**
+ * Process tags containing bech32-encoded entities
+ */
+export function processBech32Tags(tags) {
+    return tags.map(tag => {
+        try {
+            if (tag[0] === 'p' && tag[1].startsWith('npub')) {
+                return [tag[0], decodePubkey(tag[1])];
+            }
+            return tag;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.debug(`Failed to decode pubkey ${tag[1]}: ${errorMessage}`);
+            return tag;
+        }
+    });
+}
+/**
+ * Encode tags containing hex pubkeys to bech32
+ */
+export function encodeBech32Tags(tags) {
+    return tags.map(tag => {
+        try {
+            if (tag[0] === 'p' && !tag[1].startsWith('npub')) {
+                return [tag[0], encodePubkey(tag[1])];
+            }
+            return tag;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.debug(`Failed to encode pubkey ${tag[1]}: ${errorMessage}`);
+            return tag;
+        }
+    });
+}

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

@@ -0,0 +1,59 @@
+/**
+ * @file NIP-20 Command Results implementation
+ * @module nips/nip-20
+ */
+import { NostrWSMessage } from '../types';
+/**
+ * Command status types
+ */
+export declare enum CommandStatus {
+    SUCCESS = "success",
+    ERROR = "error",
+    PENDING = "pending",
+    RATE_LIMITED = "rate_limited",
+    AUTH_REQUIRED = "auth_required",
+    RESTRICTED = "restricted"
+}
+export type CommandStatusType = CommandStatus;
+/**
+ * Command result interface
+ */
+export interface CommandResult {
+    status: boolean;
+    message?: string;
+    code?: CommandStatusType;
+    details?: Record<string, unknown>;
+}
+/**
+ * Represents the data structure for command messages
+ * @interface CommandMessageData
+ * @property {string} [event_id] - ID of the event this command relates to
+ * @property {boolean} [status] - Status of the command execution
+ * @property {string} [message] - Human-readable message about the command result
+ * @property {CommandStatusType} [code] - Status code of the command result
+ * @property {Record<string, unknown>} [details] - Additional details about the command result
+ */
+interface CommandMessageData {
+    event_id?: string;
+    status?: boolean;
+    message?: string;
+    code?: CommandStatusType;
+    details?: Record<string, unknown>;
+}
+/**
+ * Validates a command message according to NIP-20
+ */
+export declare function validateCommandMessage(message: NostrWSMessage): boolean;
+/**
+ * Creates a command result message
+ */
+export declare function createCommandResult(data: CommandMessageData): CommandResult;
+/**
+ * Creates an OK message
+ */
+export declare function createOkMessage(eventId: string, success?: boolean, details?: Record<string, unknown>): NostrWSMessage;
+/**
+ * Creates a NOTICE message
+ */
+export declare function createCommandNoticeMessage(code: CommandStatusType, message: string, details?: Record<string, unknown>): NostrWSMessage;
+export {};

package/dist/nips/nip-20.js

@@ -0,0 +1,95 @@
+/**
+ * @file NIP-20 Command Results implementation
+ * @module nips/nip-20
+ */
+import { getLogger } from '../utils/logger';
+const logger = getLogger('NIP-20');
+/**
+ * Command status types
+ */
+export var CommandStatus;
+(function (CommandStatus) {
+    CommandStatus["SUCCESS"] = "success";
+    CommandStatus["ERROR"] = "error";
+    CommandStatus["PENDING"] = "pending";
+    CommandStatus["RATE_LIMITED"] = "rate_limited";
+    CommandStatus["AUTH_REQUIRED"] = "auth_required";
+    CommandStatus["RESTRICTED"] = "restricted";
+})(CommandStatus || (CommandStatus = {}));
+/**
+ * Validates a command message according to NIP-20
+ */
+export function validateCommandMessage(message) {
+    if (!message.data || typeof message.data !== 'object') {
+        logger.debug('Invalid command message data');
+        return false;
+    }
+    const data = message.data;
+    // For OK/NOTICE messages
+    if (message.type === 'OK') {
+        if (!data.event_id || typeof data.event_id !== 'string') {
+            logger.debug('Invalid event_id in OK message');
+            return false;
+        }
+        if (typeof data.status !== 'boolean') {
+            logger.debug('Invalid status in OK message');
+            return false;
+        }
+    }
+    // For NOTICE messages
+    if (message.type === 'NOTICE' && data.code) {
+        if (!Object.values(CommandStatus).includes(data.code)) {
+            logger.debug('Invalid command status code');
+            return false;
+        }
+    }
+    // Optional fields validation
+    if (data.message && typeof data.message !== 'string') {
+        logger.debug('Invalid message field');
+        return false;
+    }
+    if (data.details && typeof data.details !== 'object') {
+        logger.debug('Invalid details field');
+        return false;
+    }
+    return true;
+}
+/**
+ * Creates a command result message
+ */
+export function createCommandResult(data) {
+    const status = data.status ?? false;
+    const code = status ? CommandStatus.SUCCESS : data.code;
+    return {
+        status,
+        code,
+        message: data.message,
+        details: data.details
+    };
+}
+/**
+ * Creates an OK message
+ */
+export function createOkMessage(eventId, success = true, details) {
+    return {
+        type: 'OK',
+        data: {
+            event_id: eventId,
+            status: success,
+            ...details && { details }
+        }
+    };
+}
+/**
+ * Creates a NOTICE message
+ */
+export function createCommandNoticeMessage(code, message, details) {
+    return {
+        type: 'NOTICE',
+        data: {
+            code,
+            message,
+            ...details && { details }
+        }
+    };
+}

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

@@ -0,0 +1,89 @@
+/**
+ * @file NIP-22: Event Created At Limits
+ * @module nips/nip-22
+ * @see https://github.com/nostr-protocol/nips/blob/master/22.md
+ */
+import type { NostrWSMessage } from '../types/messages';
+import type { Logger } from '../types/logger';
+/**
+ * Default time limits in seconds
+ */
+export declare const DEFAULT_TIME_LIMITS: {
+    FUTURE_LIMIT: number;
+    PAST_LIMIT: number;
+};
+/**
+ * Time validation result
+ */
+export interface TimeValidationResult {
+    valid: boolean;
+    reason?: string;
+}
+/**
+ * Time validator interface
+ */
+export interface TimeValidator {
+    /**
+     * Validates event timestamp
+     * @param timestamp - Event timestamp
+     * @returns {TimeValidationResult} Validation result
+     */
+    validateTime(timestamp: number): TimeValidationResult;
+    /**
+     * Updates server time offset
+     * @param serverTime - Server timestamp
+     */
+    updateTimeOffset(serverTime: number): void;
+    /**
+     * Gets current adjusted timestamp
+     * @returns {number} Adjusted timestamp
+     */
+    getCurrentTime(): number;
+}
+/**
+ * Creates a time validator
+ * @param logger - Logger instance
+ * @param futureLimitSeconds - Future time limit in seconds
+ * @param pastLimitSeconds - Past time limit in seconds
+ * @returns {TimeValidator} Time validator
+ */
+export declare function createTimeValidator(logger: Logger, futureLimitSeconds?: number, pastLimitSeconds?: number): TimeValidator;
+/**
+ * Validates event timestamp
+ * @param message - Message to validate
+ * @param validator - Time validator
+ * @param logger - Logger instance
+ * @returns {TimeValidationResult} Validation result
+ */
+export declare function validateEventTime(message: NostrWSMessage, validator: TimeValidator, logger: Logger): TimeValidationResult;
+/**
+ * Time synchronization manager interface
+ */
+export interface TimeSyncManager {
+    /**
+     * Starts time synchronization
+     * @param wsUrl - WebSocket URL for time sync
+     */
+    startSync(wsUrl: string): void;
+    /**
+     * Stops time synchronization
+     */
+    stopSync(): void;
+    /**
+     * Gets current synchronized time
+     * @returns {number} Current timestamp
+     */
+    getCurrentTime(): number;
+    /**
+     * Validates event timing
+     * @param event - Event to validate
+     * @returns {TimeValidationResult} Validation result
+     */
+    validateEvent(event: NostrWSMessage): TimeValidationResult;
+}
+/**
+ * Creates a time synchronization manager
+ * @param logger - Logger instance
+ * @returns {TimeSyncManager} Time sync manager
+ */
+export declare function createTimeSyncManager(logger: Logger): TimeSyncManager;

package/dist/nips/nip-22.js

@@ -0,0 +1,142 @@
+/**
+ * @file NIP-22: Event Created At Limits
+ * @module nips/nip-22
+ * @see https://github.com/nostr-protocol/nips/blob/master/22.md
+ */
+/**
+ * Default time limits in seconds
+ */
+export const DEFAULT_TIME_LIMITS = {
+    FUTURE_LIMIT: 900, // 15 minutes
+    PAST_LIMIT: 31536000 // 1 year
+};
+/**
+ * Creates a time validator
+ * @param logger - Logger instance
+ * @param futureLimitSeconds - Future time limit in seconds
+ * @param pastLimitSeconds - Past time limit in seconds
+ * @returns {TimeValidator} Time validator
+ */
+export function createTimeValidator(logger, futureLimitSeconds = DEFAULT_TIME_LIMITS.FUTURE_LIMIT, pastLimitSeconds = DEFAULT_TIME_LIMITS.PAST_LIMIT) {
+    let timeOffset = 0; // Offset between local and server time
+    return {
+        validateTime(timestamp) {
+            const now = Date.now() / 1000 + timeOffset;
+            // Check future limit
+            if (timestamp > now + futureLimitSeconds) {
+                return {
+                    valid: false,
+                    reason: 'Event timestamp too far in the future'
+                };
+            }
+            // Check past limit
+            if (timestamp < now - pastLimitSeconds) {
+                return {
+                    valid: false,
+                    reason: 'Event timestamp too far in the past'
+                };
+            }
+            return { valid: true };
+        },
+        updateTimeOffset(serverTime) {
+            const localTime = Date.now() / 1000;
+            timeOffset = serverTime - localTime;
+            logger.debug(`Updated time offset to ${timeOffset} seconds`);
+        },
+        getCurrentTime() {
+            return Math.floor(Date.now() / 1000 + timeOffset);
+        }
+    };
+}
+/**
+ * Validates event timestamp
+ * @param message - Message to validate
+ * @param validator - Time validator
+ * @param logger - Logger instance
+ * @returns {TimeValidationResult} Validation result
+ */
+export function validateEventTime(message, validator, logger) {
+    try {
+        if (message.type !== 'EVENT' || !message.data) {
+            return { valid: true }; // Not an event message
+        }
+        const event = message.data;
+        const timestamp = event.created_at;
+        if (typeof timestamp !== 'number') {
+            return {
+                valid: false,
+                reason: 'Missing or invalid timestamp'
+            };
+        }
+        return validator.validateTime(timestamp);
+    }
+    catch (error) {
+        logger.error('Error validating event time:', error);
+        return {
+            valid: false,
+            reason: 'Error validating timestamp'
+        };
+    }
+}
+/**
+ * Creates a time synchronization manager
+ * @param logger - Logger instance
+ * @returns {TimeSyncManager} Time sync manager
+ */
+export function createTimeSyncManager(logger) {
+    const validator = createTimeValidator(logger);
+    let syncInterval = null;
+    async function syncTime(wsUrl) {
+        try {
+            const ws = new WebSocket(wsUrl);
+            await new Promise((resolve, reject) => {
+                ws.onopen = () => {
+                    // Send time request
+                    ws.send(JSON.stringify({
+                        type: 'TIME',
+                        data: { client_time: Math.floor(Date.now() / 1000) }
+                    }));
+                };
+                ws.onmessage = (event) => {
+                    try {
+                        const response = JSON.parse(event.data);
+                        if (response.type === 'TIME') {
+                            validator.updateTimeOffset(response.data.server_time);
+                            resolve();
+                        }
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                    ws.close();
+                };
+                ws.onerror = reject;
+                // Timeout after 5 seconds
+                setTimeout(() => reject(new Error('Time sync timeout')), 5000);
+            });
+        }
+        catch (error) {
+            logger.error('Time sync failed:', error);
+        }
+    }
+    return {
+        startSync(wsUrl) {
+            // Initial sync
+            syncTime(wsUrl);
+            // Periodic sync every 15 minutes
+            syncInterval = setInterval(() => syncTime(wsUrl), 900000);
+        },
+        stopSync() {
+            if (syncInterval) {
+                clearInterval(syncInterval);
+                syncInterval = null;
+            }
+        },
+        getCurrentTime() {
+            return validator.getCurrentTime();
+        },
+        validateEvent(event) {
+            return validateEventTime(event, validator, logger);
+        }
+    };
+}

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

@@ -0,0 +1,52 @@
+/**
+ * @file NIP-26: Delegated Event Signing
+ * @module nips/nip-26
+ */
+import type { NostrEvent } from '../types/events';
+/**
+ * Represents the conditions for a Nostr event delegation
+ * @interface DelegationConditions
+ * @property {number} [kind] - The kind of events this delegation is valid for
+ * @property {number} [since] - Unix timestamp from which this delegation is valid
+ * @property {number} [until] - Unix timestamp until which this delegation is valid
+ * @property {unknown} [key: string] - Any additional conditions
+ */
+interface DelegationConditions {
+    kind?: number;
+    since?: number;
+    until?: number;
+    [key: string]: unknown;
+}
+/**
+ * Represents a Nostr event delegation
+ * @interface Delegation
+ * @property {string} pubkey - The public key of the delegator
+ * @property {DelegationConditions} conditions - The conditions under which this delegation is valid
+ * @property {string} token - The delegation token signed by the delegator
+ */
+interface Delegation {
+    pubkey: string;
+    conditions: DelegationConditions;
+    token: string;
+}
+/**
+ * Create a delegation token
+ */
+export declare function createDelegation(delegatorPrivkey: string, delegateePubkey: string, conditions: DelegationConditions): Promise<string>;
+/**
+ * Verify a delegation token
+ */
+export declare function verifyDelegation(delegatorPubkey: string, delegateePubkey: string, token: string, conditions: DelegationConditions): Promise<boolean>;
+/**
+ * Add delegation tag to an event
+ */
+export declare function addDelegationTag(event: NostrEvent, delegation: Delegation): NostrEvent;
+/**
+ * Extract delegation from an event
+ */
+export declare function extractDelegation(event: NostrEvent): Delegation | null;
+/**
+ * Validate a delegated event
+ */
+export declare function validateDelegatedEvent(event: NostrEvent): Promise<boolean>;
+export {};

package/dist/nips/nip-26.js

@@ -0,0 +1,139 @@
+/**
+ * @file NIP-26: Delegated Event Signing
+ * @module nips/nip-26
+ */
+import { getLogger } from '../utils/logger';
+import { signEvent, verifySignature } from 'nostr-crypto-utils';
+const logger = getLogger('NIP-26');
+/**
+ * Create a delegation token
+ */
+export async function createDelegation(delegatorPrivkey, delegateePubkey, conditions) {
+    try {
+        const conditionsString = Object.entries(conditions)
+            .map(([key, value]) => `${key}=${value}`)
+            .sort()
+            .join('&');
+        const message = `nostr:delegation:${delegateePubkey}:${conditionsString}`;
+        // Create a NostrEvent object for signing
+        const event = {
+            id: '', // This will be set by signEvent
+            pubkey: delegateePubkey,
+            created_at: Math.floor(Date.now() / 1000),
+            kind: 0, // Using kind 0 for delegation events
+            tags: [],
+            content: message,
+            sig: '' // This will be set by signEvent
+        };
+        const signedEvent = await signEvent(event, delegatorPrivkey);
+        return signedEvent.sig;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Failed to create delegation: ${errorMessage}`);
+        throw new Error(`Failed to create delegation: ${errorMessage}`);
+    }
+}
+/**
+ * Verify a delegation token
+ */
+export async function verifyDelegation(delegatorPubkey, delegateePubkey, token, conditions) {
+    try {
+        const conditionsString = Object.entries(conditions)
+            .map(([key, value]) => `${key}=${value}`)
+            .sort()
+            .join('&');
+        const message = `nostr:delegation:${delegateePubkey}:${conditionsString}`;
+        const verificationEvent = {
+            id: '',
+            pubkey: delegatorPubkey,
+            created_at: Math.floor(Date.now() / 1000),
+            kind: 0,
+            tags: [],
+            content: message,
+            sig: token
+        };
+        return await verifySignature(verificationEvent);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Failed to verify delegation: ${errorMessage}`);
+        return false;
+    }
+}
+/**
+ * Add delegation tag to an event
+ */
+export function addDelegationTag(event, delegation) {
+    const conditionsString = Object.entries(delegation.conditions)
+        .map(([key, value]) => `${key}=${value}`)
+        .sort()
+        .join('&');
+    const delegationTag = ['delegation', delegation.pubkey, conditionsString, delegation.token];
+    return {
+        ...event,
+        tags: [...event.tags, delegationTag]
+    };
+}
+/**
+ * Extract delegation from an event
+ */
+export function extractDelegation(event) {
+    try {
+        const delegationTag = event.tags.find(tag => tag[0] === 'delegation');
+        if (!delegationTag || delegationTag.length !== 4) {
+            return null;
+        }
+        const [, pubkey, conditionsString, token] = delegationTag;
+        const conditions = {};
+        conditionsString.split('&').forEach(pair => {
+            const [key, value] = pair.split('=');
+            if (key === 'kind' || key === 'since' || key === 'until') {
+                conditions[key] = parseInt(value, 10);
+            }
+            else {
+                conditions[key] = value;
+            }
+        });
+        return { pubkey, conditions, token };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Failed to extract delegation: ${errorMessage}`);
+        return null;
+    }
+}
+/**
+ * Validate a delegated event
+ */
+export async function validateDelegatedEvent(event) {
+    try {
+        const delegation = extractDelegation(event);
+        if (!delegation) {
+            return false;
+        }
+        const { kind, created_at } = event;
+        const { kind: allowedKind, since, until } = delegation.conditions;
+        // Check kind constraint
+        if (allowedKind !== undefined && kind !== allowedKind) {
+            logger.debug('Event kind does not match delegation conditions');
+            return false;
+        }
+        // Check time constraints
+        if (since !== undefined && created_at < since) {
+            logger.debug('Event is before delegation start time');
+            return false;
+        }
+        if (until !== undefined && created_at > until) {
+            logger.debug('Event is after delegation end time');
+            return false;
+        }
+        // Verify delegation token
+        return await verifyDelegation(delegation.pubkey, event.pubkey, delegation.token, delegation.conditions);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        logger.error(`Failed to validate delegated event: ${errorMessage}`);
+        return false;
+    }
+}