@vellumai/vellum-gateway 0.7.0 → 0.7.2

package/src/__tests__/telegram-control-plane-proxy.test.ts

@@ -27,7 +27,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: true,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/__tests__/telegram-send-attachments.test.ts

@@ -30,7 +30,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: true,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/__tests__/telegram-webhook-handler.test.ts

@@ -29,7 +29,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: false,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/__tests__/text-verification-helpers.test.ts

@@ -0,0 +1,136 @@
+import { describe, test, expect } from "bun:test";
+
+import { parseVerificationCode, hashVerificationSecret } from "../verification/code-parsing.js";
+import { canonicalizeInboundIdentity } from "../verification/identity.js";
+import { checkIdentityMatch } from "../verification/identity-match.js";
+import type { VerificationSession } from "../verification/session-helpers.js";
+
+// ---------------------------------------------------------------------------
+// Code parsing
+// ---------------------------------------------------------------------------
+
+describe("parseVerificationCode", () => {
+  test("accepts 6-digit numeric code", () => {
+    expect(parseVerificationCode("123456")).toBe("123456");
+  });
+
+  test("accepts 64-char hex string", () => {
+    const hex = "a".repeat(64);
+    expect(parseVerificationCode(hex)).toBe(hex);
+  });
+
+  test("strips mrkdwn formatting", () => {
+    expect(parseVerificationCode("*123456*")).toBe("123456");
+    expect(parseVerificationCode("_123456_")).toBe("123456");
+    expect(parseVerificationCode("`123456`")).toBe("123456");
+    expect(parseVerificationCode("~123456~")).toBe("123456");
+  });
+
+  test("rejects non-code messages", () => {
+    expect(parseVerificationCode("hello")).toBeUndefined();
+    expect(parseVerificationCode("12345")).toBeUndefined(); // too short
+    expect(parseVerificationCode("1234567")).toBeUndefined(); // too long for numeric
+    expect(parseVerificationCode("verify 123456")).toBeUndefined(); // not bare
+  });
+
+  test("trims whitespace", () => {
+    expect(parseVerificationCode("  123456  ")).toBe("123456");
+  });
+});
+
+describe("hashVerificationSecret", () => {
+  test("produces a 64-char hex sha256", () => {
+    const hash = hashVerificationSecret("test");
+    expect(hash).toHaveLength(64);
+    expect(hash).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test("is deterministic", () => {
+    expect(hashVerificationSecret("abc")).toBe(hashVerificationSecret("abc"));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Identity canonicalization
+// ---------------------------------------------------------------------------
+
+describe("canonicalizeInboundIdentity", () => {
+  test("phone channel: normalizes US 10-digit to E.164", () => {
+    expect(canonicalizeInboundIdentity("phone", "5551234567")).toBe("+15551234567");
+    expect(canonicalizeInboundIdentity("whatsapp", "5551234567")).toBe("+15551234567");
+  });
+
+  test("phone channel: passes through already-E.164", () => {
+    expect(canonicalizeInboundIdentity("phone", "+15551234567")).toBe("+15551234567");
+  });
+
+  test("phone channel: strips formatting", () => {
+    expect(canonicalizeInboundIdentity("phone", "(555) 123-4567")).toBe("+15551234567");
+  });
+
+  test("non-phone channel: trims only", () => {
+    expect(canonicalizeInboundIdentity("telegram", "  user123  ")).toBe("user123");
+    expect(canonicalizeInboundIdentity("slack", "U12345")).toBe("U12345");
+  });
+
+  test("returns null for empty/whitespace", () => {
+    expect(canonicalizeInboundIdentity("telegram", "")).toBeNull();
+    expect(canonicalizeInboundIdentity("telegram", "   ")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Identity matching
+// ---------------------------------------------------------------------------
+
+describe("checkIdentityMatch", () => {
+  const baseSession: VerificationSession = {
+    id: "sess-1",
+    challengeHash: "abc",
+    expiresAt: Date.now() + 60_000,
+    status: "pending",
+    verificationPurpose: "guardian",
+    expectedExternalUserId: null,
+    expectedChatId: null,
+    expectedPhoneE164: null,
+    identityBindingStatus: "bound",
+    codeDigits: 6,
+    maxAttempts: 3,
+  };
+
+  test("matches when session has no expected identity (inbound)", () => {
+    expect(checkIdentityMatch(baseSession, "any-user", "any-chat")).toBe(true);
+  });
+
+  test("matches when binding status is not bound", () => {
+    const session = { ...baseSession, expectedExternalUserId: "user-1", identityBindingStatus: "pending_bootstrap" };
+    expect(checkIdentityMatch(session, "different-user", "any-chat")).toBe(true);
+  });
+
+  test("matches by phone E.164", () => {
+    const session = { ...baseSession, expectedPhoneE164: "+15551234567" };
+    expect(checkIdentityMatch(session, "+15551234567", "chat-1")).toBe(true);
+  });
+
+  test("rejects phone mismatch", () => {
+    const session = { ...baseSession, expectedPhoneE164: "+15551234567" };
+    expect(checkIdentityMatch(session, "+19999999999", "chat-1")).toBe(false);
+  });
+
+  test("matches by externalUserId when expectedChatId is set", () => {
+    const session = { ...baseSession, expectedExternalUserId: "user-1", expectedChatId: "chat-1" };
+    expect(checkIdentityMatch(session, "user-1", "different-chat")).toBe(true);
+  });
+
+  test("matches by chatId alone when no expectedExternalUserId", () => {
+    const session = { ...baseSession, expectedChatId: "chat-1" };
+    expect(checkIdentityMatch(session, "any-user", "chat-1")).toBe(true);
+  });
+
+  test("rejects chatId-only mismatch", () => {
+    const session = { ...baseSession, expectedChatId: "chat-1" };
+    expect(checkIdentityMatch(session, "any-user", "wrong-chat")).toBe(false);
+  });
+});
+
+

package/src/__tests__/twilio-media-websocket.test.ts

@@ -45,7 +45,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: true,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/__tests__/twilio-relay-websocket.test.ts

@@ -44,7 +44,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: true,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/__tests__/twilio-webhooks.test.ts

@@ -121,7 +121,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: true,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,
@@ -147,10 +146,15 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
 function makeCaches(
   opts: {
     authToken?: string;
+    ingressEnabled?: boolean;
     ingressUrl?: string;
   } = {},
 ) {
-  const { authToken = AUTH_TOKEN, ingressUrl } = opts;
+  const {
+    authToken = AUTH_TOKEN,
+    ingressEnabled,
+    ingressUrl,
+  } = opts;
   const credentials = {
     get: async (key: string, _opts?: { force?: boolean }) => {
       if (key === credentialKey("twilio", "auth_token")) return authToken;
@@ -163,6 +167,10 @@ function makeCaches(
       if (section === "ingress" && key === "publicBaseUrl") return ingressUrl;
       return undefined;
     },
+    getBoolean: (section: string, key: string) => {
+      if (section === "ingress" && key === "enabled") return ingressEnabled;
+      return undefined;
+    },
     getRecord: () => undefined,
     refreshNow: () => {},
   } as unknown as ConfigFileCache;
@@ -256,6 +264,20 @@ describe("Twilio voice webhook", () => {
     expect(res.status).toBe(403);
   });
 
+  test("rejects while public ingress is disabled", async () => {
+    const handler = createTwilioVoiceWebhookHandler(
+      makeConfig(),
+      makeCaches({ ingressEnabled: false }),
+    );
+    const url = "http://localhost:7830/webhooks/twilio/voice";
+    const req = buildSignedRequest(url, { From: "+15550100" }, AUTH_TOKEN);
+
+    const res = await handler(req);
+
+    expect(res.status).toBe(403);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   test("forwards valid signed request to runtime and returns response", async () => {
     const twiml = '<?xml version="1.0" encoding="UTF-8"?><Response/>';
     fetchMock = mock(
@@ -475,6 +497,53 @@ describe("Twilio connect-action webhook", () => {
 });
 
 describe("Twilio webhook signature with canonical ingress base URL", () => {
+  test("validates signature against configured publicBaseUrl", async () => {
+    fetchMock = mock(
+      async () =>
+        new Response('<?xml version="1.0" encoding="UTF-8"?><Response/>', {
+          status: 200,
+          headers: { "Content-Type": "text/xml" },
+        }),
+    );
+
+    const publicBaseUrl = "https://public.example.com";
+    const handler = createTwilioVoiceWebhookHandler(
+      makeConfig(),
+      makeCaches({
+        ingressUrl: publicBaseUrl,
+      }),
+    );
+
+    const localUrl =
+      "http://localhost:7830/webhooks/twilio/voice?callSessionId=sig-test";
+    const publicUrl =
+      publicBaseUrl + "/webhooks/twilio/voice?callSessionId=sig-test";
+    const params = { CallSid: "CA123" };
+    const signature = computeSignature(publicUrl, params, AUTH_TOKEN);
+    const req = new Request(localUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "X-Twilio-Signature": signature,
+      },
+      body: new URLSearchParams(params).toString(),
+    });
+
+    const res = await handler(req);
+    expect(res.status).toBe(200);
+
+    const successLog = findLogCall("Twilio webhook signature validated");
+    expect(successLog.method).toBe("info");
+    expect(successLog.data).toMatchObject({
+      webhookKind: "voice",
+      validatedCandidateSource: "configured_ingress",
+      validatedCandidateUrl: publicUrl,
+      candidateCount: 2,
+      candidateSources: ["configured_ingress", "raw_request"],
+      candidateUrls: [publicUrl, localUrl],
+    });
+  });
+
   test("validates signature against ingressPublicBaseUrl when configured", async () => {
     const twiml = '<?xml version="1.0" encoding="UTF-8"?><Response/>';
     fetchMock = mock(
@@ -713,9 +782,157 @@ describe("Twilio webhook signature with canonical ingress base URL", () => {
       ],
     });
   });
+
+  test("validates signature against X-Vellum-Ingress-URL from platform callback proxy", async () => {
+    fetchMock = mock(
+      async () =>
+        new Response('<?xml version="1.0" encoding="UTF-8"?><Response/>', {
+          status: 200,
+          headers: { "Content-Type": "text/xml" },
+        }),
+    );
+
+    const handler = createTwilioVoiceWebhookHandler(makeConfig(), makeCaches());
+
+    // The platform callback URL is what Twilio signs against — it includes
+    // the /v1/gateway/callbacks/{assistantId}/ prefix that the gateway
+    // never sees in the request path.
+    const platformCallbackUrl =
+      "https://platform.vellum.ai/v1/gateway/callbacks/abc123/webhooks/twilio/voice";
+    const localUrl =
+      "http://localhost:7830/webhooks/twilio/voice?callSessionId=platform-proxy-test";
+    const params = { CallSid: "CA-platform-proxy" };
+
+    // Sign against the platform callback URL (as Twilio would)
+    const signature = computeSignature(platformCallbackUrl, params, AUTH_TOKEN);
+    const req = new Request(localUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "X-Twilio-Signature": signature,
+        "X-Vellum-Ingress-URL": platformCallbackUrl,
+      },
+      body: new URLSearchParams(params).toString(),
+    });
+
+    const res = await handler(req);
+    expect(res.status).toBe(200);
+
+    const successLog = findLogCall("Twilio webhook signature validated");
+    expect(successLog.method).toBe("info");
+    expect(successLog.data).toMatchObject({
+      webhookKind: "voice",
+      validatedCandidateSource: "platform_proxy",
+      validatedCandidateUrl: platformCallbackUrl,
+      candidateCount: 2,
+      candidateSources: ["platform_proxy", "raw_request"],
+      candidateUrls: [platformCallbackUrl, localUrl],
+    });
+  });
+
+  test("platform proxy URL takes priority over configured ingress", async () => {
+    fetchMock = mock(
+      async () =>
+        new Response('<?xml version="1.0" encoding="UTF-8"?><Response/>', {
+          status: 200,
+          headers: { "Content-Type": "text/xml" },
+        }),
+    );
+
+    const staleConfiguredBase = "https://stale.example.com";
+    const handler = createTwilioVoiceWebhookHandler(
+      makeConfig(),
+      makeCaches({ ingressUrl: staleConfiguredBase }),
+    );
+
+    const platformCallbackUrl =
+      "https://platform.vellum.ai/v1/gateway/callbacks/abc123/webhooks/twilio/voice";
+    const localUrl =
+      "http://localhost:7830/webhooks/twilio/voice?callSessionId=priority-test";
+    const params = { CallSid: "CA-priority" };
+
+    // Sign against the platform callback URL
+    const signature = computeSignature(platformCallbackUrl, params, AUTH_TOKEN);
+    const req = new Request(localUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "X-Twilio-Signature": signature,
+        "X-Vellum-Ingress-URL": platformCallbackUrl,
+      },
+      body: new URLSearchParams(params).toString(),
+    });
+
+    const res = await handler(req);
+    expect(res.status).toBe(200);
+
+    const successLog = findLogCall("Twilio webhook signature validated");
+    expect(successLog.data).toMatchObject({
+      validatedCandidateSource: "platform_proxy",
+      validatedCandidateUrl: platformCallbackUrl,
+      candidateSources: ["platform_proxy", "configured_ingress", "raw_request"],
+    });
+  });
 });
 
-describe("Twilio webhook force retry on credential-missing", () => {
+describe("Twilio webhook force retry", () => {
+  test("refreshes Twilio-specific ingress URL before retrying signature validation", async () => {
+    fetchMock = mock(
+      async () =>
+        new Response('<?xml version="1.0" encoding="UTF-8"?><Response/>', {
+          status: 200,
+          headers: { "Content-Type": "text/xml" },
+        }),
+    );
+
+    let refreshCount = 0;
+    const credentials = {
+      get: async () => AUTH_TOKEN,
+      invalidate: () => {},
+    } as unknown as CredentialCache;
+
+    const staleTwilioBaseUrl = "https://stale-twilio.example.com";
+    const freshBaseUrl = "https://fresh-twilio.example.com";
+    const configFile = {
+      getString: (section: string, key: string) => {
+        if (section !== "ingress") return undefined;
+        if (key === "publicBaseUrl") {
+          return refreshCount > 0 ? freshBaseUrl : staleTwilioBaseUrl;
+        }
+        return undefined;
+      },
+      getRecord: () => undefined,
+      refreshNow: () => {
+        refreshCount++;
+      },
+    } as unknown as ConfigFileCache;
+
+    const handler = createTwilioVoiceWebhookHandler(makeConfig(), {
+      credentials,
+      configFile,
+    });
+
+    const localUrl =
+      "http://localhost:7830/webhooks/twilio/voice?callSessionId=sess-refresh";
+    const freshTwilioUrl =
+      freshBaseUrl + "/webhooks/twilio/voice?callSessionId=sess-refresh";
+    const params = { CallSid: "CA123" };
+    const signature = computeSignature(freshTwilioUrl, params, AUTH_TOKEN);
+    const req = new Request(localUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "X-Twilio-Signature": signature,
+      },
+      body: new URLSearchParams(params).toString(),
+    });
+
+    const res = await handler(req);
+
+    expect(res.status).toBe(200);
+    expect(refreshCount).toBe(1);
+  });
+
   test("succeeds after force-refreshing a missing auth token", async () => {
     const twiml = '<?xml version="1.0" encoding="UTF-8"?><Response/>';
     fetchMock = mock(

package/src/__tests__/upstream-transport.test.ts

@@ -160,41 +160,6 @@ describe("HTTP proxy timeout/error via assistant-client", () => {
 describe("WS upstream URL construction via assistant-client", () => {
   const baseUrl = "http://localhost:7821";
 
-  test("browser-relay builds correct upstream WS URL with guardian/instance params", () => {
-    const result = buildWsUpstreamUrl({
-      baseUrl,
-      path: "/v1/browser-relay",
-      serviceToken: "svc-jwt-token",
-      extraParams: {
-        guardianId: "guardian-abc",
-        clientInstanceId: "inst-xyz",
-      },
-    });
-
-    const url = new URL(result.url);
-    expect(url.protocol).toBe("ws:");
-    expect(url.hostname).toBe("localhost");
-    expect(url.port).toBe("7821");
-    expect(url.pathname).toBe("/v1/browser-relay");
-    expect(url.searchParams.get("token")).toBe("svc-jwt-token");
-    expect(url.searchParams.get("guardianId")).toBe("guardian-abc");
-    expect(url.searchParams.get("clientInstanceId")).toBe("inst-xyz");
-  });
-
-  test("browser-relay builds URL without optional params when absent", () => {
-    const result = buildWsUpstreamUrl({
-      baseUrl,
-      path: "/v1/browser-relay",
-      serviceToken: "svc-jwt-token",
-      extraParams: {},
-    });
-
-    const url = new URL(result.url);
-    expect(url.searchParams.get("token")).toBe("svc-jwt-token");
-    expect(url.searchParams.has("guardianId")).toBe(false);
-    expect(url.searchParams.has("clientInstanceId")).toBe(false);
-  });
-
   test("twilio-relay builds correct upstream WS URL with callSessionId", () => {
     const result = buildWsUpstreamUrl({
       baseUrl,
@@ -270,7 +235,6 @@ describe("WS upstream log-safe URL", () => {
       path: string;
       params: Record<string, string>;
     }> = [
-      { path: "/v1/browser-relay", params: { guardianId: "g1" } },
       { path: "/v1/calls/relay", params: { callSessionId: "c1" } },
       { path: "/v1/calls/media-stream", params: { callSessionId: "m1" } },
       { path: "/v1/stt/stream", params: { mimeType: "audio/webm" } },

package/src/__tests__/whatsapp-download.test.ts

@@ -26,7 +26,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: true,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/__tests__/whatsapp-webhook.test.ts

@@ -53,7 +53,6 @@ function makeConfig(overrides: Partial<GatewayConfig> = {}): GatewayConfig {
     defaultAssistantId: undefined,
     unmappedPolicy: "reject",
     port: 7830,
-    runtimeProxyEnabled: false,
     runtimeProxyRequireAuth: true,
     shutdownDrainMs: 5000,
     runtimeTimeoutMs: 30000,

package/src/auth/guardian-refresh.ts

@@ -3,7 +3,7 @@
  * gateway's own SQLite database for all token operations.
  */
 
-import { createHash, randomBytes } from "node:crypto";
+import { randomBytes } from "node:crypto";
 
 import { and, eq } from "drizzle-orm";
 
@@ -35,7 +35,6 @@ export type RefreshErrorCode =
   | "refresh_invalid"
   | "refresh_expired"
   | "refresh_reuse_detected"
-  | "device_binding_mismatch"
   | "revoked";
 
 export interface RotateResult {
@@ -202,15 +201,10 @@ function mintRefreshTokenInFamily(params: {
  */
 export function rotateCredentials(params: {
   refreshToken: string;
-  platform: string;
-  deviceId: string;
 }):
   | { ok: true; result: RotateResult }
   | { ok: false; error: RefreshErrorCode } {
   const refreshTokenHash = hashToken(params.refreshToken);
-  const hashedDeviceId = createHash("sha256")
-    .update(params.deviceId)
-    .digest("hex");
 
   const record = findRefreshByHash(refreshTokenHash);
 
@@ -245,14 +239,6 @@ export function rotateCredentials(params: {
     return { ok: false, error: "refresh_expired" };
   }
 
-  if (record.hashedDeviceId !== hashedDeviceId) {
-    return { ok: false, error: "device_binding_mismatch" };
-  }
-
-  if (record.platform !== params.platform) {
-    return { ok: false, error: "device_binding_mismatch" };
-  }
-
   return getGatewayDb().transaction((tx) => {
     void tx; // transaction scoped via the underlying bun:sqlite connection
 
@@ -269,19 +255,19 @@ export function rotateCredentials(params: {
     const access = mintAccessToken(
       record.guardianPrincipalId,
       record.hashedDeviceId,
-      params.platform,
+      record.platform,
     );
 
     const refresh = mintRefreshTokenInFamily({
       guardianPrincipalId: record.guardianPrincipalId,
       hashedDeviceId: record.hashedDeviceId,
-      platform: params.platform,
+      platform: record.platform,
       familyId: record.familyId,
       absoluteExpiresAt: record.absoluteExpiresAt,
     });
 
     log.info(
-      { familyId: record.familyId, platform: params.platform },
+      { familyId: record.familyId, platform: record.platform },
       "Credential rotation completed",
     );