@kodelyth/googlechat 2026.5.39 → 2026.5.42

package/src/auth.ts

@@ -0,0 +1,218 @@
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+import { fetchWithSsrFGuard } from "../runtime-api.js";
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+import {
+  testing as googleAuthRuntimeTesting,
+  getGoogleAuthTransport,
+  loadGoogleAuthRuntime,
+  resolveValidatedGoogleChatCredentials,
+} from "./google-auth.runtime.js";
+
+const CHAT_SCOPE = "https://www.googleapis.com/auth/chat.bot";
+const CHAT_ISSUER = "chat@system.gserviceaccount.com";
+// Google Workspace Add-ons use a different service account pattern
+const ADDON_ISSUER_PATTERN = /^service-\d+@gcp-sa-gsuiteaddons\.iam\.gserviceaccount\.com$/;
+const CHAT_CERTS_URL =
+  "https://www.googleapis.com/service_accounts/v1/metadata/x509/chat@system.gserviceaccount.com";
+
+async function readGoogleChatCertsResponse(response: Response): Promise<Record<string, string>> {
+  try {
+    return (await response.json()) as Record<string, string>;
+  } catch (cause) {
+    throw new Error("Google Chat cert fetch failed: malformed JSON response", { cause });
+  }
+}
+
+// Size-capped to prevent unbounded growth in long-running deployments (#4948)
+const MAX_AUTH_CACHE_SIZE = 32;
+type GoogleAuthModule = typeof import("google-auth-library");
+type GoogleAuthRuntime = {
+  GoogleAuth: GoogleAuthModule["GoogleAuth"];
+  OAuth2Client: GoogleAuthModule["OAuth2Client"];
+};
+type GoogleAuthInstance = InstanceType<GoogleAuthRuntime["GoogleAuth"]>;
+type GoogleAuthOptions = ConstructorParameters<GoogleAuthRuntime["GoogleAuth"]>[0];
+type GoogleAuthTransport = NonNullable<GoogleAuthOptions>["clientOptions"] extends {
+  transporter?: infer T;
+}
+  ? T
+  : never;
+type OAuth2ClientInstance = InstanceType<GoogleAuthRuntime["OAuth2Client"]>;
+
+const authCache = new Map<string, { key: string; auth: GoogleAuthInstance }>();
+
+let cachedCerts: { fetchedAt: number; certs: Record<string, string> } | null = null;
+let verifyClientPromise: Promise<OAuth2ClientInstance> | null = null;
+
+async function getVerifyClient(): Promise<OAuth2ClientInstance> {
+  if (!verifyClientPromise) {
+    verifyClientPromise = (async () => {
+      try {
+        const { OAuth2Client } = await loadGoogleAuthRuntime();
+        // google-auth-library types its transporter through gaxios' CJS surface,
+        // while the plugin imports the ESM entrypoint directly.
+        const transporter = (await getGoogleAuthTransport()) as unknown as GoogleAuthTransport;
+        return new OAuth2Client({ transporter });
+      } catch (error) {
+        verifyClientPromise = null;
+        throw error;
+      }
+    })();
+  }
+  return await verifyClientPromise;
+}
+
+function buildAuthKey(account: ResolvedGoogleChatAccount): string {
+  if (account.credentialsFile) {
+    return `file:${account.credentialsFile}`;
+  }
+  if (account.credentials) {
+    return `inline:${JSON.stringify(account.credentials)}`;
+  }
+  return "none";
+}
+
+async function getAuthInstance(account: ResolvedGoogleChatAccount): Promise<GoogleAuthInstance> {
+  const key = buildAuthKey(account);
+  const cached = authCache.get(account.accountId);
+  if (cached && cached.key === key) {
+    return cached.auth;
+  }
+  const [{ GoogleAuth }, rawTransporter, credentials] = await Promise.all([
+    loadGoogleAuthRuntime(),
+    getGoogleAuthTransport(),
+    resolveValidatedGoogleChatCredentials(account),
+  ]);
+  const transporter = rawTransporter as unknown as GoogleAuthTransport;
+
+  const evictOldest = () => {
+    if (authCache.size > MAX_AUTH_CACHE_SIZE) {
+      const oldest = authCache.keys().next().value;
+      if (oldest !== undefined) {
+        authCache.delete(oldest);
+      }
+    }
+  };
+
+  const auth = new GoogleAuth({
+    ...(credentials ? { credentials } : {}),
+    clientOptions: { transporter },
+    scopes: [CHAT_SCOPE],
+  });
+  authCache.set(account.accountId, { key, auth });
+  evictOldest();
+  return auth;
+}
+
+export async function getGoogleChatAccessToken(
+  account: ResolvedGoogleChatAccount,
+): Promise<string> {
+  const auth = await getAuthInstance(account);
+  const client = await auth.getClient();
+  const access = await client.getAccessToken();
+  const token = typeof access === "string" ? access : access?.token;
+  if (!token) {
+    throw new Error("Missing Google Chat access token");
+  }
+  return token;
+}
+
+async function fetchChatCerts(): Promise<Record<string, string>> {
+  const now = Date.now();
+  if (cachedCerts && now - cachedCerts.fetchedAt < 10 * 60 * 1000) {
+    return cachedCerts.certs;
+  }
+  const { response, release } = await fetchWithSsrFGuard({
+    url: CHAT_CERTS_URL,
+    auditContext: "googlechat.auth.certs",
+  });
+  try {
+    if (!response.ok) {
+      throw new Error(`Failed to fetch Chat certs (${response.status})`);
+    }
+    const certs = await readGoogleChatCertsResponse(response);
+    cachedCerts = { fetchedAt: now, certs };
+    return certs;
+  } finally {
+    await release();
+  }
+}
+
+export type GoogleChatAudienceType = "app-url" | "project-number";
+
+export async function verifyGoogleChatRequest(params: {
+  bearer?: string | null;
+  audienceType?: GoogleChatAudienceType | null;
+  audience?: string | null;
+  expectedAddOnPrincipal?: string | null;
+}): Promise<{ ok: boolean; reason?: string }> {
+  const bearer = params.bearer?.trim();
+  if (!bearer) {
+    return { ok: false, reason: "missing token" };
+  }
+  const audience = params.audience?.trim();
+  if (!audience) {
+    return { ok: false, reason: "missing audience" };
+  }
+  const audienceType = params.audienceType ?? null;
+
+  if (audienceType === "app-url") {
+    try {
+      const verifyClient = await getVerifyClient();
+      const ticket = await verifyClient.verifyIdToken({
+        idToken: bearer,
+        audience,
+      });
+      const payload = ticket.getPayload();
+      const email = normalizeLowercaseStringOrEmpty(payload?.email ?? "");
+      if (!payload?.email_verified) {
+        return { ok: false, reason: "email not verified" };
+      }
+      if (email === CHAT_ISSUER) {
+        return { ok: true };
+      }
+      if (!ADDON_ISSUER_PATTERN.test(email)) {
+        return { ok: false, reason: `invalid issuer: ${email}` };
+      }
+      const expectedAddOnPrincipal = normalizeLowercaseStringOrEmpty(
+        params.expectedAddOnPrincipal ?? "",
+      );
+      if (!expectedAddOnPrincipal) {
+        return { ok: false, reason: "missing add-on principal binding" };
+      }
+      const tokenPrincipal = normalizeLowercaseStringOrEmpty(payload?.sub ?? "");
+      if (!tokenPrincipal || tokenPrincipal !== expectedAddOnPrincipal) {
+        return {
+          ok: false,
+          reason: `unexpected add-on principal: ${tokenPrincipal || "<missing>"}`,
+        };
+      }
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, reason: err instanceof Error ? err.message : "invalid token" };
+    }
+  }
+
+  if (audienceType === "project-number") {
+    try {
+      const verifyClient = await getVerifyClient();
+      const certs = await fetchChatCerts();
+      await verifyClient.verifySignedJwtWithCertsAsync(bearer, certs, audience, [CHAT_ISSUER]);
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, reason: err instanceof Error ? err.message : "invalid token" };
+    }
+  }
+
+  return { ok: false, reason: "unsupported audience type" };
+}
+
+export const testing = {
+  resetGoogleChatAuthForTests(): void {
+    authCache.clear();
+    cachedCerts = null;
+    verifyClientPromise = null;
+    googleAuthRuntimeTesting.resetGoogleAuthRuntimeForTests();
+  },
+};
+export { testing as __testing };

package/src/channel-config.test.ts

@@ -0,0 +1,39 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { describe, expect, it } from "vitest";
+import { googlechatPlugin } from "./channel.js";
+
+describe("googlechatPlugin config adapter", () => {
+  it("keeps read-only accessors from resolving service account SecretRefs", () => {
+    const cfg = {
+      secrets: {
+        providers: {
+          google_chat_service_account: {
+            source: "file",
+            path: "/tmp/klaw-missing-google-chat-service-account",
+            mode: "singleValue",
+          },
+        },
+      },
+      channels: {
+        googlechat: {
+          serviceAccount: {
+            source: "file",
+            provider: "google_chat_service_account",
+            id: "value",
+          },
+          dm: {
+            allowFrom: ["users/123"],
+          },
+          defaultTo: "spaces/AAA",
+        },
+      },
+    } as KlawConfig;
+
+    expect(googlechatPlugin.config.resolveAllowFrom?.({ cfg, accountId: "default" })).toEqual([
+      "users/123",
+    ]);
+    expect(googlechatPlugin.config.resolveDefaultTo?.({ cfg, accountId: "default" })).toBe(
+      "spaces/AAA",
+    );
+  });
+});

package/src/channel.adapters.ts

@@ -0,0 +1,340 @@
+import { adaptScopedAccountAccessor } from "klaw/plugin-sdk/channel-config-helpers";
+import {
+  createMessageReceiptFromOutboundResults,
+  defineChannelMessageAdapter,
+  type MessageReceiptPartKind,
+} from "klaw/plugin-sdk/channel-message";
+import {
+  composeAccountWarningCollectors,
+  createAllowlistProviderOpenWarningCollector,
+} from "klaw/plugin-sdk/channel-policy";
+import {
+  createChannelDirectoryAdapter,
+  listResolvedDirectoryGroupEntriesFromMapKeys,
+  listResolvedDirectoryUserEntriesFromAllowFrom,
+} from "klaw/plugin-sdk/directory-runtime";
+import { createLazyRuntimeNamedExport } from "klaw/plugin-sdk/lazy-runtime";
+import type { OutboundMediaLoadOptions } from "klaw/plugin-sdk/outbound-media";
+import { sanitizeForPlainText } from "klaw/plugin-sdk/outbound-runtime";
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "klaw/plugin-sdk/string-coerce-runtime";
+import {
+  type ResolvedGoogleChatAccount,
+  chunkTextForOutbound,
+  readRemoteMediaBuffer,
+  isGoogleChatUserTarget,
+  loadOutboundMediaFromUrl,
+  missingTargetError,
+  normalizeGoogleChatTarget,
+  PAIRING_APPROVED_MESSAGE,
+  resolveChannelMediaMaxBytes,
+  resolveGoogleChatAccount,
+  resolveGoogleChatOutboundSpace,
+  type KlawConfig,
+} from "./channel.deps.runtime.js";
+import { resolveGoogleChatGroupRequireMention } from "./group-policy.js";
+
+const loadGoogleChatChannelRuntime = createLazyRuntimeNamedExport(
+  () => import("./channel.runtime.js"),
+  "googleChatChannelRuntime",
+);
+
+function createGoogleChatSendReceipt(params: {
+  messageId?: string;
+  chatId: string;
+  kind: MessageReceiptPartKind;
+}) {
+  const messageId = params.messageId?.trim();
+  return createMessageReceiptFromOutboundResults({
+    results: messageId
+      ? [
+          {
+            channel: "googlechat",
+            messageId,
+            chatId: params.chatId,
+            conversationId: params.chatId,
+          },
+        ]
+      : [],
+    threadId: params.chatId,
+    kind: params.kind,
+  });
+}
+
+export const formatAllowFromEntry = (entry: string) =>
+  normalizeLowercaseStringOrEmpty(
+    entry
+      .trim()
+      .replace(/^(googlechat|google-chat|gchat):/i, "")
+      .replace(/^user:/i, "")
+      .replace(/^users\//i, ""),
+  );
+
+const collectGoogleChatGroupPolicyWarnings =
+  createAllowlistProviderOpenWarningCollector<ResolvedGoogleChatAccount>({
+    providerConfigPresent: (cfg) => cfg.channels?.googlechat !== undefined,
+    resolveGroupPolicy: (account) => account.config.groupPolicy,
+    buildOpenWarning: {
+      surface: "Google Chat spaces",
+      openBehavior: "allows any space to trigger (mention-gated)",
+      remediation:
+        'Set channels.googlechat.groupPolicy="allowlist" and configure channels.googlechat.groups',
+    },
+  });
+
+const collectGoogleChatSecurityWarnings = composeAccountWarningCollectors<
+  ResolvedGoogleChatAccount,
+  {
+    cfg: KlawConfig;
+    account: ResolvedGoogleChatAccount;
+  }
+>(
+  collectGoogleChatGroupPolicyWarnings,
+  (account) =>
+    account.config.dm?.policy === "open" &&
+    '- Google Chat DMs are open to anyone. Set channels.googlechat.dm.policy="pairing" or "allowlist".',
+);
+
+export const googlechatGroupsAdapter = {
+  resolveRequireMention: resolveGoogleChatGroupRequireMention,
+};
+
+export const googlechatDirectoryAdapter = createChannelDirectoryAdapter({
+  listPeers: async (params) =>
+    listResolvedDirectoryUserEntriesFromAllowFrom<ResolvedGoogleChatAccount>({
+      ...params,
+      resolveAccount: adaptScopedAccountAccessor(resolveGoogleChatAccount),
+      resolveAllowFrom: (account) => account.config.dm?.allowFrom,
+      normalizeId: (entry) => normalizeGoogleChatTarget(entry) ?? entry,
+    }),
+  listGroups: async (params) =>
+    listResolvedDirectoryGroupEntriesFromMapKeys<ResolvedGoogleChatAccount>({
+      ...params,
+      resolveAccount: adaptScopedAccountAccessor(resolveGoogleChatAccount),
+      resolveGroups: (account) => account.config.groups,
+    }),
+});
+
+export const googlechatSecurityAdapter = {
+  dm: {
+    channelKey: "googlechat",
+    resolvePolicy: (account: ResolvedGoogleChatAccount) => account.config.dm?.policy,
+    resolveAllowFrom: (account: ResolvedGoogleChatAccount) => account.config.dm?.allowFrom,
+    allowFromPathSuffix: "dm.",
+    normalizeEntry: (raw: string) => formatAllowFromEntry(raw),
+  },
+  collectWarnings: collectGoogleChatSecurityWarnings,
+};
+
+export const googlechatThreadingAdapter = {
+  scopedAccountReplyToMode: {
+    resolveAccount: (cfg: KlawConfig, accountId?: string | null) =>
+      resolveGoogleChatAccount({ cfg, accountId }),
+    resolveReplyToMode: (account: ResolvedGoogleChatAccount, _chatType?: string | null) =>
+      account.config.replyToMode,
+    fallback: "off" as const,
+  },
+};
+
+export const googlechatPairingTextAdapter = {
+  idLabel: "googlechatUserId",
+  message: PAIRING_APPROVED_MESSAGE,
+  normalizeAllowEntry: (entry: string) => formatAllowFromEntry(entry),
+  notify: async ({
+    cfg,
+    id,
+    message,
+    accountId,
+  }: {
+    cfg: KlawConfig;
+    id: string;
+    message: string;
+    accountId?: string | null;
+  }) => {
+    const account = resolveGoogleChatAccount({ cfg: cfg, accountId });
+    if (account.credentialSource === "none") {
+      return;
+    }
+    const user = normalizeGoogleChatTarget(id) ?? id;
+    const target = isGoogleChatUserTarget(user) ? user : `users/${user}`;
+    const space = await resolveGoogleChatOutboundSpace({ account, target });
+    const { sendGoogleChatMessage } = await loadGoogleChatChannelRuntime();
+    await sendGoogleChatMessage({
+      account,
+      space,
+      text: message,
+    });
+  },
+};
+
+export const googlechatOutboundAdapter = {
+  base: {
+    deliveryMode: "direct" as const,
+    chunker: chunkTextForOutbound,
+    chunkerMode: "markdown" as const,
+    textChunkLimit: 4000,
+    sanitizeText: ({ text }: { text: string }) => sanitizeForPlainText(text),
+    resolveTarget: ({ to }: { to?: string }) => {
+      const trimmed = normalizeOptionalString(to) ?? "";
+
+      if (trimmed) {
+        const normalized = normalizeGoogleChatTarget(trimmed);
+        if (!normalized) {
+          return {
+            ok: false as const,
+            error: missingTargetError("Google Chat", "<spaces/{space}|users/{user}>"),
+          };
+        }
+        return { ok: true as const, to: normalized };
+      }
+
+      return {
+        ok: false as const,
+        error: missingTargetError("Google Chat", "<spaces/{space}|users/{user}>"),
+      };
+    },
+  },
+  attachedResults: {
+    channel: "googlechat" as const,
+    sendText: async ({
+      cfg,
+      to,
+      text,
+      accountId,
+      replyToId,
+      threadId,
+    }: {
+      cfg: KlawConfig;
+      to: string;
+      text: string;
+      accountId?: string | null;
+      replyToId?: string | null;
+      threadId?: string | number | null;
+    }) => {
+      const account = resolveGoogleChatAccount({
+        cfg: cfg,
+        accountId,
+      });
+      const space = await resolveGoogleChatOutboundSpace({ account, target: to });
+      const thread =
+        typeof threadId === "number" ? String(threadId) : (threadId ?? replyToId ?? undefined);
+      const { sendGoogleChatMessage } = await loadGoogleChatChannelRuntime();
+      const result = await sendGoogleChatMessage({
+        account,
+        space,
+        text,
+        thread,
+      });
+      const messageId = result?.messageName ?? "";
+      return {
+        messageId,
+        chatId: space,
+        receipt: createGoogleChatSendReceipt({ messageId, chatId: space, kind: "text" }),
+      };
+    },
+    sendMedia: async ({
+      cfg,
+      to,
+      text,
+      mediaUrl,
+      mediaAccess,
+      mediaLocalRoots,
+      mediaReadFile,
+      accountId,
+      replyToId,
+      threadId,
+    }: {
+      cfg: KlawConfig;
+      to: string;
+      text?: string;
+      mediaUrl?: string;
+      mediaAccess?: OutboundMediaLoadOptions["mediaAccess"];
+      mediaLocalRoots?: OutboundMediaLoadOptions["mediaLocalRoots"];
+      mediaReadFile?: OutboundMediaLoadOptions["mediaReadFile"];
+      accountId?: string | null;
+      replyToId?: string | null;
+      threadId?: string | number | null;
+    }) => {
+      if (!mediaUrl) {
+        throw new Error("Google Chat mediaUrl is required.");
+      }
+      const account = resolveGoogleChatAccount({
+        cfg: cfg,
+        accountId,
+      });
+      const space = await resolveGoogleChatOutboundSpace({ account, target: to });
+      const thread =
+        typeof threadId === "number" ? String(threadId) : (threadId ?? replyToId ?? undefined);
+      const maxBytes = resolveChannelMediaMaxBytes({
+        cfg: cfg,
+        resolveChannelLimitMb: ({ cfg, accountId }) =>
+          (
+            cfg.channels?.googlechat as
+              | { accounts?: Record<string, { mediaMaxMb?: number }>; mediaMaxMb?: number }
+              | undefined
+          )?.accounts?.[accountId]?.mediaMaxMb ??
+          (cfg.channels?.googlechat as { mediaMaxMb?: number } | undefined)?.mediaMaxMb,
+        accountId,
+      });
+      const effectiveMaxBytes = maxBytes ?? (account.config.mediaMaxMb ?? 20) * 1024 * 1024;
+      const loaded = /^https?:\/\//i.test(mediaUrl)
+        ? await readRemoteMediaBuffer({
+            url: mediaUrl,
+            maxBytes: effectiveMaxBytes,
+          })
+        : await loadOutboundMediaFromUrl(mediaUrl, {
+            maxBytes: effectiveMaxBytes,
+            mediaAccess,
+            mediaLocalRoots,
+            mediaReadFile,
+          });
+      const { sendGoogleChatMessage, uploadGoogleChatAttachment } =
+        await loadGoogleChatChannelRuntime();
+      const upload = await uploadGoogleChatAttachment({
+        account,
+        space,
+        filename: loaded.fileName ?? "attachment",
+        buffer: loaded.buffer,
+        contentType: loaded.contentType,
+      });
+      const result = await sendGoogleChatMessage({
+        account,
+        space,
+        text,
+        thread,
+        attachments: upload.attachmentUploadToken
+          ? [
+              {
+                attachmentUploadToken: upload.attachmentUploadToken,
+                contentName: loaded.fileName,
+              },
+            ]
+          : undefined,
+      });
+      const messageId = result?.messageName ?? "";
+      return {
+        messageId,
+        chatId: space,
+        receipt: createGoogleChatSendReceipt({ messageId, chatId: space, kind: "media" }),
+      };
+    },
+  },
+};
+
+export const googlechatMessageAdapter = defineChannelMessageAdapter({
+  id: "googlechat",
+  durableFinal: {
+    capabilities: {
+      text: true,
+      media: true,
+      thread: true,
+      messageSendingHooks: true,
+    },
+  },
+  send: {
+    text: googlechatOutboundAdapter.attachedResults.sendText,
+    media: googlechatOutboundAdapter.attachedResults.sendMedia,
+  },
+});

package/src/channel.deps.runtime.ts

@@ -0,0 +1,29 @@
+export {
+  buildChannelConfigSchema,
+  chunkTextForOutbound,
+  DEFAULT_ACCOUNT_ID,
+  readRemoteMediaBuffer,
+  GoogleChatConfigSchema,
+  loadOutboundMediaFromUrl,
+  missingTargetError,
+  PAIRING_APPROVED_MESSAGE,
+  resolveChannelMediaMaxBytes,
+  type ChannelMessageActionAdapter,
+  type ChannelMessageActionName,
+  type ChannelStatusIssue,
+  type KlawConfig,
+} from "../runtime-api.js";
+export {
+  type GoogleChatConfigAccessorAccount,
+  listGoogleChatAccountIds,
+  resolveGoogleChatConfigAccessorAccount,
+  resolveDefaultGoogleChatAccountId,
+  resolveGoogleChatAccount,
+  type ResolvedGoogleChatAccount,
+} from "./accounts.js";
+export {
+  isGoogleChatSpaceTarget,
+  isGoogleChatUserTarget,
+  normalizeGoogleChatTarget,
+  resolveGoogleChatOutboundSpace,
+} from "./targets.js";

package/src/channel.runtime.ts

@@ -0,0 +1,17 @@
+import {
+  probeGoogleChat as probeGoogleChatImpl,
+  sendGoogleChatMessage as sendGoogleChatMessageImpl,
+  uploadGoogleChatAttachment as uploadGoogleChatAttachmentImpl,
+} from "./api.js";
+import {
+  resolveGoogleChatWebhookPath as resolveGoogleChatWebhookPathImpl,
+  startGoogleChatMonitor as startGoogleChatMonitorImpl,
+} from "./monitor.js";
+
+export const googleChatChannelRuntime = {
+  probeGoogleChat: probeGoogleChatImpl,
+  sendGoogleChatMessage: sendGoogleChatMessageImpl,
+  uploadGoogleChatAttachment: uploadGoogleChatAttachmentImpl,
+  resolveGoogleChatWebhookPath: resolveGoogleChatWebhookPathImpl,
+  startGoogleChatMonitor: startGoogleChatMonitorImpl,
+};