fix(gchat): verify project-number tokens against Chat issuer certs; infer endpoint URL only after verification

Two fixes to the direct-webhook verification introduced in this PR:

1. Project-number-audience tokens are self-signed JWTs from
   chat@system.gserviceaccount.com, not OIDC ID tokens. verifyIdToken can
   never validate them: it checks Google's OIDC federated certs and only
   accepts accounts.google.com issuers, so the previous iss claim check was
   unreachable and real project-number tokens always failed. Verify them per
   Google's reference implementation instead: verifySignedJwtWithCertsAsync
   against the Chat service account's X.509 certs (cached 1h) with issuer
   chat@system.gserviceaccount.com. Endpoint-URL tokens keep the OIDC
   verifyIdToken path plus email/email_verified claim checks. When both
   verifiers are configured, either token type is accepted.

2. Move button-click endpoint URL inference after successful verification.
   Previously an unauthenticated request (401) could still poison
   inferredEndpointUrl via a spoofed Host header, first-write-wins, and the
   poisoned URL flowed into every outbound card's action routing.

Adds regression tests for both; updates docs, README, and the changeset.

Author: bensabic

.changeset/gchat-endpoint-url-audience.md

@@ -2,26 +2,34 @@
 "@chat-adapter/gchat": patch
 ---
 
-fix(gchat): accept `endpointUrl` as a direct-webhook JWT audience
+fix(gchat): accept `endpointUrl` as a direct-webhook verifier and verify each token type correctly
 
 When a Google Chat app's connection setting **Authentication audience** is set
 to **HTTP endpoint URL** — Google's recommended option for HTTP-hosted apps
 not behind Cloud Run IAM, and the only mode available for Workspace Add-on
-Chat apps — incoming JWTs have `aud` equal to the endpoint URL rather than
-the GCP project number. Previously the adapter only verified against
-`googleChatProjectNumber`, so URL-audience tokens always failed with 401
-Unauthorized. The adapter now verifies the bearer token against
-`googleChatProjectNumber` and/or `endpointUrl`, accepting either when both
-are set, and the constructor's fail-closed check accepts `endpointUrl` as a
-valid direct-webhook verifier.
+Chat apps — incoming tokens are Google OIDC ID tokens whose `aud` is the
+endpoint URL rather than the GCP project number. Previously the adapter only
+verified against `googleChatProjectNumber`, so URL-audience tokens always
+failed with 401 Unauthorized. The adapter now accepts `endpointUrl` as a
+direct-webhook verifier (including in the constructor's fail-closed check),
+validating the OIDC token's audience plus the Google Chat issuer email claims
+(`chat@system.gserviceaccount.com`, or the
+`service-{projectNumber}@gcp-sa-gsuiteaddons.iam.gserviceaccount.com` service
+identity for Workspace Add-on Chat apps) with `email_verified: true` — a
+public endpoint URL audience alone is not sufficient to forge a request.
 
-Direct-webhook tokens are now also matched against the expected Google Chat
-issuer/email claims (`chat@system.gserviceaccount.com`, or the
-`service-{projectNumber}@gcp-sa-gsuiteaddons.iam.gserviceaccount.com`
-service identity for Workspace Add-on Chat apps) with `email_verified: true`,
-so a public endpoint URL audience alone is not sufficient to forge a request.
+Project-number-audience tokens are now verified per Google's reference
+implementation: they are JWTs self-signed by
+`chat@system.gserviceaccount.com`, so the adapter checks them against that
+service account's X.509 certificates with issuer
+`chat@system.gserviceaccount.com` (previously it used `verifyIdToken`, which
+only accepts Google OIDC issuers and certs and therefore rejected every real
+project-number token). When both verifiers are configured, either token type
+is accepted.
 
 The adapter still infers an endpoint URL from incoming requests for
 button-click action routing only — that inferred value is never used as a
-JWT verification audience, because `request.url` derives from the
-attacker-controllable `Host` header in serverless runtimes.
+JWT verification audience, and inference now only happens after a request
+has passed verification (or verification was explicitly disabled), because
+`request.url` derives from the attacker-controllable `Host` header in
+serverless runtimes.

apps/docs/content/adapters/official/gchat.mdx

@@ -208,14 +208,14 @@ If you only configure a direct-webhook verifier, incoming Pub/Sub-shaped request
 
 #### Which direct-webhook option do I need?
 
-| Your Chat app                                                                                            | JWT `aud`        | JWT `email`                                                                | Set                                                                |
-| -------------------------------------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| Standalone Chat app, **Authentication audience: Project number** (in Chat API config)                   | project number   | `chat@system.gserviceaccount.com`                                          | `googleChatProjectNumber`                                          |
-| Standalone Chat app, **Authentication audience: HTTP endpoint URL**                                      | endpoint URL     | `chat@system.gserviceaccount.com`                                          | `endpointUrl`                                                      |
-| **Workspace Add-on Chat app** (built via Google Workspace Marketplace SDK; the audience is hardcoded)    | endpoint URL     | `service-{projectNumber}@gcp-sa-gsuiteaddons.iam.gserviceaccount.com`      | `endpointUrl`                                                      |
-| Mixed across envs / not sure                                                                             | varies           | varies                                                                     | both `googleChatProjectNumber` and `endpointUrl`                   |
-
-When both `googleChatProjectNumber` and `endpointUrl` are set, either audience is accepted. If you don't know which mode your app uses, look at the JWT `email` claim of an incoming request — `gcp-sa-gsuiteaddons` means it's a Workspace Add-on (URL audience).
+| Your Chat app                                                                                            | Token type & `aud`                       | Signed by                                                                  | Set                                                                |
+| -------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| Standalone Chat app, **Authentication audience: Project number** (in Chat API config)                   | self-signed JWT, `aud` = project number   | `chat@system.gserviceaccount.com` (its own X.509 certs)                    | `googleChatProjectNumber`                                          |
+| Standalone Chat app, **Authentication audience: HTTP endpoint URL**                                      | Google OIDC ID token, `aud` = endpoint URL | Google (`email`: `chat@system.gserviceaccount.com`)                        | `endpointUrl`                                                      |
+| **Workspace Add-on Chat app** (built via Google Workspace Marketplace SDK; the audience is hardcoded)    | Google OIDC ID token, `aud` = endpoint URL | Google (`email`: `service-{projectNumber}@gcp-sa-gsuiteaddons.iam.gserviceaccount.com`) | `endpointUrl`                                                      |
+| Mixed across envs / not sure                                                                             | varies                                    | varies                                                                     | both `googleChatProjectNumber` and `endpointUrl`                   |
+
+The two token types are verified differently, matching [Google's reference implementation](https://developers.google.com/workspace/chat/verify-requests-from-chat): endpoint-URL tokens are standard OIDC ID tokens checked against Google's public certs plus the Chat service-account `email` claim; project-number tokens are self-signed by `chat@system.gserviceaccount.com` and checked against that service account's own X.509 certificates. When both `googleChatProjectNumber` and `endpointUrl` are set, either token type is accepted. If you don't know which mode your app uses, look at an incoming token: an `email` claim containing `gcp-sa-gsuiteaddons` means it's a Workspace Add-on (URL audience).
 
 <Callout type="info">
 Workspace Add-on Chat apps don't expose an "Authentication audience" radio; their token `aud` is always the endpoint URL. Set `endpointUrl` for these.

packages/adapter-gchat/README.md

@@ -240,7 +240,9 @@ createGoogleChatAdapter({
 });
 ```
 
-Use `endpointUrl` when the setting is **HTTP endpoint URL**. Workspace Add-on Chat apps always use URL audience tokens. When both `googleChatProjectNumber` and `endpointUrl` are set, either audience is accepted.
+Use `endpointUrl` when the setting is **HTTP endpoint URL**. Workspace Add-on Chat apps always use URL audience tokens. When both `googleChatProjectNumber` and `endpointUrl` are set, either token type is accepted.
+
+The two modes carry different token types, and the adapter verifies each per [Google's reference implementation](https://developers.google.com/workspace/chat/verify-requests-from-chat): endpoint-URL tokens are standard Google OIDC ID tokens (checked against Google's public certs, plus the Chat service-account `email` claim with `email_verified`), while project-number tokens are JWTs self-signed by `chat@system.gserviceaccount.com` (checked against that service account's X.509 certificates with issuer `chat@system.gserviceaccount.com`). The configured `endpointUrl` must exactly match the URL registered in the Chat API console — a trailing-slash or scheme mismatch fails verification.
 
 ### Pub/Sub push messages
 

packages/adapter-gchat/src/index.test.ts

@@ -2788,15 +2788,28 @@ describe("GoogleChatAdapter", () => {
 
   describe("webhook verification", () => {
     let verifyIdTokenSpy: ReturnType<typeof vi.spyOn>;
+    let verifySignedJwtSpy: ReturnType<typeof vi.spyOn>;
+    let fetchSpy: ReturnType<typeof vi.spyOn>;
 
     beforeEach(() => {
       verifyIdTokenSpy = vi
         .spyOn(auth.OAuth2.prototype, "verifyIdToken")
         .mockRejectedValue(new Error("Invalid token"));
+      // Project-number tokens are self-signed by chat@system and verified
+      // against its X.509 certs, not via verifyIdToken.
+      verifySignedJwtSpy = vi
+        .spyOn(auth.OAuth2.prototype, "verifySignedJwtWithCertsAsync")
+        .mockRejectedValue(new Error("Invalid token"));
+      // Stub the Chat issuer cert fetch — never hit the network in unit tests.
+      fetchSpy = vi
+        .spyOn(globalThis, "fetch")
+        .mockResolvedValue(Response.json({ "test-kid": "test-cert" }));
     });
 
     afterEach(() => {
       verifyIdTokenSpy.mockRestore();
+      verifySignedJwtSpy.mockRestore();
+      fetchSpy.mockRestore();
     });
 
     it("should reject direct webhook without Authorization header when project number is configured", async () => {
@@ -2813,8 +2826,9 @@ describe("GoogleChatAdapter", () => {
 
       const response = await adapter.handleWebhook(request);
       expect(response.status).toBe(401);
-      // Should not even call verifyIdToken — no Bearer token present
+      // Should not even attempt verification — no Bearer token present
       expect(verifyIdTokenSpy).not.toHaveBeenCalled();
+      expect(verifySignedJwtSpy).not.toHaveBeenCalled();
     });
 
     it("should reject direct webhook with invalid Bearer token when project number is configured", async () => {
@@ -2834,18 +2848,48 @@ describe("GoogleChatAdapter", () => {
 
       const response = await adapter.handleWebhook(request);
       expect(response.status).toBe(401);
-      expect(verifyIdTokenSpy).toHaveBeenCalledWith({
-        idToken: "invalid-token",
-        audience: "123456789",
+      // Project-number tokens are verified against the Chat service
+      // account's certs with issuer chat@system.gserviceaccount.com.
+      expect(verifySignedJwtSpy).toHaveBeenCalledWith(
+        "invalid-token",
+        { "test-kid": "test-cert" },
+        "123456789",
+        ["chat@system.gserviceaccount.com"]
+      );
+    });
+
+    it("should not infer an endpoint URL from a request that fails verification", async () => {
+      // An unauthenticated caller must not be able to poison the
+      // button-click routing URL: inference only happens after the request
+      // has been verified (or verification explicitly disabled).
+      const { adapter } = await createInitializedAdapter({
+        googleChatProjectNumber: "123456789",
+      });
+
+      const event = makeMessageEvent({ messageText: "Hello" });
+      const request = new Request("https://attacker.example/webhook", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(event),
       });
+
+      const response = await adapter.handleWebhook(request);
+      expect(response.status).toBe(401);
+      expect(
+        (adapter as unknown as { inferredEndpointUrl?: string })
+          .inferredEndpointUrl
+      ).toBeUndefined();
     });
 
     it("should allow direct webhook with valid Bearer token when project number is configured", async () => {
-      verifyIdTokenSpy.mockResolvedValue({
+      // Real project-number tokens are self-signed JWTs from
+      // chat@system.gserviceaccount.com — verifiable only against that
+      // service account's X.509 certs, never via verifyIdToken (whose
+      // default issuer allowlist is accounts.google.com).
+      verifySignedJwtSpy.mockResolvedValue({
         getPayload: () => ({
           iss: "chat@system.gserviceaccount.com",
           aud: "123456789",
-          email: "chat@system.gserviceaccount.com",
         }),
       });
 
@@ -2865,10 +2909,13 @@ describe("GoogleChatAdapter", () => {
 
       const response = await adapter.handleWebhook(request);
       expect(response.status).toBe(200);
-      expect(verifyIdTokenSpy).toHaveBeenCalledWith({
-        idToken: "valid-google-jwt",
-        audience: "123456789",
-      });
+      expect(verifySignedJwtSpy).toHaveBeenCalledWith(
+        "valid-google-jwt",
+        { "test-kid": "test-cert" },
+        "123456789",
+        ["chat@system.gserviceaccount.com"]
+      );
+      expect(verifyIdTokenSpy).not.toHaveBeenCalled();
     });
 
     it("should allow direct webhook with valid Bearer token when only endpointUrl is configured (URL audience)", async () => {
@@ -3014,15 +3061,18 @@ describe("GoogleChatAdapter", () => {
 
       await adapter.handleWebhook(request);
 
-      // verifyIdToken must be called with only the explicit project number,
-      // never the inferred URL.
-      expect(verifyIdTokenSpy).toHaveBeenCalledWith({
-        idToken: "attacker-token",
-        audience: "123456789",
-      });
+      // Only the project-number verifier runs; the inferred URL must never
+      // be used as an OIDC audience.
+      expect(verifyIdTokenSpy).not.toHaveBeenCalled();
+      expect(verifySignedJwtSpy).toHaveBeenCalledWith(
+        "attacker-token",
+        { "test-kid": "test-cert" },
+        "123456789",
+        ["chat@system.gserviceaccount.com"]
+      );
     });
 
-    it("should accept either audience when both googleChatProjectNumber and endpointUrl are configured", async () => {
+    it("should accept an endpoint-URL token when both googleChatProjectNumber and endpointUrl are configured", async () => {
       verifyIdTokenSpy.mockResolvedValue({
         getPayload: () => ({
           iss: "https://accounts.google.com",
@@ -3051,8 +3101,45 @@ describe("GoogleChatAdapter", () => {
       expect(response.status).toBe(200);
       expect(verifyIdTokenSpy).toHaveBeenCalledWith({
         idToken: "valid-google-jwt",
-        audience: ["123456789", "https://example.com/webhook"],
+        audience: "https://example.com/webhook",
+      });
+      // The project-number verifier is not needed when the OIDC path passes.
+      expect(verifySignedJwtSpy).not.toHaveBeenCalled();
+    });
+
+    it("should fall back to the project-number verifier when both are configured and the OIDC check fails", async () => {
+      // verifyIdTokenSpy keeps its default rejection (not an OIDC token);
+      // the self-signed project-number verification succeeds.
+      verifySignedJwtSpy.mockResolvedValue({
+        getPayload: () => ({
+          iss: "chat@system.gserviceaccount.com",
+          aud: "123456789",
+        }),
+      });
+
+      const { adapter } = await createInitializedAdapter({
+        googleChatProjectNumber: "123456789",
+        endpointUrl: "https://example.com/webhook",
       });
+
+      const event = makeMessageEvent({ messageText: "Hello" });
+      const request = new Request("https://example.com/webhook", {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: "Bearer self-signed-chat-jwt",
+        },
+        body: JSON.stringify(event),
+      });
+
+      const response = await adapter.handleWebhook(request);
+      expect(response.status).toBe(200);
+      expect(verifySignedJwtSpy).toHaveBeenCalledWith(
+        "self-signed-chat-jwt",
+        { "test-kid": "test-cert" },
+        "123456789",
+        ["chat@system.gserviceaccount.com"]
+      );
     });
 
     it("should not throw in constructor when only endpointUrl is configured", () => {