mixdog 0.9.2 → 0.9.4

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

@@ -0,0 +1,312 @@
+import { join } from "path";
+import { readFileSync, mkdirSync, writeFileSync, unlinkSync, existsSync, renameSync, watch as fsWatch } from "fs";
+import { appendFile } from "fs/promises";
+import { DATA_DIR } from "../config.mjs";
+import { readMarkdownDocument } from "../../../shared/markdown-frontmatter.mjs";
+import { logWebhook } from "./log.mjs";
+
+const WEBHOOKS_DIR = join(DATA_DIR, "webhooks");
+
+// ── 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(); });
+    // Don't let the watcher keep the event loop alive: embedders/tests that
+    // merely load an endpoint config should still be able to exit cleanly.
+    _endpointWatcher.unref?.();
+  } 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;
+  }
+}
+// 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;
+}
+
+export {
+  WEBHOOKS_DIR,
+  _readEndpointSecret,
+  _closeEndpointWatcher,
+  loadEndpointConfig,
+  appendDelivery,
+  deliveryExists,
+  extractDeliveryId,
+  buildHeadersSummary,
+};

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

@@ -0,0 +1,42 @@
+import { join } from "path";
+import { appendFileSync } from "fs";
+import { appendFile } from "fs/promises";
+import { DATA_DIR } from "../config.mjs";
+
+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?.();
+  }
+}
+
+export { WEBHOOK_LOG, flushWebhookLog, logWebhook };

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

@@ -0,0 +1,181 @@
+import * as http from "http";
+import { join } from "path";
+import { spawnSync } from "child_process";
+import { readFileSync, writeFileSync, unlinkSync, existsSync } from "fs";
+import { DATA_DIR } from "../config.mjs";
+import { logWebhook } from "./log.mjs";
+
+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); }
+}
+
+export {
+  NGROK_MAX_AGE_MS,
+  resolveNgrokBin,
+  normalizeDomain,
+  readNgrokMeta,
+  writeNgrokMeta,
+  clearNgrokMeta,
+  isLikelyNgrok,
+  isProcessAlive,
+  parseStrictPidLine,
+  resolvePortOwnerPid,
+  handleWebhookPortInUse,
+  checkNgrokHealth,
+};

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

@@ -0,0 +1,60 @@
+import * as crypto from "crypto";
+
+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;
+  }
+}
+
+export { SIGNATURE_HEADERS, extractSignature, STRIPE_TOLERANCE_MS, verifySignature };