ncc-05 1.1.1 → 1.1.3

package/README.md

@@ -1,8 +1,17 @@
 # ncc-05
 
-Nostr Community Convention 05 - Identity-Bound Service Locator Resolution.
+**Nostr Community Convention 05 - Identity-Bound Service Locator Resolution.**
 
-This library provides a simple way to publish and resolve identity-bound service endpoints (IP/Port/Onion) using Nostr `kind:30058` events.
+A TypeScript library for publishing and resolving dynamic, encrypted service endpoints (IP, Port, Onion) bound to cryptographic identities using Nostr `kind:30058` events.
+
+## Features
+
+- **Identity-Centric**: Endpoints are bound to a Nostr Pubkey.
+- **Privacy-First**: NIP-44 encryption is mandatory by default.
+- **Multi-Recipient Support**: Implement "Wrapping" patterns to share endpoints with groups without sharing private keys.
+- **NIP-65 Gossip**: Built-in support for discovering a publisher's preferred relays.
+- **Tor Ready**: Easy integration with SOCKS5 proxies for anonymous resolution.
+- **Type Safe**: Fully typed with TypeScript.
 
 ## Installation
 
@@ -12,7 +21,7 @@ npm install ncc-05
 
 ## Usage
 
-### Resolver
+### 1. Basic Resolution (Self or Public)
 
 Resolve an identity-bound service locator for a given pubkey.
 
@@ -22,65 +31,62 @@ import { nip19 } from 'nostr-tools';
 
 const resolver = new NCC05Resolver();
 
-// Your secret key is needed to decrypt the record (NIP-44)
-const mySecretKey = nip19.decode('nsec...').data as Uint8Array;
-const targetPubkey = '...'; 
+// Resolve using an npub (or hex pubkey)
+const target = 'npub1...';
+const mySecretKey = ...; // Uint8Array needed for encrypted records
 
-const payload = await resolver.resolve(targetPubkey, mySecretKey);
+const payload = await resolver.resolve(target, mySecretKey, 'addr', { 
+    gossip: true, // Follow NIP-65 hints
+    strict: true  // Reject expired records
+});
 
 if (payload) {
-    console.log('Resolved Endpoints:');
-    payload.endpoints.forEach(ep => {
-        console.log(`- ${ep.type}://${ep.uri} (${ep.family})`);
-    });
+    console.log('Resolved Endpoints:', payload.endpoints);
 }
 ```
 
-### Publisher
+### 2. Targeted Encryption (Friend-to-Friend)
 
-Publish your own service locator record.
+Alice publishes a record that only Bob can decrypt.
 
 ```typescript
-import { NCC05Publisher, NCC05Payload } from 'ncc-05';
+import { NCC05Publisher } from 'ncc-05';
 
 const publisher = new NCC05Publisher();
-const mySecretKey = ...;
-
-const payload: NCC05Payload = {
-    v: 1,
-    ttl: 600,
-    updated_at: Math.floor(Date.now() / 1000),
-    endpoints: [
-        {
-            type: 'tcp',
-            uri: '127.0.0.1:8080',
-            priority: 10,
-            family: 'ipv4'
-        }
-    ]
-};
-
-const relays = ['wss://relay.damus.io', 'wss://nos.lol'];
-await publisher.publish(relays, mySecretKey, payload);
+const AliceSK = ...;
+const BobPK = "..."; // Bob's hex pubkey
+
+await publisher.publish(relays, AliceSK, payload, {
+    identifier: 'for-bob',
+    recipientPubkey: BobPK // Encrypts specifically for Bob
+});
 ```
 
-## Features
+### 3. Group Wrapping (One Event, Many Recipients)
 
-- **NIP-44 Encryption**: All locator records are encrypted by default.
-- **NIP-01/NIP-33**: Uses standard Nostr primitives.
-- **Identity-Centric**: Resolution is bound to a cryptographic identity (Pubkey).
-- **Tor/Proxy Support**: Easily route relay traffic through SOCKS5 in Node.js.
+Alice shares her endpoint with a list of authorized friends in a single event.
 
-## Tor & Privacy (Node.js)
+```typescript
+await publisher.publishWrapped(
+    relays, 
+    AliceSK, 
+    [BobPK, CharliePK, DavePK], 
+    payload, 
+    'private-group'
+);
+
+// Bob resolves it using his own key:
+const payload = await resolver.resolve(AlicePK, BobSK, 'private-group');
+```
 
-To resolve anonymously through Tor, you can use the `socks-proxy-agent` and a custom `WebSocket` implementation:
+### 4. Tor & Privacy (Node.js)
+
+Route all Nostr relay traffic through a local Tor proxy (`127.0.0.1:9050`).
 
 ```typescript
-import { NCC05Resolver } from 'ncc-05';
 import { SocksProxyAgent } from 'socks-proxy-agent';
 import { WebSocket } from 'ws';
 
-// Create a custom WebSocket class that uses the Tor agent
 class TorWebSocket extends WebSocket {
     constructor(address: string, protocols?: string | string[]) {
         const agent = new SocksProxyAgent('socks5h://127.0.0.1:9050');
@@ -93,6 +99,22 @@ const resolver = new NCC05Resolver({
 });
 ```
 
+## API Reference
+
+### `NCC05Resolver`
+- `resolve(targetPubkey, secretKey?, identifier?, options?)`: Finds and decrypts a locator record.
+- `close()`: Closes pool connections.
+
+### `NCC05Publisher`
+- `publish(relays, secretKey, payload, options?)`: Publishes a standard or targeted record.
+- `publishWrapped(relays, secretKey, recipients, payload, identifier?)`: Publishes a multi-recipient record.
+
+### `NCC05Group`
+- `createGroupIdentity()`: Generates a shared group keypair.
+- `resolveAsGroup(...)`: Helper for shared-nsec resolution.
+
 ## License
 
-MIT
+
+
+CC0 1.0 Universal

package/dist/index.d.ts

@@ -1,33 +1,73 @@
+/**
+ * NCC-05: Identity-Bound Service Locator Resolution
+ *
+ * This library implements the NCC-05 convention for publishing and resolving
+ * dynamic service endpoints (IP, Port, Onion) bound to Nostr identities.
+ *
+ * @module ncc-05
+ */
 import { Event } from 'nostr-tools';
+/**
+ * Represents a single reachable service endpoint.
+ */
 export interface NCC05Endpoint {
+    /** Protocol type, e.g., 'tcp', 'udp', 'http' */
     type: 'tcp' | 'udp' | string;
+    /** The URI string, e.g., '1.2.3.4:8080' or '[2001:db8::1]:9000' */
     uri: string;
+    /** Priority for selection (lower is higher priority) */
     priority: number;
+    /** Network family for routing hints */
     family: 'ipv4' | 'ipv6' | 'onion' | string;
 }
+/**
+ * The logical structure of an NCC-05 locator record payload.
+ */
 export interface NCC05Payload {
+    /** Payload version (currently 1) */
     v: number;
+    /** Time-to-live in seconds */
     ttl: number;
+    /** Unix timestamp of the last update */
     updated_at: number;
+    /** List of available endpoints */
     endpoints: NCC05Endpoint[];
+    /** Optional capability identifiers supported by the service */
     caps?: string[];
+    /** Optional human-readable notes */
     notes?: string;
 }
+/**
+ * Options for configuring the NCC05Resolver.
+ */
 export interface ResolverOptions {
+    /** List of relays used to bootstrap discovery */
     bootstrapRelays?: string[];
+    /** Timeout for relay queries in milliseconds (default: 10000) */
     timeout?: number;
+    /** Custom WebSocket implementation (e.g., for Tor/SOCKS5 in Node.js) */
     websocketImplementation?: any;
 }
 /**
- * Advanced multi-recipient "wrapping" structure.
+ * Structure for multi-recipient encrypted events.
+ * Implements a "wrapping" pattern to share one event with multiple keys.
  */
 export interface WrappedContent {
-    /** The actual payload encrypted with a random symmetric key */
+    /** The NCC05Payload encrypted with a random symmetric session key */
     ciphertext: string;
-    /** Map of recipient pubkey -> wrapped symmetric key */
+    /** Map of recipient pubkey (hex) to the encrypted session key */
     wraps: Record<string, string>;
 }
+/**
+ * Utility for managing shared group access to service records.
+ */
 export declare class NCC05Group {
+    /**
+     * Generates a fresh identity (keypair) for a shared group.
+     * The resulting nsec should be shared with all authorized group members.
+     *
+     * @returns An object containing nsec, hex pubkey, and the raw secret key.
+     */
     static createGroupIdentity(): {
         nsec: `nsec1${string}`;
         sk: Uint8Array<ArrayBufferLike>;
@@ -35,31 +75,87 @@ export declare class NCC05Group {
         npub: `npub1${string}`;
     };
     /**
-     * Resolve a record that was published using a group's shared identity.
+     * Helper to resolve a record using a group's shared identity.
+     *
+     * @param resolver - An initialized NCC05Resolver instance.
+     * @param groupPubkey - The public key of the group.
+     * @param groupSecretKey - The shared secret key of the group.
+     * @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>;
 }
+/**
+ * Handles the discovery, selection, and decryption of NCC-05 locator records.
+ */
 export declare class NCC05Resolver {
     private pool;
     private bootstrapRelays;
     private timeout;
+    /**
+     * @param options - Configuration for the resolver.
+     */
     constructor(options?: ResolverOptions);
+    /**
+     * Resolves a locator record for a given identity.
+     *
+     * Supports standard NIP-44 encryption, multi-recipient "wrapping",
+     * and plaintext public records.
+     *
+     * @param targetPubkey - The pubkey (hex or npub) of the service owner.
+     * @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.
+     */
     resolve(targetPubkey: string, secretKey?: Uint8Array, identifier?: string, options?: {
         strict?: boolean;
         gossip?: boolean;
     }): Promise<NCC05Payload | null>;
+    /**
+     * Closes connections to all relays in the pool.
+     */
     close(): void;
 }
+/**
+ * Handles the construction, encryption, and publication of NCC-05 events.
+ */
 export declare class NCC05Publisher {
     private pool;
+    /**
+     * @param options - Configuration for the publisher.
+     */
     constructor(options?: {
         websocketImplementation?: any;
     });
+    /**
+     * Publishes a single record encrypted for multiple recipients using the wrapping pattern.
+     * This avoids sharing a single group private key.
+     *
+     * @param relays - List of relays to publish to.
+     * @param secretKey - The publisher's secret key.
+     * @param recipients - List of recipient public keys (hex).
+     * @param payload - The service locator payload.
+     * @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>;
+    /**
+     * Publishes a locator record. Supports self-encryption, targeted encryption, or plaintext.
+     *
+     * @param relays - List of relays to publish to.
+     * @param secretKey - The publisher's secret key.
+     * @param payload - The service locator payload.
+     * @param options - Publishing options (identifier, recipient, or public flag).
+     * @returns The signed Nostr event.
+     */
     publish(relays: string[], secretKey: Uint8Array, payload: NCC05Payload, options?: {
         identifier?: string;
         recipientPubkey?: string;
         public?: boolean;
     }): Promise<Event>;
+    /**
+     * Closes connections to the specified relays.
+     */
     close(relays: string[]): void;
 }

package/dist/index.js

@@ -1,5 +1,22 @@
+/**
+ * NCC-05: Identity-Bound Service Locator Resolution
+ *
+ * This library implements the NCC-05 convention for publishing and resolving
+ * dynamic service endpoints (IP, Port, Onion) bound to Nostr identities.
+ *
+ * @module ncc-05
+ */
 import { SimplePool, nip44, nip19, finalizeEvent, verifyEvent, getPublicKey, generateSecretKey } from 'nostr-tools';
+/**
+ * Utility for managing shared group access to service records.
+ */
 export class NCC05Group {
+    /**
+     * Generates a fresh identity (keypair) for a shared group.
+     * The resulting nsec should be shared with all authorized group members.
+     *
+     * @returns An object containing nsec, hex pubkey, and the raw secret key.
+     */
     static createGroupIdentity() {
         const sk = generateSecretKey();
         const pk = getPublicKey(sk);
@@ -11,25 +28,49 @@ export class NCC05Group {
         };
     }
     /**
-     * Resolve a record that was published using a group's shared identity.
+     * Helper to resolve a record using a group's shared identity.
+     *
+     * @param resolver - An initialized NCC05Resolver instance.
+     * @param groupPubkey - The public key of the group.
+     * @param groupSecretKey - The shared secret key of the group.
+     * @param identifier - The 'd' tag of the record (default: 'addr').
+     * @returns The resolved NCC05Payload or null.
      */
     static async resolveAsGroup(resolver, groupPubkey, groupSecretKey, identifier = 'addr') {
         return resolver.resolve(groupPubkey, groupSecretKey, identifier);
     }
 }
+/**
+ * Handles the discovery, selection, and decryption of NCC-05 locator records.
+ */
 export class NCC05Resolver {
     pool;
     bootstrapRelays;
     timeout;
+    /**
+     * @param options - Configuration for the resolver.
+     */
     constructor(options = {}) {
         this.pool = new SimplePool();
         if (options.websocketImplementation) {
-            // @ts-ignore
+            // @ts-ignore - Patching pool for custom transport
             this.pool.websocketImplementation = options.websocketImplementation;
         }
         this.bootstrapRelays = options.bootstrapRelays || ['wss://relay.damus.io', 'wss://nos.lol'];
         this.timeout = options.timeout || 10000;
     }
+    /**
+     * Resolves a locator record for a given identity.
+     *
+     * Supports standard NIP-44 encryption, multi-recipient "wrapping",
+     * and plaintext public records.
+     *
+     * @param targetPubkey - The pubkey (hex or npub) of the service owner.
+     * @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.
+     */
     async resolve(targetPubkey, secretKey, identifier = 'addr', options = {}) {
         let hexPubkey = targetPubkey;
         if (targetPubkey.startsWith('npub1')) {
@@ -37,6 +78,7 @@ export class NCC05Resolver {
             hexPubkey = decoded.data;
         }
         let queryRelays = [...this.bootstrapRelays];
+        // 1. NIP-65 Gossip Discovery
         if (options.gossip) {
             const relayListEvent = await this.pool.get(this.bootstrapRelays, {
                 authors: [hexPubkey],
@@ -46,7 +88,9 @@ export class NCC05Resolver {
                 const discoveredRelays = relayListEvent.tags
                     .filter(t => t[0] === 'r')
                     .map(t => t[1]);
-                queryRelays = [...new Set([...queryRelays, ...discoveredRelays])];
+                if (discoveredRelays.length > 0) {
+                    queryRelays = [...new Set([...queryRelays, ...discoveredRelays])];
+                }
             }
         }
         const filter = {
@@ -68,7 +112,7 @@ export class NCC05Resolver {
         const latestEvent = validEvents[0];
         try {
             let content = latestEvent.content;
-            // 1. Try to detect if it's a "Wrapped" multi-recipient event
+            // Handle "Wrapped" multi-recipient content
             if (content.includes('"wraps"') && secretKey) {
                 const wrapped = JSON.parse(content);
                 const myPk = getPublicKey(secretKey);
@@ -76,25 +120,25 @@ export class NCC05Resolver {
                 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)));
-                    // The payload was self-encrypted by the publisher with the session key
                     const sessionConversationKey = nip44.getConversationKey(symmetricKey, getPublicKey(symmetricKey));
                     content = nip44.decrypt(wrapped.ciphertext, sessionConversationKey);
                 }
             }
             else if (secretKey) {
+                // Standard NIP-44
                 const conversationKey = nip44.getConversationKey(secretKey, hexPubkey);
                 content = nip44.decrypt(latestEvent.content, conversationKey);
             }
             const payload = JSON.parse(content);
             if (!payload.endpoints)
                 return null;
+            // Freshness validation
             const now = Math.floor(Date.now() / 1000);
             if (now > payload.updated_at + payload.ttl) {
                 if (options.strict)
                     return null;
-                console.warn('NCC-05 record expired');
+                console.warn('NCC-05 record has expired');
             }
             return payload;
         }
@@ -102,10 +146,21 @@ export class NCC05Resolver {
             return null;
         }
     }
-    close() { this.pool.close(this.bootstrapRelays); }
+    /**
+     * Closes connections to all relays in the pool.
+     */
+    close() {
+        this.pool.close(this.bootstrapRelays);
+    }
 }
+/**
+ * Handles the construction, encryption, and publication of NCC-05 events.
+ */
 export class NCC05Publisher {
     pool;
+    /**
+     * @param options - Configuration for the publisher.
+     */
     constructor(options = {}) {
         this.pool = new SimplePool();
         if (options.websocketImplementation) {
@@ -113,6 +168,17 @@ export class NCC05Publisher {
             this.pool.websocketImplementation = options.websocketImplementation;
         }
     }
+    /**
+     * Publishes a single record encrypted for multiple recipients using the wrapping pattern.
+     * This avoids sharing a single group private key.
+     *
+     * @param relays - List of relays to publish to.
+     * @param secretKey - The publisher's secret key.
+     * @param recipients - List of recipient public keys (hex).
+     * @param payload - The service locator payload.
+     * @param identifier - The 'd' tag identifier (default: 'addr').
+     * @returns The signed Nostr event.
+     */
     async publishWrapped(relays, secretKey, recipients, payload, identifier = 'addr') {
         const sessionKey = generateSecretKey();
         const sessionKeyHex = Array.from(sessionKey).map(b => b.toString(16).padStart(2, '0')).join('');
@@ -134,6 +200,15 @@ export class NCC05Publisher {
         await Promise.all(this.pool.publish(relays, signedEvent));
         return signedEvent;
     }
+    /**
+     * Publishes a locator record. Supports self-encryption, targeted encryption, or plaintext.
+     *
+     * @param relays - List of relays to publish to.
+     * @param secretKey - The publisher's secret key.
+     * @param payload - The service locator payload.
+     * @param options - Publishing options (identifier, recipient, or public flag).
+     * @returns The signed Nostr event.
+     */
     async publish(relays, secretKey, payload, options = {}) {
         const myPubkey = getPublicKey(secretKey);
         const identifier = options.identifier || 'addr';
@@ -154,5 +229,10 @@ export class NCC05Publisher {
         await Promise.all(this.pool.publish(relays, signedEvent));
         return signedEvent;
     }
-    close(relays) { this.pool.close(relays); }
+    /**
+     * Closes connections to the specified relays.
+     */
+    close(relays) {
+        this.pool.close(relays);
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ncc-05",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Nostr Community Convention 05 - Identity-Bound Service Locator Resolution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,12 +17,12 @@
     "privacy"
   ],
   "author": "lostcause",
-  "license": "MIT",
+  "license": "CC0-1.0",
   "dependencies": {
     "nostr-tools": "^2.10.0"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^25.0.3",
     "@types/ws": "^8.18.1",
     "typescript": "^5.0.0",
     "ws": "^8.18.3"

package/src/index.ts

@@ -1,3 +1,12 @@
+/**
+ * NCC-05: Identity-Bound Service Locator Resolution
+ * 
+ * This library implements the NCC-05 convention for publishing and resolving
+ * dynamic service endpoints (IP, Port, Onion) bound to Nostr identities.
+ * 
+ * @module ncc-05
+ */
+
 import { 
     SimplePool, 
     nip44, 
@@ -9,39 +18,71 @@ import {
     generateSecretKey
 } from 'nostr-tools';
 
+/**
+ * Represents a single reachable service endpoint.
+ */
 export interface NCC05Endpoint {
+    /** Protocol type, e.g., 'tcp', 'udp', 'http' */
     type: 'tcp' | 'udp' | string;
+    /** The URI string, e.g., '1.2.3.4:8080' or '[2001:db8::1]:9000' */
     uri: string;
+    /** Priority for selection (lower is higher priority) */
     priority: number;
+    /** Network family for routing hints */
     family: 'ipv4' | 'ipv6' | 'onion' | string;
 }
 
+/**
+ * The logical structure of an NCC-05 locator record payload.
+ */
 export interface NCC05Payload {
+    /** Payload version (currently 1) */
     v: number;
+    /** Time-to-live in seconds */
     ttl: number;
+    /** Unix timestamp of the last update */
     updated_at: number;
+    /** List of available endpoints */
     endpoints: NCC05Endpoint[];
+    /** Optional capability identifiers supported by the service */
     caps?: string[];
+    /** Optional human-readable notes */
     notes?: string;
 }
 
+/**
+ * Options for configuring the NCC05Resolver.
+ */
 export interface ResolverOptions {
+    /** List of relays used to bootstrap discovery */
     bootstrapRelays?: string[];
+    /** Timeout for relay queries in milliseconds (default: 10000) */
     timeout?: number;
+    /** Custom WebSocket implementation (e.g., for Tor/SOCKS5 in Node.js) */
     websocketImplementation?: any;
 }
 
 /**
- * Advanced multi-recipient "wrapping" structure.
+ * Structure for multi-recipient encrypted events.
+ * Implements a "wrapping" pattern to share one event with multiple keys.
  */
 export interface WrappedContent {
-    /** The actual payload encrypted with a random symmetric key */
+    /** The NCC05Payload encrypted with a random symmetric session key */
     ciphertext: string;
-    /** Map of recipient pubkey -> wrapped symmetric key */
+    /** Map of recipient pubkey (hex) to the encrypted session key */
     wraps: Record<string, string>;
 }
 
+/**
+ * Utility for managing shared group access to service records.
+ */
 export class NCC05Group {
+    /**
+     * Generates a fresh identity (keypair) for a shared group.
+     * The resulting nsec should be shared with all authorized group members.
+     * 
+     * @returns An object containing nsec, hex pubkey, and the raw secret key.
+     */
     static createGroupIdentity() {
         const sk = generateSecretKey();
         const pk = getPublicKey(sk);
@@ -54,7 +95,13 @@ export class NCC05Group {
     }
 
     /**
-     * Resolve a record that was published using a group's shared identity.
+     * Helper to resolve a record using a group's shared identity.
+     * 
+     * @param resolver - An initialized NCC05Resolver instance.
+     * @param groupPubkey - The public key of the group.
+     * @param groupSecretKey - The shared secret key of the group.
+     * @param identifier - The 'd' tag of the record (default: 'addr').
+     * @returns The resolved NCC05Payload or null.
      */
     static async resolveAsGroup(
         resolver: NCC05Resolver,
@@ -66,21 +113,39 @@ export class NCC05Group {
     }
 }
 
+/**
+ * Handles the discovery, selection, and decryption of NCC-05 locator records.
+ */
 export class NCC05Resolver {
     private pool: SimplePool;
     private bootstrapRelays: string[];
     private timeout: number;
 
+    /**
+     * @param options - Configuration for the resolver.
+     */
     constructor(options: ResolverOptions = {}) {
         this.pool = new SimplePool();
         if (options.websocketImplementation) {
-            // @ts-ignore
+            // @ts-ignore - Patching pool for custom transport
             this.pool.websocketImplementation = options.websocketImplementation;
         }
         this.bootstrapRelays = options.bootstrapRelays || ['wss://relay.damus.io', 'wss://nos.lol'];
         this.timeout = options.timeout || 10000;
     }
 
+    /**
+     * Resolves a locator record for a given identity.
+     * 
+     * Supports standard NIP-44 encryption, multi-recipient "wrapping", 
+     * and plaintext public records.
+     * 
+     * @param targetPubkey - The pubkey (hex or npub) of the service owner.
+     * @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.
+     */
     async resolve(
         targetPubkey: string, 
         secretKey?: Uint8Array, 
@@ -95,6 +160,7 @@ 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],
@@ -104,7 +170,9 @@ export class NCC05Resolver {
                 const discoveredRelays = relayListEvent.tags
                     .filter(t => t[0] === 'r')
                     .map(t => t[1]);
-                queryRelays = [...new Set([...queryRelays, ...discoveredRelays])];
+                if (discoveredRelays.length > 0) {
+                    queryRelays = [...new Set([...queryRelays, ...discoveredRelays])];
+                }
             }
         }
 
@@ -131,7 +199,7 @@ export class NCC05Resolver {
         try {
             let content = latestEvent.content;
             
-            // 1. Try to detect if it's a "Wrapped" multi-recipient event
+            // Handle "Wrapped" multi-recipient content
             if (content.includes('"wraps"') && secretKey) {
                 const wrapped = JSON.parse(content) as WrappedContent;
                 const myPk = getPublicKey(secretKey);
@@ -140,15 +208,13 @@ export class NCC05Resolver {
                 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)));
                     
-                    // The payload was self-encrypted by the publisher with the session key
                     const sessionConversationKey = nip44.getConversationKey(symmetricKey, getPublicKey(symmetricKey));
                     content = nip44.decrypt(wrapped.ciphertext, sessionConversationKey);
                 }
             } else if (secretKey) {
+                // Standard NIP-44
                 const conversationKey = nip44.getConversationKey(secretKey, hexPubkey);
                 content = nip44.decrypt(latestEvent.content, conversationKey);
             }
@@ -156,10 +222,11 @@ export class NCC05Resolver {
             const payload = JSON.parse(content) as NCC05Payload;
             if (!payload.endpoints) return null;
 
+            // Freshness validation
             const now = Math.floor(Date.now() / 1000);
             if (now > payload.updated_at + payload.ttl) {
                 if (options.strict) return null;
-                console.warn('NCC-05 record expired');
+                console.warn('NCC-05 record has expired');
             }
 
             return payload;
@@ -168,12 +235,23 @@ export class NCC05Resolver {
         }
     }
 
-    close() { this.pool.close(this.bootstrapRelays); }
+    /**
+     * Closes connections to all relays in the pool.
+     */
+    close() {
+        this.pool.close(this.bootstrapRelays);
+    }
 }
 
+/**
+ * Handles the construction, encryption, and publication of NCC-05 events.
+ */
 export class NCC05Publisher {
     private pool: SimplePool;
 
+    /**
+     * @param options - Configuration for the publisher.
+     */
     constructor(options: { websocketImplementation?: any } = {}) {
         this.pool = new SimplePool();
         if (options.websocketImplementation) {
@@ -182,6 +260,17 @@ export class NCC05Publisher {
         }
     }
 
+    /**
+     * Publishes a single record encrypted for multiple recipients using the wrapping pattern.
+     * This avoids sharing a single group private key.
+     * 
+     * @param relays - List of relays to publish to.
+     * @param secretKey - The publisher's secret key.
+     * @param recipients - List of recipient public keys (hex).
+     * @param payload - The service locator payload.
+     * @param identifier - The 'd' tag identifier (default: 'addr').
+     * @returns The signed Nostr event.
+     */
     async publishWrapped(
         relays: string[],
         secretKey: Uint8Array,
@@ -215,6 +304,15 @@ export class NCC05Publisher {
         return signedEvent;
     }
 
+    /**
+     * Publishes a locator record. Supports self-encryption, targeted encryption, or plaintext.
+     * 
+     * @param relays - List of relays to publish to.
+     * @param secretKey - The publisher's secret key.
+     * @param payload - The service locator payload.
+     * @param options - Publishing options (identifier, recipient, or public flag).
+     * @returns The signed Nostr event.
+     */
     async publish(
         relays: string[],
         secretKey: Uint8Array,
@@ -244,5 +342,10 @@ export class NCC05Publisher {
         return signedEvent;
     }
 
-    close(relays: string[]) { this.pool.close(relays); }
-}
+    /**
+     * Closes connections to the specified relays.
+     */
+    close(relays: string[]) {
+        this.pool.close(relays);
+    }
+}