ncc-06-js 0.4.2 → 0.6.0

package/DOCS.md

@@ -7,10 +7,10 @@
 These functions help build, parse, and verify NCC-02 service records (kind `30059`).
 
 ### `buildNcc02ServiceRecord(options)`
-- **Purpose**: create a signed service record containing `d`, `u`, `k`, and `exp`.
+- **Purpose**: asynchronously create a signed service record containing `d`, `u`, `k`, `exp`, and optional privacy metadata.
 - **Example**:
   ```js
-  const event = buildNcc02ServiceRecord({
+  const event = await buildNcc02ServiceRecord({
     secretKey,
     serviceId: 'relay',
     endpoint: 'wss://127.0.0.1:7447',

package/eslint.config.js

@@ -0,0 +1,31 @@
+import { fileURLToPath, URL } from 'node:url';
+import { FlatCompat } from '@eslint/eslintrc';
+import globals from 'globals';
+import pkg from '@eslint/js';
+
+const { configs } = pkg;
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const compat = new FlatCompat({ baseDirectory: __dirname, recommendedConfig: configs.recommended });
+const envGlobals = {
+  ...globals.es2020,
+  ...globals.node
+};
+
+export default [
+  ...compat.extends('eslint:recommended'),
+  {
+    languageOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'module',
+      globals: envGlobals
+    },
+    rules: {
+      'no-unused-vars': [
+        'warn',
+        {
+          argsIgnorePattern: '^_'
+        }
+      ]
+    }
+  }
+];

package/index.d.ts

@@ -17,9 +17,11 @@ declare module 'ncc-06-js' {
     expirySeconds?: number;
     kind?: number;
     createdAt?: number;
+    isPrivate?: boolean;
+    privateRecipients?: string[];
   }
 
-  export function buildNcc02ServiceRecord(options: BuildNcc02Options): NostrEvent;
+  export function buildNcc02ServiceRecord(options: BuildNcc02Options): Promise<NostrEvent>;
   export function parseNcc02Tags(event: NostrEvent): Record<string, string | undefined>;
   export interface ValidateNcc02Options {
     expectedAuthor?: string;
@@ -95,6 +97,7 @@ declare module 'ncc-06-js' {
     locatorId: string;
     expectedK?: string;
     torPreferred?: boolean;
+    allowedProtocols?: string[];
     locatorSecretKey?: string;
     ncc05TimeoutMs?: number;
     publicationRelayTimeoutMs?: number;
@@ -259,4 +262,4 @@ declare module 'ncc-06-js' {
     ncc02ExpectedKey?: string;
   }
   export function buildClientConfig(options: ClientConfigOptions): ClientConfig;
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ncc-06-js",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Reusable NCC-06 discovery helpers for multimodal service identities.",
   "type": "module",
   "main": "src/index.js",
@@ -10,13 +10,15 @@
     "lint": "eslint . --ext .js"
   },
   "dependencies": {
-    "ncc-02-js": "^0.3.0",
-    "ncc-05-js": "^1.1.14",
+    "ncc-02-js": "^0.5.0",
+    "ncc-05-js": "^1.2.0",
     "nostr-tools": "^2.19.4",
     "selfsigned": "^5.4.0",
     "ws": "^8.18.3"
   },
   "devDependencies": {
+    "@eslint/eslintrc": "^2.0.3",
+    "@eslint/js": "^9.39.2",
     "@types/node": "^25.0.3",
     "eslint": "^9.39.2",
     "typescript": "^5.9.3"

package/src/external-endpoints.js

@@ -3,6 +3,7 @@ import os from 'os';
 const IPV4_PRIORITY = 10;
 const IPV6_PRIORITY = 20;
 const ONION_PRIORITY = 30;
+const SECURE_PROTOCOLS = new Set(['wss', 'https', 'tls', 'tcps']);
 
 /**
  * Build a list of external endpoints that the operator wants to publish.
@@ -43,22 +44,24 @@ export async function buildExternalEndpoints({
   if (ipv6?.enabled) {
     const address = detectGlobalIPv6();
     if (address) {
-      const protocol = ipv6.protocol || 'ws';
-      const port = ipv6.port || (protocol === 'wss' ? wssPort : wsPort);
+      const protocol = (ipv6.protocol || 'ws').toLowerCase();
+      const secure = isSecureProtocol(protocol);
+      const port = ipv6.port || (secure ? wssPort : wsPort);
       const url = `${protocol}://[${address}]:${port}`;
       addEndpoint({
         url,
         priority: IPV6_PRIORITY,
         family: 'ipv6',
         protocol,
-        k: protocol === 'wss' ? ncc02ExpectedKey : undefined
+        k: secure ? ncc02ExpectedKey : undefined
       });
     }
   }
 
   if (ipv4?.enabled) {
-    const protocol = ipv4.protocol || 'wss';
-    const port = ipv4.port || (protocol === 'wss' ? wssPort : wsPort);
+    const protocol = (ipv4.protocol || 'wss').toLowerCase();
+    const secure = isSecureProtocol(protocol);
+    const port = ipv4.port || (secure ? wssPort : wsPort);
     const address = ipv4.address || (await getPublicIPv4({ sources: ipv4.publicSources ?? publicIpv4Sources }));
     if (address) {
       addEndpoint({
@@ -66,7 +69,7 @@ export async function buildExternalEndpoints({
         priority: IPV4_PRIORITY,
         family: 'ipv4',
         protocol,
-        k: protocol === 'wss' ? ncc02ExpectedKey : undefined
+        k: secure ? ncc02ExpectedKey : undefined
       });
     }
   }
@@ -126,13 +129,19 @@ export async function getPublicIPv4({ sources = ['https://api.ipify.org?format=j
       if (match) {
         return match[0];
       }
-    } catch (err) {
+    } catch {
       continue;
     }
   }
   return null;
 }
 
+function isSecureProtocol(protocol) {
+  if (!protocol) return false;
+  const normalized = protocol.toLowerCase();
+  return SECURE_PROTOCOLS.has(normalized) || (normalized.endsWith('s') && normalized !== 'ws');
+}
+
 export function normalizeRelayUrl(url) {
   if (!url) return '';
   let normalized = url.trim();
@@ -152,5 +161,3 @@ export function normalizeRelays(relays) {
     .map(normalizeRelayUrl);
   return [...new Set(normalized)];
 }
-
-

package/src/ncc02.js

@@ -1,39 +1,37 @@
-import { finalizeEvent, getPublicKey, validateEvent, verifyEvent } from 'nostr-tools/pure';
+import { NCC02Builder, verifyNCC02Event } from 'ncc-02-js';
 
-const DEFAULT_KIND = 30059;
+const DEFAULT_EXPIRY_SECONDS = 14 * 24 * 60 * 60;
 
-/**
- * Build an NCC-02 service record event.
- */
-export function buildNcc02ServiceRecord({
+function ensureSecretKey(key) {
+  if (!key) {
+    throw new Error('secretKey is required');
+  }
+  return key;
+}
+
+export async function buildNcc02ServiceRecord({
   secretKey,
   serviceId,
   endpoint,
   fingerprint,
-  expirySeconds = 14 * 24 * 60 * 60,
-  createdAt,
-  kind = DEFAULT_KIND
+  expirySeconds = DEFAULT_EXPIRY_SECONDS,
+  isPrivate = false,
+  privateRecipients
 }) {
-  if (!secretKey) {
-    throw new Error('secretKey is required');
+  ensureSecretKey(secretKey);
+  if (!serviceId) {
+    throw new Error('serviceId is required');
   }
-  const timestamp = createdAt ?? Math.floor(Date.now() / 1000);
-  const expiresAt = timestamp + Number(expirySeconds);
-  const tags = [
-    ['d', serviceId],
-    ['exp', expiresAt.toString()]
-  ];
-  if (endpoint) tags.push(['u', endpoint]);
-  if (fingerprint) tags.push(['k', fingerprint]);
-
-  const event = {
-    kind,
-    pubkey: getPublicKey(secretKey),
-    created_at: timestamp,
-    tags,
-    content: ''
-  };
-  return finalizeEvent(event, secretKey);
+  const builder = new NCC02Builder(secretKey);
+  const expiryDays = Number(expirySeconds) / (24 * 60 * 60);
+  return builder.createServiceRecord({
+    serviceId,
+    endpoint,
+    fingerprint,
+    expiryDays,
+    isPrivate,
+    privateRecipients
+  });
 }
 
 export function parseNcc02Tags(event) {
@@ -44,10 +42,10 @@ export function parseNcc02Tags(event) {
 }
 
 export function validateNcc02(event, { expectedAuthor, expectedD, now, allowExpired = false } = {}) {
-  if (!event || event.kind !== DEFAULT_KIND) {
+  if (!event || event.kind !== 30059) {
     return false;
   }
-  if (!validateEvent(event) || !verifyEvent(event)) {
+  if (!verifyNCC02Event(event)) {
     return false;
   }
   const tags = parseNcc02Tags(event);

package/src/ncc05.js

@@ -21,7 +21,7 @@ export function parseLocatorPayload(content) {
   }
   try {
     return JSON.parse(content);
-  } catch (err) {
+  } catch {
     return null;
   }
 }

package/src/protocol.js

@@ -12,7 +12,7 @@ export function parseNostrMessage(messageString) {
       return null;
     }
     return payload;
-  } catch (error) {
+  } catch {
     return null;
   }
 }

package/src/resolver.js

@@ -1,6 +1,6 @@
-import WebSocket from 'ws';
 import { SimplePool } from 'nostr-tools';
 import { NCC05Resolver } from 'ncc-05-js';
+import { parsePrivateFlag } from 'ncc-02-js';
 import { validateNcc02, parseNcc02Tags } from './ncc02.js';
 import { validateLocatorFreshness, normalizeLocatorEndpoints } from './ncc05.js';
 import { choosePreferredEndpoint } from './selector.js';
@@ -18,6 +18,7 @@ export async function resolveServiceEndpoint(options = {}) {
     locatorId,
     expectedK,
     torPreferred = false,
+    allowedProtocols,
     locatorSecretKey,
     ncc05TimeoutMs = 5000,
     publicationRelayTimeoutMs = DEFAULT_RELAY_TIMEOUT_MS,
@@ -46,37 +47,49 @@ export async function resolveServiceEndpoint(options = {}) {
 
   let serviceRecord;
   if (ncc02Resolver) {
-    serviceRecord = await ncc02Resolver.resolve(servicePubkey, serviceId, {});
+    try {
+        serviceRecord = await ncc02Resolver.resolve(servicePubkey, serviceId, {});
+    } catch (e) {
+        serviceRecord = await ncc02Resolver.resolveLatest(servicePubkey, {});
+    }
   } else {
     const poolToUse = pool || new SimplePool();
     try {
-      const filters = [{
+      const filter = {
         kinds: [30059],
-        authors: [servicePubkey],
-        '#d': [serviceId]
-      }];
-      const events = await new Promise((resolve) => {
-        const results = [];
-        const sub = poolToUse.subscribeMany(bootstrapRelays, filters, {
-          onevent(e) { results.push(e); },
-          oneose() { sub.close(); resolve(results); }
-        });
-        setTimeout(() => { sub.close(); resolve(results); }, publicationRelayTimeoutMs);
-      });
-
-      // Sort and validate
-      const validEvents = events
-        .filter(e => validateNcc02(e, { expectedAuthor: servicePubkey, expectedD: serviceId, now: timestamp }))
+        authors: [servicePubkey]
+      };
+      
+      console.log(`[NCC-Resolver] Querying relays for author ${servicePubkey}...`);
+      const events = await poolToUse.querySync(bootstrapRelays, filter);
+      
+      let validEvents = (events || [])
+        .filter(e => {
+            const tags = parseNcc02Tags(e);
+            return tags.d === serviceId && validateNcc02(e, { expectedAuthor: servicePubkey, expectedD: serviceId, now: timestamp });
+        })
         .sort((a, b) => b.created_at - a.created_at);
       
+      if (validEvents.length === 0) {
+          console.log(`[NCC-Resolver] No specific record for "${serviceId}", falling back to latest...`);
+          validEvents = (events || [])
+            .filter(e => validateNcc02(e, { expectedAuthor: servicePubkey, now: timestamp }))
+            .sort((a, b) => b.created_at - a.created_at);
+      }
+
+      console.log(`[NCC-Resolver] Found ${validEvents.length} candidate events.`);
+      
       if (validEvents[0]) {
         const tags = parseNcc02Tags(validEvents[0]);
+        console.log(`[NCC-Resolver] Selected NCC-02 record: ${validEvents[0].id} (d=${tags.d})`);
+        console.log(`[NCC-Resolver] Raw tags:`, JSON.stringify(validEvents[0].tags));
         serviceRecord = {
           endpoint: tags.u,
           fingerprint: tags.k,
           expiry: Number(tags.exp),
           eventId: validEvents[0].id,
-          pubkey: validEvents[0].pubkey
+          pubkey: validEvents[0].pubkey,
+          isPrivate: parsePrivateFlag(validEvents[0].tags) === true
         };
       }
     } finally {
@@ -85,7 +98,7 @@ export async function resolveServiceEndpoint(options = {}) {
   }
   
   if (!serviceRecord) {
-    throw new Error(`No valid NCC-02 record found for ${serviceId}`);
+    throw new Error(`No valid NCC-02 record found for ${servicePubkey}`);
   }
   
   // 2. Resolve NCC-05 Locator
@@ -103,6 +116,7 @@ export async function resolveServiceEndpoint(options = {}) {
     locatorPayload,
     expectedK,
     torPreferred,
+    allowedProtocols,
     now: timestamp
   });
 
@@ -115,14 +129,9 @@ export async function resolveServiceEndpoint(options = {}) {
   };
 }
 
-function determineEndpoint({ serviceRecord, locatorPayload, expectedK, torPreferred, now }) {
-  // serviceRecord is { endpoint, fingerprint, expiry, attestations, ... }
-  // It is already validated (signature, expiry).
-  
+function determineEndpoint({ serviceRecord, locatorPayload, expectedK, torPreferred, allowedProtocols, now }) {
   const ncc02Url = serviceRecord.endpoint;
   const k = serviceRecord.fingerprint;
-  // expiry check was done by resolver, but we check if we need to?
-  // NCC02Resolver throws if expired. So we can assume it's fresh.
   
   const result = {
     endpoint: null,
@@ -135,7 +144,8 @@ function determineEndpoint({ serviceRecord, locatorPayload, expectedK, torPrefer
     const normalized = normalizeLocatorEndpoints(locatorPayload.endpoints || []);
     const selection = choosePreferredEndpoint(normalized, {
       torPreferred,
-      expectedK
+      expectedK,
+      allowedProtocols
     });
     if (selection.endpoint) {
       return {
@@ -169,6 +179,10 @@ function determineEndpoint({ serviceRecord, locatorPayload, expectedK, torPrefer
   }
 
   result.reason = result.reason || 'no-endpoint';
+  if (serviceRecord.isPrivate && !locatorPayload) {
+      result.reason = 'private-no-decryption';
+  }
+  
   return result;
 }
 
@@ -184,7 +198,7 @@ async function defaultResolveLocator({
     timeout
   });
   try {
-    return await resolver.resolve(servicePubkey, locatorSecretKey, locatorId, {
+    return await resolver.resolveLatest(servicePubkey, locatorSecretKey, {
       strict: false,
       gossip: false
     });
@@ -193,5 +207,4 @@ async function defaultResolveLocator({
       resolver.close();
     }
   }
-}
-
+}

package/src/sidecar-config.js

@@ -1,17 +1,4 @@
-import { DEFAULT_TTL_SECONDS } from './ncc05.js';
-import { getExpectedK } from './k.js';
-
-const DEFAULT_TOR_CONTROL = {
-  enabled: false,
-  host: '127.0.0.1',
-  port: 9051,
-  password: '',
-  servicePort: 80,
-  serviceFile: './onion-service.json',
-  timeout: 5000
-};
-
-import { normalizeRelayUrl, normalizeRelays } from './external-endpoints.js';
+import { normalizeRelayUrl } from './external-endpoints.js';
 
 const RELAY_MODE_PUBLIC = 'public';
 const RELAY_MODE_PRIVATE = 'private';

package/test/ncc02.test.js

@@ -3,14 +3,17 @@ import { strict as assert } from 'assert';
 import { buildNcc02ServiceRecord, parseNcc02Tags, validateNcc02 } from '../src/ncc02.js';
 import { generateKeypair } from '../src/keys.js';
 
-test('builds and validates NCC-02 service record', () => {
+test('builds and validates NCC-02 service record', async () => {
   const { secretKey, publicKey } = generateKeypair();
-  const serviceEvent = buildNcc02ServiceRecord({
+  const recipients = ['cipher-text-1', 'cipher-text-2'];
+  const serviceEvent = await buildNcc02ServiceRecord({
     secretKey,
     serviceId: 'relay',
     endpoint: 'wss://127.0.0.1:7447',
     fingerprint: 'TESTKEY:resolver',
-    expirySeconds: 60
+    expirySeconds: 60,
+    isPrivate: true,
+    privateRecipients: recipients
   });
 
   assert.equal(serviceEvent.pubkey, publicKey);
@@ -18,5 +21,8 @@ test('builds and validates NCC-02 service record', () => {
   assert.equal(tags.d, 'relay');
   assert.equal(tags.u, 'wss://127.0.0.1:7447');
   assert.equal(tags.k, 'TESTKEY:resolver');
+  assert.equal(tags.private, 'true');
+  const privateTagCount = serviceEvent.tags.filter(t => t[0] === 'privateRecipients').length;
+  assert.strictEqual(privateTagCount, recipients.length);
   assert.ok(validateNcc02(serviceEvent, { expectedAuthor: publicKey, expectedD: 'relay' }));
 });