@vellumai/vellum-gateway 0.6.0 → 0.6.2

package/src/email/normalize.ts

@@ -0,0 +1,94 @@
+import type { GatewayInboundEvent } from "../types.js";
+
+/**
+ * Shape of a normalized inbound email event as sent by the Vellum
+ * platform (or any upstream caller).
+ *
+ * The platform is responsible for provider-specific parsing (e.g.
+ * Mailgun multipart → JSON). By the time the payload reaches the
+ * gateway it should already be in this canonical shape.
+ */
+export interface VellumEmailPayload {
+  /** Sender email address (e.g. "user@vellum.me"). */
+  from: string;
+  /** Sender display name (e.g. "Alice Smith"). Optional. */
+  fromName?: string;
+  /** Recipient email address (the assistant's address). */
+  to: string;
+  /** Email subject line. */
+  subject?: string;
+  /** Plain-text body content (latest reply only, quoted text stripped). */
+  strippedText?: string;
+  /** Full plain-text body (fallback when strippedText is unavailable). */
+  bodyText?: string;
+  /** RFC 5322 Message-ID header value. */
+  messageId: string;
+  /** Message-ID of the parent message (In-Reply-To header). */
+  inReplyTo?: string;
+  /** Space-separated chain of ancestor Message-IDs (References header). */
+  references?: string;
+  /** Stable conversation/thread identifier derived by the platform. */
+  conversationId: string;
+  /** ISO 8601 timestamp of the original email. */
+  timestamp?: string;
+}
+
+export interface NormalizedEmailEvent {
+  event: GatewayInboundEvent;
+  /** Unique event/message ID for dedup. */
+  eventId: string;
+  /** Original recipient address for routing. */
+  recipientAddress: string;
+}
+
+/**
+ * Normalize a Vellum email webhook payload into a GatewayInboundEvent.
+ *
+ * Returns null if required fields are missing.
+ */
+export function normalizeEmailWebhook(
+  payload: Record<string, unknown>,
+): NormalizedEmailEvent | null {
+  const from = payload.from as string | undefined;
+  const to = payload.to as string | undefined;
+  const messageId = payload.messageId as string | undefined;
+  const conversationId = payload.conversationId as string | undefined;
+
+  if (!from || !to || !messageId || !conversationId) {
+    return null;
+  }
+
+  // Prefer strippedText (latest reply only) over full body
+  const content =
+    (payload.strippedText as string | undefined) ??
+    (payload.bodyText as string | undefined) ??
+    "";
+
+  const fromName = payload.fromName as string | undefined;
+
+  const event: GatewayInboundEvent = {
+    version: "v1",
+    sourceChannel: "email",
+    receivedAt: new Date().toISOString(),
+    message: {
+      content,
+      conversationExternalId: conversationId,
+      externalMessageId: messageId,
+    },
+    actor: {
+      actorExternalId: from,
+      displayName: fromName || from,
+      username: from,
+    },
+    source: {
+      updateId: messageId,
+    },
+    raw: payload,
+  };
+
+  return {
+    event,
+    eventId: messageId,
+    recipientAddress: to,
+  };
+}

package/src/email/verify.test.ts

@@ -0,0 +1,96 @@
+import { createHmac } from "node:crypto";
+import { describe, it, expect } from "bun:test";
+import { verifyEmailWebhookSignature } from "./verify.js";
+
+const SECRET = "test-webhook-secret-1234";
+
+function computeSignature(body: string, secret: string): string {
+  return (
+    "sha256=" + createHmac("sha256", secret).update(body, "utf8").digest("hex")
+  );
+}
+
+describe("verifyEmailWebhookSignature", () => {
+  const body = '{"from":"sender@example.com","to":"bot@vellum.me"}';
+
+  it("accepts a valid HMAC signature", () => {
+    const headers = new Headers({
+      "vellum-signature": computeSignature(body, SECRET),
+    });
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(true);
+  });
+
+  it("rejects a wrong secret", () => {
+    const headers = new Headers({
+      "vellum-signature": computeSignature(body, "wrong-secret"),
+    });
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(false);
+  });
+
+  it("rejects when header is missing", () => {
+    const headers = new Headers();
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(false);
+  });
+
+  it("rejects when secret is empty", () => {
+    const headers = new Headers({
+      "vellum-signature": computeSignature(body, SECRET),
+    });
+    expect(verifyEmailWebhookSignature(headers, body, "")).toBe(false);
+  });
+
+  it("rejects when header value is empty", () => {
+    const headers = new Headers({
+      "vellum-signature": "",
+    });
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(false);
+  });
+
+  it("rejects a signature without sha256= prefix", () => {
+    const digest = createHmac("sha256", SECRET)
+      .update(body, "utf8")
+      .digest("hex");
+    const headers = new Headers({
+      "vellum-signature": digest,
+    });
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(false);
+  });
+
+  it("rejects when body has been tampered with", () => {
+    const headers = new Headers({
+      "vellum-signature": computeSignature(body, SECRET),
+    });
+    expect(verifyEmailWebhookSignature(headers, "tampered body", SECRET)).toBe(
+      false,
+    );
+  });
+
+  it("produces different signatures for different bodies", () => {
+    const sig1 = computeSignature("body-a", SECRET);
+    const sig2 = computeSignature("body-b", SECRET);
+    expect(sig1).not.toBe(sig2);
+
+    const headers1 = new Headers({ "vellum-signature": sig1 });
+    expect(verifyEmailWebhookSignature(headers1, "body-a", SECRET)).toBe(true);
+    expect(verifyEmailWebhookSignature(headers1, "body-b", SECRET)).toBe(false);
+  });
+
+  it("rejects a truncated hex digest", () => {
+    const headers = new Headers({
+      "vellum-signature": "sha256=abcd1234",
+    });
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(false);
+  });
+
+  it("rejects non-ASCII hex values without throwing (Buffer byte length divergence)", () => {
+    // 64 non-ASCII characters whose UTF-16 .length === 64 (same as a valid
+    // hex digest) but whose Buffer byte length > 64, which would cause
+    // timingSafeEqual to throw if we only compared string lengths.
+    const nonAsciiHex = "\u00e9".repeat(64); // é is 2 bytes in UTF-8
+    const headers = new Headers({
+      "vellum-signature": `sha256=${nonAsciiHex}`,
+    });
+    // Must return false cleanly — not throw
+    expect(verifyEmailWebhookSignature(headers, body, SECRET)).toBe(false);
+  });
+});

package/src/email/verify.ts

@@ -0,0 +1,41 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Verify the Vellum-Signature header sent by the Vellum platform.
+ *
+ * The platform computes: HMAC-SHA256(webhookSecret, rawBody) and sends it as
+ *   Vellum-Signature: sha256=<hex-digest>
+ *
+ * We must compare with a constant-time comparison to avoid timing attacks.
+ *
+ * This mirrors the WhatsApp webhook signature verification pattern
+ * (`X-Hub-Signature-256` header).
+ */
+
+const HEADER_NAME = "vellum-signature";
+
+export function verifyEmailWebhookSignature(
+  headers: Headers,
+  rawBody: string,
+  webhookSecret: string,
+): boolean {
+  const signatureHeader = headers.get(HEADER_NAME);
+  if (!signatureHeader || !webhookSecret) return false;
+
+  // Header format: "sha256=<hex-digest>"
+  if (!signatureHeader.startsWith("sha256=")) return false;
+  const providedHex = signatureHeader.slice(7);
+
+  const expected = createHmac("sha256", webhookSecret)
+    .update(rawBody, "utf8")
+    .digest("hex");
+
+  // Compare Buffer byte lengths — not string .length — to avoid
+  // timingSafeEqual throwing on non-ASCII input where UTF-16 code unit
+  // count matches but byte length diverges.
+  const providedBuf = Buffer.from(providedHex);
+  const expectedBuf = Buffer.from(expected);
+  if (providedBuf.length !== expectedBuf.length) return false;
+
+  return timingSafeEqual(providedBuf, expectedBuf);
+}

package/src/feature-flag-registry.json

@@ -121,6 +121,14 @@
       "description": "Show the Billing tab in Settings when signed in, displaying credits balance and top-up",
       "defaultEnabled": true
     },
+    {
+      "id": "referral-codes",
+      "scope": "macos",
+      "key": "referral-codes",
+      "label": "Referral Codes",
+      "description": "Surface the Earn Credits referral entry points (sidebar drawer row and Billing tab button) that open the referral modal",
+      "defaultEnabled": true
+    },
     {
       "id": "managed-sign-in",
       "scope": "macos",
@@ -199,7 +207,7 @@
       "key": "show-thinking-blocks",
       "label": "Show Thinking Blocks",
       "description": "Display the assistant's thinking/reasoning inline in chat messages as collapsible blocks",
-      "defaultEnabled": false
+      "defaultEnabled": true
     },
     {
       "id": "inline-skill-commands",
@@ -272,6 +280,14 @@
       "label": "Teleport",
       "description": "Enable teleport UI in General settings for moving assistants between hosting environments",
       "defaultEnabled": false
+    },
+    {
+      "id": "permission-controls-v2",
+      "scope": "assistant",
+      "key": "permission-controls-v2",
+      "label": "Permission Controls V2",
+      "description": "Replace risk-level permission system with two independent controls: 'Ask before acting' (LLM behavior toggle) and 'Host access' (system-enforced gate)",
+      "defaultEnabled": false
     }
   ]
 }

package/src/feature-flag-remote-store.ts

@@ -114,6 +114,25 @@ export function writeRemoteFeatureFlags(values: Record<string, boolean>): void {
   log.info({ count: Object.keys(values).length }, "Wrote remote feature flags");
 }
 
+/**
+ * Clear the in-memory cache so the next `readRemoteFeatureFlags()` call
+ * re-reads from disk. Useful in tests for resetting state between cases.
+ */
 export function clearRemoteFeatureFlagStoreCache(): void {
   cachedRemoteValues = null;
 }
+
+/**
+ * Re-read the remote feature flag file from disk into the in-memory cache.
+ *
+ * Called by the file watcher when `feature-flags-remote.json` changes on
+ * disk (e.g. written by a separate process or a previous gateway instance).
+ * This ensures the next `readRemoteFeatureFlags()` call returns fresh data
+ * without requiring every read to hit disk.
+ */
+export function refreshRemoteFeatureFlagStoreCache(): void {
+  cachedRemoteValues = null;
+  // Force a re-read into cache immediately so the next
+  // readRemoteFeatureFlags() call picks up the new values.
+  readRemoteFeatureFlags();
+}

package/src/feature-flag-watcher.ts

@@ -1,6 +1,6 @@
 /**
- * Watches feature-flags.json for external modifications and invalidates the
- * module-level cache in feature-flag-store.ts.
+ * Watches feature flag files for external modifications and invalidates /
+ * refreshes the corresponding module-level caches.
  *
  * Uses the same fs.watch() + debounce pattern as CredentialWatcher and
  * ConfigFileWatcher. Watches the parent directory (not the file itself)
@@ -15,6 +15,10 @@ import {
   clearFeatureFlagStoreCache,
   getFeatureFlagStorePath,
 } from "./feature-flag-store.js";
+import {
+  refreshRemoteFeatureFlagStoreCache,
+  getRemoteFeatureFlagStorePath,
+} from "./feature-flag-remote-store.js";
 import { getLogger } from "./logger.js";
 
 const log = getLogger("feature-flag-watcher");
@@ -24,16 +28,18 @@ const DEBOUNCE_MS = 500;
 export class FeatureFlagWatcher {
   private watcher: FSWatcher | null = null;
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
-  private flagPath: string;
-  private flagFilename: string;
+  private localFlagFilename: string;
+  private remoteFlagFilename: string;
+  /** Accumulates which files changed during the debounce window. */
+  private pendingFilenames = new Set<string>();
 
   constructor() {
-    this.flagPath = getFeatureFlagStorePath();
-    this.flagFilename = basename(this.flagPath);
+    this.localFlagFilename = basename(getFeatureFlagStorePath());
+    this.remoteFlagFilename = basename(getRemoteFeatureFlagStorePath());
   }
 
   start(): void {
-    const dir = dirname(this.flagPath);
+    const dir = dirname(getFeatureFlagStorePath());
 
     // Ensure the directory exists so fs.watch() doesn't throw ENOENT
     // on a fresh instance where no flags have been persisted yet.
@@ -43,10 +49,14 @@ export class FeatureFlagWatcher {
 
     try {
       this.watcher = watch(dir, { persistent: false }, (_event, filename) => {
-        if (filename && filename !== this.flagFilename) {
+        if (
+          filename &&
+          filename !== this.localFlagFilename &&
+          filename !== this.remoteFlagFilename
+        ) {
           return;
         }
-        this.scheduleInvalidation();
+        this.scheduleInvalidation(filename ?? undefined);
       });
 
       log.info({ path: dir }, "Watching for feature flag file changes");
@@ -66,14 +76,30 @@ export class FeatureFlagWatcher {
     }
   }
 
-  private scheduleInvalidation(): void {
+  private scheduleInvalidation(filename?: string): void {
+    if (filename) {
+      this.pendingFilenames.add(filename);
+    }
+
     if (this.debounceTimer) {
       clearTimeout(this.debounceTimer);
     }
     this.debounceTimer = setTimeout(() => {
       this.debounceTimer = null;
-      clearFeatureFlagStoreCache();
-      log.info("Feature flag cache invalidated due to file change");
+
+      const filenames = this.pendingFilenames;
+      this.pendingFilenames = new Set<string>();
+
+      if (filenames.has(this.localFlagFilename)) {
+        clearFeatureFlagStoreCache();
+      }
+      if (filenames.has(this.remoteFlagFilename)) {
+        refreshRemoteFeatureFlagStoreCache();
+      }
+      log.info(
+        { filenames: [...filenames] },
+        "Feature flag cache invalidated due to file change",
+      );
     }, DEBOUNCE_MS);
   }
 }