ncc-06-js 0.2.0

package/DOCS.md

@@ -0,0 +1,110 @@
+# ncc-06-js API Reference
+
+`ncc-06-js` exposes a set of helpers organized around NCC-02/NCC-05 publication, NCC-06 resolution, endpoint discovery, transport framing, and runtime utilities. Each section below describes the intention, available arguments, and a usage snippet where appropriate.
+
+## NCC-02 helpers
+
+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`.
+- **Example**:
+  ```js
+  const event = buildNcc02ServiceRecord({
+    secretKey,
+    serviceId: 'relay',
+    endpoint: 'wss://127.0.0.1:7447',
+    fingerprint: expectedK,
+    expirySeconds: 60 * 60
+  });
+  ```
+
+### `parseNcc02Tags(event)`
+- Converts the `tags` array to an object map for easy lookups.
+
+### `validateNcc02(event, { expectedAuthor?, expectedD?, now?, allowExpired? })`
+- Validates signature, author, `d`, and expiration windows. Use `allowExpired` for stale fallback flows.
+
+## NCC-05 helpers
+
+Utilities for locator payload construction and evaluation.
+
+### `buildLocatorPayload({ endpoints = [], ttl = 3600, updatedAt })`
+- Normalizes each endpoint and generates `{ ttl, updated_at, endpoints }`.
+
+### `parseLocatorPayload(content)`
+- Safely parses JSON from the event content; returns `null` when parsing fails.
+
+### `validateLocatorFreshness(payload, { now?, allowStale? })`
+- Returns `true` when `now <= updated_at + ttl` (unless `allowStale` is true).
+
+### `normalizeLocatorEndpoints(endpoints)`
+- Normalizes each endpoint (protocol, family, priority, fingerprint/k) so `choosePreferredEndpoint` can trust consistent metadata.
+
+## 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://`.
+- 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 }`.
+
+## Key and TLS helpers
+
+### `generateExpectedK`, `validateExpectedKFormat`
+- Create or validate placeholder `TESTKEY:` tokens used during development.
+
+### `computeKFromCertPem(pem)`
+- Derives base64url SHA-256 of the certificate’s SPKI for TLS pinning.
+
+### `getExpectedK(cfg, { baseDir? })`
+- Reads a config block (`k.mode`) and returns the expected `k` string for static/generate/tls modes; used by the sidecar.
+
+### Key helpers
+- `generateKeypair()`, `toNpub()`, `fromNsec()` wrap `nostr-tools` key utilities for convenience.
+- `ensureSelfSignedCert(options)` generates a self-signed cert for local `wss://` endpoints.
+
+## Endpoint helpers
+
+### `buildExternalEndpoints(options)`
+- Builds NCC-05 endpoints (onion/IPv6/IPv4) from operator intent, adding `k` on `wss://` entries.
+- **Options**: `ipv4`, `ipv6`, `tor`, `wsPort`, `wssPort`, `ncc02ExpectedKey`, `ensureOnionService`, `publicIpv4Sources`.
+
+### `detectGlobalIPv6()`
+- Returns first global IPv6 (non-link-local/unique-local).
+
+### `getPublicIPv4({ sources? })`
+- Queries HTTP endpoints for the external IPv4 address; used when you don’t hardcode `ipv4.address`.
+
+## Scheduling helpers
+
+### `scheduleWithJitter(baseMs, jitterRatio = 0.15)`
+- Returns a delay between `0` and `baseMs` with ±`jitterRatio` wiggle. Used for sidecar timers to avoid synchronized republishing.
+
+## Light Nostr helpers
+
+- `parseNostrMessage(messageString)` / `serializeNostrMessage(messageArray)` guard the transport framing.
+- `createReqMessage(subId, ...filters)` builds a REQ payload for subscriptions.
+
+## Usage snapshot
+
+```js
+import { buildExternalEndpoints, resolveServiceEndpoint, scheduleWithJitter } from 'ncc-06-js';
+
+const endpoints = await buildExternalEndpoints({ ipv4: { enabled: true, protocol: 'wss', address: '127.0.0.1', port: 7447 }, ncc02ExpectedKey: 'TESTKEY:relay-local-dev-1' });
+const result = await resolveServiceEndpoint({
+  bootstrapRelays: ['ws://127.0.0.1:7000'],
+  servicePubkey,
+  serviceId: 'relay',
+  locatorId: 'relay-locator',
+  expectedK: 'TESTKEY:relay-local-dev-1',
+  locatorSecretKey
+});
+
+const delay = scheduleWithJitter(60000); // use this for republish timers
+```
+
+The helpers are intentionally small, focused on NCC-06 policy, and rely on the calling code for transport/threading so they can be reused inside Node scripts, CLI tools, or downstream SDKs.

package/README.md

@@ -0,0 +1,69 @@
+# ncc-06-js
+
+Reusable helpers extracted from the NCC-06 example relay, sidecar, and client implementations. This package focuses on the core utilities that compose NCC-02, NCC-05, and NCC-06 resolution and trust semantics without bundling a relay, sidecar, or heavy client.
+
+## Key features
+
+- **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.
+
+## Usage
+
+Install directly from the repository (example workspace):
+
+```bash
+npm install ../ncc-06-js
+```
+
+Then import the helpers you need:
+
+```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
+});
+
+const resolution = await resolveServiceEndpoint({
+  bootstrapRelays: ['ws://127.0.0.1:7000'],
+  servicePubkey: '...',
+  serviceId: 'relay',
+  locatorId: 'relay-locator',
+  expectedK: 'TESTKEY:relay-local-dev-1',
+  locatorSecretKey: '...'
+});
+
+console.log('Resolved endpoint:', resolution.endpoint);
+```
+
+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.
+
+## Trust model
+
+- `k` is the binding between NCC-02/NCC-05 records and the TLS key that serves `wss://` endpoints. Clients connect with `rejectUnauthorized=false` and enforce trust by comparing the published `k` value to the expected fingerprint before using the endpoint.
+- When migrating to real TLS/SPKI pins, update the sidecar to publish the real fingerprint via `ncc02ExpectedKey` and update the resolver’s `expectedK`. The shared helpers keep the rest of the resolution flow untouched.
+
+## Reference Docs
+
+Detailed API documentation lives in `DOCS.md` for quick lookup of every helper described above.
+
+## Testing
+
+```
+npm test
+```
+
+The tests cover the helper modules (NCC-02/NCC-05 builders, selector logic, endpoint builder, resolver) to keep the deterministic behaviour aligned with the example harness.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "ncc-06-js",
+  "version": "0.2.0",
+  "description": "Reusable NCC-06 discovery helpers extracted from the example relay, sidecar, and client.",
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint . --ext .js"
+  },
+  "dependencies": {
+    "ncc-02-js": "^0.2.2",
+    "ncc-05": "^1.1.8",
+    "nostr-tools": "^2.19.4",
+    "selfsigned": "^5.4.0",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.7.2",
+    "eslint": "^8.54.0"
+  }
+}

package/src/external-endpoints.js

@@ -0,0 +1,134 @@
+import os from 'os';
+
+const IPV4_PRIORITY = 10;
+const IPV6_PRIORITY = 20;
+const ONION_PRIORITY = 30;
+
+/**
+ * Build a list of external endpoints that the operator wants to publish.
+ * The helper never probes reachability; it only reflects config + the optional onion helper.
+ */
+export async function buildExternalEndpoints({
+  tor,
+  ipv4,
+  ipv6,
+  wsPort = 7000,
+  wssPort = 7447,
+  ncc02ExpectedKey,
+  ensureOnionService,
+  publicIpv4Sources = ['https://api.ipify.org?format=json']
+} = {}) {
+  const endpoints = [];
+  const timestamp = Date.now();
+
+  const addEndpoint = (entry) =>
+    endpoints.push({ ...entry, index: endpoints.length, createdAt: timestamp });
+
+  if (tor?.enabled && typeof ensureOnionService === 'function') {
+    try {
+      const onion = await ensureOnionService();
+      if (onion) {
+        addEndpoint({
+          url: `ws://${onion.address}:${onion.servicePort}`,
+          priority: ONION_PRIORITY,
+          family: 'onion',
+          protocol: 'ws'
+        });
+      }
+    } catch (err) {
+      console.warn('[NCC06] Onion endpoint could not be created:', err.message);
+    }
+  }
+
+  if (ipv6?.enabled) {
+    const address = detectGlobalIPv6();
+    if (address) {
+      const protocol = ipv6.protocol || 'ws';
+      const port = ipv6.port || (protocol === 'wss' ? wssPort : wsPort);
+      const url = `${protocol}://[${address}]:${port}`;
+      addEndpoint({
+        url,
+        priority: IPV6_PRIORITY,
+        family: 'ipv6',
+        protocol,
+        k: protocol === 'wss' ? ncc02ExpectedKey : undefined
+      });
+    }
+  }
+
+  if (ipv4?.enabled) {
+    const protocol = ipv4.protocol || 'wss';
+    const port = ipv4.port || (protocol === 'wss' ? wssPort : wsPort);
+    const address = ipv4.address || (await getPublicIPv4({ sources: ipv4.publicSources ?? publicIpv4Sources }));
+    if (address) {
+      addEndpoint({
+        url: `${protocol}://${address}:${port}`,
+        priority: IPV4_PRIORITY,
+        family: 'ipv4',
+        protocol,
+        k: protocol === 'wss' ? ncc02ExpectedKey : undefined
+      });
+    }
+  }
+
+  return endpoints
+    .sort((a, b) => {
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      return a.index - b.index;
+    })
+    .map(({ index, createdAt, ...endpoint }) => endpoint);
+}
+
+/**
+ * Look for the first non-internal, global IPv6 address.
+ */
+export function detectGlobalIPv6() {
+  const interfaces = os.networkInterfaces();
+  for (const iface of Object.values(interfaces)) {
+    if (!Array.isArray(iface)) continue;
+    for (const addr of iface) {
+      if (addr.family !== 'IPv6' || addr.internal) continue;
+      const value = addr.address.toLowerCase();
+      if (value.startsWith('::1')) continue;
+      if (value.startsWith('fe80')) continue;
+      if (value.startsWith('fc00') || value.startsWith('fd00')) continue;
+      if (!value.startsWith('2') && !value.startsWith('3')) continue;
+      return value;
+    }
+  }
+  return null;
+}
+
+/**
+ * Query public IPv4 services to fetch the external IPv4 address.
+ */
+export async function getPublicIPv4({ sources = ['https://api.ipify.org?format=json'] } = {}) {
+  const matcher = /((25[0-5]|2[0-4]\d|[01]?\d?\d)(\.|$)){4}/;
+  for (const source of sources) {
+    try {
+      const res = await fetch(source);
+      if (!res.ok) continue;
+      const text = (await res.text()).trim();
+      if (text.startsWith('{') || text.startsWith('[')) {
+        try {
+          const parsed = JSON.parse(text);
+          if (typeof parsed === 'object' && parsed !== null) {
+            const ip = parsed.ip || parsed.address || parsed.result;
+            if (typeof ip === 'string' && matcher.test(ip)) {
+              return ip;
+            }
+          }
+        } catch {
+          // ignore parse errors
+        }
+      }
+      const match = text.match(matcher);
+      if (match) {
+        return match[0];
+      }
+    } catch (err) {
+      continue;
+    }
+  }
+  return null;
+}

package/src/index.js

@@ -0,0 +1,10 @@
+export * from './ncc02.js';
+export * from './ncc05.js';
+export * from './selector.js';
+export * from './resolver.js';
+export * from './protocol.js';
+export * from './keys.js';
+export * from './tls.js';
+export * from './k.js';
+export * from './external-endpoints.js';
+export * from './schedule.js';

package/src/k.js

@@ -0,0 +1,107 @@
+import crypto from 'crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import path from 'path';
+
+function base64url(buffer) {
+  return buffer
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+function randomSuffix() {
+  return Math.random().toString(36).slice(2, 10);
+}
+
+function resolveConfigPath(filePath, baseDir) {
+  if (!filePath) return null;
+  if (path.isAbsolute(filePath)) return filePath;
+  return path.resolve(baseDir ?? process.cwd(), filePath);
+}
+
+/**
+ * Generate an expected `k` token for NCC-02/NCC-05 pinning.
+ */
+export function generateExpectedK({ prefix = 'TESTKEY', label = 'ncc06', suffix } = {}) {
+  const resolvedSuffix = suffix ?? randomSuffix();
+  return `${prefix}:${label}-${resolvedSuffix}`;
+}
+
+/**
+ * Validate the basic formatting of a `k` token.
+ */
+export function validateExpectedKFormat(k) {
+  return typeof k === 'string' && /^[A-Z0-9_-]+:[^\s]+$/.test(k);
+}
+
+export function computeKFromCertPem(pem) {
+  if (typeof pem !== 'string' && !Buffer.isBuffer(pem)) {
+    throw new Error('PEM certificate is required to compute `k`');
+  }
+  const publicKey = crypto.createPublicKey(pem);
+  const spki = publicKey.export({ type: 'spki', format: 'der' });
+  const hash = crypto.createHash('sha256').update(spki).digest();
+  return base64url(hash);
+}
+
+function ensureDir(filePath) {
+  const dir = path.dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function hasWssEndpoints(cfg) {
+  const endpoints = cfg.externalEndpoints || {};
+  const entries = ['ipv4', 'ipv6', 'onion'];
+  return entries.some(key => {
+    const entry = endpoints[key];
+    if (!entry || entry.enabled === false) return false;
+    const protocol = (entry.protocol || entry.type || 'ws').toLowerCase();
+    return protocol === 'wss';
+  });
+}
+
+/**
+ * Determine the expected `k` value based on the sidecar k configuration.
+ */
+export function getExpectedK(cfg = {}, options = {}) {
+  const { baseDir } = options;
+  const kConfig = cfg.k || {};
+  const implicitMode = hasWssEndpoints(cfg) ? 'tls_spki' : 'generate';
+  const mode = kConfig.mode || implicitMode;
+
+  switch (mode) {
+    case 'static': {
+      if (!kConfig.value) {
+        throw new Error('k.value is required when k.mode is "static"');
+      }
+      return kConfig.value;
+    }
+    case 'generate': {
+      if (!kConfig.persistPath) {
+        throw new Error('k.persistPath is required when k.mode is "generate"');
+      }
+      const persistPath = resolveConfigPath(kConfig.persistPath, baseDir);
+      if (existsSync(persistPath)) {
+        return readFileSync(persistPath, 'utf-8').trim();
+      }
+      ensureDir(persistPath);
+      const random = crypto.randomBytes(32);
+      const token = base64url(random);
+      writeFileSync(persistPath, token, { mode: 0o600 });
+      return token;
+    }
+    case 'tls_spki': {
+      if (!kConfig.certPath) {
+        throw new Error('k.certPath is required when k.mode is "tls_spki"');
+      }
+      const certPath = resolveConfigPath(kConfig.certPath, baseDir);
+      const pem = readFileSync(certPath, 'utf-8');
+      return computeKFromCertPem(pem);
+    }
+    default:
+      throw new Error(`Unsupported k.mode "${mode}"`);
+  }
+}

package/src/keys.js

@@ -0,0 +1,52 @@
+import { generateSecretKey, getPublicKey } from 'nostr-tools/pure';
+import { nip19 } from 'nostr-tools';
+
+/**
+ * Generate a deterministic keypair, returning all common formats.
+ */
+export function generateKeypair() {
+  const secretKey = generateSecretKey();
+  const pubkey = getPublicKey(secretKey);
+  return {
+    secretKey,
+    publicKey: pubkey,
+    npub: nip19.npubEncode(pubkey),
+    nsec: nip19.nsecEncode(secretKey)
+  };
+}
+
+/**
+ * Convert raw pubkey to npub.
+ */
+export function toNpub(pubkey) {
+  return nip19.npubEncode(pubkey);
+}
+
+/**
+ * Decode npub back to raw pubkey.
+ */
+export function fromNpub(npub) {
+  const decoded = nip19.decode(npub);
+  if (decoded.type !== 'npub') {
+    throw new Error('Invalid npub value');
+  }
+  return decoded.data;
+}
+
+/**
+ * Convert raw secret key to nsec.
+ */
+export function toNsec(secretKey) {
+  return nip19.nsecEncode(secretKey);
+}
+
+/**
+ * Decode nsec back to secret key.
+ */
+export function fromNsec(nsec) {
+  const decoded = nip19.decode(nsec);
+  if (decoded.type !== 'nsec') {
+    throw new Error('Invalid nsec value');
+  }
+  return decoded.data;
+}

package/src/ncc02.js

@@ -0,0 +1,73 @@
+import { finalizeEvent, getPublicKey, validateEvent, verifyEvent } from 'nostr-tools/pure';
+
+const DEFAULT_KIND = 30059;
+
+/**
+ * Build an NCC-02 service record event.
+ * The event includes `d`, `u`, `k`, and `exp` tags and is signed with the provided secret key.
+ * @param {object} options
+ */
+export function buildNcc02ServiceRecord({
+  secretKey,
+  serviceId,
+  endpoint,
+  fingerprint,
+  expirySeconds = 14 * 24 * 60 * 60,
+  createdAt,
+  kind = DEFAULT_KIND
+}) {
+  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);
+}
+
+/**
+ * Extract the NCC-02 relevant tags from an event.
+ */
+export function parseNcc02Tags(event) {
+  if (!event || !Array.isArray(event.tags)) {
+    return {};
+  }
+  return Object.fromEntries(event.tags);
+}
+
+/**
+ * Verify an NCC-02 service record, ensuring signature, author, `d` tag, and expiration.
+ */
+export function validateNcc02(event, { expectedAuthor, expectedD, now, allowExpired = false } = {}) {
+  if (!event || event.kind !== DEFAULT_KIND) {
+    return false;
+  }
+  if (!validateEvent(event) || !verifyEvent(event)) {
+    return false;
+  }
+  const tags = parseNcc02Tags(event);
+  if (expectedAuthor && event.pubkey !== expectedAuthor) {
+    return false;
+  }
+  if (expectedD && tags.d !== expectedD) {
+    return false;
+  }
+  const timestamp = now ?? Math.floor(Date.now() / 1000);
+  const exp = Number(tags.exp) || 0;
+  if (!allowExpired && exp > 0 && timestamp > exp) {
+    return false;
+  }
+  return true;
+}

package/src/ncc05.js

@@ -0,0 +1,90 @@
+export const DEFAULT_TTL_SECONDS = 3600;
+
+/**
+ * Build a locator payload that matches NCC-05 expectations.
+ */
+export function buildLocatorPayload({ endpoints = [], ttl = DEFAULT_TTL_SECONDS, updatedAt } = {}) {
+  const timestamp = updatedAt ?? Math.floor(Date.now() / 1000);
+  return {
+    ttl,
+    updated_at: timestamp,
+    endpoints: endpoints.map(normalizeEndpoint)
+  };
+}
+
+/**
+ * Parse string content from a stored locator event.
+ */
+export function parseLocatorPayload(content) {
+  if (typeof content !== 'string') {
+    return null;
+  }
+  try {
+    return JSON.parse(content);
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Check TTL/updated_at to determine if locator is fresh.
+ */
+export function validateLocatorFreshness(payload, { now, allowStale = false } = {}) {
+  if (!payload || typeof payload !== 'object') {
+    return false;
+  }
+  const timestamp = now ?? Math.floor(Date.now() / 1000);
+  const ttl = Number(payload.ttl) || 0;
+  const updated = Number(payload.updated_at) || 0;
+  if (ttl <= 0) {
+    return false;
+  }
+  if (allowStale) {
+    return true;
+  }
+  return timestamp <= updated + ttl;
+}
+
+/**
+ * Normalize endpoint definitions retrieved from locator payloads.
+ */
+export function normalizeLocatorEndpoints(endpoints = []) {
+  return endpoints
+    .map(normalizeEndpoint)
+    .filter(Boolean);
+}
+
+function normalizeEndpoint(endpoint = {}) {
+  const url = endpoint.url || endpoint.uri || endpoint.value;
+  if (!url) {
+    return null;
+  }
+  const protocol = endpoint.protocol || endpoint.type || (url.startsWith('wss://') ? 'wss' : 'ws');
+  const family = detectFamily(url, endpoint.family);
+  const priority = Number(endpoint.priority ?? endpoint.prio ?? 0);
+  const k = endpoint.k || endpoint.fingerprint || null;
+  return {
+    url,
+    protocol,
+    family,
+    priority,
+    k,
+    raw: endpoint
+  };
+}
+
+function detectFamily(url, override) {
+  if (override) {
+    return override;
+  }
+  if (!url) {
+    return 'unknown';
+  }
+  if (url.includes('.onion')) {
+    return 'onion';
+  }
+  if (url.includes('[') && url.includes(']')) {
+    return 'ipv6';
+  }
+  return 'ipv4';
+}

package/src/protocol.js

@@ -0,0 +1,32 @@
+/**
+ * Minimal helpers for Nostr protocol framing.
+ */
+
+/**
+ * Parse a Nostr protocol JSON string into an array payload.
+ */
+export function parseNostrMessage(messageString) {
+  try {
+    const payload = JSON.parse(messageString);
+    if (!Array.isArray(payload) || payload.length === 0) {
+      return null;
+    }
+    return payload;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Serialize a Nostr protocol message array to JSON.
+ */
+export function serializeNostrMessage(messageArray) {
+  return JSON.stringify(messageArray);
+}
+
+/**
+ * Helper to build a REQ message for subscriptions.
+ */
+export function createReqMessage(subId, ...filters) {
+  return ['REQ', subId, ...filters];
+}

package/src/resolver.js

@@ -0,0 +1,238 @@
+import WebSocket from 'ws';
+import { NCC05Resolver } from 'ncc-05';
+import { parseNostrMessage, serializeNostrMessage, createReqMessage } from './protocol.js';
+import { validateNcc02, parseNcc02Tags } from './ncc02.js';
+import { normalizeLocatorEndpoints, validateLocatorFreshness } from './ncc05.js';
+import { choosePreferredEndpoint } from './selector.js';
+
+const DEFAULT_RELAY_TIMEOUT_MS = 5000;
+
+/**
+ * Resolve a concrete service endpoint by applying NCC-06 resolution order.
+ */
+export async function resolveServiceEndpoint(options = {}) {
+  const {
+    bootstrapRelays = [],
+    servicePubkey,
+    serviceId,
+    locatorId,
+    expectedK,
+    torPreferred = false,
+    locatorSecretKey,
+    ncc05TimeoutMs = 5000,
+    publicationRelayTimeoutMs = DEFAULT_RELAY_TIMEOUT_MS,
+    queryRelayEvents,
+    resolveLocator,
+    now
+  } = options;
+
+  if (!servicePubkey) {
+    throw new Error('servicePubkey is required');
+  }
+  if (!serviceId) {
+    throw new Error('serviceId is required');
+  }
+  if (!locatorId) {
+    throw new Error('locatorId is required');
+  }
+  if (!bootstrapRelays.length) {
+    throw new Error('At least one bootstrap relay is required');
+  }
+
+  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');
+  }
+
+  const locatorPayload = await locatorResolver({
+    bootstrapRelays,
+    servicePubkey,
+    locatorId,
+    locatorSecretKey,
+    timeout: ncc05TimeoutMs
+  });
+
+  const selection = determineEndpoint({
+    serviceEvent,
+    locatorPayload,
+    expectedK,
+    torPreferred,
+    now: timestamp
+  });
+
+  return {
+    endpoint: selection.endpoint,
+    source: selection.source,
+    locatorPayload,
+    serviceEvent,
+    selection
+  };
+}
+
+function determineEndpoint({ serviceEvent, locatorPayload, expectedK, torPreferred, now }) {
+  const tags = parseNcc02Tags(serviceEvent);
+  const ncc02Url = tags.u;
+  const isFreshService = !tags.exp || now <= Number(tags.exp);
+  const result = {
+    endpoint: null,
+    source: null,
+    reason: null,
+    evidence: null
+  };
+
+  if (locatorPayload && validateLocatorFreshness(locatorPayload, { now })) {
+    const normalized = normalizeLocatorEndpoints(locatorPayload.endpoints || []);
+    const selection = choosePreferredEndpoint(normalized, {
+      torPreferred,
+      expectedK
+    });
+    if (selection.endpoint) {
+      return {
+        endpoint: selection.endpoint.url,
+        source: 'locator',
+        reason: 'locator',
+        evidence: selection
+      };
+    }
+    result.reason = selection.reason;
+    result.evidence = selection;
+  }
+
+  if (ncc02Url && isFreshService) {
+    if (ncc02Url.startsWith('wss://') && expectedK && tags.k && tags.k !== expectedK) {
+      return {
+        endpoint: null,
+        source: 'ncc02',
+        reason: 'k-mismatch',
+        evidence: { expected: expectedK, actual: tags.k }
+      };
+    }
+    return {
+      endpoint: ncc02Url,
+      source: 'ncc02',
+      reason: 'fallback',
+      evidence: { tags }
+    };
+  }
+
+  result.reason = result.reason || 'no-endpoint';
+  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,
+  locatorId,
+  locatorSecretKey,
+  timeout
+}) {
+  const resolver = new NCC05Resolver({
+    bootstrapRelays,
+    timeout
+  });
+  try {
+    return await resolver.resolve(servicePubkey, locatorSecretKey, locatorId, {
+      strict: false,
+      gossip: false
+    });
+  } finally {
+    resolver.close();
+  }
+}

package/src/schedule.js

@@ -0,0 +1,20 @@
+/**
+ * Return a next-delay that applies deterministic jitter without exceeding the base interval.
+ *
+ * @param {number} baseMs - The nominal interval.
+ * @param {number} jitterRatio - Fractional jitter (default 15%).
+ * @returns {number} Delay in milliseconds (non-negative, never above baseMs).
+ */
+export function scheduleWithJitter(baseMs, jitterRatio = 0.15) {
+  if (typeof baseMs !== 'number' || Number.isNaN(baseMs) || baseMs < 0) {
+    throw new Error('baseMs must be a non-negative number');
+  }
+  if (typeof jitterRatio !== 'number' || Number.isNaN(jitterRatio) || jitterRatio < 0) {
+    throw new Error('jitterRatio must be a non-negative number');
+  }
+
+  const jitterDelta = (Math.random() * 2 - 1) * jitterRatio * baseMs;
+  const jittered = baseMs + jitterDelta;
+  const clamped = Math.min(baseMs, Math.max(0, jittered));
+  return Math.round(clamped);
+}

package/src/selector.js

@@ -0,0 +1,49 @@
+import { normalizeLocatorEndpoints } from './ncc05.js';
+
+function pickByPriority(list) {
+  if (!list.length) return null;
+  return [...list].sort((a, b) => a.priority - b.priority)[0];
+}
+
+function findByFamily(list, family) {
+  return list.find(ep => ep.family === family);
+}
+
+/**
+ * Choose which endpoint to connect to based on NCC-06 policy.
+ * - prefers onion when torPreferred.
+ * - prefers WSS endpoints with matching k.
+ */
+export function choosePreferredEndpoint(endpoints = [], options = {}) {
+  const { torPreferred = false, expectedK } = options;
+  const normalized = endpoints.length ? endpoints : [];
+  const wssEndpoints = normalized.filter(ep => ep.protocol === 'wss');
+  const wsEndpoints = normalized.filter(ep => ep.protocol === 'ws');
+
+  let candidate = null;
+  if (torPreferred) {
+    candidate = findByFamily(wssEndpoints, 'onion') || findByFamily(wsEndpoints, 'onion');
+  }
+  if (!candidate) {
+    candidate = pickByPriority(wssEndpoints) || pickByPriority(wsEndpoints);
+  }
+  if (!candidate) {
+    return { endpoint: null, reason: 'no-endpoint' };
+  }
+  if (candidate.protocol === 'wss') {
+    if (!candidate.k) {
+      return { endpoint: null, reason: 'missing-k' };
+    }
+    if (expectedK && candidate.k !== expectedK) {
+      return {
+        endpoint: null,
+        reason: 'k-mismatch',
+        expected: expectedK,
+        actual: candidate.k
+      };
+    }
+  }
+  return { endpoint: candidate };
+}
+
+export { normalizeLocatorEndpoints };

package/src/tls.js

@@ -0,0 +1,46 @@
+import fs from 'fs';
+import path from 'path';
+import selfsigned from 'selfsigned';
+
+const DEFAULT_KEY_NAME = 'server.key';
+const DEFAULT_CERT_NAME = 'server.crt';
+
+/**
+ * Ensure a TLS key/cert pair exists (used for local WSS testing).
+ */
+export async function ensureSelfSignedCert({
+  targetDir = process.cwd(),
+  keyFileName = DEFAULT_KEY_NAME,
+  certFileName = DEFAULT_CERT_NAME,
+  altNames = ['localhost', '127.0.0.1', '::1']
+} = {}) {
+  const keyPath = path.resolve(targetDir, keyFileName);
+  const certPath = path.resolve(targetDir, certFileName);
+
+  if (fs.existsSync(keyPath) && fs.existsSync(certPath)) {
+    return { keyPath, certPath };
+  }
+
+  fs.mkdirSync(path.dirname(keyPath), { recursive: true });
+  fs.mkdirSync(path.dirname(certPath), { recursive: true });
+
+  const attrs = [{ name: 'commonName', value: 'localhost' }];
+  const altNameObjects = altNames.map(name => {
+    if (name.includes(':')) {
+      return { type: 7, ip: name };
+    }
+    return { type: 2, value: name };
+  });
+
+  const generated = selfsigned.generate(attrs, {
+    algorithm: 'rsa',
+    keySize: 2048,
+    days: 365,
+    extensions: [{ name: 'subjectAltName', altNames: altNameObjects }]
+  });
+
+  fs.writeFileSync(keyPath, generated.private, 'utf-8');
+  fs.writeFileSync(certPath, generated.cert, 'utf-8');
+
+  return { keyPath, certPath };
+}

package/test/external-endpoints.test.js

@@ -0,0 +1,59 @@
+import { strict as assert } from 'assert';
+import { test } from 'node:test';
+import {
+  buildExternalEndpoints,
+  detectGlobalIPv6,
+  getPublicIPv4
+} from '../src/external-endpoints.js';
+import os from 'os';
+
+test('buildExternalEndpoints orders endpoints and adds k when needed', async () => {
+  const onion = { address: 'abc123.onion', servicePort: 80 };
+  const endpoints = await buildExternalEndpoints({
+    tor: { enabled: true },
+    ipv6: { enabled: true, protocol: 'wss', port: 8443 },
+    ipv4: { enabled: true, protocol: 'wss', address: '1.2.3.4', port: 7447 },
+    wsPort: 7000,
+    wssPort: 7447,
+    ncc02ExpectedKey: 'TESTKEY',
+    ensureOnionService: async () => onion
+  });
+
+  assert.equal(endpoints.length, 3);
+  assert.equal(endpoints[0].family, 'ipv4');
+  assert.equal(endpoints[1].family, 'ipv6');
+  assert.equal(endpoints[2].family, 'onion');
+  assert.equal(endpoints[0].k, 'TESTKEY');
+});
+
+test('detectGlobalIPv6 filters private addresses', () => {
+  const original = os.networkInterfaces;
+  os.networkInterfaces = () => ({
+    lo: [{ address: '::1', family: 'IPv6', internal: true }],
+    eth0: [
+      { address: 'fe80::1', family: 'IPv6', internal: false },
+      { address: 'fc00::1', family: 'IPv6', internal: false },
+      { address: '2001:db8::1', family: 'IPv6', internal: false }
+    ]
+  });
+  try {
+    const addr = detectGlobalIPv6();
+    assert.equal(addr, '2001:db8::1');
+  } finally {
+    os.networkInterfaces = original;
+  }
+});
+
+test('getPublicIPv4 returns from first reachable source', async () => {
+  const original = global.fetch;
+  global.fetch = async (url) => ({
+    ok: true,
+    text: async () => '{"ip":"5.6.7.8"}'
+  });
+  try {
+    const ip = await getPublicIPv4({ sources: ['https://example.com'] });
+    assert.equal(ip, '5.6.7.8');
+  } finally {
+    global.fetch = original;
+  }
+});

package/test/k.test.js

@@ -0,0 +1,40 @@
+import { strict as assert } from 'assert';
+import { test } from 'node:test';
+import { computeKFromCertPem, getExpectedK } from '../src/k.js';
+import { readFileSync, existsSync, rmSync, mkdirSync } from 'fs';
+import path from 'path';
+import os from 'os';
+
+test('computeKFromCertPem produces stable base64url output', () => {
+  const certPath = path.resolve('../ncc-06-example/ncc06-relay/certs/server.crt');
+  const pem = readFileSync(certPath, 'utf-8');
+  const value = computeKFromCertPem(pem);
+  assert.equal(value, 'SOXWTCHPUG9ZLaZ4NgH2kKp5Hmqnaj1tXNI90SY44Mw');
+});
+
+test('generate mode persists and reuses k value', () => {
+  const tmpDir = path.join(os.tmpdir(), `ncc06-k-${Date.now()}`);
+  mkdirSync(tmpDir, { recursive: true });
+  const persistPath = path.join(tmpDir, 'k.txt');
+  const cfg = { k: { mode: 'generate', persistPath } };
+
+  const first = getExpectedK(cfg);
+  assert.equal(first.length, 43); // base64url of 32 bytes
+
+  const second = getExpectedK(cfg);
+  assert.equal(second, first);
+
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test('missing static value throws error', () => {
+  assert.throws(() => getExpectedK({ k: { mode: 'static' } }), /k\.value is required/);
+});
+
+test('missing persistPath throws error', () => {
+  assert.throws(() => getExpectedK({ k: { mode: 'generate' } }), /k\.persistPath is required/);
+});
+
+test('missing certPath throws error', () => {
+  assert.throws(() => getExpectedK({ k: { mode: 'tls_spki' } }), /k\.certPath is required/);
+});

package/test/ncc02.test.js

@@ -0,0 +1,22 @@
+import { test } from 'node:test';
+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', () => {
+  const { secretKey, publicKey } = generateKeypair();
+  const serviceEvent = buildNcc02ServiceRecord({
+    secretKey,
+    serviceId: 'relay',
+    endpoint: 'wss://127.0.0.1:7447',
+    fingerprint: 'TESTKEY:resolver',
+    expirySeconds: 60
+  });
+
+  assert.equal(serviceEvent.pubkey, publicKey);
+  const tags = parseNcc02Tags(serviceEvent);
+  assert.equal(tags.d, 'relay');
+  assert.equal(tags.u, 'wss://127.0.0.1:7447');
+  assert.equal(tags.k, 'TESTKEY:resolver');
+  assert.ok(validateNcc02(serviceEvent, { expectedAuthor: publicKey, expectedD: 'relay' }));
+});

package/test/ncc05.test.js

@@ -0,0 +1,23 @@
+import { test } from 'node:test';
+import { strict as assert } from 'assert';
+import { buildLocatorPayload, normalizeLocatorEndpoints, validateLocatorFreshness } from '../src/ncc05.js';
+
+test('locator payload builds and validates freshness', () => {
+  const payload = buildLocatorPayload({
+    ttl: 60,
+    endpoints: [{ url: 'ws://example.com', protocol: 'ws', priority: 1 }]
+  });
+  assert.equal(payload.ttl, 60);
+  assert.ok(Array.isArray(payload.endpoints));
+  assert.ok(validateLocatorFreshness(payload, { now: payload.updated_at + 10 }));
+  assert.ok(!validateLocatorFreshness(payload, { now: payload.updated_at + 70 }));
+});
+
+test('normalizes locator endpoints', () => {
+  const items = normalizeLocatorEndpoints([
+    { url: 'wss://host', priority: 2, k: 'TESTKEY:1' },
+    { uri: 'ws://host2', prio: 1 }
+  ]);
+  assert.equal(items[0].protocol, 'wss');
+  assert.equal(items[1].protocol, 'ws');
+});

package/test/resolver.test.js

@@ -0,0 +1,78 @@
+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,
+    endpoint: 'wss://fallback',
+    fingerprint: 'TESTKEY:match'
+  });
+  const locatorPayload = buildLocatorPayload({
+    ttl: 60,
+    endpoints: [
+      { url: 'wss://match', protocol: 'wss', priority: 1, k: 'TESTKEY:match' }
+    ]
+  });
+
+  const result = await resolveServiceEndpoint({
+    bootstrapRelays: ['wss://example'],
+    servicePubkey: publicKey,
+    serviceId: SERVICE_ID,
+    locatorId: LOCATOR_ID,
+    expectedK: 'TESTKEY:match',
+    queryRelayEvents: async () => [serviceEvent],
+    resolveLocator: async () => locatorPayload
+  });
+
+  assert.equal(result.endpoint, 'wss://match');
+  assert.equal(result.source, 'locator');
+});
+
+test('resolver falls back to NCC-02 when locator k mismatches', async () => {
+  const { secretKey, publicKey } = generateKeypair();
+  const serviceEvent = buildServiceEvent({
+    secretKey,
+    serviceId: SERVICE_ID,
+    endpoint: 'wss://fallback',
+    fingerprint: 'TESTKEY:match'
+  });
+  const locatorPayload = buildLocatorPayload({
+    ttl: 60,
+    endpoints: [
+      { url: 'wss://mismatch', protocol: 'wss', priority: 1, k: 'TESTKEY:bad' }
+    ]
+  });
+
+  const result = await resolveServiceEndpoint({
+    bootstrapRelays: ['wss://example'],
+    servicePubkey: publicKey,
+    serviceId: SERVICE_ID,
+    locatorId: LOCATOR_ID,
+    expectedK: 'TESTKEY:match',
+    queryRelayEvents: async () => [serviceEvent],
+    resolveLocator: async () => locatorPayload
+  });
+
+  assert.equal(result.endpoint, 'wss://fallback');
+  assert.equal(result.source, 'ncc02');
+  assert.equal(result.selection.reason, 'fallback');
+});

package/test/schedule.test.js

@@ -0,0 +1,19 @@
+import { strict as assert } from 'assert';
+import { test } from 'node:test';
+import { scheduleWithJitter } from '../src/schedule.js';
+
+test('scheduleWithJitter bounds delay between 0 and base interval', () => {
+  const values = [];
+  for (let i = 0; i < 100; i++) {
+    const delay = scheduleWithJitter(1000, 0.25);
+    assert.ok(delay >= 0, 'delay should not be negative');
+    assert.ok(delay <= 1000, 'delay should not exceed base interval');
+    values.push(delay);
+  }
+  assert.ok(values.some(v => v < 1000), 'some jittered delays should be less than base');
+});
+
+test('scheduleWithJitter throws for invalid args', () => {
+  assert.throws(() => scheduleWithJitter(-1), /non-negative number/);
+  assert.throws(() => scheduleWithJitter(1000, -0.1), /non-negative number/);
+});

package/test/selector.test.js

@@ -0,0 +1,27 @@
+import { test } from 'node:test';
+import { strict as assert } from 'assert';
+import { choosePreferredEndpoint } from '../src/selector.js';
+
+test('chooses WSS endpoint with matching k', () => {
+  const { endpoint, reason } = choosePreferredEndpoint([
+    { url: 'wss://match', protocol: 'wss', priority: 1, k: 'TESTKEY:match' }
+  ], { expectedK: 'TESTKEY:match' });
+  assert.ok(endpoint);
+  assert.equal(endpoint.url, 'wss://match');
+  assert.equal(reason, undefined);
+});
+
+test('rejects mismatched k', () => {
+  const result = choosePreferredEndpoint([
+    { url: 'wss://bad', protocol: 'wss', priority: 1, k: 'TESTKEY:bad' }
+  ], { expectedK: 'TESTKEY:expected' });
+  assert.equal(result.reason, 'k-mismatch');
+  assert.equal(result.endpoint, null);
+});
+
+test('returns missing k reason', () => {
+  const result = choosePreferredEndpoint([
+    { url: 'wss://no-k', protocol: 'wss', priority: 1 }
+  ]);
+  assert.equal(result.reason, 'missing-k');
+});