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

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @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
+
+- a7f2f13: A user directory decides who people are and what they may make Mercury do.
+
+  - An app can declare a `directory` in `mercury.config.ts`. Given whoever a channel says is talking, it returns the person with their roles. The person's key is `<directory name>:<id>`, so one person reached from several channels keeps one private area, one memory and one set of confirmations.
+  - With a directory the instance is closed. Someone it doesn't know gets a refusal and nothing runs, unless `access.unknown` is `"allow"`; `access.unknownMessage` sets what they're told. A directory that can't be reached, or fails to load, refuses everyone but the terminal. Answers are cached for five minutes, so a revoked role stops counting within that time.
+  - `mercury.act-as-self` (every plugin) or `mercury.act-as-self.<plugin>` (one) lets a person make Mercury act with its own identity.
+    - A plugin acting as Mercury, such as atlassian-admin, is offered only to those people, and on the terminal.
+    - A plugin acting as the person also gives them each tool a second time, as `<tool>AsMercury`.
+    - Every call made as Mercury for someone is logged with who asked.
+  - `access.plugins` restricts a plugin to some roles. Prompts, skills and the manifest follow what each person is offered.
+  - New package `@mercury-fw/directory-static`: people, their identities on each channel and their roles, listed in `DIRECTORY_STATIC_PEOPLE`.
+  - The channel contract is at version 5:
+    - `ChannelRuntimeContext.admit` says whether the core talks to a caller;
+    - the reads are per person and async, the manifest included;
+    - `DirectoryPlugin` is the directory contract;
+    - `Principal` no longer carries `roles`.
+  - `channel-http` answers `403` to a caller the directory doesn't know and `503` when it can't be reached, on every route.
+  - `auth-static` refuses `roles` in `AUTH_STATIC_TOKENS`: roles come from the directory.
+
 ## 0.4.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/index.ts

@@ -22,7 +22,7 @@ function require(env: ChannelRuntimeContext["env"], name: string): string {
 export const googleChatChannel: ChannelPlugin = {
   // The contract this channel is written for, as a literal: importing
   // CHANNEL_API_VERSION would report whichever contract is installed.
-  apiVersion: 4,
+  apiVersion: 5,
   name: "google-chat",
   build: (ctx) => {
     // No subscription configured ⇒ this instance simply doesn't run Google Chat.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-google-chat",
-  "version": "0.4.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.40.0",
+    "@mercury-fw/channel-types": "0.44.1",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"