beacon: prober dials a curated allowlist only; default daily

Security (safe-then-expand): the prober no longer reads the harvested
relays directory for targets — that set is attacker-influenceable (anyone
can publish a relay list we harvest), which would let the prober be used
to dial arbitrary external hosts. It now dials ONLY a small built-in
allowlist of well-known relays, expandable via PROBE_RELAYS.

- src/prober.js: DEFAULT_PROBE_RELAYS + proberRelays(env); sweepOnce uses
  it (drops the db.relays.find target query); all entries screened via
  safeRelayUrl. Default interval 1h -> 24h (daily). USAGE updated.
- .env.example: document PROBE_RELAYS + daily default.
- tests: proberRelays (default allowlist; PROBE_RELAYS override drops
  loopback/junk) + interval default 86400000. npm test 64/64.

Live --once: writes exactly the 8 allowlist relays, none from the directory.

Closes #27

Author: melvincarvalho

.env.example

@@ -19,9 +19,11 @@ PORT=3000
 # writing collections still owned by the legacy firehose processes.
 # INDEX_LEGACY_KINDS=1
 
-# Relay-health prober (node probe.js / npm run probe). Dials every relay in the
-# directory, writing online/uptime/latency + NIP-11 auth/payment flags.
-# PROBE_INTERVAL=3600000   # sweep cadence in ms (default 1h)
+# Relay-health prober (node probe.js / npm run probe). Dials ONLY a curated
+# allowlist (never the harvested directory) and writes online/uptime/latency +
+# NIP-11 auth/payment flags. Expand the allowlist deliberately.
+# PROBE_RELAYS=wss://relay.damus.io,wss://nos.lol   # allowlist (default: small built-in set)
+# PROBE_INTERVAL=86400000  # sweep cadence in ms (default 86400000 = daily)
 # PROBE_CONCURRENCY=25     # relays probed in parallel
 # PROBE_TIMEOUT=7000       # per-relay connect/HTTP timeout in ms
 # RUN_ONCE=1               # single sweep then exit (or pass --once)

src/prober.js

@@ -12,6 +12,23 @@ import 'dotenv/config';
 
 const RELAY_DIRECTORY = process.env.MONGO_RELAY_DIRECTORY_COLLECTION || 'relays';
 
+// SECURITY: the prober dials ONLY this curated allowlist — never the harvested
+// `relays` directory, which is attacker-influenceable (anyone can publish a
+// relay list we harvest). Decoupling the target set from attacker-controlled
+// data is what stops the prober being used to dial arbitrary hosts. Expand
+// deliberately via PROBE_RELAYS (comma list); safe-then-expand, not the reverse.
+export const DEFAULT_PROBE_RELAYS = [
+  'wss://relay.damus.io', 'wss://nos.lol', 'wss://relay.primal.net',
+  'wss://relay.nostr.band', 'wss://nostr.wine', 'wss://relay.snort.social',
+  'wss://purplepag.es', 'wss://nostr.mom',
+];
+
+/** The curated set of relays the prober is allowed to dial (screened). */
+export function proberRelays(env = process.env) {
+  const raw = env.PROBE_RELAYS ? env.PROBE_RELAYS.split(',') : DEFAULT_PROBE_RELAYS;
+  return [...new Set(raw.map((u) => safeRelayUrl(String(u).trim())).filter(Boolean))];
+}
+
 export const USAGE = `beacon relay-health prober
 
 Usage: node probe.js [flags]    (or: node src/prober.js [flags])
@@ -20,8 +37,12 @@ Flags (override the matching env var):
   --once               run a single sweep and exit (env RUN_ONCE=1)
   --concurrency <n>    relays probed in parallel (env PROBE_CONCURRENCY, default 25)
   --timeout <ms>       per-relay connect/HTTP timeout (env PROBE_TIMEOUT, default 7000)
-  --interval <ms>      sweep interval when scheduling (env PROBE_INTERVAL, default 3600000)
-  -h, --help           show this help`;
+  --interval <ms>      sweep interval when scheduling (env PROBE_INTERVAL, default 86400000 = daily)
+  -h, --help           show this help
+
+Targets: a curated allowlist only (env PROBE_RELAYS, comma list; default: a
+small built-in set of well-known relays). The harvested directory is NEVER
+dialed — expand the allowlist deliberately.`;
 
 /** Parse prober CLI flags into an overlay (only keys the user passed). */
 export function parseArgs(argv = process.argv.slice(2)) {
@@ -43,7 +64,7 @@ export function proberConfig(env = process.env, argv = process.argv.slice(2)) {
   const flags = parseArgs(argv);
   const pos = (v, d) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? n : d; };
   return {
-    interval: flags.interval ?? pos(env.PROBE_INTERVAL, 3_600_000),
+    interval: flags.interval ?? pos(env.PROBE_INTERVAL, 86_400_000),
     concurrency: flags.concurrency ?? pos(env.PROBE_CONCURRENCY, 25),
     timeout: flags.timeout ?? pos(env.PROBE_TIMEOUT, 7_000),
     once: flags.once || env.RUN_ONCE === '1' || env.RUN_ONCE === 'true',
@@ -123,21 +144,16 @@ async function mapPool(items, concurrency, fn) {
   await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, items.length)) }, worker));
 }
 
-/** One full sweep over every relay in the directory. Returns { total, online }. */
+/** One sweep over the curated allowlist (never the harvested directory). */
 export async function sweepOnce(db, cfg) {
-  const docs = await db.collection(RELAY_DIRECTORY).find({}, { projection: { relay: 1, _id: 0 } }).toArray();
-  const all = [...new Set(docs.map((d) => d.relay).filter(Boolean))];
-  // Defense-in-depth: never dial loopback/private/reserved targets, even if
-  // junk slipped into the directory before harvest hardening (SSRF guard).
-  const relays = all.filter((r) => safeRelayUrl(r));
-  const skipped = all.length - relays.length;
+  const relays = proberRelays(); // allowlist only — attacker-fed data is never dialed
   let online = 0;
   await mapPool(relays, cfg.concurrency, async (relay) => {
     try { if ((await probeRelay(db, relay, cfg)).online) online++; }
     catch (e) { console.error(`[beacon] probe error ${relay}: ${e.message}`); }
   });
-  console.log(`[beacon] relay sweep: ${online}/${relays.length} online${skipped ? ` (skipped ${skipped} unsafe)` : ''}`);
-  return { total: relays.length, online, skipped };
+  console.log(`[beacon] relay sweep (allowlist): ${online}/${relays.length} online`);
+  return { total: relays.length, online };
 }
 
 export async function runProber() {

test/prober.test.js

@@ -3,7 +3,7 @@
 // manual smoke run, not here.
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { parseArgs, proberConfig, relayInfoUrl, nip11Flags } from '../src/prober.js';
+import { parseArgs, proberConfig, relayInfoUrl, nip11Flags, proberRelays, DEFAULT_PROBE_RELAYS } from '../src/prober.js';
 
 test('parseArgs: flags', () => {
   assert.deepEqual(parseArgs(['--once']), { once: true });
@@ -18,14 +18,25 @@ test('parseArgs: non-numeric value is ignored (not consumed as flag value)', ()
   assert.deepEqual(parseArgs(['--concurrency', 'abc']), {});
 });
 
-test('proberConfig: defaults', () => {
+test('proberConfig: defaults (daily)', () => {
   const c = proberConfig({}, []);
-  assert.equal(c.interval, 3_600_000);
+  assert.equal(c.interval, 86_400_000);
   assert.equal(c.concurrency, 25);
   assert.equal(c.timeout, 7_000);
   assert.equal(c.once, false);
 });
 
+test('proberRelays: default is the built-in allowlist (screened)', () => {
+  const r = proberRelays({});
+  assert.equal(r.length, DEFAULT_PROBE_RELAYS.length);
+  assert.ok(r.every((u) => u.startsWith('wss://')));
+});
+
+test('proberRelays: PROBE_RELAYS overrides; junk/SSRF entries dropped', () => {
+  const r = proberRelays({ PROBE_RELAYS: 'wss://relay.example.com, ws://127.0.0.1/, garbage, wss://nos.lol' });
+  assert.deepEqual(r, ['wss://relay.example.com/', 'wss://nos.lol/']); // loopback + junk screened out
+});
+
 test('proberConfig: env applies, non-positive falls back to default', () => {
   const c = proberConfig({ PROBE_CONCURRENCY: '40', PROBE_TIMEOUT: '0', RUN_ONCE: '1' }, []);
   assert.equal(c.concurrency, 40);