@actagent/googlechat 2026.6.2

package/src/auth.ts

@@ -0,0 +1,219 @@
+// Googlechat plugin module implements auth behavior.
+import { normalizeLowercaseStringOrEmpty } from "actagent/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-base.ts

@@ -0,0 +1,123 @@
+// Googlechat plugin module implements channel base behavior.
+import { describeAccountSnapshot } from "actagent/plugin-sdk/account-helpers";
+import { formatNormalizedAllowFromEntries } from "actagent/plugin-sdk/allow-from";
+import {
+  adaptScopedAccountAccessor,
+  createScopedChannelConfigAdapter,
+} from "actagent/plugin-sdk/channel-config-helpers";
+import type { ChannelPlugin } from "actagent/plugin-sdk/channel-core";
+import { normalizeLowercaseStringOrEmpty } from "actagent/plugin-sdk/string-coerce-runtime";
+import {
+  type GoogleChatConfigAccessorAccount,
+  listGoogleChatAccountIds,
+  resolveDefaultGoogleChatAccountId,
+  resolveGoogleChatConfigAccessorAccount,
+  resolveGoogleChatAccount,
+  type ResolvedGoogleChatAccount,
+} from "./accounts.js";
+import { googlechatSetupAdapter } from "./setup-core.js";
+import { googlechatSetupWizard } from "./setup-surface.js";
+
+export const GOOGLECHAT_CHANNEL_ID = "googlechat" as const;
+
+export const googlechatMeta = {
+  id: GOOGLECHAT_CHANNEL_ID,
+  label: "Google Chat",
+  selectionLabel: "Google Chat (Chat API)",
+  docsPath: "/channels/googlechat",
+  docsLabel: "googlechat",
+  blurb: "Google Workspace Chat app with HTTP webhook.",
+  aliases: ["gchat", "google-chat"],
+  order: 55,
+  detailLabel: "Google Chat",
+  systemImage: "message.badge",
+  markdownCapable: true,
+};
+
+export const formatGoogleChatAllowFromEntry = (entry: string) =>
+  normalizeLowercaseStringOrEmpty(
+    entry
+      .trim()
+      .replace(/^(googlechat|google-chat|gchat):/i, "")
+      .replace(/^user:/i, "")
+      .replace(/^users\//i, ""),
+  );
+
+const googleChatConfigAdapter = createScopedChannelConfigAdapter<
+  ResolvedGoogleChatAccount,
+  GoogleChatConfigAccessorAccount
+>({
+  sectionKey: GOOGLECHAT_CHANNEL_ID,
+  listAccountIds: listGoogleChatAccountIds,
+  resolveAccount: adaptScopedAccountAccessor(resolveGoogleChatAccount),
+  resolveAccessorAccount: resolveGoogleChatConfigAccessorAccount,
+  defaultAccountId: resolveDefaultGoogleChatAccountId,
+  clearBaseFields: [
+    "serviceAccount",
+    "serviceAccountFile",
+    "audienceType",
+    "audience",
+    "webhookPath",
+    "webhookUrl",
+    "botUser",
+    "name",
+  ],
+  resolveAllowFrom: (account) => account.config.dm?.allowFrom,
+  formatAllowFrom: (allowFrom) =>
+    formatNormalizedAllowFromEntries({
+      allowFrom,
+      normalizeEntry: formatGoogleChatAllowFromEntry,
+    }),
+  resolveDefaultTo: (account) => account.config.defaultTo,
+});
+
+type GoogleChatPluginBase = Pick<
+  ChannelPlugin<ResolvedGoogleChatAccount>,
+  | "id"
+  | "meta"
+  | "setup"
+  | "setupWizard"
+  | "capabilities"
+  | "streaming"
+  | "reload"
+  | "configSchema"
+  | "config"
+>;
+
+export function createGoogleChatPluginBase(
+  params: {
+    configSchema?: ChannelPlugin<ResolvedGoogleChatAccount>["configSchema"];
+  } = {},
+): GoogleChatPluginBase {
+  return {
+    id: GOOGLECHAT_CHANNEL_ID,
+    meta: { ...googlechatMeta },
+    setup: googlechatSetupAdapter,
+    setupWizard: googlechatSetupWizard,
+    capabilities: {
+      chatTypes: ["direct", "group", "thread"],
+      reactions: true,
+      threads: true,
+      media: true,
+      nativeCommands: false,
+      blockStreaming: true,
+    },
+    streaming: {
+      blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+    },
+    reload: { configPrefixes: ["channels.googlechat"] },
+    ...(params.configSchema ? { configSchema: params.configSchema } : {}),
+    config: {
+      ...googleChatConfigAdapter,
+      isConfigured: (account) => account.credentialSource !== "none",
+      describeAccount: (account) =>
+        describeAccountSnapshot({
+          account,
+          configured: account.credentialSource !== "none",
+          extra: {
+            credentialSource: account.credentialSource,
+          },
+        }),
+    },
+  };
+}

package/src/channel-config.test.ts

@@ -0,0 +1,174 @@
+// Googlechat tests cover channel config plugin behavior.
+import type { ChannelOutboundPayloadHint } from "actagent/plugin-sdk/channel-contract";
+import type { ACTAgentConfig } from "actagent/plugin-sdk/config-contracts";
+import type { ReplyPayload } from "actagent/plugin-sdk/reply-runtime";
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  clearGoogleChatApprovalCardBindingsForTest,
+  registerGoogleChatApprovalCardBinding,
+} from "./approval-card-actions.js";
+import { googlechatPlugin } from "./channel.js";
+import { googlechatSetupPlugin } from "./channel.setup.js";
+
+describe("googlechatPlugin config adapter", () => {
+  beforeEach(() => {
+    clearGoogleChatApprovalCardBindingsForTest();
+  });
+
+  it("keeps setup metadata aligned with the runtime plugin", () => {
+    expect(googlechatSetupPlugin.id).toBe(googlechatPlugin.id);
+    expect(googlechatSetupPlugin.meta).toEqual(googlechatPlugin.meta);
+    expect(googlechatSetupPlugin.capabilities?.chatTypes).toEqual(
+      googlechatPlugin.capabilities?.chatTypes,
+    );
+  });
+
+  it("registers an exec-capable native approval runtime", () => {
+    expect(googlechatPlugin.approvalCapability?.nativeRuntime?.eventKinds).toContain("exec");
+  });
+
+  it("keeps read-only accessors from resolving service account SecretRefs", () => {
+    const cfg = {
+      secrets: {
+        providers: {
+          google_chat_service_account: {
+            source: "file",
+            path: "/tmp/actagent-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 ACTAgentConfig;
+
+    expect(googlechatPlugin.config.resolveAllowFrom?.({ cfg, accountId: "default" })).toEqual([
+      "users/123",
+    ]);
+    expect(googlechatPlugin.config.resolveDefaultTo?.({ cfg, accountId: "default" })).toBe(
+      "spaces/AAA",
+    );
+  });
+
+  it("wires native exec approval suppression through the outbound adapter", () => {
+    const cfg = {
+      approvals: { exec: { enabled: true } },
+      channels: {
+        googlechat: {
+          serviceAccount: {
+            type: "service_account",
+            client_email: "bot@example.com",
+            private_key: "test-key",
+            token_uri: "https://oauth2.googleapis.com/token",
+          },
+          audienceType: "app-url",
+          audience: "https://chat-app.example.test/googlechat",
+          dm: { allowFrom: ["users/123"] },
+        },
+      },
+    } as ACTAgentConfig;
+    const payload: ReplyPayload = {
+      channelData: {
+        execApproval: {
+          approvalId: "12345678-1234-1234-1234-123456789012",
+          approvalSlug: "12345678",
+          approvalKind: "exec",
+          agentId: "dev",
+          sessionKey: "agent:dev:main",
+        },
+      },
+    };
+    const hint: ChannelOutboundPayloadHint = {
+      kind: "approval-pending",
+      approvalKind: "exec",
+      nativeRouteActive: true,
+    };
+
+    expect(
+      googlechatPlugin.outbound?.shouldSuppressLocalPayloadPrompt?.({
+        cfg,
+        payload,
+        hint,
+      }),
+    ).toBe(true);
+  });
+
+  it("drops duplicate manual exec approval follow-up text after a native card is registered", () => {
+    const approvalId = "12345678-1234-1234-1234-123456789012";
+    registerGoogleChatApprovalCardBinding({
+      token: "token-1",
+      accountId: "default",
+      approvalId,
+      approvalKind: "exec",
+      decision: "allow-once",
+      allowedDecisions: ["allow-once", "deny"],
+      spaceName: "spaces/AAA",
+      messageName: "spaces/AAA/messages/msg-1",
+      expiresAtMs: Date.now() + 60_000,
+    });
+    const payload: ReplyPayload = {
+      text: `I need approval.\nReply with:\n/approve ${approvalId.slice(0, 8)} allow-once`,
+    };
+
+    expect(
+      googlechatPlugin.outbound?.normalizePayload?.({
+        cfg: {} as ACTAgentConfig,
+        payload,
+      }),
+    ).toBeNull();
+  });
+
+  it("keeps unrelated or sendable structured approval-looking payloads visible", () => {
+    const approvalId = "12345678-1234-1234-1234-123456789012";
+    registerGoogleChatApprovalCardBinding({
+      token: "token-1",
+      accountId: "default",
+      approvalId,
+      approvalKind: "exec",
+      decision: "allow-once",
+      allowedDecisions: ["allow-once", "deny"],
+      spaceName: "spaces/AAA",
+      messageName: "spaces/AAA/messages/msg-1",
+      expiresAtMs: Date.now() + 60_000,
+    });
+    const unrelatedPayload: ReplyPayload = { text: "/approve deadbeef allow-once" };
+    const metadataPayload: ReplyPayload = {
+      text: `/approve ${approvalId.slice(0, 8)} allow-once`,
+      channelData: { execApproval: { approvalId } },
+    };
+    const structuredPayload: ReplyPayload = {
+      text: `/approve ${approvalId.slice(0, 8)} allow-once`,
+      presentation: { blocks: [] },
+    };
+
+    expect(
+      googlechatPlugin.outbound?.normalizePayload?.({
+        cfg: {} as ACTAgentConfig,
+        payload: unrelatedPayload,
+      }),
+    ).toBe(unrelatedPayload);
+    expect(
+      googlechatPlugin.outbound?.normalizePayload?.({
+        cfg: {} as ACTAgentConfig,
+        payload: metadataPayload,
+      }),
+    ).toBeNull();
+    expect(
+      googlechatPlugin.outbound?.normalizePayload?.({
+        cfg: {} as ACTAgentConfig,
+        payload: structuredPayload,
+      }),
+    ).toBe(structuredPayload);
+  });
+});