@jami-studio/dispatch 0.13.14

package/src/server/lib/dispatch-integrations.spec.ts

@@ -0,0 +1,277 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  consumeLinkToken: vi.fn(),
+  resolveLinkedOwner: vi.fn(),
+  resolveOrgIdForEmail: vi.fn(),
+}));
+
+vi.mock("./dispatch-store.js", () => ({
+  consumeLinkToken: mocks.consumeLinkToken,
+  resolveLinkedOwner: mocks.resolveLinkedOwner,
+}));
+
+vi.mock("@agent-native/core/org", () => ({
+  resolveOrgIdForEmail: mocks.resolveOrgIdForEmail,
+}));
+
+import type {
+  IncomingMessage,
+  PlatformAdapter,
+} from "@agent-native/core/server";
+
+import {
+  beforeDispatchProcess,
+  identityKeyForIncoming,
+  resolveDispatchOwner,
+} from "./dispatch-integrations.js";
+
+const originalFetch = globalThis.fetch;
+
+function slackIncoming(
+  overrides: Partial<IncomingMessage> = {},
+): IncomingMessage {
+  return {
+    platform: "slack",
+    externalThreadId: "C1:123.456",
+    text: "make a deck",
+    senderId: "U123",
+    senderName: "U123",
+    platformContext: { teamId: "T123", channelId: "C1" },
+    timestamp: 1,
+    ...overrides,
+  };
+}
+
+function emailIncoming(
+  overrides: Partial<IncomingMessage> = {},
+): IncomingMessage {
+  return {
+    platform: "email",
+    externalThreadId: "victim@member.test::<root@member.test>",
+    text: "transfer everything",
+    senderId: "victim@member.test",
+    senderName: "Victim",
+    platformContext: { from: "victim@member.test" },
+    timestamp: 1,
+    ...overrides,
+  };
+}
+
+function telegramIncoming(
+  overrides: Partial<IncomingMessage> = {},
+): IncomingMessage {
+  return {
+    platform: "telegram",
+    externalThreadId: "12345",
+    text: "ask analytics about traffic",
+    senderId: "777",
+    senderName: "Steve",
+    platformContext: { chatId: 12345, fromId: 777, rawText: "hello" },
+    timestamp: 1,
+    ...overrides,
+  };
+}
+
+const noopAdapter: PlatformAdapter = {
+  platform: "telegram",
+  label: "Telegram",
+  getRequiredEnvKeys: () => [],
+  handleVerification: async () => ({ handled: false }),
+  verifyWebhook: async () => true,
+  parseIncomingMessage: async () => null,
+  sendResponse: async () => {},
+  formatAgentResponse: (text: string) => ({ text, platformContext: {} }),
+  getStatus: async () => ({
+    platform: "telegram",
+    label: "Telegram",
+    enabled: true,
+    configured: true,
+  }),
+};
+
+beforeEach(() => {
+  mocks.resolveLinkedOwner.mockResolvedValue(null);
+  mocks.consumeLinkToken.mockResolvedValue("owner@example.test");
+  mocks.resolveOrgIdForEmail.mockResolvedValue(null);
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => new Response(JSON.stringify({ ok: false }))),
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.unstubAllGlobals();
+  globalThis.fetch = originalFetch;
+  vi.clearAllMocks();
+});
+
+describe("identityKeyForIncoming", () => {
+  it("scopes Slack identities by team", () => {
+    expect(identityKeyForIncoming(slackIncoming())).toBe("T123:U123");
+  });
+
+  it("uses Telegram sender ids as link identities", () => {
+    expect(identityKeyForIncoming(telegramIncoming())).toBe("777");
+  });
+});
+
+describe("resolveDispatchOwner", () => {
+  it("uses a linked identity before Slack email lookup", async () => {
+    mocks.resolveLinkedOwner.mockResolvedValueOnce("linked@example.test");
+    vi.stubEnv("SLACK_BOT_TOKEN", "xoxb-token");
+
+    await expect(resolveDispatchOwner(slackIncoming())).resolves.toBe(
+      "linked@example.test",
+    );
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+  });
+
+  it("uses the verified Slack email for org members", async () => {
+    vi.stubEnv("SLACK_BOT_TOKEN", "xoxb-token");
+    mocks.resolveOrgIdForEmail.mockResolvedValueOnce("org_123");
+    vi.mocked(globalThis.fetch).mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          ok: true,
+          user: {
+            real_name: "Slack User",
+            profile: { email: "USER@EXAMPLE.TEST", display_name: "User" },
+          },
+        }),
+      ),
+    );
+
+    const incoming = slackIncoming();
+
+    await expect(resolveDispatchOwner(incoming)).resolves.toBe(
+      "user@example.test",
+    );
+    expect(incoming.senderEmail).toBe("user@example.test");
+    expect(incoming.senderName).toBe("User");
+    expect(incoming.platformContext.senderEmail).toBe("user@example.test");
+  });
+
+  it("falls back to the configured Slack owner when the sender is not an org member", async () => {
+    vi.stubEnv("SLACK_BOT_TOKEN", "xoxb-token");
+    vi.stubEnv("DISPATCH_DEFAULT_OWNER_EMAIL", "default@example.test");
+    vi.mocked(globalThis.fetch).mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          ok: true,
+          user: { profile: { email: "guest@example.test" } },
+        }),
+      ),
+    );
+
+    await expect(resolveDispatchOwner(slackIncoming())).resolves.toBe(
+      "default@example.test",
+    );
+  });
+
+  it("does NOT impersonate an org member from an unverified (spoofed) email From", async () => {
+    // Attacker spoofs From: victim@member.test, which IS a real org member —
+    // but the message is unverified (no DKIM/SPF pass). Must fall through to
+    // the synthetic, credential-less owner, NOT the victim's identity.
+    mocks.resolveOrgIdForEmail.mockResolvedValue("org_123");
+
+    const owner = await resolveDispatchOwner(
+      emailIncoming({ senderVerified: false }),
+    );
+
+    expect(owner).not.toBe("victim@member.test");
+    expect(owner).toMatch(/@integration\.local$/);
+  });
+
+  it("does NOT impersonate when sender is verified but not an org member", async () => {
+    mocks.resolveOrgIdForEmail.mockResolvedValue(null);
+
+    const owner = await resolveDispatchOwner(
+      emailIncoming({
+        senderId: "stranger@outside.test",
+        platformContext: { from: "stranger@outside.test" },
+        senderVerified: true,
+      }),
+    );
+
+    expect(owner).not.toBe("stranger@outside.test");
+    expect(owner).toMatch(/@integration\.local$/);
+  });
+
+  it("uses the email sender as owner when verified AND an org member", async () => {
+    mocks.resolveOrgIdForEmail.mockResolvedValue("org_123");
+
+    await expect(
+      resolveDispatchOwner(emailIncoming({ senderVerified: true })),
+    ).resolves.toBe("victim@member.test");
+  });
+
+  it("honors a linked identity for email regardless of verification", async () => {
+    mocks.resolveLinkedOwner.mockResolvedValueOnce("linked@member.test");
+
+    await expect(
+      resolveDispatchOwner(emailIncoming({ senderVerified: false })),
+    ).resolves.toBe("linked@member.test");
+    expect(mocks.resolveOrgIdForEmail).not.toHaveBeenCalled();
+  });
+
+  it("restores legacy trust-From behavior under the escape hatch", async () => {
+    vi.stubEnv("DISPATCH_TRUST_UNVERIFIED_EMAIL_SENDER", "1");
+
+    await expect(
+      resolveDispatchOwner(emailIncoming({ senderVerified: false })),
+    ).resolves.toBe("victim@member.test");
+  });
+});
+
+describe("beforeDispatchProcess", () => {
+  it("asks unlinked Telegram users to link before using org context", async () => {
+    vi.stubEnv("APP_URL", "https://dispatch.agent-native.test");
+
+    const result = await beforeDispatchProcess(telegramIncoming(), noopAdapter);
+
+    expect(result).toEqual({
+      handled: true,
+      responseText:
+        "Telegram is connected, but this Telegram account is not linked to an Agent-Native user yet. Tap https://dispatch.agent-native.test/identities, create a Telegram link token, then send `/link <token>` here. After that I can use your Builder.io org and connected apps.",
+    });
+    expect(mocks.resolveLinkedOwner).toHaveBeenCalledWith("telegram", "777", {
+      allowAnyOrgFallback: true,
+    });
+  });
+
+  it("lets linked Telegram users proceed to normal agent processing", async () => {
+    mocks.resolveLinkedOwner.mockResolvedValueOnce("steve@builder.io");
+
+    await expect(
+      beforeDispatchProcess(telegramIncoming(), noopAdapter),
+    ).resolves.toEqual({ handled: false });
+  });
+
+  it("still consumes Telegram link commands before enforcing the link gate", async () => {
+    const result = await beforeDispatchProcess(
+      telegramIncoming({
+        text: "token-123",
+        platformContext: {
+          chatId: 12345,
+          fromId: 777,
+          rawText: "/link token-123",
+        },
+      }),
+      noopAdapter,
+    );
+
+    expect(result).toEqual({
+      handled: true,
+      responseText:
+        "Linked successfully. Future telegram messages will use owner@example.test's personal dispatch context.",
+    });
+    expect(mocks.consumeLinkToken).toHaveBeenCalledWith({
+      platform: "telegram",
+      token: "token-123",
+      externalUserId: "777",
+      externalUserName: "Steve",
+    });
+  });
+});

package/src/server/lib/dispatch-integrations.ts

@@ -0,0 +1,302 @@
+import crypto from "node:crypto";
+
+import { resolveOrgIdForEmail } from "@agent-native/core/org";
+import { withConfiguredAppBasePath } from "@agent-native/core/server";
+import type {
+  IncomingMessage,
+  PlatformAdapter,
+} from "@agent-native/core/server";
+
+import { handleRemoteCodeCommand } from "./dispatch-remote-commands.js";
+import { consumeLinkToken, resolveLinkedOwner } from "./dispatch-store.js";
+
+type SlackSenderProfile = {
+  email: string | null;
+  name: string | null;
+};
+
+const slackProfileCache = new Map<
+  string,
+  { profile: SlackSenderProfile; expiresAt: number }
+>();
+const SLACK_PROFILE_CACHE_TTL = 10 * 60 * 1000;
+
+function contextString(value: unknown): string | null {
+  if (typeof value === "string" && value.trim()) return value.trim();
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return null;
+}
+
+export function identityKeyForIncoming(
+  incoming: IncomingMessage,
+): string | null {
+  const senderId = contextString(incoming.senderId);
+  if (!senderId) return null;
+
+  if (incoming.platform === "slack") {
+    const teamId = contextString(incoming.platformContext.teamId);
+    return teamId ? `${teamId}:${senderId}` : senderId;
+  }
+
+  if (incoming.platform === "whatsapp") {
+    const phoneNumberId = contextString(incoming.platformContext.phoneNumberId);
+    return phoneNumberId ? `${phoneNumberId}:${senderId}` : senderId;
+  }
+
+  if (incoming.platform === "email") {
+    return senderId.toLowerCase();
+  }
+
+  return senderId;
+}
+
+function fallbackOwnerForIncoming(incoming: IncomingMessage): string {
+  const tenant =
+    contextString(incoming.platformContext.teamId) ||
+    contextString(incoming.platformContext.phoneNumberId) ||
+    contextString(incoming.platformContext.chatId) ||
+    contextString(incoming.platformContext.from) ||
+    incoming.externalThreadId;
+  const raw = `${incoming.platform}:${tenant}:${incoming.senderId || ""}`;
+  const hash = crypto
+    .createHash("sha256")
+    .update(raw)
+    .digest("hex")
+    .slice(0, 16);
+  return `dispatch+${hash}@integration.local`;
+}
+
+function configuredDefaultOwnerForIncoming(
+  incoming: IncomingMessage,
+): string | null {
+  // This is intentionally Slack-only: a deployment-wide default owner grants
+  // that Slack workspace access to the owner's connected agents and org
+  // credentials, so other platforms should opt in with explicit identity links.
+  if (incoming.platform !== "slack") return null;
+  const email = process.env.DISPATCH_DEFAULT_OWNER_EMAIL?.trim();
+  if (!email) return null;
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) ? email : null;
+}
+
+function platformRequiresExplicitLink(incoming: IncomingMessage): boolean {
+  // Telegram does not provide a verified email address. Require an explicit
+  // identity link before it can act as a Builder/Agent-Native user.
+  return incoming.platform === "telegram";
+}
+
+function configuredDispatchIdentitiesUrl(): string | null {
+  const raw =
+    process.env.WORKSPACE_GATEWAY_URL ||
+    process.env.APP_URL ||
+    process.env.URL ||
+    process.env.DEPLOY_URL ||
+    process.env.BETTER_AUTH_URL ||
+    "";
+  if (!raw.trim()) return null;
+  const base = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+  try {
+    return new URL(
+      "identities",
+      `${withConfiguredAppBasePath(base).replace(/\/+$/, "")}/`,
+    ).toString();
+  } catch {
+    return null;
+  }
+}
+
+function formatTelegramLinkRequiredMessage(): string {
+  const identitiesUrl = configuredDispatchIdentitiesUrl();
+  const linkStep = identitiesUrl
+    ? `Tap ${identitiesUrl}, create a Telegram link token, then send \`/link <token>\` here.`
+    : "Open Dispatch while signed in, create a Telegram link token, then send `/link <token>` here.";
+  return `Telegram is connected, but this Telegram account is not linked to an Agent-Native user yet. ${linkStep} After that I can use your Builder.io org and connected apps.`;
+}
+
+async function resolveSlackSenderProfile(
+  incoming: IncomingMessage,
+): Promise<SlackSenderProfile> {
+  if (incoming.platform !== "slack") return { email: null, name: null };
+  const token = process.env.SLACK_BOT_TOKEN;
+  const userId = contextString(incoming.senderId);
+  const teamId = contextString(incoming.platformContext.teamId);
+  if (!token || !userId) return { email: null, name: null };
+
+  // Slack user IDs are scoped per workspace, so without a teamId we can't
+  // safely cache: two installs of the bot in different workspaces could
+  // share user-id strings and collide on a single "default" key. Skip the
+  // cache (and lookup on every request) when teamId is missing.
+  const cacheKey = teamId ? `${teamId}:${userId}` : null;
+  if (cacheKey) {
+    const cached = slackProfileCache.get(cacheKey);
+    if (cached && cached.expiresAt > Date.now()) return cached.profile;
+  }
+
+  try {
+    const params = new URLSearchParams({ user: userId });
+    const res = await fetch(`https://slack.com/api/users.info?${params}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const data = (await res.json()) as {
+      ok?: boolean;
+      user?: {
+        real_name?: string;
+        name?: string;
+        profile?: {
+          email?: string;
+          real_name?: string;
+          display_name?: string;
+        };
+      };
+    };
+    const profile = data.ok
+      ? {
+          email: data.user?.profile?.email?.trim().toLowerCase() || null,
+          name:
+            data.user?.profile?.real_name?.trim() ||
+            data.user?.profile?.display_name?.trim() ||
+            data.user?.real_name?.trim() ||
+            data.user?.name?.trim() ||
+            null,
+        }
+      : { email: null, name: null };
+    if (cacheKey) {
+      slackProfileCache.set(cacheKey, {
+        profile,
+        expiresAt: Date.now() + SLACK_PROFILE_CACHE_TTL,
+      });
+    }
+    return profile;
+  } catch {
+    return { email: null, name: null };
+  }
+}
+
+async function resolveSlackOwnerFromVerifiedEmail(
+  incoming: IncomingMessage,
+): Promise<string | null> {
+  const profile = await resolveSlackSenderProfile(incoming);
+  if (!profile.email) return null;
+
+  incoming.senderEmail = profile.email;
+  incoming.platformContext.senderEmail = profile.email;
+  if (profile.name) {
+    incoming.senderName = profile.name;
+    incoming.platformContext.senderName = profile.name;
+  }
+
+  const orgId = await resolveOrgIdForEmail(profile.email);
+  return orgId ? profile.email : null;
+}
+
+export async function resolveDispatchOwner(
+  incoming: IncomingMessage,
+): Promise<string> {
+  try {
+    const externalUserId = identityKeyForIncoming(incoming);
+
+    // Webhooks do not have the browser request's org context, so allow a safe
+    // cross-org fallback when the linked platform identity maps to one owner.
+    const owner = await resolveLinkedOwner(incoming.platform, externalUserId, {
+      allowAnyOrgFallback: true,
+    });
+    if (owner) return owner;
+
+    // For email, the sender's `From:` address is attacker-settable: SMTP lets
+    // anyone claim any From, and our inbound webhook secret only authenticates
+    // the provider→app hop, not the original sender. So we must NOT grant a
+    // real user's identity (their API keys, org secrets, personal
+    // instructions, ownable data) off the bare From. Mirror the Slack gate:
+    // only return the sender email as the acting owner when BOTH
+    //   (a) the message is DKIM/SPF-verified for the From domain, AND
+    //   (b) that email maps to a real org member.
+    // Otherwise fall through to the synthetic, credential-less fallback owner.
+    // (A linked identity, handled by resolveLinkedOwner above, remains an
+    // always-allowed way to bind an address regardless of verification.)
+    //
+    // Escape hatch: set DISPATCH_TRUST_UNVERIFIED_EMAIL_SENDER=1 to restore
+    // the legacy "trust the From header" behavior. OFF by default; only use
+    // this if you fully control the inbound mail path and accept that a
+    // spoofed From can act as any org member. See FINDING 3 (inbound-email
+    // impersonation) in the webhook security audit.
+    if (
+      incoming.platform === "email" &&
+      incoming.senderId &&
+      incoming.senderId.includes("@")
+    ) {
+      if (process.env.DISPATCH_TRUST_UNVERIFIED_EMAIL_SENDER === "1") {
+        return incoming.senderId;
+      }
+      if (incoming.senderVerified) {
+        const orgId = await resolveOrgIdForEmail(incoming.senderId);
+        if (orgId) return incoming.senderId;
+      }
+      // Unverified or not an org member — do not impersonate. Fall through to
+      // the synthetic fallback owner below.
+    }
+
+    // Slack gives us a user id in the event payload. Resolve it to a verified
+    // workspace email and use that user's own org context when they are an
+    // Agent-Native member, so artifacts created via @agent-native are visible
+    // when they open the target app.
+    if (incoming.platform === "slack") {
+      const slackOwner = await resolveSlackOwnerFromVerifiedEmail(incoming);
+      if (slackOwner) return slackOwner;
+    }
+
+    const defaultOwner = configuredDefaultOwnerForIncoming(incoming);
+    if (defaultOwner) return defaultOwner;
+
+    return fallbackOwnerForIncoming(incoming);
+  } catch {
+    const defaultOwner = configuredDefaultOwnerForIncoming(incoming);
+    if (defaultOwner) return defaultOwner;
+    return fallbackOwnerForIncoming(incoming);
+  }
+}
+
+export async function beforeDispatchProcess(
+  incoming: IncomingMessage,
+  adapter: PlatformAdapter,
+): Promise<{ handled: true; responseText?: string } | { handled: false }> {
+  const trimmed = incoming.text.trim();
+  const commandText =
+    contextString(incoming.platformContext.rawText) || trimmed;
+  const match = commandText.match(/^\/link(?:@\w+)?\s+([a-zA-Z0-9_-]+)$/);
+  if (!match) {
+    if (platformRequiresExplicitLink(incoming)) {
+      const owner = await resolveLinkedOwner(
+        incoming.platform,
+        identityKeyForIncoming(incoming),
+        { allowAnyOrgFallback: true },
+      );
+      if (!owner) {
+        return {
+          handled: true,
+          responseText: formatTelegramLinkRequiredMessage(),
+        };
+      }
+    }
+    return handleRemoteCodeCommand(incoming, adapter, {
+      resolveOwner: () => resolveDispatchOwner(incoming),
+    });
+  }
+
+  try {
+    const owner = await consumeLinkToken({
+      platform: incoming.platform,
+      token: match[1],
+      externalUserId: identityKeyForIncoming(incoming),
+      externalUserName: incoming.senderName || null,
+    });
+    return {
+      handled: true,
+      responseText: `Linked successfully. Future ${incoming.platform} messages will use ${owner}'s personal dispatch context.`,
+    };
+  } catch (error) {
+    return {
+      handled: true,
+      responseText:
+        error instanceof Error ? error.message : "Failed to link this account.",
+    };
+  }
+}