ncc-05 1.0.0

package/README.md

@@ -0,0 +1,98 @@
+# ncc-05
+
+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.
+
+## Installation
+
+```bash
+npm install ncc-05
+```
+
+## Usage
+
+### Resolver
+
+Resolve an identity-bound service locator for a given pubkey.
+
+```typescript
+import { NCC05Resolver } from 'ncc-05';
+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 = '...'; 
+
+const payload = await resolver.resolve(targetPubkey, mySecretKey);
+
+if (payload) {
+    console.log('Resolved Endpoints:');
+    payload.endpoints.forEach(ep => {
+        console.log(`- ${ep.type}://${ep.uri} (${ep.family})`);
+    });
+}
+```
+
+### Publisher
+
+Publish your own service locator record.
+
+```typescript
+import { NCC05Publisher, NCC05Payload } 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);
+```
+
+## Features
+
+- **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.
+
+## Tor & Privacy (Node.js)
+
+To resolve anonymously through Tor, you can use the `socks-proxy-agent` and a custom `WebSocket` implementation:
+
+```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');
+        super(address, protocols, { agent });
+    }
+}
+
+const resolver = new NCC05Resolver({
+    websocketImplementation: TorWebSocket
+});
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { Event } from 'nostr-tools';
+export interface NCC05Endpoint {
+    type: 'tcp' | 'udp' | string;
+    uri: string;
+    priority: number;
+    family: 'ipv4' | 'ipv6' | 'onion' | string;
+}
+export interface NCC05Payload {
+    v: number;
+    ttl: number;
+    updated_at: number;
+    endpoints: NCC05Endpoint[];
+    caps?: string[];
+    notes?: string;
+}
+export interface ResolverOptions {
+    bootstrapRelays?: string[];
+    timeout?: number;
+    websocketImplementation?: any;
+}
+export declare class NCC05Resolver {
+    private pool;
+    private bootstrapRelays;
+    private timeout;
+    constructor(options?: ResolverOptions);
+    /**
+     * Resolve a locator record for a given pubkey.
+     * Supports both hex and npub strings.
+     */
+    resolve(targetPubkey: string, secretKey: Uint8Array, identifier?: string, options?: {
+        strict?: boolean;
+        gossip?: boolean;
+    }): Promise<NCC05Payload | null>;
+    close(): void;
+}
+export declare class NCC05Publisher {
+    private pool;
+    constructor(options?: {
+        websocketImplementation?: any;
+    });
+    /**
+     * Create and publish a locator record.
+     */
+    publish(relays: string[], secretKey: Uint8Array, payload: NCC05Payload, identifier?: string): Promise<Event>;
+    close(relays: string[]): void;
+}

package/dist/index.js

@@ -0,0 +1,121 @@
+import { SimplePool, nip44, nip19, finalizeEvent, verifyEvent, getPublicKey } from 'nostr-tools';
+export class NCC05Resolver {
+    pool;
+    bootstrapRelays;
+    timeout;
+    constructor(options = {}) {
+        this.pool = new SimplePool();
+        if (options.websocketImplementation) {
+            // @ts-ignore - Patching pool for custom WebSocket (Tor/Proxy)
+            this.pool.websocketImplementation = options.websocketImplementation;
+        }
+        this.bootstrapRelays = options.bootstrapRelays || ['wss://relay.damus.io', 'wss://nos.lol'];
+        this.timeout = options.timeout || 10000;
+    }
+    /**
+     * Resolve a locator record for a given pubkey.
+     * Supports both hex and npub strings.
+     */
+    async resolve(targetPubkey, secretKey, identifier = 'addr', options = {}) {
+        let hexPubkey = targetPubkey;
+        if (targetPubkey.startsWith('npub1')) {
+            const decoded = nip19.decode(targetPubkey);
+            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],
+                kinds: [10002]
+            });
+            if (relayListEvent) {
+                const discoveredRelays = relayListEvent.tags
+                    .filter(t => t[0] === 'r')
+                    .map(t => t[1]);
+                if (discoveredRelays.length > 0) {
+                    queryRelays = [...new Set([...queryRelays, ...discoveredRelays])];
+                }
+            }
+        }
+        const filter = {
+            authors: [hexPubkey],
+            kinds: [30058],
+            '#d': [identifier],
+            limit: 10
+        };
+        const queryPromise = this.pool.querySync(queryRelays, filter);
+        const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(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 and sort by created_at
+        const validEvents = result
+            .filter(e => verifyEvent(e))
+            .sort((a, b) => b.created_at - a.created_at);
+        if (validEvents.length === 0)
+            return null;
+        const latestEvent = validEvents[0];
+        // 2. Decrypt
+        try {
+            const conversationKey = nip44.getConversationKey(secretKey, hexPubkey);
+            const decrypted = nip44.decrypt(latestEvent.content, conversationKey);
+            const payload = JSON.parse(decrypted);
+            // 3. Basic Validation
+            if (!payload.endpoints || !Array.isArray(payload.endpoints)) {
+                console.error('Invalid NCC-05 payload structure');
+                return null;
+            }
+            // 4. Freshness check
+            const now = Math.floor(Date.now() / 1000);
+            if (now > payload.updated_at + payload.ttl) {
+                if (options.strict) {
+                    console.warn('Rejecting expired NCC-05 record (strict mode)');
+                    return null;
+                }
+                console.warn('NCC-05 record has expired');
+            }
+            return payload;
+        }
+        catch (e) {
+            console.error('Failed to decrypt or parse NCC-05 record:', e);
+            return null;
+        }
+    }
+    close() {
+        this.pool.close(this.bootstrapRelays);
+    }
+}
+export class NCC05Publisher {
+    pool;
+    constructor(options = {}) {
+        this.pool = new SimplePool();
+        if (options.websocketImplementation) {
+            // @ts-ignore - Patching pool for custom WebSocket (Tor/Proxy)
+            this.pool.websocketImplementation = options.websocketImplementation;
+        }
+    }
+    /**
+     * Create and publish a locator record.
+     */
+    async publish(relays, secretKey, payload, identifier = 'addr') {
+        const pubkey = getPublicKey(secretKey);
+        // 1. Encrypt
+        const conversationKey = nip44.getConversationKey(secretKey, pubkey);
+        const encryptedContent = nip44.encrypt(JSON.stringify(payload), conversationKey);
+        // 2. Create and Finalize Event
+        const eventTemplate = {
+            kind: 30058,
+            created_at: Math.floor(Date.now() / 1000),
+            tags: [['d', identifier]],
+            content: encryptedContent,
+        };
+        const signedEvent = finalizeEvent(eventTemplate, secretKey);
+        // 3. Publish
+        await Promise.all(this.pool.publish(relays, signedEvent));
+        return signedEvent;
+    }
+    close(relays) {
+        this.pool.close(relays);
+    }
+}

package/dist/test.d.ts

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

package/dist/test.js

@@ -0,0 +1,80 @@
+import { NCC05Publisher, NCC05Resolver } from './index.js';
+import { generateSecretKey, getPublicKey } from 'nostr-tools';
+async function test() {
+    const sk = generateSecretKey();
+    const pk = getPublicKey(sk);
+    const relays = ['wss://relay.damus.io'];
+    const publisher = new NCC05Publisher();
+    const resolver = new NCC05Resolver({ bootstrapRelays: relays });
+    const payload = {
+        v: 1,
+        ttl: 60,
+        updated_at: Math.floor(Date.now() / 1000),
+        endpoints: [
+            { type: 'tcp', uri: '127.0.0.1:9000', priority: 1, family: 'ipv4' }
+        ]
+    };
+    console.log('Publishing...');
+    await publisher.publish(relays, sk, payload);
+    console.log('Published.');
+    console.log('Resolving...');
+    const resolved = await resolver.resolve(pk, sk);
+    if (resolved) {
+        console.log('Successfully resolved:', JSON.stringify(resolved, null, 2));
+    }
+    else {
+        console.log('Failed to resolve.');
+    }
+    // Test Strict Mode with Expired Record
+    console.log('Testing expired record in strict mode...');
+    const expiredPayload = {
+        v: 1,
+        ttl: 1,
+        updated_at: Math.floor(Date.now() / 1000) - 10, // 10s ago
+        endpoints: [{ type: 'tcp', uri: '1.1.1.1:1', priority: 1, family: 'ipv4' }]
+    };
+    await publisher.publish(relays, sk, expiredPayload, 'expired-test');
+    const strictResult = await resolver.resolve(pk, sk, 'expired-test', { strict: true });
+    if (strictResult === null) {
+        console.log('Correctly rejected expired record in strict mode.');
+    }
+    else {
+        console.error('FAILED: Strict mode allowed an expired record.');
+        process.exit(1);
+    }
+    // Test Gossip Mode
+    console.log('Testing Gossip discovery...');
+    // In this test, we just point kind:10002 to the same relay we are using
+    // to verify the code path executes.
+    const relayListTemplate = {
+        kind: 10002,
+        created_at: Math.floor(Date.now() / 1000),
+        tags: [['r', relays[0]]],
+        content: '',
+    };
+    const signedRL = (await import('nostr-tools')).finalizeEvent(relayListTemplate, sk);
+    await Promise.all(publisher['pool'].publish(relays, signedRL));
+    const gossipResult = await resolver.resolve(pk, sk, 'addr', { gossip: true });
+    if (gossipResult) {
+        console.log('Gossip discovery successful.');
+    }
+    else {
+        console.error('FAILED: Gossip discovery did not find record.');
+        process.exit(1);
+    }
+    // Test npub resolution
+    console.log('Testing npub resolution...');
+    const npub = (await import('nostr-tools')).nip19.npubEncode(pk);
+    const npubResult = await resolver.resolve(npub, sk);
+    if (npubResult) {
+        console.log('npub resolution successful.');
+    }
+    else {
+        console.error('FAILED: npub resolution did not find record.');
+        process.exit(1);
+    }
+    publisher.close(relays);
+    resolver.close();
+    process.exit(0);
+}
+test().catch(console.error);

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "ncc-05",
+  "version": "1.0.0",
+  "description": "Nostr Community Convention 05 - Identity-Bound Service Locator Resolution",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["nostr", "dns", "identity", "resolution", "privacy"],
+  "author": "lostcause",
+  "license": "MIT",
+  "dependencies": {
+    "nostr-tools": "^2.10.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,186 @@
+import { 
+    SimplePool, 
+    nip44, 
+    nip19,
+    finalizeEvent, 
+    verifyEvent, 
+    Event, 
+    getPublicKey
+} from 'nostr-tools';
+
+export interface NCC05Endpoint {
+    type: 'tcp' | 'udp' | string;
+    uri: string;
+    priority: number;
+    family: 'ipv4' | 'ipv6' | 'onion' | string;
+}
+
+export interface NCC05Payload {
+    v: number;
+    ttl: number;
+    updated_at: number;
+    endpoints: NCC05Endpoint[];
+    caps?: string[];
+    notes?: string;
+}
+
+export interface ResolverOptions {
+    bootstrapRelays?: string[];
+    timeout?: number;
+    websocketImplementation?: any; // To support Tor/SOCKS5 proxies in Node.js
+}
+
+export class NCC05Resolver {
+    private pool: SimplePool;
+    private bootstrapRelays: string[];
+    private timeout: number;
+
+    constructor(options: ResolverOptions = {}) {
+        this.pool = new SimplePool();
+        if (options.websocketImplementation) {
+            // @ts-ignore - Patching pool for custom WebSocket (Tor/Proxy)
+            this.pool.websocketImplementation = options.websocketImplementation;
+        }
+        this.bootstrapRelays = options.bootstrapRelays || ['wss://relay.damus.io', 'wss://nos.lol'];
+        this.timeout = options.timeout || 10000;
+    }
+
+    /**
+     * Resolve a locator record for a given pubkey.
+     * Supports both hex and npub strings.
+     */
+    async resolve(
+        targetPubkey: string, 
+        secretKey: Uint8Array, 
+        identifier: string = 'addr',
+        options: { strict?: boolean, gossip?: boolean } = {}
+    ): Promise<NCC05Payload | null> {
+        let hexPubkey = targetPubkey;
+        if (targetPubkey.startsWith('npub1')) {
+            const decoded = nip19.decode(targetPubkey);
+            hexPubkey = decoded.data as string;
+        }
+
+        let queryRelays = [...this.bootstrapRelays];
+
+        // 1. NIP-65 Gossip Discovery
+        if (options.gossip) {
+            const relayListEvent = await this.pool.get(this.bootstrapRelays, {
+                authors: [hexPubkey],
+                kinds: [10002]
+            });
+
+            if (relayListEvent) {
+                const discoveredRelays = relayListEvent.tags
+                    .filter(t => t[0] === 'r')
+                    .map(t => t[1]);
+                if (discoveredRelays.length > 0) {
+                    queryRelays = [...new Set([...queryRelays, ...discoveredRelays])];
+                }
+            }
+        }
+
+        const filter = {
+            authors: [hexPubkey],
+            kinds: [30058],
+            '#d': [identifier],
+            limit: 10
+        };
+
+        const queryPromise = this.pool.querySync(queryRelays, filter);
+        const timeoutPromise = new Promise<null>((resolve) => 
+            setTimeout(() => resolve(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 and sort by created_at
+        const validEvents = (result as Event[])
+            .filter(e => verifyEvent(e))
+            .sort((a, b) => b.created_at - a.created_at);
+
+        if (validEvents.length === 0) return null;
+        const latestEvent = validEvents[0];
+
+        // 2. Decrypt
+        try {
+            const conversationKey = nip44.getConversationKey(secretKey, hexPubkey);
+            const decrypted = nip44.decrypt(latestEvent.content, conversationKey);
+            const payload = JSON.parse(decrypted) as NCC05Payload;
+
+            // 3. Basic Validation
+            if (!payload.endpoints || !Array.isArray(payload.endpoints)) {
+                console.error('Invalid NCC-05 payload structure');
+                return null;
+            }
+
+            // 4. Freshness check
+            const now = Math.floor(Date.now() / 1000);
+            if (now > payload.updated_at + payload.ttl) {
+                if (options.strict) {
+                    console.warn('Rejecting expired NCC-05 record (strict mode)');
+                    return null;
+                }
+                console.warn('NCC-05 record has expired');
+            }
+
+            return payload;
+        } catch (e) {
+            console.error('Failed to decrypt or parse NCC-05 record:', e);
+            return null;
+        }
+    }
+
+    close() {
+        this.pool.close(this.bootstrapRelays);
+    }
+}
+
+export class NCC05Publisher {
+    private pool: SimplePool;
+
+    constructor(options: { websocketImplementation?: any } = {}) {
+        this.pool = new SimplePool();
+        if (options.websocketImplementation) {
+            // @ts-ignore - Patching pool for custom WebSocket (Tor/Proxy)
+            this.pool.websocketImplementation = options.websocketImplementation;
+        }
+    }
+
+    /**
+     * Create and publish a locator record.
+     */
+    async publish(
+        relays: string[],
+        secretKey: Uint8Array,
+        payload: NCC05Payload,
+        identifier: string = 'addr'
+    ): Promise<Event> {
+        const pubkey = getPublicKey(secretKey);
+        
+        // 1. Encrypt
+        const conversationKey = nip44.getConversationKey(secretKey, pubkey);
+        const encryptedContent = nip44.encrypt(JSON.stringify(payload), conversationKey);
+
+        // 2. Create and Finalize Event
+        const eventTemplate = {
+            kind: 30058,
+            created_at: Math.floor(Date.now() / 1000),
+            tags: [['d', identifier]],
+            content: encryptedContent,
+        };
+
+        const signedEvent = finalizeEvent(eventTemplate, secretKey);
+
+        // 3. Publish
+        await Promise.all(this.pool.publish(relays, signedEvent));
+        
+        return signedEvent;
+    }
+
+    close(relays: string[]) {
+        this.pool.close(relays);
+    }
+}

package/src/test.ts

@@ -0,0 +1,89 @@
+import { NCC05Publisher, NCC05Resolver, NCC05Payload } from './index.js';
+import { generateSecretKey, getPublicKey } from 'nostr-tools';
+
+async function test() {
+    const sk = generateSecretKey();
+    const pk = getPublicKey(sk);
+    const relays = ['wss://relay.damus.io'];
+
+    const publisher = new NCC05Publisher();
+    const resolver = new NCC05Resolver({ bootstrapRelays: relays });
+
+    const payload: NCC05Payload = {
+        v: 1,
+        ttl: 60,
+        updated_at: Math.floor(Date.now() / 1000),
+        endpoints: [
+            { type: 'tcp', uri: '127.0.0.1:9000', priority: 1, family: 'ipv4' }
+        ]
+    };
+
+    console.log('Publishing...');
+    await publisher.publish(relays, sk, payload);
+    console.log('Published.');
+
+    console.log('Resolving...');
+    const resolved = await resolver.resolve(pk, sk);
+    
+    if (resolved) {
+        console.log('Successfully resolved:', JSON.stringify(resolved, null, 2));
+    } else {
+        console.log('Failed to resolve.');
+    }
+
+    // Test Strict Mode with Expired Record
+    console.log('Testing expired record in strict mode...');
+    const expiredPayload: NCC05Payload = {
+        v: 1,
+        ttl: 1,
+        updated_at: Math.floor(Date.now() / 1000) - 10, // 10s ago
+        endpoints: [{ type: 'tcp', uri: '1.1.1.1:1', priority: 1, family: 'ipv4' }]
+    };
+    await publisher.publish(relays, sk, expiredPayload, 'expired-test');
+    const strictResult = await resolver.resolve(pk, sk, 'expired-test', { strict: true });
+    
+    if (strictResult === null) {
+        console.log('Correctly rejected expired record in strict mode.');
+    } else {
+        console.error('FAILED: Strict mode allowed an expired record.');
+        process.exit(1);
+    }
+
+    // Test Gossip Mode
+    console.log('Testing Gossip discovery...');
+    // In this test, we just point kind:10002 to the same relay we are using
+    // to verify the code path executes.
+    const relayListTemplate = {
+        kind: 10002,
+        created_at: Math.floor(Date.now() / 1000),
+        tags: [['r', relays[0]]],
+        content: '',
+    };
+    const signedRL = (await import('nostr-tools')).finalizeEvent(relayListTemplate, sk);
+    await Promise.all(publisher['pool'].publish(relays, signedRL));
+    
+    const gossipResult = await resolver.resolve(pk, sk, 'addr', { gossip: true });
+    if (gossipResult) {
+        console.log('Gossip discovery successful.');
+    } else {
+        console.error('FAILED: Gossip discovery did not find record.');
+        process.exit(1);
+    }
+
+    // Test npub resolution
+    console.log('Testing npub resolution...');
+    const npub = (await import('nostr-tools')).nip19.npubEncode(pk);
+    const npubResult = await resolver.resolve(npub, sk);
+    if (npubResult) {
+        console.log('npub resolution successful.');
+    } else {
+        console.error('FAILED: npub resolution did not find record.');
+        process.exit(1);
+    }
+
+    publisher.close(relays);
+    resolver.close();
+    process.exit(0);
+}
+
+test().catch(console.error);

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}