@vellumai/vellum-gateway 0.6.0 → 0.6.2

package/Dockerfile

@@ -1,5 +1,5 @@
 # Bun binary source (pinned to SHA digest for immutable reference)
-FROM oven/bun:1.2.21@sha256:5a2011bf09364b9af658ac1e66f60d08092f4291aeefbff448d58b027734fdd0 AS bun
+FROM oven/bun:1.3.11@sha256:0733e50325078969732ebe3b15ce4c4be5082f18c4ac1a0f0ca4839c2e4e42a7 AS bun
 
 # Build stage
 FROM debian:trixie@sha256:3615a749858a1cba49b408fb49c37093db813321355a9ab7c1f9f4836341e9db AS builder
@@ -20,6 +20,8 @@ WORKDIR /app
 
 RUN apt-get update && apt-get upgrade -y && apt-get install -y \
     ca-certificates \
+    iproute2 \
+    procps \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy bun binary from builder

package/package.json

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

package/src/__tests__/config.test.ts

@@ -23,7 +23,8 @@ describe("config: hardcoded defaults", () => {
     expect(config.unmappedPolicy).toBe("reject");
     expect(config.routingEntries).toEqual([]);
     expect(config.defaultAssistantId).toBeUndefined();
-    expect(config.logFile).toEqual({ dir: undefined, retentionDays: 30 });
+    expect(config.logFile.dir).toMatch(/\.vellum\/logs$/);
+    expect(config.logFile.retentionDays).toBe(30);
   });
 
   test("GATEWAY_PORT defaults to 7830", () => {

package/src/__tests__/feature-flags-route.test.ts

@@ -97,7 +97,7 @@ const {
 } = await import("../feature-flag-defaults.js");
 const { clearFeatureFlagStoreCache, readPersistedFeatureFlags } =
   await import("../feature-flag-store.js");
-const { clearRemoteFeatureFlagStoreCache } =
+const { clearRemoteFeatureFlagStoreCache, writeRemoteFeatureFlags } =
   await import("../feature-flag-remote-store.js");
 
 describe("GET /v1/feature-flags handler", () => {
@@ -337,6 +337,43 @@ describe("GET /v1/feature-flags handler", () => {
     expect(emailFlag.enabled).toBe(false);
   });
 
+  test("reflects updated flags after remote sync writes new values (stale cache regression)", async () => {
+    // Scenario: the LD poller (RemoteFeatureFlagSync) writes
+    // email-channel: false, the gateway caches it, then a subsequent
+    // poll writes email-channel: true. The GET handler should return
+    // the updated value because writeRemoteFeatureFlags() updates
+    // both disk and the in-memory cache.
+
+    // Step 1: First poll writes email-channel: false (simulated via
+    // writeRemoteFeatureFlags, which is what the poller calls internally).
+    writeRemoteFeatureFlags({ "email-channel": false });
+
+    const handler = createFeatureFlagsGetHandler();
+    const res1 = await handler(
+      new Request("http://gateway.test/v1/feature-flags"),
+    );
+    const body1 = await res1.json();
+    const emailFlag1 = body1.flags.find(
+      (f: { key: string }) => f.key === "email-channel",
+    );
+    expect(emailFlag1.enabled).toBe(false);
+
+    // Step 2: Second poll writes email-channel: true — the poller
+    // calls writeRemoteFeatureFlags which updates file + cache.
+    writeRemoteFeatureFlags({ "email-channel": true });
+
+    // Step 3: The GET handler should immediately reflect the update
+    // without needing a file-watcher round-trip.
+    const res2 = await handler(
+      new Request("http://gateway.test/v1/feature-flags"),
+    );
+    const body2 = await res2.json();
+    const emailFlag2 = body2.flags.find(
+      (f: { key: string }) => f.key === "email-channel",
+    );
+    expect(emailFlag2.enabled).toBe(true);
+  });
+
   test("registry default used when neither local nor remote is set", async () => {
     // No local override
     if (existsSync(featureFlagStorePath)) {

package/src/__tests__/remote-feature-flag-sync.test.ts

@@ -428,6 +428,43 @@ describe("RemoteFeatureFlagSync", () => {
     );
   });
 
+  test("ignores remote false for GA flags (defaultEnabled: true in registry)", async () => {
+    // The platform sends false for all flags it knows about (blanket-deny).
+    // GA flags (defaultEnabled: true in the registry) should not be disabled
+    // by remote overrides — only local persisted overrides can do that.
+    fetchMock = mock(async () =>
+      Response.json({
+        flags: {
+          // GA flag (defaultEnabled: true) — remote false should be dropped
+          "conversation-starters": false,
+          // Gated flag (defaultEnabled: false) — remote false is kept
+          "email-channel": false,
+          // GA flag set to true — should be kept (redundant but harmless)
+          browser: true,
+          // Unknown flag — remote false is kept (not in registry)
+          "unknown-flag": false,
+        },
+      }),
+    );
+
+    const sync = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(defaultCredentials()),
+    });
+    await sync.start();
+    sync.stop();
+
+    clearRemoteFeatureFlagStoreCache();
+    const cached = readRemoteFeatureFlags();
+    // conversation-starters (GA, remote false) should be absent
+    expect(cached["conversation-starters"]).toBeUndefined();
+    // email-channel (gated, remote false) should be present
+    expect(cached["email-channel"]).toBe(false);
+    // browser (GA, remote true) should be present
+    expect(cached.browser).toBe(true);
+    // unknown-flag (not in registry, remote false) should be present
+    expect(cached["unknown-flag"]).toBe(false);
+  });
+
   test("trims whitespace from credential values", async () => {
     fetchMock = mock(async () => Response.json({ flags: {} }));
 
@@ -450,4 +487,97 @@ describe("RemoteFeatureFlagSync", () => {
     const headers = init?.headers as Record<string, string>;
     expect(headers.Authorization).toBe("Api-Key trimmed-key");
   });
+
+  test("polls with backoff when initial fetch fails, then snaps to steady-state on success", async () => {
+    // Simulate: first two fetches fail (missing creds), third succeeds.
+    let callCount = 0;
+    const credsFn = async (key: string) => {
+      callCount++;
+      // First 6 calls = 2 attempts × 3 credential reads each → missing API key.
+      // After that, credentials are available.
+      if (callCount <= 6) {
+        if (key === "credential/vellum/assistant_api_key") return undefined;
+        return defaultCredentials()[key];
+      }
+      return defaultCredentials()[key];
+    };
+    const creds = { get: credsFn } as unknown as CredentialCache;
+
+    fetchMock = mock(async () =>
+      Response.json({ flags: { "backoff-flag": true } }),
+    );
+
+    const sync = new RemoteFeatureFlagSync({
+      credentials: creds,
+      initialPollIntervalMs: 50,
+    });
+    await sync.start();
+
+    // Initial fetch failed (missing creds) — no fetch calls yet
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    // Wait for first poll (50ms) — still fails (creds still missing)
+    await new Promise((r) => setTimeout(r, 80));
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    // Wait for second poll (100ms = 50ms doubled) — creds now available
+    await new Promise((r) => setTimeout(r, 130));
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    clearRemoteFeatureFlagStoreCache();
+    expect(readRemoteFeatureFlags()).toEqual({ "backoff-flag": true });
+
+    sync.stop();
+  });
+
+  test("snaps to steady-state interval immediately when initial fetch succeeds", async () => {
+    fetchMock = mock(async () => Response.json({ flags: { "ok-flag": true } }));
+
+    const sync = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(defaultCredentials()),
+      initialPollIntervalMs: 50,
+    });
+    await sync.start();
+
+    // Initial fetch succeeded — 1 call
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Wait past what would be the initial poll interval — should NOT poll
+    // again because the interval snapped to steady-state (5 min)
+    await new Promise((r) => setTimeout(r, 100));
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    sync.stop();
+  });
+
+  test("doubles poll interval on consecutive failures", async () => {
+    // Always fail — missing creds
+    const creds = defaultCredentials();
+    delete creds["credential/vellum/assistant_api_key"];
+
+    fetchMock = mock(async () => Response.json({ flags: {} }));
+
+    const sync = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(creds),
+      initialPollIntervalMs: 50,
+    });
+    await sync.start();
+
+    // No fetch calls (missing creds)
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    // After 50ms: first poll fires, still fails → interval doubles to 100ms
+    await new Promise((r) => setTimeout(r, 80));
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    // After another 100ms: second poll fires, still fails → interval doubles to 200ms
+    await new Promise((r) => setTimeout(r, 130));
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    // After another 200ms: third poll fires
+    await new Promise((r) => setTimeout(r, 230));
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    sync.stop();
+  });
 });

package/src/channels/inbound-event.ts

@@ -10,7 +10,7 @@ import type { ChannelId } from "./types.js";
 
 export type InboundChannelId = Extract<
   ChannelId,
-  "telegram" | "whatsapp" | "slack"
+  "telegram" | "whatsapp" | "slack" | "email"
 >;
 
 interface InboundEventBase<C extends InboundChannelId> {
@@ -52,8 +52,10 @@ interface InboundEventBase<C extends InboundChannelId> {
 export type TelegramInboundEvent = InboundEventBase<"telegram">;
 export type WhatsAppInboundEvent = InboundEventBase<"whatsapp">;
 export type SlackInboundEvent = InboundEventBase<"slack">;
+export type EmailInboundEvent = InboundEventBase<"email">;
 
 export type GatewayInboundEvent =
   | TelegramInboundEvent
   | WhatsAppInboundEvent
-  | SlackInboundEvent;
+  | SlackInboundEvent
+  | EmailInboundEvent;

package/src/channels/transport-hints.ts

@@ -35,3 +35,21 @@ export function buildWhatsAppTransportMetadata(): {
     uxBrief: WHATSAPP_CHANNEL_TRANSPORT_UX_BRIEF,
   };
 }
+
+export const EMAIL_CHANNEL_TRANSPORT_HINTS = [
+  "email-medium",
+  "defer-dashboard-only-tasks",
+] as const;
+
+export const EMAIL_CHANNEL_TRANSPORT_UX_BRIEF =
+  "Email is an asynchronous medium. Responses can be longer and more detailed than chat. Use proper formatting. The user may not see the response immediately.";
+
+export function buildEmailTransportMetadata(): {
+  hints: string[];
+  uxBrief: string;
+} {
+  return {
+    hints: [...EMAIL_CHANNEL_TRANSPORT_HINTS],
+    uxBrief: EMAIL_CHANNEL_TRANSPORT_UX_BRIEF,
+  };
+}

package/src/config.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 
 import { getLogger, type LogFileConfig } from "./logger.js";
@@ -148,7 +149,9 @@ export function loadConfig(): GatewayConfig {
   }
 
   const logFile: LogFileConfig = {
-    dir: undefined,
+    dir:
+      process.env.GATEWAY_LOG_DIR ??
+      join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum", "logs"),
     retentionDays: 30,
   };
 

package/src/download-validation.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ContentMismatchError,
+  validateDownloadedContent,
+} from "./download-validation.js";
+
+/** Create a minimal valid PNG buffer that file-type can detect. */
+function makePngBuffer(): Uint8Array {
+  return new Uint8Array([
+    // PNG signature
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+    // IHDR chunk: length (13)
+    0x00, 0x00, 0x00, 0x0d,
+    // IHDR type
+    0x49, 0x48, 0x44, 0x52,
+    // Width: 1
+    0x00, 0x00, 0x00, 0x01,
+    // Height: 1
+    0x00, 0x00, 0x00, 0x01,
+    // Bit depth, color type, compression, filter, interlace
+    0x08, 0x02, 0x00, 0x00, 0x00,
+    // CRC (placeholder)
+    0x90, 0x77, 0x53, 0xde,
+  ]);
+}
+
+function htmlBuffer(html: string): Uint8Array {
+  return new TextEncoder().encode(html);
+}
+
+describe("validateDownloadedContent", () => {
+  test("throws ContentMismatchError when HTML is received instead of image/png", async () => {
+    const buffer = htmlBuffer(
+      "<!DOCTYPE html><html><body><h1>Access Denied</h1></body></html>",
+    );
+
+    await expect(
+      validateDownloadedContent(buffer, "image/png", "F001"),
+    ).rejects.toThrow(ContentMismatchError);
+
+    await expect(
+      validateDownloadedContent(buffer, "image/png", "F001"),
+    ).rejects.toThrow(
+      "File F001 declared as image/png but content is HTML (likely an auth/error page)",
+    );
+  });
+
+  test("throws ContentMismatchError for HTML with leading whitespace and BOM", async () => {
+    // UTF-8 BOM (EF BB BF) + whitespace + HTML
+    const bom = new Uint8Array([0xef, 0xbb, 0xbf]);
+    const html = new TextEncoder().encode(
+      "  \n  <!DOCTYPE html><html><body>Error</body></html>",
+    );
+    const buffer = new Uint8Array(bom.length + html.length);
+    buffer.set(bom, 0);
+    buffer.set(html, bom.length);
+
+    await expect(
+      validateDownloadedContent(buffer, "image/jpeg", "F002"),
+    ).rejects.toThrow(ContentMismatchError);
+  });
+
+  test("passes for valid PNG buffer with declared image/png", async () => {
+    const buffer = makePngBuffer();
+
+    // Should not throw
+    await validateDownloadedContent(buffer, "image/png", "F003");
+  });
+
+  test("passes for valid PNG buffer with declared image/jpeg (same image family)", async () => {
+    const buffer = makePngBuffer();
+
+    // file-type detects it as image/png, which still starts with "image/"
+    // so it should pass even though declared as image/jpeg
+    await validateDownloadedContent(buffer, "image/jpeg", "F004");
+  });
+
+  test("passes for plain text buffer with declared text/plain (non-binary)", async () => {
+    const buffer = new TextEncoder().encode("hello world");
+
+    // text/plain is not a binary MIME type, so no validation is performed
+    await validateDownloadedContent(
+      new Uint8Array(buffer),
+      "text/plain",
+      "F005",
+    );
+  });
+
+  test("passes for empty buffer with declared image/png", async () => {
+    const buffer = new Uint8Array(0);
+
+    // Empty buffer: looksLikeHtml returns false, fileTypeFromBuffer returns
+    // undefined, so we allow it through and let downstream handle it
+    await validateDownloadedContent(buffer, "image/png", "F006");
+  });
+});

package/src/download-validation.ts

@@ -0,0 +1,92 @@
+import { fileTypeFromBuffer } from "file-type";
+
+export class ContentMismatchError extends Error {
+  override name = "ContentMismatchError";
+}
+
+/**
+ * Check whether a buffer looks like an HTML page by inspecting the first
+ * non-whitespace / non-BOM bytes for common HTML markers.
+ */
+export function looksLikeHtml(buffer: Uint8Array): boolean {
+  // Skip leading whitespace and UTF-8 BOM (0xEF 0xBB 0xBF)
+  let offset = 0;
+  // Skip UTF-8 BOM if present
+  if (
+    buffer.length >= 3 &&
+    buffer[0] === 0xef &&
+    buffer[1] === 0xbb &&
+    buffer[2] === 0xbf
+  ) {
+    offset = 3;
+  }
+  // Skip whitespace characters (space, tab, newline, carriage return)
+  while (offset < buffer.length) {
+    const byte = buffer[offset];
+    if (byte === 0x20 || byte === 0x09 || byte === 0x0a || byte === 0x0d) {
+      offset++;
+    } else {
+      break;
+    }
+  }
+
+  if (offset >= buffer.length) {
+    return false;
+  }
+
+  const remaining = buffer.subarray(offset);
+  const prefix = new TextDecoder("utf-8", { fatal: false }).decode(
+    remaining.subarray(0, Math.min(remaining.length, 15)),
+  );
+
+  const upper = prefix.toUpperCase();
+  return upper.startsWith("<!DOCTYPE") || upper.startsWith("<HTML");
+}
+
+const BINARY_MIME_PREFIXES = [
+  "image/",
+  "audio/",
+  "video/",
+  "application/pdf",
+] as const;
+
+/**
+ * Validate that downloaded content actually matches its declared MIME type.
+ *
+ * This catches a common failure mode where CDNs (Slack, WhatsApp, Telegram)
+ * return an HTML error or auth page instead of the actual binary file.
+ * Base64-encoding that HTML and sending it to a provider as e.g. `image/png`
+ * causes the provider to reject the request.
+ */
+export async function validateDownloadedContent(
+  buffer: Uint8Array,
+  declaredMime: string,
+  fileId: string,
+): Promise<void> {
+  const isBinary = BINARY_MIME_PREFIXES.some((prefix) =>
+    declaredMime.startsWith(prefix),
+  );
+
+  if (!isBinary) {
+    return;
+  }
+
+  // Guard: if the buffer looks like HTML, it's almost certainly an error page
+  if (looksLikeHtml(buffer)) {
+    throw new ContentMismatchError(
+      `File ${fileId} declared as ${declaredMime} but content is HTML (likely an auth/error page)`,
+    );
+  }
+
+  // For image types, do a deeper check with file-type detection
+  if (declaredMime.startsWith("image/")) {
+    const detected = await fileTypeFromBuffer(buffer);
+    if (detected && !detected.mime.startsWith("image/")) {
+      throw new ContentMismatchError(
+        `File ${fileId} declared as ${declaredMime} but detected as ${detected.mime}`,
+      );
+    }
+    // If detected is undefined and it doesn't look like HTML, allow it
+    // through — some image formats may not be in file-type's database.
+  }
+}

package/src/email/normalize.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from "bun:test";
+import { normalizeEmailWebhook } from "./normalize.js";
+
+describe("normalizeEmailWebhook", () => {
+  function makePayload(overrides?: Record<string, unknown>) {
+    return {
+      from: "alice@example.com",
+      to: "bot@vellum.me",
+      messageId: "<msg-1@example.com>",
+      conversationId: "conv-1",
+      subject: "Test Subject",
+      strippedText: "Hello, world!",
+      bodyText: "On Mon, someone wrote:\n> old\n\nHello, world!",
+      timestamp: "2026-04-03T01:00:00.000Z",
+      ...(overrides ?? {}),
+    };
+  }
+
+  it("normalizes a valid email payload", () => {
+    const result = normalizeEmailWebhook(makePayload());
+    expect(result).not.toBeNull();
+    expect(result!.eventId).toBe("<msg-1@example.com>");
+    expect(result!.recipientAddress).toBe("bot@vellum.me");
+    expect(result!.event.sourceChannel).toBe("email");
+    expect(result!.event.message.content).toBe("Hello, world!");
+    expect(result!.event.message.conversationExternalId).toBe("conv-1");
+    expect(result!.event.message.externalMessageId).toBe("<msg-1@example.com>");
+    expect(result!.event.actor.actorExternalId).toBe("alice@example.com");
+    expect(result!.event.actor.displayName).toBe("alice@example.com");
+  });
+
+  it("returns null when required fields are missing", () => {
+    // Missing 'from'
+    expect(
+      normalizeEmailWebhook({
+        to: "bot@vellum.me",
+        messageId: "m",
+        conversationId: "c",
+      }),
+    ).toBeNull();
+    // Missing 'to'
+    expect(
+      normalizeEmailWebhook({
+        from: "a@b.com",
+        messageId: "m",
+        conversationId: "c",
+      }),
+    ).toBeNull();
+    // Missing 'messageId'
+    expect(
+      normalizeEmailWebhook({
+        from: "a@b.com",
+        to: "bot@vellum.me",
+        conversationId: "c",
+      }),
+    ).toBeNull();
+    // Missing 'conversationId'
+    expect(
+      normalizeEmailWebhook({
+        from: "a@b.com",
+        to: "bot@vellum.me",
+        messageId: "m",
+      }),
+    ).toBeNull();
+  });
+
+  it("returns null for empty object", () => {
+    expect(normalizeEmailWebhook({})).toBeNull();
+  });
+
+  it("uses fromName as displayName when provided", () => {
+    const result = normalizeEmailWebhook(
+      makePayload({ fromName: "Alice Smith" }),
+    );
+    expect(result).not.toBeNull();
+    expect(result!.event.actor.actorExternalId).toBe("alice@example.com");
+    expect(result!.event.actor.displayName).toBe("Alice Smith");
+  });
+
+  it("falls back to email as displayName when fromName is absent", () => {
+    const result = normalizeEmailWebhook(makePayload());
+    expect(result!.event.actor.displayName).toBe("alice@example.com");
+  });
+
+  it("prefers strippedText over bodyText", () => {
+    const result = normalizeEmailWebhook(
+      makePayload({
+        strippedText: "Just the new reply",
+        bodyText: "Full email with quoted content",
+      }),
+    );
+    expect(result!.event.message.content).toBe("Just the new reply");
+  });
+
+  it("falls back to bodyText when strippedText is missing", () => {
+    const payload = makePayload();
+    delete (payload as Record<string, unknown>).strippedText;
+    const result = normalizeEmailWebhook(payload);
+    expect(result!.event.message.content).toBe(
+      "On Mon, someone wrote:\n> old\n\nHello, world!",
+    );
+  });
+
+  it("uses empty string when both strippedText and bodyText are missing", () => {
+    const payload = makePayload();
+    delete (payload as Record<string, unknown>).strippedText;
+    delete (payload as Record<string, unknown>).bodyText;
+    const result = normalizeEmailWebhook(payload);
+    expect(result!.event.message.content).toBe("");
+  });
+
+  it("uses messageId as eventId", () => {
+    const result = normalizeEmailWebhook(
+      makePayload({ messageId: "<unique@example.com>" }),
+    );
+    expect(result!.eventId).toBe("<unique@example.com>");
+  });
+
+  it("sets username to sender email", () => {
+    const result = normalizeEmailWebhook(makePayload());
+    expect(result!.event.actor.username).toBe("alice@example.com");
+  });
+
+  it("preserves raw payload in event.raw", () => {
+    const payload = makePayload();
+    const result = normalizeEmailWebhook(payload);
+    expect(result!.event.raw).toEqual(payload);
+  });
+});