@vellumai/vellum-gateway 0.9.0-staging.1 → 0.9.0

package/node_modules/@vellumai/gateway-client/src/inbound-contract.ts

@@ -0,0 +1,105 @@
+/**
+ * Gateway → daemon inbound payload contract.
+ *
+ * Zod schema defining the wire format for messages forwarded from the
+ * gateway to the daemon via `POST /v1/channels/inbound`. Both services
+ * import from here so the contract is enforced at compile time.
+ *
+ * The gateway constructs this payload in `forwardToRuntime()` from the
+ * normalized `GatewayInboundEvent`; the daemon validates and consumes
+ * it in `handleChannelInbound()`.
+ */
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Command intent (channel-initiated commands, e.g. Telegram /start)
+// ---------------------------------------------------------------------------
+
+export const CommandIntentSchema = z.object({
+  type: z.string(),
+  payload: z.string().optional(),
+});
+
+export type CommandIntent = z.infer<typeof CommandIntentSchema>;
+
+// ---------------------------------------------------------------------------
+// Source metadata — structured fields forwarded from the gateway's
+// normalized inbound event. Replaces the untyped Record<string, unknown>.
+// ---------------------------------------------------------------------------
+
+export const SourceMetadataSchema = z
+  .object({
+    /** Provider-assigned update/event ID. */
+    updateId: z.string().optional(),
+    /** Provider message ID (e.g. Slack message `ts`). */
+    messageId: z.string().optional(),
+    /** Provider chat type (e.g. Telegram "private", "group"). */
+    chatType: z.string().optional(),
+    /** Thread/conversation-group ID (e.g. Slack `thread_ts`). */
+    threadId: z.string().optional(),
+    /** Channel name (e.g. Slack channel display name). */
+    channelName: z.string().optional(),
+    /** Actor's language code (e.g. "en", "es"). */
+    languageCode: z.string().optional(),
+    /** Whether the actor is a bot. */
+    isBot: z.boolean().optional(),
+    /** Actor's IANA timezone (e.g. "America/Los_Angeles"). */
+    timezone: z.string().optional(),
+    /** Human-readable timezone label (e.g. "Pacific Daylight Time"). */
+    timezoneLabel: z.string().optional(),
+    /** UTC offset in seconds. */
+    timezoneOffsetSeconds: z.number().optional(),
+    /** Slack-specific: actor is from an external workspace (Slack Connect). */
+    isStranger: z.boolean().optional(),
+    /** Slack-specific: actor is a guest / restricted account. */
+    isRestricted: z.boolean().optional(),
+    /** Transport-layer hints forwarded from the channel adapter. */
+    hints: z.array(z.string()).optional(),
+    /** Transport-layer UX brief. */
+    uxBrief: z.string().optional(),
+    /** Client-provided timezone for date formatting. */
+    clientTimezone: z.string().optional(),
+    /** Channel command intent (e.g. Telegram /start). */
+    commandIntent: CommandIntentSchema.optional(),
+    /** Slack-specific: whether the bot was @-mentioned. */
+    slackBotMentioned: z.boolean().optional(),
+    /** Slack workspace/team ID. */
+    account: z.string().optional(),
+
+    // Email-specific fields
+    /** Email subject line. */
+    emailSubject: z.string().optional(),
+    /** Email recipient address. */
+    emailRecipient: z.string().optional(),
+    /** Email In-Reply-To header. */
+    emailInReplyTo: z.string().optional(),
+    /** Email References header. */
+    emailReferences: z.string().optional(),
+  })
+  .passthrough();
+
+export type SourceMetadata = z.infer<typeof SourceMetadataSchema>;
+
+// ---------------------------------------------------------------------------
+// Runtime inbound payload — the full wire format
+// ---------------------------------------------------------------------------
+
+export const RuntimeInboundPayloadSchema = z.object({
+  sourceChannel: z.string(),
+  interface: z.string(),
+  conversationExternalId: z.string(),
+  externalMessageId: z.string(),
+  content: z.string(),
+  isEdit: z.boolean().optional(),
+  callbackQueryId: z.string().optional(),
+  callbackData: z.string().optional(),
+  actorDisplayName: z.string().optional(),
+  actorExternalId: z.string(),
+  actorUsername: z.string().optional(),
+  sourceMetadata: SourceMetadataSchema.optional(),
+  attachmentIds: z.array(z.string()).optional(),
+  replyCallbackUrl: z.string().optional(),
+});
+
+export type RuntimeInboundPayload = z.infer<typeof RuntimeInboundPayloadSchema>;

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -32,3 +32,15 @@ export type {
 } from "./types.js";
 
 export { noopLogger } from "./types.js";
+
+export {
+  CommandIntentSchema,
+  RuntimeInboundPayloadSchema,
+  SourceMetadataSchema,
+} from "./inbound-contract.js";
+
+export type {
+  CommandIntent,
+  RuntimeInboundPayload,
+  SourceMetadata,
+} from "./inbound-contract.js";

package/package.json

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

package/src/__tests__/remote-web-ingress-denylist.test.ts

@@ -69,6 +69,7 @@ describe("remote web ingress denylist", () => {
       "/v1/guardian/init",
       "/v1/guardian/reset-bootstrap",
       "/v1/pair",
+      "/v1/remote-web/pairing-challenge",
     ]);
 
     for (const path of unprotectedV1Routes) {

package/src/__tests__/remote-web-pairing-challenge.test.ts

@@ -0,0 +1,115 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+
+const { handleCreateRemoteWebPairingChallenge } =
+  await import("../http/routes/remote-web-pairing-challenge.js");
+const {
+  getRemoteWebPairingChallengeForTests,
+  resetRemoteWebPairingChallengesForTests,
+  setRemoteWebPairingChallengeNowForTests,
+} = await import("../remote-web/pairing-challenge-store.js");
+
+const LOOPBACK_IP = "127.0.0.1";
+const PUBLIC_BASE_URL = "https://paired.example.com";
+
+function makeRequest(
+  overrides: { publicBaseUrl?: string; edgeForwarded?: boolean } = {},
+): Request {
+  const headers: Record<string, string> = {
+    host: "localhost:7830",
+    "content-type": "application/json",
+  };
+  if (overrides.edgeForwarded) {
+    headers["x-vellum-edge-forwarded"] = "1";
+  }
+  return new Request("http://localhost:7830/v1/remote-web/pairing-challenge", {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      publicBaseUrl: overrides.publicBaseUrl ?? PUBLIC_BASE_URL,
+    }),
+  });
+}
+
+beforeEach(() => {
+  resetRemoteWebPairingChallengesForTests();
+});
+
+describe("remote web pairing challenge", () => {
+  test("creates an RFC-style short-lived challenge over direct loopback", async () => {
+    setRemoteWebPairingChallengeNowForTests(() => 1_000);
+
+    const res = await handleCreateRemoteWebPairingChallenge(
+      makeRequest({ publicBaseUrl: `${PUBLIC_BASE_URL}/` }),
+      LOOPBACK_IP,
+    );
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Cache-Control")).toBe("no-store");
+
+    const body = (await res.json()) as {
+      deviceCode: string;
+      userCode: string;
+      verificationUri: string;
+      expiresAt: string;
+      expiresInSeconds: number;
+      intervalSeconds: number;
+    };
+    expect(body.deviceCode).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    expect(body.userCode).toMatch(/^[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}$/);
+    expect(body.verificationUri).toBe(`${PUBLIC_BASE_URL}/assistant/pair`);
+    expect(body.expiresAt).toBe("1970-01-01T00:10:01.000Z");
+    expect(body.expiresInSeconds).toBe(600);
+    expect(body.intervalSeconds).toBe(5);
+  });
+
+  test("preserves path-prefixed public base URLs in the verification URI", async () => {
+    const publicBaseUrl = "https://velay.example.test/assistant-123/";
+
+    const res = await handleCreateRemoteWebPairingChallenge(
+      makeRequest({ publicBaseUrl }),
+      LOOPBACK_IP,
+    );
+
+    expect(res.status).toBe(200);
+
+    const body = (await res.json()) as {
+      verificationUri: string;
+      userCode: string;
+    };
+    expect(body.verificationUri).toBe(
+      "https://velay.example.test/assistant-123/assistant/pair",
+    );
+
+    const record = getRemoteWebPairingChallengeForTests(body.userCode);
+    expect(record?.publicBaseUrl).toBe(
+      "https://velay.example.test/assistant-123",
+    );
+  });
+
+  test("stores only hashed challenge secrets", async () => {
+    const res = await handleCreateRemoteWebPairingChallenge(
+      makeRequest(),
+      LOOPBACK_IP,
+    );
+    const body = (await res.json()) as {
+      deviceCode: string;
+      userCode: string;
+    };
+
+    const record = getRemoteWebPairingChallengeForTests(body.userCode);
+
+    expect(record).toBeDefined();
+    expect(record?.deviceCodeHash).not.toBe(body.deviceCode);
+    expect(record?.userCodeHash).not.toBe(body.userCode);
+    expect(record?.publicBaseUrl).toBe(PUBLIC_BASE_URL);
+  });
+
+  test("rejects challenge creation through the nginx edge", async () => {
+    const res = await handleCreateRemoteWebPairingChallenge(
+      makeRequest({ edgeForwarded: true }),
+      LOOPBACK_IP,
+    );
+
+    expect(res.status).toBe(403);
+  });
+});

package/src/__tests__/route-schema-guard.test.ts

@@ -171,6 +171,8 @@ const EXCLUDED_FROM_SCHEMA = new Set([
   "catch-all",
   // Loopback-only pairing endpoint — not part of the public gateway API
   "/v1/pair",
+  // Loopback-only remote web pairing challenge — not part of the public gateway API
+  "/v1/remote-web/pairing-challenge",
   // Loopback-only device management — not part of the public gateway API
   "/v1/devices",
   "/v1/devices/revoke",

package/src/handlers/handle-inbound.ts

@@ -1,4 +1,5 @@
 import { existsSync } from "node:fs";
+import type { SourceMetadata } from "@vellumai/gateway-client";
 import type { GatewayConfig } from "../config.js";
 import { ipcCallAssistant } from "../ipc/assistant-client.js";
 import { resolveIpcSocketPath } from "../ipc/socket-path.js";
@@ -40,7 +41,7 @@ export type HandleInboundOptions = {
   /** When provided, skip resolveAssistant() and use this pre-resolved route. */
   routingOverride?: RouteResult;
   /** Extra fields merged into sourceMetadata (e.g. commandIntent). */
-  sourceMetadata?: Record<string, unknown>;
+  sourceMetadata?: Partial<SourceMetadata>;
 };
 
 function normalizeTransportHints(hints: string[] | undefined): string[] {

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

@@ -199,8 +199,10 @@ export function createEmailWebhookHandler(
         sourceMetadata: {
           emailSubject: (payload.subject as string | undefined) ?? undefined,
           emailRecipient: recipientAddress,
-          ...(payload.inReplyTo ? { emailInReplyTo: payload.inReplyTo } : {}),
-          ...(payload.references
+          ...(typeof payload.inReplyTo === "string"
+            ? { emailInReplyTo: payload.inReplyTo }
+            : {}),
+          ...(typeof payload.references === "string"
             ? { emailReferences: payload.references }
             : {}),
         },
@@ -242,7 +244,9 @@ export function createEmailWebhookHandler(
 
       if (!result.rejected) {
         const denied = result.runtimeResponse?.denied ?? false;
-        const deniedReason = denied ? (result.runtimeResponse?.reason ?? "unknown") : undefined;
+        const deniedReason = denied
+          ? (result.runtimeResponse?.reason ?? "unknown")
+          : undefined;
         tlog.info(
           {
             status: denied ? "denied" : "forwarded",

package/src/http/routes/remote-web-pairing-challenge.ts

@@ -0,0 +1,56 @@
+import { createRemoteWebPairingChallenge } from "../../remote-web/pairing-challenge-store.js";
+import { enforceLoopbackOnly } from "../loopback-guard.js";
+
+function parsePublicBaseUrl(value: unknown): string | null {
+  if (typeof value !== "string" || !value.trim()) return null;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+    if (!url.host) return null;
+    const pathPrefix = url.pathname.replace(/\/+$/, "");
+    return `${url.origin}${pathPrefix}`;
+  } catch {
+    return null;
+  }
+}
+
+function jsonError(code: string, message: string, status: number): Response {
+  return Response.json({ error: { code, message } }, { status });
+}
+
+export async function handleCreateRemoteWebPairingChallenge(
+  req: Request,
+  clientIp: string,
+): Promise<Response> {
+  if (req.method !== "POST") {
+    return new Response("method not allowed", {
+      status: 405,
+      headers: { Allow: "POST" },
+    });
+  }
+
+  const guardError = enforceLoopbackOnly(
+    req,
+    clientIp,
+    "remote-web-pairing-challenge",
+  );
+  if (guardError) return guardError;
+
+  let publicBaseUrl: string | null = null;
+  try {
+    const body = (await req.json()) as { publicBaseUrl?: unknown };
+    publicBaseUrl = parsePublicBaseUrl(body.publicBaseUrl);
+  } catch {
+    return jsonError("BAD_REQUEST", "invalid JSON body", 400);
+  }
+
+  if (!publicBaseUrl) {
+    return jsonError("BAD_REQUEST", "publicBaseUrl is required", 400);
+  }
+
+  const challenge = createRemoteWebPairingChallenge(publicBaseUrl);
+
+  return Response.json(challenge, {
+    headers: { "Cache-Control": "no-store" },
+  });
+}

package/src/index.ts

@@ -94,6 +94,7 @@ import {
   handleRevokeDevice,
 } from "./http/routes/devices.js";
 import { handlePair } from "./http/routes/pair.js";
+import { handleCreateRemoteWebPairingChallenge } from "./http/routes/remote-web-pairing-challenge.js";
 import { createSlackControlPlaneProxyHandler } from "./http/routes/slack-control-plane-proxy.js";
 import { createOAuthAppsProxyHandler } from "./http/routes/oauth-apps-proxy.js";
 import { createOAuthProvidersProxyHandler } from "./http/routes/oauth-providers-proxy.js";
@@ -830,6 +831,13 @@ async function main() {
       auth: "none",
       handler: (req, _params, getClientIp) => handlePair(req, getClientIp()),
     },
+    {
+      path: "/v1/remote-web/pairing-challenge",
+      method: "POST",
+      auth: "none",
+      handler: (req, _params, getClientIp) =>
+        handleCreateRemoteWebPairingChallenge(req, getClientIp()),
+    },
     // ── Device management (localhost-only, auth: none; self-guards loopback) ──
     {
       path: "/v1/devices",

package/src/remote-web/pairing-challenge-store.ts

@@ -0,0 +1,107 @@
+import { createHash, randomBytes, randomInt } from "node:crypto";
+
+const CODE_TTL_MS = 10 * 60 * 1000;
+const USER_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+const USER_CODE_LENGTH = 8;
+const DEVICE_CODE_BYTES = 32;
+const POLL_INTERVAL_SECONDS = 5;
+
+export interface PendingRemoteWebPairingChallenge {
+  deviceCodeHash: string;
+  userCodeHash: string;
+  publicBaseUrl: string;
+  verificationUri: string;
+  expiresAtMs: number;
+}
+
+export interface CreatedRemoteWebPairingChallenge {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  expiresAt: string;
+  expiresInSeconds: number;
+  intervalSeconds: number;
+}
+
+const challengesByUserCodeHash = new Map<
+  string,
+  PendingRemoteWebPairingChallenge
+>();
+let nowForTests: (() => number) | null = null;
+
+function nowMs(): number {
+  return nowForTests?.() ?? Date.now();
+}
+
+function hashSecret(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function randomUserCode(): string {
+  let code = "";
+  for (let i = 0; i < USER_CODE_LENGTH; i++) {
+    code += USER_CODE_ALPHABET[randomInt(USER_CODE_ALPHABET.length)];
+  }
+  return `${code.slice(0, 4)}-${code.slice(4)}`;
+}
+
+function normalizeUserCode(code: string): string {
+  return code.replace(/[^A-Z0-9]/gi, "").toUpperCase();
+}
+
+function cleanupExpiredChallenges(): void {
+  const now = nowMs();
+  for (const [hash, challenge] of challengesByUserCodeHash) {
+    if (challenge.expiresAtMs <= now) challengesByUserCodeHash.delete(hash);
+  }
+}
+
+export function createRemoteWebPairingChallenge(
+  publicBaseUrl: string,
+): CreatedRemoteWebPairingChallenge {
+  cleanupExpiredChallenges();
+
+  const deviceCode = randomBytes(DEVICE_CODE_BYTES).toString("base64url");
+  let userCode = randomUserCode();
+  let userCodeHash = hashSecret(normalizeUserCode(userCode));
+  while (challengesByUserCodeHash.has(userCodeHash)) {
+    userCode = randomUserCode();
+    userCodeHash = hashSecret(normalizeUserCode(userCode));
+  }
+
+  const verificationUri = `${publicBaseUrl}/assistant/pair`;
+  const expiresAtMs = nowMs() + CODE_TTL_MS;
+  challengesByUserCodeHash.set(userCodeHash, {
+    deviceCodeHash: hashSecret(deviceCode),
+    userCodeHash,
+    publicBaseUrl,
+    verificationUri,
+    expiresAtMs,
+  });
+
+  return {
+    deviceCode,
+    userCode,
+    verificationUri,
+    expiresAt: new Date(expiresAtMs).toISOString(),
+    expiresInSeconds: Math.ceil(CODE_TTL_MS / 1000),
+    intervalSeconds: POLL_INTERVAL_SECONDS,
+  };
+}
+
+export function resetRemoteWebPairingChallengesForTests(): void {
+  challengesByUserCodeHash.clear();
+  nowForTests = null;
+}
+
+export function setRemoteWebPairingChallengeNowForTests(
+  now: () => number,
+): void {
+  nowForTests = now;
+}
+
+export function getRemoteWebPairingChallengeForTests(
+  userCode: string,
+): PendingRemoteWebPairingChallenge | undefined {
+  return challengesByUserCodeHash.get(hashSecret(normalizeUserCode(userCode)));
+}

package/src/runtime/client.ts

@@ -7,7 +7,8 @@ import {
   TWILIO_PUBLIC_BASE_WSS_PLACEHOLDER,
 } from "@vellumai/service-contracts/twilio-ingress";
 
-import type { ChannelId, InterfaceId } from "../channels/types.js";
+import type { RuntimeInboundPayload } from "@vellumai/gateway-client";
+import type { ChannelId } from "../channels/types.js";
 import type { ConfigFileCache } from "../config-file-cache.js";
 import {
   mintIngressToken,
@@ -165,23 +166,7 @@ export class AttachmentValidationError extends Error {
   }
 }
 
-export type RuntimeInboundPayload = {
-  sourceChannel: ChannelId;
-  /** Explicit interface identifier forwarded to the assistant. */
-  interface: InterfaceId;
-  conversationExternalId: string;
-  externalMessageId: string;
-  content: string;
-  isEdit?: boolean;
-  callbackQueryId?: string;
-  callbackData?: string;
-  actorDisplayName?: string;
-  actorExternalId: string;
-  actorUsername?: string;
-  sourceMetadata?: Record<string, unknown>;
-  attachmentIds?: string[];
-  replyCallbackUrl?: string;
-};
+export type { RuntimeInboundPayload } from "@vellumai/gateway-client";
 
 export type RuntimeAttachmentMeta = {
   id: string;