@vellumai/vellum-gateway 0.7.0 → 0.7.2

package/src/http/routes/stt-stream-websocket.ts

@@ -56,9 +56,8 @@ export function createSttStreamWebsocketHandler(config: GatewayConfig) {
 
     // ── Auth ──
     // STT streaming is an authenticated, assistant-scoped path. The
-    // client must present a valid edge JWT (actor principal). Unlike
-    // browser-relay, STT streaming does not have an auth-bypass mode —
-    // fail closed.
+    // client must present a valid edge JWT (actor principal). There is
+    // no auth-bypass mode — fail closed.
     if (!config.runtimeProxyRequireAuth) {
       // When runtime proxy auth is globally disabled (dev bypass), we
       // still allow the upgrade but skip token validation.

package/src/http/routes/telegram-control-plane-proxy.ts

@@ -1,8 +1,8 @@
 /**
  * Gateway proxy endpoints for Telegram integration control-plane routes.
  *
- * These routes remain available even when the broad runtime proxy is
- * disabled, so skills and clients can use gateway URLs exclusively.
+ * These routes are registered as explicit gateway routes for dedicated
+ * auth handling rather than falling through to the catch-all proxy.
  */
 
 import { proxyForward } from "@vellumai/assistant-client";

package/src/http/routes/telegram-webhook.test.ts

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

package/src/http/routes/telegram-webhook.ts

@@ -419,6 +419,8 @@ export function createTelegramWebhookHandler(
               );
             });
           }
+        } else if (result.verificationIntercepted) {
+          // Verification handled — no error, no forward needed
         } else if (!result.forwarded) {
           tlog.error(
             { updateId: payload.update_id },
@@ -739,6 +741,10 @@ export function createTelegramWebhookHandler(
         return respond({ ok: true });
       }
 
+      if (result.verificationIntercepted) {
+        return respond({ ok: true });
+      }
+
       if (!result.forwarded) {
         tlog.error(
           { updateId: payload.update_id },

package/src/http/routes/trust-rules.suggest.test.ts

@@ -212,6 +212,31 @@ describe("POST /v1/trust-rules/suggest", () => {
     expect(callArgs.currentThreshold).toBe("medium");
   });
 
+  test("passes existingRule when provided", async () => {
+    const bodyWithExistingRule = {
+      ...VALID_BODY,
+      existingRule: {
+        id: "rule-123",
+        pattern: "bash *",
+        risk: "low",
+      },
+    };
+
+    const handler = createTrustRulesSuggestHandler();
+    const res = await handler(jsonRequest(bodyWithExistingRule));
+
+    expect(res.status).toBe(200);
+    expect(ipcSuggestTrustRuleMock).toHaveBeenCalledTimes(1);
+    const callArgs = ipcSuggestTrustRuleMock.mock.calls[0][0] as {
+      existingRule: unknown;
+    };
+    expect(callArgs.existingRule).toEqual({
+      id: "rule-123",
+      pattern: "bash *",
+      risk: "low",
+    });
+  });
+
   test("passes directoryScopeOptions when provided", async () => {
     const bodyWithDirScope = {
       ...VALID_BODY,

package/src/http/routes/trust-rules.ts

@@ -47,6 +47,13 @@ const SuggestRequestSchema = z.object({
     )
     .optional(),
   intent: z.enum(["auto_approve", "escalate"]),
+  existingRule: z
+    .object({
+      id: z.string(),
+      pattern: z.string(),
+      risk: z.string(),
+    })
+    .optional(),
 });
 
 /**

package/src/http/routes/twilio-control-plane-proxy.ts

@@ -1,8 +1,8 @@
 /**
  * Gateway proxy endpoints for Twilio integration control-plane routes.
  *
- * These routes remain available even when the broad runtime proxy is
- * disabled, so skills and clients can use gateway URLs exclusively.
+ * These routes are registered as explicit gateway routes for dedicated
+ * auth handling rather than falling through to the catch-all proxy.
  */
 
 import { proxyForward } from "@vellumai/assistant-client";

package/src/http/routes/twilio-media-websocket.ts

@@ -1,4 +1,5 @@
 import { buildWsUpstreamUrl } from "@vellumai/assistant-client";
+import { TWILIO_MEDIA_STREAM_WEBHOOK_PATH } from "@vellumai/service-contracts/twilio-ingress";
 
 import {
   validateEdgeToken,
@@ -13,9 +14,6 @@ const log = getLogger("twilio-media-ws");
 // Cap buffered messages to prevent unbounded memory growth if upstream stalls
 const MAX_PENDING_MESSAGES = 100;
 
-/** Path prefix for media-stream WS upgrades. */
-const MEDIA_STREAM_PATH_PREFIX = "/webhooks/twilio/media-stream";
-
 type MediaStreamSocketData = {
   wsType: "twilio-media-stream";
   callSessionId: string;
@@ -44,8 +42,10 @@ export function extractMediaStreamMetadata(url: URL): {
 } {
   // Try path-based extraction first.
   // Expected pathname: /webhooks/twilio/media-stream/<callSessionId>[/<token>]
-  if (url.pathname.startsWith(MEDIA_STREAM_PATH_PREFIX + "/")) {
-    const suffix = url.pathname.slice(MEDIA_STREAM_PATH_PREFIX.length + 1);
+  if (url.pathname.startsWith(TWILIO_MEDIA_STREAM_WEBHOOK_PATH + "/")) {
+    const suffix = url.pathname.slice(
+      TWILIO_MEDIA_STREAM_WEBHOOK_PATH.length + 1,
+    );
     const segments = suffix.split("/").filter(Boolean);
     if (segments.length >= 1) {
       try {

package/src/http/routes/twilio-voice-verify-callback.ts

@@ -0,0 +1,310 @@
+/**
+ * POST /webhooks/twilio/voice-verify — Twilio <Gather> action callback
+ * for gateway-owned voice verification.
+ *
+ * When the gateway intercepts an inbound call that requires verification,
+ * it returns <Gather> TwiML pointing to this endpoint. Twilio POSTs the
+ * collected DTMF digits here. The gateway validates the code, creates
+ * the guardian binding on success, and then forwards to the assistant
+ * for ConversationRelay setup.
+ *
+ * The assistant is never involved in verification — it only receives
+ * calls from callers whose identity the gateway has already confirmed.
+ */
+
+import { eq } from "drizzle-orm";
+
+import type { GatewayConfig } from "../../config.js";
+import { credentialKey } from "../../credential-key.js";
+import { getLogger } from "../../logger.js";
+import {
+  CircuitBreakerOpenError,
+  forwardTwilioVoiceWebhook,
+  resolvePublicBaseWssUrl,
+} from "../../runtime/client.js";
+import {
+  validateTwilioWebhookRequest,
+  type TwilioValidationCaches,
+} from "../../twilio/validate-webhook.js";
+import {
+  findPendingPhoneSession,
+  validateVerificationCode,
+  gatherVerificationTwiml,
+  failureTwiml,
+} from "../../voice/verification.js";
+import { createGuardianBinding } from "../../auth/guardian-bootstrap.js";
+import { getGatewayDb } from "../../db/connection.js";
+import { contactChannels as gwContactChannels } from "../../db/schema.js";
+import {
+  assistantDbQuery,
+  assistantDbRun,
+} from "../../db/assistant-db-proxy.js";
+import { upsertVerifiedContactChannel } from "../../verification/contact-helpers.js";
+
+const log = getLogger("twilio-voice-verify-callback");
+
+const TWIML_HEADERS = { "Content-Type": "text/xml" };
+
+function twimlResponse(body: string, status = 200): Response {
+  return new Response(body, { status, headers: TWIML_HEADERS });
+}
+
+export function createTwilioVoiceVerifyCallbackHandler(
+  config: GatewayConfig,
+  caches?: TwilioValidationCaches,
+) {
+  return async (req: Request): Promise<Response> => {
+    const validation = await validateTwilioWebhookRequest(req, config, caches);
+    if (validation instanceof Response) return validation;
+
+    const { params } = validation;
+    const fromNumber = params.From || "";
+    const callSid = params.CallSid || "";
+
+    // Extract attempt counter from query string
+    const url = new URL(req.url);
+    const attempt = parseInt(url.searchParams.get("attempt") || "0", 10);
+    const digits = params.Digits || "";
+
+    log.info(
+      { callSid, fromNumber, attempt, hasDigits: digits.length > 0 },
+      "Voice verification callback received",
+    );
+
+    // Re-fetch the pending session (it may have been consumed or expired)
+    const session = await findPendingPhoneSession();
+    if (!session) {
+      log.warn(
+        { callSid, fromNumber },
+        "No pending verification session found on callback — forwarding to assistant",
+      );
+      return forwardToAssistant(config, params, req.url, caches);
+    }
+
+    if (!digits) {
+      log.info(
+        { callSid, fromNumber },
+        "No digits entered — re-prompting",
+      );
+      const actionUrl = buildActionUrl(url, attempt);
+      return twimlResponse(
+        gatherVerificationTwiml(actionUrl, attempt, session.codeDigits ?? 6),
+      );
+    }
+
+    // Validate the entered code
+    const result = await validateVerificationCode(
+      session,
+      digits,
+      fromNumber,
+      attempt,
+    );
+
+    if (!result.success) {
+      if (result.exhausted) {
+        log.warn(
+          { callSid, fromNumber, attempt },
+          "Voice verification exhausted — hanging up",
+        );
+        return twimlResponse(failureTwiml(result.failureMessage!));
+      }
+
+      // Re-prompt with incremented attempt
+      const nextAttempt = attempt + 1;
+      const actionUrl = buildActionUrl(url, nextAttempt);
+      return twimlResponse(
+        gatherVerificationTwiml(actionUrl, nextAttempt, session.codeDigits ?? 6),
+      );
+    }
+
+    // Verification succeeded — create guardian binding if this is a guardian verification
+    if (result.verificationType === "guardian") {
+      try {
+        // Resolve the canonical principal from the vellum channel guardian binding
+        const vellumGuardians = await assistantDbQuery<{
+          principalId: string | null;
+        }>(
+          `SELECT c.principal_id AS principalId
+           FROM contacts c
+           JOIN contact_channels cc ON cc.contact_id = c.id
+           WHERE c.role = 'guardian' AND cc.type = 'vellum' AND cc.status = 'active'
+           LIMIT 1`,
+          [],
+        );
+        const canonicalPrincipal =
+          vellumGuardians[0]?.principalId ?? fromNumber;
+
+        // Check for existing phone guardian binding conflict
+        const existingPhoneGuardians = await assistantDbQuery<{
+          externalUserId: string | null;
+        }>(
+          `SELECT cc.external_user_id AS externalUserId
+           FROM contacts c
+           JOIN contact_channels cc ON cc.contact_id = c.id
+           WHERE c.role = 'guardian' AND cc.type = 'phone' AND cc.status = 'active'
+           LIMIT 1`,
+          [],
+        );
+
+        const existingGuardian = existingPhoneGuardians[0];
+        if (existingGuardian && existingGuardian.externalUserId !== fromNumber) {
+          log.warn(
+            {
+              callSid,
+              fromNumber,
+              existingGuardian: existingGuardian.externalUserId,
+            },
+            "Guardian binding conflict — another user already holds the voice binding",
+          );
+        } else {
+          // Revoke existing phone guardian binding before creating new one
+          if (existingGuardian) {
+            await revokeExistingPhoneGuardian();
+          }
+
+          await createGuardianBinding({
+            channel: "phone",
+            externalUserId: fromNumber,
+            deliveryChatId: fromNumber,
+            guardianPrincipalId: canonicalPrincipal,
+            verifiedVia: "challenge",
+          });
+
+          log.info(
+            { callSid, fromNumber, canonicalPrincipal },
+            "Guardian phone binding created by gateway",
+          );
+        }
+      } catch (err) {
+        log.error(
+          { err, callSid, fromNumber },
+          "Failed to create guardian binding after voice verification",
+        );
+        // Don't fail the call — the verification succeeded even if binding
+        // creation had an issue. The caller should still be connected.
+      }
+    } else if (result.verificationType === "trusted_contact") {
+      try {
+        await upsertVerifiedContactChannel({
+          sourceChannel: "phone",
+          externalUserId: fromNumber,
+          externalChatId: fromNumber,
+        });
+
+        log.info(
+          { callSid, fromNumber },
+          "Trusted contact phone channel activated by gateway",
+        );
+      } catch (err) {
+        log.error(
+          { err, callSid, fromNumber },
+          "Failed to upsert trusted contact channel after voice verification",
+        );
+      }
+    }
+
+    // Forward to the assistant for ConversationRelay setup.
+    // The assistant will see the caller as already verified.
+    log.info(
+      { callSid, fromNumber },
+      "Voice verification complete — forwarding to assistant for call setup",
+    );
+    return forwardToAssistant(config, params, req.url, caches);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Revoke the existing phone guardian binding by setting status to 'revoked'.
+ * Dual-writes to both assistant DB and gateway DB.
+ */
+async function revokeExistingPhoneGuardian(): Promise<void> {
+  const now = Date.now();
+
+  const revokedRows = await assistantDbQuery<{ id: string }>(
+    `SELECT cc.id
+     FROM contacts c
+     JOIN contact_channels cc ON cc.contact_id = c.id
+     WHERE c.role = 'guardian' AND cc.type = 'phone' AND cc.status = 'active'`,
+    [],
+  );
+
+  if (revokedRows.length === 0) return;
+
+  const ids = revokedRows.map((r) => r.id);
+  const placeholders = ids.map(() => "?").join(", ");
+
+  await assistantDbRun(
+    `UPDATE contact_channels
+     SET status = 'revoked', policy = 'deny', updated_at = ?
+     WHERE id IN (${placeholders})`,
+    [now, ...ids],
+  );
+
+  // Gateway DB dual-write (best-effort)
+  try {
+    const gwDb = getGatewayDb();
+    for (const id of ids) {
+      gwDb.update(gwContactChannels)
+        .set({ status: "revoked", policy: "deny", updatedAt: now })
+        .where(eq(gwContactChannels.id, id))
+        .run();
+    }
+  } catch (gwErr) {
+    log.warn({ err: gwErr }, "Gateway DB revoke dual-write failed (best-effort)");
+  }
+}
+
+/**
+ * Build the action URL for the next Gather attempt, preserving the base
+ * path and incrementing the attempt counter.
+ */
+function buildActionUrl(currentUrl: URL, attempt: number): string {
+  const actionUrl = new URL(currentUrl.origin + currentUrl.pathname);
+  actionUrl.searchParams.set("attempt", String(attempt));
+  return actionUrl.pathname + actionUrl.search;
+}
+
+/**
+ * Forward the Twilio voice webhook to the assistant runtime and return
+ * the TwiML response (with relay token injection handled by the client).
+ */
+async function forwardToAssistant(
+  config: GatewayConfig,
+  params: Record<string, string>,
+  originalUrl: string,
+  caches?: TwilioValidationCaches,
+): Promise<Response> {
+  try {
+    const platformAssistantId = (
+      await caches?.credentials?.get(
+        credentialKey("vellum", "platform_assistant_id"),
+      )
+    )?.trim();
+    const runtimeResponse = await forwardTwilioVoiceWebhook(
+      config,
+      params,
+      originalUrl,
+      resolvePublicBaseWssUrl(config, caches?.configFile, platformAssistantId),
+    );
+    return new Response(runtimeResponse.body, {
+      status: runtimeResponse.status,
+      headers: runtimeResponse.headers,
+    });
+  } catch (err) {
+    if (err instanceof CircuitBreakerOpenError) {
+      return Response.json(
+        { error: "Service temporarily unavailable" },
+        {
+          status: 503,
+          headers: { "Retry-After": String(err.retryAfterSecs) },
+        },
+      );
+    }
+    log.error({ err }, "Failed to forward voice webhook to runtime after verification");
+    return Response.json({ error: "Internal server error" }, { status: 502 });
+  }
+}

package/src/http/routes/twilio-voice-webhook.test.ts

@@ -11,6 +11,7 @@
  * - Assistant IDs are NOT forwarded to the daemon (daemon uses internal scope).
  */
 import { describe, test, expect, mock, beforeEach } from "bun:test";
+import { resolvePublicBaseWssUrl } from "../../runtime/client.js";
 
 // ── Mocks ──────────────────────────────────────────────────────────────
 
@@ -54,6 +55,11 @@ mock.module("../../logger.js", () => ({
     }),
 }));
 
+mock.module("../../voice/verification.js", () => ({
+  findPendingPhoneSession: async () => null,
+  gatherVerificationTwiml: () => "<Response/>",
+}));
+
 import { createTwilioVoiceWebhookHandler } from "./twilio-voice-webhook.js";
 import type { GatewayConfig } from "../../config.js";
 import type { ConfigFileCache } from "../../config-file-cache.js";
@@ -77,7 +83,6 @@ const baseConfig: GatewayConfig = {
   routingEntries: [],
   runtimeInitialBackoffMs: 500,
   runtimeMaxRetries: 2,
-  runtimeProxyEnabled: false,
   runtimeProxyRequireAuth: true,
   runtimeTimeoutMs: 30000,
   shutdownDrainMs: 5000,
@@ -282,3 +287,62 @@ describe("twilio voice webhook handler", () => {
     expect(forwardCalled).toBe(true);
   });
 });
+
+// ── resolvePublicBaseWssUrl unit tests ─────────────────────────────────
+
+describe("resolvePublicBaseWssUrl", () => {
+  const baseConfig = {
+    assistantRuntimeBaseUrl: "http://localhost:3000",
+  } as Parameters<typeof resolvePublicBaseWssUrl>[0];
+
+  test("returns undefined when neither velayBaseUrl nor configFile publicBaseUrl is set", () => {
+    expect(resolvePublicBaseWssUrl(baseConfig)).toBeUndefined();
+  });
+
+  test("uses velayBaseUrl + platformAssistantId when both are present", () => {
+    const config = {
+      ...baseConfig,
+      velayBaseUrl: "https://velay-dev.vellum.ai",
+    };
+    const result = resolvePublicBaseWssUrl(
+      config,
+      undefined,
+      "abc12345-0000-0000-0000-000000000000",
+    );
+    expect(result).toBe(
+      "wss://velay-dev.vellum.ai/abc12345-0000-0000-0000-000000000000",
+    );
+  });
+
+  test("falls back to configFile publicBaseUrl when velayBaseUrl is set but platformAssistantId is missing", () => {
+    const config = {
+      ...baseConfig,
+      velayBaseUrl: "https://velay-dev.vellum.ai",
+    };
+    const mockConfigFile = {
+      getString: (section: string, key: string) =>
+        section === "ingress" && key === "publicBaseUrl"
+          ? "https://velay-dev.vellum.ai/abc12345-0000-0000-0000-000000000000"
+          : undefined,
+    } as Parameters<typeof resolvePublicBaseWssUrl>[1];
+    const result = resolvePublicBaseWssUrl(config, mockConfigFile, undefined);
+    expect(result).toBe(
+      "wss://velay-dev.vellum.ai/abc12345-0000-0000-0000-000000000000",
+    );
+  });
+
+  test("strips trailing slash from velayBaseUrl before joining assistant ID", () => {
+    const config = {
+      ...baseConfig,
+      velayBaseUrl: "https://velay-dev.vellum.ai/",
+    };
+    const result = resolvePublicBaseWssUrl(
+      config,
+      undefined,
+      "abc12345-0000-0000-0000-000000000000",
+    );
+    expect(result).toBe(
+      "wss://velay-dev.vellum.ai/abc12345-0000-0000-0000-000000000000",
+    );
+  });
+});

package/src/http/routes/twilio-voice-webhook.ts

@@ -1,9 +1,11 @@
 import type { ConfigFileCache } from "../../config-file-cache.js";
 import type { GatewayConfig } from "../../config.js";
+import { credentialKey } from "../../credential-key.js";
 import { getLogger } from "../../logger.js";
 import {
   CircuitBreakerOpenError,
   forwardTwilioVoiceWebhook,
+  resolvePublicBaseWssUrl,
 } from "../../runtime/client.js";
 import {
   resolveAssistant,
@@ -14,6 +16,10 @@ import {
   validateTwilioWebhookRequest,
   type TwilioValidationCaches,
 } from "../../twilio/validate-webhook.js";
+import {
+  findPendingPhoneSession,
+  gatherVerificationTwiml,
+} from "../../voice/verification.js";
 
 const log = getLogger("twilio-voice-webhook");
 
@@ -21,6 +27,8 @@ const log = getLogger("twilio-voice-webhook");
 const REJECT_TWIML =
   '<?xml version="1.0" encoding="UTF-8"?><Response><Reject reason="rejected"/></Response>';
 
+const TWIML_HEADERS = { "Content-Type": "text/xml" };
+
 export function createTwilioVoiceWebhookHandler(
   config: GatewayConfig,
   caches?: TwilioValidationCaches & { configFile?: ConfigFileCache },
@@ -71,7 +79,7 @@ export function createTwilioVoiceWebhookHandler(
           );
           return new Response(REJECT_TWIML, {
             status: 200,
-            headers: { "Content-Type": "text/xml" },
+            headers: TWIML_HEADERS,
           });
         }
 
@@ -85,13 +93,49 @@ export function createTwilioVoiceWebhookHandler(
           "Resolved assistant via fallback routing for inbound call",
         );
       }
+
+      // ── Gateway-owned voice verification ────────────────────────────
+      // For inbound calls, check if there's a pending phone verification
+      // session. If so, intercept the call with a <Gather> TwiML flow
+      // instead of forwarding to the assistant. The assistant never
+      // touches verification — it only receives verified calls.
+      try {
+        const pendingSession = await findPendingPhoneSession();
+        if (pendingSession) {
+          log.info(
+            {
+              callSid: params.CallSid,
+              fromNumber: params.From,
+              sessionId: pendingSession.id,
+            },
+            "Pending phone verification session found — intercepting with gateway verification",
+          );
+          const verifyCallbackPath = `/webhooks/twilio/voice-verify?attempt=0`;
+          const codeDigits = pendingSession.codeDigits ?? 6;
+          return new Response(
+            gatherVerificationTwiml(verifyCallbackPath, 0, codeDigits),
+            { status: 200, headers: TWIML_HEADERS },
+          );
+        }
+      } catch (err) {
+        log.warn(
+          { err, callSid: params.CallSid },
+          "Failed to check pending verification session — falling through to assistant",
+        );
+      }
     }
 
     try {
+      const platformAssistantId = (
+        await caches?.credentials?.get(
+          credentialKey("vellum", "platform_assistant_id"),
+        )
+      )?.trim();
       const runtimeResponse = await forwardTwilioVoiceWebhook(
         config,
         params,
         req.url,
+        resolvePublicBaseWssUrl(config, caches?.configFile, platformAssistantId),
       );
       return new Response(runtimeResponse.body, {
         status: runtimeResponse.status,

package/src/http/routes/whatsapp-webhook.test.ts

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