@sinch/functions-runtime 0.4.1 → 0.4.3

package/dist/index.d.ts

@@ -1006,6 +1006,35 @@ export interface FunctionContext {
 	/** Read a file from the assets/ directory (private, not served over HTTP) */
 	assets(filename: string): Promise<string>;
 }
+/**
+ * WebSocket handler callback
+ */
+export type WebSocketHandler = (ws: import("ws").WebSocket, req: import("http").IncomingMessage) => void;
+/**
+ * Runtime configuration object passed to the optional `setup()` export.
+ *
+ * Provides hooks for startup initialization and WebSocket endpoints
+ * without exposing the raw Express app or HTTP server.
+ *
+ * @example
+ * ```typescript
+ * export function setup(runtime: SinchRuntime) {
+ *   runtime.onStartup(async (context) => {
+ *     // Initialize database, warm caches, etc.
+ *   });
+ *
+ *   runtime.onWebSocket('/stream', (ws, req) => {
+ *     // Handle Sinch connectStream binary audio
+ *   });
+ * }
+ * ```
+ */
+export interface SinchRuntime {
+	/** Register a callback to run once at startup, before the server accepts requests. */
+	onStartup(handler: (context: FunctionContext) => Promise<void> | void): void;
+	/** Register a WebSocket upgrade handler at the given path. */
+	onWebSocket(path: string, handler: WebSocketHandler): void;
+}
 /**
  * Application credentials structure
  */
@@ -1455,6 +1484,7 @@ export interface SinchClients {
 	sms?: SmsService;
 	numbers?: NumbersService;
 	validateWebhookSignature?: (requestData: WebhookRequestData) => boolean;
+	validateConversationWebhook?: (headers: Record<string, string | string[] | undefined>, body: unknown) => boolean;
 }
 export interface WebhookRequestData {
 	method: string;
@@ -2420,6 +2450,12 @@ export declare class TunnelClient {
 	private generateTunnelId;
 	connect(): Promise<void>;
 	private handleMessage;
+	/**
+	 * Build a full tunnel URL with optional sub-path and tunnel query param.
+	 * e.g. buildTunnelUrl('/webhook/conversation') →
+	 *   https://tunnel.fn.sinch.com/ingress/webhook/conversation?tunnel=01KKT...
+	 */
+	private buildTunnelUrl;
 	private handleWelcomeMessage;
 	private handleRequest;
 	private sendPong;

package/dist/index.js

@@ -959,6 +959,122 @@ function validateBasicAuth(authHeader, expectedKey, expectedSecret) {
   return keyMatch && secretMatch;
 }
 
+// ../runtime-shared/dist/security/index.js
+function shouldValidateWebhook(mode, isDevelopment) {
+  const normalizedMode = (mode || "deploy").toLowerCase();
+  switch (normalizedMode) {
+    case "never":
+      return false;
+    case "always":
+      return true;
+    case "deploy":
+    default:
+      return !isDevelopment;
+  }
+}
+var VALID_MODES = ["never", "deploy", "always"];
+function getProtectionMode(config) {
+  const envValue = process.env.WEBHOOK_PROTECTION ?? process.env.PROTECT_VOICE_CALLBACKS;
+  if (envValue) {
+    const normalized = envValue.toLowerCase();
+    if (VALID_MODES.includes(normalized)) {
+      return normalized;
+    }
+    console.warn(`[SECURITY] Unknown WEBHOOK_PROTECTION value "${envValue}", defaulting to "deploy"`);
+    return "deploy";
+  }
+  const configValue = config?.WebhookProtection ?? config?.webhookProtection ?? config?.ProtectVoiceCallbacks ?? config?.protectVoiceCallbacks;
+  if (typeof configValue === "string") {
+    const normalized = configValue.toLowerCase();
+    if (VALID_MODES.includes(normalized)) {
+      return normalized;
+    }
+    console.warn(`[SECURITY] Unknown webhook protection value "${configValue}", defaulting to "deploy"`);
+    return "deploy";
+  }
+  return "deploy";
+}
+
+// ../runtime-shared/dist/sinch/index.js
+import { SinchClient, validateAuthenticationHeader, ConversationCallbackWebhooks } from "@sinch/sdk-core";
+function createSinchClients() {
+  const clients = {};
+  const hasCredentials = process.env.PROJECT_ID && process.env.PROJECT_ID_API_KEY && process.env.PROJECT_ID_API_SECRET;
+  if (process.env.CONVERSATION_WEBHOOK_SECRET) {
+    const callbackProcessor = new ConversationCallbackWebhooks(process.env.CONVERSATION_WEBHOOK_SECRET);
+    clients.validateConversationWebhook = (headers, body) => {
+      try {
+        const result = callbackProcessor.validateAuthenticationHeader(headers, body);
+        console.log("[SINCH] Conversation webhook validation:", result ? "VALID" : "INVALID");
+        return result;
+      } catch (error) {
+        console.error("[SINCH] Conversation validation error:", error instanceof Error ? error.message : error);
+        return false;
+      }
+    };
+  }
+  if (!hasCredentials) {
+    return clients;
+  }
+  try {
+    const sinchClient = new SinchClient({
+      projectId: process.env.PROJECT_ID,
+      keyId: process.env.PROJECT_ID_API_KEY,
+      keySecret: process.env.PROJECT_ID_API_SECRET
+    });
+    if (process.env.CONVERSATION_APP_ID) {
+      clients.conversation = sinchClient.conversation;
+      console.log("[SINCH] Conversation API initialized");
+    }
+    if (process.env.VOICE_APPLICATION_KEY && process.env.VOICE_APPLICATION_SECRET) {
+      const voiceClient = new SinchClient({
+        projectId: process.env.PROJECT_ID,
+        keyId: process.env.PROJECT_ID_API_KEY,
+        keySecret: process.env.PROJECT_ID_API_SECRET,
+        applicationKey: process.env.VOICE_APPLICATION_KEY,
+        applicationSecret: process.env.VOICE_APPLICATION_SECRET
+      });
+      clients.voice = voiceClient.voice;
+      console.log("[SINCH] Voice API initialized with application credentials");
+    }
+    if (process.env.SMS_SERVICE_PLAN_ID) {
+      clients.sms = sinchClient.sms;
+      console.log("[SINCH] SMS API initialized");
+    }
+    if (process.env.ENABLE_NUMBERS_API === "true") {
+      clients.numbers = sinchClient.numbers;
+      console.log("[SINCH] Numbers API initialized");
+    }
+  } catch (error) {
+    console.error("[SINCH] Failed to initialize Sinch clients:", error.message);
+    return {};
+  }
+  if (process.env.VOICE_APPLICATION_KEY && process.env.VOICE_APPLICATION_SECRET) {
+    clients.validateWebhookSignature = (requestData) => {
+      console.log("[SINCH] Validating Voice webhook signature");
+      try {
+        const result = validateAuthenticationHeader(process.env.VOICE_APPLICATION_KEY, process.env.VOICE_APPLICATION_SECRET, requestData.headers, requestData.body, requestData.path, requestData.method);
+        console.log("[SINCH] Validation result:", result ? "VALID" : "INVALID");
+        return result;
+      } catch (error) {
+        console.error("[SINCH] Validation error:", error.message);
+        return false;
+      }
+    };
+  }
+  return clients;
+}
+var cachedClients = null;
+function getSinchClients() {
+  if (!cachedClients) {
+    cachedClients = createSinchClients();
+  }
+  return cachedClients;
+}
+function resetSinchClients() {
+  cachedClients = null;
+}
+
 // ../runtime-shared/dist/host/app.js
 import { createRequire as createRequire2 } from "module";
 import { pathToFileURL } from "url";
@@ -1159,7 +1275,7 @@ var noOpStorage = {
 };
 function buildBaseContext(req, config = {}) {
   return {
-    requestId: req.headers["x-request-id"] || generateRequestId(),
+    requestId: req?.headers?.["x-request-id"] || generateRequestId(),
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     env: process.env,
     config: {
@@ -1180,7 +1296,13 @@ function buildBaseContext(req, config = {}) {
 async function handleVoiceCallback(functionName, userFunction, context, callbackData, logger) {
   const handler = userFunction[functionName];
   if (!handler || typeof handler !== "function") {
-    throw new Error(`Function '${functionName}' not found in function.js`);
+    if (functionName === "ice") {
+      throw new Error(`Voice callback 'ice' not found \u2014 export an ice() function in function.ts`);
+    }
+    if (logger) {
+      logger(`${functionName.toUpperCase()} callback not implemented \u2014 returning 200`);
+    }
+    return { statusCode: 200, body: {}, headers: {} };
   }
   let result;
   switch (functionName) {
@@ -1223,7 +1345,9 @@ async function handleCustomEndpoint(functionName, userFunction, context, request
     handler = userFunction["home"];
   }
   if (!handler || typeof handler !== "function") {
-    throw new Error(`Function '${functionName}' not found in function.js`);
+    const available = Object.keys(userFunction).filter((k) => typeof userFunction[k] === "function");
+    const pathHint = functionName.endsWith("Webhook") ? `/webhook/${functionName.replace("Webhook", "")}` : `/${functionName}`;
+    throw new Error(`No export '${functionName}' found for path ${pathHint}. Available exports: [${available.join(", ")}]. Custom endpoints require a named export matching the last path segment.`);
   }
   const result = await handler(context, request);
   if (logger) {
@@ -1300,6 +1424,33 @@ function setupRequestHandler(app, options = {}) {
           }
         }
       }
+      const protectionMode = getProtectionMode();
+      const isDev = process.env.NODE_ENV !== "production" && process.env.ASPNETCORE_ENVIRONMENT !== "Production";
+      if (shouldValidateWebhook(protectionMode, isDev)) {
+        const sinchClients = getSinchClients();
+        if (isVoiceCallback(functionName) && sinchClients.validateWebhookSignature) {
+          const rawBody = req.rawBody ?? JSON.stringify(req.body);
+          const isValid = sinchClients.validateWebhookSignature({
+            method: req.method,
+            path: req.path,
+            headers: req.headers,
+            body: rawBody
+          });
+          if (!isValid) {
+            logger("[SECURITY] Voice webhook signature validation failed");
+            res.status(401).json({ error: "Invalid webhook signature" });
+            return;
+          }
+        }
+        if (functionName === "conversationWebhook" && sinchClients.validateConversationWebhook) {
+          const isValid = sinchClients.validateConversationWebhook(req.headers, req.body);
+          if (!isValid) {
+            logger("[SECURITY] Conversation webhook signature validation failed");
+            res.status(401).json({ error: "Invalid webhook signature" });
+            return;
+          }
+        }
+      }
       onRequestStart({ functionName, req });
       const context = buildContext(req);
       const userFunction = await Promise.resolve(loadUserFunction());
@@ -1375,73 +1526,6 @@ function setupRequestHandler(app, options = {}) {
   });
 }
 
-// ../runtime-shared/dist/sinch/index.js
-import { SinchClient, validateAuthenticationHeader } from "@sinch/sdk-core";
-function createSinchClients() {
-  const clients = {};
-  const hasCredentials = process.env.PROJECT_ID && process.env.PROJECT_ID_API_KEY && process.env.PROJECT_ID_API_SECRET;
-  if (!hasCredentials) {
-    return clients;
-  }
-  try {
-    const sinchClient = new SinchClient({
-      projectId: process.env.PROJECT_ID,
-      keyId: process.env.PROJECT_ID_API_KEY,
-      keySecret: process.env.PROJECT_ID_API_SECRET
-    });
-    if (process.env.CONVERSATION_APP_ID) {
-      clients.conversation = sinchClient.conversation;
-      console.log("[SINCH] Conversation API initialized");
-    }
-    if (process.env.VOICE_APPLICATION_KEY && process.env.VOICE_APPLICATION_SECRET) {
-      const voiceClient = new SinchClient({
-        projectId: process.env.PROJECT_ID,
-        keyId: process.env.PROJECT_ID_API_KEY,
-        keySecret: process.env.PROJECT_ID_API_SECRET,
-        applicationKey: process.env.VOICE_APPLICATION_KEY,
-        applicationSecret: process.env.VOICE_APPLICATION_SECRET
-      });
-      clients.voice = voiceClient.voice;
-      console.log("[SINCH] Voice API initialized with application credentials");
-    }
-    if (process.env.SMS_SERVICE_PLAN_ID) {
-      clients.sms = sinchClient.sms;
-      console.log("[SINCH] SMS API initialized");
-    }
-    if (process.env.ENABLE_NUMBERS_API === "true") {
-      clients.numbers = sinchClient.numbers;
-      console.log("[SINCH] Numbers API initialized");
-    }
-  } catch (error) {
-    console.error("[SINCH] Failed to initialize Sinch clients:", error.message);
-    return {};
-  }
-  if (process.env.VOICE_APPLICATION_KEY && process.env.VOICE_APPLICATION_SECRET) {
-    clients.validateWebhookSignature = (requestData) => {
-      console.log("[SINCH] Validating Voice webhook signature");
-      try {
-        const result = validateAuthenticationHeader(process.env.VOICE_APPLICATION_KEY, process.env.VOICE_APPLICATION_SECRET, requestData.headers, requestData.body, requestData.path, requestData.method);
-        console.log("[SINCH] Validation result:", result ? "VALID" : "INVALID");
-        return result;
-      } catch (error) {
-        console.error("[SINCH] Validation error:", error.message);
-        return false;
-      }
-    };
-  }
-  return clients;
-}
-var cachedClients = null;
-function getSinchClients() {
-  if (!cachedClients) {
-    cachedClients = createSinchClients();
-  }
-  return cachedClients;
-}
-function resetSinchClients() {
-  cachedClients = null;
-}
-
 // ../runtime-shared/dist/ai/elevenlabs/state.js
 var ElevenLabsStateManager = class {
   state = {
@@ -2556,6 +2640,7 @@ import axios from "axios";
 
 // src/tunnel/webhook-config.ts
 import { SinchClient as SinchClient2 } from "@sinch/sdk-core";
+import { randomBytes } from "crypto";
 var SINCH_FN_URL_PATTERN = /\.fn(-\w+)?\.sinch\.com/;
 function isOurWebhook(target) {
   return !!target && SINCH_FN_URL_PATTERN.test(target);
@@ -2563,7 +2648,7 @@ function isOurWebhook(target) {
 function isTunnelUrl(target) {
   return !!target && target.includes("tunnel.fn");
 }
-async function configureConversationWebhooks(tunnelUrl, config) {
+async function configureConversationWebhooks(webhookUrl, config) {
   try {
     const conversationAppId = process.env.CONVERSATION_APP_ID;
     const projectId = process.env.PROJECT_ID;
@@ -2573,7 +2658,6 @@ async function configureConversationWebhooks(tunnelUrl, config) {
       console.log("\u{1F4A1} Conversation API not fully configured - skipping webhook setup");
       return;
     }
-    const webhookUrl = `${tunnelUrl}/webhook/conversation`;
     console.log(`\u{1F4AC} Conversation webhook URL: ${webhookUrl}`);
     const sinchClient = new SinchClient2({
       projectId,
@@ -2593,17 +2677,22 @@ async function configureConversationWebhooks(tunnelUrl, config) {
     }
     config.conversationWebhookId = deployedWebhook.id;
     config.originalTarget = deployedWebhook.target;
+    const hmacSecret = randomBytes(32).toString("hex");
+    process.env.CONVERSATION_WEBHOOK_SECRET = hmacSecret;
+    resetSinchClients();
     await sinchClient.conversation.webhooks.update({
       webhook_id: deployedWebhook.id,
       webhookUpdateRequestBody: {
-        target: webhookUrl
+        target: webhookUrl,
+        secret: hmacSecret
       },
-      update_mask: ["target"]
+      update_mask: ["target", "secret"]
     });
     console.log(`\u2705 Updated Conversation webhook to tunnel: ${webhookUrl}`);
+    console.log("\u{1F512} HMAC secret configured for webhook signature validation");
     console.log("\u{1F4AC} Send a message to your Conversation app to test!");
   } catch (error) {
-    console.log("\u26A0\uFE0F Could not configure Conversation webhooks:", error.message);
+    console.log("\u26A0\uFE0F Could not configure Conversation webhooks:", error instanceof Error ? error.message : error);
   }
 }
 async function cleanupConversationWebhook(config) {
@@ -2640,8 +2729,10 @@ async function cleanupConversationWebhook(config) {
     console.log(`\u{1F504} Restored webhook target to: ${restoreTarget}`);
     config.conversationWebhookId = void 0;
     config.originalTarget = void 0;
+    delete process.env.CONVERSATION_WEBHOOK_SECRET;
+    resetSinchClients();
   } catch (error) {
-    console.log("\u26A0\uFE0F Could not restore Conversation webhook:", error.message);
+    console.log("\u26A0\uFE0F Could not restore Conversation webhook:", error instanceof Error ? error.message : error);
   }
 }
 async function configureElevenLabs() {
@@ -2656,7 +2747,7 @@ async function configureElevenLabs() {
     console.log("\u{1F916} ElevenLabs auto-configuration enabled");
     console.log(`   Agent ID: ${agentId}`);
   } catch (error) {
-    console.log("\u26A0\uFE0F Could not configure ElevenLabs:", error.message);
+    console.log("\u26A0\uFE0F Could not configure ElevenLabs:", error instanceof Error ? error.message : error);
   }
 }
 
@@ -2693,14 +2784,14 @@ var TunnelClient = class {
       timestampPart = ENCODING[t % 32] + timestampPart;
       t = Math.floor(t / 32);
     }
-    const randomBytes = new Uint8Array(10);
-    crypto.getRandomValues(randomBytes);
+    const randomBytes2 = new Uint8Array(10);
+    crypto.getRandomValues(randomBytes2);
     let randomPart = "";
     for (let i = 0; i < 10; i++) {
-      const byte = randomBytes[i];
+      const byte = randomBytes2[i];
       randomPart += ENCODING[byte >> 3];
       if (randomPart.length < 16) {
-        randomPart += ENCODING[(byte & 7) << 2 | (i + 1 < 10 ? randomBytes[i + 1] >> 6 : 0)];
+        randomPart += ENCODING[(byte & 7) << 2 | (i + 1 < 10 ? randomBytes2[i + 1] >> 6 : 0)];
       }
     }
     randomPart = randomPart.substring(0, 16);
@@ -2773,6 +2864,15 @@ var TunnelClient = class {
         break;
     }
   }
+  /**
+   * Build a full tunnel URL with optional sub-path and tunnel query param.
+   * e.g. buildTunnelUrl('/webhook/conversation') →
+   *   https://tunnel.fn.sinch.com/ingress/webhook/conversation?tunnel=01KKT...
+   */
+  buildTunnelUrl(path6) {
+    const base = this.tunnelUrl.replace(/\/$/, "");
+    return `${base}${path6 || ""}?tunnel=${this.tunnelId}`;
+  }
   handleWelcomeMessage(message) {
     this.tunnelId = message.tunnelId || null;
     this.tunnelUrl = message.publicUrl || null;
@@ -2783,7 +2883,11 @@ var TunnelClient = class {
     }
   }
   async handleRequest(message) {
+    const verbose = process.env.VERBOSE === "true";
     console.log(`Forwarding ${message.method} request to ${message.path}`);
+    if (verbose && message.body) {
+      console.log(`  \u2190 Request body: ${message.body.substring(0, 2e3)}`);
+    }
     try {
       const localUrl = `http://localhost:${this.localPort}${message.path}${message.query || ""}`;
       const axiosConfig = {
@@ -2816,9 +2920,15 @@ var TunnelClient = class {
         headers,
         body
       };
+      if (verbose) {
+        console.log(`  \u2192 Response ${response.status}: ${body.substring(0, 2e3)}`);
+      }
       this.ws?.send(JSON.stringify(responseMessage));
     } catch (error) {
-      console.error("Error forwarding request:", error.message);
+      console.error(`Error forwarding request: ${error.message} (${error.response?.status || "no response"})`);
+      if (verbose && error.response?.data) {
+        console.error(`  \u2192 Error body: ${typeof error.response.data === "string" ? error.response.data : JSON.stringify(error.response.data)}`.substring(0, 2e3));
+      }
       const errorResponse = {
         type: "response",
         id: message.id,
@@ -2862,7 +2972,7 @@ var TunnelClient = class {
       await this.configureVoiceWebhooks();
     }
     if (autoConfigConversation && process.env.CONVERSATION_APP_ID) {
-      await configureConversationWebhooks(this.tunnelUrl, this.webhookConfig);
+      await configureConversationWebhooks(this.buildTunnelUrl("/webhook/conversation"), this.webhookConfig);
     }
     if (process.env.ELEVENLABS_AUTO_CONFIGURE === "true") {
       await configureElevenLabs();
@@ -2889,7 +2999,7 @@ var TunnelClient = class {
           updateUrl,
           {
             url: {
-              primary: this.tunnelUrl,
+              primary: this.buildTunnelUrl(),
               fallback: null
             }
           },
@@ -2951,7 +3061,8 @@ var TunnelClient = class {
     this.isConnected = false;
   }
   getTunnelUrl() {
-    return this.tunnelUrl;
+    if (!this.tunnelUrl || !this.tunnelId) return null;
+    return this.buildTunnelUrl();
   }
   getIsConnected() {
     return this.isConnected;