forge-remote 0.1.13 → 0.1.15

package/src/webhook-server.js

@@ -0,0 +1,714 @@
+// Forge Remote Relay — Secure Webhook Receiver
+// Copyright (c) 2025-2026 Iron Forge Apps
+// Created by Daniel Wendel, CEO/Founder of Iron Forge Apps
+
+import { createServer } from "node:http";
+import crypto from "node:crypto";
+import { getDb, FieldValue } from "./firebase.js";
+import { startTunnel, stopTunnel } from "./tunnel-manager.js";
+import {
+  startNewSession,
+  getActiveSessionCount,
+  MAX_WEBHOOK_SESSIONS,
+} from "./session-manager.js";
+import { getWebhookConfig } from "./webhook-watcher.js";
+import * as log from "./logger.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const MAX_BODY_SIZE = 1024 * 1024; // 1 MB
+const RATE_LIMIT_WINDOW_MS = 60_000; // 1 minute
+const RATE_LIMIT_MAX = 10; // max 10 requests per webhook per minute
+const DEDUP_MAX_SIZE = 1000;
+const SLACK_TIMESTAMP_MAX_AGE_S = 300; // 5 minutes
+const MAX_VARIABLE_LENGTH = 1000;
+
+// Unique session ID used for tunnel-manager (not a real Claude session).
+const WEBHOOK_TUNNEL_ID = "__webhook-server__";
+
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+
+let server = null;
+let serverPort = null;
+let tunnelUrl = null;
+let currentDesktopId = null;
+
+/** LRU deduplication set — stores recent delivery IDs. */
+const recentDeliveryIds = new Set();
+const deliveryIdOrder = []; // oldest first, for eviction
+
+/** Per-webhook sliding window rate limiter. Map<webhookId, number[]> */
+const rateLimitWindows = new Map();
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Start the webhook HTTP server on a random port, open a tunnel, and
+ * store the public URL in Firestore.
+ *
+ * @param {string} desktopId
+ * @returns {Promise<{server: import('http').Server, port: number, tunnelUrl: string}|null>}
+ */
+export async function startWebhookServer(desktopId) {
+  currentDesktopId = desktopId;
+
+  // Create HTTP server on a random port.
+  const httpServer = createServer(handleRequest);
+
+  const port = await new Promise((resolve, reject) => {
+    httpServer.listen(0, "127.0.0.1", () => {
+      resolve(httpServer.address().port);
+    });
+    httpServer.on("error", reject);
+  });
+
+  server = httpServer;
+  serverPort = port;
+
+  log.info(`Webhook server listening on 127.0.0.1:${port}`);
+
+  // Start a cloudflare tunnel for the webhook server.
+  const url = await startTunnel(WEBHOOK_TUNNEL_ID, port);
+  if (!url) {
+    log.warn("Could not create tunnel for webhook server — webhooks disabled");
+    httpServer.close();
+    server = null;
+    serverPort = null;
+    return null;
+  }
+
+  tunnelUrl = url;
+
+  // Store the public URL in Firestore.
+  try {
+    const db = getDb();
+    await db.collection("desktops").doc(desktopId).update({
+      webhookServerUrl: url,
+    });
+  } catch (err) {
+    log.error(`Failed to store webhook URL in Firestore: ${err.message}`);
+  }
+
+  return { server: httpServer, port, tunnelUrl: url };
+}
+
+/**
+ * Stop the webhook server and its tunnel.
+ */
+export async function stopWebhookServer() {
+  if (tunnelUrl) {
+    await stopTunnel(WEBHOOK_TUNNEL_ID);
+    tunnelUrl = null;
+  }
+
+  if (server) {
+    server.close();
+    server = null;
+    serverPort = null;
+    log.info("Webhook server stopped");
+  }
+
+  // Clear webhook URL from Firestore.
+  if (currentDesktopId) {
+    try {
+      const db = getDb();
+      await db.collection("desktops").doc(currentDesktopId).update({
+        webhookServerUrl: FieldValue.delete(),
+      });
+    } catch {
+      // Best effort — relay is shutting down.
+    }
+    currentDesktopId = null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Request handler
+// ---------------------------------------------------------------------------
+
+/**
+ * Main HTTP request handler.
+ *
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ */
+async function handleRequest(req, res) {
+  // Health check endpoint.
+  if (req.method === "GET" && req.url === "/health") {
+    return sendJson(res, 200, { status: "ok" });
+  }
+
+  // Parse webhook route: POST /hooks/:webhookId
+  const match = req.url?.match(/^\/hooks\/([a-zA-Z0-9_-]+)$/);
+  if (!match) {
+    return sendJson(res, 404, { error: "not found" });
+  }
+
+  if (req.method !== "POST") {
+    res.setHeader("allow", "POST");
+    return sendJson(res, 405, { error: "method not allowed" });
+  }
+
+  const webhookId = match[1];
+  const sourceIp =
+    req.headers["x-forwarded-for"]?.split(",")[0]?.trim() ||
+    req.socket.remoteAddress ||
+    "unknown";
+
+  try {
+    await handleWebhookPost(req, res, webhookId, sourceIp);
+  } catch (err) {
+    log.error(`Webhook handler error: ${err.message}`);
+    await writeAuditLog(
+      webhookId,
+      "unknown",
+      sourceIp,
+      "rejected",
+      err.message,
+      null,
+    );
+    sendJson(res, 500, { error: "internal server error" });
+  }
+}
+
+/**
+ * Handle a POST to /hooks/:webhookId.
+ */
+async function handleWebhookPost(req, res, webhookId, sourceIp) {
+  // 1. Look up webhook config.
+  const config = getWebhookConfig(webhookId);
+  if (!config) {
+    await writeAuditLog(
+      webhookId,
+      "unknown",
+      sourceIp,
+      "rejected",
+      "webhook not found",
+      null,
+    );
+    return sendJson(res, 404, { error: "webhook not found" });
+  }
+
+  if (config.enabled === false) {
+    await writeAuditLog(
+      webhookId,
+      config.source || "custom",
+      sourceIp,
+      "rejected",
+      "webhook disabled",
+      null,
+    );
+    return sendJson(res, 403, { error: "webhook disabled" });
+  }
+
+  const source = config.source || "custom";
+
+  // 2. Read body with size limit.
+  let rawBody;
+  try {
+    rawBody = await readBody(req, MAX_BODY_SIZE);
+  } catch (err) {
+    if (err.message === "payload too large") {
+      await writeAuditLog(
+        webhookId,
+        source,
+        sourceIp,
+        "rejected",
+        "payload too large",
+        null,
+      );
+      return sendJson(res, 413, { error: "payload too large" });
+    }
+    throw err;
+  }
+
+  // 2a. Handle Slack url_verification challenge (must happen before
+  //     signature validation — we don't have the Slack signing secret).
+  if (source === "slack") {
+    try {
+      const maybeChallenge = JSON.parse(rawBody.toString("utf-8"));
+      if (
+        maybeChallenge.type === "url_verification" &&
+        maybeChallenge.challenge
+      ) {
+        log.info(
+          `Slack URL verification for webhook ${webhookId} — responding with challenge`,
+        );
+        return sendJson(res, 200, { challenge: maybeChallenge.challenge });
+      }
+    } catch {
+      // Not valid JSON — continue to normal flow which will reject it.
+    }
+  }
+
+  // 3. Delivery ID deduplication.
+  const deliveryId =
+    req.headers["x-github-delivery"] || req.headers["x-webhook-delivery-id"];
+
+  if (deliveryId) {
+    if (recentDeliveryIds.has(deliveryId)) {
+      log.info(`Duplicate delivery ignored: ${deliveryId}`);
+      return sendJson(res, 200, { status: "duplicate" });
+    }
+    addDeliveryId(deliveryId);
+  }
+
+  // 4. Signature validation.
+  const signatureValid = validateSignature(
+    source,
+    config,
+    req.headers,
+    rawBody,
+  );
+  if (!signatureValid) {
+    await writeAuditLog(
+      webhookId,
+      source,
+      sourceIp,
+      "rejected",
+      "invalid signature",
+      null,
+    );
+    return sendJson(res, 401, { error: "invalid signature" });
+  }
+
+  // 5. Per-webhook rate limiting.
+  if (isWebhookRateLimited(webhookId)) {
+    await writeAuditLog(
+      webhookId,
+      source,
+      sourceIp,
+      "rejected",
+      "rate limited",
+      null,
+    );
+    return sendJson(res, 429, { error: "rate limited" });
+  }
+
+  // 6. Concurrent session cap.
+  const activeCount = getActiveSessionCount();
+  if (activeCount >= MAX_WEBHOOK_SESSIONS) {
+    await writeAuditLog(
+      webhookId,
+      source,
+      sourceIp,
+      "rejected",
+      "at session capacity",
+      null,
+    );
+    return sendJson(res, 503, { error: "at session capacity" });
+  }
+
+  // 7. Parse payload and render prompt template.
+  let payload;
+  try {
+    payload = JSON.parse(rawBody.toString("utf-8"));
+  } catch {
+    await writeAuditLog(
+      webhookId,
+      source,
+      sourceIp,
+      "rejected",
+      "invalid JSON body",
+      null,
+    );
+    return sendJson(res, 400, { error: "invalid JSON body" });
+  }
+
+  const prompt = renderTemplate(config.promptTemplate || "", payload);
+  const projectPath = config.projectPath || process.cwd();
+  const model = config.model || "sonnet";
+
+  // 8. Start a new session.
+  let sessionId;
+  try {
+    sessionId = await startNewSession(currentDesktopId, {
+      prompt,
+      projectPath,
+      model,
+      webhookMeta: {
+        webhookId,
+        source,
+        replyUrl:
+          source === "slack" ? config.sourceConfig?.replyWebhookUrl : null,
+      },
+    });
+  } catch (err) {
+    await writeAuditLog(
+      webhookId,
+      source,
+      sourceIp,
+      "rejected",
+      `session start failed: ${err.message}`,
+      null,
+    );
+    return sendJson(res, 500, { error: "failed to start session" });
+  }
+
+  // 9. Audit log + update trigger count.
+  await writeAuditLog(webhookId, source, sourceIp, "accepted", null, sessionId);
+  await updateTriggerCount(webhookId);
+
+  log.info(
+    `Webhook ${webhookId} (${source}) accepted — session ${sessionId || "started"}`,
+  );
+
+  return sendJson(res, 200, {
+    status: "accepted",
+    sessionId: sessionId || null,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Body reading
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the full request body up to a byte limit.
+ *
+ * @param {import('http').IncomingMessage} req
+ * @param {number} maxBytes
+ * @returns {Promise<Buffer>}
+ */
+function readBody(req, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > maxBytes) {
+        req.destroy();
+        reject(new Error("payload too large"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Delivery ID deduplication (LRU)
+// ---------------------------------------------------------------------------
+
+function addDeliveryId(id) {
+  if (recentDeliveryIds.size >= DEDUP_MAX_SIZE) {
+    // Evict the oldest.
+    const oldest = deliveryIdOrder.shift();
+    recentDeliveryIds.delete(oldest);
+  }
+  recentDeliveryIds.add(id);
+  deliveryIdOrder.push(id);
+}
+
+// ---------------------------------------------------------------------------
+// Signature validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate the webhook signature based on source type.
+ * Returns true if valid, false otherwise.
+ */
+function validateSignature(source, config, headers, rawBody) {
+  const secret = config.webhookSecret;
+  if (!secret) {
+    // No secret configured — skip validation.
+    log.warn(
+      "Webhook has no secret configured — skipping signature validation",
+    );
+    return true;
+  }
+
+  switch (source) {
+    case "github":
+      return validateGitHubSignature(headers, rawBody, secret);
+    case "slack":
+      return validateSlackSignature(headers, rawBody, secret);
+    default:
+      return validateCustomSignature(
+        headers,
+        rawBody,
+        secret,
+        config.sourceConfig,
+      );
+  }
+}
+
+/**
+ * GitHub: Validate x-hub-signature-256 with HMAC-SHA256.
+ */
+function validateGitHubSignature(headers, rawBody, secret) {
+  const signature = headers["x-hub-signature-256"];
+  if (!signature) return false;
+
+  const expected =
+    "sha256=" +
+    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
+
+  // Constant-time comparison.
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(signature),
+      Buffer.from(expected),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Slack: Validate x-slack-signature using v0:timestamp:body.
+ * Also checks timestamp is within 5 minutes to prevent replay.
+ *
+ * Slack signing secrets start with a known prefix. If the stored secret
+ * is not a real Slack signing secret (e.g. auto-generated by the app),
+ * skip validation — the URL verification challenge already proves ownership.
+ */
+function validateSlackSignature(headers, rawBody, secret) {
+  const signature = headers["x-slack-signature"];
+  const timestampStr = headers["x-slack-request-timestamp"];
+
+  // If no Slack signature headers, this isn't a Slack request — reject.
+  if (!signature || !timestampStr) return false;
+
+  // If the stored secret doesn't look like a Slack signing secret,
+  // skip validation (user hasn't configured it yet).
+  if (!secret.startsWith("v0=") && secret.length < 40) {
+    log.warn(
+      "Slack webhook secret doesn't appear to be a Slack signing secret — skipping signature validation",
+    );
+    return true;
+  }
+
+  // Replay protection — timestamp must be within 5 minutes.
+  const timestamp = parseInt(timestampStr, 10);
+  if (isNaN(timestamp)) return false;
+  const now = Math.floor(Date.now() / 1000);
+  if (Math.abs(now - timestamp) > SLACK_TIMESTAMP_MAX_AGE_S) return false;
+
+  const baseString = `v0:${timestampStr}:${rawBody.toString("utf-8")}`;
+  const expected =
+    "v0=" +
+    crypto.createHmac("sha256", secret).update(baseString).digest("hex");
+
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(signature),
+      Buffer.from(expected),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Custom: Validate a configurable signature header with HMAC-SHA256.
+ */
+function validateCustomSignature(headers, rawBody, secret, sourceConfig) {
+  const headerName = (
+    sourceConfig?.signatureHeader || "x-webhook-signature"
+  ).toLowerCase();
+  const signature = headers[headerName];
+  if (!signature) return false;
+
+  const expected = crypto
+    .createHmac("sha256", secret)
+    .update(rawBody)
+    .digest("hex");
+
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(signature),
+      Buffer.from(expected),
+    );
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rate limiting (per-webhook sliding window)
+// ---------------------------------------------------------------------------
+
+function isWebhookRateLimited(webhookId) {
+  const now = Date.now();
+  let timestamps = rateLimitWindows.get(webhookId);
+  if (!timestamps) {
+    timestamps = [];
+    rateLimitWindows.set(webhookId, timestamps);
+  }
+
+  // Remove entries outside the window.
+  while (timestamps.length > 0 && timestamps[0] < now - RATE_LIMIT_WINDOW_MS) {
+    timestamps.shift();
+  }
+
+  if (timestamps.length >= RATE_LIMIT_MAX) {
+    return true;
+  }
+
+  timestamps.push(now);
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Template rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Replace {{variable}} placeholders with values from the payload.
+ * Supports dot-notation for nested access (e.g., {{pull_request.title}}).
+ *
+ * Unresolved variables become [unknown: varName].
+ * Values are sanitized: max 1000 chars, control chars stripped except newlines.
+ */
+function renderTemplate(template, payload) {
+  return template.replace(/\{\{([^}]+)\}\}/g, (_match, varPath) => {
+    const trimmed = varPath.trim();
+    const value = resolveNestedValue(payload, trimmed);
+
+    if (value === undefined || value === null) {
+      return `[unknown: ${trimmed}]`;
+    }
+
+    // Convert to string and sanitize.
+    let str = String(value);
+
+    // Strip control characters except newlines (\n) and carriage returns (\r).
+    str = str.replace(/[\x00-\x09\x0b\x0c\x0e-\x1f\x7f]/g, "");
+
+    // Truncate to max variable length.
+    if (str.length > MAX_VARIABLE_LENGTH) {
+      str = str.slice(0, MAX_VARIABLE_LENGTH) + "...";
+    }
+
+    return str;
+  });
+}
+
+/**
+ * Resolve a dot-notation path against an object.
+ * e.g., resolveNestedValue({a: {b: "c"}}, "a.b") => "c"
+ */
+function resolveNestedValue(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+// ---------------------------------------------------------------------------
+// Audit logging
+// ---------------------------------------------------------------------------
+
+/**
+ * Write an audit log entry to Firestore.
+ */
+async function writeAuditLog(
+  webhookId,
+  source,
+  sourceIp,
+  status,
+  reason,
+  sessionId,
+) {
+  if (!currentDesktopId) return;
+
+  try {
+    const db = getDb();
+    await db
+      .collection("desktops")
+      .doc(currentDesktopId)
+      .collection("webhookLogs")
+      .add({
+        webhookId,
+        source,
+        timestamp: FieldValue.serverTimestamp(),
+        sourceIp,
+        status,
+        ...(reason ? { reason } : {}),
+        ...(sessionId ? { sessionId } : {}),
+      });
+  } catch (err) {
+    log.error(`Failed to write webhook audit log: ${err.message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Trigger count
+// ---------------------------------------------------------------------------
+
+/**
+ * Increment the trigger count on the webhook document in Firestore.
+ */
+async function updateTriggerCount(webhookId) {
+  if (!currentDesktopId) return;
+
+  try {
+    const db = getDb();
+    await db
+      .collection("desktops")
+      .doc(currentDesktopId)
+      .collection("webhooks")
+      .doc(webhookId)
+      .update({
+        triggerCount: FieldValue.increment(1),
+        lastTriggeredAt: FieldValue.serverTimestamp(),
+      });
+  } catch (err) {
+    log.error(
+      `Failed to update trigger count for ${webhookId}: ${err.message}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Slack reply
+// ---------------------------------------------------------------------------
+
+/**
+ * Post a message to a Slack Incoming Webhook URL.
+ * Used to send Claude's response back to the channel that triggered the session.
+ */
+export async function postToSlack(webhookUrl, text) {
+  try {
+    const body = JSON.stringify({ text });
+    const res = await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body,
+    });
+    if (!res.ok) {
+      log.error(`Slack reply failed (${res.status}): ${await res.text()}`);
+    } else {
+      log.success("Posted Claude's response back to Slack");
+    }
+  } catch (err) {
+    log.error(`Failed to post to Slack: ${err.message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sendJson(res, statusCode, data) {
+  const body = JSON.stringify(data);
+  res.writeHead(statusCode, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(body),
+  });
+  res.end(body);
+}