@kodelyth/googlechat 2026.5.39 → 2026.5.42

package/src/monitor-webhook.ts

@@ -0,0 +1,303 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+import {
+  normalizeWebhookPath,
+  resolveRequestClientIp,
+  type FixedWindowRateLimiter,
+} from "klaw/plugin-sdk/webhook-ingress";
+import type { WebhookInFlightLimiter } from "klaw/plugin-sdk/webhook-request-guards";
+import { readJsonWebhookBodyOrReject } from "klaw/plugin-sdk/webhook-request-guards";
+import {
+  resolveWebhookTargetWithAuthOrReject,
+  withResolvedWebhookRequestPipeline,
+} from "klaw/plugin-sdk/webhook-targets";
+import { verifyGoogleChatRequest } from "./auth.js";
+import type { WebhookTarget } from "./monitor-types.js";
+import type {
+  GoogleChatEvent,
+  GoogleChatMessage,
+  GoogleChatSpace,
+  GoogleChatUser,
+} from "./types.js";
+
+function extractBearerToken(header: unknown): string {
+  const authHeader = Array.isArray(header)
+    ? typeof header[0] === "string"
+      ? header[0]
+      : ""
+    : typeof header === "string"
+      ? header
+      : "";
+  return normalizeLowercaseStringOrEmpty(authHeader).startsWith("bearer ")
+    ? authHeader.slice("bearer ".length).trim()
+    : "";
+}
+
+const ADD_ON_PREAUTH_MAX_BYTES = 16 * 1024;
+const ADD_ON_PREAUTH_TIMEOUT_MS = 3_000;
+
+type ParsedGoogleChatInboundPayload =
+  | { ok: true; event: GoogleChatEvent; addOnBearerToken: string }
+  | { ok: false };
+type ParsedGoogleChatInboundSuccess = Extract<ParsedGoogleChatInboundPayload, { ok: true }>;
+
+function parseGoogleChatInboundPayload(
+  raw: unknown,
+  res: ServerResponse,
+): ParsedGoogleChatInboundPayload {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    res.statusCode = 400;
+    res.end("invalid payload");
+    return { ok: false };
+  }
+
+  let eventPayload = raw;
+  let addOnBearerToken = "";
+
+  // Transform Google Workspace Add-on format to standard Chat API format.
+  const rawObj = raw as {
+    commonEventObject?: { hostApp?: string };
+    chat?: {
+      messagePayload?: { space?: GoogleChatSpace; message?: GoogleChatMessage };
+      user?: GoogleChatUser;
+      eventTime?: string;
+    };
+    authorizationEventObject?: { systemIdToken?: string };
+  };
+
+  if (rawObj.commonEventObject?.hostApp === "CHAT" && rawObj.chat?.messagePayload) {
+    const chat = rawObj.chat;
+    const messagePayload = chat.messagePayload;
+    eventPayload = {
+      type: "MESSAGE",
+      space: messagePayload?.space,
+      message: messagePayload?.message,
+      user: chat.user,
+      eventTime: chat.eventTime,
+    };
+    addOnBearerToken =
+      typeof rawObj.authorizationEventObject?.systemIdToken === "string"
+        ? rawObj.authorizationEventObject.systemIdToken.trim()
+        : "";
+  }
+
+  const event = eventPayload as GoogleChatEvent;
+  const eventType = event.type ?? (eventPayload as { eventType?: string }).eventType;
+  if (typeof eventType !== "string") {
+    res.statusCode = 400;
+    res.end("invalid payload");
+    return { ok: false };
+  }
+
+  if (!event.space || typeof event.space !== "object" || Array.isArray(event.space)) {
+    res.statusCode = 400;
+    res.end("invalid payload");
+    return { ok: false };
+  }
+
+  if (eventType === "MESSAGE") {
+    if (!event.message || typeof event.message !== "object" || Array.isArray(event.message)) {
+      res.statusCode = 400;
+      res.end("invalid payload");
+      return { ok: false };
+    }
+  }
+
+  return { ok: true, event, addOnBearerToken };
+}
+
+type GoogleChatWebhookAuthRejection = {
+  target: WebhookTarget;
+  reason: string;
+};
+
+async function verifyGoogleChatTargetAuth(
+  target: WebhookTarget,
+  bearer: string,
+): Promise<{ ok: true } | { ok: false; reason: string }> {
+  const verification = await verifyGoogleChatRequest({
+    bearer,
+    audienceType: target.audienceType,
+    audience: target.audience,
+    expectedAddOnPrincipal: target.account.config.appPrincipal,
+  });
+  return verification.ok ? { ok: true } : { ok: false, reason: verification.reason ?? "unknown" };
+}
+
+function logGoogleChatWebhookAuthRejections(rejections: GoogleChatWebhookAuthRejection[]): void {
+  for (const rejection of rejections) {
+    rejection.target.runtime.log?.(
+      `[${rejection.target.account.accountId}] Google Chat webhook auth rejected: ${rejection.reason}`,
+    );
+  }
+}
+
+function logGoogleChatWebhookAuthRejectedForTargets(
+  targets: readonly WebhookTarget[],
+  reason: string,
+): void {
+  logGoogleChatWebhookAuthRejections(targets.map((target) => ({ target, reason })));
+}
+
+async function resolveGoogleChatWebhookTargetWithAuthOrReject(params: {
+  targets: readonly WebhookTarget[];
+  res: ServerResponse;
+  bearer: string;
+}): Promise<WebhookTarget | null> {
+  const rejections: GoogleChatWebhookAuthRejection[] = [];
+  let verifiedTargetCount = 0;
+  const selectedTarget = await resolveWebhookTargetWithAuthOrReject({
+    targets: params.targets,
+    res: params.res,
+    isMatch: async (target) => {
+      const verification = await verifyGoogleChatTargetAuth(target, params.bearer);
+      if (verification.ok) {
+        verifiedTargetCount += 1;
+        return true;
+      }
+      rejections.push({ target, reason: verification.reason });
+      return false;
+    },
+  });
+  if (!selectedTarget && verifiedTargetCount === 0) {
+    logGoogleChatWebhookAuthRejections(rejections);
+  }
+  return selectedTarget;
+}
+
+export function warnAppPrincipalMisconfiguration(params: {
+  accountId: string;
+  audienceType?: string;
+  appPrincipal?: string | null;
+  log?: (message: string) => void;
+}): void {
+  if (params.audienceType !== "app-url") {
+    return;
+  }
+  const principal = params.appPrincipal?.trim();
+  if (!principal) {
+    params.log?.(
+      `[${params.accountId}] appPrincipal is missing for audienceType "app-url"; add-on token verification will fail. Set appPrincipal to the numeric OAuth 2.0 client ID (uniqueId, 21 digits), not an email.`,
+    );
+  } else if (principal.includes("@")) {
+    params.log?.(
+      `[${params.accountId}] appPrincipal "${principal}" looks like an email address. Set appPrincipal to the numeric OAuth 2.0 client ID (uniqueId, 21 digits), not an email.`,
+    );
+  }
+}
+
+export function createGoogleChatWebhookRequestHandler(params: {
+  webhookTargets: Map<string, WebhookTarget[]>;
+  webhookRateLimiter: FixedWindowRateLimiter;
+  webhookInFlightLimiter: WebhookInFlightLimiter;
+  processEvent: (event: GoogleChatEvent, target: WebhookTarget) => Promise<void>;
+}): (req: IncomingMessage, res: ServerResponse) => Promise<boolean> {
+  return async (req: IncomingMessage, res: ServerResponse): Promise<boolean> => {
+    const path = normalizeWebhookPath(new URL(req.url ?? "/", "http://localhost").pathname);
+    // Shared-path registrations use the same gateway proxy settings in normal runtime setup.
+    const config = params.webhookTargets.get(path)?.[0]?.config;
+    const clientIp =
+      resolveRequestClientIp(
+        req,
+        config?.gateway?.trustedProxies,
+        config?.gateway?.allowRealIpFallback === true,
+      ) ?? "unknown";
+
+    return await withResolvedWebhookRequestPipeline({
+      req,
+      res,
+      targetsByPath: params.webhookTargets,
+      allowMethods: ["POST"],
+      requireJsonContentType: true,
+      rateLimiter: params.webhookRateLimiter,
+      rateLimitKey: `${path}:${clientIp}`,
+      inFlightLimiter: params.webhookInFlightLimiter,
+      handle: async ({ targets }) => {
+        const headerBearer = extractBearerToken(req.headers.authorization);
+        let selectedTarget: WebhookTarget | null = null;
+        let parsedEvent: GoogleChatEvent | null = null;
+        const readAndParseEvent = async (
+          profile: "pre-auth" | "post-auth",
+        ): Promise<ParsedGoogleChatInboundSuccess | null> => {
+          const body = await readJsonWebhookBodyOrReject({
+            req,
+            res,
+            profile,
+            ...(profile === "pre-auth"
+              ? {
+                  maxBytes: ADD_ON_PREAUTH_MAX_BYTES,
+                  timeoutMs: ADD_ON_PREAUTH_TIMEOUT_MS,
+                }
+              : {}),
+            emptyObjectOnEmpty: false,
+            invalidJsonMessage: "invalid payload",
+          });
+          if (!body.ok) {
+            return null;
+          }
+
+          const parsed = parseGoogleChatInboundPayload(body.value, res);
+          return parsed.ok ? parsed : null;
+        };
+
+        if (headerBearer) {
+          selectedTarget = await resolveGoogleChatWebhookTargetWithAuthOrReject({
+            targets,
+            res,
+            bearer: headerBearer,
+          });
+          if (!selectedTarget) {
+            return true;
+          }
+
+          const parsed = await readAndParseEvent("post-auth");
+          if (!parsed) {
+            return true;
+          }
+          parsedEvent = parsed.event;
+        } else {
+          const parsed = await readAndParseEvent("pre-auth");
+          if (!parsed) {
+            return true;
+          }
+          parsedEvent = parsed.event;
+
+          if (!parsed.addOnBearerToken) {
+            logGoogleChatWebhookAuthRejectedForTargets(targets, "missing token");
+            res.statusCode = 401;
+            res.end("unauthorized");
+            return true;
+          }
+
+          selectedTarget = await resolveGoogleChatWebhookTargetWithAuthOrReject({
+            targets,
+            res,
+            bearer: parsed.addOnBearerToken,
+          });
+          if (!selectedTarget) {
+            return true;
+          }
+        }
+
+        if (!selectedTarget || !parsedEvent) {
+          res.statusCode = 401;
+          res.end("unauthorized");
+          return true;
+        }
+
+        const dispatchTarget = selectedTarget;
+        dispatchTarget.statusSink?.({ lastInboundAt: Date.now() });
+        params.processEvent(parsedEvent, dispatchTarget).catch((err) => {
+          dispatchTarget.runtime.error?.(
+            `[${dispatchTarget.account.accountId}] Google Chat webhook failed: ${String(err)}`,
+          );
+        });
+
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "application/json");
+        res.end("{}");
+        return true;
+      },
+    });
+  };
+}

package/src/monitor.reply-delivery.test.ts

@@ -0,0 +1,144 @@
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { KlawConfig } from "../runtime-api.js";
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+import type { GoogleChatCoreRuntime, GoogleChatRuntimeEnv } from "./monitor-types.js";
+
+const mocks = vi.hoisted(() => ({
+  deleteGoogleChatMessage: vi.fn(),
+  sendGoogleChatMessage: vi.fn(),
+  updateGoogleChatMessage: vi.fn(),
+  uploadGoogleChatAttachment: vi.fn(),
+}));
+
+vi.mock("./api.js", () => ({
+  deleteGoogleChatMessage: mocks.deleteGoogleChatMessage,
+  sendGoogleChatMessage: mocks.sendGoogleChatMessage,
+  updateGoogleChatMessage: mocks.updateGoogleChatMessage,
+  uploadGoogleChatAttachment: mocks.uploadGoogleChatAttachment,
+}));
+
+const account = {
+  accountId: "default",
+  enabled: true,
+  credentialSource: "inline",
+  config: {},
+} as ResolvedGoogleChatAccount;
+
+const config = {} as KlawConfig;
+
+function createCore(params?: {
+  chunks?: readonly string[];
+  media?: { buffer: Buffer; contentType?: string; fileName?: string };
+}) {
+  return {
+    channel: {
+      text: {
+        resolveChunkMode: vi.fn(() => "markdown"),
+        chunkMarkdownTextWithMode: vi.fn((text: string) => params?.chunks ?? [text]),
+      },
+      media: {
+        readRemoteMediaBuffer: vi.fn(async () => params?.media ?? { buffer: Buffer.from("image") }),
+      },
+    },
+  } as unknown as GoogleChatCoreRuntime;
+}
+
+function createRuntime() {
+  return {
+    error: vi.fn(),
+    log: vi.fn(),
+  } satisfies GoogleChatRuntimeEnv;
+}
+
+let deliverGoogleChatReply: typeof import("./monitor-reply-delivery.js").deliverGoogleChatReply;
+
+beforeEach(async () => {
+  vi.clearAllMocks();
+  ({ deliverGoogleChatReply } = await import("./monitor-reply-delivery.js"));
+});
+
+afterAll(() => {
+  vi.doUnmock("./api.js");
+  vi.resetModules();
+});
+
+describe("Google Chat reply delivery", () => {
+  it("resends the first text chunk as a new message when typing update fails", async () => {
+    const core = createCore({ chunks: ["first chunk", "second chunk"] });
+    const runtime = createRuntime();
+    const statusSink = vi.fn();
+    mocks.updateGoogleChatMessage.mockRejectedValueOnce(new Error("message not found"));
+    mocks.sendGoogleChatMessage.mockResolvedValue({ messageName: "spaces/AAA/messages/fallback" });
+
+    await deliverGoogleChatReply({
+      payload: { text: "first chunk\n\nsecond chunk", replyToId: "spaces/AAA/threads/root" },
+      account,
+      spaceId: "spaces/AAA",
+      runtime,
+      core,
+      config,
+      statusSink,
+      typingMessageName: "spaces/AAA/messages/typing",
+    });
+
+    expect(mocks.updateGoogleChatMessage).toHaveBeenCalledWith({
+      account,
+      messageName: "spaces/AAA/messages/typing",
+      text: "first chunk",
+    });
+    expect(mocks.sendGoogleChatMessage).toHaveBeenCalledTimes(2);
+    expect(mocks.sendGoogleChatMessage).toHaveBeenNthCalledWith(1, {
+      account,
+      space: "spaces/AAA",
+      text: "first chunk",
+      thread: "spaces/AAA/threads/root",
+    });
+    expect(mocks.sendGoogleChatMessage).toHaveBeenNthCalledWith(2, {
+      account,
+      space: "spaces/AAA",
+      text: "second chunk",
+      thread: "spaces/AAA/threads/root",
+    });
+    expect(statusSink).toHaveBeenCalledTimes(2);
+    expect(runtime.error).toHaveBeenCalledWith(
+      "Google Chat message send failed: Error: message not found",
+    );
+  });
+
+  it("does not update a deleted typing message before sending media with a caption", async () => {
+    const core = createCore({
+      media: { buffer: Buffer.from("image"), contentType: "image/png", fileName: "reply.png" },
+    });
+    const runtime = createRuntime();
+    mocks.deleteGoogleChatMessage.mockResolvedValue(undefined);
+    mocks.uploadGoogleChatAttachment.mockResolvedValue({ attachmentUploadToken: "upload-token" });
+    mocks.sendGoogleChatMessage.mockResolvedValue({ messageName: "spaces/AAA/messages/media" });
+
+    await deliverGoogleChatReply({
+      payload: {
+        text: "caption",
+        mediaUrl: "https://example.invalid/reply.png",
+        replyToId: "spaces/AAA/threads/root",
+      },
+      account,
+      spaceId: "spaces/AAA",
+      runtime,
+      core,
+      config,
+      typingMessageName: "spaces/AAA/messages/typing",
+    });
+
+    expect(mocks.deleteGoogleChatMessage).toHaveBeenCalledWith({
+      account,
+      messageName: "spaces/AAA/messages/typing",
+    });
+    expect(mocks.updateGoogleChatMessage).not.toHaveBeenCalled();
+    expect(mocks.sendGoogleChatMessage).toHaveBeenCalledWith({
+      account,
+      space: "spaces/AAA",
+      text: "caption",
+      thread: "spaces/AAA/threads/root",
+      attachments: [{ attachmentUploadToken: "upload-token", contentName: "reply.png" }],
+    });
+  });
+});

package/src/monitor.test.ts

@@ -0,0 +1,159 @@
+import { recordChannelBotPairLoopAndCheckSuppression } from "klaw/plugin-sdk/inbound-reply-dispatch";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+import type { GoogleChatCoreRuntime, GoogleChatRuntimeEnv } from "./monitor-types.js";
+import { testing } from "./monitor.js";
+import type { GoogleChatEvent } from "./types.js";
+
+const apiMocks = vi.hoisted(() => ({
+  downloadGoogleChatMedia: vi.fn(),
+  sendGoogleChatMessage: vi.fn(),
+}));
+
+const accessMocks = vi.hoisted(() => ({
+  applyGoogleChatInboundAccessPolicy: vi.fn(),
+}));
+
+vi.mock("./api.js", () => ({
+  downloadGoogleChatMedia: apiMocks.downloadGoogleChatMedia,
+  sendGoogleChatMessage: apiMocks.sendGoogleChatMessage,
+}));
+
+vi.mock("./monitor-access.js", () => ({
+  applyGoogleChatInboundAccessPolicy: accessMocks.applyGoogleChatInboundAccessPolicy,
+}));
+
+beforeEach(() => {
+  apiMocks.downloadGoogleChatMedia.mockReset();
+  apiMocks.sendGoogleChatMessage.mockReset();
+  accessMocks.applyGoogleChatInboundAccessPolicy.mockReset();
+});
+
+describe("googlechat monitor bot loop protection", () => {
+  it("maps accepted bot-authored messages to shared channel-turn facts", () => {
+    expect(
+      testing.resolveGoogleChatBotLoopProtection({
+        allowBots: true,
+        isBotSender: true,
+        senderId: "users/other-bot",
+        appUserId: "users/app-bot",
+        accountId: "work",
+        conversationId: "spaces/AAA",
+        config: { maxEventsPerWindow: 3 },
+        defaultsConfig: { maxEventsPerWindow: 20 },
+        eventTime: "2026-03-22T00:00:00.000Z",
+      }),
+    ).toEqual({
+      scopeId: "work",
+      conversationId: "spaces/AAA",
+      senderId: "users/other-bot",
+      receiverId: "users/app-bot",
+      config: { maxEventsPerWindow: 3 },
+      defaultsConfig: { maxEventsPerWindow: 20 },
+      defaultEnabled: true,
+      nowMs: Date.parse("2026-03-22T00:00:00.000Z"),
+    });
+  });
+
+  it("does not guard human messages or the app's own echo", () => {
+    expect(
+      testing.resolveGoogleChatBotLoopProtection({
+        allowBots: true,
+        isBotSender: false,
+        senderId: "users/alice",
+        appUserId: "users/app",
+        accountId: "work",
+        conversationId: "spaces/AAA",
+      }),
+    ).toBeUndefined();
+    expect(
+      testing.resolveGoogleChatBotLoopProtection({
+        allowBots: true,
+        isBotSender: true,
+        senderId: "users/app",
+        appUserId: "users/app",
+        accountId: "work",
+        conversationId: "spaces/AAA",
+      }),
+    ).toBeUndefined();
+  });
+
+  it("layers space bot loop overrides over account settings field-by-field", () => {
+    expect(
+      testing.resolveGoogleChatBotLoopProtectionConfig({
+        accountConfig: { windowSeconds: 120, cooldownSeconds: 240 },
+        groupConfig: { maxEventsPerWindow: 3 },
+      }),
+    ).toEqual({
+      maxEventsPerWindow: 3,
+      windowSeconds: 120,
+      cooldownSeconds: 240,
+    });
+  });
+
+  it("suppresses bot loops before creating typing messages", async () => {
+    const eventTimeMs = Date.parse("2026-03-22T00:00:00.000Z");
+    const accountId = `bot-loop-typing-${eventTimeMs}`;
+    const conversationId = "spaces/LOOP";
+    const senderId = "users/other-bot";
+    const receiverId = "users/app";
+    const runTurn = vi.fn();
+    const core = {
+      logging: { shouldLogVerbose: () => false },
+      channel: {
+        turn: { run: runTurn },
+      },
+    } as unknown as GoogleChatCoreRuntime;
+    const runtime = { error: vi.fn(), log: vi.fn() } satisfies GoogleChatRuntimeEnv;
+    const account = {
+      accountId,
+      config: {
+        allowBots: true,
+        botUser: receiverId,
+        botLoopProtection: { maxEventsPerWindow: 1, windowSeconds: 60, cooldownSeconds: 60 },
+        typingIndicator: "message",
+      },
+      credentialSource: "inline",
+    } as ResolvedGoogleChatAccount;
+    const event = {
+      type: "MESSAGE",
+      eventTime: "2026-03-22T00:00:00.001Z",
+      space: { name: conversationId, type: "DM" },
+      message: {
+        name: "spaces/LOOP/messages/2",
+        text: "loop",
+        sender: { name: senderId, type: "BOT" },
+      },
+    } satisfies GoogleChatEvent;
+
+    accessMocks.applyGoogleChatInboundAccessPolicy.mockResolvedValue({
+      ok: true,
+      commandAuthorized: undefined,
+      effectiveWasMentioned: undefined,
+      groupBotLoopProtection: undefined,
+      groupSystemPrompt: undefined,
+    });
+    recordChannelBotPairLoopAndCheckSuppression({
+      scopeId: accountId,
+      conversationId,
+      senderId,
+      receiverId,
+      config: account.config.botLoopProtection,
+      defaultEnabled: true,
+      nowMs: eventTimeMs,
+    });
+
+    await testing.processMessageWithPipeline({
+      event,
+      account,
+      config: {},
+      runtime,
+      core,
+      mediaMaxMb: 10,
+    });
+
+    expect(apiMocks.sendGoogleChatMessage).not.toHaveBeenCalled();
+    expect(apiMocks.downloadGoogleChatMedia).not.toHaveBeenCalled();
+    expect(runTurn).not.toHaveBeenCalled();
+  });
+});