Private Watch: security audit + quality wins (matches monorepo §12.41)

Marketing for Private Watch is in the data-api monorepo (docs +
landing + stats); this is the code-side mirror.

Security audit — ten fixes:
- Lock durationDays server-side (fixed 7-day tier, re-POST to renew;
  previous behaviour gave 30 days for the same $0.10).
- IPv6 SSRF guard for ::1, fc00::/7, fe80::/10, IPv4-mapped IPv6 in
  both dotted-quad and Node-canonicalised hex forms.
- New resolveAndValidateWatchRequest does an async DNS A+AAAA
  lookup and rejects any returned address in a private range —
  defeats `evil.example.com` → 127.0.0.1 rebinds. Tests inject a
  stub resolver so the suite stays offline.
- Zcash birthdayHeight defaults to NU6 (3,042,000) so the scanner
  never autoDetects a multi-hour backwards walk. Monero now also
  honours birthdayHeight (was only Zcash). Bounds [0, 50M].
- HTTPS-only webhook URLs by default (PRIVATE_WATCH_REQUIRE_HTTPS=1).
- Reject embedded userinfo in webhook URLs.
- deliverWebhook drains the response body via getReader() and
  aborts the controller at 4 KB to defeat slow-loris megabyte
  responses.

Quick wins:
- POST /v1/private/watch/:id/test fires a synthetic signed webhook
  (event: "synthetic_test") so receivers can verify HMAC handling
  before relying on real payments. Free, token-auth.
- buildWatchSummary exposes last_delivered_event and
  next_poll_eta_ms.
- /v1/stats/overview includes a private_watch block (live counters).

333/333 tests passing (covers new IPv6 forms, DNS rebind rejection,
durationDays override rejection, test endpoint with HMAC byte-match
assertion, overview block content).

Author: S. K. Rotwang MMMMMMMMM

src/config.js

@@ -159,13 +159,25 @@ export const config = Object.freeze({
 	// for local development. Production deployments leave this off so
 	// SSRF protection is in force.
 	privateWatchAllowPrivateWebhooks: asString('PRIVATE_WATCH_ALLOW_PRIVATE_WEBHOOKS', '') === '1',
+	// Require https:// for webhook URLs. Default ON in production so a
+	// cleartext token can't be sniffed off the wire. Local dev keeps it
+	// off to support testing against an http listener.
+	privateWatchRequireHttps: asString('PRIVATE_WATCH_REQUIRE_HTTPS', '1') === '1',
 	// How often the poller drives a tick. Each tick polls every active
 	// watch; NFPT detaches scanners after 5 min idle, so we stay
 	// comfortably below.
 	privateWatchPollIntervalSec: asInt('PRIVATE_WATCH_POLL_INTERVAL_SEC', 180),
 	// HTTP timeout for outbound webhook POSTs. Set short — receivers
 	// should accept fast and process async.
 	privateWatchWebhookTimeoutMs: asInt('PRIVATE_WATCH_WEBHOOK_TIMEOUT_MS', 8_000),
+	// Cap on bytes drained from a webhook receiver's response body.
+	// We don't use the body — status code is the source of truth — so
+	// a 4 KB cap defeats slow-loris megabyte responses.
+	privateWatchResponseMaxBytes: asInt('PRIVATE_WATCH_RESPONSE_MAX_BYTES', 4 * 1024),
+	// Max active watches per source IP — keeps a single client from
+	// monopolising poller slots. Each is paywalled at $0.10 already
+	// so this is mostly a soft DoS guard.
+	privateWatchMaxPerIp: asInt('PRIVATE_WATCH_MAX_PER_IP', 32),
 	// x402 price for POST /v1/private/watch. One tier, $0.10 = 7-day
 	// monitor for one (chain, address, viewKey, webhookUrl). Override
 	// via env without touching code if we want a promo price.

src/mcp-server.js

@@ -54,7 +54,7 @@ import {
 	healthCheck as nfptHealthCheck
 } from './private-watch-nfpt.js';
 import {
-	validateWatchRequest,
+	resolveAndValidateWatchRequest,
 	buildPrivateInfo,
 	WATCH_CONSTANTS
 } from './private-watch.js';
@@ -374,7 +374,11 @@ export function buildMcpServer(options = {}) {
 		const nfptHealth = privateWatchReady()
 			? await nfptHealthCheck(nfptClient).catch((err) => ({ ok: false, reason: err?.message ?? String(err) }))
 			: { ok: false, reason: 'private watch disabled on this server' };
-		return asContent(buildPrivateInfo({ x402Cfg, nfptHealth }));
+		return asContent(buildPrivateInfo({
+			x402Cfg,
+			nfptHealth,
+			requireHttps: config.privateWatchRequireHttps && !config.privateWatchAllowPrivateWebhooks
+		}));
 	});
 
 	server.registerTool('seneschal_private_watch_create', {
@@ -399,8 +403,9 @@ export function buildMcpServer(options = {}) {
 		}
 		let input;
 		try {
-			input = validateWatchRequest(params, {
-				allowPrivateWebhooks: config.privateWatchAllowPrivateWebhooks
+			input = await resolveAndValidateWatchRequest(params, {
+				allowPrivateWebhooks: config.privateWatchAllowPrivateWebhooks,
+				requireHttps: config.privateWatchRequireHttps && !config.privateWatchAllowPrivateWebhooks
 			});
 		}
 		catch (err) {

src/private-watch-poller.js

@@ -46,6 +46,11 @@ import {
 
 const DEFAULT_WEBHOOK_TIMEOUT_MS = 8_000;
 const MAX_LOG_REASON_LEN = 200;
+// Max bytes we'll buffer from a misbehaving receiver before
+// abandoning the read. 4 KB is enough for any reasonable status
+// payload, and tiny enough that a hostile responder can't tie up the
+// poller with a slow-loris megabyte.
+const DEFAULT_RESPONSE_MAX_BYTES = WATCH_CONSTANTS.WEBHOOK_RESPONSE_MAX_BYTES;
 
 /**
  * Run a single poller tick. Returns a summary object so the CLI
@@ -68,6 +73,7 @@ export async function runPollerTick(deps) {
 		nfptClient,
 		fetchImpl = globalThis.fetch,
 		webhookTimeoutMs = DEFAULT_WEBHOOK_TIMEOUT_MS,
+		responseMaxBytes = DEFAULT_RESPONSE_MAX_BYTES,
 		logger = console,
 		now = () => Date.now()
 	} = deps;
@@ -95,7 +101,8 @@ export async function runPollerTick(deps) {
 		try {
 			await pollOne({
 				row, db, masterKey, nfptClient,
-				fetchImpl, webhookTimeoutMs, logger, now, summary
+				fetchImpl, webhookTimeoutMs, responseMaxBytes,
+				logger, now, summary
 			});
 		}
 		catch (err) {
@@ -114,7 +121,7 @@ export async function runPollerTick(deps) {
 	return summary;
 }
 
-async function pollOne({ row, db, masterKey, nfptClient, fetchImpl, webhookTimeoutMs, logger, now, summary }) {
+async function pollOne({ row, db, masterKey, nfptClient, fetchImpl, webhookTimeoutMs, responseMaxBytes, logger, now, summary }) {
 	const viewKey = decryptViewKey(row.view_key_ct, masterKey);
 	let jobId = row.nfpt_job_id;
 	let jobToken = row.nfpt_job_token;
@@ -183,13 +190,20 @@ async function pollOne({ row, db, masterKey, nfptClient, fetchImpl, webhookTimeo
 		secret: row.webhook_secret,
 		watchId: row.id,
 		fetchImpl,
-		timeoutMs: webhookTimeoutMs
+		timeoutMs: webhookTimeoutMs,
+		responseMaxBytes
 	});
 	if (result.ok) {
 		summary.webhooks_delivered += 1;
+		const eventLabel = diff.first_complete
+			? 'scan_complete'
+			: diff.balance_changed
+				? 'balance_change'
+				: 'status_change';
 		updateWatchState(db, row.id, {
 			last_delivered_balance: knownJson,
 			last_delivered_at_ms: nowMs,
+			last_delivered_event: eventLabel,
 			delivery_attempts: 0,
 			delivery_count: (row.delivery_count ?? 0) + 1,
 			last_delivery_error: null
@@ -229,10 +243,16 @@ async function startJobForRow({ row, viewKey, nfptClient }) {
 			fromHeight: row.birthday_height ?? undefined
 		});
 	}
+	// NEVER autoDetect for Zcash — it walks the chain backwards from
+	// the tip and can run for hours, holding an NFPT scanner slot for
+	// a single $0.10 watch. The validator already defaults missing
+	// birthdayHeight to NU6 (post-April-2024), which covers virtually
+	// all live wallets. Older wallets must pass an explicit
+	// birthdayHeight.
 	return startOrchardJob(nfptClient, {
 		ufvk: viewKey,
-		birthdayHeight: row.birthday_height ?? undefined,
-		autoDetect: row.birthday_height ? false : true
+		birthdayHeight: row.birthday_height ?? WATCH_CONSTANTS.ZCASH_NU6_HEIGHT,
+		autoDetect: false
 	});
 }
 
@@ -246,7 +266,8 @@ async function startJobForRow({ row, viewKey, nfptClient }) {
 export async function deliverWebhook({
 	url, body, secret, watchId,
 	fetchImpl = globalThis.fetch,
-	timeoutMs = DEFAULT_WEBHOOK_TIMEOUT_MS
+	timeoutMs = DEFAULT_WEBHOOK_TIMEOUT_MS,
+	responseMaxBytes = DEFAULT_RESPONSE_MAX_BYTES
 }) {
 	if (typeof url !== 'string') throw new TypeError('deliverWebhook: url is required');
 	if (typeof body !== 'string') throw new TypeError('deliverWebhook: body must be a string');
@@ -267,6 +288,11 @@ export async function deliverWebhook({
 			},
 			body
 		});
+		// Drain a bounded number of bytes from the response so a
+		// receiver returning a multi-megabyte body can't slow-loris
+		// us. We don't actually use the contents — the status code is
+		// the source of truth.
+		await drainBodyBounded(res, responseMaxBytes, ac);
 		const ok = res.status >= 200 && res.status < 300;
 		return { ok, status: res.status, error: ok ? null : `non-2xx HTTP ${res.status}` };
 	}
@@ -282,6 +308,27 @@ export async function deliverWebhook({
 	}
 }
 
+async function drainBodyBounded(res, maxBytes, ac) {
+	const reader = res?.body?.getReader?.();
+	if (!reader) return; // node-fetch shims without streaming bodies
+	let total = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) return;
+			if (value) total += value.byteLength;
+			if (total > maxBytes) {
+				try { ac.abort(new Error(`webhook response exceeded ${maxBytes} bytes`)); }
+				catch { /* swallow */ }
+				try { await reader.cancel(); }
+				catch { /* swallow */ }
+				return;
+			}
+		}
+	}
+	catch { /* aborted or socket gone — we don't care about the body */ }
+}
+
 function safeJson(s) {
 	try { return JSON.parse(s); }
 	catch { return null; }

src/private-watch-store.js

@@ -52,6 +52,7 @@ CREATE TABLE IF NOT EXISTS private_watches (
 	delivery_attempts INTEGER DEFAULT 0,
 	delivery_count INTEGER DEFAULT 0,
 	last_delivery_error TEXT,
+	last_delivered_event TEXT,
 	dead INTEGER DEFAULT 0,
 	cancelled INTEGER DEFAULT 0
 );
@@ -65,6 +66,11 @@ CREATE INDEX IF NOT EXISTS idx_watch_poll
  * Open (or create) the watch DB. Pass a `:memory:` path in tests.
  * The parent directory is created if absent so deployments don't
  * have to pre-mkdir the state dir.
+ *
+ * Idempotent schema migration: `last_delivered_event` was added in a
+ * later revision. We ALTER TABLE … ADD COLUMN if the table already
+ * exists without it, ignoring "duplicate column" errors so re-opens
+ * are a no-op.
  */
 export function openWatchDb(path) {
 	if (typeof path !== 'string' || path.length === 0) {
@@ -79,9 +85,17 @@ export function openWatchDb(path) {
 	db.pragma('synchronous = NORMAL');
 	db.pragma('foreign_keys = ON');
 	db.exec(WATCH_DDL);
+	addColumnIfMissing(db, 'private_watches', 'last_delivered_event', 'TEXT');
 	return db;
 }
 
+function addColumnIfMissing(db, table, col, type) {
+	try { db.prepare(`ALTER TABLE ${table} ADD COLUMN ${col} ${type}`).run(); }
+	catch (err) {
+		if (!/duplicate column/i.test(err?.message ?? '')) throw err;
+	}
+}
+
 function sha256(bytes) {
 	return createHash('sha256').update(bytes).digest('hex');
 }
@@ -227,6 +241,7 @@ export function updateWatchState(db, id, patch) {
 		'last_delivered_balance',
 		'last_polled_at_ms',
 		'last_delivered_at_ms',
+		'last_delivered_event',
 		'delivery_attempts',
 		'delivery_count',
 		'last_delivery_error',