@vellumai/vellum-gateway 0.8.1 → 0.8.3

package/ARCHITECTURE.md

@@ -298,7 +298,7 @@ The assistant runtime reads this URL via the centralized `public-ingress-urls.ts
 
 Velay is a platform-managed tunnel for assistant-hosted HTTP and WebSocket traffic. When it is active, Velay publishes the registered public assistant URL to `ingress.publicBaseUrl` and marks it with `ingress.publicBaseUrlManagedBy: "velay"`.
 
-When `VELAY_BASE_URL` is present in the gateway environment, the gateway starts `VelayTunnelClient`. The client registers with Velay over `GET /v1/register` using the assistant API key, then receives a `registered` frame containing a public assistant URL such as `https://velay.vellum.ai/<assistant-id>`. The gateway writes that URL to `ingress.publicBaseUrl`. When the tunnel disconnects, it clears that value only if the Velay ownership marker is still present and the URL still matches what the tunnel published, leaving manual URLs intact.
+When `VELAY_BASE_URL` is present in the gateway environment, the gateway creates `VelayTunnelClient` but starts it only after Twilio setup has been started in the workspace. The Twilio setup skill writes `twilio.setupStarted: true` at the beginning of setup so the tunnel can open while credentials and phone-number selection are still in progress. On boot, existing Twilio credentials or existing `twilio.accountSid` / `twilio.phoneNumber` config also count as prior setup. Before credential-backed startup side effects run, the gateway clears any stale Velay-managed `ingress.publicBaseUrl`; if setup has not started, it does this without opening a tunnel. The client registers with Velay over `GET /v1/register` using the assistant API key, then receives a `registered` frame containing a public assistant URL such as `https://velay.vellum.ai/<assistant-id>`. If Vellum platform credentials change while the tunnel is already running or waiting on backoff, the gateway asks the client to reconnect with fresh credentials instead of waiting for process restart. The gateway writes the registered URL to `ingress.publicBaseUrl`. When the tunnel disconnects, it clears that value only if the Velay ownership marker is still present and the URL still matches what the tunnel published, leaving manual URLs intact.
 
 Velay forwards both HTTP request frames and WebSocket frames into the local gateway loopback listener:
 
@@ -316,10 +316,11 @@ Local platform smoke-test flow:
 
 1. In `vellum-assistant-platform`, run `vel up velay`.
 2. Ensure vembda passes the environment-appropriate `VELAY_BASE_URL` into assistant gateway containers.
-3. Re-hatch or restart the assistant so the gateway receives the new environment.
-4. Confirm gateway logs show `Velay tunnel connected` and `Velay tunnel registered`.
-5. Verify HTTP forwarding by requesting `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/healthz` and `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/schema`. When validating a JSON webhook route under active development, POST a small JSON body through the same Velay public URL and confirm it reaches the loopback gateway.
-6. Verify Twilio WebSocket forwarding with a synthetic local WebSocket client against `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/webhooks/twilio/relay?callSessionId=...&token=...`, then with a real Twilio call after the gateway has registered with Velay.
+3. Start or complete Twilio setup in the workspace so the gateway is allowed to connect the tunnel.
+4. Re-hatch or restart the assistant so the gateway receives the new environment.
+5. Confirm gateway logs show `Velay tunnel connected` and `Velay tunnel registered`.
+6. Verify HTTP forwarding by requesting `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/healthz` and `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/schema`. When validating a JSON webhook route under active development, POST a small JSON body through the same Velay public URL and confirm it reaches the loopback gateway.
+7. Verify Twilio WebSocket forwarding with a synthetic local WebSocket client against `${VELAY_PUBLIC_BASE_URL}/<assistant-id>/webhooks/twilio/relay?callSessionId=...&token=...`, then with a real Twilio call after the gateway has registered with Velay.
 
 ### URL Builders
 

package/README.md

@@ -212,7 +212,7 @@ The assistant runtime uses this URL to construct all webhook and OAuth callback
 
 ### Velay for Twilio Testing
 
-Velay is a managed ingress transport for assistant-hosted HTTP and WebSocket traffic. When Velay registration succeeds, the gateway writes the registered public assistant URL to `ingress.publicBaseUrl` and marks it with `ingress.publicBaseUrlManagedBy: "velay"`. Twilio URL builders use that public base URL for voice, status, relay, and media-stream endpoints.
+Velay is a managed ingress transport for assistant-hosted HTTP and WebSocket traffic. The gateway starts the Velay tunnel only after Twilio setup has been started in the workspace, or when existing Twilio config shows it was set up before. When Velay registration succeeds, the gateway writes the registered public assistant URL to `ingress.publicBaseUrl` and marks it with `ingress.publicBaseUrlManagedBy: "velay"`. Twilio URL builders use that public base URL for voice, status, relay, and media-stream endpoints.
 
 Use Velay when testing Twilio voice webhooks or Twilio WebSocket upgrades through the platform-managed tunnel:
 
@@ -230,8 +230,9 @@ Use Velay when testing Twilio voice webhooks or Twilio WebSocket upgrades throug
 
    Hosted environments should use their environment's deployed Velay URL instead.
 
-3. Re-hatch or restart the assistant so the gateway process receives `VELAY_BASE_URL`.
-4. Confirm the gateway logs include `Velay tunnel connected` followed by `Velay tunnel registered`. Registration publishes the returned Velay URL to `ingress.publicBaseUrl`.
+3. Start or complete Twilio setup in the workspace so the gateway is allowed to connect the tunnel.
+4. Re-hatch or restart the assistant so the gateway process receives `VELAY_BASE_URL`.
+5. Confirm the gateway logs include `Velay tunnel connected` followed by `Velay tunnel registered`. Registration publishes the returned Velay URL to `ingress.publicBaseUrl`.
 
 For an HTTP bridge smoke test, send a request to the registered Velay public URL and confirm it reaches the loopback gateway, for example:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/config-file-watcher.test.ts

@@ -42,6 +42,31 @@ function makeEvent(
   };
 }
 
+function makeManualIntervalTimer() {
+  let intervalFn: (() => void) | undefined;
+  let cleared = false;
+  type IntervalHandle = ReturnType<typeof setInterval>;
+  const timer = 1 as unknown as IntervalHandle;
+  return {
+    timerApi: {
+      setInterval: (fn: () => void, _delayMs: number) => {
+        intervalFn = fn;
+        return timer;
+      },
+      clearInterval: (_timer: IntervalHandle) => {
+        cleared = true;
+      },
+    },
+    runInterval: () => {
+      if (!intervalFn) {
+        throw new Error("interval was not scheduled");
+      }
+      intervalFn();
+    },
+    isCleared: () => cleared,
+  };
+}
+
 afterEach(() => {
   try {
     if (existsSync(configPath)) unlinkSync(configPath);
@@ -51,6 +76,38 @@ afterEach(() => {
 });
 
 describe("ConfigFileWatcher", () => {
+  test("polls config changes when file watcher events are missed", () => {
+    const events: ConfigChangeEvent[] = [];
+    const timer = makeManualIntervalTimer();
+    const watcher = new ConfigFileWatcher(
+      (event) => {
+        events.push(event);
+      },
+      { pollIntervalMs: 10, timerApi: timer.timerApi },
+    );
+
+    try {
+      watcher.start();
+      writeConfig({
+        twilio: {
+          setupStarted: true,
+        },
+      });
+
+      timer.runInterval();
+
+      expect(events).toHaveLength(1);
+      expect(events[0].changedKeys).toEqual(new Set(["twilio"]));
+      expect(events[0].changedFields.get("twilio")).toEqual(
+        new Set(["setupStarted"]),
+      );
+    } finally {
+      watcher.stop();
+    }
+
+    expect(timer.isCleared()).toBe(true);
+  });
+
   test("reports shallow ingress fields changed by Velay-managed URL writes", () => {
     writeConfig({
       ingress: {

package/src/__tests__/contact-store-mark-channel-verified.test.ts

@@ -2,8 +2,10 @@
  * Tests for ContactStore.markChannelVerified — manual channel verification
  * flow used by the /v1/contact-channels/:id/verify endpoint.
  *
- * assistantDbRun is mocked to a no-op so tests exercise gateway DB logic
- * only, without needing an assistant daemon.
+ * The assistant DB proxy is mocked behind a per-test fake (`fakeAssistantDb`)
+ * so tests can stage either an empty assistant DB (most cases) or a
+ * pre-populated one (mirror-from-assistant cases) without spinning up a
+ * daemon.
  */
 
 import {
@@ -18,13 +20,75 @@ import {
 
 import "./test-preload.js";
 
-// Mock the assistant DB proxy before importing ContactStore.
+type FakeChannelRow = {
+  id: string;
+  contact_id: string;
+  type: string;
+  address: string;
+  is_primary: number;
+  external_user_id: string | null;
+  external_chat_id: string | null;
+  status: string;
+  policy: string;
+  verified_at: number | null;
+  verified_via: string | null;
+  invite_id: string | null;
+  revoked_reason: string | null;
+  blocked_reason: string | null;
+  last_seen_at: number | null;
+  interaction_count: number;
+  last_interaction: number | null;
+  created_at: number;
+  updated_at: number | null;
+};
+
+type FakeContactRow = {
+  id: string;
+  display_name: string;
+  role: string | null;
+  principal_id: string | null;
+  created_at: number;
+  updated_at: number | null;
+};
+
+const fakeAssistantDb = {
+  channels: new Map<string, FakeChannelRow>(),
+  contacts: new Map<string, FakeContactRow>(),
+  runCalls: [] as { sql: string; bind?: unknown[] }[],
+  reset(): void {
+    this.channels.clear();
+    this.contacts.clear();
+    this.runCalls = [];
+  },
+};
+
+// Mock the assistant DB proxy before importing ContactStore. The fake
+// honors `SELECT ... FROM contact_channels WHERE id = ?` and
+// `SELECT ... FROM contacts WHERE id = ?`; all other SELECTs return [].
 mock.module("../db/assistant-db-proxy.js", () => ({
-  assistantDbRun: mock(async () => ({ changes: 0, lastInsertRowid: 0 })),
-  assistantDbQuery: mock(async () => []),
+  assistantDbRun: mock(async (sql: string, bind?: unknown[]) => {
+    fakeAssistantDb.runCalls.push({ sql, bind });
+    return { changes: 1, lastInsertRowid: 0 };
+  }),
+  assistantDbQuery: mock(async (sql: string, bind?: unknown[]) => {
+    const lower = sql.toLowerCase();
+    if (lower.includes("from contact_channels")) {
+      const id = String(bind?.[0] ?? "");
+      const row = fakeAssistantDb.channels.get(id);
+      return row ? [row] : [];
+    }
+    if (lower.includes("from contacts")) {
+      const id = String(bind?.[0] ?? "");
+      const row = fakeAssistantDb.contacts.get(id);
+      return row ? [row] : [];
+    }
+    return [];
+  }),
   assistantDbExec: mock(async () => undefined),
 }));
 
+import { eq } from "drizzle-orm";
+
 import { ContactStore } from "../db/contact-store.js";
 import {
   initGatewayDb,
@@ -41,8 +105,48 @@ beforeEach(() => {
   const db = getGatewayDb();
   db.delete(contactChannels).run();
   db.delete(contacts).run();
+  fakeAssistantDb.reset();
 });
 
+function seedAssistantContact(id: string, role: string = "guardian"): void {
+  fakeAssistantDb.contacts.set(id, {
+    id,
+    display_name: `name-${id}`,
+    role,
+    principal_id: `prin-${id}`,
+    created_at: 100,
+    updated_at: 100,
+  });
+}
+
+function seedAssistantChannel(opts: {
+  id: string;
+  contactId: string;
+  status?: string;
+}): void {
+  fakeAssistantDb.channels.set(opts.id, {
+    id: opts.id,
+    contact_id: opts.contactId,
+    type: "vellum",
+    address: `addr-${opts.id}`,
+    is_primary: 0,
+    external_user_id: null,
+    external_chat_id: null,
+    status: opts.status ?? "unverified",
+    policy: "allow",
+    verified_at: null,
+    verified_via: null,
+    invite_id: null,
+    revoked_reason: null,
+    blocked_reason: null,
+    last_seen_at: null,
+    interaction_count: 0,
+    last_interaction: null,
+    created_at: 100,
+    updated_at: 100,
+  });
+}
+
 afterAll(() => {
   resetGatewayDb();
 });
@@ -90,7 +194,7 @@ function seedChannel(opts: {
 }
 
 describe("ContactStore.markChannelVerified", () => {
-  test("returns null when the channel does not exist", async () => {
+  test("returns null when neither side has the channel", async () => {
     const store = new ContactStore();
     expect(await store.markChannelVerified("missing-id")).toBeNull();
   });
@@ -174,4 +278,113 @@ describe("ContactStore.markChannelVerified", () => {
     // Same verifiedAt — predicate prevented re-stamping
     expect(b!.channel.verifiedAt).toBe(a!.channel.verifiedAt);
   });
+
+  test("mirrors channel + contact from assistant DB when gateway is empty, then verifies", async () => {
+    seedAssistantContact("c1");
+    seedAssistantChannel({
+      id: "ch1",
+      contactId: "c1",
+      status: "unverified",
+    });
+
+    const before = Date.now();
+    const result = await new ContactStore().markChannelVerified("ch1");
+    expect(result).not.toBeNull();
+    expect(result!.didWrite).toBe(true);
+    expect(result!.channel.status).toBe("active");
+    expect(result!.channel.verifiedVia).toBe("manual");
+    expect(result!.channel.verifiedAt!).toBeGreaterThanOrEqual(before);
+
+    // Channel + contact were materialized in the gateway DB.
+    const channelInGateway = getGatewayDb()
+      .select()
+      .from(contactChannels)
+      .where(eq(contactChannels.id, "ch1"))
+      .get();
+    expect(channelInGateway).toBeTruthy();
+    expect(channelInGateway!.contactId).toBe("c1");
+    expect(channelInGateway!.type).toBe("vellum");
+    const contactInGateway = getGatewayDb()
+      .select()
+      .from(contacts)
+      .where(eq(contacts.id, "c1"))
+      .get();
+    expect(contactInGateway).toBeTruthy();
+    expect(contactInGateway!.displayName).toBe("name-c1");
+    expect(contactInGateway!.role).toBe("guardian");
+  });
+
+  test("refuses to mirror when assistant channel references a missing contact", async () => {
+    // Channel present, parent contact absent — broken state, refuse silently.
+    seedAssistantChannel({ id: "ch1", contactId: "orphan", status: "unverified" });
+
+    const result = await new ContactStore().markChannelVerified("ch1");
+    expect(result).toBeNull();
+
+    // Nothing landed in the gateway.
+    const channelInGateway = getGatewayDb()
+      .select()
+      .from(contactChannels)
+      .where(eq(contactChannels.id, "ch1"))
+      .get();
+    expect(channelInGateway).toBeUndefined();
+  });
+
+  test("mirror is idempotent across successive calls", async () => {
+    seedAssistantContact("c1");
+    seedAssistantChannel({
+      id: "ch1",
+      contactId: "c1",
+      status: "unverified",
+    });
+
+    const store = new ContactStore();
+    const first = await store.markChannelVerified("ch1");
+    const second = await store.markChannelVerified("ch1");
+    expect(first!.didWrite).toBe(true);
+    expect(second!.didWrite).toBe(false);
+    expect(second!.channel.verifiedAt).toBe(first!.channel.verifiedAt);
+    // Mirror INSERT OR IGNORE: still exactly one channel row, one contact row.
+    expect(
+      getGatewayDb().select().from(contactChannels).all().length,
+    ).toBe(1);
+    expect(getGatewayDb().select().from(contacts).all().length).toBe(1);
+  });
+
+  test("gateway-present channel takes precedence over assistant copy (no mirror, no overwrite)", async () => {
+    // Gateway has the row (with a custom display_name for the contact);
+    // assistant has a different display_name. We should verify the gateway
+    // row in place — not overwrite gateway state with the assistant copy.
+    const now = Date.now();
+    getGatewayDb()
+      .insert(contacts)
+      .values({
+        id: "c1",
+        displayName: "gateway-name",
+        role: "guardian",
+        principalId: "prin-c1",
+        createdAt: now,
+        updatedAt: now,
+      })
+      .run();
+    seedChannel({ id: "ch1", contactId: "c1", status: "unverified" });
+    seedAssistantContact("c1");
+    seedAssistantChannel({
+      id: "ch1",
+      contactId: "c1",
+      status: "unverified",
+    });
+
+    const result = await new ContactStore().markChannelVerified("ch1");
+    expect(result).not.toBeNull();
+    expect(result!.didWrite).toBe(true);
+    expect(result!.channel.status).toBe("active");
+
+    const contactRow = getGatewayDb()
+      .select()
+      .from(contacts)
+      .where(eq(contacts.id, "c1"))
+      .get();
+    expect(contactRow!.displayName).toBe("gateway-name");
+  });
 });

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

@@ -393,6 +393,43 @@ describe("handleUpsertContact (gateway-native)", () => {
     expect(params.displayName).toBe("Alice");
   });
 
+  test("strips role and principalId from request body (privilege escalation guard)", async () => {
+    // Regression: a malicious caller MUST NOT be able to rebind the guardian
+    // by sending `role: "guardian"` + their own principalId via POST
+    // /v1/contacts. The route handler must never pass those fields through
+    // to the service layer; ContactStore's params surface must not include
+    // them.
+    contactStoreUpsertMock = mock(async () => ({
+      contact: { ...DEFAULT_MOCK_CONTACT, id: "ct_target", role: "guardian" },
+      created: false,
+    }));
+
+    const handler = createContactsControlPlaneProxyHandler(makeConfig());
+    const res = await handler.handleUpsertContact(
+      new Request("http://localhost:7830/v1/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          id: "ct_target",
+          displayName: "Pwn3d",
+          role: "guardian",
+          principalId: "attacker-principal-id",
+        }),
+      }),
+    );
+
+    expect(res.status).toBe(200);
+    expect(contactStoreUpsertMock).toHaveBeenCalledTimes(1);
+    const [params] = contactStoreUpsertMock.mock.calls[0] as [
+      Record<string, unknown>,
+    ];
+    expect(params.role).toBeUndefined();
+    expect(params.principalId).toBeUndefined();
+    // The other fields still flow through.
+    expect(params.id).toBe("ct_target");
+    expect(params.displayName).toBe("Pwn3d");
+  });
+
   test("returns 400 when body is invalid JSON", async () => {
     const handler = createContactsControlPlaneProxyHandler(makeConfig());
     const res = await handler.handleUpsertContact(