@mercury-fw/channel-google-chat 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @mercury-fw/channel-google-chat
 
+## 0.6.0
+
+### Minor Changes
+
+- c24de78: A Google Chat sender is recognised as their ZITADEL user.
+
+  - `channel-google-chat` passes the sender's email on as a claim (`claims.email`), on messages and on card clicks, when Google vouches for it: a person's (`HUMAN`) only.
+  - `zitadelDirectory` resolves a Google Chat sender to the one active ZITADEL user with that email, verified, whose links to the Google identity provider (`ZITADEL_GOOGLE_IDP_ID`, new and optional) include the sender's own Google account. Without that variable nobody is recognised from Chat. Anyone else on Chat stays unknown and can link their account with a code.
+  - `mfw create` lists `ZITADEL_GOOGLE_IDP_ID` in the env example of an app with the ZITADEL directory.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -24,6 +24,8 @@ channels: [googleChatChannel],
 | `GOOGLE_CHAT_APP_CLIENT_EMAIL` | The service account the app authenticates as. |
 | `GOOGLE_CHAT_APP_PRIVATE_KEY` | That service account's private key, on one line with literal `\n` (step 5 writes it that way). |
 
+Each message reaches the core as `google-chat:users/<id>`, the sender's Chat user, with their email when Google vouches for it (a person's, never a bot's), which a user directory can join on: the ZITADEL directory of `@mercury-fw/plugin-zitadel` does.
+
 ## Table of contents
 
 - [Setting up the Chat app](#setting-up-the-chat-app)

package/dist/google-chat-provider.d.ts

@@ -41,6 +41,8 @@ export type ParsedMessageEvent = {
     space: string;
     sender: string;
     senderDisplayName: string | undefined;
+    /** The sender's email, which Google vouches for: a person's only, never a bot's. */
+    senderEmail: string | undefined;
     /**
      * True only when `space.type` is exactly `"DM"` (the Chat API's shape
      * for a private 1:1 space) — anything else, including a missing field,
@@ -54,11 +56,12 @@ export type ParsedCardClickEvent = {
     kind: "card-click";
     space: string;
     sender: string;
+    senderEmail: string | undefined;
     parameters: Record<string, string>;
 };
 /** Parses one decoded Pub/Sub event, or `null` if it isn't a kind this provider acts on. */
 export declare function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardClickEvent | null;
-export type CardClickHandler = (params: Record<string, string>, space: string, sender: string) => Promise<void>;
+export type CardClickHandler = (params: Record<string, string>, space: string, sender: string, senderEmail?: string) => Promise<void>;
 export type GoogleChatProviderDeps = {
     credentials: ServiceAccountCredentials;
     subscription: string;

package/google-chat-provider.ts

@@ -197,6 +197,8 @@ export type ParsedMessageEvent = {
   space: string;
   sender: string;
   senderDisplayName: string | undefined;
+  /** The sender's email, which Google vouches for: a person's only, never a bot's. */
+  senderEmail: string | undefined;
   /**
    * True only when `space.type` is exactly `"DM"` (the Chat API's shape
    * for a private 1:1 space) — anything else, including a missing field,
@@ -211,9 +213,15 @@ export type ParsedCardClickEvent = {
   kind: "card-click";
   space: string;
   sender: string;
+  senderEmail: string | undefined;
   parameters: Record<string, string>;
 };
 
+/** The email Google vouches for on `sender`: a person's only (`HUMAN`), never a bot's or an unknown kind's. */
+function emailOf(sender: RawChatSender | undefined): string | undefined {
+  return typeof sender?.email === "string" && sender.email !== "" && sender.type === "HUMAN" ? sender.email : undefined;
+}
+
 /** Parses one decoded Pub/Sub event, or `null` if it isn't a kind this provider acts on. */
 export function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardClickEvent | null {
   const event = raw as RawChatEvent;
@@ -229,6 +237,7 @@ export function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardCli
       space: m.space.name,
       sender: m.sender.name,
       senderDisplayName: m.sender.displayName,
+      senderEmail: emailOf(m.sender),
       isDirectMessage: m.space.type === "DM",
     };
   }
@@ -241,12 +250,12 @@ export function parseChatEvent(raw: unknown): ParsedMessageEvent | ParsedCardCli
         parameters[p.key] = p.value;
       }
     }
-    return { kind: "card-click", space: event.space.name, sender: event.user.name, parameters };
+    return { kind: "card-click", space: event.space.name, sender: event.user.name, senderEmail: emailOf(event.user), parameters };
   }
   return null;
 }
 
-export type CardClickHandler = (params: Record<string, string>, space: string, sender: string) => Promise<void>;
+export type CardClickHandler = (params: Record<string, string>, space: string, sender: string, senderEmail?: string) => Promise<void>;
 
 export type GoogleChatProviderDeps = {
   credentials: ServiceAccountCredentials;
@@ -310,13 +319,17 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
    */
   const onCardClick: CardClickHandler =
     deps.onCardClick ??
-    (async (params, space, sender) => {
+    (async (params, space, sender, senderEmail) => {
       const token = params.token;
       if (!token) {
         log(`[chat] card click with no token parameter`);
         return;
       }
-      const reply = await deps.confirm(token, deriveSessionKey(space, sender), { id: sender, provider: "google-chat" });
+      const reply = await deps.confirm(token, deriveSessionKey(space, sender), {
+        id: sender,
+        provider: "google-chat",
+        ...(senderEmail === undefined ? {} : { claims: { email: senderEmail } }),
+      });
       if (reply !== null) {
         log(`[chat:${space}] [out] ${reply}`);
         const sent = await sendMessageFn(space, reply, clientDeps);
@@ -483,6 +496,8 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
       id: event.sender,
       provider: "google-chat",
       ...(event.senderDisplayName ? { displayName: event.senderDisplayName } : {}),
+      // A directory joins a Chat identity to a person on it (see the ZITADEL directory).
+      ...(event.senderEmail === undefined ? {} : { claims: { email: event.senderEmail } }),
     };
 
     const confirmReply = await deps.confirm(event.text, sessionKey, principal);
@@ -556,7 +571,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
       if (parsed.kind === "message") {
         await processMessageEvent(parsed, handleTurn);
       } else {
-        await onCardClick(parsed.parameters, parsed.space, parsed.sender);
+        await onCardClick(parsed.parameters, parsed.space, parsed.sender, parsed.senderEmail);
       }
     } catch (err) {
       log(`[chat] event handling failed: ${String(err)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-google-chat",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "@mercury-fw/channel-types": ">=0.36.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.42.0",
+    "@mercury-fw/channel-types": "0.44.1",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"