mixdog 0.9.3 → 0.9.5

package/src/runtime/channels/lib/webhook.mjs

@@ -1,578 +1,36 @@
 import * as http from "http";
-import * as crypto from "crypto";
 import { join } from "path";
 import { spawn, spawnSync } from "child_process";
-import { DATA_DIR, isInQuietWindow } from "./config.mjs";
-import { getWebhookAuthtoken } from "../../shared/config.mjs";
-import { appendFileSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync, existsSync, renameSync, watch as fsWatch } from "fs";
-import { appendFile } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
 import { randomUUID } from "crypto";
+import { getWebhookAuthtoken } from "../../shared/config.mjs";
 import { readMarkdownDocument } from "../../shared/markdown-frontmatter.mjs";
-const WEBHOOKS_DIR = join(DATA_DIR, "webhooks");
-const WEBHOOK_LOG = join(DATA_DIR, "webhook.log");
-let webhookLogBuffer = [];
-let webhookLogTimer = null;
-function flushWebhookLog() {
-  if (webhookLogTimer) {
-    clearTimeout(webhookLogTimer);
-    webhookLogTimer = null;
-  }
-  if (!webhookLogBuffer.length) return;
-  const lines = webhookLogBuffer.join("");
-  webhookLogBuffer = [];
-  void appendFile(WEBHOOK_LOG, lines).catch(() => {});
-}
-try {
-  process.on("beforeExit", flushWebhookLog);
-  process.on("exit", () => {
-    if (!webhookLogBuffer.length) return;
-    try { appendFileSync(WEBHOOK_LOG, webhookLogBuffer.join("")); } catch {}
-    webhookLogBuffer = [];
-  });
-} catch {}
-function logWebhook(msg) {
-  const line = `[${(/* @__PURE__ */ new Date()).toISOString()}] ${msg}
-`;
-  try {
-    process.stderr.write(`mixdog webhook: ${msg}
-`);
-  } catch {
-  }
-  webhookLogBuffer.push(line);
-  if (!webhookLogTimer) {
-    webhookLogTimer = setTimeout(flushWebhookLog, 1000);
-    webhookLogTimer.unref?.();
-  }
-}
-const SIGNATURE_HEADERS = {
-  github: { header: "x-hub-signature-256", prefix: "sha256=" },
-  sentry: { header: "sentry-hook-signature", prefix: "" },
-  stripe: { header: "stripe-signature", prefix: "" },
-  generic: { header: "x-signature-256", prefix: "sha256=" }
-};
-function extractSignature(headers, parser) {
-  if (parser) {
-    const mapping = SIGNATURE_HEADERS[parser];
-    if (mapping) {
-      const raw = headers[mapping.header];
-      if (raw) return mapping.prefix ? raw.replace(mapping.prefix, "") : raw;
-    }
-  }
-  for (const mapping of Object.values(SIGNATURE_HEADERS)) {
-    const raw = headers[mapping.header];
-    if (raw) return mapping.prefix ? raw.replace(mapping.prefix, "") : raw;
-  }
-  return null;
-}
-// Stripe's documented replay tolerance. A captured signature older (or more
-// than this skew newer) than the window is rejected even if the HMAC matches.
-const STRIPE_TOLERANCE_MS = 5 * 60 * 1000;
-function verifySignature(secret, rawBody, signatureValue, parser) {
-  if (parser === "stripe") {
-    // Stripe signs `${t}.${payload}`, not the body alone, and the t= field
-    // must be validated against the clock: without it a captured (t, v1) pair
-    // replays forever. Require BOTH fields, check freshness, then verify the
-    // HMAC over the timestamped payload.
-    const vMatch = signatureValue.match(/v1=([a-f0-9]+)/);
-    const tMatch = signatureValue.match(/t=(\d+)/);
-    if (!vMatch || !tMatch) return false;
-    const ts = Number(tMatch[1]);
-    if (!Number.isFinite(ts) || Math.abs(Date.now() - ts * 1000) > STRIPE_TOLERANCE_MS) return false;
-    const expected = crypto.createHmac("sha256", secret).update(`${tMatch[1]}.${rawBody}`).digest("hex");
-    // timingSafeEqual throws on length mismatch / malformed hex; wrap so a
-    // crafted signature header can't crash the request handler.
-    try {
-      const a = Buffer.from(vMatch[1], "hex");
-      const b = Buffer.from(expected, "hex");
-      if (a.length !== b.length) return false;
-      return crypto.timingSafeEqual(a, b);
-    } catch {
-      return false;
-    }
-  }
-  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
-  try {
-    const a = Buffer.from(signatureValue, "hex");
-    const b = Buffer.from(expected, "hex");
-    if (a.length !== b.length) return false;
-    return crypto.timingSafeEqual(a, b);
-  } catch {
-    return false;
-  }
-}
-
-// ── Endpoint config loader ─────────────────────────────────────────────
-// Reads DATA_DIR/webhooks/<name>/WEBHOOK.md (written by setup-server.mjs
-// via POST /webhooks). The frontmatter IS the config object; the markdown
-// body is the instructions/prompt. Cached in-memory, invalidated by
-// fs.watch on the webhooks directory. Returns the frontmatter object
-// { secret, parser, channel, model, role, enabled } where routing is by
-// `channel` presence and `role` names a user-workflow entry when set.
-const _endpointCache = new Map();
-let _endpointWatcher = null;
-function _endpointConfigPath(name) {
-  return join(WEBHOOKS_DIR, name, "WEBHOOK.md");
-}
-// Per-endpoint HMAC secret is stored in a side file (WEBHOOKS_DIR/<name>/secret),
-// not in WEBHOOK.md frontmatter — frontmatter is a lossy `key: value` format
-// (unquote strips surrounding quotes) and would corrupt user secrets on the
-// save->rewrite round-trip. Read fresh on each verify (no cache): the signing
-// path is not hot and a stale secret would silently reject valid deliveries.
-function _readEndpointSecret(name) {
-  try {
-    const s = readFileSync(join(WEBHOOKS_DIR, name, "secret"), "utf8").trim();
-    return s || null;
-  } catch {
-    return null;
-  }
-}
-function _ensureEndpointWatcher() {
-  if (_endpointWatcher) return;
-  try {
-    if (!existsSync(WEBHOOKS_DIR)) return;
-    _endpointWatcher = fsWatch(WEBHOOKS_DIR, { recursive: true }, (_event, filename) => {
-      if (!filename) { _endpointCache.clear(); return; }
-      // filename is like "<endpoint>/WEBHOOK.md" or "<endpoint>"
-      const parts = String(filename).split(/[\\/]/);
-      const endpointName = parts[0];
-      if (endpointName) _endpointCache.delete(endpointName);
-      else _endpointCache.clear();
-    });
-    _endpointWatcher.on("error", () => { _endpointWatcher = null; _endpointCache.clear(); });
-  } catch {
-    // Watch failures are non-fatal; cache simply stays until process restart.
-  }
-}
-function _closeEndpointWatcher() {
-  if (!_endpointWatcher) return;
-  try { _endpointWatcher.close(); } catch {}
-  _endpointWatcher = null;
-  _endpointCache.clear();
-}
-function loadEndpointConfig(name) {
-  if (!name) return null;
-  // A cached entry is only authoritative while the fs.watch handle is
-  // armed — otherwise a later mkdir+write of WEBHOOKS_DIR/<name>/
-  // WEBHOOK.md has no way to invalidate the cache and a stale `null`
-  // (e.g. captured before WEBHOOKS_DIR existed) would pin forever.
-  if (_endpointCache.has(name) && _endpointWatcher) return _endpointCache.get(name);
-  _ensureEndpointWatcher();
-  const p = _endpointConfigPath(name);
-  if (!existsSync(p)) {
-    // Only cache the missing-config state when the watcher is live, so
-    // a later create can invalidate it. Otherwise leave the slot empty
-    // and re-read on the next call.
-    if (_endpointWatcher) _endpointCache.set(name, null);
-    return null;
-  }
-  try {
-    // Frontmatter is the config object; `enabled` arrives as a string and
-    // is cast so `endpoint?.enabled === false` gates match a written
-    // `enabled: false`.
-    const { frontmatter } = readMarkdownDocument(readFileSync(p, "utf8"));
-    const cfg = { ...frontmatter };
-    if (Object.prototype.hasOwnProperty.call(cfg, "enabled")) {
-      cfg.enabled = cfg.enabled !== "false" && cfg.enabled !== false;
-    }
-    _endpointCache.set(name, cfg);
-    return cfg;
-  } catch {
-    if (_endpointWatcher) _endpointCache.set(name, null);
-    return null;
-  }
-}
-
-// ── Delivery tracking ─────────────────────────────────────────────────
-// Per-endpoint append-only log at WEBHOOKS_DIR/<name>/deliveries.jsonl.
-// Each POST writes at least two lines: {status:"pending"|"processing"}
-// then {status:"done"|"failed"|"dedup"}. Earlier fields (payloadPreview,
-// headersSummary) are kept on the first line only; later status updates
-// reference the same `id` and are merged latest-wins at read time.
-const DELIVERY_INDEX_MAX_IDS = 2000;
-const DELIVERY_LOG_MAX_LINES = 10_000;
-/** @type {Map<string, Map<string, object>>} */
-const _deliveryIndexByEndpoint = new Map();
-/** @type {Set<string>} */
-const _deliveryIndexWarmed = new Set();
-/** @type {Map<string, number>} */
-const _deliveryLogLineCountByEndpoint = new Map();
-/** @type {Map<string, number>} distinct-id count at last warm/compaction; drives the redundancy-based compaction trigger. */
-const _deliveryKeptCountByEndpoint = new Map();
-function _deliveriesPath(name) {
-  return join(WEBHOOKS_DIR, name, "deliveries.jsonl");
-}
-function _mergeDeliveryRows(prior, entry) {
-  return prior ? { ...prior, ...entry } : entry;
-}
-function _isBlockingDeliveryStatus(status) {
-  return status === "received" || status === "processing" || status === "done";
-}
-function _deliveryIndexFor(name) {
-  let map = _deliveryIndexByEndpoint.get(name);
-  if (!map) {
-    map = new Map();
-    _deliveryIndexByEndpoint.set(name, map);
-  }
-  return map;
-}
-// Bound retained ids so successful ("done") deliveries cannot accumulate
-// forever in RAM or on disk. In-flight claims (received/processing) are
-// ALWAYS kept — dropping one would let a duplicate dispatch through. The
-// remaining DELIVERY_INDEX_MAX_IDS budget goes to the newest "done" rows
-// (dedup of recent retries) first, then newest terminal rows for history.
-// Older "done" rows age out; a sender re-delivering an id that stale is
-// treated as new — acceptable beyond any realistic retry window.
-function _retainedDeliveryIds(entries) {
-  const inflight = [];
-  const done = [];
-  const other = [];
-  for (const e of entries) {
-    if (e.status === "received" || e.status === "processing") inflight.push(e);
-    else if (e.status === "done") done.push(e);
-    else other.push(e);
-  }
-  const keep = new Set(inflight.map((e) => e.id));
-  const byTsDesc = (a, b) => String(b.ts || "").localeCompare(String(a.ts || ""));
-  done.sort(byTsDesc);
-  other.sort(byTsDesc);
-  for (const e of [...done, ...other]) {
-    if (keep.size >= DELIVERY_INDEX_MAX_IDS) break;
-    keep.add(e.id);
-  }
-  return keep;
-}
-function _pruneDeliveryIndexMap(byId) {
-  if (byId.size <= DELIVERY_INDEX_MAX_IDS) return;
-  const keep = _retainedDeliveryIds([...byId.values()]);
-  for (const id of byId.keys()) {
-    if (!keep.has(id)) byId.delete(id);
-  }
-}
-function _deliveryLogLineCount(name) {
-  return _deliveryLogLineCountByEndpoint.get(name) ?? 0;
-}
-function _setDeliveryLogLineCount(name, n) {
-  _deliveryLogLineCountByEndpoint.set(name, Math.max(0, n));
-}
-function _bumpDeliveryLogLineCount(name, delta = 1) {
-  _setDeliveryLogLineCount(name, _deliveryLogLineCount(name) + delta);
-}
-function _readDeliveriesFileMerged(name) {
-  const p = _deliveriesPath(name);
-  const byId = new Map();
-  let lineCount = 0;
-  if (!existsSync(p)) return { byId, lineCount };
-  try {
-    const raw = readFileSync(p, "utf8");
-    for (const line of raw.split("\n")) {
-      if (!line) continue;
-      lineCount++;
-      try {
-        const entry = JSON.parse(line);
-        if (!entry?.id) continue;
-        byId.set(entry.id, _mergeDeliveryRows(byId.get(entry.id), entry));
-      } catch {}
-    }
-  } catch {}
-  return { byId, lineCount };
-}
-function _ingestDeliveriesFileIntoIndex(name) {
-  const { byId: merged, lineCount } = _readDeliveriesFileMerged(name);
-  const byId = _deliveryIndexFor(name);
-  byId.clear();
-  for (const [id, row] of merged) byId.set(id, row);
-  _pruneDeliveryIndexMap(byId);
-  _setDeliveryLogLineCount(name, lineCount);
-  // Track the RETAINED (post-prune) distinct count, not the raw file count:
-  // a pre-existing oversized log then trips the compaction trigger promptly
-  // instead of inflating the threshold until it grows even larger.
-  _deliveryKeptCountByEndpoint.set(name, byId.size);
-}
-function _ensureDeliveryIndex(name) {
-  if (_deliveryIndexWarmed.has(name)) return;
-  _deliveryIndexWarmed.add(name);
-  _ingestDeliveriesFileIntoIndex(name);
-}
-function _applyDeliveryEntryToIndex(name, entry) {
-  if (!entry?.id) return;
-  const byId = _deliveryIndexFor(name);
-  byId.set(entry.id, _mergeDeliveryRows(byId.get(entry.id), entry));
-  _pruneDeliveryIndexMap(byId);
-}
-function _compactDeliveriesLogIfNeeded(name) {
-  // Redundancy-based trigger: compact only when the log holds meaningfully more
-  // lines than distinct ids (i.e. there are status-update rows to collapse).
-  // The threshold scales with the distinct-id count so an endpoint with many
-  // legitimate blocking ids does NOT re-compact on every append (which would
-  // re-read the whole log permanently once distinct > DELIVERY_LOG_MAX_LINES).
-  const kept = _deliveryKeptCountByEndpoint.get(name) ?? _deliveryIndexFor(name).size;
-  const threshold = Math.max(DELIVERY_LOG_MAX_LINES, kept * 2);
-  if (_deliveryLogLineCount(name) <= threshold) return;
-  const { byId: merged } = _readDeliveriesFileMerged(name);
-  const rows = [...merged.values()];
-  const keepIds = _retainedDeliveryIds(rows);
-  const keep = new Map();
-  for (const e of rows) {
-    if (keepIds.has(e.id)) keep.set(e.id, e);
-  }
-  const lines = [...keep.values()]
-    .sort((a, b) => String(a.ts || "").localeCompare(String(b.ts || "")))
-    .map((e) => JSON.stringify(e) + "\n")
-    .join("");
-  const p = _deliveriesPath(name);
-  const tmp = `${p}.compact-${process.pid}-${Date.now()}.tmp`;
-  try {
-    writeFileSync(tmp, lines);
-    renameSync(tmp, p);
-    // Refresh index + counters by RE-READING the post-rename file (not the
-    // pre-rename `keep` snapshot). The webhook daemon is the single writer and
-    // append+compact run synchronously in one process, so no append can
-    // interleave between the fresh read and the rename; re-reading keeps the
-    // warmed state exactly matching on-disk content.
-    _ingestDeliveriesFileIntoIndex(name);
-  } catch (err) {
-    logWebhook(`${name}: deliveries compact failed: ${err?.message ?? err}`);
-    try {
-      if (existsSync(tmp)) unlinkSync(tmp);
-    } catch {}
-  }
-}
-function appendDelivery(name, entry) {
-  try {
-    const dir = join(WEBHOOKS_DIR, name);
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    const full = { ts: new Date().toISOString(), ...entry };
-    const line = JSON.stringify(full) + "\n";
-    void appendFile(_deliveriesPath(name), line).catch((err) => {
-      logWebhook(`${name}: deliveries append failed: ${err?.message ?? err}`);
-    });
-    const wasWarmed = _deliveryIndexWarmed.has(name);
-    _ensureDeliveryIndex(name);
-    if (wasWarmed) _bumpDeliveryLogLineCount(name, 1);
-    _applyDeliveryEntryToIndex(name, full);
-    _compactDeliveriesLogIfNeeded(name);
-    return true;
-  } catch (err) {
-    logWebhook(`${name}: deliveries append failed: ${err?.message ?? err}`);
-    return false;
-  }
-}
-function readDeliveries(name) {
-  _ensureDeliveryIndex(name);
-  const byId = _deliveryIndexByEndpoint.get(name);
-  return byId ? [...byId.values()] : [];
-}
-// Dedup gate against a still-active claim or a successful prior delivery.
-// Only rows with status "received" (non-terminal claim) or "done"
-// (successful delivery) block a retry; terminal "failed" / "quiet-skip"
-// rows are NOT considered duplicates so a sender can legitimately
-// redeliver the same id after a recoverable failure. Without this
-// scoping, every prior row would permanently dedup the id and stop
-// legit redelivery.
-function deliveryExists(name, id) {
-  // "processing" must also dedup: a delegate dispatch in flight (up to
-  // DISPATCH_TIMEOUT_MS = 10 min) would otherwise be duplicated by a
-  // retried delivery of the same id while the first handler is still
-  // running. Block on any non-terminal status.
-  _ensureDeliveryIndex(name);
-  const entry = _deliveryIndexFor(name).get(id);
-  return Boolean(entry && _isBlockingDeliveryStatus(entry.status));
-}
-function extractDeliveryId(headers) {
-  return headers["x-github-delivery"]
-    || headers["x-delivery-id"]
-    || headers["x-request-id"]
-    || null;
-}
-function buildHeadersSummary(headers) {
-  const summary = {};
-  if (headers["x-github-event"]) summary.event_type = headers["x-github-event"];
-  if (headers["x-github-delivery"]) summary.delivery_id = headers["x-github-delivery"];
-  summary.signature_present = Boolean(
-    headers["x-hub-signature-256"] || headers["x-signature-256"]
-      || headers["stripe-signature"] || headers["sentry-hook-signature"]
-  );
-  if (headers["content-type"]) summary.content_type = headers["content-type"];
-  return summary;
-}
-// Public read helper — used by setup-server API to list deliveries across endpoints.
-function listAllDeliveries({ endpoint = null, status = null, limit = 100 } = {}) {
-  const out = [];
-  if (!existsSync(WEBHOOKS_DIR)) return out;
-  const names = endpoint
-    ? [endpoint]
-    : readdirSync(WEBHOOKS_DIR, { withFileTypes: true })
-        .filter((d) => d.isDirectory())
-        .map((d) => d.name);
-  for (const name of names) {
-    for (const entry of readDeliveries(name)) {
-      if (status && entry.status !== status) continue;
-      out.push({ endpoint: name, ...entry });
-    }
-  }
-  out.sort((a, b) => String(b.ts || "").localeCompare(String(a.ts || "")));
-  return out.slice(0, limit);
-}
-export { listAllDeliveries };
-function _readNgrokBinFromRegistry() {
-  if (process.platform !== "win32") return null;
-  try {
-    const r = spawnSync("reg", ["query", "HKCU\\Environment", "/v", "NGROK_BIN"], {
-      encoding: "utf8", windowsHide: true, stdio: ["ignore", "pipe", "ignore"],
-    });
-    if (r.status === 0 && r.stdout) {
-      const m = r.stdout.match(/NGROK_BIN\s+REG_(?:EXPAND_)?SZ\s+(.+?)\r?\n/);
-      if (m && m[1]) return m[1].trim();
-    }
-  } catch { /* missing reg.exe is non-fatal */ }
-  return null;
-}
-function resolveNgrokBin() {
-  // Invariant on Windows: BOTH process.env.NGROK_BIN AND HKCU\Environment\NGROK_BIN
-  // are candidate sources. process.env is the shell-start snapshot; registry
-  // is the live user definition. Each candidate is tried in order and the
-  // first that resolves to an existing file wins. This recovers two distinct
-  // post-setx cases without a host-agent restart:
-  //   (a) env unset, registry set    — fresh install + setx after process start
-  //   (b) env set to stale old path, registry set to new — user moved or
-  //       re-installed ngrok and setx'd the new path; the old env value would
-  //       otherwise dead-end at existsSync=false.
-  // POSIX has no registry; process.env is the sole candidate.
-  const candidates = [];
-  if (process.env.NGROK_BIN) candidates.push(process.env.NGROK_BIN);
-  const fromReg = _readNgrokBinFromRegistry();
-  if (fromReg && !candidates.includes(fromReg)) candidates.push(fromReg);
-  for (const p of candidates) {
-    if (existsSync(p)) return p;
-  }
-  if (candidates.length > 0) {
-    throw new Error(`NGROK_BIN candidates (${candidates.join(", ")}) do not exist on disk. Set NGROK_BIN to the correct ngrok binary path.`);
-  }
-  throw new Error('NGROK_BIN env var is not set. Set NGROK_BIN to the path of the ngrok binary (e.g. NGROK_BIN=/usr/local/bin/ngrok).');
-}
-const NGROK_META_FILE = join(DATA_DIR, "ngrok-meta.json");
-const NGROK_OLD_PID_FILE = join(DATA_DIR, "ngrok.pid");
-const NGROK_MAX_AGE_MS = 24 * 60 * 60 * 1e3; // 24 hours
-
-function normalizeDomain(d) {
-  if (!d) return '';
-  const url = new URL(d.includes('://') ? d : 'https://' + d);
-  if (!url.hostname) throw new Error(`[webhook] invalid host: ${d}`);
-  return url.hostname.toLowerCase();
-}
-
-function readNgrokMeta() {
-  try { return JSON.parse(readFileSync(NGROK_META_FILE, 'utf8')) } catch {}
-  // Migration: read old pid file if meta doesn't exist
-  try {
-    const pid = parseInt(readFileSync(NGROK_OLD_PID_FILE, 'utf8').trim());
-    if (pid > 0) {
-      logWebhook(`migrating ngrok.pid (PID ${pid}) to ngrok-meta.json`);
-      const meta = { pid, domain: '', port: 0, startedAt: new Date().toISOString() };
-      writeNgrokMeta(meta);
-      try { unlinkSync(NGROK_OLD_PID_FILE) } catch {}
-      return meta;
-    }
-  } catch {}
-  return null;
-}
-function writeNgrokMeta(meta) {
-  try { writeFileSync(NGROK_META_FILE, JSON.stringify(meta, null, 2)) } catch {}
-}
-function clearNgrokMeta() {
-  try { unlinkSync(NGROK_META_FILE) } catch {}
-}
-// Recycled-PID guard: a stale ngrok-meta.json may name a PID that ngrok
-// long ago freed and the OS reassigned to an unrelated process (commonly
-// another mixdog server). Verify the PID is actually an ngrok process
-// before sending a kill signal, so a live peer's server is never taken
-// down. Returns false (skip kill) when the check is inconclusive.
-function isLikelyNgrok(pid) {
-  if (!pid || pid <= 0) return false;
-  try {
-    if (process.platform === "win32") {
-      const r = spawnSync("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"], { encoding: "utf8", timeout: 5000, windowsHide: true });
-      return /ngrok/i.test(r.stdout || "");
-    }
-    const r = spawnSync("ps", ["-p", String(pid), "-o", "comm="], { encoding: "utf8", timeout: 5000, windowsHide: true });
-    return /ngrok/i.test(r.stdout || "");
-  } catch { return false; }
-}
-
-function isProcessAlive(pid) {
-  if (!pid || pid <= 0) return false;
-  try { process.kill(pid, 0); return true; } catch { return false; }
-}
-
-// Strict PID extraction: the first non-empty output line must be decimal-only.
-// `123junk` / any non-numeric noise → null, so a malformed shell result can
-// never be coerced into a real PID we might later signal or kill.
-function parseStrictPidLine(out) {
-  const line = String(out || "").split(/\r?\n/).map((s) => s.trim()).find((s) => s.length > 0);
-  if (!line || !/^\d+$/.test(line)) return null;
-  const n = parseInt(line, 10);
-  return Number.isFinite(n) && n > 0 ? n : null;
-}
-
-function resolvePortOwnerPid(port) {
-  // Coerce + range-validate the port BEFORE any spawn so it can never inject
-  // into a command, and use spawnSync argv (no shell) for defense in depth.
-  // Invalid port → null (treated as "no owner", never an exec).
-  const p = Number(port);
-  if (!Number.isInteger(p) || p < 1 || p > 65535) return null;
-  try {
-    if (process.platform === "win32") {
-      const r = spawnSync(
-        "powershell",
-        ["-NoProfile", "-Command", `(Get-NetTCPConnection -LocalPort ${p} -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1).OwningProcess`],
-        { encoding: "utf8", timeout: 3000, windowsHide: true },
-      );
-      return r.status === 0 ? parseStrictPidLine(r.stdout) : null;
-    }
-    const r = spawnSync("lsof", ["-ti", `:${p}`, "-sTCP:LISTEN"], { encoding: "utf8", timeout: 3000, windowsHide: true });
-    return r.status === 0 ? parseStrictPidLine(r.stdout) : null;
-  } catch {
-    return null;
-  }
-}
-
-async function handleWebhookPortInUse(basePort, expectedDomain) {
-  const ownerPid = resolvePortOwnerPid(basePort);
-  const ownerAlive = ownerPid != null && isProcessAlive(ownerPid);
-  const ownerIsNgrok = ownerAlive && isLikelyNgrok(ownerPid);
-  logWebhook(
-    `port ${basePort} EADDRINUSE — not reclaiming external PID ${ownerPid ?? "unknown"} (alive=${ownerAlive}, ngrok=${ownerIsNgrok}); trying next port`,
-  );
-  return { ok: false, bump: true, ownerPid };
-}
-
-function checkNgrokHealth(expectedDomain, expectedPort = null) {
-  try {
-    return new Promise((resolve) => {
-      const req = http.get("http://localhost:4040/api/tunnels", { timeout: 2000 }, (res) => {
-        let data = "";
-        res.on("data", chunk => data += chunk);
-        res.on("end", () => {
-          try {
-            const tunnels = JSON.parse(data).tunnels || [];
-            const expected = normalizeDomain(expectedDomain);
-            const match = tunnels.some(t => {
-              if (normalizeDomain(t.public_url) !== expected) return false;
-              if (!expectedPort) return true;
-              const addr = String(t.config?.addr || '');
-              return addr === `http://localhost:${expectedPort}`
-                || addr === `https://localhost:${expectedPort}`
-                || addr.endsWith(`:${expectedPort}`);
-            });
-            resolve(match);
-          } catch { resolve(false); }
-        });
-      });
-      req.on("error", () => resolve(false));
-      req.on("timeout", () => { req.destroy(); resolve(false); });
-    });
-  } catch { return Promise.resolve(false); }
-}
+import { logWebhook } from "./webhook/log.mjs";
+import { SIGNATURE_HEADERS, extractSignature, STRIPE_TOLERANCE_MS, verifySignature } from "./webhook/signature.mjs";
+import {
+  WEBHOOKS_DIR,
+  _readEndpointSecret,
+  _closeEndpointWatcher,
+  loadEndpointConfig,
+  appendDelivery,
+  deliveryExists,
+  extractDeliveryId,
+  buildHeadersSummary,
+} from "./webhook/deliveries.mjs";
+import {
+  NGROK_MAX_AGE_MS,
+  resolveNgrokBin,
+  normalizeDomain,
+  readNgrokMeta,
+  writeNgrokMeta,
+  clearNgrokMeta,
+  isLikelyNgrok,
+  isProcessAlive,
+  parseStrictPidLine,
+  resolvePortOwnerPid,
+  handleWebhookPortInUse,
+  checkNgrokHealth,
+} from "./webhook/ngrok.mjs";
 
 class WebhookServer {
   config;
@@ -583,19 +41,8 @@ class WebhookServer {
   listenInFlight = false;
   noSecretWarned = false;
   ngrokProcess = null;
-  quiet = null;
-  // ctor accepts the TOP-LEVEL normalized config slice as the second arg:
-  //   new WebhookServer(config.webhook, { quiet: config.quiet })
-  constructor(config, topLevel) {
+  constructor(config) {
     this.config = config;
-    this._applyTopLevel(topLevel);
-  }
-  _applyTopLevel(src) {
-    this.quiet = null;
-    if (!src || typeof src !== "object") return;
-    if (src.quiet && typeof src.quiet === "object") {
-      this.quiet = src.quiet;
-    }
   }
   setEventPipeline(pipeline) {
     this.eventPipeline = pipeline;
@@ -782,7 +229,6 @@ class WebhookServer {
       const parsed = body ? JSON.parse(body) : {};
       const eventType = headers["x-github-event"] || null;
       const eventAction = parsed?.action || null;
-      if (this._maybeQuietSkip(name, eventType, eventAction, deliveryId, res)) return;
       // Invariant: skip self-generated GitHub issue_comment events. All
       // mixdog-authored issue comments are prefixed with "[mixdog "
       // (e.g. "[mixdog reviewer] ..."), so a comment.body starting with
@@ -882,32 +328,6 @@ class WebhookServer {
     }
     return true;
   }
-  // Quiet-hours skip: drop (do not queue) when webhook opt-in is on
-  // and current time falls inside the shared quiet window. Returns
-  // true when the request was answered with a 202 quiet-skip.
-  _maybeQuietSkip(name, eventType, eventAction, deliveryId, res) {
-    const webhookRespect = this.config?.respectQuiet === true;
-    const quietCfg = this.quiet
-      ? { schedule: this.quiet.schedule ?? null, holidays: this.quiet.holidays ?? false }
-      : null;
-    if (webhookRespect && quietCfg && isInQuietWindow(quietCfg, new Date())) {
-      logWebhook(`${name}: quiet-skip event=${eventType || "<none>"} action=${eventAction || "<none>"} (id=${deliveryId})`);
-      // Terminal delivery row: the `received` claim at the top of
-      // handleRequest must be resolved by a terminal status. Without
-      // it, deliveryExists() keeps the non-terminal row visible and
-      // dedupes every future retry of the same id forever.
-      appendDelivery(name, {
-        id: deliveryId,
-        status: "quiet-skip",
-        event: eventType,
-        action: eventAction,
-      });
-      res.writeHead(202, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ status: "quiet-skip", event: eventType, action: eventAction, id: deliveryId }));
-      return true;
-    }
-    return false;
-  }
   _listenWithRetry() {
     if (!this.server || this.listenInFlight) return;
     this.listenInFlight = true;
@@ -1149,10 +569,8 @@ class WebhookServer {
     logWebhook("stopped (ngrok left running for reuse)");
     return closed;
   }
-  // reloadConfig(webhookCfg, topLevel, options?)
-  // `topLevel` mirrors the constructor: a top-level normalized config
-  // slice (typically `{ quiet }`).
-  async reloadConfig(config, topLevel, options = {}) {
+  // reloadConfig(webhookCfg, options?)
+  async reloadConfig(config, options = {}) {
     // Await server.close() before re-listen: server.close() is async and
     // releases the bound port only after the close callback fires. Calling
     // start() before that drains races the port and surfaces EADDRINUSE
@@ -1160,7 +578,6 @@ class WebhookServer {
     // holds the port.
     await this.stop();
     this.config = config;
-    this._applyTopLevel(topLevel);
     if (options.autoStart !== false && config.enabled) this.start();
   }
   // ── Webhook handler ───────────────────────────────────────────────
@@ -1174,14 +591,17 @@ class WebhookServer {
     // The signature gate (below) fails closed on any WEBHOOK.md
     // endpoint lacking a secret, so dropping `mode` does not weaken auth.
     // `instructions` carries the markdown body (the prompt) so callers read
-    // one file instead of a config.json + instructions.md pair.
-    const handler = { channel: null, role: "webhook-handler", model: null, instructions: "" };
+    // one file instead of a config.json + instructions.md pair. Frontmatter
+    // `name`/`description` (SKILL.md convention) are display-only: dir name
+    // stays the canonical identity/URL routing key, so `name` is ignored here.
+    const handler = { channel: null, role: "webhook-handler", model: null, description: "", instructions: "" };
     if (existsSync(mdPath)) {
       try {
         const { frontmatter, body } = readMarkdownDocument(readFileSync(mdPath, "utf8"));
         if (frontmatter.channel) handler.channel = frontmatter.channel;
         if (typeof frontmatter.role === "string" && frontmatter.role) handler.role = frontmatter.role;
         if (typeof frontmatter.model === "string" && frontmatter.model) handler.model = frontmatter.model;
+        handler.description = String(frontmatter.description || "");
         handler.instructions = String(body || "").trim();
       } catch {
       }
@@ -1313,4 +733,11 @@ ${payload}
 }
 export {
   WebhookServer,
+  // Exported for scripts/webhook-smoke.mjs unit coverage. No behavior
+  // change — these were previously module-private.
+  extractSignature,
+  verifySignature,
+  loadEndpointConfig,
+  SIGNATURE_HEADERS,
+  STRIPE_TOLERANCE_MS,
 };