Add intentional mentions to generic webhooks (#1051)

* Add support for explicit mentions

* Add test

* changelog

* tyoes

Author: Half-Shot

changelog.d/1051.feature

@@ -0,0 +1 @@
+Add new `mentions` field to generic hook transformation functions, to intentionally mention users. 

docs/setup/webhooks.md

@@ -174,6 +174,10 @@ The `v2` api expects an object to be returned from the `result` variable.
   "plain": "Some text", // The plaintext value to be used for the Matrix message.
   "html": "<b>Some</b> text", // The HTML value to be used for the Matrix message. If not provided, plain will be interpreted as markdown.
   "msgtype": "some.type", // The message type, such as m.notice or m.text, to be used for the Matrix message. If not provided, m.notice will be used.
+  "mentions": { // Explicitly mention these users, see https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions 
+    "room": true,
+    "user_ids": ["@foo:bar"]
+  },
   "webhookResponse": { // Optional response to send to the webhook requestor. All fields are optional. Defaults listed.
     "body": "{ \"ok\": true }",
     "contentType": "application/json",

src/App/BridgeApp.ts

@@ -10,6 +10,7 @@ import BotUsersManager from "../Managers/BotUsersManager";
 import * as Sentry from '@sentry/node';
 import { GenericHookConnection } from "../Connections";
 import { UserTokenStore } from "../tokens/UserTokenStore";
+import { WebhookTransformer } from "../generic/transformer";
 
 Logger.configure({console: "info"});
 const log = new Logger("App");
@@ -46,7 +47,7 @@ export async function start(config: BridgeConfig, registration: IAppserviceRegis
     }
 
     if (config.generic?.allowJsTransformationFunctions) {
-        await GenericHookConnection.initialiseQuickJS();
+        await WebhookTransformer.initialiseQuickJS();
     }
 
     const botUsersManager = new BotUsersManager(config, appservice);

src/Connections/GenericHook.ts

@@ -15,6 +15,7 @@ import { GenericWebhookEventResult } from "../generic/types";
 import { StatusCodes } from "http-status-codes";
 import { IBridgeStorageProvider } from "../Stores/StorageProvider";
 import { formatDuration, isMatch, millisecondsToHours } from "date-fns";
+import { ExecuteResultContent, ExecuteResultWebhookResponse, WebhookTransformer } from "../generic/transformer";
 
 export interface GenericHookConnectionState extends IConnectionState {
     /**
@@ -63,21 +64,6 @@ export interface GenericHookAccountData {
     [hookId: string]: string;
 }
 
-export interface WebhookResponse {
-    body: string;
-    contentType?: string;
-    statusCode?: number;
-}
-
-interface WebhookTransformationResult {
-    version: string;
-    plain?: string;
-    html?: string;
-    msgtype?: string;
-    empty?: boolean;
-    webhookResponse?: WebhookResponse;
-}
-
 export interface GenericHookServiceConfig {
     userIdPrefix?: string;
     allowJsTransformationFunctions?: boolean,
@@ -89,7 +75,6 @@ export interface GenericHookServiceConfig {
 const log = new Logger("GenericHookConnection");
 const md = new markdownit();
 
-const TRANSFORMATION_TIMEOUT_MS = 500;
 const SANITIZE_MAX_DEPTH = 10;
 const SANITIZE_MAX_BREADTH = 50;
 
@@ -104,12 +89,6 @@ const EXPIRY_NOTICE_MESSAGE = "The webhook **%NAME** will be expiring in %TIME."
  */
 @Connection
 export class GenericHookConnection extends BaseConnection implements IConnection {
-    private static quickModule?: QuickJSWASMModule;
-
-    public static async initialiseQuickJS() {
-        GenericHookConnection.quickModule = await newQuickJSWASMModule();
-    }
-
     /**
      * Ensures a JSON payload is compatible with Matrix JSON requirements, such
      * as disallowing floating point values.
@@ -164,7 +143,7 @@ export class GenericHookConnection extends BaseConnection implements IConnection
         }
         // Use !=, not !==, to check for both undefined and null
         if (transformationFunction != undefined) {
-            if (!this.quickModule) {
+            if (!WebhookTransformer.canTransform) {
                 throw new ApiError('Transformation functions are not allowed', ErrCode.DisabledFeature);
             }
             if (typeof transformationFunction !== "string") {
@@ -284,7 +263,7 @@ export class GenericHookConnection extends BaseConnection implements IConnection
         GenericHookConnection.LegacyCanonicalEventType,
     ];
 
-    private transformationFunction?: string;
+    private webhookTransformer?: WebhookTransformer;
     private cachedDisplayname?: string;
     private warnOnExpiryInterval?: NodeJS.Timeout;
 
@@ -303,8 +282,8 @@ export class GenericHookConnection extends BaseConnection implements IConnection
         private readonly storage: IBridgeStorageProvider,
     ) {
         super(roomId, stateKey, GenericHookConnection.CanonicalEventType);
-        if (state.transformationFunction && GenericHookConnection.quickModule) {
-            this.transformationFunction = state.transformationFunction;
+        if (state.transformationFunction && WebhookTransformer.canTransform) {
+            this.webhookTransformer = new WebhookTransformer(state.transformationFunction);
         }
         this.handleExpiryTimeUpdate(false).catch(ex => {
             log.warn("Failed to configure expiry time warning for hook", ex);
@@ -372,27 +351,20 @@ export class GenericHookConnection extends BaseConnection implements IConnection
     public async onStateUpdate(stateEv: MatrixEvent<unknown>) {
         const validatedConfig = GenericHookConnection.validateState(stateEv.content as Record<string, unknown>);
         if (validatedConfig.transformationFunction) {
-            const ctx = GenericHookConnection.quickModule!.newContext();
-            const codeEvalResult = ctx.evalCode(`function f(data) {${validatedConfig.transformationFunction}}`, undefined, { compileOnly: true });
-            if (codeEvalResult.error) {
-                const errorString = JSON.stringify(ctx.dump(codeEvalResult.error), null, 2);
-                codeEvalResult.error.dispose();
-                ctx.dispose();
-
+            const error = WebhookTransformer.validateScript(validatedConfig.transformationFunction);
+            if (error) {
                 const errorPrefix = "Could not compile transformation function:";
                 await this.intent.sendEvent(this.roomId, {
                     msgtype: "m.text",
-                    body: errorPrefix + "\n\n```json\n\n" + errorString + "\n\n```",
-                    formatted_body: `<p>${errorPrefix}</p><p><pre><code class=\\"language-json\\">${errorString}</code></pre></p>`,
+                    body: errorPrefix + "\n\n```json\n\n" + error + "\n\n```",
+                    formatted_body: `<p>${errorPrefix}</p><p><pre><code class=\\"language-json\\">${error}</code></pre></p>`,
                     format: "org.matrix.custom.html",
                 });
             } else {
-                codeEvalResult.value.dispose();
-                ctx.dispose();
-                this.transformationFunction = validatedConfig.transformationFunction;
+                this.webhookTransformer = new WebhookTransformer(validatedConfig.transformationFunction); ;
             }
         } else {
-            this.transformationFunction = undefined;
+            this.webhookTransformer = undefined;
         }
 
         const prevDate = this.state.expirationDate;
@@ -469,78 +441,6 @@ export class GenericHookConnection extends BaseConnection implements IConnection
         return msg;
     }
 
-    public executeTransformationFunction(data: unknown): {content?: {plain: string, html?: string, msgtype?: string}, webhookResponse?: WebhookResponse} {
-        if (!this.transformationFunction) {
-            throw Error('Transformation function not defined');
-        }
-        let result;
-        const ctx = GenericHookConnection.quickModule!.newContext();
-        ctx.runtime.setInterruptHandler(shouldInterruptAfterDeadline(Date.now() + TRANSFORMATION_TIMEOUT_MS));
-        try {
-            ctx.setProp(ctx.global, 'HookshotApiVersion', ctx.newString('v2'));
-            const ctxResult = ctx.evalCode(`const data = ${JSON.stringify(data)};\n(() => { ${this.state.transformationFunction} })();`);
-
-            if (ctxResult.error) {
-                const e = Error(`Transformation failed to run: ${JSON.stringify(ctx.dump(ctxResult.error))}`);
-                ctxResult.error.dispose();
-                throw e;
-            } else {
-                const value = ctx.getProp(ctx.global, 'result');
-                result = ctx.dump(value);
-                value.dispose();
-                ctxResult.value.dispose();
-            }
-        } finally {
-            ctx.global.dispose();
-            ctx.dispose();
-        }
-
-        // Legacy v1 api
-        if (typeof result === "string") {
-            return {content: {plain: `Received webhook: ${result}`}};
-        } else if (typeof result !== "object") {
-            return {content: {plain: `No content`}};
-        }
-        const transformationResult = result as WebhookTransformationResult;
-        if (transformationResult.version !== "v2") {
-            throw Error("Result returned from transformation didn't specify version = v2");
-        }
-
-        let content;
-        if (!transformationResult.empty) {
-            if (typeof transformationResult.plain !== "string") {
-                throw Error("Result returned from transformation didn't provide a string value for plain");
-            }
-            if (transformationResult.html !== undefined && typeof transformationResult.html !== "string") {
-                throw Error("Result returned from transformation didn't provide a string value for html");
-            }
-            if (transformationResult.msgtype !== undefined && typeof transformationResult.msgtype !== "string") {
-                throw Error("Result returned from transformation didn't provide a string value for msgtype");
-            }
-            content = {
-                plain: transformationResult.plain,
-                html: transformationResult.html,
-                msgtype: transformationResult.msgtype,
-            };
-        }
-
-        if (transformationResult.webhookResponse) {
-            if (typeof transformationResult.webhookResponse.body !== "string") {
-                throw Error("Result returned from transformation didn't provide a string value for webhookResponse.body");
-            }
-            if (transformationResult.webhookResponse.statusCode !== undefined && typeof transformationResult.webhookResponse.statusCode !== "number" && Number.isInteger(transformationResult.webhookResponse.statusCode)) {
-                throw Error("Result returned from transformation didn't provide a number value for webhookResponse.statusCode");
-            }
-            if (transformationResult.webhookResponse.contentType !== undefined && typeof transformationResult.webhookResponse.contentType !== "string") {
-                throw Error("Result returned from transformation didn't provide a contentType value for msgtype");
-            }
-        }
-
-        return {
-            content,
-            webhookResponse: transformationResult.webhookResponse,
-        }
-    }
 
     /**
      * Processes an incoming generic hook
@@ -559,21 +459,21 @@ export class GenericHookConnection extends BaseConnection implements IConnection
             };
         }
 
-        let content: {plain: string, html?: string, msgtype?: string}|undefined;
-        let webhookResponse: WebhookResponse|undefined;
+        let content: ExecuteResultContent|undefined;
+        let webhookResponse: ExecuteResultWebhookResponse|undefined;
         let successful = true;
-        if (!this.transformationFunction) {
-            content = this.transformHookData(data);
-        } else {
+        if (this.webhookTransformer) {
             try {
-                const result = this.executeTransformationFunction(data);
+                const result = this.webhookTransformer.execute(data);
                 content = result.content;
                 webhookResponse = result.webhookResponse;
             } catch (ex) {
                 log.warn(`Failed to run transformation function`, ex);
                 content = {plain: `Webhook received but failed to process via transformation function`};
                 successful = false;
             }
+        } else {
+            content = this.transformHookData(data);
         }
 
         if (content) {
@@ -591,6 +491,7 @@ export class GenericHookConnection extends BaseConnection implements IConnection
                 body: content.plain,
                 // render can output redundant trailing newlines, so trim it.
                 formatted_body: content.html || md.render(content.plain).trim(),
+                ...(content.mentions ? {"m.mentions": content.mentions} : undefined),
                 format: "org.matrix.custom.html",
                 "uk.half-shot.hookshot.webhook_data": safeData,
             }, 'm.room.message', sender);