ncc-05 1.1.4 → 1.1.7

package/dist/index.d.ts

@@ -6,7 +6,22 @@
  *
  * @module ncc-05
  */
-import { Event } from 'nostr-tools';
+import { SimplePool, Event } from 'nostr-tools';
+export declare class NCC05Error extends Error {
+    constructor(message: string);
+}
+export declare class NCC05RelayError extends NCC05Error {
+    constructor(message: string);
+}
+export declare class NCC05TimeoutError extends NCC05Error {
+    constructor(message: string);
+}
+export declare class NCC05DecryptionError extends NCC05Error {
+    constructor(message: string);
+}
+export declare class NCC05ArgumentError extends NCC05Error {
+    constructor(message: string);
+}
 /**
  * Represents a single reachable service endpoint.
  */
@@ -47,6 +62,19 @@ export interface ResolverOptions {
     timeout?: number;
     /** Custom WebSocket implementation (e.g., for Tor/SOCKS5 in Node.js) */
     websocketImplementation?: any;
+    /** Existing SimplePool instance to share connections */
+    pool?: SimplePool;
+}
+/**
+ * Options for configuring the NCC05Publisher.
+ */
+export interface PublisherOptions {
+    /** Custom WebSocket implementation */
+    websocketImplementation?: any;
+    /** Existing SimplePool instance */
+    pool?: SimplePool;
+    /** Timeout for publishing in milliseconds (default: 5000) */
+    timeout?: number;
 }
 /**
  * Structure for multi-recipient encrypted events.
@@ -83,13 +111,14 @@ export declare class NCC05Group {
      * @param identifier - The 'd' tag of the record (default: 'addr').
      * @returns The resolved NCC05Payload or null.
      */
-    static resolveAsGroup(resolver: NCC05Resolver, groupPubkey: string, groupSecretKey: Uint8Array, identifier?: string): Promise<NCC05Payload | null>;
+    static resolveAsGroup(resolver: NCC05Resolver, groupPubkey: string, groupSecretKey: string | Uint8Array, identifier?: string): Promise<NCC05Payload | null>;
 }
 /**
  * Handles the discovery, selection, and decryption of NCC-05 locator records.
  */
 export declare class NCC05Resolver {
     private pool;
+    private _ownPool;
     private bootstrapRelays;
     private timeout;
     /**
@@ -106,14 +135,16 @@ export declare class NCC05Resolver {
      * @param secretKey - Your secret key (required if the record is encrypted).
      * @param identifier - The 'd' tag of the record (default: 'addr').
      * @param options - Resolution options (strict mode, gossip discovery).
-     * @returns The resolved and validated NCC05Payload, or null if not found/invalid.
+     * @returns The resolved and validated NCC05Payload, or null if not found.
+     * @throws {NCC05TimeoutError} if resolution times out.
+     * @throws {NCC05RelayError} if underlying relay communication fails.
      */
-    resolve(targetPubkey: string, secretKey?: Uint8Array, identifier?: string, options?: {
+    resolve(targetPubkey: string, secretKey?: string | Uint8Array, identifier?: string, options?: {
         strict?: boolean;
         gossip?: boolean;
     }): Promise<NCC05Payload | null>;
     /**
-     * Closes connections to all relays in the pool.
+     * Closes connections to all relays in the pool if managed internally.
      */
     close(): void;
 }
@@ -122,12 +153,13 @@ export declare class NCC05Resolver {
  */
 export declare class NCC05Publisher {
     private pool;
+    private _ownPool;
+    private timeout;
     /**
      * @param options - Configuration for the publisher.
      */
-    constructor(options?: {
-        websocketImplementation?: any;
-    });
+    constructor(options?: PublisherOptions);
+    private _publishToRelays;
     /**
      * Publishes a single record encrypted for multiple recipients using the wrapping pattern.
      * This avoids sharing a single group private key.
@@ -139,7 +171,7 @@ export declare class NCC05Publisher {
      * @param identifier - The 'd' tag identifier (default: 'addr').
      * @returns The signed Nostr event.
      */
-    publishWrapped(relays: string[], secretKey: Uint8Array, recipients: string[], payload: NCC05Payload, identifier?: string): Promise<Event>;
+    publishWrapped(relays: string[], secretKey: string | Uint8Array, recipients: string[], payload: NCC05Payload, identifier?: string): Promise<Event>;
     /**
      * Publishes a locator record. Supports self-encryption, targeted encryption, or plaintext.
      *
@@ -149,13 +181,13 @@ export declare class NCC05Publisher {
      * @param options - Publishing options (identifier, recipient, or public flag).
      * @returns The signed Nostr event.
      */
-    publish(relays: string[], secretKey: Uint8Array, payload: NCC05Payload, options?: {
+    publish(relays: string[], secretKey: string | Uint8Array, payload: NCC05Payload, options?: {
         identifier?: string;
         recipientPubkey?: string;
         public?: boolean;
     }): Promise<Event>;
     /**
-     * Closes connections to the specified relays.
+     * Closes connections to the specified relays if managed internally.
      */
     close(relays: string[]): void;
 }

package/dist/index.js

@@ -7,6 +7,50 @@
  * @module ncc-05
  */
 import { SimplePool, nip44, nip19, finalizeEvent, verifyEvent, getPublicKey, generateSecretKey } from 'nostr-tools';
+// --- Error Classes ---
+export class NCC05Error extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NCC05Error';
+    }
+}
+export class NCC05RelayError extends NCC05Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NCC05RelayError';
+    }
+}
+export class NCC05TimeoutError extends NCC05Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NCC05TimeoutError';
+    }
+}
+export class NCC05DecryptionError extends NCC05Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NCC05DecryptionError';
+    }
+}
+export class NCC05ArgumentError extends NCC05Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NCC05ArgumentError';
+    }
+}
+// --- Helpers ---
+function ensureUint8Array(key) {
+    if (key instanceof Uint8Array)
+        return key;
+    if (typeof key === 'string') {
+        // Assume hex string
+        if (key.match(/^[0-9a-fA-F]+$/)) {
+            return new Uint8Array(key.match(/.{1,2}/g).map(byte => parseInt(byte, 16)));
+        }
+        throw new NCC05ArgumentError("Invalid hex key provided");
+    }
+    throw new NCC05ArgumentError("Key must be a hex string or Uint8Array");
+}
 /**
  * Utility for managing shared group access to service records.
  */
@@ -45,16 +89,24 @@ export class NCC05Group {
  */
 export class NCC05Resolver {
     pool;
+    _ownPool;
     bootstrapRelays;
     timeout;
     /**
      * @param options - Configuration for the resolver.
      */
     constructor(options = {}) {
-        this.pool = new SimplePool();
-        if (options.websocketImplementation) {
-            // @ts-ignore - Patching pool for custom transport
-            this.pool.websocketImplementation = options.websocketImplementation;
+        this._ownPool = !options.pool;
+        this.pool = options.pool || new SimplePool();
+        if (this._ownPool) {
+            if (options.websocketImplementation) {
+                // @ts-ignore - Patching pool for custom transport
+                this.pool.websocketImplementation = options.websocketImplementation;
+            }
+            else if (typeof WebSocket === 'undefined' && typeof globalThis !== 'undefined' && globalThis.WebSocket) {
+                // @ts-ignore
+                this.pool.websocketImplementation = globalThis.WebSocket;
+            }
         }
         this.bootstrapRelays = options.bootstrapRelays || ['wss://relay.damus.io', 'wss://nos.lol'];
         this.timeout = options.timeout || 10000;
@@ -69,7 +121,9 @@ export class NCC05Resolver {
      * @param secretKey - Your secret key (required if the record is encrypted).
      * @param identifier - The 'd' tag of the record (default: 'addr').
      * @param options - Resolution options (strict mode, gossip discovery).
-     * @returns The resolved and validated NCC05Payload, or null if not found/invalid.
+     * @returns The resolved and validated NCC05Payload, or null if not found.
+     * @throws {NCC05TimeoutError} if resolution times out.
+     * @throws {NCC05RelayError} if underlying relay communication fails.
      */
     async resolve(targetPubkey, secretKey, identifier = 'addr', options = {}) {
         let hexPubkey = targetPubkey;
@@ -80,19 +134,25 @@ export class NCC05Resolver {
         let queryRelays = [...this.bootstrapRelays];
         // 1. NIP-65 Gossip Discovery
         if (options.gossip) {
-            const relayListEvent = await this.pool.get(this.bootstrapRelays, {
-                authors: [hexPubkey],
-                kinds: [10002]
-            });
-            // Security: Verify NIP-65 event signature and author
-            if (relayListEvent && verifyEvent(relayListEvent) && relayListEvent.pubkey === hexPubkey) {
-                const discoveredRelays = relayListEvent.tags
-                    .filter(t => t[0] === 'r')
-                    .map(t => t[1]);
-                if (discoveredRelays.length > 0) {
-                    queryRelays = [...new Set([...queryRelays, ...discoveredRelays])];
+            try {
+                const relayListEvent = await this.pool.get(this.bootstrapRelays, {
+                    authors: [hexPubkey],
+                    kinds: [10002]
+                });
+                // Security: Verify NIP-65 event signature and author
+                if (relayListEvent && verifyEvent(relayListEvent) && relayListEvent.pubkey === hexPubkey) {
+                    const discoveredRelays = relayListEvent.tags
+                        .filter(t => t[0] === 'r')
+                        .map(t => t[1]);
+                    if (discoveredRelays.length > 0) {
+                        queryRelays = [...new Set([...queryRelays, ...discoveredRelays])];
+                    }
                 }
             }
+            catch (e) {
+                console.warn(`[NCC-05] Gossip discovery failed: ${e.message}`);
+                // Proceed with bootstrap relays
+            }
         }
         const filter = {
             authors: [hexPubkey],
@@ -100,47 +160,64 @@ export class NCC05Resolver {
             '#d': [identifier],
             limit: 10
         };
-        const queryPromise = this.pool.querySync(queryRelays, filter);
-        const timeoutPromise = new Promise((r) => setTimeout(() => r(null), this.timeout));
-        const result = await Promise.race([queryPromise, timeoutPromise]);
-        if (!result || (Array.isArray(result) && result.length === 0))
-            return null;
-        // 2. Filter for valid signatures, correct author, and sort by created_at
-        const validEvents = result
-            .filter(e => e.pubkey === hexPubkey && verifyEvent(e))
-            .sort((a, b) => b.created_at - a.created_at);
-        if (validEvents.length === 0)
-            return null;
-        const latestEvent = validEvents[0];
+        const sk = secretKey ? ensureUint8Array(secretKey) : undefined;
         try {
+            const queryPromise = this.pool.querySync(queryRelays, filter);
+            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new NCC05TimeoutError("Resolution timed out")), this.timeout));
+            const result = await Promise.race([queryPromise, timeoutPromise]);
+            if (!result || (Array.isArray(result) && result.length === 0))
+                return null;
+            // 2. Filter for valid signatures, correct author, and sort by created_at
+            const validEvents = result
+                .filter(e => e.pubkey === hexPubkey && verifyEvent(e))
+                .sort((a, b) => b.created_at - a.created_at);
+            if (validEvents.length === 0)
+                return null;
+            const latestEvent = validEvents[0];
             let content = latestEvent.content;
             // Security: Robust multi-recipient detection
             const isWrapped = content.includes('"wraps"') &&
                 content.includes('"ciphertext"') &&
                 content.startsWith('{');
-            if (isWrapped && secretKey) {
-                const wrapped = JSON.parse(content);
-                const myPk = getPublicKey(secretKey);
-                const myWrap = wrapped.wraps[myPk];
-                if (myWrap) {
-                    const conversationKey = nip44.getConversationKey(secretKey, hexPubkey);
-                    const symmetricKeyHex = nip44.decrypt(myWrap, conversationKey);
-                    // Convert hex symmetric key back to Uint8Array for NIP-44 decryption
-                    const symmetricKey = new Uint8Array(symmetricKeyHex.match(/.{1,2}/g).map(byte => parseInt(byte, 16)));
-                    const sessionConversationKey = nip44.getConversationKey(symmetricKey, getPublicKey(symmetricKey));
-                    content = nip44.decrypt(wrapped.ciphertext, sessionConversationKey);
+            if (isWrapped && sk) {
+                try {
+                    const wrapped = JSON.parse(content);
+                    const myPk = getPublicKey(sk);
+                    const myWrap = wrapped.wraps[myPk];
+                    if (myWrap) {
+                        const conversationKey = nip44.getConversationKey(sk, hexPubkey);
+                        const symmetricKeyHex = nip44.decrypt(myWrap, conversationKey);
+                        // Convert hex symmetric key back to Uint8Array for NIP-44 decryption
+                        const symmetricKey = new Uint8Array(symmetricKeyHex.match(/.{1,2}/g).map(byte => parseInt(byte, 16)));
+                        const sessionConversationKey = nip44.getConversationKey(symmetricKey, getPublicKey(symmetricKey));
+                        content = nip44.decrypt(wrapped.ciphertext, sessionConversationKey);
+                    }
+                    else {
+                        return null; // Not intended for us
+                    }
                 }
-                else {
-                    return null; // Not intended for us
+                catch (_e) {
+                    throw new NCC05DecryptionError("Failed to decrypt wrapped content");
                 }
             }
-            else if (secretKey && !content.startsWith('{')) {
+            else if (sk && !content.startsWith('{')) {
                 // Standard NIP-44 (likely encrypted if not starting with {)
-                const conversationKey = nip44.getConversationKey(secretKey, hexPubkey);
-                content = nip44.decrypt(latestEvent.content, conversationKey);
+                try {
+                    const conversationKey = nip44.getConversationKey(sk, hexPubkey);
+                    content = nip44.decrypt(latestEvent.content, conversationKey);
+                }
+                catch (_e) {
+                    throw new NCC05DecryptionError("Failed to decrypt content");
+                }
             }
             // Security: Safe JSON parsing
-            const payload = JSON.parse(content);
+            let payload;
+            try {
+                payload = JSON.parse(content);
+            }
+            catch (_e) {
+                return null; // Invalid JSON
+            }
             if (!payload || !payload.endpoints || !Array.isArray(payload.endpoints)) {
                 return null;
             }
@@ -154,14 +231,18 @@ export class NCC05Resolver {
             return payload;
         }
         catch (e) {
-            return null; // Decryption or parsing failed
+            if (e instanceof NCC05Error)
+                throw e;
+            throw new NCC05RelayError(`Relay query failed: ${e.message}`);
         }
     }
     /**
-     * Closes connections to all relays in the pool.
+     * Closes connections to all relays in the pool if managed internally.
      */
     close() {
-        this.pool.close(this.bootstrapRelays);
+        if (this._ownPool) {
+            this.pool.close(this.bootstrapRelays);
+        }
     }
 }
 /**
@@ -169,15 +250,53 @@ export class NCC05Resolver {
  */
 export class NCC05Publisher {
     pool;
+    _ownPool;
+    timeout;
     /**
      * @param options - Configuration for the publisher.
      */
     constructor(options = {}) {
-        this.pool = new SimplePool();
-        if (options.websocketImplementation) {
-            // @ts-ignore
-            this.pool.websocketImplementation = options.websocketImplementation;
+        this._ownPool = !options.pool;
+        this.pool = options.pool || new SimplePool();
+        if (this._ownPool) {
+            if (options.websocketImplementation) {
+                // @ts-ignore
+                this.pool.websocketImplementation = options.websocketImplementation;
+            }
+            else if (typeof WebSocket === 'undefined' && typeof globalThis !== 'undefined' && globalThis.WebSocket) {
+                // @ts-ignore
+                this.pool.websocketImplementation = globalThis.WebSocket;
+            }
         }
+        this.timeout = options.timeout || 5000;
+    }
+    async _publishToRelays(relays, signedEvent) {
+        const publishPromises = this.pool.publish(relays, signedEvent);
+        // Convert to promise that resolves/rejects based on timeout
+        const wrappedPromises = publishPromises.map(p => {
+            // In nostr-tools v2, publish returns Promise<void>. 
+            // We wrap it to handle timeout.
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => reject(new NCC05TimeoutError("Publish timed out")), this.timeout);
+                p.then(() => {
+                    clearTimeout(timer);
+                    resolve();
+                }).catch((err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                });
+            });
+        });
+        const results = await Promise.allSettled(wrappedPromises);
+        const successful = results.filter(r => r.status === 'fulfilled');
+        if (successful.length === 0) {
+            const errors = results
+                .filter(r => r.status === 'rejected')
+                .map(r => r.reason.message)
+                .join(', ');
+            throw new NCC05RelayError(`Failed to publish to any relay. Errors: ${errors}`);
+        }
+        // If partial success, we consider it a success.
     }
     /**
      * Publishes a single record encrypted for multiple recipients using the wrapping pattern.
@@ -191,13 +310,14 @@ export class NCC05Publisher {
      * @returns The signed Nostr event.
      */
     async publishWrapped(relays, secretKey, recipients, payload, identifier = 'addr') {
+        const sk = ensureUint8Array(secretKey);
         const sessionKey = generateSecretKey();
         const sessionKeyHex = Array.from(sessionKey).map(b => b.toString(16).padStart(2, '0')).join('');
         const selfConversation = nip44.getConversationKey(sessionKey, getPublicKey(sessionKey));
         const ciphertext = nip44.encrypt(JSON.stringify(payload), selfConversation);
         const wraps = {};
         for (const rPk of recipients) {
-            const conversationKey = nip44.getConversationKey(secretKey, rPk);
+            const conversationKey = nip44.getConversationKey(sk, rPk);
             wraps[rPk] = nip44.encrypt(sessionKeyHex, conversationKey);
         }
         const wrappedContent = { ciphertext, wraps };
@@ -207,8 +327,8 @@ export class NCC05Publisher {
             tags: [['d', identifier]],
             content: JSON.stringify(wrappedContent),
         };
-        const signedEvent = finalizeEvent(eventTemplate, secretKey);
-        await Promise.all(this.pool.publish(relays, signedEvent));
+        const signedEvent = finalizeEvent(eventTemplate, sk);
+        await this._publishToRelays(relays, signedEvent);
         return signedEvent;
     }
     /**
@@ -221,12 +341,13 @@ export class NCC05Publisher {
      * @returns The signed Nostr event.
      */
     async publish(relays, secretKey, payload, options = {}) {
-        const myPubkey = getPublicKey(secretKey);
+        const sk = ensureUint8Array(secretKey);
+        const myPubkey = getPublicKey(sk);
         const identifier = options.identifier || 'addr';
         let content = JSON.stringify(payload);
         if (!options.public) {
             const encryptionTarget = options.recipientPubkey || myPubkey;
-            const conversationKey = nip44.getConversationKey(secretKey, encryptionTarget);
+            const conversationKey = nip44.getConversationKey(sk, encryptionTarget);
             content = nip44.encrypt(content, conversationKey);
         }
         const eventTemplate = {
@@ -236,14 +357,16 @@ export class NCC05Publisher {
             tags: [['d', identifier]],
             content: content,
         };
-        const signedEvent = finalizeEvent(eventTemplate, secretKey);
-        await Promise.all(this.pool.publish(relays, signedEvent));
+        const signedEvent = finalizeEvent(eventTemplate, sk);
+        await this._publishToRelays(relays, signedEvent);
         return signedEvent;
     }
     /**
-     * Closes connections to the specified relays.
+     * Closes connections to the specified relays if managed internally.
      */
     close(relays) {
-        this.pool.close(relays);
+        if (this._ownPool) {
+            this.pool.close(relays);
+        }
     }
 }

package/dist/test-lifecycle.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test-lifecycle.js

@@ -0,0 +1,33 @@
+import { NCC05Resolver } from './index.js';
+import { SimplePool } from 'nostr-tools';
+async function testLifecycle() {
+    console.log('--- Starting Lifecycle Test ---');
+    // 1. Internal Pool Management
+    console.log('Test 1: Internal Pool (should close)');
+    const resolverInternal = new NCC05Resolver();
+    // @ts-ignore - Access private property for testing or infer from behavior
+    const internalPool = resolverInternal['pool'];
+    internalPool.close = (_relays) => {
+        console.log('Internal pool close called.');
+    };
+    resolverInternal.close(); // Should log
+    // 2. Shared Pool Management
+    console.log('Test 2: Shared Pool (should NOT close)');
+    const sharedPool = new SimplePool();
+    let sharedClosed = false;
+    sharedPool.close = (_relays) => {
+        sharedClosed = true;
+        console.error('ERROR: Shared pool was closed!');
+    };
+    const resolverShared = new NCC05Resolver({ pool: sharedPool });
+    resolverShared.close(); // Should NOT close sharedPool
+    if (!sharedClosed) {
+        console.log('Shared pool correctly remained open.');
+    }
+    else {
+        process.exit(1);
+    }
+    console.log('Lifecycle Test Suite Passed.');
+    process.exit(0);
+}
+testLifecycle().catch(console.error);

package/dist/test-new.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test-new.js

@@ -0,0 +1,94 @@
+import { NCC05Publisher, NCC05Resolver, NCC05TimeoutError } from './index.js';
+import { generateSecretKey, getPublicKey, SimplePool } from 'nostr-tools';
+import { MockRelay } from './mock-relay.js';
+import { WebSocketServer } from 'ws';
+async function testNewFeatures() {
+    console.log('--- Starting New Features Test ---');
+    const relayPort = 8081;
+    const relayUrl = `ws://localhost:${relayPort}`;
+    const relay = new MockRelay(relayPort);
+    // 1. External SimplePool & Hex Keys
+    console.log('Test 1: External SimplePool & Hex Keys');
+    const pool = new SimplePool();
+    const publisher = new NCC05Publisher({ pool });
+    const resolver = new NCC05Resolver({ bootstrapRelays: [relayUrl], pool });
+    const sk = generateSecretKey();
+    const pk = getPublicKey(sk);
+    const skHex = Array.from(sk).map(b => b.toString(16).padStart(2, '0')).join('');
+    const payload = {
+        v: 1, ttl: 60, updated_at: Math.floor(Date.now() / 1000),
+        endpoints: [{ type: 'tcp', uri: 'hex-test', priority: 1, family: 'ipv4' }]
+    };
+    try {
+        // Publish using HEX string secret key
+        await publisher.publish([relayUrl], skHex, payload, { identifier: 'hex-key' });
+        console.log('Published with Hex Key: OK');
+    }
+    catch (e) {
+        console.error('Failed to publish with hex key:', e);
+        process.exit(1);
+    }
+    try {
+        // Resolve using Hex string secret key
+        const res = await resolver.resolve(pk, skHex, 'hex-key');
+        if (res && res.endpoints[0].uri === 'hex-test') {
+            console.log('Resolved with Hex Key: OK');
+        }
+        else {
+            console.error('Failed to resolve with hex key');
+            process.exit(1);
+        }
+    }
+    catch (e) {
+        console.error('Resolution error:', e);
+        process.exit(1);
+    }
+    // 2. Graceful Degradation
+    console.log('Test 2: Graceful Degradation (One bad relay)');
+    const badRelay = 'ws://localhost:9999'; // assuming closed/unreachable
+    try {
+        // Should succeed because one relay is good
+        await publisher.publish([relayUrl, badRelay], sk, payload, { identifier: 'graceful' });
+        console.log('Graceful degradation publish: OK');
+    }
+    catch (e) {
+        console.error('Graceful degradation failed:', e);
+        process.exit(1);
+    }
+    // 3. Timeout
+    console.log('Test 3: Resolver Timeout');
+    // Create a "Hanging Relay" that accepts connection but sends no data
+    const hangingPort = 8082;
+    const wss = new WebSocketServer({ port: hangingPort });
+    const timeoutResolver = new NCC05Resolver({
+        bootstrapRelays: [`ws://localhost:${hangingPort}`],
+        timeout: 500 // 500ms
+    });
+    const start = Date.now();
+    try {
+        await timeoutResolver.resolve(pk, sk, 'any');
+        console.error('Should have timed out!');
+        wss.close();
+        process.exit(1);
+    }
+    catch (e) {
+        const duration = Date.now() - start;
+        if (e instanceof NCC05TimeoutError) {
+            console.log(`Timed out as expected in ${duration}ms: OK`);
+        }
+        else {
+            console.error('Caught unexpected error:', e);
+            // It might be that SimplePool fails connection before timeout if it's super fast,
+            // but WebSocketServer is listening.
+        }
+    }
+    finally {
+        wss.close();
+    }
+    relay.stop();
+    pool.close([relayUrl]);
+    timeoutResolver.close();
+    console.log('New Features Test Suite Passed.');
+    process.exit(0);
+}
+testNewFeatures().catch(console.error);

package/eslint.config.mjs

@@ -0,0 +1,25 @@
+import globals from "globals";
+import pluginJs from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default [
+  {files: ["**/*.{js,mjs,cjs,ts}"]},
+  {languageOptions: { globals: globals.node }},
+  pluginJs.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+      rules: {
+          "@typescript-eslint/no-explicit-any": "off",
+          "@typescript-eslint/ban-ts-comment": "off",
+          "@typescript-eslint/no-unused-vars": ["warn", { 
+              "argsIgnorePattern": "^_",
+              "varsIgnorePattern": "^_",
+              "caughtErrorsIgnorePattern": "^_"
+          }],
+          "no-console": "off"
+      }
+  },
+  {
+      ignores: ["dist/", "node_modules/"]
+  }
+];

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "ncc-05",
-  "version": "1.1.4",
+  "version": "1.1.7",
   "description": "Nostr Community Convention 05 - Identity-Bound Service Locator Resolution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
   "scripts": {
     "build": "tsc",
+    "lint": "eslint src/**/*.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -22,9 +23,15 @@
     "nostr-tools": "^2.10.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.2",
     "@types/node": "^25.0.3",
     "@types/ws": "^8.18.1",
+    "@typescript-eslint/eslint-plugin": "^8.50.1",
+    "@typescript-eslint/parser": "^8.50.1",
+    "eslint": "^9.39.2",
+    "globals": "^16.5.0",
     "typescript": "^5.0.0",
+    "typescript-eslint": "^8.50.1",
     "ws": "^8.18.3"
   }
 }

package/src/index.ts

@@ -18,6 +18,57 @@ import {
     generateSecretKey
 } from 'nostr-tools';
 
+// --- Error Classes ---
+
+export class NCC05Error extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'NCC05Error';
+    }
+}
+
+export class NCC05RelayError extends NCC05Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'NCC05RelayError';
+    }
+}
+
+export class NCC05TimeoutError extends NCC05Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'NCC05TimeoutError';
+    }
+}
+
+export class NCC05DecryptionError extends NCC05Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'NCC05DecryptionError';
+    }
+}
+
+export class NCC05ArgumentError extends NCC05Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'NCC05ArgumentError';
+    }
+}
+
+// --- Helpers ---
+
+function ensureUint8Array(key: string | Uint8Array): Uint8Array {
+    if (key instanceof Uint8Array) return key;
+    if (typeof key === 'string') {
+        // Assume hex string
+        if (key.match(/^[0-9a-fA-F]+$/)) {
+             return new Uint8Array(key.match(/.{1,2}/g)!.map(byte => parseInt(byte, 16)));
+        }
+        throw new NCC05ArgumentError("Invalid hex key provided");
+    }
+    throw new NCC05ArgumentError("Key must be a hex string or Uint8Array");
+}
+
 /**
  * Represents a single reachable service endpoint.
  */
@@ -60,6 +111,20 @@ export interface ResolverOptions {
     timeout?: number;
     /** Custom WebSocket implementation (e.g., for Tor/SOCKS5 in Node.js) */
     websocketImplementation?: any;
+    /** Existing SimplePool instance to share connections */
+    pool?: SimplePool;
+}
+
+/**
+ * Options for configuring the NCC05Publisher.
+ */
+export interface PublisherOptions {
+    /** Custom WebSocket implementation */
+    websocketImplementation?: any;
+    /** Existing SimplePool instance */
+    pool?: SimplePool;
+    /** Timeout for publishing in milliseconds (default: 5000) */
+    timeout?: number;
 }
 
 /**
@@ -106,7 +171,7 @@ export class NCC05Group {
     static async resolveAsGroup(
         resolver: NCC05Resolver,
         groupPubkey: string,
-        groupSecretKey: Uint8Array,
+        groupSecretKey: string | Uint8Array,
         identifier: string = 'addr'
     ): Promise<NCC05Payload | null> {
         return resolver.resolve(groupPubkey, groupSecretKey, identifier);
@@ -118,6 +183,7 @@ export class NCC05Group {
  */
 export class NCC05Resolver {
     private pool: SimplePool;
+    private _ownPool: boolean;
     private bootstrapRelays: string[];
     private timeout: number;
 
@@ -125,11 +191,19 @@ export class NCC05Resolver {
      * @param options - Configuration for the resolver.
      */
     constructor(options: ResolverOptions = {}) {
-        this.pool = new SimplePool();
-        if (options.websocketImplementation) {
-            // @ts-ignore - Patching pool for custom transport
-            this.pool.websocketImplementation = options.websocketImplementation;
+        this._ownPool = !options.pool;
+        this.pool = options.pool || new SimplePool();
+        
+        if (this._ownPool) {
+            if (options.websocketImplementation) {
+                // @ts-ignore - Patching pool for custom transport
+                this.pool.websocketImplementation = options.websocketImplementation;
+            } else if (typeof WebSocket === 'undefined' && typeof globalThis !== 'undefined' && globalThis.WebSocket) {
+                 // @ts-ignore
+                 this.pool.websocketImplementation = globalThis.WebSocket;
+            }
         }
+
         this.bootstrapRelays = options.bootstrapRelays || ['wss://relay.damus.io', 'wss://nos.lol'];
         this.timeout = options.timeout || 10000;
     }
@@ -144,11 +218,13 @@ export class NCC05Resolver {
      * @param secretKey - Your secret key (required if the record is encrypted).
      * @param identifier - The 'd' tag of the record (default: 'addr').
      * @param options - Resolution options (strict mode, gossip discovery).
-     * @returns The resolved and validated NCC05Payload, or null if not found/invalid.
+     * @returns The resolved and validated NCC05Payload, or null if not found.
+     * @throws {NCC05TimeoutError} if resolution times out.
+     * @throws {NCC05RelayError} if underlying relay communication fails.
      */
     async resolve(
         targetPubkey: string, 
-        secretKey?: Uint8Array, 
+        secretKey?: string | Uint8Array, 
         identifier: string = 'addr',
         options: { strict?: boolean, gossip?: boolean } = {}
     ): Promise<NCC05Payload | null> {
@@ -162,18 +238,23 @@ export class NCC05Resolver {
 
         // 1. NIP-65 Gossip Discovery
         if (options.gossip) {
-            const relayListEvent = await this.pool.get(this.bootstrapRelays, {
-                authors: [hexPubkey],
-                kinds: [10002]
-            });
-            // Security: Verify NIP-65 event signature and author
-            if (relayListEvent && verifyEvent(relayListEvent) && relayListEvent.pubkey === hexPubkey) {
-                const discoveredRelays = relayListEvent.tags
-                    .filter(t => t[0] === 'r')
-                    .map(t => t[1]);
-                if (discoveredRelays.length > 0) {
-                    queryRelays = [...new Set([...queryRelays, ...discoveredRelays])];
+            try {
+                const relayListEvent = await this.pool.get(this.bootstrapRelays, {
+                    authors: [hexPubkey],
+                    kinds: [10002]
+                });
+                // Security: Verify NIP-65 event signature and author
+                if (relayListEvent && verifyEvent(relayListEvent) && relayListEvent.pubkey === hexPubkey) {
+                    const discoveredRelays = relayListEvent.tags
+                        .filter(t => t[0] === 'r')
+                        .map(t => t[1]);
+                    if (discoveredRelays.length > 0) {
+                        queryRelays = [...new Set([...queryRelays, ...discoveredRelays])];
+                    }
                 }
+            } catch (e: any) {
+                console.warn(`[NCC-05] Gossip discovery failed: ${e.message}`);
+                // Proceed with bootstrap relays
             }
         }
 
@@ -184,21 +265,26 @@ export class NCC05Resolver {
             limit: 10
         };
 
-        const queryPromise = this.pool.querySync(queryRelays, filter);
-        const timeoutPromise = new Promise<null>((r) => setTimeout(() => r(null), this.timeout));
-        const result = await Promise.race([queryPromise, timeoutPromise]);
-        
-        if (!result || (Array.isArray(result) && result.length === 0)) return null;
-        
-        // 2. Filter for valid signatures, correct author, and sort by created_at
-        const validEvents = (result as Event[])
-            .filter(e => e.pubkey === hexPubkey && verifyEvent(e))
-            .sort((a, b) => b.created_at - a.created_at);
-
-        if (validEvents.length === 0) return null;
-        const latestEvent = validEvents[0];
+        const sk = secretKey ? ensureUint8Array(secretKey) : undefined;
 
         try {
+            const queryPromise = this.pool.querySync(queryRelays, filter);
+            const timeoutPromise = new Promise<never>((_, reject) => 
+                setTimeout(() => reject(new NCC05TimeoutError("Resolution timed out")), this.timeout)
+            );
+            
+            const result = await Promise.race([queryPromise, timeoutPromise]);
+            
+            if (!result || (Array.isArray(result) && result.length === 0)) return null;
+            
+            // 2. Filter for valid signatures, correct author, and sort by created_at
+            const validEvents = (result as Event[])
+                .filter(e => e.pubkey === hexPubkey && verifyEvent(e))
+                .sort((a, b) => b.created_at - a.created_at);
+
+            if (validEvents.length === 0) return null;
+            const latestEvent = validEvents[0];
+
             let content = latestEvent.content;
             
             // Security: Robust multi-recipient detection
@@ -206,35 +292,49 @@ export class NCC05Resolver {
                              content.includes('"ciphertext"') && 
                              content.startsWith('{');
 
-            if (isWrapped && secretKey) {
-                const wrapped = JSON.parse(content) as WrappedContent;
-                const myPk = getPublicKey(secretKey);
-                const myWrap = wrapped.wraps[myPk];
-                
-                if (myWrap) {
-                    const conversationKey = nip44.getConversationKey(secretKey, hexPubkey);
-                    const symmetricKeyHex = nip44.decrypt(myWrap, conversationKey);
+            if (isWrapped && sk) {
+                try {
+                    const wrapped = JSON.parse(content) as WrappedContent;
+                    const myPk = getPublicKey(sk);
+                    const myWrap = wrapped.wraps[myPk];
                     
-                    // Convert hex symmetric key back to Uint8Array for NIP-44 decryption
-                    const symmetricKey = new Uint8Array(
-                        symmetricKeyHex.match(/.{1,2}/g)!.map(byte => parseInt(byte, 16))
-                    );
-                    
-                    const sessionConversationKey = nip44.getConversationKey(
-                        symmetricKey, getPublicKey(symmetricKey)
-                    );
-                    content = nip44.decrypt(wrapped.ciphertext, sessionConversationKey);
-                } else {
-                    return null; // Not intended for us
+                    if (myWrap) {
+                        const conversationKey = nip44.getConversationKey(sk, hexPubkey);
+                        const symmetricKeyHex = nip44.decrypt(myWrap, conversationKey);
+                        
+                        // Convert hex symmetric key back to Uint8Array for NIP-44 decryption
+                        const symmetricKey = new Uint8Array(
+                            symmetricKeyHex.match(/.{1,2}/g)!.map(byte => parseInt(byte, 16))
+                        );
+                        
+                        const sessionConversationKey = nip44.getConversationKey(
+                            symmetricKey, getPublicKey(symmetricKey)
+                        );
+                        content = nip44.decrypt(wrapped.ciphertext, sessionConversationKey);
+                    } else {
+                        return null; // Not intended for us
+                    }
+                } catch (_e) {
+                    throw new NCC05DecryptionError("Failed to decrypt wrapped content");
                 }
-            } else if (secretKey && !content.startsWith('{')) {
+            } else if (sk && !content.startsWith('{')) {
                 // Standard NIP-44 (likely encrypted if not starting with {)
-                const conversationKey = nip44.getConversationKey(secretKey, hexPubkey);
-                content = nip44.decrypt(latestEvent.content, conversationKey);
+                try {
+                    const conversationKey = nip44.getConversationKey(sk, hexPubkey);
+                    content = nip44.decrypt(latestEvent.content, conversationKey);
+                } catch (_e) {
+                     throw new NCC05DecryptionError("Failed to decrypt content");
+                }
             }
 
             // Security: Safe JSON parsing
-            const payload = JSON.parse(content) as NCC05Payload;
+            let payload: NCC05Payload;
+            try {
+                payload = JSON.parse(content) as NCC05Payload;
+            } catch (_e) {
+                return null; // Invalid JSON
+            }
+
             if (!payload || !payload.endpoints || !Array.isArray(payload.endpoints)) {
                 return null;
             }
@@ -248,15 +348,18 @@ export class NCC05Resolver {
 
             return payload;
         } catch (e) {
-            return null; // Decryption or parsing failed
+            if (e instanceof NCC05Error) throw e;
+            throw new NCC05RelayError(`Relay query failed: ${(e as Error).message}`);
         }
     }
 
     /**
-     * Closes connections to all relays in the pool.
+     * Closes connections to all relays in the pool if managed internally.
      */
     close() {
-        this.pool.close(this.bootstrapRelays);
+        if (this._ownPool) {
+            this.pool.close(this.bootstrapRelays);
+        }
     }
 }
 
@@ -265,16 +368,60 @@ export class NCC05Resolver {
  */
 export class NCC05Publisher {
     private pool: SimplePool;
+    private _ownPool: boolean;
+    private timeout: number;
 
     /**
      * @param options - Configuration for the publisher.
      */
-    constructor(options: { websocketImplementation?: any } = {}) {
-        this.pool = new SimplePool();
-        if (options.websocketImplementation) {
-            // @ts-ignore
-            this.pool.websocketImplementation = options.websocketImplementation;
+    constructor(options: PublisherOptions = {}) {
+        this._ownPool = !options.pool;
+        this.pool = options.pool || new SimplePool();
+        
+        if (this._ownPool) {
+            if (options.websocketImplementation) {
+                // @ts-ignore
+                this.pool.websocketImplementation = options.websocketImplementation;
+            } else if (typeof WebSocket === 'undefined' && typeof globalThis !== 'undefined' && globalThis.WebSocket) {
+                // @ts-ignore
+                this.pool.websocketImplementation = globalThis.WebSocket;
+            }
         }
+        
+        this.timeout = options.timeout || 5000;
+    }
+
+    private async _publishToRelays(relays: string[], signedEvent: Event): Promise<void> {
+        const publishPromises = this.pool.publish(relays, signedEvent);
+        
+        // Convert to promise that resolves/rejects based on timeout
+        const wrappedPromises = publishPromises.map(p => {
+             // In nostr-tools v2, publish returns Promise<void>. 
+             // We wrap it to handle timeout.
+             return new Promise<void>((resolve, reject) => {
+                 const timer = setTimeout(() => reject(new NCC05TimeoutError("Publish timed out")), this.timeout);
+                 p.then(() => {
+                     clearTimeout(timer);
+                     resolve();
+                 }).catch((err) => {
+                     clearTimeout(timer);
+                     reject(err);
+                 });
+             });
+        });
+
+        const results = await Promise.allSettled(wrappedPromises);
+        const successful = results.filter(r => r.status === 'fulfilled');
+        
+        if (successful.length === 0) {
+            const errors = results
+                .filter(r => r.status === 'rejected')
+                .map(r => (r as PromiseRejectedResult).reason.message)
+                .join(', ');
+            throw new NCC05RelayError(`Failed to publish to any relay. Errors: ${errors}`);
+        }
+        
+        // If partial success, we consider it a success.
     }
 
     /**
@@ -290,11 +437,12 @@ export class NCC05Publisher {
      */
     async publishWrapped(
         relays: string[],
-        secretKey: Uint8Array,
+        secretKey: string | Uint8Array,
         recipients: string[],
         payload: NCC05Payload,
         identifier: string = 'addr'
     ): Promise<Event> {
+        const sk = ensureUint8Array(secretKey);
         const sessionKey = generateSecretKey();
         const sessionKeyHex = Array.from(sessionKey).map(b => b.toString(16).padStart(2, '0')).join('');
         
@@ -303,7 +451,7 @@ export class NCC05Publisher {
 
         const wraps: Record<string, string> = {};
         for (const rPk of recipients) {
-            const conversationKey = nip44.getConversationKey(secretKey, rPk);
+            const conversationKey = nip44.getConversationKey(sk, rPk);
             wraps[rPk] = nip44.encrypt(sessionKeyHex, conversationKey);
         }
 
@@ -316,8 +464,8 @@ export class NCC05Publisher {
             content: JSON.stringify(wrappedContent),
         };
 
-        const signedEvent = finalizeEvent(eventTemplate, secretKey);
-        await Promise.all(this.pool.publish(relays, signedEvent));
+        const signedEvent = finalizeEvent(eventTemplate, sk);
+        await this._publishToRelays(relays, signedEvent);
         return signedEvent;
     }
 
@@ -332,17 +480,18 @@ export class NCC05Publisher {
      */
     async publish(
         relays: string[],
-        secretKey: Uint8Array,
+        secretKey: string | Uint8Array,
         payload: NCC05Payload,
         options: { identifier?: string, recipientPubkey?: string, public?: boolean } = {}
     ): Promise<Event> {
-        const myPubkey = getPublicKey(secretKey);
+        const sk = ensureUint8Array(secretKey);
+        const myPubkey = getPublicKey(sk);
         const identifier = options.identifier || 'addr';
         let content = JSON.stringify(payload);
 
         if (!options.public) {
             const encryptionTarget = options.recipientPubkey || myPubkey;
-            const conversationKey = nip44.getConversationKey(secretKey, encryptionTarget);
+            const conversationKey = nip44.getConversationKey(sk, encryptionTarget);
             content = nip44.encrypt(content, conversationKey);
         }
 
@@ -354,15 +503,17 @@ export class NCC05Publisher {
             content: content,
         };
 
-        const signedEvent = finalizeEvent(eventTemplate, secretKey);
-        await Promise.all(this.pool.publish(relays, signedEvent));
+        const signedEvent = finalizeEvent(eventTemplate, sk);
+        await this._publishToRelays(relays, signedEvent);
         return signedEvent;
     }
 
     /**
-     * Closes connections to the specified relays.
+     * Closes connections to the specified relays if managed internally.
      */
     close(relays: string[]) {
-        this.pool.close(relays);
+        if (this._ownPool) {
+            this.pool.close(relays);
+        }
     }
 }

package/src/test-lifecycle.ts

@@ -0,0 +1,40 @@
+import { NCC05Resolver } from './index.js';
+import { SimplePool } from 'nostr-tools';
+
+async function testLifecycle() {
+    console.log('--- Starting Lifecycle Test ---');
+    
+    // 1. Internal Pool Management
+    console.log('Test 1: Internal Pool (should close)');
+    const resolverInternal = new NCC05Resolver();
+    // @ts-ignore - Access private property for testing or infer from behavior
+    const internalPool = resolverInternal['pool'];
+    internalPool.close = (_relays?: string[]) => {
+        console.log('Internal pool close called.');
+    };
+    
+    resolverInternal.close(); // Should log
+
+    // 2. Shared Pool Management
+    console.log('Test 2: Shared Pool (should NOT close)');
+    const sharedPool = new SimplePool();
+    let sharedClosed = false;
+    sharedPool.close = (_relays?: string[]) => {
+        sharedClosed = true;
+        console.error('ERROR: Shared pool was closed!');
+    };
+
+    const resolverShared = new NCC05Resolver({ pool: sharedPool });
+    resolverShared.close(); // Should NOT close sharedPool
+
+    if (!sharedClosed) {
+        console.log('Shared pool correctly remained open.');
+    } else {
+        process.exit(1);
+    }
+    
+    console.log('Lifecycle Test Suite Passed.');
+    process.exit(0);
+}
+
+testLifecycle().catch(console.error);

package/src/test-new.ts

@@ -0,0 +1,99 @@
+import { NCC05Publisher, NCC05Resolver, NCC05Payload, NCC05TimeoutError } from './index.js';
+import { generateSecretKey, getPublicKey, SimplePool } from 'nostr-tools';
+import { MockRelay } from './mock-relay.js';
+import { WebSocketServer } from 'ws';
+
+async function testNewFeatures() {
+    console.log('--- Starting New Features Test ---');
+    const relayPort = 8081;
+    const relayUrl = `ws://localhost:${relayPort}`;
+    const relay = new MockRelay(relayPort);
+    
+    // 1. External SimplePool & Hex Keys
+    console.log('Test 1: External SimplePool & Hex Keys');
+    const pool = new SimplePool();
+    const publisher = new NCC05Publisher({ pool });
+    const resolver = new NCC05Resolver({ bootstrapRelays: [relayUrl], pool });
+
+    const sk = generateSecretKey();
+    const pk = getPublicKey(sk);
+    const skHex = Array.from(sk).map(b => b.toString(16).padStart(2, '0')).join('');
+
+    const payload: NCC05Payload = {
+        v: 1, ttl: 60, updated_at: Math.floor(Date.now() / 1000),
+        endpoints: [{ type: 'tcp', uri: 'hex-test', priority: 1, family: 'ipv4' }]
+    };
+
+    try {
+        // Publish using HEX string secret key
+        await publisher.publish([relayUrl], skHex, payload, { identifier: 'hex-key' });
+        console.log('Published with Hex Key: OK');
+    } catch (e) {
+        console.error('Failed to publish with hex key:', e);
+        process.exit(1);
+    }
+
+    try {
+        // Resolve using Hex string secret key
+        const res = await resolver.resolve(pk, skHex, 'hex-key');
+        if (res && res.endpoints[0].uri === 'hex-test') {
+            console.log('Resolved with Hex Key: OK');
+        } else {
+            console.error('Failed to resolve with hex key');
+            process.exit(1);
+        }
+    } catch (e) {
+        console.error('Resolution error:', e);
+        process.exit(1);
+    }
+
+    // 2. Graceful Degradation
+    console.log('Test 2: Graceful Degradation (One bad relay)');
+    const badRelay = 'ws://localhost:9999'; // assuming closed/unreachable
+    try {
+        // Should succeed because one relay is good
+        await publisher.publish([relayUrl, badRelay], sk, payload, { identifier: 'graceful' });
+        console.log('Graceful degradation publish: OK');
+    } catch (e) {
+        console.error('Graceful degradation failed:', e);
+        process.exit(1);
+    }
+
+    // 3. Timeout
+    console.log('Test 3: Resolver Timeout');
+    // Create a "Hanging Relay" that accepts connection but sends no data
+    const hangingPort = 8082;
+    const wss = new WebSocketServer({ port: hangingPort });
+    
+    const timeoutResolver = new NCC05Resolver({ 
+        bootstrapRelays: [`ws://localhost:${hangingPort}`],
+        timeout: 500 // 500ms
+    });
+    
+    const start = Date.now();
+    try {
+        await timeoutResolver.resolve(pk, sk, 'any');
+        console.error('Should have timed out!');
+        wss.close();
+        process.exit(1);
+    } catch (e) {
+        const duration = Date.now() - start;
+        if (e instanceof NCC05TimeoutError) {
+            console.log(`Timed out as expected in ${duration}ms: OK`);
+        } else {
+            console.error('Caught unexpected error:', e);
+            // It might be that SimplePool fails connection before timeout if it's super fast,
+            // but WebSocketServer is listening.
+        }
+    } finally {
+        wss.close();
+    }
+
+    relay.stop();
+    pool.close([relayUrl]); 
+    timeoutResolver.close();
+    console.log('New Features Test Suite Passed.');
+    process.exit(0);
+}
+
+testNewFeatures().catch(console.error);