forge-remote 0.1.14 → 0.1.15

package/firestore.rules

@@ -37,6 +37,14 @@ service cloud.firestore {
         allow create: if isSignedIn();
         allow update: if isSignedIn();
       }
+
+      // ---- Webhooks (subcollection) ----
+      match /webhooks/{webhookId} {
+        allow read: if isSignedIn();
+        allow create: if isSignedIn();
+        allow update: if isSignedIn();
+        allow delete: if isSignedIn();
+      }
     }
 
     // ---- Sessions ----

package/package.json

@@ -1,18 +1,11 @@
 {
   "name": "forge-remote",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Desktop relay for Forge Remote — monitor and control Claude Code sessions from your phone",
   "type": "module",
   "license": "UNLICENSED",
   "author": "Daniel Wendel <daniel@ironforgeapps.com> (https://ironforgeapps.com)",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/IronForgeApps/forge-remote.git"
-  },
-  "bugs": {
-    "url": "https://github.com/IronForgeApps/forge-remote/issues"
-  },
-  "homepage": "https://github.com/IronForgeApps/forge-remote#readme",
+  "homepage": "https://forgeremote.com",
   "engines": {
     "node": ">=18.0.0"
   },

package/src/cli.js

@@ -30,7 +30,10 @@ import {
 import { stopAllTunnels } from "./tunnel-manager.js";
 import { stopAllCaptures } from "./screenshot-manager.js";
 import { scanProjects } from "./project-scanner.js";
+import { startWebhookServer, stopWebhookServer } from "./webhook-server.js";
+import { watchWebhookConfigs, stopWatching } from "./webhook-watcher.js";
 import * as log from "./logger.js";
+import { checkForUpdate } from "./update-checker.js";
 
 program
   .name("forge-remote")
@@ -126,6 +129,7 @@ program
     "Start the desktop relay (register, heartbeat, listen for commands)",
   )
   .action(async () => {
+    await checkForUpdate();
     initFirebase();
     const desktopId = await registerDesktop();
 
@@ -140,6 +144,13 @@ program
 
     listenForCommands(desktopId);
 
+    // Start webhook server with tunnel for external integrations.
+    const webhookServer = await startWebhookServer(desktopId);
+    if (webhookServer) {
+      watchWebhookConfigs(desktopId, webhookServer.tunnelUrl);
+      log.info(`Webhook server ready at ${webhookServer.tunnelUrl}`);
+    }
+
     // Print startup banner.
     log.banner(hostname(), getPlatformName(), desktopId, projects.length);
 
@@ -162,6 +173,8 @@ program
       }, 5000);
 
       try {
+        stopWatching();
+        await stopWebhookServer();
         await shutdownAllSessions();
         stopAllTunnels();
         stopAllCaptures();
@@ -183,6 +196,7 @@ program
   .command("pair")
   .description("Generate a pairing QR code for the mobile app")
   .action(async () => {
+    await checkForUpdate();
     initFirebase();
     const desktopId = await registerDesktop();
 
@@ -232,4 +246,52 @@ program
     await runInit({ projectId: opts.projectId });
   });
 
+program
+  .command("set-pro <uid>")
+  .description(
+    "Grant permanent Pro access to a Firebase Auth UID via custom claims",
+  )
+  .action(async (uid) => {
+    initFirebase();
+
+    const { getAuth } = await import("firebase-admin/auth");
+    const auth = getAuth();
+
+    try {
+      // Verify the UID exists.
+      const user = await auth.getUser(uid);
+      log.info(
+        `Found user: ${user.uid} (created ${user.metadata.creationTime})`,
+      );
+
+      // Set the custom claim.
+      await auth.setCustomUserClaims(uid, { pro: true });
+      log.success(`Set pro: true custom claim on UID ${uid}`);
+      log.info(
+        "The user must re-open the app (or force-refresh their token) for this to take effect.",
+      );
+    } catch (e) {
+      log.error(`Failed to set custom claims: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("remove-pro <uid>")
+  .description("Revoke permanent Pro access from a Firebase Auth UID")
+  .action(async (uid) => {
+    initFirebase();
+
+    const { getAuth } = await import("firebase-admin/auth");
+    const auth = getAuth();
+
+    try {
+      await auth.setCustomUserClaims(uid, { pro: false });
+      log.success(`Removed pro claim from UID ${uid}`);
+    } catch (e) {
+      log.error(`Failed to remove custom claims: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/src/firebase.js

@@ -1,5 +1,6 @@
 import { initializeApp, cert } from "firebase-admin/app";
 import { getFirestore, FieldValue, Timestamp } from "firebase-admin/firestore";
+import { getMessaging as _getMessaging } from "firebase-admin/messaging";
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
@@ -43,4 +44,8 @@ export function getDb() {
   return db;
 }
 
+export function getMessaging() {
+  return _getMessaging();
+}
+
 export { FieldValue, Timestamp };

package/src/notifications.js

@@ -0,0 +1,202 @@
+// Forge Remote Relay — Push Notification Module
+// Copyright (c) 2025-2026 Iron Forge Apps
+// Created by Daniel Wendel, CEO/Founder of Iron Forge Apps
+
+import { getDb, getMessaging } from "./firebase.js";
+import * as log from "./logger.js";
+
+// ---------------------------------------------------------------------------
+// FCM token retrieval
+// ---------------------------------------------------------------------------
+
+/**
+ * Read all FCM tokens for a desktop from Firestore.
+ * Tokens are stored at: desktops/{desktopId}/fcmTokens/{platform}
+ * Returns an array of { token, platform, docRef } objects.
+ */
+async function getFcmTokens(desktopId) {
+  const db = getDb();
+  const snap = await db
+    .collection("desktops")
+    .doc(desktopId)
+    .collection("fcmTokens")
+    .get();
+
+  return snap.docs.map((doc) => ({
+    token: doc.data().token,
+    platform: doc.id,
+    docRef: doc.ref,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Core send function
+// ---------------------------------------------------------------------------
+
+/**
+ * Send a push notification to all devices registered for a desktop.
+ * Uses FCM HTTP v1 API via Firebase Admin SDK.
+ *
+ * @param {string} desktopId - Desktop document ID
+ * @param {object} notification - { title, body }
+ * @param {object} data - Custom data payload (all values must be strings)
+ */
+async function sendPushNotification(desktopId, notification, data = {}) {
+  let tokens;
+  try {
+    tokens = await getFcmTokens(desktopId);
+  } catch (e) {
+    log.warn(
+      `[notifications] Failed to read FCM tokens for ${desktopId}: ${e.message}`,
+    );
+    return;
+  }
+
+  if (tokens.length === 0) return;
+
+  const messaging = getMessaging();
+
+  for (const { token, platform, docRef } of tokens) {
+    try {
+      await messaging.send({
+        token,
+        notification,
+        data,
+        // Use high priority for permission requests on Android.
+        android: {
+          priority: data.type === "permission_request" ? "high" : "normal",
+          notification: {
+            channelId:
+              data.type === "permission_request"
+                ? "permissions_channel"
+                : "sessions_channel",
+          },
+        },
+        apns: {
+          payload: {
+            aps: {
+              alert: notification,
+              sound: "default",
+              // Use critical alert priority for permission requests.
+              ...(data.type === "permission_request" && {
+                "interruption-level": "time-sensitive",
+              }),
+            },
+          },
+        },
+      });
+    } catch (e) {
+      const code = e.code || "";
+      // Clean up invalid/expired tokens.
+      if (
+        code === "messaging/registration-token-not-registered" ||
+        code === "messaging/invalid-registration-token"
+      ) {
+        log.warn(
+          `[notifications] Removing stale FCM token for ${platform}: ${code}`,
+        );
+        try {
+          await docRef.delete();
+        } catch {
+          // Best-effort cleanup.
+        }
+      } else {
+        log.warn(`[notifications] Failed to send to ${platform}: ${e.message}`);
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Convenience methods — called from session-manager.js
+// ---------------------------------------------------------------------------
+
+/**
+ * Notify mobile that a permission request needs approval.
+ */
+export async function notifyPermissionRequest(
+  desktopId,
+  sessionId,
+  { toolName, commandPreview, projectName },
+) {
+  await sendPushNotification(
+    desktopId,
+    {
+      title: "Permission Needed",
+      body: `${toolName}: ${commandPreview}`.slice(0, 200),
+    },
+    {
+      type: "permission_request",
+      sessionId,
+      toolName: toolName || "",
+      commandPreview: (commandPreview || "").slice(0, 200),
+      projectName: projectName || "",
+    },
+  );
+}
+
+/**
+ * Notify mobile that a session completed successfully.
+ */
+export async function notifySessionComplete(
+  desktopId,
+  sessionId,
+  { projectName },
+) {
+  await sendPushNotification(
+    desktopId,
+    {
+      title: "Task Complete",
+      body: `${projectName}: Claude finished the task`,
+    },
+    {
+      type: "session_complete",
+      sessionId,
+      projectName: projectName || "",
+    },
+  );
+}
+
+/**
+ * Notify mobile that a session encountered an error.
+ */
+export async function notifySessionError(
+  desktopId,
+  sessionId,
+  { projectName, errorMessage },
+) {
+  await sendPushNotification(
+    desktopId,
+    {
+      title: "Session Error",
+      body: `${projectName}: ${errorMessage || "An error occurred"}`.slice(
+        0,
+        200,
+      ),
+    },
+    {
+      type: "session_error",
+      sessionId,
+      projectName: projectName || "",
+      errorMessage: (errorMessage || "").slice(0, 200),
+    },
+  );
+}
+
+/**
+ * Notify mobile that Claude is waiting for input.
+ */
+export async function notifySessionIdle(desktopId, sessionId, { projectName }) {
+  await sendPushNotification(
+    desktopId,
+    {
+      title: "Claude is Waiting",
+      body: `${projectName}: Claude needs your input`,
+    },
+    {
+      type: "session_idle",
+      sessionId,
+      projectName: projectName || "",
+    },
+  );
+}

package/src/session-manager.js

@@ -15,6 +15,13 @@ import {
   stopCapturing,
   hasActiveSimulator,
 } from "./screenshot-manager.js";
+import { postToSlack } from "./webhook-server.js";
+import {
+  notifyPermissionRequest,
+  notifySessionComplete,
+  notifySessionError,
+  notifySessionIdle,
+} from "./notifications.js";
 
 // ---------------------------------------------------------------------------
 // Resolve the user's shell environment so spawned processes inherit PATH,
@@ -153,10 +160,15 @@ const activeSessions = new Map();
  */
 const MAX_SESSIONS = parseInt(process.env.FORGE_MAX_SESSIONS, 10) || 3;
 
+/**
+ * Maximum concurrent sessions allowed via webhook triggers.
+ */
+export const MAX_WEBHOOK_SESSIONS = 5;
+
 /**
  * Returns the count of real sessions (excluding command-watcher sentinel keys).
  */
-function getActiveSessionCount() {
+export function getActiveSessionCount() {
   let count = 0;
   for (const key of activeSessions.keys()) {
     if (!key.startsWith("cmd-watcher-")) count++;
@@ -458,7 +470,7 @@ export async function startNewSession(desktopId, payload) {
     );
   }
 
-  const { prompt, projectPath, model } = payload || {};
+  const { prompt, projectPath, model, webhookMeta } = payload || {};
   const db = getDb();
   const resolvedModel = model || "sonnet";
   const resolvedPath = projectPath || process.cwd();
@@ -503,6 +515,7 @@ export async function startNewSession(desktopId, payload) {
     process: null,
     desktopId,
     projectPath: resolvedPath,
+    projectName,
     model: resolvedModel,
     startTime: Date.now(),
     messageCount: 0,
@@ -511,6 +524,8 @@ export async function startNewSession(desktopId, payload) {
     lastToolCall: null, // Last tool_use block (for permission requests)
     permissionNeeded: false, // True when Claude reports permission denial
     permissionWatcher: null, // Firestore unsubscribe for permission doc
+    webhookMeta: webhookMeta || null, // Webhook metadata for reply callbacks
+    lastAssistantText: "", // Last assistant message text (for webhook replies)
   });
 
   // Desktop terminal banner.
@@ -705,6 +720,13 @@ async function runClaudeProcess(sessionId, prompt) {
           "Process timed out — no output received. Claude CLI may need re-authentication or the model may be unavailable.",
       });
 
+      // Push notification for timeout error.
+      const timeoutSess = activeSessions.get(sessionId);
+      notifySessionError(timeoutSess?.desktopId || desktopId, sessionId, {
+        projectName: timeoutSess?.projectName || "Unknown",
+        errorMessage: "Process timed out — no output received",
+      }).catch(() => {});
+
       await db
         .collection("sessions")
         .doc(sessionId)
@@ -862,6 +884,17 @@ async function runClaudeProcess(sessionId, prompt) {
           lastActivity: FieldValue.serverTimestamp(),
         });
         watchPermissionDecision(sessionId, permDocId);
+
+        // Push notification for permission request.
+        notifyPermissionRequest(sess.desktopId, sessionId, {
+          toolName: toolForPermission.name || "Unknown tool",
+          commandPreview:
+            toolForPermission.input?.command ||
+            toolForPermission.input?.content ||
+            JSON.stringify(toolForPermission.input || {}).slice(0, 200),
+          projectName: sess.projectName || "Unknown",
+        }).catch(() => {});
+
         log.session(
           sessionId,
           "Permission needed — waiting for mobile approval",
@@ -884,6 +917,19 @@ async function runClaudeProcess(sessionId, prompt) {
             timestamp: FieldValue.serverTimestamp(),
           });
 
+        // Push notification for idle.
+        notifySessionIdle(sess.desktopId, sessionId, {
+          projectName: sess.projectName || "Unknown",
+        }).catch(() => {});
+
+        // If this session was triggered by a webhook with a reply URL,
+        // post Claude's last response back to the source (e.g., Slack).
+        if (sess?.webhookMeta?.replyUrl && sess.lastAssistantText) {
+          postToSlack(sess.webhookMeta.replyUrl, sess.lastAssistantText).catch(
+            () => {},
+          );
+        }
+
         log.session(
           sessionId,
           "Turn complete — session idle, waiting for input",
@@ -917,6 +963,12 @@ async function runClaudeProcess(sessionId, prompt) {
           timestamp: FieldValue.serverTimestamp(),
         });
 
+      // Push notification for error.
+      notifySessionError(sess?.desktopId || desktopId, sessionId, {
+        projectName: sess?.projectName || "Unknown",
+        errorMessage: `Process exited with code ${code}`,
+      }).catch(() => {});
+
       log.sessionEnded({
         sessionId,
         status: "error",
@@ -938,6 +990,12 @@ async function runClaudeProcess(sessionId, prompt) {
       errorMessage: `Failed to start: ${err.message}`,
     });
 
+    // Push notification for spawn error.
+    notifySessionError(sess?.desktopId || desktopId, sessionId, {
+      projectName: sess?.projectName || "Unknown",
+      errorMessage: `Failed to start: ${err.message}`,
+    }).catch(() => {});
+
     await db
       .collection("sessions")
       .doc(sessionId)
@@ -1005,6 +1063,13 @@ async function stopSession(sessionId) {
       timestamp: FieldValue.serverTimestamp(),
     });
 
+  // Push notification for session completion.
+  if (session?.desktopId) {
+    notifySessionComplete(session.desktopId, sessionId, {
+      projectName: session.projectName || "Unknown",
+    }).catch(() => {});
+  }
+
   log.sessionEnded({
     sessionId,
     status: "completed",
@@ -1263,7 +1328,10 @@ const PERMISSION_PATTERNS = [
 async function storeAssistantMessage(sessionId, text) {
   const db = getDb();
   const session = activeSessions.get(sessionId);
-  if (session) session.messageCount = (session.messageCount || 0) + 1;
+  if (session) {
+    session.messageCount = (session.messageCount || 0) + 1;
+    session.lastAssistantText = text; // Track for webhook reply callbacks
+  }
 
   await db.collection("sessions").doc(sessionId).collection("messages").add({
     type: "assistant",

package/src/update-checker.js

@@ -0,0 +1,72 @@
+/**
+ * Checks npm registry for newer versions and warns the user.
+ *
+ * Runs non-blocking — never delays startup if the check fails or times out.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import * as log from "./logger.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Read the local package version from package.json. */
+function getLocalVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(__dirname, "..", "package.json"), "utf-8"),
+    );
+    return pkg.version;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compare two semver strings. Returns true if remote is newer than local.
+ */
+function isNewer(local, remote) {
+  const parse = (v) => v.split(".").map(Number);
+  const [lMaj, lMin, lPat] = parse(local);
+  const [rMaj, rMin, rPat] = parse(remote);
+  if (rMaj !== lMaj) return rMaj > lMaj;
+  if (rMin !== lMin) return rMin > lMin;
+  return rPat > lPat;
+}
+
+/**
+ * Check npm for a newer version. Logs a warning if one is found.
+ * Never throws — silently returns on any failure.
+ */
+export async function checkForUpdate() {
+  const localVersion = getLocalVersion();
+  if (!localVersion) return;
+
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+
+    const res = await fetch("https://registry.npmjs.org/forge-remote/latest", {
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+
+    if (!res.ok) return;
+
+    const data = await res.json();
+    const remoteVersion = data.version;
+
+    if (remoteVersion && isNewer(localVersion, remoteVersion)) {
+      console.log();
+      log.warn(
+        `A new version of forge-remote is available: ${localVersion} → ${remoteVersion}`,
+      );
+      log.warn("  Run:  npm update -g forge-remote");
+      log.warn("  Then: forge-remote init    (to update Firestore rules)");
+      console.log();
+    }
+  } catch {
+    // Network error, timeout, etc. — don't bother the user.
+  }
+}

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);
+}

package/src/webhook-watcher.js

@@ -0,0 +1,111 @@
+// Forge Remote Relay — Webhook Config Watcher
+// Copyright (c) 2025-2026 Iron Forge Apps
+// Created by Daniel Wendel, CEO/Founder of Iron Forge Apps
+
+import { getDb } from "./firebase.js";
+import * as log from "./logger.js";
+
+/**
+ * In-memory cache of webhook configurations.
+ * Map<webhookId, config>
+ */
+const webhookConfigs = new Map();
+
+/** Firestore unsubscribe function. */
+let unsubscribe = null;
+
+/**
+ * Watch Firestore for webhook config changes and maintain an in-memory cache.
+ *
+ * @param {string} desktopId
+ * @param {string} tunnelBaseUrl — Public tunnel URL to build webhook URLs from
+ */
+export function watchWebhookConfigs(desktopId, tunnelBaseUrl) {
+  const db = getDb();
+  const webhooksRef = db
+    .collection("desktops")
+    .doc(desktopId)
+    .collection("webhooks");
+
+  unsubscribe = webhooksRef.onSnapshot(
+    (snap) => {
+      for (const change of snap.docChanges()) {
+        const id = change.doc.id;
+        const data = change.doc.data();
+
+        if (change.type === "removed") {
+          webhookConfigs.delete(id);
+          log.info(`Webhook removed: ${id}`);
+          continue;
+        }
+
+        // added or modified
+        webhookConfigs.set(id, data);
+
+        if (change.type === "added") {
+          log.info(
+            `Webhook registered: ${id} (source: ${data.source || "custom"}, enabled: ${data.enabled !== false})`,
+          );
+        } else {
+          log.info(`Webhook updated: ${id}`);
+        }
+
+        // If the webhook doc doesn't have a webhookUrl yet, write it back.
+        if (!data.webhookUrl) {
+          const webhookUrl = `${tunnelBaseUrl}/hooks/${id}`;
+          webhooksRef
+            .doc(id)
+            .update({ webhookUrl })
+            .then(() => {
+              log.info(`Wrote webhook URL for ${id}: ${webhookUrl}`);
+            })
+            .catch((err) => {
+              log.error(
+                `Failed to write webhook URL for ${id}: ${err.message}`,
+              );
+            });
+        }
+      }
+    },
+    (err) => {
+      log.error(`Webhook watcher error: ${err.message}`);
+    },
+  );
+
+  log.info(`Watching webhook configs for desktop ${desktopId}`);
+}
+
+/**
+ * Get a webhook config from the in-memory cache.
+ *
+ * @param {string} webhookId
+ * @returns {object|null}
+ */
+export function getWebhookConfig(webhookId) {
+  return webhookConfigs.get(webhookId) || null;
+}
+
+/**
+ * Get the count of enabled webhooks.
+ *
+ * @returns {number}
+ */
+export function getActiveWebhookCount() {
+  let count = 0;
+  for (const config of webhookConfigs.values()) {
+    if (config.enabled !== false) count++;
+  }
+  return count;
+}
+
+/**
+ * Stop watching Firestore for webhook changes.
+ */
+export function stopWatching() {
+  if (unsubscribe) {
+    unsubscribe();
+    unsubscribe = null;
+    log.info("Stopped watching webhook configs");
+  }
+  webhookConfigs.clear();
+}