@vellumai/vellum-gateway 0.7.0 → 0.7.2

package/src/telegram/send.test.ts

@@ -39,7 +39,6 @@ const baseConfig: GatewayConfig = {
   routingEntries: [],
   runtimeInitialBackoffMs: 500,
   runtimeMaxRetries: 2,
-  runtimeProxyEnabled: false,
   runtimeProxyRequireAuth: true,
   runtimeTimeoutMs: 30000,
   shutdownDrainMs: 5000,

package/src/twilio/validate-webhook.ts

@@ -1,3 +1,10 @@
+import {
+  normalizePublicBaseUrl,
+  TWILIO_CONNECT_ACTION_WEBHOOK_PATH,
+  TWILIO_STATUS_WEBHOOK_PATH,
+  TWILIO_VOICE_WEBHOOK_PATH,
+} from "@vellumai/service-contracts/twilio-ingress";
+
 import type { CredentialCache } from "../credential-cache.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
 import type { GatewayConfig } from "../config.js";
@@ -10,6 +17,7 @@ const log = getLogger("twilio-validate");
 type TwilioWebhookKind = "voice" | "status" | "connect-action" | "unknown";
 
 type SignatureUrlCandidateSource =
+  | "platform_proxy"
   | "configured_ingress"
   | "forwarded_headers"
   | "raw_request";
@@ -28,15 +36,15 @@ function firstHeaderValue(value: string | null): string | undefined {
 function inferWebhookKind(reqUrl: string): TwilioWebhookKind {
   const pathname = new URL(reqUrl).pathname;
 
-  if (pathname === "/webhooks/twilio/voice") {
+  if (pathname === TWILIO_VOICE_WEBHOOK_PATH) {
     return "voice";
   }
 
-  if (pathname === "/webhooks/twilio/status") {
+  if (pathname === TWILIO_STATUS_WEBHOOK_PATH) {
     return "status";
   }
 
-  if (pathname === "/webhooks/twilio/connect-action") {
+  if (pathname === TWILIO_CONNECT_ACTION_WEBHOOK_PATH) {
     return "connect-action";
   }
 
@@ -80,11 +88,20 @@ function buildSignatureUrlCandidateDetails(
     source: SignatureUrlCandidateSource,
   ): void => {
     if (!base) return;
-    const normalized = base.trim().replace(/\/+$/, "");
+    const normalized = normalizePublicBaseUrl(base);
     if (!normalized) return;
     addCandidate(`${normalized}${pathAndQuery}`, source);
   };
 
+  // Platform callback proxy injects the original public URL that the
+  // provider signed against. Use it as-is (not base + path) since the
+  // platform path includes the /v1/gateway/callbacks/{id}/ prefix that
+  // the gateway never sees.
+  addCandidate(
+    req.headers.get("x-vellum-ingress-url") ?? undefined,
+    "platform_proxy",
+  );
+
   addBase(resolved.ingressUrl, "configured_ingress");
 
   const forwardedProto =
@@ -173,6 +190,22 @@ export type TwilioValidationCaches = {
   configFile?: ConfigFileCache;
 };
 
+function readConfiguredIngressUrl(
+  configFile: ConfigFileCache | undefined,
+): string | undefined {
+  if (!configFile) return undefined;
+  return configFile.getString("ingress", "publicBaseUrl");
+}
+
+function isPublicIngressDisabled(
+  configFile: ConfigFileCache | undefined,
+): boolean {
+  if (!configFile || typeof configFile.getBoolean !== "function") {
+    return false;
+  }
+  return configFile.getBoolean("ingress", "enabled", { force: true }) === false;
+}
+
 /**
  * Validate an incoming Twilio webhook request:
  * - Enforces POST method
@@ -201,15 +234,21 @@ export async function validateTwilioWebhookRequest(
     return Response.json({ error: "Payload too large" }, { status: 413 });
   }
 
+  if (isPublicIngressDisabled(caches?.configFile)) {
+    log.warn(
+      { webhookKind: inferWebhookKind(req.url) },
+      "Twilio webhook rejected because public ingress is disabled",
+    );
+    return Response.json({ error: "Forbidden" }, { status: 403 });
+  }
+
   // Resolve the auth token from cache
   let authToken = caches?.credentials
     ? await caches.credentials.get(credentialKey("twilio", "auth_token"))
     : undefined;
 
   // Resolve ingress URL from cache
-  let ingressUrl = caches?.configFile
-    ? caches.configFile.getString("ingress", "publicBaseUrl")
-    : undefined;
+  let ingressUrl = readConfiguredIngressUrl(caches?.configFile);
 
   let resolved: ResolvedValidationContext = { authToken, ingressUrl };
 
@@ -228,10 +267,7 @@ export async function validateTwilioWebhookRequest(
       let freshIngressUrl = ingressUrl;
       if (caches.configFile) {
         caches.configFile.refreshNow();
-        freshIngressUrl = caches.configFile.getString(
-          "ingress",
-          "publicBaseUrl",
-        );
+        freshIngressUrl = readConfiguredIngressUrl(caches.configFile);
       }
       authToken = freshAuthToken;
       ingressUrl = freshIngressUrl;
@@ -300,7 +336,7 @@ export async function validateTwilioWebhookRequest(
     let freshIngressUrl: string | undefined;
     if (caches.configFile) {
       caches.configFile.refreshNow();
-      freshIngressUrl = caches.configFile.getString("ingress", "publicBaseUrl");
+      freshIngressUrl = readConfiguredIngressUrl(caches.configFile);
     }
 
     const retryAuthToken = freshAuthToken;
@@ -325,9 +361,12 @@ export async function validateTwilioWebhookRequest(
 
       if (validatingIndex !== -1) {
         log.info(
-          "Twilio webhook signature validated after forced credential refresh",
+          "Twilio webhook signature validated after forced cache refresh",
         );
         // Update references for the success log below
+        ingressUrl = retryIngressUrl;
+        validationLogContext = retryDiagnostics.logContext;
+        signatureUrlCandidates = retryDiagnostics.signatureUrlCandidates;
         signatureCandidateUrls = retryCandidateUrls;
       }
     }
@@ -351,7 +390,7 @@ export async function validateTwilioWebhookRequest(
     validatedCandidateUrl: normalizeUrlForLog(validatingCandidate.url),
   };
 
-  // When ingressPublicBaseUrl is configured and the signature only validated
+  // When a configured ingress URL is present and the signature only validated
   // against the raw local URL (last candidate), log a warning. This indicates
   // a likely drift between the configured ingress URL and the actual webhook
   // registration — the ingress URL should match what Twilio is signing against.

package/src/twilio/webhook-sync-trigger.ts

@@ -0,0 +1,58 @@
+import type { ConfigChangeEvent } from "../config-file-watcher.js";
+
+const PUBLIC_BASE_URL_FIELD = "publicBaseUrl";
+const PUBLIC_BASE_URL_MANAGED_BY_FIELD = "publicBaseUrlManagedBy";
+const TWILIO_PHONE_NUMBER_FIELD = "phoneNumber";
+const TWILIO_ACCOUNT_SID_FIELD = "accountSid";
+
+/**
+ * Returns true when the only config change is a Velay-managed publicBaseUrl
+ * update. Callers use this to skip side effects that shouldn't fire for
+ * Velay-only ingress updates (e.g. Telegram webhook re-registration).
+ */
+export function isOnlyVelayPublicBaseUrlChange(
+  event: ConfigChangeEvent,
+): boolean {
+  if (event.changedKeys.size !== 1 || !event.changedKeys.has("ingress")) {
+    return false;
+  }
+
+  const ingressFields = event.changedFields.get("ingress");
+  if (!ingressFields || ingressFields.size === 0) {
+    return false;
+  }
+
+  // A Velay-managed update always touches publicBaseUrlManagedBy. If only
+  // publicBaseUrl changed (without the manager marker), treat it as a
+  // user-initiated change that should trigger downstream side effects.
+  if (!ingressFields.has(PUBLIC_BASE_URL_MANAGED_BY_FIELD)) {
+    return false;
+  }
+
+  return [...ingressFields].every(
+    (field) =>
+      field === PUBLIC_BASE_URL_FIELD ||
+      field === PUBLIC_BASE_URL_MANAGED_BY_FIELD,
+  );
+}
+
+export function shouldSyncTwilioPhoneWebhooksAfterConfigChange(
+  event: ConfigChangeEvent,
+): boolean {
+  if (event.changedKeys.has("ingress")) {
+    const ingressFields = event.changedFields.get("ingress");
+    if (ingressFields?.has(PUBLIC_BASE_URL_FIELD) === true) {
+      return true;
+    }
+  }
+
+  if (!event.changedKeys.has("twilio")) {
+    return false;
+  }
+
+  const twilioFields = event.changedFields.get("twilio");
+  return (
+    twilioFields?.has(TWILIO_PHONE_NUMBER_FIELD) === true ||
+    twilioFields?.has(TWILIO_ACCOUNT_SID_FIELD) === true
+  );
+}

package/src/twilio/webhook-sync.test.ts

@@ -0,0 +1,286 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+import type { ConfigFileCache } from "../config-file-cache.js";
+import type { CredentialCache } from "../credential-cache.js";
+import { credentialKey } from "../credential-key.js";
+const ACCOUNT_SID = "AC123";
+const AUTH_TOKEN = "auth-token";
+const PHONE_NUMBER = "+15550100";
+const PHONE_NUMBER_SID = "PN123";
+
+type FetchFn = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+interface MockedResponse {
+  body?: unknown;
+  status: number;
+}
+
+interface MockFetchEntry {
+  init: Partial<RequestInit>;
+  path: string;
+  response: MockedResponse | Response;
+}
+
+const mockFetchEntries: MockFetchEntry[] = [];
+const mockFetchCalls: { init: RequestInit; path: string }[] = [];
+let fetchImpl: ReturnType<typeof mock<FetchFn>> = mockFetchImpl();
+
+mock.module("../fetch.js", () => ({
+  fetchImpl: (...args: Parameters<FetchFn>) => fetchImpl(...args),
+}));
+
+const { syncConfiguredTwilioPhoneNumberWebhooks } =
+  await import("./webhook-sync.js");
+
+afterEach(() => {
+  resetMockFetch();
+});
+
+function makeCaches(opts: {
+  phoneNumber?: string;
+  accountSid?: string;
+  accountSidCredential?: string;
+  authToken?: string;
+  ingressEnabled?: boolean;
+  publicBaseUrl?: string;
+}): { credentials: CredentialCache; configFile: ConfigFileCache } {
+  const credentialValues = new Map<string, string | undefined>([
+    [credentialKey("twilio", "account_sid"), opts.accountSidCredential],
+    [credentialKey("twilio", "auth_token"), opts.authToken],
+  ]);
+  const configValues: Record<string, Record<string, string | undefined>> = {
+    twilio: {
+      phoneNumber: opts.phoneNumber,
+      accountSid: opts.accountSid,
+    },
+    ingress: {
+      publicBaseUrl: opts.publicBaseUrl,
+    },
+  };
+
+  return {
+    credentials: {
+      get: async (key: string) => credentialValues.get(key),
+      invalidate: () => {},
+    } as unknown as CredentialCache,
+    configFile: {
+      getString: (section: string, key: string) =>
+        configValues[section]?.[key] ?? undefined,
+      getBoolean: (section: string, key: string) => {
+        if (section === "ingress" && key === "enabled") {
+          return opts.ingressEnabled;
+        }
+        return undefined;
+      },
+      invalidate: () => {},
+    } as unknown as ConfigFileCache,
+  };
+}
+
+function mockFetchImpl(): ReturnType<typeof mock<FetchFn>> {
+  return mock(
+    async (input: string | URL | Request, actualInit?: RequestInit) => {
+      const url = String(input);
+      mockFetchCalls.push({ path: url, init: actualInit ?? {} });
+
+      const idx = mockFetchEntries.findIndex((entry) => {
+        if (!url.includes(entry.path)) return false;
+        for (const [key, value] of Object.entries(entry.init)) {
+          const actualValue = (
+            actualInit as Record<string, unknown> | undefined
+          )?.[key];
+          if (actualValue !== value) {
+            return false;
+          }
+        }
+        return true;
+      });
+
+      if (idx === -1) {
+        return new Response(JSON.stringify({ detail: "No mock matched" }), {
+          status: 500,
+        });
+      }
+
+      const entry = mockFetchEntries[idx];
+      mockFetchEntries.splice(idx, 1);
+
+      if (entry.response instanceof Response) {
+        return entry.response;
+      }
+
+      return new Response(JSON.stringify(entry.response.body ?? null), {
+        status: entry.response.status,
+        headers: { "Content-Type": "application/json" },
+      });
+    },
+  );
+}
+
+function mockFetch(
+  path: string,
+  init: Partial<RequestInit>,
+  response: MockedResponse | Response,
+): void {
+  mockFetchEntries.push({ path, init, response });
+}
+
+function getMockFetchCalls(): { init: RequestInit; path: string }[] {
+  return mockFetchCalls;
+}
+
+function resetMockFetch(): void {
+  mockFetchEntries.length = 0;
+  mockFetchCalls.length = 0;
+  fetchImpl = mockFetchImpl();
+}
+
+function mockTwilioLookupAndUpdate(): void {
+  mockFetch(
+    `/Accounts/${ACCOUNT_SID}/IncomingPhoneNumbers.json?PhoneNumber=${encodeURIComponent(
+      PHONE_NUMBER,
+    )}`,
+    { method: "GET" },
+    {
+      status: 200,
+      body: {
+        incoming_phone_numbers: [
+          { sid: PHONE_NUMBER_SID, phone_number: PHONE_NUMBER },
+        ],
+      },
+    },
+  );
+  mockFetch(
+    `/Accounts/${ACCOUNT_SID}/IncomingPhoneNumbers/${PHONE_NUMBER_SID}.json`,
+    { method: "POST" },
+    { status: 200, body: {} },
+  );
+}
+
+describe("syncConfiguredTwilioPhoneNumberWebhooks", () => {
+  test("syncs phone webhooks to publicBaseUrl when configured", async () => {
+    mockTwilioLookupAndUpdate();
+
+    await syncConfiguredTwilioPhoneNumberWebhooks(
+      makeCaches({
+        phoneNumber: PHONE_NUMBER,
+        accountSid: ACCOUNT_SID,
+        authToken: AUTH_TOKEN,
+        publicBaseUrl: " https://velay.example.test/twilio/ ",
+      }),
+    );
+
+    const calls = getMockFetchCalls();
+    expect(calls).toHaveLength(2);
+    const body = new URLSearchParams(String(calls[1].init.body));
+    expect(body.get("VoiceUrl")).toBe(
+      "https://velay.example.test/twilio/webhooks/twilio/voice",
+    );
+    expect(body.get("VoiceMethod")).toBe("POST");
+    expect(body.get("StatusCallback")).toBe(
+      "https://velay.example.test/twilio/webhooks/twilio/status",
+    );
+    expect(body.get("StatusCallbackMethod")).toBe("POST");
+    expect(calls[1].init.headers).toEqual({
+      Authorization:
+        "Basic " +
+        Buffer.from(`${ACCOUNT_SID}:${AUTH_TOKEN}`).toString("base64"),
+      "Content-Type": "application/x-www-form-urlencoded",
+    });
+  });
+
+  test("syncs phone webhooks using publicBaseUrl", async () => {
+    mockTwilioLookupAndUpdate();
+
+    await syncConfiguredTwilioPhoneNumberWebhooks(
+      makeCaches({
+        phoneNumber: PHONE_NUMBER,
+        accountSid: ACCOUNT_SID,
+        authToken: AUTH_TOKEN,
+        publicBaseUrl: "https://generic.example.test/",
+      }),
+    );
+
+    const calls = getMockFetchCalls();
+    expect(calls).toHaveLength(2);
+    const body = new URLSearchParams(String(calls[1].init.body));
+    expect(body.get("VoiceUrl")).toBe(
+      "https://generic.example.test/webhooks/twilio/voice",
+    );
+    expect(body.get("StatusCallback")).toBe(
+      "https://generic.example.test/webhooks/twilio/status",
+    );
+  });
+
+  test("uses credential-store account SID before legacy config fallback", async () => {
+    mockTwilioLookupAndUpdate();
+
+    await syncConfiguredTwilioPhoneNumberWebhooks(
+      makeCaches({
+        phoneNumber: PHONE_NUMBER,
+        accountSid: "AC_CONFIG_STALE",
+        accountSidCredential: ACCOUNT_SID,
+        authToken: AUTH_TOKEN,
+        publicBaseUrl: "https://generic.example.test/",
+      }),
+    );
+
+    const calls = getMockFetchCalls();
+    expect(calls).toHaveLength(2);
+    expect(calls[0].path).toContain(`/Accounts/${ACCOUNT_SID}/`);
+    expect(calls[1].path).toContain(`/Accounts/${ACCOUNT_SID}/`);
+  });
+
+  test("skips without Twilio REST calls when required inputs are missing", async () => {
+    await syncConfiguredTwilioPhoneNumberWebhooks(
+      makeCaches({
+        phoneNumber: PHONE_NUMBER,
+        accountSid: ACCOUNT_SID,
+        authToken: undefined,
+        publicBaseUrl: "https://generic.example.test",
+      }),
+    );
+
+    expect(getMockFetchCalls()).toEqual([]);
+  });
+
+  test("skips without Twilio REST calls when public ingress is disabled", async () => {
+    await syncConfiguredTwilioPhoneNumberWebhooks(
+      makeCaches({
+        phoneNumber: PHONE_NUMBER,
+        accountSid: ACCOUNT_SID,
+        authToken: AUTH_TOKEN,
+        ingressEnabled: false,
+        publicBaseUrl: "https://generic.example.test",
+      }),
+    );
+
+    expect(getMockFetchCalls()).toEqual([]);
+  });
+
+  test("does not throw when Twilio lookup fails", async () => {
+    mockFetch(
+      `/Accounts/${ACCOUNT_SID}/IncomingPhoneNumbers.json?PhoneNumber=${encodeURIComponent(
+        PHONE_NUMBER,
+      )}`,
+      { method: "GET" },
+      { status: 500, body: { error: "unavailable" } },
+    );
+
+    await expect(
+      syncConfiguredTwilioPhoneNumberWebhooks(
+        makeCaches({
+          phoneNumber: PHONE_NUMBER,
+          accountSid: ACCOUNT_SID,
+          authToken: AUTH_TOKEN,
+          publicBaseUrl: "https://generic.example.test",
+        }),
+      ),
+    ).resolves.toBeUndefined();
+
+    expect(getMockFetchCalls()).toHaveLength(1);
+  });
+});

package/src/twilio/webhook-sync.ts

@@ -0,0 +1,84 @@
+import {
+  buildTwilioPhoneNumberWebhookUrls,
+  resolveTwilioPublicBaseUrl,
+} from "@vellumai/service-contracts/twilio-ingress";
+import { updatePhoneNumberWebhooks } from "@vellumai/twilio-client";
+
+import type { ConfigFileCache } from "../config-file-cache.js";
+import type { CredentialCache } from "../credential-cache.js";
+import { credentialKey } from "../credential-key.js";
+import { fetchImpl } from "../fetch.js";
+import { getLogger } from "../logger.js";
+
+const log = getLogger("twilio-webhook-sync");
+
+export type TwilioWebhookSyncCaches = {
+  credentials: CredentialCache;
+  configFile: ConfigFileCache;
+};
+
+function resolveEffectiveTwilioBaseUrl(
+  configFile: ConfigFileCache,
+): string | undefined {
+  if (configFile.getBoolean("ingress", "enabled", { force: true }) === false) {
+    return undefined;
+  }
+
+  return resolveTwilioPublicBaseUrl({
+    publicBaseUrl: configFile.getString("ingress", "publicBaseUrl"),
+  });
+}
+
+export async function syncConfiguredTwilioPhoneNumberWebhooks(
+  caches: TwilioWebhookSyncCaches,
+): Promise<void> {
+  try {
+    const phoneNumber = caches.configFile
+      .getString("twilio", "phoneNumber")
+      ?.trim();
+    const accountSidFromCredentials = (
+      await caches.credentials.get(credentialKey("twilio", "account_sid"))
+    )?.trim();
+    const accountSid =
+      accountSidFromCredentials ||
+      caches.configFile.getString("twilio", "accountSid")?.trim();
+    const authToken = (
+      await caches.credentials.get(credentialKey("twilio", "auth_token"))
+    )?.trim();
+    const baseUrl = resolveEffectiveTwilioBaseUrl(caches.configFile);
+
+    if (!phoneNumber || !accountSid || !authToken || !baseUrl) {
+      log.debug(
+        {
+          hasPhoneNumber: !!phoneNumber,
+          hasAccountSid: !!accountSid,
+          hasAuthToken: !!authToken,
+          hasBaseUrl: !!baseUrl,
+        },
+        "Skipping Twilio webhook sync because configuration is incomplete",
+      );
+      return;
+    }
+
+    const urls = buildTwilioPhoneNumberWebhookUrls(baseUrl);
+    await updatePhoneNumberWebhooks({
+      accountSid,
+      authToken,
+      fetchImpl,
+      phoneNumber,
+      timeoutMs: 10_000,
+      webhooks: urls,
+    });
+
+    log.info(
+      {
+        phoneNumber,
+        voiceUrl: urls.voiceUrl,
+        statusCallbackUrl: urls.statusCallbackUrl,
+      },
+      "Synced Twilio phone number webhooks",
+    );
+  } catch (err) {
+    log.warn({ err }, "Twilio webhook sync skipped after non-fatal error");
+  }
+}

package/src/util/is-loopback-address.ts

@@ -1,3 +1,30 @@
+import type { Server } from "bun";
+
+/**
+ * Check whether the TCP peer of a Bun HTTP request is a loopback address.
+ *
+ * When `trustProxy` is set, the first entry in `X-Forwarded-For` is used
+ * instead of the raw socket IP.
+ */
+export function isLoopbackPeer(
+  server: Server<unknown>,
+  req: Request,
+  opts?: { trustProxy?: boolean },
+): boolean {
+  if (opts?.trustProxy) {
+    const forwarded = req.headers.get("x-forwarded-for");
+    if (forwarded) {
+      const first = forwarded.split(",")[0]?.trim();
+      if (!first) return false;
+      return isLoopbackAddress(first);
+    }
+  }
+
+  const peer = server.requestIP(req);
+  if (!peer) return false;
+  return isLoopbackAddress(peer.address);
+}
+
 /**
  * Stricter loopback-only check: accepts only 127.0.0.0/8 and ::1.
  * Use this instead of isPrivateNetworkPeer for endpoints that must be