ncc-06-js 0.2.0 → 0.2.2

package/.eslintrc.json

@@ -0,0 +1,19 @@
+{
+  "env": {
+    "node": true,
+    "es2020": true
+  },
+  "extends": "eslint:recommended",
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module"
+  },
+  "rules": {
+    "no-unused-vars": [
+      "warn",
+      {
+        "argsIgnorePattern": "^_"
+      }
+    ]
+  }
+}

package/DOCS.md

@@ -52,6 +52,14 @@ Utilities for locator payload construction and evaluation.
 - **Options** include `bootstrapRelays`, `servicePubkey`, `serviceId`, `locatorId`, `expectedK`, `locatorSecretKey`, `torPreferred`, timeouts, and override hooks.
 - **Returns** `{ endpoint, source, serviceEvent, 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.
+
+### `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.
+
 ## Key and TLS helpers
 
 ### `generateExpectedK`, `validateExpectedKFormat`
@@ -108,3 +116,7 @@ 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.
+
+## TypeScript definitions
+
+`ncc-06-js` ships an `index.d.ts` file that mirrors the helpers documented above so TypeScript consumers receive accurate typings.

package/README.md

@@ -11,6 +11,8 @@ Reusable helpers extracted from the NCC-06 example relay, sidecar, and client im
 - **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.
 
 ## Usage
 

package/index.d.ts

@@ -0,0 +1,269 @@
+declare module 'ncc-06-js' {
+  export interface NostrEvent {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+    sig: string;
+  }
+
+  export interface BuildNcc02Options {
+    secretKey: string;
+    serviceId: string;
+    endpoint: string;
+    fingerprint?: string | null;
+    expirySeconds?: number;
+    kind?: number;
+    createdAt?: number;
+  }
+
+  export function buildNcc02ServiceRecord(options: BuildNcc02Options): NostrEvent;
+  export function parseNcc02Tags(event: NostrEvent): Record<string, string | undefined>;
+  export interface ValidateNcc02Options {
+    expectedAuthor?: string;
+    expectedD?: string;
+    now?: number;
+    allowExpired?: boolean;
+  }
+  export function validateNcc02(event: NostrEvent, options?: ValidateNcc02Options): boolean;
+
+  export interface LocatorEndpoint {
+    url: string;
+    type?: string;
+    uri?: string;
+    value?: string;
+    protocol?: 'ws' | 'wss';
+    family?: 'ipv4' | 'ipv6' | 'onion' | string;
+    priority?: number;
+    prio?: number;
+    k?: string;
+    fingerprint?: string;
+    [key: string]: unknown;
+  }
+
+  export interface LocatorPayload {
+    ttl: number;
+    updated_at: number;
+    endpoints: LocatorEndpoint[];
+  }
+
+  export const DEFAULT_TTL_SECONDS: number;
+  export function buildLocatorPayload(options?: {
+    endpoints?: LocatorEndpoint[];
+    ttl?: number;
+    updatedAt?: number;
+  }): LocatorPayload;
+  export function parseLocatorPayload(content: string | null | undefined): LocatorPayload | null;
+  export function validateLocatorFreshness(
+    payload: LocatorPayload | null | undefined,
+    options?: { now?: number; allowStale?: boolean }
+  ): boolean;
+  export function normalizeLocatorEndpoints(endpoints?: LocatorEndpoint[]): LocatorEndpoint[];
+
+  export interface SelectorOptions {
+    torPreferred?: boolean;
+    expectedK?: string;
+  }
+  export interface SelectorResult {
+    endpoint: LocatorEndpoint | null;
+    reason?: string;
+    expected?: string;
+    actual?: string;
+  }
+  export function choosePreferredEndpoint(
+    endpoints?: LocatorEndpoint[],
+    options?: SelectorOptions
+  ): SelectorResult;
+  export { normalizeLocatorEndpoints };
+
+  export interface ResolverOptions {
+    bootstrapRelays: string[];
+    servicePubkey: string;
+    serviceId: string;
+    locatorId: string;
+    expectedK?: string;
+    torPreferred?: boolean;
+    locatorSecretKey?: string;
+    ncc05TimeoutMs?: number;
+    publicationRelayTimeoutMs?: number;
+    queryRelayEvents?: (
+      relays: string[],
+      filter: Record<string, unknown>,
+      options?: { timeoutMs?: number }
+    ) => Promise<NostrEvent[]>;
+    resolveLocator?: (options: {
+      bootstrapRelays: string[];
+      servicePubkey: string;
+      locatorId: string;
+      locatorSecretKey?: string;
+      timeout?: number;
+    }) => Promise<LocatorPayload | null>;
+    throttle?: unknown;
+    now?: number;
+  }
+  export interface ResolverSelection {
+    endpoint: string | null;
+    source: 'locator' | 'ncc02' | null;
+    reason: string;
+    evidence?: Record<string, unknown>;
+  }
+  export interface ResolverResult {
+    endpoint: string | null;
+    source: 'locator' | 'ncc02' | null;
+    locatorPayload: LocatorPayload | null;
+    serviceEvent: NostrEvent;
+    selection: ResolverSelection;
+  }
+  export function resolveServiceEndpoint(options: ResolverOptions): Promise<ResolverResult>;
+
+  export interface Protocol {
+    parseNostrMessage(messageString: string): unknown[] | null;
+    serializeNostrMessage(messageArray: unknown[]): string;
+    createReqMessage(subId: string, ...filters: unknown[]): unknown[];
+  }
+
+  export interface Keypair {
+    secretKey: string;
+    publicKey: string;
+    npub: string;
+    nsec: string;
+  }
+  export function generateKeypair(): Keypair;
+  export function toNpub(pubkey: string): string;
+  export function fromNpub(npub: string): string;
+  export function toNsec(secretKey: string): string;
+  export function fromNsec(nsec: string): string;
+
+  export type KMode = 'tls_spki' | 'static' | 'generate';
+  export interface KConfig {
+    mode?: KMode;
+    value?: string;
+    certPath?: string;
+    persistPath?: string;
+    externalEndpoints?: Record<string, unknown>;
+  }
+  export function generateExpectedK(options?: {
+    prefix?: string;
+    label?: string;
+    suffix?: string;
+  }): string;
+  export function validateExpectedKFormat(k: string): boolean;
+  export function computeKFromCertPem(pem: string): string;
+  export function getExpectedK(cfg?: { k?: KConfig; externalEndpoints?: Record<string, unknown> }, options?: {
+    baseDir?: string;
+  }): string;
+
+  export interface JitterResult {
+    baseMs: number;
+    jitterRatio?: number;
+  }
+  export function scheduleWithJitter(baseMs: number, jitterRatio?: number): number;
+
+  export interface SelfSignedCertificate {
+    keyPath: string;
+    certPath: string;
+  }
+  export interface EnsureCertOptions {
+    targetDir?: string;
+    keyFileName?: string;
+    certFileName?: string;
+    altNames?: string[];
+  }
+  export function ensureSelfSignedCert(options?: EnsureCertOptions): Promise<SelfSignedCertificate>;
+
+  export interface ExternalEndpointOptions {
+    tor?: {
+      enabled?: boolean;
+    };
+    ipv4?: {
+      enabled?: boolean;
+      protocol?: 'ws' | 'wss';
+      port?: number;
+      address?: string;
+      publicSources?: string[];
+    };
+    ipv6?: {
+      enabled?: boolean;
+      protocol?: 'ws' | 'wss';
+      port?: number;
+    };
+    wsPort?: number;
+    wssPort?: number;
+    ncc02ExpectedKey?: string;
+    ensureOnionService?: () => Promise<{ address: string; servicePort: number } | null>;
+    publicIpv4Sources?: string[];
+  }
+  export function buildExternalEndpoints(options?: ExternalEndpointOptions): Promise<LocatorEndpoint[]>;
+  export function detectGlobalIPv6(): string | null;
+  export function getPublicIPv4(options?: { sources?: string[] }): Promise<string | null>;
+
+  export interface SidecarConfigOptions {
+    serviceSk: string;
+    servicePk: string;
+    serviceNpub: 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;
+    ncc02ExpectedKeySource?: string;
+  }
+  export interface SidecarConfig {
+    serviceSk: string;
+    servicePk: string;
+    serviceNpub: 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;
+  }
+  export function buildSidecarConfig(options: SidecarConfigOptions): SidecarConfig;
+
+  export interface ClientConfigOptions {
+    relayUrl: string;
+    servicePubkey?: string;
+    serviceNpub?: string;
+    serviceIdentityUri?: string;
+    locatorSecretKey?: string;
+    locatorFriendPubkey?: string;
+    publicationRelays?: string[];
+    staleFallbackSeconds?: number;
+    torPreferred?: boolean;
+    ncc05TimeoutMs?: number;
+    serviceId?: string;
+    locatorId?: string;
+    expectedK?: string;
+  }
+  export interface ClientConfig {
+    relayUrl: string;
+    serviceIdentityUri: string;
+    servicePubkey: string;
+    serviceNpub: string;
+    publicationRelays: string[];
+    staleFallbackSeconds: number;
+    torPreferred: boolean;
+    ncc05TimeoutMs: number;
+    locatorSecretKey?: string;
+    locatorFriendPubkey?: string;
+    serviceId?: string;
+    locatorId?: string;
+    ncc02ExpectedKey?: string;
+  }
+  export function buildClientConfig(options: ClientConfigOptions): ClientConfig;
+}

package/package.json

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

package/src/external-endpoints.js

@@ -76,7 +76,7 @@ export async function buildExternalEndpoints({
       if (a.priority !== b.priority) return a.priority - b.priority;
       return a.index - b.index;
     })
-    .map(({ index, createdAt, ...endpoint }) => endpoint);
+    .map(({ index: _index, createdAt: _createdAt, ...endpoint }) => endpoint);
 }
 
 /**

package/src/index.js

@@ -8,3 +8,4 @@ export * from './tls.js';
 export * from './k.js';
 export * from './external-endpoints.js';
 export * from './schedule.js';
+export * from './sidecar-config.js';

package/src/resolver.js

@@ -1,5 +1,5 @@
 import WebSocket from 'ws';
-import { NCC05Resolver } from 'ncc-05';
+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';

package/src/sidecar-config.js

@@ -0,0 +1,127 @@
+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
+};
+
+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;
+  });
+}
+
+/**
+ * Build a deployable sidecar config object that mirrors the example's defaults.
+ */
+export function buildSidecarConfig({
+  serviceSk,
+  servicePk,
+  serviceNpub,
+  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(),
+  ncc02ExpectedKeySource
+} = {}) {
+  if (!serviceSk || !servicePk || !serviceNpub) {
+    throw new Error('service keypair must be provided');
+  }
+  if (!relayUrl) {
+    throw new Error('relayUrl is required');
+  }
+
+  const expectedKey = getExpectedK({ k, externalEndpoints }, { baseDir });
+  const normalizedPublicationRelays = uniqueList([relayUrl, ...publicationRelays]);
+  const normalizedPublishRelays = uniqueList([
+    relayUrl,
+    ...(publishRelays ?? normalizedPublicationRelays)
+  ]);
+  const keySource = ncc02ExpectedKeySource ?? k.mode ?? 'auto';
+
+  return {
+    serviceSk,
+    servicePk,
+    serviceNpub,
+    relayUrl,
+    serviceId,
+    locatorId,
+    publicationRelays: normalizedPublicationRelays,
+    publishRelays: normalizedPublishRelays,
+    ncc02ExpSeconds,
+    ncc05TtlSeconds,
+    ncc02ExpectedKey: expectedKey,
+    ncc02ExpectedKeySource: keySource,
+    externalEndpoints,
+    torControl,
+    k
+  };
+}
+
+/**
+ * Build a client config that matches the NCC-06 example expectations.
+ */
+export function buildClientConfig({
+  relayUrl,
+  servicePubkey,
+  serviceNpub,
+  serviceIdentityUri,
+  locatorSecretKey,
+  locatorFriendPubkey,
+  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');
+  }
+  if (!servicePubkey) {
+    throw new Error('servicePubkey is required');
+  }
+  const publicationList = uniqueList([relayUrl, ...publicationRelays]);
+
+  return {
+    relayUrl,
+    serviceIdentityUri: identityUri,
+    servicePubkey,
+    serviceNpub: serviceNpub ?? '',
+    publicationRelays: publicationList,
+    staleFallbackSeconds,
+    torPreferred,
+    ncc05TimeoutMs,
+    locatorSecretKey,
+    locatorFriendPubkey,
+    serviceId,
+    locatorId,
+    ncc02ExpectedKey: expectedK
+  };
+}

package/test/external-endpoints.test.js

@@ -46,7 +46,7 @@ test('detectGlobalIPv6 filters private addresses', () => {
 
 test('getPublicIPv4 returns from first reachable source', async () => {
   const original = global.fetch;
-  global.fetch = async (url) => ({
+  global.fetch = async (_url) => ({
     ok: true,
     text: async () => '{"ip":"5.6.7.8"}'
   });

package/test/k.test.js

@@ -1,7 +1,7 @@
 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 { readFileSync, rmSync, mkdirSync } from 'fs';
 import path from 'path';
 import os from 'os';
 

package/test/sidecar-config.test.js

@@ -0,0 +1,36 @@
+import { test } from 'node:test';
+import { strict as assert } from 'assert';
+import { buildSidecarConfig, buildClientConfig } 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 }
+    }
+  });
+
+  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('buildClientConfig enforces identity URI and relays', () => {
+  const client = buildClientConfig({
+    relayUrl: 'ws://relay',
+    servicePubkey: 'pk',
+    serviceNpub: 'npub',
+    expectedK: 'TESTKEY:abc',
+    publicationRelays: ['ws://relay', 'ws://aux']
+  });
+
+  assert.equal(client.serviceIdentityUri, 'wss://npub');
+  assert.equal(client.publicationRelays.length, 2);
+  assert.equal(client.ncc02ExpectedKey, 'TESTKEY:abc');
+});

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "checkJs": false,
+    "allowJs": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.js", "test/**/*.js"]
+}