ncc-06-js 0.2.3 → 0.3.0

package/DOCS.md

@@ -43,28 +43,29 @@ Utilities for locator payload construction and evaluation.
 
 ## NCC-06 helpers
 
-### `choosePreferredEndpoint(endpoints, { torPreferred?, expectedK? })`
-- Applies NCC-06 policy: prefer `wss://` with matching `k`, favor onion if `torPreferred`, fall back to any `ws://`.
+### `choosePreferredEndpoint(endpoints, { torPreferred?, expectedK?, allowedProtocols? })`
+- Applies NCC-06 policy: favors onion if `torPreferred`, filters by `allowedProtocols` (default: `['wss', 'ws']`), and validates `k` fingerprints for secure protocols (`wss`, `https`, `tls`, etc).
 - Returns `{ endpoint?: NormalizedEndpoint, reason?: string, expected?, actual? }`.
 
 ### `resolveServiceEndpoint(options)`
 - Orchestrates resolution by querying bootstrap relays, preferring NCC-05 locators, and falling back to NCC-02 records.
-- **Options** include `bootstrapRelays`, `servicePubkey`, `serviceId`, `locatorId`, `expectedK`, `locatorSecretKey`, `torPreferred`, timeouts, and override hooks.
-- **Returns** `{ endpoint, source, serviceEvent, locatorPayload, selection }`.
+- **Options** include `bootstrapRelays`, `servicePubkey`, `serviceId`, `locatorId`, `expectedK`, `locatorSecretKey`, `torPreferred`, `allowedProtocols`, timeouts, and override hooks.
+- **Returns** `{ endpoint, source, serviceRecord, locatorPayload, selection }`.
 
 ## Sidecar config helpers
 
 ### `buildSidecarConfig(options)`
-- Mirrors the example sidecar setup and derives `ncc02ExpectedKey`, `publishRelays`, and `torControl` from operator intent so you do not need to duplicate those scripts.
+- Mirrors the example sidecar setup and derives `ncc02ExpectedKey`, `publishRelays`, and `torControl` from operator intent.
+- Supports `serviceUrl` and `serviceMode` as aliases for `relayUrl` and `relayMode`.
 
 ### `getRelayMode(config)`
-- Returns the normalized `"public"` or `"private"` mode that drives whether the sidecar publishes NCC-05 locators.
+- Returns the normalized `"public"` or `"private"` mode based on `relayMode` or `serviceMode`.
 
 ### `setRelayMode(config, mode)`
-- Normalizes and writes `"public"` or `"private"` back into the config object so you can persistively toggle the relay’s exposure level.
+- Normalizes and writes `"public"` or `"private"` back into the config object (setting both `relayMode` and `serviceMode`).
 
 ### `buildClientConfig(options)`
-- Rehydrates the minimal client config that the example resolver expects; dedupes publication relays, enforces `serviceIdentityUri`, and carries the `expectedK` for NCC-02 pinning.
+- Rehydrates the minimal client config that the example resolver expects. Supports `serviceUrl` as alias for `relayUrl`.
 
 ## Key and TLS helpers
 

package/README.md

@@ -6,14 +6,13 @@ Reusable helpers extracted from the NCC-06 example relay, sidecar, and client im
 
 - **NCC-02 builders & validators** (`buildNcc02ServiceRecord`, `parseNcc02Tags`, `validateNcc02`) that manage the `d`, `u`, `k`, and `exp` tags a service record must expose.
 - **NCC-05 helpers** (`buildLocatorPayload`, `normalizeLocatorEndpoints`, `validateLocatorFreshness`) that assemble locator payloads, parse stored JSON, and enforce TTL/`updated_at` freshness rules.
-- **Deterministic NCC-06 resolution** via `choosePreferredEndpoint` and `resolveServiceEndpoint`, which query bootstrap relays, prefer fresh NCC-05 locators, verify `k` fingerprints for `wss://`, and fall back to NCC-02 `u` values.
-- **External endpoint helpers** (`buildExternalEndpoints`, `detectGlobalIPv6`, `getPublicIPv4`) so sidecars can declare onion/IPv6/IPv4 reachability in a reproducible order without making the relay probe the network.
-- **Scheduling helpers** (`scheduleWithJitter`) for applying bounded jitter to recurring NCC-02/NCC-05 timers without ever publishing outside the declared window.
-- **TLS/key utilities** (`ensureSelfSignedCert`, `generateKeypair`, `toNpub`, `fromNsec`, `generateExpectedK`, `validateExpectedKFormat`) that mirror the key and fingerprint management used by the example sidecar.
-- **Lightweight protocol helpers** (`parseNostrMessage`, `serializeNostrMessage`, `createReqMessage`) for downstream code that wants to reuse the same framing logic as the example client.
-- **Sidecar config helpers** (`buildSidecarConfig`, `buildClientConfig`) so you can reuse the same config generation logic the example sidecar/client rely on without copying the scripts.
-- **TypeScript definitions** (`index.d.ts`) that describe every exported helper, making it easier to import from TypeScript consumers.
-- **Relay mode helpers** (`getRelayMode`, `setRelayMode`) so you can portrait whether your relay is *public* (publishes NCC-05 locators) or *private* (only maintains an NCC-02 record without advertising endpoints).
+- **Deterministic NCC-06 resolution** via `choosePreferredEndpoint` and `resolveServiceEndpoint`. It queries bootstrap relays, prefers fresh NCC-05 locators, verifies `k` fingerprints for any secure protocol (`wss://`, `https://`, etc.), and falls back to NCC-02 `u` values.
+- **Service-Agnostic Helpers:** While originally built for relays, all helpers support generic `serviceUrl`, `serviceMode`, and custom `allowedProtocols`.
+- **External endpoint helpers** (`buildExternalEndpoints`, `detectGlobalIPv6`, `getPublicIPv4`) so services can declare onion/IPv6/IPv4 reachability in a reproducible order.
+...
+- **Sidecar config helpers** (`buildSidecarConfig`, `buildClientConfig`) so you can reuse the same config generation logic. Supports `serviceUrl` and `serviceMode` aliases for broader application.
+...
+- **Relay & Service mode helpers** (`getRelayMode`, `setRelayMode`) so you can control whether your service is *public* (publishes NCC-05 locators) or *private`.
 
 ## Usage
 
@@ -23,36 +22,37 @@ Install directly from the repository (example workspace):
 npm install ../ncc-06-js
 ```
 
-Then import the helpers you need:
+### Resolving an HTTP API Service
 
 ```js
-import {
-  resolveServiceEndpoint,
-  buildExternalEndpoints,
-  generateExpectedK
-} from 'ncc-06-js';
-
-const endpoints = await buildExternalEndpoints({
-  ipv4: { enabled: true, protocol: 'wss', address: '1.2.3.4', port: 7447 },
-  wsPort: 7000,
-  wssPort: 7447,
-  ncc02ExpectedKey: 'TESTKEY:relay-local-dev-1',
-  ensureOnionService
-});
+import { resolveServiceEndpoint } from 'ncc-06-js';
 
 const resolution = await resolveServiceEndpoint({
-  bootstrapRelays: ['ws://127.0.0.1:7000'],
+  bootstrapRelays: ['wss://relay.damus.io'],
   servicePubkey: '...',
-  serviceId: 'relay',
-  locatorId: 'relay-locator',
-  expectedK: 'TESTKEY:relay-local-dev-1',
-  locatorSecretKey: '...'
+  serviceId: 'my-api',
+  locatorId: 'api-locator',
+  expectedK: '...', // SPKI fingerprint for HTTPS pinning
+  allowedProtocols: ['https', 'http'] // Override default [wss, ws]
 });
 
-console.log('Resolved endpoint:', resolution.endpoint);
+console.log('Resolved API endpoint:', resolution.endpoint);
+```
+
+### Building a Service Config
+
+```js
+import { buildSidecarConfig } from 'ncc-06-js';
+
+const config = buildSidecarConfig({
+  secretKey: '...',
+  serviceUrl: 'https://api.example.com',
+  serviceId: 'my-api',
+  serviceMode: 'public'
+});
 ```
 
-The package exposes modular helpers so you can keep using your own transport stack while reusing the deterministic NCC-06 behaviour that now powers the `ncc06-client` harness.
+The package exposes modular helpers so you can keep using your own transport stack while reusing deterministic NCC-06 behaviour.
 
 ## Trust model
 

package/index.d.ts

@@ -34,7 +34,7 @@ declare module 'ncc-06-js' {
     type?: string;
     uri?: string;
     value?: string;
-    protocol?: 'ws' | 'wss';
+    protocol?: string;
     family?: 'ipv4' | 'ipv6' | 'onion' | string;
     priority?: number;
     prio?: number;
@@ -65,6 +65,7 @@ declare module 'ncc-06-js' {
   export interface SelectorOptions {
     torPreferred?: boolean;
     expectedK?: string;
+    allowedProtocols?: string[];
   }
   export interface SelectorResult {
     endpoint: LocatorEndpoint | null;
@@ -78,6 +79,15 @@ declare module 'ncc-06-js' {
   ): SelectorResult;
   export { normalizeLocatorEndpoints };
 
+  export interface ResolvedService {
+    endpoint?: string;
+    fingerprint?: string;
+    expiry: number;
+    attestations: any[];
+    eventId: string;
+    pubkey: string;
+  }
+
   export interface ResolverOptions {
     bootstrapRelays: string[];
     servicePubkey: string;
@@ -88,11 +98,8 @@ declare module 'ncc-06-js' {
     locatorSecretKey?: string;
     ncc05TimeoutMs?: number;
     publicationRelayTimeoutMs?: number;
-    queryRelayEvents?: (
-      relays: string[],
-      filter: Record<string, unknown>,
-      options?: { timeoutMs?: number }
-    ) => Promise<NostrEvent[]>;
+    pool?: any;
+    ncc02Resolver?: any;
     resolveLocator?: (options: {
       bootstrapRelays: string[];
       servicePubkey: string;
@@ -100,7 +107,6 @@ declare module 'ncc-06-js' {
       locatorSecretKey?: string;
       timeout?: number;
     }) => Promise<LocatorPayload | null>;
-    throttle?: unknown;
     now?: number;
   }
   export interface ResolverSelection {
@@ -113,7 +119,7 @@ declare module 'ncc-06-js' {
     endpoint: string | null;
     source: 'locator' | 'ncc02' | null;
     locatorPayload: LocatorPayload | null;
-    serviceEvent: NostrEvent;
+    serviceRecord: ResolvedService;
     selection: ResolverSelection;
   }
   export function resolveServiceEndpoint(options: ResolverOptions): Promise<ResolverResult>;
@@ -179,14 +185,14 @@ declare module 'ncc-06-js' {
     };
     ipv4?: {
       enabled?: boolean;
-      protocol?: 'ws' | 'wss';
+      protocol?: string;
       port?: number;
       address?: string;
       publicSources?: string[];
     };
     ipv6?: {
       enabled?: boolean;
-      protocol?: 'ws' | 'wss';
+      protocol?: string;
       port?: number;
     };
     wsPort?: number;
@@ -198,76 +204,59 @@ declare module 'ncc-06-js' {
   export function buildExternalEndpoints(options?: ExternalEndpointOptions): Promise<LocatorEndpoint[]>;
   export function detectGlobalIPv6(): string | null;
   export function getPublicIPv4(options?: { sources?: string[] }): Promise<string | null>;
+  export function normalizeRelayUrl(url: string): string;
+  export function normalizeRelays(relays: string[]): string[];
 
   export interface SidecarConfigOptions {
-    serviceSk: string;
-    servicePk: string;
-    serviceNpub: string;
-    relayUrl: string;
+    secretKey: string;
+    serviceUrl?: string;
+    relayUrl?: string;
     serviceId?: string;
     locatorId?: string;
     publicationRelays?: string[];
     publishRelays?: string[];
-    ncc02ExpSeconds?: number;
-    ncc05TtlSeconds?: number;
-    torControl?: Record<string, unknown>;
-    externalEndpoints?: Record<string, unknown>;
-    k?: KConfig;
-    baseDir?: string;
+    persistPath?: string;
+    certPath?: string;
     relayMode?: 'public' | 'private';
-    ncc02ExpectedKeySource?: string;
+    serviceMode?: 'public' | 'private';
   }
   export interface SidecarConfig {
-    serviceSk: string;
-    servicePk: string;
-    serviceNpub: string;
+    secretKey: string;
+    serviceUrl: string;
     relayUrl: string;
     serviceId: string;
     locatorId: string;
     publicationRelays: string[];
     publishRelays: string[];
-    ncc02ExpSeconds: number;
-    ncc05TtlSeconds: number;
-    ncc02ExpectedKey: string;
-    ncc02ExpectedKeySource: string;
-    externalEndpoints: Record<string, unknown>;
-    torControl: Record<string, unknown>;
-    k: KConfig;
+    persistPath?: string;
+    certPath?: string;
     relayMode: 'public' | 'private';
+    serviceMode: 'public' | 'private';
   }
   export function buildSidecarConfig(options: SidecarConfigOptions): SidecarConfig;
-  export function getRelayMode(config?: { relayMode?: string }): 'public' | 'private';
+  export function getRelayMode(config?: { relayMode?: string, serviceMode?: string }): 'public' | 'private';
   export function setRelayMode(config?: Record<string, unknown>, mode: 'public' | 'private'): Record<string, unknown>;
 
   export interface ClientConfigOptions {
-    relayUrl: string;
-    servicePubkey?: string;
-    serviceNpub?: string;
     serviceIdentityUri?: string;
-    locatorSecretKey?: string;
-    locatorFriendPubkey?: string;
+    serviceNpub?: string;
+    servicePubkey?: string;
+    serviceUrl?: string;
+    relayUrl?: string;
     publicationRelays?: string[];
-    staleFallbackSeconds?: number;
-    torPreferred?: boolean;
-    ncc05TimeoutMs?: number;
     serviceId?: string;
     locatorId?: string;
-    expectedK?: string;
+    ncc02ExpectedKey?: string;
   }
   export interface ClientConfig {
-    relayUrl: string;
     serviceIdentityUri: string;
     servicePubkey: string;
-    serviceNpub: string;
+    serviceUrl: string;
+    relayUrl: string;
     publicationRelays: string[];
-    staleFallbackSeconds: number;
-    torPreferred: boolean;
-    ncc05TimeoutMs: number;
-    locatorSecretKey?: string;
-    locatorFriendPubkey?: string;
-    serviceId?: string;
-    locatorId?: string;
+    serviceId: string;
+    locatorId: string;
     ncc02ExpectedKey?: string;
   }
   export function buildClientConfig(options: ClientConfigOptions): ClientConfig;
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ncc-06-js",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Reusable NCC-06 discovery helpers extracted from the example relay, sidecar, and client.",
   "type": "module",
   "main": "src/index.js",
@@ -10,15 +10,15 @@
     "lint": "eslint . --ext .js"
   },
   "dependencies": {
-    "ncc-02-js": "^0.2.3",
-    "ncc-05-js": "^1.1.9",
+    "ncc-02-js": "^0.3.0",
+    "ncc-05-js": "^1.1.14",
     "nostr-tools": "^2.19.4",
     "selfsigned": "^5.4.0",
     "ws": "^8.18.3"
   },
   "devDependencies": {
-    "@types/node": "^20.7.2",
-    "eslint": "^8.54.0",
-    "typescript": "^5.5.3"
+    "@types/node": "^25.0.3",
+    "eslint": "^9.39.2",
+    "typescript": "^5.9.3"
   }
 }

package/src/external-endpoints.js

@@ -132,3 +132,25 @@ export async function getPublicIPv4({ sources = ['https://api.ipify.org?format=j
   }
   return null;
 }
+
+export function normalizeRelayUrl(url) {
+  if (!url) return '';
+  let normalized = url.trim();
+  if (normalized.endsWith('/')) {
+    normalized = normalized.slice(0, -1);
+  }
+  if (!normalized.includes('://')) {
+    normalized = `wss://${normalized}`;
+  }
+  return normalized;
+}
+
+export function normalizeRelays(relays) {
+  if (!Array.isArray(relays)) return [];
+  const normalized = relays
+    .filter(Boolean)
+    .map(normalizeRelayUrl);
+  return [...new Set(normalized)];
+}
+
+

package/src/ncc02.js

@@ -1,4 +1,5 @@
 import { finalizeEvent, getPublicKey, validateEvent, verifyEvent } from 'nostr-tools/pure';
+import { NCC02Builder } from 'ncc-02-js';
 
 const DEFAULT_KIND = 30059;
 
@@ -19,22 +20,31 @@ export function buildNcc02ServiceRecord({
   if (!secretKey) {
     throw new Error('secretKey is required to build NCC-02 records');
   }
-  const timestamp = createdAt ?? Math.floor(Date.now() / 1000);
-  const expiresAt = timestamp + Number(expirySeconds);
-  const tags = [
-    ['d', serviceId],
-    ['u', endpoint],
-    ['k', fingerprint],
-    ['exp', expiresAt.toString()]
-  ];
-  const event = {
-    kind,
-    pubkey: getPublicKey(secretKey),
-    created_at: timestamp,
-    tags,
-    content: ''
-  };
-  return finalizeEvent(event, secretKey);
+
+  const builder = new NCC02Builder(secretKey);
+  // NCC02Builder expects days.
+  const expiryDays = expirySeconds / (24 * 60 * 60);
+  
+  const event = builder.createServiceRecord({
+    serviceId,
+    endpoint,
+    fingerprint,
+    expiryDays
+  });
+
+  // If createdAt or kind override is needed, we must re-sign.
+  if (createdAt || kind !== DEFAULT_KIND) {
+    const template = {
+      ...event,
+      created_at: createdAt ?? event.created_at,
+      kind: kind ?? event.kind,
+      id: undefined,
+      sig: undefined
+    };
+    return finalizeEvent(template, secretKey);
+  }
+
+  return event;
 }
 
 /**
@@ -70,4 +80,4 @@ export function validateNcc02(event, { expectedAuthor, expectedD, now, allowExpi
     return false;
   }
   return true;
-}
+}

package/src/resolver.js

@@ -1,8 +1,7 @@
 import WebSocket from 'ws';
 import { NCC05Resolver } from 'ncc-05-js';
-import { parseNostrMessage, serializeNostrMessage, createReqMessage } from './protocol.js';
-import { validateNcc02, parseNcc02Tags } from './ncc02.js';
-import { normalizeLocatorEndpoints, validateLocatorFreshness } from './ncc05.js';
+import { NCC02Resolver } from 'ncc-02-js';
+import { validateLocatorFreshness, normalizeLocatorEndpoints } from './ncc05.js';
 import { choosePreferredEndpoint } from './selector.js';
 
 const DEFAULT_RELAY_TIMEOUT_MS = 5000;
@@ -21,7 +20,8 @@ export async function resolveServiceEndpoint(options = {}) {
     locatorSecretKey,
     ncc05TimeoutMs = 5000,
     publicationRelayTimeoutMs = DEFAULT_RELAY_TIMEOUT_MS,
-    queryRelayEvents,
+    pool, // Allow passing a shared pool
+    ncc02Resolver, // Injection for testing
     resolveLocator,
     now
   } = options;
@@ -40,22 +40,25 @@ export async function resolveServiceEndpoint(options = {}) {
   }
 
   const timestamp = now ?? Math.floor(Date.now() / 1000);
-  const fetchEvents = queryRelayEvents ?? defaultQueryRelayEvents;
   const locatorResolver = resolveLocator ?? defaultResolveLocator;
 
-  const filter = {
-    kinds: [30059],
-    authors: [servicePubkey],
-    '#d': [serviceId],
-    limit: 10
-  };
-
-  const events = await fetchEvents(bootstrapRelays, filter, { timeoutMs: publicationRelayTimeoutMs });
-  const serviceEvent = pickBestServiceRecord(events, timestamp, serviceId);
-  if (!serviceEvent) {
-    throw new Error('No valid NCC-02 service record available');
+  // 1. Resolve NCC-02 Service Record using the library
+  let serviceRecord;
+  try {
+    const resolver = ncc02Resolver || new NCC02Resolver(bootstrapRelays, { pool });
+    serviceRecord = await resolver.resolve(servicePubkey, serviceId, {
+       // We can pass options if needed, e.g. minLevel
+    });
+  } catch (err) {
+    // Map library errors or rethrow?
+    // The library throws generic Error or NCC02Error.
+    // We can just let it propagate or wrap.
+    // Existing code threw "No valid NCC-02 service record available".
+    // We'll let the library error bubble up as it provides more detail.
+    throw err;
   }
-
+  
+  // 2. Resolve NCC-05 Locator
   const locatorPayload = await locatorResolver({
     bootstrapRelays,
     servicePubkey,
@@ -64,8 +67,9 @@ export async function resolveServiceEndpoint(options = {}) {
     timeout: ncc05TimeoutMs
   });
 
+  // 3. Determine Endpoint
   const selection = determineEndpoint({
-    serviceEvent,
+    serviceRecord,
     locatorPayload,
     expectedK,
     torPreferred,
@@ -76,15 +80,20 @@ export async function resolveServiceEndpoint(options = {}) {
     endpoint: selection.endpoint,
     source: selection.source,
     locatorPayload,
-    serviceEvent,
+    serviceRecord,
     selection
   };
 }
 
-function determineEndpoint({ serviceEvent, locatorPayload, expectedK, torPreferred, now }) {
-  const tags = parseNcc02Tags(serviceEvent);
-  const ncc02Url = tags.u;
-  const isFreshService = !tags.exp || now <= Number(tags.exp);
+function determineEndpoint({ serviceRecord, locatorPayload, expectedK, torPreferred, now }) {
+  // serviceRecord is { endpoint, fingerprint, expiry, attestations, ... }
+  // It is already validated (signature, expiry).
+  
+  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,
     source: null,
@@ -110,20 +119,22 @@ function determineEndpoint({ serviceEvent, locatorPayload, expectedK, torPreferr
     result.evidence = selection;
   }
 
-  if (ncc02Url && isFreshService) {
-    if (ncc02Url.startsWith('wss://') && expectedK && tags.k && tags.k !== expectedK) {
+  if (ncc02Url) {
+    const isSecure = ncc02Url.match(/^(wss|https|tls|tcps):\/\//) || (ncc02Url.includes('://') && ncc02Url.split(':')[0].endsWith('s'));
+    
+    if (isSecure && expectedK && k && k !== expectedK) {
       return {
         endpoint: null,
         source: 'ncc02',
         reason: 'k-mismatch',
-        evidence: { expected: expectedK, actual: tags.k }
+        evidence: { expected: expectedK, actual: k }
       };
     }
     return {
       endpoint: ncc02Url,
       source: 'ncc02',
       reason: 'fallback',
-      evidence: { tags }
+      evidence: { endpoint: ncc02Url, fingerprint: k }
     };
   }
 
@@ -131,91 +142,6 @@ function determineEndpoint({ serviceEvent, locatorPayload, expectedK, torPreferr
   return result;
 }
 
-function pickBestServiceRecord(events, now, expectedServiceId) {
-  const candidates = [];
-  for (const event of events) {
-    if (!validateNcc02(event, { now, expectedD: expectedServiceId })) {
-      continue;
-    }
-    candidates.push(event);
-  }
-  return candidates.sort((a, b) => {
-    if (b.created_at !== a.created_at) {
-      return b.created_at - a.created_at;
-    }
-    return b.id.localeCompare(a.id);
-  })[0] || null;
-}
-
-async function defaultQueryRelayEvents(relays, filter, options = {}) {
-  const queries = relays.map(relay => queryRelayForEvents(relay, filter, options.timeoutMs));
-  const settled = await Promise.allSettled(queries);
-  return settled.reduce((acc, item) => {
-    if (item.status === 'fulfilled') {
-      return acc.concat(item.value);
-    }
-    return acc;
-  }, []);
-}
-
-function queryRelayForEvents(relayUrl, filter, timeoutMs = DEFAULT_RELAY_TIMEOUT_MS) {
-  return new Promise((resolve, reject) => {
-    const ws = new WebSocket(relayUrl);
-    const events = [];
-    const subId = `ncc06-${Math.random().toString(16).slice(2, 8)}`;
-    let settled = false;
-    const timer = setTimeout(() => {
-      if (!settled) {
-        settled = true;
-        ws.close();
-        resolve(events);
-      }
-    }, timeoutMs);
-
-    ws.onopen = () => {
-      ws.send(serializeNostrMessage(createReqMessage(subId, filter)));
-    };
-
-    ws.onmessage = raw => {
-      const message = parseNostrMessage(raw.data.toString());
-      if (!message) {
-        return;
-      }
-      const [type, ...payload] = message;
-      if (type === 'EVENT') {
-        const [receivedSubId, event] = payload;
-        if (receivedSubId === subId) {
-          events.push(event);
-        }
-      } else if (type === 'EOSE') {
-        const [receivedSubId] = payload;
-        if (receivedSubId === subId && !settled) {
-          settled = true;
-          clearTimeout(timer);
-          ws.close();
-          resolve(events);
-        }
-      }
-    };
-
-    ws.onerror = err => {
-      if (!settled) {
-        settled = true;
-        clearTimeout(timer);
-        reject(err);
-      }
-    };
-
-    ws.onclose = () => {
-      if (!settled) {
-        settled = true;
-        clearTimeout(timer);
-        resolve(events);
-      }
-    };
-  });
-}
-
 async function defaultResolveLocator({
   bootstrapRelays,
   servicePubkey,
@@ -236,3 +162,4 @@ async function defaultResolveLocator({
     resolver.close();
   }
 }
+

package/src/selector.js

@@ -9,41 +9,60 @@ function findByFamily(list, family) {
   return list.find(ep => ep.family === family);
 }
 
+function isSecureProtocol(protocol) {
+  return ['wss', 'https', 'tls', 'tcps'].includes(protocol) || (protocol && protocol.endsWith('s') && protocol !== 'ws');
+}
+
 /**
  * Choose which endpoint to connect to based on NCC-06 policy.
  * - prefers onion when torPreferred.
- * - prefers WSS endpoints with matching k.
+ * - filters by allowedProtocols (default: wss, ws).
+ * - validates 'k' for secure protocols.
  */
 export function choosePreferredEndpoint(endpoints = [], options = {}) {
-  const { torPreferred = false, expectedK } = options;
+  const { 
+    torPreferred = false, 
+    expectedK, 
+    allowedProtocols = ['wss', 'ws'] 
+  } = options;
+
   const normalized = endpoints.length ? endpoints : [];
-  const wssEndpoints = normalized.filter(ep => ep.protocol === 'wss');
-  const wsEndpoints = normalized.filter(ep => ep.protocol === 'ws');
+  
+  // Filter by allowed protocols
+  const candidates = normalized.filter(ep => allowedProtocols.includes(ep.protocol));
+
+  let selection = null;
 
-  let candidate = null;
+  // Tor Preference: Look for onion in candidates
   if (torPreferred) {
-    candidate = findByFamily(wssEndpoints, 'onion') || findByFamily(wsEndpoints, 'onion');
+    selection = findByFamily(candidates, 'onion');
   }
-  if (!candidate) {
-    candidate = pickByPriority(wssEndpoints) || pickByPriority(wsEndpoints);
+
+  // Priority Fallback
+  if (!selection) {
+    selection = pickByPriority(candidates);
   }
-  if (!candidate) {
+
+  if (!selection) {
     return { endpoint: null, reason: 'no-endpoint' };
   }
-  if (candidate.protocol === 'wss') {
-    if (!candidate.k) {
+
+  // Security Validation
+  if (isSecureProtocol(selection.protocol)) {
+    if (!selection.k) {
       return { endpoint: null, reason: 'missing-k' };
     }
-    if (expectedK && candidate.k !== expectedK) {
+    if (expectedK && selection.k !== expectedK) {
       return {
         endpoint: null,
         reason: 'k-mismatch',
         expected: expectedK,
-        actual: candidate.k
+        actual: selection.k
       };
     }
   }
-  return { endpoint: candidate };
+
+  return { endpoint: selection };
 }
 
 export { normalizeLocatorEndpoints };

package/src/sidecar-config.js

@@ -11,6 +11,8 @@ const DEFAULT_TOR_CONTROL = {
   timeout: 5000
 };
 
+import { normalizeRelayUrl, normalizeRelays } from './external-endpoints.js';
+
 const RELAY_MODE_PUBLIC = 'public';
 const RELAY_MODE_PRIVATE = 'private';
 
@@ -18,136 +20,112 @@ function normalizeRelayMode(mode) {
   if (!mode) {
     return RELAY_MODE_PUBLIC;
   }
-  const value = String(mode).toLowerCase();
+  const value = mode.toLowerCase();
   if (value !== RELAY_MODE_PUBLIC && value !== RELAY_MODE_PRIVATE) {
-    throw new Error(`relayMode must be "${RELAY_MODE_PUBLIC}" or "${RELAY_MODE_PRIVATE}"`);
+    throw new Error(`relayMode (or serviceMode) must be "${RELAY_MODE_PUBLIC}" or "${RELAY_MODE_PRIVATE}"`);
   }
   return value;
 }
 
-function uniqueList(items) {
-  const seen = new Set();
-  return items.filter(item => {
-    if (!item) return false;
-    const normalized = item.trim();
-    if (seen.has(normalized)) {
-      return false;
-    }
-    seen.add(normalized);
-    return true;
-  });
+function uniqueList(arr) {
+  return [...new Set(arr.filter(Boolean))];
 }
 
 export function getRelayMode(config = {}) {
-  return normalizeRelayMode(config.relayMode);
+  return normalizeRelayMode(config.relayMode || config.serviceMode);
 }
 
 export function setRelayMode(config = {}, mode) {
   const normalized = normalizeRelayMode(mode);
-  return { ...config, relayMode: normalized };
+  return { ...config, relayMode: normalized, serviceMode: normalized };
 }
 
 /**
- * Build a deployable sidecar config object that mirrors the example's defaults.
+ * Build configuration for the NCC-06 Sidecar.
  */
 export function buildSidecarConfig({
-  serviceSk,
-  servicePk,
-  serviceNpub,
+  secretKey,
+  serviceUrl,
   relayUrl,
   serviceId = 'relay',
   locatorId = 'relay-locator',
   publicationRelays = [],
   publishRelays,
-  ncc02ExpSeconds = 14 * 24 * 60 * 60,
-  ncc05TtlSeconds = DEFAULT_TTL_SECONDS,
-  torControl = DEFAULT_TOR_CONTROL,
-  externalEndpoints = {},
-  k = {},
-  baseDir = process.cwd(),
+  persistPath,
+  certPath,
   relayMode,
-  ncc02ExpectedKeySource
-} = {}) {
-  if (!serviceSk || !servicePk || !serviceNpub) {
-    throw new Error('service keypair must be provided');
+  serviceMode
+}) {
+  if (!secretKey) {
+    throw new Error('secretKey is required');
   }
-  if (!relayUrl) {
-    throw new Error('relayUrl is required');
+  
+  const primaryUrl = serviceUrl || relayUrl;
+  
+  if (!primaryUrl) {
+    throw new Error('serviceUrl (or relayUrl) is required');
   }
 
-  const expectedKey = getExpectedK({ k, externalEndpoints }, { baseDir });
-  const normalizedPublicationRelays = uniqueList([relayUrl, ...publicationRelays]);
+  const normalizedPrimaryUrl = normalizeRelayUrl(primaryUrl);
+  const normalizedPublicationRelays = uniqueList([normalizedPrimaryUrl, ...publicationRelays]);
   const normalizedPublishRelays = uniqueList([
-    relayUrl,
+    normalizedPrimaryUrl,
     ...(publishRelays ?? normalizedPublicationRelays)
   ]);
-  const keySource = ncc02ExpectedKeySource ?? k.mode ?? 'auto';
-  const normalizedRelayMode = normalizeRelayMode(relayMode);
+  
+  const mode = relayMode || serviceMode;
+  const normalizedMode = normalizeRelayMode(mode);
 
   return {
-    serviceSk,
-    servicePk,
-    serviceNpub,
-    relayUrl,
+    secretKey,
+    serviceUrl: normalizedPrimaryUrl,
+    relayUrl: normalizedPrimaryUrl, // Backward compatibility
     serviceId,
     locatorId,
     publicationRelays: normalizedPublicationRelays,
     publishRelays: normalizedPublishRelays,
-    ncc02ExpSeconds,
-    ncc05TtlSeconds,
-    ncc02ExpectedKey: expectedKey,
-    ncc02ExpectedKeySource: keySource,
-    externalEndpoints,
-    torControl,
-    k,
-    relayMode: normalizedRelayMode
+    persistPath,
+    certPath,
+    relayMode: normalizedMode,
+    serviceMode: normalizedMode // Alias
   };
 }
 
 /**
- * Build a client config that matches the NCC-06 example expectations.
+ * Build configuration for the NCC-06 Client.
  */
 export function buildClientConfig({
-  relayUrl,
-  servicePubkey,
-  serviceNpub,
   serviceIdentityUri,
-  locatorSecretKey,
-  locatorFriendPubkey,
+  serviceNpub, // Deprecated, but supported
+  servicePubkey,
+  serviceUrl,
+  relayUrl,
   publicationRelays = [],
-  staleFallbackSeconds = 600,
-  torPreferred = false,
-  ncc05TimeoutMs = 5000,
-  serviceId,
-  locatorId,
-  expectedK
-} = {}) {
-  if (!relayUrl) {
-    throw new Error('relayUrl is required');
-  }
-  const identityUri =
-    serviceIdentityUri || (serviceNpub ? `wss://${serviceNpub}` : undefined);
-  if (!identityUri) {
-    throw new Error('serviceIdentityUri or serviceNpub is required');
+  serviceId = 'relay',
+  locatorId = 'relay-locator',
+  ncc02ExpectedKey
+}) {
+  if (!serviceIdentityUri && !serviceNpub) {
+    throw new Error('serviceIdentityUri (or serviceNpub) is required');
   }
-  if (!servicePubkey) {
-    throw new Error('servicePubkey is required');
+  
+  const primaryUrl = serviceUrl || relayUrl;
+
+  if (!primaryUrl) {
+    throw new Error('serviceUrl (or relayUrl) is required');
   }
-  const publicationList = uniqueList([relayUrl, ...publicationRelays]);
+  
+  const normalizedPrimaryUrl = normalizeRelayUrl(primaryUrl);
+  const publicationList = uniqueList([normalizedPrimaryUrl, ...publicationRelays]);
 
   return {
-    relayUrl,
-    serviceIdentityUri: identityUri,
+    serviceIdentityUri: serviceIdentityUri || (serviceNpub ? `wss://${serviceNpub}` : null),
     servicePubkey,
-    serviceNpub: serviceNpub ?? '',
+    serviceUrl: normalizedPrimaryUrl,
+    relayUrl: normalizedPrimaryUrl, // Backward compatibility
     publicationRelays: publicationList,
-    staleFallbackSeconds,
-    torPreferred,
-    ncc05TimeoutMs,
-    locatorSecretKey,
-    locatorFriendPubkey,
     serviceId,
     locatorId,
-    ncc02ExpectedKey: expectedK
+    ncc02ExpectedKey
   };
 }

package/test/resolver.test.js

@@ -1,31 +1,23 @@
 import { test } from 'node:test';
 import { strict as assert } from 'assert';
 import { resolveServiceEndpoint } from '../src/resolver.js';
-import { buildNcc02ServiceRecord } from '../src/ncc02.js';
 import { buildLocatorPayload } from '../src/ncc05.js';
 import { generateKeypair } from '../src/keys.js';
 
 const SERVICE_ID = 'relay';
 const LOCATOR_ID = 'relay-locator';
 
-function buildServiceEvent({ secretKey, serviceId, endpoint, fingerprint }) {
-  return buildNcc02ServiceRecord({
-    secretKey,
-    serviceId,
-    endpoint,
-    fingerprint,
-    expirySeconds: 60
-  });
-}
-
 test('resolver prefers NCC-05 endpoint when k matches', async () => {
-  const { secretKey, publicKey } = generateKeypair();
-  const serviceEvent = buildServiceEvent({
-    secretKey,
-    serviceId: SERVICE_ID,
+  const { publicKey } = generateKeypair();
+  const mockServiceRecord = {
     endpoint: 'wss://fallback',
-    fingerprint: 'TESTKEY:match'
-  });
+    fingerprint: 'TESTKEY:match',
+    expiry: Math.floor(Date.now() / 1000) + 60,
+    attestations: [],
+    eventId: 'mock-id',
+    pubkey: publicKey
+  };
+
   const locatorPayload = buildLocatorPayload({
     ttl: 60,
     endpoints: [
@@ -39,7 +31,7 @@ test('resolver prefers NCC-05 endpoint when k matches', async () => {
     serviceId: SERVICE_ID,
     locatorId: LOCATOR_ID,
     expectedK: 'TESTKEY:match',
-    queryRelayEvents: async () => [serviceEvent],
+    ncc02Resolver: { resolve: async () => mockServiceRecord },
     resolveLocator: async () => locatorPayload
   });
 
@@ -48,13 +40,16 @@ test('resolver prefers NCC-05 endpoint when k matches', async () => {
 });
 
 test('resolver falls back to NCC-02 when locator k mismatches', async () => {
-  const { secretKey, publicKey } = generateKeypair();
-  const serviceEvent = buildServiceEvent({
-    secretKey,
-    serviceId: SERVICE_ID,
+  const { publicKey } = generateKeypair();
+  const mockServiceRecord = {
     endpoint: 'wss://fallback',
-    fingerprint: 'TESTKEY:match'
-  });
+    fingerprint: 'TESTKEY:match',
+    expiry: Math.floor(Date.now() / 1000) + 60,
+    attestations: [],
+    eventId: 'mock-id',
+    pubkey: publicKey
+  };
+
   const locatorPayload = buildLocatorPayload({
     ttl: 60,
     endpoints: [
@@ -68,11 +63,11 @@ test('resolver falls back to NCC-02 when locator k mismatches', async () => {
     serviceId: SERVICE_ID,
     locatorId: LOCATOR_ID,
     expectedK: 'TESTKEY:match',
-    queryRelayEvents: async () => [serviceEvent],
+    ncc02Resolver: { resolve: async () => mockServiceRecord },
     resolveLocator: async () => locatorPayload
   });
 
   assert.equal(result.endpoint, 'wss://fallback');
   assert.equal(result.source, 'ncc02');
   assert.equal(result.selection.reason, 'fallback');
-});
+});

package/test/selector.test.js

@@ -21,7 +21,32 @@ test('rejects mismatched k', () => {
 
 test('returns missing k reason', () => {
   const result = choosePreferredEndpoint([
-    { url: 'wss://no-k', protocol: 'wss', priority: 1 }
+    { protocol: 'wss', url: 'wss://secure', k: null }
   ]);
+  assert.equal(result.endpoint, null);
   assert.equal(result.reason, 'missing-k');
 });
+
+test('supports custom allowedProtocols and validates https k', () => {
+  const endpoints = [
+    { protocol: 'https', url: 'https://secure', k: 'key', priority: 1 },
+    { protocol: 'http', url: 'http://insecure', priority: 2 }
+  ];
+  const result = choosePreferredEndpoint(endpoints, {
+    allowedProtocols: ['https', 'http'],
+    expectedK: 'key'
+  });
+  assert.equal(result.endpoint.url, 'https://secure');
+});
+
+test('rejects https with mismatched k', () => {
+  const endpoints = [
+    { protocol: 'https', url: 'https://secure', k: 'wrong', priority: 1 }
+  ];
+  const result = choosePreferredEndpoint(endpoints, {
+    allowedProtocols: ['https'],
+    expectedK: 'key'
+  });
+  assert.equal(result.endpoint, null);
+  assert.equal(result.reason, 'k-mismatch');
+});

package/test/sidecar-config.test.js

@@ -8,22 +8,26 @@ import {
 } from '../src/sidecar-config.js';
 
 test('buildSidecarConfig constructs expected fields based on inputs', () => {
-  const cfg = buildSidecarConfig({
-    serviceSk: 'sk',
-    servicePk: 'pk',
-    serviceNpub: 'npub',
-    relayUrl: 'ws://localhost:7000',
-    k: { mode: 'static', value: 'TESTKEY:abc' },
-    publicationRelays: ['ws://aux:7001'],
-    externalEndpoints: {
-      ipv4: { enabled: true, protocol: 'ws', address: '127.0.0.1', port: 7447 }
-    }
+  const config = buildSidecarConfig({
+    secretKey: 'hex',
+    relayUrl: 'wss://test',
+    relayMode: 'private'
   });
+  assert.equal(config.relayUrl, 'wss://test');
+  assert.equal(config.serviceUrl, 'wss://test');
+  assert.equal(config.relayMode, 'private');
+});
 
-  assert.equal(cfg.serviceSk, 'sk');
-  assert.equal(cfg.ncc02ExpectedKey, 'TESTKEY:abc');
-  assert.deepEqual(cfg.publicationRelays[0], 'ws://localhost:7000');
-  assert.ok(cfg.publishRelays.length >= 1);
+test('buildSidecarConfig supports serviceUrl and serviceMode aliases', () => {
+  const config = buildSidecarConfig({
+    secretKey: 'hex',
+    serviceUrl: 'https://api.example.com',
+    serviceMode: 'private'
+  });
+  assert.equal(config.serviceUrl, 'https://api.example.com');
+  assert.equal(config.relayUrl, 'https://api.example.com');
+  assert.equal(config.serviceMode, 'private');
+  assert.equal(config.relayMode, 'private');
 });
 
 test('buildClientConfig enforces identity URI and relays', () => {
@@ -31,7 +35,7 @@ test('buildClientConfig enforces identity URI and relays', () => {
     relayUrl: 'ws://relay',
     servicePubkey: 'pk',
     serviceNpub: 'npub',
-    expectedK: 'TESTKEY:abc',
+    ncc02ExpectedKey: 'TESTKEY:abc',
     publicationRelays: ['ws://relay', 'ws://aux']
   });