refactor: split webhook ingress and policy guards

extensions/googlechat/src/monitor-access.ts

@@ -0,0 +1,357 @@
+import {
+  GROUP_POLICY_BLOCKED_LABEL,
+  createScopedPairingAccess,
+  isDangerousNameMatchingEnabled,
+  resolveAllowlistProviderRuntimeGroupPolicy,
+  resolveDefaultGroupPolicy,
+  resolveDmGroupAccessWithLists,
+  resolveMentionGatingWithBypass,
+  warnMissingProviderGroupPolicyFallbackOnce,
+} from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+import { sendGoogleChatMessage } from "./api.js";
+import type { GoogleChatCoreRuntime } from "./monitor-types.js";
+import type { GoogleChatAnnotation, GoogleChatMessage, GoogleChatSpace } from "./types.js";
+
+function normalizeUserId(raw?: string | null): string {
+  const trimmed = raw?.trim() ?? "";
+  if (!trimmed) {
+    return "";
+  }
+  return trimmed.replace(/^users\//i, "").toLowerCase();
+}
+
+function isEmailLike(value: string): boolean {
+  // Keep this intentionally loose; allowlists are user-provided config.
+  return value.includes("@");
+}
+
+export function isSenderAllowed(
+  senderId: string,
+  senderEmail: string | undefined,
+  allowFrom: string[],
+  allowNameMatching = false,
+) {
+  if (allowFrom.includes("*")) {
+    return true;
+  }
+  const normalizedSenderId = normalizeUserId(senderId);
+  const normalizedEmail = senderEmail?.trim().toLowerCase() ?? "";
+  return allowFrom.some((entry) => {
+    const normalized = String(entry).trim().toLowerCase();
+    if (!normalized) {
+      return false;
+    }
+
+    // Accept `googlechat:<id>` but treat `users/...` as an *ID* only (deprecated `users/<email>`).
+    const withoutPrefix = normalized.replace(/^(googlechat|google-chat|gchat):/i, "");
+    if (withoutPrefix.startsWith("users/")) {
+      return normalizeUserId(withoutPrefix) === normalizedSenderId;
+    }
+
+    // Raw email allowlist entries are a break-glass override.
+    if (allowNameMatching && normalizedEmail && isEmailLike(withoutPrefix)) {
+      return withoutPrefix === normalizedEmail;
+    }
+
+    return withoutPrefix.replace(/^users\//i, "") === normalizedSenderId;
+  });
+}
+
+type GoogleChatGroupEntry = {
+  requireMention?: boolean;
+  allow?: boolean;
+  enabled?: boolean;
+  users?: Array<string | number>;
+  systemPrompt?: string;
+};
+
+function resolveGroupConfig(params: {
+  groupId: string;
+  groupName?: string | null;
+  groups?: Record<string, GoogleChatGroupEntry>;
+}) {
+  const { groupId, groupName, groups } = params;
+  const entries = groups ?? {};
+  const keys = Object.keys(entries);
+  if (keys.length === 0) {
+    return { entry: undefined, allowlistConfigured: false };
+  }
+  const normalizedName = groupName?.trim().toLowerCase();
+  const candidates = [groupId, groupName ?? "", normalizedName ?? ""].filter(Boolean);
+  let entry = candidates.map((candidate) => entries[candidate]).find(Boolean);
+  if (!entry && normalizedName) {
+    entry = entries[normalizedName];
+  }
+  const fallback = entries["*"];
+  return { entry: entry ?? fallback, allowlistConfigured: true, fallback };
+}
+
+function extractMentionInfo(annotations: GoogleChatAnnotation[], botUser?: string | null) {
+  const mentionAnnotations = annotations.filter((entry) => entry.type === "USER_MENTION");
+  const hasAnyMention = mentionAnnotations.length > 0;
+  const botTargets = new Set(["users/app", botUser?.trim()].filter(Boolean) as string[]);
+  const wasMentioned = mentionAnnotations.some((entry) => {
+    const userName = entry.userMention?.user?.name;
+    if (!userName) {
+      return false;
+    }
+    if (botTargets.has(userName)) {
+      return true;
+    }
+    return normalizeUserId(userName) === "app";
+  });
+  return { hasAnyMention, wasMentioned };
+}
+
+const warnedDeprecatedUsersEmailAllowFrom = new Set<string>();
+
+function warnDeprecatedUsersEmailEntries(logVerbose: (message: string) => void, entries: string[]) {
+  const deprecated = entries.map((v) => String(v).trim()).filter((v) => /^users\/.+@.+/i.test(v));
+  if (deprecated.length === 0) {
+    return;
+  }
+  const key = deprecated
+    .map((v) => v.toLowerCase())
+    .sort()
+    .join(",");
+  if (warnedDeprecatedUsersEmailAllowFrom.has(key)) {
+    return;
+  }
+  warnedDeprecatedUsersEmailAllowFrom.add(key);
+  logVerbose(
+    `Deprecated allowFrom entry detected: "users/<email>" is no longer treated as an email allowlist. Use raw email (alice@example.com) or immutable user id (users/<id>). entries=${deprecated.join(", ")}`,
+  );
+}
+
+export async function applyGoogleChatInboundAccessPolicy(params: {
+  account: ResolvedGoogleChatAccount;
+  config: OpenClawConfig;
+  core: GoogleChatCoreRuntime;
+  space: GoogleChatSpace;
+  message: GoogleChatMessage;
+  isGroup: boolean;
+  senderId: string;
+  senderName: string;
+  senderEmail?: string;
+  rawBody: string;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  logVerbose: (message: string) => void;
+}): Promise<
+  | {
+      ok: true;
+      commandAuthorized: boolean | undefined;
+      effectiveWasMentioned: boolean | undefined;
+      groupSystemPrompt: string | undefined;
+    }
+  | { ok: false }
+> {
+  const {
+    account,
+    config,
+    core,
+    space,
+    message,
+    isGroup,
+    senderId,
+    senderName,
+    senderEmail,
+    rawBody,
+    statusSink,
+    logVerbose,
+  } = params;
+  const allowNameMatching = isDangerousNameMatchingEnabled(account.config);
+  const spaceId = space.name ?? "";
+  const pairing = createScopedPairingAccess({
+    core,
+    channel: "googlechat",
+    accountId: account.accountId,
+  });
+
+  const defaultGroupPolicy = resolveDefaultGroupPolicy(config);
+  const { groupPolicy, providerMissingFallbackApplied } =
+    resolveAllowlistProviderRuntimeGroupPolicy({
+      providerConfigPresent: config.channels?.googlechat !== undefined,
+      groupPolicy: account.config.groupPolicy,
+      defaultGroupPolicy,
+    });
+  warnMissingProviderGroupPolicyFallbackOnce({
+    providerMissingFallbackApplied,
+    providerKey: "googlechat",
+    accountId: account.accountId,
+    blockedLabel: GROUP_POLICY_BLOCKED_LABEL.space,
+    log: logVerbose,
+  });
+  const groupConfigResolved = resolveGroupConfig({
+    groupId: spaceId,
+    groupName: space.displayName ?? null,
+    groups: account.config.groups ?? undefined,
+  });
+  const groupEntry = groupConfigResolved.entry;
+  const groupUsers = groupEntry?.users ?? account.config.groupAllowFrom ?? [];
+  let effectiveWasMentioned: boolean | undefined;
+
+  if (isGroup) {
+    if (groupPolicy === "disabled") {
+      logVerbose(`drop group message (groupPolicy=disabled, space=${spaceId})`);
+      return { ok: false };
+    }
+    const groupAllowlistConfigured = groupConfigResolved.allowlistConfigured;
+    const groupAllowed = Boolean(groupEntry) || Boolean((account.config.groups ?? {})["*"]);
+    if (groupPolicy === "allowlist") {
+      if (!groupAllowlistConfigured) {
+        logVerbose(`drop group message (groupPolicy=allowlist, no allowlist, space=${spaceId})`);
+        return { ok: false };
+      }
+      if (!groupAllowed) {
+        logVerbose(`drop group message (not allowlisted, space=${spaceId})`);
+        return { ok: false };
+      }
+    }
+    if (groupEntry?.enabled === false || groupEntry?.allow === false) {
+      logVerbose(`drop group message (space disabled, space=${spaceId})`);
+      return { ok: false };
+    }
+
+    if (groupUsers.length > 0) {
+      const normalizedGroupUsers = groupUsers.map((v) => String(v));
+      warnDeprecatedUsersEmailEntries(logVerbose, normalizedGroupUsers);
+      const ok = isSenderAllowed(senderId, senderEmail, normalizedGroupUsers, allowNameMatching);
+      if (!ok) {
+        logVerbose(`drop group message (sender not allowed, ${senderId})`);
+        return { ok: false };
+      }
+    }
+  }
+
+  const dmPolicy = account.config.dm?.policy ?? "pairing";
+  const configAllowFrom = (account.config.dm?.allowFrom ?? []).map((v) => String(v));
+  const normalizedGroupUsers = groupUsers.map((v) => String(v));
+  const senderGroupPolicy =
+    groupPolicy === "disabled"
+      ? "disabled"
+      : normalizedGroupUsers.length > 0
+        ? "allowlist"
+        : "open";
+  const shouldComputeAuth = core.channel.commands.shouldComputeCommandAuthorized(rawBody, config);
+  const storeAllowFrom =
+    !isGroup && dmPolicy !== "allowlist" && (dmPolicy !== "open" || shouldComputeAuth)
+      ? await pairing.readAllowFromStore().catch(() => [])
+      : [];
+  const access = resolveDmGroupAccessWithLists({
+    isGroup,
+    dmPolicy,
+    groupPolicy: senderGroupPolicy,
+    allowFrom: configAllowFrom,
+    groupAllowFrom: normalizedGroupUsers,
+    storeAllowFrom,
+    groupAllowFromFallbackToAllowFrom: false,
+    isSenderAllowed: (allowFrom) =>
+      isSenderAllowed(senderId, senderEmail, allowFrom, allowNameMatching),
+  });
+  const effectiveAllowFrom = access.effectiveAllowFrom;
+  const effectiveGroupAllowFrom = access.effectiveGroupAllowFrom;
+  warnDeprecatedUsersEmailEntries(logVerbose, effectiveAllowFrom);
+  const commandAllowFrom = isGroup ? effectiveGroupAllowFrom : effectiveAllowFrom;
+  const useAccessGroups = config.commands?.useAccessGroups !== false;
+  const senderAllowedForCommands = isSenderAllowed(
+    senderId,
+    senderEmail,
+    commandAllowFrom,
+    allowNameMatching,
+  );
+  const commandAuthorized = shouldComputeAuth
+    ? core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
+        useAccessGroups,
+        authorizers: [
+          { configured: commandAllowFrom.length > 0, allowed: senderAllowedForCommands },
+        ],
+      })
+    : undefined;
+
+  if (isGroup) {
+    const requireMention = groupEntry?.requireMention ?? account.config.requireMention ?? true;
+    const annotations = message.annotations ?? [];
+    const mentionInfo = extractMentionInfo(annotations, account.config.botUser);
+    const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
+      cfg: config,
+      surface: "googlechat",
+    });
+    const mentionGate = resolveMentionGatingWithBypass({
+      isGroup: true,
+      requireMention,
+      canDetectMention: true,
+      wasMentioned: mentionInfo.wasMentioned,
+      implicitMention: false,
+      hasAnyMention: mentionInfo.hasAnyMention,
+      allowTextCommands,
+      hasControlCommand: core.channel.text.hasControlCommand(rawBody, config),
+      commandAuthorized: commandAuthorized === true,
+    });
+    effectiveWasMentioned = mentionGate.effectiveWasMentioned;
+    if (mentionGate.shouldSkip) {
+      logVerbose(`drop group message (mention required, space=${spaceId})`);
+      return { ok: false };
+    }
+  }
+
+  if (isGroup && access.decision !== "allow") {
+    logVerbose(
+      `drop group message (sender policy blocked, reason=${access.reason}, space=${spaceId})`,
+    );
+    return { ok: false };
+  }
+
+  if (!isGroup) {
+    if (account.config.dm?.enabled === false) {
+      logVerbose(`Blocked Google Chat DM from ${senderId} (dmPolicy=disabled)`);
+      return { ok: false };
+    }
+
+    if (access.decision !== "allow") {
+      if (access.decision === "pairing") {
+        const { code, created } = await pairing.upsertPairingRequest({
+          id: senderId,
+          meta: { name: senderName || undefined, email: senderEmail },
+        });
+        if (created) {
+          logVerbose(`googlechat pairing request sender=${senderId}`);
+          try {
+            await sendGoogleChatMessage({
+              account,
+              space: spaceId,
+              text: core.channel.pairing.buildPairingReply({
+                channel: "googlechat",
+                idLine: `Your Google Chat user id: ${senderId}`,
+                code,
+              }),
+            });
+            statusSink?.({ lastOutboundAt: Date.now() });
+          } catch (err) {
+            logVerbose(`pairing reply failed for ${senderId}: ${String(err)}`);
+          }
+        }
+      } else {
+        logVerbose(`Blocked unauthorized Google Chat sender ${senderId} (dmPolicy=${dmPolicy})`);
+      }
+      return { ok: false };
+    }
+  }
+
+  if (
+    isGroup &&
+    core.channel.commands.isControlCommandMessage(rawBody, config) &&
+    commandAuthorized !== true
+  ) {
+    logVerbose(`googlechat: drop control command from ${senderId}`);
+    return { ok: false };
+  }
+
+  return {
+    ok: true,
+    commandAuthorized,
+    effectiveWasMentioned,
+    groupSystemPrompt: groupEntry?.systemPrompt?.trim() || undefined,
+  };
+}

extensions/googlechat/src/monitor-types.ts

@@ -0,0 +1,33 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { ResolvedGoogleChatAccount } from "./accounts.js";
+import type { GoogleChatAudienceType } from "./auth.js";
+import { getGoogleChatRuntime } from "./runtime.js";
+
+export type GoogleChatRuntimeEnv = {
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+export type GoogleChatMonitorOptions = {
+  account: ResolvedGoogleChatAccount;
+  config: OpenClawConfig;
+  runtime: GoogleChatRuntimeEnv;
+  abortSignal: AbortSignal;
+  webhookPath?: string;
+  webhookUrl?: string;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+};
+
+export type GoogleChatCoreRuntime = ReturnType<typeof getGoogleChatRuntime>;
+
+export type WebhookTarget = {
+  account: ResolvedGoogleChatAccount;
+  config: OpenClawConfig;
+  runtime: GoogleChatRuntimeEnv;
+  core: GoogleChatCoreRuntime;
+  path: string;
+  audienceType?: GoogleChatAudienceType;
+  audience?: string;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  mediaMaxMb: number;
+};

extensions/googlechat/src/monitor-webhook.ts

@@ -0,0 +1,216 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import {
+  beginWebhookRequestPipelineOrReject,
+  readJsonWebhookBodyOrReject,
+  resolveWebhookTargetWithAuthOrReject,
+  resolveWebhookTargets,
+  type WebhookInFlightLimiter,
+} from "openclaw/plugin-sdk";
+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) ? String(header[0] ?? "") : String(header ?? "");
+  return authHeader.toLowerCase().startsWith("bearer ")
+    ? authHeader.slice("bearer ".length).trim()
+    : "";
+}
+
+type ParsedGoogleChatInboundPayload =
+  | { ok: true; event: GoogleChatEvent; addOnBearerToken: string }
+  | { ok: false };
+
+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 = 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 };
+}
+
+export function createGoogleChatWebhookRequestHandler(params: {
+  webhookTargets: Map<string, WebhookTarget[]>;
+  webhookInFlightLimiter: WebhookInFlightLimiter;
+  processEvent: (event: GoogleChatEvent, target: WebhookTarget) => Promise<void>;
+}): (req: IncomingMessage, res: ServerResponse) => Promise<boolean> {
+  return async (req: IncomingMessage, res: ServerResponse): Promise<boolean> => {
+    const resolved = resolveWebhookTargets(req, params.webhookTargets);
+    if (!resolved) {
+      return false;
+    }
+    const { path, targets } = resolved;
+
+    const requestLifecycle = beginWebhookRequestPipelineOrReject({
+      req,
+      res,
+      allowMethods: ["POST"],
+      requireJsonContentType: true,
+      inFlightLimiter: params.webhookInFlightLimiter,
+      inFlightKey: `${path}:${req.socket?.remoteAddress ?? "unknown"}`,
+    });
+    if (!requestLifecycle.ok) {
+      return true;
+    }
+
+    try {
+      const headerBearer = extractBearerToken(req.headers.authorization);
+      let selectedTarget: WebhookTarget | null = null;
+      let parsedEvent: GoogleChatEvent | null = null;
+
+      if (headerBearer) {
+        selectedTarget = await resolveWebhookTargetWithAuthOrReject({
+          targets,
+          res,
+          isMatch: async (target) => {
+            const verification = await verifyGoogleChatRequest({
+              bearer: headerBearer,
+              audienceType: target.audienceType,
+              audience: target.audience,
+            });
+            return verification.ok;
+          },
+        });
+        if (!selectedTarget) {
+          return true;
+        }
+
+        const body = await readJsonWebhookBodyOrReject({
+          req,
+          res,
+          profile: "post-auth",
+          emptyObjectOnEmpty: false,
+          invalidJsonMessage: "invalid payload",
+        });
+        if (!body.ok) {
+          return true;
+        }
+
+        const parsed = parseGoogleChatInboundPayload(body.value, res);
+        if (!parsed.ok) {
+          return true;
+        }
+        parsedEvent = parsed.event;
+      } else {
+        const body = await readJsonWebhookBodyOrReject({
+          req,
+          res,
+          profile: "pre-auth",
+          emptyObjectOnEmpty: false,
+          invalidJsonMessage: "invalid payload",
+        });
+        if (!body.ok) {
+          return true;
+        }
+
+        const parsed = parseGoogleChatInboundPayload(body.value, res);
+        if (!parsed.ok) {
+          return true;
+        }
+        parsedEvent = parsed.event;
+
+        if (!parsed.addOnBearerToken) {
+          res.statusCode = 401;
+          res.end("unauthorized");
+          return true;
+        }
+
+        selectedTarget = await resolveWebhookTargetWithAuthOrReject({
+          targets,
+          res,
+          isMatch: async (target) => {
+            const verification = await verifyGoogleChatRequest({
+              bearer: parsed.addOnBearerToken,
+              audienceType: target.audienceType,
+              audience: target.audience,
+            });
+            return verification.ok;
+          },
+        });
+        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;
+    } finally {
+      requestLifecycle.release();
+    }
+  };
+}

extensions/googlechat/src/monitor.ts

@@ -1,23 +1,11 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import {
-  beginWebhookRequestPipelineOrReject,
   createWebhookInFlightLimiter,
-  GROUP_POLICY_BLOCKED_LABEL,
-  createScopedPairingAccess,
   createReplyPrefixOptions,
-  readJsonWebhookBodyOrReject,
   registerWebhookTargetWithPluginRoute,
-  isDangerousNameMatchingEnabled,
-  resolveAllowlistProviderRuntimeGroupPolicy,
-  resolveDefaultGroupPolicy,
   resolveInboundRouteEnvelopeBuilderWithRuntime,
-  resolveSingleWebhookTargetAsync,
   resolveWebhookPath,
-  resolveWebhookTargets,
-  warnMissingProviderGroupPolicyFallbackOnce,
-  resolveMentionGatingWithBypass,
-  resolveDmGroupAccessWithLists,
 } from "openclaw/plugin-sdk";
 import { type ResolvedGoogleChatAccount } from "./accounts.js";
 import {
@@ -26,48 +14,29 @@ import {
   sendGoogleChatMessage,
   updateGoogleChatMessage,
 } from "./api.js";
-import { verifyGoogleChatRequest, type GoogleChatAudienceType } from "./auth.js";
-import { getGoogleChatRuntime } from "./runtime.js";
+import { type GoogleChatAudienceType } from "./auth.js";
+import { applyGoogleChatInboundAccessPolicy, isSenderAllowed } from "./monitor-access.js";
 import type {
-  GoogleChatAnnotation,
-  GoogleChatAttachment,
-  GoogleChatEvent,
-  GoogleChatSpace,
-  GoogleChatMessage,
-  GoogleChatUser,
-} from "./types.js";
-
-export type GoogleChatRuntimeEnv = {
-  log?: (message: string) => void;
-  error?: (message: string) => void;
-};
-
-export type GoogleChatMonitorOptions = {
-  account: ResolvedGoogleChatAccount;
-  config: OpenClawConfig;
-  runtime: GoogleChatRuntimeEnv;
-  abortSignal: AbortSignal;
-  webhookPath?: string;
-  webhookUrl?: string;
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
-};
-
-type GoogleChatCoreRuntime = ReturnType<typeof getGoogleChatRuntime>;
-
-type WebhookTarget = {
-  account: ResolvedGoogleChatAccount;
-  config: OpenClawConfig;
-  runtime: GoogleChatRuntimeEnv;
-  core: GoogleChatCoreRuntime;
-  path: string;
-  audienceType?: GoogleChatAudienceType;
-  audience?: string;
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
-  mediaMaxMb: number;
-};
+  GoogleChatCoreRuntime,
+  GoogleChatMonitorOptions,
+  GoogleChatRuntimeEnv,
+  WebhookTarget,
+} from "./monitor-types.js";
+import { createGoogleChatWebhookRequestHandler } from "./monitor-webhook.js";
+import { getGoogleChatRuntime } from "./runtime.js";
+import type { GoogleChatAttachment, GoogleChatEvent } from "./types.js";
+export type { GoogleChatMonitorOptions, GoogleChatRuntimeEnv } from "./monitor-types.js";
+export { isSenderAllowed };
 
 const webhookTargets = new Map<string, WebhookTarget[]>();
 const webhookInFlightLimiter = createWebhookInFlightLimiter();
+const googleChatWebhookRequestHandler = createGoogleChatWebhookRequestHandler({
+  webhookTargets,
+  webhookInFlightLimiter,
+  processEvent: async (event, target) => {
+    await processGoogleChatEvent(event, target);
+  },
+});
 
 function logVerbose(core: GoogleChatCoreRuntime, runtime: GoogleChatRuntimeEnv, message: string) {
   if (core.logging.shouldLogVerbose()) {
@@ -75,31 +44,6 @@ function logVerbose(core: GoogleChatCoreRuntime, runtime: GoogleChatRuntimeEnv,
   }
 }
 
-const warnedDeprecatedUsersEmailAllowFrom = new Set<string>();
-function warnDeprecatedUsersEmailEntries(
-  core: GoogleChatCoreRuntime,
-  runtime: GoogleChatRuntimeEnv,
-  entries: string[],
-) {
-  const deprecated = entries.map((v) => String(v).trim()).filter((v) => /^users\/.+@.+/i.test(v));
-  if (deprecated.length === 0) {
-    return;
-  }
-  const key = deprecated
-    .map((v) => v.toLowerCase())
-    .sort()
-    .join(",");
-  if (warnedDeprecatedUsersEmailAllowFrom.has(key)) {
-    return;
-  }
-  warnedDeprecatedUsersEmailAllowFrom.add(key);
-  logVerbose(
-    core,
-    runtime,
-    `Deprecated allowFrom entry detected: "users/<email>" is no longer treated as an email allowlist. Use raw email (alice@example.com) or immutable user id (users/<id>). entries=${deprecated.join(", ")}`,
-  );
-}
-
 export function registerGoogleChatWebhookTarget(target: WebhookTarget): () => void {
   return registerWebhookTargetWithPluginRoute({
     targetsByPath: webhookTargets,
@@ -138,211 +82,11 @@ function normalizeAudienceType(value?: string | null): GoogleChatAudienceType |
   return undefined;
 }
 
-function extractBearerToken(header: unknown): string {
-  const authHeader = Array.isArray(header) ? String(header[0] ?? "") : String(header ?? "");
-  return authHeader.toLowerCase().startsWith("bearer ")
-    ? authHeader.slice("bearer ".length).trim()
-    : "";
-}
-
-type ParsedGoogleChatInboundPayload =
-  | { ok: true; event: GoogleChatEvent; addOnBearerToken: string }
-  | { ok: false };
-
-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 = 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 };
-}
-
-async function resolveGoogleChatWebhookTargetByBearer(
-  targets: readonly WebhookTarget[],
-  bearer: string,
-) {
-  return await resolveSingleWebhookTargetAsync(targets, async (target) => {
-    const verification = await verifyGoogleChatRequest({
-      bearer,
-      audienceType: target.audienceType,
-      audience: target.audience,
-    });
-    return verification.ok;
-  });
-}
-
 export async function handleGoogleChatWebhookRequest(
   req: IncomingMessage,
   res: ServerResponse,
 ): Promise<boolean> {
-  const resolved = resolveWebhookTargets(req, webhookTargets);
-  if (!resolved) {
-    return false;
-  }
-  const { path, targets } = resolved;
-
-  const requestLifecycle = beginWebhookRequestPipelineOrReject({
-    req,
-    res,
-    allowMethods: ["POST"],
-    requireJsonContentType: true,
-    inFlightLimiter: webhookInFlightLimiter,
-    inFlightKey: `${path}:${req.socket?.remoteAddress ?? "unknown"}`,
-  });
-  if (!requestLifecycle.ok) {
-    return true;
-  }
-
-  try {
-    const headerBearer = extractBearerToken(req.headers.authorization);
-    let matchedTarget: Awaited<ReturnType<typeof resolveGoogleChatWebhookTargetByBearer>> | null =
-      null;
-    let parsedEvent: GoogleChatEvent | null = null;
-    let addOnBearerToken = "";
-
-    if (headerBearer) {
-      matchedTarget = await resolveGoogleChatWebhookTargetByBearer(targets, headerBearer);
-      if (matchedTarget.kind === "none") {
-        res.statusCode = 401;
-        res.end("unauthorized");
-        return true;
-      }
-      if (matchedTarget.kind === "ambiguous") {
-        res.statusCode = 401;
-        res.end("ambiguous webhook target");
-        return true;
-      }
-
-      const body = await readJsonWebhookBodyOrReject({
-        req,
-        res,
-        profile: "post-auth",
-        emptyObjectOnEmpty: false,
-        invalidJsonMessage: "invalid payload",
-      });
-      if (!body.ok) {
-        return true;
-      }
-
-      const parsed = parseGoogleChatInboundPayload(body.value, res);
-      if (!parsed.ok) {
-        return true;
-      }
-      parsedEvent = parsed.event;
-      addOnBearerToken = parsed.addOnBearerToken;
-    } else {
-      const body = await readJsonWebhookBodyOrReject({
-        req,
-        res,
-        profile: "pre-auth",
-        emptyObjectOnEmpty: false,
-        invalidJsonMessage: "invalid payload",
-      });
-      if (!body.ok) {
-        return true;
-      }
-
-      const parsed = parseGoogleChatInboundPayload(body.value, res);
-      if (!parsed.ok) {
-        return true;
-      }
-      parsedEvent = parsed.event;
-      addOnBearerToken = parsed.addOnBearerToken;
-
-      if (!addOnBearerToken) {
-        res.statusCode = 401;
-        res.end("unauthorized");
-        return true;
-      }
-
-      matchedTarget = await resolveGoogleChatWebhookTargetByBearer(targets, addOnBearerToken);
-      if (matchedTarget.kind === "none") {
-        res.statusCode = 401;
-        res.end("unauthorized");
-        return true;
-      }
-      if (matchedTarget.kind === "ambiguous") {
-        res.statusCode = 401;
-        res.end("ambiguous webhook target");
-        return true;
-      }
-    }
-
-    if (!matchedTarget || !parsedEvent) {
-      res.statusCode = 401;
-      res.end("unauthorized");
-      return true;
-    }
-
-    const selected = matchedTarget.target;
-    selected.statusSink?.({ lastInboundAt: Date.now() });
-    processGoogleChatEvent(parsedEvent, selected).catch((err) => {
-      selected.runtime.error?.(
-        `[${selected.account.accountId}] Google Chat webhook failed: ${String(err)}`,
-      );
-    });
-
-    res.statusCode = 200;
-    res.setHeader("Content-Type", "application/json");
-    res.end("{}");
-    return true;
-  } finally {
-    requestLifecycle.release();
-  }
+  return await googleChatWebhookRequestHandler(req, res);
 }
 
 async function processGoogleChatEvent(event: GoogleChatEvent, target: WebhookTarget) {
@@ -365,98 +109,6 @@ async function processGoogleChatEvent(event: GoogleChatEvent, target: WebhookTar
   });
 }
 
-function normalizeUserId(raw?: string | null): string {
-  const trimmed = raw?.trim() ?? "";
-  if (!trimmed) {
-    return "";
-  }
-  return trimmed.replace(/^users\//i, "").toLowerCase();
-}
-
-function isEmailLike(value: string): boolean {
-  // Keep this intentionally loose; allowlists are user-provided config.
-  return value.includes("@");
-}
-
-export function isSenderAllowed(
-  senderId: string,
-  senderEmail: string | undefined,
-  allowFrom: string[],
-  allowNameMatching = false,
-) {
-  if (allowFrom.includes("*")) {
-    return true;
-  }
-  const normalizedSenderId = normalizeUserId(senderId);
-  const normalizedEmail = senderEmail?.trim().toLowerCase() ?? "";
-  return allowFrom.some((entry) => {
-    const normalized = String(entry).trim().toLowerCase();
-    if (!normalized) {
-      return false;
-    }
-
-    // Accept `googlechat:<id>` but treat `users/...` as an *ID* only (deprecated `users/<email>`).
-    const withoutPrefix = normalized.replace(/^(googlechat|google-chat|gchat):/i, "");
-    if (withoutPrefix.startsWith("users/")) {
-      return normalizeUserId(withoutPrefix) === normalizedSenderId;
-    }
-
-    // Raw email allowlist entries are a break-glass override.
-    if (allowNameMatching && normalizedEmail && isEmailLike(withoutPrefix)) {
-      return withoutPrefix === normalizedEmail;
-    }
-
-    return withoutPrefix.replace(/^users\//i, "") === normalizedSenderId;
-  });
-}
-
-function resolveGroupConfig(params: {
-  groupId: string;
-  groupName?: string | null;
-  groups?: Record<
-    string,
-    {
-      requireMention?: boolean;
-      allow?: boolean;
-      enabled?: boolean;
-      users?: Array<string | number>;
-      systemPrompt?: string;
-    }
-  >;
-}) {
-  const { groupId, groupName, groups } = params;
-  const entries = groups ?? {};
-  const keys = Object.keys(entries);
-  if (keys.length === 0) {
-    return { entry: undefined, allowlistConfigured: false };
-  }
-  const normalizedName = groupName?.trim().toLowerCase();
-  const candidates = [groupId, groupName ?? "", normalizedName ?? ""].filter(Boolean);
-  let entry = candidates.map((candidate) => entries[candidate]).find(Boolean);
-  if (!entry && normalizedName) {
-    entry = entries[normalizedName];
-  }
-  const fallback = entries["*"];
-  return { entry: entry ?? fallback, allowlistConfigured: true, fallback };
-}
-
-function extractMentionInfo(annotations: GoogleChatAnnotation[], botUser?: string | null) {
-  const mentionAnnotations = annotations.filter((entry) => entry.type === "USER_MENTION");
-  const hasAnyMention = mentionAnnotations.length > 0;
-  const botTargets = new Set(["users/app", botUser?.trim()].filter(Boolean) as string[]);
-  const wasMentioned = mentionAnnotations.some((entry) => {
-    const userName = entry.userMention?.user?.name;
-    if (!userName) {
-      return false;
-    }
-    if (botTargets.has(userName)) {
-      return true;
-    }
-    return normalizeUserId(userName) === "app";
-  });
-  return { hasAnyMention, wasMentioned };
-}
-
 /**
  * Resolve bot display name with fallback chain:
  * 1. Account config name
@@ -489,11 +141,6 @@ async function processMessageWithPipeline(params: {
   mediaMaxMb: number;
 }): Promise<void> {
   const { event, account, config, runtime, core, statusSink, mediaMaxMb } = params;
-  const pairing = createScopedPairingAccess({
-    core,
-    channel: "googlechat",
-    accountId: account.accountId,
-  });
   const space = event.space;
   const message = event.message;
   if (!space || !message) {
@@ -510,7 +157,6 @@ async function processMessageWithPipeline(params: {
   const senderId = sender?.name ?? "";
   const senderName = sender?.displayName ?? "";
   const senderEmail = sender?.email ?? undefined;
-  const allowNameMatching = isDangerousNameMatchingEnabled(account.config);
 
   const allowBots = account.config.allowBots === true;
   if (!allowBots) {
@@ -532,202 +178,24 @@ async function processMessageWithPipeline(params: {
     return;
   }
 
-  const defaultGroupPolicy = resolveDefaultGroupPolicy(config);
-  const { groupPolicy, providerMissingFallbackApplied } =
-    resolveAllowlistProviderRuntimeGroupPolicy({
-      providerConfigPresent: config.channels?.googlechat !== undefined,
-      groupPolicy: account.config.groupPolicy,
-      defaultGroupPolicy,
-    });
-  warnMissingProviderGroupPolicyFallbackOnce({
-    providerMissingFallbackApplied,
-    providerKey: "googlechat",
-    accountId: account.accountId,
-    blockedLabel: GROUP_POLICY_BLOCKED_LABEL.space,
-    log: (message) => logVerbose(core, runtime, message),
-  });
-  const groupConfigResolved = resolveGroupConfig({
-    groupId: spaceId,
-    groupName: space.displayName ?? null,
-    groups: account.config.groups ?? undefined,
-  });
-  const groupEntry = groupConfigResolved.entry;
-  const groupUsers = groupEntry?.users ?? account.config.groupAllowFrom ?? [];
-  let effectiveWasMentioned: boolean | undefined;
-
-  if (isGroup) {
-    if (groupPolicy === "disabled") {
-      logVerbose(core, runtime, `drop group message (groupPolicy=disabled, space=${spaceId})`);
-      return;
-    }
-    const groupAllowlistConfigured = groupConfigResolved.allowlistConfigured;
-    const groupAllowed = Boolean(groupEntry) || Boolean((account.config.groups ?? {})["*"]);
-    if (groupPolicy === "allowlist") {
-      if (!groupAllowlistConfigured) {
-        logVerbose(
-          core,
-          runtime,
-          `drop group message (groupPolicy=allowlist, no allowlist, space=${spaceId})`,
-        );
-        return;
-      }
-      if (!groupAllowed) {
-        logVerbose(core, runtime, `drop group message (not allowlisted, space=${spaceId})`);
-        return;
-      }
-    }
-    if (groupEntry?.enabled === false || groupEntry?.allow === false) {
-      logVerbose(core, runtime, `drop group message (space disabled, space=${spaceId})`);
-      return;
-    }
-
-    if (groupUsers.length > 0) {
-      warnDeprecatedUsersEmailEntries(
-        core,
-        runtime,
-        groupUsers.map((v) => String(v)),
-      );
-      const ok = isSenderAllowed(
-        senderId,
-        senderEmail,
-        groupUsers.map((v) => String(v)),
-        allowNameMatching,
-      );
-      if (!ok) {
-        logVerbose(core, runtime, `drop group message (sender not allowed, ${senderId})`);
-        return;
-      }
-    }
-  }
-
-  const dmPolicy = account.config.dm?.policy ?? "pairing";
-  const configAllowFrom = (account.config.dm?.allowFrom ?? []).map((v) => String(v));
-  const normalizedGroupUsers = groupUsers.map((v) => String(v));
-  const senderGroupPolicy =
-    groupPolicy === "disabled"
-      ? "disabled"
-      : normalizedGroupUsers.length > 0
-        ? "allowlist"
-        : "open";
-  const shouldComputeAuth = core.channel.commands.shouldComputeCommandAuthorized(rawBody, config);
-  const storeAllowFrom =
-    !isGroup && dmPolicy !== "allowlist" && (dmPolicy !== "open" || shouldComputeAuth)
-      ? await pairing.readAllowFromStore().catch(() => [])
-      : [];
-  const access = resolveDmGroupAccessWithLists({
+  const access = await applyGoogleChatInboundAccessPolicy({
+    account,
+    config,
+    core,
+    space,
+    message,
     isGroup,
-    dmPolicy,
-    groupPolicy: senderGroupPolicy,
-    allowFrom: configAllowFrom,
-    groupAllowFrom: normalizedGroupUsers,
-    storeAllowFrom,
-    groupAllowFromFallbackToAllowFrom: false,
-    isSenderAllowed: (allowFrom) =>
-      isSenderAllowed(senderId, senderEmail, allowFrom, allowNameMatching),
-  });
-  const effectiveAllowFrom = access.effectiveAllowFrom;
-  const effectiveGroupAllowFrom = access.effectiveGroupAllowFrom;
-  warnDeprecatedUsersEmailEntries(core, runtime, effectiveAllowFrom);
-  const commandAllowFrom = isGroup ? effectiveGroupAllowFrom : effectiveAllowFrom;
-  const useAccessGroups = config.commands?.useAccessGroups !== false;
-  const senderAllowedForCommands = isSenderAllowed(
     senderId,
+    senderName,
     senderEmail,
-    commandAllowFrom,
-    allowNameMatching,
-  );
-  const commandAuthorized = shouldComputeAuth
-    ? core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
-        useAccessGroups,
-        authorizers: [
-          { configured: commandAllowFrom.length > 0, allowed: senderAllowedForCommands },
-        ],
-      })
-    : undefined;
-
-  if (isGroup) {
-    const requireMention = groupEntry?.requireMention ?? account.config.requireMention ?? true;
-    const annotations = message.annotations ?? [];
-    const mentionInfo = extractMentionInfo(annotations, account.config.botUser);
-    const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
-      cfg: config,
-      surface: "googlechat",
-    });
-    const mentionGate = resolveMentionGatingWithBypass({
-      isGroup: true,
-      requireMention,
-      canDetectMention: true,
-      wasMentioned: mentionInfo.wasMentioned,
-      implicitMention: false,
-      hasAnyMention: mentionInfo.hasAnyMention,
-      allowTextCommands,
-      hasControlCommand: core.channel.text.hasControlCommand(rawBody, config),
-      commandAuthorized: commandAuthorized === true,
-    });
-    effectiveWasMentioned = mentionGate.effectiveWasMentioned;
-    if (mentionGate.shouldSkip) {
-      logVerbose(core, runtime, `drop group message (mention required, space=${spaceId})`);
-      return;
-    }
-  }
-
-  if (isGroup && access.decision !== "allow") {
-    logVerbose(
-      core,
-      runtime,
-      `drop group message (sender policy blocked, reason=${access.reason}, space=${spaceId})`,
-    );
-    return;
-  }
-
-  if (!isGroup) {
-    if (account.config.dm?.enabled === false) {
-      logVerbose(core, runtime, `Blocked Google Chat DM from ${senderId} (dmPolicy=disabled)`);
-      return;
-    }
-
-    if (access.decision !== "allow") {
-      if (access.decision === "pairing") {
-        const { code, created } = await pairing.upsertPairingRequest({
-          id: senderId,
-          meta: { name: senderName || undefined, email: senderEmail },
-        });
-        if (created) {
-          logVerbose(core, runtime, `googlechat pairing request sender=${senderId}`);
-          try {
-            await sendGoogleChatMessage({
-              account,
-              space: spaceId,
-              text: core.channel.pairing.buildPairingReply({
-                channel: "googlechat",
-                idLine: `Your Google Chat user id: ${senderId}`,
-                code,
-              }),
-            });
-            statusSink?.({ lastOutboundAt: Date.now() });
-          } catch (err) {
-            logVerbose(core, runtime, `pairing reply failed for ${senderId}: ${String(err)}`);
-          }
-        }
-      } else {
-        logVerbose(
-          core,
-          runtime,
-          `Blocked unauthorized Google Chat sender ${senderId} (dmPolicy=${dmPolicy})`,
-        );
-      }
-      return;
-    }
-  }
-
-  if (
-    isGroup &&
-    core.channel.commands.isControlCommandMessage(rawBody, config) &&
-    commandAuthorized !== true
-  ) {
-    logVerbose(core, runtime, `googlechat: drop control command from ${senderId}`);
+    rawBody,
+    statusSink,
+    logVerbose: (message) => logVerbose(core, runtime, message),
+  });
+  if (!access.ok) {
     return;
   }
+  const { commandAuthorized, effectiveWasMentioned, groupSystemPrompt } = access;
 
   const { route, buildEnvelope } = resolveInboundRouteEnvelopeBuilderWithRuntime({
     cfg: config,
@@ -762,8 +230,6 @@ async function processMessageWithPipeline(params: {
     body: rawBody,
   });
 
-  const groupSystemPrompt = groupConfigResolved.entry?.systemPrompt?.trim() || undefined;
-
   const ctxPayload = core.channel.reply.finalizeInboundContext({
     Body: body,
     BodyForAgent: rawBody,