@axiom-lattice/gateway 2.1.53 → 2.1.55

package/src/channels/lark/__tests__/verification.test.ts

@@ -0,0 +1,157 @@
+import type { FastifyRequest } from "fastify";
+import crypto from "crypto";
+import {
+  createLarkRequestVerifier,
+  decryptLarkPayload,
+  parseLarkRequestBody,
+} from "../verification";
+
+describe("createLarkRequestVerifier", () => {
+  it("accepts requests with the configured verification token", () => {
+    const verify = createLarkRequestVerifier({
+      enabled: true,
+      appId: "app-id",
+      appSecret: "app-secret",
+      verificationToken: "token-1",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+    });
+
+    const request = {
+      headers: {},
+      body: { token: "token-1" },
+    } as FastifyRequest;
+
+    expect(verify(request)).toBe(true);
+  });
+
+  it("rejects requests with the wrong verification token", () => {
+    const verify = createLarkRequestVerifier({
+      enabled: true,
+      appId: "app-id",
+      appSecret: "app-secret",
+      verificationToken: "token-1",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+    });
+
+    const request = {
+      headers: {},
+      body: { token: "token-2" },
+    } as FastifyRequest;
+
+    expect(verify(request)).toBe(false);
+  });
+
+  it("accepts requests carrying lark signature headers", () => {
+    const verify = createLarkRequestVerifier({
+      enabled: true,
+      appId: "app-id",
+      appSecret: "app-secret",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+    });
+
+    const request = {
+      headers: {
+        "x-lark-request-timestamp": "1712730010",
+        "x-lark-signature": "signature",
+      },
+      body: {},
+    } as FastifyRequest;
+
+    expect(verify(request)).toBe(true);
+  });
+
+  it("accepts v2 payloads that carry the token in header.token", () => {
+    const verify = createLarkRequestVerifier({
+      enabled: true,
+      appId: "app-id",
+      appSecret: "app-secret",
+      verificationToken: "token-1",
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+    });
+
+    const request = {
+      headers: {},
+      body: {
+        schema: "2.0",
+        header: {
+          token: "token-1",
+        },
+      },
+    } as FastifyRequest;
+
+    expect(verify(request)).toBe(true);
+  });
+
+  it("decrypts an encrypted lark payload", () => {
+    const encryptKey = "encrypt-key-1";
+    const payload = JSON.stringify({
+      type: "url_verification",
+      challenge: "challenge-1",
+      token: "token-1",
+    });
+    const encrypted = encryptForTest(encryptKey, payload);
+
+    expect(decryptLarkPayload(encryptKey, encrypted)).toEqual({
+      type: "url_verification",
+      challenge: "challenge-1",
+      token: "token-1",
+    });
+  });
+
+  it("parses encrypted payloads before token verification", () => {
+    const encryptKey = "encrypt-key-1";
+    const verify = createLarkRequestVerifier({
+      enabled: true,
+      appId: "app-id",
+      appSecret: "app-secret",
+      verificationToken: "token-1",
+      encryptKey,
+      tenantId: "tenant-a",
+      assistantId: "assistant-a",
+      mappingMode: "hybrid",
+    });
+
+    const encrypted = encryptForTest(
+      encryptKey,
+      JSON.stringify({
+        type: "url_verification",
+        challenge: "challenge-1",
+        token: "token-1",
+      }),
+    );
+
+    const request = {
+      headers: {},
+      body: {
+        encrypt: encrypted,
+      },
+    } as FastifyRequest;
+
+    expect(verify(request)).toBe(true);
+    expect(parseLarkRequestBody(request.body, encryptKey)).toEqual({
+      type: "url_verification",
+      challenge: "challenge-1",
+      token: "token-1",
+    });
+  });
+});
+
+function encryptForTest(encryptKey: string, plaintext: string): string {
+  const key = crypto.createHash("sha256").update(encryptKey).digest();
+  const iv = Buffer.alloc(16, 1);
+  const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(Buffer.from(plaintext, "utf8")),
+    cipher.final(),
+  ]);
+
+  return Buffer.concat([iv, ciphertext]).toString("base64");
+}

package/src/channels/lark/aggregator.ts

@@ -0,0 +1,16 @@
+import type { MessageChunk } from "@axiom-lattice/protocols";
+import { MessageChunkTypes } from "@axiom-lattice/protocols";
+
+export function aggregateLarkReply(
+  messageId: string,
+  chunks: MessageChunk[],
+): string {
+  return chunks
+    .filter(
+      (chunk) =>
+        chunk.type === MessageChunkTypes.AI && chunk.data.id === messageId,
+    )
+    .map((chunk) => chunk.data.content || "")
+    .join("")
+    .trim();
+}

package/src/channels/lark/config.ts

@@ -0,0 +1,44 @@
+import type { LarkIngressConfig } from "./types";
+
+export function loadLarkIngressConfig(): LarkIngressConfig {
+  return {
+    enabled: process.env.LARK_ENABLED !== "false",
+    appId: process.env.LARK_APP_ID || "",
+    appSecret: process.env.LARK_APP_SECRET || "",
+    verificationToken: process.env.LARK_VERIFICATION_TOKEN,
+    encryptKey: process.env.LARK_ENCRYPT_KEY,
+    tenantId: process.env.LARK_TENANT_ID || "default",
+    assistantId: process.env.LARK_ASSISTANT_ID || "default_agent",
+    workspaceId: process.env.LARK_WORKSPACE_ID,
+    projectId: process.env.LARK_PROJECT_ID,
+    mappingMode:
+      (process.env.LARK_MAPPING_MODE as "user" | "group" | "hybrid") ||
+      "hybrid",
+  };
+}
+
+export function isLarkIngressEnabled(config: LarkIngressConfig): boolean {
+  return config.enabled;
+}
+
+export function assertLarkIngressConfig(config: LarkIngressConfig): void {
+  if (!config.enabled) {
+    return;
+  }
+
+  if (!config.appId) {
+    throw new Error("LARK_APP_ID is required when Lark ingress is enabled");
+  }
+
+  if (!config.appSecret) {
+    throw new Error("LARK_APP_SECRET is required when Lark ingress is enabled");
+  }
+
+  if (!config.tenantId) {
+    throw new Error("LARK_TENANT_ID is required when Lark ingress is enabled");
+  }
+
+  if (!config.assistantId) {
+    throw new Error("LARK_ASSISTANT_ID is required when Lark ingress is enabled");
+  }
+}

package/src/channels/lark/controller.ts

@@ -0,0 +1,189 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { parseLarkMessageEvent } from "./parser";
+import type {
+  LarkIngressConfig,
+  LarkUrlVerificationPayload,
+  ParsedLarkMessageEvent,
+} from "./types";
+
+export interface LarkEventHandlerDependencies {
+  getInstallationConfig: (
+    installationId: string,
+  ) => Promise<LarkIngressConfig | null>;
+  parseRequestBody: (
+    body: unknown,
+    encryptKey?: string,
+  ) => LarkUrlVerificationPayload;
+  verifyParsedBody: (
+    body: LarkUrlVerificationPayload,
+    config: LarkIngressConfig,
+  ) => boolean;
+  parseEvent: (payload: unknown) => ParsedLarkMessageEvent | null;
+  claimInboundReceipt: (input: {
+    channel: string;
+    channelAppId: string;
+    externalMessageId: string;
+    tenantId: string;
+  }) => Promise<{ accepted: boolean; status: "processing" | "completed" }>;
+  markInboundReceiptCompleted: (input: {
+    channel: string;
+    channelAppId: string;
+    externalMessageId: string;
+    tenantId: string;
+    threadId: string;
+  }) => Promise<void>;
+  markInboundReceiptFailed: (input: {
+    channel: string;
+    channelAppId: string;
+    externalMessageId: string;
+    tenantId: string;
+  }) => Promise<void>;
+  resolveThread: (input: {
+    channel: string;
+    channelAppId: string;
+    tenantId: string;
+    assistantId: string;
+    mappingMode: "user" | "group" | "hybrid";
+    openId: string;
+    chatId: string;
+    chatType: "direct" | "group";
+    messageId: string;
+    workspaceId?: string;
+    projectId?: string;
+  }) => Promise<{ threadId: string }>;
+  runAgentAndCollectText: (input: {
+    tenantId: string;
+    assistantId: string;
+    threadId: string;
+    text: string;
+    workspaceId?: string;
+    projectId?: string;
+  }) => Promise<string>;
+  sendTextReply: (input: {
+    chatId: string;
+    text: string;
+    config: LarkIngressConfig;
+  }) => Promise<void>;
+}
+
+export function createLarkEventHandler(
+  dependencies: LarkEventHandlerDependencies,
+) {
+  return async function handleLarkEvent(
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ): Promise<void> {
+    const installationId = (request.params as { installationId?: string })
+      ?.installationId;
+
+    if (!installationId) {
+      reply.status(400).send({ success: false, message: "Missing installationId" });
+      return;
+    }
+
+    const config = await dependencies.getInstallationConfig(installationId);
+    if (!config) {
+      reply.status(404).send({ success: false, message: "Lark installation not found" });
+      return;
+    }
+
+    const body = dependencies.parseRequestBody(
+      request.body,
+      config.encryptKey,
+    ) as LarkUrlVerificationPayload;
+
+    if (!dependencies.verifyParsedBody(body, config)) {
+      reply.status(401).send({ success: false, message: "Invalid Lark request" });
+      return;
+    }
+
+    if (body.type === "url_verification" && body.challenge) {
+      reply.status(200).send({ challenge: body.challenge });
+      return;
+    }
+
+    const parsed = dependencies.parseEvent(request.body);
+    if (!parsed) {
+      reply.status(200).send({ success: true, ignored: true });
+      return;
+    }
+
+    const receipt = await dependencies.claimInboundReceipt({
+      channel: "lark",
+      channelAppId: config.appId,
+      externalMessageId: parsed.messageId,
+      tenantId: config.tenantId,
+    });
+
+    if (!receipt.accepted) {
+      reply.status(200).send(
+        receipt.status === "processing"
+          ? { success: true, processing: true }
+          : { success: true, duplicate: true },
+      );
+      return;
+    }
+
+    try {
+      const { threadId } = await dependencies.resolveThread({
+        channel: "lark",
+        channelAppId: config.appId,
+        tenantId: config.tenantId,
+        assistantId: config.assistantId,
+        mappingMode: config.mappingMode,
+        openId: parsed.openId,
+        chatId: parsed.chatId,
+        chatType: parsed.chatType,
+        messageId: parsed.messageId,
+        workspaceId: config.workspaceId,
+        projectId: config.projectId,
+      });
+
+      const text = await dependencies.runAgentAndCollectText({
+        tenantId: config.tenantId,
+        assistantId: config.assistantId,
+        threadId,
+        text: parsed.text,
+        workspaceId: config.workspaceId,
+        projectId: config.projectId,
+      });
+
+      await dependencies.sendTextReply({
+        chatId: parsed.chatId,
+        text,
+        config,
+      });
+
+      await dependencies.markInboundReceiptCompleted({
+        channel: "lark",
+        channelAppId: config.appId,
+        externalMessageId: parsed.messageId,
+        tenantId: config.tenantId,
+        threadId,
+      });
+
+      reply.status(200).send({ success: true, threadId });
+    } catch (error) {
+      await dependencies.markInboundReceiptFailed({
+        channel: "lark",
+        channelAppId: config.appId,
+        externalMessageId: parsed.messageId,
+        tenantId: config.tenantId,
+      });
+      throw error;
+    }
+  };
+}
+
+export const handleLarkEvent = createLarkEventHandler({
+  getInstallationConfig: async () => null,
+  parseRequestBody: (body) => (body || {}) as LarkUrlVerificationPayload,
+  verifyParsedBody: () => true,
+  parseEvent: parseLarkMessageEvent,
+  claimInboundReceipt: async () => ({ accepted: true, status: "processing" }),
+  markInboundReceiptCompleted: async () => undefined,
+  markInboundReceiptFailed: async () => undefined,
+  resolveThread: async () => ({ threadId: "" }),
+  runAgentAndCollectText: async () => "",
+  sendTextReply: async () => undefined,
+});

package/src/channels/lark/mapping-service.ts

@@ -0,0 +1,138 @@
+import type { ThreadStore } from "@axiom-lattice/protocols";
+import type { ChannelIdentityMappingStore } from "@axiom-lattice/pg-stores";
+import { randomUUID } from "crypto";
+
+interface GetOrCreateThreadInput {
+  channel: string;
+  channelAppId: string;
+  tenantId: string;
+  assistantId: string;
+  mappingMode: "user" | "group" | "hybrid";
+  openId: string;
+  chatId: string;
+  chatType: "direct" | "group";
+  messageId: string;
+  workspaceId?: string;
+  projectId?: string;
+}
+
+interface ChannelThreadMappingServiceDeps {
+  mappingStore: Pick<
+    ChannelIdentityMappingStore,
+    "getMappingBySubject" | "createMapping"
+  >;
+  threadStore: Pick<ThreadStore, "createThread" | "deleteThread">;
+  uuid?: () => string;
+}
+
+export function createChannelThreadMappingService(
+  deps: ChannelThreadMappingServiceDeps,
+) {
+  return {
+    async getOrCreateThread(input: GetOrCreateThreadInput): Promise<{ threadId: string }> {
+      const externalSubjectKey = buildExternalSubjectKey(input);
+      const existing = await deps.mappingStore.getMappingBySubject({
+        channel: input.channel,
+        channelAppId: input.channelAppId,
+        tenantId: input.tenantId,
+        assistantId: input.assistantId,
+        externalSubjectKey,
+      });
+
+      if (existing) {
+        return { threadId: existing.threadId };
+      }
+
+      const threadId = (deps.uuid || randomUUID)();
+
+      await deps.threadStore.createThread(input.tenantId, input.assistantId, threadId, {
+        metadata: {
+          tenantId: input.tenantId,
+          workspaceId: input.workspaceId,
+          projectId: input.projectId,
+          channel: input.channel,
+          larkChatId: input.chatId,
+          larkOpenId: input.openId,
+        },
+      });
+
+      try {
+        await deps.mappingStore.createMapping({
+          channel: input.channel,
+          channelAppId: input.channelAppId,
+          tenantId: input.tenantId,
+          assistantId: input.assistantId,
+          mappingMode: input.mappingMode,
+          externalSubjectType:
+            resolveSubjectType(input.mappingMode, input.chatType) === "user"
+              ? "user"
+              : "chat",
+          externalSubjectKey,
+          larkOpenId: input.openId,
+          larkChatId: input.chatId,
+          larkMessageId: input.messageId,
+          threadId,
+        });
+      } catch (error) {
+        if (!isUniqueViolation(error)) {
+          throw error;
+        }
+
+        const canonical = await deps.mappingStore.getMappingBySubject({
+          channel: input.channel,
+          channelAppId: input.channelAppId,
+          tenantId: input.tenantId,
+          assistantId: input.assistantId,
+          externalSubjectKey,
+        });
+
+        if (!canonical) {
+          throw error;
+        }
+
+        await deps.threadStore.deleteThread(input.tenantId, threadId);
+
+        return { threadId: canonical.threadId };
+      }
+
+      return { threadId };
+    },
+  };
+}
+
+function isUniqueViolation(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: string }).code === "23505"
+  );
+}
+
+function buildExternalSubjectKey(input: GetOrCreateThreadInput): string {
+  const subjectType = resolveSubjectType(input.mappingMode, input.chatType);
+  const subjectValue = subjectType === "user" ? input.openId : input.chatId;
+
+  return [
+    input.channel,
+    input.channelAppId,
+    `tenant:${input.tenantId}`,
+    `assistant:${input.assistantId}`,
+    `${subjectType}:${subjectValue}`,
+  ].join(":");
+}
+
+function resolveSubjectType(
+  mappingMode: "user" | "group" | "hybrid",
+  chatType: "direct" | "group",
+): "user" | "chat" {
+  if (mappingMode === "user") {
+    return "user";
+  }
+
+  if (mappingMode === "group") {
+    return "chat";
+  }
+
+  return chatType === "direct" ? "user" : "chat";
+}

package/src/channels/lark/parser.ts

@@ -0,0 +1,68 @@
+import type { ParsedLarkMessageEvent } from "./types";
+
+interface RawLarkPayload {
+  header?: {
+    event_type?: string;
+  };
+  event?: {
+    sender?: {
+      sender_id?: {
+        open_id?: string;
+      };
+    };
+    message?: {
+      message_id?: string;
+      chat_id?: string;
+      chat_type?: string;
+      message_type?: string;
+      content?: string;
+    };
+  };
+}
+
+export function parseLarkMessageEvent(
+  payload: unknown,
+): ParsedLarkMessageEvent | null {
+  const raw = payload as RawLarkPayload;
+
+  if (raw.header?.event_type !== "im.message.receive_v1") {
+    return null;
+  }
+
+  const message = raw.event?.message;
+  const openId = raw.event?.sender?.sender_id?.open_id;
+
+  if (!message || !openId || message.message_type !== "text") {
+    return null;
+  }
+
+  const parsedContent = parseLarkTextContent(message.content);
+  if (!message.message_id || !message.chat_id || !parsedContent) {
+    return null;
+  }
+
+  return {
+    messageId: message.message_id,
+    openId,
+    chatId: message.chat_id,
+    chatType: normalizeChatType(message.chat_type),
+    text: parsedContent,
+  };
+}
+
+function parseLarkTextContent(content: string | undefined): string | null {
+  if (!content) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(content) as { text?: string };
+    return typeof parsed.text === "string" ? parsed.text : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeChatType(chatType: string | undefined): "direct" | "group" {
+  return chatType === "p2p" ? "direct" : "group";
+}