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

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @mercury-fw/channel-google-chat
 
+## 0.7.0
+
+### Minor Changes
+
+- 4184ea6: - `loginLinkText` words a login link the same way on every channel, and the contract states that a login link is shown only to the person it's for.
+  - Google Chat shows the login to a service a plugin acts on as the person (Jira, Bitbucket) as a button that opens it, visible only to them: in a shared space it's a private message to whoever asked.
+  - `@mercury-fw/channel-google-chat` needs `@mercury-fw/channel-types` 0.46.0 or later.
+
+## 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,10 @@ 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.
+
+When a plugin that acts as the person (Jira, Bitbucket) needs them to log in, the channel sends a card with a button that opens the service's login, visible only to that person: in a direct message the space is already theirs, in a shared space the card is a private message to whoever asked, since anyone else opening it would log their own account in as them. The service sends the browser back to the HTTP channel's `/login/callback`, so the app needs [`@mercury-fw/channel-http`](https://www.npmjs.com/package/@mercury-fw/channel-http) with `HTTP_SURFACE_PUBLIC_URL` too; without it Mercury answers that nobody can log in on this instance.
+
 ## Table of contents
 
 - [Setting up the Chat app](#setting-up-the-chat-app)

package/dist/google-chat-app-client.d.ts

@@ -55,10 +55,16 @@ export type ChatCard = {
     };
     sections: ChatCardSection[];
 };
-/** Posts `card` as a Cards v2 message to `space`. Returns the created message's `name`, same shape as `sendMessage`. */
+/**
+ * Posts `card` as a Cards v2 message to `space`. Returns the created message's
+ * `name`, same shape as `sendMessage`. With `privateViewer` (`users/<id>`) only
+ * that user and the app see it, in a space anyone else is in too.
+ */
 export declare function sendCard(space: string, card: ChatCard, deps: {
     tokenSource: TokenSource;
     fetchFn?: FetchFn;
+}, options?: {
+    privateViewer?: string;
 }): Promise<{
     name: string;
 }>;

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-app-client.ts

@@ -171,17 +171,22 @@ export type ChatCardSection = {
 };
 export type ChatCard = { header?: { title: string }; sections: ChatCardSection[] };
 
-/** Posts `card` as a Cards v2 message to `space`. Returns the created message's `name`, same shape as `sendMessage`. */
+/**
+ * Posts `card` as a Cards v2 message to `space`. Returns the created message's
+ * `name`, same shape as `sendMessage`. With `privateViewer` (`users/<id>`) only
+ * that user and the app see it, in a space anyone else is in too.
+ */
 export async function sendCard(
   space: string,
   card: ChatCard,
   deps: { tokenSource: TokenSource; fetchFn?: FetchFn },
+  options: { privateViewer?: string } = {},
 ): Promise<{ name: string }> {
-  const data = (await callChatApi(
-    `${space}/messages`,
-    { method: "POST", body: { cardsV2: [{ cardId: "card", card }] } },
-    deps,
-  )) as { name: string };
+  const body = {
+    cardsV2: [{ cardId: "card", card }],
+    ...(options.privateViewer === undefined ? {} : { privateMessageViewer: { name: options.privateViewer } }),
+  };
+  const data = (await callChatApi(`${space}/messages`, { method: "POST", body }, deps)) as { name: string };
   return { name: data.name };
 }
 

package/google-chat-provider.ts

@@ -32,9 +32,12 @@ import {
 import { openSubscription, type PubSubSubscription, type StreamMessage } from "./google-chat-pubsub-stream.ts";
 import { splitForSendLimit } from "./google-chat-message-buffer.ts";
 import {
+  detectLoginRequired,
   detectPendingConfirmation,
+  loginLinkText,
   PENDING_CONFIRMATION_NOTE,
   NO_REPLY,
+  type LoginRequest,
   type PendingConfirmation,
   type ToolOutcome,
   type Provider,
@@ -73,6 +76,13 @@ function buildConfirmCard(pending: PendingConfirmation): ChatCard {
   };
 }
 
+/** The card that shows a person the link to log in to a service a plugin acts on as them: one button that opens it. */
+function buildLoginCard(login: LoginRequest): ChatCard {
+  return {
+    sections: [{ widgets: [{ buttonList: { buttons: [{ text: loginLinkText(login), onClick: { openLink: { url: login.url } } }] } }] }],
+  };
+}
+
 const TOOL_STATUS_LINES: Record<"loading" | ToolOutcome, string> = {
   loading: "In corso…",
   success: "Fatto.",
@@ -197,6 +207,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 +223,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 +247,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 +260,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 +329,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);
@@ -325,8 +348,12 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
     });
   let activeSubscription: PubSubSubscription | undefined;
 
-  /** Per-turn output sink — same responsibilities as the retired `ChatStreamer`, rebuilt against the new client. */
-  function createSink(space: string): TurnSink {
+  /**
+   * Per-turn output sink — same responsibilities as the retired `ChatStreamer`,
+   * rebuilt against the new client. `viewer` is the person the turn is for;
+   * outside a direct message, what only they may see is sent to them alone.
+   */
+  function createSink(space: string, viewer: { user: string; isDirectMessage: boolean }): TurnSink {
     let chain: Promise<void> = Promise.resolve();
 
     function enqueue(fn: () => Promise<void>): void {
@@ -363,6 +390,9 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
     // the same turn (e.g. after a tool call) always gets its own new card,
     // never reuses this one.
     let receivingCardName: string | undefined;
+
+    // A tool asking again in the same turn hands back the same pending login.
+    const shownLogins = new Set<string>();
     enqueue(async () => {
       log(`[chat:${space}] [out] receiving card`);
       const sent = await sendCardFn(space, buildReceivingCard(), clientDeps);
@@ -457,6 +487,16 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
             sentMessageNames.add(sent.name);
           });
         }
+        const login = detectLoginRequired(step);
+        if (login && !shownLogins.has(login.url)) {
+          shownLogins.add(login.url);
+          enqueue(async () => {
+            log(`[chat:${space}] [out] login card: ${login.service}`);
+            const options = viewer.isDirectMessage ? undefined : { privateViewer: viewer.user };
+            const sent = await sendCardFn(space, buildLoginCard(login), clientDeps, options);
+            sentMessageNames.add(sent.name);
+          });
+        }
       },
       finalize: async (finalText: string) => {
         const trimmed = finalText.trim();
@@ -483,6 +523,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);
@@ -505,7 +547,7 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
 
     busySessions.add(sessionKey);
     try {
-      const sink = createSink(event.space);
+      const sink = createSink(event.space, { user: event.sender, isDirectMessage: event.isDirectMessage });
       await handleTurn(
         {
           channel: "google-chat",
@@ -556,7 +598,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.7.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -31,10 +31,10 @@
     "@google-cloud/pubsub": "^5.3.1"
   },
   "peerDependencies": {
-    "@mercury-fw/channel-types": ">=0.36.0 <1.0.0"
+    "@mercury-fw/channel-types": ">=0.46.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.42.0",
+    "@mercury-fw/channel-types": "0.46.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"